Digital PDFs

AA-LA66B-TE

December 1990

151 pages

Original

5.8MB

Document:	. VMS Introduction to VMS System Routines
Order Number:	AA-LA66B-TE
Revision:
Pages:	151
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/5.4/AA-LA66B-TE_Introduction_to_VMS_5.4_System_Routines_199006.pdf

OCR Text

. VMS

Introduction to VMS System Routines

Order Number: AA-LA66B-TE

Introduction to VMS
System Routines
Order Number: AA-LA66B-TE

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

Revision/Update Information:

This manual supersedes the Introduction to
VMS System Routines, Version 5.0.

Software Version:

VMS Version 5.4

digital equipment corporation
maynard, massachusetts

June 1990

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.
Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject
to restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data
and Computer Software clause at DFARS 252.227-7013.
© Digital Equipment Corporation 1990.
All Rights Reserved.
Printed in U.S.A.
The postpaid Reader's Comments forms at the end of this document request your
critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
CDA
DDIF
DEC
DECdtm
DECnet
DECUS
DECwindows
DECwriter

DEQNA
Desktop-VMS
DIGITAL
GIGI
HSC
Live link
LN03
MASS BUS

MicroVAX
PrintServer 40
Q-bus
ReGIS
ULTRIX
UNIBUS
VAX
VAXcluster

VAX RMS
VAXserver
VAXstation
VMS
VT
XUI

mnmnnmnTM

The following is a third-party trademark:
Postscript is a registered trademark of Adobe Systems Incorporated.

ZK4512

Production Note
This book was produced with the VAX DOCUMENT electronic publishing
system, a software tool developed and sold by Digital. In this system,
writers use an ASCII text editor to create source files containing text and
English-like code; this code labels the structural elements .of the document,
such as chapters, paragraphs, and tables. The VAX DOCUMENT software,
which runs on the VMS operating system, interprets the code to format
the text, generate a table of contents and index, and paginate the entire
document. Writers can print the document on the terminal or line printer,
or they can use Digital-supported devices, such as the LN03 laser printer
and PostScript printers (PrintServer 40 or LN03R ScriptPrinter), to
produce a typeset-quality copy containing integrated graphics.

Contents
PREFACE

CHAPTER 1 DOCUMENTATION FORMAT FOR SYSTEM ROUTINES

1-1

1.1

OVERVIEW

1-1

1.2

FORMAT HEADING

1-2

1.3
1.3.1
1.3.2
1.3.3

RETURNS HEADING
Condition Values Returned in RO
Data in Registers RO Through R11
Condition Values Signaled

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

1.4
1.4.1
1.4.2
1.4.3
1.4.4
1.4.5

ARGUMENTS HEADING
VMS Usage Entry
Type Entry
Access Entry
Mechanism Entry
Explanatory Text Entry

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

1.5
1.5.1
1.5.2
1.5.3
1.5.4

CONDITION VALUES RETURNED HEADING
Condition Values Returned
Condition Values Returned in the 1/0 Status Block
Condition Values Returned in a Mailbox
Condition Values Signaled

1-12
1-14
1-14
1-14
1-15

CHAPTER 2 VAX PROCEDURE CALLING AND CONDITION HANDLING
STANDARD
2.1
2.1.1
2.1.2

INTRODUCTION
Goals of the Calling Standard
Definitions Used in the VAX Calling Standard

2-1

2-1
2-2
2-3

Contents

2.2

CALLING SEQUENCE

2-4

2.3
2.3.1
2.3.2
2.3.2.1
2.3.2.2

ARGUMENT LIST
Argument List Format
Argument Lists and Higher-Level Languages
Order of Argument Evaluation • 2-6
Language Extensions for Argument Transmission • 2-6

2-4
2-4
2-6

2.4

FUNCTION VALUE RETURN

2-7

2.5
2.5.1
2.5.2

CONDITION VALUE
Interpretation of Severity Codes
Use of Condition Values

2-8
2-10
2-11

2.6
2.6.1
2.6.2
2.6.3
2.6.3.1
2.6.3.2
2.6.3.3

REGISTER USAGE
Scalar Register Usage
Vector Register Usage
Vector and Scalar Processor Synchronization
Memory Synchronization • 2-13
Exception Synchronization • 2-13
Synchronization Summary • 2-14

2-12
2-12
2-12
2-13

2.7

STACK USAGE

2-14

2.8
2.8.1
2.8.2
2.8.3
2.8.4
2.8.5
2.8.6
2.8.7

ARGUMENT DATA TYPES
Atomic Data Types
String Data Types
Miscellaneous Data Types
Facility-Specific Data Type Codes
Reserved Data Type Codes
COBOL Intermediate Temporary Data Type
Varying Character String Data Type (DSC$K_DTVPE_VT)

2-15
2-15
2-17
2-18
2-19
2-20
2-20
2-21

2.9
2.9.1
2.9.2
2.9.3
2.9.4
2.9.5
2.9.6
2.9.7

ARGUMENT DESCRIPTOR FORMATS
Descriptor Prototype
Fixed-Length Descriptor (DSC$K_CLASS_S)
Dynamic String Descriptor (DSC$K_CLASS_D)
Variable Buffer Descriptor (DSC$K_CLASS_V)
Array Descriptor (DSC$K_CLASS_A)
Procedure Descriptor (DSC$K_CLASS_P)
Procedure Incarnation Descriptor (DSC$K_CLASS_PI)

2-21
2-22
2-23
2-24
2-25
2-25
2-29
2-29

Contents

2.9.8
2.9.9
2.9.10
2.9.11
2.9.12
2.9.13
2.9.14
2.9.15
2.9.16
2.9.17
2.9.18
2.9.19

Label Descriptor (DSC$K_CLASS_J)
Label Incarnation Descriptor (DSC$K_CLASS_JI)
Decimal String Descriptor (DSC$K_CLASS_SD)
Noncontiguous Array Descriptor (DSC$K_CLASS_NCA)
Varying String Descriptor (DSC$K_CLASS_VS)
Varying String Array Descriptor (DSC$K_CLASS_VSA)
Unaligned Bit String Descriptor (DSC$K_CLASS_UBS)
Unaligned Bit Array Descriptor (DSC$K_CLASS_UBA)
String with Bounds Descriptor (DSC$K_CLASS_SB)
Unaligned Bit String with Bounds Descriptor
(DSC$K_CLASS_UBSB)
Facility-Specific Descriptor Class Codes
Reserved Descriptor Class Codes

2-42
2-43
2-44

2.10
2.10.1
2.10.2

VAX CONDITIONS
Condition Handlers
Condition Handler Options

2-44
2-45
2-45

2.11
2.11.1
2.11.2
2.11.3

OPERATIONS INVOLVING CONDITION HANDLERS
Establishing a Condition Handler
Reverting to the Caller's Handling
Signaling a Condition

2-46
2-46
2-47
2-47

2.12
2.12.1
2.12.2
2.12.3
2.12.4
2.12.5
2.12.6

PROPERTIES OF CONDITION HANDLERS
Condition Handler Parameters and Invocation
System Default Condition Handlers
Use of Memory
Returning from a Condition Handler
Request to Unwind
Signaler's Registers

2-49
2-49
2-51
2-51
2-52
2-52
2-53

2.13

MULTIPLE ACTIVE SIGNALS

2-54

APPENDIX A VMS DATA TYPES
A.1

VMS DATA TYPES

2-29
2-29
2-30
2-31
2-34
2-35
2-37
2-38
2-41

A-1

vii

Contents

A.2

VAX ADA IMPLEMENTATION

A-13

A.3

VAX APL IMPLEMENTATION

A-15

A.4

VAX BASIC IMPLEMENTATION

A-18

A.5

VAX BLISS IMPLEMENTATION

A-22

A.6

VAX C IMPLEMENTATION

A-25

A.7

VAX COBOL IMPLEMENTATION

A-28

A.8

VAX FORTRAN IMPLEMENTATION

A-31

A.9

VAX MACRO IMPLEMENTATION

A-36

A.10

VAX PASCAL IMPLEMENTATION

A-38

A.11

VAX PL/I IMPLEMENTATION

A-42

A.12

VAX RPG II IMPLEMENTATION

A-48

A.13

VAX SCAN IMPLEMENTATION

A-51

INDEX

FIGURES

viii

2-1

Argument List Format

2-5

2-2

Format of the Condition Value

2-8

2-3

Stack Frame Generated by CALLG and CALLS Instructions

2-4

Descriptor Prototype Format

2-22

2-5

Fixed-Length Descriptor Format

2-23

2-6

Dynamic String Descriptor Format

2-24

2-7

Array Descriptor Format

2-26

2-8

Procedure Descriptor Format

2-29

2-14

Contents

2-9

Decimal String Descriptor Format

2-30

2-10

Noncontiguous Array Descriptor Format

2-32

2-11

Varying String Descriptor Format

2-34

2-12

Varying String Array Descriptor Format

2-36

2-13

Unaligned Bit String Descriptor Format

2-37

2-14

Unaligned Bit Array Descriptor Format

2-39

2-15

String with Bounds Descriptor Format

2-42

2-16

Unaligned Bit String with Bounds Descriptor Format

2-43

2-17

Interaction Between Handlers and Default Handlers

2-49

2-18

Format of the Mechanism Argument Vector

2-50

2-19

Format of the Signal Argument Vector

2-51

Main Heading in the Documentation Format for System
Routines

1-1

1-2

General Rules of Syntax

1-4

1-3

VAX Standard Data Types

1-8

1-4

Descriptor Passing Mechanism Class Types

1-11

2-1

Atomic Data Types

2-16

2-2

String Data Types

2-17

2-3

Miscellaneous Data Types

2-19

A-1

VMS Data Types

A-2

VAX Ada Implementation

A-13

A-3

VAX APL Implementation

A-16

A-4

VAX BASIC Implementation

A-18

A-5

VAX BLISS Implementation

A-22

A-6

VAX C Implementation

A-25

A-7

VAX COBOL Implementation

A-28

A-8

VAX FORTRAN Implementation

A-31

A-9

VAX MACRO Implementation

A-36

A-10

VAX Pascal Implementation

A-38

A-11

VAX PL/I Implementation

A-42

A-12

VAX RPG II Implementation

A-49

A-13

VAX SCAN Implementation

A-51

TABLES
1-1

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

Document Structure
This manual contains two chapters and an appendix.
•

Chapter 1 describes the format used to document system routines.

•

Chapter 2 describes the VAX Procedure Calling and Condition
Handling Standard. This standard explains programming mechanisms
that are used with the VAX hardware procedure-calling 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:

•

VMS System Services Reference Manual

•

VMS Run-Time Library Routines Volume

•

VMS Record Management Services Manual

•

VMS Utility Routines Manual

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

Conventions
The following conventions are used in this manual:
Convention

Meaning

Ctrl/x

A sequence such as Ctrl/x indicates that you must
hold down the key labeled Ctrl while you press
another key or a pointing device button.
In examples, a key name is shown enclosed in
a box to indicate that you press a key on the
keyboard. (In text, c: key name is not enclosed in a
box.)

Preface

Convention

Meaning

In examples, a horizontal ellipsis indicates one of
the following possibilities:
Additional optional arguments in a statement
have been omitted.
The preceding item or items can be repeated
one or more times.
Additional parameters, values, or other
information can be entered.
A vertical ellipsis indicates the omission of items
from a code example or command format; the
items are omitted because they are not important
to the topic being discussed.

()

In format descriptions, parentheses indicate that,
if you choose more than one option, you must
enclose the choices in parentheses.

[]

In format descriptions, brackets indicate that
whatever is enclosed within the brackets is
optional; you can select none, one, or all of the
choices. (Brackets are not, however, optional in
the syntax of a directory name in a file specification
or in the syntax of a substring specification in an
assignment statement.)

{}

In format descriptions, braces surround a required
choice of options; you must choose one of the
options listed.

boldface text

Boldface text represents the introduction of a new
term or the name of an argument, an attribute, or a
reason.

italic text

Italic text represents information that can vary
in system messages (for example, Internal error
number).

UPPERCASE TEXT

Uppercase letters indicate that you must enter a
command (for example, enter OPEN/READ), or
they indicate the name of a routine, the name of
a file, the name of a file protection code, or the
abbreviation for a system privilege.
Hyphens in coding examples indicate that
additional arguments to the request are provided
on the line that follows.

numbers

xii

Unless otherwise noted, all numbers in the text are
assumed to be decimal. Nondecimal radixesbinary, octal, or hexadecimal-are explicitly
indicated.

Documentation Format for System Routines

Each system routine is documented using a structured format. This
chapter discusses the main categories in this format, the information
presented under each, and the format used to present the information.

1.1

Overview
This chapter explains where to find information on routines and how
to read that information correctly. Subsequent chapters cover the VAX
Procedure Calling and Condition Handling Standard and VMS Data
Types.
Note: The documentation format described in this chapter is generic;
portions of it are used or not used, as appropriate, in the four VMS
manuals that document system routines.

VMS System Services Reference Manual
VMS Run-Time Library Routines Volume
VMS Utility Routines Manual
VMS Record Management Services Manual
Some main categories in the routine format contain information requiring
no explanation beyond that given in Table 1-1. However, additional
information, presented in this manual, is required for the following
categories:
•

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.
(continued on next page)

1-1

Documentation Format for System Routines
1.1 Overview

Table 1-1 (Cont.)

Main Heading in the Documentation Format for
System Routines

Main Heading

Description

Format

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

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, it is indicated by the word
"None."

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 VMS; user privileges needed to call
the routine, if any; system resources used by the routine;
and user quotas that might 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 provides 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 that illustrate
how to use the routine, and is followed by an explanation.
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, examples are provided 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

Documentation Format for System Routines
1.2 Format Heading

•

JSB (Jump to Subroutine) format

•

Explanatory text

All system routines have a procedure call format, but not all system
routines have JSB formats; 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 in Chapter 2; for example, an entry mask is
created, registers are saved, and so on. ·
Procedure call formats can appear in many forms. The following four
examples 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.
ROUTINE_NAME arg1[, [arg2][, arg3]]
Typically, VMS 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 you omit the optional
arguments arg3 and arg4 and specify the trailing argument arg5, you
must use commas to delimit the positions of the omitted arguments.
ROUTINE_NAME argl, [arg2], nullarg, [arg3], [arg4], arg5
Typically, 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 you do not specify the optional arguments,
you need not use commas to delimit unoccupied positions.
However, if you specify a required argument or a separate optional
argument after arg5, you must use commas when arg2, arg3, arg4,
and arg5 are omitted.
ROUTINE_NAME argl[, arg2, arg3, arg4, arg5]

1-3

Documentation Format for System Routines
1.2 Format Heading

Example 4

In the following example, you can specify arg2 and omit arg3. However,
whenever you specify arg3, you must specify arg2.

ROUTINE_NAME argll arg2l arg3]]
JSB Call Format

The JSB call format activates the routine code directly, without the
overhead of constructing the entry mask or saving registers. You can
use the JSB call format only with the VAX. MACRO and VAX. BLISS
languages.
Explanatory Text

Explanatory text might follow the procedure call format or the JSB call
format, or both. This text is present only when needed to clarify the
format. For example, in the call format, you indicate that arguments
are optional by enclosing them in brackets ( [] ). However, brackets alone
cannot convey all the important information that might apply to optional
arguments. For example, in some routines that have many optional
arguments, if you select one optional argument, you must also select
another optional argument. In such cases, text following the format
clarifies this.
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 might 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.
(continued on next page)

1-4

Documentation Format for System Routines
1.2 Format Heading

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 might 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. See your
language user's guide for language-specific syntax.

1.3

Returns Heading
The returns heading contains a description of any information returned by
the routine to the caller. A routine can return information to the caller in
various ways. The following subsections 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. You test
the condition value to determine if the routine completed successfully.
If you program 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 oflittle importance because you receive 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 contains the following information:
VMS Usage:
type:
access:
mechanism:

longword unsigned
longword-(unsigned)
write only
by value

The VMS Usage entry specifies the VMS data type of the information
returned. Because the data type of a condition value in the VMS operating
system environment is an unsigned longword, the VMS Usage entry is
longword_unsigned.

1-5

Documentation Format for System Routines
1.3 Returns Heading

The type entry specifies the data type of the information returned.
Because the data type of a condition value is an unsigned long\vord,
the type heading is longword (unsigned).
The access entry specifies the way in which the called routine accesses
the object. Because 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. Because 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 Rl 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 contains the
following information:
VMS Usage:
type:
access:
mechanism:

f loating_point
G_floating
write only
by value

For example, for the mathematics routine just discussed, the VMS data
type is floating_point and the VAX standard data type is G_floating point.
The meaning of the contents of the access and mechanism headings are
discussed in Sections 1.4.3 and 1.4.4.
In addition, under the returns heading, some text can be provided after

the information about the type, access, and mechanism. This text explains
other relevant information about what the routine is returning.
For example, because 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 points out that the routine signals its
completion status.

1-6

Documentation Format for System Routines
1.3 Returns Heading

1.3.3

Condition Values Signaled
Although 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, and the Condition Values Signaled heading in
the documentation format 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 is 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, it
is indicated by the word "None."
The following format is used to describe each argument:
argument-name
VMS Usage:
VMS data type
type:
argument data type
access:
argument access
mechanism:
argument passing mechanism

Next is a paragraph of structured text describing the arguments.
Additional information follows, if 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
previously, argument data types are described in two ways:
•

VMS data type

•

VAX standard data type

Ordinarily, the VAX standard data type, discussed in Section 1.4.2 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 the VMS
data type vector_ longword_unsigned, further explains that an array of
unsigned longwords must be declared.

1-7

Documentation Format for System Routines
1.4 Arguments Heading

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.
Table A-1 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
In actuality, 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 passing data to the called routine. Nevertheless, the phrase
argument data type is used frequently to describe the data type of the
data specified by the argument. This terminology is used because it is
more simple and straightforward than the strictly accurate phrase data
type of the.data specified by the argument.

Procedure calls result in the construction of an argument list on the
stack. (This process is described in Chapter 2.) The 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.
Table 1-3 lists each VAX standard data type that can appear for the type
entry in an argument description and the VMS-defined symbolic code for
each. These symbolic codes are used in descriptors.
For a detailed description of each of the following symbolic codes, see
Section 2.8.
Table 1-3 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
(continued on next page)

1-8

Documentation Format for System Routines
1.4 Arguments Heading

Table 1-3 (Cont.)

1.4.3

VAX Standard Data Types

Data Type

Symbolic Code

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

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_N RO

Numeric string, unsigned

DSC$K_DTYPE_NU

Numeric string, zoned sign

DSC$K_DTYPE_NZ

Octaword integer (signed)

DSC$K_DTYPE_O

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.

1-9

Documentation Format for System Routines
1.4 Arguments Heading

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.

•

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.

Following is a complete list of access methods that can appear under the
access entry in an argument description:

•

Read only

• Write only

•
•
•
•
•

Modify
Function call (before return)
JMP after unwind
Call after stack unwind
Call without stack unwind

For more information, see the VAX Procedure Calling and Condition
Handling Standard in Chapter 2 of this manual.

1.4.4

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:

1-10

•

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. Because 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.

Documentation Format for System Routines
1.4 Arguments Heading

•

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) that 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 descriptor. Each one 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 the types of descriptors and their corresponding class
types. See Section 2.9 for a detailed description of each descriptor class
type.

Table 1-4

Descriptor Passing Mechanism Class Types

Passing Mechanism

Descriptor Symbolic Code

By descriptor, fixed-length

DSC$K_CLASS_S
DSC$K_CLASS_D
DSC$K_CLASS_A
DSC$K_CLASS_P
DSC$K_CLASS_SD
DSC$K_CLASS_NCA
DSC$K_CLASS_VS
DSC$K_CLASS_VSA
DSC$K_CLASS_UBS
DSC$K_CLASS_UBA
DSC$K_CLASS_SB
DSC$K_CLASS_UBSB

By descriptor, dynamic string
By descriptor, array
By descriptor, procedure
By descriptor, decimal string
By descriptor, noncontiguous array
By descriptor, varying string
By descriptor, varying string array
By descriptor, unaligned bit string
By descriptor, unaligned bit array
By descriptor, string with bounds
By descriptor, unaligned bit string with bounds

1.4.5

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

A sentence or 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

1-11

Documentation Format for System Routines
1.4 Arguments Heading

A sentence that expresses 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:

a. 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.
b. 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.
c.

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

1.5

Additional explanatory paragraphs that 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.

Condition Values Returned Heading
A condition value is an unsigned longword that has the following uses in
the VAX architecture:

1-12

•

Indicates the success or failure of a called procedure

•

Describes an exception condition when an exception is signaled

Documentation Format for System Routines
1.5 Condition Values Returned Heading

•

Identifies system messages

•

Reports program success or failure to the command level

Section 2.5 explains in detail the uses for the longword condition value
and what it contains. Figure 2-2 depicts its format.
The documentation heading Condition Values Returned describes the
condition values returned by the routine when it completes execution
without generating an exception condition. These condition values describe
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 either
continues normal execution or terminates abnormally.
If a called routine executes without generating an exception condition, the
called routine returns a condition value in one or two of the following four
possible ways:

•

Condition Values Returned

•

Condition Values Returned in the I/O Status Block

•

Condition Values Returned in a Mailbox

•

Condition Values Signaled

The method used to return the condition value is indicated under the
Condition Values Returned heading in the documentation of each routine.
These methods are discussed individually in the following subsections.
Under these headings, a 2-column list shows the symbolic code for each
condition value the routine can return and an accompanying description.
The description explains whether the condition value indicates success or
failure and, if failure, what user action might have caused the failure and
what you can do to correct it. Condition values that indicate success are
listed first.
Symbolic codes for condition values are defined by the system. 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 three sections that follow discuss the ways in which the called routine
returns condition values.

1-13

Documentation Format for System Routines
1.5 Condition Values Returned Heading

1.5.1

Condition Values Returned
The possible condition value~ 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 1/0 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 are completed asynchronously. Each of these
asynchronous system services returns to the caller as soon as the service
call is queued. This allows the continued use of the calling program during
the execution of the service operations. System services that are completed
asynchronously all have arguments that specify an I/O status block. When
the system service operation is 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 in detail what the fields contain
in the longword condition value.

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
mailbox of the sending process.

1-14

Documentation Format for System Routines
1.5 Condition Values Returned Heading

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. Because 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-15

VAX Procedure Calling and Condition Handling
Standard
This chapter describes the VAX Procedure Calling and Condition Handling
Standard, Version 10.3.

2.1

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

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 to
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 VMS system services and within
programs written in VAX BLISS, VAX C, 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

2-1

VAX Procedure Calling and Condition Handling Standard
2.1 Introduction

2.1.1

•

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

•

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
efficiently

Goals of the Calling Standard
When the VAX Procedure Calling Standard was developed, 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 Ada, VAX BLISS, VAX BASIC,
VAX C, VAX COBOL, VAX CORAL, VAX FORTRAN, VAX Pascal, VAX
PEARL, VAX PUI, VAX RPG II, and calls to the operating system and
library procedures. The needs of other languages that Digital might
support in the future must be met by the standard or by a 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 should be writable 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 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 to have a variety of
techniques for argument handling. Specifically, the called procedure
must be able to do the following:
Reference arguments indirectly through the argument list
Copy atomic data types, strings, and arrays
Copy addresses of atomic data types, strings, and arrays

2-2

•

The standard should provide you with some control over fixing,
reporting, and controlling flow 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.

VAX Procedure Calling and Condition Handling Standard
2.1 Introduction

•

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-calling
mechanism include the following:

2.1.2

•

The procedure mechanism need not provide complete checking of
argument data types, data structures, and parameter access. The VAX
protection and memory-management system is not dependent upon
correct interactions between user-level calling and called procedures.
Such extended checking might be desirable in some circumstances, but
system integrity is not dependent upon it.

•

The VAX procedure mechanism need not provide complete information
for an interpretive VMS Debugger. The definition of the debugger
includes a debug symbol table (DST) 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 in accordance with
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 returns a known value not in accordance
with 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 where
the actual value is provided in the longword argument list entry by the
calling program.
Reference is a mechanism for passing parameters where the address of
the parameter is provided in the longword argument list by the calling
program.
Descriptor is a mechanism for passing parameters where 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.

2-3

VAX Procedure Calling and Condition Handling Standard
2.1 Introduction

A condition value is a 32-bit value used to identify uniquely an exception
condition. A condition value can 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.2

Calling Sequence
At the option of the calling program, you invoke the called procedure using
either the CALLG or CALLS instruction, as follows:
CAL LG
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 as follows:
push

argn

push

argl
#n, proc

CALLS

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 allowed only 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.

2-4

VAX Procedure Calling and Condition Handling Standard
2.3 Argument List

Figure 2-1

Argument List Format

:arglst

arg 1
arg 2

••
•

arg n
ZK-1885-GE

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
by 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:
•

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.

•

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 programs to call 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. Higher-level languages use the reference or descriptor
mechanisms for passing input parameters. VMS system services and VAX
BLISS, VAX C, or VAX MACRO programs use all three mechanisms.
A procedure with no arguments is called with a list consisting of a 0
argument count longword, as follows:
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 can be allocated in read-only memory at the option of
the calling program.

2-5

VAX Procedure Calling and Condition Handling Standard
2.3 Argument List

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 leftmost (first) argument has an address of arglst+4; the
next has an address of arglst+S, 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+S; the second
argument has 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

Because most higher-level languages do not specify the order of evaluation
of arguments (with respect to side effects), 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. You should
not write programs that depend on the order of evaluation of arguments.
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. By default, all language
processors, except VAX BLISS, VAX C, and VAX MACRO pass arguments
by reference or by descriptor.
Language extensions are needed to reconcile the different argumentpassing mechanisms. In addition to the default passing mechanism used,
each language processor is required to give you 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.

2-6

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

VAX Procedure Calling and Condition Handling Standard
2.3 Argument List

Data Type

Section

Value

Miscellaneous

2.8.3

Array

2.9

Reference

Descriptor

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.

You can use these intrinsic functions in the syntax of a procedure call to
control generation of the argument list. For example:
CALL SUB1(%VAL(l23), %REF(X), %DESCR(A))

In other languages the same effect might be achieved by making
appropriate attributes of the declaration of SUBl in the calling program.
Thus, you might write the following after making the external declaration
for SUBl:
CALL SUBl

2.4

(123, X, A)

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 Rl 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 Rl 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 Rl are undefined. Two
separate 32-bit entities cannot be returned in RO and Rl because higherlevel languages cannot process them.

In all other cases (the function value needs more than 64 bits, the data
type is a string, 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.

2-7

VAX Procedure Calling and Condition Handling Standard
2.4 Function Value Return

•

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 or 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
The VAX architecture 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.
Figure 2-2

Format of the Condition Value

28 27
Control

3 2

'
27

16 15

Severity

Condition Identification
)"-.

)

I sj

I Facility Number I Message Number I
ZK-1795-GE

Fields in the Condition Value
condition identification

Identifies the condition uniquely on a systemwide basis.

2-8

VAX Procedure Calling and Condition Handling Standard
2.5 Condition Value

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 systemwide
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 by Digital

Section 2.5.1 describes the severity code more fully.
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 by Digital for
future use.

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

2-9

VAX Procedure Calling and Condition Handling Standard
2.5 Condition Value

Symbol

Value

STS$S_INHIB_MSG

2.5.1

Meaning

Field

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

Mask for 27:16

Facility number

STS$M_FAC_NO

Mask

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

STS$V_CODE

Position of 14:3

Message code

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 O

Success

STS$S_SUCCESS

Size of 0

Success

STS$M_SUCCESS

Mask for O

Success

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, as expected.
A severity code of 2 indicates that an error has occurred but the procedure
did produce output. Execution can continue, but the results produced by
the component generating the condition value are not all correct.
A severity code of 3 indicates that the procedure generating the condition
value completed successfully but has some parenthetical information to be
included in a message if the condition is signaled.
A severity code of 4 indicates that a severe error occurred and the
component generating the condition value was unable to produce output.

2-10

VAX Procedure Calling and Condition Handling Standard
2.5 Condition Value

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

The calling program typically performs a low-bit test, so it treats
warnings, errors, and severe errors as failures, and 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

Continue
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
SYS$0UTPUT. In addition, for severities other than success (STS$K_
SUCCESS), a copy of the message is made on SYS$ERROR. At program
exit, success and information completion values do not generate messages;
however, warning, error, and severe error condition values do generate
messages to both SYS$0UTPUT 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.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 or be used to
generate a message, or both.
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 so that they do not
conflict with values generated by Digital.

2-11

VAX Procedure Calling and Condition Handling Standard
2.6 Register Usage

2.6

2.6.1

Scalar Register Usage
The following registers have defined uses:
Register

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.

RO,R1

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

Registers R2 through Rll are to be preserved across procedure calls.
The called procedure can use these registers, provided 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 restores all registers correctly. In addition,
PC, SP, FP, and AP are always preserved by the CALL instruction and
restored by the RET instruction. However, a called procedure can use AP
as a temporary register.
If JSB routines are used, they must not save or modify any preserved
registers (R2 through Rll) not already saved by the entry mask
mechanism of the calling program.

2.6.2

Vector Register Usage
The VAX Calling Standard specifies no conventions for preserved vector
registers, vector argument registers, or vector function value return
registers. All such conventions are by agreement between the calling
and called procedures. In the absence of such an agreement, all vector
registers, including VO through V15, VLR, VCR, and VMR are scratch
registers. Among cooperating procedures, a procedure that does preserve
or otherwise manipulate the vector registers by agreement with its callers
must provide an exception handler to restore them during an unwind.

2-12

VAX Procedure Calling and Condition Handling Standard
2.6 Register Usage

2.6.3

Vector and Scalar Processor Synchronization
There are two kinds of synchronization between a scalar and vector
processor pair: memory synchronization and exception synchronization.
2.6.3.1

Memory Synchronization
Every procedure is responsible for synchronization of memory operations
with the calling procedure and with procedures it calls. If a procedure
executes vector loads or stores, one of the following must occur:

•

An MSYNC instruction (a form of the MFVP instruction) must
be executed before the first vector load/store to synchronize with
memory operations issued by the caller. While an MSYNC instruction
might typically occur in the entry code sequence of a procedure,
exact placement might also depend on a variety of optimization
considerations.

•

An MSYNC instruction must be executed after the last vector load
or store to synchronize with memory operations issued after return.
While an MSYNC instruction might typically occur in the return code
sequence of a procedure, exact placement might also depend on a
variety of optimization considerations.

•

An MSYNC must be executed between each vector load/store and
each standard call to other procedures to synchronize with memory
operations issued by those procedures.

That is, any procedure that executes vector loads or stores is responsible
for synchronizing with potentially conflicting memory operations in any
other procedure. However, execution of an MSYNC to ensure scalar/vector
memory synchronization can be omitted when it can be determined for the
current procedure that all possibly incomplete vector load/stores operate
only on memory that is not accessed by other procedures.
2.6.3.2

Exception Synchronization
Every procedure must ensure that no exception can be raised after the
current frame is changed (as a result of either a CALL or RET). If a
procedure executes any vector instruction that might possibly raise an
exception, then a SYNC instruction (a form of the MFVP instruction) must
be executed prior to any subsequent CALL or RET.

However, if the only possible exceptions that can occur are ensured to be
reported by an MSYNC instruction that is otherwise needed for memory
synchronization, then the SYNC is redundant and can be omitted as an
optimization.
Moreover, if the only possible exceptions that can occur are ensured
to be reported by one or more MFVP instructions that read the vector
control registers, then the SYNC is redundant and can be omitted as an
optimization.

2-13

VAX Procedure Calling and Condition Handling Standard
2.6 Register Usage

2.6.3.3

Synchronization Summary

Memory synchronization with the caller of a procedure that uses the
vector processor is required because there might be scalar machine
writes (to main memory) still pending at the time of entry to the called
procedure. The various forms of write-cache strategies allowed by the
VAX architecture combined with the possibly independent scalar and
vector memory access paths implies that a scalar store followed by a CALL
followed by a vector load is not safe without an intervening MSYNC.
Within a procedure that uses the vector processor, proper memory and
exception synchronization might require use of an MSYNC instruction or
a SYNC instruction, or both, prior to calling another procedure or upon
being called by another procedure. Further, for calls to other procedures,
the requirements can vary from call to call, depending on details of actual
vector usage.
An MSYNC instruction (without a SYNC) at procedure entry, at procedure
exit, and prior to a call provides proper synchronization in most cases.
A SYNC instruction without an MSYNC prior to a CALL (or RET) is
sometimes appropriate. The remaining two cases, where either both or
neither MSYNC and SYNC are needed, are probably rare.
Refer to the VAX Vector Architecture section in the VAX MACRO and
Instruction Set Reference Manual for the specific rules on what exceptions
are ensured to be reported by MSYNC and other MFVP instructions.

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 instruction.
Figure 2-3

Stack Frame Generated by CALLG and CALLS Instructions

condition handler (0)

: (SP): (FP))

mask/PSW

AP
FP

PC
R2

(optional)

Rll

(optional)

FP always points at the condition handler longword of the stack frame.
Other uses of FP within a procedure are 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 modified continually and
unpredictably.

2-14

VAX Procedure Calling and Condition Handling Standard
2. 7 Stack Usage

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 by 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:
•

Atomic

•

String

•

Miscellaneous

When existing data types are not sufficient to satisfy the semantics of a
language, new data types are added to this standard, including certain
language-specific ones. These data types can generally be passed by
immediate value (if 32 bits or less), by reference, or by descriptor.
You use the encoding given in Sections 2.8.1 and 2.8.2 whenever you need
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.
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.

2-15

VAX Procedure Calling and Condition Handling Standard
2.8 Argument Data Types

Table 2-1

Atomic Data Types

Symbol

Code

Name/Description

DSC$K_DTYPE_Z

Unspecified
The calling program has specified no data type.
The default argument for the called procedure
should be the correct type.

DSC$K_DTYPE_BU

Byte (unsigned)
8-bit unsigned quantity.

DSC$K_DTYPE_WU

Word (unsigned)
16-bit unsigned quantity.

DSC$K_DTYPE_LU

Longword (unsigned)

DSC$K_DTYPE_QU

Quadword (unsigned)

32-bit unsigned quantity.
64-bit unsigned quantity.
DSC$K_DTYPE_OU

Octaword (unsigned)
128-bit unsigned quantity.

DSC$K_DTYPE_B

Byte integer (signed)
8-bit signed 2's-complement integer.

DSC$K_DTYPE_W

Word integer (signed)
16-bit signed 2's-complement integer.

DSC$K_DTYPE_L

Longword integer (signed)
32-bit signed 2's-complement integer.

DSC$K_DTYPE_Q

Quadword integer (signed)
64-bit signed 2's-complement integer.

DSC$K_DTYPE_O

DSC$K_DTYPE_F

Octaword integer (signed)
128-bit signed 2's-complement integer.
F_floating
32-bit F_floating quantity representing a singleprecision number.

DSC$K_DTYPE_D

D_floating
64-bit D_floating quantity representing a doubleprecision number.

DSC$K_DTYPE_G

G_floating
64-bit G_floating quantity representing a doubleprecision number.

DSC$K_DTYPE_H

H_floating
128-bit H_floating quantity representing a
quadruple-precision number.
(continued on next page)

2-16

VAX Procedure Calling and Condition Handling Standard
2.8 Argument Data Types

Table 2-1 (Cont.)

Atomic Data Types

Symbol

Code

Name/Description

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 details.

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.
Table 2-2 String Data Types
Symbol

Code

DSC$K_DTYPE_T

Name/Description
Character string
A single 8-bit character (atomic data type) or a
sequence of Oto 2 16 -1 8-bit characters (string
data type).
(continued on next page)

2-17

VAX Procedure Calling and Condition Handling Standard
2.8 Argument Data Types

Table 2-2 (Cont.}

String Data Types

Symbol

Code

Name/Description

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 O to 216 -1 8-bit characters (see
Section 2.8.7 for details). When this data type
is used with descriptors, it can only be used
with the varying string and varying string array
descriptors because the length field is interpreted
differently from the other 8-bit string data types.
(See Sections 2.8.7, 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
A string of O 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, because allocation is a multiple
of 8 bits.

DSC$K_DTYPE_VU

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

2.8.3

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

2-18

VAX Procedure Calling and Condition Handling Standard
2.8 Argument Data Types

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 2-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, tbis 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~b~v~ue

A 2-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 100-nanosecond
units offset from the VMS operating system base
date and time, which is 00:00 o'clock, November
17, 1858 (the Smithsonian base date and time
for astronomical calendars). The value zero
indicates that the date and time have not been
specified, so a default value or distinctive print
format can be used.
Note that the ADT data type is the same as the
VMS date format for positive values only.

2.8.4

Facility-Specific Data Type Codes
Data type codes 160 through 191 are reserved by Digital for facilityspeci:fic purposes. These codes must not be passed between facilities
because different facilities can use the same code for different purposes.
These codes might be used by compiler-generated code to pass parameters
to the language-specific run-time support procedures associated with that
language or the VMS Debugger.

2-19

VAX Procedure Calling and Condition Handling Standard
2.8 Argument Data Types

2.8.5

Reserved Data Type Codes
The type codes 38 through 191 are reserved by 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, as follows:
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
:A

Exponent

k16>

k15>

k17>

:A+2

f<12>

k11>

k14>

k13>

:A+4

k8>

k7>

f<10>

k9>

:A+6

k4>

k3>

k6>

k5>

:A+8

kO>

Sign

k2>

k1>

:A+10
ZK-1887-GE

A COBOL intermediate temporary datum represents a floating-point
datum with a normalized, 18-digit, packed-decimal fraction and a 16-bit
2's-complement 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 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-20

VAX Procedure Calling and Condition Handling Standard
2.8 Argument Data Types

2.8.7

Varying Character String Data Type {DSC$K_DTYPE_VT)
The varying character string data type consists of the following two
fixed-length areas allocated contiguously with no padding in 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 that can vary from zero to a
maximum length defined for each instance of string. The range of this
maximum length is Oto 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 can modify all bytes of BODY-even those beyond the new
length.
For example, consider a varying string with a maximum length of seven
characters. For the representation of the string, ABC, CURLEN would be
three and the last four bytes would be undefined, as follows:
15

[

:adr

3
A
B

c
\ \ \
\ \ \
\ \ \
\ \ \

0
ZK-1889-GE

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
are added to this standard.

2-21

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

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.
Note: Unless stated otherwise, all fields in descriptors represent
unsigned quantities, are read-only from the point of view of the
called procedure, and can be allocated in read-only memory at the
option of the calling program.
If a language processor implements a language-specific data type that

is not added to this standard (see 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 fills 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 PU! 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

J DTYPE 1

Length

:Descriptor

Pointer
ZK-1890-GE

2-22

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

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 Sections 2.8.1 and 2.8.2.

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 following sections. 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 can be used at
run time by a called procedure to determine which
descriptor is being passed.

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 preceding
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 fixedlength descriptor.
Figure 2-5

Fixed-Length Descriptor Format

DlYPE

Length

:Descriptor

Pointer
ZK-1891-GE

2-23

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

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
Sections 2.8.1 and 2.8.2.

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 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.
Figure 2-6

Dynamic String Descriptor Format

DTYPE

Length

:Descriptor

Pointer
ZK-1892-GE

2-24

Symbol

Description

DSC$W_LENGTH

DSC$B_DTYPE

A 1-byte data type code. Data type codes are listed in
Sections 2.8.1 and 2.8.2.

DSC$B_CLASS

2 = DSC$K_CLASS_D.

DSC$A_POINTER

Address of first byte of data storage.

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

2.9.4

Variable Buffer Descriptor {DSC$K_CLASS_V)
This descriptor is 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-25

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

Figure 2-7

Array Descriptor Format

DTYPE

I
l

Length

:Descriptor

Pointer
DIMCT

AFLAGS

Digits

Scale

Block 1 - Prototype

ARSIZE

AO
M1
-v
-r--

•
•
•

-1.;

-,..,

Block 2 - Multipliers

M(n-1)
Mn

L1
U1
-v

•
•

•
Ln
Un

.-&...;

Block 3 - Bounds

i
ZK-1888-GE

2-26

Symbol

Description

DSC$W_LENGTH

Length of an array element in bytes, unless the SC$B_DTYPE
field contains the value 1 (aligned bit string) or 21 (packeddecimal 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
Sections 2.8.1 and 2.8.2.

DSC$B_CLASS

4 = DSC$K_CLASS_A.

DSC$A_POINTER

Address of first actual byte of data storage.

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

Symbol

Description

DSC$B_SCALE
<2,7:0>

Signed power-of-two or -ten multiplier, as specified by DSC$V_
FL_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. This field should be zero unless
the DSC$B_TYPE field specifies a string data type that could
contain numeric values.

DSC$B_AFLAGS
<2,23:16>

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

DSC$8_DIMCT
<2,31 :24>

Must be zero.

DSC$V_FL_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_FL_REDIM
<2,20>

If set, the array can be
redimensioned; that is, DSC$A_AO,
DSC$L_Mi,DSC$L_Li, and
DSC$L_Ui can 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 leftmost subscript (first
dimension) is varied most rapidly,
and the rightmost subscript (nth
dimension) is varied least rapidly.
If not set, the elements are stored
by rows (most other languages).
That is, the rightmost subscript is
varied most rapidly and the leftmost
subscript is varied least rapidly.

DSC$V_FL_COEFF
<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.

Number of dimensions, n.

2-27

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

Symbol

Description

DSC$L_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 can 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 because the unit of length is
bits while the unit of allocation is aligned bytes.

DSC$A_AO
<4,31 :0>

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

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

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

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

Lower bound (signed) of ith dimension.

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

Upper bound (signed) of ith 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 = Ao + I*LENGTH
=POINTER+ [I - LiJ*LENGTH

The effective address, E, for element A(Ii,I2) with DSC$V_FL_COLUMN
clear:
E =Ao+ [I1*M2 + I2l*LENGTH
=POINTER+ [[I1-L1J*M2 + I2 - L2]*LENGTH

The effective address, E, for element A(I1 ,I 2 ) with DSC$V_FL_COLUMN
set:
E =Ao+ [I2*M1 + Ii]*LENGTH
=POINTER+ [[I2-L2J*M1 + I1 - L1J*LENGTH

The effective address, E, for element A(Ii, . . . ,In) with
DSC$V_FL_COLUMN clear:
E =Ao+ [[[[ ... [I1J*M2 + ... ]*Mn-2 + In-2J*Mn-l
+ In-ll*Mn + Inl*LENGTH
=POINTER+ [[[[ ... [I1 - L1J*M2 + ... ]*Mn-2 + In-2
- Ln-2l*Mn-l + In-1 Ln-ll*Mn +In - Lnl*LENGTH

The effective address, E, for element A(Ii, . . . ,In) with
DSC$V_FL_COLUMN set:

2-28

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

E =Ao+ [[[[ ... [Inl*Mn-1 + ... ]*M3
+ I3]*M2 + I2]*M1 + Ii]*LENGTH
=POINTER+ [[[[ ... [In - Ln]*Mn-1 + ... ]*M3 + I3
- L3]*M2 + I2 - L2]*M1
+ Ii - LiJ*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-GE

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
Sections 2.8.1 and 2.8.2.

DSC$B_CLASS

5 = DSK$K_CLASS_P.

DSC$A_POINTER

Address of entry mask to routine.

Procedures return a function value in RO, Rl/RO, 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)
The procedure incarnation descriptor is obsolete.

2.9.8

Label Descriptor (DSC$K_CLASS_J)
The label descriptor is reserved for use by the VMS Debugger.

2.9.9

Label Incarnation Descriptor (DSC$K_CLASS_JI)
The label incarnation descriptor is obsolete.

2-29

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

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

Length

DTYPE

Pointer
ReseNed

SFLAGS

Scale

Digits

ZK-1894-GE

2-30

Symbol

Description

DSC$W_LENGTH

DSC$B_DTYPE

A 1-byte data type code. Data type codes are listed in
Sections 2.8.1 and 2.8.2.

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_
FL_BINSCALE, to convert the internal form to external form.
(See examples in the following table.)

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. This field should be zero unless
the DSC$8_TYPE field specifies a string data type that could
contain numeric values.

DSC$B_SFLAGS
<2,23:16>

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

Must be zero.

DSC$V_FL_BINSCALE
<2,19>

Reserved
<2,23:20>

Must be zero.

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

Examples of DSC$B_SCALE and DSC$V_FL_BINSCALE interpretation
are presented in the following table:

2.9.11

Internal Value

DSC$B_
SCALE

DSC$V_FL_
BINSCALE

123
123
200
200

+1
+1
-2
-2

1230
246

External Value

Noncontiguous Array Descriptor (DSC$K_CLASS_NCA)
The noncontiguous array descriptor describes an array in which the
storage of the array elements can be allocated with a fixed, nonzero
number of bytes separating logically adjacent elements. Two elements
are said to be logically adjacent if their subscripts differ by 1 in the most
rapidly varying dimension only. The difference between the addresses
of two adjacent elements is termed the stride. Whether elements are
stored by row or by 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 allocations.
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 contiguous
arrays.
Figure 2-10 shows the format of a noncontiguous array descriptor, which
consists of three contiguous blocks.

2-31

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

Figure 2-10

Noncontiguous Array Descriptor Format

DTYPE

Length

:Descriptor

Pointer
DIMCT

Block 1 - Prototype

I AFLAGS I Digits I Scale
ARSIZE

AO
S1
-L,.,

••

,...L,_,

•

S(n-1)
Sn

Block 2 - Strides

L1
U1
~

""'""'

••
•

""'""'

Block 3 - Bounds

Ln
Un
ZK-1895-GE

2-32

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
Sections 2.8.1 and 2.8.2.

DSC$B_CLASS

10 = DSC$K_CLASS_NCA.

DSC$A_POINTER

Address of first actual byte of data storage.

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

Symbol

Description

DSC$B_SCALE
<2,7:0>

Signed power-of-two or -ten multiplier, as specified by
DSC$V_FL_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. This field should be
zero unless the DSC$B_TYPE field specifies a string data
type that could contain numeric values.

DSC$B_AFLAGS
<2,23:16>

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

Reserved for future
standardization by Digital. Must
be zero.

DSC$V_FL_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_FL_RED IM
<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 if the
program unit allocating the descriptor is uncertain whether
the array is actually contiguous, the value placed in ARSIZE
might be meaningless.
For data type 1 (aligned bit string), DSC$W_LENGTH is in
bits while DSC$L_ARSIZE is in bytes because 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(O,O, ... ,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 ith 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 ith dimension.

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

Upper bound (signed) of the ith dimension.

DSC$A_AO = POINTER - ( S1 *L1 + S2 *L2 + ... +Sn *Ln)

The following formulas specify the effective address, E, of an array
element.

2-33

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

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(l):
E =Ao + S1*I
=POINTER+ S1*[I - L1]

The effective address, E, of A(I1,I2):
E =Ao + S1*I1 + S2*I2
=POINTER+ S1*[I1 - L1J + S2*[I2 - 12]

The effective address, E, of A(Ii, ... ,In):
E =Ao+ S1*I1 + . . . + Sn*In
=POINTER+ S1*[I1 - L1] + . . . + Sn*[In
- Ln]

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 in 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 that 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 can modify all bytes of BODY.
Figure 2-11 shows the format of a varying string descriptor.
Figure 2-11

Varying String Descriptor Format

DTYPE

MAXSTRLEN

Pointer
ZK-1896-GE

2-34

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

Symbol

Description

DSC$W_MAXSTRLEN

Maximum length of the BODY field of the varying
string in bytes in the range Oto 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 Section 2.8.2 and Section 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.

In the following example, MAXSTRLEN contains five, CURLEN contains
four, string is currently ABCD, and the remaining byte is currently
undefined.
31

0
11

:Descriptor

adr

:adr

c
D
\ \ \

0
ZK-1897-GE

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 in
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 that can vary from zero to the
maximum length defined for an array element (MAXSTRLEN).

2-35

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

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 can modify all bytes of BODY. The format of this
descriptor is the same as the noncontiguous array descriptor except for
the first two longwords. Figure 2-12 shows the format of a varying string
array descriptor.
Figure 2-12

Varying String Array Descriptor Format

DTYPE

MAXSTRLEN

Pointer
DIMCT

J AFLAGS J Digits

Block 1 - Prototype

Scale

AR SIZE

1
............

AO
S1

••
•

i
.............

Block 2 - Strides

S(n-1)
Sn

L1
U1
-i,.,,

-r-'

••
•

-i,.,,

-r-'

Block 3 - Bounds

Ln
Un
ZK-1898-GE

2-36

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

Symbol

Description

DSC$W_MAXSTRLEN

Maximum length of the BODY field of an array
element in bytes in the range Oto 2 16 -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 Section 2.8.2 and Section 2.8. 7). The use of
other data types is reserved for future standardization.

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 can 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

DTYPE

Length

:Descriptor

Base
POS
ZK-1899-GE

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 2.8.1 and 2.8.2). The use
of other data types is reserved for future standardization.

DSC$B_CLASS

13 = DSC$K_CLASS_UBS

2-37

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

Symbol

Description

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$L_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:
EXTZV

DSC$L_POS(R0), DSC$W_LENGTH(RO), @DSC$A_BASE(R0), Rl

If RO contains the address of the descriptor, this instruction copies the bit

string to Rl.

2.9.15

Unaligned Bit Array Descriptor (DSC$K_CLASS_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. You can access elements of the array 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.

2-38

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

Figure 2-14

DIMCT

Unaligned Bit Array Descriptor Format

l
I

DTYPE

l
I

Length

:Descriptor

Base
AFLAGS

Digits

Block 1 - Prototype

Scale

ARSIZE

l
-.-

VO
81

•••

i
"'"""'

Block 2 - Strides

""""'

Block 3 - Bounds

S(n-1)
Sn

L1
U1
-i..,,

•••
Ln
Un

POS

f
Block 4 - Position
ZK-1900-GE

2-39

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

2-40

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 Sections
2.8.1 and 2.8.2). The use of other data types is reserved for
future standardization.

DSC$B_CLASS

14 = DSC$K_CLASS_UBA.

DSC$A_BASE

Base address relative to the effective bit offset, EB, 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

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. This field should be
zero unless the DSC$B_TYPE field specifies a string data
type that could contain numeric values.

DSC$B_AFLAGS
<2,23:16>

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

Reserved for future
standardization by Digital. Must
be zero.

DSC$V_FL_BINSCALE
<2,19>

Must be zero.

DSC$V_FL_RED IM
<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 bits. If the elements are not allocated
contiguously or if the program unit allocating the descriptor is
uncertain whether the array is actually contiguous, the value
placed in ARSIZE might be meaningless.

DSC$L_VO
<4,31:0>

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

DSC$L_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$L_Li
<3+n+2*i,31 :0>

Lower bound (signed) of the ith dimension.

DSC$L_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).

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

The signed, 32-bit effective bit offset, EB, of A(I1 ):
EB= Vo+ S1*Ii
= POS + Si*[Ii - Lil

The signed, 32-bit effective bit offset, EB, of A(I1,l2):
EB= Vo+ S1*I1 + S2*I2
= POS + Si*[Ii - Lil + S2*[I2 - L2]

The signed, 32-bit effective bit offset, EB, of A(Ii, ... , In):
EB= Vo+ S1*Ii + ... + Sn*In
= POS + Si*[Ii
- Li] + ... + Sn*[In
- Ln]

Note that EB is computed ignoring integer overflow. EB is then usable as
the position operand, and the content 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 2 28 bytes of all bytes
of storage in the bit array.
For example, consider a 1-origin, !-dimension, 5-element array consisting
of 3-bit elements allocated adjacently (therefore, Sl = 3). Assume BASE is
byte 1000 and the first actual element, A(l), starts at bit <4> of byte 1001.
7

:1000
2

:1001

0
3

:1002

:1003
ZK-1901-GE

The following dependent field values occur in the descriptor:
POS
i2
Vo = 12 - 3*i

2.9.16

= 9

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.

2-41

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

Figure 2-15 String with Bounds Descriptor Format

DTYPE

Length

:Descriptor

Pointer
SB_L1
SB_U1
ZK-1908-GE

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 Sections 2.8.1
and 2.8.2). 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.

DSC$L_SB_L 1

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

DSC$L_SB_U1

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

The following formula specifies the effective address, E, of a string element
A(I):
E = POINTER + [I - SB_Ll]

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.

2-42

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

Figure 2-16

Unaligned Bit String with Bounds Descriptor Format

DTYPE

Length

:Descriptor

Base
POS
UBSB_L1
UBSB_U1
ZK-1909-GE

Symbol

Description

DSC$W_LENGTH

Length of data item 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.1
and Section 2.8.2). 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 the signed relative bit position, POS,
used to locate the bit string. The base address need not be
the first actual byte of data storage.

DSC$L_POS

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

DSC$L_UBSB_L 1

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

DSC$L_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 by Digital for facilityspecific purposes. These codes must not be passed between facilities
because different facilities might use the same code for different purposes.
These codes can be used by compiler-generated code to pass parameters
to the language-specific, run-time support procedures associated with that
language or to VAX DEBUG.

2-43

VAX Procedure Calling and Condition Handling Standard
2.9 Argument Descriptor Formats

2.9.19

Reserved Descriptor Class Codes
Descriptor classes 15 through 191 are reserved by 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, you can take four types
of action when a condition occurs:
•

Ignore the condition.
For example, if an underflow occurs in a floating-point operation,
continuing from the point of the exception with a zero result might be
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.
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-44

VAX Procedure Calling and Condition Handling Standard
2.10 VAX Conditions

2.10.1

Condition Handlers
To handle hardware- or software-detected exceptions, the VAX Condition
Handling Facility allows you to specify a condition handler procedure to be
called when an exception condition occurs.
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 SYS$0UTPUT only. All other
conditions, including informational messages (STS$K_INFO), produce
messages on SYS$0UTPUT 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
is entered and logs the condition. The handler returns 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
is 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 are searched until the frame for the system program invoking
the user program is reached. A default condition handler that prints an
error message is then entered.

2.10.2

Condition Handler Options
Each procedure activation potentially has a single condition handler
associated with it. This condition handler is 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

2-45

VAX Procedure Calling and Condition Handling Standard
2.10 VAX Conditions

condition value should be examined to determine the cause of the signal.
After the handler processes the condition or ignores 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 begins 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, you can remove it by
clearing its address in the current procedure activation's stack frame.

•

Enable or disable certain arithmetic exceptions.
The software can enable or disable the following hardware exceptions:
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; 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.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
the value 0, indicating no handler. You establish a handler by moving the
address of the handler's procedure entry point mask to the establisher's
stack frame.

2-46

VAX Procedure Calling and Condition Handling Standard
2.11 Operations Involving Condition Handlers

In addition, the VMS operating system 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 procedurenesting rules, they should not be used by modular code. Instead, the
stack-based declaration should be used.
The following code establishes a condition handler:
MOVAB handler_entry_point,O(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. You do this by clearing the handler
address in the stack frame.
The code to revert to the caller's handling is as follows:
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 Rl 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
Rl is useful for debugging checks and gathering statistics. Hardware and
system service exceptions behave like calls to LIB$SIGNAL.
The signal procedure examines th& two exception vectors first, then up to
a system-defined. maximum number of 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

2-47

VAX Procedure Calling and Condition Handling Standard
2.11 Operations Involving Condition Handlers

frames using the saved FP in each frame. The exception vectors have
three address locations per access mode.
As part of image startup, 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
a system-defined maximum number of 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
indicating that an attempt was made to continue from a noncontinuable
exception and exits with the condition value as the final image status.

Figure 2-1 7 lists all combinations of interaction between condition handler
actions, the default condition handlers, the types of signal, 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-48

VAX Procedure Calling and Condition Handling Standard
2.11 Operations Involving Condition Handlers

Figure 2-17 Interaction Between Handlers and Default Handlers

Call to:

Signaled
Condition
Severity

<2:0>

<4
Ll8$SIGNAL
or
Hardware
Exception
=4

LIB$STOP

Force
(=4)

Default
Handler
Gets Control

Condition
Message
REf

Handler
Specifies
Continue

REf

Condition
Message
EXIT

REf

Condition
Message
EXIT

"Cannot
Continue"
EXIT

Handler
Specifies
UNWIND

No Handler
ls Found
(Stack Bad)

UNWIND

Call
Last
Chance
Handler
EXIT

UNWIND

Call
Last
Chance
Handler
EXIT

UNWIND

Call
Last
Chance
Handler
EXIT
ZK-4247-GE

2.12

Properties of Condition Handlers
The following subsections describe 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. You can
use the symbols CHF$L_SIGARGLST ( =4) and CHF$L_MCHARGLST
( =8 ) to access the condition handler arguments relative to AP.
The signal_args longword 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. 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

2-49

VAX Procedure Calling and Condition Handling Standard
2.12 Properties of Condition Handlers

handlers might only 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-18 shows the format of the mechanism argument vector.
Figure 2-18

Format of the Mechanism Argument Vector

CHF$L_MCH_ARGS

Frame

CHF$L_MCH_FRAME

Depth

CHF$L_MCH_DEPTH

CHF$L_MCH_SAVRO

CHF$L_MCH_SAVR1
ZK-1883-GE

The frame is the contents of the FP in the establisher's context. If the
restrictions described in Section 2.12.3 are met, the frame can be used as
a base to access the local storage of the establisher.
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 Rl 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; the next 0 or several longwords are additional
parameters. The remaining two longwords are the PC and PSL.
Figure 2-19 shows the format of the signal argument vector.

2-50

VAX Procedure Calling and Condition Handling Standard
2.12 Properties of Condition Handlers

Figure 2-19

Format of the Signal Argument Vector

CHF$L_SIG_ARGS

Condition-Value

CHF$L_SIG_NAME

None or Some
Additional
Arguments

PC
PSL
ZK-1882-GE

If the VAX vector hardware or emulator option is in use, then for hardware

detected exceptions, the vector state is implicitly saved before any
condition handler is entered and restored after the condition handler
returns. (No save/restore is required for exceptions that are initiated by
calls to LIB$SIGNAL or LIB$STOP because there can be no useful vector
state at the time of such calls in accordance with the rules for Vector
Register Usage in Section 2.6.2.) A condition handler can thus make use
of the system vector facilities in the same manner as mainline code.
The saved vector state is not directly available to a condition handler.
A condition handler that needs to manipulate the vector state to carry
out agreements with its callers can call the SYS$RESTORE_VP_STATE
service. This service restores the saved state to the vector registers
(whether hardware or emulated) and cancels any subsequent restore. The
vector state can then be manipulated directly in the normal manner by
means of vector instructions. (This service is normally of interest only
during processing for an unwind condition.)

2.12.2

System Default Condition Handlers
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 SYS$PUTMSG in the VMS System Services Reference
Manual for the format of the signal argutnent list.

2.12.3

Use of Memory
A condition handler and the procedures it calls can refer only to 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-51

VAX Procedure Calling and Condition Handling Standard
2.12 Properties of Condition Handlers

2.12.4

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 conditionhandling 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 is signaled with a call to LIB$STOP,
the image exits. 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.5

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 the longword containing
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=O) 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 signalargs 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 either a standard success code
(SS$_NORMAL), or it indicates failure with one of the following return
status condition values:

2-52

•

No signal active (SS$_NOSIGNAL)

•

Already unwinding (SS$_UNWINDING)

•

Insufficient frames for depth (SS$_INSFRAME)

VAX Procedure Calling and Condition Handling Standard
2.12 Properties of Condition Handlers

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. If the depth specified includes unwinding
the establisher's frame, the current handler is 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
Rl

establisher's frame
0 (that is, unwinding self)
RO that unwind will restore
Rl 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 Rl in the mechanism_args vector. They are restored from the
mechanism_args vector at the end of the unwind. Depending on the
arguments to SYS$UNWIND, the unwinding operation is terminated as
follows:
SYS$UNWIND(O,O)

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

SYS$UNWIND(depth,O)

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.

You can call SYS$UNWIND 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.12.6

Signaler's Registers
Because the handler is called and can in turn call routines, the actual
register values 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

2-53

VAX Procedure Calling and Condition Handling Standard
2.12 Properties of Condition Handlers

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_HANDL+4. Thus, the registers are
as follows:
RO, R1

2.13

In mechanism_args

R2 .. R11

Last frame saving it

Old AP of SYS$CALL_HANDL+4 frame

Old FP of SYS$CALL_HAN DL+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, and C establish condition handlers Ah, Bh, and Ch. If
A calls Band 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 as follows:
<SignalT>
y

x
Bh
<Signal S>

B
A
Which Was Programmed:

A
B --------------_. Bh

c
<Signal S>

y
<SignalT>
ZK-1884-GE

The handlers are searched for in the following 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 cannot be coded in nonrecursive languages such as FORTRAN.
Instead, Bh can establish itself or another procedure as its handler (Bhh).

2-54

VAX Procedure Calling and Condition Handling Standard
2.13 Multiple Active Signals

The following algorithm is used on the second and subsequent signals that
occur before the handler for the original signal returns to the conditionhandling 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 is not automatically 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 preceding diagram, if Ah specifies unwinding to A, the following
handlers are 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-55

VMS Data Types

This appendix describes the structures of the VMS operating system data
types and ones that support the higher level languages.

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 conceptual types; that is, they
carry meaning 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 therefore has
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 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-1 and read its definition.

Find the same VMS data type in the appropriate VAX. language
implementation table (Tables A-2 through A-13) 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-1 lists and describes the VMS data types.

A-1

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: O 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 1 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:

ARG 1
ARG2

•

••
ARGN

ZK-4204-GE

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 can have only
two values: 1 (true) and O (false).

byte_signed

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

byte_unsigned

Is the same as the data type byte (unsigned) in Table 1-3.

channel

Unsigned word integer that is an index to an 1/0 channel.

char_string

String of from o 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:
(continued on next page)

A-2

VMS Data Types
A.1 VMS Data Types

Table A-1 (Cont.)
Data Type

VMS Data Types
Definition

0
"X"

"Y"

: A+ 1

"Z"

:A+2
ZK-4202-GE

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 is the real part ( r) of the complex number; the second is the imaginary part ( i ).
The structure of an F_floating complex number is as follows:

15 14

Real

Part
Imaginary

Part

7 6

sJ Exponent I Fraction
Fraction
s} Exponent I Fraction
Fraction

:A
:A+2
:A+4
:A+6
ZK-4203-GE

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

15 14

7 6

sJ Exponent l
Real

Part

Fraction

:A+2

Fraction

:A+4

Fraction

:A+6

sJ Exponent l
Imaginary

Fraction

:AS

Fraction

: A+ 10

Fraction

: A+ 12

Fraction

: A+ 14
ZK-4201-GE

(continued on next page)

A-3

VMS Data Types
A.1 VMS Data Types

Table A-1 (Cont.)
Data Type

VMS Data Types
Definition
A G_floating complex number ( r,i) is comprised of two G_floating point numbers: the
first is the real part ( r) of the complex number; the second is the imaginary part ( i ).
The structure of a G_floating complex number is as follows:

15 14

4 3

sl Exponent l

Fraction

Real

Fraction

:A+2

Part

Fraction

:A+4

Fraction

:A+6

sl Exponent l

Fraction

:AS

Imaginary

Fraction

:A+ 10

Part

Fraction

: A+ 12

Fraction

: A+ 14
ZK-4200-GE

cond_value

Unsigned longword integer denoting a condition value (that is, a return status or
system condition code) that is typically returned by a procedure in RO. Each numeric
condition value has a unique symbolic name in the following format, where code is a
mnemonic describing the return condition:

28 27

Control

Severity

Condition Identification

3 2

16 15

)

I sl

I Facility Number I Message Number I
ZK-1795-GE

(continued on next page)

A-4

VMS Data Types
A.1 VMS Data Types

Table A-1 (Cont.)
Data Type

VMS Data Types
Definition
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 ( O) 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.

context

Unsigned longword 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.

date_time

Unsigned 64-bit 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 15-character 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 the device name string, it indicates that the string is a physical device name.

ef_cluster_name

Character string denoting the 1- to 15-character 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:

Forward Link (Used by VMS only)
Exit Handler Address
These 3 bytes must be O

arg. count

Address Condition Value (Written by VMS)

.-t,._.

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

.-t,._.

:r
ZK-1714-GE

fab

Structure denoting an HMS file access block.
(continued on next page)

A-5

VMS Data Types
A.1 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 users, 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

Owner

System

DEWRDEWRDEWRDEWR
151413121110 9 8 7 6 5 4 3 2 1 0
ZK-1706-GE

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

Fraction
l
Fraction

Exponent

:A+2
16

ZK-4197-GE

The structure of a D_floating number is as follows:

7 6

15 14

Exponent

Fraction

:A+2

Fraction

:A+4

Fraction

:A+6
48
ZK-4198-GE

(continued on next page)

A-6

VMS Data Types
A.1 VMS Data Types

Table A-1 (Cont.)
Data Type

VMS Data Types
Definition
The structure of a G_floating number is as follows:

15 14

4 3

sJ Exponent I

Fraction

:A+2

Fraction

:A+4

Fraction

:A+6

48
ZK-4199-GE

The structure of an H_floating number is as follows:

15 14

127

Exponent

Fraction

:A+2

Fraction

:A+4

Fraction

:A+6

Fraction

:A+8

Fraction

:A+ 10

Fraction

: A+ 12

Fraction

: A+ 14
113
ZK-4196-GE

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.
(continued on next page)

A-7

VMS Data Types
A.1 VMS Data Types

Table A-1 (Cont.)
Data Type

VMS Data Types
Definition

The following figure illustrates the format of the information written in the IOSB for
SYS$QIO:

16 15

Count

Condition Value

Device-Dependent Information
ZK-0856-GE

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 1/0 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 1/0 completion and the integrity of data transfers, you should
check the IOSB following 1/0 requests, particularly for device-dependent 1/0 functions.
item_list_2

Structure that consists of one or more item descriptors and 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:

Item Code

Component Length

Component Address
ZK-1709-GE

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 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.
item_list_3

Structure that consists of one or more item descriptors and is terminated by a longword
containing 0. Each item descriptor is a 3-longword structure that contains four fields.
(continued on next page)

A-8

VMS Data Types
A.1 VMS Data Types

Table A-1 (Cont.)
Data Type

VMS Data Types
Definition

The following diagram depicts the format of a single item descriptor:

Item Code

Buffer Length

Buffer Address
Return Length Address
ZK-1705-GE

The first field is a word containing a user-supplied 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 user-supplied symbolic code specifying the
item of information that the service is to return. These codes are defined by macros
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.
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 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.

lock_id

Unsigned longword integer denoting a lock identifier. This lock identifier is assigned to
a lock by the lock manager facility 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
by Digital. The second longword also contains the lock identifier.
The lock status block receives the final condition value plus 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).
(continued on next page)

A-9

VMS Data Types
A.1 VMS Data Types

Table A-1 (Cont.)
Data Type

VMS Data Types
Definition
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
(Used only when LCK$M_VALBLK is set.)
ZK-0376-GE

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.

logical_name

Character string 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

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

longword_unsigned

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 as a bit mask.

null_arg

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

octaword_signed

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

octaword_unsigned

Is the same as the data type octaword (unsigned) in Table 1-3.
(continued on next page)

A-10

VMS Data Types
A.1 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. If you specify
the protection as 0, the protection defaults to kernel read only.
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

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 identification (PIO). This process
identification is assigned to a process by VMS when the process is created.

process_name

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

quadword_signed

Is the same as the data type quadword integer (signed) in 1-3.

quadword_unsigned

Is the same as the data type quadword (unsigned) in 1-3.

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-GE

{continued on next page)

A-11

VMS Data Types
A.1 VMS Data Types

Table A-1 (Cont.)

VMS Data Types

Data Type

Definition

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
1000

Identifier
ID Format
ZK-1906-GE

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.
An identifier name consists of 1 to 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 O through 9. Any lowercase characters
are automatically converted to uppercase.
rab

Structure denoting an RMS record access block.

section_id

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 to be associated with a
rights database.

transaction_id

Unsigned octaword that denotes a unique transaction identifier.

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:
(continued on next page)

A-12

VMS Data Types
A.1 VMS Data Types

Table A-1 (Cont.)

VMS Data Types

Data Type

Definition

Group

Member

UIC Format
ZK-1905-GE

A.2

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.

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

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

word_unsigned

Is the same as the data type word (unsigned) in Table 1-3.

VAX Ada Implementation
Table A-2 lists the 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

STARLE~ACCESS_MODE_TYPE

address

SYSTEM.ADDRESS

address_range

STARLE~ADDRESS_RANGE_TYPE

arg_list

STARLET.ARG_LIST_TYPE

ast_procedure

SYSTEM.AST_HANDLER
(continued on next page)

A-13

VMS Data Types
A.2 VAX Ada Implementation

Table A-2 (Cont.)

VAX Ada Implementation

VMS Data Structure

VAX Ada Declaration

boolean

STANDARD.BOOLEAN

byte_signed

STANDARD.SHORT_SHORT_INTEGER

byte_unsigned

SYSTEM.UNSIGNED_BYTE

channel

STARLET. CHANNEL_TYPE

char_string

STANDARD.STRING

complex_number

User-defined record

cond_value

CONDITION_HANDLING.COND_VALUE_TYPE

context

STARLET.CONTEXT_TYPE

date_time

STARLET.DATE_TIME_TYPE

device_name

STARLET.DEVICE_NAME_TYPE

et_cluster_name

STARLET.EF_CLUSTER_NAME_TYPE

ef_number

STARLET.EF_NUMBER_TYPE

exit_handler_block

STARLET. EXIT_HANDLER_BLOCK_TYPE

fab

STARLET.FAS_TYPE

file_protection

STARLET.FILE_PROTECTION_TYPE

floating_point

STANDARD.FLOAT
STANDARD.LONG_FLOAT
STANDARD.LONG_LONG_FLOAT
SYSTEM.F_FLOAT
SYSTEM.D_FLOAT
SYSTEM.G_FLOAT
SYSTEM.H_FLOAT

function_code

STARLET. FUNCTION_CODE_TYPE

identifier

SYSTEM.UNSIGNED_LONGWORD

io_status_block

STARLET.IOSB_TYPE

item_list_pair

SYSTEM.UNSIGNED_LONGWORD

item_list_2

STARLET. ITEM_LIST_2_TYPE

item_list_3

STARLET. ITEM_LIST_TYPE

item_quota_list

User-defined record

lock_id

STARLET. LOCK_ID_TYPE

lock_status_block

STARLET.LOCK_STATUS_BLOCK_TYPE

lock_value_block

STARLET.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
(continued on next page)

A-14

VMS Data Types
A.2 VAX Ada Implementation

Table A-2 (Cont.)

A.3

VAX Ada Implementation

VMS Data Structure

VAX Ada Declaration

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

STARLE~PROCESS_NAME_TYPE

quadword_signed

SYSTEM.UNSIGNED_QUADWORD

quadword_unsigned

SYSTEM.UNSIGNED_QUADWORD

rights_holder

STARLET.RIGHTS_HOLDER_TYPE

rights_id

STARLET.RIGHTS_ID_TYPE

rab

STARLET. RAB_TYPE

section_id

STARLET.SECTION_ID_TYPE

section_name

STARLET.SECTION_NAME_TYPE

system_access_id

STARLET.SYSTEM_ACCESS_ID_TYPE

time_name

STARLET.TIME_NAME_TYPE

transaction_id

array(1 ..4) of SYSTEM.UNSIGNED_LONGWORD

uic

STARLET.UIC_TYPE

user_arg

STARLE~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

STANDARD.SHORT_INTEGER

word_unsigned

SYSTEM.UNSIGNED_WORD

VAX APL Implementation
Table A-3 lists the VMS data types and their corresponding VAX APL
data-type declarations.

A-15

VMS Data Types
A.3 VAX APL Implementation

Table A-3

VAX APL Implementation

VMS Data Type

VAX APL Declaration

access_bit_names

access_mode

/TYPE= BU

address

ast_proced ure

NA
NA
NA
NA

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

NA
NA

address_range
arg_list

device_name

/TYPE=T

ef_cluster_name

/TYPE=T

ef_number

/TYPE= LU

exit_handler_block
fab

NA
NA

file_protection

/TYPE= WU

floating_point

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

function_code

item_quota_list

NA
NA
NA
NA
NA
NA
NA

lock_id

/TYPE= LU

lock_status_block

NA
NA

identifier
io_status_block
item_list_2
item_list_3
item_list_pair

lock_value_block

(continued on next page)

A-16

VMS Data Types
A.3 VAX APL Implementation

Table A-3 (Cont.)

VAX APL Implementation

VMS Data Type

VAX APL Declaration

logical_name

/TYPE=T

longword_signed

/TYPE=L

longword_unsigned

/TYPE= LU

mask_byte

/TYPE=BU

mask_longword

/TYPE= LU

mask_quadword

mask_word

/TYPE=WU

null_arg

/TYPE= LU

octaword_signed
octaword_unsigned

NA
NA

page_protection

/TYPE= LU

procedure

process_id

/TYPE= LU

process_name

/TYPE=T

quadword_signed
rights_holder

NA
NA
NA

rights_id

/TYPE= LU

rab

quadword_unsigned

section_id

NA
NA

section_name

/TYPE=T

system_access_id

time_name

/TYPE=T

transaction_id

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

NA
NA

vector_word_signed

/TYPE=W
(continued on next page)

A-17

VMS Data Types
A.3 VAX APL Implementation

Table A-3 (Cont.)
VMS Data Type

A.4

VAX APL Implementation
VAX APL Declaration

vector_word_unsigned

/TYPE= WU

word_signed

/TYPE=W

word_unsigned

/TYPE= WU

VAX BASIC Implementation
Table A-4 lists the VMS data types and their corresponding VAX BASIC
data-type declarations.
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

BYTE 1

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

1 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.
(continued on next page)

A-18

VMS Data Types
A.4 VAX BASIC Implementation

Table A-4 (Cont.)

VAX BASIC Implementation

VMS Data Type

VAX BASIC Declaration

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

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
(continued on next page)

A-19

VMS Data Types
A.4 VAX BASIC Implementation

Table A-4 (Cont.)

VAX BASIC Implementation

VMS Data Type

VAX BASIC Declaration

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

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

LONG 1

mask_byte

BYTE

mask_longword

LONG

1 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.

(continued on next page)

A-20

VMS Data Types
A.4 VAX BASIC Implementation

Table A-4 (Cont.)

VAX BASIC Implementation

VMS Data Type

VAX BASIC Declaration

mask_quadword

RECORD quadword
LONG FILL ( 2)
END RECORD 1

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 RECORD 1

rights_holder

RECORD quadword
LONG FILL ( 2)
END RECORD 1

rights_id

LONG

rab

section_id

RECORD quadword
LONG FILL ( 2)
END RECORD 1

section_name

STRING

system_access_id

RECORD quadword
LONG FILL ( 2)
END RECORD 1

time_name

STRING

transaction_id

uic

LONG

user_arg

LONG

varying_arg

Dependent upon application.

vector_byte_signed

BYTE array ( n )

vector_byte_unsigned

BYTE array ( n )1

vector_longword_signed

LONG array ( n )

1 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.

(continued on next page)

A-21

VMS Data Types
A.4 VAX BASIC Implementation

Table A-4 (Cont.)

VAX BASIC Implementation

VMS Data Type

VAX BASIC Declaration

vector_longword_unsigned

LONG array ( n ) 1

vector_quadword_signed
vector_quadword_unsigned

NA
NA

vector_word_signed

WORD array ( n)

vector_word_unsigned

WORD array ( n) 1

word_signed

WORD

word_unsigned

WORD 1

1 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
Table A-5 lists the VMS data types and their corresponding VAX BLISS
data-type declarations.
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]
(continued on next page)

A-22

VMS Data Types
A.5 VAX BLISS Implementation

Table A-5 (Cont.)

VAX BLISS Implementation

VMS Data Type

VAX BLISS Declaration

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.
$1TMLST_DECU$1TMLST_INIT
from STARLET.REQ

item_list_pair

BLOCKVECTOR[n,2,LONG]
where n is the number of the item descriptors

+ 1.
item_quota_list

BLOCKVECTOR[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_status_block minus at least 8.

lock_value_block

BLOCK[16,BYTE]

logical_name

VECTOR[255,BYTE,UNSIGNED]

longword_signed

SIGNED LONG

longword_unsigned

UNSIGNED LONG

mask_byte

BITVECTOR[8]
(continued on next page)

A-23

VMS Data Types
A.5 VAX BLISS Implementation

Table A-5 (Cont.)

VAX BLISS Implementation

VMS Data Type

VAX BLISS Declaration

mask_longword

BITVECTOR[32]

mask_quadword

BITVECTOR[64]

mask_word

BITVECTOR[16]

null_arg

UNSIGNED LONG

octaword_signed

VECTOR[4,LONG,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

VECTOR[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.

transaction_id

VECTOR[4,LONG,UNSIGNED]

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.
(continued on next page)

A-24

VMS Data Types
A.5 VAX BLISS Implementation

Table A-5 (Cont.)

A.6

VAX BLISS Implementation

VMS Data Type

VAX BLISS Declaration

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
Table A-6 lists the 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-defined 1

access_mode

unsigned char

address

int *pointer2•4

address_range

int *array [2] 2 •3 •4

arg_list

User-defined 1

ast_procedure

Pointer to function 2

boolean

unsigned long int

byte_signed

char

byte_unsigned

unsigned char

channel

unsigned short int

char_string

char array[n] 3 •5

complex_number

User-defined 1

The 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.
3 The term array denotes the syntax of a VAX C array declaration.
4

The data type specified can be changed to any valid VAX C data type.

5 The size of the array must be substituted for n.

(continued on next page)

A-25

VMS Data Types
A.6 VAX C Implementation

Table A-6 (Cont.)

VAX C Implementation

VMS Data Type

VAX C Declaration

cond_value

unsigned long int

context

unsigned long int

date_time

User-defined 1

device_name

char array[n] 3 •5

ef_cluster_name

char array[n] 3 •5

ef_number

unsigned long int

exit_handler_block

User-defined 1

fab

#include fab from text library
struct FAB

file_protection

unsigned short int or user-defined 1

floating_point

float or double

function_code

unsigned long int or user-defined 1

identifier

int *pointer2•4

io_status_block

User-defined 1

item_list_2

User-defined 1

item_list_3

User-defined 1

item_list_pair

User-defined 1

item_quota_list

User-defined 1

lock_id

unsigned long int

lock_status_block

User-defined 1

lock_value_block

User-defined 1

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

mask_quadword

User-defined 1

mask_word

unsigned short int

null_arg

unsigned long int

octaword_signed

User-defined 1

octaword_unsigned

User-defined 1

1The 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 suitable only to specific applications.
2 The 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.

3 The term array denotes the syntax of a VAX C array declaration.
4 The data type specified can be changed to any valid VAX C data type.

5 The size of the array must be substituted for n.

(continued on next page)

A-26

VMS Data Types
A.6 VAX C Implementation

Table A-6 (Cont.)

VAX C Implementation

VMS Data Type

VAX C Declaration

page_protection

unsigned long int

procedure

Pointer to function 2

process_id

unsigned long int

process_name

char array[n] 3 •5

quadword_signed

User-defined 1

quadword_unsigned

User-defined 1

rights_holder

User-defined 1

rights_id

unsigned long int

rab

#include rab from text library
struct RAB

section_id

User-defined 1

section_name

char array[n] 3 •5

system_access_id

User-defined 1

time_name

char array[n] 3 •5

transaction_id

User-defined 1

uic

unsigned long int

user_arg

User-defined 1

varying_arg

User-defined 1

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-defined 1

vector_quadword_unsigned

User-defined 1

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

2 The 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.
3 The term array denotes the syntax of a VAX C array declaration.
5 The size of the array must be substituted for n.

A-27

VMS Data Types
A.7 VAX COBOL Implementation

A.7

VAX COBOL Implementation
Table A-7 lists the 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 ... PIG X(128) 2

access_mode

NA ... PIG X2
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 cannot be referenced
by the COBOL CALL statement.
01 ARG-LIST
02 ARG-COUNT PIG S9(5) COMP
02 ARG-BY-VALUE PIG S9(5) COMP
02 ARG-BY-REFERENCE USAGE PQINTER
02 VALUE REFERENCE ARG-NAME
... continue as needed

ast_procedure

01 AST-PROC PIG 9(5) COMP 1

boolean

01 BOOLEAN-VALUE PIG 9(5) COMP 1

byte_signed

NA ... PIG X2

byte_unsigned

NA ... PIG X2

channel

01 CHANNEL PIG 9(4) COMP 1

char_string

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

complex_number

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

cond_value

01 COND-VALUE PIG 9(5) COMP 1

context

01 CONTEXT PIG 9(5) COMP 1

date_time

NA ... PIG X(16) 2

device_name

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

ef_cluster_name

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

ef_number

01 EF-NO PIG 9(5) COMP 1

1 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.
2 Most 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.
(continued on next page)

A-28

VMS Data Types
A.7 VAX COBOL Implementation

Table A-7 (Cont.)

VAX COBOL Implementation

VMS Data Type

VAX COBOL Declaration

exit_handler_block

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

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 IOSB
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

1 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.
2 Most 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.

(continued on next page)

A-29

VMS Data Types
A.7 VAX COBOL Implementation

Table A-7 (Cont.)

VAX COBOL Implementation

VMS Data Type

VAX COBOL Declaration

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

longword_unsigned

01 LWU PIC 9( 5) COMP 1

mask_byte

NA ... PIC X2

mask_longword

01 MLW PIC 9( 5) COMP 1

mask_quadword

01 MQW 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 PIO PIC 9( 5) COMP 1

process_name

01 PROCESS-NAME PIC X TO X(15)

quadword_signed

01 aws 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

1 Although unsigned computational data structures are not directly supported in VAX COBOL,

(continued on next page)

A-30

VMS Data Types
A.7 VAX COBOL Implementation

Table A-7 (Cont.)

VAX COBOL Implementation

VMS Data Type

VAX COBOL Declaration

time_name

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

transaction_id

uic

01 UIC PIG 9( 5) COMP 1

user_arg

01 USER-ARG PIG 9( 5) COMP 1

varying_arg

Dependent upon application

vector_byte_signed

NA ... 3

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 PIG 9( 4) COMP 1

1 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.

3 VAX COBOL does not permit the passing of variable-length data structures.

A.8

VAX FORTRAN Implementation
Table A-8 lists the 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
(continued on next page)

A-31

VMS Data Types
A.8 VAX FORTRAN Implementation

Table A-8 (Cont.)

VAX FORTRAN Implementation

VMS Data Type

VAX FORTRAN Declaration

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

byte_unsigned

BYTE 1

channel

INTEGER*2

char_string

CHARACTER*n

complex_number

COMPLEX*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 !cntrlblk
RECORD /exhblock/ myexh_block
fab

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

file_protection

INTEGER*4

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

(continued on next page)

A-32

VMS Data Types
A.8 VAX FORTRAN Implementation

Table A-8 (Cont.)

VAX FORTRAN Implementation

VMS Data Type

VAX FORTRAN Declaration

floating_point

REAL*4
REAL*8
DOUBLE PRECISION
REAL*16

function_code

INTEGER*4

identifier

INTEGER*4

io_status_block

STRUCTURE liosbl
INTEGER*2 iostat, !return status
2 term_offset, !loc. of line terminator
2 terminator, !value of terminator
2 term_size !size of terminator
END STRUCTURE
RECORD liosbl my_iosb

item_list_2

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

item_list_3

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

A-33

VMS Data Types
A.8 VAX FORTRAN Implementation

Table A-8 (Cont.)

VAX FORTRAN Implementation

VMS Data Type

VAX FORTRAN Declaration

item_list_pair

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

item_quota_list

STRUCTURE litem_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

STRUCTUREllksbl
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

CHARACTER*n

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(O)

octaword_signed

INTEGER*4( 4)

1 Unsigned data types are not directly supported by VAX FORTRAN. However, in most cases

you can substitute the signed equivalent as long as you do not exceed the range of the signed
data structure.
(continued on next page)

A-34

VMS Data Types
A.8 VAX FORTRAN Implementation

Table A-8 (Cont.)

VAX FORTRAN Implementation

VMS Data Type

VAX FORTRAN Declaration

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

section_id

INTEGER*4( 2)

section_name

CHARACTER*n

system_access_id

INTEGER*4(2)

time_name

CHARACTER*23

transaction_id

INTEGER*4( 4 ) 1

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

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

A-35

VMS Data Types
A.9 VAX MACRO Implementation

A.9

VAX MACRO Implementation
Table A-9 lists the 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_tor_bitO/
.ASCID /name_tor_bit1/ ...
.ASCID /name_tor_bit31/

access_mode

.BYTE PSL$C_xxxx

address

.ADDRESSS virtual_address

address_range

.ADD RESS start_address,end_address

arg_list

.LONG n_args, arg1, arg2, ...

ast_procedure

.ADDRESS ast_procedure

boolean

.LONG 1 or .LONG 0

byte_signed

.SIGNED_BYTE byte_value

byte_unsigned

.BYTE byte_value

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:/

et_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

tab

MYFAB: $FAB

file_protection

.WORD prot_value

f loati ng_poi nt

.FLOAT, .G_FLOAT, or .H_FLOAT

function_code

.LONG code!mask

identifier

.ADDRESSS virtual_address

io_status_block

.QUAD 0

item_list_2

.WORD component_length
.WORD item_code
.ADDRESS component_address
(continued on next page)

A-36

VMS Data Types
A.9 VAX MACRO Implementation

Table A-9 (Cont.)

VAX MACRO Implementation

VMS Data Type

VAX MACRO Declaration

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$_1istend

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

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_rights_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/

transaction_id

.OCTA value

uic

.LONG uic

user_arg

.LONG data
(continued on next page)

A-37

VMS Data Types
A.9 VAX MACRO Implementation

Table A-9 (Cont.)

A.10

VAX MACRO Implementation

VMS Data Type

VAX MACRO Declaration

varying_arg

Dependent upon application

vector_byte_signed

.SIGNED_BYTE val1,val2, ... valN

vector_byte_unsigned

.BYTE val1,val2, ... valN

vector_longword_signed

.LONG val1,val2, ... valN

vector_longword_unsigned

.LONG val1,val2, ... valN

vector_quadword_signed

vector_quadword_unsigned

.QUAD val1, val2, ... valN

vector_word_signed

.SIGNED_WORD val1,val2, ... valN

vector_word_unsigned

.WORO val1,val2, ... valN

word_signed

.SIGNED_WORD value

word_unsigned

.WORD value

VAX Pascal Implementation
Table A-10 lists the VMS data types and their corresponding VAX Pascal
data-type declarations.
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

1
This type is not available in VAX Pascal when 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.

3 VAX Pascal allocates a byte for a BOOLEAN variable. Use the [LONG] attribute when passing to routines that expect a

longword.
4 This parameter declaration accepts VARYING OF CHAR or PACKED ARRAY OF CHAR and produces the CLASS_S descriptor

required by system services.
6

VAX 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.
(continued on next page)

A-38

VMS Data Types
A.10 VAX Pascal Implementation

Table A-10 (Cont.)

VAX Pascal Implementation

VMS Data Type

VAX Pascal Declaration

complex_number

[LONG(2)] RECORD END;* F_Floating Complex *1•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

FAB$TYPE;5

file_protection

[WORD] RECORD END; 1 •6

floating_point

REAL; { F_Floating }
SINGLE; { F_Floating }
DOUBLE; { D_Floating/G_Floating }2
QUADRUPLE; { H_Floating }

function_code

UNSIGNED;

identifier

UNSIGNED;

io_status_block

[QUAD] RECORD END; 1 •6

item_list_2

PACKED ARRAY [1 .. n] OF PACKED RECORD 6
CASE INTEGER OF

1: (
FIELD1 : [WORD] 0.. 65535;
FIELD2 : [WORD] 0 .. 65535;
FIELD3 : UNSIGNED);

2: (
TERMINATOR : UNSIGNED);
END;
1 This type is not available in VAX Pascal when 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.
2 1f 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.
4 This parameter declaration accepts VARYING OF CHAR or PACKED ARRAY OF CHAR and produces the CLASS_S descriptor

required by system services.
5 The program must inherit the STARLET environment file located in SYS$LIBRARY:STARLET.PEN.
6 VAX 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.
(continued on next page)

A-39

VMS Data Types
A.10 VAX Pascal Implementation

Table A-10 (Cont.)

VAX Pascal Implementation

VMS Data Type

VAX Pascal Declaration

item_list_3

PACKED ARRAY [1 .. n] OF PACKED RECORD6
CASE INTEGER OF

1: (
FIELD1 : [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: (
FIELD1 : INTEGER;
FIELD2: INTEGER);

2: (
TERMINATOR : UNSIGNED);
END;
item_quota_list

PACKED ARRAY [1 .. n] OF PACKED RECORD 6
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

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

This parameter declaration accepts VARYING OF CHAR or PACKED ARRAY OF CHAR and produces the CLASS_S descriptor
required by system services.

6 VAX 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.
(continued on next page)

A-40

VMS Data Types
A.10 VAX Pascal Implementation

Table A-10 (Cont.)

VAX Pascal Implementation

VMS Data Type

VAX Pascal Declaration

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

RAB$TYPE; 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

transaction_id

[OCTA] RECORD END; 1 •6

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

1This type is not available in VAX Pascal when 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.
4 This parameter declaration accepts VARYING OF CHAR or PACKED ARRAY OF CHAR and produces the CLASS_S descriptor

required by system services.
5 The program must inherit the STARLET environment file located in SYS$LIBRARY:STARLET.PEN.
6 VAX 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-41

VMS Data Types
A.11 VAX PL/I Implementation

A.11

VAX PL/I Implementation
Table A-11 lists the VMS data types and their corresponding VAX PIA
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; 1
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
DSC$K_CLASS_S and DSC$K_DTYPE_T can
be used by including the module $DSCDEF from
PLl$STARLET.

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 $PSLDEF
in PL1$STARLET.)

address

POINTER

address_range

( 2) POINTER 1

arg_list

1 ARG_LIST BASED,
2 ARGCOUNT FIXED BINARY(31 ),
2 ARGUMENT (X REFER (ARGCOUNT})
POINTER; 1
If the arguments are passed by value, you may
need to change the type of the ARGUMENT
field of the structure. Alternatively, you can use
the POSINT, INT, or UNSPEC built-in functions
/pseudovariables to access the data. X should be
an expression with a value in the range O to 255
when the structure is allocated.

ast_procedure

PROCEDURE or ENTRY2

boolean

BIT ALIGNED 1

1 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.)
2 AST procedures and those passed as parameters of type ENTRY VALUE or ANY VALUE must

be external procedures. This applies to all system routines that take procedure parameters.
(continued on next page)

A-42

VMS Data Types
A.11 VAX PL/I Implementation

Table A-11 (Cont.) VAX PL/I Implementation
VMS Data Type

VAX PUI Declaration

byte_signed

FIXED BINARY( 7)

byte_unsigned

FIXED BINARY(7) 3

channel

FIXED BINARY(15)

char_string

CHARACTER( n )5

complex_number

( 2) FLOAT BINARY( n) (See floating_point for
values of n.)

cond_value

See STS$VALUE in module $STSDEF in
PLl$STARLET. 1

context

FIXED BINARY(31)

date_time

BIT(64) ALIGNED 4•6

device_name

CHARACTER( n )5

ef_cluster_name

CHARACTER( n )5

ef_number

FIXED BINARY(31)

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; 1
(Replace n with an expression that yields a
value between O and 255 when the structure is
allocated.)

fab

See module $FABDEF in PLl$STARLET.

file_protection

BIT(16) ALIGNED 1

3 This is actually an unsigned integer. This declaration is interpreted as a signed number; use

the POSINT function to determine the actual value.
4 VAX PUI does not support FIXED BINARY numbers with precisions greater than 31.

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.
5 System 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(*).
6 Routines declared in PL1$STARLET often use ANY so you are free to declare the data structure

in the most convenient way for the application. ANY may be necessary in some cases because
PUI does not allow parameter declarations for some data types used by VMS. (In particular, PUI
parameters with arrays passed by reference cannot be declared to have nonconstant bounds.)
(continued on next page)

A-43

VMS Data Types
A.11 VAX PL/I Implementation

Table A-11 (Cont.)

VAX PL/I Implementation

VMS Data Type

VAX PL/I Declaration

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

io_status_block

Because there are different formats for 1/0 status
blocks for various system services, different
definitions are appropriate for different uses. Some
of the common formats are as follows:
/* See the VMS System Services Reference
Manual. *I
1 IOSB_SYS$GETSYI,
2 STATUS FIXED BINARY(31 },
2 RESERVED FIXED BINARY(31 );
/* See the VMS 110 User's Reference Manual:
Part I. *I
1 IOSB_TTDRIVER_A,
2 STATUS FIXED BINARY(15},
2 BYTE_COUNT FIXED BINARY(15},
2 MBZ FIXED BINARY(31) INITIAL( 0 );
/* See the VMS 110 User's Reference Manual:
Part I.*/
1 IOSB_TTDRIVER_B,
2 STATUS FIXED BINARY(15),
2 TRANSMIT_SPEED FIXED
BINARY(?},
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( 0 );
(continued on next page)

A-44

VMS Data Types
A.11 VAX PL/I Implementation

Table A-11 (Cont.)

VAX PL/I Implementation

VMS Data Type

VAX PUI Declaration

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); 1
(Replace SIZE with the number of items you
want.)

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( 0 ); 1
(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 ),
4 REAL FLOAT BINARY(24),
2 TERMINATOR FIXED BINARY(31)
INITIAL( 0 ); 1
(Replace SIZE with the number of items you
want.)

(continued on next page)

A-45

VMS Data Types
A.11 VAX PL/I Implementation

Table A-11 (Cont.)

VAX PL/I Implementation

VMS Data Type

VAX PUI Declaration

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); 1
(Replace SIZE with the number of quota entries
you want to use. The constant PQL$_LISTEND
can be used by including the module $PQLDEF
from PLl$STARLET or by declaring it GLOBALREF
FIXED BINARY(31) VALUE.)

lock_id

FIXED BINARY(31)

lock_status_block

1 LOCK_STATUS_BLOCK,
2 STATUS_CODE FIXED BINARY(15),
2 RESERVED FIXED BINARY(15),
2 LOCK_ID FIXED BINARY(31 ); 1

lock_value_block

The declaration of an item of this structure depends
on the use of the structure, because VMS does not
interpret the value. 1

logical_name

CHARACTER( n )5

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.

3 This is actually an unsigned integer. This declaration is interpreted as a signed number; use

the POSINT function to determine the actual value.
5 System 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 (*).
(continued on next page)

A-46

VMS Data Types
A.11 VAX PL/I Implementation

Table A-11 (Cont.) VAX PL/I Implementation
VMS Data Type

VAX PUI Declaration

octaword_signed

BIT(128) ALIGNED 4 •6

octaword_unsigned

BIT(128) ALIGNED 4 •6

page_protection

FIXED BINARY(31) (The constants for this type are
declared in module $PRTDEF in PLl$STARLET.)

procedure

PROCEDURE or ENTRY2

process_id

FIXED BINARY(31)

process_name

CHARACTER( n )5

quadword_signed

BIT(64) ALIGNED 4 •6

quadword_unsigned

BIT(64) ALIGNED 4 •6

rights_holder

1 RIGHTS_HOLDER,
2 RIGHTS_ID FIXED BINARY(31 ),
2 ACCESS_RIGHTS BIT(32)
ALIGNED; 1

rights_id

FIXED BINARY(31)

rab

See module $RABDEF in PLl$STARLET1

section_id

BIT(64) ALIGNED

section_name

CHARACTER(n) 5

system_access_id

BIT(64) ALIGNED

time_name

CHARACTER( n )5

transaction_id

BIT(128) ALIGNED 4 •6

uic

FIXED BINARY(31)

user_arg

ANY

varying_arg

ANY with OPTIONS(VARIABLE) on the routine
declaration or with OPTIONAL on the parameter
declaration.

1 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.)
2 AST procedures and those passed as parameters of type ENTRY VALUE or ANY VALUE must
be external procedures. This applies to all system routines that take procedure parameters.

4 VAX PUI does not support FIXED BINARY numbers with precisions greater than 31.

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.
5 System 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 (*).
6 Routines declared in PL1$STARLET often use ANY so you are free to declare the data structure

A-47

VMS Data Types
A.11 VAX PL/I Implementation

Table A-11 (Cont.)

VAX PL/I Implementation

VMS Data Type

VAX PL/I 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) ALIGNED 4 •6 •7

vector_quadword_unsigned

( n) BIT(64) ALIGNED 3 •4 •6 •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) 4

3 This is actually an unsigned integer.

This declaration is interpreted as a signed number; use
the POSINT function to determine the actual value.

VAX PUI does not support FIXED BINARY numbers with precisions greater than 31. 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.

6 Routines declared in PLl$STARLET often use ANY so you are free to declare the data structure
in the most convenient way for the application. ANY may be necessary in some cases because
PUI does not allow parameter declarations for some data types used by VMS. (In particular, PUI
parameters with arrays passed by reference cannot be declared to have nonconstant bounds.)
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 PLI$STARLET.TLB.
While the current version of VAX PUI does not support unsigned
fixed binary numbers or fixed binary numbers with a precision
greater than 31, future versions may support these features.
If VAX PUI is extended to support these types, declarations
in PLISTARLET may change to use the new data types where
appropriate.

A.12

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

A-48

VMS Data Types
A.12 VAX RPG II Implementation

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

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

cond_value 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. You cannot 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

item_list_2

DATA STRUCTURE

item_list_3

DATA STRUCTURE

1Technically, RPG II does not support unsigned data structures.

However, unsigned information
may be passed using the signed equivalent, provided the contents do not exceed the range of
the signed data structure.
(continued on next page)

A-49

VMS Data Types
A.12 VAX RPG II Implementation

Table A-12 (Cont.)

VAX RPG II Implementation

VMS Data Type

VAX RPG II Declaration

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
process_id

L1
L1
L1

process_name

TEXT STRING

quadword_signed
rights_holder

a
a1
a1

rights_id

rab

Implicitly generated by the compiler on your
behalf. You cannot access the rab data
structure from an RPG II program.

procedure

quadword_unsigned

section_id

section_name

TEXT STRING

system_access_id

time_name

TEXT STRING

transaction_id

DATA STRUCTURE

uic
user_arg

L1
L1

varying_arg

Dependent upon application

vector_byte_signed

ARRAY OF TEXT STRING

vector_byte_unsigned

ARRAY OF TEXT STRING 1

1 Technically, RPG II does not support unsigned data structures.

However, unsigned information
may be passed using the signed equivalent, provided the contents do not exceed the range of
the signed data structure.
(continued on next page)

A-50

VMS Data Types
A.12 VAX RPG II Implementation

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 W 1

word_signed

word_unsigned

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

A.13

VAX SCAN Implementation
Table A-13 lists the 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 )1

access_mode

FILL( 1 ) 1

address

POINTER

address_range

RECORD
start: POINTER,
end: POINTER,
END RECORD

arg_list

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

ast_procedure

POINTER

boolean

BOOLEAN 2

1 FILL is a data type that can always be used. A FILL is an object 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.
2 SCAN Boolean is just one byte.

(continued on next page)

A-51

VMS Data Types
A.13 VAX SCAN Implementation

Table A-13 (Cont.)

VAX SCAN Implementation

VMS Data Type

VAX SCAN Declaration

byte_signed

FILL( 1 )1

byte_unsigned

FILL( 1 )1

channel

FILL( 2 )1

char_string

FIXED STRING( x ) where x is length

complex_number

FILL( x) where xis length 1

cond_value

INTEGER

context

INTEGER

date_time

FILL( 8 )1

device_name

FIXED STRING( x ) where xis length

ef_cluster_name

FIXED STRING( x ) where x is length

ef_number

INTEGER

exit_handler_block

FILL( x ) where xis length 1

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 ) 1

floating_point

FILL( x ) where xis length 1

function_code

INTEGER

identifier

POINTER

io_status_block

FILL( 8 )1

item_list_2

RECORD
item1: FILL( 8 },
item2: FILL( 8 },
terminator: INTEGER,
END RECORD 1

item_list_3

RECORD
item1: FILL( 12 ),
item2: FILL( 12 ),
terminator: INTEGER,
END RECORD 1

1 FILL is a data type that can always be used. A FILL is an object between O 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.

(continued on next page)

A-52

VMS Data Types
A.13 VAX SCAN Implementation

Table A-13 (Cont.)

VAX SCAN Implementation

VMS Data Type

VAX SCAN Declaration

item_list_pair

RECORD
pair_ 1: RECORD ! 2 integer pair
long1: INTEGER,
long2: INTEGER,
END RECORD,
pair_2: RECORD ! integer-real pair
long1: INTEGER,
long2: FILL(4),
END RECORD,
! depending on need
terminator: INTEGER,
END RECORD

item_quota_list

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

lock_id

INTEGER

lock_status_block

RECORD
status: FILL( 2 ),
reserved: FILL( 2 ),
lock id: INTEGER,
END RECORD 1

lock_value_block

FILL( 16 ) 1

logical_name

FIXED STRING( x ) where x is length

longword_signed

INTEGER

longword_unsigned

INTEGER

mask_byte

FILL( 1 )1

mask_longword

INTEGER

mask_quadword

RECORD
first_half: INTEGER,
second_half: INTEGER,
END RECORD

mask_word

FILL( 2 )1

null_arg

Use asterisk (*) for argument.

(continued on next page)

A-53

VMS Data Types
A.13 VAX SCAN Implementation

Table A-13 (Cont.)

VAX SCAN Implementation

VMS Data Type

VAX SCAN Declaration

octaword_signed

FILL( 16 )1

octaword_unsigned

FILL( 16 )1

page_protection

INTEGER

procedure

POINTER

process_id

INTEGER

process_name

FIXED STRING( x ) where x is length

quadword_signed

FILL( 8 ) 1

quadword_unsigned

FILL( 8 ) 1

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 )1

section_name

FIXED STRING( x ) where x is length

system_access_id

FILL( 8 ) 1

time_name

FIXED STRING( x ) where xis length

transaction_id

FILL( 16 )1

uic

INTEGER

user_arg

INTEGER

varying_arg

INTEGER

vector_byte_signed

FILL( x ) where x is length 1

vector_byte_unsigned

FILL( x ) where x is length 1

vector_longword_signed

FILL( 4*x) where xis length 1

vector_longword_unsigned

FILL( 4*x) where xis length 1

vector_quadword_signed

FILL( 8*x ) where x is length 1

vector_quadword_unsigned

FILL( 8*x ) where x is. length 1

vector_word_signed

FILL( 2*x ) where x is length 1

vector_word_unsigned

FILL( 2*x ) where x is length 1

word_signed

FILL( 2 ) 1

word_unsigned

FILL( 2 ) 1

1 FILL is a data type that can always be used. A FILL is an object between O 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-54

Index

A
Access
file• A-St
page• A-10t
system object • A-11 t
Access entry • 1-9
Access method • 1-9
Access mode
processor • A-2
access_bit_names data type • A-2
access_mode data type • A-2
Ada data type declaration • A-13
Ada implementation table • A-13
Address
definition of • 2-3
address data type • A-2t
address_range data type • A-2t
APL data type declaration • A-1 S
APL Implementation table • A-1 S
Argument data type • 2-1 S
Argument list• 2-4
definition of • 2-3
evaluation • 2-6
format • 2-4
interpretating • 2-4
Arguments heading • 1-7
arg_list data type • A-2t
Array descriptor • 2-2S
ast_procedure data type• A-2t
Atomic data type • 2-15

B
BASIC data type declaration• A-18
BASIC implementation table • A-18
BLISS data type declaration • A-22
BLISS implementation table • A-22
boolean data type • A-2t
Boolean value flag • A-2t
byte_signed data type• A-2t

c
Calling sequence • 2-4
Calling standard • 2-1
C data type declaration • A-25
channel data type • A-2t
Character string• A-2t
char_string data type• A-2t
C implementation table • A-2S
COBOL data type declaration • A-28
COBOL implementation table • A-28
COBOL intermediate temporary data type • 2-20
complex_number data type • A-3t
Component • A-St
Condition handler • 1-12, 2-45
default • 2-S 1
deleting• 2-47
establishing • 2-46
exceptions • 1-12, 2-45
exit• A-St
memory
use of• 2-S1
multiple active signals• 2-S4
operations involving • 2-46
options • 2-4S
parameters and invocation • 2-49
properties of • 2-49
register values • 2-S3
request to unwind • 2-52
returning from • 2-S2
stack usage • 2-46
Condition handling
vector processor • 2-51
Condition Handling Standard • 2-44
Condition value • A-4t
definition of • 2-3
description of • 2-8
field
cntrl • 2-9
condition identification • 2-8
facility• 2-9
message number• 2-9
severity code • 2-9
interpreting severity codes • 2-10
registers
use of• 2-12

lndex-1

Index

Condition value (Cont.)
returned • 1-14
in 1/0 status block• 1-14
in mailbox• 1-14
in RO• 1-5
signaled in register• 1-7, 1-15
signaled• 1-7, 1-15
symbols for • 2-9
use of• 2-11
Condition values returned heading • 1-12
cond_value data type• A-4t
context data type • A-5t

D
Data type • 2-15
Ada declaration • A-13
APL declaration• A-15
atomic• 2-15
DSC$K_DTYPE_B•2-16
DSC$K_DTYPE_BU • 2-16
DSC$K_DTYPE_CIT • 2-17
DSC$K_DTYPE_D•2-16
DSC$K_DTYPE_DC•2-17
DSC$K_DTYPE_F•2-16
DSC$K_DTYPE_FC • 2-16
DSC$K_DTYPE_G•2-16
DSC$K_DTYPE_GC•2-17
DSC$K_DTYPE_H•2-16
DSC$K_DTYPE_HC•2-17
DSC$K_DTYPE_L•2-16
DSC$K_DTYPE_LU•2-16
DSC$K_DTYPE_0•2-16
DSC$K_DTYPE_OU•2-16
DSC$K_DTYPE_Q • 2-16
DSC$K_DTYPE_QU•2-16
DSC$K_DTYPE_W • 2-16
DSC$K_DTYPE_WU • 2-16
DSC$K_DTYPE_Z•2-16
BASIC declaration• A-18
BLISS declaration • A-22
C declaration • A-25
COBOL declaration • A-28
COBOL intermediate temporary • 2-20
code• 1-8
facility-specific • 2-19
reserved • 2-20
FORTRAN declaration • A-31
MACRO declaration • A-36
miscellaneous • 2-18

lndex-2

Data type
miscellaneous (Cont.)
DSC$K_DTYPE_ADT•2-19
DSC$K_DTYPE_BLV•2-19
DSC$K_DTYPE_BPV•2-19
DSC$K_DTYPE_DSC•2-19
DSC$K_DTYPE_ZEM • 2-19
DSC$K_DTYPE_ZI • 2-19
Pascal declaration • A-38
PUI declaration• A-42
RPG II declaration • A-48
SCAN declaration • A-51
string • 2-17
DSC$K_DTYPE_NL•2-18
DSC$K_DTYPE_NLO • 2-18
DSC$K_DTYPE_NR•2-18
DSC$K_DTYPE_NRO • 2-18
DSC$K_DTYPE_NU•2-18
DSC$K_DTYPE_NZ•2-18
DSC$K_DTYPE_P•2-18
DSC$K_DTYPE_T•2-17
DSC$K_DTYPE_V•2-18
DSC$K_DTYPE_VT• 2-17, 2-21
DSC$K_DTYPE_VU•2-18
varying character string• 2-21
DSC$K_DTYPE_VT•2-21
VAX standard • 1-8
VMS• A-1
access_bit_names • A-2
access_mode • A-2
address • A-2t
address_range • A-2t
arg_list • A-2t
ast_procedure • A-2t
boolean • A-2t
byte_signed • A-2t
channel • A-2t
char_string • A-2t
complex_number • A-3t
cond_value • A-4t
context • A-5t
date_time • A-5t
device_name • A-5t
ef_cluster_name • A-5t
ef_number • A-5t
exit_handler_block • A-5t
fab • A-5t
file_protection • A-5t
floating_point • A-6t
function_code • A-7t
identifier• A-7t

Index

Data type
VMS (Cont.)
io_status_block • A-7t
item_list_2 • A-Bt
item_list_3 • A-Bt
item_list_pair • A-9t
item_quota_list • A-9t
lock_id • A-9t
lock_status_block • A-9t
lock_value_block • A-10t
logical_name • A-1 Ot
longword_signed • A-1 Ot
longword_unsigned • A-1 Ot
mask_byte • A-1 Ot
mask_longword • A-1 Ot
mask_word • A-1 Ot
null_arg • A-1 Ot
octaword_signed • A-10t
octaword_unsigned • A-1 Ot
page_protection • A-1 Ot
procedure • A-11 t
process_id • A-11t
process_name • A-11t
quadword_signed • A-11t
quadword_unsigned • A-11 t
quad_longword • A-1 Ot
rab • A-12t
rights_holder• A-11 t
rights_id • A-12t
section_id • A-12t
section_name • A-12t
system_access_id • A-12t
time_name • A-12t
transaction_id • A-12t
uic • A-12t
user_arg • A-13t
varying_arg • A-13t
vector_byte_signed • A-13t
vector_byte_unsigned • A-13t
vector_longword_signed • A-13t
vector_longword_unsigned • A-13t
vector_quadword_signed • A-13t
vector_quadword_unsigned • A-13t
vector_word_signed • A-13t
vector_word_unsigned • A-13t
word_signed • A-13t
word_unsigned • A-13t
VMS Usage• 1-7
date_time data type• A-5t
Decimal string descriptor• 2-30
Default
condition handlers • 2-51

Descriptor
array• 2-25
class codes • 1-11
facility-specific • 2-43
reserved • 2-44
decimal string • 2-30
dynamic string • 2-24
fixed-length • 2-23
format• 2-21
DSC$A_POINTER • 2-23
DSC$B_CLASS • 2-23
DSC$B_DTYPE • 2-23
DSC$K_CLASS_A•2-25
DSC$K_CLASS_D•2-24
DSC$K_CLASS_J•2-29
DSC$K_CLASS_NCA • 2-31
DSC$K_CLASS_P•2-29
DSC$K_CLASS_S•2-23
DSC$K_CLASS_SB•2-41
DSC$K_CLASS_SD • 2-30
DSC$K_CLASS_UBA•2-38
DSC$K_CLASS_UBS•2-37
DSC$K_CLASS_UBSB•2-42
DSC$K_CLASS_V•2-25
DSC$K_CLASS_VS•2-34
DSC$K_CLASS_VSA•2-35
DSC$W_LENGTH • 2-23
prototype • 2-22
label• 2-29
noncontiguous array • 2-31
procedure • 2-29
string with bounds • 2-41
unaligned bit array • 2-38
unaligned bit string • 2-37
unaligned bit string with bounds • 2-42
variable buffer • 2-25
varying string • 2-34
varying string array • 2-35
device_name data type • A-5t
Documentation format
See System routine documentation
Dynamic string descriptor• 2-24

E
ef_cluster_name data type• A-5t
ef_number data type • A-5t
Entry mask procedure • A-11 t

lndex-3

Index

Event flag
cluster• A-St
number • A-St
Exception condition • 1-12, 2-3, 2-44
handler• 1-12, 2-4S
indicating occurrence of• 2-47
signaling an• 2-47
exit_handler_block data type• A-St
Explanatory text • 1-4, 1-11

F
fab data type • A-St
Facility-specific data type code • 2-19
Facility-specific descriptor class codes • 2-43
File access
protection• A-St
File access block • A-St
file_protection data type• A-St
Fixed-length descriptor • 2-23
Flag word • A-1 Ot
Floating-point number
O_floating complex • A-3t
D_floating standard• A-6t
F_floating complex• A-3t
F_floating standard• A-6t
G_floating complex • A-4t
G_floating standard• A-7t
H_floating standard• A-7t
floating_point data type• A-6t
Format heading • 1-2

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

I
1/0 channel
index• A-2t
1/0 status block (IOSB)

See also System routine documentation
FORTRAN data type declaration• A-31
FORTRAN implementation table • A-31
Function
definition of • 2-3
Function value • 2-7
registers • 2-12
Function value returned
in registers • 2-7
function_code data type • A-7t

See IOSB
Identifier
global section • A-12t
rights database • A-12t
user • A-11t, A-12t
identifier data type• A-7t
Immediate value • 2-3
Implementation table
VAX Ada• A-13
VAX APL• A-1S
VAX BASIC• A-1S
VAX BLISS • A-22
VAX C•A-2S
VAX COBOL• A-2S
VAX FORTRAN• A-31
VAX MACRO•A-36
VAX Pascal • A-3S
VAX PUI • A-42
VAX RPG II• A-4S
VAX SCAN• A-S1
VMS Usage • A-1
IOSB•A-7t
io_status_block data type• A-7t
item_list_2 data type • A-St
item_list_3 data type • A-St
item_list_pair data type• A-9t
item_quota_list data type • A-9t

Global section • A-12t

JSB call format • 1-4

lndex-4

Index

MACRO data type declaration• A-36
MACRO implementation table • A-36
Main headings• 1-1
mask_byte data type • A-1 Ot
mask_longword data type • A-1 Ot
mask_quadword data type • A-1 Ot
mask_word data type• A-10t
Mechanism entry• 1-10
Miscellaneous data type • 2-18
Multiple active signal • 2-54

Pascal data type declaration • A-38
Pascal implementation table • A-38
Passing mechanism• 1-1 O
descriptor
code· 1-11
definition of • 2-3
language extensions • 2-6
reference
definition of• 2-3
value
definition of • 2-3
Physical device name • A-St
PUI data type declaration • A-42
PUI implementation table • A-42
Procedure
definition of• 2-3
language support
definition of• 2-4
use of• 2-4
library
definition of• 2-4
use of• 2-4
operation • A-7t
Procedure call format • 1-3
procedure data type• A-11t
Procedure descriptor• 2-29
process_id data type • A-11 t
process_name data type • A-11 t
Properties of condition handler • 2-49
$PRTDEF macro• A-10t

Noncontiguous array descriptor• 2-31
null_arg data type• A-1 Ot

quadword_signed data type• A-11 t
quadword_unsigned data type• A-11t
Quota• A-9t

L
Label descriptor • 2-29
Language extension • 2-6
Language support procedure • 2-4
Library procedure • 2-4
Lock manager • A-9t
Lock values• A-9t
lock_id data type • A-9t
lock_status_block data type • A-9t
lock_value_block data type• A-1 Ot
logical_name data type • A-1 Ot
longword_signed data type • A-1 Ot
longword_unsigned data type• A-1 Ot

0
octaword_signed data type• A-1 Ot
octaword_unsigned data type• A-10t
Operation involving condition handler • 2-46

p
page_protection data type • A-1 Ot

R
rab data type • A-12t
Record access block • A-12t
Register
data• 1-6
for returns• 1-5, 1-15, 2-12
usage• 2-12
vector • 2-12
Request to unwind • 2-52

lndex-5

Index

Reserved data type code • 2-20
Reserved descriptor class code • 2-44
Return
1/0 status• A-7t
object• A-7t
Returning from condition handler• 2-52
Returns• 1-14
condition value • 2-8
function value• 2-7
in 1/0 status block • 1-14
in mailbox• 1-14
signaled in register • 1-15
Returns heading • 1-5
Revert to the caller's handling • 2-47
Rights identifier • A-12t
rights_holder data type • A-11 t
rights_id data type • A-12t
Routine name heading • 1-1
Routine overview heading• 1-1
RPG II data type declaration• A-48
RPG II implementation table • A-48

s
Scalar
processor synchronization • 2-13
SCAN data type declaration• A-51
SCAN implementation table• A-51
section_id data type • A-12t
section_name data type • A-12t
Severity code • 2-9
handling of• 2-1 O
interpreting • 2-1 O
meanings • 2-1 O
symbols • 2-1 O
Signaler's registers • 2-53
Signaling a condition • 2-47
Stack usage • 2-14, 2-45
String data type • 2-17
String with bounds descriptor • 2-41
Subroutine
definition of• 2-3
Sychronization
exception • 2-13
memory • 2-13
System routine documentation • 1-1
arguments heading• 1-7
access entry • 1-9
mechanism entry• 1-10

lndex-6

System routine documentation
arguments heading (Cont.)
text entry• 1-11
type entry• 1-8
VMS Usage entry• 1-7
condition values returned• 1-12
returns• 1-12, 1-14
returns in 1/0 status block • 1-14
returns in mailbox• 1-14
returns signaled • 1-15
description of • 1-1
format heading • 1-2
explanatory text • 1-4
JSB call format• 1-4
procedure call format• 1-3
main headings• 1-1
returns heading • 1-5
condition values • 1-5
reigister data • 1-6
routine name heading • 1-1
routine overview heading• 1-1
System routine template • 1-1
system_access_id data type • A-12t

T
Text entry
See Explanatory text
time_name data type • A-12t
transaction_id data type • A-12t
Type entry • 1-8

u
UIC • A-11t, A-12t
uic data type • A-12t
Unaligned bit array descriptor • 2-38
Unaligned bit string descriptor• 2-37
Unaligned bit string with bounds descriptor • 2-42
User identification code (U IC)
See UIC
user_arg data type• A-13t

v
Variable buffer descriptor • 2-25

Index

Varying character string data type• 2-21
Varying string array descriptor • 2-35
Varying string descriptor • 2-34
varying_arg data type • A-13t
VAX condition • 2-44
VAX Condition Handling Standard• 2-44
exception • 2-44
VAX data type • 1-8
VAX language extension • 2-6
VAX language implementation table
See Implementation table
VAX Procedure Calling Standard• 2-1
address • 2-3
argument list • 2-3
argument list format• 2-4
calling sequence • 2-4
argument list• 2-4
condition value • 2-3
severity code • 2-9
condition value format • 2-8
data type • 2-15
atomic• 2-15
COBOL intermediate temporary • 2-20
miscellaneous • 2-18
string• 2-17
descriptor • 2-3
descriptor formats• 2-21
exception condition • 2-3
for high-level languages • 2-6
function • 2-3
function value• 2-7
goals• 2-2
immediate value • 2-3
introduction • 2-1
language support procedures • 2-4
library procedures • 2-4
procedure • 2-3
reference • 2-3
registers • 2-12
stacks
use of• 2-14
subroutine • 2-3
VAX language extensions• 2-6
VAX scalar
See Scalar
VAX standard data type• 1-8
VAX vector
See Vector
Vector
processor synchronization• 2-13
register usage• 2-12

Vector processor
exception handling• 2-51
vector_byte_signed data type• A-13t
vector_byte_unsigned data type• A-13t
vector_longword_unsigned data type• A-13t
vector_lonword_signed data type• A-13t
vector_quadword_signed data type• A-13t
vector_quadword_unsigned data type• A-13t
vector_word_signed data type• A-13t
vector_word_unsigned data type• A-13t
VMS data type• 1-7, A-1
VMS Usage• 1-7, A-1
VMS Usage entry • 1-7
VMS Usage implementation table
See Implementation table

w
word_signed data type• A-13t
word_unsigned data type • A-13t

lndex-7

How to Order Additional Documentation

Technical Support
If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing
your electronic, telephone, or direct mail order.

Electronic Orders
To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a 1200- or 2400-baud
modem. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825).

Telephone and Direct Mail Orders
Your Location

Call

Contact

Continental USA,
Alaska, or Hawaii

800-DIGITAL

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

Puerto Rico

809-754-7575

Local Digital subsidiary

Canada

800-267-6215

Digital Equipment of Canada
Attn: DECdirect Operations KA02/2
P.O. Box 13000
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6

International
Internal1

Local Digital subsidiary or
approved distributor
USASSB Order Processing - WMO/El5
or
U.S. Area Software Supply Business
Digital Equipment Corporation
Westminster, Massachusetts 01473

1 For internal orders, you must submit an Internal Software Order Form (EN-01740-07).

Reader's Comments

Introduction to VMS
System Routines

AA-LA66B-TE

Please use this postage-paid form to comment on this manual. If you require a written reply to a software
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your
comments on an SPR form.
Thank you for your assistance.

I rate this manual's:
Accuracy (software works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

Good

Fair

Poor

D
D
D
D
D
D
D
D

I would like to see more/less

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

I am using Version ___ of the software this manual describes.

Name/Title

Dept.

Company

Date

Mailing Address
Phone

-- Do Not Tear - Fold Here and Tape ------------------~1111--------------
No Postage

~nmnama™

~:~=i~=~y
in the
United States

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

DIGIT AL EQUIPMENT CORPORATION
Corporate User Publications-Spit Brook
ZK01-3/J35 110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

Ill 11111 II 1 II1111 II 1111 I1 II1 Ifl 1.1 .. 1.. 1.1 ••• 1.11 •• 1
-- Do Not Tear - Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

I
I
I
I