You can think of a CICSPlex® SM API program as existing in or having access to three environments.
User environment
The program itself and the environment in which it runs, such
as MVS or CICS®.
CICSPlex SM environment
The data that CICSPlex SM maintains and the services it provides to the program.
Managed resource environment
The resources that CICSPlex SM manages and which the program can access.
Before your program can access the CICSPlex SM environment and the resources it manages, you must establish a connection to CICSPlex SM. This connection is called an API processing thread and serves two basic purposes:
When a thread is created, the user is identified so that security
validation and auditing of the program's operations can take place
transparently.
There are implicit relationships between some API functions, and
those relationships are maintained at the thread level. Each thread
is considered a unique API user and no resources can cross the boundary
of a thread.
Once a thread is created, your program can issue commands within
the context of the local CMAS. The local CMAS is dictated by where
and how the connect command is issued:
If issued in a CICS system, it is the local CMAS to that CICS system.
If issued as a batch job and no CMAS is stated explicitly, the
local CMAS is the last CMAS started.
If issued as a batch job and a CMAS within the MVS image
is included in the CONNECT command, it is that CMAS.
You can look at data from CMASs other than the local CMAS but
you cannot change the context to point directly to them.
A simple API program would establish only a single thread. You
could establish the thread, perform the operations, and then
terminate the thread. A more complex program might maintain several
concurrent threads to perform parallel operations that would be prohibited
on a single thread or to simplify the correlation of commands and
results.
You can use the following commands to manage an API thread:
CONNECT
Establishes a connection to CICSPlex SM, defines an
API processing thread, and provides default settings for the thread. The thread is maintained by the
CMAS that is supporting your API session.
DISCONNECT
Disconnects an API processing thread from CICSPlex SM
and releases any resources associated with the thread.
QUALIFY
Defines the CICSPlex SM context and scope for
subsequent commands issued by the thread.
TERMINATE
Terminates all API processing on all the threads created by the CICS or MVS task that issues the command.
These commands manage the connection between the user environment (your program) and CICSPlex SM; they do not affect the managed resources. Figure 1 illustrates the impact these commands have on the API environment. Figure 1. API commands involved in managing a thread
