EXTRACT (Extract Control Information) Macro

The macro is used to retrieve and display partition boundaries or unit information from the PUB table.

It can also be used to retrieve a free tape drive for a subsequent LBSERV MOUNT request.

The retrieved information can be interpreted with the help of the MAPEXTR (or MAPBDY, MAPBDYVR, MAPSYSP) and IJBPUB macros.

Format

To display partition boundaries:
Read syntax diagramSkip visual syntax diagramnameEXTRACT ID=BDY,AREA=name1(S, name1)( r1),LEN=length( r2),MFG=name3( r3),MODE=T,MODE=TEMPPPERMSYSP,PID=name4(S, name4)( r4)
To display unit information:
Read syntax diagramSkip visual syntax diagramnameEXTRACT ID=PUB,AREA=name1(S, name1)( r1),LEN=length( r2),DISP=name6( r6),MFG=name3( r3),PID=name4(S, name4)( r4),SEL=name5(S, name5)( r5)
To retrieve a free tape drive in an automated tape library:
Read syntax diagramSkip visual syntax diagramnameEXTRACT ID=ATLCUU,AREA=name1(S, name1)( r1),LEN=length( r2),MFG=name3( r3)
To retrieve channel path activity:
Read syntax diagramSkip visual syntax diagramnameEXTRACT ID=STCPS,AREA=name1(S, name1)( r1),LEN=length( r2),MFG=name3( r3)

Requirements for the caller

AMODE:
24 or 31
RMODE:
24 or ANY
ASC Mode:
Primary

Parameters

ID=BDY
Indicates that partition boundaries are to be displayed.
ID=PUB
Indicates that unit information is to be displayed.
ID=STCPS
Indicates that information about channel paths currently and actively communicating with a device is retrieved. This service is equivalent to the STCPS z/Architecture® instruction, which might not be available on all models. Further information can be found in z/Architecture Principles of Operation.
ID=ATLCUU
Indicates that a free tape drive in an automated tape library is to be retrieved for a subsequent LBSERV MOUNT request.

If the tape library is VM-controlled, z/VSE searches for a free, not operational tape drive, which was added as '3490E', 'TPA', 'EEFMTx'or 'EFMTx'. Refer to Using Commands for supported tapes. The specified external device type and logical library name are ignored in this case. If the tape library is not controlled by VM, z/VSE searches for a free, operational tape drive belonging to the requested library.

In both cases, if a free cuu is found, the mount ownership flag is set and the cuu is returned to the caller. Mount ownership can only be reset by EOJ processing.

AREA=name1 | (S,name1) | (r1)
Specifies the address of the area where the extracted information is to be stored. For ID=ATLCUU, the area also contains input information as described in Table 4.
LEN=length | (r2)
Specifies the length of the area as an integer, a self-defining term, or as a value in a register.
DISP=name6 | (r6)
Defines the offset within the PUB table entry of the specified device. DISP can be specified as a number, a register containing the displacement value, or the field name in the DSECT generated by the IJBPUB macro.
MFG=name3 | (r3)
The MFG operand is required if the program is to be reenterable. It specifies the address of a 64-byte dynamic storage area, that is: storage which your program obtained through a GETVIS macro. The area is required for system use during execution of the macro.
MODE=T | TEMP | P | PERM | SYSP
MODE=T or MODE=TEMP indicates that the temporary boundaries of the issuing partition plus the PFIX limits of the partition are to be returned. Do not specify the PID operand together with MODE=T|TEMP; a snapshot of any other partition 's temporary boundaries is unreliable.

If your program runs in real mode, the boundaries of the real partition are returned.

The output can be interpreted with the help of the MAPEXTR macro with the keywords ID=BDY and MODE=TEMP. For compatibility reasons, the MAPBDY macro is still supported.

MODE=P or MODE=PERM indicates that the permanent boundaries (including the PFIX limits) are to be returned of either the issuing partition or of the partition indicated by the PID operand. However, these boundaries correspond to the latest allocation and might not have been used by the job active in the partition.

The output can be interpreted with the help of the MAPEXTR macro with the keywords ID=BDY and MODE=PERM. For compatibility reasons, the MAPBDYVR macro is still supported.

MODE=SYSP indicates that information about the system layout is to be provided, including the values for the 31-bit addressable part of the supervisor. The output can be interpreted with the help of the MAPEXTR macro with the keywords ID=BDY and MODE=SYSP. For compatibility reasons, the MAPSYSP macro is still supported for old programs; however, new fields are no longer mapped.

PID=name4 | (S,name4) | (r4)
Specifies the address of a 2-byte field containing the identification key of the partition (PIK) for which the information is retrieved. If this operand is omitted, the identifier of the partition issuing the request is taken as the default.
SEL=name5 | (S,name5) | (r5)
Specifies the address of a halfword containing the logical unit number in the same format as the logical unit number in the CCB.

Return Codes in Register 15

0
The requested information has been extracted and, for ID=ATLCUU, the mount ownership is set.
4
The partition that is specified is not supported in the system. For ID=ATLCUU, an invalid external device type has been specified.
8
The logical unit that is specified exceeds the range of the logical units for the specified partition.
12
The LUB is not assigned or ignored. In addition, an indicator is stored in byte 0 of the area indicated by the AREA operand. This indicator is either
  • X'FF' if the logical unit is unassigned, or
  • X'FE' if the logical unit is assigned IGN.
16
The length value is zero, negative, or below the minimum, or the DISP specification exceeds the length of the PUB entry.
20
For ID=ATLCUU, no free device has been found.