NAMETOKN subcommand — display the token from a name/token pair

Use the NAMETOKN subcommand to obtain the token from a name/token pair in a dump. Specify the name and the level of the name/token pair; in response, NAMETOKN returns the following:

The token data
Whether the name/token pair is persistent
Whether an authorized program created the name/token pair
The address space identifier (ASID) for the address space associated with the name/token pair

Syntax

  NAMETOKN   data-descr

              { NAME((name)) }
              [ LIST | NOLIST]
              [ CLIST (TOKEN(variable-name) )  ]
              [ DIALOG (TOKEN(variable-name) ) ]
              [ REXX (TOKEN(variable-name) )   ]

-------- SETDEF-Defined Parameters -------------------------
Note: You can override the following SETDEF parameters.
See
SETDEF subcommand — set defaults.

              [ FLAG(severity) ]
              [ PRINT | NOPRINT ]
              [ TERMINAL | NOTERMINAL ]
              [ TEST | NOTEST ]

Parameters
data-descr
Describes the level of the name/token pair. The data description parameter consists of five parts:
- An address (required)
- Address processing parameters (optional)
- An attribute parameter (optional)
- Array parameters (optional)
- A remark parameter (optional)
Data description parameter explains the use and syntax of the data description parameter.
To retrieve the token from a task-level name/token pair, specify a TCB on data-descr. For example:
```
NAMETOKN TCB65A NAME((TASKLEV_NAME_003))
NAMETOKN 0F8640. STRUCTURE(TCB) ASID(65) NAME((TASKLEV_NAME_003))
```
To retrieve an primary- or home-address-space-level name/token pair, specify an ASCB on data-descr. For example:
```
NAMETOKN ASCB65 NAME((ASCBLEV_NAME_003))
NAMETOKN 0F2200. STRUCTURE(ASCB) NAME((ASCBLEV_NAME_003))
```
If you specify a data-descr other than an ASCB or TCB, NAMETOKN assumes the token you want to retrieve is from a system-level name/token pair. For example:
```
NAMETOKN 0 NAME((SYSTLEV_NAME_003))
NAMETOKN CVT NAME((SYSTLEV_NAME_003))
```
If you do not specify a data-descr parameter, NAMETOKN assumes the token you want to retrieve is from a system-level name/token pair.
NAME((name))
Specifies the name to be translated. NAMETOKN treats all text inside the parentheses, including blanks, literally. Enclose the name in double parentheses.
If the name contains non-printing hexadecimal characters or lowercase EBCDIC characters, then specify the name using hexadecimal characters. For example:
```
NAMETOKN NAME((X'007D3A23'))
```
In this case, NAMETOKN does not treat the apostrophes and the letter X literally.
LIST or NOLIST

LIST indicates that a report is to be generated. LIST is the default. NOLIST suppresses the generation of a report.

CLIST(TOKEN(variable-name))

DIALOG(TOKEN(variable-name))

REXX(TOKEN(variable-name))

Specifies where IPCS is to store the unedited value of the token associated with the name. variable-name specifies the name of the variable into which the information is stored. If the token cannot be successfully resolved by the NAMETOKEN subcommand, no change is made to the specified command procedure variable.
CLIST directs that the value be stored in CLIST variable storage.

DIALOG directs that the value be stored in ISPF function pool dialog variable storage.

REXX directs that the value be stored in REXX variable storage.

Note: Many binary values can produce unintended results when placed into a CLIST variable. Only names associated with fully-printable EBCDIC tokens should be handled by a CLIST. Command procedures that need to handle arbitrary token values should be written using ISPF DIALOG or REXX services.
Return Codes
See Standard subcommand return codes for a description of the return codes produced by the NAMETOKN subcommand.

Example 1: Retrieve a system-level token from the name/token pair SYSTLEV_NAME_003.

Action

COMMAND ===> NAMETOKN CVT NAME((SYSTLEV_NAME_003))

Results

The following output is produced.

System level
TOKEN.... SYSTLEV_NAME_003_token
NAME..... SYSTLEV_NAME_003_name
ASID..... 000F
Persistent
Created by authorized program

Example 2: Obtain the logrec data set name by retrieving a system-level token from the name/token pair DSNLOGREC. This example has 5 actions.
- Action 1
  In the IPCS dialog, specify your dump data set and options.
- Action 2
  In the IPCS primary menu, choose the COMMAND option. In the COMMAND panel, enter:
```
===> NAMETOKN 0 NAME((DSNLOGREC))
```
- Results
  The following NAMETOKN output is produced.
```
System level
TOKEN.... 01CE0020  0100002C  00000000  00000000
NAME..... DSNLOGREC
ASID..... 0010
Persistent
Created by authorized program
```
- Explanation
  The fields in the output contain:
  - Field 1: Address of area that contains the name of the logrec data set. The data set name field is 44 bytes.
  - Field 2:
    - Byte 1: Version
    - Byte 2: Reserved
    - Bytes 3 and 4: Length of data area pointed to by field 1
  - Field 3: Reserved
  - Field 4: Reserved
- Action 3
  Browse your dump data set to look at the address in the NAMETOKN output.
- Result
```
ASID(X'0010') is the default address space
PTR   Address  Address space                            Data type
00001 00000000 ASID(X'0010')                            AREA
      Remarks:
```
- Action 4
  Add a pointer entry that has the address from field 1 in the NAMETOKN output.
- Results
```
ASID(X'0010') is the default address space
PTR   Address  Address space                            Data type
00001 00000000 ASID(X'0010')                            AREA
      Remarks:
s0002 01CE0020 ASID(X'0010')                            AREA
      Remarks:
```
- Action 5
  Select a new pointer to obtain a display of the logrec data set name.
- Results
```
01CE0020  E2E8E2F1  4BD3D6C7  D9C5C340  40404040  | SYS1.LOGREC |
01CE0030 TO 01CE004F (X'00000020' bytes)--All bytes contain X'40', C' '
```