BuiltIn Functions › $RETURNCODE Function

$RETURNCODE Function

$RETURN‑CODE is a pseudo function that returns the highest return code caused by a system error or set by a CA Ideal program during an online run or batch session.

This function has the following format:

$RETURN‑CODE

or

$RC

When a system error is encountered, $RETURN‑CODE is set to a value that depends on the severity level. Each system message has a message level with an associated return code. The program can also explicitly set the return code to any value. For commands other than RUN (which can set any value for $RC), the following table shows how $RETURN‑CODE values are associated with warning and error messages.

$RETURN‑CODE is set to the returned value only if the current value of the function is lower than the returned value.

In a PDL procedure, you can use $RETURN‑CODE as a sending field in any context where numeric fields can be used (for example, in numeric expressions and conditional expressions). When used in a SET statement, $RETURN‑CODE can be a sending or a receiving field. The SET statement unconditionally changes the value of $RETURN‑ CODE. In a MOVE statement, $RETURN‑CODE can only be a sending field or part of a sending numeric expression.

Execution of a default error procedure sets the value of $RETURN‑CODE to 12 when the value is less than 12. Otherwise, the value remains unchanged. A user defined error procedure is not called on a system error, so it changes the value of $RETURN‑CODE only if explicitly coded to do so.

At the end of a run, the message 'RUN completed, RC=nn' appears. The RC=nn is the value of the return code at the end of the run.

In a batch jobstream, you can use $RETURN‑CODE with CA Ideal's IF, ELSE, and ENDIF commands to conditionally execute other CA Ideal commands. You can also use return codes to ensure that programs in a batch environment do not run unless the previous program executes successfully. The return code value is passed to the operating system at the end of a CA Ideal batch session. For more information, see the Messages and Codes Guide.

Return code values set before a run by another RUN or a CA Ideal command are retained at the start of a new RUN when SET RUN $RC KEEP is in effect. SET RUN $RC ZERO resets the return code to zero at the start of a run.

Note: The LIST ERROR statement automatically displays the value of $RETURN‑CODE.

Example

In the following example, the $RETURN‑CODE is set to different codes, depending on which WHEN statement qualifies. When the $ERROR‑CLASS is DVW, the $RETURN‑CODE is set to 1660 to indicate a DVW error. The LIST ERROR codes, LIST ERROR, and QUIT RUN statements are performed.

When the ERROR‑CLASS is NUM, the $RETURN‑CODE is set to 8. The PROCESS NEXT MAIN‑LOOP statement returns the control to the main loop. The $RETURN‑CODE prints as a warning at the end of the run unless higher $RETURN‑CODEs are incurred.

When the $ERROR‑CLASS is any other value, the $RETURN‑CODE is set to 12. This indicates that an unexpected error was found and the procedure does a LIST ERROR and QUIT RUN.

<<ERROR>> PROCEDURE
    SELECT $ERROR‑CLASS
    WHEN 'DVW'
        SET $RETURN‑CODE = 1660:Use a high number which
                               :you might choose
        LIST $ERROR‑DVW‑DBID   :to indicate a dvw error
        LIST $ERROR‑DVW‑STATUS
        LIST $ERROR‑DVW‑INTERNAL‑STATUS
    WHEN 'NUM'
        SET $RETURN‑CODE = 8
        PROCESS NEXT MAIN‑LOOP
     WHEN OTHER
        SET $RETURN‑CODE = 12
    ENDSEL
    LIST ERROR
    QUIT RUN
   ENDPROC