Current position after unsuccessful calls

IMS establishes another kind of position when you issue retrieval and ISRT calls. This is position on one segment occurrence at each hierarchic level in the path to the segment that you are retrieving or inserting. Not every DL/I call that your program issues will be completely successful. When a call is unsuccessful, you should understand how to determine your position in the database after that call.

You need to know how IMS establishes this position to understand the U and V command codes described in the topic "General Command Codes for DL/I Calls" in IMS Version 15.2 Application Programming APIs. Also, you need to understand where your position in the database is when IMS returns a not-found status code to a retrieval or ISRT call.

Position after an unsuccessful DLET or REPL call

DLET and REPL calls do not affect current position. Your position in the database is the same as it was before you issued the call. However, an unsuccessful Get call or ISRT call does affect your current position.

To understand where your position is in the database when IMS cannot find the segment you have requested, you need to understand how DL/I determines that it cannot find your segment.

In addition to establishing current position after the lowest segment that is retrieved or inserted, IMS maintains a second type of position on one segment occurrence at each hierarchic level in the path to the segment you are retrieving or inserting.

For example, in the following figure, if you had just successfully issued the GU call with the SSA shown below, IMS has a position established at each hierarchic level.

GU   Abbbbbbb(AKEYbbbb=bA1)
     Bbbbbbbb(BKEYbbbbbbB11)
     Cbbbbbbb(CKEYbbbb=bC111)

Now DL/I has three positions, one on each hierarchic level in the call:

One on the A segment with the key A1
One on the B segment with the key B11
One on the C segment with the key C111

Hierarchical relationship between segment types. Segment A is parent of segments B and E. Segment B is parent of segments C and D. Segment E is parent of segment F

When IMS searches for a segment occurrence, it accepts the first segment occurrence it encounters that satisfies the call. As it does so, IMS stores the key of that segment occurrence in the key feedback area.

Position after an unsuccessful retrieval or ISRT call

Current position after a retrieval or ISRT call that receives a GE status code depends on how far IMS got in trying to satisfy the SSA in the call. When IMS processes an ISRT call, it checks for each of the parents of the segment occurrence you are inserting. An ISRT call is similar to a retrieval call, because IMS processes the call level by level, trying to find segment occurrences to satisfy each level of the call. When IMS returns a GE status code on a retrieval call, it means that IMS was unable to find a segment occurrence to satisfy one of the levels in the call. When IMS returns a GE status code on an ISRT call, it means that IMS was unable to find one of the parents of the segment occurrence you are inserting. These are called not-found calls.

When IMS processes retrieval and ISRT calls, it tries to satisfy your call until it determines that it cannot. When IMS first tries to find a segment matching the description you have given in the SSA and none exists under the first parent, IMS tries to search for your segment under another parent. How you code the SSA in the call determines whether IMS can move forward and try again under another parent.

For example, suppose you issue the following GN call to retrieve the C segment with the key of C113 in the hierarchy shown in the previous figure.

     Abbbbbbb(AKEYbbbb=bA1)
     Bbbbbbbb(BKEYbbbb=bB11)
     Cbbbbbbb(CKEYbbbb=bC113)

When IMS processes this call, it searches for a C segment with the key equal to C113. IMS can only look at C segments whose parents meet the qualifications for the A and B segments. The B segment that is part of the path must have a key equal to B11, and the A segment that is part of the path must have a key equal to A1. IMS then looks at the first C segment. Its key is C111. The next C segment has a key of C112. IMS looks for a third C segment occurrence under the B11 segment occurrence. No more C segment occurrences exist under B11.

Because you have specified in the SSA that the A and B segment occurrences in C's path must be equal to certain values, IMS cannot look for a C segment occurrence with a key of C113 under any other A or B segment occurrence. No more C segment occurrences exist under the parent B11; the parent of C must be B11, and the parent of B11 must be A1. IMS determines that the segment you have specified does not exist and returns a not-found (GE) status code.

When you receive the GE status code on this call, you can determine where your position is from the key feedback area, which reflects the positions that IMS has at the levels it was able to satisfy, in this case, A1 and B11.

After this call, current position immediately follows the last segment occurrence that IMS examined in trying to satisfy your call, in this case, C112. Then, if you issue an unqualified GN call, IMS returns D111.

The current position after this call is different if A and B have non-unique keys. Suppose A's key is unique and B's is non-unique. After IMS searches for a C113 segment under B11 and is unable to find one, IMS moves forward from B11 to look for another B segment with a key of B11. When IMS does not find one, DL/I returns a GE status code. Current position is further in the database than it was when both keys were unique. Current position immediately follows segment B11. An unqualified GN call would return B12.

If B is an unkeyed segment, there can be no position at B level. Position is set after the highest segment matching SSA qualification, in this case, A1.

If A and B both have non-unique keys, current position after the previous call immediately follows segment A1. Assuming no more segment A1s exist, an unqualified GN call would return segment A2. If other A1s exist, IMS tries to find a segment C113 under the other A1s.

But suppose you issue the same call with a greater-than-or-equal-to relational operator in the SSA for segment B:

GU   Abbbbbbb(AKEYbbbb=>bA1)
     Bbbbbbbb(BKEYbbbb=>B11)
     Cbbbbbbb(CKEYbbbb=>bC113)

IMS establishes position on segment A1 and segment B11. Because A1 and B11 satisfy the first two SSAs in the call, IMS stores their keys in the key feedback area. IMS searches for a segment C113 under segment B11. None is found. But this time, IMS can continue searching, because the key of the B parent can be greater than or equal to B11. The next segment is B12. Because B12 satisfies the qualification for segment B, IMS places B12's key in the key feedback area. IMS then looks for a C113 under B12 and does not find one. The same thing happens for B13: IMS places the key of B13 in the key feedback area and looks for a C113 under B13.

When IMS finds no more B segments under A1, it again tries to move forward to look for B and C segments that satisfy the call under another A parent. But this time it cannot; the SSA for the A segment specifies that the A segment must be equal to A1. (If the keys were non-unique, IMS could look for another A1 segment.) IMS then knows that it cannot find a C113 under the parents you have specified and returns a GE status code to your program.

In this example, you have not limited the search for segment C113 to only one B segment, because you have used the greater-than-or-equal-to operator. The position is further than you might have expected, but you can tell what the position is from the key feedback area. The last key in the key feedback area is the key of segment B13. The current position of IMS immediately follows segment B13. If you then issue an unqualified GN call, IMS returns segment E11.

Each of the B segments that IMS examines for this call satisfies the SSA for the B segment, so IMS places the key of each in the key feedback area. But if one or more of the segments IMS examines does not satisfy the call, IMS does not place the key of that segment in the key feedback area. This means that the position in the database might be further than the position reflected by the key feedback area. For example, suppose you issue the same call, but you qualify segment B on a data field in addition to the key field. To do this, you use multiple qualification statements for segment B.

Assume the data field you are qualifying the call on is called BDATA. Assume the value you want is 14, but that only one of the segments, B11, contains a value in BDATA of 14:

GN   Abbbbbbb(AKEYbbbb=bA1)
     Bbbbbbbb(BKEYbbbb>=B11*BDATAbbb=b14)
     Cbbbbbbb(CKEYbbbb=bC113)

After you issue this call, the key feedback area contains the key for segment B11. If you continue issuing this call until you receive a GE status code, the current position immediately follows segment B13, but the key feedback area still contains only the key for segment B11. Of the B segments IMS examines, only one of them (B11) satisfies the SSA in the call.

When you use a greater-than or greater-than-or-equal-to relational operator, you do not limit the search. If you get a GE status code on this kind of call, and if one or more of the segments IMS examines does not satisfy an SSA, the position in the database may be further than the position reflected in the key feedback area. If, when you issue the next GN or GNP call, you want IMS to start searching from the position reflected in the key feedback area instead of from its real position, you can either:

Issue a fully qualified GU call to reestablish position to where you want it.
Issue a GN or GNP call with the U command code. Including a U command code on an SSA tells IMS to use the first position it established at that level as qualification for the call. This is like supplying an equal-to relational operator for the segment occurrence that IMS has positioned on at that level.

For example, suppose that you first issue the GU call with the greater-than-or-equal-to relational operator in the SSA for segment B, and then you issue this GN call:

GN   Abbbbbbb*U
     Bbbbbbbb*U
     Cbbbbbbbb

The U command code tells IMS to use segment A1 as the A parent, and segment B11 as the B parent. IMS returns segment C111. But if you issue the same call without the U command code, IMS starts searching from segment B13 and moves forward to the next database record until it encounters a B segment. IMS returns the first B segment it encounters.