SWBTUREQ — Call SJF SWBTU processing services

Description

SWBTUREQ requests services for processing scheduler work block text units (SWBTUs). The RETRIEVE service can be requested on the SWBTUREQ macro. RETRIEVE obtains text unit information from SWBTUs for a specified set of keys and places the information in the output area defined by the caller.

An SWBTU is made up of JCL statement or dynamically created JCL information in contiguous text unit format. More than one SWBTU may be used to represent a single JCL statement.

Examples of the use of SWBTUREQ RETRIEVE are the JES sysout separator page installation exits. See the HASX15A member of SYS1.SAMPLIB for a sample exit.

For the RETRIEVE service, there are three calls that you can make:

A call to determine the local working storage size needed for the service
A call to determine the output area size needed to accommodate all the matched text units
A call to obtain the text units that match the requested keys.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state, and any PSW key. For SWBTUREQ RETRIEVE, the caller must have a PSW key that matches the key of the caller's storage.
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in the primary address space

Programming requirements

The caller must set up recovery for SWBTUREQ RETRIEVE. The caller must include the CVT and IEFJESCT mapping macros. IEFSJTRP maps the storage for the required RETRIEVE service parameter list. SWBTUREQ RETRIEVE input parameters describes the parameter list's input fields. SWBTUREQ RETRIEVE output describes the fields that contain output on return from the SWBTUREQ RETRIEVE service.

The caller is responsible for supplying all storage for SWBTUREQ RETRIEVE processing. You can use SWBTUREQ RETRIEVE with different combinations of parameters to determine the local working storage size needed, and to determine and obtain the output area size needed for a particular request. A third combination of parameters allows you to invoke SWBTUREQ RETRIEVE to obtain text unit information. Table 1 lists the required combination of parameters to use based on the type of service call you are making.

Restrictions

None.

Input register information

On input to the SWBTUREQ macro, the caller must insure that general purpose register (GPR) 13 points to a standard, 72-byte save area.

Output register information

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0: If GPR 15 contains a zero, GPR 0 is used as a work register by the system. If GPR 15 contains return code 12, GPR 0 contains a reason code; otherwise, GPR 0 contains zero.
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

Performance implications

None.

Syntax

The standard form of the SWBTUREQ macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede SWBTUREQ

SWBTUREQ

␢	One or more blanks must follow SWBTUREQ

REQUEST=`service`	`service`: Service name

,PARM=`addr`	`addr`: RX-type address, or registers (2) - (12). Register 1 is the default.

Parameters

The parameters are explained as follows:

REQUEST=service: Specifies the SJF SWBTU service to be called. RETRIEVE is the valid service name.
,PARM=addr: Specifies the address of the parameter list for the service requested. The parameter list for the RETRIEVE service is IEFSJTRP. SWBTUREQ RETRIEVE input parameters lists the parameter fields you must initialize.

SWBTUREQ RETRIEVE service

Use RETRIEVE to obtain text unit information for a specified set of JCL or output descriptor keys. The retrieved information is placed in a caller-defined output area.

Table 1. Parameter Combinations for SWBTUREQ RETRIEVE Functions
Function	Required Parameters
Obtain local working storage size	SJTRID, SJTRVERS, SJTRLEN, SJTRSTOR, SJTRSTSZ, SJTRAREA, and SJTRSIZE. SJTRSTOR, SJTRSTSZ, SJTRAREA, and SJTRSIZE should be zero on this invocation.
Obtain output area size	SJTRID, SJTRVERS, SJTRLEN, SJTRSTOR, SJTRSTSZ, SJTRSWBN, SJTRSWBA, SJTRKIDN, SJTRKIDL. Fill in SJTRSTOR and SJTRSTSZ with the values returned when you invoked the macro to determine the local working storage size. SJTRAREA and SJTRSIZE should be zero on this invocation.
Retrieve requested keys	SJTRID, SJTRVERS, SJTRLEN, SJTRSTOR, SJTRSTSZ, SJTRSWBN, SJTRSWBA, SJTRKIDN, SJTRKIDL. Fill in SJTRSTOR, SJTRSTSZ, SJTRAREA, and SJTRSIZE with the values returned when you invoked the macro to determine the local working storage size and the output buffer size.

SWBTUREQ RETRIEVE input parameters

For each SWBTUREQ invocation, you need to initialize certain fields of parameter list IEFSJTRP. Figure 1 illustrates some of the parameter fields and their relationships to other fields. The list below describes the valid value assignments for all input parameters in IEFSJTRP.

SJTRID

The identifier ‘SJTR’ of the SWBTUREQ RETRIEVE parameter list. Assign the symbolic equate SJTRCID to this field.

SJTRVERS

The current version number of the SWBTUREQ RETRIEVE service. Assign the symbolic equate SJTRCVER to this field.

SJTRLEN

The length of the SWBTUREQ RETRIEVE parameter list (IEFSJTRP). Assign the symbolic equate SJTRLGTH to this field.

SJTRSTOR

The local working storage pointer or zero.

SJTRSTSZ

The size of the local working storage area required by the service.

SJTRSWBN

The number of SWBTUs in the SWBTU address list table. The table is mapped by SJTRSBTL.

SJTRSWBA

The address of the SWBTU address list table from which text units are retrieved. The address list is mapped by SJTRSBTL.

SJTRAREA

The address of the text unit output area.

SJTRSIZE

The size of the text unit output area.

SJTRKIDN

The number of entries in the key list. The key list is mapped by SJTRKEYL.

SJTRKIDL

The address of the list of keys that are to be retrieved. The key list is mapped by SJTRKEYL.

SJTRSBTL

SWBTU address list from which text units are returned. The list contains one entry per SWBTU. Parameter SJTRSWBN specifies the number of entries in the list; SJTRSWBA specifies the address of the list. More than one SWBTU may be used to represent a single JCL statement.

SJTRSTUP: An SWBTU address entry.

SJTRKEYL

The requested list of keys to be retrieved. Parameter SJTRKIDN specifies the number of entries in the list; SJTRKIDL specifies the address of this list.

SJTRKYID: The key to be used for the retrieve. If you are using the RETRIEVE service to obtain information about output descriptors, the key values for the attributes are defined in mapping macro IEFDOKEY. See z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for the mapping provided by IEFDOKEY. z/OS MVS Programming: Authorized Assembler Services Guide lists the dynamic output keys and their JCL equivalents.

SWBTUREQ RETRIEVE output

These parameters are returned with values on completion of RETRIEVE service processing.

SJTRREAS

The reason code returned. The reason codes are defined in Return and reason codes.

SJTRWKSZ

The local working storage size required by the SWBTUREQ service.

SJTRTULN

The size of the area needed to contain all matched requested text units.

SJTRERRP

This field contains a zero unless a parameter list error (key list or SWBTU address entry error) occurs. In the case of a key list error (return code 8 with a reason code of 65), the address of the key list entry in error appears in the field. In the case of a SWBTU address entry error (return code 8 with a reason code of 19 or 28), the address of the SWBTU address entry in error appears in the field.

SJTRAREA

The address of the text unit output area. The text unit output area contains the matched text unit strings organized by key in the order they were requested. Matched text unit strings are contiguous in the text unit output area. For the mapping of each text unit see the IEFDOTUM mapping macro in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.

SJTRKEYL

The requested key list. Parameter SJTRKIDN specifies the number of entries in the list; SJTRKIDL specifies the address of this list.

SJTRTPAD: The address of a text unit for this key in the output area. Values are returned in this field only if the key and text unit match. If the address is not found, this field is zero.

Figure 1. Relationship of Data and Work Areas Referenced in IEFSJTRP ieaa4rdw

ABEND codes

None.

Return and reason codes

Return codes appear in register 15. If you receive return code 12, the reason code appears in register 0. If you receive return codes 0, 4, or 8, the reason code appears in output field SJTRREAS. Return and reason codes are defined in macro IEFSJTRC. The hexadecimal return and reason codes from the SWBTUREQ RETRIEVE service are as follows:

Table 2. Return and Reason Codes for SWBTUREQ RETRIEVE
Return Code	Reason Code	Meaning and Action
00	None	Meaning: RETRIEVE processing completed successfully. At least one text unit and key match was found. For any unmatched text units, the corresponding SJTRTPAD values are zero. Action: None.
04	None	Meaning: Either the caller did not provide enough storage for the service or none of the requested items was found. This is the expected return code if you issue the RETRIEVE request to obtain the working storage size or output area size.
	004	Meaning: RETRIEVE requires more local working storage. The size of the local working storage, as specified in input parameter SJTRSTSZ, is not large enough for the service. The amount of local working storage needed appears in output parameter SJTRWKSZ. Action: Repeat the request and supply the amount of storage returned in SJTRWKSZ in SJTRSTSZ.
	008	Meaning: RETRIEVE requires more text unit output area storage. The size needed for the output storage area appears in output parameter SJTRTULN. Action: Repeat the request and supply the amount of storage returned in SJTRTULN in SJTRAREA.
	064	Meaning: Successful completion. None of the keys in the input key list were found in the SWBTUs. All corresponding SJTRTPAD values are zero. There are no returned text units in the output area. Action: None required.
08	None	Meaning: The parameter list is not valid.
	015	Meaning: The parameter length specified in SJTRLEN is not valid for the specified version.
	016	Meaning: The version number specified is not correct for this service.
	018	Meaning: The caller must provide at least one SWBTU. Input parameter SJTRSWBN must be greater than zero, and SJTRSWBA must reference the SWBTU address list. Action: Set SJTRSWBN to a value greater than zero; set SJTRSWBA to the address of the SWBTV address list.
	019	Meaning: The specified SWBTU is not valid. Either one of the entries is zero, or the SWBTU address entry is not valid. Output parameter SJTRERRP contains the address of the SWBTU address entry. Action: Specify a valid SWBTU referenced by the SWBTU address is in SJTRERRP.
	01A	Meaning: Program error. The text length shown in the DOCNTLEN field in the IEFDOTUM mapping macro is not valid. SWBTUREQ RETRIEVE processing stops. One possible cause of the problem is a storage overlay. Action: If your program has overlaid storage, correct the error and rerun the program. Otherwise, contact the appropriate IBM® support personnel.
	028	Meaning: Either all of the verbs for the SWBTUs or all of the labels for the SWBTUs do not match. Output parameter SJTRERRP contains the address of the SWBTU address entry where the inconsistency was found. Action: Correct the SWBTU in the SWBTU address table entry whose address is in SJTRERRP.
	029	Meaning: The output area size, defined by the combination of the input parameters SJTRAREA and SJTRSIZE, is not valid. One of the parameters is zero and the other is not zero. Action: Set SJTRAREA and SJTRSIZE to values greater than 0. (See SWBTUREQ RETRIEVE input parameters.)
	065	Meaning: The key entry is not valid. Input parameter SJTRKYID is zero. Output parameter SJTRERRP contains the address of the error key entry, SJTRKYID. Action: Correct the key in error (the key pointed to by SJTRKYID).
	066	Meaning: At least one key must be requested. Input parameter SJTRKIDN must be greater than zero and SJTRKIDL must reference the key entry list. Action: Set SJTRKIDN and SJTRKIDL to values greater than zero. (See input parameter description.)
0C	None	Meaning: A severe parameter list error occurred. The reason code appears in register 0.
	014	Meaning: An incorrect parameter ID was specified. SJTRID is not ‘SJTR’. Action: See SWBTUREQ RETRIEVE input parameters for SJTRID.
	015	Meaning: An incorrect parameter length was specified. SJTRLEN is not at least as large as the common parameter list size, 36 bytes. Action: See SWBTUREQ RETRIEVE input parameters for SJTRLEN.
	016	Meaning: The version number is not correct. SJTRVERS is less than one. Action: See SWBTUREQ RETRIEVE input parameters for SJTRVERS.
	017	Meaning: The service specified by SWBTUREQ REQUEST=`service`, is not known. Action: Specify a valid request for 'service'.
14	None	Meaning: SJF encountered a condition that would have caused an abend. If processing had continued, an abend would have occurred.
18	None	Meaning: The service routines for SWBTUREQ are not available.

Example

Invoke the SWBTUREQ RETRIEVE service to obtain text unit information for three output descriptor attributes (title, name, and room). Represent the output descriptor with SWBTU1 and SWBTU2. Use register 6 to contain the address of SWBTU1, and register 7 to contain the address of SWBTU2. Use AREA to define the text unit output area. Define the service's local working storage in LCLSTOR. Establish an ESTAE for a recovery environment.

On return, register 15 contains return code 0, register 0 contains reason code 0, and SJTRREAS contains reason code 0. The output areas from the service contain the following information:

SJTRAREA contains two contiguous text units that were in the SWBTUs and were requested in the key list.
SJTRWKSZ contains the size of local working storage required for the SWBTUREQ RETRIEVE service.
SJTRTULN contains the size of the area used to return the two matched text units.
SJTRKEYL contains unchanged SJTRKYIDs.
- SJTRTPAD contains the pointers for the matched text units and zero for unmatched text units. For this example, SJTRTPAD's first entry points to the first text unit returned in the text unit output area. The second entry contains zero, and the third entry points to the second text unit returned in the text unit output area.

***********************************************************************
*                                                                     *
*        Fill in 3 requested keys in the key list, SJTRKEYL.          *
*                                                                     *
***********************************************************************
*
         XC    KEYLIST,KEYLIST     Initialize KEYLIST area
         LA    R2,KEYLIST          Point to start of key list
         USING SJTRKEYL,R2         Establish addressability
*
         MVC   SJTRKYID+0*SJTRKLEN,=Y(DOTITLE)   Title Key
         MVC   SJTRKYID+1*SJTRKLEN,=Y(DONAME)    Name Key
         MVC   SJTRKYID+2*SJTRKLEN,=Y(DOROOM)    Room Key
*
***********************************************************************
*                                                                     *
*        Fill in 2 SWBTU pointers in SWBTU address list, SJTRSBTL.    *
*                                                                     *
***********************************************************************
*
         XC    SWBTULST,SWBTULST   Initialize SWBTU pointer list area
*
         LA    R3,SWBTULST         Point to start of SWBTU pointer list
         USING SJTRSBTL,R3         Establish addressability
*
         ST    R6,SJTRSTUP         Set address of first SWBTU in 1st
*                                   entry of SWBTU address list
         LA    R3,SJTRSLEN(,R3)    Point to second entry in SWBTU
         ST    R7,SJTRSTUP         Set address of second SWBTU in 2nd
*                                   entry of SWBTU address list
*
***********************************************************************
*                                                                     *
*        Fill in the SWBTUREQ RETRIEVE parameter list, IEFSJTRP.      *
*                                                                     *
***********************************************************************
*
         XC    SJTRP(SJTRLGTH),SJTRP  Clear the parameter list
         MVC   SJTRID,=A(SJTRCID)  Parameter list ID
         MVI   SJTRVERS,SJTRCVER   Parameter list version
         LA    R4,SJTRLGTH         Get parameter list length
         STH   R4,SJTRLEN          Set parameter list length
*
         LA    R4,LCLSTOR          Get local working storage address
         ST    R4,SJTRSTOR         Set local working storage address
         LA    R4,STORLGTH         Get local working storage size
         STH   R4,SJTRSTSZ         Set local working storage size
*
         LA    R4,AREA             Get text unit output area address
         ST    R4,SJTRAREA         Set text unit output area address
         LA    R4,AREALGTH         Get text unit output area size
         STH   R4,SJTRSIZE         Set text unit output area size
*
         ST    R2,SJTRKIDL         Set key list address
         LA    R4,KEYNUM           Get number of requested keys
         STH   R4,SJTRKIDN         Set number of request keys
*
         LA    R3,SWBTULST         Point to start of SWBTU pointer list
         ST    R3,SJTRSWBA         Set address of SWBTU address list
         LA    R4,SWBTUNUM         Get number of SWBTUs
         STH   R4,SJTRSWBN         Set number of SWBTUs
*
***********************************************************************
*                                                                     *
*        Set up Register 1 to point to a word of storage that         *
*        contains the address of the parameter list, IEFSJTRP.        *
*                                                                     *
***********************************************************************
*
         LA    R4,SJTRP            Address of
         ST    R4,SJTRPPTR           the SWBTUREQ RETRIEVE
         LA    R1,SJTRPPTR             parameter list
*
***********************************************************************
*                                                                     *
*        Invoke the SWBTUREQ macro to retrieve the matched text units *
*        for items in the requested key list.                         *
*                                                                     *
***********************************************************************
*
         SWBTUREQ REQUEST=RETRIEVE  Issue the SJF macro
*
***********************************************************************
*                                                                     *
*        Check for a zero return code.                                *
*                                                                     *
***********************************************************************
*
         LTR   R15,R15             Check service return code
         BNZ   NODATA              Go to nonzero return processing
*
*        Code to process zero return code from SWBTUREQ ...
*         .
*         .
*         .
*
NODATA   DS    0H                  Label used for branch when SWBTUREQ
*                                   service returns with a nonzero
*                                   return code.
*
*        Code to process nonzero return code from SWBTUREQ...
*         .
*         .
*         .
*
***********************************************************************
*                                                                     *
*        Storage definitions                                          *
*                                                                     *
***********************************************************************
*
  IEFSJTRP DSECT=NO                SWBTUREQ Retrieve parameter list
*
SJTRPPTR DS    A                   Field used to contain SJTRP address
*
KEYLIST  DS    CL24                Area mapped by SJTRKEYL:
*                                   enough storage for 3 entries
*
SWBTULST DS    CL16                Area mapped by SJTRSBTL:
*                                   enough storage for 2 entries
*
AREA     DS    CL600               Area used by SWBTUREQ service to move
*                                   matched text units for output.
*                                   600 bytes is large enough and was
*                                   chosen at random.
AREALGTH EQU   *-AREA              Size of AREA
*
LCLSTOR  DS    CL1000              Area used by SWBTUREQ service as
*                                   local working storage.
STORLGTH EQU   *-LCLSTOR           Size of LCLSTOR
*
***********************************************************************
*                                                                     *
*        Equates and Constants                                        *
*                                                                     *
***********************************************************************
*
R0       EQU   0                   Register 0
R1       EQU   1                   Register 1
R2       EQU   2                   Register 2
R3       EQU   3                   Register 3
R4       EQU   4                   Register 4
R15      EQU   15                  Register 15
*
SWBTUNUM EQU   2                   Indicates number of SWBTUs
KEYNUM   EQU   3                   Indicates number of requested keys
*
         IEFDOKEY                  Dynamic Output keys
         CVT   DSECT=YES           CVT mapping macro
         IEFJESCT                  IEFJESCT mapping macro