SPECIFY FILTER
Define an attribute or value filter and assign an identifying token to it.
Description
This command defines an attribute
or value filter and assigns an identifying token to it.
- Filters are associated with the specific processing thread on which they are defined; they cannot be shared by other processing threads.
- You can define multiple filters for use by a processing thread; CICSPlex SM assigns a unique identifying token to each one.
- When a processing thread is terminated, any filters defined by it are discarded.
Related commands
COPY, DELETE, DISCARD, FETCH, GET, GROUP, LISTEN, LOCATE, MARK, PERFORM OBJECT, PERFORM SET, REFRESH, SET, UNMARK
Options
- CRITERIA(data-area)
- Identifies a buffer containing the filter expression
to be used for this operation. The CRITERIA option filters only those
resource table records that meet the specified criteria.
For details on how to form a filter expression, see Developing CICSPlex SM applications.
Note: You cannot specify the EYU_CICSNAME or EYU_CICSREL attributes in a filter expression. - FILTER(data-ref)
- Names a variable to receive the token that CICSPlex SM assigns
to this filter.
This identifying token must be specified on all subsequent commands that use this filter.
- LENGTH(data-value)
- A fullword value that specifies the length of the CRITERIA buffer.
Note: The buffer length you specify should not include any data other than a filter expression.
- OBJECT(data-value)
- Identifies the resource table for which a filter is being created. This value must be the 8-character name of a valid resource table.
- REASON(data-ref)
- Names a variable to receive the fullword reason value returned by this command.
- RESPONSE(data-ref)
- Names a variable to receive the fullword response value returned by this command.
- THREAD(cpsm-token)
- Identifies the API thread to be used for this operation. The cpsm-token value that identifies a thread is returned by the CONNECT command.
Conditions
The following is a list of the
RESPONSE values that can be returned by the SPECIFY FILTER command.
The description of each RESPONSE includes a list of associated REASON
values, if appropriate.
- OK
- The command completed processing successfully.
- ENVIRONERROR
- An environment error occurred for one of the following reasons:
- NOSERVICE
- The application stub program could not load the API service module.
- NOSTORAGE
- The application stub program could not obtain the necessary storage in the address space where the processing thread is running.
- SOCRESOURCE
- A required resource that is owned by the CMAS is not available.
- FAILED
- The command failed for one of the following reasons:
- ABENDED
- Command processing abended.
- EXCEPTION
- Command processing encountered an exceptional condition.
- INVALIDATA
- Invalid data was detected. The parameter that contains invalid
data is returned as the reason value:
- CRITERIA
- An attribute value listed in the CRITERIA buffer is not valid for the specified attribute.
- INVALIDCMD
- The command is invalid for one of the following reasons:
- FILTER
- The filter expression passed on the operation is too large or complex.
- LENGTH
- The total length of all the options on the command exceeds the maximum limit.
- INVALIDPARM
- An invalid parameter was detected. The parameter that is invalid
is returned as the reason value:
- CRITERIA
- FILTER
- LENGTH
- OBJECT
- THREAD.
- NOTAVAILABLE
- A not available condition occurred for one of the following reasons:
- APITASK
- The API control subtask is not active.
- CPSMAPI
- The CMAS to which the processing thread is connected is not available for API processing.
- NOTFOUND
- A not found condition occurred for the following reason:
- ATTRIBUTE
- An attribute specified in the CRITERIA buffer was not found for the specified resource table.
- SERVERGONE
- The CMAS to which the processing thread was connected is no longer active.
- VERSIONINVL
- A version conflict occurred for one of the following reasons:
- NOTSUPPORTED
- The version of the application stub program used for this command is not supported.
- NOTVSNCONN
- The version of the application stub program used for this command is not the same as the version used with the CONNECT command.