TESTCB—Test the contents of a control block field

Purpose

TESTCB compares the contents of a specified ACB, RPL, EXLST, or NIB field with a value supplied with the macroinstruction and sets the PSW condition code accordingly.

Usage

The user of the TESTCB macroinstruction indicates a particular control block, identifies a single field within that control block, and supplies the value against which the contents of that field are to be tested. Table 1 lists the control block fields that can be tested.

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

The operands for testing control block fields are used in much the same way as operands for modifying or setting control block fields in macroinstructions like MODCB or GENCB. For example, RECLEN=200 in a MODCB macroinstruction places the value 200 in the RECLEN field of an RPL; if RECLEN=200 is specified in a TESTCB macroinstruction, the contents of the RECLEN field are compared with the value 200. See Summary of operand specifications, for a list and explanation of the various formats in which the TESTCB operands can be coded.

The test performed by TESTCB is a logical comparison between the field's actual contents and the specified value. The condition code indicates a high, equal, or low result (with the actual contents considered as A in the A:B comparison). The TESTCB macroinstruction can be followed by any branching assembler instructions that are valid following a compare instruction.

TESTCB can be used to test most control block fields whose contents can be set by the application program, as well as some of the control block fields whose contents are set by VTAM®. The explanation of the field name operand indicates the fields that can be tested.

With the ERET operand of the TESTCB macroinstruction, the application program can supply the address of an error-handling routine. This routine is invoked if some error condition prevents the test from being performed correctly.

List, generate, and execute forms of TESTCB are available; they are designated by the MF operand. (See Forms of the manipulative macroinstruction, for more information.)

The TESTCB 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


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

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

>--+----------------------------------------+------------------->
   '-,--ERET--=--error_exit_routine_address-'   

>--+------------------------------+----------------------------->
   '-,--field_name--=--test_value-'   

>--+----------------------------------------------------------------+-><
   '-,--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 field is to be tested.
This operand is normally required but can be omitted if a control block length is being tested. (To test the control block lengths, specify ACBLEN, EXLLEN, RPLLEN, or NIBLEN for the TESTCB macroinstruction.) Because every control block of a given type is the same length, you do not have to indicate which ACB, EXLST, RPL, or NIB you are testing.
AM=VTAM: Identifies this macroinstruction as a VTAM macroinstruction. This operand is required.
ERET=error_exit_routine_address: Indicates the location of a routine to be entered if TESTCB processing encounters a situation that prevents it from performing the test.
When the ERET routine receives control, register 15 contains a return code. If this return code indicates an error, register 0 contains an error code that indicates the nature of the error. These codes, summarized in the following, are described fully in Return codes for manipulative macroinstructions. Register 14 contains the address of the ERET exit routine and the remaining registers are unchanged.

Note: If this operand is omitted, the program instructions that follow the TESTCB macroinstruction should check register 15 to determine whether an error occurred (indicating that the PSW condition code is meaningless) or not. To make this check without disturbing the condition code, a branching table based on register 15 can be used.
field_name=test_value: Indicates a control block field and a value that its contents are to be tested against. For field name, code one of the field names that appear in the table at the end of this macroinstruction description ( Table 1).
The rules for coding test value are defined and summarized in Summary of operand specifications.
MF=E, G, or L: Indicates that an execute, generate, or list form of TESTCB is to be used. Omitting this operand causes the standard form of TESTCB to be used. See Forms of the manipulative macroinstruction, for a description of the execute, generate, and list forms of TESTCB.

Examples

TESTCB   ACB=ACB1,PASSWD=(6),AM=VTAM
TESTCB   EXLST=EXLST1,SYNAD=SYNADPGM,AM=VTAM

RPL option codes or NIB processing options (including combinations of them) can also be tested. The test results in an equal condition code if all of the specified options are present. The following example shows how to test for the presence of the SPEC and CS option codes of an RPL. The second example illustrates how to code a similar test for the CONFTXT processing option of an NIB.

TESTCB   RPL=RPL1,OPTCD=(SPEC,CS),AM=VTAM
TESTCB   NIB=NIB1,PROC=(CONFTXT),AM=VTAM

Completion information

After TESTCB processing is finished and control is either passed to the ERET error routine or returned to the next sequential instruction, register 15 indicates whether the test was completed successfully. If the test completed successfully, register 15 is set to X'00'; if it completed unsuccessfully, register 15 is set to either X'04' or X'08'.

If register 15 is set to X'04' or X'0C' register 0 is also set indicating the specific nature of the error (see Return codes for manipulative macroinstructions, for additional information).