Digital PDFs

AA-Z500B-TE

April 1986

142 pages

Original

6.9MB

Document:	VMS 4.4 Introduction to VAX VMS System Routines
Order Number:	AA-Z500B-TE
Revision:
Pages:	142
Original Filename:	https://archive.org/download/stx_AA-Z500B-TE_VMS_4.4_Introduction_to_VAX_VMS_System_Routines_Apr86/AA-Z500B-TE_VMS_4.4_Introduction_to_VAX_VMS_System_Routines_Apr86.pdf

OCR Text

Introduction to
VAX/VMS System
Routines
Order Number: AA-Z500B-TE

April 1986
This manual describes the system routines documentation format, the
VAX Procedure Calling and Condition Handling Standard, and the VAX
language implementation tables.

Revision/Update Information:

This revised manual supersedes the
Introduction to VAX/VMS System
Routines, Version 4.0 (Order No.
AA-Z500A-TE).

Software Version:

VAX/VMS Version 4.4

digital equipment corporation
maynard, massachusetts

April 1986

The information in this document is subject to change without notice and should
not be construed as a commitment by Digital Equipment Corporation. Digital
Equipment Corporation assumes no responsibility for any errors that may appear
in this document.
The software described in this document is furnished under a license and may be
used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment
that is not supplied by Digital Equipment Corporation or its affiliated companies.

Copyright ©1986 by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter

DIBOL
EduSystem
IAS
MASSBUS
PDP
PDT
RSTS
RSX

UNIBUS
VAX
VAXcluster
VMS
VT

SMBBEQ
ZK-2841

HOW TO ORDER ADDITIONAL DOCUMENTATION
DIRECT MAIL ORDERS
USA & PUERTO RICO*

CANADA

INTERNATIONAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire
03061

Digital Equipment
of Canada Ltd.
100 Herzberg Road
Kanata, Ontario K2K 2A6
Attn: Direct Order Desk

Digital Equipment Corporation
PSG Business Manager
c/o Digital's local subsidiary
or approved distributor

In Continental USA and Puerto Rico call 800-258-1710.
In New Hampshire, Alaska, and Hawaii call 603-884-6660.
In Canada call 800-267-6215.
Any prepaid order from Puerto Rico must be placed with the local Digital subsidiary (809-754-7575).
Internal orders should be placed through the Software Distribution Center (SDC), Digital Equipment
Corporation, Westminster, Massachusetts 01473.
This document was prepared using an in-house documentation production system. All page
composition and make-up was performed by T|=X, the typesetting system developed by
Donald E. Knuth at Stanford University. T^X is a registered trademark of the American Mathematical
Society.

Contents
PREFACE

NEW AND CHANGED FEATURES

SECTION 1

DOCUMENTATION FORMAT FOR SYSTEM
ROUTINES

i-i

1.1

OVERVIEW

i-i

1.2

FORMAT HEADING

1-2

1.3

RETURNS HEADING
1.3.1
Condition Values Returned in RO
1.3.2
Data in Registers RO Through R11

_
_

1-5
1-5
1-6
1-7

1.4 ARGUMENTSHEADING
1.4.1
VMS Usage Entry _
1.4.2
Type Entry _
1.4.3
Access Entry _
1.4.4
Mechanism Entry _
1.4.5
Explanatory Text Entry _

1-7
1-7
1 -8
1-9
1-10
1-11

1.5 CONDITION VALUES RETURNED HEADING
1.5.1
Condition Values Returned _
1.5.2
Condition Values Returned in the I/O Status Block _
1.5.3
Condition Values Returned in a Mailbox _
1.5.4
Condition Values Signaled _

1 -12
1-13
1-13
1-14
1-14

1.3.3

Condition Values Signaled

SECTION 2 VAX PROCEDURE CALLING AND CONDITION HANDLING
STANDARD
21
2.1

INTRODUCTION
2.1.1
Goals of the Calling Standard _
2.1.2
Definitions Used in the VAX Calling Standard _

2-1
2-2
2-3

iii

Contents

2.2 CALLING SEQUENCE

2-4

2.3 ARGUMENT LIST
2.3.1
Argument List Format _
2.3.2
Argument Lists and Higher-Level Languages _
2.3.2.1
Order of Argument Evaluation • 2-5
2.3.2.2
Language Extensions for Argument Transmission • 2-6

2-4
2-4
2-5

2.4 FUNCTION VALUE RETURN

2-7

2.5 CONDITION VALUE
2.5.1
Interpretation of Severity Codes _
2.5.2
Use of Condition Values _

2-7
2-10
2-11

2.6 REGISTER USAGE

2-11

2.7 STACK USAGE

2-11

2.8 ARGUMENT DATA TYPES
2.8.1
Atomic Data Types _
2.8.2
String Data Types _
2.8.3
Miscellaneous Data Types _
2.8.4
Facility-Specific Data Type Codes _
2.8.5
Reserved Data Type Codes _
2.8.6
COBOL Intermediate Temporary Data Type _
2.8.7
Varying Character String Data Type
(DSC$K_DTYPE_VT) _

2-12
2-13
2-14
2-16
2-17
2-17
2-17

2.9 ARGUMENT DESCRIPTOR FORMATS
2.9.1
Descriptor Prototype _
2.9.2
Fixed-length Descriptor (DSC$K_CLASS_S) _
2.9.3
Dynamic String Descriptor (DSC$K_CLASS_D) _
2.9.4
Variable Buffer Descriptor (DSC$K_CLASS_V) _
2.9.5
Array Descriptor (DSC$K_CLASS_A) _
2.9.6
Procedure Descriptor (DSC$K_CLASS_P) _
2.9.7
Procedure Incarnation Descriptor (DSC$K_CLASS_PI)
2.9.8
Label Descriptor (DSC$K_CLASS_J) _
2.9.9
Label Incarnation Descriptor (DSC$K_CLASS_JI) _
2.9.10 Decimal String Descriptor (DSC$K_CLASS—SD) _
2.9.11 Noncontiguous Array Descriptor
(DSC$K_CLASS_NCA) _
2.9.12 Varying String Descriptor (DSC$K_CLASS_VS) _

2-18
2-19
2-20
2-20
2-21
2-21
2-24
2-25
2-25
2-25
2-25

2-18

2-26
2-29

Contents

2.9.13 Varying String Array Descriptor
(DSC$ K _C LASS—VS A) _
2.9.14 Unaligned Bit String Descriptor
(DSC$ K _C LASS—U BS) _
2.9.15 Unaligned Bit Array Descriptor (DSC$K_CLASS_UBA)
2.9.16 String with Bounds Descriptor (DSC$K_CLASS—SB) _
2.9.17 Unaligned Bit String with Bounds Descriptor
(DSC$K_CLASS_UBSB) _
2.9.18 Facility-Specific Descriptor Class Codes _
2.9.19 Reserved Descriptor Class Codes _

2.10

2-30
2-32
2-33
2-35
2-36
2-37
2-37

VAX CONDITIONS
2.10.1 Condition Handlers _
2.10.2 Condition Handler Options _

2-37
2-38
2-39

OPERATIONS INVOLVING CONDITION HANDLERS
2.11.1 Establishina a Condition Handler
2.11.2 Reverting to the Caller's Handling
2.11.3 Signaling a Condition

2-39
2-40
2-40
2-40

2.12

PROPERTIES OF CONDITION HANDLERS
2.12.1 Condition Handler Parameters and Invocation _
2.12.2 Use of Memory _
2.12.3 Returning from a Condition Handler _
2.12.4 Request to Unwind _
2.12.5 Signaler's Registers _

2-42
2-42
2-44
2-44
2-44
2-46

2.13

MULTIPLE ACTIVE SIGNALS

2-46

VMS DATA TYPES

A-1

APPENDIX A
A.1

VMS DATA TYPES

A.2

VAX ADA IMPLEMENTATION

A-18

A.3

VAX APL IMPLEMENTATION

A-20

A.4

VAX BASIC IMPLEMENTATION

A-22

A.5

VAX BLISS IMPLEMENTATION

A-26

Contents

A.6

VAX C IMPLEMENTATION

A-29

A.7

VAX COBOL IMPLEMENTATION

A-32

A.8

VAX FORTRAN IMPLEMENTATION

A-35

A.9

VAX MACRO IMPLEMENTATION

A-39

A.10

VAX PASCAL IMPLEMENTATION

A-41

A.11

VAX PL/I IMPLEMENTATION

A-45

A. 12

VAX RPG II IMPLEMENTATION

A-52

A.13

VAX SCAN IMPLEMENTATION

A-54

Argument List Format _
Format of the Condition Value _
Stack Frame Generated by CALLG and CALLS Instructions _
Descriptor Prototype Format _
Fixed-length Descriptor Format _
Dynamic String Descriptor Format _
Array Descriptor Format _
Procedure Descriptor Format _
Decimal String Descriptor Format _
Noncontiguous Array Descriptor Format _
Varying String Descriptor Format _
Varying String Array Descriptor Format _
Unaligned Bit String Descriptor Format _
Unaligned Bit Array Descriptor Format _
String with Bounds Descriptor Format _
Unaligned Bit String with Bounds Descriptor Format _
Format of the Mechanism Argument Vector _
Format of the Signal Argument Vector _

2-4
2-8
2-12
2-19
2-20
2-21
2-22
2-24
2-25
2-27
2-29
2-31
2-32
2-33
2-35
2-36
2-43
2-43

INDEX

FIGURES
2—1
2-2
2—3
2—4
2—5
2—6
2—7
2—8
2—9
2-10
2-11
2—12
2-13
2—14
2—15
2—16
2—17
2-18

Contents

TABLES
1—1
1 —2
1 —3
1— 4
2— 1
2—2
2—3
2—4
A—1
A—2
A—3
A-4
A—5
A—6
A—7
A—8
A—9
A—10
A—11
A—12
A—13

Main Heading in the Documentation Format for System Routines
General Rules of Syntax _
VAX Standard Data Types __
Passing Mechanisms ___
Atomic Data Types ___
String Data Types ___
Miscellaneous Data Types _
Interaction between Handlers and Default Handlers _
VMS Data Types _
VAX Ada Implementation _
VAX APL Implementation _
VAX BASIC Implementation _
VAX BLISS Implementation _
VAX C Implementation _
VAX COBOL Implementation __
VAX FORTRAN Implementation _
VAX MACRO Implementation _
VAX PASCAL Implementation _
VAX PL/I Implementation _
VAX RPG II Implementation _
VAX SCAN Implementation _

1-1
1 -4
1 -8
1-11
2-13
2-15
2-16
2-42
A-2
A-18
A-21
A-23
A-27
A-29
A-32
A-35
A-39
A-42
A-45
A-52
A-54

Preface

Intended Audience
This manual is intended for all programmers who call VAX/VMS-supplied
system routines.

Structure of This Document
This manual contains two sections and an appendix.
•

Section 1 describes the format used to document system routines.

•

Section 2 describes the VAX Procedure Calling and Condition Handling
Standard. This standard explains programming mechanisms that are used
with the VAX hardware procedure call mechanism.

•

Appendix A describes VMS data types, the VMS Usage entry, and the
VAX language implementation tables.

Associated Documents
The following four manuals document the VMS-supplied system routines.
•

VAX/VMS System Services Reference Manual

•

VAX/VMS Run-Time Library Routines Reference Manual

•

VAX Record Management Services Reference Manual

•

VAX/VMS Utility Routines Reference Manual

The VAX-11 Architecture Reference Manual and the VAX Architecture Handbook
also contain information about the VAX architecture and its procedure calling
mechanisms.

Conventions Used in This Document
Convention

Meaning

A symbol with a one- to six-character
abbreviation indicates that you press a key
on the terminal, for example, I RET I.
The phrase CTRL/x indicates that you
must press the key labeled CTRL while you
simultaneously press another key, for example,
CTRL/C, CTRL/Y, CTRL/O.

Convention

Meaning

$ TYPE MYFILE.DAT

Vertical series of periods, or ellipsis, mean
either that not all the data that the system
would display in response to the particular
command is shown or that not all the data a
user would enter is shown.

file-spec,...

Horizontal ellipsis indicates that additional
parameters, values, or information can be
entered.

[logical-name]

Square brackets indicate that the enclosed item
is optional. (However, square brackets are not
optional in the syntax of a directory name in a
file specification or in the syntax of a substring
specification in an assignment statement.)

quotation marks
apostrophes

The term quotation marks is used to refer
to double quotation marks ("). The term
apostrophe (') is used to refer to a single
quotation mark.

New and Changed Features

New VMS Usage Argument Characteristic
All system routines now provide explicit argument characteristics, that is,
type, access, and mechanism information for each argument in a routine
description. A new argument characteristic called the VMS Usage has been
added and is described in this manual. The purpose of the VMS Usage
argument characteristic is to facilitate data declarations in your application
programs. A typical VMS Usage entry is a VMS data type.
A VMS Usage table containing definitions of each VMS data type is provided.

New VAX Language Implementation Tables
Data declaration implementation tables for each VAX language have been
added. Each implementation table matches a VMS data type with a VAX
language data declaration. You can use this data declaration in your
application program.

Documentation Format for System Routines

1.1

Overview
Each system routine is documented using a structured format. This section
discusses the main categories in this format, the information that is presented
under each, and the format used to present the information.
This section explains where to find information and how to read it correctly,
not how to use it. Other sections cover the contents, meaning, and use of the
information.
Note: The documentation format described in this section is generic; portions
of it are used or not used, as appropriate, in the four VAX/VMS manuals
that document system routines.
VAX/VMS System Services Reference Manual
VAX/VMS Run-Time Library Routines Reference Manual
VAX/VMS Utility Routines Reference Manual
VAX Record Management Services Reference Manual
Some main categories in the routine format contain information that requires
no explanation beyond what is given in Table 1-1. However, the following
categories contain information that does require additional discussion, and
this discussion takes place below.
•

Format

•

Returns

•

Arguments

•

Condition Values Returned

Table 1-1

Main Heading in the Documentation Format for
System Routines

Main Heading

Description

Routine Name

Always present. The routine entry point name appears
at the top of the first page. It is usually, though not
always, followed by the English text name of the
routine.

Routine Overview

Always present. The routine overview appears directly
below the routine name; the overview explains, usually
in one or two sentences, what the routine does.

Format

Always present. The format heading follows the
routine overview. The format gives the routine entry
point name and the routine argument list.

1-1

Documentation Format for System Routines

Table 1-1 (Cont.)

Main Heading in the Documentation Format
for System Routines

Main Heading

Description

Returns

Always present. The returns heading follows the
routine format. It explains what information is returned
by the routine.

Arguments

Always present. The arguments heading follows
the returns heading. Detailed information about each
argument is provided under the arguments heading.
If a routine takes no arguments, the word "None”
appears.

Description

Optional. The description heading follows the
arguments heading. The description section contains
information about specific actions taken by the
routine: interaction between routine arguments, if
any; operation of the routine within the context of
VAX/VMS; user privileges needed to call the routine,
if any; system resources used by the routine; and user
quotas that may affect the operation of the routine.
Note that any restrictions on the use of the routine
are always discussed first in the description section;
for example, any required user privileges or necessary
system resources are explained first.
For some simple routines, a description section is not
necessary because the routine overview carries the
needed information.

Condition Values
Returned

Always present. The condition values returned section
follows the description section. It lists the condition
values (typically status or completion codes) that are
returned by the routine.

Example

Optional. The examples heading appears following
the condition values returned heading. The example
section contains one or more programming examples
to illustrate use of the routine. An explanation of the
example follows the example.
All examples have been tested and should run when
compiled (or assembled) and linked. Incomplete
examples and code fragments do not appear under
the examples heading. Throughout the manuals that
document system routines, an effort was made to
provide examples in as many different programming
languages as possible.

1.2

Format Heading
The following three types of information can be present in the format
heading.

1-2

•

Procedure call format

•

JSB (Jump to Subroutine) format

•

Explanatory text

Documentation Format for System Routines

All system routines have a procedure call format, but not all system routines
have JSB formats, in fact, most do not. If a routine has a JSB format, it always
appears after the routine's procedure call format.

Procedure Call Format
The procedure call format ensures that a routine call
conforms to the procedure call mechanism described in
the VAX Procedure Calling and Condition Handling Standard, Section 2;
for example, an entry mask is created, registers are saved, and so on.
Procedure call formats can appear in many forms. Four examples have been
provided to illustrate the meaning of syntactical elements such as brackets
and commas. General rules of syntax governing how to use procedure call
formats are shown in Table 1-2.
Example 1
This example illustrates the standard representation of optional arguments
and best describes the use of commas as delimiters. Arguments enclosed
within square brackets are optional, but if an optional argument other than
a trailing optional argument is omitted, you must include a comma as a
delimiter for the omitted argument.
ENTRY-POINT-NAME

argl [.[arg2 [,arg3]]

Typically, VAX RMS system routines use this format where at most three
arguments appear in the argument list.
Example 2
When the argument list contains three or more optional arguments, the
syntax does not provide enough information. If the optional arguments arg3
and arg4 are omitted and the trailing argument arg5 is specified, commas
must be used to delimit the positions of the omitted arguments.
ENTRY-POINT-NAME

argl farg2 .[arg3] .nullarg [,arg4]

[,arg5]

Typically, VAX/VMS system services, utility routines, and VAX Run-time
Library routines contain call formats with more than three arguments.
Example 3
In the following call format example, the trailing four arguments are optional
as a group, that is, either you specify arg2, arg3, arg4,and arg5 or none of
them. Therefore, if the optional arguments are not specified, commas need
not be used to delimit unoccupied positions.
However, if a hypothetical required argument or a separate optional argument
were specified after arg5, commas must be used when arg2, arg3, arg4, and
arg5 are omitted.
ENTRY-POINT-NAME

argl [,arg2 .arg3 ,arg4 ,arg5]

Example 4
In the following example, you may specify arg2 and omit arg3. However
whenever you specify arg3, you must specify arg2
ENTRY-POINT-NAME

argl [,arg2 [,arg3]]

1-3

Documentation Format for System Routines

JSB Call Format
The JSB call format activates the routine code directly, without the overhead
of constructing the entry mask or saving registers. The JSB call format can be
used only with VAX MACRO and VAX BLISS languages.

Explanatory Text
Explanatory text may follow one or both of the above formats. This text
is present only when needed to clarify the format. For example, the call
format indicates that arguments are optional by enclosing them in brackets
([]). However, brackets alone cannot convey all the important information
that may apply to optional arguments. For example, in some routines that
have many optional arguments, if one optional argument is selected, another
optional argument must also be selected. In such cases, text following the
format clarifies this fact.
Table 1-2

General Rules of Syntax

Element

Syntax Rule

Entry point names

Entry point names are always shown in uppercase
characters.

Argument names

Argument names are always shown in lowercase
characters.

Spaces

One or more spaces are used between the entry
point name and the first argument, and between
each argument.

Braces

Braces surround two or more arguments. You
must choose one of the arguments.

Brackets ([])

Brackets surround optional arguments. Note that
commas too can be optional (see the comma
element).

Commas

Between arguments, the comma always follows
the space. If the argument is optional, the comma
may appear inside the brackets or outside the
brackets, depending on the position of the
argument in the list and on whether surrounding
arguments are optional or required.

Documentation Format for System Routines

Table 1-2 (Cont.)

General Rules of Syntax

Element

Syntax Rule

Null arguments

A null argument is a place-holding argument. It is
used for either of the following reasons: (1 ) to

hold a place in the argument list for an argument
that has not yet been implemented by DIGITAL but
may be in the future or (2) to mark the position
of an argument that was used in earlier versions
of the routine but is not used in the latest version
(upward compatibility is thereby ensured because
arguments that follow the null argument in the
argument list keep their original positions). A null
argument is always given the name nullarg.
In the argument list constructed on the stack when
a procedure is called, both null arguments and
omitted optional arguments are represented by
longword argument list entries containing the value
0 . The programming language syntax required to
produce argument list entries containing 0 differ
from language to language, so see your language
user's guide for language-specific syntax.

1.3

Returns Heading
A description of the information, if any, returned by the routine to the caller
is given in the returns heading. A routine can return information to the caller
in various ways. The subsections that follow discuss each possibility and then
describe how this returned information is presented.

1.3.1

Condition Values Returned in RO
Most routines return a condition value in register RO. This condition
value contains various kinds of information, but most importantly for the
caller, it describes (in bits <3:0> ) the completion status of the operation.
Programmers test the condition value to determine if the routine completed
successfully.
For the purposes of programmers in high-level languages, the fact that status
information is returned by means of a condition value and that it is returned
in a VAX register is of little importance because the high-level language
programmer receives this status information in the return (or status) variable.
The run-time environment established for the high-level language program
allows the status information in RO to be moved automatically to the user's
return variable.
Nevertheless, for routines that return a condition value in RO, the returns
heading in the documentation will contain the following information:
VMS Usage:
type:
access:
mechanism:

longword_imsigned
longword (unsigned)
write only
by value

1-5

Documentation Format for System Routines

The VMS Usage entry specifies the VMS data type of the information returned.
Since the data type of a condition value in the VMS operating system
environment is an unsigned longword, the VMS Usage entry is longword—
unsigned.
The type entry specifies the data type of the information returned. Since the
data type of a condition value is an unsigned longword, the type heading is
longword (unsigned).
The access entry specifies the way in which the called routine accesses the
object. Since the called routine is returning the condition value, it is writing
into this longword; so the access heading is write only.
The mechanism heading specifies the passing mechanism used by the called
routine in returning the condition value. Since the called routine is writing
the condition value directly into RO, the mechanism heading is by value. (If
the called routine had written the address of the condition value into RO, the
passing mechanism would have been by reference.)
Note that if a routine returns a condition value in RO, another main heading
in the documentation format (Condition Values Returned) describes the
possible condition values that the routine can return.

1.3.2

Data in Registers RO Through R11
Some routines return actual data in the VAX registers. The number of
registers needed to contain the data depends on the length (or data type)
of the information being returned. For example, a Run-Time Library
mathematics routine that is returning the cosine of an angle as a G—floating
point number would use registers RO and R1 because the length of a G_
floating point number is two longwords.
If a routine returns actual data in one or more of the registers RO through
Rll, the returns heading in the documentation of that routine will contain the
following information:
VMS Usage:
type:
access:
mechanism:

floating_point
G_floating
write only
by value

For example, for the mathematics routine discussed above, the VMS data type
is floating-point and the VAX standard data type would be G_floating point.
The meaning of the contents of the access and mechanism headings are as
discussed in Sections 1.4.3 and 1.4.4.
In addition, under the Returns heading, following the information about the
type, access, and mechanism, some text may be provided. This text explains
other relevant information about what the routine is returning.
For example, since the routine is returning actual data in the VAX registers,
the registers cannot be used to convey completion status information. All
routines that return actual data in VAX registers must signal the condition
value, which contains the completion status. Thus, the text under the returns
heading will point out that the routine signals its completion status.

Documentation Format for System Routines

1.3.3

Condition Values Signaled
Though most routines return condition values in RO, some routines choose to
signal their condition values using the VAX Signaling Mechanism. Routines
can signal their completion status whether or not they are returning actual
data in the VAX registers. But all routines that return actual data in the VAX
registers must signal their completion status if they are to return this status
information at all.
If a routine signals its completion status, text under the returns heading
explains this fact, and another main heading in the documentation format
(Condition Values Signaled) describes the possible condition values that the
routine can signal.
DIGITAL'S system routines never signal condition values indicating success.
Only error condition values are signaled.

1.4

Arguments Heading
Detailed information about each argument listed in the call format under
the arguments heading. Arguments are described in the order in which they
appear in the call format. If the routine has no arguments, the word "None"
appears.
The following format is used to describe each argument.
argument-name
VMS Usage:
VMS data
type:
argument
access:
argument
mechanism:
argument

type
data type
access
passing mechanism

One paragraph of structured text is followed by other paragraphs of text, as
needed.

1.4.1

VMS Usage Entry
The purpose of the VMS Usage entry is to facilitate the coding of source
language data type declarations in application programs. As mentioned
earlier, argument data types are described in two ways:
•

VMS data type

•

VAX standard data type

The VAX standard data type is described below in Section 1.4.2. Ordinarily,
the VAX standard data type would be sufficient to describe the type of
data passed by an argument. However, within the VMS operating system
environment, many system routines contain arguments whose conceptual
nature or complexity or both require additional explanation. For instance,
when an argument passes the name of an array by reference, the type entry
longword (unsigned) alone does not indicate that a data structure argument
is being referenced. In this particular instance, an accompanying VMS Usage
entry, denoting a VMS data type, vector_longword_unsigned further
explains that an array of unsigned longwords must be declared.
Note: The VMS Usage entry is NOT a traditional data type such as the VAX
standard data types byte, word, longword and so on. It is significant only
within the context of the VMS operating system environment and is
intended solely to expedite data declarations within application programs.

1-7

Documentation Format for System Routines

Table A-l in Appendix A lists possible VMS Usage entries and their
definitions.
See the appropriate VAX language implementation table (Tables A-2
through A-13) in Appendix A to determine the correct syntax of the type
declaration, in the language you are using.

1.4.2

Type Entry
Properly speaking, an argument does not have a data type; rather, the data
specified by an argument has a data type. The argument is merely the vehicle
for the passing of data to the called routine.
As described in the VAX Procedure Calling and Condition Handling Standard
in Section 2 of this manual, procedure calls result in the construction of
an argument list on the stack. This argument list is a vector of longwords.
The first longword on the list contains a count of the number of remaining
longwords, and each remaining longword is one argument. Thus, an argument
is one longword in the argument list.
Nevertheless, the phrase argument data type is frequently used to describe the
data type of the data that is specified by the argument. This terminology is
used because it is simpler and more straightforward than the strictly accurate
phrase data type of the data specified by the argument.
Table 1-3 gives each VAX standard data type that may appear for the type
entry in an argument description. The second column of the list gives the
VAX/VMS-defined symbolic code for the data type in column one. These
symbolic codes are used in descriptors.
See Section 2.8 for a detailed description of each of the following symbolic
codes.
Table 1-3

1—8

VAX Standard Data Types

Data Type

Symbolic Code

Absolute date and time

DSC$K_DTYPE—ADT

Byte integer (signed)

DSC$K_DTYPE—B

Bound label value

DSC$K_DTYPE—BLV

Bound procedure value

DSC$K_DTYPE—BPV

Byte (unsigned)

DSC$K_DTYPE—BU

COBOL intermediate temporary

DSC$K_DTYPE—CIT

D_floating

DSC$K_DTYPE—D

D_floating complex

DSC$K_DTYPE—DC

Descriptor

DSC$K_DTYPE—DSC

F_floating

DSC$K_DTYPE—F

F_floating complex

DSC$K_DTYPE—FC

G—floating

DSC$K_DTYPE—G

G_floating complex

DSC$K_DTYPE—GC

H—floating

DSC$K_DTYPE—H

H_floating complex

DSC$K_DTYPE—HC

Documentation Format for System Routines

Table 1-3 (Cont.)

1.4.3

VAX Standard Data Types

Data Type

Symbolic Code

Longword integer (signed)

DSC$K_DTYPE_L

Longword (unsigned)

DSC$K_DTYPE_LU

Numeric string, left separate sign

DSC$K_DTYPE_NL

Numeric string, left overpunched sign

DSC$K_DTYPE_NLO

Numeric string, right separate sign

DSC$K_DTYPE_NR

Numeric string, right overpunched sign

DSC$K_DTYPE_NRO

Numeric string, unsigned

DSC$K_DTYPE_NU

Numeric string, zoned sign

DSC$K_DTYPE_NZ

Octaword integer (signed)

DSC$K_DTYPE_0

Octaword (unsigned)

DSC$K_DTYPE_OU

Packed decimal string

DSC$K_DTYPE_P

Quadword integer (signed)

DSC$K_DTYPE_Q

Quadword (unsigned)

DSC$K_DTYPE_QU

Character string

DSC$K_DTYPE_T

Aligned bit string

DSC$K_DTYPE_V

Varying character string

DSC$K_DTYPE_VT

Unaligned bit string

DSC$K_DTYPE_VU

Word integer (signed)

DSC$K_DTYPE_W

Word (unsigned)

DSC$K_DTYPE_WU

Unspecified

DSC$K_DTYPE_Z

Procedure entry mask

DSC$K_DTYPE_ZEM

Sequence of instruction

DSC$K_DTYPE_ZI

Access Entry
The access entry describes the way in which the called routine accesses
the data specified by the argument, or access method. The following three
methods of access are the most common.
•

Read only. Data upon which a routine operates, or data needed by the
routine to perform its operation, must be read by the called routine. Such
data is also called input data. When an argument specifies input data, the
access entry is read only.
The term only is present to indicate that the called routine does not both
read and write (that is, modify) the input data. Thus, input data supplied
by a variable is preserved when the called routine completes execution.

•

Write only. Data that the called routine returns to the calling routine must
be written into a location where the calling routine can access it. Such
data is also called output data. When an argument specifies output data,
the access entry is write only.
In this context, the term only is present to indicate that the called routine
does not read the contents of the location either before or after it writes
into the location.

1-9

Documentation Format for System Routines

•

Modify. When an argument specifies data that is both read and written
by the called routine, the access entry is modify. In this case, the
called routine reads the input data, which it uses in its operation, and
then overwrites the input data with the results (the output data) of the
operation. Thus, when the called routine completes execution, the input
data specified by the argument is lost.

The following is a complete list of access methods that may
appear under the access entry in an argument description; see
the VAX Procedure Calling and Condition Handling Standard, in Section 2 of
this manual for more information.

1.4.4

•

Read only

•

Write only

•

Modify

•

Function call (before return)

•

JMP after unwind

•

Call after stack unwind

•

Call without stack unwind

Mechanism Entry
The way in which an argument specifies the actual data to be used by the
called routine is defined in terms of the argument passing mechanism. There
are three basic passing mechanisms.
•

By value. When the longword argument in the argument list contains the
actual data to be used by the routine, the actual data is said to be passed
to the routine by value. In this case, the longword argument contains the
actual data; in other words, the argument is the actual data. Note that
since an argument is only one longword in length, only data that can be
represented in one longword can be passed by value.

•

By reference. When the longword argument in the argument list contains
the address of the data to be used by the routine, the data is said to be
passed by reference. In this case, the argument is a pointer to the data.

•

By descriptor. When the longword argument in the argument list contains
the address of a descriptor, the data is said to be passed by descriptor.
A descriptor consists of two or more longwords (depending on the type
of descriptor used), which describe the location, length, and the VAX
standard data type of the data to be used by the called routine. In this
case, the argument is a pointer to a descriptor that itself is a pointer to the
actual data.
There are several types of descriptors. Each descriptor contains a value, or
class type, in the fourth byte of the first longword. The class type identifies
the type of descriptor it is. Each class type has a symbolic code.

Table 1-4 lists each passing mechanism that may appear under the
mechanism entry in an argument description. When the passing mechanism
is by descriptor, the second column in the list gives the symbolic code for
the descriptor class type, except in the case where the passing mechanism
in column one is by descriptor. In this case, no symbolic code appears in

1-10

Documentation Format for System Routines

column two because the class type of the descriptor must be determined by
reading the class-type field of the descriptor itself.
Table 1-4

Passing Mechanisms

Passing Mechanism

Descriptor Code

By value

By reference

By reference, array reference

By descriptor

see above paragraph

By descriptor, fixed-length

DSC$K_CLASS_S

By descriptor, dynamic string

DSC$K_CLASS_D

By descriptor, array

DSC$K_CLASS_A

By descriptor, procedure

DSC$K_CLASS_P

By descriptor, decimal string

DSC$K_CLASS_SD

By descriptor, noncontiguous array

DSC$K _CLASS—NCA

By descriptor, varying string

DSC$K_CLASS_VS

By descriptor, varying string array

DSC$K_CLASS_VSA

By descriptor, unaligned bit string

DSC$K_CLASS_UBS

By descriptor, unaligned bit array

DSC$K_CLASS_UBA

By descriptor, string with bounds

DSC$K_CLASS_SB

By descriptor, unaligned bit string with bounds

DSC$K_CLASS_UBSB

See Section 2.9 for a detailed description of each descriptor class type.

1.4.5

Explanatory Text Entry
For each argument, one or more paragraphs of explanatory text follows the
VMS Usage, type, access, and mechanism entries. The first paragraph is
highly structured and always contains information in the following sequence.
1

A sentence fragment that describes (1) the nature of the data specified
by the argument and (2) the way in which the routine uses this data.
For example, if an argument were supplying a number, which the routine
converts to another data type, the argument description would contain the
following sentence fragment.
Integer to be converted to an F_floating point number

A sentence expressing the relationship between the argument and the data
that it specifies. This relationship is the passing mechanism used to pass
the data and, for a given argument, is expressed in one of the following
ways:
•

If the passing mechanism is by value, the sentence should read as
follows:
The attrib argument is a longword that contains (or is) the
bit mask specifying the attributes.

1-11

Documentation Format for System Routines

•

If the passing mechanism is by reference, the sentence should read as
follows:
The objtyp argument is the address of a longword
containing a value indicating whether the object is a
file or a device.

•

If the passing mechanism is by descriptor, the sentence should read as
follows:
The devnam argument is the address of a string descriptor
of a logical name denoting a device name.

3 Additional explanatory paragraphs appear for each argument as needed.
For example, some arguments specify complex data consisting of many
discrete fields, each of which has a particular purpose and use. In such
cases, additional paragraphs provide detailed descriptions of each such
field, symbolic names for the fields, if any, and guidance on their use.

1.5

Condition Values Returned Heading
A condition value is an unsigned longword that has several uses in the VAX
architecture.
•

To indicate the success or failure of a called procedure.

•

To describe an exception condition when an exception is signaled.

•

To identify system messages.

•

To report program success or failure to the command level.

Figure 2-2 depicts the format and contents of the longword condition value,
and Section 2.5 decribes these contents and explains in detail the uses of the
condition value.
The documentation heading "Condition Values Returned" describes the
condition values returned by the routine when it completes execution
without generating an exception condition. This condition value describes
the completion status of the operation.
If a called routine generates an exception condition during execution, the
exception condition is signaled; the exception condition is then handled by
a condition handler (either user-supplied or system-supplied). Depending
on the nature of the exception condition and on the condition handler that
handles the exception condition, the called routine will either continue normal
execution or terminate abnormally.
If a called routine executes without generating an exception condition, the
called routine returns a condition value in one or two of four possible ways
as follows:
•

Condition Values Returned

•

Condition Values Returned in the I/O Status Block

•

Condition Values Returned in a Mailbox

•

Condition Values Signaled

In the documentation of each routine, the method used to return the condition
value is indicated. Under the Condition Values Returned heading, these
methods are discussed individually in the following subsections.

1-12

Documentation Format for System Routines

Under either of these headings, a two-column list gives the symbolic code
for each condition value that the routine can return and its accompanying
description. This description explains whether the condition value indicates
success or failure, and if failure, what user action may have caused the failure
and what can be done to correct it. Condition values that indicate success are
listed first.
Symbolic codes for condition values are system defined. The symbolic code
defined for each condition value equates to a number that is identical to the
longword condition value when interpreted as a number. In other words,
though the condition value consists of several fields, each of which can
be interpreted individually for specific information, the entire longword
condition value itself can be interpreted as an unsigned longword integer, and
this integer has an equivalent symbolic code.
The following three subsections discuss the three ways in which the called
routine returns condition values.

1.5.1

Condition Values Returned
The possible condition values that the called routine can return in general
register RO are listed under the "Condition Values Returned" heading in the
documentation. Most routines return a condition value in this way.
In the documentation of system services that complete asynchronously, both
the "Condition Values Returned" and "Condition Values Returned in the I/O
Status Block" are used. Under the "Condition Values Returned" heading, the
condition values returned by the asynchronous service refer to the success
or failure of the system service request; that is, to the status associated
with the correctness of the syntax of the call, in contrast to the final status
associated with the completion of the service operation. For asynchronous
system services, condition values describing the success or failure of the
actual service operation, that is, the final completion status, are listed under
the "Condition Values Returned in the I/O Status Block" heading.

1.5.2

Condition Values Returned in the I/O Status Block
The possible condition values that the called routine can return in an I/O
status block, are listed under the "Condition Values Returned in the I/O
Status Block" heading in the documentation.
The routines that return condition values in the I/O status block are the
system services that complete asynchronously. Each of these asynchronous
system services returns to the caller immediately after the call to the service
is successfully queued but before the operation to be performed by the
service has completed. This allows the calling program to continue execution
while the system service itself is executing. System services that complete
asynchronously all have arguments that specify an I/O status block. When
the system service operation has completed, a condition value specifying the
completion status of the operation is written in the first word of this I/O
status block.
Representing a longword condition value in a word-length field is possible for
system services because the high-order word in all system service condition
values is 0 . Section 2.5 explains the contents of the fields in the longword
condition value in detail.

1-13

Documentation Format for System Routines

1.5.3

Condition Values Returned in a Mailbox
The possible condition values that the called routine can return in a mailbox
are listed under the "Condition Values Returned in a Mailbox" heading.
Routines such as SYS$SNDOPR that return condition values in a mailbox
send information to another process to perform a task. The receiving process
performs the action and returns the status of the task to the sending process's
mailbox.

1.5.4

Condition Values Signaled
The possible condition values that the called routine can signal (instead
of returning them in RO) are listed under the "Condition Values Signaled"
heading.
Routines that signal condition values as a way of indicating the completion
status do so because these routines are returning actual data in one or more
of the general registers. Since register RO is used to convey data, it cannot
also receive the condition value.
As mentioned, the signaling of condition values occurs whenever a routine
generates an exception condition, regardless of how the routine returns its
completion status under normal circumstances.

1-14

VAX Procedure Calling and Condition
Handling Standard

13 March 1984 - Version 9.4

Introduction
The VAX Procedure Calling Standard is used with the VAX hardware
procedure call mechanism. This standard applies to
•

All externally callable interfaces in DIGITAL-supported, standard system
software

•

All intermodule CALLs to major VAX components

•

All external procedure CALLs generated by standard DIGITAL language
processors

This standard does not apply to calls to internal (local) routines, or language
support routines. Within a single module, the language processor or
programmer can use a variety of other linkage and argument-passing
techniques.
The standard defines mechanisms for passing arguments by immediate value,
by reference, and by descriptor. However, the immediate value mechanism
is intended for use only by VAX/VMS system services and within programs
written in VAX BLISS or VAX MACRO.
The procedure CALL mechanism depends on agreement between the calling
and called procedures to interpret the argument list. The argument list does
not fully describe itself. This standard requires language extensions to permit
a calling program to generate some of the argument passing mechanisms
expected by called procedures.
This standard specifies the following attributes of the interfaces between
modules:
•

Calling sequence—The instructions at the call site and at the entry point

•

Argument list—The structure of the list describing the arguments to the
called procedure

•

Function value return—The form and conventions for the return of the
function value as a value or as a condition value to indicate success or
failure

•

Stack usage—Rules governing the use of the stack

•

Argument data types—The data types of arguments that can be passed

•

Argument descriptor formats—How descriptors are passed for the more
complex arguments

2-1

VAX Procedure Calling and Condition Handling Standard

2.1.1

•

Condition handling—How exception conditions are signaled and how
they can be handled in a modular fashion

•

Stack unwinding—How the current thread of execution can be aborted
cleanly

Goals of the Calling Standard
In developing the VAX Procedure Calling Standard, the following goals were
kept in mind:
•

The standard must be applicable to all intermodule callable interfaces in
the VAX software system. Specifically, the standard must consider the
requirements of VAX MACRO, VAX BLISS, VAX BASIC, VAX COBOL,
VAX CORAL, VAX FORTRAN, VAX PASCAL, VAX PEARL, VAX PL/I,
VAX RPG II, and CALLs to the operating system and library procedures.
The needs of other languages that DIGITAL may support in the future
must be met by the standard or by compatible revision of it.

•

The standard should not include capabilities for lower-level components
(such as VAX BLISS, VAX MACRO, operating system) that cannot be
invoked from the higher-level languages.

•

The calling program and called procedure can be written in different
languages. The standard attempts to reduce the need for use of language
extensions for mixed-language programs.

•

The procedure mechanism must be sufficiently economical in both space
and time to be used and usable as the only calling mechanism within
VAX.

•

The standard should contribute to the writing of error-free, modular,
and maintainable software. Effective sharing and reuse of VAX software
modules are significant goals.

•

The standard must allow the called procedure a variety of techniques for
argument handling. Specifically, the called procedure can:
— Reference arguments indirectly through the argument list
— Copy atomic data types, strings, and arrays
— Copy addresses of atomic data types, strings, and arrays

•

The standard should provide the programmer with some control over
fixing, reporting, and flow of control on hardware and software exceptions.

•

The standard should provide subsystem and application writers with the
ability to override system messages to provide a more suitable application
oriented interface.

•

The standard should add no space or time overhead to procedure calls and
returns that do not establish handlers and should minimize time overhead
for establishing handlers at the cost of increased time overhead when
exceptions occur.

Some possible attributes of a procedure calling mechanism were considered
and rejected. Specific attributes rejected for the VAX procedure CALL
mechanism include the following:
•

2-2

It is not necessary for the procedure mechanism to provide complete
checking of argument data types, data structures, and parameter access.

VAX Procedure Calling and Condition Handling Standard

The VAX protection and memory-management system is not dependent
upon correct interactions between user-level calling and called procedures.
Such extended checking may be desirable in some circumstances, but
system integrity is not dependent upon it.
•

2.1.2

The VAX procedure mechanism need not provide complete information
for an interpretive DEBUG facility. The definition of the DEBUG facility
includes a DEBUG symbol table that contains the required descriptive
information.

Definitions Used in the VAX Calling Standard
A procedure is a closed sequence of instructions that is entered from and
returns control to the calling program.
A function is a procedure that returns a single value according to the standard
conventions for value returning. If additional values are returned, they are
returned by means of the argument list.
A subroutine is a procedure that does not return a known value according to
the standard conventions for value returning. If values are returned, they are
returned by means of the argument list.
An address is a 32-bit VAX address positioned in a longword item.
An argument list is a vector of longwords that represents a procedure
parameter list and possibly a function value.
Immediate value is a mechanism for passing input parameters in which the
actual value is provided in the longword argument list entry by the calling
program.
Reference is a mechanism for passing parameters in which the address of the
parameter is provided in the longword argument list by the calling program.
Descriptor is a mechanism for passing parameters in which the address of a
descriptor is provided in the longword argument list entry. The descriptor
contains the address of the parameter, the data type, size, and additional
information needed to describe fully the data passed.
An exception condition is a hardware- or software-detected event that alters
the normal flow of instruction execution. It usually indicates a failure.
A condition value is a 32-bit value used to identify uniquely an exception
condition. A condition value may be returned to a calling program as a
function value or signaled using the VAX signaling mechanism.
Language support procedures are called implicitly to implement higher-level
language constructs. They are not intended to be called explicitly from user
programs.
Library procedures are called explicitly using the equivalent of a CALL
statement or function reference. They are usually language independent.

2-3

VAX Procedure Calling and Condition Handling Standard

2.2

Calling Sequence
At the option of the calling program, the called procedure is invoked using
either the CALLG or CALLS instruction as shown below.
CALLG
CALLS

arglst, proc
argent, proc

CALLS pushes the argument count argent onto the stack as a longword and
sets the argument pointer, AP, to the top of the stack. The complete sequence
using CALLS is shown below.
push

argn

push
CALLS

argl
#n, proc

If the called procedure returns control to the calling program, control must
return to the instruction immediately following the CALLG or CALLS
instruction. Skip returns and GOTO returns are only allowed during stack
unwind operations.
The called procedure returns control to the calling program by executing the
return instruction, RET.

2.3

Argument List
The argument list is the primary means of passing information to and
receiving results from a procedure.

2.3.1

Argument List Format
Figure 2-1 shows the argument list format.
Figure 2-1

Argument List Format

.arglst

arg 1
arg 2
argn
ZK-1885-84

The first longword is always present and contains the argument count as
an unsigned integer in the low byte. The 24 high-order bits are reserved
to DIGITAL and must be zero. To access the argument count, the called
procedure must ignore the reserved bits and access the count as an unsigned
byte (for example MOVZBL, TSTB, or CMPB).
The remaining longwords can be one of the following:
•

2-4

An uninterpreted 32-bit value (by immediate value mechanism). If the
called procedure expects fewer than 32 bits, it accesses the low-order bits
and ignores the high-order bits.

VAX Procedure Calling and Condition Handling Standard

•

An address (by reference mechanism). It is typically a pointer to a scalar
data item, an array, a structure, a record, or a procedure.

•

An address of a descriptor (by descriptor mechanism). See Section 2.9 for
descriptor formats.

The standard permits by immediate value, by reference, by descriptor, or
combinations of these mechanisms. Interpretation of each argument list entry
depends on agreement between the calling and called procedures. Higherlevel languages use the reference or descriptor mechanisms for passing input
parameters. VAX/VMS system services and VAX MACRO or VAX BLISS
programs use all three mechanisms.
A procedure with no arguments is called with a list consisting of a 0 argument
count longword as shown below.
CALLS

#0, proc

A missing or null argument, for example CALL SUB(A„B), is represented by
an argument list entry consisting of a longword 0. Some procedures allow
trailing null arguments to be omitted, others require all arguments. See each
procedure's specification for details.
The argument list must be treated as read-only data by the called procedure
and may be allocated in read-only memory at the option of the calling
program.

2.3.2

Argument Lists and Higher-Level Languages
Functional notations for procedure calls in higher-level languages are mapped
into VAX argument lists according to the following rules:

2.3.2.1

•

Arguments are mapped from left to right to increasing argument list
offsets. The left-most (first) argument has an address of arglst+4; the next
has an address of arglst+8; and so on. The only exception to this is when
arglst+4 specifies where a function value is to be returned, in which case
the first argument has an address of arglst+8; the second argument, an
address of arglst+12; and so on. See Section 2.4 for more information.

•

Each argument position corresponds to a single VAX argument list entry.

Order of Argument Evaluation
Since most higher-level languages do not specify the order of evaluation (with
respect to side effects) of arguments, those language processors can evaluate
arguments in any convenient order.
In constructing an argument list on the stack, a language processor can
evaluate arguments from right to left and push their values on the stack. If
call-by-reference semantics are used, argument expressions can be evaluated
from left to right, with pointers to the expression values or descriptors being
pushed from right to left.
The choice of argument evaluation order and code generation strategy is
constrained only by the definition of the particular language. Programs that
depend on the order of evaluation of arguments should not be written.

2-5

VAX Procedure Calling and Condition Handling Standard

2.3.2.2

Language Extensions for Argument Transmission
The VAX Procedure Calling Standard permits arguments to be passed by
immediate value, by reference, or by descriptor. All language processors,
except VAX MACRO and VAX BLISS, pass arguments by reference or
descriptor by default.
Language extensions are needed to reconcile the different argument passing
mechanisms. In addition to the default passing mechanism used, each
language processor is required to give the user explicit control, in the calling
program, of the argument passing mechanism for the data types supported by
the language.
The value. Yes, means the language processor is required to provide the user
explicit control of that passing mechanism.
Data Type

Section

Value

Reference

Descriptor

Atomic <= 32 bits

2.8.1

Yes

Atomic > 32 bits

2.8.1

Yes

String

2.8.2

Yes

Miscellaneous

2.8.3

No1

Array

2.9

Yes

1 For those languages supporting the bound procedure value data type, a
language extension is required to pass it by immediate value in order to be able
to interface with VMS system services and other software. See Section 2.8.3
For example, VAX FORTRAN provides the following intrinsic compile-time
functions:
%VAL(arg)

By immediate value mechanism. Corresponding argument list
entry is the 32-bit value of the argument, arg, as defined in the
language.

%REF(arg)

By reference mechanism. Corresponding argument list entry
contains the address of the value of the argument, arg, as
defined in the language.

%DESCR(arg)

By descriptor mechanism. Corresponding argument list entry
contains the address of a VAX descriptor of the argument, arg,
as defined in Section 2.9 and in the language.

These intrinsic functions can be used in the syntax of a procedure call to
control generation of the argument list. For example:
CALL SUBl(%VAL(123) , 7.REF(X) , */,DESCR(A))

In other languages the same effect might be achieved by appropriate attributes
of the declaration of SUB1 made in the calling program. Thus, the user might
write
CALL SUBl (123, X, A)

after making the external declaration for SUBl.

2-6

VAX Procedure Calling and Condition Handling Standard

2.4

Function Value Return
A function value is returned in register RO if its data type can be represented
in 32 bits, or in registers RO and R1 if its data type can be represented in 64
bits, provided the data type is not a string data type (see Section 2.8.2).
If the data type requires fewer than 32 bits, then R1 and the high-order bits
of RO are undefined. If the data type requires 32 or more bits but fewer than
64 bits, then the high-order bits of R1 are undefined. Two separate 32-bit
entities cannot be returned in RO and R1 because higher-level languages
cannot process them.
In all other cases (the function value needs more than 64 bits, the data type is
a string data type, the size of the value can vary from call to call, and so on)
the actual argument list and the formal argument list are shifted one entry.
The new, first entry is reserved for the function value. In this case, one of the
following mechanisms is used to return the function value:
•

If the maximum length of the function value is known (for example,
octaword integer, H —floating, or fixed-length string), the calling program
can allocate the required storage and pass the address of the storage or a
descriptor for the storage as the first argument.

•

If the maximum length of a string function value is not known to the
calling program, the calling program can allocate a dynamic string
descriptor. The called procedure then allocates storage for the function
value and updates the contents of the dynamic string descriptor using VAX
Run-Time Library procedures. See Section 2.9.3.

Some procedures, such as operating system calls and many library procedures,
return a success/failure value as a longword function value in RO. Bit <0>
of the value is set (Boolean true) for a success and clear (Boolean false) for a
failure. The particular success or failure status is encoded in the remaining 31
bits, as described in Section 2.5.

2.5

Condition Value
VAX uses condition values for the following reasons:
•

To indicate the success or failure of a called procedure as a function value

•

To describe an exception condition when an exception is signaled

•

To identify system messages

•

To report program success or failure to the command language level

A condition value is a longword that includes fields to describe the software
component generating the value, the reason the value was generated, and the
error severity status. Figure 2-2 shows the format of the condition value.

2-7

VAX Procedure Calling and Condition Handling Standard

Figure 2-2

Format of the Condition Value

3
1

2
7

2
8

3
condition identification

cntrl

0
severity

1
6

2
7

1
5

3
message number

facility number

/K-1886-84

Fields in the Condition Value
condition identification
Identifies the condition uniquely on a system-wide basis.
facility
Identifies the software component generating the condition value. Bit <27>
is set for customer facilities and clear for DIGITAL facilities.
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 system-wide
status codes.
severity
Indicates success or failure. The severity code bit <0> is set for success
(logical true) and 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

warning

STS$K_SUCCESS

success

STS$K_ERROR

error

STS$K_INFO

information

STS$K_SEVERE

severe_error

reserved to DIGITAL

Section 2.5.1 describes the severity code more fully.

2-8

VAX Procedure Calling and Condition Handling Standard

cntrl
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 that
the condition has been either printed or suppressed). Bits <31:29> must be
zero; they are reserved for future use by DIGITAL.
Software symbols are defined for these fields as follows:
Symbol

Value

Meaning

Field

STS$V_COND_ID

position of 27:3

condition identification

STS$S_COND_ID

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

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

position of 27:16

facility number

STS$S_FAC_NO

size of 27:16

facility number

STS$M_FAC_NO

mask

mask for 27:16

facility number

STS$V_CUST_DEF

position for 27

customer facility

STS$S_CUST_DEF

size for 27

customer facility

STS$M_CUST_DEF

1@27

mask for 27

customer facility

STS$V_MSG_NO

position of 15:3

message number

STS$S_MSG_NO

size of 15:3

message number

STS$M_MSG_NO

mask

mask for 15:3

message number

STS$V_FAC_SP

position of 15

facility specific

STS$S_FAC_SP

size for 15

facility specific

STS$M_FAC_SP

1@15

mask for 15

facility specific
message code

STS$V_CODE

position of 14:3

STS$S_CODE

size of 14:3

message code

STS$M_CODE

mask

mask for 14:3

message code

STS$V_SEVERITY

position of 2:0

severity

STS$S_SEVERITY

size of 2:0

severity

STS$M_SEVERITY

mask for 2:0

severity

STS$V_SUCCESS

position of 0

success

STS$S_SUCCESS

size of 0

success

STS$M —SUCCESS

mask for 0

success

2-9

VAX Procedure Calling and Condition Handling Standard

2.5.1

Interpretation of Severity Codes
A severity code of 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.
A severity code of 1 indicates that the procedure generating the condition
value completed successfully, that is, as expected.
A severity code of 2 indicates that an error has occurred, but that the
procedure did produce output. Execution can continue but the results
produced by the component generating the condition value are not all correct.
A severity code of 3 indicates that the procedure generating the condition
value successfully completed, but has some parenthetical information to be
included in a message if the condition is signaled.
A severity code of 4 indicates that a severe_error occurred and the component
generating the condition value was unable to produce output.
When designing a procedure, the choice of severity code for its condition
values should be based 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 success and information as
successes.

•

If the condition value is signaled (see Section 2.11.3), the default handler
treats severe errors as reason to terminate and all the others as the basis
for attempting to continue.

•

When the program image exits, the command interpreter by default treats
errors and severe errors as the basis for stopping the job, and warnings,
information, and successes as the basis for continuing.

The following table summarizes the default interpretation of condition values.

Severity

Routine

Signal

Default at
Program Exit

Success

Normal

Continue

Information

Normal

Continue

Warning

Failure

Continue

Error

Failure

Continue

Stop job

Severe error

Failure

Exit

Stop job

The default for signaled messages is to output a message to file
SYS$OUTPUT. In addition, for severities other than success (STS$K_
SUCCESS), a copy of the message is made on file 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 both files 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 either
success or severe error as its severity for each condition value.

2-10

VAX Procedure Calling and Condition Handling Standard

2.5.2

Use of Condition Values
VAX software components return condition values when they complete
execution. When a severity code of warning, error, or severe error is
generated, the status code describes the nature of the problem. This value
can be tested to change the flow of control of a procedure and/or be used to
generate a message.
User procedures can also generate condition values to be examined by other
procedures and by the command interpreter. User-generated condition values
should have bits <27> and <15> set; in this way, they will not conflict
with values generated by DIGITAL.

2.6

Use

Program counter.

Stack pointer.

Current stack frame pointer. It must always point at the current
frame. No modification is permitted within a procedure body.

Argument pointer. When a call occurs, AP must point to a valid
argument list. A procedure without parameters points to an
argument list consisting of a single longword containing the value 0.

Environment value. When a procedure that needs an environment
value is called, the calling program must set R1 to the environment
value. See bound procedure value in Section 2.8.3.

R0,R1

Function value return registers. These registers are not to be
preserved by any called procedure. They are available to any called
procedure as temporary registers.

Registers R2 through Rll are to be preserved across procedure calls.
The called procedure can use these registers provided that it saves and
restores them using the procedure entry mask mechanism. The entry mask
mechanism must be used so that any stack unwinding done by the condition
handling mechanism will restore all registers correctly. In addition, PC, SP,
FP, and AP are always preserved by the CALL instructions and restored by
the RET instruction. However, AP can be used as a temporary register by a
called procedure.

2.7

Stack Usage
Figure 2-3 shows the contents of the stack frame that is created for the called
procedure by the CALLG or CALLS instructions.

2-11

VAX Procedure Calling and Condition Handling Standard

Figure 2-3

Stack Frame Generated by CALLG and CALLS
Instructions

condition handler (0)
mask/PSW
AP
FP
PC
R2
(optional)

Rll

:(SP):(FP))

(optional)

FP always points at the condition handler longword of the stack frame.
Other uses of FP within a procedure is prohibited. See Section 2.10 for more
information.
The contents of the stack located at addresses higher than the mask/PSW
longword belong to the calling program; they should not be read or written
by the called procedure, except as specified in the argument list. The contents
of the stack located at addresses lower than SP belong to interrupt and
exception routines; they are continually and unpredictably modified.
The called procedure allocates local storage by subtracting the required
number of bytes from the SP provided on entry. This local storage is freed
automatically by the RET instruction.
Bit <28> of the mask/PSW longword is reserved to DIGITAL for future
extensions to the stack frame.

2.8

Argument Data Types
Each data type implemented for a higher-level language uses one of the
following VAX data types for procedure parameters and elements of file
records. When existing data types are not sufficient to satisfy the semantics of
a language, new data types will be added to this standard, including certain
language-specific ones.
Data types fall into three categories:
•

Atomic

•

String

•

Miscellaneous

These data types can generally be passed by immediate value (if 32 bits or
less), by reference, or by descriptor.
The encoding given in this section is used whenever it is necessary to identify
data types, such as in a descriptor. However, in addition to their use in
descriptors, these data type codes are also useful in areas outside the scope
of the Procedure Calling Standard for identifying VAX data types. Therefore,
each data type code indicates a unique data format independent of its use in
descriptors.

2-12

VAX Procedure Calling and Condition Handling Standard

Some data types are composed of a record-like structure consisting of two or
more elementary data types. For example, the F_floating complex (FC) data
type is made up of two F_floating data types, and the varying character string
(VT) data type is made up of a word (unsigned) (WU) data type followed by
a character string (T) data type.
Unless stated otherwise, all data types represent signed quantities. The
unsigned quantities throughout this standard do not allocate space for the
sign; all bit or character positions are used for significant data.

2.8.1

Atomic Data Types
Table 2-1 shows how atomic data types are defined and encoded.
Table 2-1

Atomic Data Types

Symbol

Code

Name/Description

DSC$K_DTYPE_Z

unspecified

The calling program has specified no data
type. The called procedure should assume
the argument is of the correct type.
DSC$K_DTYPE _BU

DSC$K_DTYPE_
WU

DSC$K_DTYPE_LU

byte (unsigned)

8-bit unsigned quantity.
word (unsigned)

16-bit unsigned quantity.
long word (unsigned)

32-bit unsigned quantity.
DSC$K_DTYPE_QU

quadword (unsigned)

64-bit unsigned quantity.
DSC$K_DTYPE_OU

octaword (unsigned)

DSC$K_DTYPE_B

byte integer (signed)

DSC$K_DTYPE_W

word integer (signed)

DSC$K_DTYPE_L

longword integer (signed)

128-bit unsigned quantity.

8-bit signed 2's-complement integer.

16-bit signed 2's-complement integer.
32-bit signed 2's-complement integer.
DSC$K_DTYPE_Q

quadword integer (signed)

64-bit signed 2's-complement integer.
DSC$K_DTYPE_0

octaword integer (signed)

DSC$K_DTYPE_F

F_ floating

128-bit signed 2's-complement integer.
32-bit F_floating quantity representing a single¬
precision number.

2-13

VAX Procedure Calling and Condition Handling Standard

Table 2-1 (Cont.)

Atomic Data Types

Symbol

Code

DSC$K_DTYPE_D

Name/Description
D_ floating
64-bit D_floating quantity representing a double¬
precision number.

DSC$K_DTYPE_G

G—floating
64-bit G_floating quantity representing a double¬
precision number.

DSC$K_DTYPE_H

H_ floating
128-bit H_floating quantity representing a
quadruple-precision number.

DSC$K_DTYPE_FC

F_floating complex
Ordered pair of F_floating quantities, representing
a single-precision complex number. The lower
addressed quantity is the real part, the higher
addressed quantity is the imaginary part.

DSC$K_DTYPE_DC

D—floating complex
Ordered pair of D_floating quantities, representing
a double-precision complex number. The lower
addressed quantity is the real part, the higher
addressed quantity is the imaginary part.

DSC$K_DTYPE_GC

G_floating complex
Ordered pair of G_floating quantities,
representing a double-precision complex number.
The lower addressed quantity is the real part, the
higher addressed quantity is the imaginary part.

DSC$K_DTYPE_HC

H_floating complex
Ordered pair of H_floating quantities,
representing a quadruple-precision complex
number. The lower addressed quantity is the
real part, the higher addressed quantity is the
imaginary part.

DSC$K_DTYPE_CIT

COBOL Intermediate Temporary
A floating-point datum with an 18-digit
normalized decimal fraction and a 2-decimal¬
digit exponent. The fraction is a packed decimal
string. The exponent is a 16-bit 2's-complement
integer. See Section 2.8.6 for more detail.

2.8.2

String Data Types
String data types are ordinarily described by a string descriptor. Table 2-2
shows how the string data types are defined and encoded.

2-14

VAX Procedure Calling and Condition Handling Standard

Table 2-2

String Data Types

Symbol

Code

Name/Description

DSC$K_DTYPE_T

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

DSC$K_DTYPE_VT

varying character string
A 16-bit unsigned count of the current
number of 8-bit characters following,
followed by a sequence of 0 to 216-1 8bit characters (see Section 2.8.7 for more
detail). 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 than the other 8-bit
string data types. (See Sections 2.9.12
and 2.9.13 for further discussion.)

DSC$K_DTYPE_NU

numeric string, unsigned

DSC$K_DTYPE_NL

numeric string, left separate sign

DSC$K_DTYPE_NLO

numeric string, left overpunched sign

DSC$K_DTYPE_NR

numeric string, right separate sign

DSC$K_DTYPE_NRO

numeric string, right overpunched sign

DSC$K_DTYPE_NZ

numeric string, zoned sign

DSC$K_DTYPE_P

packed decimal string

DSC$K_DTYPE_V

aligned bit string
An aligned bit string. A string of 0 to 216-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 zero 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,
since allocation is a multiple of 8 bits.

DSC$K_DTYPE_VU

unaligned bit string
The data is 0 to 216-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 only be used with the
unaligned bit string and unaligned bit array
descriptors (see Sections 2.9.14 and 2.9.15).

2-15

VAX Procedure Calling and Condition Handling Standard

2.8.3

Miscellaneous Data Types
Table 2-3 shows how miscellaneous data types are defined and encoded.
Table 2-3

Miscellaneous Data Types

Symbol

Code

Name/Description

DSC$K_DTYPE_ZI

sequence of instructions

DSC$K_DTYPE_ZEM

procedure entry mask

DSC$K_DTYPE_DSC

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

DSC$K_DTYPE_BPV

bound procedure value
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

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

absolute date and time
A 64-bit unsigned, scaled, binary integer
representing a date and time in 100nanosecond units offset from the VMS system
base date and time, which is 00:00 o'clock,
November 17, 1858 (the Smithsonian base
date and time for astronomical calendars). A
value of zero indicates that the date and time
have not been specified, so a default value or
distinctive print format may be used.
Note that the ADT data type is the same as
the VMS date format for positive values only.

2-16

VAX Procedure Calling and Condition Handling Standard

2.8.4 Facility-Specific Data Type Codes
Data type codes 160 through 191 are reserved to DIGITAL facilities for
facility-specific purposes. These codes must not be passed between facilities
because different facilities may use the same code for different purposes.
These codes may be used by compiler-generated code to pass parameters
to the language-specific run-time support procedures associated with that
language or to VAX DEBUG.

2.8.5 Reserved Data Type Codes
The type codes 38 through 191 are reserved to DIGITAL. Codes 192 through
255 are reserved for DIGITAL's Computer Special Systems Group and for
customers for their own use.

2.8.6 COBOL Intermediate Temporary Data Type
A COBOL intermediate temporary datum is 12 contiguous bytes starting on
an arbitrary byte boundary. It is specified by its address, A.

5 4 3 2

10 9 8 7 6 5 4 3 2

exponent
f< 16>

f<15>

f < 17>

A+2

f < 12>

f<11>

f < 14>

f < 13>

A+4

f<8>

f<7>

f<10>

f<9>

A+6

f<4>

f<3>

f<6>

f<5>

A+8

f<0>

sign

f<2>

f<1>

A + 10
ZK-1887-84

A COBOL intermediate temporary datum represents a floating-point datum
with a normalized 18-digit packed decimal fraction and a 16-bit 2'scomplement integer exponent. Bytes 0 and 1 are the exponent. Bytes 2
through 11 contain the normalized packed decimal fraction. The sign of the
datum is the sign of the fraction. If the fraction is zero, the value of the
datum is zero.
If the exponent is from -99 to +99 , operations can be performed on this
datum. If the exponent is outside this range, a reserved operand condition
is signaled (see Section 2.12). If a calculated datum has an exponent greater
than +99 , the exact result with the low-order 15 bits of the true exponent is
stored in the result datum and an overflow condition is signaled.
If a calculated datum has an exponent less than -99 , the exact result with
the low-order 15 bits of the true exponent is stored in the result datum and
an underflow condition is signaled. The condition handler can take the
appropriate action. Condition mnemonics have a COB$_ prefix and are
documented with the COBOL part of the VAX/VMS Run-Time Library. An
exponent value of -32768 is taken as reserved and should be used to encode
reserved operands such as uninitialized datum and indeterminate value. By
convention, if the fraction of a result is zero, the exponent is set to zero.
Fractions are generated with preferred sign codes and avoid minus zero.

2-17

VAX Procedure Calling and Condition Handling Standard

2.8.7

Varying Character String Data Type (DSC$K_DTYPE_VT)
The varying character string data type consists of the following two fixedlength areas allocated contiguously with no padding between:
CURLEN

An unsigned word specifying the current length in bytes of the
immediately following string (byte aligned).

BODY

A fixed-length area containing the string which can vary from zero to
a maximum length defined for each instance of string. The range of
this maximum length is 0 to 216-1.

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
may modify all bytes of BODY.
For example, consider a varying string with a maximum length of seven
characters. For the representation of the string ABC, CURLEN would be three
and the last four bytes would be undefined as shown below.

:adr

0
7K-1889-84

2.9

Argument Descriptor Formats
A uniform descriptor mechanism is defined for use by all procedures that
conform to the VAX Procedure Calling Standard. Descriptors are self
describing, and the mechanism is extensible. When existing descriptors
are not sufficient to satisfy the semantics of a language, new descriptors will
be 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 would ignore the contents of some of the fields.
A descriptor conforms to the VAX Procedure Calling Standard if all fields are
filled in by the calling program according to the standard, even if the field is
not needed by the called program.

2-18

VAX Procedure Calling and Condition Handling Standard

Note: Unless stated otherwise, all fields in descriptors represent unsigned
quantities, are read-only from the point of view of the called procedure,
and may 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 Section 2.8), it is not required to use a
standard descriptor to pass an array of such a data type. However, if a
language processor does pass an array of such a data type using a standard
descriptor, the language processor will fill in the DSC$B_DTYPE field with
zero 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 zero and for additional data types.

2.9.1

Descriptor Prototype
Figure 2-4 shows the descriptor prototype format, which consists of at least
two longwords.
Figure 2-4

Descriptor Prototype Format

CLASS

DTYPE

LENGTH

: Descriptor

POINTER
ZK-1890-84

Symbol

Description

DSC$W_LENGTH
<0,15:0>

A 1-word field specific to the descriptor class,
typically a 16-bit (unsigned) length.

DSC$B_DTYPE
<0,23:16>

A 1-byte data type code.Data type codes are listed
in Section 2.8.

DSC$B_CLASS
<0,31:24>

A 1-byte descriptor class code that identifies
the format and interpretation of the other fields
of the descriptor as specified in the remaining
Sections of 2.9. This interpretation is intended
to be independent of the DTYPE field, except for
the data types that are made up of units that are
less than a byte (packed decimal string (P), aligned
bit string (V), and unaligned bit string (VU)). The
CLASS code may be used at run time by a called
procedure to determine which descriptor is being
passed.

2-19

VAX Procedure Calling and Condition Handling Standard

Symbol

Description

DSC$A_POINTER
<1,31:0>

A longword containing the address of the first byte
of the data element described.

Note that the descriptor can be placed in a pair of registers with a MOVQ
instruction and then the length and address can be used directly. This gives
a word length, so the class and type are placed as bytes in the rest of that
longword. When the class field is zero, no more than the above information
can be assumed.

2.9.2

Fixed-length Descriptor (DSC$K_CLASS_S)
A single descriptor form is used for scalar data and fixed-length strings.
Any VAX data type can be used with this descriptor, except data type
34 (unaligned bit string). Figure 2-5 shows the format of a fixed-length
descriptor.
Figure 2-5

Fixed-length Descriptor Format

LENGTH

DTYPE

: Descriptor

POINTER
ZK-1891-84

Symbol

Description

DSC$W_LENGTH

Length of data item in bytes, unless the DSC$B_DTYPE field
contains the value 1 (aligned bit string) or 21 (packed decimal
string). Length of data item is in bits for bit. Length of data
item is the number of 4-bit digits (not including the sign) for
packed decimal string.

DSC$B_DTYPE

A 1-byte data type code. Data type codes are listed in
Section 2.8.

DSC$B_CLASS

1 = DSC$K_CLASS_S.

DSC$A_POINTER

Address of first byte of data storage.

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.

2.9.3

Dynamic String Descriptor (DSC$K_CLASS_D)
A single descriptor form is used for dynamically allocated strings. When
a string is written, either or both the length field and the pointer field can
be changed. The VAX/VMS Run-Time Library provides procedures for
changing fields. As an input parameter this format is interchangeable with
class 1 (DSC$K_CLASS_S). Figure 2-6 shows the format of a dynamic string
descriptor.

2-20

VAX Procedure Calling and Condition Handling Standard

Figure 2-6

Dynamic String Descriptor Format

DTYPE

LENGTH

: Descriptor

POINTER
ZK-1892-84

2.9.4

Symbol

Description

DSC$W_LENGTH

DSC$B_DTYPE

A 1-byte data type code. Data type codes are listed in
Section 2.8.

DSC$B_CLASS

2 = DSC$K_CLASS_D.

DSC$ A-POINTER

Address of first byte of data storage.

Variable Buffer Descriptor (DSC$K_CLASS_V)
Reserved for use by DIGITAL.

2.9.5

Array Descriptor (DSC$K_CLASS_A)
The array descriptor 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. Figure 2-7 shows
the format of an array descriptor.

2-21

VAX Procedure Calling and Condition Handling Standard

Figure 2-7

Array Descriptor Format

LENGTH

DTYPE

DIMCT

AFLAGS

: Descriptor

POINTER
DIGITS

SCALE

Block 1 - Prototype

ARSIZE

AO
Ml
Block 2 - Multipliers
M(n-1)
Mn
LI
U1
Block 3 - Bounds
Ln
Un
7K 1888-84

2-22

Symbol

Description

DSC$W_LENGTH

Length of an array element in bytes, unless the DSC$B_
DTYPE field contains the value 1 (aligned bit string) or 21
(packed decimal string). Length of an array element is in bits
for bit. Length of an array element is the number of 4-bit
digits (not including the sign) for packed decimal string.

DSC$B_DTYPE

A 1-byte data type code. Data type codes are listed in
Section 2.8.

DSC$B_CLASS

4 = DSC$K_CLASS_A.

DSC$A_POINTER

Address of first actual byte of data storage.

DSC$B_SCALE
<2,7:0

Signed power of two or ten multiplier, as specified by
DSC$V_FI_BINSCALE, to convert the internal form to
external form. (See Section 2.9.10.)

DSC$B_DIGITS
<2,15:8>

If nonzero, the unsigned number of decimal digits in the
internal representation. If zero, the number of digits can be
computed based on DSC$W_LENGTH.

VAX Procedure Calling and Condition Handling Standard

Symbol

Description

DSC$B_AFLAGS
<2,23:16>

Array flag bits
Reserved
<2,18:16>

Must be zero.

DSC$V_FI_BINSCALE
<2,19>

If set, the scale factor specified by
DSC$B_SCALE is a signed power
of two multiplier to convert the
internal form to external form. If
not set, DSC$B_SCALE specifies
a signed power of ten multiplier.
(See Section 2.9.10.)

DSC$V_FI_REDIM
<2,20>

If set, the array can be
redimensioned, that is, DSC$A_
AO, DSC$L_Mi, DSC$L_Li, and
DSC$I—Ui may be changed.
The redimensioned array cannot
exceed the size allocated to the
array (DSC$L_ARSIZE).

DSC$ V_FL —COLUMN
<2,21 >

If set, the elements of the
array are stored by columns
(FORTRAN). That is, the left-most
subscript (first dimension) is
varied most rapidly, and the right¬
most subscript (nth dimension)
is varied least rapidly. If not set,
the elements are stored by rows
(most other languages). That is,
the right-most subscript is varied
most rapidly and the left-most
subscript is varied least rapidly.

DSC$V_FI_COEFF
<2,22>

If set, the multiplicative
coefficients in Block 2 are
present. Must be set if DSC$V_
FL—BOUNDS is set.

DSC$ V_FL —BOUNDS
<2,23>

If set, the bounds information in
Block 3 is present and requires
that DSC$V_FL_COEFF be set.

DSC$B_DIMCT
<2,31:24>

Number of dimensions, n.

DSC$I_ARSIZE
<3,31:0>

Total size of array (in bytes unless the DSC$B_TYPE field
contains the value 21 ; see the description for DSC$W_
LENGTH). A redimensioned array may use less than the total
size allocated.
For data type 1 (aligned bit string), DSC$W_LENGTH is in
bits while DSC$L_ARSIZE is in bytes since the unit of length
is bits while the unit of allocation is aligned bytes.

DSC$A_AO
<4,31:0>

Address of element A(0,0, . . . ,0). This need not be within
the actual array. It is the same as DSC$A_POINTER for
zero-origin arrays.

DSC$I_Mi
<4+i,31:0>

Addressing coefficients. ( Mi = Ui-Li+1 )

2-23

VAX Procedure Calling and Condition Handling Standard

Symbol

Description

DSC$L_Li
<3+n+2*i,31:0>

Lower bound (signed) of /th dimension.

DSC$I_Ui
<4+n+2*i,31:0>

Upper bound (signed) of /th dimension.

The following formulas specify the effective address, E, of an array element.
Warning: Modification of the following formulas is required if DSC$B_DTYPE
contains a 1 or 21 because DSC$W—LENGTH is given in bits or 4-bit
digits rather than bytes.
The effective address, E, for element A(I):
E = A0 + I*LENGTH
= POINTER + [I - Li]*LENGTH
The effective address, E, for element A(Ii,I2) with DSC$V_FL—COLUMN
clear:
E = A0 + [Ii*M2 + I2]*LENGTH
= POINTER + [ [Ii -L^] *M2 + I2 - L2]*LENGTH
The effective address, E, for element A(Ii,I2) with DSC$V_FL—COLUMN set:
E = A0 + [I2*Mi + Ii]*LENGTH
= POINTER + [[I2-L2]*Mi + Ii - Li]*LENGTH
The effective address, E, for element A(Ii, . . . ,In) with DSC$V_FL_
COLUMN clear:
E = A0 + [[[[... [Iil*M2 + . . . ] *Mn_2 + In_2] *Mn_i
+ In-l]*Mn + Inl^LENGTH
= POINTER + [[[[... [Ii - LU *M2 + ...]*Mn_2 + In_2
- Ln_2] *Mn_! + In_i - Ln_!]*Mn ♦ In - Ln] *LENGTH

The effective address, E, for element A(Ii, . . . ,In) with DSC$V_FL —
COLUMN set:
E = A0 + [[[[. • • [In]*Mn_i + . . .]*M3
+ I3]*M2 + I2]*Ma + Ii]*LENGTH
= POINTER + [[[[...[In - Ln]*Mn_! + ...]*M3 + I3
- L3]*M2 + I2 - L2]*Mi
+ i! - LU+LENGTH

2.9.6

Procedure Descriptor (DSC$K_CLASS_P)
The descriptor for a procedure specifies its entry address and function value
data type, if any. Figure 2-8 shows the format of a procedure descriptor.
Figure 2—8

Procedure Descriptor Format

DTYPE

LENGTH

POINTER
ZK-1893-84

2-24

VAX Procedure Calling and Condition Handling Standard

Symbol

Description

DSC$W_LENGTH

Length associated with the function value or zero if no
function value is returned.

DSC$B_DTYPE

Function value data type code. Data type codes are listed in
Section 2.8.

DSC$B_CLASS

5 = DSK$K_CLASS_P.

DSC$A_POINTER

Address of entry mask to routine.

Procedures return a function value in RO, R1/R0, or using the first argument
list entry depending on the size of the data type (see Section 2.4).

2.9.7 Procedure Incarnation Descriptor (DSC$K_CLASS_PI)
This descriptor is obsolete.

2.9.8 Label Descriptor (DSC$K_CLASS_J)
Reserved for use by the VAX/VMS Symbolic Debugger.

2.9.9 Label Incarnation Descriptor (DSC$K_CLASS_Jl)
This descriptor is obsolete.

2.9.10 Decimal String Descriptor (DSC$K_CLASS_SD)
Figure 2-9 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.

Figure 2-9

Decimal String Descriptor Format

DTYPE

LENGTH

POINTER
RESERVED

DIGITS

SCALE
ZK-1 894-84

Symbol

Description

DSC$W_LENGTH

DSC$B_DTYPE

A 1-byte data type code. Data type codes are listed in
Section 2.8.

2-25

VAX Procedure Calling and Condition Handling Standard

Symbol

Description

DSC$B_CLASS

9 = DSC$K_CLASS_SD.

DSC$A_POINTER

Address of first byte of data storage.

DSC$B_SCALE
<2,7:0>

Signed power of two or ten multiplier, as specified by
DSC$V_FI_BINSCALE, to convert the internal form to
external form. (See examples below.)

DSC$B_DIGITS
<2,15:8>

If nonzero, the unsigned number of decimal digits in the
internal representation. If zero, the number of digits can be
computed based on DSC$W_LENGTH.

DSCSB—SFLAGS
<2/23:16>

Scalar flag bits:
Reserved
<2,18:16>

Reserved
<2,31:24>

Must be zero.

DSC$ V_FL —BINSCALE
<2,19>

Reserved
<2,23:20>

Must be zero.

Examples of DSC$B_SCALE and DSC$V_FL_BINSCALE interpretation are
presented in the table below.

Internal value

DSC$B_
SCALE

DSC$V_FI_
BINSCALE

External
value

123

1230

123

246

200

-2

200

-2

2.9.11 Noncontiguous Array Descriptor (DSC$K_CI_ASS_NCA)
The noncontiguous array descriptor describes an array in which the storage
of the array elements may 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 one in the most rapidly varying
dimension only. The difference between the addresses of two adjacent
elements is termed the stride. Whether elements are stored by row or column
is the option of the calling program, and is automatically taken care of by a
single accessing algorithm used by the called procedure.
This array descriptor is to be used where the calling program, at its option,
can pass a slice of an array that contains noncontiguous allocation. At the
present time this standard indicates no preference between the noncontiguous
array descriptor (NCA) and the contiguous array descriptor (A) as described
in Section 2.9.5 for language processors that always allocate arrays that are
contiguous.
2—26

VAX Procedure Calling and Condition Handling Standard

Figure 2-10 shows the format of a noncontiguous array descriptor, which
consists of three contiguous blocks.
Figure 2-10

Noncontiguous Array Descriptor Format

DTYPE field contains the value 1 (aligned bit string) or
21 (packed decimal string). Length of an array element is
in bits for bit. Length of an array element is the number
of 4-bit digits (not including the sign) for packed decimal
string.
DSC$B_DTYPE

A 1-byte data type code. Data type codes are listed in
Section 2.8.

DSC$B_CLASS

10 = DSC$K_CLASS_NC A.

DSC$ A—POINTER

Address of first actual byte of data storage.

DSC$B_SCALE
<2,7:0>

Signed power of two or ten multiplier, as specified by
DSC$V_FI_BINSCALE, to convert the internal form to
external form. (See Section 2.9.10.)

DSC$B_DIGITS
<2,15:8>

If nonzero, the unsigned number of decimal digits in the
internal representation. If zero, the number of digits can
be computed based on DSC$W_LENGTH.

2-27

VAX Procedure Calling and Condition Handling Standard

Symbol

Description

DSCSB—AFLAGS
<2,23:16>

Array flag bits
Reserved
<2,18:16>

Reserved for future
standardization by DIGITAL.
Must be zero.

DSC$V_FI_BINSCALE
<2,19>

If set, the scale factor specified
by DSC$B_SCALE is a signed
power of two multiplier to
convert the internal form to
external form. If not set,
DSC$B_SCALE specifies a
signed power of ten multiplier.
(See Section 2.9.10.)

DSC$V_FI_REDIM
<2,20>

Must be zero.

Reserved
<2,23:21 >

Reserved for future
standardization by DIGITAL.
Must be zero.

DSC$B_DIMCT
<2,31:24>

Number of dimensions. n.

DSC$L —ARSIZE
<3,31:0>

If the elements are actually contiguous, ARSIZE is the
total size of the array (in bytes, unless the DSC$B_DTYPE
field contains the value 21 , see description of DSC$W_
LENGTH). If the elements are not allocated contiguously
or the program unit allocating the descriptor is uncertain
whether the array is actually contiguous or not, the value
placed in ARSIZE may be meaningless.
For data type 1 (aligned bit string), DSC$W_LENGTH is
in bits while DSC$L_ARSIZE is in bytes since the unit
of length is in bits while the unit of allocation is aligned
bytes.

DSC$A_AO
<4,31:0>

Address of element A(0,0, . . . ,0). This need not be
within the actual array. It is the same as DSC$A_
POINTER for zero-origin arrays.

DSC$L_Si
<4+i,31:0>

Stride of the /th dimension. The difference between the
addresses of successive elements of the ith dimension.

DSC$L_Li
<3+n+2*i,31:0>

Lower bound (signed) of the /th dimension.

DSC$I_Ui
<4+n+2*i,31:0>

Upper bound (signed) of the /th dimension.

DSC$A_A0 = POINTER - ( S-j *L-j + S2*L2 + . . . +Sn*Ln)

The following formulas specify the effective address, E, of an array element.
WARNING: Modification of the following formulas is required if DSC$B_
DTYPE equals 1 or 21 because DSC$W_LENGTH is given in bits or 4-bit
digits rather than bytes.
The effective address, E, of A(I):
E = Aq + Si*I
= POINTER + Si* [I - Li]

2-28

VAX Procedure Calling and Condition Handling Standard

The effective address, E, of A(l!,I2):
E = Aq + Si*Ii + S2*I2
= POINTER + Si*[Ii - LJ + S2*[l2 “ L2]

The effective address, E, of A(Ii, . . . ,In):
E = A0 + Si*Ii + . . . + Sn*In
= POINTER ♦ Si*[Ii - Li] + . .
" Ln]

. + Sn*[In

2.9.12 Varying String Descriptor (DSC$K_CLASS_VS)
A single descriptor form is used for varying string data types consisting of
the following two fixed-length areas allocated contiguously with no padding
between.
CURLEN

An unsigned word specifying the current length in bytes of the
immediately following string (byte aligned).

BODY

A fixed-length area containing the string which can vary from zero to
a maximum length defined for each instance of string.

As an input parameter, this format is not interchangeable with class 1
(DSC$K_CLASS_S) or with class 2 (DSC$K_CLASS_D). When a called
procedure modifies a varying string passed by reference or by descriptor, it
writes the new length, n , into CURLEN and may modify all bytes of BODY.
Figure 2-11 shows the format of a varying string descriptor.
Figure 2-11

Varying String Descriptor Format

MAXSTRLEN

DTYPE
POINTER

ZK-1896-84

Symbol

Description

DSC$W_
MAXSTRLEN

Maximum length of the BODY field of the varying string in
bytes in the range 0 to 216-1.

DSC$B_DTYPE

A 1-byte data type code that must have the value 37 ,
which specifies the varying character string data type (see
Sections 2.8.2 and 2.8.7). The use of other data types is
reserved for future standardization.

DSC$B_CLASS

11 = DSC$K_CLASS_VS.

DSC$A_POINTER

Address of first field (CURLEN) of the varying string.

For example, MAXSTRLEN contains five, CURLEN contains four, string is
currently ABCD, and the remaining byte is currently undefined:

2-29

VAX Procedure Calling and Condition Handling Standard

31
11

:descriptor
adr

:adr

ZK-1897-84

2.9.13 Varying String Array Descriptor (DSC$K_CLASS_VSA)
A variant of the noncontiguous array descriptor is used to specify an array
of varying strings where each varying string has the same maximum length.
Each array element is a varying string data type consisting of the following
two fixed-length areas allocated contiguously with no padding between.
CURLEN

An unsigned word specifying the current length in bytes of the
immediately following string (byte aligned).

BODY

A fixed-length area containing the string which can vary from zero to
the maximum length defined for an array element (MAXSTRLEN).

When a called procedure modifies a varying string in an array of varying
strings passed to it by reference or by descriptor, it writes the new length,
n, into CURLEN and may modify all bytes of BODY. The format of this
descriptor is the same as the noncontiguous array descriptor except for the
two first longwords. Figure 2-12 shows the format of a varying string array
descriptor.

2-30

VAX Procedure Calling and Condition Handling Standard

Figure 2-12

Varying String Array Descriptor Format

Symbol

Description

DSC$W_
MAXSTRLEN

Maximum length of the BODY field of an array element in
bytes in the range 0 to 216-1.

2-31

VAX Procedure Calling and Condition Handling Standard

Symbol

Description

DSC$B_DTYPE

DSC$B_CLASS

12 = DSC$K_CLASS_VSA.

DSC$ A —POINTER

Address of first actual byte of data storage.

The remaining fields in the descriptor are identical to those in the
noncontiguous array descriptor (NCA). The effective address computation
of an array element produces the address of CURLEN of the desired element.

2.9.14 Unaligned Bit String Descriptor (DSC$K_CLASS_UBS)
A descriptor is used to pass an unaligned bit string (DSC$K_DTYPE_VU)
that starts on an arbitrary bit boundary and ends on an arbitrary bit boundary.
The length is 0 to 216-1 bits. The bit string may be accessed directly using
the VAX variable bit field instructions. Therefore the descriptor provides two
components: a base address and a signed relative bit position. Figure 2-13
shows the format of an unaligned bit string descriptor.
Figure 2-13

Unaligned Bit String Descriptor Format

LENGTH

DTYPE

: Descriptor

BASE
POS
ZK-1899-84

Symbol

Description

DSC$W_LENGTH

Length of data item in bits.

DSC$B_DTYPE

A 1-byte data type code that has the value 34 , which
specifies the unaligned bit string data type (see Section 2.8).
The use of other data types is reserved for future
standardization.

DSC$B_CLASS

13 = DSC$K_CLASS_UBS

DSC$A_BASE

Base of address relative to which the signed relative bit
position, POS, is used to locate the bit string. The base
address need not be first actual byte of data storage.

DSC$I_POS

Signed longword relative bit position with respect to BASE
of the first bit of unaligned bit string.

For example, a called procedure can use the following instruction to access a
bit string of 32 bits or less. If RO contains the address of the descriptor, the
following instruction copies the bit string to Rl.
EXTZV

DSC$L_POS(RO), DSC$W_LENGTH(RO), <DDSC$A_BASE(RO). Rl

VAX Procedure Calling and Condition Handling Standard

2.9.15 Unaligned Bit Array Descriptor (DSC$K_CI_ASS_UBA)
A variant of the noncontiguous array descriptor is used to specify an array
of unaligned bit strings. Each array element is an unaligned bit string data
type (DSC$K_DTYPE_VU) that starts on an arbitrary bit boundary and ends
on an arbitrary bit boundary. The length of each element is the same and
is 0 to 216-1 bits. Elements of the array may be accessed directly using the
VAX variable bit field instructions. Therefore, the descriptor provides two
components: a byte address, DSC$A_BASE, and a means to compute the
signed bit offset, EB, with respect to BASE of an array element.
The unaligned bit array descriptor consists of four contiguous blocks that are
always present. The first block contains the descriptor prototype information.
Figure 2-14 shows the format of an unaligned bit array descriptor.
Figure 2-14

Unaligned Bit Array Descriptor Format

LENGTH

DTYPE

:Descriptor

BASE
DIMCT

DIGITS

AFLAGS

SCALE

Block 1 - Prototype

ARSIZE

Block 2 - Strides

Block 3 - Bounds

POS

Block 4-Position
ZK-1900-84

Symbol

Description

DSC$W_LENGTH

Length of an array element in bits.

DSC$B_DTYPE

A 1-byte data type code that must have the value 34 ,
which specifies the unaligned bit string data type (see
Section 2.8). The use of other data types is reserved for
future standardization.

DSC$B_CLASS

14 = DSC$K_CLASS_UBA

2-33

VAX Procedure Calling and Condition Handling Standard

Symbol

Description

DSC$A_BASE

Base address relative to which the effective bit offset, EB,
is used to locate elements of the array. The base address
need not be the first actual byte of data storage.

DSC$B_SCALE

Reserved for future standardization by DIGITAL. Must be
zero.

DSC$B_DIGITS

Reserved for future standardization by DIGITAL. Must be
zero.

DSC$B_AFLAGS
<2,23:16>

Array flag bits.
Reserved
<2,18:16>

Reserved for future
standardization by DIGITAL.
Must be zero.

DSC$V_FI_BINSCALE
<2,19>

Must be zero.

DSC$V_FL—REDIM
<2,20>

Must be zero.

Reserved
<2,23:21>

Reserved for future
standardization by DIGITAL.
Must be zero.

DSC$B_DIMCT
<2,31:24>

Number of dimensions, n.

DSC$I_ARSIZE
<3,31:0>

If the elements are actually contiguous, ARSIZE is the
total size of the array in bits. If the elements are not
allocated contiguously or the program unit allocating
the descriptor is uncertain whether the array is actually
contiguous or not, the value placed in ARSIZE may be
meaningless.

DSCSI_VO
<4,31:0>

Signed bit offset of element A(0, ... ,0) with respect to
BASE. V0 = POS - [S1*L1 +
Sn*Ln].

DSCSI_Si
<4+i,31:0>

Stride of the ith dimension. The difference between the
bit (not byte) addresses of successive elements of the ith
dimension.

DSC$I_Li
<3+n+2*i,31:0>

Lower bound (signed) of the ith dimension.

DSC$I_Ui
<4+n+2*i,31:0>

Upper bound (signed) of the ith dimension.

DSC$L_POS
<5+n*3,31:0>

Signed longword relative bit position with respect to
BASE of the first actual bit of the array, that is element
A(L1.Ln)._

The signed, 32-bit effective bit offset, EB, of A(Ii):
EB = Vq + Si*Ii
= POS + Si*[Ii - Li]

The signed, 32-bit effective bit offset, EB, of A(Ii,I2):
EB = Vq ♦ Si*Ii + S2*I2
= POS + Si*[Ii - Li] + S2*[I2 - L2]

The signed, 32-bit effective bit offset, EB, of A(Ii, . . . , In):
EB = Vq + Si*Ii + ... + Sn*In
= POS + Si*[Ij
■ Lj] + ... + Sn*[In
' Ln]

2-34

VAX Procedure Calling and Condition Handling Standard

Note that EB is computed ignoring integer overflow. EB is then usable as
the position operand and the contents of DSC$A_BASE is usable as the base
address operand in the VAX variable length bit field instructions. Therefore,
BASE must specify a byte that is within 228 bytes of all bytes of storage in the
bit array.
For example, consider a one-origin, one-dimension, five-element array
consisting of 3-bit elements allocated adjacently (therefore SI = 3). Assume
BASE is byte 1000 and the first actual element, A(l), starts at bit <4> of
byte 1001.
7

0
:1000

0
3

:1001

:1002

: 1003
ZK-1901 -84

The following dependent field values occur in the descriptor:
pos = 12
v0 = 12 - 3*1 = 9

2.9.16 String with Bounds Descriptor (DSC$K_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 2-15 shows the format of a string with bounds descriptor.
Figure 2-15

String with Bounds Descriptor Format

LENGTH

DTYPE

:Descriptor

POINTER
SB_LI
SB_U1
ZK-1908-84

Symbol

Description

DSC$W_LENGTH

Length of string in bytes.

DSC$B_DTYPE

A 1-byte data type code that must have the value
14, which specifies the character string data type (see
Section 2.8). The use of other data types is reserved for
future standardization.

DSC$B_CLASS

15 = DSC$K_CLASS_SB.

DSC$A_POINTER

Address of first byte of data storage.

2-35

VAX Procedure Calling and Condition Handling Standard

Symbol

Description

DSC$I_SB_L1

Lower bound (signed) of the first (and only) dimension.

DSC$I_SB_U 1

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.

2.9.17 Unaligned Bit String with Bounds Descriptor
(DSC$K_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 2-16 shows the format of an unaligned bit string with bounds
descriptor.
Figure 2-16

Unaligned Bit String with Bounds Descriptor
Format

LENGTH

DTYPE

:Descriptor

BASE
POS
UBSB_LI
UBSB_U1
ZK-1909-84

2-36

Symbol

Description

DSC$W_LENGTH

Length of data item in bits.

DSC$B_DTYPE

A 1-byte data type code that must the value 34, which
specifies the unaligned bit string data type (see Section 2.8).
The use of other data types is reserved for future
standardization.

DSC$B_CLASS

16 = DSC$K_CLASS_UBSB.

DSC$A_BASE

Base address relative to which the signed relative bit
position, POS, is used to locate the bit string. The base
address need not be the first actual byte of data storage.

DSC$I_POS

Signed longword relative bit position with respect to BASE
of the first bit of the unaligned bit string.

DSC$I_UBSB_L 1

Lower bound (signed) of the first (and only) dimension.

VAX Procedure Calling and Condition Handling Standard

Symbol

Description

DSC$I_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.Ll]

2.9.18 Facility-Specific Descriptor Class Codes
Descriptor class codes 160 through 191 are reserved to DIGITAL facilities for
facility-specific purposes. These codes must not be passed between facilities
because different facilities may use the same code for different purposes.
These codes may be used by compiler-generated code to pass parameters
to the language-specific run-time support procedures associated with that
language or to VAX DEBUG.

2.9.19 Reserved Descriptor Class Codes
Descriptor classes 15 through 191 are reserved to DIGITAL. Classes 192
through 255 are reserved for DIGITAL's Computer Special Systems group and
customers.

2.10

VAX Conditions
A condition is either (1) a hardware-generated synchronous exception or (2)
a software event that is to be processed in a manner analogous 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, or 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, four types of action can be
taken 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 may be
satisfactory.

•

Take some special action and then 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.

2-37

VAX Procedure Calling and Condition Handling Standard

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 2.5). 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.

2.10.1 Condition Handlers
To handle hardware- or software-detected exceptions, the VAX Condition
Handling Facility allows the programmer to specify a condition handler
procedure to be called when an exception condition occurs. This same
handler procedure may also be used to handle software-detected conditions.
An active procedure can establish a condition handler to be associated with it.
The presence of a condition handler is indicated by a nonzero address in the
first longword of the procedure's stack frame. When an event occurs that is
to be treated using the condition handling facility, the procedure detecting the
event signals the event by calling the facility and passing a condition value
describing the condition that occurred. This condition value has the format
and interpretation as described in Section 2.5. All hardware exceptions are
signaled.
When a condition is signaled, the condition handling facility looks for a
condition handler in the current procedure's stack frame. If a handler is
found, it is entered. If no handler is associated with the current procedure,
the immediately preceding stack frame is examined. Again, if a handler
is found it is entered. If a handler is not found, the search of previous stack
frames continues until the default condition handler established by the system
is reached or the stack runs out.
The default condition handler prints messages indicated by the signal
argument list by calling the Put Message (SYS$PUTMSG) system service,
followed by an optional symbolic stack traceback. Success conditions
with STS$K_SUCCESS result in messages to file SYS$OUTPUT only. All
other conditions, including informational messages (STS$K_INFO), produce
messages on files SYS$OUTPUT and SYS$ERROR.
For example, if a procedure needs to keep track of the occurrence of the
floating-point underflow exception, it can establish a condition handler to
examine the condition value passed when the handler is invoked. Then when
the floating-point underflow exception occurs, the condition handler will be
entered and will log the condition. The handler will return to the instruction
immediately following the instruction causing the underflow.
If floating-point operations occur in many procedures of a program, the
condition handler can be associated with the program's main procedure.
When the condition is signaled, successive stack frames are searched until the
stack frame for the main procedure is found, at which time the handler will
be entered. If a user program has not associated a condition handler with any
of the procedures that are active at the time of the signal, successive stack
frames will be searched until the frame for the system program invoking the

2-38

VAX Procedure Calling and Condition Handling Standard

user program is reached. A default condition handler that prints an error
message will then be entered.

2.10.2 Condition Handler Options
Each procedure activation potentially has a single condition handler
associated with it. This condition handler will be entered whenever any
condition is signaled within that procedure. (It can also be entered as a result
of signals within active procedures called by the procedure.) Each signal
includes a condition value (see Section 2.5), that describes the condition
causing the signal. When the condition handler is entered, the condition
value should be examined to determine the cause of the signal. After the
handler has processed the condition or chosen to ignore it, it can take one of
the following actions:

2.11

•

Return to the instruction immediately following the signal. Note that it is
not always possible to make such a return.

•

Resignal the same or a modified condition value. A new search for a
condition handler will begin with the immediately preceding stack frame.

•

Signal a different condition.

•

Unwind the stack.

Operations Involving Condition Handlers
The VAX Condition Handling Facility provides functions to perform the
following operations:
•

Establish a condition handler.
A condition handler is associated with the current procedure by placing
the handler's address in the current procedure's activation stack frame.

•

Revert to the caller's handling.
If a condition handler has been established, it can be removed by clearing
its address in the current procedure activation's stack frame.

•

Enable or disable certain arithmetic exceptions.
The following hardware exceptions can be enabled or disabled by
software: floating-point underflow, integer overflow, and decimal
overflow. No signal occurs when the exception is disabled.

•

Signal a condition.
Signaling a condition initiates the search for an established condition
handler.

•

Unwind the stack.
Upon exit from a condition handler it is possible to remove one or more
frames occurring before the signal from the stack. During the unwinding
operation, the stack is scanned and if a condition handler is associated
with a frame, that handler is entered before the frame is removed.
Unwinding the stack allows a procedure to perform application specific
cleanup operations before exiting.

2-39

VAX Procedure Calling and Condition Handling Standard

2.11.1 Establishing a Condition Handler
Each procedure activation has a condition handler potentially associated
with it using longword 0 in its stack frame. Initially, longword 0 contains 0 ,
indicating no handler. A handler is established by moving the address of the
handler's procedure entry point mask to the established stack frame.
In addition, VAX/VMS provides three statically allocated exception vectors
for each access mode of a process. These vectors are available to declare
condition handlers that take precedence over any handlers declared at the
procedure level. These are used, for example, to allow a debugger to monitor
all exceptions and for the system to establish a last chance handler. Because
these handlers do not obey the procedure nesting rules, they should not be
used by modular code. Instead the stack-based declaration should be used.
The code to establish a condition handler is shown below:
MOVAB handler_entry.point,0(FP)

2.11.2 Reverting to the Caller's Handling
Reverting to the caller's handling deletes the condition handler associated
with the current procedure activation. This is done by clearing the handler
address in the stack frame.
The code to revert to the caller's handling is shown below:
CLRL O(FP)

2.11.3 Signaling a Condition
The signal operation is the method used for indicating the occurrence of an
exception condition. To issue a message and be able to continue execution
after handling the condition, a program calls the LIB$SIGNAL procedure as
follows:
CALL LIB$SIGNAL (condition-value, arg.list...)

To issue a message, but not continue execution, a program calls LIB$STOP, as
follows:
CALL LIB$STOP (condition-value, arg.list...)

In both cases, the condition-value argument indicates the condition that
is signaled. However, LIB$STOP sets the severity of the condition-value
argument to be a severe error. The remaining arguments describe the details
of the exception. These are the same arguments used to issue a system
message.
Note that unlike most calls, LIB$SIGNAL and LIB$STOP preserve RO and
R1 as well as the other registers. Therefore, a debugger can insert a call
to LIB$SIGNAL to display the entire state of the process at the time of
the exception. It also allows signals to be coded in VAX MACRO without
changing the register usage. This feature of preserving RO and R1 is useful
for debugging checks and gathering statistics. Hardware and system service
exceptions behave like calls to LIB$SIGNAL.

2-40

VAX Procedure Calling and Condition Handling Standard

The signal procedure examines the two exception vectors and then up to
64K previous stack frames and finally the last-chance exception vector, if
necessary. The current and previous stack frames are found by using FP and
chaining back through the stack frames using the saved FP in each frame.
The exception vectors have three address locations per access mode.
As a part of image start-up, the system declares a default last-chance handler.
This handler is used as a last resort when the normal handlers are not
performing correctly. The debugger can replace the default system last-chance
handler with its own.
In some frame before the call to the main program, the system establishes
a default catch-all condition handler that issues system messages. In a
subsequent frame before the call to the main program, the system usually
establishes a traceback handler. These system-supplied condition handlers
use the condition-value argument to get the message and then use the
remainder of the argument list to format and output the message through the
system service, SYS$PUTMSG.
If the severity field of the condition-value argument (bits <2:0> ) does not
indicate a severe error (that is, a value of 4 ) these default condition handlers
return with SS$_CONTINUE. If the severity is a severe error, these default
handlers exit the program image with the condition value as the final image
status.
The stack search ends when the old FP is 0 or is not accessible, or when 64K
frames have been examined. If no condition handler is found, or all handlers
returned with a SS$_RESIGNAL, then the vectored last-chance handler is
called.
If a handler returns SS$_CONTINUE, and LIB$STOP was not called, control
returns to the signaler. Otherwise LIB$STOP issues a message that an attempt
was made to continue from a noncontinuable exception and exits with the
condition value as the final image status.
Table 2-4 lists all combinations of interaction between condition handler
actions, the default condition handlers, the type of signals, and the call to
signal or stop. In the table, "cannot continue" indicates an error that results in
the following message:
IMPROPERLY HANDLED CONDITION, ATTEMPT TO CONTINUE FROM
STOP.

2-41

VAX Procedure Calling and Condition Handling Standard

Table 2-4

Interaction between Handlers and Default Handlers
Signaled

Call to:

Condition

Default

Handler

Severity

Handler

Specifies

Is Found

<2:0>

Gets Control

Continue

UNWIND

(stack bad)

No Handler

Call
condition
<4

message
RET

last
RET

UNWIND

chance

LIBSSIGNAL
or

EXIT

hardware
exception

Call
last

condition
=4

message

RET

UNWIND

EXIT

chance
handler
EXIT
Call

LIB$STOP

force
(=4)

condition

"cannot

message

continue"

EXIT

last
UNWIND

chance
handler
EXIT

2.12

Properties of Condition Handlers
This section describes the properties of condition handlers.

2.12.1 Condition Handler Parameters and Invocation
If a condition handler is found on a software-detected exception, the handler
is called with the following argument list.
continue = handler (signal.args, mechanism.args)

Each argument is a reference to a longword vector. The first longword of
each vector is the number of remaining longwords in the vector. The symbols
CHF$L —SIGARGLST (=4) and CHF$L __MCHARGLST (=8) can be used to
access the condition handler arguments relative to AP.
Signal_args is the condition argument list from the call to LIB$SIGNAL or
LIB$STOP expanded to include the PC and PSL of the next instruction to
execute on a continue. In particular, the second longword is the condition
value being signaled.
Because bits <2:0> of the condition value indicate severity and do not
indicate which condition is being signaled, the handler should examine only
the condition identification, that is, condition value bits <27:3> . The
setting of bits <2:0> varies depending upon the environment. In fact, some
handlers may simply change the severity of a condition and resignal. The
symbols CHF$L_SIG_ARGS (=0) and CHF$L_SIG_NAME (=4) can be
used to refer to the elements of the signal vectors.
Figure 2-17 shows the format of the mechanism argument vector.

2-42

VAX Procedure Calling and Condition Handling Standard

Figure 2-17

Format of the Mechanism Argument Vector

CHF$L_MCH_ARGS
CHF$L_MCH_FRAME
CHF$L_MCH_DEPTH
CHF$L_MCH_SAVRO
CHF$L_MCH_SAVR1
ZK-1883-84

The frame is the contents of the FP in the established context. This can be
used as a base to access the local storage of the establisher if the restrictions
described in Section 2.12.2 are met.
The depth is a positive count of the number of procedure activation stack
frames between the frame in which the exception occurred and the frame
depth that established the handler being called. Depth has the value 0 for
an exception handled by the procedure activation invoking the exception
(that is, containing the instruction causing the hardware exception or calling
LIB$SIGNAL). Depth has positive values for procedure activations calling the
one having the exception. For example, 1 for the immediate caller.
If a system service gives an exception, the immediate caller of the service
is notified at depth = 1 . Depth has value -2 when the condition handler is
established by the primary exception vector, -1 when it is established by the
secondary vector, and -3 when it is established by the last-chance vector.
The contents of RO and R1 are the same as at the time of the call to
LIB$SIGNAL or LIB$STOP.
For hardware-detected exceptions, the condition value indicates which
exception vector was taken and the next 0 or several longwords are additional
parameters. The remaining two longwords are the PC and PSL. Figure 2-18
shows the format of the signal argument vector.
Figure 2-18

Format of the Signal Argument Vector

CHF$I_SIG_ARGS

condition-value

CHF$L_SIG_NAME

none or some
additional
arguments
PC
PSL
ZK-1882-84

If one of the default condition handlers established by the system is entered,
it calls the system service, SYS$PUTMSG, to interpret the signal argument list
and output the indicated information or error message. See the description
of SYSSPUTMSG in the VAX/VMS System Services Reference Manual for the
format of the signal argument list.
2-43

VAX Procedure Calling and Condition Handling Standard

2.12.2 Use of Memory
A condition handler and procedures it calls are restricted to referring to only
explicitly passed arguments. Handlers cannot refer to COMMON or other
external storage, and they cannot reference local storage in the procedure that
established the handler. The existence of handlers does not affect compiler
optimization. Compilers that do not follow this rule must ensure that any
variables referred to by the handler are always in memory.

2.12.3 Returning from a Condition Handler
Condition handlers are invoked by the VAX Condition Handling Facility.
Therefore, the return from the condition handler is to the condition handling
facility.
To continue from the instruction following the signal, the handler must return
with the function value SS$_CONTINUE (true), that is, with bit <0> set).
If, however, the condition was signaled with a call to LIB$STOP, the image
will exit. To resignal the condition, the condition handler returns with the
function value SS$_RESIGNAL (false), that is, with bit <0> clear). To alter
the severity of the signal, the handler modifies the low-order three bits of
the condition value longword in the signal-args vector and resignals. If the
condition handler wants to alter the defined control bits of the signal, the
handler modifies bits <31:28> of the condition value and resignals. To
unwind, the handler calls SYS$UNWIND and then returns. In this case, the
handler function value is ignored.

2.12.4 Request to Unwind
To unwind, the handler or any procedure it calls can make the following call:
success = SYS$UNWIND
( [depadr *
[new_PC =

handler depth
return PC ] )

+ 1],

The argument depadr specifies the address of a longword that contains the
number of presignal frames (depth) to be removed. If that number is less
than or equal to 0 , then nothing is to be unwound. The default (address=0)
is to return to the caller of the procedure that established the handler that
issued the $UNWIND service. To unwind to the establisher, the depth from
the call to the handler should be specified. When the handler is at depth 0,
it can achieve the equivalent of an unwind operation to an arbitrary place in
its establisher by altering the PC in its signal-args vector and returning with
SS$_CONTINUE instead of performing an unwind.
The argument new_PC specifies the location to receive control when the
unwinding operation is complete. The default is to continue at the instruction
following the call to the last procedure activation removed from the stack.
The function value SUCCESS is a standard success code (SS$_NORMAL), or
indicates failure with one of the following return status condition values:

2-44

•

No signal active (SS$_NOSIGNAL)

•

Already unwinding (SS$_UNWINDING)

•

Insufficient frames for depth (SS$_INSFRAME)

VAX Procedure Calling and Condition Handling Standard

The unwinding operation occurs when the handler returns to the condition
handling facility. Unwinding is done by scanning back through the stack
and calling each handler that has been associated with a frame. The
handler is called with exception SS$_UNWIND to perform any application
specific cleanup. In particular, if the depth specified includes unwinding the
establisher's frame, the current handler will be recalled with this unwind
exception.
The call to the handler takes the same form as previously described, with the
following values:
signal.args
1
condition.value = SS$_UNWIND
mechanism.args

4
frame
depth
RO
R1

establisher's frame
0 (that is, unwinding self)
RO that unwind will restore
R1 that unwind will restore

After each handler is called, the stack is cut back to the previous frame.
Note that the exception vectors are not checked because they are not being
removed. Any function value from the handler is ignored. To specify the
value of the top level function being unwound, the handler should modify
RO and R1 in the mechanism_args vector. They will be restored from
the mechanism_args vector at the end of the unwind. Depending on the
arguments to SYS$UNWIND, the unwinding operation will be terminated as
follows:
SYS$UNWIND(0,0)

Unwind to the establisher's caller with
the establisher function value restored
from RO and R1 in the mechanism-args
vector.

SYS$UNWIND(depth,0)

Unwind to the establisher at the point
of the call that resulted in the exception.
The contents of RO and R1 are restored
from RO and R1 in the mechanism_args
vector.

SYS$UNWIND(depth,location)

Unwind to the specified procedure
activation and transfer to a specified
location with the contents of RO and R1
from RO and R1 in the mechanism_args
vector.

SYS$UNWIND can be called whether the condition was a software exception
signaled by calling LIB$SIGNAL or LIB$STOP, or was a hardware exception.
Calling SYS$UNWIND is the only way to continue execution after a call to
LIB$STOP.

2—45

VAX Procedure Calling and Condition Handling Standard

2.12.5 Signaler's Registers
Because the handler is called, and can in turn call routines, the actual values
of the registers that were in use at the time of the signal or exception can
be scattered on the stack. To find the registers R2 through FP, a scan of
stack frames must be performed starting with the current frame and ending
with the call to the handler. During the scan, the last frame found to save
a register contains that register's contents at the time of the exception. If no
frame saved the register, the register is still active in the current procedure.
The frame of the call to the handler can be identified by the return address of
SYS$CALL_JTANDL+4. Thus, the registers are
In mechanism_args

RO, R1

2.13

R2..R11

Last frame saving it

old AP of SYS$CALL_HANDL+4 frame

old FP of SYS$CALL_HANDL+4 frame

equal to end of signal-args vector+4

PC, PSL

at end of signal-args vector

Multiple Active Signals
A signal is said to be active until the signaler gets control again or is
unwound. A signal can occur while a condition handler or a procedure
it has called is executing in response to a previous signal. For example,
procedures (A, B, C, . . . ) establish condition handlers (Ah, Bh, Ch, . . . ),
respectively. If A calls B and B calls C which signals S and Ch resignals, then
Bh gets control. If Bh calls procedure X and X calls procedure Y and Y signals
T the stack is:
<signal T>
Y
X

Bh
<signal S>
C

B
A
which was programmed:
A
B

-►Bh
X

C
<signal S>

<signal T>
ZK-1884-84

The handlers are searched for in the order: Yh, Xh, Bhh, Ah. Note that Ch
is not called because it is a structural descendant of B. Bh is not called again
because that would require it to be recursive. Recursive handlers could not be
coded in nonrecursive languages such as FORTRAN. Instead, Bh can establish
itself or another procedure as its handler (Bhh).

2-46

VAX Procedure Calling and Condition Handling Standard

The following algorithm is used on the second and subsequent signals that
occur before the handler for the original signal returns to the condition
handling facility. The primary and secondary exception vectors are checked.
Then, however, the search backward in the process stack is modified. In
effect, the stack frames traversed in the first search are skipped over in the
second search. Thus, the stack frame preceding the first condition handler up
to and including the frame of the procedure that has established the handler
is skipped. Despite this skipping, depth is not incremented. For example, the
stack frames traversed in the first and second search are skipped over in a
third search. Note that if a condition handler signals, it will not automatically
be invoked recursively. However, if a handler itself establishes a handler,
this second handler will be invoked. Thus, a recursive condition handler
should start by establishing itself. Any procedures invoked by the handler are
treated in the normal way that is, exception signaling follows the stack up to
the condition handler.
If an unwinding operation is requested while multiple signals are active, all
the intermediate handlers are called for the operation. For example, in the
above diagram, if Ah specifies unwinding to A, the following handlers will be
called for the unwind: Yh, Xh, Bhh, Ch, and Bh.
For proper hierarchical operation, an exception that occurs during execution
of a condition handler established in an exception vector should be handled
by that handler rather than propagating up the activation stack. To prevent
such propagation, the vectored condition handler should establish a handler
in its stack frame to handle all exceptions.

2-47

VMS Data Types

A.1

VMS Data Types
The VMS Usage entry in the documentation format for system routines
indicates the VMS data type of the argument. Each VMS data type has only
one storage representation. For example, the VMS data type access_mode
is an unsigned byte. In addition, a VMS data type may or may not have a
conceptual meaning.
Most VMS data types may be considered as conceptual types; that is, they
carry meaning that is unique in the context of the VMS operating system. The
access—mode is one of these. The storage representation of this VMS type is
an unsigned byte, and the conceptual content of this unsigned byte is the fact
that it designates a hardware access mode and has therefore only four valid
values: 0 , designating kernel mode; 1 , executive mode; 2 , supervisor mode;
and 3 , user mode. However, some VMS data types are not conceptual types;
that is, they specify a storage representation but carry no other semantic
content from the point of view of VAX/VMS. For example, the VMS data
type byte—signed is not a conceptual type.
Note: The VMS Usage entry is NOT a traditional data type such as the VAX
standard data types byte, word, longword, and so on. It is significant only
within the VMS operating system environment and is intended solely to
expedite data declarations within application programs.
To use the VMS Usage entry, perform the following procedure:
1

Find the data type in Table A-l and read its definition

Find the same VMS data type in the appropriate VAX language
implementation table (Tables A-2 through A-l3) and its corresponding
source language type declaration

Use this code as your type declaration in your application program. Note
that, in some instances, you may have to modify the declaration.

Table A-l lists and describes the VMS data types.

A—1

VMS Data Types

Table A-1

VMS Data Types

Data Type

Definition

access_bit_names

Homogeneous array of 32 quadword
descriptors; each descriptor defines the name
of one of the 32 bits in an access mask. The
first descriptor names bit <0> , the second
descriptor names bit <1> , and so on.

access_mode

Unsigned byte denoting a hardware access
mode. This unsigned byte can take four
values: 0 specifies kernel mode; 1 , executive
mode; 2 , supervisor mode; and 3 , user
mode.

address

Unsigned longword denoting the virtual
memory address of either data or code,
but not of a procedure entry mask (which is of
type procedure).

address_range

Unsigned quadword denoting a range of virtual
addresses, which identify an area of memory.
The first longword specifies the beginning
address in the range; the second longword
specifies the ending address in the range.

arg_list

Procedure argument list consisting of one
to 256 longwords. The first longword
contains an unsigned integer count of the
number of successive, contiguous longwords,
each of which is an argument to be passed
to a procedure by means of a VAX CALL
instruction.
The argument list has the following format:

A-2

ast_procedure

Unsigned longword integer denoting the entry
mask to a procedure to be called at AST level.
(Procedures that are not to be called at AST
level are of type procedure.)

boolean

Unsigned longword denoting a Boolean truth
value flag. This longword may have only two
values: 1 (true) and 0 (false).

VMS Data Types

Table A—1 (Cont.)

VMS Data Types

Data Type

Definition

byte_signed

This VMS data type is the same as the data
type byte integer (signed) in Table 1-3.

byte_unsigned

This VMS data type is the same as the data
type byte (unsigned) in Table 1-3.

channel

Unsigned word integer that is an index to an
I/O channel.

char_string

String of from 0 to 65,535 8-bit characters.
This VMS data type is the same as the data
type character string in Table 1-3. The
following diagram shows the character string
XYZ.

ZK-4202-85

A—3

VMS Data Types

Table A—1 (Cont.)

VMS Data Types

Data Type

Definition

complex_number

One of the VAX standard complex floating¬
point data types. The three complex floating¬
point numbers are: F_floating complex, D_
floating complex, and G_floating complex.
An F_floating complex number (r,i) is
comprised of two F_floating point numbers.
The first F_floating point number is the real
part (r) of the complex number; the second
F_floating point number is the imaginary part
(i). The structure of an F_floating complex
number is as follows:
my_tree

1010'

1st (STRING)

111'

2nd (INTEGER)

-1

1000

3rd (STRING)

'a'

'b'

'c'.

'd'

'x'

values

(0)

(11)

(5)

(-5)

(44)

(22)
ZK-4293-85

A—4

VMS Data Types

Table A—1 (Cont.)

VMS Data Types

Data Type

Definition
A D_floating complex number (r,i) is
comprised of two D_floating point numbers.
The first D_floating point number is the real
part (r) of the complex number; the second
D_floating point number is the imaginary part
(i). The structure of an D_floating complex
number is as follows:
15 14

43
EXPONENT

REAL
PART

FRACTION

: A

FRACTION

: A+2

FRACTION

: A+4

FRACTION

: A+6

EXPONENT

FRACTION

: A8

IMAGINARY

FRACTION

: A + 10

PART

FRACTION

: A + 12

FRACTION

: A + 14
ZK-4200-85

A G_floating complex number (r,i) is
comprised of two G_floating point numbers.
The first G_floating point number is the real
part (r) of the complex number; the second
G_floating point number is the imaginary part
(i). The structure of an G_floating complex
number is as follows:
15 14

[ s EXPONENT FRACTION : A
)

FRACTION

: A+2

PART J

FRACTION

: A+4

FRACTION

: A+6

EXPONENT FRACTION

: A8

REAL

[
(
IMAGINARY 1

FRACTION

: A+10

PART

FRACTION

: A + 12

(

FRACTION

: A + 14
ZK-4201-85

A—5

VMS Data Types

Table A-1 (Cont.)

VMS Data Types

Data Type

Definition

cond_value

Unsigned longword integer denoting a
condition value (that is, a return status or
system condition code), which is typically
returned by a procedure in RO. The structure
of a condition value is as follows:

facility number

message number

ZK-1795-84

Depending on your specific needs, you can
test just the low-order bit, the low-order three
bits, or the entire value.
•

The low-order bit indicates successful
(1) or unsuccessful (0) completion of the
service.

•

The low-order three bits, taken together,
represent the severity of the error.

•

The remaining bits <31:3> classify
the particular return condition and the
operating system component that issued
the condition value.

Each numeric condition value has a unique
symbolic name in the following format, where
code is a mnemonic describing the return
condition.
SS$_code

context

A—6

Unsigned longword that is used by a called
procedure to maintain position over an iterative
sequence of calls. It is usually initialized by the
caller, but thereafter manipulated by the called
procedure.

VMS Data Types

Table A-1 (Cont.)

VMS Data Types

Data Type

Definition

date_time

64-bit unsigned, binary integer denoting a
date and time as the number of elapsed
100-nanosecond units since 00:00 o'clock,
November 17, 1858. This VMS data type is
the same as the data type absolute date and
time in Table 1-3.

device_name

Character string denoting the 1- to 15character name of a device. It can be a
logical name, but if it is, it must translate to a
valid device name. If the device name contains
a colon (:), the colon and the characters
past it are ignored. When an underscore (_)
precedes device name string, it indicates that
the string is a physical device name.

ef_cluster_name

Character string denoting the 1- to 15character name of an event flag cluster. It
can be a logical name, but if it is, it must
translate to a valid event flag cluster name.

ef_number

Unsigned longword integer denoting the
number of an event flag. Local event flags
numbered 32 to 63 are available to your
programs.

exit_handler_block

Variable-length structure denoting an exit
handler control block. This control block,
which describes the exit handler, is depicted in
the following diagram.

0
forward link (used by VMS only)
exit handler address
these 3 bytes must be 0

arg. count

Address of condition value (written by VMS)

additional arguments for the
exit handler; these are optional;
one argument per longword

ZK-1714-84

fab

Structure denoting an RMS file access block.

A—7

VMS Data Types

Table A-1 (Cont.)

VMS Data Types

Data Type

Definition

file-protection

Unsigned word that is a 16-bit mask that
specifies file protection. The mask contains
four 4-bit fields, each of which specifies the
protection to be applied to file access attempts
by one of the four categories of user: from
the rightmost field to the leftmost field, (1)
system users, (2) the file owner, (3) users in
the same UIC group as the owner, and (4) all
other users (the world). Each field specifies,
from the rightmost bit to the leftmost bit: (1)
read access, (2) write access, (3) execute
access, (4) delete access. Set bits indicate
that access is denied.
The following diagram depicts the 16-bit
file-protection mask.

WORLD

GROUP
W

15 14 13 12 11 10 9

SYSTEM

OWNER

E
0

ZK-1706-84

floating_point

One of the VAX standard floating-point data
types. These types are F_floating, D_floating,
G_floating, and H_floating.
The structure of an F_floating number is as
follows:
15 14

7 6

EXPONENT

0
FRACTION

FRACTION
31

: A
: A+2

16
ZK-4197-85

A—8

VMS Data Types

Table A-1 (Cont.)
Data Type

VMS Data Types
Definition
The structure of a D_floating number is as
follows:
15 14

S EXPONENT

0
FRACTION

: A

FRACTION

: A+2

FRACTION

: A+4

FRACTION

: A+6

48
ZK-4198-85

The structure of a G_floating number is as
follows:

: A
: A+2
: A+4
: A+6
63

48
ZK-4199-85

The structure of an H_floating number is as
follows:
15 14

127

0
EXPONENT

: A

FRACTION

: A+2

FRACTION

: A+4

FRACTION

: A+6

FRACTION

: A+8

FRACTION

: A + 10

FRACTION

: A + 12

FRACTION

: A + 14
113
ZK-4196-85

A—9

VMS Data Types

Table A-1 (Cont.)

VMS Data Types

Data Type

Definition

function_code

Unsigned longword specifying the exact
operations a procedure is to perform. This
longword has two word-length fields: the
first field is a number specifying the major
operation; the second field is a mask or bit
vector specifying various suboperations within
the major operation.

identifier

Unsigned longword that identifies an object
returned by the system.

io_status_block

Quadword structure containing information
returned by a procedure that completes
asynchronously. The information returned
varies depending on the procedure. The
following figure illustrates the format of the
information written in the IOSB for SYS$QIO.

16 15

0
condition value

count

device-dependent information
ZK-856-82

The first word contains a condition value
indicating the success or failure of the
operation. The condition values used are
the same as for all returns from system
services; for example, SS$_NORMAL indicates
successful completion.
The second word contains the number of
bytes actually transferred in the I/O operation.
Note that for some devices this word contains
only the low-order word of the count.
The second longword contains device¬
dependent return information.
To ensure successful I/O completion and the
integrity of data transfers, the IOSB should be
checked following I/O requests, particularly for
device-dependent I/O functions.

A—10

VMS Data Types

Table A-1 (Cont.)

VMS Data Types

Data Type

Definition

item_list_2

Structure that consists of one or more
item descriptors and that is terminated by
a longword containing 0 . Each item descriptor
is a 2-longword structure that contains three
fields. The following diagram depicts a single
item descriptor:

15
item code

0
component length

component address
ZK-1 709-84

The first field is a word in which the service
writes the length (in characters) of the
requested component. If the service does
not locate the component, it returns the value
0 in this field and in the component address
field.
The second field contains a user-supplied,
word-length symbolic code that specifies
the component desired. The item codes are
defined by the macros that are specific to the
service.
The third field is a longword in which the
service writes the starting address of the
component. This address is within the input
string itself.

A—11

VMS Data Types

Table A-1 (Cont.)

VMS Data Types

Data Type

Definition

item_list_3

Structure that consists of one or more
item descriptors and that is terminated by
a longword containing 0 . Each item descriptor
is a 3-longword structure that contains four
fields. The following diagram depicts the
format of a single item descriptor.
15

0
buffer length

item code
buffer address
return length address

ZK-1705-84

The first field is a word containing a usersupplied integer specifying the length (in bytes)
of the buffer in which the service writes the
information. The length of the buffer needed
depends upon the item code specified in the
item code field of the item descriptor. If the
value of buffer length is too small, the service
truncates the data.
The second field is a word containing a usersupplied symbolic code specifying the item of
information that the service is to return. These
codes are defined by macros that are specific
to the service.
The third field is a longword containing the
user-supplied address of the buffer in which
the service writes the information.
The fourth field is a longword containing the
user-supplied address of a word in which
the service writes the length in bytes of the
information it actually returned.

A-12

item_list_pair

Structure that consists of one or more
longword pairs, or doublets and is terminated
by a longword containing 0 . Typically, the
first longword contains an integer value such
as a code. The second longword can contain
a real or integer value.

item_quota_list

Structure that consists of one or more quota
descriptors and that is terminated by a byte
containing a value defined by the symbolic
name PQL$_LISTEND. Each quota descriptor
consists of a 1-byte quota name followed by
an unsigned longword containing the value for
that quota.

VMS Data Types

Table A-1 (Cont.)

VMS Data Types

Data Type

Definition

lock_id

Unsigned longword integer denoting a lock
identifier. This lock identifier is assigned by
the lock manager facility to a lock when the
lock is granted.

lock_status_block

Structure into which the lock manager facility
writes status information about a lock. A
lock status block always contains at least two
longwords: the first word of the first longword
contains a condition value; the second word
of the first longword is reserved to DIGITAL;
and the second longword contains the lock
identifier.
The lock status block receives the final
condition value and the lock identification, and
optionally contains a lock value block. When
a request is queued, the lock identification is
stored in the lock status block even if the lock
has not been granted. This allows a procedure
to dequeue locks that have not been granted.
The condition value is placed in the lock status
block only when the lock is granted (or when
errors occur in granting the lock).
The following diagram depicts a lock status
block that includes the optional 16-byte lock
value block.

reserved

condition value

lock identification

16 byte lock value block
only used when LCK$M_VALBLK is set

ZK-376-81

lock_value_block

16-byte block that the lock manager facility
includes in a lock status block if the user
requests it. The contents of the lock value
block are user-defined and are not interpreted
by the lock manager facility.

A-13

VMS Data Types

Table A-1 (Cont.)

A-14

VMS Data Types

Data Type

Definition

logical-name

Character string of from 1 to 255 characters
that identifies a logical name or equivalence
name to be manipulated by VMS logical name
system services. Logical names that denote
specific VMS objects have their own VMS
types: for example, a logical name identifying
a device has the VMS type device—name.

longword—signed

This VMS data type is the same as the data
type longword integer (signed) in Table 1-3.

longword—unsigned

This VMS data type is the same as the data
type longword (unsigned) in Table 1-3.

mask_byte

Unsigned byte wherein each bit is interpreted
by the called procedure. A mask is also
referred to as a set of flags or as a bit mask.

mask—longword

Unsigned longword wherein each bit is
interpreted by the called procedure. A mask
is also referred to as a set of flags or as a bit
mask.

mask—quadword

Unsigned quadword wherein each bit is
interpreted by the called procedure. A mask
is also referred to as a set of flags or as a bit
mask.

mask—word

Unsigned word wherein each bit is interpreted
by the called procedure. A mask is also
referred to as a set of flags or bit mask.

null—arg

Unsigned longword denoting a null argument.
A null argument is an argument whose only
purpose is to hold a place in the argument list.

octaword—signed

This VMS data type is the same as the data
type octaword integer (signed) in Table 1-3.

octaword—unsigned

This VMS data type is the same as the data
type octaword (unsigned) in Table 1-3.

VMS Data Types

Table A-1 (Cont.)

VMS Data Types

Data Type

Definition

page_protection

Unsigned longword specifying page protection
to be applied by the VAX hardware.
Protection values are specified using bits
<3:0> ; bits <31:4> are ignored.
The $PRTDEF macro defines the following
symbolic names for the protection codes:
Symbol

Description

PRT$C_NA

No access

PRT$C_KR

Kernel read only

PRT$C_KW

Kernel write

PRT$C_ER

Executive read only

PRT$C_EW

Executive write

PRT$C_SR

Supervisor read only

PRT$C_SW

Supervisor write

PRT$C_UR

User read only

PRT$C_UW

User write

PRT$C_ERKW

Executive read; kernel
write

PRT$C_SRKW

Supervisor read; kernel
write

PRT$C_SREW

Supervisor read; executive
write

PRT$C_URKW

User read; kernel write

PRT$C_UREW

User read; executive write

PRT$C_URSW

User read; supervisor write

If the protection is specified as 0 , the
protection defaults to kernel read only.
procedure

Unsigned longword denoting the entry mask
to a procedure that is not to be called at AST
level. (Arguments specifying procedures to
be called at AST level have the VMS type
ast—procedure.)

process-id

Unsigned longword integer denoting a process
identifier (PID). This process identifier is
assigned by VMS to a process when the
process is created.

process_name

Character string, containing 1 to 15 characters,
that specifies the name of a process.

quadword_signed

This VMS data type is the same as the data
type quadword integer (signed) in Table 1-3.

quadword_unsigned

This VMS data type is the same as the data
type quadword (unsigned) in Table 1-3.

A-1 5

VMS Data Types

Table A-1 (Cont.)

VMS Data Types

Data Type

Definition

rights_holder

Unsigned quadword specifying a user's access
rights to a system object. This quadword
consists of two fields: the first is an unsigned
longword identifier (VMS type rights—id)
and the second is a longword bit mask
wherein each bit specifies an access right.
The following diagram depicts the format of a
rights holder.

UIC Identifier of Holder
0
ZK-1903-84

rights_id

Unsigned longword denoting a rights identifier,
which identifies an interest group in the
context of the VMS security environment.
This rights environment may consist of all or
part of a user's user identification code (UIC).
Identifiers have two formats in the rights
database: UIC format (VMS type uic) and ID
format. The high order bits of the identifier
value specify the format of the identifier. Two
high order zero bits identify a UIC format
identifier; bit <31> , set to 1 , identifies an
ID format identifier.
Bit <31> , set to 1 , specifies ID format.
Bits <30:28> are reserved by DIGITAL. The
remaining bits specify the identifier value. The
following diagram depicts the ID format of a
rights identifier.
0

31
1000

identifier
ID Format
ZK-1906-84

To the system, an identifier is a binary value;
however, to make identifiers easy to use, the
system translates the binary identifier value
into an identifier name. The binary value and
the identifier name are associated in the rights
database.

A-16

VMS Data Types

Table A-1 (Cont.)
Data Type

VMS Data Types
Definition
An identifier name consists of 1-31
alphanumeric characters and contains at least
one nonnumeric character. An identifier name
cannot consist entirely of numeric characters.
It can include the characters A through Z,
dollar signs ($) and underscores (_), as well
as the numbers 0 through 9. Any lowercase
characters are automatically converted to
uppercase.

rab

Structure denoting an RMS record access
block.

sectioned

Unsigned quadword denoting a global section
identifier. This identifier specifies the version
of a global section and the criteria to be used
in matching that global section.

section_name

Character string denoting a 1 to 43-character
global-section name. This character string can
be a logical name, but it must translate to a
valid global-section name.

system_access_id

Unsigned quadword that denotes a system
identification value that is to be associated
with a rights database.

time_name

Character string specifying a time value in VMS
format.

uic

Unsigned longword denoting a user
identification code (UIC). Each UIC is unique
and represents a system user. The UIC
identifier contains two high order bits that
designate format, a member field, and a
group field. Member numbers range from 0
to 65,534; group numbers range from 1 to
16,382. The following diagram depicts the
UIC format.
0

31
00

group

member

UIC Format
ZK-1905-84

user_arg

Unsigned longword denoting a user-defined
argument. This longword is passed to a
procedure as an argument, but the contents of
the longword are defined and interpreted by
the user.

varying_arg

Unsigned longword denoting a variable
argument. A variable argument can have
variable types, depending on specifications
made for other arguments in the call.

A-17

VMS Data Types

Table A—1 (Cont.)

A.2

VMS Data Types

Data Type

Definition

vector_byte_signed

A homogeneous array whose elements are all
signed bytes.

vector_byte_unsigned

A homogeneous array whose elements are all
unsigned bytes.

vector_longword_signed

A homogeneous array whose elements are all
signed longwords.

vector_longword_unsigned

A homogeneous array whose elements are all
unsigned longwords.

vector_quadword_signed

A homogeneous array whose elements are all
signed quadwords.

vector_quadword_unsigned

A homogeneous array whose elements are all
unsigned quadwords.

vector_word_signed

A homogeneous array whose elements are all
signed words.

vector_word_unsigned

A homogeneous array whose elements are all
unsigned words.

word_signed

This VMS data type is the same as the data
type word integer (signed) in Table 1-3.

word_unsigned

This VMS data type is the same as the data
type word (unsigned) in Table 1-3.

VAX Ada Implementation
The following table lists VMS data types and their corresponding VAX®
Ada® data type declarations.
Table A-2

VAX Ada Implementation

VMS Data Structure

VAX Ada Declaration

access_bit _names

STARLET.ACCESS_BIT_NAMES_TYPE

access_mode

ST ARLET. ACCESS_MODE_TYPE

address

SYSTEM.ADDRESS

address_range

STARLET. ADDRESS_RANGE_TYPE

arg_list

STARLET. ARG_LIST_TYPE

ast_procedure

SYSTEM. AST_HANDLER

boolean

ST ANDARD.BOOLEAN

byte_signed

ST ANDARD.SHORT_SHORT__INTEGER

byte_unsigned

SYSTEM.UNSIGNED_BYTE

channel

ST ARLET.CHANNEI_TYPE

char_string

ST ANDARD.STRING

VAX is a trademark of the Digital Equipment Corporation
Ada is a registered trademark of the U.S. Government, Ada Joint Program Office

A—18

VMS Data Types

Table A-2 (Cont.)

VAX Ada Implementation

VMS Data Structure

VAX Ada Declaration

complex_number

User-defined record

cond_value

CONDITION—HANDLING.COND—VALUE—TYPE

context

ST ARLET.CONTEXT—TYPE

date_time

ST ARLET.DATE—TIME—TYPE

device_name

ST ARLET.DEVICE—NAME—TYPE

ef_cluster_name

ST ARLET.EF—CLUSTER—NAME—TYPE

ef_number

ST ARLET.EF—NUMBER—TYPE

exit_handler_block

ST ARLET.EXIT—HANDLER—BLOCK—TYPE

fab

STARLET.FAB—TYPE

file_protection

STARLET.FILE—PROTECTION—TYPE

floating-point

STANDARD.FLOAT
ST ANDARD.LONG—FLOAT
STANDARD.LONG_LONG_FLOAT
SYSTEM.F-FLOAT
SYSTEM.D_FLOAT
SYSTEM.G-FLOAT
SYSTEM. H-FLOAT

function_code

ST ARLET.FUNCTION—CODE—TYPE

identifier

SYSTEM.UNSIGNED-LONGWORD

io_status-block

STARLET. IOSB-TYPE

item_list_pair

SYSTEM.UNSIGNED-LONGWORD

item—list _2

ST ARLET.ITEM—LIST—2_TYPE

item_list—3

STARLET.ITEM—LIST—TYPE

item_quota—list

User-defined record

lock—id

ST ARLET.LOCK—ID_TYPE

lock—status—block

STARLET. LOCK_STATUS_BLOCK_TYPE

lock—value—block

ST ARLET.LOCK—VALUE—BLOCK—TYPE

logical—name

STARLET.LOGICAL—NAME—TYPE

longword—signed

STANDARD.INTEGER

longword—unsigned

SYSTEM.UNSIGNED-LONGWORD

mask—byte

SYSTEM.UNSIGNED_BYTE

mask—longword

SYSTEM.UNSIGNED-LONGWORD

mask—quadword

SYSTEM.UNSIGNED-QUADWORD

mask—word

SYSTEM.UNSIGNED-WORD

null—arg

SYSTEM.UNSIGNED-LONGWORD

octaword—signed

array( 1 ..4) of SYSTEM.UNSIGNED-LONGWORD

octaword—unsigned

array! 1 ..4) of SYSTEM.UNSIGNED-LONGWORD

page_protection

STARLET.PAGE_PROTECTION_TYPE

procedure

SYSTEM.ADDRESS

process—id

STARLET.PROCESS—ID_TYPE

process—name

ST ARLET.PROCESS—NAME—TYPE

A-19

VMS Data Types

Table A-2 (Cont.)

A.3

VAX Ada Implementation

VMS Data Structure

VAX Ada Declaration

quadword_signed

SYSTEM. UNSIGNED_QUADWORD

quadword_unsigned

SYSTEM.UNSIGNED_QUADWORD

rights_holder

STARLET.RIGHTS_HOLDER_TYPE

rights_id

ST ARLET.RIGHTS_ID_TYPE

rab

ST ARLET.RAB_TYPE

section _id

STARLET.SECTION_ID_TYPE

section_name

ST ARLET.SECTION_NAME_TYPE

system_access_id

STARLET.SYSTEM_ACCESS_ID_TYPE

time_name

STARLET.TIME_NAME_TYPE

uic

ST ARLET.UIC—TYPE

user_arg

ST ARLET.USER_ARG_TYPE

varying_arg

SYSTEM.UNSIGNED_LONGWORD

vector_byte_signed

array( 1 ..n) of STANDARD.SHORT_SHORT_INTEGER

vector_byte_unsigned

array! 1 ..n) of SYSTEM.UNSIGNED_BYTE

vector_longword_signed

array! 1 ..n) of STANDARD.INTEGER

vector_longword_unsigned

array! 1 ..n) of SYSTEM.UNSIGNED_LONGWORD

vector_quadword_signed

array! 1 ..n) of SYSTEM.UNSIGNED_QUADWORD

vector_quadword_unsigned

array! 1 ..n) of SYSTEM.UNSIGNED_QUADWORD

vector_word_signed

array! 1 ..n) of STANDARD.SHORT_INTEGER

vector_word_unsigned

array! 1 ..n) of SYSTEM.UNSIGNED_WORD

word_signed

array! 1..n) of STANDARD.SHORT_INTEGER

word-unsigned

SYSTEM.UNSIGNED_WORD

VAX APL Implementation
The following table lists VMS data types and their corresponding VAX APL
data type declarations.

A—20

VMS Data Types

Table A—3

VAX APL Implementation

VMS Data Type

VAX APL Declaration

access_bit_names

access_mode

/TYPE=BU

address

address_range

arg_list

ast_procedure

boolean

/TYPE=V

byte_signed

/TYPE=B

byte_unsigned

/TYPE=BU

channel

/TYPE=WU

char_string

/TYPE=T

complex_number

/TYPE=FC
/TYPE=DC
/TYPE=GC
/TYPE=HC

cond_value

/TYPE=LU

context

date_time

device_name

/TYPE=T

ef_cluster_name

/TYPE=T

ef_number

/TYPE=LU

exit_handler_block

fab

file_protection

/TYPE=WU

floating-point

/TYPE=F
/TYPE=D
/TYPE=G
/TYPE=H

function_code

identifier

io_status_block

item_list_2

item_list_3

item_list_pair

item_quota_list

lock_id

/TYPE=LU

lock_status_block

lock_value_block

logical_name

/TYPE=T

longword_signed

/TYPE=L

longword_unsigned

/TYPE=LU

A—21

VMS Data Types

Table A-3 (Cont.)

A.4

VAX APL Implementation

VMS Data Type

VAX APL Declaration

mask_byte

/TYPE=BU

mask_longword

/TYPE=LU

mask_quadword

mask_word

/TYPE=WU

null_arg

/TYPE=LU

octaword_signed

octaword_unsigned

page_protection

/TYPE=LU

procedure

process-id

/TYPE=LU

process_name

/TYPE=T

quadword—signed

quadword—unsigned

rights_holder

rights_id

/TYPE=LU

rab

section_id

section_name

/TYPE=T

system _access_id

time_name

/TYPE=T

uic

/TYPE=LU

user_arg

/TYPE=LU

varying_arg

vector_byte_signed

/TYPE=B

vector_byte_unsigned

/TYPE=BU

vector_longword_signed

/TYPE=L

vector_longword_unsigned

/TYPE=LU

vector_quadword_signed

vector_quadword_unsigned

vector_word_signed

/TYPE=W

vector_word_unsigned

/TYPE=WU

word_signed

/TYPE=W

word_unsigned

/TYPE=WU

VAX BASIC Implementation
The following table lists VMS data types and their corresponding VAX BASIC
data type declarations.

A—22

VMS Data Types

Table A-4

VAX BASIC Implementation

VMS Data Type

VAX BASIC Declaration

access_bit_names

access_mode

BYTE (signed)

address

LONG

address_range

LONG address_range (1)
or
RECORD Address_range
LONG beginning_address
LONG ending_address
END RECORD

arg_list

ast_procedure

EXTERNAL LONG ast_proc

boolean

LONG

byte_signed

BYTE

byte_unsigned

BYTE1

channel

WORD

char_string

STRING

complex_number

RECORD complex
REAL real_part
REAL imaginary_part
END RECORD

cond_value

LONG

context

LONG

date_time

RECORD date_time
LONG FILL (2)
END RECORD

device_name

STRING

ef_cluster_name

STRING

ef_number

LONG

exit_handler_block

RECORD EHCB
LONG flink
LONG handler_addr
BYTE arg_count
BYTE FILL) 3)
LONG status_value_addr
END RECORD

fab

file_protection

LONG

floating-point

SINGLE
DOUBLE
GFLOAT
HFLOAT

Although unsigned data types are not directly supported in VAX BASIC, you
may substitute the signed equivalent provided you do not exceed the range of the
signed data type.

A—23

VMS Data Types

Table A-4 (Cont.)

A—24

VAX BASIC Implementation

VMS Data Type

VAX BASIC Declaration

function_code

RECORD function-code
WORD major-function
WORD subfunction
END RECORD

identifier

LONG

io_status_block

RECORD iosb
WORD iosb-field (3)
END RECORD

item_list_2

RECORD item_list_two
GROUP item(15)
VARIANT
CASE
WORD comp_length
WORD code
LONG comp_address
CASE
LONG terminator
END VARIANT
END GROUP
END RECORD

item_list_3

RECORD item_list_3
GROUP item (15)
VARIANT
CASE
WORD buf_len
WORD code
LONG buffer_address
LONG length_address
CASE
LONG terminator
END VARIANT
END GROUP
END RECORD

item_list_pair

RECORD item_list_pair
GROUP item(15)
VARIANT
CASE
LONG Code
LONG value
CASE
LONG Terminator
END VARIANT
END GROUP
END RECORD item_list_pair

VMS Data Types

Table A-4 (Cont.)

VAX BASIC Implementation

VMS Data Type

VAX BASIC Declaration

item_quota_list

RECORD item_quota—list
GROUP quota(n)
VARIANT
CASE
BYTE quota—name
LONG value
CASE
BYTE list-end
END VARIANT
END GROUP
END RECORD

lock_id

LONG

lock_status_block

lock_value__block

logical-name

STRING

longword—signed

LONG

longword_unsigned

LONG1

mask_byte

BYTE

mask—longword

LONG

mask—quadword

RECORD quadword
LONG FILL (2)
END RECORD1

mask—word

WORD

null—arg

A null argument is indicated by a comma
used as a placeholder in the argument list.

octaword—signed

octaword—unsigned

page_protection

LONG

procedure

EXTERNAL LONG proc

process—id

LONG

process—name

STRING

quadword—signed

RECORD quadword
LONG FILL (2)
END RECORD

quadword—unsigned

RECORD quadword
LONG FILL (2)
END RECORD1

rights—holder

RECORD quadword
LONG FILL (2)
END RECORD1

rights—id

LONG

rab

Although unsigned data types are not directly supported in VAX BASIC, you
may substitute the signed equivalent provided you do not exceed the range of the
signed data type.
A—25

VMS Data Types

Table A—4 (Cont.)

VAX BASIC Implementation

VMS Data Type

VAX BASIC Declaration

section_id

RECORD quadword
LONG FILL (2)
END RECORD1

section_name

STRING

system _access_id

RECORD quadword
LONG FILL( 2)
END RECORD1

time_name

STRING

uic

LONG

user_arg

LONG

varying_arg

Dependent upon application.

vector_byte_signed

BYTE array) n)

vector_byte_unsigned

BYTE array! n I1

vector_longword_signed

LONG array! n)

vector_longword_unsigned

LONG array! n)1

vector_quadword_signed

vector_quadword_unsigned

vector_word_signed

WORD array! n)

vector_word_unsigned

WORD array! n)1

word_signed

WORD

word-unsigned

WORD1

Although unsigned data types are not directly supported in VAX BASIC, you
may substitute the signed equivalent provided you do not exceed the range of the
signed data type.

A.5

VAX BLISS Implementation
The following table lists VMS data types and their corresponding VAX BLISS
data type declarations.

A—26

VMS Data Types

Table A-5

VAX BLISS Implementation

VMS Data Type

VAX BLISS Declaration

access_bit _names

BLOCKVECTOR[32,8/BYTE]

access—mode

UNSIGNED BYTE

address

UNSIGNED LONG

address—range

VECTOR[2,LONG/UNSIGNED]

arg_list

VECTOR[n,LONG,UNSIGNED]
where n is the number of arguments + 1

ast_procedure

UNSIGNED LONG

boolean

UNSIGNED LONG

byte_signed

SIGNED BYTE

byte_unsigned

UNSIGNED BYTE

channel

UNSIGNED WORD

char_string

VECTOR[65536,BYTE,UNSIGNED]

complex—number

F_Complex: VECTOR[2,LONG]
D_Complex: VECTOR[4,LONG]
G_Complex: VECTOR[4/LONG]
H_Complex: VECTOR[8,LONG]

cond_value

UNSIGNED LONG

context

UNSIGNED LONG

date_time

VECTOR[2,LONG,UNSIGNED]

device—name

VECTOR[n,BYTE,UNSIGNED]
where n is the length of the device name

ef_cluster—name

VECTOR[n,BYTE, UNSIGNED]
where n is the length of the event flag
cluster name

ef_ number

UNSIGNED LONG

exit—handler—block

BLOCK[n,BYTE]
where n is the size of the exit handler
control block

fab

$FAB_DECL (from STARLET.REQ)

file_protection

BLOCK[2/BYTE]

floating-point

F_Floating: VECTOR[1 ,LONG]
D_Floating: VECTOR[2,LONG]
G_Floating: VECTOR[2/LONG]
H_Floating: VECTOR[4,LONG]

function-code

BLOCK[2,WORD]

identifier

UNSIGNED LONG

io_status—block

BLOCK[8,BYTE]

item_list—2

BLOCKVECTOR[n,8,BYTE]
where n is the number of the item
descriptors + 1

item_list—3

BLOCKVECTOR[n, 12,BYTE]
where n is the number of the item
descriptors + 1

A—27

VMS Data Types

Table A-5 (Cont.)
VMS Data Type

VAX BLISS Implementation
VAX BLISS Declaration
$ITMLST_DECL/$ITMLST_INIT
from STARLET.REQ

A—28

item_list_pair

BL0CKVECT0R[n,2,L0NG]
where n is the number of the item
descriptors + 1

item_quota_list

BL0CKVECT0R[n,5,BYTE]
where n is the number of the quota
descriptors + 1

lock_id

UNSIGNED-LONG

lock_status_block

BLOCK[n,BYTE]
where n is the size of the lock—statusblock -at least 8

lock_value_block

BL0CKp6,BYTE]

logical-name

VECTOR[255/BYTE#UNSIGNED]

longword_signed

SIGNED LONG

longword_unsigned

UNSIGNED LONG

mask_byte

BITVECT0R[8]

mask—longword

BITVECTOR[32]

mask—quadword

BITVECT0R[64]

mask—word

BITVECT0R[16]

null—arg

UNSIGNED LONG

octaword—signed

VECT0R[4,L0NG,UNSIGNED]

octaword—unsigned

VECTOR[4,LONG,UNSIGNED]

page_protection

UNSIGNED LONG

procedure

UNSIGNED LONG

process—id

UNSIGNED LONG

process—name

VECTOR[n,BYTE,UNSIGNED]
where n is the length of the process name

quadword—signed

VECTOR[2,LONG,UNSIGNED]

quadword—unsigned

VECT0R[2,LONG,UNSIGNED]

rights—holder

BLOCK[8,BYTE]

rights—id

UNSIGNED LONG

rab

$RAB_DECL
from STARLET.REQ

section—id

VECTOR[2,LONG,UNSIGNED]

section—name

VECTOR[n,BYTE,UNSIGNED]
where n is the length of the global section
name

system _access—id

VECTOR[2,LONG,UNSIGNED]

time_name

VECTOR[n,BYTE,UNSIGNED]
where n is the length of the time value in
VMS format

VMS Data Types

Table A-5 (Cont.)

VAX BLISS Implementation

VMS Data Type

A.6

VAX BLISS Declaration

uic

UNSIGNED LONG

user_arg

UNSIGNED LONG

varying_arg

UNSIGNED LONG

vector_byte_signed

VECTOR[n,BYTE,SIGNED]
where n is the size of the array

vector_byte_unsigned

VECTOR[n,BYTE,UNSIGNED]
where n is the size of the array

vector_longword_signed

VECTOR[n,LONG,SIGNED]
where n is the size of the array

vector_longword_unsigned

VECTOR[n,LONG,UNSIGNED]
where n is the size of the array

vector_quadword_signed

BLOCKVECTOR[n,2,LONG]
where n is the size of the array

vector_quadword_unsigned

BLOCKVECTOR[n,2,LONG]
where n is the size of the array

vector_word_signed

VECTOR[n,BYTE,SIGNED]
where n is the size of the array

vector_word_unsigned

VECTOR[n,BYTE,UNSIGNED]
where n is the size of the array

word_signed

SIGNED WORD

word—unsigned

UNSIGNED WORD

VAX C Implementation
The following table lists VMS data types and their corresponding VAX C data
type declarations.

Table A-6

VAX C Implementation

VMS Data Type

VAX C Declaration

access_bit—names

User-defined1

access_mode

unsigned char

address

int *pointer2’4

address—range

int *array [2]2’3’4

arg_ list

User-defined1

ast_procedure

Pointer to function.2

boolean

unsigned long int

^he declaration of a user-defined data structure depends on how the data will be used. Such data
structures can be declared in a variety of ways, each of which is more suitable to specific applications.
2The term pointer refers to several declarations involving pointers. Pointers are declared with special syntax
and associated with the data type of the object being pointed to. This object is often user-defined.
3The term array denotes the syntax of a VAX C array declaration.
4The data type specified can be changed to any valid VAX C data type.

A—29

VMS Data Types

Table A-6 (Cont.)

VAX C Implementation

VMS Data Type

VAX C Declaration

byte_signed

char

byte_unsigned

unsigned char

channel

unsigned short int

char_string

char array[n]3>5

complex-number

User-defined1

cond_value

unsigned long int

context

unsigned long int

date_time

User-defined1

device_name

char array[n]3’5

ef_cluster_ name

char array[n]3’5

ef_number

unsigned long int

exit_handler_block

User-defined1

fab

#include fab from text library
struct FAB

file-protection

unsigned short int, or User-defined1

floating-point

float or double

function—code

Unsigned long int or User-defined1

identifier

int ‘pointer2’4

io_status—block

User-defined1

item_list—2

User-defined1

item_list—3

User-defined1

item_list—pair

User-defined1

item_quota—list

User-defined1

lock—id

unsigned long int

lock—status—block

User-defined1

lock—value—block

User-defined1

logical—name

char array[n]3’5

longword—signed

long int

longword—unsigned

unsigned long int

mask—byte

unsigned char

mask—longword

unsigned long int

’The declaration of a user-defined data structure depends on how the data will be used. Such data
structures can be declared in a variety of ways, each of which is more suitable to specific applications.
2The term pointer refers to several declarations involving pointers. Pointers are declared with special syntax
and associated with the data type of the object being pointed to. This object is often user-defined.
3The term array denotes the syntax of a VAX C array declaration.
4The data type specified can be changed to any valid VAX C data type.
5The size of the array must be substituted for n.

A—30

VMS Data Types

Table A—6 (Cont.)

VAX C Implementation

VMS Data Type

VAX C Declaration

mask_quadword

User-defined1

mask_word

unsigned short int

null_arg

unsigned long int

octaword_signed

User-defined1

octaword_unsigned

User-defined1

page_protection

unsigned long int

procedure

Pointer to function2

processed

unsigned long int

process_name

char array[n]3’5

quadword_signed

User-defined1

quadword_unsigned

User-defined1

rights_holder

User-defined1

rights_id

unsigned long int

rab

#include rab from text library
struct RAB

section_id

User-defined1

section_name

char array[n]3’5

system _access_id

User-defined1

time_name

char array[n]3’5

uic

unsigned long int

user_arg

User-defined1

varying_arg

User-defined1

vector_byte_signed

char array[n]3’5

vector_byte_unsigned

unsigned char array[n]3’5

vector_longword_signed

long int array[n]3’5

vector_longword_unsigned

unsigned long int array[n]3’5

vector_quadword_signed

User-defined1

vector_quadword_unsigned

User-defined1

vector_word_signed

short int array[n]3’5

vector_word_unsigned

unsigned short int array[n]3>5

word_signed

short int

word-unsigned

unsigned short int

A—31

VMS Data Types

A.7

VAX COBOL Implementation
The following table lists VMS data types and their corresponding VAX
COBOL data type declarations.

Table A-7

VAX COBOL Implementation

VMS Data Type

VAX COBOL Declaration

access_bit_names

NA . . . PIC X(128).2

access_mode

NA . . . PIC X.2
access_mode is usually passed BY VALUE
as PIC 9(5) COMP.

address

USAGE POINTER.

address_range

01 ADDRESS-RANGE.
02 BEGINNING-ADDRESS USAGE POINTER.
02 ENDING-ADDRESS USAGE POINTER.

arg_list

NA . . . Constructed by the compiler as a result of
using the COBOL CALL statement. An argument
list may be created as follows, but may not be
referenced by the COBOL CALL statement.
01 ARG-LIST.
02 ARG-COUNT PIC S9(5) COMP.
02 ARG-BY-VALUE PIC S9(5) COMP.
02 ARG-BY-REFERENCE USAGE POINTER
02 VALUE REFERENCE ARG-NAME.
. . . continue as needed

ast_procedure

01 AST-PROC PIC 9(5) COMP.1

boolean

01 BOOLEAN-VALUE PIC 9(5) COMP.1

byte_signed

NA . . . PIC X.2

byte_unsigned

NA . . . PIC X.2

channel

01 CHANNEL PIC 9(4) COMP.1

char_string

01 CHAR-STRING PIC X to PIC X(65535).

complex_number

NA . . . PIC X(n) where n is length.2

cond_value

01 COND-VALUE PIC 9(5) COMP.1

context

01 CONTEXT PIC 9(5) COMP.1

date_time

NA . . . PIC X(16).2

device_name

01 DEVICE-NAME PIC X(n) where n is length.

ef_cluster_name

01 CLUSTER-NAME PIC X(n) where n is length.

ef_number

01 EF-NO PIC 9(5) COMP.1

exit_handler_block

NA . . . PIC X(n) where n is length.2

Although unsigned computational data structures are not directly supported
in VAX COBOL, you may substitute the signed equivalent provided you do not
exceed the range of the signed data structure.
2Most VMS data types not directly supported in VAX COBOL can be represented
as an alphanumeric data item of a certain number of bytes. While VAX COBOL
does not interpret the data type, it may be used to pass objects from one
language to another.

A—32

VMS Data Types

Table A-7 (Cont.)

VAX COBOL Implementation

VMS Data Type

VAX COBOL Declaration

fab

NA . . . Too complex for general COBOL use.
Most of a FAB structure can be described by
a lengthy COBOL record description, but such
a FAB cannot then be referenced by a COBOL
1-0 statement. It is much simpler to do the 1-0
completely within COBOL, and let the COBOL
compiler generate the FAB structure, or do the 1-0
in another language.

file_protection

01 FILE-PROT PIC 9(4) COMP.1

floating-point

01 F-FLOAT USAGE COMP-1.
01 D-FLOAT USAGE COMP-2.
* g-float and h-float are not supported in
VAX COBOL.

function_code

01 FUNCTION-CODE.
02 MAJOR-FUNCTION PIC 9(4) COMP.1
02 SUB-FUNCTION PIC 9(4) COMP.1

identifier

01 ID PIC 9(5) COMP.1

io_status_block

01 I0SB.
02 COND-VAL PIC 9(4) COMP.1
02 BYTE-CNT PIC 9(4) COMP.1
02 DEV-INFO PIC 9(5) COMP.1

item_list_2

01 ITEM-LIST-TWO.
02 ITEM-LIST OCCURS n TIMES.
04 COMP-LENGTH PIC S9(4) COMP.
04 ITEM-CODE PIC S9(4) COMP.
04 COMP-ADDRESS PIC S9(5) COMP.
02 TERMINATOR PIC S9(5) COMP VALUE 0.

item_list_3

01 ITEM-LIST-3.
02 ITEM-LIST OCCURS n TIMES.
04 BUF-LEN PIC S9(4) COMP.
04 ITEM-CODE PIC S9(4) COMP.
04 BUFFER-ADDRESS PIC S9(5) COMP.
04 LENGTH-ADDRESS PIC S9(5) COMP.
02 TERMINATOR PIC S9(5) COMP VALUE 0.

item_list_pair

01 ITEM-LIST-PAIR.
02 ITEM-LIST OCCURS n TIMES.
04 ITEM-CODE PIC S9(5) COMP.
04 ITEM-VALUE PIC S9(5) COMP.
02 TERMINATOR PIC S9(5) COMP VALUE 0.

item_quota_list

lock_id

01 LOCK-ID PIC 9(5) COMP.1

lock_status_block

lock_value_block

logical_name

01 LOG-NAME PIC X TO X(255).

longword_signed

01 LWS PIC S9( 5) COMP.

VMS Data Types

Table A-7 (Cont.)

VAX COBOL Implementation

VMS Data Type

VAX COBOL Declaration

longword_unsigned

01 LWU PIC 9(5) COMP.1

mask_byte

NA . . . PIC X.2

mask_longword

01 MLW PIC 9(5) COMP.1

mask_quadword

01 MOW PIC 9(18) COMP.1

mask_word

01 MW PIC 9(4) COMP.1

null_arg

CALL . . . USING OMITTED or
PIC S9( 5) COMP VALUE 0
passed USING BY VALUE.

octaword_signed

octaword_unsigned

page-protection

01 PAGE-PROT PIC 9(5) COMP.1

procedure

01 ENTRY-MASK PIC 9(5) COMP.1

process-id

01 PID PIC 9(5) COMP.1

process_name

01 PROCESS-NAME PIC X TO X(15).

quadword_signed

01 QWS PIC S9(18) COMP.

quadword_unsigned

01 QWU PIC 9(18) COMP.1

rights_holder

01 RIGHTS-HOLDER.
02 RIGHTS-ID PIC 9(5) COMP.1
02 ACCESS-RIGHTS PIC 9(5) COMP.1

rights_id

01 RIGHTS-ID PIC 9(5) COMP.1

rab

NA ... Too complex for general COBOL use.
Most of a RAB structure can be described by
a lengthy COBOL record description, but such
a RAB cannot then be referenced by a COBOL
1-0 statement. It is much simpler to do the 1-0
completely within COBOL, and let the COBOL
compiler generate the RAB structure, or do the 1-0
in another language.

section_id

01 SECTION-ID PIC 9(18) COMP.1

section_name

01 SECTION-NAME PIC X to X(43).

system _access_id

01 SECTION-ACCESS-ID PIC 9(18) COMP.1

time_name

01 TIME-NAME PIC X(n) where n is the length.

uic

01 UIC PIC 9(5) COMP.1

user_arg

01 USER-ARG PIC 9(5) COMP.1

varying_arg

Dependent upon application.

vector_byte_signed

NA . . . 3

’Although unsigned computational data structures are not directly supported
in VAX COBOL, you may substitute the signed equivalent provided you do not
exceed the range of the signed data structure.
2Most VMS data types not directly supported in VAX COBOL can be represented
as an alphanumeric data item of a certain number of bytes. While VAX COBOL
does not interpret the data type, it may be used to pass objects from one
language to another.
3VAX COBOL does not permit the passing of variable length data structures.
A—34

VMS Data Types

Table A—7 (Cont.)

VAX COBOL Implementation

VMS Data Type

VAX COBOL Declaration

vector_byte_unsigned

NA . . . 3

vector_longword_signed

NA . . . 3

vector_longword_unsigned

NA . . . 3

vector_quadword_signed

NA . . . 3

vector_quadword_unsigned

NA . . . 3

vector_word_signed

NA . . . 3

vector_word_unsigned

NA . . . 3

word-signed

01 WS PIC S9(4) COMP.

word-unsigned

01 WS PIC 9(4) COMP.1

A.8

VAX FORTRAN Implementation
The following table lists VMS data types and their corresponding VAX
FORTRAN data type declarations.
Table A-8

VAX FORTRAN Implementation

VMS Data Type

VAX FORTRAN Declaration

access_bit_names

INTEGER*4(2,32)
or
STRUCTURE /access_bit_names/
INTEGER*4 access_name_len
INTEGER*4 access_name_buf
END STRUCTURE !access_bit_names
RECORD /access_bit_names/ my_names(32)

access_mode

BYTE

address

INTEGER*4

address_range

INTEGER*4(2)
or
STRUCTURE /address_range/
INTEGER*4 low_address
INTEGER*4 high_address
END STRUCTURE

arg_list

INTEGER*4(n)

ast_procedure

EXTERNAL

boolean

LOGICAL*4

byte_signed

BYTE

A—35

VMS Data Types

Table A-8 (Cont.)

VAX FORTRAN Implementation

VMS Data Type

VAX FORTRAN Declaration

byte_unsigned

BYTE1

channel

INTEGER*2

char_string

CHARACTERS

complex_number

C0MPLEX*8
COMPLEX* 16

cond_value

INTEGER*4

context

INTEGER*4

date_time

INTEGER*4(2)

device_name

CHARACTER*n

ef_cluster_name

CHARACTER*n

ef_number

INTEGER*4

exit_handler_block

STRUCTURE /exhblock/
INTEGER*4 flink
INTEGER*4 exit_handler_addr
BYTE(3) /0/
BYTE arg_count
INTEGER*4 cond_value
!
! .(optional arguments . . .
! . one argument per longword)
!
END STRUCTURE Icntrlblk
RECORD /exhblock/ myexh_block

fab

INCLUDE '($FABDEF)'
RECORD /fabdef/ myfab

file_protection

INTEGER*4

floating-point

REAL*4
REAL*8
DOUBLE PRECISION
REAL* 16

function_code

INTEGER*4

identifier

INTEGER*4

io_status_block

STRUCTURE /iosb/
INTEGER*2 iostat, Ireturn status
2 term_offset, !Loc. of line terminator
2 terminator, lvalue of terminator
2 term_size Isize of terminator
END STRUCTURE
RECORD /iosb/ my_iosb

'Unsigned data types are not directly supported by VAX FORTRAN. However,
in most cases you can substitute the signed equivalent so long as you do not
exceed the range of the signed data structure.

A—36

VMS Data Types

Table A-8 (Cont.)

VAX FORTRAN Implementation

VMS Data Type

VAX FORTRAN Declaration

item_list_2

STRUCTURE /itmlst/
UNION
MAP
INTEGER*2 buflen,code
INTEGER*4 bufadr
END MAP
MAP
INTEGER*4 end_list /0/
END MAP
END UNION
END STRUCTURE litmlst
RECORD /itmlst/ my_itmlst_2( n)
(Allocate n records where n is the number item
codes plus an extra element for the end-of-list
item)

item_list_3

STRUCTURE /itmlst/
UNION
MAP
INTEGER*2 buflen,code
INTEGER*4 bufadr,retlenadr
END MAP
MAP
INTEGER*4 end_list /0/
END MAP
END UNION
END STRUCTURE litmlst
RECORD /itmlst/ my_itmlst_2( n)
(Allocate n records where n is the number item
codes plus an extra element for the end-of-list
item)

item_list_pair

STRUCTURE /itmlist_pair/
UNION
MAP
INTEGER*4 code
INTEGER*4 value
END MAP
MAP
INTEGER*4 end_list /0/
END MAP
END UNION
END STRUCTURE !itmlst_pair
RECORD /itmlst_pair/ my_itmlst_pair(n)
(Allocate n records where n is the number item
codes plus an extra element for the end-of-list
item)

A—37

VMS Data Types

Table A—8 (Cont.)

VAX FORTRAN Implementation

VMS Data Type

VAX FORTRAN Declaration

item_quota_list

STRUCTURE /item_quota_list/
MAP
BYTE quota_name
INTEGER*4 quota_value
END MAP
MAP
BYTE end_quota_list
END MAP
END STRUCTURE !item_quota_list

lock_id

INTEGER*4

lock_status_block

STRUCTURE/lksb/
INTEGER*2 cond_value
INTEGER*2 unused
INTEGER*4 lock_id
BYTE(16)
END STRUCTURE !lock_status_lock

lock_value_block

BYTE(16)

logical_name

CHARACTERS

longword_signed

INTEGER*4

longword_unsigned

INTEGER‘41

mask_byte

INTEGER* 1

mask_longword

INTEGER*4

mask_quadword

INTEGER*4(2)

mask_word

INTEGER*2

null_arg

%VAL(0)

octaword_signed

INTEGER*4(4)

octaword_unsigned

INTEGER*4(4)1

page-protection

INTEGER*4

procedure

INTEGER*4

process_id

INTEGER*4

process_name

CHARACTER*n

quadword_signed

INTEGER*4(2)

quadword_unsigned

INTEGER*4(2)1

rights_holder

INTEGER*4(2)
or
STRUCTURE /rights_holder/
INTEGER*4 rights_id
INTEGER*4 rights_mask
END STRUCTURE !rights_holder

rights_id

INTEGER*4

rab

INCLUDE '($RABDEF)'
RECORD /rabdef/ myrab

Unsigned data types are not directly supported by VAX FORTRAN. However,
in most cases you can substitute the signed equivalent so long as you do not
exceed the range of the signed data structure.
A—38

VMS Data Types

Table A-8 (Cont.)

VAX FORTRAN Implementation

VMS Data Type

VAX FORTRAN Declaration

section—id

INTEGER*4(2)

section—name

CHARACTERS

system —access—id

INTEGER*4(2)

time_name

CHARACTER*23

uic

INTEGER*4

user_arg

Any longword quantity

varying—arg

INTEGER*4

vector—byte_signed

BYTE(n)

vector—byte_unsigned

BYTE(n)1

vector—longword—signed

INTEGER*4(n)

vector—longword—unsigned

INTEGER*4(n)1

vector—quadword—signed

INTEGER*4(2, n)

Vector—quadword—unsigned

INTEGER*4(2,n)1

vector—word—signed

INTEGER*2(n)

vector—word—unsigned

INTEGER*2(n)1

word—signed

INTEGER*2(n)

word—unsigned

INTEGER*2(n)1

Unsigned data types are not directly supported by VAX FORTRAN. However,
in most cases you can substitute the signed equivalent so long as you do not
exceed the range of the signed data structure.

A.9

VAX MACRO Implementation
The following table lists VMS data types and their corresponding VAX
MACRO data type declarations.
Table A-9

VAX MACRO Implementation

VMS Data Type

VAX MACRO Declaration

access_bit—names

.ASCID /name_for_bitO/
.ASCID /name_for_bit1/
.ASCID /name—for_bit31 /

access—mode

.BYTE PSL$C_xxxx

address

.ADDRESSS virtual—address

address—range

.ADDRESS start—address^nd—address

arg_list

.LONG n_args, argl, arg2, . . .

ast_procedure

.ADDRESS ast_procedure

boolean

.LONG 1 or .LONG 0

byte_signed

.SIGNED_BYTE byte_value

byte_unsigned

.BYTE byte_value

A—39

VMS Data Types

Table A-9 (Cont.)

A—40

VAX MACRO Implementation

VMS Data Type

VAX MACRO Declaration

channel

.WORD channel-number

char_string

.ASCID /string/

complex_number

cond_value

.LONG cond_value

context

.LONG 0

date_time

.QUAD date_time

device_name

.ASCID /ddcu:/

ef_cluster_name

.ASCID /ef_cluster—name/

ef_number

.LONG ef_number

exit_handler_block

.LONG 0
.ADDRESS exit—handler—routine
.LONG 1
.ADDRESS status
STATUS: .BLKL 1

fab

MYFAB: $FAB

file-protection

.WORD prot_value

floating-point

.FLOAT, .G-FLOAT, or .H-FLOAT

function_code

.LONG codelmask

identifier

.ADDRESSS virtual—address

io_status_block

.QUAD 0

item_list_2

.WORD component—length
.WORD item_code
.ADDRESS component—address

item_list_3

.WORD buffer—length
.WORD item_code
.ADDRESS buffer—address
.ADDRESS return—length—address

item_list_pair

.LONG item_code
.LONG data

item_quota_list

.BYTE PQL$_xxxx
.LONG value—for_quota
.BYTE pql$_listend

lock_id

.LONG lock-id

lock_status_block

.QUAD 0

lock_value_block

.BLKB 16

logical_name

.ASCID /logical—name/

longword_signed

.LONG value

longword—unsigned

.LONG value

mask_byte

.BYTE mask—byte

mask_longword

.LONG mask—longword

mask_quadword

.QUAD mask—quadword

mask_word

.WORD mask—word

VMS Data Types

Table A—9 (Cont.)

VAX MACRO Implementation

VMS Data Type

VAX MACRO Declaration

null_arg

.LONG 0

octaword_signed

octaword_unsigned

.OCTA value

page-protection

.LONG page_protection

procedure

.ADDRESS procedure

process-id

.LONG process_id

process_name

.ASCID /process_name/

quadword—signed

quadword—unsigned

.QUAD value

rights_holder

.LONG identifier, access_right_bitmask

rights_id

.LONG rights_id

rab

MYRAB: $RAB

section_id

.LONG sec$k_matXXX, version_number

section_name

.ASCID /section_name/

system _access_id

.QUAD system_access_id

time_name

.ASCID /dd-mmm-yyyy:hh:mm:ss.cc/

uic

.LONG uic

user_arg

.LONG data

varying_arg

Dependent upon application.

vector_byte_signed

.SIGNED_BYTE val1,val2, . . . vaIN

vector_byte_unsigned

.BYTE vail,val2, . . . vaIN

vector_longword_signed

.LONG vail,val2, . . . vaIN

vector_longword_unsigned

.LONG val1,val2, . . . vaIN

vector_quadword_signed

vector_quadword_unsigned

.QUAD vail
.QUAD val2
.QUAD vaIN

A. 10

vector_word_signed

.SIGNED—WORD val1,val2, . . . vaIN

vector_word_unsigned

.WORD vail,val2, . . . vaIN

word_signed

.SIGNED_WORD value

word-unsigned

.WORD value

VAX PASCAL Implementation
The following table lists VMS data types and their corresponding VAX
PASCAL data type declarations.

A—41

VMS Data Types

Table A-10

VAX PASCAL Implementation

VMS Data Type

VAX PASCAL Declaration

access_bit_names

PACKED ARRAY [1 .32] OF [QUAD] RECORD END;1-6

access_mode

[BYTE] 0..3;6

address

UNSIGNED;

address_range

PACKED ARRAY [1..2] OF UNSIGNED;6

arg_list

PACKED ARRAY [1..n] OF UNSIGNED;6

ast_procedure

UNSIGNED,

boolean

BOOLEAN;3

byte_signed

[BYTE] -128..127;6

byte_unsigned

[BYTE] 0..255;6

channel

[WORD] 0..65535;6

char_string

[CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR;4

complex_number

[LONG(2>] RECORD END; * F_Floating Complex *^6
[QUAD(2(] RECORD END; * D/G_Floating Complex *
[OCTA(2)] RECORD END; * H_Floating Complex *

cond_value

UNSIGNED;

context

UNSIGNED;

date_time

[QUAD] RECORD END;1-6

device_name

[CLASS—S] PACKED ARRAY [L..U:INTEGER] OF CHAR;4

ef_cluster_name

[CLASS-S] PACKED ARRAY [L..U:INTEGER] OF CHAR;4

ef_number

UNSIGNED;

exit_handler_block

PACKED ARRAY [1..n] OF UNSIGNED;6

fab

FABSTYPE;5

file_protection

[WORD] RECORD END;1-6

floating-point

REAL; j F_Floating |
SINGLE; { F_Floating )
DOUBLE; { D_Floating/G_Floating )2
QUADRUPLE; j H_Floating [

function_code

UNSIGNED;

identifier

UNSIGNED;

io_status_block

[QUAD] RECORD END;1-6

1_This type is not available in VAX PASCAL and an empty record has been inserted. To manipulate the
contents, declare with explicit field components. If you pass an empty record as a parameter to a PASCAL
routine, you must use the VAR keyword.
2lf the [G—FLOATING] attribute is used in compiling, double-precision variables and expressions are
represented in G_floating format. The /G_FLOATING command line qualifier can also be used. Both
methods default to no G_floating.
3VAX PASCAL allocates a byte for a BOOLEAN variable. Use the [LONG] attribute when passing to routines
that expect a longword.
4This parameter declaration accepts VARYING OF CHAR or PACKED ARRAY OF CHAR and produces the
CLASS—S descriptor required by system services.
5The program must inherit the STARLET environment file located in SYS$LIBRARY:STARLET.PEN.
6VAX PASCAL expects either a type identifier or conformant schema. Declare this under the TYPE
declaration and use the type identifier in the formal parameter declaration.
A—42

VMS Data Types

Table A-10 (Cont.)

VAX PASCAL Implementation

VMS Data Type

VAX PASCAL Declaration

item_list_2

PACKED ARRAY [1..n] OF PACKED RECORD6
CASE INTEGER OF
1: (
FIELD 1 : [WORD] 0..65535;
FIELD2 : [WORD] 0..65535;
FIELD3 : UNSIGNED);
2: (
TERMINATOR : UNSIGNED);
END;

item_Llist_3

PACKED ARRAY [1..n] OF PACKED RECORD6
CASE INTEGER OF
1: (
FIELD 1 : [WORD] 0..65535;
FIELD2 : [WORD] 0..65535;
FIELD3 : UNSIGNED;
FIELD4 : UNSIGNED);
2: (
TERMINATOR : UNSIGNED);
END;

item_list_pair

PACKED ARRAY [1..n] OF PACKED RECORD6
CASE INTEGER OF
1: (
FIELD 1 : INTEGER;
FIELD2 : INTEGER);
2: (
TERMINATOR : UNSIGNED);
END;

item_quota_list

PACKED ARRAY [1..n] OF PACKED RECORD6
CASE INTEGER OF
1: (
QUOTA-NAME : [BYTE] 0..255;
QUOTA-VALUE: UNSIGNED);
2: (
QUOTA-TERM : [BYTE] 0..255);
END;

lock_id

UNSIGNED;

lock_status_block

[BYTE(24(] RECORD END;1’6

lock_value_block

[BYTE( 16)] RECORD END;1’6

logical-name

[CLASS-S] PACKED ARRAY [L..U:INTEGER] OF CHAR;4

longword_signed

INTEGER;

longword_unsigned

UNSIGNED;

mask_byte

[BYTE,UNSAFE] PACKED ARRAY [1..8] OF BOOLEAN;6

'This type is not available in VAX PASCAL and an empty record has been inserted. To manipulate the
contents, declare with explicit field components. If you pass an empty record as a parameter to a PASCAL
routine, you must use the VAR keyword.
4This parameter declaration accepts VARYING OF CHAR or PACKED ARRAY OF CHAR and produces the
CLASS—S descriptor required by system services.
6VAX PASCAL expects either a type identifier or conformant schema. Declare this under the TYPE
declaration and use the type identifier in the formal parameter declaration.
A—43

VMS Data Types

Table A-10 (Cont.)

VAX PASCAL Implementation

VMS Data Type

VAX PASCAL Declaration

mask_longword

[LONG,UNSAFE] PACKED ARRAY [1..32] OF BOOLEAN;6

mask_quadword

[QUAD,UNSAFE] PACKED ARRAY [1..64] OF BOOLEAN;6

mask_word

[WORD,UNSAFE] PACKED ARRAY [1.16] OF BOOLEAN;6

null_arg

UNSIGNED;

octaword_signed

[OCTA] RECORD END;1-6

octaword—unsigned

[OCTA] RECORD END;1*6

page_protection

[LONG] 0..7;6

procedure

UNSIGNED;

process—id

UNSIGNED;

process_name

[CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR;4

quadword_signed

[QUAD] RECORD END;1-6

quadword—unsigned

[QUAD] RECORD END;1-6

rights_holder

[QUAD] RECORD END;1-6

rights_id

UNSIGNED;

rab

RABSTYPE;5

section-id

[QUAD] RECORD END;1-6

section_name

[CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR;4

system _access_id

[QUAD] RECORD END;1-6

time_name

[CLASS-S] PACKED ARRAY [L..U:INTEGER] OF CHAR;4

uic

UNSIGNED;

user_arg

[UNSAFE] UNSIGNED;

varying_arg

[UNSAFE,REFERENCE] PACKED ARRAY [L..U:INTEGER] OF [BYTE]
0..255;

vector_byte_signed

PACKED ARRAY [1..n] OF [BYTE] -128 .127;6

vector_byte_ unsigned

PACKED ARRAY [1..n] OF [BYTE] 0..255;6

vector_longword_signed

PACKED ARRAY [1..n] OF INTEGER;6

vector_longword_unsigned

PACKED ARRAY [1..n] OF UNSIGNED;6

vector_quadword_signed

PACKED ARRAY [1..n] OF [QUAD] RECORD END;1-6

vector—quadword_unsigned

PACKED ARRAY [1..n] OF [QUAD] RECORD END;1-6

vector—word—signed

PACKED ARRAY [1..n] OF [WORD] -32768.,32767;6

vector—word—unsigned

PACKED ARRAY [1..n] OF [WORD] 0..65535;6

word—signed

[WORD] -32768.,32767;6

word—unsigned

[WORD] 0..65535;6

’This type is not available in VAX PASCAL and an empty record has been inserted. To manipulate the
contents, declare with explicit field components. If you pass an empty record as a parameter to a PASCAL
routine, you must use the VAR keyword.
4This parameter declaration accepts VARYING OF CHAR or PACKED ARRAY OF CHAR and produces the
CLASS—S descriptor required by system services.
5The program must inherit the STARLET environment file located in SYS$LIBRARY:STARLET.PEN.
6VAX PASCAL expects either a type identifier or conformant schema. Declare this under the TYPE
declaration and use the type identifier in the formal parameter declaration.
A—44

VMS Data Types

A. 11

VAX PL/1 Implementation
The following table lists VMS data types and their corresponding VAX PL/I
data type declarations.
Table A-11

VAX PL/I Implementation

VMS Data Type

VAX PL/I Declaration

access_bit_names

1 ACCESS_BIT_NAMES(32),
2 LENGTH FIXED BINARY) 15),
2 DTYPE FIXED BINARY) 7)
INITIAL((32)DSC$K_DTYPE_T),
2 CLASS FIXED BINARY) 7)
INITIAL((32)DSC$K_CLASS_S),
2 CHAR_PTR POINTER;6
The length of the LENGTH field in each element
of the array should correspond to the length of
a string of characters pointed to by the CHAR_
PTR field. The constants DST$K_CLASS_S and
DST$K_DTYPE_T can be used by including the
module SDSCDEF from PLISTARLET or by
declaring it GLOBALREF FIXED BINARY(31)
VALUE.

access_mode

FIXED BINARY) 7)
(The constants for this type— PSL$C_
KERNEL, PSL$C_EXEC, PSL$C_SUPER, PSL$C_
USER—are declared in module SPSLDEF in
PLISTARLET.)1

address

POINTER

address_range

(2) POINTER6

arg_list

1 ARG—LIST BASED,
2 ARGCOUNT FIXED BINARY(31),
2 ARGUMENT (X REFER (ARGCOUNT))
POINTER;6
If the arguments are passed by value, it may
be appropriate to change the type of the
ARGUMENT field of the structure. Alternatively,
you can use the POSINT, INT, or UNSPEC builtin functions/ pseudovariables to access the
data. X should be an expression with a value
in the range 0-255 at the time the structure is
allocated.

System routines are often written so the parameter passed occupies more
storage than the object requires. For example, some system services have
parameters that return a bit value as a longword. These variables must be
declared BIT(32) ALIGNED (not BIT(n) ALIGNED) so adjacent storage is not
overwritten by return values or used incorrectly as input. (Longword parameters
are always declared BIT(32) ALIGNED.)
6Routines declared in PLISTARLET often use ANY so the user is free to declare
the data structure in the most convenient way for her application. ANY may be
necessary in some cases since PL/I does not allow parameters declarations for
some data types used by VMS. (In particular, PL/I parameters with arrays passed
by reference may not be declared to have nonconstant bounds.)
A—45

VMS Data Types

Table A-11 (Cont.)

VAX PL/I Implementation

VMS Data Type

VAX PL/I Declaration

ast_procedure

PROCEDURE or ENTRY2

boolean

BIT ALIGNED1

byte_signed

FIXED BINARY) 7)

byte_unsigned

FIXED BINARY) 7 )3

channel

FIXED BINARY(15)

char_string

CHARACTER) n)4

complex_number

(2) FLOAT BINARY(n) (See floating-point for
values of n.)

cond_value

See module STSSVALUE in PLISTARLET6

context

FIXED BINARY(31)

date_time

BIT(64) ALIGNED5

device_name

CHARACTER) n)4

ef_cluster_name

CHARACTER) n)4

ef_n umber

FIXED BINARY(31)

’System routines are often written so the parameter passed occupies more
storage than the object requires. For example, some system services have
parameters that return a bit value as a longword. These variables must be
declared BIT(32) ALIGNED (not BIT(n) ALIGNED) so adjacent storage is not
overwritten by return values or used incorrectly as input. (Longword parameters
are always declared BIT(32) ALIGNED.)
2AST procedures and those passed as parameters of type ENTRY VALUE or
ANY VALUE must be external procedures. This applies to all system routines
which take procedure parameters.
3This is actually an unsigned integer. This declaration is interpreted as a signed
number; use the POSINT function to determine the actual value.
4System services require CHARACTER string representation for parameters. Most
other system routines allow either CHARACTER or CHARACTER VARYING. For
parameter declarations, n should be an asterisk.
5VAX PL/I does not support FIXED BINARY numbers with precisions greater than
32. To use larger values, declare variables to be BIT variables of the appropriate
size and use the POSINT and SUBSTR bits as necessary to access the values, or
declare the item as a structure. The RTL routines LIB$ADDX and LIB$SUBX may
be useful if you need to perform arithmetic on these types.
6Routines declared in PLISTARLET often use ANY so the user is free to declare
the data structure in the most convenient way for her application. ANY may be
necessary in some cases since PL/I does not allow parameters declarations for
some data types used by VMS. (In particular, PL/I parameters with arrays passed
by reference may not be declared to have nonconstant bounds.)

VMS Data Types

Table A-11 (Cont.)

VAX PL/I Implementation

VMS Data Type

VAX PL/I Declaration

exit_handler_block

1 EXIT_HANDLER_BLOCK BASED,
2 FORWARD-LINK POINTER,
2 HANDLER POINTER,
2 ARGCOUNT FIXED BINARY(31),
2 ARGUMENT (n REFER
(ARGCOUNT) POINTER;6

Replace n with an expression that will yield
a value between 0 and 255 at the time the
structure is allocated.
fab

See module SFABDEF in PLISTARLET6

file_protection

BIT(16) ALIGNED1

floating-point

FLOAT BINARY) n)
The values for n are as follows:
1 <= n <= 24 - F floating
25 <= n <= 53 - D floating
25 <= n <= 53 - G floating (with /G_FLOAT)
54 <= n <= 113 - H floating

function_code

BIT(32) ALIGNED

identifier

POINTER

A—47

VMS Data Types

Table A-11 (Cont.)

VAX PL/I Implementation

VMS Data Type

VAX PL/I Declaration

io_status_block

Since there are different formats for I/O status
blocks for various system services, different
definitions will be appropriate for different uses.
Some of the common formats are shown here.6

/* See p. SYS-229 */
1 IOSB_SYS$GETSYI,
2 STATUS FIXED BINARY(31),
2 RESERVED FIXED BINARY(31);
/* See fig. 8-16 in Part 1 of the I/O User's
Guide */
1 IOSB_TTDRIVER_A,
2 STATUS FIXED BINARY(15),
2 BYTE_COUNT FIXED BINARY) 15),
2 MBZ FIXED BINARY(31) INITIAL(O);
/* See fig. 8-16 in Part 1 of the I/O User's
Guide */
1 IOSB—TTDRIVER—B,
2 STATUS FIXED BINARY(15),
2 TRANSMIT-SPEED FIXED
BINARY! 7),
2 RECEIVE—SPEED FIXED BINARY) 7),
2 CR-FILL FIXED BINARY) 7),
2 LF-FILL FIXED BINARY) 7),
2 PARITY-FLAGS FIXED BINARY) 7),
2 MBZ FIXED BINARY)7) INITIAL(O);
item_list_2

1 ITEM—LIST—2,
2 ITEM(SIZE),
3 COMPONENT-LENGTH FIXED
BINARY(15),
3 ITEM-CODE FIXED BINARY(15),
3 COMPONENT-ADDRESS
POINTER,
2 TERMINATOR FIXED BINARY(31)
INITIAL) 0);6
Replace SIZE with the number of items you
want.

®Routines declared in PLISTARLET often use ANY so the user is free to declare
the data structure in the most convenient way for her application. ANY may be
necessary in some cases since PL/I does not allow parameters declarations for
some data types used by VMS. (In particular, PL/I parameters with arrays passed
by reference may not be declared to have nonconstant bounds.)

A—48

VMS Data Types

Table A-11 (Cont.)

VAX PL/I Implementation

VMS Data Type

VAX PL/I Declaration

item_list_3

1 ITEM_LIST_3,
2 ITEM(SIZE),
3 BUFFER_LENGTH FIXED
BINARY(15),
3 ITEM_CODE FIXED BINARY(15),
3 BUFFER_ADDRESS POINTER,
3 RETURN_LENGTH POINTER,
2 TERMINATOR FIXED BINARY(31)
INITIAL(O);6
Replace SIZE with the number of items you
want.

item_list_pair

1 ITEM_LIST_PAIR,
2 ITEM(SIZE),
3 ITEM_CODE FIXED BINARY(31),
3 ITEM UNION,
4 INTEGER FIXED BINARY(31),
0 REAL FLOAT BINARY(24),
2 TERMINATOR FIXED BINARY(31)
INITIAL! 0);6
Replace SIZE with the number of items you
want.

item_quota_list

1 ITEM_QUOTA_LIST,
2 QUOTA(SIZE),
3 NAME FIXED BINARY! 7),
3 VALUE FIXED BINARY(31),
2 TERMINATOR FIXED BINARY) 7)
INITIAL(PQL$_LISTEND);6
Replace SIZE with the number of quota entries
that you want to use. The constant PQL$_
LISTEND can be used by including the module
SPQLDEF from PLISTARLET or by declaring it
GLOBALREF FIXED BINARY(31) VALUE.

lock_id

FIXED BINARY(31)

lock_status_block

1 LOCK_ST ATUS—BLOCK,
2 STATUS_CODE FIXED BINARY! 15),
2 RESERVED FIXED BINARY) 15),
2 LOCK_ID FIXED BINARY(31);6

lock_value_block

The declaration of an item of this structure will
depend on the use of the structure, since VMS
does not interpret the value.6

6Routines declared in PLISTARLET often use ANY so the user is free to declare
the data structure in the most convenient way for her application. ANY may be
necessary in some cases since PL/I does not allow parameters declarations for
some data types used by VMS. (In particular, PL/I parameters with arrays passed
by reference may not be declared to have nonconstant bounds.)

A—49

VMS Data Types

Table A-11 (Cont.)
VMS Data Type

VAX PL/I Implementation
VAX PL/I Declaration

logical_name

CHARACTERS )3 4

longword—signed

FIXED BINARY(31)

longword—unsigned

FIXED BINARY(31)3

mask_byte

BIT(8) ALIGNED

mask_longword

BIT(32) ALIGNED

mask_quadword

BIT(64) ALIGNED

mask_word

BIT(16) ALIGNED

null_arg

Omit the corresponding parameter in the call.
For example, FOO(A,,B) would omit the second
parameter.

octaword—signed

BIT(128) ALIGNED5

octaword_unsigned

BIT(128) ALIGNED3 5

page_protection

FIXED BINARY(31) (The constants for this
type are declared in module SPRTDEF in
PLISTARLET.)

procedure

PROCEDURE or ENTRY2

process_id

FIXED BINARY(31)

process_name

CHARACTERS )4

quadword—signed

BIT(64) ALIGNED5

quadword—unsigned

BIT(64) ALIGNED3’5

rights—holder

1 RIGHTS—HOLDER,
2 RIGHTS—ID FIXED BINARY(31),
2 ACCESS-RIGHTS BIT(32)
ALIGNED;6

rights_id

FIXED BJNARY(31)

rab

See module SRABDEF in PLISTARLET6

section_id

BIT(64) ALIGNED

2AST procedures and those passed as parameters of type ENTRY VALUE or
ANY VALUE must be external procedures. This applies to all system routines
which take procedure parameters.
3This is actually an unsigned integer. This declaration is interpreted as a signed
number; use the POSINT function to determine the actual value.
4System services require CHARACTER string representation for parameters. Most
other system routines allow either CHARACTER or CHARACTER VARYING. For
parameter declarations, n should be an asterisk.
5VAX PL/I does not support FIXED BINARY numbers with precisions greater than
32. To use larger values, declare variables to be BIT variables of the appropriate
size and use the POSINT and SUBSTR bits as necessary to access the values, or
declare the item as a structure. The RTL routines LIB$ADDX and LIB$SUBX may
be useful if you need to perform arithmetic on these types.
6Routines declared in PLISTARLET often use ANY so the user \s free \o decteve
the data structure in the most convenient way for her application. ANY may be
necessary in some cases since PL/I does not allow parameters declarations for
some data types used by VMS. (In particular, PL/I parameters with arrays passed
by reference may not be declared to have nonconstant bounds.)
A—50

VMS Data Types

Table A-11 (Cont.)

VAX PL/I Implementation

VMS Data Type

VAX PL/I Declaration

section_name

CHARACTER(n)4

system _access_id

BIT(64) ALIGNED

time_name

CHARACTER) n)4

uic

FIXED BINARY(31)

user_arg

ANY

varying_arg

ANY with OPTIONS(VARIABLE) on the routine
declaration.

vector_byte_signed

(n) FIXED BINARY(7)7

vector_byte_unsigned

(n) FIXED BINARY)7)3>7

vector_longword_signed

(n) FIXED BINARY(31)7

vector_longword_unsigned

(n) FIXED BINARY(31)3’7

vector_quadword_signed

(n) BIT(64) ALIGNED5-7

vector_quadword_unsigned

(n) BIT(64) ALIGNED3-5-7

vector_word_signed

(n) FIXED BINARY) 15)7

vector_word_unsigned

(n) FIXED BINARY(15)3-7

word-signed

FIXED BINARY) 15)

word-unsigned

FIXED BINARY) 15)3

3This is actually an unsigned integer. This declaration is interpreted as a signed
number; use the POSINT function to determine the actual value.
4System services require CHARACTER string representation for parameters. Most
other system routines allow either CHARACTER or CHARACTER VARYING. For
parameter declarations, n should be an asterisk.
5VAX PL/I does not support FIXED BINARY numbers with precisions greater than
32. To use larger values, declare variables to be BIT variables of the appropriate
size and use the POSINT and SUBSTR bits as necessary to access the values, or
declare the item as a structure. The RTL routines LIB$ADDX and LIB$SUBX may
be useful if you need to perform arithmetic on these types.
7 For parameter declarations, the bounds must be constant for arrays passed by
reference. For arrays passed by descriptor, *s should be used for the array extent
instead. (VMS system routines almost always take arrays by reference.)

Note: All system services and many system constants and data structures are
declared in PLISTARLET.TLB. For examples of using system services, see
either the VAX-11 PL/I User's Guide or Programming in VAX-11 PL/I.
Important note: While the current version of VAX PL/I Version 2 does
not support unsigned fixed binary numbers or fixed binary numbers
with a precision greater that 31, it is possible that future versions may
support these features. If VAX PL/I is extended to support these types, it
is possible that declarations in PLISTARLET will change to use the new
data types where appropriate.

A—51

VMS Data Types

A.12

VAX RPG II Implementation
The following table lists VMS data types and their corresponding VAX RPG
data type declarations.
Table A-12

VAX RPG II Implementation

VMS Data Type

VAX RPG II Declaration

access_bit_names

access_mode

Declare as text string of one byte. When
using this data structure, you must
interpret the ASCII contents of the string to
determine the access_mode.

address

address_range

arg_list

ast_procedure

L’

boolean

byte_signed

Declare as text string of one byte. When
using this data structure, you must interpret
the ASCII contents of the string.

byte_unsigned

Same as for byte-signed.1

channel

char_string

TEXT STRING

complex_number

DATA STRUCTURE

cond_value

condvalue GIVNG OPCODE

context

date_time

device_name

TEXT STRING

ef_cluster_name

TEXT STRING

ef_number

exit_handler_block

DATA STRUCTURE

fab

Implicitly generated by the compiler on
your behalf. It is not possible for a user to
access the fab data structure from an RPG II
program.

file_protection

floating-point

F
D

function_code

identifier

io_status_block

item_list_pair

DATA STRUCTURE

technically, RPG II does not support unsigned data structures. However,
unsigned information may be passed using the signed equivalent providing the
contents do not exceed the range of the signed data structure.

A—52

VMS Data Types

Table A-12 (Cont.)

VAX RPG II Implementation

VMS Data Type

VAX RPG II Declaration

item_list_2

DATA STRUCTURE

item_list_3

DATA STRUCTURE

item_quota_list

lock_id

lock_status_block

DATA STRUCTURE

lock_value_block

DATA STRUCTURE

logical_name

TEXT STRING

longword_signed

longword_unsigned

mask_byte

Same as for byte_signed.1

mask_longword

mask_quadword

mask_word

null_arg

octaword_signed

DATA STRUCTURE

octaword_unsigned

DATA STRUCTURE

page_protection

procedure

process-id

process_name

TEXT STRING

quadword_signed

quadword_unsigned

rights_holder

rights_id

rab

Implicitly generated by the compiler on
your behalf. It is not possible for a user to
access the rab data structure from an RPG II
program.

section_id

section_name

TEXT STRING

system _access_id

time_name

TEXT STRING

uic

user_arg

varying_arg

Dependent upon application.

vector_byte_signed

ARRAY OF TEXT STRING

vector_byte_unsigned

ARRAY OF TEXT STRING1

A—53

VMS Data Types

Table A-12 (Cont.)

VAX RPG II Implementation

VMS Data Type

VAX RPG II Declaration

vector_longword_signed

ARRAY OF LONGWORD INTEGER (SIGNED)
L

vector_longword_unsigned

RAY OF LONGWORD INTEGER L1

vector_quadword_signed

vector_quadword_unsigned

vector_word_signed

ARRAY OF WORD INTEGER (SIGNED) W

vector_word_unsigned

ARRAY OF WORD INTEGER W1

word_signed

word_unsigned

A. 13

VAX SCAN Implementation
The following table lists VMS data types and their corresponding VAX SCAN
data type declarations.
Table A-13

VAX SCAN Implementation

VMS Data Type

VAX SCAN Declaration

access_bit_name

FILL( 8*32 t1

access_mode

FILL( 1 )’

address

POINTER

address_range

RECORD
start: POINTER,
end: POINTER,
END RECORD

arg_list

RECORD
count: INTEGER,
argl: POINTER, ! if by reference
arg2: INTEGER, ! if by value
. . . ! depending on needs
END RECORD

ast_procedure

POINTER

boolean

BOOLEAN2

byte_signed

FILL( 1 )’

byte_unsigned

FILL( 1 V

1 FILL is a data type that can always be used. A FILL is an object that is between
0 and 65K bytes in length. VAX SCAN does not interpret the contents of an
object. Thus it can be used to pass or return the object to another language that
does understand the type.
2SCAN boolean is just one byte.

A—54

VMS Data Types

Table A-13 (Cont.)

VAX SCAN Implementation

VMS Data Type

VAX SCAN Declaration

channel

FILL( 2 j1

char_string

FIXED STRING( x ) where x is length

complex_number

FILL( x ) where x is length1

cond_value

INTEGER

context

INTEGER

date_time

FILM 8 J1

device_name

FIXED STRING! x ) where x is length

ef_cluster_name

FIXED STRING! x ) where x is length

ef_number

INTEGER

exit_handler_block

FILL! x ) where x is length1

fab

** A fab is too complicated a structure to include
in this chart—much of it can be described with a
SCAN record; however, it is much simpler and less
prone to error to access fabs from other languages
that have the record predefined.

file-protection

FILL! 2 j1

floating-point

FILL! x ) where x is length1

function_code

INTEGER

identifier

POINTER

io_status_block

FILL! 8 I1

item_list—2

RECORD
iteml: FILL! 8 ),
item2: FILL! 8 ),
terminator: INTEGER,
END RECORD1

item_list—3

RECORD
iteml: FILL! 12 ),
item2: FILL( 12 ),
terminator: INTEGER,
END RECORD1

^ILL is a data type that can always be used. A FILL is an object that is between
0 and 65K bytes in length. VAX SCAN does not interpret the contents of an
object. Thus it can be used to pass or return the object to another language that
does understand the type.

A—55

VMS Data Types

Table A-13 (Cont.)

VAX SCAN Implementation

VMS Data Type

VAX SCAN Declaration

item_list_pair

RECORD
pair—1: RECORD ! 2 integer pair
longl: INTEGER,
long2: INTEGER,
END RECORD,
pair_2: RECORD I integer-real pair
longl: INTEGER,
long2: FILL(4),
END RECORD,
...
! depending on need
terminator: INTEGER,
END RECORD

item_quota_list

RECORD
iteml: RECORD
type: FILL( 1 ),
value: INTEGER,
END RECORD,
item2: RECORD
type: FILL( 1 ),
value: INTEGER,
END RECORD,
terminator: FILL( 1 ),
END RECORD1

lock_id

INTEGER

lock_status_block

RECORD
status: FILL( 2 ),
reserved: FILL( 2 ),
lock_id: INTEGER,
END RECORD1

lock_value_block

FILL( 16 J1

logical_narne

FIXED STRINGf x ) where x is length

longword—signed

INTEGER

longword_unsigned

INTEGER

mask_byte

FILL( 1 j1

mask—longword

INTEGER

mask—quadword

RECORD
first-half: INTEGER,
second-half: INTEGER,
END RECORD

mask—word

FILL( 2 I1

null—arg

use * for argument

octaword—signed

FILL( 16 j1

octaword—unsigned

FILL( 16 l1

VMS Data Types

Table A-13 (Cont.)

VAX SCAN Implementation

VMS Data Type

VAX SCAN Declaration

page-protection

INTEGER

procedure

POINTER

process-id

INTEGER

process_name

FIXED STRING( x ) where x is length

quadword_signed

FILL( 8 I1

quadword_unsigned

FILL( 8 I1

rights_holder

RECORD
rights_id: INTEGER,
bitmask: INTEGER,
END RECORD

rights_id

INTEGER

rab

** A rab is too complicated a structure to include
in this chart - much of it can be described with a
SCAN record, however, it is much simpler and less
prone to error to access rabs from other languages
that have the record predefined.

second_name

FILL( 8 J1

section_name

FIXED STRING! x ) where x is length

system _access_id

FILM 8 I1

time_name

FIXED STRING! x ) where x is length

uic

INTEGER

user_arg

INTEGER

varying_arg

INTEGER

vector_byte_signed

FILL! x ) where x is length1

vector_byte_unsigned

FILL! x ) where x is length1

vector_longword_signed

FILL! 4*x ) where x is length1

vector_longword_unsigned

FILL! 4*x ) where x is length1

vector_quadword_signed

FILL! 8*x ) where x is length1

vector_quadword_unsigned

FILL! 8*x ) where x is length1

vector_word_signed

FILL) 2*x ) where x is length1

vector_word_unsigned

FILL! 2*x ) where x is length1

word_signed

FILL! 2 j1

word-unsigned

FILL! 2 j1

A—57

Index

A
Access entry
See Routine format
Access method
See Routine format
Ada implementation table
See Implementation table
Address
definition of • 2-3
APL Implementation table
See Implementation table
Argument data type
See Data type
Argument list
definition of • 2-3
Arguments heading
See Routine format
Array descriptor
See Descriptor
Atomic data type
See Data type

B
BASIC implementation table
See Implementation table
BLISS implementation table
See Implementation table

c
Calling sequence*2-4
Calling standard
See VAX Procedure Calling Standard
C implementation table
See Implementation table
COBOL implementation table
See Implementation table
COBOL intermediate temporary data type
See Data type

Condition
See Exception condition
Condition handler *2-38
deleting • 2-40
establishing • 2-40
interaction with default handler *2-41
memory
use of *2-44
multiple active signals *2-46
operations involving • 2-39
options *2-39
parameters and invocation • 2-42
properties of *2-42
register values • 2-46
request to unwind • 2-44
returning from • 2-44
stack usage*2-39
Condition Handling Standard
See VAX Condition Handling Standard
Condition value
See also Routine format
definition of • 2-3
description of *2-7
field
cntrl • 2-9
condition identification • 2-8
facility *2-8
message number *2-8
severity code*2-8
registers
use of *2-11
returned
I/O status block* 1-13
mailbox* 1-14
RO* 1-13
severity code
interpretation of *2-10
signaled* 1-14
symbols for *2-9
use of • 2-11

D
Data type *2-12
atomic* 2-13
DSC$K_DTYPE_B *2-13

Index—1

Index

Data type
atomic (cont'd.)

Decimal string descriptor (cont'd.)

DSC$K_DTYPE_BU *2-13
DSC$K_DTYPE_CIT • 2-14
DSC$K_DTYPE_D *2-14
DSC$K_DTYPE_DC *2-14
DSC$K_DTYPE_F • 2-13
DSC$K_DTYPE_FC • 2-14
DSC$K_DTYPE_G *2-14
DSC$K_DTYPE_GC *2-14
DSC$K_DTYPE_H•2-14
DSC$K_DTYPE_HC•2-14
DSC$K_DTYPE_L *2-13
DSC$K_DTYPE_LU *2-13
DSC$K_DTYPE_0 • 2-13
DSC$K_DTYPE_OU *2-13
DSC$K_DTYPE_Q • 2-13
DSC$K_DTYPE_QU • 2-13
DSC$K_DTYPE_W *2-13
DSC$K_DTYPE_WU *2-13
DSC$K_DTYPE_Z *2-13
COBOL intermediate temporary *2-17
code
facility-specific *2-17
reserved *2-17
miscellaneous *2-16
DSC$K_DTYPE_ADT • 2-16
DSC$K_DTYPE_BLV • 2-16
DSC$K_DTYPE_BPV *2-16
DSC$K_DTYPE_DSC *2-16
DSC$K_DTYPE_ZEM *2-16
DSC$K_DTYPE_ZI • 2-16
string* 2-14
DSC$K_DTYPE_NL *2-15
DSC$K_DTYPE_NLO *2-15
DSC$K_DTYPE_NR *2-15
DSC$K_DTYPE_NRO *2-15
DSC$K_DTYPE_NU *2-15
DSC$K_DTYPE_NZ *2-15
DSC$K_DTYPE_P *2-15
DSC$K_DTYPE_T *2-15
DSC$K_DTYPE_V *2-15
DSC$K_DTYPE_VT*2-15, 2-18
DSC$K_DTYPE_VU *2-15
varying character string *2-18
DSC$K_DTYPE_VT *2-18
VAX standard* 1-8
VMS
definition of • A-1
description of* A-1 to A-18
VMS Usage* 1-7
Decimal string descriptor

Descriptor
Descriptor
array • 2-21
class codes
facility-specific • 2-37
reserved • 2-37
decimal string *2-25
dynamic string • 2-20
fixed-length • 2-20
format *2-18
DSC$A_POINTER • 2-20
DSC$B_CLASS *2-19
DSC$B_DTYPE *2-19
DSC$K_CLASS_A • 2-21
DSC$K_CLASS_D • 2-20
DSC$K_CLASS_J • 2-25
DSC$K_CLASS_NCA • 2-26
DSC$K_CLASS_P • 2-24
DSC$K_CLASS_S • 2-20
DSC$K_CLASS_SB • 2-35
DSC$K_CLASS_SD • 2-25
DSC$K_CLASS_UBA • 2-33
DSC$K_CLASS_UBS • 2-32
DSC$K_CLASS_UBSB • 2-36
DSC$K_CLASS_V • 2-21
DSC$K_CLASS_VS • 2-29
DSC$K_CLASS_VSA • 2-30
DSC$ W_LENGTH *2-19
prototype *2-19
label • 2-25
noncontiguous array *2-26
procedure • 2-24
string with bounds *2-35
unaligned bit array *2-33
unaligned bit string • 2-32
unaligned bit string with bounds *2-36
variable buffer *2-21
varying string *2-29
varying string array *2-30
Dynamic string descriptor
See Descriptor

Index—2

See Descriptor

E
Exception condition • 2-3
definition of • 2-37
indicating occurrence of *2-40
signaling an • 2-40

Facility-specific data type code

Label descriptor

See Data type
Facility-specific descriptor class codes

See Descriptor
Language extension

See Descriptor
Fixed-length descriptor

See VAX language extension
Language support procedure

See Descriptor
Format heading

See Procedure
Library procedure

See Routine format
FORTRAN implementation table
See Implementation table
Function
definition of • 2-3
Function value *2-7
registers
use of • 2-11

H
High-level language
argument evaluation • 2-5
argument transmission • 2-6
mapped into argument lists *2-5

See Procedure

M
MACRO implementation table
See Implementation table
Mechanism entry
See Routine format
Miscellaneous data type
See Data type
Multiple active signal
See Condition handler

ivi
Noncontiguous array descriptor
See Descriptor

Immediate value
See Passing mechanism
Implementation table
VAX Ada* A-18
VAX APL* A-20
VAX BASIC *A-22
VAX BLISS *A-26
VAX C • A-29
VAX COBOL *A-32
VAX FORTRAN *A-35
VAX MACRO *A-39
VAX PASCAL *A-41
VAX PL/I • A-45
VAX RPG II • A-52
VAX SCAN* A-54
VMS Usage* A-1

o
Operation involving condition handler
See Condition handler

p
PASCAL implementation table
See Implementation table
Passing mechanism
See also Routine format
Descriptor
definition of • 2-3
Reference
definition of • 2-3

Index—3

Index

Passing mechanism (cont'd.)
Value
definition of*2-3
PL/I implementation table
See Implementation table
Procedure
definition of *2-3
language support
definition of • 2-3
use of • 2-3
library
definition of • 2-3
use of • 2-3
Procedure descriptor
See Descriptor
Properties of condition handler
See Condition handler

R
Register
See Condition value
See Function value
Request to unwind
See Condition handler
Reserved data type code
See Data type
Reserved descriptor class code
See Descriptor
Returning from condition handler

RPG II implementation table
See Implementation table

s
SCAN implementation table
See Implementation table
Severity code
See condition value
Signaler's register
See Condition handler
Signalling a condition
See Condition handler
Stack usage *2-11
See also Condition handler
String data type
See Data type
Subroutine
definition of *2-3
System routine template
See Routine format

T
Text entry
See Routine format
Type entry
See Routine format

See Condition handler
Returns heading
See Routine format
Revert to the caller's handling
See Condition handler
Routine format
arguments heading* 1-7
access entry* 1-9
mechanism entry* 1-10
text entry *1-11
type entry* 1-8
VMS Usage entry* 1-7
condition values returned heading* 1-12 to
1-14
description of* 1-1
format heading* 1-2
returns heading* 1-5
condition values* 1-5 to 1-7
data* 1-6

Index—4

u
Unaligned bit string with bounds descriptor
See Descriptor

v
Variable buffer descriptor
See Descriptor
Varying character string data type
See Data type
VAX condition
See Exception condition
VAX Condition Handling Standard • 2-37

Index

VAX data type
See Data type
VAX language extension • 2-6
VAX language implementation table
See Implementation table
VAX Procedure Calling Standard
calling sequence
argument list • 2-4
goals *2-2
introduction *2-1
VAX standard data type
See Data type
VMS data type
See Data type
VMS Usage
See Data type
VMS Usage entry
See Routine format
VMS Usage implementation table
See Implementation table

Index—5

Introduction to
VAX/VMS System
Routines
AA-Z500B-TE

READER'S
I b

Note: This form is for document comments only. DIGITAL will use comments
submitted on this form at the company's discretion. If you require a written reply
ancj are eligible to receive one under Software Performance Report (SPR) service,
submit your comments on an SPR form.

Did you find this manual understandable, usable, and well organized? Please make suggestions for
improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent:
□
□
□
□
□
□

Assembly language programmer
Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
Other (please specify) _

Name _Date_
Organization __
Street_
City -State_Zip Code_
or Country

—

Do Not Tear - Fold Here and Tape
No Postage
Necessary
if Mailed in the
United States

EffllBDSD
BUSINESS REPLY MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

SSG PUBLICATIONS ZK1-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03062-2698

I.II,IIm..II....I.II.I..I.I..I,ImII.1,11
Do Not Tear - Fold Here

Cut Along Dotted Line

— —

Introduction to
VAX/VMS System
Routines
AA-Z500B-TE

READER'S
COMMENTS

Note: This form is for document comments only. DIGITAL will use comments
submitted on this form at the company's discretion. If you require a written reply
and are eligible to receive one under Software Performance Report (SPR) service,
submit your comments on an SPR form.

Did you find this manual understandable, usable, and well organized? Please make suggestions for
improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent:
□
□
□
□
□
□

Assembly language programmer
Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
Other (please specify) _

Name _Date_
Organization _
Street __
City _State_Zip Code_
or Country

mwm

No Postage
Necessary
if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

SSG PUBLICATIONS ZK1-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03062-2698

—

Do Not Tear - Fold Here

Cut Along Dotted Line

- —

Do Not Tear - Fold Here and Tape