EVALSYM subcommand — format the definition of a symbol

Use the EVALSYM subcommand to retrieve information associated with a symbol and format that information in CLIST variables, REXX variables, or ISPF function pool dialog variables.

The symbol is in a symbol table that is part of a source description. 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 can 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.

• Related subcommands
  • EQUATE
  • EVALDEF
  • EVALDUMP
  • EVALMAP
  • EVALUATE

  Guideline: EVALUATE does not handle log streams nor does it deal with dumps or traces in added status within the dump directory. The ability to format the value of a literal symbol was added to EVALSYM to enable command procedures to access such values in these circumstances.

• Syntax

    EVALSYM    [ relational-operator ]
  
                 symbol
               [ CLIST(var-list)  ]
               [ DIALOG(var-list) ]
               [ REXX(var-list)   ]
               [ INDATASET(dsname) | INFILE(ddname) ]

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

               [ ACTIVE | MAIN | STORAGE          ]
               [ DSNAME(dsname) | DATASET(dsname) ]
               [ FILE(ddname) | DDNAME(ddname)    ]
               [ PATH(path-name)     ]
               [ TEST | NOTEST ]

• Parameters

  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.

  symbol

  Specifies a symbol to be used with a relational operator. The definition of the symbol is to be retrieved.

  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.

  INDATASET(dsname)

  INDSNAME(dsname)

  Requests allocation of directory dsname and use of the contents of that directory by the subcommand.

  INFILE(ddname)

  INDDNAME(ddname)

  Requests use of a directory that the IPCS user has allocated to ddname and use of the contents of that directory by the subcommand.

  The syntax for var-list is as follows:

       [ DECIMAL | F     ]
       [ HEXADECIMAL | X ]
       [ ADDRESS(address) ]
       [ DATATYPE(type[,group]) ]
       [ DIMENSION(dimension)|MULTIPLE(dimension) ]
       [ DROP(drop) ]
       [ ENQUOTE|UNQUOTE|NOQUOTES ]
       [ ENTRY(entry) ]
       [ FLAG(flag) ]
       [ LENGTH(length) ]
       [ NOBLANKS ]
       [ POSITION(position) ]
       [ QUALIFICATION(qualification) ]
       [ REMARK(remark) ]
       [ SYMBOL(symbol) ]
       [ VALUE(value) ]

  DECIMAL or F

  HEXADECIMAL or X

  Specifies the format of the numeric information:

  • DECIMAL or F for decimal
  • HEXADECIMAL or X for hexadecimal

  ADDRESS(address)

  Places in the variable address the address associated with the symbol. Unless DECIMAL is specified, the address is formatted in hexadecimal; if DECIMAL is specified, decimal is used.

  DATATYPE(type)

  Places in the variable type the data type for the symbol. The preferred representations for the data type are:

  • BIT (rather than HEXADECIMAL or X)
  • CHARACTER (rather than C)
  • SIGNED (rather than F)
  • POINTER (rather than PTR)

  DIMENSION(dimension) or MULTIPLE(dimension)

  Places in the variable dimension the dimension, or replication factor, associated with the symbol. Unless HEXADECIMAL is specified, the dimension is in decimal; if HEXADECIMAL is specified, hexadecimal is used.

  If the symbol 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.

  DROP(drop)

  Places in the variable drop the value DROP or NODROP.

  ENQUOTE | UNQUOTE | NOQUOTES

  Specifies how REMARK text is to be formatted:

  • ENQUOTE requests a quoted string.
  • UNQUOTE and NOQUOTES request that apostrophes (X'7D') translated to periods.

  ENTRY(entry)

  Places in the variable entry the subscript associated with the initial array entry described by the symbol. Unless HEXADECIMAL is specified, the subscript is in decimal; if HEXADECIMAL is specified, hexadecimal is used.

  If the symbol 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)

  Places in the variable flag the most severe condition detected when the validity of the block was checked:

  • INFORMATIONAL
  • WARNING
  • ERROR
  • SERIOUS

  LENGTH(length)

  Places in the variable length the length associated with the symbol. Unless HEXADECIMAL is specified, the length is decimal; if HEXADECIMAL is specified, hexadecimal is used.

  If the data described is an array, the length describes one entry in the array. The length of the array may be computed by multiplying the length of one entry by the dimension.

  NOBLANKS

  Requests that blanks (X'40') in REMARK text be translated to periods.

  POSITION(position)

  Places in the variable position the signed offset associated with the symbol. 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 in hexadecimal; if DECIMAL is specified, decimal is used.

  QUALIFICATION(qualification)

  Places in the variable qualification the address qualifiers for the address space described by the symbol.

  REMARK(remark)

  Places in the variable remark the remark associated with the symbol. The remark text is edited for use in CLISTs, REXX execs, or ISPF dialogs:

  • EBCDIC lower case alphabetic characters (a-z) are always replaced by uppercase characters (A-Z), and EBCDIC superscript decimal digits (X'B0'-X'B9') are always replaced by common decimal digits (X'F0'-X'F9').
  • Characters not present on either the IBM® 1403 TN print chain or the IBM 3211 T11 print train are always replaced by periods.
  • Ampersands are always replaced by periods.
  • Blanks are replaced by periods if the NOBLANKS option is selected. Otherwise, blanks are not edited.
  • Apostrophes (X'7D') are left alone if you do not specify ENQUOTE, UNQUOTE, or NOQUOTES. The string placed in the variable is the same length as that of the string in the dump. However, the following parameters affect this option:

    ENQUOTE

    One leading apostrophe and one trailing apostrophe are supplied. Apostrophes found in dump data are paired.

    UNQUOTE|NOQUOTES

    Apostrophes found in dump data are replaced by periods. The string placed in the variable is the same length as that of the string in the dump.

  SYMBOL(symbol)

  Places in the variable symbol the name of the symbol retrieved.

  VALUE(value)

  Places in the literal value the value associated with a literal symbol. The following formatting is performed:

  1. If the symbol is not associated with a literal value, a single blank is stored.
  2. Unless HEXADECIMAL is specified, SIGNED and UNSIGNED data are formatted using decimal digits. If HEXADECIMAL is specified, hexadecimal digits are used.
  3. Unless DECIMAL is specified, POINTER data is formatted using hexadecimal digits. If DECIMAL is specified, decimal digits are used.
  4. CHARACTER data is formatted subject to the same criteria used for REMARK text.
  5. All other types of data are formatted using hexadecimal digits.

• SETDEF-Defined Parameters

  ACTIVE or MAIN or STORAGE

  DSNAME(dsname) or DATASET(dsname)

  FILE(ddname) or DDNAME(ddname)

  Specifies the source of the source description that contains the symbol. If one of these parameters is not specified, IPCS uses your current source.

• Return Codes

  See Standard subcommand return codes for a description of the return codes produced by the EVALSYM subcommand.

• Example: The BLSCESYM CLIST counts all the symbols representing task control blocks (TCBs) in the symbol table for the default data set and displays the sum. It uses the following EVALSYM subcommand to retrieve the information:

  EVALSYM >= $ CLIST(SYMBOL(SYM) DATATYPE(T))

  See the BLSCESYM member of SYS1.SBLSCLI0 for the complete listing.