STRDATA subcommand — format coupling facility structure data

Use the STRDATA subcommand to format coupling facility structure data. Depending on the parameters you specify, you can obtain information at the summary or detail level and about one or more coupling facility structures.

If duplexing rebuild is supported for a structure, duplexing control information is returned in addition to the dump header information for each structure instance. The control information is returned regardless of whether duplexing is currently active for the structure.

For more information about the reports generated by the STRDATA subcommand, see the XES chapter of z/OS MVS Diagnosis: Reference.

Note: To diagnose problems related to XES, you may also want to use the XESDATA and COUPLE subcommands.

Syntax

    STRDATA

-------- Data Selection Parameters --------

               { DETAIL     }
               { SUMMARY    }

-------- Report Type Parameters --------

               { ALLSTRS     }
               { STRNAME(strname,strdumpid),...   }

-------- Additional Filter Parameters --------

               [ ALLDATA                  ]
               [ ARB                      ]
               [ COCLASS(coclass)         ]
               [ EMCONTROLS(emcontrols)   ]
               [ ENTRYID(entryid)         ]
               [ ENTRYNAME(entryname)     ]
               [ EVENTQS(conid)           ]
               [ LISTNUM(listnum)         ]
               [ LOCKENTRIES(lockentries) ]
               [ STGCLASS(stgclass)       ]
               [ USERCNTLS(usercntls)     ]

-------- Cache Specifier Parameters --------

               [ ENTRYPOS(entrypos)     ]
               [ ORDER                  ]

-------- List Specifier Parameters --------

               [ ENTRYPOS(entrypos)     ]
               [ ORDER                  ]
               [ ENTRYKEY(entrykey)     ]

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

               [ ACTIVE | MAIN | STORAGE          ]
               [ DSNAME(dsname) | DATASET(dsname) ]
               [ FILE(ddname) | DDNAME(ddname)    ]
               [ PATH(path-name)                  ]
               [ FLAG(severity)                   ]
               [ PRINT | NOPRINT                  ]
               [ TERMINAL | NOTERMINAL            ]
               [ TEST | NOTEST                    ]

Parameters
If you omit all parameters, the defaults are SUMMARY and ALLSTRS.
Data Selection Parameters
Use these parameters to limit the scope of the data in the report. If you omit these parameters, the default is SUMMARY.
SUMMARY
Requests summary information for each report you specify. The report output is STRDATA ALL STRUCTURES SUMMARY REPORT. The output fields for each structure are:
- Structure name
- Structure type
- Structure dump ID
- Coupling facility information
- Facility name
- A summary of coupling facility structure controls
An example is:
COMMAND ===> STRDATA SUMMARY
DETAIL
Requests detailed information for each report you specify. The report output is STRDATA ALL STRUCTURES DETAIL REPORT The output fields for each structure are:
- Structure name
- Structure type
- Structure dump ID
- Coupling facility information
- Facility name
- All of the coupling facility structure controls
- List of assigned users
- If applicable, duplexing control information including
  Duplexing-active indicator
  
  Remote facility node descriptor (ND) and system identifier (SYID)
  
  Remote structure identifier (SID) and structure authority (SAU)
An example is:
COMMAND ===> STRDATA DETAIL
Report Type Parameters
Use these parameters to select the type of report. If you omit a report type parameter, the default is ALLSTRS.
ALLSTRS
Requests information about all coupling facility structures found in the dump. The report output is STRDATA ALL STRUCTURES SUMMARY REPORT. The output fields for each structure are:
- Structure name
- Structure type
- Structure dump ID
- Coupling facility information
- Facility name
- A summary of coupling facility structure controls
```
COMMAND ===>  STRDATA ALLSTRS
```
STRNAME ((strname,strdumpid),(strname,strdumpid),...)
Requests information about the coupling facility structures listed. Structures may be list, cache, or any combination of list and cache.
Note: Lock structures are not dumped.
The report output is CACHE STRUCTURE SUMMARY REPORT The output fields for each structure name specified are:
Structure name

Structure type

Structure dump ID

Coupling facility information

Facility name

A summary of coupling facility cache structure controls
The strname specifies the name of a structure. For example:
COMMAND ===> STRDATA STRNAME((CACHE01))

Note: If you specify a list structure in strname, the report output is a List Structure Summary Report.
At the end of a strname, an asterisk (*) may be used as a generic character to include in the report all structure names having the specified characters in common. The following subcommand specifies all structure names beginning with the characters ‘LIST’ and the report includes structures LIST01, LIST02, LIST03, and so forth.
COMMAND ===> STRDATA STRNAME((LIST*))
The strdumpid specifies an instance of the structure in the dump. A reason you may have more than one instance of a structure in a dump is if a structure is in rebuild processing or is in the Duplex Established phase, when the dump is captured. If a structure dump ID is not provided, information for all the structures in the dump with the same name are displayed. The strdumpid is specified in hexadecimal and without quotation marks, as this example shows:
COMMAND ===> STRDATA STRNAME((CACHE01,0101))
The STRDATA STRNAME parameter is associated with the STRNAME parameter of the IXLCONN macro.
ALLDATA
Requests the display of all data found in the dump for the specified structures. When ALLDATA is specified with STRNAME, all the data regarding the specified structure is presented. When ALLDATA is specified with ALLSTRS, all the data found for all the structures in the dump is presented. The report output is:
- LIST STRUCTURE ALLDATA SUMMARY REPORT
- ASSOCIATED REQUEST BLOCK REPORT
- EVENT MONITOR CONTROLS REPORT
- EVENT QUEUE CONTROLS REPORT
- LIST NUMBER ENTRY POSITION SUMMARY REPORT
- LOCK ENTRIES REPORT
- USER CONTROLS REPORT
For the output fields in the report, see the output fields for ARB, ENTRYPOS, LOCKENTRIES, and USERCNTLS. If a cache structure had been specified, then all reports pertaining to cache structures would have been displayed.
An example is:
COMMAND ===> STRDATA STRNAME((LIST02)) ALLDATA

Additional data selection parameters

COCLASS (ALL | coclass,coclass:coclass,...)

Requests information by cast-out class for a coupling facility cache structure. The coclass can be a single cast-out class, a range of classes, or a list of noncontiguous classes. When you specify a range, separate the first and last classes in the range with a colon. When you specify a list, separate the list members with commas.

The report output is:

STRDATA ALL STRUCTURES SUMMARY REPORT
CASTOUT CLASS SUMMARY REPORT

The output fields for each coclass specified are:

Class type
Class
Class status
Cast-out class controls

The STRDATA COCLASS parameter is associated with:

The NUMCOCLASS parameter of the IXLCONN macro
The COCLASS parameter of the IXLCACHE macro

An example is:

COMMAND ===>  STRDATA COCLASS(01)

STGCLASS (ALL | stgclass,stgclass:stgclass,...)

Requests information by storage class for a coupling facility cache structure. The stgclass can be a single storage class, a range of classes, or a list of noncontiguous classes. When you specify a range, separate the first and last classes in the range with a colon. When you specify a list, separate the list members with commas.

The report output is:

STRDATA ALL STRUCTURES SUMMARY REPORT
STORAGE CLASS SUMMARY REPORT

The output fields for each storage class specified are:

Class type
Class
Class status
Class control information

The STRDATA STGCLASS parameter is associated with:

The NUMSTGCLASS parameter of the IXLCONN macro
The STGCLASS parameter of the IXLCACHE macro

An example is:

COMMAND ===>  STRDATA STGCLASS(01)

LISTNUM (ALL | listnum,listnum:listnum,...)

Requests information by list number in a coupling facility list structure. The listnum can be a single list number, a range of numbers, or a list of noncontiguous numbers. When you specify a range, separate the first and last numbers in the range with a colon. When you specify a list, separate the list members with commas.

The report output is:

STRDATA ALL STRUCTURES SUMMARY REPORT
LIST NUMBER SUMMARY REPORT

The output fields for each list number specified are:

List number
List number status
Summary of the list controls

The STRDATA LISTNUM parameter is associated with:

The LISTHEADERS parameter of the IXLCONN macro
The LISTNUM parameter of the IXLLIST macro

An example is:

COMMAND ===>  STRDATA LISTNUM(01)

EMCONTROLS(ALL | listnum,listnum:listnum,...)

Requests information about event monitor controls (EMCs) associated with a list structure identified by its list number. The listnum can be a single list number, a range of list numbers, or a list of noncontiguous list numbers. When you specify a range, separate the first and last identifiers in the range with a colon. When you specify a list number, separate the list numbers with commas.

The report output is:

STRDATA ALL STRUCTURES SUMMARY/DETAIL REPORT
EVENT MONITOR CONTROLS SUMMARY/DETAIL REPORT

The output fields for each list number are:

Event monitor controls list number
Event monitor controls status
For each EMC associated with the list number, the following EMC Detail Report information:
- Connection ID
- List number
- List entry key
- Event queue status
- User notification controls.

An example is:

COMMAND ===>  STRDATA EMCONTROLS(01)

EVENTQS(ALL | conid,conid:conid,...)

Requests information about event monitor controls (EMCs) on the event queue associated with a list structure connector. The conid can be a single connection identifier, a range of connection identifiers, or a list of noncontiguous connection identifiers. When you specify a range, separate the first and last identifiers in the range with a colon. When you specify a connection identifier, separate the connection identifiers with commas.

The report output is:

STRDATA ALL STRUCTURES SUMMARY/DETAIL REPORT
EVENT QUEUE CONTROLS SUMMARY/DETAIL REPORT

The output fields for each connection ID are:

Connection ID
Number of EMCs dumped
Event queue controls status
Event queue transition exit status
Event queue monitoring status
Event notification vector index
Number of EMCs queued
Number of state transitions
For each EMC on the event queue:
- EMC Detail Report information as described above for EMCONTROLS

An example is:

COMMAND ===>  STRDATA EVENTQS(1)

USERCNTLS (ALL | conid,conid:conid,...)

Requests information by user connection identifier about the user of a structure. The conid can be a single connection identifier, a range of identifiers, or a list of noncontiguous identifiers. When you specify a range, separate the first and last identifiers in the range with a colon. When you specify a list, separate the list members with commas.

The report output is:

STRDATA ALL STRUCTURES SUMMARY REPORT
USER CONTROLS REPORT

The output fields for each connection identifier (ID) specified are:

Connection ID status
Connection name
Connection ID
Connection status
User authority
User control information

An example is:

COMMAND ===>  STRDATA USERCNTLS(01)

LOCKENTRIES (ALL | lockentry,lockentry:lockentry,...)

Requests information by the entries specified for the lock table entries of a coupling facility list structure. The lockentry can be a entry, a range of entries, or a list of noncontiguous entries. When you specify a range, separate the first and last entries in the range with a colon. When you specify a list, separate the list members with commas.

The report output is:

STRDATA ALL STRUCTURES SUMMARY REPORT
LOCK ENTRIES REPORT

The output fields for each entry into the lock table are:

Lock entries status
Lock entries
Owners connection ID
Held By system indicator

The STRDATA LOCKENTRIES parameter is associated with:

The LOCKENTRIES parameter of the IXLCONN macro
The LOCKINDEX parameter of the IXLLIST macro

An example is:

COMMAND ===>  STRDATA LOCKENTRIES(ALL)

ENTRYID (entryid,X'entryid',...)

Requests the display of information by list entry identifiers for a coupling facility list structure. The entryid can be expressed in decimal or in hexadecimal (X'nnn').

The report output is:

STRDATA ALL STRUCTURES SUMMARY REPORT
LIST ENTRY IDENTIFIER SUMMARY REPORT

The output fields for each entry ID specified are:

List entry identifier
List entry controls
Adjunct data
Structure serialization indicator

The STRDATA ENTRYID parameter is associated with the ENTRYID parameter of the IXLLIST macro.

An example is:

COMMAND ===>  STRDATA ENTRYID(X'000000000000000100000009')

ENTRYNAME (entryname,entryname...)

Requests information by list entry names in a coupling facility list structure or by data entry names in a coupling facility cache structure.

The report output is:

STRDATA ALL STRUCTURES SUMMARY REPORT
ENTRY NAME SUMMARY REPORT

The output fields for each entry name specified are:

Entry name
Directory information (for cache)/ list entry controls (for list)
Adjunct data
Structure serialization indicator

The STRDATA ENTRYNAME parameter is associated with:

The ENTRYNAME parameter of the IXLLIST macro
The NAME parameter of the IXLCACHE macro

An example is:

COMMAND ===>  STRDATA ENTRYNAME(ELEMENT2)

ARB

Requests formatting of the associated request block (ARB), which contains a list of all the valid ranges specified on the STRLIST option of the DUMP, CHNGDUMP, or SLIP operator command. If the dump was taken by a recovery routine, the ARB contains the data derived from the IHABLDP macro.

Note: The actual dump parameters may have been modified to be consistent with the structure specifications. For example, if castout classes 1 to 2000 were requested to be dumped, but only castout classes 1 to 10 were valid, the ARB input were modified before the dump was taken.

The report output is:

STRDATA ALL STRUCTURES SUMMARY REPORT
ASSOCIATED REQUEST BLOCK REPORT

The output fields are:

Total ranges requested in ARB
Last range dumped
Range number
Dump object type for each range requested. For example, list number or lock entries.

An example is:

COMMAND ===>  STRDATA ARB

ENTRYPOS (ALL | entrypos,entrypos:entrypos,...)

Requests information about an entry in a particular position, or range of positions. This parameter is valid only with COCLASS, STGCLASS, or LISTNUM. The position of an entry is counted from the head or tail of the queue, depending on the ORDER parameter. The entrypos can be a single position, a range of positions, or a list of noncontiguous positions. When you specify a range, separate the first and last positions in the range by a colon. When you specify a list, separate the list members with commas.

The report output is:

STRDATA ALL STRUCTURES SUMMARY REPORT
LIST NUMBER ENTRY POSITION SUMMARY REPORT

Note: If STGCLASS is also specified, IPCS also displays the STORAGE CLASS ENTRY POSITION SUMMARY REPORT. If STGCLASS or COCLASS is specified, IPCS also displays the CASTOUT CLASS ENTRY POSITION SUMMARY REPORT.

The output fields for each entry specified are:

List number
List number status
Summary of the list controls
Entry key, if requested
Order indicator
For each entry requested:
- Entry position
- List entry controls
- Adjunct data
- Serialization indicator

The STRDATA ENTRYPOS parameter is associated with:

The LISTDIR parameter of the IXLLIST macro
The COCLASS and STGCLASS parameters of the IXLCACHE macro

An example is:

COMMAND ===>  STRDATA LISTNUM(ALL) ENTRYPOS(2)

ORDER (HEAD | TAIL)

Specifies the order for entries to be displayed. Specify ORDER only with ENTRYPOS. The position number specified in ENTRYPOS depends on whether you are counting from the head or the tail of the queue.

HEAD is the default and specifies that entries be located from at the top of a list or the head of a queue. For a storage class, the head of a queue is the least recently referenced entry. For a cast-out class, the head of a queue is the least recently changed entry.

TAIL specifies that entries be located from the end of a list or the tail of a queue. For a storage class, the tail of a queue is the most recently referenced entry. For a cast-out class, the tail of a queue is the most recently changed entry.

For example, if there are 35 entries on list number 2, and you want the 30th entry from the start of the queue, specify either of the following to display the same entry:

COMMAND ===>  STRDATA LISTNUM(2) ENTRYPOS(30) ORDER(HEAD)

COMMAND ===>  STRDATA LISTNUM(2) ENTRYPOS(6) ORDER(TAIL)

ENTRYKEY(entrykey,entrykey...)

Requests the display of a list entry with the specified key or the event monitor controls (EMCs) associated with a list entry and the specified key. This parameter can be used only for LISTNUM (when ENTRYPOS is specified) and EMCONTROLS processing.

The report output is

STRDATA ALL STRUCTURES SUMMARY REPORT
LIST NUMBER ENTRYKEY ENTRY POSITION SUMMARY REPORT

The output fields are:

List number
List number status
Summary of the list controls
Entry key
Order indicator
For each entry requested:
- Entry position
- List entry controls
- Adjunct data
- Serialization indicator

The STRDATA ENTRYKEY parameter is associated with:

The LISTCNTLTYPE=ENTRY and REFOPTION=KEY parameters of the IXLCONN macro
The ENTRYKEY parameter of the IXLLIST macro

For example, the entry positions are in an order that is relative to the entry key. Table 1 shows queue 1, which is a list with 5 entries:

Table 1. Example of queue and entry postions
LIST 2
Head of Queue
entry 1 key 1 entry 2 key 2 entry 3 key 2 entry 4 key 2 entry 5 key 3
Tail of Queue

To display the second and third entries for key 2 from the head of list 2, enter the following command:

COMMAND ===>  STRDATA LISTNUM(2) ENTRYPOS(2,3) ENTRYKEY(02) ORDER(HEAD)

Table 2 shows how entries with the same key are considered a separate queue, queue 2, so you get back entry 3 as entry position 2 and entry 4 as entry position 3.

Table 2. Example of entries considered as a separate queue
LIST 2
entry 1 key 1
Head of Queue
entry 2 key 2 position 1 entry 3 key 2 position 2 entry 4 key 2 position 3
Tail of Queue
entry 5 key 3

Another example is:

COMMAND ===>  STRDATA ENTRYKEY(02) LISTNUM(ALL) ENTRYPOS(ALL)