EXTENTS: Storage Area Where Extents Are Returned

EXTENTS=addr

Specifies the address where extent information is to be returned. You specify this parameter only when you also specify MAP=VOLUME to request that unallocated space information from the volume is to be returned.

When RTA4BYTE=YES is specified the following occurs:

Information about free extents uses mapping macro ICVEDT02 (see Using Macro ICVEDT02 to Map the Extents Area for ICVEDT02 format).
EXTENTS= specifies the address of a control block (ICVEDT02) used to pass 4 byte relative track addresses of the unallocated space. You provide this storage, and you must use this mapping macro to initialize it.
Prior to calling CVAF, initialize the ICVEDT02 control block as follows:
- Place "ICVEDT02" in the first 8 bytes (DT2X7EYE).
- Place the total area length, in bytes, in DT2X7LEN. This value is 36 + (8 * the value in DT2X7ENT).
- Set the control block level number to "1" (DT2X7LEV). (Note that this value can be different in a possible future release, if IBM® makes changes that effect the control block.)
- Set the remaining fields in the control block static area DT2X7FLG through DT2X7RE2 to zero prior to calling CVAF for the first time. Leave these fields unchanged from the way the previous call returned them, when calling for additional extents.
- Set DT2X7ENT to the total number of extent descriptor entries that will fit in the storage you provide.
- Place the relative track address (RTA) at which CVAF should start the search into the first four bytes of the first extent area DT2RTAST(1).
  CVAF updates the first extent entry with information about the next free extent found that has a higher starting RTA than that provided. Each subsequent extent entry is filled in with information about additional free space extents (in ascending RTA order).
  
  For all calls, if all the unallocated extents from the volume are returned before the provided storage area is filled, the remaining entries are set to zero. CVAF will now set return code 4 in register 15, and will set the CVSTAT field to X'20' to indicate end of data.
  
  If End Of Data is reached before the provided storage area is filled with unallocated extents, CVAF will set return code 4 in register 15. If return code 0 is set in register 15, you can call CVAF again to get the remaining unallocated space information if there is any. Do NOT modify ANY header information in ICVEDT02, as CVAF can have saved internal use restart information there. Instead, copy the last ending RTA+1 (DT2RTAED) returned from the previous CVAF search into DT2RTAST.

When RTA4BYTE=NO is specified or defaulted the following occurs:

Information about free extents has the format of XXYYZ (see RTA4BYTE: Specify the Type of Extent Area Used for XXYYZ format).
EXTENTS= is the address of a 1-byte count field containing the number of 5-byte entries that follow. You provide this storage area. The length of the area, in bytes, is 1 + ( count * 5), where count is the value of the first byte of the area. The first two bytes ("XX") of the first 5-byte extent area entry, is the relative track address (RTA) at which CVAF will start the search. CVAF updates the first entry with information about the next free extent found that has a higher starting RTA than that supplied. Each subsequent entry is filled in with information about additional free extents (in ascending track address order).
CVAF can be called multiple times, as needed, to retrieve more extents than the area can hold in a single call. The first extent returned is the first free extent after the relative track address ("XX") recorded in the first extent (XXYYZ) in the area.
To retrieve the first free extent on the volume, set "XX" in the first entry to zero. When calling additional times, set "XX" in the first entry to the LAST relative track address returned by the previous call.

Recommendation: If you use larger volumes, specify RTA4BYTE=YES when you request extent information. If an extent is beyond the 64x1024 tracks boundary when the program specifies RTA4BYTE=NO or allows the default, the CVAF request fails with a CVSTAT of STAT075.