 |
HP OpenVMS Calling Standard
7.2 Fixed-Length Descriptor (CLASS_S)
A single descriptor class is used for scalar data and fixed-length
strings. Any OpenVMS data type, except data type 34 (unaligned bit
string), can be used with this descriptor. Figure 7-2 shows the
format of a fixed-length descriptor. Table 7-3 describes the fields
of the descriptor.
Figure 7-2 Fixed-Length Descriptor Format
Table 7-3 Contents of the CLASS_S Descriptor
| Symbol |
Description |
DSC$W_LENGTH
DSC64$Q_LENGTH
|
Length of the data item in bytes, unless the DTYPE field contains the
value 1 (aligned bit string) or 21 (packed-decimal string). Length of
the data item is in bits for bit string. Length of the data item is the
number of 4-bit digits (not including the sign) for a packed-decimal
string.
|
|
DSC64$W_MBO
|
Must be 1. See Section 7.1.
|
DSC$B_DTYPE
DSC64$B_DTYPE
|
A data-type code. Data-type codes are listed in Sections 6.1
and 6.2.
|
DSC$B_CLASS
DSC64$B_CLASS
|
Defines the descriptor class code that must be equal to 1 for CLASS_S.
|
DSC$A_POINTER
DSC64$PQ_POINTER
|
Address of first byte of data storage.
|
|
DSC64$L_MBMO
|
Must be -1. See Section 7.1.
|
If the data type is 14 (character string) and the string must be
extended in a string comparison or is being copied to a fixed-length
string containing a greater length, the space character (hexadecimal 20
if ASCII) is used as the fill character.
7.3 Dynamic String Descriptor (CLASS_D)
A class D descriptor is used for dynamically allocated strings. When a
string is written, either the length field, pointer field, or both can
be changed. The OpenVMS Run-Time Library provides procedures for
changing fields. As an input parameter, this format is interchangeable
with class 1 (CLASS_S). Figure 7-3 shows the format of a dynamic
string descriptor. Table 7-4 describes the fields of the descriptor.
Figure 7-3 Dynamic String Descriptor Format
Table 7-4 Contents of the CLASS_D Descriptor
| Symbol |
Description |
DSC$W_LENGTH
DSC64$Q_LENGTH
|
Length of the data item in bytes, unless the DTYPE field contains the
value 1 (aligned bit string) or 21 (packed-decimal string). Length of
the data item is in bits for the bit string. Length of the data item is
the number of 4-bit digits (not including the sign) for a
packed-decimal string.
|
|
DSC64$W_MBO
|
Must be 1. See Section 7.1.
|
DSC$B_DTYPE
DSC64$B_DTYPE
|
A data-type code. Data-type codes are listed in Sections 6.1
and 6.2.
|
DSC$B_CLASS
DSC64$B_CLASS
|
Defines the descriptor class code that must be equal to 2 for CLASS_D.
|
DSC$A_POINTER
DSC64$PQ_POINTER
|
Address of first byte of data storage.
|
|
DSC64$L_MBMO
|
Must be -1. See Section 7.1.
|
7.4 Array Descriptor (CLASS_A)
The array descriptor shown in Figure 7-4 is used to describe
contiguous arrays of atomic data types or contiguous arrays of
fixed-length strings. An array descriptor consists of three contiguous
blocks. The first block contains the descriptor prototype information
and is part of every array descriptor. The second and third blocks are
optional. If the third block is present, so is the second.
Table 7-5 describes the fields of the descriptor.
Figure 7-4 Array Descriptor Format
Table 7-5 Contents of the CLASS_A Descriptor
| Symbol |
Description |
DSC$W_LENGTH
DSC64$Q_LENGTH
|
Length of an array element in bytes, unless the DTYPE field contains
the value 1 (aligned bit string) or 21 (packed-decimal string). Length
of an array element is in bits for the bit string. Length of an array
element is the number of 4-bit digits (not including the sign) for a
packed-decimal string.
|
|
DSC64$W_MBO
|
Must be 1. See Section 7.1.
|
DSC$B_DTYPE
DSC64$B_DTYPE
|
A data-type code. Data-type codes are listed in Sections 6.1
and 6.2.
|
DSC$B_CLASS
DSC64$B_CLASS
|
Defines the descriptor class code that must be equal to 4 for CLASS_A.
|
DSC$A_POINTER
DSC64$PQ_POINTER
|
Address of the first actual byte of data storage.
|
|
DSC64$L_MBMO
|
Must be -1. See Section 7.1.
|
DSC$B_SCALE
DSC64$B_SCALE
|
Signed power-of-two or power-of-ten multiplier, as specified by
FL_BINSCALE, to convert the internal form to external form. (See
Section 7.6.)
|
DSC$B_DIGITS
DSC64$B_DIGITS
|
If nonzero, the unsigned number of decimal digits in the internal
representation. If 0, the number of digits can be computed based on
LENGTH. This field should be 0 unless the TYPE field specifies a string
data type that could contain numeric values.
|
DSC$B_AFLAGS
DSC64$B_AFLAGS
|
Array flag bits <23:16>:
|
Bits <18:16>
|
Reserved and must be 0.
|
DSC$V_FL_BINSCALE
DSC64$V_FL_BINSCALE
|
If set, the scale factor specified by SCALE is a signed power-of-two
multiplier to convert the internal form to external form. If not set,
SCALE specifies a signed power-of-ten multiplier. (See Section 7.6.)
|
DSC$V_FL_REDIM
DSC64$V_FL_REDIM
|
If set, the array can be redimensioned; that is, A0, M
i, L
i, and U
i can be changed. The redimensioned array cannot exceed the
size allocated to the array ARSIZE.
|
DSC$V_FL_COLUMN
DSC64$V_FL_COLUMN
|
If set, the elements of the array are stored by columns (FORTRAN). That
is, the leftmost subscript (first dimension) is varied most rapidly,
and the rightmost subscript (
nth dimension) is varied least rapidly. If not set, the
elements are stored by rows (most other languages). That is, the
rightmost subscript is varied most rapidly and the leftmost subscript
is varied least rapidly.
|
DSC$V_FL_COEFF
DSC64$V_FL_COEFF
|
If set, the multiplicative coefficients in block 2 are present. Must be
set if FL_BOUNDS is set.
|
DSC$V_FL_BOUNDS
DSC64$V_FL_BOUNDS
|
If set, the bounds information in block 3 is present and requires that
FL_COEFF be set.
|
|
DSC$B_DIMCT
DSC64$B_DIMCT
|
Number of dimensions,
n.
|
DSC$L_ARSIZE
DSC64$Q_ARSIZE
|
Total size of array (in bytes, unless the TYPE field contains the value
21; see the description for LENGTH). A redimensioned array can use less
than the total size allocated.
For data type 1 (aligned bit string), LENGTH is in bits while ARSIZE
is in bytes because the unit of length is bits, while the unit of
allocation is aligned bytes.
|
DSC$A_A0
DSC64$PQ_A0
|
Address of element A(0,0,...,0). This need not be within the actual
array. It is the same as POINTER for zero-origin arrays.
|
DSC$L_M
i
DSC64$Q_M
i
|
Addressing coefficients ( M
i = U
i - L
i + 1 ).
|
DSC$L_L
i
DSC64$Q_L
i
|
Lower bound (signed) of
ith dimension.
|
DSC$L_U
i
DSC64$Q_U
i
|
Upper bound (signed) of
ith dimension.
|
The following formulas specify the effective address, E, of an array
element.
Caution
Modification of the following formulas is required if DTYPE contains a
1 or 21, because LENGTH is given in bits or 4-bit digits rather than in
bytes.
|
The effective address, E, for element A(I):
E = A0 + I*LENGTH
= POINTER + [I - L1]*LENGTH
|
The effective address, E, for element A(I1,I2)
with FL_COLUMN clear:
E = A0 + [I1*M2 + I2]*LENGTH
= POINTER + [[I1 - L1]*M2 + I2 - L2]*LENGTH
|
The effective address, E, for element A(I1,I2)
with FL_COLUMN set:
E = A0 + [I2*M1 + I1]*LENGTH
= POINTER + [[I2 - L2]*M1 + I1 - L1]*LENGTH
|
The effective address, E, for element A(I1, . . .
,In) with FL_COLUMN clear:
E = A0 + [[[[...[I1]*M2 + ...]*Mn-2 + In-2]*Mn-1
+ In-1]*Mn + In]*LENGTH
= POINTER + [[[[...[I1 - L1]*M2
+ ...]*Mn-2 + In-2 - Ln-2]*Mn-1
+ In-1 - Ln-1]*Mn + In - Ln]*LENGTH
|
The effective address, E, for element A(I1, . . .
,In) with FL_COLUMN set:
E = A0 + [[[[...[In]*Mn-1 + ...]*M3 + I3]*M2 + I2]*M1 + I1]*LENGTH
= POINTER + [[[[...[In - Ln]*Mn-1 + ...]*M3 + I3
- L3]*M2 + I2 - L2]*M1 + I1 - L1]*LENGTH
|
7.5 Procedure Argument Descriptor (CLASS_P)
A descriptor for a procedure argument identifies a procedure and its
result data type, if any.
On OpenVMS VAX systems, the descriptor for a procedure argument
specifies its entry address and function value data type. On OpenVMS
Alpha systems, the procedure argument descriptor is a pointer to the
procedure descriptor, which is described in Section 3.4. On OpenVMS
I64 systems, the procedure argument descriptor is a pointer to the
function descriptor, which is described in Section 4.7.7. Figure 7-5
shows the format of a procedure argument descriptor. Table 7-6
describes the fields of the descriptor.
Figure 7-5 Procedure Argument Descriptor Format
Table 7-6 Contents of the CLASS_P Descriptor
| Symbol |
Description |
DSC$W_LENGTH
DSC64$Q_LENGTH
|
Length associated with the function value, or 0 if no function value is
returned.
|
|
DSC64$W_MBO
|
Must be 1. See Section 7.1.
|
DSC$B_DTYPE
DSC64$B_DTYPE
|
Function value data-type code. Data-type codes are listed in Sections
6.1 and 6.2.
|
DSC$B_CLASS
DSC64$B_CLASS
|
Defines the descriptor class code that must be equal to 5 for CLASS_P.
|
DSC$A_POINTER
DSC64$PQ_POINTER
|
Address of entry mask to the procedure for VAX environments.
Address of the procedure descriptor of the procedure for Alpha
environments.
Address of the function descriptor of the procedure for I64
environments.
|
|
DSC64$L_MBMO
|
Must be -1. See Section 7.1.
|
Procedures return a function value as described in Section 2.5 for
VAX systems, Section 3.7.7 for Alpha systems, or Section 4.7.6 for I64
systems.
7.6 Decimal String Descriptor (CLASS_SD)
Figure 7-6 shows the format of a decimal string descriptor. Decimal
size and scaling information for both scalar data and simple strings is
given in this descriptor form. Table 7-7 describes the fields of
the descriptor.
Figure 7-6 Decimal String Descriptor Format
Table 7-7 Contents of the CLASS_SD Descriptor
| Symbol |
Description |
DSC$W_LENGTH
DSC64$Q_LENGTH
|
Length of the data item in bytes, unless the DTYPE field contains the
value 1 (aligned bit string) or 21 (packed-decimal string). Length of
the data item is in bits for the bit string. Length of the data item is
the number of 4-bit digits (not including the sign) for packed-decimal
string.
|
|
DSC64$W_MBO
|
Must be 1. See Section 7.1.
|
DSC$B_DTYPE
DSC64$B_DTYPE
|
A data-type code. Data-type codes are listed in Sections 6.1
and 6.2.
|
DSC$B_CLASS
DSC64$B_CLASS
|
Defines the descriptor class code that must be equal to 9 for CLASS_SD.
|
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$B_SCALE
DSC64$B_SCALE
|
Signed power-of-two or power-of-ten multiplier, as specified by
FL_BINSCALE, to convert the internal form to external form. (See
examples in Table 7-8.)
|
DSC$B_DIGITS
DSC64$B_DIGITS
|
If nonzero, the unsigned number of decimal digits in the internal
representation. If 0, the number of digits can be computed based on
LENGTH. This field should be 0 unless the TYPE field specifies a string
data type that could contain numeric values.
|
DSC$B_SFLAGS
DSC64$B_SFLAGS
|
Scalar flag bits <23:16>:
|
Bits <18:16>
|
Reserved and must be 0.
|
DSC$V_FL_BINSCALE
DSC64$V_FL_BINSCALE
|
If set, the scale factor specified by SCALE is a signed power-of-two
multiplier to convert the internal form to external form. If not set,
SCALE specifies a signed power-of-ten multiplier. (See examples in
Table 7-8.)
|
|
Bit <23:20>
|
Reserved and must be 0.
|
|
Examples of SCALE and FL_BINSCALE interpretation are presented in
Table 7-8.
7.7 Noncontiguous Array Descriptor (CLASS_NCA)
The noncontiguous array descriptor describes an array in which the
storage of the array elements can be allocated with a fixed, nonzero
number of bytes separating logically adjacent elements. Two elements
are said to be logically adjacent if their subscripts differ by 1 in
the most rapidly varying dimension only. The difference between the
addresses of two adjacent elements is termed the
stride. You can align elements by row or column,
because the accessing algorithm in the called procedure handles both
alignments.
This array descriptor is to be used where the calling program, at its
option, can pass a slice of an array that contains noncontiguous
allocations. This standard indicates no preference between the
noncontiguous array descriptor (NCA) and the contiguous array
descriptor (A), as described in Section 7.4, for language processors
that always allocate contiguous arrays. Figure 7-7 shows the format
of a noncontiguous array descriptor, which consists of three contiguous
blocks. Table 7-9 describes the fields of the descriptor.
Figure 7-7 Noncontiguous Array Descriptor Format
Table 7-9 Contents of the CLASS_NCA Descriptor
| Symbol |
Description |
DSC$W_LENGTH
DSC64$Q_LENGTH
|
Length of an array element in bytes, unless the DTYPE field contains
the value 1 (aligned bit string) or 21 (packed-decimal string). Length
of an array element is in bits for the bit string. Length of an array
element is the number of 4-bit digits (not including the sign) for a
packed-decimal string.
|
|
DSC64$W_MBO
|
Must be 1. See Section 7.1.
|
DSC$B_DTYPE
DSC64$B_DTYPE
|
A data-type code. Data-type codes are listed in Sections 6.1
and 6.2.
|
|
DSC$B_CLASS
|
Defines the descriptor class code that must be equal to 10 for
CLASS_NCA.
|
DSC$A_POINTER
DSC64$PQ_POINTER
|
Address of first actual byte of data storage.
|
|
DSC64$L_MBMO
|
Must be -1. See Section 7.1.
|
DSC$B_SCALE
DSC64$B_SCALE
|
Signed power-of-two or power-of-ten multiplier, as specified by
FL_BINSCALE, to convert the internal form to external form. (See
Section 7.6.)
|
DSC$B_DIGITS
DSC64$B_DIGITS
|
If nonzero, the unsigned number of decimal digits in the internal
representation. If 0, the number of digits can be computed based on
LENGTH. This field should be 0 unless the TYPE field specifies a string
data type that could contain numeric values.
|
DSC$B_AFLAGS
DSC64$B_AFLAGS
|
Array flag bits <23:16>:
|
Bits <18:16>
|
Reserved to Hewlett-Packard. Must be 0.
|
DSC$V_FL_BINSCALE
DSC64$V_FL_BINSCALE
|
If set, the scale factor specified by SCALE is a signed power-of-two
multiplier to convert the internal form to external form. If not set,
SCALE specifies a signed power-of-ten multiplier. (See Section 7.6.)
|
DSC$V_FL_REDIM
DSC64$V_FL_REDIM
|
Must be 0.
|
DSC$V_FL_UNALLOC
DSC64$V_FL_UNALLOC
|
If set, the storage for the array described by this descriptor has not
been allocated; the POINTER field must contain 0. If not set, storage
for the array described by this descriptor has been allocated; the
POINTER field may or may not be 0, depending on the bounds of the
array. (If the POINTER field contains a nonzero value, then this flag
must not be set.)
|
|
DSC$V_FL_NODEALLOC
|
If set, the storage for the array described by this descriptor must not
be deallocated. (The POINTER and other fields of this descriptor may be
cleared or otherwise set to eliminate access to the described storage,
but the storage itself belongs to some other descriptor which must be
used to deallocate that storage.)
|
|
Bit <23:23>
|
Reserved to Hewlett-Packard. Must be 0.
|
|
DSC$B_DIMCT
DSC64$B_DIMCT
|
Number of dimensions,
n.
|
DSC$L_ARSIZE
DSC64$Q_ARSIZE
|
If the elements are contiguous, ARSIZE is the total size of the array
(in bytes, unless the DTYPE field contains the value 21; see the
description of LENGTH). If the elements are not allocated contiguously
or if the program unit allocating the descriptor is uncertain whether
the array is actually contiguous, the value placed in ARSIZE might be
meaningless.
For data type 1 (aligned bit string), LENGTH is in bits while
ARSIZE is in bytes because the unit of length is in bits while the unit
of allocation is in bytes.
|
DSC$A_A0
DSC64$PQ_A0
|
Address of element A(0,0,...,0). This need not be within the actual
array. It is the same as POINTER for zero-origin arrays.
A0 = POINTER - ( S
1*L
1 + S
2*L
2 + ...+ S
n
*L
n
)
|
DSC$L_Si
DSC64$Q_Si
|
Stride of the
ith dimension. The difference between the addresses of
successive elements of the
ith dimension.
|
DSC$L_L
i
DSC64$Q_L
i
|
Lower bound (signed) of the
ith dimension.
|
DSC$L_U
i
DSC64$Q_U
i
|
Upper bound (signed) of the
ith dimension.
|
The following formulas specify the effective address, E, of an array
element.
Caution
Modification of the following formulas is required if DTYPE equals 1 or
21 because LENGTH is given in bits or 4-bit digits rather than bytes.
|
|
