HP OpenVMS Calling Standard

Contents

Index

The following formulas specify the signed effective bit offset, EB, of an array element:

The signed effective bit offset, EB, of A(I₁):

EB = V₀ + S₁*I₁ = POS + S₁*[I₁ - L₁]

The signed effective bit offset, EB, of A(I₁,I₂):

EB = V₀ + S₁*I₁ + S₂*I₂ = POS + S₁*[I₁ - L₁] + S₂*[I₂ - L₂]

The signed effective bit offset, EB, of A(I₁, ... , I_n):

EB = V₀ + S₁*I₁ + ... + S_n*I_n = POS + S₁*[I₁ - L₁] + ... + S_n*[I_n - L_n]

Note that EB is computed ignoring integer overflow.

On VAX systems, EB is used as the position operand, and the content of BASE is used as the base address operand in the VAX variable-length bit field instructions. Therefore, BASE must specify a byte within 2²⁸ bytes of all bytes of storage in the bit array.

For example, consider a single-origin, one-dimensional, five-element array consisting of 3-bit elements allocated adjacently (therefore, S1 = 3). Assume BASE is byte 1000 and the first actual element, A(1), starts at bit <4> of byte 1001.

The following dependent field values occur in the descriptor:

POS = 12 V₀ = 12 - 3*1 = 9

7.12 String with Bounds Descriptor (CLASS_SB)

A variant of the fixed-length string descriptor is used to specify strings where the string is viewed as a one-dimensional array with user-specified bounds. Figure 7-13 shows the format of a string with bounds descriptor. Table 7-14 describes the fields of the descriptor.

Figure 7-13 String with Bounds Descriptor Format

Table 7-14 Contents of the CLASS_SB Descriptor
Symbol Description

DSC$W_LENGTH
DSC64$Q_LENGTH Length of the string in bytes.

DSC64$W_MBO Must be 1. See Section 7.1.

DSC$B_DTYPE
DSC64$B_DTYPE A data-type code that must have the value 14, which specifies the character string data type (see Sections 6.1 and 6.2). The use of other data types is reserved to Hewlett-Packard.

DSC$B_CLASS
DSC64$B_CLASS Defines the descriptor class code that must be equal to 15 for CLASS_SB.

DSC$A_POINTER
DSC64$PQ_POINTER Address of the first byte of data storage.

DSC64$L_MBMO Must be -1. See Section 7.1.

DSC$L_SB_L1
DSC64$Q_SB_L1 Lower bound (signed) of the first (and only) dimension.

DSC$L_SB_U1
DSC64$Q_SB_U1 Upper bound (signed) of the first (and only) dimension.

**Table 7-14 Contents of the CLASS_SB Descriptor**
Symbol	Description
DSC$W_LENGTH DSC64$Q_LENGTH	Length of the string in bytes.
DSC64$W_MBO	Must be 1. See Section 7.1.
DSC$B_DTYPE DSC64$B_DTYPE	A data-type code that must have the value 14, which specifies the character string data type (see Sections 6.1 and 6.2). The use of other data types is reserved to Hewlett-Packard.
DSC$B_CLASS DSC64$B_CLASS	Defines the descriptor class code that must be equal to 15 for CLASS_SB.
DSC$A_POINTER DSC64$PQ_POINTER	Address of the first byte of data storage.
DSC64$L_MBMO	Must be -1. See Section 7.1.
DSC$L_SB_L1 DSC64$Q_SB_L1	Lower bound (signed) of the first (and only) dimension.
DSC$L_SB_U1 DSC64$Q_SB_U1	Upper bound (signed) of the first (and only) dimension.

The following formula specifies the effective address, E, of a string element A(I):

E = POINTER + [I - SB_L1]

If the string must be extended in a string comparison or assignment, the space character (hexadecimal 20 if ASCII) is used as the fill character.

7.13 Unaligned Bit String with Bounds Descriptor (CLASS_UBSB)

A variant of the unaligned bit string descriptor is used to specify bit strings where the string is viewed as a one-dimensional bit array with user-specified bounds. Figure 7-14 shows the format of an unaligned bit string with bounds descriptor. Table 7-15 describes the fields of the descriptor.

Figure 7-14 Unaligned Bit String with Bounds Descriptor Format

Table 7-15 Contents of the CLASS_UBSB Descriptor
Symbol Description

DSC$W_LENGTH
DSC64$Q_LENGTH Length of the data item in bits.

DSC64$W_MBO Must be 1. See Section 7.1.

DSC$B_DTYPE
DSC64$B_DTYPE A data-type code that must have the value 34, which specifies the unaligned bit string data type (see Sections 6.1 and 6.2). The use of other data types is reserved to Hewlett-Packard.

DSC$B_CLASS
DSC64$B_CLASS Defines the descriptor class code that must be equal to 16 for CLASS_UBSB.

DSC$A_BASE
DSC64$PQ_BASE Base address relative to the signed relative bit position, POS, used to locate the bit string. The base address need not be the first actual byte of data storage.

DSC64$L_MBMO Must be -1. See Section 7.1.

DSC$L_POS
DSC64$Q_POS Signed longword that defines the relative bit position of the first bit of the unaligned bit string to the BASE address.

DSC$L_UBSB_L1
DSC64$Q_UBSB_L1 Lower bound (signed) of the first (and only) dimension.

DSC$L_UBSB_U1
DSC64$Q_UBSB_U1 Upper bound (signed) of the first (and only) dimension.

**Table 7-15 Contents of the CLASS_UBSB Descriptor**
Symbol	Description
DSC$W_LENGTH DSC64$Q_LENGTH	Length of the data item in bits.
DSC64$W_MBO	Must be 1. See Section 7.1.
DSC$B_DTYPE DSC64$B_DTYPE	A data-type code that must have the value 34, which specifies the unaligned bit string data type (see Sections 6.1 and 6.2). The use of other data types is reserved to Hewlett-Packard.
DSC$B_CLASS DSC64$B_CLASS	Defines the descriptor class code that must be equal to 16 for CLASS_UBSB.
DSC$A_BASE DSC64$PQ_BASE	Base address relative to the signed relative bit position, POS, used to locate the bit string. The base address need not be the first actual byte of data storage.
DSC64$L_MBMO	Must be -1. See Section 7.1.
DSC$L_POS DSC64$Q_POS	Signed longword that defines the relative bit position of the first bit of the unaligned bit string to the BASE address.
DSC$L_UBSB_L1 DSC64$Q_UBSB_L1	Lower bound (signed) of the first (and only) dimension.
DSC$L_UBSB_U1 DSC64$Q_UBSB_U1	Upper bound (signed) of the first (and only) dimension.

The following formula specifies the effective bit offset, EB, of a bit element A(I):

EB = POS + [I - UBSB_L1]

7.14 Reserved Descriptor Class Codes

All descriptor class codes from 0 through 191 not otherwise defined in this standard are reserved to Hewlett-Packard. Classes 192 through 255 are reserved for Hewlett-Packard custom systems and for customers for their own use.

Table 7-16 lists some specific descriptor classes and codes that are obsolete or reserved to Hewlett-Packard.

Table 7-16 Specific OpenVMS VAX Descriptors Reserved to Hewlett-Packard
Descriptor Code Class

DSC$K_CLASS_V 3 Obsolete (variable buffer)

DSC$K_CLASS_PI 6 Obsolete (procedure incarnation)

DSC$K_CLASS_J 7 Reserved to DEBUG (label)

DSC$K_CLASS_JI 8 Obsolete (label incarnation)

DSC$K_CLASS_CT 17 Reserved to ACMS (compressed text)

DSC$K_CLASS_BFA 191 Reserved to BASIC (file array)

**Table 7-16 Specific OpenVMS VAX Descriptors Reserved to Hewlett-Packard**
Descriptor	Code	Class
DSC$K_CLASS_V	3	Obsolete (variable buffer)
DSC$K_CLASS_PI	6	Obsolete (procedure incarnation)
DSC$K_CLASS_J	7	Reserved to DEBUG (label)
DSC$K_CLASS_JI	8	Obsolete (label incarnation)
DSC$K_CLASS_CT	17	Reserved to ACMS (compressed text)
DSC$K_CLASS_BFA	191	Reserved to BASIC (file array)

7.14.1 Facility-Specific Descriptor Class Codes

Descriptor class codes 160 through 191 are reserved for Hewlett-Packard for facility-specific purposes. These codes must not be passed between facilities, because different facilities might use the same code for different purposes. These codes can be used by compiler-generated code to pass parameters to the language-specific, run-time support procedures associated with that language or to the OpenVMS Debugger.

Chapter 8
OpenVMS Conditions

An OpenVMS condition is a hardware-generated synchronous exception or a software event that is to be processed in a manner similar to a hardware exception.

Floating-point overflow exception, memory access violation exception, and reserved operation exception are examples of hardware-generated conditions. An output conversion error, an end of file, and the filling of an output buffer are examples of software events that might be treated as conditions.

Depending on the condition and on the program, you can exercise any of four types of action when a condition occurs:

Ignore the condition.
For example, if an underflow occurs in a floating-point operation, continuing from the point of the exception with a zero result might be sufficient.
Take some special action and continue from the point at which the condition occurred.
For example, if the end of a buffer is reached while a series of data items are being written, the special action is to start a new buffer.
End the operation and branch from the sequential flow of control.
For example, if the end of an input file is reached, the branch exits from a loop that is processing the input data.
Treat the condition as an unrecoverable error.
For example, when the floating divide-by-zero exception condition occurs, the program exits after writing (optionally) an appropriate error message.

When an unusual event or error occurs in a called procedure, the procedure can return a condition value to the caller indicating what has happened (see Section 8.1). The caller tests the condition value and takes the appropriate action.

When an exception is generated by the hardware, a branch out of the program's flow of control occurs automatically. In this case, and for certain software-generated events, it is more convenient to handle the condition as soon as it is detected rather than to program explicit tests.

8.1 Condition Values

Condition values are used in the OpenVMS operating system to provide the following functions:

Indicate the success or failure of a called procedure as a function value.
Describe an exception condition when an exception is signaled.
Identify system messages.
Report program success or failure to the command language level.

A condition value is a longword that includes fields to describe the software component that generates the value, the reason the value was generated, and severity status of the condition value. Figure 8-1 shows the format of a condition value. Table 8-1 describes the fields of a condition value.

Figure 8-1 Format of a Condition Value

Table 8-1 Contents of the Condition Value
Symbol Description

Severity Indicates success or failure. The severity code bit <0> is set for success (logical true) and is clear for failure (logical false); bits <1> and <2> distinguish degrees of success or failure. Bits <2:0>, when taken as an unsigned integer, are interpreted as shown in the following table:

Symbol Value Description

STS$K_WARNING 0 Warning

STS$K_SUCCESS 1 Success

STS$K_ERROR 2 Error

STS$K_INFO 3 Information

STS$K_SEVERE 4 Severe error

5 Reserved to Hewlett-Packard

6 Reserved to Hewlett-Packard

7 Reserved to Hewlett-Packard

Section 8.1.1 more fully describes severity codes.

Condition identification Identifies the condition uniquely on a systemwide basis.

Message number Describes the status, which can be a hardware exception that occurred or a software-defined value. Message numbers with bit <15> set are specific to a single facility. Message numbers with bit <15> clear are systemwide status codes.

Facility number Identifies the software component generating the condition value. Bit <27> is set for customer facilities and is clear for Hewlett-Packard facilities.

Control Controls the printing of the message associated with the condition value. Bit <28> inhibits the message associated with the condition value from being printed by the SYS$EXIT system service. This bit is set by the system default handler after it has output an error message using the SYS$PUTMSG system service. It should also be set in the condition value returned by a procedure as a function value, if the procedure has also signaled the condition (so the condition has been printed or suppressed). Bits <31:29> must be 0; they are reserved to Hewlett-Packard for future use.
Table 8-2 lists the possible software symbols that are defined for the various fields of the condition-value longword.

Table 8-2 Value Symbols for the Condition Value Longword
Symbol Value Meaning Field

STS$V_COND_ID 3 Position of 27:3 Condition identification

STS$S_COND_ID 25 Size of 27:3 Condition identification

STS$M_COND_ID Mask Mask for 27:3 Condition identification

STS$V_INHIB_MSG 1@28 Position for 28 Inhibit message on image exit

STS$S_INHIB_MSG 1 Size for 28 Inhibit message on image exit

STS$M_INHIB_MSG Mask Mask for 28 Inhibit message on image exit

STS$V_FAC_NO 16 Position of 27:16 Facility number

STS$S_FAC_NO 12 Size of 27:16 Facility number

STS$M_FAC_NO Mask Mask for 27:16 Facility number

STS$V_CUST_DEF 27 Position for 27 Customer facility

STS$S_CUST_DEF 1 Size for 27 Customer facility

STS$M_CUST_DEF 1@27 Mask for 27 Customer facility

STS$V_MSG_NO 3 Position of 15:3 Message number

STS$S_MSG_NO 13 Size of 15:3 Message number

STS$M_MSG_NO Mask Mask for 15:3 Message number

STS$V_FAC_SP 15 Position of 15 Facility-specific

STS$S_FAC_SP 1 Size for 15 Facility-specific

STS$M_FAC_SP 1@15 Mask for 15 Facility-specific

STS$V_CODE 3 Position of 14:3 Message code

STS$S_CODE 12 Size of 14:3 Message code

STS$M_CODE Mask Mask for 14:3 Message code

STS$V_SEVERITY 0 Position of 2:0 Severity

STS$S_SEVERITY 3 Size of 2:0 Severity

STS$M_SEVERITY 7 Mask for 2:0 Severity

STS$V_SUCCESS 0 Position of 0 Success

STS$S_SUCCESS 1 Size of 0 Success

STS$M_SUCCESS 1 Mask for 0 Success

**Table 8-2 Value Symbols for the Condition Value Longword**
Symbol	Value	Meaning	Field
STS$V_COND_ID	3	Position of 27:3	Condition identification
STS$S_COND_ID	25	Size of 27:3	Condition identification
STS$M_COND_ID	Mask	Mask for 27:3	Condition identification
STS$V_INHIB_MSG	1@28	Position for 28	Inhibit message on image exit
STS$S_INHIB_MSG	1	Size for 28	Inhibit message on image exit
STS$M_INHIB_MSG	Mask	Mask for 28	Inhibit message on image exit
STS$V_FAC_NO	16	Position of 27:16	Facility number
STS$S_FAC_NO	12	Size of 27:16	Facility number
STS$M_FAC_NO	Mask	Mask for 27:16	Facility number
STS$V_CUST_DEF	27	Position for 27	Customer facility
STS$S_CUST_DEF	1	Size for 27	Customer facility
STS$M_CUST_DEF	1@27	Mask for 27	Customer facility
STS$V_MSG_NO	3	Position of 15:3	Message number
STS$S_MSG_NO	13	Size of 15:3	Message number
STS$M_MSG_NO	Mask	Mask for 15:3	Message number
STS$V_FAC_SP	15	Position of 15	Facility-specific
STS$S_FAC_SP	1	Size for 15	Facility-specific
STS$M_FAC_SP	1@15	Mask for 15	Facility-specific
STS$V_CODE	3	Position of 14:3	Message code
STS$S_CODE	12	Size of 14:3	Message code
STS$M_CODE	Mask	Mask for 14:3	Message code
STS$V_SEVERITY	0	Position of 2:0	Severity
STS$S_SEVERITY	3	Size of 2:0	Severity
STS$M_SEVERITY	7	Mask for 2:0	Severity
STS$V_SUCCESS	0	Position of 0	Success
STS$S_SUCCESS	1	Size of 0	Success
STS$M_SUCCESS	1	Mask for 0	Success

8.1.1 Interpretation of Severity Codes

A standard procedure must consider all possible severity codes (0--4) of a condition value. Table 8-3 lists the interpretation of severity codes 0 through 4.

Table 8-3 Interpretation of Severity Codes
Severity Code Meaning

0 Indicates a warning. This code is used whenever a procedure produces output, but the output produced might not be what the user expected (for example, a compiler modification of a source program).

1 Indicates that the procedure generating the condition value completed successfully, as expected.

2 Indicates that an error has occurred but the procedure did produce output. Execution can continue, but the results produced by the component generating the condition value are not all correct.

3 Indicates that the procedure generating the condition value completed successfully but has some parenthetical information to be included in a message if the condition is signaled.

4 Indicates that a severe error occurred and the component generating the condition value was unable to produce output.

**Table 8-3 Interpretation of Severity Codes**
Severity Code	Meaning
0	Indicates a warning. This code is used whenever a procedure produces output, but the output produced might not be what the user expected (for example, a compiler modification of a source program).
1	Indicates that the procedure generating the condition value completed successfully, as expected.
2	Indicates that an error has occurred but the procedure did produce output. Execution can continue, but the results produced by the component generating the condition value are not all correct.
3	Indicates that the procedure generating the condition value completed successfully but has some parenthetical information to be included in a message if the condition is signaled.
4	Indicates that a severe error occurred and the component generating the condition value was unable to produce output.

When designing a procedure, you should base the choice of severity code for its condition values on the following default interpretations:

The calling program typically performs a low-bit test, so it treats warnings, errors, and severe errors as failures, and treats success and information as successes.
If the condition value is signaled (see Section 8.4.3), the default handler treats severe errors as reason to terminate and treats all the others as the basis for continuation.
When the program image exits, the command interpreter by default treats errors and severe errors as the basis for stopping the job, and treats warnings, information, and successes as the basis for continuation.

The following table summarizes the action default decisions of the severity conditions:

Severity Routine Signal Default at
Program Exit

Success Normal Continue Continue

Information Normal Continue Continue

Warning Failure Continue Continue

Error Failure Continue Stop job

Severe error Failure Exit Stop job

Severity	Routine	Signal	Default at Program Exit
Success	Normal	Continue	Continue
Information	Normal	Continue	Continue
Warning	Failure	Continue	Continue
Error	Failure	Continue	Stop job
Severe error	Failure	Exit	Stop job

The default for signaled messages is to output a message with the SYS$OUTPUT system service. In addition, for severities other than success (STS$K_SUCCESS), a copy of the message is made on SYS$ERROR. At program exit, success and information completion values do not generate messages; however, warning, error, and severe error condition values do generate messages to SYS$OUTPUT and SYS$ERROR unless bit <28> (STS$V_INHIB_MSG) is set.

Unless there is a good basis for another choice, a procedure should use success or severe error as its severity code for each condition value.