Setting the context and scope

The set of managed objects that your API program can work with is determined primarily by the context and scope associated with the processing thread. As with all CICSPlex® SM operations, the context and scope of an API program identify the CICS® systems on which the program can act.

In general, you can set the context and scope values as follows:
CONTEXT
For most operations in a CICSplex, the context is the name of the CICSplex. For operations related to CMAS configuration (such as defining CICSplexes or CMAS communication links), the context must be a CMAS name and for applications executing in a CICS local MAS the CMAS name must be the local CMAS name.
SCOPE
When the context is a CICSplex, the scope can be:
  • 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, the scope value is ignored. There are also a number of resources for which the scope value is ignored. These are identified by the SCOPE applies field in the description of resource tables in CICSPlex SM resource tables.
You can set a default context and scope for your program by using one of these commands:
CONNECT
Defines a default context and scope when the API processing thread is established.
QUALIFY
Changes the default context and scope for subsequent commands issued on the thread.
The values you set on either of these commands are in effect for all API commands that use context and scope.
Alternatively, you can specify context and scope values for individual API commands. The following commands support one or both of the CONTEXT and SCOPE options:
  • CREATE
  • GET
  • LISTEN
  • PERFORM OBJECT
  • REMOVE
  • UPDATE.
The context and scope values you set on any of these commands are in effect for that command alone. If you specified a default context and scope for the thread, the values on any of these commands temporarily override the default values. If you did not specify a default context and scope and you issue a command that expects these values (such as GET), you must specify a context and scope on the command.