Current position after successful calls

Position is important when you process the database sequentially by issuing GN, GNP, GHN, and GHNP calls.

Current position is where IMS starts its search for the segments that you specify in the calls.

This topic explains current position for successful calls. Current position is also affected by an unsuccessful retrieval or ISRT call.

Before you issue the first call to the database, the current position is the place immediately before the first root segment occurrence in the database. This means that if you issue an unqualified GN call, IMS retrieves the first root segment occurrence. It is the next segment occurrence in the hierarchy that is defined by the DB PCB that you referenced.

Certain calls cancel your position in the database. You can reestablish this position with the GU call. Because the CHKP and SYNC (commit point) calls cancel position, follow either of these calls with a GU call. The ROLS and ROLB calls also cancel your position in the database.

When you issue a GU call, your current position in the database does not affect the way that you code the GU call or the SSA you use. If you issue the same GU call at different points during program execution (when you have different positions established), you will receive the same results each time you issue the call. If you have coded the call correctly, IMS returns the segment occurrence you requested regardless of whether the segment is before or after the current position.

Exception: If a GU call does not have SSAs for each level in the call, it is possible for IMS to return a different segment at different points in your program. This is based on the position at each level.

For example, suppose you issue the following call against the data structure shown in the following figure.
GU   Abbbbbbb(AKEYbbbbbA1)
     Bbbbbbbb(BKEYbbbb=bB11)
     Dbbbbbbb(DKEYbbbbbD111)
The structure in the figure contains six segment types: A, B, C, D, E, and F. Figure 1 shows one database record, the root of which is A1.
Figure 1. Current position hierarchy
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 you issue this call, IMS returns the D segment with the key D111, regardless of where your position is when you issue the call. If this is the first call your program issues (and if this is the first database record in the database), current position before you issue the call is immediately before the first segment occurrence in the database—just before the A segment with the key of A1. Even if current position is past segment D111 when you issue the call (for example, just before segment F111), IMS still returns the segment D111 to your program. This is also true if the current position is in a different database record.

When you issue GN and GNP calls, current position in the database affects the way that you code the call and the SSA. That is because when IMS searches for a segment described in a GN or GNP call, it starts the search from current position and can only search forward in the database. IMS cannot look behind that segment occurrence to satisfy a GN or GNP. These calls can only move forward in the database when trying to satisfy your call, unless you use the F command code, the use of which is described in the topic "F Command Code" in IMS Version 15 Application Programming APIs.

If you issue a GN call for a segment occurrence that you have already passed, IMS starts searching at the current position and stops searching when it reaches the end of the database (resulting in a GB status code), or when it determines from your SSA that it cannot find the segment you have requested (GE status code).

Current position affects ISRT calls when you do not supply qualified SSAs for the parents of the segment occurrence that you are inserting. If you supply only the unqualified SSA for the segment occurrence, you must be sure that your position in the database is where you want the segment occurrence to be inserted.