BDTUX02—Unrecognized Spool Data Management (RBAM) Initialization Statements

Type

Customization (optional).

General Description

This exit routine allows an installation to identify and process spool data management (RBAM) initialization statements not recognized by BDTINIC. RBAM statements precede network initialization statements processed by BDTUX03. BDTINIC processes the OPTIONS statement and the ENDRBAM statement. The exit routine runs only during cold or warm starts. BDTINIC is the initialization module that processes initialization statements that structure the BDT work queue.

You can also use the exit routine to identify and process unrecognized keywords specified on the OPTIONS statement.

For example, you might write:

USERSTMT,PASS=YES
   .
   .
   .
OPTIONS,PRIORITY=6

where:

USERSTMT is the unrecognized user statement
PASS is the keyword on the unrecognized user statement
YES is the value associated with the keyword
OPTIONS is the recognized BDT initialization statement
PRIORITY is the unrecognized keyword on the BDT initialization statement. The value associated with the keyword is 6.

See Initialization Flow and User Exit Routines for an understanding of how this user exit routine fits into the initialization process.

BDTINIC invokes BDTUX02 for four reasons. A reason code in register 0 informs the user exit routine of the purpose for which it is run. The user exit routine does not parse the statement; parsing is performed by BDTINIC. BDTINIC passes the information to the user exit routine.

Reason=0 Invalid initialization statement

This invocation allows the user to recognize and process initialization statements not recognized by BDT. BDTINIC calls the exit routine to examine the statement. If the exit routine does not recognize it, BDTINIC processes the statement as an error.

Reason=4 Process a keyword on the user-defined statement

This invocation allows the user to recognize and process a keyword and its parameters on a user-defined initialization statement. BDTINIC calls BDTUX02 with reason=4 as long as there are keywords associated with a user-defined initialization statement.

Reason=8 EOD condition on a user-defined statement

This invocation communicates the end-of-data condition to the user exit routine. BDTINIC has passed all the keywords on an unrecognized statement.

Reason=12 Unrecognized keyword on an OPTIONS statement

This invocation allows the user to recognize and process user-defined keywords on the OPTIONS initialization statement.

Register Conventions at Entry

BDTXCALL linkage is used to establish the interface to the BDTUX02 user exit routine. Registers 2-14 are saved by BDT ASAVE processing in BDTGRSV.

Register 0

Contains a reason code:

Reason 0: Unrecognized initialization statement
Reason 4: Keyword on the user-defined initialization statement
Reason 8: End-of-data condition
Reason 12: Invalid OPTIONS statement keyword

Register 1

Contains the address of the parameter list. The parameter list contents depend upon the reason for which the user exit routine runs.

Reason 0

Word 1: Address of the unrecognized initialization statement

Reason 4

Word 1: Address of the keyword on a user-defined initialization statement
Word 2: Address of the keyword parameter value
Word 3: Address of a halfword field containing the length of the keyword parameter value

Reason 8

No parameters are passed when the exit routine runs for an EOD condition.

Reason 12

Word 1: Address of the OPTIONS initialization statement unrecognized keyword
Word 2: Address of the keyword’s parameter value
Word 3: Address of a halfword field containing the length of the keyword parameter value

Register 11

Contains the address of the initialization data CSECT, BDTINDT.

Register 12

Contains the address of the BDT TVT.

Register 13

Points to the register save area set up by ASAVE processing.

Register 14

Contains the address of the return point in BDTGRSV.

Register 15

Contains the entry point address into the BDTUX02 user exit routine.

Register Conventions at Exit

Because BDTXCALL linkage is used to establish the interface to the BDTUX02 user exit routine, registers 2-14 of BDTINIC are saved in BDTGRSV. You must store registers 12, 13, and 14 in an area you provide (either a GETMAINed area or one within your user exit routine) and those registers must be restored on return to BDTGRSV by register 14.

Register 14

Contains the address of the return point in BDTGRSV.

Register 15

Used for returning a return code value set by the BDTUX02 user exit routine.

For reason codes 0, 4, and 8:

RC 0: Indicates that the BDTUX02 user exit routine recognizes the statement and BDTINIC continues initialization processing.
RC 4: Indicates that BDTUX02 does not recognize the statement or keyword. BDTINIC prints the statement and initialization continues until complete. At this time, BDT terminates due to the error.
RC 8: Indicates that the BDTUX02 user exit routine failed to recognize the statement or its keywords. BDTINIC prints the statement and causes initialization to terminate as soon as possible.

For reason code 12:

RC 0: Indicates that the BDTUX02 user exit routine recognizes the user-defined keyword on the OPTIONS statement and processing continues.
RC 4: Indicates that BDTUX02 does not recognize the user-defined keyword on the OPTIONS statement. BDTINIC prints an error message and processing continues until initialization is complete. At this time, BDT terminates due to the error.
RC 8: Indicates that the BDTUX02 user exit routine failed to recognize the user-defined keyword on the OPTIONS statement. BDTINIC prints an error message and terminates initialization as soon as possible.

Operation

When BDTINIC encounters an unknown initialization statement, it passes control to the user exit routine with reason code=0. If the exit routine recognizes the statement, it sets a return code of 0 in register 15 and returns to BDTINIC.

BDTINIC invokes the exit routine again for each keyword it encounters on the user-defined initialization statement. The exit routine runs in this case with reason code=4.

When all keywords have been processed, the exit routine is called with reason code=8, which informs the exit routine of the end-of-data condition on the user-defined keyword.

For each exit call with reason codes 0, 4, and 8, a return code of 0 indicates the exit routine recognizes the statement as user-defined; a return code of 4 indicates the exit routine failed to recognize the parameter as user-defined, but the error is not serious enough to fail BDT initialization immediately. A return code of 8 indicates an error serious enough to prevent BDT from completing initialization as soon as possible. Error messages are issued for return codes 4 and 8.

For reason code 12, a return code of 0 indicates that the user-defined keyword on the OPTIONS statement is recognized. Processing continues. A return code of 4 causes BDTINIC to issue an error message; processing continues until the end of initialization. Then BDT terminates. A return code of 8 causes BDTINIC to issue an error message, then terminate initialization processing as soon as possible.

Recovery the Exit Routine Must Establish: You should provide ESTAE protection for your exit routine in the event of an abend. If there is no recovery in the routine, an ESTAE recovery routine in BDTABMN provides clean-up in the case of system failure.

Environment

Point Where Exit Routine Receives Control: This exit routine receives control during BDT cold or warm starts when the initialization file must be opened, read, and closed.

Address Space in Which Exit Routine Runs: BDT address space.

Task under Which Exit Routine Runs: This exit routine runs under the TCB of BDTINIT.

PSW State: Supervisor.

Storage Protection Key: BDTKEY (key 8).

Data Areas

Mapping Macros

BDTDINT to map the initialization data CSECT
BDTDREG to map the registers
BDTDTVT to map the TVT
BDTDGSD to update the generalized subtask directory (GSD) (if you code an ESTAE)

Executable Macros

BDTXASRV to invoke abend services (if you code an ESTAE)

What If BDTUX02 Is Not Used?

If the exit routine is not provided, the error handling for the unrecognized initialization statement issues error message BDT3243. It displays the unrecognized statement. The message processing sets the severe error indicator. This causes the eventual termination of BDT initialization. BDTINIC processing continues by reading the next initialization statement.