Index of /pdf/dec/vax/vms/5.0
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: Software Version:
This document supersedes Sections 1 and 2 of the VAX/VMS Run- Time Library Routines Reference Manual, Version 4.4.
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~DD5lDTM
ZK4608
HOW TO ORDER ADDITIONAL DOCUMENTATION DIRECT MAIL ORDERS
USA & PUERTO Rico*
Digital Equipment Corporation P.O. Box CS2008 Nashua, New Hampshire 03061
CANADA
Digital Equipment of Canada Ltd. 100 Herzberg Road Kanata, Ontario K2K 2A6 Attn: Direct Order Desk
INTERNATIONAL
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
PREFACE
CHAPTER 1 INTRODUCTION
1.1
ORGANIZATION OF THE RUN-TIME LIBRARY
1.2
FEATURES OF THE RUN-TIME LIBRARY
1.3
LINKING WITH THE RUN-TIME LIBRARY
CHAPTER 2 RUN-TIME LIBRARY DOCUMENTATION FORMAT
2.1
FORMAT HEADING
2.2 2.2.1 2.2.2
RETURNS HEADING Condition Values in RO Data in Registers RO Through R11
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.4 2.4.1 2.4.2
CONDITION VALUES RETURNED HEADING Condition Values Returned Condition Values Signaled
ix
1-1
1-1
1-18
1-19
2-1
2-2
2-4 2-4 2-5
2-5 2-6 2-21 2-23 2-24 2-26
2-27 2-28 2-28
v
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
RUN-TIME LIBRARY NAMING CONVENTIONS
3-4
3.3.1
Entry Point Names
3-5
3.3.2
JSB Entry Point Names
3-5
3.3.3
Function Return Values
3-6
3.3.4
Facility Return Status and Condition Value Symbols
3-6
3.3.5
Argument Passing Mechanisms
3-6
3.3.5.1
Passing Arguments by Value· 3-7
3.3.5.2
Passing Arguments by Reference · 3-7
3.3.5.3
Passing Arguments by Descriptor · 3-8
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
vi
Contents
INDEX
FIGURES
2-1 3-1
Routine Argument Passing Mechanisms Calling the Run-Time Library
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
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
2-25 3-2
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
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-74 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.
ix
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.
x
Preface
Conventions
Convention
CTRL/C
$SHOW TIME 05-JUN-1988 11 :55:22
$ TYPE MYFILE.DAT
input-file, ...
[logical-name]
quotation marks apostrophes
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.)
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.
In examples, system output (what the system displays) is shown in black. User input (what you enter) is shown in red.
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.
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.
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.)
The term quotation marks is used to refer to double quotation marks ( " ). The term apostrophe ( ' ) is used to refer to a single quotation mark.
xi
1 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$ LIB$
MTH$ OTS$ PPL$ SMG$ STR$
DECtalk routines that are used to control DIGITAL' s DECtalk device
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
Mathematics routines that perform arithmetic, algebraic, and trigonometric calculations
General purpose routines that perform tasks such as data type conversions as part of a compiler's generated code, and also some mathematical functions
Parallel processing routines that simplify subprocess creation, interprocess communication, and resource sharing for parallel applications
Screen management routines that are used in designing, composing, and keeping track of complex images on a video screen
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 DTK$ Facility Routines
Routine Name DTK$ANS\NER_PHONE
DTK$CHECK_HD\NR_STATUS DTK$DIAL _PHONE DTK$HANGUP_PHONE DTK$1NITIALIZE DTK$LOAD_DICTIONARY
DTK$READ_KEYSTROKE
Function
\Nait for the phone to ring and answer Check the hardware status Dial the telephone Hang up the phone Initialize the DECtalk device Load a word into the DECtalk dictionary Read a key entered on the phone keypad
1-2
Introduction
1 .1 Organization of the Run-Time Library
Table 1-2 (Cont.) DTK$ Facility Routines
Routine Name
Function
DTK$READ_STRING
DTK$RETURN _LAST_INDEX DTK$SET_INDEX DTK$SET_KEYP AD_MODE DTK$SET_LQGGING_MODE
DTK$SET_MQDE
DTK$SET_SPEECH _MQDE DTK$SET_ TERMINAL_MQDE
DTK$SET_VOICE DTK$SPEAK_FILE DTK$SPEAK_PHONEMIC_TEXT DTK$SPEAK_TEXT DTK$SPELL_TEXT DTK$TERMINA TE
Read a series of keys entered on the phone keypad Return the last index spoken Insert an index at the current position Turn the phone keypad on and off Set the specified logging mode on the DECtalk terminal Set the specified mode on the DECtalk terminal Turn the speech on and off Set the specified terminal mode on the DECtalk terminal Set the voice characteristics Speak text from the specified file Speak the specified phonemic text Speak the specified text Spell out the specified text 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
LIB$ADAWI LIB$ADD_TIMES LIB$ADDX
LIB$ANAL YZE_SDESC LIB$ASN_WTH_MBX LIB$AST_IN_PROG LIB$ATTACH LIB$BBCCI LIB$BBSSI LIB$CALLG
LIB$CHAR
LIB$CONVERT_DATE_STRING
Function
Add adjacent word with interlock Add two quadword times Add two multiple-precision binary numbers Analyze a string descriptor Assign a channel to a mailbox AST in progress Attach a terminal to a process Test and clear a bit with interlock Test and set a bit with interlock Call a procedure with a general argument list Transform a byte to the first character of a string Convert a date string to a quadword
1-3
Introduction
1 .1 Organization of the Run-Time Library
Table 1-3 (Cont.) LIB$ Facility Routines
Routine Name
Function
LIB$CRC
LIB$CRC_TABLE
LIB$CREA TE_DIR LIB$CREATE_USER_VM_ZONE LIB$CREATE_VM_ZONE LIB$CRF_INS_KEY
LIB$CRF_INS_REF
LIB$CRF_OUTPUT
LIB$CURRENCY LIB$CVT_DX_DX LIB$CVT_FROM_INTERNAL _TIME LIB$CVTF_FROM _INTERNAL_TIME
LIB$CVT_TO_INTERNAL_TIME LIB$CVTF_ TQ_INTERNAL_TIME
LIB$CVT_xTB LIB$CVT_VECTIM
LIB$DATE_TIME LIB$DAY
LIB$DAY_OF_WEEK LIB$DECODE_FAUL T
LIB$DEC_OVER
LIB$DELETE_FILE LIB$DELETE _LOGICAL LIB$DELETE_SYMBOL LIB$DELETE _ VM _ZONE LIB$DIGIT_SEP LIB$DISABLE_CTRL
LIB$DO_COMMAND LIB$EDIV
Calculate a Cyclic Redundancy Check (CRC)
Construct a Cyclic Redundancy Check (CRC) table
Create a directory Create a user-defined storage zone Create a new storage zone Insert a key in the cross-reference table Insert a reference to a key in the cross-reference table Output some cross-reference table information Get the system currency symbol Convert the specified data type Convert internal time to external time Convert internal time to external time (F-floating value) Convert external time to internal time Convert external time to internal time (F-floating value) Convert numeric text to binary
Convert 7-word vector to internal time Return the date and time as a string Return the day number as a longword integer Return the numeric day of the week Decode instruction stream during a fault Enable or disable decimal overflow detection Delete one or more files Delete a logical name Delete a CU symbol Delete a virtual memory zone Get the digit separator symbol Disable CU interception of control characters Execute the specified command Perform an extended-precision divide
1-4
Introduction
1.1 Organization of the Run-Time Library
Table 1-3 (Cont.) LIB$ Facility Routines
Routine Name
Function
LIB$EMODF
LIB$EMODD
LIB$EMODG
LIB$EMODH
LIB$EMUL
LIB$ENABLE_CTRL
LIB$ESTABLISH LIB$EXTV LIB$EXTZV LIB$FFx LIB$FID_TO_NAME
LIB$FILE _SCAN LIB$FILE_SCAN_END LIB$FIND_FILE LIB$FIND_FILE_END LIB$FIND_IMAGE_SYMBOL LIB$FIND_VM_ZONE LIB$FIXUP_FLT LIB$FL T_UNDER LIB$FORMAT_DATE_TIME LIB$FREE_DATE_TIME_CONTEXT
LIB$FREE_EF LIB$FREE_LUN LIB$FREE_ TIMER LIB$FREE_VM
LIB$FREE_VM_PAGE LIB$GETDVI LIB$GET JPI LIB$GETQUI LIB$GETSYI LIB$GET_COMMAND
Perform extended multiply and integerize for F-floating values Perform extended multiply and integerize for D-floating values Perform extended multiply and integerize for G-floating values Perform extended multiply and integerize for H-floating values Perform an extended-precision multiply Enable CU interception of control characters Establish a condition handler Extract a field and sign-extend Extract a zero-extended field Find the first clear or set bit Convert a device and file ID to a file specification Perform a file scan End of file scan Find a file End of find file Merge activate an image symbol Find the next valid zone Fix floating reserved operand Floating-point underflow detection Format a date and/or time Free the context used to format a date or time Free an event flag Free a logical unit number Free timer storage Free virtual memory from the program region Free a virtual memory page Get device/volume information Get job/process information Get queue information Get systemwide information Get line from SYS$COMMAND
1-5
Introduction
1.1 Organization of the Run-Time Library
Table 1-3 (Cont.) LIB$ Facility Routines
Routine Name
Function
LIB$GET_COMMON LIB$GET_DATE_FORMAT LIB$GET_EF LIB$GET_FOREIGN LIB$GET_INPUT LIB$GET_LUN LIB$GET_MAXIMUM_DATE_LENGTH
LIB$GET_SYMBOL LIB$GET_USERS_LANGUAGE LIB$GET_VM LIB$GET_VM_PAGE LIB$1CHAR
LIB$1NDEX LIB$1NIT_DATE_TIME_CONTEXT
LIB$1NIT_ TIMER LIB$1NSERT_ TREE LIB$1NSQHI LIB$1NSQTI LIB$1NSV LIB$1NT_OVER LIB$LEN
LIB$LOCC LIB$LOOKUP_KEY LIB$LOOKUP_TREE
LIB$LP_LINES
LIB$MATCHC
LIB$MATCH_COND LIB$MOVC3 LIB$MOVC5 LIB$MOVTC LIB$MOVTUC LIB$MULT_DELTA_TIME
Get string from common area Return the user's date input format Get an event flag Get foreign command line Get line from SYS$1NPUT Get logical unit number Get the maximum possible date/time string length Get the value of a CU symbol Return the user's language choice Allocate virtual memory Get a virtual memory page Convert first character of string to integer Index to relative position of substring Initialize the context used in formatting date/time strings Initialize times and counts Insert entry in a balanced binary tree Insert entry at the head of a queue Insert entry at the tail of a queue Insert a variable bit field Integer overflow detection Return the length of a string as a longword Locate a character Look up keyword in table Look up an entry in a balanced binary tree Specify the number of lines on each printer page Match characters, return relative position Match condition values Move characters Move characters with fill Move translated characters Move translated until character Multiply delta time by scalar
1-6
Introduction
1.1 Organization of the Run-Time Library
Table 1-3 (Cont.) LIBS Facility Routines
Routine Name
Function
LIB$MULTF_DELTA_TIME
LIB$PAUSE LIB$POLYF
LIB$POLYD
LIB$POLYG
LIB$POLYH
LIB$PUT_COMMON LIB$PUT_OUTPUT LIB$RADIX_POINT LIB$REMQHI LIB$REMQTI LIB$RENAME_FILE LIB$RESERVE_EF LIB$RESET_ VM _ZONE LIB$REVERT
LIB$RUN _PROGRAM LIB$SCANC
LIB$SCOPY_DXDX
LIB$SCOPY_R_DX
LIB$SET_LOGICAL LIB$SET_SYMBOL LIB$SFREE 1_DD LIB$SFREEN_DD LIB$SGET1_DD LIB$SHOW _TIMER LIB$SHOW_ VM LIB$SHOW_VM_ZONE
LIB$SIGNAL LIB$SIG_TO_RET
Multiply delta time by F-floating scalar Pause program execution Evaluate polynomials for F-floating values Evaluate polynomials for D-floating values Evaluate polynomials for G-floating values Evaluate polynomials for H-floating values Put string into common area Put line to SYS$0UTPUT Radix point symbol Remove entry from head of queue Remove entry from tail of queue Rename one or more files Reserve an event flag Reset virtual memory zone Revert to the handler of the procedure activator Run new program Scan for characters and return relative position Copy source string by descriptor to destination Copy source string by reference to destination Set logical name Set value of a CU symbol Free one or more dynamic strings Free n dynamic strings Get one dynamic string Show accumulated times and counts Show virtual memory statistics Display information about a virtual memory zone Signal exception condition 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
LIB$SIM_TRAP LIB$SKPC LIB$SPANC LIB$SPAWN LIB$STAT_TIMER
LIB$STAT_VM LIB$STOP
LIB$SUB_TIMES LIB$SUBX
LIB$SYS_ASCTIM
LIB$SYS_FAO
LIB$SYS_FAOL
LIB$SYS_GETMSG
LIB$TPARSE
LIB$TRA_ASC_EBC LIB$TRA _EBC_ASC LIB$TRAVERSE_TREE LIB$TRIM _FILESPEC
LIB$VERIFY_ VM_ZQNE LIB$WAIT
Convert a signaled condition to a signaled stop
Simulate floating trap
Skip equal characters
Skip selected characters
Spawn a subprocess
Return accumulated time and count statistics
Return virtual memory statistics Stop execution and signal the condition
Subtract two quadword times
Perform multiple-precision binary subtraction
Invoke $ASCTIM to convert binary time to ASCII
Invoke $FAQ system service to format output
Invoke $FAOL system service to format output
Invoke $GETMSG system service to get message text
Implement a table-driven, finite-state parser
Translate ASCII to EBCDIC Translate EBCDIC to ASCII
Traverse a balanced binary tree
Fit long file specification into fixed field
Verify a virtual memory zone 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 MTH$xACOSD MTH$xASIN MTH$xASIND MTH$xATAN MTH$xATAND MTH$xATAN2 MTH$xAT AND2 MTH$xATANH MTH$CxABS MTH$CCOS MTH$CxCOS MTH$CEXPP MTH$CxEXP
MTH$CLOG MTH$CxLOG
MTH$CMPLX MTH$xCMPLX MTH$CONJG
MTH$xCONJG
MTH$xCOS MTH$xCOSD MTH$xCOSH MTH$CSIN
MTH$CxSIN
MTH$CSORT MTH$CxSORT
MTH$CVT_x_x MTH$CVT_xA_xA MTH$xEXP
Return arc cosine of angle expressed in radians 1 Return arc cosine of angle expressed in degrees 1 Return arc sine in radians 1 Return arc sine in degrees 1 Return arc tangent in radians 1 Return arc tangent in degrees 1 Return arc tangent in radians with two arguments 1 Return arc tangent in degrees with two arguments 1 Return hyperbolic arc tangent 1 Return complex absolute value2
Return complex cosine (F-floating complex value)
Return complex cosine (D- and G-floating complex values) Return complex exponential (F-floating complex value)
Return complex exponential (D- and G-floating complex values)
Return complex natural logarithm (F-floating complex value)
Return complex natural logarithm (D- and G-floating complex values)
Return complex number made from F-floating point values
Return complex number made from D- and G-floating values Return conjugate of a complex number (F-floating point complex value)
Return conjugate of a complex number (D- and G-floating complex values) Return cosine of angle expressed in radians 1 Return cosine of angle expressed in degrees 1 Return hyperbolic cosine 1
Return complex sine of complex number (F-floating complex value)
Return complex sine of complex number (D- and G-floating complex values)
Return complex square root (F-floating point value)
Return complex square root (D- and G-floating complex values)
Convert one double-precision value
Convert an array of double-precision values 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
1-10
Table 1-4 (Cont.) MTH$ Facility Routines
Routine Name
Function
MTH$HACOS MTH$HACOSD MTH$HASIN MTH$HASIND MTH$HATAN MTH$HATAND MTH$HATAN2
MTH$HATAND2
MTH$HATANH MTH$HCOS
MTH$HCOSD
MTH$HCOSH MTH$HEXP MTH$HLOG MTH$HLOG2 MTH$HLOG10 MTH$HSIN
MTH$HSIND
MTH$HSINH MTH$HSQRT MTH$HTAN
MTH$HTAND
MTH$HTANH MTH$xlMAG MTH$xLOG MTH$xLOG2 MTH$xLOG10 MTH$RANDOM MTH$xREAL
Return arc cosine in radians (H-floating point value) Return arc cosine in degrees (H-floating point value) Return arc sine in radians (H-floating point value) Return arc sine in degrees (H-floating point value) Return arc tangent in radians (H-floating point value) Return arc tangent in degrees (H-floating point value) Return arc tangent in radians (H-floating point) with two arguments Return arc tangent in degrees (H-floating point) with two arguments Return hyperbolic arc tangent (H-floating point value) Return cosine of angle expressed in radians (H-floating point value) Return cosine of angle expressed in degrees (H-floating point value) Return hyperbolic cosine (H-floating point value) Return exponential (H-floating point value) Return natural logarithm (H-floating point value) Return base two logarithm (H-floating point value) Return common logarithm (H-floating point value) Return sine of angle expressed in radians (H-floating point value) Return sine of angle expressed in degrees (H-floating point value) Return hyperbolic sine (H-floating point value) Return square root (H-floating point value) Return tangent of angle expressed in radians (H-floating point value) Return tangent of angle expressed in degrees (H-floating point value) Compute the hyperbolic tangent (H-floating point value) Return imaginary part of a complex number2 Return the natural logarithm 1 Return base two logarithm 1 Return common logarithm 1 Generate a random number with uniform distribution Return real part of a complex number2
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.
Introduction
1 .1 Organization of the Run-Time Library
Table 1-4 (Cont.) MTH$ Facility Routines
Routine Name
MTH$xSIN MTH$xSINCOS MTH$xSINCOSD MTH$xSIND MTH$xSINH MTH$xSQRT MTH$xTAN MTH$xTAND MTH$xTANH MTH$UMAX MTH$UMIN
Function
Return sine of angle expressed in radians 1 Return sine and cosine of angle expressed in radians3 Return sine and cosine of angle expressed in degrees3 Return sine of angle expressed in degrees 1 Return hyperbolic sine 1 Return square root 1 Return tangent of angle expressed in radians 1 Return tangent of angle expressed in degrees1 Compute the hyperbolic tangent 1
Compute the unsigned maximum
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
OTS$CVT_L_TB OTS$CVT_L_Tl OTS$CVT_L_TL OTS$CVT_L_TO OTS$CVT_L_TU OTS$CVT_L_TZ OTS$CVT_TB_L OTS$CVT_Tl_L OTS$CVT_TL_L OTS$CVT_TQ_L OTS$CVT_TU_L OTS$CVT_T_z OTS$CVT_ T_x OTS$CVT_TZ_L OTS$DIVCx
Convert D-floating, G-floating, or H-floating to character string Convert unsigned integer to binary text Convert signed integer to signed integer text Convert integer to logical text Convert unsigned integer to octal text Convert unsigned integer to decimal text Convert integer to hexadecimal text Convert binary text to unsigned integer Convert signed integer text to integer Convert logical text to integer Convert octal text to integer Convert unsigned decimal text to integer Convert numeric text to D- or F-floating value Convert numeric text to G- or H-floating value Convert hexadecimal text to unsigned longword 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 OTS$01V_PK_SHORT OTS$MOVE3 OTS$MOVE5 OTS$MULCx OTS$POWCxCx
OTS$POWCxJ
OTS$POWOO OTS$POWOR OTS$POWOJ OTS$POWGx
OTS$POWGJ OTS$POWHx OTS$POWHJ OTS$POWll OTS$POWHJJ OTS$POWLULU
OTS$POWxLU
OTS$POWRO OTS$POWRR OTS$POWRJ OTS$SCOPY_OXOX
OTS$SCOPY_R_OX
OTS$SFREE 1_00 OTS$SFREEN _OO OTS$SGET1_00
Perform packed decimal division with long divisor Perform packed decimal division with short divisor Move data without fill Move data with fill Perform complex multiplication Raise a complex base to a complex floating-point exponent Raise a complex base to a signed longword exponent Raise a 0-floating base to a 0-floating exponent Raise a 0-floating base to an F-floating exponent Raise a 0-floating base to a longword exponent Raise a G-floating base to a G-floating or longword exponent Raise a G-floating base to a longword exponent Raise an H-floating base to floating-point exponent Raise an H-floating base to a longword exponent Raise a word base to a word exponent Raise a longword base to a longword exponent Raise an unsigned longword base to an unsigned longword exponent Raise a floating-point base to an unsigned longword exponent Raise an F-floating base to a 0-floating exponent Raise an F-floating base to an F-floating exponent Raise an F-floating base to a longword exponent Copy a source string passed by descriptor to a destination string Copy a source string passed by reference to a destination string Free one dynamic string Free n dynamic strings 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 PPL$A W A IT_EVENT PPL$CREATE_BARRIER PPL$CREA TE_EVENT PPL$CREATE_SEMAPHORE PPL$CREATE _SHARED_MEMORY PPL$CREATE_SPIN_LQCK PPL$CREATE_VM_ZQNE PPL$DECREMENT_SEMAPHORE
PPL$DELETE_SHARED_MEMORY PPL$ENABLE_EVENT_AST PPL$ENABLE _EVENT_SIGNAL PPL$FIND_SYNCH_ELEMENT_ID PPL$FLUSH _SHARED_MEMORY PPL$GET_INDEX PPL$1NCREMENT_SEMAPHORE
PPL$1NDEX _ TQ_PID PPL$1NITIALIZE PPL$PID_TQ_INDEX PPL$RELEASE _SPIN _LOCK PPL$READ_SEMAPHORE
PPL$SEIZE_SPIN_LOCK PPL$SET_QUORUM PPL$SPAWN PPL$STOP PPL$TERMINA TE PPL$TRIGGER_EVENT PPL$UNIOUE _NAME PPL$WAIT_AT_BARRIER
Adjust the barrier quorum Await the occurrence of an event Create a barrier Create an event Create a semaphore Create shared memory Create a spin lock Create a new virtual memory zone Decrement a semaphore to gain access to a resource Delete shared memory Enable AST notification of an event Enable signal notification of an event Find the synchronization element identifier Flush shared memory Get the index of a participant Increment a semaphore to release a resource Convert a participant-index to a VMS PID Initialize the PPL$ facility Convert a VMS PIO to a participant-index Release a spin lock Read the values associated with a particular semaphore Seize a spin lock Set the barrier quorum Initiate parallel execution Stop a participant Terminate PPL$ participation Trigger an event Provide a unique name 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
Routine Name
Function
SMG$ADD_KEY_DEF SMG$BEGIN_DISPLA V_ U P D A T E SMG$BEGIN_PASTEBOARD_UPDATE
SMG$CANCEL _INPUT SMG$CHANGE_PBD_CHARACTERISTICS SMG$CHANGE_RENDITION SMG$CHANGE_VIEWPORT
SMG$CHANGE_VIRTUAL_DISPLAY SMG$CHECK_FQR_OCCLUSION SMG$CONTROL_MODE SMG$COPY_ VIRTUAL_DISPLAY SMG$CREATE_KEY_TABLE SMG$CREA TE_MENU SMG$CREATE_PASTEBOARD SMG$CREATE_SUBPROCESS SMG$CREATE_VIEWPORT SMG$CREATE_VIRTUAL _DISPLAY SMG$CREATE_VIRTUAL_KEYBOARD SMG$CURSOR_CQLUMN SMG$CURSOR_RQW SMG$DEFINE_KEY SMG$DEL_TERM_TABLE SMG$DELETE_CHARS SMG$DELETE_KEY_DEF SMG$DELETE_LINE SMG$DELETE _MENU SMG$DELETE _PASTEBOARD SMG$DELETE_SUBPROCESS SMG$DELETE_VIEWPORT SMG$DELETE_VIRTUAL _DISPLAY SMG$DELETE_VIRTUAL _KEYBOARD SMG$DISABLE_BROADCAST_TRAPPING
SMG$DISABLE_UNSOLICITED_INPUT
SMG$DRAW _CHAR SMG$DRAW _LINE
Add a key definition Begin batching of display updates Begin batching of pasteboard updates Cancel input request Change pasteboard characteristics Change default rendition Change a viewport associated with a virtual display Change a virtual display Check for occlusion Control mode Copy a virtual display Create a key table Create a menu in a virtual display Create a pasteboard Create and initialize a subprocess Create a virtual viewport Create a virtual display Create a virtual keyboard Return the cursor column position Return the cursor row position Perform a DEFINE/KEY command Delete a terminal table Delete the specified characters Delete a key definition Delete a line Delete a menu Delete a pasteboard Terminate a subprocess Delete a viewport Delete a virtual display Delete a virtual keyboard Disable the trapping of broadcast messages Disable the trapping of unsolicited input Draw the specified character Draw a line
1-14
Introduction
1 .1 Organization of the Run-Time Library
Table 1-7 (Cont.) SMG$ Facility Routines
Routine Name
Function
SMG$DRAW _RECTANGLE SMG$ENABLE_UNSOLICITED_INPUT
SMG$END_DISPLA V_UPDATE SMG$END_PASTEBOARD_UPDATE
SMG$ERASE_CHARS SMG$ERASE_COLUMN SMG$ERASE_DISPLA Y SMG$ERASE_LINE SMG$ERASE_PASTEBOARD SMG$EXECUTE_COMMAND
SMG$FIND_CURSOR_DISPLA Y
SMG$FLUSH_BUFFER SMG$GET_BROADCAST_MESSAGE SMG$GET_CHAR_AT_PHYSICAL_ CURSOR SMG$GET_DISPLA V_ A TTR SMG$GET_KEY_DEF SMG$GET_KEYBOARD_ATTRIBUTES SMG$GET_NUMERIC_DAT A SMG$GET_P ASTEBOARD_A TTRIBUTES SMG$GET_PASTING_INFO SMG$GET_TERM_DATA SMG$GET_ VIEWPORT_CHAR
SMG$HOME_CURSOR SMG$1NIT_TERM_TABLE SMG$1NIT_TERM_TABLE_BV_TYPE
SMG$1NSERT_CHARS SMG$1NSERT_LINE SMG$1NV ALIDATE_DISPLAY SMG$KEYCODE_TO_NAME SMG$LABEL _BORDER SMG$LIST_KEY_DEFS SMG$LIST_PASTING_ORDER SMG$LOAD_KEY_DEFS
Draw a rectangle Enable the trapping of unsolicited input End the batching of display updates End the batching of pasteboard updates Erase the specified characters Erase a column from the display Erase a virtual display Erase a line from the display Erase a pasteboard Execute the specified command in a subprocess Find the virtual display that contains the cursor Flush the buffer Get the broadcast message Return the character at the cursor
Get the display attributes Get the key definition Get the keyboard attributes Get the numeric data Get the pasteboard attributes Get the display pasting information Get the terminal data Get the characteristics of the display view port Home the cursor Initialize the terminal table Initialize TERMTABLE by VMS terminal type Insert the specified characters Insert a line Mark a virtual display as invalid Translate a key code to a key name Label a virtual display border List key definitions List the display pasting order Load key definitions
1-15
Introduction
1.1 Organization of the Run-Time Library
Table 1-7 (Cont.) SMG$ Facility Routines
Routine Name
Function
SMG$LOAD_VIRTUAL _DISPLAY SMG$MOVE_TEXT S M G $ M O V E _VIRTUAL_DISPLA Y SMG$NAME_TO_KEYCODE SMG$PASTE_VIRTUAL_DISPLAY SMG$POP_VIRTUAL _DISPLAY SMG$PRINT_PASTE BOARD
SMG$PUT_CHARS SMG$PUT_CHARS_HIGHWIDE
SMG$PUT_CHARS_MUL Tl
SMG$PUT_CHARS_WIDE SMG$PUT_HELP_TEXT SMG$PUT_LINE SMG$PUT_LINE _HIGHWIDE
SMG$PUT_LINE _MULTl
SMG$PUT_LINE_WIDE SMG$PUT_PASTEBOARD SMG$PUT_ST ATUS_LINE
SMG$READ_COMPOSED_LINE SMG$READ_FROM_DISPLA Y SMG$READ_KEYSTROKE SMG$READ_STRING SMG$READ_VERIFY SMG$REMOVE_LINE SMG$REPAINT_LINE
SMG$REPAINT_SCREEN SMG$REPASTE_VIRTUAL _DISPLAY SMG$REPLACE_INPUT_LINE SMG$RESTORE_PHYSICAL _SCREEN SMG$RETURN_CURSOR_POS SMG$RETURN _INPUT_LINE SMG$RING_BELL SMG$SAVE _PHYSICAL _SCREEN
Load a virtual display from a file Move the specified text Move a virtual display Translate a key name to a key code Paste a virtual display Delete a series of virtual displays Print the pasteboard using a print queue Write characters to a virtual display Write double-height, double-width characters Put text with multiple renditions to the display Write wide characters Output HELP text to a display Write lines to a virtual display Write double-height, double-width line Put text with multiple renditions to a display in line mode Write a double-width line Output pasteboard via routine Output a line of text to the hardware status line Read a composed line Read text from a display Read a single character Read a string Read and verify a string Remove a line from a virtual display Repaint one line on the current screen Repaint the current screen Repaste the virtual display Replace the input line Restore the physical screen Return the cursor position Return the input line Ring the terminal bell or buzzer Save the physical screen
1-16
Introduction
1 .1 Organization of the Run-Time Library
Table 1-7 (Cont.) SMGS Facility Routines
Routine Name
Function
SMG$SAVE_VIRTUAL_DISPLAY SMG$SCROLL _DISPLAV_AREA SMG$SCROLL _ VIEWPORT SMG$SELECT_FROM_MENU SMG$SET_BROADCAST_TRAPPING
SMG$SET_CURSOR_ABS SMG$SET_CURSOR_MODE SMG$SET_CURSOR_REL
SMG$SET_DEFAULT_ST ATE SMG$SET_DISPLAY_SCROLL _REGION SMG$SET_KEYPAD_MODE SMG$SET_OUT_OF_BAND_ASTS
SMG$SET_PHYSICAL _CURSOR SMG$SET_ TERM_CHARACTERISTICS SMG$SNAPSHOT SMG$UNPASTE_VIRTUAL _DISPLAY
Save the virtual display to a file Scroll the display area Scroll a display under a viewport Select an item from a menu Enable the trapping of broadcast messages Set absolute cursor position Turn the physical cursor on or off Set the cursor relative to the current position Set the default state Create a display scrolling region Set the keypad mode Establish an AST routine for out-ofband characters Set the cursor on the physical screen Change the terminal characteristics Write a snapshot of the pasteboard 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 STR$ANALYZE_SDESC STR$APPEND STR$CASE_BLIND_COMP ARE STR$COMP ARE STR$COMP ARE _EQL STR$COMPARE_MULTl
STR$CONCAT STR$COPY_DX
STR$COPY_R
Add two decimal strings Analyze a string descriptor Append a string Compare strings without regard to case Compare two strings Compare two strings for equality Compare two strings for equality using the DEC Multinational Character Set Concatenate two or more strings Copy a source string passed by descriptor to a destination string 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.) STR$ Facility Routines
Routine Name
Function
STR$DIVIDE STR$DUPL_CHAR STR$ELEMENT STR$FIND_FIRST_IN _SET
STR$FIND_FIRST_NQT_IN _SET
STR$FIND_FIRST_SUBSTRING STR$FREE1_DX STR$GET1_DX STR$LEFT STR$LEN_EXTR STR$MATCH_WILD STR$MUL STR$POSITION STR$POS_EXTR STR$PREFIX STR$RECIP STR$REPLACE STR$RIGHT STR$ROUND STR$TRANSLA TE STR$TRIM STR$UPCASEL ·
Divide two decimal strings Duplicate character n times Extract delimited element substring Find the first character in a set of characters Find the first character that does not occur in the set Find the first substring in the input string Free one dynamic string Allocate one dynamic string Extract a substring of a string Extract a substring of a string Match a wildcard specification Multiply two decimal strings Return relative position of a substring Extract a substring of a string Prefix a string Return the reciprocal of a decimal string Replace a substring Extract a substring of a string Round or truncate a decimal string Translate matched characters Trim trailing blanks and tabs Corvert string to all uppercase
1 .2 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.
· 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.
1-18
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
2 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 Routine overview Format
Returns Arguments
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.
Required. The routine overview appears directly below the routine name. The overview explains, usually in one or two sentences, what the routine does.
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.
Required. The returns heading follows the routine format. It explains what information is returned by the routine.
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
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.
Condition Values Returned
Example
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.
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.
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.
2.1
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
arg 1 ,arg2 ,[arg3] ,nullarg [,arg4] [,arg5]
2-2
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: type: access: mechanism:
cond_value longword (unsigned) write only 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".)
2-4
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:
type:
access: mechanism:
yyyyyyyy xxxxxxxx
write only 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: type: access: mechanism:
VMS-usage-type argument-data-type argument-access 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 access_mode address address_range arg_list
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.
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.
Unsigned longword denoting the virtual memory address of either data or code, but not of a procedure entry mask (which is of type "procedure").
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.
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.) VMS Data Structures
Data Structure
Definition
ast_procedure boolean byte_signed byte_unsig ned channel char_string
complex_number
lN
ARG 1
ARG 2
·
· ·
N ARG
ZK-4204-85
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" .)
Unsigned longword denoting a Boolean truth value flag. This longword may have only two values: 1 (true) and 0 (false).
This VMS data type is the same as the data type ubyte (signed)"in Table 2-3.
This VMS data type is the same as the data type ubyte integer (unsigned)" in Table 2-3.
Unsigned word integer that is an index to an 1/0 channel.
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 "X"
0 :A
"Y"
: A+1
"Z"
:A+2
ZK-4202-85
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.) VMS Data Structures
Data Structure
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
0
REAL { S EXPONENT FRACTION : A
PART
FRACTION
: A+2
IMAGINARY { 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
0
S lEXPONENTJ FRACTION :A
REAL PART
FRACTION FRACTION
:A+2 :A+4
FRACTION
:A+6
sIEXPONENTlFRACTION :AB
IMAGINARY PART
FRACTION FRACTION
: A+10 : 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
sI I 15 14
4 3
0
EXPONENT
FRACTION :A
REAL PART
FRACTION FRACTION
:A+2 :A+4
FRACTION
:A+6
sl l EXPONENT
FRACTION :AB
IMAGINARY PART
FRACTION FRACTION
: A+10 : 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
28 27
3 2
0
"- ,______ cntrl
condition identification
severity
--..~!~------~.../~
Is I
I 27
16 15
3
facility number message number
context date_time
ZK-1795-84
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.
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 ef_cluster_name ef_number exit _handler_block
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.
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.
Unsigned longword integer denoting the number of an event flag. Local event flags numbered 32 to 63 are available to your programs.
Variable-length structure denoting an exit handler control block. This control block, which describes the exit handler, is depicted in the following diagram.
31
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
r
ZK-1714-84
fab
Structure denoting an RMS file access block.
A complete description of this structure is
contained in the VMS Record Management
Services Manual.
2-10
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 8 7 6 5 4 3 2
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
0
SlEXPONENTl FRACTION : A
FRACTION 31
: 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.) VMS Data Structures
Data Structure
Definition
15 14
7 6
0
sJEXPONENTI FRACTION : A
FRACTION
:A+2
FRACTION
:A+4
FRACTION
:A+6
63
48
ZK-4198-85
The structure of a G-floating number is as follows:
15 14
4 3
0
sl EXPONENT lFRACTION :A
FRACTION
:A+2
FRACTION
:A+4
FRACTION
:A+6
63
48
ZK-4199-85
The structure of an H-floating number is as follows:
15 14
sl EXPONENT
0
:A
FRACTION
:A+2
FRACTION
:A+4
FRACTION
:A+6
FRACTION
:A+8
FRACTION
:A+10
FRACTION
: A+12
FRACTION 127
: 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 io_status_block
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.
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.
31
16 15
0
count
condition value
item_lisL2
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.
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
Data Structure
Definition
31
15
0
item code
I
component length
component address
ZK-1709-84
item _list _3
31 item code
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.
Structure that consists of one or more item descriptors and that is terminated by a longword containing 0. Each item descriptor is a 3-longword structure that contains four fields. The following diagram depicts the format of a single item descriptor.
15
0
I
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.) VMS Data Structures
Data Structure
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.
item _quota_list
lock_id lock_status_block
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.
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.
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.
Structure into which the lock manager facility writes status information about a lock. A lock status block always contains at least two longwords: the first word of the first longword contains a condition value; the second word of the first longword is reserved to DIGITAL; and the second longword contains the lock identifier.
The lock status block receives the final condition value and the lock identification, and optionally contains a lock value block. When a request is queued, the lock identification is stored in the lock status block even if the lock has not been granted. ,This allows a procedure to dequeue locks that have not been granted.
The condition value is placed in the lock status block only when the lock is granted (or when errors occur in granting the lock).
The following diagram depicts a lock status block that includes the optional 16-byte lock value block.
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_VALBLK is set)
ZK-376-81
lock_value_block
logical_name
longword_signed longword_unsigned mask_byte mask_longword mask_quadword mask_word
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.
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".
This VMS data type is the same as the data type "longword integer (signed)" in Table 2-3.
This VMS data type is the same as the data type "longword (unsigned)" in Table 2-3.
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".
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".
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".
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".
2-16
Run-Time Library Documentation Format
2.3 Arguments Heading
Table 2-2 (Cont.) VMS Data Structures
Data Structure null_arg
octaword_signed octaword_unsigned page_protection
Definition
Unsigned longword denoting a "null argument." A "null argument" is an argument whose only purpose is to hold a place in the argument list.
This VMS data type is the same as the data type "octaword integer (signed)" in Table 2-3.
This VMS data type is the same as the data type "octaword (unsigned)" in Table 2-3.
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 PRT$C_KR PRT$C_KW PRT$C_ER PRT$C_EW PRT$C_SR PRT$C_SW PRT$C_UR PRT$C_UW PRT$C_ERKW
PRT$C_SRKW
PRT$C_SREW
PRT$C_URKW PRT$C_UREW PRT$C_URSW
No access Kernel read only Kernel write Executive read only Executive write Supervisor read only Supervisor write User read only User write Executive read; kernel write Supervisor read; kernel write Supervisor read; executive write User read; kernel write User read; executive write User read; supervisor write
procedure
If the protection is specified as 0, the protection defaults to kernel read-only.
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 process_id
process_name quadword_signed quadword_unsigned rights_holder
Definition
Unsigned longword integer denoting a process identifier (PIO). This process identifier is assigned by VMS to a process when the process is created.
Character string, containing 1 to 15 characters, that specifies the name of a process.
This VMS data type is the same as the data type "quadword integer (signed)" Table 2-3.
This VMS data type is the same as the data type "quadword (unsigned)" in Table 2-3.
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.) VMS Data Structures
Data Structure
Definition
rights_id
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.
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
I I group
0 member
UIC Format
ZK-1905-84
Bit 31, set to 1, specifies ID format. Bits 30 through 28 are reserved by DIGITAL. The remaining bits specify the identifier value.
31
j 1000
0 identifier
ID Format
ZK-1906-84
2-19
Run-Time Library Documentation Format
2.3 Arguments Heading
Table 2-2 (Cont.) VMS Data Structures
Data Structure
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.
rab section_id section _name
system _access_id time_name uic user_arg
varying_arg
An identifier name consists of 1 to 31 alphanumeric characters and contains at least one nonnumeric character. An identifier name cannot consist entirely of numeric characters. It can include the characters A through Z, dollar signs ($) and underscores (_), as well as the numbers 0 through 9. Any lowercase characters are automatically converted to uppercase.
Structure denoting an RMS record access block. A complete description of this structure is contained in the VMS Record Management Services Manual.
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.
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.
Unsigned quadword that denotes a system identification value that is to be associated with a rights database.
Character string specifying a time value in VMS format.
Unsigned longword denoting a user identification code (UIC).
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.
Unsigned longword denoting a variable argument. A variable argument can have variable types, depending on specifications made for other arguments in the call.
2-20
2.3.2 Type Entry
Run-Time Library Documentation Format
2.3 Arguments Heading
Table 2-2 (Cont.) VMS Data Structures
Data Structure
Definition
vector_byte_signed vector_byte_unsigned vector_longword_signed vector_longword_unsigned vector_quadword_signed vector_quadword_unsigned vector_word_signed vector_word_unsigned word_signed word_unsigned
A homogeneous array whose elements are all signed bytes.
A homogeneous array whose elements are all unsigned bytes.
A homogeneous array whose elements are all signed longwords.
A homogeneous array whose elements are all unsigned longwords.
A homogeneous array whose elements are all signed quadwords.
A homogeneous array whose elements are all unsigned quadwords.
A homogeneous array whose elements are all signed words.
A homogeneous array whose elements are all unsigned words.
This VMS data type is the same as the data type "word integer (signed)" in Table 2-3.
This VMS data type is the same as the data type "word (unsigned)" in Table 2-3.
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
Absolute date and time Byte integer (signed) Bound label value Bound procedure value Byte (unsigned) COBOL intermediate temporary
Symbolic Code
DSC$K_DTYPE_ADT DSC$K_DTYPE_B DSC$K_DTYPE_BLV DSC$K_DTYPE_BPV DSC$K_DTYPE_BU DSC$K_DTYPE_CIT
2-21
Run-Time Library Documentation Format
2.3 Arguments Heading
Table 2-3 (Cont.) VAX Data Types
Data Type
D_floating D_floating complex Descriptor F_floating F_floating complex G_floating G_floating complex H_floating H_floating complex Longword integer (signed) Longword (unsigned) Numeric string, left separate sign Numeric string, left overpunched sign Numeric string, right separate sign Numeric string, right overpunched sign Numeric string, unsigned Numeric string, zoned sign Octaword integer (signed) Octaword (unsigned) Packed decimal string Quadword integer (signed) Quadword (unsigned) Character string Aligned bit string Varying character string Unaligned bit string Word integer (signed) Word (unsigned) Unspecified Procedure entry mask Sequence of instruction
Symbolic Code DSC$K_DTYPE_D DSC$K_DTYPE_DC DSC$K_DTYPE_DSC DSC$K_DTYPE_F DSC$K_DTYPE_FC DSC$K_DTYPE_G DSC$K_DTYPE_GC DSC$K_DTYPE_H DSC$K_DTYPE_HC DSC$K_DTYPE_L DSC$K_DTYPE_LU DSC$K_DTYPE_NL DSC$K_DTYPE_NLO DSC$K_DTYPE_NR DSC$K_DTYPE_NRO DSC$K_DTYPE_NU DSC$K_DTYPE_NZ DSC$K_DTYPE_O DSC$K_DTYPE_OU DSC$K_DTYPE_P DSC$K_DTYPE_Q DSC$K_DTYPE_QU DSC$K_DTYPE_T DSC$K_DTYPE_V DSC$K_DTYPE_VT DSC$K_DTYPE_VU DSC$K_DTYPE_W DSC$K_DTYPE_WU DSC$K_DTYPE_Z DSC$K_DTYPE_ZEM DSC$K_DTYPE_ZI
2-22
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.
1 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.
2 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.
3 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
· Function call (before return)
· JMP after unwind
· Call after stack unwind
· Call without stack unwind
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.
1 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.
2 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.
3 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.
2-24
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
IN ARG 1
(AP) (a) ARGUMENT PASSED BY VALUE
ARG 2
ACTUAL VALUE
ARG N
N ARG 1
(AP) (b) ARGUMENT PASSED BY REFERENCE
ARG 2
POINTER TO ACTUAL VALUE
ARG N
N ARG 1
(AP) (c) ARGUMENT PASSED BY DESCRIPTOR
ARG 2
POINTER TO DESCRIPTOR
CLASS D TYPE LENGTH
ARG N
POINTER
DATA
T
I H
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
By value 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
Descriptor Code
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
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."
2 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
2.4
· 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.
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
3 How to Call Run-Time Library Procedures
3.1
Overview
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.
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
USER PROCEDURE
--------
CALL
RETURN
'
I
I
?IP"RLoIBcRrAouR"YR~II
I
I
I CALL
RETURN
·
MAIN PROGRAM (A USER PROCEDURE)
RETURN
t
ZK-4262-85
· 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.
3.2
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.
· 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.
3-2
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 = LIB$GET_INPUT (GET_STR,PROMPT,LENGTH) STAT = LIB$GET_INPUT (GET_STR,PROMPT) STAT = LIB$GET_INPUT (GET_STR,PROMPT,) STAT = LIB$GET_INPUT (GET_STR,,LENGTH) STAT = LIB$GET_INPUT (GET_STR) STAT = LIB$GET_INPUT (GET_STR,) STAT = 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
3.3
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_STATUS := 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:
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:
DTK$ LIB$ MTH$ OTS$ PPL$ SMG$ STR$
DECtalk routines Library routines Mathematics routines General purpose routines Parallel processing routines Screen management routines String handling routines
3.3.2
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
abc mno xyz
The 2- or 3-letter facility symbol The first three letters of the first word of the associated message The first three letters of the next word 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.
SS$_NORMAL LIB$_1NSVIRMEM MTH$_FLOOVEMA T OTS$_FATINTERR
LIB$_SCRBUFOVF
Routine successfully completed Insufficient virtual memory Floating overflow in mathematics library procedure Fatal internal error in a language-independent support procedure Screen buffer overflow
3.3.5
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 #SS$_INTOVF
; Push longword by value
CALLS #1, G-LIB$SIGNAL ; 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 1
Longword value 1
PUSHAL ONE CALLS #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
DSC$B_DTYPE DSC$B_CLASS DSC$A_POINTER
Length of data (or DSC$W_MAXSTRLEN, maximum length, for varying strings) Data type Descriptor class code 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 COMMON STRING GREETING = 30
200 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
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
3-8
How to Call Run-Time Library Procedures
3.3 Run-Time Library Naming Conventions
3.4
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
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 3.6
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.
Passing Strings as Arguments
Strings are passed by descriptor to Run-Time Library routines. The Run-Time Library routine recognizes the following descriptors:
Descriptor
Unspecified Fixed-length Dynamic Array Scaled decimal Noncontiguous array Varying-length
Descriptor Class Code
DSC$K_CLASS_Z DSC$K_CLASS_S DSC$K_CLASS_D DSC$K_CLASS_A DSC$K_CLASS_SD DSC$K_CLASS_NCA DSC$K_CLASS_VS
Numeric Value 0
2 4 9 10 11
A Run-Time Library routine writes strings according to the following three types of semantics:
· 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
3.7 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_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
= 26 = 10 = 11 = 27 = 28 = 12 = 13 = 29 = 30 = 31
_s = 1
Yes Yes Yes Yes Yes Yes Yes Yes Yes
_o = 2
-
_v = 3
-
-
-
_A
= 4
Yes Yes Yes Yes Yes Yes Yes Yes Yes
DSC$K_CLASS
_p _SD _NCA
= 5 = 9 = 10
-
Yes Yes
Yes
Yes Yes
Yes
Yes Yes
Yes
Yes Yes
Yes
Yes Yes
Yes
-
Yes
Yes
-
Yes
Yes
-
Yes
-
-
-
-
-
Yes
_vs = 11
-
_VSA
= 12
-
_UBS
= 13
-
_URA
= 14
-
-
Yes
Yes
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
_BFA
= 191
Yes 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 _p _SD _NCA _vs = 1 = 2 = 3 = 4 = 5 = 9 = 10 = 11
DSC$K_DTYPLZ
= 0 Yes
-
-
Yes
-
-
Yes
-
= DSC$K_DTYPLBU
2 Yes
-
-
Yes Yes
-
Yes
-
= D S C $ K _ D T Y P L W U
3 Yes
-
-
Yes
-
-
Yes
-
= DSC$K_DTYPLLU
4 Yes
-
-
Yes
-
-
Yes
-
= DSC$K_DTYPLQU
5 Yes
-
-
Yes
-
-
Yes
-
= DSC$K_DTYPLOU
25 Yes
-
-
Yes
-
-
Yes
-
DSC$K_DTYPLB
= 6 Yes
-
-
Yes Yes
Yes Yes
-
= D S C $ K _ D T Y P L W
7 Yes
-
-
Yes Yes
Yes Yes
-
DSC$K_DTYPLL
= 8 Yes
-
-
Yes Yes
Yes Yes
-
= DSC$K_DTYPLQ
9 Yes
-
-
Yes
-
Yes Yes
-
_VSA
= 12
-
-
-
-
-
_UBS
= 13
Yes Yes Yes Yes -
-
Yes Yes Yes -
_UBA
= 14
Yes Yes Yes Yes Yes Yes Yes
-
_BFA
= 191
Yes 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_DTYPLV = 1 DSC$K_DTYPLT = 14 DSC$K_DTYPLNU = 15 DSC$K_DTYPLN L = 16 DSC$K_DTYPLN LO = 17 DSC$K_DTYPLNR = 18 DSC$K_DTYPLNLR = 19 DSC$K_DTYPLNZ = 20 DSC$K_DTYPLP = 21 DSC$K_DTYPE_VT = 37 DSC$K_DTYPLVU = 34
_s
= 1
Yes Yes Yes Yes Yes Yes Yes Yes Yes -
*
_D _v
=2 =3
-
-
Yes
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
*
*
DSC$K_CLASS _A _p _SD =4 =5 =9
_NCA = 10
Yes
-
-
Yes
Yes Yes
Yes
Yes
-
-
Yes Yes
-
-
Yes Yes
-
-
Yes Yes
-
-
Yes Yes
-
-
Yes Yes
-
-
Yes Yes
-
-
Yes Yes
-
-
-
-
*
*
*
*
_vs
= 11
Yes
-
-
-
-
Yes
*
_VSA _UBS _UBA = 12 = 13 = 14
-
Yes
Yes
Yes
Yes
Yes
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Yes
-
-
*
*
*
_BFA = 191
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-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 _NCA _vs _VSA _UBS _UBA = 1 = 2 = 3 = 4 = 5 = 9 = 10 = 11 = 12 = 13 = 14
DSC$K_DTYPLZI
= 22 Yes
-
-
-
-
*
-
-
-
-
-
= DSC$K_DTYPLZEM
23 Yes
-
-
-
-
*
-
-
-
-
-
= DSC$K_DTYPLDSC
3
(See Note 3)
-
-
-
Yes
-
*
Yes
-
-
-
-
= DSC$K_DTYPLBPV
32 Yes
-
-
-
-
*
Yes
-
-
-
-
= DSC$K_DTYPLBLV
33 Yes
-
-
-
-
*
Yes
-
-
-
-
_BFA
= 191
-
-
-
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
1 Class types DSC$K_CLAss_p1 (6) and DSC$K_CLASS_JI (8) are considered obsolete.
2 Class type DSC$K_CLASS_J (7) is reserved for use by the debugger.
3 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.
4 DSC$K_CLASS_p is used by VAX FORTRAN. No new VAX languages will use it.
5 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.
6 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.
3-14
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 PIC,USR,CON,REL,GBL,NOSHR,NOEXE,RD,WRT,NOVEC
MEM: .LONG 0 LEN: .LONG 700
Longword to hold address of ; allocated memory ; Number of bytes to allocate
.PSECT CODE PIC,USR,CON,REL,GBL,SHR,EXE,RD,NOWRT,NOVEC
.ENTRY PROG, -M<>
PUS HAL MEM
PUS HAL LEN
CALLS #2, G-LIB$GET_VM BLBC RO, 1$ RET 1$: PUSHL RO CALLS #1, G-LIB$SIGNAL RET
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
.END PROG
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: .LONG .ADDRESS
.ADDRESS
2
LEN
START
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.
LEN: .LONG
20
START: .BLKL
1
Number of bytes to allocate Starting address of the virtual memory.
CALLG ARGLIST, G-LIB$GET_VM BLBC RO, ERROR BRB 10$
Get virtual memory Check for error
3.9.4
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).
.ENTRY PROC. AM <R2, R3, R4, RS> MOVF ©4(AP), RO JSB GAMTH$SIN_R4 MOVF RO , R5
MOVF ©8(AP) , RO JSB GAMTH$SIN_R4 MULF R5 , RO 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
3.9.5 Return Status
3-18
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
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
Descriptor for prompt Length field Type field is text Class field is string Address
PROMPT: .ASCII /NAME: /
PROMPT_LEN = . - PROMPT
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
String descriptor Calculate length of string
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
Push address of prompt
descriptor
Push address of string
descriptor
-
CALLS #2 G-LIB$GET_INPUT BLBS RO 10$ CMPL RO #LIB$_INPSTRTRU
BEQL 10$ PUSHL RO CALLS #1 , G-LIB$SIGNAL
Get input string Check for success Error: Was it truncated string? No, more serious error
10$:
MOVL #SS$_NORMAL , RO
Success, or name too
long
RET
.END START
3.9.6
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 D-floating or G-floating H-floating
RO through R1 RO through R3 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:
· 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.
3.10.1
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;
64-bit system time Output message buff er Descriptor for message buff er Length of result string
!+
! Initialize the fields 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
END ELUDOM
$FAOL(CTRSTR=FMTDESC,
Format descriptor
OUTLEN=RSLT,
Output length (only a word!)
OUTBUF=MSGDESC,
! Output buffer desc.
PRMLST= %REF(TIMEBUF));
Address of 64-bit
time block
MSGDESC [DSC$W_LENGTH] = .RSLT;
Modify output desc.
RETURN (LIB$PUT_OUTPUT(MSGDESC);
Return status
END;
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 =
Routine
BEGIN LOCAL
INPUT_VALUE SIN_ VALUE;
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 SIN_VALUE);
RETURN SS$_NORMAL; END;
! End of routine
END ELUDOM
End of module JSB_LINK
3-22
Index
A
Argument characteristics of· 3-3, 3-6 passing mechanism· 2-21 VMS usage· 2-6
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
E
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
F
Function definition of· 1-1
Function return value· 3-6
L
LIB$FLT_UNDER· 3-7
LIB$GET_INPUT· 3-3 LIB$SHOW_TIMER· 3-2 LIB$SIGNAL · 3-1
M
MTH$SIN_R4 · 3-5
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
R
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
s
Shareable image· 1-19
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 A A - L A 7 0 A -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
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
D
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 Company Mailing Address
Dept.
Date
Phone
!
I
Here and I
--;;~';;~:d Ta~ ------------------~lllr-------~~~~v~---
in the United States
BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS. POSTAGE WILL BE PAID BY ADDRESSEE
DIGITAL 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
.!
.","
...c.
c
' ~ s
~
<II!
Acrobat 11.0.23 Paper Capture Plug-in