PH12244: GUR CALL EXCEEDS OUTPUT AREA TRUNCATING OUTPUT. AIB RETURN/REASON CODE IS 108/338

Obtain the fix for this APAR.

APAR status

• Closed as program error.

Error description

• Catalog GUR call does not provide all the XML metadata output.
  Return/Reason code returned is
  108 - System error
  338 - Active resource are not found in the catalog.
  The output area is too small to hold the complete XML output.
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED:                                              *
  * All IMS V15 users of IMS DB DL/I GUR (Get Unique Record)     *
  * calls to retrieve the IMS catalog database records.          *
  ****************************************************************
  * PROBLEM DESCRIPTION:                                         *
  * Problem 1                                                    *
  * -----------                                                  *
  * A GUR call returns incomplete XML of a large IMS catalog     *
  * record.                                                      *
  *                                                              *
  * Problem 2                                                    *
  * -----------                                                  *
  * A GUR call on a record incorrectly returns XML of a          *
  * different record of the previous GUR call.                   *
  ****************************************************************
  * RECOMMENDATION:                                              *
  * INSTALL CORRECTIVE SERVICE FOR APAR/PTF                      *
  ****************************************************************
  Problem 1
  -----------
  The program that processes the GUR call builds a large XML
  output and runs into an internal buffer shortage that holds the
  XML.
  The program does not handle the storage problem and incorrectly
  stops processing.
  As the result, the GUR call requestor received an incomplete XML
  output.
  
  Problem 2
  -----------
  The program that processes a GUR call does not detect the new
  record being requested and incorrectly continue processing on
  the previous record .
  As the result, the GUR call requestor receives incorrect XML
  ouput of the previous GUR call.
  

Problem conclusion

• Problem 1 - Incomplete XML output
  -----------
  
  Change summary
  
  ODBM side
  Corrected the second GUR call decision making, upon the
  incomplete data return code and total XML size receipt from the
  first GUR call, make the second GUR call using the returned
  total XML size as the new larger user I/O area to retrieve all
  XML data.
  
  DB side
  Enhanced GUR processor with the dynamically obtained storage
  capability to hold any large resources retrieval from catalog
  for client request.
  
  CSLDBR00 PLX - ODBM Request Server
  -----------
  Reversed PI99502 changes. The user passed length of 5M in
  AIBOALEN on a GUR call to ask the GUR driver to get more
  storage, is no longer needed.
  The GUR driver no longer depends on the user passed I/O area
  size in AIBOALEN to allocate the driver?s own internal storage,
  the driver will instead dynamically obtain additional storage it
  needs when building the XML output.
  The user can use the returned total XML size in the output
  parameter AIBOAUSE and a blank AIB token to drive another new
  GUR call to retrieve the whole XML output.
  Updated the decision that drives another new GUR call using the
  returned total XML output as the I/O area, by detecting the
  partial data return code AIBRETRN = X'100' and reason code
  AIBREASN = X'00C'.
  
  DFS3GURP macro - Work area DSECT for GUR DLI processors
  -----------
  Defined new fields to be used between GUR requests processing:
  first buffer address, source buffer address, water mark and data
  size.
  Defined the GUR IO buffer header to hold the buffer meta data:
  buffer data size, next buffer pointer, catalog record name, type
  and timestamp.
  Added boundary spaces to fix AKEE compiler messages.
  
  DFS3GUR1 PLX - Catalog DB XML builder
  -----------
  If GUR IO area is full, return a new RC32 for specifically
  asking DFS3GUR0 to allocate more storage.
  In the DFSALL_XML procedure, saved pending flags in the new GUR1
  work area that indicate some XML blocks could be open then and
  need to close now
  in case of a storage error, the flags can be restored when the
  process resumes.
  In the mainline, if there is a storage error of RC32, restored
  the pending flag positions so that the process knows where it
  has left off and can resume properly.
  
  DFS3GUR0 PLX - Get unique catalog records driver
  -----------
  - Mainline - Catalog DB DLI GUR request processor
  Any places that free the internal work area, added code to free
  the multiple buffer list if any.
  In first call path, remove the special handling for continuation
  token -1 callers who want to be treated as a new GUR call and
  cache deletion.
  After the raw data to XML transformation, changed to check if
  the XML document resides in a single or multiple buffer.
  For the multiple buffers case, the new procedure CopyBufList
  will process for the first or continued GUR requests as
  appropriate.
  CopyBufList procedure needs to be passed as input the starting
  or first buffer address and size of the buffer list.
  
  - SSAparse procedure - Parse user-passed SSAs on DL/I GUR call
  Added a block comment that if user does not pass a optional
  timestamp on the SSA#3, then DoGUR routine will gets the
  timestamp from ACBLIB later, no code change.
  
  - Initblocks procedure - Work areas allocator
  Doubled the GUR1 work area size, the additional space will be
  used to hold the pending flags and counts during DFS3GUR1?s XML
  building process.
  After the GUR work area allocation including the first buffer
  space, saved the first and current buffer addresses of the
  buffer list for later use.
  Initialized buffer header fields, set the buffer pointer to
  point to the data portion of the buffer, updated the buffer size
  to exclude the header portion.
  
  - CopyToCache procedure - Copy XML from GUR IO buffer to cache
  Added buffer header size to the amount of the data to copy to
  cache.
  
  - Searchcache procedure - Search XML in cache
  When XML data is found, repositioned the buffer pointer and
  size, ensure the buffer pointer to point to data, not header,
  since now we have header in the GUR IO buffer.
  Also initially Initblocks procedure already set the buffer
  pointer to point to data, Searchcache procedure should preserve
  what Initblocks has set.
  Updated the amount of XML data to exclude the buffer header
  size.
  
  - Dataxform procedure - Catalog data to XML conversion
  During the process of reading fields of catalog records and
  transforming the data to XML along the way,
  changed to check if the first GUR I/O buffer space still has
  enough room to hold the XML output as we move along.
  If the first buffer is out of space, receiving a RC32 from
  DFS3GUR1, then create a new buffer and link to the prior buffer
  to form a list of buffers.
  Repeat the process until we have all enough buffer storage to
  hold all XML output.
  
  - Extrabuf procedure - Additional buffer allocator (new)
  New service routine creates a new buffer with two sections:
  header and data.
  The header portion has the meta data of the buffer: the buffer
  data size , the address of the next buffer on chain, the record
  key info: record name, type and timestamp.
  The data portion is the same size the first buffer and contains
  the XML output.
  The routine populates the header information and ties the newly
  created buffer to the buffer list.
  The routine also adjusts the buffer data pointer to ensure it
  points to the XML end tags, not in the middle starting and
  ending tags,
  this will make the XML output stay within the starting and
  ending tags boundary in each buffer.
  
  - CopyToIO procedure - Single buffer processor
  Added block comments to describe the logic flow of the
  procedure, no code change.
  
  - CopyBufList procedure - Multiple buffers processor (new)
  New service routine copies all buffers of a buffer list to
  user?s I/O area.
  The routine will use the caller passed starting buffer address
  of the buffer list as a starting point.
  It copies one buffer at a time and checks if the buffer fits the
  user?s I/O area.
  If the buffer exceeds the target area, the routine copies only
  the amount of data that fits and
  returns a partial data return code and token for users to get
  the rest of the data at next GUR request.
  The routine remembers where it left off and the remaining data
  size for next GUR request if any.
  If all buffers fit the target area, the routine will return good
  return code to user, releases work area storage, and updates
  statistics.
  
  - Freebufs procedure - Buffer list release (new)
  New service routine frees all buffers of a buffer list.
  
  - Gettotal procedure - XML document length calculator (new)
  New service routine supplies to total length of the XML instance
  document.
  
  Problem 2 - Incorrect XML output
  -----------
  
  DFS3GURP macro - Work area DSECT for GUR DLI processors
  -----------
  Define the GUR IO buffer header the catalog record name, type
  that is being requested to be used between GUR calls to
  distinguish a new GUR call from a continued one.
  
  DFS3GUR0 PLX - Get unique catalog records driver
  -----------
  In the new GUR call path: after parsing the user passed SSA,
  save the catalog record name, type, timestamp in the buffer
  header to remember the resource that is being processed.
  In the new GUR call path: after the DoGUR routine processing,
  save the catalog record timestamp in the buffer header, this
  covers the case where SSAparse routine was unable to get the
  timestamp.
  In the continued GUR call path: add additional GUR call
  validation by parsing the user passed SSA to retrieve the
  catalog record name,
  type and timestamp that being requested, then check to see if
  the requested resource is the same as the resource that was
  being processed in the previous GUR call:
  If the resource is the same, continue the processing to resume
  reading the records.
  If the resource is not the same, consider this GUR call is a new
  one and send it to the appropriate new call processing path.
  Before calling the SSA parser, ensure to turn off the high order
  bit of the PCB address to tell the parser that this SSA input is
  not the last SSA so as to pass the parser?s front validation and
  continue the function.
  

Temporary fix

Comments

APAR Information

• APAR is sysrouted FROM one or more of the following:

  PH03810

• APAR is sysrouted TO one or more of the following:

  UI64964

Modules/Macros

• DFS3GURP DFS3GUR1 DFS3GUR0 CSLDBR00
  

Fix information

• Fixed component name

  IMS V15

• Fixed component ID

  5635A0600

Applicable component levels

• R500 PSY UI64964

     UP19/08/29 P F908 ¢

Fix is available

• Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.