GUR call

The Get Unique Record (GUR) call is used to retrieve entire records from the IMS catalog database. The records are returned as XML instance documents.

Format

Parameters

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-aligned 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. This four-byte input parameter specifies the size of the I/O area in bytes that will hold the records retrieved from the IMS catalog database.

AIBRTKN

AIB return token. This 8-byte field contains a token value when a GUR call returns more data than can fit in the I/O area. You can retrieve the rest of the data by setting this field to the returned value and providing the same resource name and type in the SSA when you issue a subsequent GUR call. IMS returns the next block of data, and you can continue to issue sequential calls by continuing to set the AIBRTKN field until all of the data is retrieved.

A GUR call for a new resource is done if the resource name and type in the SSA do not match the resource name and type for the AIBRTKN.

If an invalid or unrecognized token value is specified, the call fails.

AIBOAUSE

Specifies the total length of the XML instance document returned by the GUR call. This value is set by IMS after a successful GUR call. The value is given in bytes.

When the value of the AIBOAUSE field is less than the value of the AIBOALEN field, the application program can retrieve the entire XML document from the I/O area.

When the value of the AIBOAUSE field is greater than the value of the AIBOALEN field, the application program must make additional GUR calls with the AIBRTKN value set to the returned token value of the first call to retrieve the entire XML instance document.

The size of the last GUR call in a linked series might not match the size of the remaining data. For example, a GUR call that returns 9000 bytes of data for a request with AIBOALEN=4096 requires three linked GUR calls to retrieve all of the data. The third call returns only 808 bytes of data in the I/O area.

The AIBOAUSE value is returned for all GUR calls in a linked series, and always reflects the total size of the XML instance document.

AIBRETRN

Return code.

AIBREASN

Reason code.

i/o area

Specifies the I/O area where IMS places the XML instance document returned by the call. This parameter is an output parameter. When you issue the calls successfully, IMS returns the requested record to this area. The XML instance document that this area contains is always left-aligned. The I/O area parameter points to the first byte of this area.

header ssa

Specifies the name of the HEADER segment to search for. This parameter is required.

resource ssa

Specifies the ACB generation timestamp of the DBD or PSB segment to search for. This parameter is optional and is valid only if a HEADER SSA is specified.

If the user ACB generation timestamp is not specified,IMS uses the time stamp for the active resource, either a DBD or PSB, in the ACBLIB to find the corresponding resource in the catalog.

Usage

The Get Unique Record (GUR) call is a request for a complete record from the IMS catalog.

Catalog records are returned as XML instance documents, and can be larger than the available I/O area. IMS stores a complete XML instance document for a successful GUR call in an internal retrieval cache and can return it to an application program in pieces that are each the size of the available I/O area. Each subsequent GUR call to retrieve another piece of the XML instance document must use the token value set by IMS in the AIBRTKN field after the original call.

The XML schemas for the documents returned as responses to this call are included in the IMS.ADFSSMPL data set:

DFS3XDBD.xsd (for DBD records)
DFS3XPSB.xsd (for PSB records)

You can use z/OS® XML System Services to parse the response document. The z/OS XML parser is started as a callable service. The services stubs are shipped in CSSLIB.

A GUR call SSA must start with the HEADER segment.

A GUR call that is issued with an unqualified SSA attempts to satisfy the request by starting at the beginning of the target database. If the SSA at the root level is the only SSA, IMS retrieves the first segment in the database. A GUR call with a qualified SSA can retrieve the segment described in the SSA, regardless of the location of the segment relative to the current position of the cursor. The two levels of SSA qualification that can be used with a GUR call correspond to the levels of the DBD or PSB stored in the catalog.

The IMS catalog has a structure that uses a header segment as the root for each record. Each header segment instance has either a PSB or DBD child segment instance. This structure is important to understand because an unqualified GUR call (such as the following example) might not return the expected record.

GUR 	HEADER
		PSB

This call locates the first record, which is always a DBD record because DBD precedes PSB in alphanumeric order. Because the first record does not contain a PSB segment instance, the call does not return the first PSB record as expected. You must qualify the wanted record type at the level of the segment header:

GUR HEADER (TYPE = PSB     )
    PSB

A GUR call that is issued without a qualification at the PSB or DBD level retrieves the record for the member that is currently active in the ACB library. If no catalog record is found that corresponds to the active member, the call fails with return code X’108’ and reason code X’338’ This error occurs even if there are one or more catalog records for inactive members of the ACB library or records for members that do not currently exist in the ACB library. To retrieve those catalog records, you must determine the ACB generation timestamp for the member corresponding to the wanted catalog record and include it as a PSB or DBD-level qualification.

For example, the following GUR call fails if there is no active ACB library member for BMP255:

GUR   HEADER  (RHDRSEQ ==PSB     BMP255  )

To retrieve the record for an inactive or removed ACB library member, add an SSA qualification for the correct ACB generation timestamp:

GUR   HEADER  (RHDRSEQ ==PSB     BMP255  )  
      PSB     (TSVERS  ==xxxxxxxxxxxxx)

Restriction: A GUR call that is not qualified with a timestamp always fails in environments without an active ACB library, such as batch regions.

IMS returns the active or last instance of the record in catalog or a return code if the following conditions are met:

You specify the resource ssa with no ACB generation timestamp of the record of your choice.
IMS is unable to find the timestamp for the active record in the ACBLIB or in the catalog header.
Depending on whether the pending timestamp in the catalog header is zero or not:
- If the pending timestamp is zero, which indicates that the record is activated and copied from the catalog staging data to the directory data sets, IMS returns the last instance of the record.
- If the pending timestamp is non-zero, which indicates that the record is still in the catalog staging data set and is yet to be activated by the IMPORT DEFN SOURCE(CATALOG) command so that it is placed in the directory data sets, IMS returns the AIB return code X’108’ and reason code X’338’, which means that the active record was not found in the catalog.

Special AIB return and reason codes

The following combinations of AIB return and reason codes have specific meanings for the GUR call:

AIBRETRN = X’000’ (CALLCOMP)
AIBREASN = X’000’ (CALLOK): The GUR call completed successfully.
AIBRETRN = X’100’ (CALLOKWE)
AIBREASN = X’00C’ (PARTDATA): The XML response document did not fit in the I/O area. A GUR continuation token is set in the AIBRTKN field.
AIBRETRN = X’004’ (CALLOKWI)
AIBREASN = X’004’ (LASTSEG): This GUR call contains the last portion of response data for a continued GUR call that was previously issued. The GUR continuation token for the call is now invalid.
AIBRETRN = X’104’ (APPLERR)
AIBREASN = X’224’ (INVAOITK): The GUR continuation token passed with the call is invalid.
AIBRETRN = X’104’ (APPLERR)
AIBREASN = X’248’ (INVPCBN): The correct PCB name specified to access the IMS™ catalog was not found.
AIBRETRN = X’104’ (APPLERR)
AIBREASN = X’404’ (INVFUNC): The function code specified on the DL/I call was unknown or invalid.
AIBRETRN = X’108’ (SYSERROR)
AIBREASN = X’338’ (NOCATACB): The requested catalog member is not in the catalog. IMS searched for a member with the timestamp of the active ACBLIB member, but no member with a matching timestamp was found.
AIBRETRN = X’108’ (SYSERROR)
AIBREASN = X’340’ (NOGURDLI): The GUR call did not find the specified IMS catalog resource in the batch region.
AIBRETRN = X’108’ (SYSERROR)
AIBREASN = X’342’ (NOGURXML): The GUR call was unable to build a valid XML response document.
AIBRETRN = X’108’ (SYSERROR)
AIBREASN = X’344’ (NOGURNFD): The requested catalog member is not in the catalog.

Example

The following GUR example retrieves the catalog record for the DBD named DX41SK01

GUR HEADER (RHDRSEQ==DBD DX41SK01)

Restrictions

The GUR call is valid only for retrieving records from the IMS catalog database. If a user PSB is used, the IMS catalog database must be available, and CATPSBATTACH in the CATALOG section of DFSDFxxx must be set to YES.

The GUR call is only supported by the AIB interface.

SSA command codes are not allowed.