Description

The EXTRACT macro causes the system to provide information from specified fields of the task control block or a subsidiary control block for either the active task or one of its subtasks. The system places the information in an area that the program provides. For a description of this area see “Providing an EXTRACT Answer Area” in z/OS MVS Programming: Authorized Assembler Services Guide. When EXTRACT is issued, its parameter list can reside in 24 or 31-bit addressable storage.

To obtain the address of a TIOT entry, you can use either the GETDSAB macro or the EXTRACT macro.

Your installation might have installed products that require the use of the GETDSAB macro to obtain the address of the products' TIOT entries. If you plan to use the EXTRACT macro, first check the documentation for the related product to ensure that the product does not require the use of the GETDSAB macro.

Note:

For procedures for using GETDSAB to obtain the address of a TIOT entry and the UCB address, see z/OS MVS Programming: Authorized Assembler Services Guide.
If the EXTRACT macro is used to obtain the TIOT in order to find the UCB, it is the user's responsibility to ensure that the TIOT contains the UCB address. For procedures for finding the UCB address, see z/OS MVS Programming: Authorized Assembler Services Guide.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state, and user key
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in the primary address space

Programming requirements

None.

Restrictions

None.

Performance implications

None.

Syntax

The standard form of the EXTRACT macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede EXTRACT.

EXTRACT

␢	One or more blanks must follow EXTRACT.

`answer addr`	`answer addr`: A-type address, or register (2) - (12).

`,‘S’`	Default: 'S'
`,tcb addr`	`tcb addr`: A-type address, or register (2) - (12).

,FIELDS=`(tcb info)`	`tcb info`: Any combination of the following, separated by commas: ALL PRI GRS CMC FRS TIOT AETX COMM TSO PSB TJID ASID

Parameters

The parameters are explained as follows:

answer addr

Specifies the address of the answer area to contain the requested information. The area is one or more fullwords, starting on a fullword boundary. The number of fullwords must be the same as the number of fields specified in the FIELDS parameter, unless ALL is coded. If ALL is coded, seven fullwords are required.

,'S'

,tcb addr

Specifies the address of a fullword on a fullword boundary containing the address of a task control block for a subtask of the active task. If ‘S’ is coded or is the default, no address is specified and the active task is assumed.

,FIELDS=(tcb info)

Specifies the task control block information requested:

ALL

Requests information from the GRS, FRS, reserved, AETX, PRI, CMC, and TIOT fields. (If ALL is specified, 7 words are required just for ALL.)

GRS

Is the address of the save area used by the system to save the general purpose registers 0-15 when the task is not active.

FRS

Is the address of the save area used by the system to save the floating point registers 0, 2, 4, and 6 when the task is not active.

AETX

Is the address of the end-of-task exit routine specified in the ETXR parameter of the ATTACH (or ATTACHX) macro used to create the task.

PRI

Is the current limit (third byte) and dispatching (fourth byte) priorities of the task. The two high-order bytes are set to zero.

CMC

Is the task completion code. If the task is not complete, the field is set to zero.

TIOT

Is the address of the task input/output table.

COMM

Is the address of the command scheduler communications list. The list consists of a pointer to the communications event control block and a pointer to the command input buffer, and a token. (If a token exists, the high-order bit of the token field is set to one). The token is used only with internal START commands. See “Issuing an Internal START or REPLY Command” in z/OS MVS Programming: Authorized Assembler Services Guide.

TSO

Is the address of a byte in which a high-order bit of 1 indicates a TSO/E address space initiated from the LOGON command (that is, in a foreground TSO/E session). A high-order bit of 0 indicates either background TSO/E or a non-TSO/E address space.

PSB

Is the address of the TSO/E protected step control block and is returned:

In a foreground TSO/E session (initiated through LOGON)
In a background TSO/E session (initiated through the TSO/E TMP, IKJEFT01).
In a TSO/E environment initialized outside of the TSO/E TMP (initiated through the IKJTSOEV service).

TJID

Is the address space identifier (ASID) for a foreground TSO/E session (initiated through LOGON), or zero for either background TSO/E or a non-TSO/E address space.

ASID

Is the address space identifier.

ABEND codes

The EXTRACT macro might abnormally terminate with one of the following abend codes: X'128', X'228', and X'328'. See z/OS MVS System Codes for explanations and programmer responses.

Return and reason codes

None.

Example 1

Provide information from all the fields of the indicated TCB except ASID. WHERE is the label of the answer area, ADDRESS is the label of a fullword that contains the address of the subtask TCB for which information is to be extracted.

EXTRACT WHERE,ADDRESS,FIELDS=(ALL,TSO,COMM,PSB,TJID)

Example 2

Provide information from the current TCB, as above.

EXTRACT WHERE,'S',FIELDS=(ALL,TSO,COMM,PSB,TJID)

Example 3

Provide information from the command scheduler communications list. ANSWER is the label of the answer area and TCBADDR is the label of a fullword that contains the address of the subtask TCB from which information is to be extracted.

EXTRACT ANSWER,TCBADDR,FIELDS=(COMM)