LSPACE-Execute Form

The format of the execute form of the LSPACE macro is:


>>-+-------+--LSPACE--MF=-+-(E,addr)--+--+-----------------+---->
   '-label-'              '-(E,(reg))-'  '-,UCB=-+-addr--+-'   
                                                 '-(reg)-'     

>--+---------------------+--+----------------+------------------>
   +-,MSG=-+-addr--+-----+  '-,SMF=-+-TEST-+-'   
   |       +-(reg)-+     |          +-YES--+     
   |       '-0-----'     |          '-NONE-'     
   +-,EXPMSG=-+-addr--+--+                       
   |          +-(reg)-+  |                       
   |          '-0-----'  |                       
   +-,DATA=-+-addr--+----+                       
   |        +-(reg)-+    |                       
   |        '-0-----'    |                       
   +-,XEXPMSG=-+-addr--+-+                       
   |           +-(reg)-+ |                       
   |           '-0-----' |                       
   '-,EXPDATA=-+-addr--+-'                       
               +-(reg)-+                         
               '-0-----'                         

>--+--------------------+--+--------------------------+--------><
   '-,F4DSCB=-+-addr--+-'  |            .-ALL-------. |   
              +-(reg)-+    '-,DATATYPE=-+-FRAGINDEX-+-'   
              '-0-----'                 +-INDEX-----+     
                                        +-VOLUME----+     
                                        '-VTOC------'

MF=(E,addr) or (E,(reg))

Specifies the execute form of the LSPACE macro.

The MF=L form is usually issued before the execute form to create the parameter list.

(E,addr): Loads the address of the parameter list specified by addr into register 1 and then issues a supervisor call.
(E,(reg)): Loads the address of the parameter list specified by (reg) into register 1 and then issues a supervisor call.

UCB=addr or (reg)

Specifies the address of the UCB for the volume whose free space information you are requesting. The address can be for a captured UCB, or for an actual UCB above or below the 16MB line. For 31-bit callers, the high-order byte is part of the UCB address and must be cleared to zeros if a 24-bit UCB address is being passed.

addr—RX-type address: Specifies the address of a fullword containing the UCB address.
(reg)—(2-12): Specifies a register containing the UCB address for the device. Note that this differs from the addr form of the parameter.

When using the standard (MF=I) form of the macro, you must provide a UCB address.

Restrictions:

The LSPACE macro will accept 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. The UCB copy can be above or below the 16MB line and on a word boundary. Refer to z/OS HCD Planning for details.
LSPACE does not support VIO UCBs.

MSG=addr or (reg)or 0 or EXPMSG=addr or (reg) or 0 or DATA= addr or (reg) or 0

Specifies the way LSPACE is to return free space information. (optional)

Restriction: The MSG, EXPMSG, and DATA parameters are mutually exclusive.

MSG=addr or (2-12) or 0

Specifies the address of a caller-provided 30-byte message return area into which LSPACE returns either a free space message or, for unsuccessful requests, status information. For a description of this area, see Message Return Area.

addr–RX-type address: Specifies the address of the message return area.
(reg)–(2-12): Specifies a register containing the address of the message return area.
0: Specifies that you do not want the free space message. This is the default for all forms of the macro except execute.

EXPMSG=addr or (reg) or 0

Specifies the address of a caller-provided 40-byte expanded message return area into which LSPACE returns either a free space message or, for unsuccessful requests, status information. For a description of this area, see Expanded Message Return Area.

addr–RX-type address: Specifies the address of the message return area.
(reg)–(2-12): Specifies a register containing the address of the message return area.
0: Specifies that you do not want the free space message. This is the default for all forms of the macro except execute.

DATA=addr or (reg) or 0

Specifies the address of a caller-provided data return area into which LSPACE returns free space and volume information. For a description of this area, see Data Return Area.

addr–RX-type address: Specifies the address of the data return area.
(reg)–(2-12): Specifies a register containing the address of the data return area.
0: Specifies that you do not want the free space and volume information.

SMF=TEST or YES or NONE

Specifies the type of SMF processing.

TEST: Specifies that LSPACE is to test for an active SMF system and whether SMF volume information is desired. If these conditions are met, an SMF record is written.Only programs executing in supervisor state, protect key 0-7, or APF authorized can specify this operand.
YES: Specifies that you want an SMF record containing volume information to be written. Only programs executing in supervisor state, protect key 0-7, or APF authorized can specify this operand.
NONE: Specifies that you do not want an SMF record containing volume information to be written. This is the default for all forms of the macro except execute.

F4DSCB=addr or (reg) or 0

Specifies the address of a 96-byte DSCB return area provided by the calling program, into which LSPACE returns the volume's format-4 DSCB. For a description of the format-4 DSCB fields, see Table 1.

addr– RX-type address: Specifies the address of the format-4 DSCB return area.
(reg)– (2-12): Specifies a register containing the address of the format-4 DSCB return area.
0: Specifies that you do not want the data portion of the format-4 DSCB for the volume. This is the default for all forms of the macro except execute.

XEXPMSG=addr or (reg) or 0

Specifies the address of a caller-provided 95-byte extended expanded message return area into which LSPACE returns either a free space message or, for unsuccessful requests, status information. Specify this keyword if you wish to obtain free space information in the message return area for volumes that are configured with cylinder-managed space. The returned free space will include space for the total volume and space from the track-managed space on a volume. The two sets of free space message data will be the same for a volume that does not have cylinder-managed space. The use of XEXPMSG is recommended for all requests to return message data. See LSPACE Information Return Areas for a description of the message return area.

addr– RX-type address: Specifies the address of the message return area.
(reg)– (2-12): Specifies a register containing the address of the message return area.
0: Specifies that you do not want the free space message. This is the default for all forms of the macro except execute.

EXPDATA=addr or (reg) or 0

Specifies the address of a caller-provided EXPANDED data return area into which LSPACE returns expanded free space and volume information. Specify this keyword if you wish to obtain free space information and total volume space in the LSPACE data return area for volumes. The returned free space will include space for the total volume and space from the track managed space on a volume. For volumes with cylinder-managed space this data will be returned as free space for the entire volume and free space for the track-managed space. The two sets of free space data will be the same for a volume that does not have cylinder-managed space. The use of EXPDATA is recommended for all requests to return binary data. See Table 1 for a description of the expanded data return area.

addr– RX-type address: Specifies the address of the expanded data return area.
(reg)– (2-12): Specifies a register containing the address of the expanded data return area.
0: Specifies that you do not want the expanded free space and volume information.

DATATYPE= ALL or FRAGINDEX or INDEX orVOLUME orVTOC

This keyword is allowed only when the DATA or EXPDATA keyword is specified. Only the information specified will be returned to the caller. DATATYPE is valid for both non-EAV and EAV. This keyword will eliminate unnecessary I/O required to retrieve free space information that is not be required by the caller. DATATYPE=ALL is the default.

ALL: Provide all available LSPACE statistics. This is the default
FRAGINDEX: Provide the fragmentation index
INDEX: Provide free space information related to the VTOC INDEX
VOLUME: Provide free space information for the VOLUME
VTOC: Provide free space information related to the VTOC

PLISTVER

This keyword, if specified on the MF=E form of the LSPACE macro, will generate an MNOTE.