GU/GHU call

Format

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. The segment data that this area contains is always left-justified. The I/O area points to the first byte of this area.

When you use the GU 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 you supply in the call point to data areas in your program where you have defined the SSAs for the call. You can use up to 15 SSAs for the parameter. This parameter is optional for the GU call.

rsa

Specifies the area in your program that contains the record search argument. This required input parameter is only used for GSAM. See the topic "GSAM Data Areas" in IMS Version 15 Application Programming for more information on RSAs.

Usage: Get Unique (GU)

GU is a request for a segment, as described by the SSAs you supply. You use it when you want a specific segment. You can also use it to establish your position in the database.

The GU call is the only call that can establish position backward in the database. (The GN and GNP calls, when used with the F command code, can back up in the database, but with limitations. Unlike GN and GNP, a GU call does not move forward in the database automatically.

If you issue the same GU call repeatedly, IMS retrieves the same segment each time you issue the call. If you want to retrieve only particular segments, use fully qualified GUs for these segments instead of GNs. If you want to retrieve a specific segment occurrence or obtain a specific position within the database, use GU.

If you want to retrieve a specific segment or to set your position in the database to a specific place, you generally use qualified GU calls. A GU call can have the same number of SSAs as the hierarchy has levels, as defined by the DB PCB. If the segment you want is on the fourth level of the hierarchy, you can use four SSAs to retrieve the segment. (No reason would ever exist to use more SSAs than levels in the hierarchy. If your hierarchy has only three levels, you would never need to locate a segment lower than the third level.) The following is additional information for using the GU call with SSAs:

• A GU call with an unqualified SSA at the root level attempts to satisfy the call by starting at the beginning of the database. If the SSA at the root level is the only SSA, IMS retrieves the first segment in the database.
• A GU call with a qualified SSA can retrieve the segment described in the SSA, regardless of that segment's location relative to current position.
• When you issue a GU that mixes qualified and unqualified SSAs at each level, IMS retrieves the first occurrence of the segment type that satisfies the call.
• If you leave out an SSA for one of the levels in a GU call that has multiple SSAs, IMS assumes an SSA for that level. The SSA that IMS assumes depends on current position:
  • If IMS has a position established at the missing level, the SSA that IMS uses is derived from that position, as reflected in the DB PCB.
  • If IMS does not have a position established at the missing level, IMS assumes an unqualified SSA for that level.
  • If IMS moves forward from a position established at a higher level, IMS assumes an unqualified SSA for that level.
  • If the SSA for the root level is missing, and IMS has position established on a root, IMS does not move from that root when trying to satisfy the call.

Usage: Get Hold Unique (GHU)

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. Once 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 without a hold is that the hold calls can be followed by a REPL or DLET call.

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 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.

Restrictions

You can use GU to retrieve the record with the RSA you provide with a GSAM database, but GHU is not valid for GSAM.