I mentioned in last month's column that CICSPlex System Manager (CPSM) is a mixture of system, automation and workload management. All of these functions are available from CPSM's Rexx interface, which allows enterprises to control CICS and CPSM operation from batch and TSO.
CPSM Rexx interface
There are two types of Rexx interfaces. The first interface works through a series of functions defined as follows:
| Function |
Parameters |
Purpose |
| EYUINIT
| None |
Initialize the CPSM environment
|
| EYUTERM
| None
| Terminate the CPSM environment
|
| EYUAPI
| CPSM
| command string Issue a CPSM command
|
| EYUREAS
| Numeric reason code
| Return interpreted CPSM reason code
|
| EYURESP
| Numeric response code
| Return interpreted response code
|
There are also two functions, TPARSE and TBUILD, which are used to get data in to and out of CPSM through Rexx variables.
The second interface uses the Rexx ADDRESS function to execute commands as follows: ADDRESS CPSM "". Though this interface seems more straightforward than invoking the EYUAPI function, I haven't been able to get it to work. Hence, I won't include it in examples shown here.
In addition to getting used to the interface, you must also get used to how CPSM interacts with Rexx variables. CPSM functions expect variables to be passed as literals in the command string. When called, the function uses the literal variable name to get the parameter value.
For example, in this code fragment:
w_context = "CICSPLEX"
w_scope = "PLEXSCOP"
xx = EYUAPI('CONNECT CONTEXT(w_context) SCOPE(w_scope)….')
The variables w_context and w_scope pass to EYUAPI as character strings. EYUAPI, in turn, gets the actual variables' contents somewhere in Rexx.
This is different from the way I would normally code Rexx:
w_context = "CICSPLEX"
w_scope = "PLEXSCOP"
xx = EYUAPI('CONNECT CONTEXT('w_context') …)'
In this case, Rexx passes the value of w_context ("CICSPLEX") to EYUAPI. EYUAPI and looks for a variable named CICSPLEX to get the context value. Since the variable doesn't exist, hilarity ensues.
CPSM data repository
CPSM's data repository is set up as a series of tables and views after the manner of a relational database. As such, a programmer must deal with tables and attributes, as opposed to columns.
Each table represents the status of a CICS resource or CPSM object. For instance, there is the CONNECT table listing CICS connections and their attributes just as they would be viewed with CEMT. There is also a CONNDEF, which you might employ to install a new connection definition from CPSM or BAS. There are even separate tables for the same resources with different attributes, such as LOCTRAN (for local transactions) and REMTRAN (for remote).
Each table comes with a list of attributes about the resource, including its present status. Some of the attributes may be identified as primary or secondary keys, which uniquely identify a resource within the table given the context and scope of the command. From the documentation, the keys seem to mostly come into play when you want to use the API to define, delete or update resources.
For all the information you can stand about the CPSM tables and their attributes, I recommend reading the Resource Table Reference in the CICS Information Center.
CPSM commands
CPSM commands are based on the same structure as CICS commands with a few important differences:
- Substitute "EXEC CPSM" for "EXEC CICS"
- CPSM uses RESPONSE and REASON parameters for status checking
- CPSM provides EYUVALUE to convert a text token into its numerical value
- Functions EYURESP and EYUREAS interpret a status code number into text just like DFHRESP
- When a program initially connects, CPSM passes back a thread token. All subsequent CPSM commands must use this token or suffer the consequences.
For more details on the commands, consult the CPSM Application Programming Guide and Application Programming Reference in the information center.
Error checking
Before you begin programming, be aware that each EYU function issues a return code. A zero return code is good. A non-zero code is not. But this is not the true error. To find the true error, you must interrogate the response and reason code returned from CPSM. Therefore, a common program technique would be to first check the function's return code. If it's non-zero, use the CPSM response and reason codes to figure out what's wrong. Remember you may use EYUREAS or EYURESP functions to interpret them.
Program structure
Every Rexx CPSM program begins its adventure by calling the EYUINIT function. EYUINIT doesn't take any parameters, but it will issue a non-zero return code if there's some kind of problem in the initialization.
Following EYUINIT are the EYUAPI calls until you want to terminate your program. The first API call should be a CONNECT command specifying the context, scope and the CPSM version you wish to use. A successful CONNECT will return a thread token required for all subsequent commands. After connecting, the Rexx program is free to issue any commands it wishes, although the program structure is a little more complicated for browsing CPSM tables.
As mentioned above, the CPSM repository is externalized as a set of tables. Thus, a GET OBJECT command will create what is called a "result set" based on the specified filtering criteria. Once you have a result set, you must issue LOCATE TOP command to set the cursor to the first row of the results set. This must be followed by a number of FETCH commands to access the individual rows. The number of fetches needed is determined by the value of the COUNT parameter passed back by the GET OBJECT command. As you fetch each row you must use the TPARSE function to get the row's attributes into Rexx variables.
Finally, when you've had enough, the EYUTERM function severs the connection to CPSM. Note that EYUTERM is not always required but is recommended by IBM.
The Rexx interface to CPSM is weird but powerful. It presents many opportunities for automation both from TSO and batch. In my next column I will go through a couple of examples to show in more detail how the interface works and what it can be used for.
ABOUT THE AUTHOR: Robert Crawford has been a CICS systems programmer off and on for 24 years. He is experienced in debugging and tuning applications and has written in COBOL, Assembler and C++ using VSAM, DLI and DB2.
