Accessing resource table data

Because of the way CICSPlex® SM supplies resource table data to REXX, two additional commands are provided as part of the REXX function package. These commands are TPARSE and TBUILD.

TPARSE: Extracts individual resource table attributes from a record and places them into standard REXX variables. The resource table record itself can be supplied in any valid REXX variable, including a stem variable.
You can use TPARSE to break down and access the attribute data in a resource table record.
TBUILD: Builds a CPSM Definition or CICS® Definition resource table record from a set of variables that you supply. Each variable must contain an individual resource table attribute.
You can use TBUILD to build the resource table record for a definition that you want to create, update, or remove in the CICSPlex SM data repository.

Note: TBUILD only uses attributes that you specify; it does not assume any default values for optional attributes. If you do not supply a variable for an attribute that is optional, the corresponding field in the resource table record is initialized according to its data type (that is, character fields are set to blanks, binary data and EYUDA values are set to zeroes).

The variables that represent the resource table attributes are created either by CICSPlex SM, in the case of TPARSE, or by you, in the case of TBUILD. The variable names are formed by adding a prefix to the attribute name, like this:

  prefix_fieldname

where:

prefix: Is a text string that you supply. The maximum allowable length for a prefix is determined by REXX and the environment in which the program runs.
fieldname: Is the name of an attribute in the resource table.

An underscore character (_) must be inserted between the prefix and the attribute name.

When a program written in REXX passes resource table records to the API, the format and layout of the record must be exactly as it is defined by CICSPlex SM.

Best practices for using TBUILD and TPARSE

The TBUILD and TPARSE processors require significant sets of internal storage structures to execute. Where possible, these structures are reused for the execution of consecutive TBUILD and TPARSE commands. But over time storage fragmentation will arise, causing the eventual consumption of an increasing amount of address space storage. TPARSE and TBUILD failures will occur because of storage unavailability.

This issue should not cause ill effects to applications that execute in the form of a single logical pass. However, applications that run in the form of extended long running processes might start to report TPARSE and TBUILD failures.

To resolve this issue, you can insert EYUINIT() and EYUTERM() calls to cause these structures to be released and reallocated with each process pass.

For example, observe the following code:


  XX = EYUINIT();
  XX = EYUAPI('CONNECT CONTEXT('my_context') THREAD(TTKN.1) .... ;
    Do Forever;
    /* perform application processing that includes TPARSE or TBUILD commands */
      ...
      ...      
    If Loop_Termination = True then
        Signal EndJob;
    End; /* Do Forever */
 EndJob:
  XX = EYUAPI('DISCONNECT THREAD(TTKN.1) .... ;
  XX = EYUTERM();
  Return;

If the Do Forever loop executes TBUILD or TPARSE calls, over time the executions will fail because of storage fragmentation. The recommended solution is to insert EYUINIT() and EYUTERM() calls inside the loop, as follows, to cause these structures to be released and reallocated with each process pass:


  Do Forever;
    XX = EYUINIT();
    XX = EYUAPI('CONNECT CONTEXT('my_context') THREAD(TTKN.1) .... ;
    /* perform application processing that includes TPARSE or TBUILD commands */
     ...
     ...
    XX = EYUAPI('DISCONNECT THREAD(TTKN.1) .... ;
    XX = EYUTERM();
    TTKN. = '00'X; /* Reset the Thread Token */
    If Loop_Termination = True then
      Signal EndJob;
  End; /* Do Forever */
EndJob:
  Return;

Considerations for processing attribute values

The TBUILD and TPARSE commands use the TRANSLATE API command when processing certain resource table attributes. For example, EYUDA and CVDA values are maintained in a resource table record in their numeric form. By default, the TPARSE command converts these values into a displayable character form. TBUILD, on the other hand, converts any EYUDA or CVDA character values that you supply into their numeric equivalents.

However, if you use the ASIS option on these commands, attribute values are not converted. If you specify ASIS on the TPARSE command, you must also specify ASIS on the TBUILD command when you rebuild the record so that the API does not try to reconvert the values.

If you specify ASIS on the TPARSE command and then decide you want to convert the attribute values, you can use the TRANSLATE API command.

Considerations for processing FEEDBACK attributes

Having used a TPARSE command to extract the individual resource table attributes, additional processing may be required before the data can be used in subsequent API commands.

The ERR_RESULT error result set token is returned in decimal format and must be converted to character format before it can be used in a RESULT() option. To do this, you can use the D2X() and X2C() REXX built-in functions. For example:

var = X2C(RIGHT(D2X(FEEDBACK_ERR_RESULT),8,'0'))