Evaluate command

The Evaluate command can be used to by a Formatting user exit to obtain storage from the analyzed fault environment.

Read syntax diagramSkip visual syntax diagram
Syntax

                                      .-------------------------------------------------.   
                                      V .-Bit-----------------------------------------. |   
>>-EVALuate--+---------------------+----+-ADDRESS--(--+-address-------------+--)------+-+-><
             +-address-------------+    |             '-address--:--address-'         |     
             '-address--:--address-'    +-LENGTH--(--length--)------------------------+     
                                        +-POSITIONs--(--+-position--------------+--)--+     
                                        |               '-position--:--position-'     |     
                                        +-+-POINTER-+---------------------------------+     
                                        | '-PTR-----'                                 |     
                                        +-Character-----------------------------------+     
                                        +-+-SIGNED-+----------------------------------+     
                                        | '-F------'                                  |     
                                        +-UNSIGNED------------------------------------+     
                                        |          .-----------------------------.    |     
                                        |          V                             |    |     
                                        '-REXX--(----+-STORAGE--(--var_name--)-+-+--)-'     
                                                     +-FORMATTED---------------+            
                                                     +-UNFORMATTED-------------+            
                                                     +-ENQUOTE-----------------+            
                                                     +-+-UNQUOTE--+------------+            
                                                     | '-NOQUOTES-'            |            
                                                     '-NOBLANKS----------------'            

Parameters

address
start:end
Specifies either the start address, or an address range, as a positional parameter. This address is an alternative to using the ADDRESS keyword. See ADDRESS below for details about valid syntax.
ADDRESS(address)
ADDRESS(address:address)
Specifies the address of the storage to be returned. Specify as either a single address or as an address range.

The address parameter is 64-bit enabled. For details, see Specifying 64-bit addresses. The address may optionally followed by a period (for example, "000176C0.").

LENGTH(length)
Specifies the number of bytes to be returned. Specify as a hexadecimal value (indicated by X'…') or as a decimal value (no indication required). If an address range is specified, then specification of LENGTH is ignored.
POSITIONs(position)
POSITIONs(position:position)
Specifies the offset from the start address to the first byte of storage to be returned. Specify as either a single offset or as an offset range. Both POSITION and POSITIONS are accepted.

All offsets must be either hexadecimal (indicated by X'…') or signed decimal (optionally indicated by F'…').

Bit
Specifies that data is to be returned in hexadecimal format.

This parameter is only valid if FORMATTED is in effect.

POINTER
PTR
Specifies that data is to be returned in hexadecimal format.

The valid LENGTH is 1 - 4 bytes. If LENGTH is greater than 4, then it is changed to 4.

This parameter is only valid if FORMATTED is in effect.

Character
Specifies that data is to be returned in character string format with non-printable characters replaced by periods. Further editing is determined by the specification of ENQUOTE, UNQUOTE, NOQUOTES, or NOBLANKS parameters.

This parameter is only valid if FORMATTED is in effect.

SIGNED
F
Specifies that data is to be returned in signed decimal format. Leading zeroes are removed and a minus sign is supplied for negative integers.

The valid LENGTH is either 2 or 4 bytes. If LENGTH is 1 or 3, then it is changed to 2. If LENGTH is greater than 4, then it is changed to 4.

This parameter is only valid if FORMATTED is in effect.

UNSIGNED
Specifies that data is to be returned in unsigned decimal format. Leading zeroes are removed.

The valid LENGTH is 1 - 4 bytes. If LENGTH is greater than 4, then it is changed to 4.

This parameter is only valid if FORMATTED is in effect.

REXX(…)
Specifies that the storage is to be returned in a REXX variable. This parameter is required.
STORAGE(var_name)
Specifies the name of the REXX variable which is to receive the storage. This parameter is required.
FORMATTED
Specifies that storage is to be returned formatted. This value is the default.
UNFORMATTED
Specifies that storage is to be returned in raw hex format (one byte returned for each byte of storage).
ENQUOTE
Specifies that one leading and one trailing quote are to be added to the returned character string, and that any apostrophes found in the string are to be paired.

This parameter is only valid if character data is being returned.

UNQUOTE
NOQUOTES
Specifies that all apostrophes (X'7D') in the returned character string are to be replaced by periods.

This parameter is only valid if character data is being returned.

NOBLANKS
Specifies that all blanks in the returned character string are to be replaced by periods.

This parameter is only valid if character data is being returned.

If a parameter is specified multiple times, then only the last specification takes effect.

Return codes

The Evaluate command provides the following return codes:
0
Storage was obtained successfully.
4
The requested data length was modified. An explanation is written to the HFZTRACE DDname.
12
Command syntax error or storage not available. An explanation of the error is written to the HFZTRACE DDname.

Example

Figure 1. Evaluate command example
/* REXX */

"EVALUATE 0 LENGTH(128) REXX(STORAGE(x))"
if RC = 0 then say 'Storage at address 0 =' x