CONNECT

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 one of the following:

• 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).

When the context is a CMAS, this option has no meaning and is ignored.

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.

Notes:

1. The VERSION value must be 0120 or greater. The API cannot access data from a release of CICSPlex SM earlier than release 2.
2. The VERSION value must be less than or equal to the version of the CICSPlex SM runtime environment.
3. 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.
   For complete details on things to consider when running under a different release, see Developing CICSPlex SM applications.

Conditions