The CICSPlex® SM API accepts and returns resource data in the form of records that contain the resource attributes. For example, if you issue a FETCH command against a result set containing LOCTRAN resource table records, the API returns all the attributes for a given transaction in a single record. Your program must identify an area of storage to receive the resource table records.
To simplify the use of these resource table records, CICSPlex SM provides a set of copy books for each resource table that you can access from an API program. By including these copy books in your program, you can access the resource table data in the appropriate structure and format for the language you are using.
The copy books are installed as part of the CICSPlex SM installation process. They are placed into the following libraries:
If you want to include the copy books in your program, make sure the appropriate library is available to the assemble or compile step.
Each CICSPlex SM resource table has a name that is unique within the product. In addition, a unique name is created for each copy book version of the resource table in each language. The copy book names take the form:
EYUtnnnn
where:
For example:
To make the copy books easy to reference in your program, CICSPlex SM provides alias support for the copy book names. The appropriate data set contains the following two entries for each resource table:
So, using the previous example, the Assembler DSECT for the CICSRGN resource table could be referred to as either EYUA0001 or its alias, CICSRGN.
Each copy book contains a prologue that describes the resource table and its characteristics, including:
A description is provided for each attribute of the resource table. In addition, the following information is provided for an attribute, if appropriate:
Each resource table that can be processed by an API program contains data values for each of its attributes. The attribute values are presented in an internal format that is appropriate for the data type and the environment in which the program is running:
EYU_RSVnnnn
Make sure the data areas your program uses to send and receive resource table records have proper boundary alignment.
This section provides detailed information about the resource table copy books supplied for each language.
Note the following as you use the Assembler copy books:
The resource table data types are defined using the data definition operands of the DS statement. The following data type definitions are used:
DS X - Bit, binary values greater than 8 bytes
- Odd number binary values less than 8 bytes
- Mixed character and binary data
DS H - 2-byte binary numeric values
DS F - 4-byte binary numeric values
- 4-byte intervals
DS D - Time stamps and 8-byte intervals
- 8-byte numeric values
DS P - Packed decimal data
DS C - Character data
Figure 13 is a representative extract of an Assembler resource table copy book:
*------------------------------------------------------------------*
* Name = EYUA2400 *
* Format Name = EMASSTRT *
* Version = 0001 *
* Status = CPSMREL(0310) *
* Function = Base Table Structure generator *
* Format definition for this element = EMASSTRT *
* Valid Operations = None *
* Valid Actions = None *
*------------------------------------------------------------------*
EMASSTRT DSECT Notify CICS System Start Event
EMASSTRT_CMASNAME DS CL0008 CMAS Name
EMASSTRT_PLEXNAME DS CL0008 CICSPlex Name
EMASSTRT_CSYSNAME DS CL0008 CICS System Name
EMASSTRT_MON_SPEC DS CL0008 Monitor Spec Name
EMASSTRT_RTA_SPEC DS CL0008 Real Time Analysis Spec Name
EMASSTRT_WLM_SPEC DS CL0008 Work Load Manager Spec Name
EMASSTRT_STATUS DS XL0001 Status
EMASSTRT_STATUS_LOCAL EQU 128 Local MAS
EMASSTRT_STATUS_REMOTE EQU 64 Remote MAS
EMASSTRT_DYNROUTE DS XL0001 Dynamic Routing Mode
EMASSTRT_DYNROUTE_ACTIVE EQU 1 Routing ACTIVE
EMASSTRT_DYNROUTE_SUSPEND EQU 2 Routing SUSPENDED
EMASSTRT_DYNTYPE DS CL0003 Dynamic Routing Type
EMASSTRT_DYNTYPE_WLMTOR EQU C'TOR' Routing TOR
EMASSTRT_DYNTYPE_WLMAOR EQU C'AOR' Routing AOR
EMASSTRT_DESC DS CL0030 Description
EMASSTRT_CSYSAPPL DS CL0008 CICS System VTAM APPLID
EMASSTRT_EYU_RSV0015 DS XL0005 Alignment Padding
EMASSTRT_MASSTART DS D MAS Start STCK Value
EMASSTRT_TMEZONEO DS XL0001 Time Zone Offset
EMASSTRT_TMEZONE DS CL0001 Time Zone
EMASSTRT_EYU_RSV0019 DS XL0002 Alignment Padding
EMASSTRT_DAYLGHTSV DS F DayLight savings in effect
EMASSTRT_SYSID DS CL0004 MAS System Id
EMASSTRT_OPSYSREL DS CL0004 MAS Op Sys Release
EMASSTRT_MVSNAME DS CL0004 MVS System Name
EMASSTRT_JOBNAME DS CL0008 MAS Job Name
EMASSTRT_CECNAME DS CL0008 CEC Name
EMASSTRT_SYSPLEX DS CL0008 SYSPlex Name
EMASSTRT_EYU_RSV0257 DS XL0004 Alignment Padding
EMASSTRT_TBL_LEN EQU 152 Current Table size
Note the following as you use the PL/I copy books:
DCL EYUPTPTR POINTER;
The resource table data types are mapped into the valid set of PL/I data types. However, exact mapping is not always possible. The resource table data types are mapped as follows:
BIT(8) ALIGNED - 1-byte binary numeric values
FIXED BIN(15) - 2-byte binary numeric values
FIXED BIN(31) - 4-byte binary numeric values
- 4-byte intervals
(2) FIXED BIN(31) - Time stamps and 8-byte intervals
- 8-byte binary numeric values
(an array of two fullwords)
FIXED DEC(n) - Packed decimal data
CHAR(nnnn) - Character data
- Binary values greater than 8 bytes
- Odd number binary values less than 8 bytes
Figure 14 is a representative extract of a PL/I resource table copy book:
/*----------------------------------------------------------------*/
/* Name = EYUP2400 */
/* Format Name = EMASSTRT */
/* Version = 0001 */
/* Status = CPSMREL(0310) */
/* Function = Base Table Structure generator */
/* Format definition for this element = EMASSTRT */
/* Valid Operations = None */
/* Valid Actions = None */
/*----------------------------------------------------------------*/
DCL 01 EMASSTRT BASED(EYUPTPTR), /* Notify CICS System Start Event*/
02 CMASNAME CHAR(0008),
/* CMAS Name */
02 PLEXNAME CHAR(0008),
/* CICSPlex Name */
02 CSYSNAME CHAR(0008),
/* CICS System Name */
02 MON_SPEC CHAR(0008),
/* Monitor Spec Name */
02 RTA_SPEC CHAR(0008),
/* Real Time Analysis Spec Name */
02 WLM_SPEC CHAR(0008),
/* Work Load Manager Spec Name */
02 STATUS,
/* Status */
03 LOCAL BIT(1) UNALIGNED,
/* Local MAS */
03 REMOTE BIT(1) UNALIGNED,
/* Remote MAS */
03 RSVD0003 BIT(1) UNALIGNED,
/* Reserved */
03 RSVD0004 BIT(1) UNALIGNED,
/* Reserved */
03 RSVD0005 BIT(1) UNALIGNED,
/* Reserved */
03 RSVD0006 BIT(1) UNALIGNED,
/* Reserved */
03 RSVD0007 BIT(1) UNALIGNED,
/* Reserved */
03 RSVD0008 BIT(1) UNALIGNED,
/* Reserved */
02 DYNROUTE BIT(8) ALIGNED,
/* Dynamic Routing Mode */
02 DYNTYPE CHAR(0003),
/* Dynamic Routing Type */
02 DESC CHAR(0030),
/* Description */
02 CSYSAPPL CHAR(0008),
/* CICS System VTAM APPLID */
02 EYU_RSV0015 CHAR(0005),
/* Alignment Padding */
02 MASSTART(2) FIXED BIN(31),
/* MAS Start STCK Value */
02 TMEZONEO BIT(8) ALIGNED,
/* Time Zone Offset */
02 TMEZONE CHAR(0001),
/* Time Zone */
02 EYU_RSV0019 CHAR(0002),
/* Alignment Padding */
02 DAYLGHTSV FIXED BIN(31),
/* DayLight savings in effect */
02 SYSID CHAR(0004),
/* MAS System Id */
02 OPSYSREL CHAR(0004),
/* MAS Op Sys Release */
02 MVSNAME CHAR(0004),
/* MVS System Name */
02 JOBNAME CHAR(0008),
/* MAS Job Name */
02 CECNAME CHAR(0008),
/* CEC Name */
02 SYSPLEX CHAR(0008),
/* SYSPlex Name */
02 EYU_RSV0257 CHAR(0004);
/* Alignment Padding */
/*----------------------------------------------------------------*/
/* */
/* EMASSTRT Constants for Table */
/* */
/*----------------------------------------------------------------*/
DCL EMASSTRT_DYNROUTE_ACTIVE BIT(8) ALIGNED STATIC INIT('01'BX);
/* Routing ACTIVE */
DCL EMASSTRT_DYNROUTE_SUSPEND BIT(8) ALIGNED STATIC INIT('02'BX);
/* Routing SUSPENDED */
DCL EMASSTRT_DYNTYPE_WLMTOR CHAR(3) STATIC INIT('TOR');
/* Routing TOR */
DCL EMASSTRT_DYNTYPE_WLMAOR CHAR(3) STATIC INIT('AOR');
/* Routing AOR */
DCL EMASSTRT_TBL_LEN FIXED BIN(15) STATIC INIT(152);
Note the following as you use the COBOL copy books:
The resource table data types are mapped into the valid set of COBOL data types. However, exact mapping is not always possible. The resource table data types are mapped as follows:
PIC S9(0004) USAGE BINARY - 2-byte binary numeric values
PIC S9(0008) USAGE BINARY - 4-byte binary numeric values
- 4-byte intervals
PIC S9(0016) USAGE BINARY - Time stamps and 8-byte intervals
- 8-byte binary numeric values
PIC S9(nnnn) USAGE PACKED-DECIMAL - Packed decimal data
PIC X(0001) - 1-byte binary and bit indicators
PIC X(nnnn) - Character data
- Binary values greater than 8 bytes
- Odd number binary values less than
8 bytes
Figure 15 is a representative extract of a COBOL resource table copy book:
* -------------------------------------------------------------*
* Name = EYUL2400 *
* Format Name = EMASSTRT *
* Version = 0001 *
* Status = CPSMREL(0310) *
* Function = Base Table Structure generator *
* Format definition for this element = EMASSTRT *
* Valid Operations = None *
* Valid Actions = None *
* -------------------------------------------------------------*
01 EMASSTRT.
* Notify CICS System Start Event
02 CMASNAME PIC X(0008).
* CMAS Name
02 PLEXNAME PIC X(0008).
* CICSPlex Name
02 CSYSNAME PIC X(0008).
* CICS System Name
02 MON-SPEC PIC X(0008).
* Monitor Spec Name
02 RTA-SPEC PIC X(0008).
* Real Time Analysis Spec Name
02 WLM-SPEC PIC X(0008).
* Work Load Manager Spec Name
02 STATUS-R PIC X(0001).
* Status -- RESERVED WORD --
88 LOCAL VALUE X'80'.
* Local MAS
88 REMOTE VALUE X'40'.
* Remote MAS
02 DYNROUTE PIC X(0001).
* Dynamic Routing Mode
88 ACTIVE VALUE X'01'.
* Routing ACTIVE
88 SUSPEND VALUE X'02'.
* Routing SUSPENDED
02 DYNTYPE PIC X(0003).
* Dynamic Routing Type
88 WLMTOR VALUE 'TOR'.
* Routing TOR
88 WLMAOR VALUE 'AOR'.
* Routing AOR
02 DESC PIC X(0030).
* Description
02 CSYSAPPL PIC X(0008).
* CICS System VTAM APPLID
02 EYU-RSV0015 PIC X(0005).
* Alignment Padding
02 MASSTART PIC S9(0016) USAGE BINARY.
* MAS Start STCK Value
02 TMEZONEO PIC X(0001).
* Time Zone Offset
02 TMEZONE PIC X(0001).
* Time Zone
02 EYU-RSV0019 PIC X(0002).
* Alignment Padding
02 DAYLGHTSV PIC S9(0008) USAGE BINARY.
* DayLight savings in effect
02 SYSID PIC X(0004).
* MAS System Id
02 OPSYSREL PIC X(0004).
* MAS Op Sys Release
02 MVSNAME PIC X(0004).
* MVS System Name
02 JOBNAME PIC X(0008).
* MAS Job Name
02 CECNAME PIC X(0008).
* CEC Name
02 SYSPLEX PIC X(0008).
* SYSPlex Name
02 EYU-RSV0257 PIC X(0004).
* Alignment Padding
* -------------------------------------------------------------*
* *
* EMASSTRT Constants for Table *
* *
* -------------------------------------------------------------*
01 EMASSTRT-TBL-LEN PIC S9(4) USAGE BINARY VALUE 152.
Note the following as you use the C copy books:
The resource table data types are mapped into the valid set of C data types. However, exact mapping is not always possible. The resource table data types are mapped as follows:
char - 1-byte binary numeric values
short int - 2-byte binary numeric values
long - 4-byte binary numeric values
- 4-byte intervals
long 2 - Time stamps and 8-byte intervals
8- byte binary numeric values
(an array of two fullwords)
char nnnn - Packed decimal data
char nnnn - Character data
- Binary values greater than 8 bytes
- Odd number binary values less than 8 bytes
Figure 16 is a representative extract of a C resource table copy book:
/*------------------------------------------------------------------*
* Name = EYUC2400 *
* Format Name = EMASSTRT *
* Version = 0001 *
* Status = CPSMREL(0310) *
* Function = Base Table Structure generator *
* Format definition for this element = EMASSTRT *
* Valid Operations = None *
* Valid Actions = None *
*------------------------------------------------------------------*/
typedef struct EMASSTRT {
char CMASNAME??(8??); /* CMAS Name */
char PLEXNAME??(8??); /* CICSPlex Name */
char CSYSNAME??(8??); /* CICS System Name */
char MON_SPEC??(8??); /* Monitor Spec Name */
char RTA_SPEC??(8??); /* Real Time Analysis Spec Name */
char WLM_SPEC??(8??); /* Work Load Manager Spec Name */
char STATUS; /* Status */
char DYNROUTE; /* Dynamic Routing Mode */
char DYNTYPE??(3??); /* Dynamic Routing Type */
char DESC??(30??); /* Description */
char CSYSAPPL??(8??); /* CICS System VTAM APPLID */
char EYU_RSV0015??(5??); /* Alignment Padding */
long MASSTART??(2??); /* MAS Start STCK Value */
char TMEZONEO; /* Time Zone Offset */
char TMEZONE; /* Time Zone */
char EYU_RSV0019??(2??); /* Alignment Padding */
long DAYLGHTSV; /* DayLight savings in effect */
char SYSID??(4??); /* MAS System Id */
char OPSYSREL??(4??); /* MAS Op Sys Release */
char MVSNAME??(4??); /* MVS System Name */
char JOBNAME??(8??); /* MAS Job Name */
char CECNAME??(8??); /* CEC Name */
char SYSPLEX??(8??); /* SYSPlex Name */
char EYU_RSV0257??(4??); /* Alignment Padding */
} EMASSTRT;
/*------------------------------------------------------------------*
* *
* EMASSTRT Defines for Table *
* *
*------------------------------------------------------------------*/
#define EMASSTRT_STATUS_LOCAL 128
#define EMASSTRT_STATUS_REMOTE 64
#define EMASSTRT_DYNROUTE_ACTIVE 1
#define EMASSTRT_DYNROUTE_SUSPEND 2
#define EMASSTRT_DYNTYPE_WLMTOR "TOR"
#define EMASSTRT_DYNTYPE_WLMAOR "AOR"
#define EMASSTRT_TBL_LEN 152