WHERE subcommand — identify an area at a given address

Use the WHERE subcommand to identify the area in a dump in which an address resides. IPCS provides a report containing:

The address space text
The specified address
The name of the area in the dump at the specified address. The name can be:
- The name of a load module. For nucleus CSECTs, the load module name is IEANUC0x, where x is obtained from field CVTNUCLS. Externally defined CSECTs within the nucleus are identified following the load module name. Externally defined CSECTs in other load modules are not displayed.
  To be displayed, the module name must conform to the following naming conventions:
  - The name is 1 through 8 characters.
  - The first character is an uppercase EBCDIC letter or one of the following national characters:
```
$  (X'5B')
#  (X'7B')
@  (X'7C')
```
  - The remaining characters are uppercase EBCDIC letters, national characters, or EBCDIC decimal digits.
  If a module name does not conform to these conventions, IPCS displays:
```
MODULE(SPECIALNAME)
```
- The name of a control block. The parameter STRUCTURE is displayed followed by the control block name.
- The name of an area of storage that is not a module or a control block. IPCS displays AREA followed by the name of the area.
The offset into the identified area.
The name of the system area containing the specified address, which can be:
- Common service area (CSA)
- Fixed link pack area (FLPA)
- Modified link pack area (MLPA)
- Pageable link pack area (PLPA)
- Private
- Prefixed save areas (PSA)
- Read only nucleus
- Read/write nucleus
- System queue area (SQA)

If after examining the return code, IPCS cannot identify the area pointed to by the specified address, IPCS issues the following message:

BLS18451I Unable to identify the area at 'addr space' address xxxxxxxx

If IPCS issues this message, enter one or more of the dump analysis subcommands, such as SUMMARY and STATUS, then reenter the WHERE subcommand. Based the dump processing for the analysis subcommands, IPCS may now be able to identify the area.

The detail in the report generated by the WHERE subcommand depends to a large extent on previous processing of the dump. For example, if after initializing a dump, you enter WHERE, IPCS generates a minimal report. But if you reenter WHERE after entering a number of subcommands, IPCS will probably produce a more detailed report.

Note: The WHERE subcommand may modify X, the current address, as follows:

If WHERE can associate the location identified by data-descr with a block of storage containing that location, X is set to describe the block of storage containing the location.
If WHERE cannot associate the location identified by data-descr with a block of storage containing that location, X is set to describe the location identified by data-descr.

WHERE will not change X if error conditions occur, such as syntax errors or an unresolvable data-descr.

When used as a primary command, WHERE stacks a pointer to the address, but does not change the value of X. Use option 1 (BROWSE) of the IPCS dialog to find the pointer.

You can invoke WHERE as an IPCS subcommand or as an IPCS primary command. (This section refers to both the subcommand and the primary command as the “WHERE command.”) The WHERE command is useful for identifying locations of addresses found in other reports produced by IPCS subcommands.

For specified addresses in each of the system areas, the WHERE command names different areas in the dump, some more helpful than others.

Addresses in the LPA and Nucleus
The WHERE command has the greatest benefit when used on addresses in the following system areas:
- Fixed link pack area (FLPA)
- Modified link pack area (MLPA)
- Pageable link pack area (PLPA)
- Read-only nucleus
- Read-write nucleus.
For addresses in these areas, the WHERE command returns the name of a load module.

The WHERE command provides the most specific information for addresses located in the nucleus. The WHERE command provides the name of the externally defined CSECTs within the nucleus in which the address is located. They are identified following the load module name. For nucleus CSECTs, the load module name is IEANUCOx, where x is obtained from field CVTNUCLS. Externally defined CSECTs in other load modules are not displayed.
When you invoke WHERE for an address in any of the parts of the LPA, it returns the name of a load module that contains a number of CSECTs. To find the exact CSECT you are looking for, you must do one of the following:
- If the address is in the section of dump that fits into memory, you can enter the WHERE subcommand from the Browse option of the IPCS dialog. When you press F3 to exit the WHERE output, the Browse panel will scroll to the location of that CSECT in the dump.
- If the address is not in the section of dump in memory, you can use the AMBLIST service aid to format and print the load module. The AMBLIST service aid gives you a list of the component CSECTs in the load module. See z/OS MVS Diagnosis: Tools and Service Aids for more information about using AMBLIST.
Addresses in private storage
The WHERE primary command can also be used on addresses in private and extended private area storage.
- Private area analysis may identify load modules and offsets within them.
- It may also associate the address of interest with data areas.
- z/OS® R2 IPCS adds the ability to associate addresses with pages containing application subpools, AREA(SUBPOOLspKEY(key), where
  sp
  
  A three-digit decimal subpool number between 0 and 255.
  
  key
  
  A two-digit decimal storage key between 0 and 15.
  
  The IPCS storage map entries describe subpools in increments of 4096-byte pages associated with subpools rather than the 8-byte units of allocated storage within them.
Addresses in other areas of storage
The WHERE primary command can also be used on addresses in other areas of storage:
- Common storage area (CSA)
- Prefixed save area (PSA)
- System queue area (SQA).
For addresses in these areas, the information provided is less specific than the information provided for the LPA and nucleus addresses. When issued on an address in these areas, WHERE returns one of the following:
- The name of a control block. The parameter STRUCTURE is displayed followed by the control block name.
- The name of an area of storage (not a module or control block). The parameter AREA is typically displayed followed by the name of the area.
- The names of the load modules that are loaded by LOAD with GLOBAL=YES option from the current ASID, if the address is in the CSA or ECSA storage.
When WHERE Does Not Work
If after examining the return code IPCS determines that the area pointed to by the specified address cannot be identified, IPCS issued message BLS18451I with the address and ASID:
```
BLS18451I Unable to identify the area at ASID(X'0032') address 005CD478
```
This situation sometimes occurs when the dump directory does not contain enough information about the area of the dump. Try entering the SUMMARY or STATUS subcommand. These subcommands should fill missing information in the dump directory. Then reenter the WHERE subcommand:
```
ASID(X'0032') 005CD478. AREA(CURRENT)+5CC478 IN PRIVATE
```
The detail of the report generated by the WHERE command depends to a large extent on how much you have processed the dump. For example, if after initializing a dump, you enter WHERE, IPCS generates a minimal report. But if you enter WHERE again later in your IPCS session, after entering a number of subcommands, a more detailed report will probably be produced.

Syntax

    { WHERE }   data-descr
    { W     }
               [SELECT([AREA][MODULE][STRUCTURE])]

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

               [ FLAG(severity) ]
               [ PRINT | NOPRINT ]
               [ TERMINAL | NOTERMINAL ]
               [ TEST | NOTEST ]

Parameters
data-descr
Specifies an address in a dump through the data description parameter, which consists of five parts:
- An address (required)
- Address processing parameters (see note below)
- 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:
An ASID may optionally be specified as part of the data description parameter. If the specified address is in private storage, and no ASID is specified, the default ASID is the only ASID searched.

ACTIVE, MAIN, and STORAGE cannot be specified.
SELECT([AREA][MODULE][STRUCTURE])

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

Allows WHERE to associate the location of interest with AREAs.

MODULE

Allows WHERE to associate the location of interest with MODULEs.

STRUCTURE

Allows WHERE to associate the location of interest with STRUCTUREs.

When no selection is specified or all selections are chosen, WHERE can associate the location of interest with AREAs, MODULEs, or STRUCTUREs.
Return Codes
See Standard subcommand return codes for a description of the return codes produced by the WHERE subcommand.
Example 1: Determine where an absolute address is located.
- Action
```
COMMAND ===> IPCS WHERE FD2834.
```
- Result
  WHERE generates the following output line, showing that the specified address, in address space X'0058' is X'20D14' bytes into CSECT IOSUCB, which is located in load module IEANUC01 in the READ/WRITE NUCLEUS.
```
IPCS OUTPUT STREAM -------------------------------------- LINE 0 COLS 1 78
COMMAND ===> _                                             SCROLL ===> CSR
 ****************************** TOP OF DATA ***********************************
      ASID(X'0058') 00FD2834. IEANUC01.IOSUCB+020D14 IN READ/WRITE NUCLEUS
 ****************************** END OF DATA ***********************************
```
  If the address you specified is in the portion of the dump in memory, the WHERE subcommand also takes you to that address in the dump when you press F3 to exit this screen.
  
  If the primary command are used in this example, the item that contains the address are added to the pointer stack. If more than one item contains the address, the item with the smallest offset are added to the pointer stack.

Example 2: Use WHERE from system trace table output, which provides a history of the most recent events in the system. The WHERE command can save you from having to leave the system trace table to find the information needed. For example, if you are going through the table and you see a PSW that interests you, you can use the WHERE command to find out to what module the PSW points. Instead of having to use the VERBEXIT NUCMAP, LPAMAP, or go into the Browse panel of the IPCS dialog, you can type WHERE directly from the system trace table and find out the module name. Also, if you enter WHERE as a primary command it will put a pointer to the module on the stack.

Choose option 4 from the IPCS Primary Option Menu. Then, enter the system trace table with:

===> SYSTRACE

Now, enter WHERE on the command line of the system trace table.

IPCS OUTPUT STREAM ---------------------------------------- LINE 471 COLS 1 78
COMMAND ===> WHERE 1D073D0                         SCROLL ===> CSR
 01 001B 009F8E88   SVCR   78 070C2000 81D07386  00000000 00000080 7FFFDD10
 01 001B 009F8E88   SVC    78 070C3000 81D073B2  0000E101 00000030 7FFFDD10
 01 001B 009F8E88   SVCR   78 070C3000 81D073B2  00000000 00000030 7FFFDD10
 01 001B 009F8E88   SVC    78 070C1000 81D073D0  0000E101 00000010 7FFFDD80
 01 001B 009F8E88   SVCR   78 070C1000 81D073D0  00000000 00000010 7FFFDD80
 01 001B 009F8E88   SVCR   2A 070C1000 8001B832  00000000 00000000 009F8CF0
 01 001B 009F8E88   SVC    78 070C2000 8001B93E  00000003 00000190 00006C60
 01 001B 009F8E88   SVCR   78 070C2000 8001B93E  00000000 00000190 00006C60
 01 001B 009F8E88   SVC    78 070C0000 80008B50  00000002 00000368 00000000
 01 001B 009F8E88   SVCR   78 070C0000 80008B50  00000000 00000368 00006A88
 01 001B 009F8E88   SVC    38 070C1000 80008C4E  00000000 00000006 00006C78
 01 001B 009F8E88   PC    ...   0      811520D2  00108
 01 001B 009F8E88   PT    ...   0      811520D2  001B
 01 001B 009F8E88   SVCR   38 070C1000 80008C4E  00000000 00000002 00F3FB14
 01 001B 009F8E88   SVC    78 070C0000 80019294  00000002 00000358 00000000
 01 001B 009F8E88   SVCR   78 070C0000 80019294  00000000 00000358 00006730
 01 001B 009F8E88  ?EXPL 0003                    77007B16 C3629700 00000003
 01 000E 009F6E88   SRB       070C0000 811A3180  0000000E 00F42200 00F4222C
                                                 80
 01 000E 00000000   SSRV    2          80FFB540  000A002C 7F000000 00000000
                                                 00000000
 01 000E 00000000   SSRV  12A          80007478  00B9E8B0 40000000 00000000
                                                 00000000
 01 000E 009F6E88   DSP       070C0000 800073C2  00000000 000070C0 00B9E8B0  00
 01 000E 009F6E88   SSRV    1          80007388  00B9E8B0 00000001 00000000
                                                 00000000
 01 001B 009F8E88   DSP       070C0000 800192C8  00000000 00000002 00006B48  00
 01 001B 009F8E88   SVC    78 070C2000 8001936C  0000E572 00001000 00000000
 01 001B 009F8E88   SVCR   78 070C2000 8001936C  00000000 00001000 7FFE0000
 01 001B 009F8E88   SVC    78 070C2000 800199B8  0000EF72 00000018 00000000
 01 001B 009F8E88   SVCR   78 070C2000 800199B8  00000000 00000018 01B1E640
 01 001B 009F8E88   SVC    F0 070C2000 80014912  80014910 00000000 0000677C
 01 001B 009F8E88  *SVC     D 070C1000 80FE5CFC  80014910 80000000 80FF0000
 01 001B 009F8E88   PC    ...   0      811808CE  00506
 01 001B 009F8E88   PC    ...   0      82106B2A  00503
 ****************************** END OF DATA ***********************************

Result

WHERE generates the following dump display reporter panel. It tells you that the address is 03D0 hexadecimal bytes into load module IGC0004B in the extended PLPA.

IPCS OUTPUT STREAM -------------------------------------- LINE 0 COLS 1 78
COMMAND ===> _                                             SCROLL ===> CSR
 ****************************** TOP OF DATA ***********************************
      ASID(X'001B') 01D073D0. IGC0004B+03D0 IN EXTENDED PLPA
 ****************************** END OF DATA ***********************************

Because WHERE was invoked as a primary command, WHERE also stacks a pointer to the beginning of the load module, X'1D07000'. The pointer will appear in the Browse option of the IPCS dialog. The following shows using WHERE in the system trace table.

DSNAME('D46IPCS.DRVC400.SA00001') POINTERS  -----------------------------------
COMMAND ===> _                                             SCROLL ===> CSR
PTR   Address  Address space                            Data type
00001 00000000 ASID(X'0003')                            AREA
      Remarks:
00002 000006B0 ASID(X'0003')                            AREA
      Remarks:
00003 00FD7420 ASID(X'0001')                            STRUCTURE(Cvt)
      Remarks: Communications Vector Table
-------------------------------------------------------------------------------
|00004 01D07000 ASID(X'001B')                           MODULE(IGC0004B)      |
|      Remarks:                                                               |
-------------------------------------------------------------------------------
**************************** END OF POINTER STACK *****************************

Example 3: Use WHERE from a logrec buffer in a dump. WHERE can help you look through this table. For example, if you are examining the error PSW in the VERBEXIT LOGDATA report and want to know where address X'120E298' in the error PSW points to, you can use WHERE directly from this screen.

IPCS OUTPUT STREAM -------------------------------------- LINE 0 COLS 1 78
COMMAND ===> WHERE 120E298                                    SCROLL ===> CSR
 ****************************** TOP OF DATA ***********************************

                    * * * * * L O G D A T A * * * * *

 TYPE: SOFTWARE RECORD               REPORT: SOFTWARE EDIT REPORT   DAY.YEAR
       (SVC 13)                                         REPORT DATE 197.95
 SVC: VS 2 REL 3                                         ERROR DATE 158.95
                                     MODEL:3090                     HH:MM:SS.T
                                     SERIAL:170067                  13::1:44.9
 JOBNAME: D22AMSTR
 ERRORID: SEQ=17095 CPU=0041 ASID=0047 TIME=13:31:43.9

 < Some Output Not Shown >

 TIME OF ERROR INFORMATION

   PSW: 070C2000 8120E298   INSTRUCTION LENGTH: 02   INTERRUPT CODE: 000D
   FAILING INSTRUCTION TEXT: 581097E6 0A0D4830 C0105800

   REGISTERS 0-7
   GR: 00000000 04C78000 006F72D8 0000E601 006F72D8 7FF12080 00000004 00EE5500
   AR: 0124E1B8 00000000 00000000 00000000 00000000 00000000 00000000 00000000

Result

First, all items that contain this address are displayed using the dump display reporter panel. The message below shows that the PSW you want to examine more closely is 200 bytes into CSECT IGVSTSKT. That CSECT is in load module IEANUC01 in the read-only nucleus.

IPCS OUTPUT STREAM -------------------------------------- LINE 0 COLS 1 78
COMMAND ===> _                                             SCROLL ===> CSR
 ****************************** TOP OF DATA ***********************************
      ASID(X'0058') 0120E298. IEANUC01.IGVSTSKT+0200 IN READ ONLY NUCLEUS
 ****************************** END OF DATA ***********************************

When you press F3 to exit this screen, IPCS will stack the pointer to the beginning of the CSECT, so when you go back into Browse you can look at all of the detailed information in that register or PSW.

DSNAME('D46IPCS.DRVC400.SA00001') POINTERS  -----------------------------------
COMMAND ===> _                                             SCROLL ===> CSR
PTR   Address  Address space                            Data type
00001 00000000 ASID(X'0003')                            AREA
      Remarks:
00002 000006B0 ASID(X'0003')                            AREA
      Remarks:
00003 00FD7420 ASID(X'0001')                            STRUCTURE(Cvt)
      Remarks: Communications Vector Table
-------------------------------------------------------------------------------
|00004 0120E298 ASID(X'0058')                           MODULE(IEANUC01)      |
|      Remarks:                                                               |
-------------------------------------------------------------------------------
**************************** END OF POINTER STACK *****************************

Example 4: Determine where an absolute address is located.
- Action
```
COMMAND ===> where cda800.
```
- Result
  WHERE generates the following output line, showing that the specified address is a TCB in the PRIVATE area.
```
CDA800. STRUCTURE(TCB)-10 IN PRIVATE
```
Example 5: Determine the name of a module in storage.
- Action
  Given an address, enter a WHERE subcommand specifying the address.
```
COMMAND ===> where 04a8001a
```
- Result
  IPCS identifies the address space containing the module, the module name (if the name conforms to IPCS naming conventions), the offset of the address into the module, and the storage area containing the module.
```
 ASID(X'0179') 04A8001A. IGC0006A+1A IN EXTENDED PLPA
```
Example 6: Determine the name of a module in storage when the module name does not conform to IPCS naming conventions.
- Action
  Given an address, enter a WHERE subcommand specifying the address.
```
COMMAND ===> where 04ab001a
```
- Result
  IPCS provides the same information shown in the previous example, but instead of the name of the module, IPCS displays “SPECIALNAME”. IPCS also expands the name in hexadecimal characters, and shows the module name as an eye-catcher in the output.
```
 ASID(X'0179') 04AB001A. SPECIALNAME+A01A IN EXTENDED PLPA
+0000  C9C7C3F0  F0F1F3C0                      | IGC0013{         |
```