Guidelines for using AREA and FAILSAFE statements (nonshared-queues environment)

Reasons why queue space message buffers become exhausted

The major reasons that the IMS queue space message buffers can become exhausted are for any combination of the following reasons:

• Insufficient Dependent Regions to process all inputted transactions from an input device or from another transaction (insert to ALTPCB)
• Customer Program stopped, therefore building up the queue count for that transaction
• Looping IMS transaction sending output back to the input device, or to one or more other destinations
• Looping IMS intelligent input device looping on sending in 1 to n message segments
• Transactions that produce a larger volume of output data than the destination (such as another transaction, output to the inputting device, or an alternate output device) can process
• Input devices that produce a larger volume of data than the destination (such as a non-response transaction) can process

There are also other factors, in combination with these listed reasons, that can require you to make additional considerations.

• If the transaction types are all response mode transactions in your environment, then the definition of the AREA and FAILSAFE statements are much easier to define.
• If the transaction types also include non-response mode transactions, and the larger the volume of non-response transactions in your environment, then the definition of the AREA and FAILSAFE statements are more difficult to define. You might want to include more of these statements in your definition.

Setting ACTION and TOTAL values

AREA and FAILSAFE statements provide you with notification information about the input devices and transactions when the inserting of messages to the IMS message buffer queue space has met the definitions defined in these statements.

When selecting the action to be taken on the FAILSAFE statement that defines the largest TOTAL=percentage, you must be careful to choose the correct ACTION=value. It is also very important to set the correct FAILSAFE and AREA statement TOTAL=percentage value.

The setting of both the TOTAL= and ACTION= values need to take into account the types of input devices and transactions. If your system is largely made up of response mode transactions rather than non-response transactions, then the setting of the TOTAL= and ACTION= is less restrictive.

If however, you have a large volume of non-response transactions from the OTMA network, then you will need to consider setting a lower TOTAL= value with the ACTION= set to STOP or ABEND.

If you have a run away OTMA client that is looping and sending in non-response transactions, and you specify ACTION=WTO or ACTION=WAIT, the problem will continue.

If you have a stopped program, and you specify ACTION=WTO or ACTION=WAIT, the problem will continue as well.

Considerations when defining AREA and FAILSAFE statements

Consider the following items when defining AREA and FAILSAFE statements:

• Response mode transaction input can require from 1 to n IMS queue space message buffers

  These buffers will remain allocated if:

  • ACTION=WTO is specified, or
  • ACTION=WAIT is specified

  However, for (ACTION=WAIT) an IMS queue space message buffer will be allocated to send out an IMS message to the MVS console to identify that a transaction on input device has been added to the QCF WAIT Queue.

  Once the IMS message has been sent, the IMS queue space message buffer for the IMS wait notification message will be deallocated.

  In both cases (ACTION=WTO and ACTION=WAIT) for the response mode transaction the IMS message queue space message buffer will remain allocated for the input message. IMS queue space message buffer count will increase.

• Response mode transaction input can require from 1 to n IMS queue space message buffers

  These buffers will be deallocated if:

  • ACTION=STOP is specified, or
  • ACTION=ABEND is specified

  However, for both ACTION=STOP and ACTION=ABEND, an IMS queue space message buffer will be allocated to send out an IMS message to notify the input device that the input message was rejected (ACTION=STOP), or to send out an IMS message to notify the input device that application has terminated abnormally (ACTION=ABEND).

  Once the IMS message has been sent to the input device, the IMS queue space message buffer for the IMS error message will be deallocated.

  In both response mode transaction cases (ACTION=STOP and ACTION=ABEND), the input message in the IMS message queue space message buffer will be deallocated in addition to the IMS error messages. The IMS message queue space message buffer count will increase for the input message, and IMS error message will decrease by the same amount for these actions.

• Non-response mode transaction input can require from 1 to n IMS queue space message buffers

  These buffers will remain allocated if:

  • ACTION=WTO is specified, or
  • ACTION=WAIT is specified

  However, for ACTION=WAIT, an IMS queue space message buffer will be allocated to send out an IMS message to the MVS console to identify that a transaction on input device has been added to the QCF WAIT Queue.

  Once the IMS message has been sent, the IMS queue space message buffer for the IMS wait notification message will be deallocated.

  In both non-response mode transaction cases (ACTION=WTO and ACTION=WAIT), the IMS message queue space message buffer will remain allocated for the input message. IMS queue space message buffer count will increase.

• Non-response mode transaction input can require from 1 to n IMS queue space message buffers

  These buffers will be deallocated if:

  • ACTION=STOP is specified, or
  • ACTION=ABEND is specified

  However, for both ACTION=STOP and ACTION=ABEND, an IMS queue space message buffer will be allocated to send out an IMS message to notify the input device that the input message was rejected (ACTION=STOP), or to send out an IMS message to notify the input device that application has terminated abnormally (ACTION=ABEND).

  The problem here is that if the input device is sending many non-response messages one after the other, the IMS message to notify the input device that the input was rejected (ACTION=STOP), or the IMS message to notify the input device that application has terminated abnormally (ACTION=ABEND), will not be read by the input device.

  This is because the message will remain in a send mode until it has completed sending in all of its non-response transactions. The IMS queue space message buffer for the IMS error message will remain allocated.

  In both non-response mode transaction cases (ACTION=STOP and ACTION=ABEND), the input message in the IMS message queue space message buffer will be deallocated. However the IMS error messages will not be deallocated until the input device goes to read mode.

  If the input device does not issue a read function to get any output (in this case the error messages), then the IMS message queue space message buffer count will increase for the input message and the IMS error message, and decrease only for the input message and not the error message.

Using OSTARTACTION=JTSTP

The OSTARTACTION=JTSTP option functions in the same manner as the STOP option. However, JTSTP does not default to the WTO action. When a queue has reached or exceeded the specified AREA Statement threshold, the JTSTP option causes either an A7 status code to be returned to the IMS application, or one of the following IMS DFS messages to be returned to the input device:

• VTAM® = DFS074 message
• APPC = DFS0777 message
• OTMA = NAK message
• BTAM = DFS074 message
• MSC = DFS1945 message

A PCB status code A7 message call indicates that the number of output segments inserted has exceeded the limit by one. Any further queue manager calls are prohibited to prevent message queue overflow.

As an example, the following AREA statement is specified:

AREA=(ID=AREA0001,
            PERCENT=(TOTAL=50,USED=40),
            TYPE=(ALL),
            CSTOPACTION=WTO,
            CSTARTACTION=STOP,
            OSTOPACTION=WTO,
            OSTARTACTION=JTSTP)    

This example assumes that each message uses a single buffer and that 200 messages triggers this AREA statement.

If a single transaction or terminal (source) loops in error, or places 200 messages on a single queue (destination), a CSTARTACTION=STOP setting causes all remaining message inserts made by that same transaction or terminal (source) during the same UOW to receive an A7 status code or one of the IMS DFS messages. During that single UOW, all message inserts starting with 201 and above are rejected and the queue will not increase in size.

If the queue remains at 200 messages and a second (or more) transaction or terminal (source) places a single message or multiple messages on the queue (destination), an OSTARTACTION=JTSTP setting causes the messages to be rejected. An A7 status code or one of the IMS DFS messages is sent.

When using the JTSTP option, it is important to understand that all attempted message inserts to this destination, once the AREA statement threshold has been reached, results in these messages being rejected, regardless of whether the message comes from an application or a terminal. A possible consequence might be that an application program must back out database updates and return a message to the input device stating that the input has been rejected.