SHOWCB—Extract the contents of control block fields

Purpose

SHOWCB extracts the contents of one or more ACB, EXLST, RPL, or NIB fields and places them into an area designated by the application program.

Usage

The SHOWCB user specifies the address of a control block and the names of the fields whose contents are to be extracted. In general, the field names are the same as the keywords of the ACB, EXLST, RPL, and NIB macroinstructions. Not all such field names are supported by SHOWCB. All of the fields applicable for SHOWCB are shown in Table 1 at the end of the SHOWCB macroinstruction description. See Summary of operand specifications, for a list and explanation of the valid formats in which the SHOWCB operands can be specified.

Control block fields that can be operated on by SHOWCB are not limited, however, to fields that can be set by the application program in the ACB, EXLST, RPL, and NIB macroinstructions. Several additional fields whose contents are set only by VTAM® can also be displayed with SHOWCB.

The user of SHOWCB must use the AREA and LENGTH operands to indicate the location and length of the area where the fields are placed. The contents of each field are placed there contiguously, in the order indicated by the FIELDS operand. If the area is too short to hold all of the fields, SHOWCB does not modify the area but returns error codes in register 0 and 15. Table 1 shows the required lengths for all the control block fields that can be displayed with SHOWCB.

Note: The FDBK2 parameter on the SHOWCB macroinstruction represents the RPLFDB2 field.

List, generate, and execute forms of the SHOWCB macroinstruction are available; they are designated by the MF operand. See Optional and required operands for the alternative forms of SHOWCB for more information on this macroinstruction.

The SHOWCB macroinstruction can be issued by an application program running in either 24- or 31-bit addressing mode. To use 31-bit addressing, the application program must use the VTAM mapping macroinstructions as well as GETMAIN and FREEMAIN.

Syntax


>>-+------+--SHOWCB--AM--=--VTAM-------------------------------->
   '-name-'                        

>--+-,--ACB--=--acb_address---------+--------------------------->
   +-,--EXLST--=--exit_list_address-+   
   +-,--NIB--=--nib_address---------+   
   '-,--RPL--=--rpl_address---------'   

>--,--AREA--=--data_area_address-------------------------------->

>--+------------------------------------+----------------------->
   '-,--FIELDS--=--+-field_name-------+-'   
                   '-(--field_name--)-'     

>--,--LENGTH--=--data_area_length------------------------------->

>--+----------------------------------------------------------------+-><
   '-,--MF--=--+-(--E--,--parameter_list_address--)---------------+-'   
               +-(--G--,--parameter_list_address--+----------+--)-+     
               |                                  '-,--label-'    |     
               +-L------------------------------------------------+     
               '-(--L--,--parameter_list_address--+----------+--)-'     
                                                  '-,--label-'

Input parameters

ACB=acb_address
EXLST=exit_list_address
NIB=nib_address
RPL=rpl_address: Indicates the type and location of the control block whose fields are to be extracted. One of these operands must be specified unless a control block length (and only the length) is being extracted. That is, if FIELDS=ACBLEN, FIELDS=EXLLEN, FIELDS=RPLLEN, or FIELDS=NIBLEN is specified, no specific control block need be specified.
AM=VTAM: Identifies the macroinstruction as capable of manipulating a VTAM control block. This operand is required.
AREA=data_area_address: Indicates the location of the storage area in the application program where the contents of the control block field or fields are to be placed. This work area must begin on a fullword boundary.
FIELDS=field_name: Indicates the control block field or fields whose contents are to be extracted.
For field name, code one of the field names that appear in the first column of the table that appears at the end of this macroinstruction description ( Table 1). Most of these field names correspond to keywords of the ACB, EXLST, RPL, and NIB macroinstructions. Only those fields associated with one control block (those for the control block whose address is supplied in the first operand) can be specified.
LENGTH=data_area_length: Indicates the length (in bytes) of the storage area designated by the AREA operand.
If this length is insufficient, SHOWCB returns a value of 4 in register 15 (unsuccessful completion) and a value of 9 in register 0 (insufficient length). The required length for each field is shown in the second column of Table 1.
MF=E, G, or L: Indicates that an execute, generate, or list form of SHOWCB is to be used. Omitting this operand causes the standard form of SHOWCB to be used. See Forms of the manipulative macroinstruction, for a description of the execute, generate, and list forms of SHOWCB.

Examples

SHOW1    SHOWCB NIB=NIB1,FIELDS=NAME,AREA=NAME1,                       C
               LENGTH=8,AM=VTAM

SHOW1 extracts the contents of NIB1's NAME field and places it in NAME1.

SHOW2    SHOWCB RPL=RPL1,FIELDS=(FDBK,ARG,AREA,RECLEN),                C
               AREA=(3),LENGTH=16,AM=VTAM

SHOW2 extracts the contents of RPL1's FDBK, ARG, AREA, and RECLEN fields and places them (in that order) in a storage area. The address of this storage area must be in register 3 when SHOW2 is executed. Note that LENGTH indicates a storage area length great enough to accommodate all four fields.

Completion information

After SHOWCB processing is completed, VTAM sets register 15 to indicate successful or unsuccessful completion. If the operation is completed successfully, register 15 is set to 0, and register 0 contains the total number of bytes that SHOWCB extracted and placed in the work area. If the operation completes unsuccessfully, register 15 is set to either 04 or 08. If register 15 is set to 04 or 0C, register 0 is also set, indicating the specific nature of the error (see Return codes for manipulative macroinstructions, for additional information).