 |
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 five mutually exclusive services depending
on how you specify the TYPE parameter: - TYPE=TOTTOKEN gives you the TTOKEN for the task associated with
a specified TCB address.
- TYPE=TOTCB gives you the TCB address for a specified TTOKEN.
- TYPE=CURRENT gives you the TTOKEN for the current task.
- TYPE=PARENT gives you the TTOKEN for the task that attached the
current task.
- TYPE=JOBSTEP gives you the TTOKEN for the job step task.
Typical situations when you would use TYPE=TOTTOKEN are: - When you create a data space and want to assign ownership of the
data space to a second task.
In this case, you know the TCB address
for the second task, but you don't know its TTOKEN (for input to the
DSPSERV CREATE macro). Use TYPE=TOTTOKEN to obtain the TTOKEN.
- When you want to delete a data space you do not own.
In this
case, you know the TCB address for the other task, but you don't know
its TTOKEN (for input to the DSPSERV DELETE macro). Use TYPE=TOTTOKEN
to obtain the TTOKEN.
- When you want to know whether the owner of a data space still
exists.
In this case, you know the TTOKEN for the owning task.
If the system returns the TCB address in response to the TYPE=TOTCB
parameter, the task still exists.
z/OS MVS Programming: Extended Addressability Guide describes
STOKENs and TTOKENs. Environment
The requirements for the caller are:
| Environmental factor |
Requirement |
|---|
| Minimum authorization: |
Problem or supervisor state, any PSW key |
| Dispatchable unit mode: |
For TOTTOKEN or TOTCB requests, the caller can
be in task or SRB mode. For CURRENT, PARENT, and JOBSTEP requests,
the caller must be in task mode. |
| Cross memory mode: |
Any |
| AMODE: |
31-bit |
| ASC mode: |
Primary or AR |
| Interrupt Status: |
Enabled or disabled for I/O and external interrupts |
| Locks: |
For TOTTOKEN and TOTCB requests, the caller must
hold the local lock or CML lock of the specified address space. For
CURRENT, PARENT, and JOBSTEP requests, there is no requirement. |
| 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) |
Register information
After the caller issues the macro, the macro might use some registers
as work registers or might change the contents of some registers.
When the macro returns control to the caller, the contents of these
registers are not the same as they were before the macro was issued.
Therefore, if the caller depends on these registers containing the
same value before and after issuing the macro, the caller must save
these registers before issuing the macro and restore them after the
system returns control.
When control returns to the caller, the general purpose registers
(GPRs) contain: - Register
- Contents
- 0-1
- Used as work registers by the macro
- 2-13
- Unchanged
- 14
- Used as a work register by the macro
- 15
- Return code
When control returns to the caller, the access registers (ARs)
contain: - Register
- Contents
- 0-1
- Used as work registers by the macro
- 2-13
- Unchanged
- 14-15
- Used as work registers by the macro
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=TOTTOKEN |
Note: See the table following this diagram for
information on parameter usage with TYPE.
|
| TYPE=TOTCB |
|
| TYPE=CURRENT |
|
| TYPE=PARENT |
|
| TYPE=JOBSTEP |
|
| |
|
| ,TCB=tcb addr |
tcb addr: RX-type address or
register (2) - (12). |
| |
|
| ,TTOKEN=ttoken addr |
ttoken addr: RX-type address. |
| |
|
| ,ASCB=ascb addr |
ascb addr: RX-type address
or register (2) - (12). |
| ,STOKEN=stoken addr |
stoken addr: RX-type address. |
| |
Default: Home address space. |
| |
|
| ,RELATED=value |
value: Any valid macro parameter
specification. |
| |
|
The following table shows how the parameters may be specified with
the TYPE keywords.
| Parameters |
TYPE= TOTTOKEN |
TYPE= TOTCB |
TYPE= CURRENT |
TYPE= PARENT |
TYPE= JOBSTEP |
|---|
| TCB |
required |
required |
not valid |
not valid |
not valid |
| TTOKEN |
required |
required |
required |
required |
required |
| ASCB |
optional |
optional |
not valid |
not valid |
not valid |
| STOKEN |
optional |
not valid |
not valid |
not valid |
not valid |
| RELATED |
optional |
optional |
optional |
optional |
optional |
Parameters
The parameters are explained as follows:
- TYPE=TOTTOKEN
- TYPE=TOTCB
- TYPE=CURRENT
- TYPE=PARENT
- TYPE=JOBSTEP
- Specifies the type of TCB information requested, as follows:
- TOTTOKEN
- The system returns the TTOKEN of the task whose TCB address is
specified in the TCB parameter. The TTOKEN is returned at the address
specified by the TTOKEN parameter.
- TOTCB
- The system returns the TCB address for the task whose TTOKEN is
specified in the TTOKEN parameter. The TCB address is returned at
the address specified by the TCB parameter.
- 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 address
space in which the currently active task is running. The TTOKEN is
returned at the address specified by the TTOKEN parameter.
- ,TCB=tcb addr
- Specifies the TCB address. For TYPE=TOTTOKEN, tcb addr contains
the TCB address that is to be translated to a TTOKEN. For TYPE=TOTCB, tcb
addr points to a fullword where the system returns the TCB
address for the task whose TTOKEN is specified by the TTOKEN parameter.
- ,TTOKEN=ttoken addr
- Specifies the address of the 16-byte TTOKEN. For TYPE=TOTTOKEN,
TYPE=CURRENT, TYPE=PARENT, and TYPE=JOBSTEP, ttoken addr is
the address at which the TTOKEN associated with the specified TCB
is returned. For TYPE=TOTCB, ttoken addr is the
address of the TTOKEN for the task whose TCB address is to be obtained.
- ,ASCB=ascb addr
- ,STOKEN=stoken addr
- Identifies the address space of the TCB. ASCB specifies the address
of the fullword containing the ASCB address. STOKEN specifies the
address of the 8-byte STOKEN that identifies the address space in
which the TCB resides. If you do not specify either ASCB or STOKEN,
TCBTOKEN uses the home address space by default.
- ,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.
Return codes
When TCBTOKEN returns control, register 15 contains one of the
following hexadecimal return codes:
Table 1. Return Codes for the
TCBTOKEN Macro| Return Code |
Meaning and Action |
|---|
| 00 |
Meaning: TCBTOKEN services completed successfully. Action:
None.
|
| 04 |
Meaning: The input STOKEN or TTOKEN does
not represent a valid address space. Action: Ensure that
you specify a valid token on the STOKEN or TTOKEN keywords.
|
| 08 |
Meaning: No local lock was held. Action:
Obtain the local lock before issuing TCBTOKEN.
|
| 0C |
Meaning: A local lock was held, but not
the local lock of the associated address space. Action:
Obtain the correct local lock before issuing TCBTOKEN.
|
| 10 |
Meaning: The TCB could not be referenced. Action:
Ensure that the input TCB address specified on the TCB keyword is
valid.
|
| 14 |
Meaning: The TCB did not pass the acronym
check. Action: Ensure that the input TCB address specified
on the TCB keyword is valid.
|
| 18 |
Meaning: The TCB has ended. The TCB
control block has not been deleted yet. Action: None
required.
|
| 1C |
Meaning: The TCB associated with the TTOKEN
represents a different task than when the TTOKEN was obtained. Action:
None required.
|
| 20 |
Meaning: An unexpected error occurred. Action:
Reissue the TCBTOKEN macro.
|
| 24 |
Meaning: The contents of access register
1, used to address the parameter list, were not valid. Action:
Either 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.
|
| 2C |
Meaning: The ASCB address is the address
of the wait ASCB. The system cannot obtain the TTOKEN. Action:
Specify an ASCB address which is not the wait ASCB.
|
| 30 |
Meaning: The task is scheduled for termination,
but has not yet terminated. The TCB control block has not been
deleted yet. Action: None required.
|
| 34 |
Meaning: The caller is not running in task
mode. This return code is valid only for TYPE=CURRENT, TYPE=PARENT,
or TYPE=JOBSTEP. Action: Change your program to run in task
mode.
|
Note: Return codes 04, 08, 0C, 1C, and 2C are valid only with TYPE=TOTTOKEN
and TYPE=TOTCB.
Example 1
Obtain the TTOKEN for the task whose TCB address is specified in
THEIR_TCB. The task resides in the address space whose ASCB address
is specified in register 4. Store the returned TTOKEN in THEIR_TOKEN. TCBTOKEN TYPE=TOTTOKEN,TCB=THEIR_TCB,TTOKEN=THEIR_TTOKEN,ASCB=(4)
Example 2
Obtain the TTOKEN for the currently active task and store it in
CURRENT_TTOKEN. TCBTOKEN TYPE=CURRENT,TTOKEN=CURRENT_TTOKEN
Example 3
Obtain the TCB address of the job step TCB and store it in JOBSTEP_TCB_ADDR. TCBTOKEN TYPE=JOBSTEP,TTOKEN=JOBSTEP_TTOKEN
TCBTOKEN TYPE=TOTCB,TTOKEN=JOBSTEP_TTOKEN,TCB=JOBSTEP_TCB_ADDR
|
z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
Copyright IBM Corporation 1990, 2014