IMS DB Get Next Call

IMSDB Database Functions IMSDB Get Hold Next(GHN)


Used to retrieve the next segment in the database.

GN call is used to retrieve the segments sequentially from the database.

			  I/O Area

Lets discuss about individual parameters.


- Database Program Control Block

- Specifies the DB PCB for the GN call.

- DB PCB will act as an input and output parameter.


- Known as Application Interface Block.

- Specifies the AIB for the call.

- AIB parameter is an input and output parameter.

- If AIB using in the GN call, all the below fields must be initialized in the AIB



- Known as Input-Output Area.

- Specifies the I/O area in GN Call.

- I/O Area parameter is an output parameter.

- If Get Next calls completed successfully, IMS returns the requested segment in I/O area.

- If any path calls issued from the application program, the I/O area must be long enough to hold the longest path of concatenated segments.

- I/O area always contains left-justified segment data.

- The I/O area points to the first byte of this area.


- Known as Segment Search Arguments.

- Specifies to be used in the call.

- SSA parameter is an input parameter.

- The SSA supplies in the call to data areas in the application program where the SSA has been defined for the call.

- Up to 15 SSAs can be used in the parameter.

- SSA parameter is optional for the GN call.


- Specifies the area in application program where the RSA for the record should be returned.

- RSA output parameter is used for GSAM only.

- RSA parameter is optional for GN call.

A Get Next (GN) call is used to request for a segment based on the SSA supplied in the call statement.

After issuing GN call, IMS starts its search at the current position.

The GN call can be used in below scenarios:

  • If processing from current position to move forward.
  • If IMS uses the current position as the search starting point.

A GN call retrieves the next segment in the hierarchy that satisfies the SSA supplied in call.

Normally GN issued a call after GU call.

GN retrieves the next segment in the hierarchy after the successful call of GU.

GN retrieves the first segment in the database (i.e. root), if GU call is not successful.

GN call retrieves a segment or path of segments by moving forward from the current position in the database.

IMS looks for segments at each level to satisfy the GN call if the continuous call satisfies.

The 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 returned the last segment, IMS returns the root segment occurrence of the current root segment.

A GN call with qualified segment type, can retrieve all the occurrences of a particular segment type from the database.

Like GU, a GN call can have as many SSAs as the hierarchy has levels.

A GN calls with fully qualified SSAs, clearly identifies the hierarchic path and the segment required.

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

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

A GN that has multiple SSAs, the presence or absence of unqualified SSAs in the call has no effect on the operation unless command codes used on the unqualified SSA.

A GN call with a SSA qualified on the key of the root segment can produce different results based on the current position 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.

Return Codes:

GE - Not found

GN returns the GE status code if the below conditions occurred,

• The value of the key in the SSA has an upper limit ( i.e. <= set)

• A segment with a key greater than the value in the SSA is found in a sequential search.

GB - End of the Database.

IMS returns the GB status code if the sequential search reaches to End of the database without finding the required segment.

  1. GN can return the GE status code for segment exists and can be retrieved by a GU call. Because GN can’t search for the segments which are might be behind the current position.
  2. The GN call will be dangerous if it is triggered with the "not equal" or "greater than" relational operators that force IMS to search to the end of the database without retrieving a segment.

IMSDB Database Functions IMSDB Get Hold Next(GHN)