CONNECT
Establish a connection with CICSPlex SM, define an API processing thread, and provide default settings to be used by the thread.
Description
The specifics of the connection process depend upon the environment in which your program is running. For a complete description of the connection process, see Developing CICSPlex SM applications.
Related commands
DISCONNECT, QUALIFY, TERMINATE
Options
- CONTEXT(data-value)
- Identifies the default context for commands issued against this
thread. The context must be the 1- to 8-character name of a CMAS or
CICSplex.
The default context is in effect for all commands issued against the thread unless you override it for a specific command or change it by issuing the QUALIFY command. As an alternative to specifying a default context for the thread, you can specify the context for individual commands as they are processed.
If you do not specify the CONTEXT option, the default context for the thread is the CMAS to which the thread is connected.
- 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 default scope for 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 default scope is in effect for all commands issued against the thread unless you override it for a specific command or change it by issuing the QUALIFY command. If you do not specify the SCOPE option, no default scope is assumed.
Note: Certain API commands require a valid scope when the context is a CICSplex. If you do not specify a scope on a CONNECT or QUALIFY command, you must specify the SCOPE option when you issue any of the following commands for a resource table that represents a CICS resource:- GET
- PERFORM OBJECT
- PERFORM SET
- REFRESH
- SET
- SIGNONPARM(data-value)
- Identifies a 1- to 8-character sign-on parameter to be passed to the API security
exit routine (EYU9XESV) at your enterprise. Password phrases are not
supported.
If CMAS security is active and no security is defined in the environment where the API program is running, CICSPlex SM passes the USER and SIGNONPARM values from the CONNECT command to EYU9XESV. For more information about API security, see Developing CICSPlex SM applications.
- THREAD(data-ref)
- Names a variable to receive the fullword token that CICSPlex SM assigns
to this processing thread.
This identifying token must be specified on all subsequent commands issued against this thread.
- USER(data-value)
- Identifies a 1- to 8-character user ID to be passed to the API security exit
routine (EYU9XESV) at your enterprise.
If CMAS security is active and CICSPlex SM finds no security defined in the environment where the API program is running, it passes the USER and SIGNONPARM values from the CONNECT command to EYU9XESV. For more information about API security, see Developing CICSPlex SM applications.
- VERSION(data-value)
- Identifies the release of CICSPlex SM resource
table data that you want to be available to your program. The VERSION
value must be the 4-character number of a valid CICSPlex SM release,
such as 0410 for CICS TS 4.1.
Note: Notes
- The VERSION value must be 0120 or greater. The API cannot access data from a release of CICSPlex SM earlier than release 2.
- The VERSION value must be less than or equal to the version of the CICSPlex SM runtime environment.
- You can specify a VERSION value that is greater than the release
under which your API program was originally written, provided:
- You compile your program using the appropriate copy books for the version specified.
- Your program is compatible with the copy books for the version specified.
Conditions
- OK
- The command completed processing successfully.
- FAILED
- The command failed for one of the following reasons:
- ABENDED
- Command processing abnormally terminated.
- EXCEPTION
- Command processing encountered an exceptional condition.
- ENVIRONERROR
- An environment error occurred for one of the following reasons:
- APITASKERR
- The API control subtask encountered an error during startup.
- 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.
- SOERESOURCE
- A required resource that is owned by the Environment Services System Services (ESSS) address space is not available.
- SOLRESOURCE
- A required resource that is locally owned (that is, owned by the address space where the processing thread is running) is not available.
- INVALIDPARM
- An invalid parameter was detected. The parameter that is invalid
is returned as the reason value:
- CONTEXT
- SCOPE
- SIGNONPARM
- USRID
- VERSION
- 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.
- CPSMSERVER
- The CMAS to which the processing thread was trying to connect is not available.
- CPSMSYSTEM
- No CICSPlex SM systems are available.
- CPSMVERSION
- No CICSPlex SM system at the specified version is available.
- NOTPERMIT
- A not permitted condition occurred for one of the following reasons:
- EXPIRED
- The security authorization of the specified user ID has expired.
- SIGNONPARM
- The specified sign-on parameter is not authorized for the user ID.
- USRID
- The specified user ID does not have the required security authorization.
- VERSIONINVL
- A version conflict occurred for the following reason:
- NOTSUPPORTED
- The version of the application stub program used for this command is not supported.