Things to Know about Datacom ADROUT Recovery

Products

Datacom Ideal Datacom/AD IPC Datacom/DB

Issue/Introduction

The automatic deletion of outputs from the ADROUT library after their retention period has expired is known as "PSS Recovery". PSS Recovery also handles the deletion of incomplete outputs that were created due to a program failure.

When NETT executes after being initiated from the CICS PLT startup program (SCPSPLTI), all outputs older than the value specified in the Maximum Retention Period field of the PSS Options Block are deleted. (To display the maximum retention period, issue SET OUTPUT SITE OPTIONS from the Ideal command line.)

Note: SCPSPLTI must be specified in the CICS startup PLT for PSS Recovery to automatically occur.

The normal default settings for PSS recovery will work fine in a single Ideal CICS environment. However, if your site has multiple Ideal CICS regions, each with its own ADRPNL and ADROUT library, there are a few site options that you must specify to ensure that the VLS output library, ADROUT, will work properly. If these are not specified correctly, "PSS Recovery" may not work as intended.

Cause

PSS Recovery in a Multiple CICS Environment

When "PSS Recovery" is initiated, an exclusive enqueue is issued against the ADROUT library. The first three characters of the enqueue name are built from the value specified in the System Name field of the PSS Options Block. After all eligible outputs are deleted, "PSS Recovery" is terminated and the exclusive enqueue is changed to a shared enqueue.

If a second Ideal CICS region which accesses a different ADROUT data set but shares the same PSS Options settings is now started, PSS recovery will not work as intended. When NETT is initiated from the CICS PLT startup program SCPSPLTI in the second CICS, "PSS Recovery" once again uses the three characters from the System Name field in the PSS Option Block and tries to issue the same exclusive enqueue.

Unfortunately, the exclusive enqueue will now fail since the first Ideal CICS region is still holding a shared enqueue against the ADROUT library even though it is hooked to a different data set. Since "PSS Recovery" must obtain a successful exclusive enqueue to delete any expired or incomplete output listings, no outputs are deleted.

The same type of enqueue problem can be encountered if users on separate CICS regions try to access an output member with the same name. Since the enqueue prefix is the same, the enqueue generated for the member name in both CICS regions will be the same.

Resolution

To avoid these situations, the System Name and Prefix Name must be unique for each unique ADROUT data set. The following procedure changes the System Name and Prefix Name values. Keep in mind that each CICS region has its own ADRPNL and ADROUT data sets.

(Note: ADRPNL and ADROUT data sets should always be considered a set since the options for ADROUT are stored in ADRPNL member PSS#OPTIONS.)

Print all outputs from the ADROUT library that you want to keep. What you are about to do will delete all outputs from the library, not just those with expired retention periods.
Perform one of the following:
1. Create an IDEAL MEMBER that contains all the DEFINE OUTPUT DESTINATION commands necessary to redefine all desired output destinations, since reformatting ADROUT deletes all your existing output destinations.
2. Run a VLSUTIL SELBKUP command to back up your PSS Destination Table that resides in ADROUT.

From Ideal, enter the command SET OUTPUT SITE OPTIONS. Change the System Name field to a three-character value which is different from your other CICS regions and change the Prefix Name to a four-character value which is also different from your other CICS regions.

Shut down the Ideal CICS region.

Run VLSUTIL against ADROUT with the control statement:

FORMAT BLKSIZE=4000,NAMELEN=11

Run the PSS batch utility program SCPSUTIL with the following control cards:
INIT
LIBRARY

Based on the method chosen in Step 2, perform one of the following:

1. Restart the Ideal CICS region. EXECUTE the IDEAL MEMBER containing the DEFINE OUTPUT DESTINATION commands created in Step 2 to redefine your printer destinations.
2. Run a VLSUTIL SELREST command to restore your PSS destination table from the backup created in Step 2 into your newly formatted ADROUT. Once the table is successfully restored, run a VLSUTIL RENAME command to modify the table name to match your new System Name value. Restart the Ideal CICS region.

Example:

The default PSS destination table name is PSS@PSSDST@. If you changed your System Name to PS1, you must rename your PSS destination table to PS1@PSSDST@.

After these steps are completed, the enqueues should no longer conflict, which will keep each ADROUT library free from expired output listings and erroneous enqueues on individual output members.

Additional Information

HELPFUL HINT:

To display the date and time that PSS Recovery last ran successfully, execute the following command from the Ideal command line:

@I$UTIL OUT STATUS

**Refer to our documentation under Datacom Tools: section "Maintaining the IPC System" for further details on VLSUTIL and SCPSUTIL.