HP OpenVMS Systems Documentation

HP COBOL
User Manual

In the following example, LIB$STAT_TIMER returns a condition value called RET-STATUS. To call this system routine, use the FORMAT of the function call described in the OpenVMS documentation on system services or Run-Time Library routines. In this case, the format is as follows:

01 ARG-CODE   PIC S9(9) COMP.
01 ARG-VALUE  PIC S9(9) COMP.
01 RET-STATUS PIC S9(9) COMP.
         .
         .
         .
    CALL "LIB$STAT_TIMER"
          USING BY REFERENCE ARG-CODE, ARG-VALUE
          GIVING RET-STATUS.

As stated earlier, this example does not pass a value for the optional handle-address argument.

The FORMAT will describe optional arguments in one of two ways:

   [,optional-argument]

or

   ,[optional-argument]

If the comma appears outside of the brackets, you must pass a zero by value or use the OMITTED phrase to indicate the place of the omitted argument.

If the comma appears inside the brackets, you can omit the argument as long as it is the last argument in the list.

For example, look at the optional arguments of a hypothetical routine, LIB$EXAMPLE_ROUTINE:

LIB$EXAMPLE_ROUTINE arg1 [,arg2] [,arg3] [,arg4]

You can omit the optional arguments without using a placeholder:

CALL "LIB$EXAMPLE_ROUTINE"
      USING ARG1
      GIVING RET-STATUS.

However, if you omit an optional argument in the middle of the argument list, you must insert a placeholder:

CALL "LIB$EXAMPLE_ROUTINE"
      USING ARG1, OMITTED, ARG3
      GIVING RET-STATUS.

In general, Run-Time Library routines use the [,optional-argument] format, while system services use the ,[optional-argument] format.

In passing arguments to the procedure, you must define the passing mechanism required if it is not the default. The default passing mechanism for all COBOL data types is BY REFERENCE.

The passing mechanism required for a system routine argument is indicated in the argument description. The passing mechanisms allowed in system routines are those listed in the HP OpenVMS Calling Standard.

If the passing mechanism expected by the routine or service differs from the default mechanism in COBOL, you must override the default. To force an argument to be passed by a specific mechanism, refer to the following list:

• If the argument is described as "the address of," use BY REFERENCE, which is the default.
• If the argument is described as "the value of," use BY VALUE.
• If the argument is described as "address of descriptor," use BY DESCRIPTOR.

Even when you use the default passing mechanism, you can include the passing mechanism that is used. For example, to call LIB$STAT_TIMER, you can use either of the following definitions:

CALL "LIB$STAT_TIMER"
      USING ARG-CODE, ARG-VALUE
      GIVING RET-STATUS.

CALL "LIB$STAT_TIMER"
      USING BY REFERENCE ARG-CODE, ARG-VALUE
      GIVING RET-STATUS.

If the routine or service you are calling does not return a function value or condition value, you can call the system routine as a procedure. The same rules apply to optional arguments; you must follow the calling sequence presented in the FORMAT section of the OpenVMS documentation on system services or Run-Time Library routines.

One system routine that does not return a condition value or function value is the Run-Time Library routine LIB$SIGNAL. LIB$SIGNAL should always be called as a procedure, as shown in the following example:

01 ARG-VALUE PIC S9(5) COMP VALUE 90.
    .
    .
    .
    CALL "LIB$SIGNAL" USING BY VALUE ARG-VALUE.

Many system routines return a condition value that indicates success or failure; this value can be either returned or signaled. In general, system routines return a condition value with the following exceptions:

• The system routine returns a function value.
• The CONDITION VALUES RETURNED is None.
• There is no CONDITION VALUES RETURNED description, but rather a CONDITION VALUES SIGNALED description. (Success conditions are not signaled.)
• The call to the routine was made as a procedure call.

If any of these conditions apply, there is no condition value to check.

If there is a condition value, you must check this value to make sure that it indicates successful completion. All success condition values are listed in the CONDITION VALUES RETURNED description.

Condition values indicating success always appear first in the list of condition values for a particular routine, and success codes always have odd values. A success code common to many system routines is the condition value SS$_NORMAL, which indicates that the routine completed normally and successfully. You can reference the condition values symbolically in your COBOL program by specifying them in the EXTERNAL phrase of the VALUE IS clause. Symbolic names specified in VALUE IS EXTERNAL become link-time constants; that is, the evaluation of the symbolic name is deferred until link time because it is known only at link time.

For example:

01 SS$_NORMAL PIC S9(5) COMP VALUE EXTERNAL SS$_NORMAL
     .
     .
     .
     CALL "LIB$STAT_TIMER" USING ARG-CODE, ARG-VALUE GIVING RET-STATUS.
     IF RET-STATUS NOT EQUAL SS$_NORMAL...

Because all success codes have odd values, you can check a return status for any success code. For example, you can cause execution to continue only if a success code is returned by including the following statement in your program:

IF RET-STATUS IS SUCCESS ...

Sometimes several success condition values are possible. You may only want to continue execution on specific success codes.

For example, the $SETEF system service returns one of two success values: SS$_WASSET or SS$_WASCLR. If you want to continue only when the success code SS$_WASSET is returned, you can check for this condition value as follows and branch accordingly:

IF RET-STATUS EQUAL SS$_WASSET ...

or

EVALUATE RET-STATUS
     WHEN SS$_WASSET ...

If the condition value returned is not a success condition, then the routine did not complete normally, and the information it should have returned may be missing, incomplete, or incorrect.

You can also check for specific error conditions as follows:

WORKING-STORAGE SECTION.
01 USER-LINE     PIC X(30).
01 PROMPT-STR    PIC X(16) VALUE IS "Type Your Name".
01 OUT-LEN       PIC S9(4) USAGE IS COMP.
01 COND-VALUE    PIC S9(9) USAGE IS COMP.
88 LIB$_INPSTRTRU VALUE IS EXTERNAL LIB$_INPSTRTRU.
                     .
                     .
                     .
PROCEDURE DIVISION.
P0.
    CALL "LIB$GET_INPUT" USING BY DESCRIPTOR USER-LINE PROMPT-STR
                               BY REFERENCE OUT-LEN
                               GIVING COND-VALUE.
    EVALUATE TRUE
        WHEN LIB$_INPSTRTRU
             DISPLAY "User name too long"
        WHEN COND-VALUE IS FAILURE
             DISPLAY "More serious error".
                    .
                    .
                    .