Building the Browse Token (DALBRTKN)

Before issuing the dynamic allocation request, the application must build the browse token and pass it with the DALBRTKN text unit. The format of the browse token is mapped by macro IAZBTOKP. The browse token is built in text unit format with 7 subparameters. When building the browse token, the following SVC 99 text unit fields must be set: The token is of fixed length and all subparameters must be coded. Each browse token subparameter contains a length followed by the data, so it will be in text unit format.

You can complete the fields in the token as follows:

BTOKPL1

Length of the browse token identifier (LENGTH(BTOKID)).

BTOKID

Browse token id (BTOK). The IAZBTOKP macro defines constant BTOKCID to be used to set this field.

BTOKPL2

Length of the token version field (LENGTH(BTOKVER)).

BTOKVER

The 2 byte version number of the token parameter list. Byte 1 (or TOKTYPE) indicates the call type. If it is set to BTOKBRWS, then this is a normal browse request. If it is set to BTOKSTKN, then this is a SPOOL token based browse request. JES3 supports only BTOKSTKN. Byte 2 (or BTOKVERS) is the parm list version and should be set to BTOKVRNM.

BTOKPL3

Length of the data pointer field.

BTOKIOTP/BTOKSPLT

Data pointer whose content is based on the first byte of BTOKVER.

BTOKIOTP

If BTOKVER is set to BTOKBRWS (JES2 only), this is a normal browse, and BTOKIOTP is either zero or the MTTR of the IOT containing the PDDB of the file to be allocated (obtained from JOEIOTTR or IOTTRACK, for example). The data set name supplied in DALDSNAM keyed text unit is used to locate the specific data set to be allocated. If BTOKIOTP is zero, the data set is located by using only the data set name.

BTOKSPLT

If BTOKVER is set to BTOKSTKN, BTOKSPLT can be zeroes or point to a client token (returned from dynamic allocation using key DALRTCTK) or a data set token (returned by the SAPI SSI in field SSS2DSTR or the Extended Status SSI in field STVSCTKN). If BTOKIOTP is zeroes, JES will use the data set name supplied in the DALDSNAM keyed text unit to find the specific data set to allocate. If BTOKIOTP points to a client or data set token, the token is used to find the data set to allocate and the data set name supplied in the DALDSNAM keyed text unit is ignored.

BTOKPL4

Length of the job key field (LENGTH(BTOKJKEY)).

BTOKJKEY

Optional job key of the file to be allocated (for example, the job key obtained from JCTJBKEY, JQEJBKEY, or SJBJKEY). This field is not used if BTOKVER is set to BTOKSTKN. This field is required if BTOKTYPE is set to BTOKBRWS and BTOKIOTP is non-zero. JES3 does not support this parameter and this field is set to zero.

BTOKPL5

Length of the ASID field (LENGTH(BTOKASID)).

BTOKASID

The 2 byte ASID of the data set owning job if active buffers are needed. If active buffers are not needed, then pass 0. If the ASID is not known, then pass X'FFFF' and JES will determine the correct ASID.

BTOKPL6

Length of the RECVR field (LENGTH(BTOKRCID)).

BTOKRCID

Eight byte userid to be used as the RECVR on the SAF call or zeros if the RECVR is not being used. JES uses this field to check authority to the browse request. When RECVR is used, the value must be left justified and padded with blanks. For JES3, this is supported for authorized callers only.

When this parameter is specified, the logstr field should also be used so that usage of recvr can be logged. However, neither JES nor SAF enforces this convention.

BTOKPL7

Length of the logstr field (LENGTH(BTOKLOGS)).

BTOKLSDL

Length of the logstr (specified in field BTOKLSDA) to be used on the SAF call used by JES to check authority to the browse request, or zero if the logstr is not being used.

The logstr length must be a value from 0 to 254.

BTOKLSDA

Text of the logstr if BTOKLSDL is non-zero, or zeros if the logstr is not being used.

The maximum length text is 254 characters.