Retrieve trace
When an application program executes and a problem occurs (such as damaged data or unexpected results), you can use the Retrieve trace records to see how IMS responded to various calls in the application.
To set the Retrieve trace
To set the Retrieve trace on, use either of the following methods:
- At initialization time, IMS always turns the Retrieve trace on, except for batch.
- For DB/DC and DBCTL environments, use the /TRACE SET
ON TABLE RETR command. If you start the DL/I trace by using
the /TRACE SET ON TABLE DLI command, the Retrieve
trace is not automatically turned on. Note: The Retrieve trace cannot be turned on if the DL/I trace is not active.
- X'0700'
- Indicates the trace is on.
- X'07FC'
- Indicates the trace is off.
Every time an application issues a get or insert call, the retrieve module (DFSDLR00) is called. This module is very large and contains many subroutines. By looking at the Retrieve trace, you can see the flow of control through the various subroutines of the retrieve module. As each subroutine calls another, a 2-byte hexadecimal entry is inserted into the trace table. (Byte 1 of the trace entry is the ID of the calling subroutine; byte 2 is the ID of the subroutine that is called.)
The Retrieve trace table is filled from beginning to end. When the table becomes full, tracing starts at the beginning of the table, overlaying each old entry with the new entry.
The first entry in the trace table for a call is X'F1', which is paired with entries: X'2F' (UNQL), X'30' (ROOTISRT), or X'31' (QUAL). The presence of any of these entries indicates the beginning of a trace entry for a retrieve call.
Field JCBRTVTR in the JCB also contains Retrieve trace information. JDBRTVTR contains the offsets to the initial entries in the trace table for the previous four DL/I calls that are associated with a database. The offset to the last call is in the low-order byte, and all offsets are shifted left at the start of each new call.
Example of Retrieve Trace
The execution of an application results in an error message that indicates damaged data. You can refer to the Retrieve trace table and interpret the entries in order to determine if the problem is caused by:
- An application error
- A database design error
- An internal IMS DB problem
- An IMS system problem related to pointers
If you determine that the problem was caused by an application or database design error, you can use the Retrieve trace to debug and resolve the problem. Otherwise, you can do a keyword search. If the search results in a large number of problems, you can reduce the number of problems by including the name of the subroutine (listed in the following table) that you found in the Retrieve trace table.
| Hex ID | Subroutine title | Subroutine description |
|---|---|---|
| 01 | BLDVKEY | Builds alternate parent's concatenated key in work area. |
| 02 | CSIIGEXT | Reads root based on SSA qualification. If found, GE at level one. If not found, GE at level 0. |
| 03 | DIVRSETU | Position (DIV) was not found at this level. Sets off EOC and sets on not posted first child and siblings. |
| 04 | ENQDQ | Handles all enqueue and dequeue for retrieve. |
| 05 | FNDLPNQ | Final physical root of LP SDB and enqueue it. |
| 06 | FORTHISL | Tries to get a segment that satisfies the call at this level or higher. |
| 07 | GEEXIT | Publishes GE status code or GB (if root SDBEOC on). |
| 08 | GETPSDB | Gets the PSDB of the segment pointed to by JCBACSC. |
| 09 | GETPRIME | Issues request for SETL to retrieve next higher root in database. |
| 0A | STLALTPS | Processes request for data by key when an alternate processing sequence is used. |
| 0B | ISRTMPOS | While positioning for insert, a matching segment was found; checks if permissible. |
| 0C | ISRTPOS | Checks for LC insert to locate alternate parent, validate insert, or establish position on alternate twin chain. |
| 0D | ISRTVER | Verifies segment in POSP points to segment in SDBPOSN for HDAM and HIDAM organizations. |
| 0E | KDTEST | Compares value in SSA to value in segment or to key feedback for requalification. |
| 0F | LCPTRTST | Used by CC=L processing to use PCL pointer, if any. |
| 10 | LTW | Main driver for requalification to determine the acceptability of current position. |
| 11 | LTWLRTN | Used by CC=L processing to see if on last or should use PCL pointer or continue trying (HS). |
| 12 | LTWLTST | Used by CC=L processing to find the last segment. |
| 13 | MOVEKEY | Moves key from segment to PCB key feedback. |
| 14 | MVSEGUSE | Moves the requested segment from the I/O area to the user area. |
| 15 | POSTCHLD | Captures child RBNs from input SDB prefix and places in SDBPOSN of dependent SDBs. |
| 16 | POSTME | Places search starting position for segment in SDB. |
| 17 | POSTTRY | Unqualified GN has found a segment. Posts the position and key. |
| 18 | POSTCURP | Moves position from JCB work words into SDB and sets post code. |
| 19 | POSTSDBN | Stores location of next segment on chain in JCB work words. |
| 1A | READCUR | Locates current entry in passes SDB. |
| 1B | RDLPCONK | Locates logical parent using its key. |
| 1C | READNXT | Locates next segment from passes SDB. |
| 1D | RDPHYPR | Locates physical pair of segments when passed SDB address of its pair. |
| 1E | RESETMP | Initializes for unqualified call. |
| 1F | RESETQMP | Compares previous call position in level table to current qualification where POS=M. |
| 20 | SCDCRSCK | Not first LR crossed and concatenated segment ISRT, builds concatenated key of LC physical parent. |
| 21 | SETEOC | Sets EOC in requested SDB. If logical parent enqueues outstanding, locates each and dequeues. |
| 22 | SETL | Provides interface to buffer handler for all external data requests. |
| 23 | SETLBG | Issues request for SETL to get first root in database. |
| 24 | SETPVEOC | Sets EOC on previous SDBs in the hierarchy having the same parent as the passed SDB. |
| 25 | SSAEVAL | Examines a segment to see if it satisfies the qualification. |
| 26 | SETCHEOC | Sets on SDBEOC of dependent SDBs. |
| 27 | STECHISB | Sets SDBEOC on for input SDB and siblings having same physical parent. |
| 28 | SETLMIKY | SETL to find key equal to or greater than key determined as minimum value for SSA. |
| 29 | STNPHISB | Sets EOC (if in use) and not posted for siblings of input SDB. |
| 2A | THISLVOK | Found one at this level that satisfies the call. Uses it and checks for more levels in call. |
| 2B | UNQGN | Gets next sensitive segment without violating parentage. |
| 2C | VLEXP | Processes variable length segment and user data compaction. |
| 2D | WIPEDN | Clears level table below level passed to bottom of table or below entry currently cleared. |
| 2E | XDFTEST | Qualification is secondary index. Checks index entries to validate the position. |
| 2F | UNQL | Master driver for calls without SSAs. |
| 30 | ROOTISRT | Routine for positioning to insert at physical root of database. |
| 31 | QUAL | Driver for qualified retrievals. |
| 32 | HSAMRTN | HSAM I/O interface routine. |
| 33 | RETRY | Retry routine for processing option GOT. |
| 34 | ISRTCHCK | Use two keys in DSG for root insert. |
| 35 | VALIDATE | Validate an EPS. |
| 36 | PARTCKRC | Check results of the validate. |
| 37 | HDTARGET | PHDAM/HDAM get a key equal or greater. |
| 38 | HDNEXT | PHDAM/HDAM get next. |
| 39 | HDTARGET | PHDAM/HDAM get a first. |
| 3A | OLRTRACE | Trace IWAIT/IPOST for OLR fence. |
| F1 | INIT | Initialization. |
