[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS Calling Standard


Previous Contents Index

6.2 String Data Types

String data types are ordinarily described by a string descriptor. Table 6-2 shows how the string data types are defined and encoded for all OpenVMS environments.

Table 6-2 String Data Types
Symbol Code Name/Description
DSC$K_DTYPE_T 14 Character string

A single 8-bit character (atomic data type) or a sequence of 0 to 2 16 - 1 8-bit characters (string data type).

DSC$K_DTYPE_VT 37 Varying character string

A 16-bit unsigned count of the current number of 8-bit characters in the following string, followed by a string of 0 to 2 16 - 1 8-bit characters (see Section 6.5 for details). When this data type is used with descriptors, it can only be used with the varying string and varying string array descriptors, because the length field is interpreted differently from the other 8-bit string data types. (See Sections 6.5, 7.8, and 7.9 for further discussion.)

DSC$K_DTYPE_NU 15 Numeric string, unsigned
DSC$K_DTYPE_NL 16 Numeric string, left separate sign
DSC$K_DTYPE_NLO 17 Numeric string, left overpunched sign
DSC$K_DTYPE_NR 18 Numeric string, right separate sign
DSC$K_DTYPE_NRO 19 Numeric string, right overpunched sign
DSC$K_DTYPE_NZ 20 Numeric string, zoned sign
DSC$K_DTYPE_P 21 Packed-decimal string
DSC$K_DTYPE_V 1 Aligned bit string

A string of 0 to 2 16 - 1 contiguous bits. The first bit is bit <0> of the first byte, and the last bit is any bit in the last byte. Remaining bits in the last byte must be 0 on read and are cleared on write. Unlike the unaligned bit string (VU) data type, when the aligned bit string (V) data type is used in array descriptors, the ARSIZE field is in units of bytes, not bits, because allocation is a multiple of 8 bits.

DSC$K_DTYPE_VU 34 Unaligned bit string

The data is 0 to 2 16 - 1 contiguous bits located arbitrarily with respect to byte boundaries. See also aligned bit string (V) data type. Because additional information is required to specify the bit position of the first bit, this data type can be used only with the unaligned bit string and unaligned bit array descriptors (see Sections 7.10 and 7.11).

6.3 Miscellaneous Data Types

Table 6-3 shows how miscellaneous data types are defined and encoded for all OpenVMS environments.

Table 6-3 Miscellaneous Data Types
Symbol Code Name/Description
+DSC$K_DTYPE_ZI 22 Sequence of instructions
+DSC$K_DTYPE_ZEM 23 Procedure entry mask
DSC$K_DTYPE_DSC 24 Descriptor

This data type allows a descriptor to be a data type; thus, levels of descriptors are allowed.

+DSC$K_DTYPE_BPV 32 Bound procedure value (for VAX environment only)

A two-longword entity in which the first longword contains the address of a procedure entry mask and the second longword is the environment value. The environment value is determined in a language-specific manner when the original bound procedure value is generated. When the bound procedure is called, the calling program loads the second longword into R1. When the environment value is not needed, this data type can be passed using the immediate value mechanism. In this case, the argument list entry contains the address of the procedure entry mask and the second longword is omitted.

DSC$K_DTYPE_BLV 33 Bound label value

A two-longword entity in which the first longword contains the address of an instruction and the second longword is the language-specific environment value. The environment value is determined in a language-specific manner when the original bound label value is generated.

DSC$K_DTYPE_ADT 35 Absolute date and time

A 64-bit unsigned, scaled, binary integer representing a date and time in 100-nanosecond units offset from the OpenVMS operating system base date and time, which is 00:00 o'clock, November 17, 1858 (the Smithsonian base date and time for astronomical calendars). The value 0 indicates that the date and time have not been specified, so a default value or distinctive print format can be used.

Note that the ADT data type is the same as the OpenVMS date format for positive values only.


+VAX specific.

6.4 Reserved Data-Type Codes

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

Table 6-4 lists the data types and codes that are obsolete or reserved to Hewlett-Packard.

Table 6-4 Reserved Data Types
Symbol Code Purpose
DSC$K_DTYPE_CIT 31 Reserved to COBOL (intermediate temporary)
DSC$K_DTYPE_CIT2 64 Reserved to COBOL (intermediate temporary alternative 2)
DSC$K_DTYPE_TF 40 Reserved to DEBUG (Boolean true/false)
DSC$K_DTYPE_SV 41 Reserved to DEBUG (signed bit-field, aligned)
DSC$K_DTYPE_SVU 42 Reserved to DEBUG (signed bit-field, unaligned)
DSC$K_DTYPE_FIXED 43 Reserved to DEBUG (fixed binary---fixed point in Ada and fixed binary in PL/I)
DSC$K_DTYPE_TASK 44 Reserved to DEBUG (task type in Ada)
DSC$K_DTYPE_AC 45 Reserved to DEBUG (ASCIC text)
DSC$K_DTYPE_AZ 46 Reserved to DEBUG (ASCIZ text)
DSC$K_DTYPE_M68_S 47 Reserved to DEBUG (Motorola 68881 single precision, 32-bit) 1
DSC$K_DTYPE_M68_D 48 Reserved to DEBUG (Motorola 68881 double precision, 64-bit) 1
DSC$K_DTYPE_M68_X 49 Reserved to DEBUG (Motorola 68881 extended precision, 96-bit) 2
DSC$K_DTYPE_1750_S 50 Reserved to DEBUG (1750 single precision, 32-bit)
DSC$K_DTYPE_1750_X 51 Reserved to DEBUG (1750 extended precision, 48-bit)
DSC$K_DTYPE_WC 56 Reserved to DEBUG ( setlocale dependent C string)
DSC$K_DTYPE_F80 59 Reserved to DEBUG (Intel Itanium extended precision, 80-bit)
DSC$K_DTYPE_F80C 60 Reserved to DEBUG (Intel Itanium extended precision complex, two 80-bit)
DCS$K_DTYPE_FIR 61 Reserved to DEBUG (Intel Itanium floating-point Register format, 84-bit)
DCS$K_DTYPE_FIRC 62 Reserved to DEBUG (Intel Itanium floating-point Register format complex, two 84-bit)
No symbol defined 36 Obsolete
DSC$K_DTYPE_T2 38 Obsolete
DSC$K_DTYPE_VT2 39 Obsolete

1Differs from Alpha IEEE floating because of byte ordering.
2Differs from Alpha IEEE floating because of byte ordering and size.

6.4.1 Facility-Specific Data-Type Codes

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

As shown in Table 6-4, data-type codes 31 and 64 are reserved for the COBOL facility. Codes 40 through 51 and 56 are reserved for the OpenVMS Debugger facility.

6.5 Varying Character String Data Type (DSC$K_DTYPE_VT)

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



Chapter 7
OpenVMS Argument Descriptors

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.

Note

Unless stated otherwise, all fields in descriptors represented as unsigned quantities are read-only from the point of view of the called procedure, and can be allocated in read-only memory at the option of the calling program.

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

1The pointer field usage for this descriptor differs from VAX usage (see Section 7.5).

7.1 Descriptor Prototype

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
before concluding that it has a 64-bit form descriptor.

Note

It may seem sufficient to test just the MBMO field. However, that allows a 32-bit descriptor with a length of 0 and an undefined pointer to be inadvertently treated as a 64-bit descriptor.

If the MBMO field contains -1, then 0 and 1 are the only values of the MBO field that have defined interpretations.


Previous Next Contents Index