PI68458: THERE IS NO INFORMATION ON THE SIZE OF A TOF BUFFER WHEN A TOF-BUFFER-FULL ERROR HAS OCCURRED

Obtain the fix for this APAR.

APAR status

• Closed as program error.

Error description

• A MERVA API program has written more and more data to an
  application defined field in a message's TOF. Then the TOF
  buffer became full. MERVA issued error message DSL883I with
  reason code 011 indicating that the TOF buffer is too small to
  incorporate the data. The size of the TOF buffer is not
  reported. So there is no idea how much the TOF buffer should be
  increased in order to successfully process this message.
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: All MERVA ESA users.                         *
  ****************************************************************
  * PROBLEM DESCRIPTION: Neither operators nor API programs know *
  *                      the size of a TOF buffer.               *
  ****************************************************************
  * RECOMMENDATION: This has been corrected. MERVA now makes the *
  *                 TOF buffer size transparent.                 *
  ****************************************************************
  A TOF buffer contains a MERVA message in the tokenized format
  (TOF). Neither operators nor API programs know the size of a
  TOF buffer. This makes it difficult to react appropriately when
  the TOF buffer size is growing over time. For example,
  to inhibit that the TOF buffer is going to become full.
  

Problem conclusion

• TOF buffer sizes can now be obtained on three ways:
  1. Command LENGTH
  2. Utility DSLBA42R
  3. Fields for an API program
  
  1. Command LENGTH
  The existing command LENGTH (abbreviated LEN) has been assigned
  a new parameter: * (asterisk).
  LENGTH * returns the size of the currently used TOF buffer and
  the size of the maximum possible TOF buffer.
  You can enter LENGTH * when a message has been displayed.
  
  2. Utility DSLBA42R
  This sample REXX utility prints a report on TOF buffer sizes.
  It
  - Inspects all messages in a queue and identifies the message
    which requires the largest TOF buffer.
  - Shows the size of the maximum possible TOF buffer based on
    the given customization in DSLPRM.
  - Explains if and how to increase the maximum TOF buffer size
    by changing the customization in DSLPRM.
  
  This is the JCL to run DSLBA42R.
  
  //....... JOB ............
  //REXXB EXEC PGM=DSLAREXX,PARM='DSLBA42R,inputq'
  //*
  //* .. MERVA ESA LOAD LIBRARY
  //STEPLIB DD DSN=loadlib,DISP=SHR
  //*
  //* .. ON THIS PDS: DSLBA42R
  //SYSEXEC DD DSN=samplib,DISP=SHR
  //*
  //* .. LISTING DATASET (VB136)
  //SYSTSPRT DD DSN=listds,DISP=OLD
  //
  
  Parameter inputq represents the name of the queue whose
  messages are to be inspected. This parameter is optional.
  If specified, MERVA must be active. The report prints
  - The initial TOF buffer size before any message is inspected.
  - The maximum TOF buffer size based on the given customization
    in DSLPRM from the STEPLIB concatenation.
  - The number of inspected messages.
  - The largest TOF buffer size (between initial and maximum TOF
    buffer size).
  - The QSN of the largest message using this buffer.
  - The length of this message in queue format
    (order of magnitude for message length in TOF buffer).
  
  If inputq is omitted, MERVA can be inactive.
  The report explains if and how to increase the maximum TOF
  buffer size using the DSLPRM from the STEPLIB concatenation.
  
  3. Fields for an API program
  There are three new fields:
  - DSLTBSZ         TOF buffer size
  - DSLTBMSZ        Maximum TOF buffer size
  - DSLQFMTL        Length of message in queue format
  
  The FLDG API call retrieves a 4-byte fullword binary value
  of each field. See "FLDG Get a MERVA Variable" in Chapter 9
  of the Application Programming Interface Guide
  how to code an FLDG call.
  
  You can obtain the value of DSLTBSZ before the first or
  after any API TOF service call (READ, WRIT, EMPT). It can
  vary as this is the size of the currently used TOF buffer.
  You can obtain the value of DSLTBMSZ at any time.
  It is constant throughout the program.
  
  You should obtain the value of DSLQFMTL after an API queue
  management retrieval call (GEKU, GET, GETC, GETK, GETN, GETU).
  
  In a program, you can compare the value of DSLTBSZ with the
  value of DSLTBMSZ. If the comparison indicates, according to
  the rules you defined, that the currently used TOF buffer has
  reached a critical size, the program can react on this.
  For example, it can stop processing and orderly terminate
  before the TOF buffer becomes full.
  
  Utility DSLBA42R uses these three fields.
  

Temporary fix

Comments

APAR Information

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

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

  UI41303

Modules/Macros

• DSLAPIFL DSLBA42R DSLCSD41 DSLEMLNG DSLEMSC  DSL1080  H0B0410J
  

Fix information

• Fixed component name

  MERVA ESA 4.1.0

• Fixed component ID

  5648B2900

Applicable component levels

• R410 PSY UI41303

     UP16/10/05 P F610

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.