Address, LENGTH, and POSITIONS parameters

If the address is a positional parameter, the syntax is as follows:

address[:address]  [LENGTH(length)] [POSITIONS(position[:position])]

If the address is a keyword parameter, the syntax is as follows:

 { ADDRESS(address[:address]) }
 { RANGE(address[:address])   }
 [ LENGTH(length) ]
 [ POSITIONS(position [:position ] ) ]

address [: address]

ADDRESS(address : address )

RANGE(address : address )

address expression

Specify the address as:

• A single address
• A range of addresses
• An address expression

A single address is a symbolic address, relative address, literal address, general-purpose register, floating-point register, or indirect address.

Example:

list +73

Result: LIST displays a relative address, X‘73’ bytes beyond X, the current address.

A range of addresses is any pair of addresses, address expressions, and registers (general-purpose and floating-point), separated with a colon. A range of addresses includes both end-points of the range. If you specify a range of addresses and LENGTH, the length of the range overrides the LENGTH value.

Example:

scan range(7819b.:8019b.) asid(6)

Result: SCAN processes only the storage map entries for ASID 6 that originate between X‘7819B’ and X‘8019B’ inclusive.

An address expression is an address followed by any number of expression values. An address expression has the format:

address[{%|?}...]±value[{%|?}...]&cont;
[±value[{%|?}...]]

address

A symbolic address, relative address, literal address, indirect address, or general-purpose register. You cannot use floating-point registers (and it is not advisable to use general-purpose registers) in an address expression. For any symbol that has a positive or negative origin point, be sure to use the +0 displacement for indirect addressing.

value

An address modifier that is either:

• A 1- to 19-digit decimal number followed by the letter N. The N may be in uppercase or lowercase.
• A 1- to 16-digit hexadecimal number that is not followed by a period. Underscores may be used between pairs of hexadecimal digits to improve legibility.

Value must be preceded by a plus (+) or a minus (-) sign and cannot be the first value in an address expression. You can use address modifiers with general-purpose registers but you cannot use address modifiers with floating-point registers.

Types of addresses

An address can be any one of the following types:

- Symbolic address

A symbolic address is a symbol consisting of at least one and no more than 31 characters. The first character must be a letter or the following characters:

$  (X'5B')
#  (X'7B')
@  (X'7C')

The same characters plus the decimal digits, 0 through 9, may be used for any of the remaining characters.

Note:

1. A symbolic address provides a complete description of a block of storage to IPCS:
   • Address, LENGTH, and POSITIONS parameters
   • Address processing parameters
   • An attribute parameter
   • Array parameters
   • A remark parameter
2. A symbolic address can be defined and used by the same IPCS subcommand if the following conditions are met:
   • The symbolic address conforms to IPCS naming conventions. See IPCS symbols for a list of the IPCS naming conventions supported. The diagnostic guides for other products that you have installed may supplement this list.
   • IPCS is able to associate the symbolic address with the type of AREA, MODULE, or STRUCTURE required by IPCS naming conventions. This will occur if, for example, you enter

     list ascb1

     or you enter

     list ascb1 structure(ascb)

     It will not occur if you enter

     list ascb1 structure

Example:

list x

Result: LIST displays X, the current address.

- Relative address

A relative address value can designate a maximum of 16 hexadecimal digits. Underscores (_) can be used as separators when the value is entered.

- Literal address

Before OS/390® Release 10, a literal address is a maximum of eight hexadecimal digits. If the initial digit is a letter A through F, the literal address must end with a period. Otherwise, the period can be omitted. The maximum address is ‘7FFFFFFF’.

The following list explains valid literal address ranges.

• If the address is absolute, real, or virtual, the address can range from 0 through 2⁶⁴-1.
• If the address is in the status record, the address can range from 0 through 4095.
• If the address is in the dump header record, the address can range from 0 through 4159.

Example:

where fe2b8.

Result: WHERE identifies the area in storage in which the address resides.

Underscores (_) can be used as separators when the value is entered. IPCS accepts literal addresses beginning with a decimal digit without regard to the presence of a trailing period.

- General-purpose register

A general-purpose register is designated as a decimal integer followed by an R. The decimal integer can range from 0 through 15.

With OS/390 Release 10 and higher, 64-bits of general-purpose registers are recorded as part of an unformatted dump. When dumps are produced on OS/390 Release 10 on processors lacking support for the z/Architecture® instruction set and 64-bit registers, the fullword values actually available are prefixed with 32 bits of binary zeros.

Example:

list 0r:15r terminal

Result: LIST displays the contents of all 16 general-purpose registers as they were at the time of the dump to the terminal.

- Floating-point register

A floating-point register is designated as a decimal integer followed by a D for double precision. The decimal integer can be 0 through 15.

Example:

list 0d:6d

Result: LIST displays the seven floating-point double precision registers in hexadecimal.

Note:

1. Single precision floating point register notation, a decimal integer followed by an E, is accepted but interpreted as a reference to the corresponding double precision floating point register.
2. Two or three decimal digit values ending in D or E are going to be interpreted as precise instances of floating point registers, so it is very important that you end an address with a period if you want it to be literal.

- Indirect address

An indirect address is a symbolic, relative, or literal address, or a general-purpose register followed by a maximum of 255 percent signs (%) or question marks (?). The address may include up to a maximum of 255 exclamation points (!) to indicate a 64-bit address value.

Each percent sign, question mark, or exclamation point indicates one level of indirect addressing. Indirect addressing is a method of addressing in which one area of dump data is used as the address of other dump data. The address preceding the percent sign, question mark, or exclamation point is used to locate a pointer in the dump as follows:

• If the address preceding the percent sign, question mark, or exclamation point is a symbolic address that describes a pointer, the contents of the pointer are retrieved from the dump.
• If the address preceding the percent sign, question mark, or exclamation point is not a symbolic address that describes a pointer, IPCS verifies that the addressed storage is acceptable for indirect addressing:
  • If the addressed storage begins on a fullword or doubleword boundary, IPCS accepts the fullword or doubleword pointer.
  • If not, IPCS checks the data type of the address storage. if the addressed storage has a data type of POINTER, IPCS accepts the pointer, even though it does not begin on a fullword or doubleword boundary.

Once IPCS accepts a pointer, it retrieves the contents of that pointer from the dump. The pointer is interpreted to form an address as follows:

• If the address is followed by a percent sign, the pointer is interpreted as a 24-bit address. If a fullword pointer was retrieved from the dump, nonzero bits in the first byte are set to zeros to form the address.
• If the address is followed by a question mark, the pointer is interpreted as a 31-bit address. If a fullword pointer was retrieved from the dump, the initial bit is set to zero to form the address.
• If the address is followed by an exclamation point, the pointer is interpreted as a 64-bit address.

It is not recommended that you use registers in indirect addresses. For compatibility with TSO/E TEST, general-purpose registers will be accepted in an address expression, but the resolution of the expression by IPCS will generally prove unsatisfactory. You cannot use floating-point registers in an address expression.

LENGTH(length)

The length of the area beginning at the specified address. The length can be specified in decimal (nnn), hexadecimal (X‘xxx’), or binary (B‘bbb’) notation.

The following list explains valid address length ranges.

• If the address is absolute, real, or virtual, the length can range from 1 through 2⁶⁴-1.
• If the address is in the status record, the length can range from 1 through 4096.
• If the address is in the dump header record, the length can range from 1 through 4160.

If you specify the LENGTH parameter and a range of addresses, the length of the range overrides the LENGTH value. If the length exceeds the upper limit for an addressing mode, the length is adjusted to include the last valid address for that addressing mode.

If you omit the LENGTH parameter, the subcommand uses the default length.

Note: When STRUCTURE(cbname) attribute parameter is specified, IPCS can supply a preferred length that overrides the default length. See Attribute parameters for more details.

Example:

equate abc a72f4. length(80) area

Result: EQUATE creates a symbol table entry for symbol ABC associating it with an 80-byte area beginning at X‘A72F4’.

POSITIONS(position[:position])

The offset of the initial and, optionally, the final byte of the area. The offsets can be specified in signed decimal ([+ | -]nnn or F‘[+ | -]nnn’), signed hexadecimal (X‘[+ | -]xxx’), signed binary (B‘[+ | -]bbb’).

Example 1:

list 400. position(30) length(10) structure

Result: LIST displays locations X‘41E’ (decimal 1054) through X‘427’. IPCS uses offset caption +0000001E for the line of storage displayed.

Example 2:

list asvt positions(512:519)

Result: LIST displays the cross section of the ASVT containing fields ASVTASVT and ASVTMAXU. The ending position is an alternate means to designate the length of the storage.

Example 3:

list +5 position(0) length(5)

Result: LIST performs the following steps:

1. The definition of the current symbol, X, is retrieved.
2. The POSITION(0) specification in conjunction with the explicit offset specification, +5, causes 5 to be added to the address of X before 0 is stored as a new offset.
3. The LENGTH(5) specification causes the updated definition of X to be stored with a length of 5 bytes.
4. The 5 bytes of storage are displayed.

This combination of explicit offset and the POSITION parameter can be used to move down (or up) within storage, in increments.