GENCB—Generate a control block

Purpose

The GENCB macroinstruction builds an ACB, EXLST, RPL, or NIB. The advantage of using the GENCB macroinstruction is that the control blocks are generated during program execution. (With the ACB, EXLST, RPL, and NIB macroinstructions, the control blocks are built during program assembly.)

GENCB not only builds the control block during program execution, but can also build the control block in dynamically allocated storage. One advantage of this technique is that it can remove application program dependencies on the length of each control block.

Usage

The GENCB user specifies the type of control block to be built and the contents of some of its fields. The operands used to specify the field contents are exactly the same as those used in the declarative macroinstruction that builds the control block during assembly. For example, these macroinstructions build the same exit list:

GENCB BLK=EXLST,SYNAD=SYNADPGM,AM=VTAM
EXLST SYNAD=SYNADPGM,AM=VTAM

To build the control block in the application program's storage, the application program should either reserve enough storage during program assembly to accommodate the control block or issue an operating system storage manipulation macroinstruction to get the necessary storage. If an operating system macroinstruction is used, the location and length of this storage must be coded in the GENCB macroinstruction. Dynamic storage allocation for the control block occurs automatically if the location and length operands (WAREA and LENGTH) are omitted.

To free the storage obtained by the GENCB macro, the application program can issue the appropriate operating system instruction.

Ordinarily, the storage should be returned to subpool 0. However, if GENCB is issued in a task running in privileged state, return the storage to subpool 252.

Dynamic storage allocation can be successful only if (1) the program is operating in virtual mode and (2) enough unallocated virtual storage remains in the program's partition or address space to build the control block. See the description of the LENGTH operand for an explanation of how control block lengths are determined.

List, generate, and execute forms of the GENCB macroinstruction are available; they are designated by the MF operand. (See Forms of the manipulative macroinstruction, for more information.) These forms must be used if the invoking routine is reentrant.

Because the GENCB operands can be specified in a large variety of formats, format specifications have been tabulated in Summary of operand specifications, and do not appear in this macroinstruction description.

Note: Not all control block fields can be initialized by using GENCB. See Summary of operand specifications, for those supported. You can initialize other fields at execution time by using the appropriate control block DSECTs described in Control block formats and DSECTs.

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

Syntax


>>-+------+--GENCB--BLK--=--+-ACB---+--,--AM--=--VTAM----------->
   '-name-'                 +-EXLST-+                   
                            +-NIB---+                   
                            '-RPL---'                   

   .-,--COPIES--=--1--------.                             
>--+------------------------+--+----------------------+--------->
   '-,--COPIES--=--quantity-'  '-,--keyword--=--value-'   

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

>--+----------------------------------------------------------------+-><
   '-,--WAREA--=--work_area_address--,--LENGTH--=--work_area_length-'

Input parameters

AM=VTAM

Identifies this macroinstruction as a VTAM macroinstruction. This operand is required.

BLK

Indicates the type of control block to be generated.

BLK=ACB: An ACB control block is to be generated.
BLK=EXLST: An EXLST control block is to be generated.
BLK=NIB: An NIB control block is to be generated.
BLK=RPL: An RPL control block is to be generated.

COPIES=quantity

Indicates the number of control blocks to be generated.

The copies are identical in form and contents. They are placed contiguously in storage, whether that storage is the area indicated by the WAREA operand or in dynamically allocated storage.

The length returned in register 0 is the total length of the generated control blocks. The length of each block (the total length divided by the number of copies) can be used to determine the location of the beginning of each block.

Note: If this operand is not used, one control block is built.

keyword=value

Indicates a control block field and the value that is to be contained or represented within it.

For keyword, code a GENCB-supported keyword (see Summary of operand specifications) that can be used in the macroinstruction corresponding to the BLK operand. If BLK=ACB is used, for example, code the keyword of any GENCB-supported operand that can be used in the ACB macroinstruction. There is one exception: ARG=(register) can also be coded if BLK=RPL.

For value, indicate a register, or code any value that could be used if the operand were being specified in the ACB, EXLST, RPL, or NIB macroinstruction, or use one of the formats indicated in Summary of operand specifications.

Note: If no keywords are included, the following types of control blocks are built.

ACB: All fields are set to their default values as indicated in the ACB macroinstruction description, except MACRF which is set to NLOGON.
RPL: All fields are set to their default values as indicated in the RPL macroinstruction description.
EXLST: All fields are set to 0.
NIB: All fields are set to their default values as indicated in the NIB macroinstruction description.

LENGTH=work_area_length

Indicates the length (in bytes) of the storage area designated by the WAREA operand. If this length is insufficient, register 15 contains the value 4, and register 0 contains the value 9.

Warning: To avoid having to recode your application program should you wish to run it under a different operating system or a different release of VTAM, use the manipulative macroinstructions to obtain the control block lengths. You do this by specifying ACBLEN, EXLLEN, RPLLEN, or NIBLEN in either a SHOWCB or TESTCB macroinstruction.

GENCB fails if LENGTH specifies a smaller value than the length of the control block to be generated. For example, if you use the IFGACB DSECT to determine the length of the ACB, and if your program is assembled on one release of VTAM but is executed on a subsequent release in which the ACB is larger, the GENCB fails.

To obtain the length of an ACB, the following SHOWCB could be coded:

SHOWCB FIELDS=ACBLEN,AREA=WORKAREA,LENGTH=4,AM=VTAM

To test the length of an exit list in your particular operating system, the following TESTCB could be coded:

TESTCB EXLLEN=(7),AM=VTAM

If you are generating more than one control block, remember that the total length of each control block is the length indicated by the control block's length field (ACBLEN, EXLLEN, RPLLEN, NIBLEN) plus the number of bytes required for fullword alignment. (EXLSTs are variable in length; when no specific EXLST is specified, the length returned by SHOWCB or tested by TESTCB is the maximum possible length for your operating system.)

MF=E, G, or L

Indicates that an execute, generate, or list form of GENCB is to be used. Omitting this operand causes the standard form of GENCB to be used. See Forms of the manipulative macroinstruction, for a description of the execute, generate, and list forms of GENCB.

WAREA=work_area_address

Indicates the location of the storage area in the application program where the control block is to be built. The work area must be aligned on a fullword boundary. If this operand is specified, the LENGTH operand must also be specified.

If the WAREA and LENGTH operands are omitted, VTAM obtains dynamically allocated storage from the operating system and builds the control block there. Assuming that GENCB is completed successfully (this is indicated by a return code of 0 in register 15), the address of the generated control block (or blocks) is placed in register 1, and their total length is placed in register 0.

Examples

GEN1     GENCB  AM=VTAM,BLK=ACB,                                       C
               APPLID=(3),EXLST=(6),                                   C
               WAREA=BLOKPOOL,LENGTH=(4)
         .
         .
         .
BLOKPOOL DS    32D

GEN1 builds an ACB in statically reserved storage (BLOKPOOL). When GEN1 is executed, register 3 must contain the address of an application program's symbolic name, and register 6 must contain the address of the exit list to be pointed to by the ACB.

         L     10,WORKAREA         (REG10=ACB LENGTH)
         GETMAIN R,LV=(10)
         LR    5,1                 (REG5=ACB ADDRESS)
GEN2     GENCB  AM=VTAM,BLK=ACB,                                       C
               WAREA=(5),LENGTH=(10)

In this example, the application program is building an ACB in dynamically allocated storage obtained by itself. Using the procedure described in the preceding LENGTH operand description, the application program has obtained the length of an ACB and placed it in a fullword called WORKAREA. The instructions preceding GEN2 obtain the correct amount of storage, and GEN2 builds the ACB in that storage.

GEN3     GENCB BLK=RPL,COPIES=10,AM=VTAM

GEN3 creates 10 RPLs in dynamically allocated storage. The address of the beginning of these RPLs is returned in register 1, and the total length is returned in register 0. This length includes all padding for fullword alignment; the RPLLEN field indicates the length of each unpadded RPL. Each RPL is built as though an RPL macroinstruction with no operands had been issued.

Completion information

After GENCB processing is finished and control is returned to the application program, register 15 indicates whether the operation is completed successfully. If the operation is completed successfully, register 15 is set to 0. If it is completed unsuccessfully, register 15 is set to either X'04', X'08', or X'0C'. 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). After successful completion, register 1 has the address of the generated control blocks, and register 0 has their total length (including padding to a fullword boundary).