Using the resource table copy books

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.

Note:
This method of returning data differs from the EXEC CICS® system programming interface, where you must fetch each attribute of a resource individually.

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.

How to access the copy books

The copy books are installed as part of the CICSPlex SM installation process. They are placed into the following libraries:

Assembler
CICSTS31.CPSM.SEYUMAC
COBOL
CICSTS31.CPSM.SEYUCOB
PL1
CICSTS31.CPSM.SEYUPL1
C
CICSTS31.CPSM.SEYUC370.

If you want to include the copy books in your program, make sure the appropriate library is available to the assemble or compile step.

Note:
The CICSPlex SM API uses variable names that begin with EYU. Make sure your program does not define variables or structures with variable names that are the same as variable names generated by the translator or declared in the resource table copy books. Also be careful that your program does not implicitly generate such variable names.

Copybook names and aliases

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:

t
Identifies which language the copy book supports, as one of the following:
A
Assembler
P
PL/I
L
COBOL
C
C
nnnn
Is a 4-character numeric resource table identifier.

For example:

EYUA0001
Is the Assembler DSECT for the CICSRGN resource table.
EYUC2451
Is the C structured data type for the CMAS resource table.

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:

EYUtnnnn
The resource table copy book name.
formname
The format name alias, which is the resource table name as shown in CICSPlex System Manager Resource Tables Reference.

So, using the previous example, the Assembler DSECT for the CICSRGN resource table could be referred to as either EYUA0001 or its alias, CICSRGN.

Copybook format

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:

Copybook data characteristics

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:

Supplied copy books

This section provides detailed information about the resource table copy books supplied for each language.

Assembler copy books

Distributed in:
CICSTS31.CPSM.SEYUMAC
Distributed as:
DSECTs
Copybook names:
EYUAnnnn

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:

Figure 13. Sample Assembler 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

PL/I copy books

Distributed in:
CICSTS31.CPSM.SEYUPL1
Distributed as:
Based structures
Copybook names:
EYUPnnnn

Note the following as you use the PL/I copy books:

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:

Figure 14. Sample PL/I 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);

COBOL copy books

Distributed in:
CICSTS31.CPSM.SEYUCOB
Distributed as:
Structures
Copybook names:
EYULnnnn

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:

Figure 15. Sample COBOL 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.

C copy books

Distributed in:
CICSTS31.CPSM.SEYUC370
Distributed as:
Structured data types
Copybook names:
EYUCnnnn

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:

Figure 16. Sample C 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
[[ Contents Previous Page | Next Page Index ]]