Digital PDFs

AA-LA70A-TE

December 1988

87 pages

Original

3.1MB

Document:	Introduction to the VMS 5.0 Run-Time Library 198804
Order Number:	AA-LA70A-TE
Revision:
Pages:	87
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/5.0/AA-LA70A-TE_Introduction_to_the_VMS_5.0_Run-Time_Library_198804.pdf

OCR Text

VMS

Introduction to the VMS Run-Time Library

OrderNumberAA-LA70A-TE

Introduction to the VMS
Run-Time Library
Order Number: AA-LA 70A-TE

April 1988
This manual provides an overview of the VMS Run-Time Library.

Revision/Update Information:

This document supersedes
Sections 1 and 2 of the VAX/VMS
Run- Time Library Routines Reference
Manual, Version 4.4.

Software Version:

VMS Version 5.0

digital equipment corporation
maynard, massachusetts

April 1988
The information in this document is subject to change without notice and should
not be construed as a commitment by Digital Equipment Corporation. Digital
Equipment Corporation assumes no responsibility for any errors that may appear
in this document.
The software described in this document is furnished under a license and may be
used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment
that is not supplied by Digital Equipment Corporation or its affiliated companies.
Copyright © 1988 by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-10
DECSYSTEM-20
DEC US
DECwriter

DIBOL
EduSystem
IAS
MASSBUS
PDP
PDT
RSTS
RSX

UNIBUS
VAX
VAXcluster
VMS
VT

~D~DD5lD™
ZK4608

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

CANADA

INTERNATIONAL

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

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

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

In Continental USA and Puerto Rico call 800-258-1710.
In New Hampshire, Alaska, and Hawaii call 603-884-6660.
In Canada call 800-267-6215.
*Any prepaid order from Puerto Rico must be placed with the local Digital subsidiary (809-754-7575).
Internal orders should be placed through the Software Distribution Center (SOC), Digital Equipment
Corporation, Westminster, Massachusetts 01473.

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.

m;t

"""" PostScript is a trademark of Adobe Systems, Inc.

Contents
ix

PREFACE

CHAPTER 1 INTRODUCTION

1-1

1.1

ORGANIZATION OF THE RUN-TIME LIBRARY

1-1

1.2

FEATURES OF THE RUN-TIME LIBRARY

1-18

1.3

LINKING WITH THE RUN-TIME LIBRARY

1-19

CHAPTER 2 RUN-TIME LIBRARY DOCUMENTATION FORMAT

2-1

2.1

FORMAT HEADING

2-2

2.2
2.2.1
2.2.2

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

2-4
2-4
2-5

2.3
2.3.1
2.3.2
2.3.3
2.3.4
2.3.5

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

2-5
2-6
2-21
2-23
2-24
2-26

2.4
2.4.1
2.4.2

CONDITION VALUES RETURNED HEADING
Condition Values Returned
Condition Values Signaled

2-27
2-28
2-28

Contents

CHAPTER 3 HOW TO CALL RUN-TIME LIBRARY PROCEDURES

3-1

3.1

OVERVIEW

3-1

3.2

CALL FORMATS

3-2

3.3
3.3.1
3.3.2
3.3.3
3.3.4
3.3.5
3.3.5.1
3.3.5.2
3.3.5.3

RUN-TIME LIBRARY NAMING CONVENTIONS
Entry Point Names
JSB Entry Point Names
Function Return Values
Facility Return Status and Condition Value Symbols
Argument Passing Mechanisms
Passing Arguments by Value• 3-7
Passing Arguments by Reference • 3-7
Passing Arguments by Descriptor • 3-8

3-4
3-5
3-5
3-6
3-6
3-6

3.4

PASSING SCALARS AS ARGUMENTS

3-9

3.5

PASSING ARRAYS AS ARGUMENTS

3-10

3.6

PASSING STRINGS AS ARGUMENTS

3-10

3.7

COMBINATIONS OF DESCRIPTOR CLASS AND DATA TYPE

3-10

3.8

ERRORS FROM RUN-TIME LIBRARY ROUTINES

3-15

3.9
3.9.1
3.9.2
3.9.3
3.9.4
3.9.5
3.9.6

CALLING A LIBRARY PROCEDURE IN MACRO
MACRO Calling Sequence
CALLS Instruction Example
CALLG Instruction Example
JSB Entry Points
Return Status
Function Return Values in MACRO

3-15
3-15
3-16
3-17
3-17
3-18
3-19

3.10
3.10.1
3.10.2
3.10.3

CALLING A LIBRARY ROUTINE IN BLISS
BLISS Calling Sequence
Accessing a Return Status in BLISS
Calling JSB Entry Points from BLISS

3-20
3-20
3-21
3-21

Contents

INDEX

FIGURES
2-1
3-1

Routine Argument Passing Mechanisms
Calling the Run-Time Library

2-25
3-2

Run-Time Library Facilities
DTK$ Facility Routines
LI 8$ Facility Routines
MTH$ Facility Routines
OTS$ Facility Routines
PPL$ Facility Routines
SMG$ Facility Routines
STR$ Facility Routines
Main Headings in the Routine Template
VMS Data Structures
VAX Data Types
Passing Mechanisms
Atomic Data Types and Descriptor Classes
String Data Types and Descriptor Classes
Miscellaneous Data Types and Descriptor Classes

1-2
1-2
1-3
1-9
1-11
1-13
1-14
1-17
2-1
2-6
2-21
2-26
3-11
3-13
3-14

TABLES
1-1
1-2
1-3
1-4
1-5
1-6
1-7
1-8
2-1
2-2
2-3
2-4
3-1
3-2
3-3

vii

Preface
This manual provides users of the VMS operating system with an overview of
the capabilities and functions of the VMS Run-Time Library.
Run-Time Library routines can only be used in programs written in languages
that produce native code for the VAX hardware. At present, these languages
include VAX MACRO and the following compiled high-level languages:
VAX Ada
VAX BASIC
VAX BLISS-32
VAXC
VAX COBOL
VAX COBOL-7 4
VAX CORAL
VAX DIBOL
VAX FORTRAN
VAX Pascal
VAX PL/I
VAX RPG
VAX SCAN
Interpreted languages that can also access Run-Time Library routines include
VAX DSM and DATATRIEVE.

Intended Audience
This manual is intended for system and application programmers who want
to call Run-Time Library routines.

Document Structure
This manual is organized into three chapters as follows:
•

Chapter 1 gives an overview of the VMS Run-Time Library.

•

Chapter 2 discusses the documentation format used in the reference
section of the various Run-Time Library facility manuals.

•

Chapter 3 discusses the calling formats used to call Run-Time Library
routines.

Preface

Associated Documents
The Run-Time Library Routines are documented in a series of reference
manuals. This manual provides an overview of the Run-Time Library and a
description of how to access its routines. Descriptions of the individual RunTime Library facilities, along with reference sections describing the individual
routines in detail, can be found in the following books:
•

The VMS RTL DECtalk (DTK$) Manual

•

The VMS RTL Library (LIB$) Manual

•

The VMS RTL Mathematics (MTH$) Manual

•

The VMS RTL General Purpose (OTS$) Manual

•

The VMS RTL Parallel Processing (PPL$) Manual

•

The VMS RTL Screen Management (SMG$) Manual

•

The VMS RTL String Manipulation (STR$) Manual

The VAX Procedure Calling and Condition Handling Standard, which is
documented in the Introduction to VMS System Routines, contains useful
information for anyone who wants to call Run-Time Library routines.
Applications programmers in any language may wish to refer to the Guide to
Creating VMS Modular Procedures for the Modular Programming Standard and
other guidelines.
VAX MACRO programmers will find additional information on calling RunTime Library routines in the VAX MACRO and Instruction Set Reference
Manual.
High-level language programmers will find additional information on calling
Run-Time Library routines in the language reference manual. Additional
information may also be found in the language user's guide provided with
your VAX language documentation.
The Guide to Using VMS Command Procedures may also be useful.
For a complete list and description of the manuals in the VMS document set,
see the Overview of VMS Documentation.

Preface

Conventions
Convention

Meaning
In examples, a key name (usually abbreviated)
shown within a box indicates that you press
a key on the keyboard; in text, a key name is
not enclosed in a box. In this example, the key
is the RETURN key. (Note that the RETURN
key is not usually shown in syntax statements
or in all examples; however, assume that you
must press the RETURN key after entering a
command or responding to a prompt.)

CTRL/C

A key combination, shown in uppercase with a
slash separating two key names, indicates that
you hold down the first key while you press the
second key. For example, the key combination
CTRL/C indicates that you hold down the key
labeled CTRL while you press the key labeled C.
In examples, a key combination is enclosed in a
box.

$SHOW TIME
05-JUN-1988 11 :55:22

In examples, system output (what the system
displays) is shown in black. User input (what
you enter) is shown in red.

$ TYPE MYFILE.DAT

In examples, a vertical series of periods, or
ellipsis, means either that not all the data that
the system would display in response to a
command is shown or that not all the data a
user would enter is shown.

input-file, ...

In examples, a horizontal ellipsis indicates
that additional parameters, values, or other
information can be entered, that preceding
items can be repeated one or more times, or
that optional arguments in a statement have
been omitted.

[logical-name]

Brackets indicate that the enclosed item is
optional. (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.)

quotation marks
apostrophes

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

Introduction

The VMS Common Run-Time Procedure Library (or simply the Run-Time
Library) is a library of prewritten, commonly-used routines that perform a
wide variety of operations. These Run-Time Library routines follow the VAX
Procedure Calling and Condition Handling Standard and the VMS Modular
Programming Standard; hence they are part of the Common Run-Time
environment. The Common Run-Time environment lets a program contain
routines written in different languages, so that you can call Run-Time Library
routines from any VAX language, thus increasing program flexibility.
In this manual, a routine is a closed, ordered set of instructions that performs
one or more specific tasks. Every routine has an entry point (the routine
name), and optionally an argument list. Procedures and functions are specific
types of routines: a procedure is a routine that does not return a value,
whereas a function is a routine that returns a value by assigning that value to
the function's identifier.

1.1

Organization of the Run-Time Library
The routines of the VMS Run-Time Library are grouped according to the
types of tasks they perform; these groups are referred to as facilities. Each
group or facility has an associated prefix that is used in the routine name
to identify that routine as a member of a particular facility. Table 1-1 lists
all the Run-Time Library facility prefixes and the types of tasks each facility
performs.

1-1

Introduction
1 .1 Organization of the Run-Time Library

Table 1-1

Run-Time Library Facilities

Facility Prefix

Types of Tasks Performed

DTK$

DECtalk routines that are used to control DIGIT AL' s
DECtalk device

LIB$

Library routines that obtain records from devices,
manipulate strings, convert data types for 1/0,
allocate resources, obtain system information, signal
exceptions, establish condition handlers, enable
detection of hardware exceptions, and process
cross-reference data

MTH$

Mathematics routines that perform arithmetic,
algebraic, and trigonometric calculations

OTS$

General purpose routines that perform tasks such
as data type conversions as part of a compiler's
generated code, and also some mathematical
functions

PPL$

Parallel processing routines that simplify subprocess
creation, interprocess communication, and resource
sharing for parallel applications

SMG$

Screen management routines that are used in
designing, composing, and keeping track of complex
images on a video screen

STR$

String manipulation routines that perform such tasks
as searching for substrings, concatenating strings,
and prefixing and appending strings

The following tables list all the routines available for each of the
aforementioned facilities, as well as a brief statement of the routine's
function. Table 1-2 lists all the DTK$ facility routines that are used to
operate DIGITAL's DECtalk device. For more detailed information on these
routines, or on the DTK$ facility in general, refer to the VMS RTL DECtalk
(DTK$) Manual.
Table 1-2

1-2

DTK$ Facility Routines

Routine Name

Function

DTK$ANS\NER_PHONE

\Nait for the phone to ring and
answer

DTK$CHECK_HD\NR_STATUS

Check the hardware status

DTK$DIAL _PHONE

Dial the telephone

DTK$HANGUP_PHONE

Hang up the phone

DTK$1NITIALIZE

Initialize the DECtalk device

DTK$LOAD_DICTIONARY

Load a word into the DECtalk
dictionary

DTK$READ_KEYSTROKE

Read a key entered on the phone
keypad

Introduction
1 .1 Organization of the Run-Time Library

Table 1-2 (Cont.)

DTK$ Facility Routines

Routine Name

Function

DTK$READ_STRING

Read a series of keys entered on the
phone keypad

DTK$RETURN _LAST_INDEX

Return the last index spoken

DTK$SET_INDEX

Insert an index at the current position

DTK$SET_KEYP AD_MODE

Turn the phone keypad on and off

DTK$SET_LQGGING_MODE

Set the specified logging mode on
the DECtalk terminal

DTK$SET_MQDE

Set the specified mode on the
DECtalk terminal

DTK$SET_SPEECH _MQDE

Turn the speech on and off

DTK$SET_ TERMINAL_MQDE

Set the specified terminal mode on
the DECtalk terminal

DTK$SET_VOICE

Set the voice characteristics

DTK$SPEAK_FILE

Speak text from the specified file

DTK$SPEAK_PHONEMIC_TEXT

Speak the specified phonemic text

DTK$SPEAK_TEXT

Speak the specified text

DTK$SPELL_TEXT

Spell out the specified text

DTK$TERMINA TE

Terminate the DECtalk device

Table 1-3 lists all of the LIB$ facility routines. For more detailed information
on these routines, or on the LIB$ facility in general, refer to the VMS RTL
Library (LIB$) Manual.

Table 1-3

LIBS Facility Routines

Routine Name

Function

LIB$ADAWI

Add adjacent word with interlock

LIB$ADD_TIMES

Add two quadword times

LIB$ADDX

Add two multiple-precision binary
numbers

LIB$ANAL YZE_SDESC

Analyze a string descriptor

LIB$ASN_WTH_MBX

Assign a channel to a mailbox

LIB$AST_IN_PROG

AST in progress

LIB$ATTACH

Attach a terminal to a process

LIB$BBCCI

Test and clear a bit with interlock

LIB$BBSSI

Test and set a bit with interlock

LIB$CALLG

Call a procedure with a general
argument list

LIB$CHAR

Transform a byte to the first
character of a string

LIB$CONVERT_DATE_STRING

Convert a date string to a quadword

1-3

Introduction
1 .1 Organization of the Run-Time Library

Table 1-3 (Cont.)

1-4

LIB$ Facility Routines

Routine Name

Function

LIB$CRC

Calculate a Cyclic Redundancy Check
(CRC)

LIB$CRC_TABLE

Construct a Cyclic Redundancy
Check (CRC) table

LIB$CREA TE_DIR

Create a directory

LIB$CREATE_USER_VM_ZONE

Create a user-defined storage zone

LIB$CREATE_VM_ZONE

Create a new storage zone

LIB$CRF_INS_KEY

Insert a key in the cross-reference
table

LIB$CRF_INS_REF

Insert a reference to a key in the
cross-reference table

LIB$CRF_OUTPUT

Output some cross-reference table
information

LIB$CURRENCY

Get the system currency symbol

LIB$CVT_DX_DX

Convert the specified data type

LIB$CVT_FROM_INTERNAL _TIME

Convert internal time to external time

LIB$CVTF_FROM _INTERNAL_ TIME

Convert internal time to external time
(F-floating value)

LIB$CVT_TO_INTERNAL_TIME

Convert external time to internal time

LIB$CVTF_ TQ_INTERNAL_TIME

Convert external time to internal time
(F-floating value)

LIB$CVT_xTB

Convert numeric text to binary

LIB$CVT_VECTIM

Convert 7-word vector to internal
time

LIB$DATE_TIME

Return the date and time as a string

LIB$DAY

Return the day number as a
longword integer

LIB$DAY_OF_WEEK

Return the numeric day of the week

LIB$DECODE_FAUL T

Decode instruction stream during a
fault

LIB$DEC_OVER

Enable or disable decimal overflow
detection

LIB$DELETE_FILE

Delete one or more files

LIB$DELETE _LOGICAL

Delete a logical name

LIB$DELETE_SYMBOL

Delete a CU symbol

LIB$DELETE _ VM _ZONE

Delete a virtual memory zone

LIB$DIGIT_SEP

Get the digit separator symbol

LIB$DISABLE_CTRL

Disable CU interception of control
characters

LIB$DO_COMMAND

Execute the specified command

LIB$EDIV

Perform an extended-precision divide

Introduction
1 .1 Organization of the Run-Time Library

Table 1-3 (Cont.)

LIB$ Facility Routines

Routine Name

Function

LIB$EMODF

Perform extended multiply and
integerize for F-floating values

LIB$EMODD

Perform extended multiply and
integerize for D-floating values

LIB$EMODG

Perform extended multiply and
integerize for G-floating values

LIB$EMODH

Perform extended multiply and
integerize for H-floating values

LIB$EMUL

Perform an extended-precision
multiply

LIB$ENABLE_CTRL

Enable CU interception of control
characters

LIB$ESTABLISH

Establish a condition handler

LIB$EXTV

Extract a field and sign-extend

LIB$EXTZV

Extract a zero-extended field

LIB$FFx

Find the first clear or set bit

LIB$FID_TO_NAME

Convert a device and file ID to a file
specification

LIB$FILE _SCAN

Perform a file scan

LIB$FILE_SCAN_END

End of file scan

LIB$FIND_FILE

Find a file

LIB$FIND_FILE_END

End of find file

LIB$FIND_IMAGE_SYMBOL

Merge activate an image symbol

LIB$FIND_VM_ZONE

Find the next valid zone

LIB$FIXUP_FLT

Fix floating reserved operand

LIB$FLT_UNDER

Floating-point underflow detection

LIB$FORMAT_DATE_TIME

Format a date and/or time

LIB$FREE_DATE_TIME_CONTEXT

Free the context used to format a
date or time

LIB$FREE_EF

Free an event flag

LIB$FREE_LUN

Free a logical unit number

LIB$FREE_TIMER

Free timer storage

LIB$FREE_VM

Free virtual memory from the
program region

LIB$FREE_VM_PAGE

Free a virtual memory page

LIB$GETDVI

Get device/volume information

LIB$GETJPI

Get job/process information

LIB$GETQUI

Get queue information

LIB$GETSYI

Get systemwide information

LIB$GET_COMMAND

Get line from SYS$COMMAND

1-5

Introduction
1 .1 Organization of the Run-Time Library

Table 1-3 (Cont.)

1-6

LIB$ Facility Routines

Routine Name

Function

LIB$GET_COMMON

Get string from common area

LIB$GET_DATE_FORMAT

Return the user's date input format

LIB$GET_EF

Get an event flag

LIB$GET_FOREIGN

Get foreign command line

LIB$GET_INPUT

Get line from SYS$1NPUT

LIB$GET_LUN

Get logical unit number

LIB$GET_MAXIMUM_DATE_LENGTH

Get the maximum possible date/time
string length

LIB$GET_SYMBOL

Get the value of a CU symbol

LIB$GET_USERS_LANGUAGE

Return the user's language choice

LIB$GET_VM

Allocate virtual memory

LIB$GET_VM_PAGE

Get a virtual memory page

LIB$1CHAR

Convert first character of string to
integer

LIB$1NDEX

Index to relative position of substring

LIB$1NIT_DATE_TIME_CONTEXT

Initialize the context used in
formatting date/time strings

LIB$1NIT_TIMER

Initialize times and counts

LIB$1NSERT_TREE

Insert entry in a balanced binary tree

LIB$1NSQHI

Insert entry at the head of a queue

LIB$1NSQTI

Insert entry at the tail of a queue

LIB$1NSV

Insert a variable bit field

LIB$1NT_OVER

Integer overflow detection

LIB$LEN

Return the length of a string as a
longword

LIB$LOCC

Locate a character

LIB$LOOKUP_KEY

Look up keyword in table

LIB$LOOKUP_TREE

Look up an entry in a balanced binary
tree

LIB$LP_LINES

Specify the number of lines on each
printer page

LIB$MATCHC

Match characters, return relative
position

LIB$MATCH_COND

Match condition values

LIB$MOVC3

Move characters

LIB$MOVC5

Move characters with fill

LIB$MOVTC

Move translated characters

LIB$MOVTUC

Move translated until character

LIB$MULT_DELTA_TIME

Multiply delta time by scalar

Introduction
1 .1 Organization of the Run-Time Library

Table 1-3 (Cont.)

LIBS Facility Routines

Routine Name

Function

LIB$MUL TF_DELTA_ TIME

Multiply delta time by F-floating
scalar

LIB$PAUSE

Pause program execution

LIB$POLYF

Evaluate polynomials for F-floating
values

LIB$POLYD

Evaluate polynomials for D-floating
values

LIB$POLYG

Evaluate polynomials for G-floating
values

LIB$POLYH

Evaluate polynomials for H-floating
values

LIB$PUT_COMMON

Put string into common area

LIB$PUT_OUTPUT

Put line to SYS$0UTPUT

LIB$RADIX_POINT

Radix point symbol

LIB$REMQHI

Remove entry from head of queue

LIB$REMQTI

Remove entry from tail of queue

LIB$RENAME_FILE

Rename one or more files

LIB$RESERVE_EF

Reserve an event flag

LIB$RESET_ VM _ZONE

Reset virtual memory zone

LIB$REVERT

Revert to the handler of the
procedure activator

LIB$RUN _PROGRAM

Run new program

LIB$SCANC

Scan for characters and return
relative position

LIB$SCOPY_DXDX

Copy source string by descriptor to
destination

LIB$SCOPY_R_DX

Copy source string by reference to
destination

LIB$SET_LOGICAL

Set logical name

LIB$SET_SYMBOL

Set value of a CU symbol

LIB$SFREE 1_DD

Free one or more dynamic strings

LIB$SFREEN_DD

Free n dynamic strings

LIB$SGET1_DD

Get one dynamic string

LIB$SHOW_TIMER

Show accumulated times and counts

LIB$SHOW_ VM

Show virtual memory statistics

LIB$SHOW_VM_ZONE

Display information about a virtual
memory zone

LIB$SIGNAL

Signal exception condition

LIB$SIG_TO_RET

Convert signaled message to a return
status

1-7

Introduction
1 .1 Organization of the Run-Time Library

Table 1-3 (Cont.)

LIBS Facility Routines

Routine Name

Function

LIB$SIG_TO_STOP

Convert a signaled condition to a
signaled stop

LIB$SIM_TRAP

Simulate floating trap

LIB$SKPC

Skip equal characters

LIB$SPANC

Skip selected characters

LIB$SPAWN

Spawn a subprocess

LIB$ST AT_TIMER

Return accumulated time and count
statistics

LIB$STAT_VM

Return virtual memory statistics

LIB$STOP

Stop execution and signal the
condition

LIB$SUB_TIMES

Subtract two quadword times

LIB$SUBX

Perform multiple-precision binary
subtraction

LIB$SYS_ASCTIM

Invoke $ASCTIM to convert binary
time to ASCII

LIB$SYS_FAO

Invoke $FAQ system service to
format output

LIB$SYS_FAOL

Invoke $FAOL system service to
format output

LIB$SYS_GETMSG

Invoke $GETMSG system service to
get message text

LIB$TPARSE

Implement a table-driven, finite-state
parser

LIB$TRA_ASC_EBC

Translate ASCII to EBCDIC

LIB$TRA _EBC_ASC

Translate EBCDIC to ASCII

LIB$TRA VERSE_TREE

Traverse a balanced binary tree

LIB$TRIM _FILESPEC

Fit long file specification into fixed
field

LIB$VERIFY_ VM_ZQNE

Verify a virtual memory zone

LIB$WAIT

Wait a specified period of time

Table 1-4 lists all of the MTH$ facility routines. For more detailed
information on these routines, or on the MTH$ facility in general, refer to
the VMS RTL Mathematics (MTH$) Manual.

1-8

Introduction
1 .1 Organization of the Run-Time Library

Table 1-4 MTH$ Facility Routines
Routine Name

Function

MTH$xACOS

Return arc cosine of angle expressed in radians 1

MTH$xACOSD

Return arc cosine of angle expressed in degrees 1

MTH$xASIN

Return arc sine in radians 1

MTH$xASIND

Return arc sine in degrees 1

MTH$xATAN

Return arc tangent in radians 1

MTH$xATAND

Return arc tangent in degrees 1

MTH$xATAN2

Return arc tangent in radians with two arguments 1

MTH$xA T AND2

Return arc tangent in degrees with two arguments 1

MTH$xATANH

Return hyperbolic arc tangent 1

MTH$CxABS

Return complex absolute value 2

MTH$CCOS

Return complex cosine (F-floating complex value)

MTH$CxCOS

Return complex cosine (D- and G-floating complex values)

MTH$CEXPP

Return complex exponential (F-floating complex value)

MTH$CxEXP

Return complex exponential (D- and G-floating complex
values)

MTH$CLOG

Return complex natural logarithm (F-floating complex value)

MTH$CxLOG

Return complex natural logarithm (D- and G-floating
complex values)

MTH$CMPLX

Return complex number made from F-floating point values

MTH$xCMPLX

Return complex number made from D- and G-floating values

MTH$CONJG

Return conjugate of a complex number (F-floating point
complex value)

MTH$xCONJG

Return conjugate of a complex number (D- and G-floating
complex values)

MTH$xCOS

Return cosine of angle expressed in radians 1

MTH$xCOSD

Return cosine of angle expressed in degrees 1

MTH$xCOSH

Return hyperbolic cosine 1

MTH$CSIN

Return complex sine of complex number (F-floating complex
value)

MTH$CxSIN

Return complex sine of complex number (D- and G-floating
complex values)

MTH$CSORT

Return complex square root (F-floating point value)

MTH$CxSORT

Return complex square root (D- and G-floating complex
values)

MTH$CVT_x_x

Convert one double-precision value

MTH$CVT_xA_xA

Convert an array of double-precision values

MTH$xEXP

Return an exponential 1

1The routine is valid only for the F-, D-, and G-floating point data types. The corresponding
H-floating routine is listed separately with the format MTH$Hroutine_name.

2 The routine is valid for the three floating-point complex data types:

F-, D- and G-floating

point complex.

1-9

Introduction
1 .1 Organization of the Run-Time Library

Table 1-4 (Cont.)

MTH$ Facility Routines

Routine Name

Function

MTH$HACOS

Return arc cosine in radians (H-floating point value)

MTH$HACOSD

Return arc cosine in degrees (H-floating point value)

MTH$HASIN

Return arc sine in radians (H-floating point value)

MTH$HASIND

Return arc sine in degrees (H-floating point value)

MTH$HATAN

Return arc tangent in radians (H-floating point value)

MTH$HATAND

Return arc tangent in degrees (H-floating point value)

MTH$HATAN2

Return arc tangent in radians (H-floating point) with two
arguments

MTH$HATAND2

Return arc tangent in degrees (H-floating point) with two
arguments

MTH$HATANH

Return hyperbolic arc tangent (H-floating point value)

MTH$HCOS

Return cosine of angle expressed in radians (H-floating
point value)

MTH$HCOSD

Return cosine of angle expressed in degrees (H-floating
point value)

MTH$HCOSH

Return hyperbolic cosine (H-floating point value)

MTH$HEXP

Return exponential (H-floating point value)

MTH$HLOG

Return natural logarithm (H-floating point value)

MTH$HLOG2

Return base two logarithm (H-floating point value)

MTH$HLOG10

Return common logarithm (H-floating point value)

MTH$HSIN

Return sine of angle expressed in radians (H-floating point
value)

MTH$HSIND

Return sine of angle expressed in degrees (H-floating point
value)

MTH$HSINH

Return hyperbolic sine (H-floating point value)

MTH$HSQRT

Return square root (H-floating point value)

MTH$HTAN

Return tangent of angle expressed in radians (H-floating
point value)

MTH$HTAND

Return tangent of angle expressed in degrees (H-floating
point value)

MTH$HTANH

Compute the hyperbolic tangent (H-floating point value)

MTH$xlMAG

Return imaginary part of a complex number2

MTH$xLOG

Return the natural logarithm 1

MTH$xLOG2

Return base two logarithm 1

MTH$xLOG10

Return common logarithm 1

MTH$RANDOM

Generate a random number with uniform distribution

MTH$xREAL

Return real part of a complex number2

1 The routine is valid only for the F-, D-, and G-floating point data types. The corresponding

H-floating routine is listed separately with the format MTH$Hroutine_name.
2 The routine is valid for the three floating-point complex data types:

point complex.

1-10

F-, D- and G-floating

Introduction
1 .1 Organization of the Run-Time Library

Table 1-4 (Cont.)

MTH$ Facility Routines

Routine Name

Function

MTH$xSIN

Return sine of angle expressed in radians 1

MTH$xSINCOS

Return sine and cosine of angle expressed in radians 3

MTH$xSINCOSD

Return sine and cosine of angle expressed in degrees3

MTH$xSIND

Return sine of angle expressed in degrees 1

MTH$xSINH

Return hyperbolic sine 1

MTH$xSQRT

Return square root 1

MTH$xTAN

Return tangent of angle expressed in radians 1

MTH$xTAND

Return tangent of angle expressed in degrees 1

MTH$xTANH

Compute the hyperbolic tangent 1

MTH$UMAX

Compute the unsigned maximum

MTH$UMIN

Compute the unsigned minimum

1The routine is valid only for the F-, D-, and G-floating point data types. The corresponding
H-floating routine is listed separately with the format MTH$Hroutine_name.

3 The routine is valid for the four floating-point data types:

F-, D-, G-, and H-floating.

Table 1-5 lists all of the OTS$ facility routines. For more detailed information
on these routines, or on the OTS$ facility in general, refer to the VMS RTL
General Purpose (OTS$) Manual.

Table 1-5 OTS$ Facility Routines
Routine Name

Function

OTS$CNVOUT

Convert D-floating, G-floating, or H-floating to
character string

OTS$CVT_L_TB

Convert unsigned integer to binary text

OTS$CVT_L_Tl

Convert signed integer to signed integer text

OTS$CVT_L_TL

Convert integer to logical text

OTS$CVT_L_TO

Convert unsigned integer to octal text

OTS$CVT_L_TU

Convert unsigned integer to decimal text

OTS$CVT_L_TZ

Convert integer to hexadecimal text

OTS$CVT_TB_L

Convert binary text to unsigned integer

OTS$CVT_Tl_L

Convert signed integer text to integer

OTS$CVT_TL_L

Convert logical text to integer

OTS$CVT_TQ_L

Convert octal text to integer

OTS$CVT_TU_L

Convert unsigned decimal text to integer

OTS$CVT_T_z

Convert numeric text to D- or F-floating value

OTS$CVT_ T_x

Convert numeric text to G- or H-floating value

OTS$CVT_TZ_L

Convert hexadecimal text to unsigned longword

OTS$DIVCx

Perform complex division

1-11

Introduction
1 .1 Organization of the Run-Time Library

Table 1-5 (Cont.)

OTS$ Facility Routines

Routine Name

Function

OTS$01V_PK_LQNG

Perform packed decimal division with long divisor

OTS$01V_PK_SHORT

Perform packed decimal division with short divisor

OTS$MOVE3

Move data without fill

OTS$MOVE5

Move data with fill

OTS$MULCx

Perform complex multiplication

OTS$POWCxCx

Raise a complex base to a complex floating-point
exponent

OTS$POWCxJ

Raise a complex base to a signed longword
exponent

OTS$POWOO

Raise a 0-floating base to a 0-floating exponent

OTS$POWOR

Raise a 0-floating base to an F-floating exponent

OTS$POWOJ

Raise a 0-floating base to a longword exponent

OTS$POWGx

Raise a G-floating base to a G-floating or longword
exponent

OTS$POWGJ

Raise a G-floating base to a longword exponent

OTS$POWHx

Raise an H-floating base to floating-point exponent

OTS$POWHJ

Raise an H-floating base to a longword exponent

OTS$POWll

Raise a word base to a word exponent

OTS$POWHJJ

Raise a longword base to a longword exponent

OTS$POWLULU

Raise an unsigned longword base to an unsigned
longword exponent

OTS$POWxLU

Raise a floating-point base to an unsigned
longword exponent

OTS$POWRO

Raise an F-floating base to a 0-floating exponent

OTS$POWRR

Raise an F-floating base to an F-floating exponent

OTS$POWRJ

Raise an F-floating base to a longword exponent

OTS$SCOPY_OXOX

Copy a source string passed by descriptor to a
destination string

OTS$SCOPY_R_OX

Copy a source string passed by reference to a
destination string

OTS$SFREE 1_00

Free one dynamic string

OTS$SFREEN _OO

Free n dynamic strings

OTS$SGET1_00

Get one dynamic string

Table 1-6 lists all of the PPL$ facility routines. These routines are used
to implement parallel processing applications on VMS systems. For more
detailed information on these routines, or on the PPL$ facility in general,
refer to the VMS RTL Parallel Processing (PPL$) Manual.

1-12

Introduction
1 .1 Organization of the Run-Time Library

Table 1-6

PPL$ Facility Routines

Routine Name

Function

PPL$ADJUST_QUORUM

Adjust the barrier quorum

PPL$A WA IT_EVENT

Await the occurrence of an event

PPL$CREATE_BARRIER

Create a barrier

PPL$CREA TE_EVENT

Create an event

PPL$CREATE_SEMAPHORE

Create a semaphore

PPL$CREA TE _SHARED_MEMORY

Create shared memory

PPL$CREATE_SPIN_LQCK

Create a spin lock

PPL$CREA TE_ VM_ZQNE

Create a new virtual memory zone

PPL$DECREMENT_SEMAPHORE

Decrement a semaphore to gain access to
a resource

PPL$DELETE_SHARED_MEMORY

Delete shared memory

PPL$ENABLE_EVENT_AST

Enable AST notification of an event

PPL$ENABLE _EVENT_SIGNAL

Enable signal notification of an event

PPL$FIND_SYNCH_ELEMENT_ID

Find the synchronization element identifier

PPL$FLUSH _SHARED_MEMORY

Flush shared memory

PPL$GET_INDEX

Get the index of a participant

PPL$1NCREMENT_SEMAPHORE

Increment a semaphore to release a
resource

PPL$1NDEX _ TQ_PID

Convert a participant-index to a VMS PID

PPL$1NITIALIZE

Initialize the PPL$ facility

PPL$PID_TQ_INDEX

Convert a VMS PIO to a participant-index

PPL$RELEASE _SPIN _LOCK

Release a spin lock

PPL$READ_SEMAPHORE

Read the values associated with a
particular semaphore

PPL$SEIZE_SPIN_LOCK

Seize a spin lock

PPL$SET_QUORUM

Set the barrier quorum

PPL$SPAWN

Initiate parallel execution

PPL$STOP

Stop a participant

PPL$TERMINA TE

Terminate PPL$ participation

PPL$TRIGGER_EVENT

Trigger an event

PPL$UNIOUE _NAME

Provide a unique name

PPL$WAIT_AT_BARRIER

Synchronize at a barrier

Table 1-7 lists all of the SMG$ facility routines. These routines are used
to perform screen management operations. For more detailed information
on these routines, or on the SMG$ facility in general, refer to the VMS RTL
Screen Management (SMG$) Manual.

1-13

Introduction
1 .1 Organization of the Run-Time Library

Table 1-7 SMG$ Facility Routines

1-14

Routine Name

Function

SMG$ADD_KEY_DEF

Add a key definition

SMG$BEGIN_DISPLA V_UPDATE

Begin batching of display updates

SMG$BEGIN_PASTEBOARD_UPDATE

Begin batching of pasteboard
updates

SMG$CANCEL _INPUT

Cancel input request

SMG$CHANGE_PBD_CHARACTERISTICS

Change pasteboard characteristics

SMG$CHANGE_RENDITION

Change default rendition

SMG$CHANGE_VIEWPORT

Change a viewport associated with a
virtual display

SMG$CHANGE_VIRTUAL_DISPLAY

Change a virtual display

SMG$CHECK_FQR_OCCLUSION

Check for occlusion

SMG$CONTROL_MODE

Control mode

SMG$COPY_ VIRTUAL_DISPLA Y

Copy a virtual display

SMG$CREATE_KEY_TABLE

Create a key table

SMG$CREA TE_MENU

Create a menu in a virtual display

SMG$CREATE_PASTEBOARD

Create a pasteboard

SMG$CREATE_SUBPROCESS

Create and initialize a subprocess

SMG$CREA TE_ VIEWPORT

Create a virtual viewport

SMG$CREA TE_ VIRTUAL _DISPLAY

Create a virtual display

SMG$CREATE_VIRTUAL_KEYBOARD

Create a virtual keyboard

SMG$CURSOR_CQLUMN

Return the cursor column position

SMG$CURSOR_RQW

Return the cursor row position

SMG$DEFINE_KEY

Perform a DEFINE/KEY command

SMG$DEL_TERM_TABLE

Delete a terminal table

SMG$DELETE_CHARS

Delete the specified characters

SMG$DELETE_KEY_DEF

Delete a key definition

SMG$DELETE_LINE

Delete a line

SMG$DELETE _MENU

Delete a menu

SMG$DELETE _PASTEBOARD

Delete a pasteboard

SMG$DELETE_SUBPROCESS

Terminate a subprocess

SMG$DELETE_VIEWPORT

Delete a viewport

SMG$DELETE_VIRTUAL _DISPLAY

Delete a virtual display

SMG$DELETE_VIRTUAL _KEYBOARD

Delete a virtual keyboard

SMG$DISABLE_BROADCAST_TRAPPING

Disable the trapping of broadcast
messages

SMG$DISABLE_UNSOLICITED_INPUT

Disable the trapping of unsolicited
input

SMG$DRA W _CHAR

Draw the specified character

SMG$DRA W _LINE

Draw a line

Introduction
1 .1 Organization of the Run-Time Library

Table 1-7 (Cont.)

SMG$ Facility Routines

Routine Name

Function

SMG$DRA W _RECTANGLE

Draw a rectangle

SMG$ENABLE_UNSOLICITED_INPUT

Enable the trapping of unsolicited
input

SMG$END_DISPLA V_UPDATE

End the batching of display updates

SMG$END_PASTEBOARD_UPDATE

End the batching of pasteboard
updates

SMG$ERASE_CHARS

Erase the specified characters

SMG$ERASE_COLUMN

Erase a column from the display

SMG$ERASE_DISPLA Y

Erase a virtual display

SMG$ERASE_LINE

Erase a line from the display

SMG$ERASE_PASTEBOARD

Erase a pasteboard

SMG$EXECUTE_COMMAND

Execute the specified command in a
subprocess

SMG$FIND_CURSOR_DISPLA Y

Find the virtual display that contains
the cursor

SMG$FLUSH_BUFFER

Flush the buffer

SMG$GET_BROADCAST_MESSAGE

Get the broadcast message

SMG$GET_CHAR_AT_PHYSICAL_
CURSOR

Return the character at the cursor

SMG$GET_DISPLA V_A TTR

Get the display attributes

SMG$GET_KEY_DEF

Get the key definition

SMG$GET_KEYBOARD_ATTRIBUTES

Get the keyboard attributes

SMG$GET_NUMERIC_DAT A

Get the numeric data

SMG$GET_P ASTEBOARD_A TTRIBUTES

Get the pasteboard attributes

SMG$GET_PASTING_INFO

Get the display pasting information

SMG$GET_TERM_DAT A

Get the terminal data

SMG$GET_ VIEWPORT_CHAR

Get the characteristics of the display
view port

SMG$HOME_CURSOR

Home the cursor

SMG$1NIT_TERM_TABLE

Initialize the terminal table

SMG$1NIT_TERM_TABLE_BV_TYPE

Initialize TERMTABLE by VMS
terminal type

SMG$1NSERT_CHARS

Insert the specified characters

SMG$1NSERT_LINE

Insert a line

SMG$1NV ALIDA TE_DISPLA Y

Mark a virtual display as invalid

SMG$KEYCODE_TO_NAME

Translate a key code to a key name

SMG$LABEL _BORDER

Label a virtual display border

SMG$LIST_KEY_DEFS

List key definitions

SMG$LIST_PASTING_ORDER

List the display pasting order

SMG$LOAD_KEY_DEFS

Load key definitions

1-15

Introduction
1 .1 Organization of the Run-Time Library

Table 1-7 (Cont.)

1-16

SMG$ Facility Routines

Routine Name

Function

SMG$LOAD_VIRTUAL _DISPLAY

Load a virtual display from a file

SMG$MOVE_TEXT

Move the specified text

SMG$MOVE_VIRTUAL_DISPLA Y

Move a virtual display

SMG$NAME_TO_KEYCODE

Translate a key name to a key code

SMG$PASTE_VIRTUAL_DISPLAY

Paste a virtual display

SMG$POP_VIRTUAL _DISPLAY

Delete a series of virtual displays

SMG$PRINT_PASTE BOARD

Print the pasteboard using a print
queue

SMG$PUT_CHARS

Write characters to a virtual display

SMG$PUT_CHARS_HIGHWIDE

Write double-height, double-width
characters

SMG$PUT_CHARS_MUL Tl

Put text with multiple renditions to
the display

SMG$PUT_CHARS_ WIDE

Write wide characters

SMG$PUT_HELP_ TEXT

Output HELP text to a display

SMG$PUT_LINE

Write lines to a virtual display

SMG$PUT_LINE _HIGHWIDE

Write double-height, double-width
line

SMG$PUT_LINE _MUL Tl

Put text with multiple renditions to a
display in line mode

SMG$PUT_LINE_ WIDE

Write a double-width line

SMG$PUT_PASTEBOARD

Output pasteboard via routine

SMG$PUT_ST ATUS_LINE

Output a line of text to the hardware
status line

SMG$READ_COMPOSED_LINE

Read a composed line

SMG$READ_FROM_DISPLA Y

Read text from a display

SMG$READ_KEYSTROKE

Read a single character

SMG$READ_STRING

Read a string

SMG$READ_VERIFY

Read and verify a string

SMG$REMOVE_LINE

Remove a line from a virtual display

SMG$REPAINT_LINE

Repaint one line on the current
screen

SMG$REP AINT_SCREEN

Repaint the current screen

SMG$REPASTE_VIRTUAL _DISPLAY

Repaste the virtual display

SMG$REPLACE_INPUT_LINE

Replace the input line

SMG$RESTORE_PHYSICAL _SCREEN

Restore the physical screen

SMG$RETURN_CURSOR_POS

Return the cursor position

SMG$RETURN _INPUT_LINE

Return the input line

SMG$RING_BELL

Ring the terminal bell or buzzer

SMG$SA VE _PHYSICAL _SCREEN

Save the physical screen

Introduction
1 .1 Organization of the Run-Time Library

Table 1-7 (Cont.)

SMGS Facility Routines

Routine Name

Function

SMG$SAVE_ VIRTUAL_DISPLA Y

Save the virtual display to a file

SMG$SCROLL _DISPLA V_AREA

Scroll the display area

SMG$SCROLL _ VIEWPORT

Scroll a display under a viewport

SMG$SELECT_FROM_MENU

Select an item from a menu

SMG$SET_BROADCAST_TRAPPING

Enable the trapping of broadcast
messages

SMG$SET_CURSOR_ABS

Set absolute cursor position

SMG$SET_CURSOR_MODE

Turn the physical cursor on or off

SMG$SET_CURSOR_REL

Set the cursor relative to the current
position

SMG$SET_DEFAULT_ST ATE

Set the default state

SMG$SET_DISPLAY_SCROLL _REGION

Create a display scrolling region

SMG$SET_KEYPAD_MODE

Set the keypad mode

SMG$SET_OUT_OF_BAND_ASTS

Establish an AST routine for out-ofband characters

SMG$SET_PHYSICAL _CURSOR

Set the cursor on the physical screen

SMG$SET_ TERM_CHARACTERISTICS

Change the terminal characteristics

SMG$SNAPSHOT

Write a snapshot of the pasteboard

SMG$UNPASTE_VIRTUAL _DISPLAY

Remove the specified virtual display

Table 1-8 lists all of the STR$ facility routines. These routines are used to
perform string manipulation operations. For more detailed information on
these routines, or on the STR$ facility in general, refer to the VMS RTL String
Manipulation (STR$) Manual.
Table 1-8 STRS Facility Routines
Routine Name

Function

STR$ADD

Add two decimal strings

STR$ANALYZE_SDESC

Analyze a string descriptor

STR$APPEND

Append a string

STR$CASE_BLIND_COMP ARE

Compare strings without regard to case

STR$COMP ARE

Compare two strings

STR$COMP ARE _EQL

Compare two strings for equality

STR$COMPARE_MULTl

Compare two strings for equality using
the DEC Multinational Character Set

STR$CONCAT

Concatenate two or more strings

STR$COPY_DX

Copy a source string passed by
descriptor to a destination string

STR$COPY_R

Copy a source string passed by reference
to a destination string

1-17

Introduction
1 .1 Organization of the Run-Time Library

Table 1-8 (Cont.)

1 .2

STR$ Facility Routines

Routine Name

Function

STR$DIVIDE

Divide two decimal strings

STR$DUPL_CHAR

Duplicate character n times

STR$ELEMENT

Extract delimited element substring

STR$FIND_FIRST_IN _SET

Find the first character in a set of
characters

STR$FIND_FIRST_NQT_IN _SET

Find the first character that does not
occur in the set

STR$FIND_FIRST_SUBSTRING

Find the first substring in the input string

STR$FREE1_DX

Free one dynamic string

STR$GET1_DX

Allocate one dynamic string

STR$LEFT

Extract a substring of a string

STR$LEN_EXTR

Extract a substring of a string

STR$MATCH_WILD

Match a wildcard specification

STR$MUL

Multiply two decimal strings

STR$POSITION

Return relative position of a substring

STR$POS_EXTR

Extract a substring of a string

STR$PREFIX

Prefix a string

STR$RECIP

Return the reciprocal of a decimal string

STR$REPLACE

Replace a substring

STR$RIGHT

Extract a substring of a string

STR$ROUND

Round or truncate a decimal string

STR$TRANSLA TE

Translate matched characters

STR$TRIM

Trim trailing blanks and tabs

STR$UPCASEL •

Corvert string to all uppercase

Features of the Run-Time Library
The Run-Time Library provides the following features and capabilities:
•

Run-Time Library routines perform a wide range of general utility
operations. You can call a Run-Time Library routine from any VAX
language instead of writing your own code to perform the operation.
Routines in the Run-Time Library are part of the VAX Common RunTime environment; therefore, they can be called from any VAX language.
Because they follow the VMS Modular Programming Standard, Run-Time
Library routines can be easily incorporated into any program.

1-18

•

Because many of the routines are shared, they take up less space in
memory.

•

When new versions of the Run-Time Library are installed, you do not
need to revise your calling program, and generally do not need to relink.

Introduction
1 .2 Features of the Run-Time Library

•

All Run-Time Library routines are fully reentrant unless the description of
the facility or the routine specifies otherwise.
The term reentrant means that the routine executes correctly regardless of
how many threads of execution are executing at the same time. Currently,
reentrancy is supported only when those multiple threads are executing
on the same processor. The term AST-reentrant means that a routine
may be interrupted and reentered from itself or an AST-level thread of
execution only. In particular, an AST-reentrant routine may not execute
properly if more than one non-AST-level thread of execution is executing
the routine at once.
Because the Run-Time Library routines are reentrant (unless otherwise
noted), they can be called from multiple threads of execution. For
example, a routine may be called from both an AST-level thread and
a non-AST-level thread of an image, as well as from the multiple tasks of
an Ada program.

1.3

Linking with the Run-Time Library
Routines in the Run-Time Library execute entirely in the mode of the caller
and are intended to be called in user mode. This section explains how to link
your program and the Run-Time Library into a single executable unit.
When you link your program, the VMS Linker creates an executable image.
If your program includes explicit or implicit calls to the Run-Time Library,
the linker automatically searches the following system libraries for the named
procedures:
•

The system default shareable image library, IMAGELIB.OLB
The most frequently used portions of the Run-Time Library are contained
in this set of shareable images. When you link your program, the linker
searches IMAGELIB.OLB to resolve undefined symbols. That is, your
program is linked by default with the shareable images in this library to
form an executable image.

•

The system default object module library, STARLET.OLB
A portion of the Run-Time Library is contained as object modules in
STARLET.OLB. If the linker does not find the shareable image of the
routine in IMAGELIB.OLB, it copies the object module of the routine from
STARLET.OLB into your program's executable image.

Note that when your program calls a routine that is part of a shareable image,
the linker does not copy the routine into your program's executable image, as
it does for routines maintained in the object module library.
Using shareable images offers the following advantages:
•

Many programs can use the single copy of a shareable image, so each
program takes up less space in physical memory and less disk storage.

•

More than one program can use a shareable image simultaneously, thus
saving memory space.

•

When new versions of the Run-Time Library are installed, you do not
need to relink the programs that call the shareable Run-Time Library.

1-19

Run-Time Library Documentation Format

Each Run-Time Library routine is documented using a structured format
called the routine template. This section discusses the main headings in the
routine template, the information that is presented under each heading, and
the format used to present the information.
The purpose of this section, therefore, is to explain where to find information
and how to read it correctly - not how to use the routines themselves. For
information on using Run-Time Library routines, see Chapter 3.
Some main headings in the routine template contain information that requires
no further explanation beyond what is given in Table 2-1. However, the
following main headings contain information that does require additional
discussion, and this discussion takes place in the remaining subsections of
this section.
•

Format heading

•

Returns heading

•

Arguments heading

•

Condition Values Returned heading

Table 2-1

Main Headings in the Routine Template

Main Heading

Description

Routine name

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

Routine overview

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

Format

Required. The format heading follows the routine
overview. The format gives the routine entry point
name and the routine argument list. It also specifies
whether arguments are required or optional.

Returns

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

Arguments

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

2-1

Run-Time Library Documentation Format

Table 2-1 (Cont.)

Main Headings in the Routine Template

Main Heading

Description

Optional. The description heading follows the
arguments heading. The description section contains
more detailed 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 may affect the operation of the routine.
Note that any restrictions on the use of the routine
are always discussed first in the description section;
for example, any required user privileges or necessary
system resources are explained first.

2.1

Condition Values
Returned

Required. The condition values returned section
appears following the description section. It lists the
condition values (typically status or completion codes)
that are returned by the routine.

Example

Optional. The examples heading appears following
the condition values returned heading. The example
section contains one or more programming examples
to illustrate use of the routine. Text explaining the
example is most often provided.

Format Heading
Under the format heading, the following three types of information can be
present.
•

Procedure call format

•

Jump to Subroutine (JSB) format

•

Explanatory text

All Run-Time Library routines have a procedure call format, but not all RunTime Library routines have JSB formats; in fact, most do not. If a routine has
a JSB format, it always appears after the routine's procedure call format.
By using the procedure call format, your routine call conforms to the VAX
Procedure Calling and Condition Handling Standard. That is, an entry mask
is created, registers are saved, and so on.
Use of the JSB call format results in activation of the routine code directly,
without the overhead of constructing the entry mask, saving registers, and so
on. The JSB call format can be used only by VAX MACRO and VAX BLISS
programs.
Explanatory text may appear following one or both of the above formats.
This text is present only when needed to clarify the formats.
A procedure call format appears under the format heading as follows:
ENTRY_POINT_NAME

2-2

arg 1 ,arg2 ,[arg3] ,nullarg [,arg4] [,arg5]

Run-Time Library Documentation Format
2.1 Format Heading

The preceding format shows the use of the following syntax rules.
•

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 and the next.

•

Brackets ([])
Brackets surround optional arguments; in the previous example, arg3,
arg4, and argS are optional arguments because they are surrounded by
brackets.

•

Commas
Between arguments, the comma always follows the space. That is,
the comma immediately precedes an argument instead of immediately
following the previous one. If the argument is optional, the comma may
appear inside or outside the brackets. If the optional argument is not the
last argument in the list, you must either pass a zero by value or use the
comma as a place holder to indicate the place of the omitted argument.
If the optional argument is the last argument in the list, you must still
include the comma if the comma appears outside the brackets; if the
comma appears inside the brackets you can omit the argument entirely.
For example, arg3 in the previous example is an optional argument;
but because there are other required arguments that follow arg3 in the
list, the comma itself is not optional (since it marks the place of arg3);
therefore, the comma is not inside the brackets.
The arguments arg4 and argS are optional. Because there are no required
arguments that follow arg4 and argS in the list, the commas in front of
arg4 and argS are themselves optional; that is, the commas would not be
specified in the call if arg4 and argS were not specified. Therefore, the
commas in front of arg4 and argS are inside the brackets. Note however
that if argS is specified, the comma in front of arg4 is required whether or
not arg4 is specified.

•

Null arguments
A null argument is a place-holding argument. It is used for either of the
following two reasons: ( 1 ) to hold a place in the argument list for an
argument that has not yet been implemented by DIGITAL but which
may be at some future time or ( 2) to mark the position of an argument
that was used in earlier versions of the routine but which 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).
In the argument list constructed 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 differs from
language to language, so you should refer to your language user's guide
for language-specific syntax.

2-3

Run-Time Library Documentation Format
2.1 Format Heading

However, in general, the following rule applies to high-level languages:
to mark a null argument or to omit an optional argument in the call,
specify a comma (,) for each null argument or omitted optional argument.

2.2

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

2.2.1

Condition Values in RO
Most Run-Time Library 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 0 through 3) the completion status of the
operation. Programmers test the condition value to determine if the routine
completed successfully, or to determine the cause of the error.
For the purposes of high-level language programmers, the fact that status
information is returned by means of a condition value and that it is returned
in a VAX register is of little importance because the high-level language
programmer receives this status information in the return (or status) variable
he or she uses when making the call. The Common Run-Time environment
established for high-level languages allows the status information in RO to be
moved automatically to the user's return variable.
Nevertheless, if a routine returns a condition value in RO, the returns heading
in the documentation will contain the following information:
VMS Usage:

2-4

cond_value

type:

longword (unsigned)

access:

write only

mechanism:

by value

•

The "VMS Usage" heading specifies how the data type is interpreted.
VMS Usages are discussed in detail further in this chapter.

•

The "type" heading specifies the data type of the information returned.
Since the data type of a condition value is an unsigned longword, the
"type" heading shows "longword (unsigned)".

•

The "access" heading specifies the way in which the called routine
accesses the object. Since the called routine is returning the condition
value, it is writing into this longword; so the "access" heading shows
"write only".

•

The "mechanism" heading specifies the passing mechanism used by the
called routine in returning the condition value. Since the called routine
is writing the condition value directly into RO, the mechanism heading
shows "by value". (If the called routine had written the address of the
condition value into RO, the passing mechanism would have been "by
reference".)

Run-Time Library Documentation Format
2.2 Returns Heading
Note that if a routine returns a condition value in RO, another main heading
in the routine template (Condition Values Returned) describes the possible
condition values that the routine can return. This heading is discussed further
in this chapter.

2.2.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
number would use registers RO and Rl because the length of a G-floating
number is two longwords.
If a routine returns actual data in one or more of the registers RO through
Rl1, the returns heading in the documentation of that routine will contain the
following information:
VMS Usage:

yyyyyyyy

type:

xxxxxxxx

access:

write only

mechanism:

by value

The symbol "yyyyyyyy" indicates the VMS usage of the information. In this
particular case, the VMS usage would be floating_point.
The symbol "xxxxxxxx" above indicates the data type of the information being
returned. For example, for the mathematics routine discussed above, the data
type would be G-floating.
Additionally, some explanatory text may be provided following the
information about the usage, type, access, and mechanism of the returned
value. This text explains other relevant information about what the routine is
returning.
It is important to note that, since the routine is returning actual data in the
VAX registers, the registers cannot be used to convey completion status
information. All routines that return actual data in VAX registers must signal
a condition value that contains the completion status. If this is the case, the
heading reads "Condition Values Signaled". This heading is discussed further
in this chapter.

2.3

Arguments Heading
Under the arguments heading appears detailed information about each
argument listed in the call format. Arguments are described in the order in
which they appear in the call format. If the routine has no arguments, the
term "none" appears.
The following format is used to describe each argument.

2-5

Run-Time Library Documentation Format
2.3 Arguments Heading

argument-name
VMS Usage:

VMS-usage-type

type:

argument-data-type

access:

argument-access

mechanism:

argument-passing-mechanism

Additionally, the arguments heading contains at least one paragraph of
structured text, followed by other paragraphs of text, as needed.
The following sections discuss each part of the arguments heading separately.

2.3.1

VMS Usage Entry
The VMS usage entry indicates the abstract data structure of the argument.
Table 2-2 contains a list of the VMS data structures. Note that most highlevel language documentation sets contain a table listing all the VMS usages
and the statements required to implement each usage in the appropriate
language.
Table 2-2 VMS Data Structures
Data Structure

Definition

access_bit_names

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

access_mode

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

address

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

address_range

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

arg_list

Procedure argument list consisting of one
or more 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:

2-6

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)
Data Structure

VMS Data Structures
Definition

lN
ARG 1
ARG 2

•
•
•

ARG

N
ZK-4204-85

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 uprocedure" .)

boolean

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

byte_signed

This VMS data type is the same as the data
type ubyte (signed)"in Table 2-3.

byte_unsig ned

This VMS data type is the same as the data
type ubyte integer (unsigned)" in Table 2-3.

channel

Unsigned word integer that is an index to an

1/0 channel.
char_string

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

0
"X"

"Y"

: A+1

"Z"

:A+2
ZK-4202-85

complex_number

One of the VAX standard complex floatingpoint data types. The three complex floatingpoint numbers are: F-floating complex,
0-floating complex, and G-floating complex.

2-7

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)
Data Structure

VMS Data Structures
Definition
An F-floating complex number ( r,i) is
composed of two F-floating point numbers.
The first F-floating point number is the real
part ( r) of the complex number; the second
F-floating point number is the imaginary part
( i ). The structure of an F-floating complex
number is as follows:
15 14

7 6

REAL {

S EXPONENT FRACTION : A

PART

FRACTION

IMAGINARY {

: A+2

S EXPONENT FRACTION : A+6

PART

FRACTION

: A+B
ZK-4203-85

A D-floating complex number ( r,i) is
composed of two D-floating point numbers.
The first D-floating point number is the real
part ( r) of the complex number; the second
D-floating point number is the imaginary part
( i ) . The structure of a D-floating complex
number is as follows:
15 14

7 6

S lEXPONENTJ FRACTION :A
REAL
PART

FRACTION

:A+2

FRACTION

:A+4

FRACTION

:A+6

s IEXPONENTlFRACTION :AB
IMAGINARY
PART

FRACTION

: A+10

FRACTION

: A+12

FRACTION

: A+14
ZK-4201-85

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

2-8

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)

VMS Data Structures

Data Structure

Definition
4 3

15 14

EXPONENT

FRACTION

REAL

FRACTION

:A+2

PART

FRACTION

:A+4

FRACTION

:A+6

EXPONENT

FRACTION

:AB

IMAGINARY

FRACTION

: A+10

PART

FRACTION

: A+12

FRACTION

: A+14
ZK-4200-85

cond_value

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

31
cntrl

3 2
condition identification

"- ,______

severity

--..~!~------~.../~

Is I
27

facility number

message number

ZK-1795-84

context

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

date_time

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

2-9

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)

VMS Data Structures

Data Structure

Definition

device_name

Character string denoting the 1- to 9-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 15character name of an event flag cluster. It
can be a logical name, but if it is, it must
translate to a valid event flag cluster name.
For more information on how the system
translates logical names to global section
names see the "Event Flag Services" section
of the Introduction to VMS System Services.

ef_number

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

exit _handler_block

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

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

]

arg. count

address of condition value (written by VMS)

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

ZK-1714-84

fab

2-10

Structure denoting an RMS file access block.
A complete description of this structure is
contained in the VMS Record Management
Services Manual.

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)

VMS Data Structures

Data Structure

Definition

file_protection

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

WORLD

GROUP

OWNER

SYSTEM

WRDEWRDEWRDEWR
13 12 11 10 9

0
ZK-1706-84

floating_point

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

7 6

S lEXPONENTl FRACTION
FRACTION
31

:A
: A+2

16
ZK-4197-85

The structure of a 0-floating number is as
follows:

2-11

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)
Data Structure

VMS Data Structures
Definition
15 14

7 6

sJEXPONENTI FRACTION

FRACTION

:A+2

FRACTION

:A+4

FRACTION

:A+6

48
ZK-4198-85

The structure of a G-floating number is as
follows:
15 14

4 3
EXPONENT

lFRACTION

FRACTION

:A+2

FRACTION

:A+4

FRACTION

:A+6
48

ZK-4199-85

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

2-12

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)

VMS Data Structures

Data Structure

Definition

function _code

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

io_status_block

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

16 15
count

0
condition value

device-dependent information

ZK-856-82

The first word contains a condition value
indicating the success or failure of the
operation. The condition values used are
the same as for all returns from system
services; for example, SS$_NORMAL indicates
successful completion.
The second word contains the number of
bytes actually transferred in the 1/0 operation.
Note that for some devices this word contains
only the low-order word of the count. For
information on specific devices, see the VMS
1/0 User's Reference Volume.
The second longword contains devicedependent return information.
To ensure successful 1/0 completion and the
integrity of data transfers, the IOSB should be
checked following 1/0 requests, particularly for
device-dependent 1/0 functions. For complete
details on how to use the 1/0 status block,
see the VMS 1/0 User's Reference Volume.
item_lisL2

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

2-13

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)

VMS Data Structures
Definition

Data Structure

item code

component length

component address
ZK-1709-84

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

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

item code

0
buffer length

buffer address
return length address
ZK-1705-84

The first field is a word containing a usersupplied integer specifying the length (in bytes)
of the buffer in which the service writes the
information. The length of the buffer needed
depends upon the item code specified in the
item code field of the item descriptor. If the
value of buffer length is too small, the service
truncates the data.

2-14

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)
Data Structure

VMS Data Structures
Definition
The second field is a word containing a usersupplied symbolic code specifying the item of
information that the service is to return. These
codes are defined by macros that are specific
to the service.
The third field is a longword containing the
user-supplied address of the buffer in which
the service writes the information.
The fourth field is a longword containing the
user-supplied address of a word in which
the service writes the length in bytes of the
information it actually returned.

item _quota_list

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

lock_id

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

lock_status_block

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

2-15

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)

VMS Data Structures

Data Structure

Definition

reserved

condition value

lock identification

16-byte lock value block
(used only when LCK$M_ V ALBLK is set)
ZK-376-81

2-16

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 of from 1 to 255 characters
that identifies a logical name or equivalence
name to be manipulated by VMS logical name
system services. Logical names that denote
specific VMS objects have their own VMS
types: for example, a logical name identifying
a device has the VMS type "device_name".

longword_signed

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

longword_unsigned

This VMS data type is the same as the data
type "longword (unsigned)" in Table 2-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".

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)

VMS Data Structures

Data Structure

Definition

null_arg

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

octaword_signed

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

octaword_unsigned

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

page_protection

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

Symbol

Description

PRT$C_NA

No access

PRT$C_KR

Kernel read only

PRT$C_KW

Kernel write

PRT$C_ER

Executive read only

PRT$C_EW

Executive write

PRT$C_SR

Supervisor read only

PRT$C_SW

Supervisor write

PRT$C_UR

User read only

PRT$C_UW

User write

PRT$C_ERKW

Executive read; kernel
write

PRT$C_SRKW

Supervisor read; kernel
write

PRT$C_SREW

Supervisor read; executive
write

PRT$C_URKW

User read; kernel write

PRT$C_UREW

User read; executive write

PRT$C_URSW

User read; supervisor write

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

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

2-17

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)

VMS Data Structures

Data Structure

Definition

process_id

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

process_name

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

quadword_signed

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

quadword_unsigned

This VMS data type is the same as the data
type "quadword (unsigned)" in Table 2-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 bitmask wherein
each bit specifies an access right.
Once the identifier record exists in the rights
database, you define the holders of that
identifier with the $ADD_HOLDER system
service. You pass the binary identifier value
with the id argument; you specify the holder
with the holder argument, which is the
address of a quadword data structure with
the following format.
UIC identifier of holder
0
ZK-1903-84

One holder record exists in the rights database
for each holder of each identifier. The holder
record associates the holder with the identifier,
specifies the attributes of the holder, and
identifies the UIC identifier of the holder. The
format of a holder record is as follows:
identifier value
attributes
UIC identifier of holder
(reserved)
ZK-1907-84

2-18

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)
Data Structure

VMS Data Structures
Definition
The rights database is an indexed file with
three keys. The primary key is the identifier
value, the secondary key is the holder ID, and
the third key is the identifier name. Through
the use of the secondary key of the holder
ID, all the rights held by a process can be
retrieved quickly when LOGINOUT creates the
process rights list.

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).
The basic component of the VMS protection
scheme is an identifier. This 32-bit binary
value represents various types of agents using
the system. The types of agents represented
include individual users, groups of users, and
environments in which a process is operating.
Identifiers have two formats in the rights
database: UIC format 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.
Each UIC identifier is unique and represents
a system user. The UIC identifier contains
the 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.

31
group

I member I

UIC Format
ZK-1905-84

Bit 31, set to 1, specifies ID format. Bits 30
through 28 are reserved by DIGIT AL. The
remaining bits specify the identifier value.

j 1000

0
identifier
ID Format
ZK-1906-84

2-19

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)
Data Structure

VMS Data Structures
Definition
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 non numeric character. An identifier name
cannot consist entirely of numeric characters.
It can include the characters A through Z,
dollar signs ( $) and underscores ( _), as well
as the numbers 0 through 9. Any lowercase
characters are automatically converted to
uppercase.

2-20

rab

Structure denoting an RMS record access
block. A complete description of this structure
is contained in the VMS Record Management
Services Manual.

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 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. For more
information on how the system translates
logical names to global section names see
the "Memory Management" section of the
Introduction to VMS System Services.

system _access_id

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

time_name

Character string specifying a time value in VMS
format.

uic

Unsigned longword denoting a user
identification code (UIC).

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.

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-2 (Cont.)

2.3.2

VMS Data Structures

Data Structure

Definition

vector_byte_signed

A homogeneous array whose elements are all
signed bytes.

vector_byte_unsigned

A homogeneous array whose elements are all
unsigned bytes.

vector_longword_signed

A homogeneous array whose elements are all
signed longwords.

vector_longword_unsigned

A homogeneous array whose elements are all
unsigned longwords.

vector_quadword_signed

A homogeneous array whose elements are all
signed quadwords.

vector_quadword_unsigned

A homogeneous array whose elements are all
unsigned quadwords.

vector_word_signed

A homogeneous array whose elements are all
signed words.

vector_word_unsigned

A homogeneous array whose elements are all
unsigned words.

word_signed

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

word_unsigned

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

Type Entry
When a calling program passes an argument to a Run-Time Library routine,
the routine expects the argument to be of a particular data type. The type
entry indicates the expected data type for each argument.
Properly speaking, an argument does not have a data type; rather, the data
specified by an argument has a data type. The argument is merely the
vehicle for the passing of data to the called routine. Nevertheless, the phrase
"argument data type" is frequently used to describe the data type of the data
that is specified by the argument.
The following list contains the data types allowed by the VAX Procedure
Calling and Condition Handling Standard.
Table 2-3 VAX 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

2-21

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-3 (Cont.)

2-22

VAX Data Types

Data Type

Symbolic Code

D_floating

DSC$K_DTYPE_D

D_floating complex

DSC$K_DTYPE_DC

Descriptor

DSC$K_DTYPE_DSC

F_floating

DSC$K_DTYPE_F

F_floating complex

DSC$K_DTYPE_FC

G_floating

DSC$K_DTYPE_G

G_floating complex

DSC$K_DTYPE_GC

H_floating

DSC$K_DTYPE_H

H_floating complex

DSC$K_DTYPE_HC

Longword integer (signed)

DSC$K_DTYPE_L

Longword (unsigned)

DSC$K_DTYPE_LU

Numeric string, left separate sign

DSC$K_DTYPE_NL

Numeric string, left overpunched sign

DSC$K_DTYPE_NLO

Numeric string, right separate sign

DSC$K_DTYPE_NR

Numeric string, right overpunched sign

DSC$K_DTYPE_NRO

Numeric string, unsigned

DSC$K_DTYPE_NU

Numeric string, zoned sign

DSC$K_DTYPE_NZ

Octaword integer (signed)

DSC$K_DTYPE_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

Run-Time Library Documentation Format
2.3 Arguments Heading

2.3.3

Access Entry
The argument access entry describes the way in which the called routine
accesses the data specified by the argument. 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 shows "read only".
The term "only" is present to indicate that the called routine does not
both read and write (that is, "modify") the input data. Thus, input data
supplied by a variable is preserved when the called routine completes
execution.

Write only. Data that the called routine returns to the calling routine
must be written into a location where the calling routine can access it.
Such data is also called output data. When an argument specifies output
data, the access entry shows "write only".
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 shows "modify". In this case,
the called routine reads the input data, uses it in its operation, and
then overwrites the input data with the results (the output data) of the
operation. Thus, when the called routine completes execution, the input
data specified by the argument is lost.

The following is a complete list of the access types allowed by the VAX
Procedure Calling and Condition Handling Standard.
•

Read only

•
•
•

Write only
Modify

•

JMP after unwind

•

Call after stack unwind

•

Call without stack unwind

Function call (before return)

2-23

Run-Time Library Documentation Format
2.3 Arguments Heading

2.3.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 types of passing mechanisms.

2-24

By value. When an argument contains the actual data to be used by
the routine, the data is said to be passed to the routine "by value". The
argument therefore contains a copy of the actual data. Note that since an
actual argument in an argument list is only one longword in length, only
data that can be represented in one longword can be passed by value.

By reference. When an argument 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 actual data.

By descriptor. When an argument contains the address of a descriptor,
the data is said to be passed "by descriptor". A descriptor consists of two
or more longwords (depending on the type of descriptor used), which
describe the location, length, and 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.

Run-Time Library Documentation Format
2.3 Arguments Heading

Figure 2-1 illustrates the three passing mechanisms.
Figure 2-1

Routine Argument Passing Mechanisms

ARGUMENT LIST

(AP)
(a) ARGUMENT PASSED BY VALUE

ARG 1
ARG 2
ACTUAL VALUE

ARG N

(AP)
(b) ARGUMENT PASSED BY REFERENCE

ARG 1
ARG 2
POINTER TO
ACTUAL VALUE

ARG N

DATA

(AP)
(c) ARGUMENT PASSED BY DESCRIPTOR

ARG 1
ARG 2
POINTER TO
DESCRIPTOR

CLASS D TYPE

LENGTH

POINTER
ARG N

Note: ARG 1, ARG 2, and ARG N
can be passed by value, by
reference, or by descriptor
in any of these examples.
:(AP) = argument pointer

N =number of arguments
ZK-1962-84

2-25

Run-Time Library Documentation Format
2.3 Arguments Heading

Table 2-4 contains a list of the passing mechanisms allowed by the VAX
Procedure Calling and Condition Handling Standard:
Table 2-4

Passing Mechanisms

Passing Mechanism

Descriptor Code

By value

N/A
N/A
N/A
N/A
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 reference
By reference, array reference
By descriptor
By descriptor, fixed-length
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

2.3.5

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

An initial 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 that the
routine was to convert to another data type, the initial sentence fragment
would be something like the following: "number that is to be converted
to the such-and-such data type."

A sentence expressing the data type and passing mechanism of the
argument data.
•

If the passing mechanism is "by value", this sentence says something
like the following: "The xxx argument is an unsigned longword
containing the such-and-such data."

•

If the passing mechanism is "by reference", this sentence says

something like the following: "The xxx argument is the address
of a data type that contains the such-and-such data."

2-26

Run-Time Library Documentation Format
2.3 Arguments Heading

•

If the passing mechanism is "by descriptor", this sentence says
something like the following: "The xxx argument is the address of a
descriptor pointing to the such-and-such data."

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

2.4

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

It indicates the success or failure of a called procedure.

•

It describes an exception condition when an exception is signaled.

•

It identifies system messages.

•

It reports program success or failure to the command language level.

The documentation heading "Condition Values Returned" describes the
condition values returned by the routine when it completes execution
without generating an exception condition. This condition value describes
the completion status of the operation.
If a called routine generates an exception condition during execution, the
exception condition is signaled; the exception condition is then handled by
a condition handler (either user-supplied or system-supplied). Depending
on the nature of the exception condition and the condition handler that
handles the exception condition, the called routine will either continue
normal execution or terminate abnormally.
If a called Run-Time Library routine executes without generating an exception
condition, the called routine either returns a condition value or signals an
error condition; a few procedures both return a condition value and signal
an error condition. In the documentation of each routine, the method used
to return the condition value is indicated in the heading title itself. These
heading titles are discussed individually in the subsections that follow.

Under either of these headings, a two-column list gives the symbolic code
for each condition value that the routine can return and its accompanying
description. This description explains whether the condition value indicates
success or failure, and if failure, what user action may have caused the failure
and what can be done to correct it. Condition values that indicate success are
listed first.

2-27

Run-Time Library Documentation Format
2.4 Condition Values Returned Heading

Symbolic codes for condition values are system defined. The symbolic code
defined for each condition value equates to a number that is identical to the
longword condition value when interpreted as a number. In other words,
though the condition value consists of several fields, each of which can be
interpreted individually for specific information, the entire longword condition
value itself can be interpreted as an unsigned longword integer, which has an
equivalent symbolic code.
The following subsections discuss the ways in which a called routine returns
condition values.

2.4.1

Condition Values Returned
When the called routine returns a condition value in general register RO, the
possible condition values that the routine can return are listed under the
"Condition Values Returned" heading. Most routines return a condition value
in this way.

2.4.2

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

2-28

How to Call Run-Time Library Procedures

The VAX Procedure Calling and Condition Handling Standard describes the
mechanisms used by all VAX languages for invoking routines and passing
data between them. In effect, this standard describes the interface between
your program and the Run-Time Library routines that your program calls.
This chapter describes the basic methods for coding calls to Run-Time Library
routines from any VAX language.
In simple terms, when you call a Run-Time Library routine from your
program, you must furnish whatever arguments the routine requires. When
the routine completes execution, in most cases it returns control to your
program. If the routine returns a status code, your program should check
the value of the code to determine whether or not the routine completed
successfully. If the return status indicates an error, you may want to change
the flow of execution of your program to handle the error before returning
control to your program.

3.1

Overview
When you log in, the VMS system creates a process that exists until you log
out. When you run a program, the system activates an executable image in
your process. This image consists of a set of user procedures.
From the Run-Time Library's point of view, user procedures are procedures
that exist outside the Run-Time Library and that can call Run-Time Library
routines. User procedures can additionally call other user procedures that are
either supplied by DIGITAL or written by you. According to this definition,
then, the Run-Time Library views a VAX native-mode language compiler as a
set of user procedures, since the compiler generates code that calls Run-Time
Library routines. When you write a program that calls a Run-Time Library
routine, the Run-Time Library views your program as a user procedure.
The main program, or main procedure, is the first user procedure that the
system calls after calling a number of initialization procedures. A user
program, then, consists of the main program and all of the other user
procedures that it calls.
Figure 3-1 shows the calling relationships among a main program, other user
procedures, library routines, and the VMS operating system. In this figure,
CALL indicates that the calling procedures requested some information or
action; RETURN indicates that the called procedure returned the information
to the calling procedure or performed the action.
Although library routines can always call other library routines or the VMS
operating system, they can call user procedures only in the following cases:
•

When a user procedure establishes its own condition handler. For
example, LIB$SIGNAL operates by searching for and calling user
procedures that have been established as condition handlers (see the
VMS RTL Library (LIB$) Manual for more information).

3-1

How to Call Run-Time Library Procedures
3.1 Overview

Figure 3-1

Calling the Run-Time Library

OPERATING SYSTEM

'CALL

RETURN

'cALL

RETURN

LIBRARY

?P"Rocrou"R~I

CALL

RETURN

USER
PROCEDURE

-------CALL

RETURN

•

MAIN PROGRAM
(A USER PROCEDURE)

ZK-4262-85

•

3.2

When a user procedure passes to a routine the address of another
procedure that the library will call later. For example, when your program
calls LIB$SHOW_TIMER, you can pass the address of an action routine
that LIB$SHOW_TIMER will call to process timing statistics.

Call Formats
Each Run-Time Library routine requires a specific calling sequence. This
calling sequence indicates the elements that you must include when calling
the routine, and the order of those elements. The form of a calling sequence
is explained below.
Call Type

A calling sequence first specifies the type of call being made. A library routine
can be invoked by a CALLS or CALLG instruction or by a JSB instruction.
•

CALLS - Call Procedure with Stack Argument List instruction

•

CALLG - Call Procedure with General Argument List instruction

•

JSB - Jump to Subroutine instruction

Note that the following restrictions apply to the different types of calls.

3-2

•

High-level languages do not differentiate between CALLS and CALLG.
They use a CALL statement or a function reference to invoke a Run-Time
Library routine.

•

MACRO does not differentiate between functions and subroutines in its
CALLS and CALLG instructions.

How to Call Run-Time Library Procedures
3.2 Call Formats

•

Only MACRO and BLISS programs can explicitly access the JSB entry
points that are provided for some routines in the Run-Time Library. You
cannot write a program to access the JSB entry points directly from a
high-level language.

Facility Prefix and Routine Name

Each routine is identified by a unique entry point name, consisting of the
facility prefix (DTK$, LIB$, MTH$, and so on) and the procedure name (for
example, MTH$SIN). Section 3.3 provides more detailed information on entry
point naming conventions.
Argument List

Arguments passed to a routine must be listed in your program in the order
shown in the format section of the routine description. Each argument
has four characteristics: VMS usage, data type, access type, and passing
mechanism. These characteristics are described in Chapter 2 of this manual.
Some arguments are optional. Optional arguments are indicated by brackets
in the routine descriptions. When your program invokes a Run-Time Library
routine using a CALL entry point, you can omit optional arguments at the
end of the argument list. If the optional argument is not the last argument
in the list, you must either pass a zero by value or use a comma as a place
holder to indicate the place of the omitted argument.
Optional arguments apply only to the CALL entry points. JSB entry points do
not have optional arguments; all specified registers are used.
For example, the call format for a procedure with two optional arguments is
as follows:
LIB$GET_INPUT

get-str [,prompt-str] [,out-len]

A FORTRAN program could include any one of the following calls to this
procedure:
STAT =
ST AT =
STAT =
ST AT =
STAT =
STAT =
ST AT =

LIB$GET_INPUT (GET_STR,PROMPT,LENGTH)
LIB$GET_INPUT (GET_STR,PROMPT)
LIB$GET_INPUT (GET_STR,PROMPT,)
LIB$GET_INPUT (GET_STR,,LENGTH)
LIB$GET_INPUT (GET_STR)
LIB$GET_INPUT (GET_STR,)
LIB$GET_INPUT (GET_STA,% V AL(O))

The following examples illustrate the standard mechanism for calling an
external procedure, subroutine, or function in most high-level languages.
BASIC
CALL LIB$MOVTC(SRC, FILL, TABLE, DEST)
STATUS = LIB$GET_INPUT(STRING, 'NAME:')

3-3

How to Call Run-Time Library Procedures
3.2 Call Formats

BLISS
LOCAL
MSG_DESC : BLOCK [8,BYTE];
MSG_DESC [DSC$B_CLASS] = DSC$K_CLASS_S;
MSG_DESC [DSC$B_DTYPE] = DSC$K_DTYPE_T;
MSG_DESC [DSC$W_LENGTH] = 5;
MSG_DESC [DSC$A_POINTER] = MSG;
STATUS = LIB$PUT_OUTPUT(MSG_DESC);

COBOL
CALL LIB$MOVTC USING BY DESCRIPTOR
SRC,
FILL,
TABLE,
DEST,
GIVING RET-ST A TUS.

FORTRAN
CALL LIB$MOVTC(SRC, FILL, TABLE, DEST)
STATUS = LIB$GET_INPUT(STRING, 'NAME:')

Pascal
RET_ST ATUS := LIB$MOVTC (SRC, FILL, TABLE, DEST);

PL/I
CALL LIB$MOVTC(SRC, FILL, TABLE, DEST);
STATUS = LIB$GET_INPUT(STRING, 'NAME:');

As these examples show, VAX languages use varying call forms. Each
language user's guide gives specific information on calling the Run-Time
Library from that language.
In MACRO, a calling sequence takes one of three forms, as illustrated by the
following examples:

3.3

CALLS

#2,GALIB$GET_INPUT

CALLG

ARGUST, GALIB$GET_VM

JSB

GAMTH$SIN_R4

Run-Time Library Naming Conventions
This section explains the naming conventions that the Run-Time Library
follows for its entry point names, return status codes, and condition value
symbols.

3-4

How to Call Run-Time Library Procedures
3.3 Run-Time Library Naming Conventions

3.3.1

Entry Point Names
Run-Time Library entry points follow the VAX conventions for naming global
symbols. A global entry point takes the following general form:
fac$symbol

The elements which make up this format represent the following:
FAC

A 2- or 3-character facility name

SYMBOL

A 1- to 27-character symbol

The facility names are maintained in a systemwide DIGITAL registry. A
unique, 12-bit facility number is assigned to each facility name for use in
(1) condition value symbols, and (2) condition values in procedure return
status codes, signaled conditions, and messages. The high-order bit of this
number is 0 for facilities assigned by DIGITAL and 1 for those assigned by
Computer Special Services (CSS) and customers. For further information,
refer to the VAX Procedure Calling and Condition Handling Standard.
The Run-Time Library facility names are as follows:

3.3.2

DTK$

DECtalk routines

LIB$

Library routines

MTH$

Mathematics routines

OTS$

General purpose routines

PPL$

Parallel processing routines

SMG$

Screen management routines

STR$

String handling routines

JSB Entry Point Names
JSB entry point names follow the naming conventions explained in the
previous section, except that they include a suffix indicating the number of
the highest register accessed or modified. This helps ensure that the calling
program and the called routine will agree on the number of registers that the
called routine is going to change.
The following example illustrates the MACRO code that invokes the library
routine MTH$SIN _R4 by means of a JSB instruction. As indicated in the JSB
entry point name, this routine uses RO through R4.
JSB GAMTH$SIN_R4

;F-floating sine uses RO to R4

JSB entry points are available only to MACRO and BLISS programs. No VAX
high-level language provides a mechanism for accessing JSB entry points
explicitly.

3-5

How to Call Run-Time Library Procedures
3.3 Run-Time Library Naming Conventions

3.3.3

Function Return Values
Some Run-Time Library routines return a function value. This is generally
a 32-bit value returned in register RO or a 64-bit value returned in registers
RO:Rl. When a routine returns a function value, it cannot use RO and Rl
to return a status code. Therefore, such a procedure signals errors rather
than returning a status. This is explained in more detail in Chapter 2 of this
manual.
In high-level languages, statuses or function return values in RO appear as the
function result.

3.3.4

Facility Return Status and Condition Value Symbols
Library return status and condition value symbols have the following general
form:
fac$_abcmnoxyz

The elements which make up this format represent the following:

tac

The 2- or 3-letter facility symbol

abc

The first three letters of the first word of the associated message

mno

The first three letters of the next word

xyz

The first three letters of the third word, if any

Articles and prepositions are not considered significant words in this format.
If a significant word is only two letters long, an underscore is used to fill
out the third space. Some examples follow. Note that in most facilities the
normal or success symbol is an exception to the convention just described.

3.3.5

SS$_NORMAL

Routine successfully completed

LIB$_1NSVIRMEM

Insufficient virtual memory

MTH$_FLOOVEMA T

Floating overflow in mathematics library procedure

OTS$_FATINTERR

Fatal internal error in a language-independent support
procedure

LIB$_SCRBUFOVF

Screen buffer overflow

Argument Passing Mechanisms
A calling program passes an argument list of longwords to a called routine;
each longword in the argument list specifies a single argument. The called
routine interprets each argument using one of three standard passing
mechanisms: by value, by reference, or by descriptor.

3-6

How to Call Run-Time Library Procedures
3.3 Run-Time Library Naming Conventions

3.3.5.1

Passing Arguments by Value

When your program passes an argument using the by value mechanism,
the argument list entry contains the actual uninterpreted 32-bit value of
the argument. The value mechanism is usually used to pass constants. For
example, to pass the constant 100 by value, the calling program puts 100
directly in the argument list.
All VAX high-level languages require you to specify the by-value mechanism
explicitly when you call a procedure that accepts an argument by value.
FORTRAN, for example, uses the %VAL built-in function, while COBOL uses
the BY VALUE qualifier on the CALL [USING] statement.
A FORTRAN program calls a procedure using the by-value mechanism as
follows:
INCLUDE '($SSDEF)'
CALL LIB$STOP (%VAL(SS$_INTOVF))

A BLISS program calls this procedure as follows:
LIB$SIGNAL (SS$_INTOVF)

The equivalent MACRO code is as follows:
PUSHL
CALLS

#SS$_INTOVF
#1, G-LIB$SIGNAL

; Push longword by value
; Call LIB$SIGNAL

Note: Because the Run-Time Library is intended to be called from higherlevel languages, most Run-Time Library routines receive arguments by
reference, rather than by value, at their CALL entry points.

3.3.5.2

Passing Arguments by Reference

When your program passes arguments using the by reference mechanism,
the argument list entry contains the address of the location that contains the
value of the argument. For example, if variable xis allocated at location 1000,
the argument list entry will contain 1000, the address of the value of x.
Most languages pass scalar data by reference by default. Therefore, if you
simply specify x in the CALL statement or function invocation, the language
automatically passes the value stored at the location allocated to x to the
Run-Time Library routine.
A BLISS program calls a procedure using the by-reference mechanism as
follows:
LIB$FLT_UNDER (%REF(1))

The equivalent MACRO code is as follows:
ONE:

.LONG

Longword value 1

PUSHAL
CALLS

ONE
#1,G-LIB$FLT_UNDER

Push address of longword
Call LIB$FLT_UNDER

3-7

How to Call Run-Time Library Procedures
3.3 Run-Time Library Naming Conventions

3.3.5.3

Passing Arguments by Descriptor
When a procedure specifies that an argument is passed by descriptor, the
argument list entry must contain the address of a descriptor for the argument.
This mechanism is used to pass more complicated data. A descriptor includes
at least the following fields:
Symbol

Description

DSC$W_LENGTH

Length of data (or DSC$W_MAXSTRLEN, maximum length,
for varying strings)

DSC$B_DTYPE

Data type

DSC$B_CLASS

Descriptor class code

DSC$A_POINTER

Address at which the data begins

The VAX Procedure Calling and Condition Handling Standard describes these
fields in greater detail.
VAX high-level languages include extensions for passing arguments by
descriptor. When you specify by descriptor in these languages, the compiler
creates the descriptor, defines its fields, and passes the address of the
descriptor to the Run-Time Library routine. In some languages, by descriptor
is the default passing mechanism for certain types of arguments, such as
character strings. For example, the default mechanism for passing strings in
VAX BASIC is by descriptor.
100
200

COMMON STRING GREETING = 30
CALL LIB$PUT_SCREEN(GREETING)

The default mechanism for passing strings in COBOL, however, is by
reference. Therefore, when passing a string argument to a Run-Time Library
routine from a COBOL program, you must specify BY DESCRIPTOR for the
string argument in the CALL statement.
CALL LIB$PUT_OUTPUT USING BY DESCRIPTOR GREETING.

In MACRO or BLISS, you must define the descriptor's fields explicitly
and push its address onto the stack. Following is the MACRO code that
corresponds to the previous examples.
MSGDSC:

.WORD LEN
.BYTE DSC$K_DTYPE_T
.BYTE DSC$K_CLASS_S
.ADDRESS MSG

MSG:
.ASCII/Hello/
LEN = . -MSG
. ENTRY EX1 . AM<>
PUSHAQ MSGDSC
CALLS #1,GALIB$PUT_OUTPUT
RET
.END EX1

3-8

DESCRIPTOR: DSC$W_LENGTH
DSC$B_DTYPE
DSC$B_CLASS
DSC$A_POINTER
String itself
Define the length of the string
Push address of descriptor
Output the string

How to Call Run-Time Library Procedures
3.3 Run-Time Library Naming Conventions

The equivalent BLISS code looks like this:
MODULE BLISS! (MAIN = BLISS!,
! Example of calling LIB$PUT_OUTPUT
!DENT = , 1-001',
ADDRESSING_MODE(EXTERNAL = GENERAL)) =
BEGIN
EXTERNAL ROUTINE
LIB$STOP,
Stop execution via signaling
LIB$PUT_OUTPUT;
Put a line to SYS$0UTPUT
FORWARD ROUTINE
BLISS! : NOVALUE;
LIBRARY 'SYS$LIBRARY:STARLET.L32';
ROUTINE BLISS!
: NOVALUE =

! Routine

BEGIN
!+
! Allocate the necessary local
!-

storage.

LOCAL
STATUS,
MSG_DESC: BLOCK [8, BYTE];

Return status
Message descriptor

BIND
MSG= UPLIT('HELLO');
!+

! Initialize the string descriptor.
!-

MSG_DESC [DSC$B_CLASS] = DSC$K_CLASS_S;
MSG_DESC [DSC$B_DTYPE] = DSC$K_DTYPE_T;
MSG_DESC [DSC$W_LENGTH] = 5;
MSG_DESC [DSC$A_POINTER] = MSG:
!+
! Put out the string. Test the return status.
! If it is not a success, then signal the RMS error.
!-

STATUS= LIB$PUT_OUTPUT(MSG_DESC);
IF NOT .STATUS THEN LIB$STOP(.STATUS);
END;
End of routine BLISS!
END
! End of module BLISS!
ELUDOM

3.4

Passing Scalars as Arguments
When you are passing an input scalar value to a Run-Time Library routine,
you usually pass it either by reference or by value. You usually pass output
scalar arguments by reference to Run-Time Library routines. An output scalar
argument is the address of a location where some scalar output of the routine
will be stored.

3-9

How to Call Run-Time Library Procedures
3.5 Passing Arrays as Arguments

3.5

Passing Arrays as Arguments
Arrays are passed to Run-Time Library routines by reference or by descriptor.
Sometimes, the routine knows the length and dimensions of the array to be
received, as in the case of the table passed to LIB$CRC_TABLE. Arrays such
as this are normally passed by reference.
In other cases, the routine will actually analyze and operate on the input
array. The routine does not necessarily know the length or dimensions
of such an input array, so that a descriptor is necessary to provide the
information the routine needs to accurately describe the array.

3.6

Passing Strings as Arguments
Strings are passed by descriptor to Run-Time Library routines. The Run-Time
Library routine recognizes the following descriptors:
Descriptor

Descriptor Class Code

Numeric Value

Unspecified

DSC$K_CLASS_Z

Fixed-length

DSC$K_CLASS_S

Dynamic

DSC$K_CLASS_D

Array

DSC$K_CLASS_A

Scaled decimal

DSC$K_CLASS_SD

Noncontiguous array

DSC$K_CLASS_NCA

Varying-length

DSC$K_CLASS_VS

A Run-Time Library routine writes strings according to the following three
types of semantics:

3.7

•

Fixed length, characterized by an address and a constant length

•

Varying length, .characterized by an address, a current length, and a
maximum length

•

Dynamic, characterized by a current address and a current length

Combinations of Descriptor Class and Data Type
Some combinations of descriptor class and data type are not permitted, either
because they are not meaningful or because the VAX Procedure Calling and
Condition Handling Standard does not recognize them. Furthermore, the
same function may be performed with more than one combination. This
section describes the restrictions on the combinations of descriptor classes
and data types. These restrictions help to keep procedure interfaces simple
by allowing a procedure to accept a limited set of argument formats without
sacrificing functional flexibility.
Tables 3-1 to 3-3 show all possible combinations of descriptor classes and
data types. For example, Table 3-1 shows that your program can pass an
argument to a Run-Time Library routine whose descriptor class is DSC$K_
CLASS-A (array descriptor) and whose data type is unsigned byte (DSC$K_
DTYPE_BU). The VAX Procedure Calling and Condition Handling Standard

3-10

How to Call Run-Time Library Procedures
3. 7 Combinations of Descriptor Class and Data Type

does not permit your program to pass an argument whose descriptor class is
DSC$K_CLASS_D (decimal string) and whose data type is unsigned byte.
Table 3-1

Atomic Data Types and Descriptor Classes
DSC$K_CLASS

_s _o _v _A _p _SD _NCA
= 1 = 2 = 3 = 4 = 5 = 9 = 10
= 26
= 10
= 11
= 27
= 28
= 12
= 13
= 29
= 30
= 31

DSC$K_DTYPLO
DSC$K_DTYPL F
DSC$K_DTYPLD
DSC$K_DTYPLG
DSC$K_DTYPLH
DSC$K_DTYPLFC
DSC$K_DTYPLDC
DSC$K_DTYPLGC
DSC$K_DTYPLHC
DSC$K_DTYPLCIT

_vs
= 11

_UBS
= 13

_URA

_BFA

= 12

= 14

= 191

_VSA

Yes

Key

Yes

The Calling Standard allows this combination of class and data type.

No valid interpretation exists for this combination.

The Calling Standard forbids the use of this combination of class and data type. Higher-level
languages and their run-time support must conform to this restriction.

ZK-4267 /1-85

3-11

How to Call Run-Time Library Procedures
3. 7 Combinations of Descriptor Class and Data Type

Table 3-1 (Cont.)

Atomic Data Types and Descriptor Classes
DSC$K_CLASS

_s _D _v _A
=1 =2 =3 =4

= 0
= 2
DSC$K_DTYPL WU = 3
DSC$K_DTYPLLU
= 4
DSC$K_DTYPLQU = 5
DSC$K_DTYPLOU = 25
DSC$K_DTYPLB
= 6
DSC$K_DTYPL W
= 7
DSC$K_DTYPLL
= 8
DSC$K_DTYPLQ
= 9

_SD

_NCA

= 10

_vs
= 11

_VSA
= 12

_UBS

=5 =9

= 13

_UBA
= 14

= 191

_BFA

DSC$K_DTYPLZ

Yes

DSC$K_DTYPLBU

Yes

Key

Yes

The Calling Standard allows this combination of class and data type.

No valid interpretation exists for this combination.

The Calling Standard forbids the use of this combination of class and data type. Higher-level
languages and their run-time support must conform to this restriction.

ZK-4267 /2-85

3-12

How to Call Run-Time Library Procedures
3. 7 Combinations of Descriptor Class and Data Type

Table 3-2

String Data Types and Descriptor Classes
DSC$K_CLASS

_s
= 1

= 2

= 3

= 4

_p
= 5

_SD

= 9

_NCA
= 10

_vs
= 11

_VSA
= 12

_UBS

_UBA

_BFA

= 13

= 14

= 191

DSC$K_DTYPL V

Yes

DSC$K_DTYPL T

= 14

Yes

DSC$K_DTYPLNU

= 15

Yes

DSC$K_DTYPLN L

= 16

Yes

DSC$K_DTYPLN LO = 17

Yes

DSC$K_DTYPLNR

= 18

Yes

DSC$K_DTYPLNLR

= 19

Yes

DSC$K_DTYPLNZ

= 20

Yes

DSC$K_DTYPLP

= 21

Yes

DSC$K_DTYPE_ VT

= 37

Yes

DSC$K_DTYPL VU

= 34

Key

Yes

The Calling Standard allows this combination of class and data type.

No valid interpretation exists for this combination.

The Calling Standard forbids the use of this combination of class and data type. Higher-level
languages and their run-time support must conform to this restriction.

ZK-4266-85

3-13

How to Call Run-Time Library Procedures
3. 7 Combinations of Descriptor Class and Data Type

Table 3-3

Miscellaneous Data Types and Descriptor Classes
DSC$K_CLASS

_s _o _v _A _p _so
=1 =2 =3 =4 =5 =9
DSC$K_DTYPLZI
DSC$K_DTYPLZEM
DSC$K_DTYPLDSC
(See Note 3)
DSC$K_DTYPLBPV
DSC$K_DTYPLBL V

= 22
= 23
= 3
= 32
= 33

_NCA
10

_vs
= 11

_VSA
12

_UBS
13

_UBA
14

= 191

_BFA

Yes

Key

Yes

The Calling Standard allows this combination of class and data type.

No valid interpretation exists for this combination.

The Calling Standard forbids the use of this combination of class and data type. Higher-level
languages and their run-time support must conform to this restriction.
ZK-4265-85

Note

3-14

Class types DSC$K_CLAss_p1 (6) and DSC$K_CLASS_JI (8) are
considered obsolete.

Class type DSC$K_CLASS_J (7) is reserved for use by the debugger.

A descriptor with data type DSC$K_DTYPE_DSC (24) points to a
descriptor that has class DSC$K_CLASS_D (2) and data type
DSC$K_DTYPE_T (14). All other class and data type combinations in
the target descriptor are reserved for future definition in the standard.

DSC$K_CLASS_p is used by VAX FORTRAN. No new VAX languages
will use it.

The scale factor for DSC$K_CLASS_SD is always a decimal data type. It
does not vary with the data type of the data described by the descriptor.

For DSC$K_CLASS_UBS and DSC$K_CLASS_UBA, the length field
will specify the length of the data field in bits. For example, if the data
type is unsigned word (DSC$K_DTYPE_WU), DSC$W_LENGTH
equals 16.

How to Call Run-Time Library Procedures
3.8 Errors from Run-Time Library Routines

3.8

Errors from Run-Time Library Routines
A routine can indicate an error condition to the calling program either by
returning a 32-bit condition value in RO as a completion code or by signaling
the error.
A completion code, also called a return status or condition value, is either a
success (bit 0 = 1) or error condition value (bit 0 = 0). In an error condition
value, the low-order three bits specify the severity of the error. Bits 27
through 16 contain the facility number, and bits 15 through 3 indicate the
particular condition. The high-order four bits are control bits. When the
called procedure returns a condition value, the calling program can test RO
and choose a recovery path. A general guideline to follow when testing for
success or failure is that all success codes have odd values and all error codes
have even values.
When the completion code is signaled, the calling program must establish a
handler to get control and take appropriate action. (See the VMS RTL Library
(LIB$) Manual for a description of signaling and condition handling and more
information on the condition value.)

3.9

Calling a Library Procedure in MACRO
This section describes how to code MACRO calls to library routines using a
CALLS, CALLG, or JSB instruction. The routine descriptions that appear later
in this manual describe the entry points for each routine. You can use either
a CALLS or a CALLG instruction to invoke a procedure with a CALL entry
point. You must use a JSB instruction to invoke a procedure with a JSB entry
point. All MACRO calls are explicitly defined.

3.9.1

MACRO Calling Sequence
All Run-Time Library routines have a CALL entry point. Some routines
also have a JSB entry point. In MACRO, you invoke a CALL entry point
with a CALLS or CALLG instruction. To access a JSB entry point, use a JSB
instruction.
Arguments are passed to CALLS and CALLG entry points by a pointer to
the argument list. The only difference between the CALLS and CALLG
instructions is as follows:
•

For CALLS, the calling procedure pushes the argument list onto the stack
(in reverse order) before performing the call. The list is automatically
removed from the stack upon return.

•

For CALLG, the calling program specifies the address of the argument
list, which can be anywhere in memory. This list remains in memory
upon return.

Both of these instructions have the same effect on the called procedure.
JSB instructions execute faster than CALL instructions. They do not set up
a new stack frame, do not change the enabling of hardware traps or faults,
and do not preserve the contents of any registers before modifying them. For
this reason, you must be careful when invoking a JSB entry point in order to
prevent the loss of information stored by the calling program.

3-15

How to Call Run-Time Library Procedures
3.9 Calling a Library Procedure in MACRO

Whichever type of call you use, the actual reference to the procedure entry
point should use general mode addressing (G"). This ensures that the linker
and the image activator will be able to locate the module within the shareable
image.
In most cases, you have to tell a library routine where to find input values
and store output values. You must select a data type for each argument when
you code your program. Most routines accept and return 32-bit arguments.
For input arguments of byte, word, or longword values, you can supply either
a constant value, a variable name, or an expression in the Run-Time Library
routine call. If you supply a variable name for the argument, the data type
of the variable must be as large or larger than the data types that the called
procedure requires. If, for example, the called procedure expects a byte in the
range 0 to 100, you can use a variable data type of a byte, word, or longword
with a value between 0 and 100.
For each output argument, you must declare a variable of exactly the length
required to avoid extraneous data. If, for example, the called procedure
returns a byte value to a word-length variable, the leftmost eight bits of the
variable (15:8) are not overwritten on output. Conversely, if a procedure
returns a longword value to a word-length variable, it modifies variables in
the next higher word.

3.9.2

CALLS Instruction Example
Before executing a CALLS instruction, you must push the necessary
arguments on the stack. Arguments are pushed in reverse order; the last
argument listed in the calling sequence is pushed first. The following
example shows how a MACRO program calls the procedure that allocates
virtual memory in the program region for LIB$GET_VM .
. PSECT DATA
MEM:
LEN:

.LONG

700

.PSECT CODE

1$:

PIC,USR,CON,REL,GBL,NOSHR,NOEXE,RD,WRT,NOVEC
Longword to hold address of
; allocated memory
; Number of bytes to allocate
PIC,USR,CON,REL,GBL,SHR,EXE,RD,NOWRT,NOVEC

.ENTRY

PROG, -M<>

PUS HAL

MEM

PUS HAL

LEN

CALLS
BLBC
RET
PUSHL
CALLS
RET

#2, G-LIB$GET_VM
RO, 1$

.END

PROG

RO
#1, G-LIB$SIGNAL

Push address of longword
to receive address of block
Push address of longword
containing number of bytes
desired
Allocate memory
Branch if memory not available
Signal the error

Because the stack grows toward location 0, arguments are pushed onto the
stack in reverse order from the order shown in the general format for the
routine. Thus, the base-address argument, here called START, is pushed
first, and then the number-bytes argument, called LEN. Upon return from
LIB$GET_VM, the calling program tests the return status (ret-status), which

3-16

How to Call Run-Time Library Procedures
3.9 Calling a Library Procedure in MACRO

is returned in RO and branches to an appropriate error routine if an error
occurred.

3.9.3

CALLG Instruction Example
When you use the CALLG instruction, the arguments are set up in any
location, and the call includes a reference to the argument list. The following
example of a CALLG instruction is equivalent to the preceding CALLS
example.
ARGLST:

LEN:
START:

.LONG
.ADDRESS

LEN

.ADDRESS

START

.LONG
.BLKL

CALLG ARGLIST, G-LIB$GET_VM
BLBC RO, ERROR
BRB
10$

3.9.4

Argument list count
Address of longword containing
the number of bytes to allocate.
Address of longword to receive
the starting address of the
virtual memory allocated.
Number of bytes to allocate
Starting address of the virtual
memory.
Get virtual memory
Check for error

JSB Entry Points
A procedure's JSB entry point name indicates the highest numbered register
that the procedure modifies. Thus a procedure with a suffix Rn modifies
registers RO through Rn. (You should always assume that RO and Rl are
modified.) The calling program loads the arguments in the registers before
the JSB instruction is executed.
A calling program must use a JSB instruction to invoke a Run-Time Library
routine by means of its JSB entry point. You pass arguments to a JSB entry
point by placing them in registers in the following manner.
NUM:

.FLOAT
MOVF
JSB

0.7853981
NUM, RO
G-MTH$SIN_R4

Constant P1/4
Set up input argument
Call F-floating sine procedure
Return with value in RO

In this example, R4 in the entry point name indicates t,hat MTH$SIN_R4
changes the contents of registers RO through R4. The routine does not
reference or change the contents of registers RS through Rll.
The entry mask of a calling procedure should specify all the registers to be
saved if the procedure invokes a JSB routine. This step is necessary because a
JSB procedure does not have an entry mask, and thus has no way to specify
registers to be saved or restored.
For example, consider program A calling procedure B by means of a CALL
entry point.
•

Procedure B modifies the contents of R2 through R6, so the contents of
these registers are preserved at the time of the CALL.

•

Procedure B then invokes procedure C by means of a JSB entry point.

3-17

How to Call Run-Time Library Procedures
3.9 Calling a Library Procedure in MACRO

•

Procedure C modifies registers RO through R7.

•

When control returns to procedure B, R7 has been modified, but when
procedure B passes control back to procedure A, it restores only R2
through R6. Thus the contents of R7 are unpredictable, and program A
does not execute as expected. Procedure B should be rewritten so that R2
through R7 are saved in procedure B's entry mask.

A similar problem occurs if the stack is unwound, because unwinding the
stack restores the contents of registers for each stack frame as it removes the
previous frame. Because a JSB entry point does not create a stack frame, the
contents of the registers before the JSB instruction will not be restored unless
they were saved in the entry mask of the calling program. You do this by
naming the registers to be saved in the calling program's entry mask, so a
stack unwind correctly restores all registers from the stack. In the following
example, the function Y=PROC(A,B) returns the value Y, where
Y = SIN(A)•SIN(B).

3.9.5

.ENTRY
MOVF
JSB
MOVF

MOVF
JSB
MULF
RET

Save R2:R5
RO = A
RO = SIN(A)
Copy result to register
not modified by MTH$SIN
RO = B
RO = SIN(B)
RO = SIN(A)SIN(B)
Return

Return Status
Your MACRO program can test for errors by examining segments of the
32-bit status code returned by a Run-Time Library routine.
To test for errors, check for a zero in bit zero, using a Branch on Low Bit Set
(BLBS) or Branch on Low Bit Clear (BLBC) instruction.
To test for a particular condition value, compare the 32 bits of the return
status with the appropriate return status symbol, using a Compare Long
(CMPL) instruction or the Run-Time Library routine LIB$MATCH_COND.
There are three ways to define a symbol for the condition value returned by
a Run-Time Library routine so that you can compare the value in RO with a
particular error code:
•

Using the .EXTRN symbol directive. This causes the assembler to
generate an external symbol declaration.

•

Using the $facDEF macro call. Calling the $LIBDEF macro, for example,
causes the assembler to define all LIB$ condition values.

•

By default. The assembler automatically declares the condition value as
an external symbol that is defined as a global symbol in the Run-Time
Library.

The following example asks for the user's name. It then calls the RunTime Library routine LIB$GET-1NPUT to read the user's response from
the terminal. If the string returned is longer than 30 characters (the space
allocated to receive the name), LIB$GET-1NPUT returns in RO the condition
value equivalent to the error LIB$-1NPSTRTRU, 'input string truncated.' This
value is defined as a global symbol by default. The example then checks for

3-18

How to Call Run-Time Library Procedures
3.9 Calling a Library Procedure in MACRO

the specific error by comparing LIB$_INPSTRTRU with the contents of RO.
If LIB$_INPSTRTRU is the error returned, the program considers that the
routine executed successfully. If any other error occurs, the program handles
it as a true error.
$SSDEF
$DSCDEF
.PSECT $DATA
PROMPT_D:
.WORD
PROMPT_LEN
.BYTE
DSC$K_DTYPE_T
.BYTE
DSC$K_CLASS_S
.ADDRESS PROMPT

Define SS$ symbols
Define DSC$ symbols

PROMPT: .ASCII
/NAME: /
PROMPT_LEN = . - PROMPT

String descriptor
Calculate length of
string

STR_LEN = 30
STRING_D:
.WORD
STR_LEN
.BYTE
DSC$K_DTYPE_T
.BYTE
DSC$K_CLASS_S
.ADDRESS STR_AREA
STR_AREA: .BLKB STR_LEN

Use 30-byte string
Input string descriptor
Length field
Type field in text
Class field is string
Address
Area to receive string

.PSECT $CODE
.ENTRY START , -M<>
PUSHAQ PROMPT_D
PUSHAQ STRING_D
CALLS #2
BLBS RO
CMPL RO

G-LIB$GET_INPUT
10$
#LIB$_INPSTRTRU

BEQL 10$
PUSHL RO
CALLS #1 , G-LIB$SIGNAL
10$:

3.9.6

MOVL

#SS$_NORMAL , RO

RET
.END

START

Descriptor for prompt
Length field
Type field is text
Class field is string
Address

Push address of prompt
descriptor
Push address of string
descriptor
Get input string
Check for success
Error: Was it
truncated string?
No, more serious error

Success, or name too
long

Function Return Values in MACRO
Function values are generally returned in RO (32-bit values) or RO:Rl
(64-bit) values. A MACRO program can access a function value by
referencing RO or RO:Rl directly. For functions that return a string, the
address of the string or the address of its descriptor is returned in RO. If a
function needs to return a value larger than 64 bits, it must return the value
by using an output argument.
There are some exceptions to these rules:
•

JSB entry points in the MTH$ facility return H-floating values in RO:R3.

3-19

How to Call Run-Time Library Procedures
3.9 Calling a Library Procedure in MACRO

•

One routine, MTH$SINCOS, returns two function values, the sine and
the cosine of an angle. Depending on the data type of the function
values, the function values are returned in the following registers:
F-floating

RO through R 1

D-floating or G-floating

RO through R3

H-floating

RO through R7

As in the case of output arguments, a variable declared to receive the function
values must be exactly the same length as the value.

3.10

Calling a Library Routine in BLISS
This section describes how to code BLISS calls to library routines. A called
routine can return only one of the following:

3.10.1

•

No value.

•

A function value (typically, an integer or floating-point number). For
example, MTH$SIN returns its result as an F-floating value in RO.

•

A return status (typically, a 32-bit condition value) indicating that the
routine has either executed successfully or failed. For example,
LIB$GET_INPUT returns a return status in RO. If the routine executed
successfully, it returns SS$_NQRMAL; if not, it returns one of several
possible error condition values. BLISS treats the return status like any
other value.

BLISS Calling Sequence
Scalar arguments are usually passed to Run-Time Library routines by
reference. Thus, when a BLISS program passes a variable, it appears with
no preceding period in the procedure-call actual argument list. A constant
value can be easily passed using the %REF built-in function.
The following example shows how a BLISS program calls
LIB$PUT_OUTPUT. This routine writes a record at the user's terminal.
MODULE SHOWTIME(IDENT='1-1' %TITLE'Print time', MAIN=TIMEOUT)=
BEGIN
LIBRARY 'SYS$LIBRARY:STARLET'; ! Defines system services, etc.
MACRO
DESC[]=%CHARCOUNT(%REMAINING), ! VAX string descriptor
UPLIT BYTE(%REMAINING) %;
! definition
BIND
FMTDESC=UPLIT( DESC('At the tone, the time will be ,
%CHAR(7), '!%T' )) ;
EXTERNAL ROUTINE
LIB$PUT_OUTPUT: ADDRESSING_MODE(GENERAL);

3-20

How to Call Run-Time Library Procedures
3.10 Calling a Library Routine in BLISS

ROUTINE TIMEOUT
BEGIN
LOCAL
TIMEBUF: VECTOR[2],
MSGBUF: VECTOR[80,BYTE],
MSGDESC: BLOCK[8,BYTE],
RSLT: WORD;
!+
! Initialize the fields
!-

64-bit system time
Output message buff er
Descriptor for message buff er
Length of result string

of the string descriptor.

MSGDESC[DSC$B_CLASS]=DSC$K_CLASS_S;
MSGDESC[DSC$B_DTYPE]=DSC$K_DTYPE_T;
MSGDESC[DSC$W_LENGTH]=80;
MSGDESC[DSC$A_POINTER]=MSGBUF[O]
$GETTIM(TIMADR=TIMEBUF);

Get time as 64-bit integer

$FAOL(CTRSTR=FMTDESC,
OUTLEN=RSLT,
OUTBUF=MSGDESC,
PRMLST= %REF(TIMEBUF));

Format descriptor
Output length (only a word!)
! Output buffer desc.
Address of 64-bit
time block
MSGDESC [DSC$W_LENGTH] = .RSLT;
Modify output desc.
RETURN (LIB$PUT_OUTPUT(MSGDESC);
Return status
END;
END
ELUDOM

3.10.2 Accessing a Return Status in BLISS
BLISS accesses a function return value or condition value returned in RO as
follows:
STATUS= LIB$PUT_OUTPUT(MSG_DESC);
IF NOT .STATUS THEN LIB$STOP(.STATUS);

3.10.3 Calling JSB Entry Points from BLISS
Many of the library mathematics routines have JSB entry points. You can
efficiently invoke these routines from a BLISS procedure using LINKAGE and
EXTERNAL ROUTINE declarations as in the following example.
MODULE JSB_LINK (MAIN = MATH_JSB,
! Example of using JSB linkage
IDENT = '1-001' ,
ADDRESSING_MODE(EXTERNAL = GENERAL))
BEGIN
LINKAGE
LINK_MATH_R4 = JSB (REGISTER = 0; ! input reg
REGISTER= 0): ! output reg
NOPRESERVE (0,1,2,3,4)
NOTUSED (5,6,7,8,9,10,11);
EXTERNAL ROUTINE
MTH$SIND_R4
LINK_MATH_R4;
FORWARD ROUTINE
MATH_JSB;

3-21

How to Call Run-Time Library Procedures
3.10 Calling a Library Routine in BLISS

LIBRARY 'SYS$LIBRARY:STARLET.L32';
ROUTINE MATH_JSB =
BEGIN
LOCAL
INPUT_VALUE
SIN_VALUE;

Routine

INITIAL (%E'30.0'),

!+
! Get the sine of single floating 30 degrees. The input, 30 degrees,
! is passed in RO, and the answer, is returned in RO. Registers

! 0 to 4 are modified by MTH$SIND_R4.
!-

MTH$SIND_R4 (.INPUT_VALUE
RETURN SS$_NORMAL;
END;
END
ELUDOM

3-22

SIN_VALUE);
! End of

routine

End of module JSB_LINK

Index

A
Argument
characteristics of• 3-3, 3-6
passing mechanism• 2-21
VMS usage• 2-6

LIB$GET_INPUT• 3-3
LIB$SHOW _TIMER• 3-2
LIB$SIGNAL • 3-1

M
MTH$SIN_R4 • 3-5

c
Calling standard• 1-1 , 3-1
Condition value• 3-6, 3-15

D
Descriptor
class and data type• 3-1 O
fields of• 3-8

p
Passing mechanism• 2-24
by descriptor• 3-8
by reference • 3-7
by value • 3-7
for arrays • 3-10
for scalars• 3-9
for strings• 3-10

Function
definition of• 1-1
Function return value• 3-6

Routine
See also Entry point
See also Mathematics routine
definition of• 1-1
how to call• 1-19, 3-1, 3-2
Run-Time Library
capabilities of• 1-1
described • 1-1
organization of• 1-19
Run-Time Library routine
capabilities of• 1-18
defined • 1-1
entry point• 3-3, 3-4, 3-5
how to call• 1-19, 3-1, 3-2
linking with • 1-19

LIB$FLT_UNDER• 3-7

Shareable image• 1-19

Entry point• 3-4
CALL entry point• 3-3
JSB entry point• 3-5
Error• 3-15
returning condition value• 3-15
signaling condition value• 3-15

lndex-1

Index

u
User procedure• 3-1

v
VAX BLISS
using JSB entry point• 2-2
VAX MACRO
using JSB entry point• 2-2
VMS usage• 2-6

lndex-2

Reader's Comments

Introduction to the VMS
Run-Time Library
AA-LA 70A-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

--;;~';;~:d

Here and Ta~ ------------------~lllr-------~~~~v~---

in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE 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

111 ..... 11.11 .... 11 .... 1.11.1 .. 1.1 .. 1•• 1.1 ••• 1.11 .. 1
-- Do Not Tear - Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

.,""c
....

's
~

<II!