Connecting to CICSPlex SM

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:

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:

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.

Figure 1. API commands involved in managing a thread
 This figure illustrates a user-written program utilizing the CONNECT, DISCONNECT and QUALIFY API commands to manage the connection between the user and CICSPlex SM environments.

For complete descriptions of these commands, see CICSPlex System Manager Application Programming Reference.

The connection process

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 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

Security considerations

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:
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
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
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 ]]