TRKCALC—Standard Form

The format of the TRKCALC macro is:


>>-listname--TRKCALC--FUNCTN=-+-TRKBAL-+--+-,DEVTAB=addr-+------>
                              '-TRKCAP-'  +-,UCB=addr----+   
                                          '-,TYPE=addr---'   

>--+---------------+--+-----------------+----------------------->
   '-,BALANCE=addr-'  |       .-BELOW-. |   
                      '-,LOC=-+-ANY---+-'   

>--+------------------+--+-------------------+------------------>
   |          .-NO--. |  |           .-NO--. |   
   '-,REMOVE=-+-YES-+-'  '-,MAXSIZE=-+-YES-+-'   

>--+-,RKDD=addr---------------+--+-------------------+---------->
   '-,R=addr-,K=addr-,DD=addr-'  |           .-NO--. |   
                                 '-,REGSAVE=-+-YES-+-'   

>--+------------+----------------------------------------------><
   |      .-I-. |   
   '-,MF=-+---+-'

FUNCTN=TRKBAL or TRKCAP

Specifies the function to be performed. Specify one of the three keywords, DEVTAB, UCB, or TYPE, to provide the information source for the macro.

TRKBAL

If REMOVE=NO is specified, TRKBAL calculates whether an additional record fits on the track and what the new track balance would be if the record were added. If REMOVE=YES is specified, TRKBAL calculates what the track balance would be if a record were removed from the track. The record to be added or removed from the track is defined by the RKDD parameter, or by the R, K, and DD parameters.

If R is equal to 1 (or the R value in the RKDD parameter is 1) and REMOVE=NO is specified, TRKCALC will treat record 1 as if it were being added to an empty track; if R is equal to 1 and REMOVE=YES is specified, TRKCAL will treat record 1 as if it were being deleted from the track, leaving an empty track.

If R is not equal to 1, the specified record is added to or removed from the track. If the input track balance is not supplied through the BALANCE parameter, it is assumed that the track contains equal-sized records as specified in the RKDD parameter (or in the R, K, and DD parameters).

When REMOVE=NO is specified, one of the following occurs:

If the record fits on the track, register 0 contains the new track balance.
If the record does not fit on the track and MAXSIZE=NO is specified, a record does not fit return code is placed in register 15.
If the record does not fit and MAXSIZE=YES is specified, one of the following happens:
- The data length of the largest record that fits in the remaining space is returned in register 0.
- A code is returned that indicates no record fits in the remaining space.

When REMOVE=YES is specified, one of the following occurs:

If R is equal to 1, register 0 contains the track capacity.
If R is not equal to 1, registers 0 contains the input track balance (supplied through the BALANCE parameter) incremented by the track balance used by the input record. If the input balance is not supplied, register 0 contains the track capacity left after R–1 records are written on the track.

TRKCAP

Calculates, and returns in register 0, the number of fixed-length records that can be written on a whole track (R is equal to 1) or on a partially-filled track (R is not equal to 1). The records are defined by the K and DD values of the RKDD parameter, or by the K and DD parameters.

Depending on the value for R, one of the following occurs:

If R is equal to 1, TRKCALC ignores the BALANCE parameter and makes the calculation as if the track were empty.
If R is not equal to 1 and the BALANCE parameter is omitted, the calculation is made for a track that already contains R–1 records of the length defined by the K and DD values.
If R is not equal to 1 and the BALANCE parameter is supplied, the calculation is made for a track whose remaining track balance is the value of the BALANCE parameter.

DEVTAB=addr—RX-type address, (2-12), (0), (14)

addr specifies a word that contains the address of the device characteristics table entry (DCTE). If you specify a register, it contains the actual address of the DCTE. The address of the DCTE can be found in the word beginning at the DCBDVTBL field of an opened DCB.

UCB=addr—RX-type address, (2-12), (0), (14)

addr specifies the address of a word that contains the address of the UCB. If you specify a register, it contains the actual address of the UCB.

The TRKCALC macro accepts the address of a UCB or UCB copy. Unauthorized programs can get a copy of the UCB by using the UCBSCAN macro and specifying the COPY and UCBAREA keywords. See z/OS HCD Planning for more information.

TYPE=addr—RX-type address, (2-12), (0), (14)

You can specify the address of the UCB device type (UCBTBYT4), or you can specify the 1-byte UCB device type in the low-order byte of a register.

LOC=BELOW or ANY

Optional parameter indicating whether the value passed by the UCB parameter is a 4-byte or a 3-byte address. This parameter only applies to callers running in AMODE 31. If the caller is running in AMODE 24, this parameter is ignored and the high-order byte is treated as X'00'.

BELOW: The UCB parameter contains a UCB address for a UCB which resides in storage below 16 megabytes, or a captured UCB. This is the default.
If LOC=BELOW is specified, the high-order byte of the UCB address will be treated as X'00'.
ANY: The address passed in the UCB parameter contains a 3-byte or 4-byte UCB address.
If LOC=ANY is specified when invoking in 31-bit mode, TRKCALC will treat the UCB address as a 31-bit address.

BALANCE=addr—RX-type address, (2-12), (0), (14)

You can specify either the address of a halfword containing the current track balance, or you can specify the balance in the low-order two bytes of a register. The value supplied could be the value returned when you last issued TRKCALC. If R is equal to 1, the balance is reset to track capacity by TRKCALC, and your supplied value is ignored. This is an input value and is not modified by the TRKCALC macro. The resulting track balance is returned in register 0 and in the TRKCALC parameter list field STARBAL. The value you supply for this parameter must be a valid value for the device type in use.

REMOVE=YES or NO

Indicates if a record is to be deleted from the track.

YES: Specifies that the record identified by the record number (specified in the R keyword) is being deleted from the track. The track balance is incremented instead of decremented.
YES is valid only on a FUNCTN=TRKBAL call.
NO: Specifies that a record is not to be deleted from the track. NO is the default.

MAXSIZE=YES or NO

YES: If the specified record does not fit, the largest length of a record with the specified key length that fits is returned (register 0).
YES is valid only on a FUNCTN=TRKBAL call.
NO: Maximum size is not returned. NO is the default.

RKDD=addr—RX-type address, (2-12), (0), (14)

addr specifies a word containing a record number (1 byte), key length (1 byte), and data length (2 bytes) (bytes 0, 1, and 2 and 3, respectively) or a register containing the record number, key length, and data length. R, K, and DD can be specified by this keyword, or you can use the following three keywords instead.

R=addr—RX-type address, (2-12), (0), (14), or n: You can specify either the address of the record number, or you can specify the record number using the low-order byte of a register or immediate data (n). Specify a decimal digit for n (immediate data).
K=addr—RX-type address, (2-12), (0), (14), or n: You can specify either the address of a field containing the hexadecimal value of the record's key length, or you can specify the record's key length using the low-order byte of a register or immediate data (n). Specify a decimal digit for n (immediate data).
DD=addr—RX-type address, (2-12), (0), (14), or n: You can specify either the address of a field containing the hexadecimal value of the record's data length, or you can specify the record's data length using the low-order two bytes of a register or immediate data (n). Specify a decimal digit for n (immediate data).

REGSAVE=YES or NO

Specifies whether registers are to be saved.

YES: Specifies registers 1 through 14 are saved and restored in the caller-provided save area (pointed to by register 13) across the TRKCALC call. Otherwise, registers 1, 9, 10, 11, and 14 are modified. Registers 0 and 15 are always modified by a TRKCALC call.
NO: Specifies registers are not saved across a TRKCALC call. NO is the default.

MF=I

Specifies storage definition for the TRKCALC parameter list and parameter list initialization, using the given keywords, then calling the TRKCALC function. MF=I is the default.