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 desired 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.
For complete descriptions of these commands, see CICSPlex System Manager Application Programming Reference.
The process of connecting to CICSPlex SM varies according to what type of program
you write and where it runs. For programs written using the command-level interface, keep in
mind the following requirements:
- CICS
- A program written to run as a CICS application must be linked with the
proper stub routine and must run in a CICS system that is being actively managed
by CICSPlex SM as a local MAS.
A connection is established first to the MAS agent
code that resides in the CICS system and then to the CMAS that controls that MAS.
On the CONNECT command, you must specify a CONTEXT of the local CMAS.
- Batch, NetView®, or TSO
- A program written to run as a batch job or under NetView or TSO must be
linked with the proper stub routine and must run in the same MVS image as
the CMAS to which you want to connect.
In these environments, if there
is more than one CMAS in the MVS image, the API selects a suitable CMAS and
establishes a connection. The following rules apply to the selection of a CMAS:
- The CMAS must be running the same version of CICSPlex SM as the run-time
module (EYU9AB00).
- If the context specified on the CONNECT command is a CMAS, CICSPlex SM connects
to that CMAS. If that CMAS is either not active or not running the appropriate
version of CICSPlex SM, the CONNECT command fails.
- If the context specified on CONNECT is a CICSplex, CICSPlex SM selects a CMAS running
the appropriate version that participates in the management of the CICSplex.
- If no context is specified on CONNECT, CICSPlex SM connects to the CMAS that
was most recently started, provided it is running the appropriate version
of CICSPlex SM.
The CICSPlex SM API also supports another type of batch environment. A
program can issue API commands from an address space that is running a CICS system without
itself being a CICS transaction. In other words, the program can run as a
separate MVS task in the same address space as the CICS system. This type of program
must be linked with the batch environment stub routine and the connection
process is the same as for other batch programs.
Note:
A program
that is a CICS transaction must be run in a CICS system that is a CICSPlex SM local MAS.
For details on the stub routines that are required for each of these
environments, see Link editing your program.
Note:
For programs written in REXX, the connection process is the
same as for a command-level program that runs in the same environment (batch,
TSO, or NetView). No stub routine is required, but the REXX function package
that is supplied by CICSPlex SM must have been properly installed.
MVS restrictions:
Upon successful completion of a CONNECT
request, a thread token is returned to the user. All subsequent commands referring
to this thread token must be issued from the same MVS TCB that issued the
comnnection request
When an API program requests a connection to CICSPlex SM, the CMAS being
connected to attempts to extract user authorization data from the environment.
How the connection is established depends upon whether such authorization
data exists and whether security is active in the CMAS:
- If security exists
- Regardless of whether CMAS security is active, if a security environment
exists where the API program is running:
- The API security routine, EYU9XESV, is not called.
- The USER and SIGNONPARM options on the CONNECT command are ignored.
- The API program is connected with the user ID of the invoking user,
as obtained from the accessor environment element (ACEE).
Note:
If CMAS security is not active, the ACEE user ID is
not validated by CICSPlex SM.
This type of security environment
may exist when a program runs under TSO, batch, NetView, or a local MAS where
CICS security is active. Security checking is performed by the environment
where the API program is running.
- If security does not exist and CMAS security is not active
-
- The API security routine, EYU9XESV, is not called.
- The USER and SIGNONPARM options on the CONNECT command are ignored.
- No signon is performed. However, the user ID specified in the XESV_CONN_USERID
field of the security routine parameter block, EYUBXESV, is associated with
the connection.
This type of security environment may exist when a program runs under
a local MAS where CICS security is not active. Since CMAS security is
not active, no security checking is performed.
- If security does not exist and CMAS security is active
-
- The API security routine, EYU9XESV, is called.
- The USER and SIGNONPARM values from the CONNECT command are passed to
EYU9XESV.
- A signon is performed using the user ID returned by EYU9XESV, but no password
checking is performed. By default, EYU9XESV returns the default CICS user
ID for the CMAS (the DFLT_UID value).
This type of security environment may exist when a program runs under a local MAS where CICS security is not active.
Since CMAS security is active, security checking is performed by EYU9XESV.
Table 3 summarizes the levels of API security and the
conditions under which they are implemented.
Table 3. Possible API security environments
Environment Security |
CMAS Security |
No CMAS Security |
YES |
EYU9XESV not called.
CONNECT
options ignored.
User ID=ACEE. |
EYU9XESV not called.
CONNECT
options ignored.
User ID=ACEE (not checked). |
NO |
EYU9XESV called.
CONNECT
options passed.
User ID=As returned by EYU9XESV
(signon with no password checking). |
EYU9XESV not called.
CONNECT
options ignored.
User ID= XESV_CONN_USERID
(no signon). |
For a description of the USER and SIGNONPARM options, see the API CONNECT
Command in the CICSPlex System Manager Application Programming Reference. For a description of
EYU9XESV and information on customizing this security routine, see CICS RACF® Security Guide.
[[ Contents Previous Page | Next Page Index ]]