SPECIFY FILTER

Define an attribute or value filter and assign an identifying token to it.

Read syntax diagramSkip visual syntax diagramSPECIFYFILTER(data-ref) CRITERIA(data-area) LENGTH(data-value) OBJECT(data-value) THREAD(cpsm-token) RESPONSE(data-ref) REASON(data-ref)

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.
1024 OK
The command completed processing successfully.
1026 NOTFOUND
A not found condition occurred for the following reason:
1310 ATTRIBUTE
An attribute specified in the CRITERIA buffer was not found for the specified resource table.
1028 INVALIDPARM
An invalid parameter was detected. The parameter that is invalid is returned as the reason value:
  • 1280 THREAD
  • 1281 OBJECT
  • 1285 LENGTH
  • 1286 FILTER
  • 1299 CRITERIA

Check the command description for valid parameter syntax.

1029 FAILED
The command failed for one of the following reasons:
1331 ABENDED
Command processing abended.
1359 EXCEPTION
Command processing encountered an exceptional condition.
1030 ENVIRONERROR
An environment error occurred for one of the following reasons:
1321 SOCRESOURCE
A required resource that is owned by the CMAS is not available.
1357 NOSTORAGE
The application stub program could not obtain the necessary storage in the address space where the processing thread is running.
1358 NOSERVICE
The application stub program could not load the API service module.
1033 SERVERGONE
The CMAS to which the processing thread was connected is no longer active.
1034 NOTAVAILABLE
A not available condition occurred for one of the following reasons:
1334 CPSMAPI
The CMAS to which the processing thread is connected is not available for API processing.
1340 APITASK
The API control subtask is not active.
1035 VERSIONINVL
A version conflict occurred for one of the following reasons:
1335 NOTSUPPORTED
The version of the application stub program used for this command is not supported.
1336 NOTVSNCONN
The version of the application stub program used for this command is not the same as the version used with the CONNECT command.
1036 INVALIDCMD
The command is invalid for one of the following reasons:
1285 LENGTH
The total length of all the options on the command exceeds the maximum limit.
1286 FILTER
The filter expression passed on the operation is too large or complex.
1041 INVALIDATA
Invalid data was detected. The parameter that contains invalid data is returned as the reason value:
1299 CRITERIA
An attribute value listed in the CRITERIA buffer is not valid for the specified attribute.