EVALMAP subcommand — format a storage map entry

Use the EVALMAP subcommand to retrieve information associated with an entry in the storage map and to format that information in CLIST variables, REXX variables, or ISPF function pool dialog variables.

The storage map is part of a source description. The source description is for an unformatted source that IPCS can format, for example, an SVC dump, a stand-alone dump, an SYSMDUMP dump, a trace data set, a data set, or active storage. The source description is in a directory allocated with ddname IPCSDDIR and is your current dump directory. The current dump directory is your user dump directory or, for users with access authority, might be the sysplex dump directory.

Numeric information may be formatted in decimal or hexadecimal. Default formatting for pointers and data used in conjunction with pointers is hexadecimal. Default formatting for other numeric data is decimal.

Note: With TSO/E Release 2 installed, you can use this subcommand to update global CLIST variables. For information about using global variables and writing your own CLISTs, see z/OS TSO/E CLISTs and z/OS MVS IPCS User's Guide.

Related subcommands
- EQUATE
- EVALDEF
- EVALDUMP
- EVALSYM

Syntax

  EVALMAP    [ relational-operator ]

             data-descr
             [SELECT([AREA][MODULE][STRUCTURE])]
             [ CLIST(var-list)  ]
             [ DIALOG(var-list) ]
             [ REXX(var-list)   ]

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

             [ TEST | NOTEST ]

Parameters

The DIMENSION, ENTRY, HEXADECIMAL, LENGTH, MULTIPLE, POSITION, and X parameters may appear in both the data-descr and var-list variables.

relational-operator

Specifies one of the following symbolic or programming operators to be used in conjunction with the data description to identify which map entry is to be retrieved. The syntax for relational-operator is as follows:

      [  < | LT ]
      [ <= | LE ]
      [  > | GT ]
      [ >= | GE ]
      [ ¬> | NG ]
      [ ¬< | NL ]
      [  = | EQ ]

For example, the less than(<|LT) relationship is satisfied by the highest-collating map entry that collates lower than the byte addressed by the data description.

data-descr

Specifies the data description parameter, which 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.

Note: The qualification, address, and data type are all part of the key of a map entry. To write a CLIST or dialog that moves from one map entry to another, you must specify all three arguments in your data description.

SELECT([AREA][MODULE][STRUCTURE])

Specifies the data types to be returned as results of the EVALMAP command.

AREA: Allows EVALMAP to associate the location of interest with AREAs.
MODULE: Allows EVALMAP to associate the location of interest with MODULEs.
STRUCTURE: Allows EVALMAP to associate the location of interest with STRUCTUREs.

When no selection is specified or all selections are chosen, EVALMAP can associate the location of interest with AREAs, MODULEs, or STRUCTUREs.

CLIST(var-list)

DIALOG(var-list)

REXX(var-list)

Specifies how the information is to be formatted.

CLIST(var-list) designates that the information be formatted into CLIST variables.

DIALOG(var-list) designates that the information be formatted into ISPF function pool dialog variables.

REXX(var-list) designates that the information be formatted into REXX variables.

The syntax for var-list is as follows:

     [ DECIMAL | F     ]
     [ HEXADECIMAL | X ]
     [ ADDRESS(address) ]
     [ ANALYSIS(analysis) ]
     [ DATATYPE(type[,group]) ]
     [ DIMENSION(dimension)|MULTIPLE(dimension) ]
     [ ENTRY(entry) ]
     [ FLAG(flag) ]
     [ LENGTH(length) ]
     [ POSITION(position) ]
     [ QUALIFICATION(qualification) ]

DECIMAL or F

HEXADECIMAL or X

Specifies the format of the numeric information.

DECIMAL or F designates that the numeric information be formatted using decimal digits.

HEXADECIMAL or X designates that the numeric information be formatted using hexadecimal digits.

Table 1 summarizes the effect of specifying DECIMAL and HEXADECIMAL on the other parameters.

Table 1. Effect of DECIMAL and HEXADECIMAL on the other parameters
Parameter	Default	DECIMAL changes the default?	HEXADECIMAL changes the default?
ADDRESS	HEXADECIMAL	yes
DIMENSION	DECIMAL		yes
ENTRY	DECIMAL		yes
LENGTH	DECIMAL		yes
POSITION	HEXADECIMAL	yes

ADDRESS(address)

Requests that the address associated with the map entry be formatted and placed in the variable address. Unless DECIMAL is specified, the address is formatted in hexadecimal; if DECIMAL is specified, decimal digits are used.

ANALYSIS(analysis)

The degree of validation completed for the block is placed in the variable analysis:

NOCHECKER
NONE
PARTIAL
COMPLETE

DATATYPE(type[,group])

Requests that the data type associated with the map entry be formatted and placed in the variable type.

If you specify group, EVALMAP formats the group data type and places it in the variable group. For example, if type is set to STRUCTURE(UCBDA) for an MVS™ dump, group is set to STRUCTURE(UCB).

DIMENSION(dimension) | MULTIPLE(dimension)

Requests that the dimension, or replication factor, for the map entry be formatted and placed in the variable dimension. Unless HEXADECIMAL is specified, the dimension is formatted in decimal; if HEXADECIMAL is specified, hexadecimal digits are used.

If the map entry is defined as a SCALAR, a zero dimension is supplied. The return code is set to 4 unless a more serious condition is also detected.

ENTRY(entry)

Requests that the subscript associated with the initial array entry described by the map entry be formatted and placed in the variable entry Unless HEXADECIMAL is specified, the subscript is formatted in decimal; if HEXADECIMAL is specified, hexadecimal digits are used.

If the map entry is defined as a SCALAR, a zero subscript is supplied. The return code is set to 4 unless a more serious condition is also detected.

FLAG(flag)

Requests that the most severe condition detected when the validity of the block was checked be placed in the variable flag:

INFORMATIONAL
WARNING
ERROR
SERIOUS

LENGTH(length)

Requests that the length associated with the map entry be formatted and placed in the variable length. Unless HEXADECIMAL is specified, the length is formatted in decimal; if HEXADECIMAL is specified, hexadecimal digits are used.

If the data described is an array, length is for one entry in the array. To calculate the length of the array, multiply the length by the dimension.

POSITION(position)

Requests that the signed offset associated with the map entry be formatted and placed in the variable position. The offset is the number of bytes skipped between the address of the data and the first physical byte described.

Unless DECIMAL is specified, the address is formatted in hexadecimal; if DECIMAL is specified, decimal digits are used.

QUALIFICATION(qualification)

Requests that the address qualifiers be formatted and placed in the variable qualification. The address qualifiers are for the address space described by the map entry.

Return Codes
See Standard subcommand return codes for a description of the return codes produced by the EVALMAP subcommand.
Example: The BLSCEMAP CLIST counts all the task control blocks (TCBs) in the storage map for the default data set and displays the sum. It uses the EVALMAP subcommand to retrieve the information as follows:
```
EVALMAP >= 0. ABSOLUTE STRUCTURE CLIST(QUALIFICATION(Q) +
    ADDRESS(A) DATATYPE(T))
```
See the BLSCEMAP member of SYS1.SBLSCLI0 for the complete listing.