GNP/GHNP call

The Get Next in Parent (GNP) call is used to retrieve dependents sequentially. The Get Hold Next in Parent (GHNP) call is the hold form for the GNP call.

Format

Read syntax diagramSkip visual syntax diagramGNPGHNPdb pcbaibi/o areassa
  Call Name DB/DC DBCTL DCCTL DB Batch TM Batch
For Full-Function: GNP/GHNP X X   X  
For DEDB: GNP/GHNP X X X    
For MSDB: GNP/GHNP 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 the Get call 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. The segment data that this area contains is always left-justified. The I/O area points to the first byte of this area.
ssa
Specifies the SSA, if any, to be used in the call. This parameter is an input parameter. The SSA you supply in the call point to data areas in your program in which you have defined the SSAs for the call. You can use up to 15 SSAs for this parameter. This parameter is optional for the GNP call.

Usage: Get Next in Parent (GNP)

A GNP call retrieves segments sequentially. The difference between a GN and a GNP is that GNP limits the segments that can satisfy the call to the dependent segments of the established parent.

An unqualified GNP retrieves the first dependent segment occurrence under the current parent. If your current position is already on a dependent of the current parent, an unqualified GNP retrieves the next segment occurrence.

If you are moving forward in the database, even if you are not retrieving every segment in the database, you can use GNP to restrict the returned segments to only those children of a specific segment.

Linking with previous DL/I calls

A GNP call is linked to the previous DL/I calls that were issued by your program in two ways:

  • Current position: The search for the requested segment starts at the current position established by the preceding GU, GN, or GNP call.
  • Parentage: The search for the requested segment is limited to the dependents of the lowest-level segment most recently accessed by a GU or GN call. Parentage determines the end of the search and is in effect only following a successful GU or GN call.
Processing with parentage

You can set parentage in two ways:

  • By issuing a successful GU or GN call. When you issue a successful GU or GN call, IMS sets parentage at the lowest-level segment returned by the call. Issuing another GU or GN call (but against a different PCB) does not affect the parentage that you set using the first PCB in the previous call. An unsuccessful GU or GN call cancels parentage.
  • By using the P command code with a GU, GN, or GNP call, you can set parentage at any level.
How DL/I calls affect parentage

A GNP call does not affect parentage unless it includes the P command code.

Unless you are using a secondary index, REPL does not affect parentage. If you are using a secondary index, and you replace the indexed segment, parentage is lost.

A DLET call does not affect parentage unless you delete the established parent. If you do delete the established parent, you must reset parentage before issuing a GNP call.

ISRT affects parentage only when you insert a segment that is not a dependent of the established parent. In this case, ISRT cancels parentage. If the segment you are inserting is a dependent at some level of the established parent, parentage is unaffected. For example, in the topic "Position after ISRT" in IMS Version 15 Application Programming, assume segment B11 is the established parent. Neither of these two ISRT calls would affect parentage: 
ISRT   Abbbbbbb(AKEYbbbb=bA1)
       Bbbbbbbb(BKEYbbbb=bB11)
       Cbbbbbbbb
 
ISRT   Abbbbbbbb(AKEYbbbb=bA1)
       Bbbbbbbbb(BKEYbbbb=bB11)
       Cbbbbbbb(CKEYbbbb=bC111)
       Dbbbbbbbb
The following ISRT call would cancel parentage, because the F segment is not a direct dependent of B, the established parent: 
ISRT   Abbbbbbbb(AKEYbbb=bA1)
       Fbbbbbbbb

You can include one or more SSAs in a GNP call. The SSA can be qualified or unqualified. Without SSAs, a GNP call retrieves the next sequential dependent of the established parent. The advantage of using SSAs with GNP is that they allow you to point IMS to a specific dependent or dependent type of the established parent.

A GNP with an unqualified SSA sequentially retrieves the dependent segment occurrences of the segment type you have specified under the established parent.

A GNP with a qualified SSA describes to IMS the segment you want retrieved or the segment that is to become part of the hierarchic path to the segment you want retrieved. A qualified GNP describes a unique segment only if it is qualified on a unique key field and not a data field or a non-unique key field.

A GNP with multiple SSAs defines the hierarchic path to the segment you want. If you specify SSAs for segments at levels above the established parent level, those SSAs must be satisfied by the current position at that level. If they cannot be satisfied using the current position, a GE status code is returned and the existing position remains unchanged. The last SSA must be for a segment that is below the established parent level. If it is not, a GP status code is returned. Multiple unqualified SSAs establish the first occurrence of the specified segment type as part of the path you want. If some SSAs between the parent and the requested segment in a GNP call are missing, they are generated internally as unqualified SSAs. This means that IMS includes the first occurrence of the segment from the missing SSAs as part of the hierarchic path to the segment you have requested.

Usage: Get Hold Next in Parent (GHNP)

Retrieval for the GHNP call is the same as for the GHN call.