QUALIFY
Define the CICSPlex SM context and scope.
Related commands
CONNECT
Description
This command defines the CICSPlex SM context and scope for subsequent commands issued by an API processing thread.
Options
- CONTEXT(data-value)
- Identifies the context for subsequent commands issued against this thread.
The context must be the 1- to 8-character name of a CMAS or CICSplex.
The specified context remains in effect for the thread until you override it or change it on a subsequent command.
- 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.
- SCOPE(data-value)
- Identifies the scope for subsequent commands issued against this thread.
The SCOPE option qualifies the CONTEXT option. When the context is a CICSplex, the scope can be:
- The 1- to 8-character name of the CICSplex itself
- A CICS® system or CICS system group within the CICSplex
- A logical scope, as defined in a CICSPlex SM resource description (RESDESC).
The specified scope remains in effect for the thread unless you override it for a specific command or change it by issuing another QUALIFY command. If you do not specify the SCOPE option, no scope value is assumed (that is, the default scope established for the thread by the CONNECT command is not retained).
Note: Certain API commands require a valid scope when the context is a CICSplex. If you do not specify a scope on the QUALIFY command, then you must specify the SCOPE option when you issue any of these commands for a resource table that represents a CICS resource:- GET
- PERFORM OBJECT
- PERFORM SET
- REFRESH
- SET.
- 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 QUALIFY 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.
- INVALIDPARM
- An invalid parameter was detected. The parameter that is invalid is returned
as the reason value:
- CONTEXT
- SCOPE
- 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.
- PLEXMGR
- The CMAS to which the processing thread is currently connected does not participate in managing the specified CICSplex and no other CMAS is available that does manage the CICSplex.
- 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.