Address processing parameters

Address processing parameters are optional. They describe an address space within which the data to be processed resides.

Note: Address processing parameters DSNAME, FILE, BLOCK, and RBA are the only address processing parameters you can use when referencing VSAM data sets.
  [ ABSOLUTE                              ]
  [ ASID(asid) [CPU(cpu)|NOCPU] [SUMDUMP] ]
  [ ASID(asid) DSPNAME(dspname) [SUMDUMP] ]
  [ BLOCK(block-number)                   ]
  [ COMPDATA(component-id)                ]
  [ DOMAIN(domain-id) [CPU(cpu)]          ]
  [ HEADER                                ]
  [ RBA [(0|rba-group)]                   ]
  [ REAL   [CPU(cpu)]                     ]
  [ STATUS [CPU(cpu)]                     ]
  [ TTR(ttr)                              ]
  [ ACTIVE | MAIN | STORAGE               ]
  [ DSNAME(dsname) | DATASET(dsname)      ]
  [ FILE(ddname) | DDNAME(ddname)         ]
  [ PATH(hfspath)                         ]
ABSOLUTE
The storage at the address or address range is in absolute storage in a system dump or ACTIVE storage (that is, the LPAR in which IPCS is running).

Access to the absolute storage in ACTIVE requires READ authority to FACILITY class resource BLSACTV.SYSTEM. Without such authority, all ABSOLUTE storage are treated as inaccessible.

ASID(asid)
The storage at the address or address range is in an address space or a data space. IPCS accesses the storage differently, depending on the type of information source:
  • For dumps, IPCS accesses address spaces using a valid ASID.
  • For ACTIVE storage, IPCS accesses storage from the system where it is executing on demand as an enabled application. Access to sensitive storage is restricted by proper authority to FACILITY class resources BLSACTV.ADDRSPAC or BLSACTV.SYSTEM. See supported keywords for more discussions about the FACILITY class authority.
  • For stand-alone dumps, IPCS simulates dynamic address translation or central storage prefixing, depending on the parameter you specify. (See the descriptions for the CPU and NOCPU parameters.)

The ASID can range from 1 through 65,535. You can specify the ASID in decimal, hexadecimal (X'xxx'...), or binary (B'bbb'...).

Example: 
equate abc a72f4. asid(1) length(80) area

Result: EQUATE creates a symbol table entry for symbol ABC, associating it with an 80-byte area beginning at X‘A72F4’. ASID(1) indicates that this address is in virtual storage and IPCS simulates dynamic address translation.

BLOCK(block-number)
The storage at the address or address range is in physical block number “block-number” as follows: 
BLOCK(0) is the first physical block.
BLOCK(1) is the second physical block.
BLOCK(2) is the third physical block.
BLOCK(3) is the fourth physical block.
⋮

The block number can range from 0 through 224-1. You can specify the block number in decimal, hexadecimal (X'xxx...'), or binary (B‘bbb...’).

For VSAM data sets, BLOCK(0) is the first control interval, BLOCK(1) is the second, and so on.

COMPDATA(component-id)
The storage supplied as part of a dump to facilitate analysis of a specific component. Use the LISTDUMP subcommand to find the COMPDATA records available in a dump. For example, the stand-alone dump program can produce the following COMPDATA records:
AMDSAMSG
Requests display of messages displayed at the operator's console during the dumping process.
AMDSA001 - AMDSA005
Request display of self-dump information from stand-alone dump when it detects errors in its own processing.
AMDSA009
Request display of internal control blocks used by stand-alone dump during its processing.
See z/OS MVS Diagnosis: Tools and Service Aidsfor more information about stand-alone dump COMPDATA records.

Records written by a stand-alone dump use component-ids that begin with the same prefix characters as that component's module names (“AMDSA”). This is true for all IBM-supplied components.

CPU(cpu)
The storage within the CPU address that provides the context for the ASID, DOMAIN, REAL, or STATUS parameter. The CPU parameter applies only to stand-alone dumps.
  • For the ASID and REAL parameters, this is the processor whose prefix register is used when IPCS simulates prefixing.
  • For the STATUS parameter, this is the processor whose registers were saved by a store-status operation during the dumping of the operating system.
The CPU address can range from 0 to 63 and may be specified in decimal, hexadecimal (X‘xxx...’), or binary (B‘bbb...’). If you specify this parameter and omit ASID, REAL, and STATUS, the subcommand uses the default ASID. See supported keywords for more details.
DOMAIN(identifier)
The dump storage that supplements the storage pages that record system status. The valid domain-ids are:
DOMAIN(VECTOR)
The vector registers recorded by stand-alone dump. Stand-alone dumps might contain vector registers that are for each processor in the configuration. If you do not use the CPU parameter to specify the address of the CPU containing vector records you want, IPCS uses a default CPU address.
DOMAIN(SDUMPBUFFER)
The diagnostic data in the SDUMP buffer. The requester of a system-initiated dump puts the data in the SDUMP buffer.
DOMAIN(SUMDUMP)
The highly volatile diagnostic data that is useful for problem determination.
DSPNAME(dspname)
The data space dspname that is associated with the specified ASID. If the dump is not a stand-alone dump, and the DSPNAME and SUMDUMP parameters are specified or are the default, IPCS accesses only that data space information which was collected in DOMAIN(SUMDUMP) records.
As of z/OS® V1R9, IPCS users can access data spaces via ACTIVE storage:
  • Without special authority, the data spaces that are visible to an authorized application can be accessed.
  • Authority to the FACILITY class resources BLSACTV.ADDRSPAC and BLSACTV.SYSTEM can provide access to the data spaces that are not directly accessible by an authorized application.
HEADER
The storage at the address or address range is in the header record for a system dump or ACTIVE storage. When you use this parameter, the subcommand accesses data in the header record from offset 0. That is, the subcommand processes data in the header record at the address you specify.
NOCPU
The storage at the address or address range is in virtual storage in a system stand-alone dump. IPCS is to simulate dynamic address translation and use the results to directly access absolute storage without the use of prefix registers. If you specify the NOCPU parameter and omit ASID, the subcommand uses the default ASID.
RBA[(0|rba-group)]
The storage at the address or address range is in relative byte address group number “rba-group.” Each relative byte address group consists of up to 231 bytes from a data set as follows:
  • RBA(0) contains the first 231 bytes.
  • RBA(1) contains the second 231 bytes.
  • RBA(2) contains the third 231 bytes.
  • RBA(3) contains the fourth 231 bytes. ⋮
Note: IPCS interprets RBA(0) (or just RBA) as the first 264 bytes of a data set.

The group number can range from 0 through 224-1 If the group number is omitted, it defaults to 0. You can specify the group number in decimal, hexadecimal (X‘xxx...’), or binary (B‘bbb...’).

For VSAM data sets, IPCS masks the boundaries between control intervals, allowing them to be referenced as part of a single address space.

REAL
The storage at the address or address range is in central storage in a system stand-alone dump. IPCS is to simulate prefixing for the specified or current default CPU. If you specify the REAL parameter and omit the CPU parameter, the subcommand uses the default CPU.
STATUS
The storage at the address or address range is in one of the CPU status records in a system stand-alone dump. Stand-alone dumps contain a CPU status record for each CPU that was active on the system at the time of the dump. The CPU status record for a particular CPU contains an image of a 4096-byte prefixed save area (PSA) just after a STORE STATUS operation was performed from the CPU to the PSA. The status information stored by the STORE STATUS operation includes the current PSW and the general registers. IPCS supports access to each CPU's status as a 4096-byte CPU status address space.

When you use STATUS, the parameter accesses data in the status records from offset eight. That is, the parameter processes data in the status record eight bytes beyond the address you specify. See the AMDDATA mapping macro for more information.

If you specify this parameter and omit CPU, the subcommand uses the default CPU.

Example: 
list 100 status cpu(0) length(8)

Result: LIST displays the PSW that is placed in the store status record at X‘100’ of a stand-alone dump.

SUMDUMP
The dump storage containing the DOMAIN(SUMDUMP) records, provided that the dump is not a stand-alone dump. For dumps other than stand-alone dumps, the SUMDUMP parameter can be specified or may be the default.
Note: The SUMDUMP parameter does not apply to stand-alone dumps.
TTR(ttr)
The storage at the address or address range is in the physical block that has the relative track and record address of “ttr”. The value of ttr can range from 0 through 224-1. You can specify the ttr in decimal, hexadecimal (X‘xxx...’), or binary (B‘bbb...’).
ACTIVE or MAIN or STORAGE
DSNAME(dsname) or DATASET(dsname)
FILE(ddname) or DDNAME(ddname)
Specifies the source that contains the address space or address range. If one of these parameters is not specified, IPCS uses your current source.
Note: Do not use these parameters for:
  • Volatile common or private storage
  • Prefixed storage

ACTIVE or MAIN or STORAGE specifies that the address or address range is in the central storage in which IPCS is currently running.

A header record similar to those used for system dumps is supplied by IPCS to enable common dump analysis programs to function.

Storage is accessed incrementally on demand, and IPCS generally remains enabled. As a result, ACTIVE storage might be subject to frequent changes, which can prevent the analysis programs from producing useful results.

ABSOLUTE, ASID, DSPNAME, and HEADER keywords are supported. Access to sensitive storage areas, such as ABSOLUTE, is limited using facility classes. When the user does not have the authority, the access attempts are handled as though the storage in question was not included in a dump.

With no special authority, IPCS can access the following storage:
  • The common and private storage in its own ASID visible to a key 8 application
  • The data spaces owned by its own ASID and visible to a key 8 application
Before z/OS V1R9, no data space access was supported.
With read authority to facility class BLSACTV.ADDRSPAC, IPCS can look at the following storage (in addition to those storage areas it can access with no special authority) :
  • The common and private storage visible to a key 0 application
  • All data spaces owned by its own ASID
Before z/OS V1R9, no data space access was supported.
With read authority to facility class BLSACTV.SYSTEM, IPCS can look at the following storage (in addition to those storage areas it can access with no special authority) :
  • The ABSOLUTE storage
  • Other ASIDs
  • The data spaces owned by other ASIDs
BLSACTV.SYSTEM support was added in z/OS V1R9.
Note: IPCS artificially attributes CADS ownerships to ASID(1) as it also does for the page frame table space, ASID(1) DSPNAME(IARPFT). Consistent with this perspective BLSACTV.SYSTEM authority is required to access these data spaces.

DSNAME or DATASET specifies that the address or address range is in the cataloged data set dsname.

For VSAM data sets, you can:
  • Access the data portion of the cluster by:
    • Specifying the cluster data set name for dsname
    • Specifying the optional data portion data set name for dsname
    • Specifying dsname in pseudo-PDS notation, providing a member name of “data”, as in 
      DSNAME(vsam.cluster.dsname(data))
  • Access the index portion of the cluster by:
    • Specifying the optional index portion data set name for dsname
    • Specifying dsname in pseudo-PDS notation, providing a member name of “index”, as in 
      DSNAME(vsam.cluster.dsname(index))

FILE or DDNAME specifies that the address or address range is in the data set ddname.

z/OS UNIX files can be referenced with this notation.
  • Those z/OS UNIX files whose size is a multiple of 4160 bytes will be treated as z/OS unformatted dumps.
  • No trace formatting support is provided for GTF or component traces that have been copied into z/OS UNIX files.
  • RBA access is supported for any z/OS UNIX file.

For VSAM data sets, allocate the data or index portions of the VSAM cluster to use the FILE parameter in pseudo-PDS notation. For example, specify FILE(vsam.cluster.dsname(data)) or FILE(vsam.cluster.dsname(index)). Specifying the name of the required portion with the DSNAME parameter instead avoids allocating the portions.

PATH(hfspath)
Specifies a valid path name.
  • You can reference path names directly. There is no need to associate a path with a ddname before asking IPCS to process a z/OS UNIX file path.
  • Fully qualified path names are limited to 44 characters. Enclosing apostrophes or quotation marks are not counted toward the limit.
  • You can use partially-qualified path names. IPCS will determine the fully-qualified names.
You can enter PATH as follows:
PATH(‘/pathname’)
PATH(“/pathname used in IPCS dialog”)
You can always enter path names within apostrophes. Quotation marks can be used as an alternative to apostrophes when supplying a source name to the defaults or browse options of the IPCS dialog. The rules for entering a path name within quotation marks are standard:
  • If the path name contains an apostrophe and you used that punctuation to delimit the name, two adjacent apostrophes need to be entered.
  • If the path name contains a quotation mark and you used that punctuation to delimit the name, two adjacent quotation marks need to be entered.

Always use quoted string notation when your path name contains blanks, commas, horizontal tabulation characters (EBCDIC X'05'), apostrophes (single quotation marks), or quotation marks.

PATH(/x/y/z)
Quoted string notation is not always required. You can enter most path names without enclosing them with punctuations.
PATH(partially-qualified-name)
IPCS accepts existing z/OS UNIX file paths that can be qualified when they are entered, as if the fully-qualified name had been entered.
Note: Path names are case-sensitive. Path names “/ABC”, “Abc”, and “abc” refer to three different paths.
Parent topic: Data description parameter