Description

The TTOKEN is the 16-byte identifier of a task. Unlike a TCB address, each TTOKEN is unique within the IPL; the system does not reassign this same identifier to any other TCB.

The TCBTOKEN macro provides three mutually exclusive services depending on how you specify the TYPE parameter: z/OS MVS Programming: Extended Addressability Guide describes TTOKENs.
Parent topic: TCBTOKEN — Request or translate the TTOKEN

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state and any PSW key.
Dispatchable unit mode: Task
Cross memory mode: Any
AMODE: 31-bit
ASC mode: Primary or AR
Interrupt Status: Enabled or disabled for I/O and external interrupts
Locks: The caller may hold locks, but is not required to hold any.
Control parameters: Can reside in the primary address space or in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the TCBTOKEN macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0
Used as a work register by the system
1
Address of the TCBTOKEN parameter list
2-13
Unchanged
14
Used as a work register by the system
15
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0
Used as a work register by the system
1
ALET used to address the TCBTOKEN parameter list
2-13
Unchanged
14-15
Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

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

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede TCBTOKEN.
   
TCBTOKEN  
   
␢ One or more blanks must follow TCBTOKEN.
   

TYPE=CURRENT
TYPE=PARENT
TYPE=JOBSTEP

  
   
,TTOKEN=ttoken addr ttoken addr: RX-type address.
   
   ,RELATED=value value: Any valid macro parameter specification.
   

Parameters

The parameters are explained as follows:

TYPE=CURRENT
TYPE=PARENT
TYPE=JOBSTEP
Specifies the type of TCB information requested, as follows:
CURRENT
The system returns the TTOKEN of the currently active task. The TTOKEN is returned at the address specified by the TTOKEN parameter.
PARENT
The system returns the TTOKEN of the task that attached the currently active task. The TTOKEN is returned at the address specified by the TTOKEN parameter.
JOBSTEP
The system returns the TTOKEN of the job step task for the primary address space. The TTOKEN is returned at the address specified by the TTOKEN parameter.
,TTOKEN=ttoken addr
Specifies the address at which the 16-byte TTOKEN associated with the specified TCB is returned.
,RELATED=value
Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user and may be any valid coding values.

ABEND codes

None.

Return codes

When TCBTOKEN returns control, register 15 contains one of the following return codes:

Table 1. Return Codes for the TCBTOKEN Macro
Hexadecimal Return Code Meaning and Action
00 Meaning: TCBTOKEN services completed successfully.

Action: None.
10 Meaning: The TCB could not be referenced.

Action: Ensure that the input TCB address is valid.
14 Meaning: The TCB did not pass the acronym check.

Action: Ensure that the input TCB address is valid.
18 Meaning: The TCB has terminated.

Action: None required.
20 Meaning: An unexpected error occurred.

Action: Reissue TCBTOKEN.
24 Meaning: The contents of access register 1, used to address the parameter list, were not valid.

Action: Change your program to run in primary mode or set access register 1 to zero.
28 Meaning: The parameter list is not valid.

Action: Ensure that the parameter list address is valid and addressable in the calling program's key.
30 Meaning: The task is scheduled for termination, but has not yet terminated.

Action: None required.
34 Meaning: The caller is not running in task mode.

Action: Change your program to run in task mode.

Example

Obtain the TTOKEN for the currently active task and store it in CURRENT_TTOKEN. 
TCBTOKEN  TYPE=CURRENT,TTOKEN=CURRENT_TTOKEN