HP OpenVMS systems documentation

The varying character string data type (DSC$K_DTYPE_VT) consists of the following two fixed-length areas allocated contiguously with no padding in between (see Figure 6-1):

CURLEN	An unsigned word specifying the current length in bytes of the immediately following string.
BODY	A fixed-length area containing the string that can vary from 0 to a maximum length defined for each instance of string. The range of this maximum length is 0 to 2 16 - 1.

Figure 6-1 Varying Character String Data Type (DSC$K_DTYPE_VT)---General Format

When passed by reference or by descriptor, the address of the varying character string (VT) data type is always the address of the CURLEN field, not the BODY field.

When a called procedure modifies a varying character string data type passed by reference or by descriptor, it writes the new length, n, into CURLEN and can modify all bytes of BODY, even those beyond the new length.

For example, consider a varying string with a maximum length of seven characters. To represent the string ABC, CURLEN will have a value of 3 and the last four bytes will be undefined, as shown in Figure 6-2.

Figure 6-2 Varying Character String Data Type (DSC$K_DTYPE_VT) Format

This chapter describes the argument descriptors used in calling a procedure on OpenVMS.

A uniform descriptor mechanism is defined for use by all procedures that conform to the OpenVMS calling standard. Descriptors are self-describing and the mechanism is extensible. When existing descriptors fail to satisfy the semantics of a language, new descriptors are added to this standard.

Unless stated otherwise, the calling program fills in all fields in descriptors. This is true whether the descriptor is generated by default or by a language extension. The fields are filled in even if a called procedure written in the same language ignores the contents of some of the fields. Therefore, a descriptor conforms to this calling standard if all fields are filled in by the calling program, even if the called program does not need the field.

If a language processor implements a language-specific data type that is not added to this standard (see Chapter 6), the processor is not required to use a standard descriptor to pass an array of such a data type. However, if a language processor passes an array of such a data type using a standard descriptor, the language processor fills in the DSC$B_DTYPE field with the value 0, indicating that the data-type field is unspecified, rather than using a more general data-type code.

For example, an array of PL/I POINTER data types has the DTYPE field filled in with the value 0 (unspecified data type), rather than with the value 4 (longword [unsigned] data type). The remaining fields are filled in as specified by this standard; for example, DSC$W_LENGTH is filled in with the size in bytes. Because the language-specific data type might be added to the standard in the future, generic application procedures that examine the DTYPE field should be prepared for 0 and for additional data types.

Table 7-1 identifies the classes of argument descriptors for use in standard environments. Each class has two synonymous names---one for 32-bit environments (DSC$) and one for 64-bit environments (DSC64$). Descriptions and formats of each of these descriptors follow.

Table 7-1 Argument Descriptor Classes for OpenVMS Alpha and OpenVMS VAX

Descriptor	Code	Class
DSC$K_CLASS_S DSC64$K_CLASS_S	1	Fixed-length scalar/string
DSC$K_CLASS_D DSC64$K_CLASS_D	2	Dynamic string
DSC$K_CLASS_A DSC64$K_CLASS_A	4	Contiguous array
DSC$K_CLASS_P 1 DSC64$K_CLASS_P 1	5	Procedure argument descriptor
DSC$K_CLASS_SD DSC64$K_CLASS_SD	9	Decimal (scalar) string
DSC$K_CLASS_NCA DSC64$K_CLASS_NCA	10	Noncontiguous array
DSC$K_CLASS_VS DSC64$K_CLASS_VS	11	Varying string
DSC$K_CLASS_VSA DSC64$K_CLASS_VSA	12	Varying string array
DSC$K_CLASS_UBS DSC64$K_CLASS_UBS	13	Unaligned bit string
DSC$K_CLASS_UBA DSC64$K_CLASS_UBA	14	Unaligned bit array
DSC$K_CLASS_SB DSC64$K_CLASS_SB	15	String with bounds
DSC$K_CLASS_UBSB DSC64$K_CLASS_UBSB	16	Unaligned bit string with bounds

Figure 7-1 shows the descriptor prototype format. There are two forms: one for use with 32-bit addresses and one for use with 64-bit addresses. The two forms are compatible in that the forms can be distinguished dynamically at run time and, except for the size and consequential placement of fields, 32-bit and 64-bit descriptors are identical in content and interpretation.

The 32-bit descriptors are used on all OpenVMS systems. When used on OpenVMS Alpha systems or OpenVMS I64 systems, 32-bit descriptors provide full compatibility with their use on OpenVMS VAX systems. The 64-bit descriptors are used on both OpenVMS Alpha systems and OpenVMS I64 systems---they have no counterparts and are not recognized on OpenVMS VAX systems.

Figure 7-1 Descriptor Prototype Format

The 32-bit descriptors on OpenVMS Alpha systems and OpenVMS I64 systems have no required alignment for compatibility with OpenVMS VAX systems; however, longword alignment generally promotes performance. The 64-bit descriptors on OpenVMS Alpha systems and OpenVMS I64 systems must be quadword aligned.

Table 7-2 describes the fields of the descriptor. In this table and the similar tables for descriptors in later sections, note that most fields have two symbols and one description. The symbol that begins with the prefix DSC$ is used with 32-bit descriptors, while the symbol that begins with the prefix DSC64$ is used with 64-bit descriptors.

In this chapter, it is generally the practice to use only the main part of a field name, without either of the prefixes used in actual code. For example, the length field is referred to using LENGTH rather than mentioning both DSC$W_LENGTH and DSC64$Q_LENGTH. The DSC$ and DSC64$ prefixes are used only when referring to a particular form of descriptor.

The CLASS and DTYPE fields occupy the same offsets in both 32-bit and 64-bit descriptors. Thus, the symbols DSC$B_CLASS and DSC64$B_CLASS have the same definition, as do DSC$B_DTYPE and DSC64$B_DTYPE. Furthermore, these fields are permitted to contain the same values with the same meanings in both 32-bit and 64-bit forms.

The DSC$W_LENGTH and DSC$A_POINTER fields in the 32-bit descriptors correspond in placement to the DSC64$W_MBO (must be 1) and DSC64$L_MBMO (must be -1) fields in the 64-bit descriptors. The values of these fields are used to distinguish whether a given descriptor has the 32-bit or 64-bit form as described later in this section.

When the CLASS field is 0, no more information can be assumed than is shown in Table 7-2.

Table 7-2 Contents of the Prototype Descriptor

Symbol	Description
DSC$W_LENGTH DSC64$Q_LENGTH	Defines the data item length specific to the descriptor class.
DSC64$W_MBO	In a 64-bit descriptor, this field must contain the value 1. This field overlays the DSC$W_LENGTH field of a 32-bit descriptor and the value 1 is necessary to correctly distinguish between the two forms (see below).
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	A descriptor class code that identifies the format and interpretation of the other fields of the descriptor as specified in the following sections. This interpretation is intended to be independent of the DTYPE field, except for the data types that are made up of units less than a byte (packed-decimal string [P], aligned bit string [V], and unaligned bit string [VU]). The CLASS code can be used at run time by a called procedure to determine which descriptor is being passed.
DSC$A_POINTER DSC64$PQ_POINTER	The address of the first byte of the data element described.
DSC64$L_MBMO	In a 64-bit descriptor, this field must contain the value -1 (all 1 bits). Note that this field overlays the DSC$A_POINTER field of a 32-bit descriptor and the value -1 is necessary to correctly distinguish between the two forms (see below).

As previously mentioned, the MBO field (a word at offset 0) and the MBMO field (a longword at offset 4) are used to distinguish between a 32-bit and 64-bit descriptor. A called routine that is designed to handle both kinds of descriptors must do both of the following:

• Confirm that the MBO field contains 1
• Confirm that the MBMO field contains -1

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.

The effective address, E, for element A(I):

E = A0 + I*LENGTH = POINTER + [I - L1]*LENGTH

The effective address, E, for element A(I₁,I₂) with FL_COLUMN clear:

E = A0 + [I1*M2 + I2]*LENGTH = POINTER + [[I1 - L1]*M2 + I2 - L2]*LENGTH

The effective address, E, for element A(I₁,I₂) with FL_COLUMN set:

E = A0 + [I2*M1 + I1]*LENGTH = POINTER + [[I2 - L2]*M1 + I1 - L1]*LENGTH

The effective address, E, for element A(I₁, . . . ,I_n) 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(I₁, . . . ,I_n) 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