CA Ramis setting return code when exiting

Products

• Ramis Reporter

Issue/Introduction

Are there times you would like to see a return code other than the one set by CA Ramis?
By using the positional parameter for return code on the FIN command, it is possible to set a return code at the completion of a CA Ramis session or job step.

Environment

Release:      7.4

CA Ramis
CA Ramis Reporter

Resolution

Since a Ramis job step or session may contain many activities, you may wish to set the return code based on your own criteria.

The nnn parameter of the FINish command allows you to do just that.

In its simplest form, the command FINish ends the Ramis session or job step. By supplying a numeric value from 0 - 999, the application ends and Ramis passes the parameter value nnn to the host operating system as the standard return code for the step or session.

Why would anyone want to intervene and override the return code being set internally? Perhaps part of the application runs a TABLE request or a RELATE request which is retrieving records. If the request contains selection criteria, and no records meet the criteria, the result will contain 0 records and the resulting return code will be 0, unless there were other errors. However, if this request is followed by a job step which is dependent on the records selected in the preceding step, you may choose to have the application set a non-zero return code to prevent subsequent steps from executing.

Let's say the 1st step of a Ramis z/OS batch job contains a TABLE request that will generate a SAVE file to be used in batch step 2.
This example uses the SALES file from the sample files distributed with the Ramis product.
Looking at the following request, no records will be selected for the SAVE file since the YEAR field in the SALES file only contains data for 1995 and 1996.

TABLE
FILE SALES
PRINT CUSTNUM AND UNITS AND LISTPRICE AND SAVE
BY INDUS-CODE
WHERE YEAR GT 1996
END

Although no records will be selected, and the SAVE file will not be populated, the return code will be set to 0, allowing subsequent job steps to be processed.

By including the statement:

FIN 9

after the END statement, Ramis will set the return code to 9, providing a method for allowing subsequent steps or sessions to be bypassed.

To bypass the next batch job step, code the parameter COND=(8,LT) on the EXEC statement for batch step 2.
This will force step 2 to be flushed from the processing stream.

This technique can also be used in TSO by executing a CLIST or REXX procedure which checks the return code between invocations of Ramis.
In the CMS environment an EXEC or REXX procedure may be used to test the return code between successive invocations of Ramis.

Additional Information

In actual practice, you would not want to set the return code to 9 if records were retrieved and the SAVE file had been populated. Ramis provides many options to check processing results. The System Building Executive (SBX) component provides many variables useful in checking application results. Among them are %RECORDS, %TRANS, %INPUT, %CHANGES, and %REJECTS. The FIN nnn statement may be included as DEFERRED code in an SBX procedure. Using an SBX procedure to verify the result of an application may be helpful in bypassing unnecessary code, and determining when to set a return code with the FINish command.

The CA Ramis Version 7.4 set of documentation can be found at CA Ramis Bookshelves and PDFs.
For more information on using the Ramis FIN command, refer to the publication Utilities section 2.24 FINISH.
For more information on Ramis variables can be found in the publication System Building Executive (SBX).