The status values from OpenVMS system service procedures are returned in general register R0. This return status value indicates the success or failure of the operation performed by the called procedure. In DEC C, passing a return status value in R0 is equivalent to a function returning int.
To obtain a return status value from any system procedure, declare the procedure as a function, as shown in the following example:
int SYS$SETEF();
After declaring a procedure in this way, you can invoke the procedure as a function and obtain a return status value. In DEC C, such a declaration is needed only as program documentation; SYS$SETEF can be called without explicit declaration and will be interpreted by default as a function returning int.
This section describes the following topics:
All OpenVMS system procedures and programs use a longword value to communicate return status information. When a DEC C main function executing under the control of the DCL interpreter executes a return statement to return control to the command level, the command interpreter uses the return status value to conditionally display a message on the current output device.
To provide a unique means of identifying every return condition in the system, bit fields within the value are defined as shown in Figure 3-5.
The following list describes the division of this bit field:
| Value | Meaning |
|---|---|
| 0 | Warning |
| 1 | Success |
| 2 | Error |
| 3 | Informational |
| 4 | Severe error, FATAL |
| 5-7 | Reserved |
Odd values indicate success (an informational condition is considered a successful status) and even values indicate failures (a warning is considered an unsuccessful status).
The following names are associated with these fields:
| control bits bit 28 (inhibit message) | CONTROLINHIB_MSG |
| facility number bit 27 (customer facility) | FAC_NOCUST_DEF |
| message number bit 15 (facility specific) | MSG_NOFAC_SP |
| severity bit 0 (success) | SEVERITYSUCCESS |
When testing return values in a DEC C program, either you can test only for successful completion of a procedure or you can test for specific return status values.
You can construct a structure or union that describes a return status value, but this method of manipulating return status values is not recommended. A status value is usually constructed or checked using bitwise operators. DEC C provides the <stsdef.h> header file, which contains preprocessor definitions to make this job easier. All the preprocessor symbols are named according to the following OpenVMS naming convention:
STS$type_name
| K | Represents a constant value |
| M | Represents a bit mask |
| S | Represents the bit size of a field |
| V | Defines the bit offset to the field |
For example, the following constants are defined in <stsdef.h> for the facility number field, FAC_NO, which spans bits 16 through 27:
/* Size of field in bits */
#define STS$S_FAC_NO 12
/* Bit offset to the *
* beginning of the field */
#define STS$V_FAC_NO 16
/* Bit mask of the field */
#define STS$M_FAC_NO 0xFFF0000
Figure 3-6 shows how the status value is represented internally.
Use the following expression to extract the facility number from a particular status value contained in the variable named status:
(status & STS$M_FAC_NO) >> STS$V_FAC_NO
In the previous example, the parentheses are required for the expression to be evaluated properly; the relative precedence of the bitwise AND operator (&) is lower than the precedence of the binary shift operator (>>).
To test a return status value for success or failure, you need only test the success bit. A value of true in this bit indicates that the return value is a successful value.
Example 3-21 shows a program that checks the success bit.
/* This program shows how to test the success bit. */
#include <stdio.h>
#include <descrip.h>
#include <stsdef.h>
#include <starlet.h>
#include <stdlib.h>
int main(void)
{
int status;
$DESCRIPTOR(name, "student");
status = sys$setprn(&name);
if (status & STS$M_SUCCESS)
/* Success code */
fprintf(stderr, "Successful completion");
else
/* Failure code */
fprintf(stderr, "Failed to set process name.\n");
exit(status);
}
The failure code in Example 3-21 causes the printing of a program-specific message indicating the condition that caused the program to terminate. The error status is passed to the DCL by the exit function, which then interprets the status value.
Each numeric return status value defined by the system has a symbolic name associated with it. The names of these values are defined as system global symbols, and you can access their values by referring to their symbolic names.
The global symbol names for OpenVMS return status values have the following format:
facility$_code
Table 3-14 shows some examples of facility codes used in global symbol names.
| Facility | Description |
|---|---|
| SS | System services; these status codes are listed in the OpenVMS System Services Reference Manual. |
| RMS | File system procedures; these status codes are listed in the OpenVMS Record Management Services Reference Manual. |
| SOR | SORT procedures; these status codes are listed in the VMS Sort/Merge Utility Manual. |
The definitions of the global symbol names for the facilities listed are located in the default DEC C object module libraries, so they are automatically located when you link a DEC C program that references them.
When you write a DEC C program that calls system procedures and you want to test for specific return status values using the symbol names, you must perform the following tasks:
globalvalue int SOR$_OPENIN;
Example 3-22 shows a program that checks for specific return status values defined in the <ssdef.h> header file.
/* This program checks for specific return status values. */
#include <ssdef.h>
#include <stdio.h>
#include <descrip.h>
$DESCRIPTOR(message,"\07**Lunch_time**\07");
int main(void)
{
int status = SYS$BRDCST(&message,0);
if (status != SS$_NORMAL)
{
if (status == SS$_NOPRIV)
fprintf(stderr, "Can't broadcast; requires OPER \
privilege.");
else
fprintf(stderr, "Can't broadcast; some fatal \
error.");
exit(status);
}
}