GN/GHN call

The Get Next (GN) call is used to retrieve segments sequentially from the database. The Get Hold Next (GHN) is the hold form for a GN call.

Format

Read syntax diagramSkip visual syntax diagramGNdb pcbaibi/o areassarsaGHNdb pcbaibi/o areassa
  Call Name DB/DC DBCTL DCCTL DB Batch TM Batch
For Full-Function: GN/GHN X X   X  
For GSAM: GN X X X X X
For DEDB: GN X X X    
For MSDB: GN X        

Parameters

db pcb
Specifies the DB PCB for the call. This parameter is an input and output parameter.
aib
Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB:
AIBID
Eye catcher. This 8-byte field must contain DFSAIBbb.
AIBLEN
AIB lengths. This field must contain the actual length of the AIB that the application program obtained.
AIBRSNM1
Resource name. This 8-byte, left-justified field must contain the name of a DB PCB.
AIBOALEN
I/O area length. This field must contain the length of the I/O area specified in the call list.
i/o area
Specifies the I/O area. This parameter is an output parameter. When you issue one of the Get calls successfully, IMS returns the requested segment to this area. If your program issues any path calls, the I/O area must be long enough to hold the longest path of concatenated segments following a path call. This area always contains left-justified segment data. The I/O area points to the first byte of this area.

When you use the GN call with GSAM, the area named by the i/o area parameter contains the record you are retrieving.

ssa
Specifies the SSA, if any, to be used in the call. This parameter is an input parameter. The SSA that you supply in the call point to data areas in your program where the SSA have been defined for the call. You can use up to 15 SSAs in the parameter. This parameter is optional for the GN call.
rsa
Specifies the area in your program where the RSA for the record should be returned. This output parameter is used for GSAM only and is optional. See the topic "GSAM Data Areas" in IMS Version 15.2 Application Programming for more information on RSAs.

Usage: Get Next (GN)

A Get Next (GN) call is a request for a segment, as described by the SSA you supply, that is linked to the call that was issued prior to the GN call. IMS starts its search at the current position.

When you use the GN call:

  • Processing moves forward from current position (unless the call includes the F command code).
  • IMS uses the current position (that was set by the previous call) as the search starting point.
  • The segment retrieved is determined by a combination of the next sequential position in the hierarchy and the SSA included in the call.
  • Be careful when you use GN, because it is possible to use SSAs that force IMS to search to the end of the database without retrieving a segment. This is particularly true with the not equal or greater than relational operators.

A GN call retrieves the next segment in the hierarchy that satisfies the SSA that you supplied. Because the segment retrieved by a GN call depends on the current position in the hierarchy, GN is often issued after a GU call. If no position has been established in the hierarchy, GN retrieves the first segment in the database. A GN call retrieves a segment or path of segments by moving forward from the current position in the database. As processing continues, IMS looks for segments at each level to satisfy the call.

For example, sequential retrieval in a hierarchy is always top to bottom and left to right. For example, if you repeatedly issue unqualified GN calls against the hierarchy in the following figure, IMS returns the segment occurrences in the database record in this order:

  1. A1 (the root segment)
  2. B1 and its dependents (C1,D1,F1,D2,D3,E1,E2, and G1)
  3. H1 and its dependents (I1,I2,J1, and K1).

If you issue an unqualified GN again after IMS has returned K1, IMS returns the root segment occurrence whose key follows segment A1 in the database.

A GN call that is qualified with the segment type can retrieve all the occurrences of a particular segment type in the database.

Figure 1. Hierarchic sequence
Shows hierarchical relationship. A1 is the parent of both B1 and H1. Because B1 appears on the left side of the hierarchy, IMS returns B1 and all of its dependencies before returning H1

For example, if you issue a GN call with qualified SSAs for segments A1 and B1, and an unqualified SSA for segment type D, IMS returns segment D1 the first time you issue the call, segment D2 the second time you issue the call, and segment D3 the third time you issue the call. If you issue the call a fourth time, IMS returns a status code of GE, which means that IMS could not find the segment you requested.

You can use unqualified GN calls to retrieve all of the occurrences of a segment in a hierarchy, in their hierarchic sequence, starting at the current position. Each unqualified GN call retrieves the next sequential segment forward from the current position. For example, to answer the processing request:

Print out the entire medical database.
You would issue an unqualified GN call repeatedly until IMS returned a GB status code, indicating that it had reached the end of the database without being able to satisfy your call. If you issued the GN again after the GB status code, IMS would return the first segment occurrence in the database.

Like GU, a GN call can have as many SSAs as the hierarchy has levels. Using fully qualified SSAs with GN calls clearly identifies the hierarchic path and the segment you want, thus making it useful in documenting the call.

A GN call with an unqualified SSA retrieves the next occurrence of that segment type by going forward from the current position.

GN with a qualified SSA retrieves the next occurrence of the specified segment type that satisfies the SSAs.

When you specify a GN that has multiple SSAs, the presence or absence of unqualified SSAs in the call has no effect on the operation unless you use command codes on the unqualified SSA. IMS uses only qualified SSAs plus the last SSA to determine the path and retrieve the segment. Unspecified or unqualified SSAs for higher-level segments in the hierarchy mean that any high-level segment that is the parent of the correct lower-level, specified or qualified segment will satisfy the call.

A GN call with a SSA that is qualified on the key of the root can produce different results from a GU with the same SSA, depending on the position in the database and the sequence of keys in the database. If the current position in the database is beyond a segment that would satisfy the SSA, the segment is not retrieved by the GN. GN returns the GE status code if both of these conditions are met:

  • The value of the key in the SSA has an upper limit that is set, for example, to less-than-or-equal-to the value.
  • A segment with a key greater than the value in the SSA is found in a sequential search before the specified segment is found.

GN returns the GE status code, even though the specified segment exists and would be retrieved by a GU call.

Usage: Get Hold Next (GHN)

Before your program can delete or replace a segment, it must retrieve the segment and indicate to IMS that it is going to change the segment in some way. The program does this by issuing a Get call with a hold before deleting or replacing the segment. When the program has successfully retrieved the segment with a Get Hold call, it can delete the segment or change one or more fields (except the key field) in the segment.

The only difference between Get calls with a hold and Get calls without a hold is that the hold calls can be followed by REPL or DLET.

The hold status on the retrieved segment is canceled and must be reestablished before you reissue the DLET or REPL call. After issuing a Get Hold call, you can issue more than one REPL or DLET call to the segment if you do not issue intervening calls to the same PCB.

If you find out that you do not need to update it after issuing a Get Hold call, you can continue with other processing without releasing the segment. The segment is freed as soon as the current position changes—when you issue another call to the same PCB that you used for the Get Hold call. In other words, a Get Hold call must precede a REPL or DLET call. However, issuing a Get Hold call does not require you to replace or delete the segment.

Usage: HDAM, PHDAM, or DEDB database with GN

For database organizations other than HDAM, PHDAM, and DEDB, processing the database sequentially using GN calls returns the root segments in ascending key sequence. However, the order of the root segments for a HDAM, PHDAM, or DEDB database depends on the randomizing routine that is specified for that database. Unless a sequential randomizing routine was specified, the order of the root segments in the database is not in ascending key sequence.

For a hierarchic direct access method (HDAM, PHDAM) or a DEDB database, a series of unqualified GN calls or GN calls that are qualified only on the root segment:

  1. Returns all the roots from one anchor point
  2. Moves to the next anchor point
  3. Returns the roots from the anchor point

Unless a sequential randomizing routine was specified, the roots on successive anchor points are not in ascending key sequence. One situation to consider for HDAM, PHDAM, and DEDB organizations is when a GN call is qualified on the key field of the root segment with an equal-to operator or an equal-to-or-greater-than operator. If IMS has an existing position in the database, it checks to ensure that the requested key is equal to or greater than the key of the current root. If it is not, a GE status code is returned. If it is equal to or greater than the current key and is not satisfied using the current position, IMS calls the randomizing routine to determine the anchor point for that key. IMS tries to satisfy the call starting with the first root of the selected anchor.

Restrictions

You can use GN to retrieve the next record of a GSAM database, but GHN is not valid for GSAM.