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
