Digital PDFs

AA-LA67B-TE

December 1990

547 pages

Original

20MB

Document:	. VMS VMS Utility Routines Manual
Order Number:	AA-LA67B-TE
Revision:
Pages:	547
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/5.4/AA-LA67B-TE_VMS_5.4_Utility_Routines_Manual_199006.pdf

OCR Text

. VMS

digital

VMS Utility Routines Manual

Order Number: AA-LA67B-TE

VMS Utility Routines
Manual
Order Number: AA-LA678-TE

June 1990

This manual describes the VMS utility routines, a set of routines that provides
a programming interface to various VMS utilities.

Revision/Update Information:

This manual supersedes the VMS Utility
Routines Manual, Version 5.2.

Software Version:

VMS Version 5.4

digital equipment corporation
maynard, massachusetts

(
June 1990
The information in this document is subject to change without notice and should
not be construed as a commitment by Digital Equipment Corporation. Digital
Equipment Corporation assumes no responsibility for any errors that may appear
in this document.
The software described in this document is furnished under a license and may be
used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is
not supplied by Digital Equipment Corporation or its affiliated companies.
Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject
to restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data
and Computer Software clause at DFARS 252.227-7013.

© Digital Equipment Corporation 1990.
All Rights Reserved.
Printed in U.S.A.
The postpaid Reader's Comments forms at the end of this document request your
critical evaluation to assist in preparing future documentation.

The following are trademarks of Digital Equipment Corporation:
CDA
DDIF
DEC
DECdtm
DECnet
DECUS
DECwindows
DECwriter

DEQNA
Desktop-VMS
DIGITAL
GIGI
HSC
Livelink
LN03
MASS BUS

MicroVAX
PrintServer 40
Q-bus
ReGIS
ULTRIX
UNIBUS
VAX
VAXcluster

VAX RMS
VAXserver
VAXstation
VMS
VT
XUI

mamaama™

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

ZK4493

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

Contents
xvii

PREFACE

CHAPTER 1 INTRODUCTION TO UTILITY ROUTINES

1-1

CHAPTER 2 ACCESS CONTROL LIST (ACL) EDITOR ROUTINE

ACL-1

2.1

USING THE ACL EDITOR ROUTINE: AN EXAMPLE

ACL-1

2.2

ACL EDITOR ROUTINE

ACL-2

ACLEDIT$EDIT

ACL-3

CHAPTER3 COMMAND LANGUAGE (CLI) ROUTINES

CLl-1

3.1

INTRODUCTION TO CLI ROUTINES

CLl-1

3.2

USING THE CLI ROUTINES:AN EXAMPLE

CLl-2

3.3

CLI ROUTINES

CLl-5

CL1$DCL_PARSE

CLl-6

CL1$DISPATCH

CLl-9

CL1$GET_VALUE

CLl-10

CL1$PRESENT

CLl-13

CHAPTER 4 CONVERT (CONV) ROUTINES

CONV-1

4.1

INTRODUCTION TO CONVERT ROUTINES

CONV-1

4.2

USING THE -CONVERT ROUTINES: EXAMPLES

CONV-1

Contents

(
4.3

CONVERT ROUTINES

CONV-7

CONV$CONVERT

CONV-8

CONV$PASS_FILES

CONV-11

CONV$PASS_OPTIONS

CONV·-14

CONV$RECLAIM

CONV-18

CHAPTER 5 DATA COMPRESSION/EXPANSION (DCX) ROUTINES

DCX-1

5.1

INTRODUCTION TO DCX ROUTINES

DCX-1

5.2

USING THE DCX ROUTINES: EXAMPLES

DCX-2

5.3

DCX ROUTINES

DCX-10

DCX$ANALYZE_DATA

DCX-11

DCX$ANALYZE_DONE

DCX-13

DCX$ANALYZE_INIT

DCX-14

DCX$COMPRESS_DATA

DCX-17

DCX$COMPRESS_DONE

DCX-19

DCX$COMPRESS_INIT

DCX-20

DCX$EXPAND_DATA

DCX-22

DCX$EXPAND_DONE

DCX-24

DCX$EXPAND_INIT

DCX-25

DCX$MAKE_MAP

DCX-27

CHAPTERS EDT ROUTINES

EDT-1

6.1

INTRODUCTION TO EDT ROUTINES

EDT-1

6.2

USING EDT ROUTINES: AN EXAMPLE

EDT-1

6.3

EDT ROUTINES

EDT-2

EDT$EDIT

EDT-3

FILEIO

EDT-7

WORKIO

EDT-11

XLATE

EDT-13

Contents

CHAPTER7 FILE DEFINITION LANGUAGE (FOL) ROUTINES

FDL-1

7.1

INTRODUCTION TO FOL ROUTINES

FDL-1

7.2

USING THE FOL ROUTINES: EXAMPLES

FDL-1

7.3

FOL ROUTINES

FDL-5

FDL$CREATE

FDL-6

FDL$GENERATE

FDL-11

FDL$PARSE

FDL-14

FDL$RELEASE

FDL-17

CHAPTERS LIBRARIAN (LBR) ROUTINES
8.1
8.1.1
8.1.2

LBR-1

LBR-1
LBR-1
LBR-2

8.1.2.1
8.1.2.2
8.1.2.3
8.1.2.4

INTRODUCTION TO LBR ROUTINES
Types of Library
Structure of Libraries
Library Headers • LBR-2
Modules· LBR-2
Indexes and Keys • LBR-2
Summary of Routines • LBR-5

8.2

USING THE LBR ROUTINES: EXAMPLES

LBR-7

8.3

LBR ROUTINES

LBR-19

LBR$CLOSE

LBR-20

LBR$DELETE_DATA

LBR-21

LBR$DELETE_KEY

LBR-23

LBR$FIND

LBR-25

LBR$FLUSH

LBR-27

LBR$GET_HEADER

LBR-29

LBR$GET_HELP

LBR-31

LBR$GET_HISTORY

LBR-34

LBR$GET_INDEX

LBR-36

LBR$GET_RECORD

LBR-38

LBR$1Nl_CONTROL

LBR-40

LBR$1NSERT_KEY

LBR-42

LBR$LOOKUP_KEY

LBR-44

LBR$0PEN

LBR-46

vii

Contents

LBR$0UTPUT_HELP
LBR$PUT_END
LBR$PUT_HISTORV
LBR$PUT_RECORD
LBR$REPLACE_KEV
LBR$RET_RMSSTV
LBR$SEARCH
LBR$SET_INDEX
LBR$SET_LOCATE
LBR$SET_MODULE
LBR$SET_MOVE

CHAPTER 9 MAIL ROUTINES

MAIL-1

9.1

INTRODUCTION TO MAIL ROUTINES

MAIL-1

9.2

MESSAGES

MAIL-1

9.3

FOLDERS

MAIL-2

9.4

MAIL FILES

MAIL-3

9.5

USER COMMON DATABASE

MAIL-3

9.6
9.6.1
9.6.2

MAIL PROCESSING CONTEXTS
Callable MAIL Routines
Single and Multiple Threads

MAIL-4
MAIL-5
MAIL-5

9.7
9.7.1
9.7.2

PROGRAMMING CONSIDERATIONS
Condition Handling
Item Lists and Item Descriptors
Structure of an Item Descriptor• MAIL-7
Null Item Lists • MAIL-8
Declaring Item Lists and Item Descriptors • MAIL-8
Terminating an Item List • MAIL-8
Action Routines
Types of Action Routines • MAIL-8

MAIL-6
MAIL-6
MAIL-6

9.7.2.1
9.7.2.2
9.7.2.3
9.7.2.4
9.7.3

9.7.3.1

viii

LBR-50
LBR-55
LBR-56
LBR-58
LBR-60
LBR-62
LBR-63
LBR-65
LBR-67
LBR-68
LBR-70

MAIL-8

Contents

9.8
9.8.1
9.8.1.1

9.8.1.2
9.8.1.3

MAIL FILE CONTEXT
MAIL-9
Managing Mail Files
MAIL-1 O
Opening and Closing Mail Files• MAIL-10
9.8.1.1.1
Using the Default Specification for Mail Files • MAIL-1 O
9.8.1.1.2
Specifying an Alternate Mail File Specification • MAIL-1 O
Displaying Folder Names• MAIL-11
Purging Mail Files Using the Wastebasket Folder • MAIL-12
9.8.1.3.1
Reclaiming Disk Space• MAIL-12
9.8.1.3.2
Compressing Mail Files• MAIL-12

9.9
9.9.1
9.9.2
9.9.3
9.9.4
9.9.4.1
9.9.4.2
9.9.4.3
9.9.5

MESSAGE CONTEXT
Selecting Messages
Reading and Printing Messages
Modifying Messages
Copying and Moving Messages
Creating Folders • MAIL-15
Deleting Folders • MAIL-15
Creating Mail Files• MAIL-15
Deleting Messages

MAIL-12
MAIL-13
MAIL-14
MAIL-14
MAIL-15

9.10
9.10.1
9.10.1.1

SEND CONTEXT
Sending New Messages
Creating a Message• MAIL-17
9.10.1.1.1 Constructing the Message Header • MAIL-17
9.10.1.1.2 Constructing the Body of the Message• MAIL-17
Creating an Address List • MAIL-17
Sending Existing Messages
Send Action Routines
Success Action Routines• MAIL-18
Error Handling Routines• MAIL-18
Aborting a Send Operation • MAIL-18

MAIL-16
MAIL-17

MAIL-19
MAIL-19

9.11.1.2

USER PROFILE CONTEXT
User Profile Entries
Adding User Profile Entries to the User Common
Database• MAIL-20
Modifying or Deleting User Profile Entries • MAIL-20

9.12

INPUT ITEM CODES

MAIL-21

9.10.1.2
9.10.2
9.10.3
9.10.3.1
9.10.3.2
9.10.3.3

9.11
9.11.1
9.11.1.1

MAIL-16

MAIL-18
MAIL-18

Contents

9.13

OUTPUT ITEM CODES

MAIL-23

9.14

EXAMPLES OF USING MAIL ROUTINES

MAIL-25

9.15

MAIL ROUTINES

MAIL-33

MAIL$MAILFILE_BEGIN
MAIL$MAILFILE_CLOSE

MAIL-34
MAIL-38

MAIL$MAILFILE_COMPRESS
MAIL$MAILFILE_END

MAIL-41
MAIL-44

MAIL$MAILFILE_INFO_FILE
MAIL$MAILFILE_MODIFV

MAIL-46
MAIL-49

MAIL$MAILFILE_OPEN

MAIL-52

MAIL$MAILFILE_PURGE_WASTE
MAIL$MESSAGE_BEGIN

MAIL-55
MAIL-58

MAIL$MESSAGE_COPY
MAIL$MESSAGE_DELETE

MAIL-62
MAIL-67

MAIL$MESSAGE_END
MAIL$MESSAGE_GET

MAIL-69
MAIL-71

MAIL$MESSAGE_INFO
MAIL$MESSAGE_MODIFY

MAIL-76
MAIL-80

MAIL$MESSAGE_SELECT
MAIL$SEND_ABORT

MAIL-83
MAIL-87

MAIL$SEND_ADD_ADDRESS

MAIL-89

MAIL$SEND_ADD_ATTRIBUTE

MAIL-91
MAIL-94

MAIL$SEND_BEGIN
MAIL$SEND_ADD_BODVPART
MAIL$SEND_END
MAIL$SEND_MESSAGE

MAIL-98
MAIL-101

MAIL$USER_BEGIN

MAIL-103
MAIL-105

MAIL$USER_DELETE_INFO

MAIL-110

MAIL$USER_END

MAIL-112

MAIL$USER_GET_INFO

MAIL-114

MAIL$USER_SET_INFO

MAIL-118

CHAPTER 10 NATIONAL CHARACTER SET (NCS) UTILITY ROUTINES
10.1

INTRODUCTION TO NCS ROUTINES

NCS-1

Contents

10.2

EXAMPLES OF HOW TO USE NCS UTILITY ROUTINES

NCS-2

10.3

NCS ROUTINES
NCS$COMPARE
NCS$CONVERT
NCS$END_CF
NCS$END_CS
NCS$GET_CF
NCS$GET_CS
NCS$RESTORE_CF
NCS$RESTORE_CS
NCS$SAVE_CF
NCS$SAVE_CS

NC5-6

CHAPTER 11

NCS-7
NCS-9
NCS-11
NCS-12
NCS-13
NCS-15
NCS-17
NCS-19
NCS-21
NCS-23

PRINT SYMBIONT MODIFICATION (PSM) ROUTINES

PSM-1

11.1

INTRODUCTION TO PSM ROUTINES

PSM--1

11.2
11.2.1
11.2.2
11.2.3
11.2.4
11.2.5

VMS PRINT SYMBIONT OVERVIEW
Components of the VMS Print Symbiont
Creation of the Print Symbiont Process
Symbiont Streams
Symbiont and Job Controller Functions
Print Symbiont Internal Logic

PSM-2
PSM-2
PSM-2
PSM-3
PSM-4
PSM-5

11.3
11.3.1
11.3.2
11.3.2.1
11.3.2.2
11.3.3
11.3.3.1
11.3.4
11.3.4.1
11.3.5
11.3.6
11.3.7

SYMBIONT MODIFICATION PROCEDURE
Guidelines and Restrictions
Writing an Input Routine
Internal Logic of the Symbiont's Main Input Routine • PSM-11
Symbiont Processing of Carriage Control • PSM-12
Writing a Format Routine
Internal Logic of the Symbiont's Main Format Routine• PSM-13
Writing an Output Routine
Internal Logic of the Symbiont's Main Output Routine • PSM-15
Other Function Codes
Writing a Symbiont Initialization Routine
Integrating a Modified Symbiont

PSM-7
PSM-8
PSM-10

PSM-13
PSM-14
PSM-15
PSM-16
PSM-17

Contents

11.4

EXAMPLE OF USING THE PSM ROUTINES

PSM-18

11.5

PSM ROUTINES
PSM$PRINT
PSM$READ_ITEM_DX

PSM-22

PSM$REPLACE
PSM$REPORT

PSM-23
PSM-25
PSM-27
PSM-32

USER-FORMAT-ROUTINE

PSM-35

USER-INPUT-ROUTINE

PSM-40
PSM-46

USER-OUTPUT-ROUTINE

CHAPTER 12 SYMBIONT/JOB CONTROLLER INTERFACE (SMB)
ROUTINES
12.1
12.1.1
12.1.2
12.1.3
12.1.4
12.1.5
12.1.6
12.1.7

12.1.7.1
12.1.7.2

xii

INTRODUCTION TO SMB ROUTINES

SMB-1

SMB-1
SMB-1
SMB-1
SMB-2
SMB-3
SMB-4
SMB-5
SMB-5

Types of Symbiont
Symbionts Supplied with the VMS Operating System
Symbiont Behavior in the VMS Environment
Writing a Symbiont
Guidelines for Writing a Symbiont
The Symbiont/Job-Controller Interface Routines
Choosing the Symbiont Environment
Synchronous Versus Asynchronous Delivery of
Requests • SMB-5
Single-Streaming Versus Multistreaming • SMB-9

12.1.8
12.1.9
12.1.10

Reading Job Controller Requests
Processing Job Controller Requests
Responding to Job Controller Requests

SMB-10
SMB-10
SMB-13

12.2

SMB ROUTINES

SMB-14

SMB$CHECK_FOR_MESSAGE

SMB-15

SMB$1NITIALIZE

SMB-16

SMB$READ_MESSAGE

SMB-18

SMB$READ_MESSAGE_ITEM

SMB-21

SMB$SEND_TO_JOBCTL

SMB-31

Contents

CHAPTER 13 SORT/MERGE (SOR) ROUTINES
13.1
13.1.1
13.1.2

SOR-1

13.1.3

INTRODUCTION TO SOR ROUTINES
Arguments to SOR Routines
Interfaces to SOR Routines
Sort Operation Using File Interface • SOR-2
Sort Operation Using Record Interface • SOR-3
Merge Operation Using File Interface • SOR-3
Merge Operation Using Record Interface • SOR-3
Reentrancy

SOR-4

13.2

EXAMPLES OF USING SOR ROUTINES

SOR-4

13.3

SOR ROUTINES
SOR$BEGIN_MERGE
SOR$BEGIN_SORT
SOR$DTVPE
SOR$END_SORT
SOR$PASS_FILES
SOR$RELEASE_REC

SOR-17

SOR-31
SOR-34
SOR-36
SOR-41

SOR$RETURN_REC
SOR$SORT_MERGE

SOR-43
SOR-45

SOR$SPEC_FILE
SOR$STAT

SOR-48
SOR-50

13.1.2.1
13.1.2.2
13.1.2.3
13.1.2.4

SOR-1
SOR-2
SOR-2

SOR-18
SOR-25

CHAPTER 14 VAX TEXT PROCESSING UTILITY (VAXTPU) ROUTINES

TPU-1

14.1
14.1.1
14.1.2
14.1.3
14.1.4
14.1.5

INTRODUCTION TO VAXTPU ROUTINES
Two Interfaces to Callable VAXTPU
Shareable Image
Passing Parameters to Callable VAXTPU Routines
Error Handling
Return Values

TPU-1
TPU-2
TPU-3
TPU-4
TPU-4
TPU-4

14.2
14.2.1

THE SIMPLIFIED CALLABLE INTERFACE
Examples of the Simplified Interface

TPU-5
TPU-5

xiii

Contents

14.3
14.3.1
14.3.2
14.3.3

THE FULL CALLABLE INTERFACE
Main Callable VAXTPU Utility Routines
Other VAXTPU Utility Routines
User-Written Routines

TPU-6
TPU-7
TPU-7
TPU-8

14.4

EXAMPLES OF USING VAXTPU ROUTINES

TPU-8

14.5

VAXTPU ROUTINES
TPU$CLEANUP
TPU$CLIPARSE
TPU$CLOSE_TERMINAL
TPU$CONTROL
TPU$EDIT
TPU$EXECUTE_COMMAND
TPU$EXECUTE_INIFILE
TPU$FILEIO
TPU$HANDLER
TPU$1NITIALIZE
TPU$MESSAGE
TPU$PARSEINFO
TPU$TPU
FILEIO
HANDLER
INITIALIZE
USER

TPU-25
TPU-26
TPU-29
TPU-30
TPU-31
TPU-32
TPU-34
TPU-35
TPU-37
TPU-41
TPU-43
TPU-48
TPU-49
TPU-50
TPU-51
TPU-53
TPU-54
TPU-55

INDEX

EXAMPLES

xiv

2-1

Calling the ACL Editor with a VAX BLISS Program

3-1

Using the CU Routines to Retrieve Information About
Command Lines in a FORTRAN Program

ACL-1

CLl-3
CONV-2
CONV-3
CONV-5
CONV-6

4-1
4-2
4-3

Using the Convert Routines in a FORTRAN Program

4-4

Using the CONV$RECLAIM Routine in a MACRO Program _

5-1

Compressing a File in a VAX FORTRAN Program

DCX-2

5-2

Expanding a Compressed File in a VAX FORTRAN Program .

DCX-7

Using the Convert Routines in a MACRO Program
Using the CONV$RECLAIM Routine in a FORTRAN Program

Contents

6-1

Using the EDT Routines in a VAX BASIC Program

EDT-2

7-1

Using FDL$CREATE in a FORTRAN Program

FDL-2

7-2

Using FDL$PARSE and FDL$RELEASE in a MACRO
Program

FDL-2

Using FDL$PARSE and FDL$GENERATE in a VAX Pascal
Program

FDL-4

8-1

Creating a New Library Using VAX Pascal

LBR-8

8-2

Inserting a Module Into a Library Using VAX Pascal

LBR-11

8-3

Extracting a Module from a Library Using VAX Pascal

LBR-14

8-4

Deleting a Module from a Library Using VAX Pascal

LBR-17

9-1

Sending a File

MAIL-26

9-2

Displaying Folders

MAIL-28

9-3

Displaying User Profile Information

MAIL-30

10-1

Using NCS Routines in a FORTRAN Program

NCS-3

10-2

Using NCS Routines in a MACR0-32 Program

NCS-4

11-1

Using PSM Routines to Supply a Page Header Routine in a
MACRO Program

PSM-19

Using SOR Routines to Perform a Merge Using Record
Interface in a VAX FORTRAN Program

SOR-4

Using SOR Routines to Sort Using Mixed Interface in a VAX
FORTRAN Program

SOR-8

Using SOR Routines to Merge Three Input Files in a VAX
Pascal Program

SOR-10

Using SOR Routines to Sort Records from Two Input Files in
a VAX Pascal Program

SOR-13

7-3

13-1
13-2
13-3
13-4

Sample VAX BLISS Template for Callable VAXTPU

TPU-9

14-2

Normal VAXTPU Setup in VAX FORTRAN

TPU-14

14-3

Building a Callback Item List with VAX FORTRAN

TPU-17

14-4

Specifying a User-Written File 1/0 Routine in VAX C

TPU-20

8-1

Structure of a Macro, Text, or Help Library

LBR-3

8-2

Structure-of an Object or Shareable Image Library

LBR-4

8-3

Structure of a User-Developed Library

LBR-5

9-1

Standard Message Format

MAIL-2

9-2

Item Descriptor

MAIL-7

11-1

Multithreaded Symbiont

PSM-4

11-2

Symbiont Execution Sequence or Flow of Control

PSM-6

12-1

Symbionts in the VMS Operating System Environment

SMB-3

12-2

Flowchart for a Single-Threaded, Synchronous Symbiont _

SMB-7

14-1

FIGURES

Contents

12-3

Flow Chart for a Single-Threaded, Asynchronous Symbiont
{MAIN Routine)

SMB-8

Flow Chart for a Single-Threaded, Asynchronous Symbiont
{AST Routine)

SMB-9

9-1

Default Mail Folders

MAIL-3

9-2

User Profile Information

MAIL-3

9-3

Levels of MAIL Processing

MAIL-4

9-4

Callable MAIL Routines
Mail File Routines

MAIL-5
MAIL-9

Message Routines

MAIL-12
MAIL-16

12-4

TABLES

9-5
9-6
9-7
9-8
9-9
9-10
10-1
11-1

xvi

Send Routines
User Profile Context Routines

MAIL-19

Input Item Codes

MAIL-21

Output Item Codes

MAIL-24

NCS Routines

NCS-1

Routine Codes for Specification to PSM$REPLACE

PSM-16

Preface
Intended Audience
This manual is intended for programmers who want to invoke and
manipulate VMS utilities from a program.

Document Structure
This document contains the following chapters.
Chapter 1 introduces the utility routines and describes the documentation
format used to describe each set of utility routines, as well as the
individual routines in each set. Each subsequent chapter contains an
introduction to a set of utility routines, a programming example to
illustrate the use of the routines in the set, and a detailed description
of each routine.
This manual presents the utility routine sets as follows:
•

Chapter 2 - ACL Editor routine.

•

Chapter 3 - Command Language (CL!) routines

•

Chapter 4 - Convert (CONV) routines

•

Chapter 5 - Data Compression/Expansion routines

•

Chapter 6 - EDT Editor routines

•

Chapter 7 - File Definition Language (FDL) routines

•

Chapter 8 - Librarian (LBR) routines

•

Chapter 9 - Mail routines

•

Chapter 10 - National Character Set (NCS) Utility routines

•

Chapter 11 - Print Symbiont Modification (PSM) routines

•

Chapter 12 - Symbiont/Job Controller Interface (SMB) routines

•

Chapter 13 - Sort/Merge (SOR) routines

•

Chapter 14 - VAX. Text Processing Utility (VAX.TPU) routines

Associated Documents
The VAX. Procedure Calling and Condition Handling Standard, which
is documented in the Introduction to VMS System Routines, contains
useful information for all programmers. The Introduction to VMS System
Routines also describes in detail the documentation format of the routine
descriptions.

xvii

Preface

Some sets of utility routines documented in this manual invoke and
manipulate utilities that have a command level interface. Consult the
following manuals for a description of the command level interface:

•

VMS Access Control List Editor Manual

•

VMS Command Definition Utility Manual

•

VMS Convert and Convert I Reclaim Utility Manual

•

VAX EDT Reference Manual

•

VMS File Definition Language Facility Manual

•

VMS Librarian Utility Manual

•

VMS Mail Utility Manual

•

VMS Sort I Merge Utility Manual

•

VAX Text Processing Utility Manual

•

VMS National Character Set Utility Manual

Conventions
The documentation template for utility routines, which is described in the
Introduction to VMS System Routines, details the conventions used in this
manual, as well as the organizational approach used to document each
utility routine.
The following table describes additional conventions that appear in this
manual:
Convention

Meaning

Ctrl/x

A sequence such as Ctrl/x indicates that you must
hold down the key labeled Ctrl while you press
another key or a pointing device button.

PF1 x

A sequence such as PF1 x indicates that you must
first press and release the key labeled PF1 , then
press and release another key or a pointing device
button.
In examples, a key name is shown enclosed in
a box to indicate that you press a key on the
keyboard. {In text, a key name is not enclosed in a
box.)
In examples, a horizontal ellipsis indicates one of
the following possibilities:
Additional optional arguments in a statement
have been omitted.
The preceding item or items can be repeated
one or more times.
Additional parameters, values, or other
information can be entered.

xviii

Preface

Convention

Meaning
A vertical ellipsis indicates the omission of items
from a code example or command format; the
items are omitted because they are not important
to the topic being discussed.
,

()

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

[]

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

{}

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

red ink

Red ink indicates information that you must enter
from the keyboard or a screen object that you must
choose or click on.
For online versions of the book, user input is
shown in bold.

boldface text

Boldface text represents the introduction of a new
term or the name of an argument, an attribute, or a
reason.
Boldface text is also used to show user input in
online versions of the book.

italic text

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

UPPERCASE TEXT

Uppercase letters indicate that you must enter a
command (for example, enter OPEN/READ}, or
they indicate the name of a routine, the name of
a file, the name of a file protection code, or the
abbreviation for a system privilege.

number}.

Hyphens in coding examples indicate that
additional arguments to the request are provided
on the line that follows.
numbers

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

xix

Introduction to Utility Routines

A set of utility routines performs a particular task or set of tasks. For
example, you can use the Print Symbiont Modification (PSM) routines to
modify the VMS print symbiont, and the EDT routines to invoke the EDT
editor from a program.
Some of the tasks performed by utility routines can also be performed
at the DIGITAL Command Language (DCL) level (for example, the DCL
command EDIT invokes the EDT editor). While DCL commands invoke
VMS utilities that allow you to perform tasks at your terminal, you can
perform some of these tasks at the programming level through the use of
the utility routines.
When using a set of utility routines that performs the same tasks as a
VMS utility, you should read the documentation for that utility; doing
so will provide additional information about the tasks the routines
can perform as a set. The following table lists VMS utilities and their
corresponding routines:
Utility or Editor

Utility Routines

Access Control List Editor

ACL Editor routine

Command Definition Utility

CLI routines

Convert and Convert/Reclaim Utilities

CONV routines

EDT Editor

EDT routines

File Definition Language Facility

FDL routines

Library Utility

LBR routines

MAIL

Mail routines

VMS National Character Set Utility

NCS routines

Sort/Merge Utility

SOR routines

VAX Text Processing Utility

VAXTPU routines

When a set of utility routines performs functions that you cannot perform
by invoking a VMS utility, the functions provided by that set of routines "is
termed a facility. The following facilities have no other user interface
except the programming interface provided by the utility routines
described in this manual:
Facility

Utility Routines

Data Compression/Expansion Facility

DCX routines

Print Symbiont Modification Facility

PSM routines

Symbiont/Job-Controller Interface Facility

SMB routines

1-1

Introduction to Utility Routines

The utility routines described in this manual are called in the same way
as all other system routines in the VMS operating system environment,
which is to say that utility routines conform to the VAX Procedure Calling
and Condition Handling Standard.
Each chapter of this book documents one set of utility routines. Each
chapter has the following major components, documented as a major
heading:
•

An introduction to the set of utility routines. This component discusses
the utility routines as a group and explains how to use them.

•

A series of descriptions of each utility routine in the set.

Most of the chapters also include a programming example that illustrates
how the utility routines are used.

1-2

Access Control List {ACL) Editor Routine

This chapter describes the Access Control List (ACL) Editor routine,
ACLEDIT$EDIT. U ser-writte:a applications can use this callable interface
of the ACL Editor to manipulate Access Control Lists.
The ACL Editor is a VMS utility that lets you create and maintain access
control lists. Using ACLs, you can fine-tune the type of access to files,
devices, global sections, logical name tables, or mailboxes available to
system users.
Currently, the ACL Editor provides one callable interface that allows the
application program to define an object for editing.
Note that the application program should declare referenced constants and
return status symbols as external symbols; these symbols will be resolved
upon linking with the utility shareable image.
See Introduction to VMS System Services for fundamental conceptual
information on the creation, translation, and maintenance of ACEs.

2.1

Using the ACL Editor Routine: An Example
Example 2-1 shows a VAX BLISS program that calls the ACL Editor
routine.
Example 2-1

Calling the ACL Editor with a VAX BLISS Program

MODULE MAIN (LANGUAGE (BLISS32), MAIN= STARTUP) =
BEGIN
LIBRARY 'SYS$LIBRARY:LIB';
ROUTINE STARTUP =
BEGIN
LOCAL
STATUS,
ITMLST

! Routine return status
BLOCKVECTOR [6, ITM$S ITEM, BYTE];
ACL editor item list
-

EXTERNAL LITERAL
ACLEDIT$V JOURNAL,
ACLEDIT$V=PROMPT_MODE,
ACLEDIT$C OBJNAM,
ACLEDIT$C-OBJTYP,
ACLEDIT$C=OPTIONS;
EXTERNAL ROUTINE
ACLEDIT$EDIT : ADDRESSING_MODE (GENERAL),

Main routine
(continued on next page)

ACL-1

Access Control List {ACL) Editor Routine
2.1 Using the ACL Editor Routine: An Example

Example 2-1 (Cont.)
CLI$GET VALUE,
CLI$PRESENT,
LIB$PUT OUTPUT,
STR$COPY_DX;

Calling the ACL Editor with a VAX BLISS Program
! Get qualifier value
See if qualifier present
! General output routine
Copy string by descriptor

! Set up the item list to pass back to TPU so it can figure out what to do.

CH$FILL (0, 6*ITM$S ITEM, ITMLST);
ITMLST[O, ITM$W ITMCOD] = ACLEDIT$C OBJNAM;
ITMLST[O, ITM$W-BUFSIZ] = %CHARCOUNT ('YOUR OBJECT NAME');
ITMLST[O, ITM$L-BUFADR] =$DESCRIPTOR ('YOUR OBJECT NAME');
ITMLST[l, ITM$W-ITMCOD] = ACLEDIT$C OBJTYP; ITMLST[l, ITM$W-BUFSIZ] = 4;
ITMLST[l, ITM$L-BUFADR] = UPLIT (ACL$C FILE);
ITMLST[2, ITM$W-ITMCOD] = ACLEDIT$C_OPTIONS;
ITMLST[2, ITM$W-BUFSIZ] = 4;
ITMLST[2, ITM$L-BUFADR] = UPLIT (1 A ACLEDIT$V_PROMPT_MODE OR
1 A ACLEDIT$V_JOURNAL);
RETURN ACLEDIT$EDIT (ITMLST);
END;
! End of routine STARTUP
END
ELUDOM

2.2

ACL Editor Routine
The following pages describe the ACL Editor routine.

(

ACL-2

Access Control List (ACL) Editor Routine
ACLEDIT$EDIT

ACLEDIT$EDIT

Edit Access Control List

The ACLEDIT$EDIT routine is used to create and modify an Access Control
List (ACL) associated with any system object.

FORMAT

ACLEDIT$EDIT

RETURNS

VMS usage:
type:
access:
mechanism:

item_list

cond_value
longword {unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

item list
item_list_3
longword {unsigned)
read only
by descriptor
Item list used by the callable ACL Editor. The item_list argument is the
address of one or more descriptors of arrays, routines, or longword bit
masks that control various aspects of the editing session.

VMS usage:
type:
access:
mechanism:

Each entry in an item list is in the standard format shown in the following
figure.
Item Code

I Buffer Length

Buffer Address
Return Length Address

ZK-5012-GE

Following is a detailed description of each item list entry.
Item Identifier

Description

ACLEDIT$C_OBJNAM

Specifies the name of the object whose ACL is being
edited.

ACLEDIT$C_OBJTYP

Specifies the type of the object whose ACL is being
edited. These type codes are defined in $ACLDEF. The
default object type is a file (ACL$C_FILE).

ACL-3

Access Control List {ACL) Editor Routine
ACLEDIT$EDIT

Item Identifier

Description

ACLEDIT$C_OPTIONS

Represents a longword bit mask of the various options
available to control the editing session.

ACLEDIT$C_BIT_TABLE

DESCRIPTION

Flag

Function

ACLEDIT$V_JOURNAL

Indicates that the
editing session is
to be journaled.

ACLEDIT$V_RECOVER

Indicates that the
editing session is
to be recovered
from an existing
journal file.

ACLEDIT$V_KEEP_RECOVER

Indicates that the
journal file used to
recover the editing
session is not to
be deleted when
the recovery is
complete.

ACLEDIT$V_KEEP_JOURNAL

Indicates that the
journal file used
for the editing
session is not to
be deleted when
the session ends.

ACLEDIT$V_PROMPT_MODE

Indicates that
the session is to
use automatic
text insertion
(prompting) to
build new access
control list entries
(ACEs).

Specifies a vector of 32 quadword string descriptors
of strings which define the names of the bits present
in the access mask. (The first descriptor defines the
name of Bit O; the last descriptor defines the name
of Bit 31.) These descriptors are used in parsing or
formatting an ACE. The buffer address field of the item
descriptor contains the address of this vector.

You use the ACLEDIT$EDIT routine to create and modify an ACL
associated with any system object.
Under normal circumstances, the application calls the ACL Editor to
modify an object's ACL, and control is returned to the application when
you finish or abort the editing session.

ACL-4

Access Control List (ACL) Editor Routine
ACLEDIT$EDIT

If you also want to use a customized version of the ACL Editor section
file, the logical name ACLEDT$SECTION should be defined. See the VMS

Access Control List Editor Manual for more information.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

RMS$_xxx

See the VMS Record Management Services Manual
for a description of RMS status codes.

TPU$_xxx

See Chapter 14 for a description of the TPUspecific condition values that may be returned by
ACLEDIT$EDIT.

ACL-5

Command Language {CLI) Routines

You use the CLI routines to process command strings using information
from a command table. A command table contains command definitions
that describe the allowable formats for commands. To create or modify a
command table, you must write a command definition file and then process
this file with the Command Definition Utility (the SET COMMAND
command). For information about how to use the Command Definition
Utility, see the VMS Command Definition Utility Manual.

3.1

Introduction to CLI Routines
The CLI routines include the following:
•

CLI$DCL_PARSE

•

CLI$DISPATCH

•

CLI$GET_VALUE

•

CLI$PRESENT

When you use the Command Definition Utility to add a new command
to your process command table or to the DCL command table, use the
CLI$PRESENT and CLI$GET_VALUE routines in the program invoked
by the new command. These routines retrieve information about the
command string that invokes the program.
When you use the Command Definition Utility to create an object module
containing a command table and you link this module with a program,
you must use all four CLI routines. First, use CLI$DCL_PARSE and
CLI$DISPATCH to parse command strings and invoke routines. Then, use
CLI$PRESENT and CLI$GET_VALUE within the routines that execute
each command.
Note that the application program should declare referenced contants and
return status symbols as external symbols; these symbols are resolved
upon linking with utility shareable image.
A CLI must be present in order to use the CLI routines. If your application
might be run from a detached process, then the application should check
to verify that a CLI exists. For information about how to determine if a
CLI exists for a process, see the description of the SYS$GETJPI system
service in the VMS System Services Reference Manual.

CLl-1

Command Language {CLI) Routines
3.2 Using the CLI Routines:An Example

3.2

Using the CLI Routines:An Example
Example 3-1 contains a command definition file (SUBCOMMANDS.CLD)
and a FORTRAN program (INCOME.FOR). INCOME.FOR uses the
command definitions in SUBCOMMANDS.CLD to process commands. To
execute the example, enter the following commands:
$ SET COMMAND SUBCOMMANDS/OBJECT=SUBCOMMANDS
$

FORTRAN INCOME

$ LINK INCOME,SUBCOMMANDS
$

RUN INCOME

INCOME.FOR accepts a command string and parses it using
CLI$DCL_PARSE. If the command string is valid, the program
uses CLI$DISPATCH to execute the command. Each routine uses
CLI$PRESENT and CLI$GET_VALUE to obtain information about the
command string.

CLl-2

Command Language (CLI) Routines
3.2 Using the CLI Routines:An Example

Example 3-1

Using the CLI Routines to Retrieve Information About
Command Lines In a FORTRAN Program

****************************************************
SUBCOMMANDS.CLO

****************************************************
MODULE INCOME_SUBCOMMANDS
DEFINE VERB ENTER
ROUTINE ENTER
DEFINE VERB FIX
ROUTINE FIX
QUALIFIER HOUSE_NUMBERS, VALUE (LIST)
DEFINE VERB REPORT
ROUTINE REPORT
QUALIFIER OUTPUT, VALUE (TYPE = $FILE,
DEFAULT = "INCOME.RPT")
DEFAULT

****************************************************
INCOME.FOR

****************************************************
PROGRAM INCOME
INTEGER STATUS,
2
CLI$DCL PARSE,
2
CLI$DISPATCH
INCLUDE' ($RMSDEF)'
INCLUDE' ($STSDEF)'
EXTERNAL INCOME SUBCOMMANDS,
2
LIB$GET_INPUT
! Write explanatory text
STATUS = LIB$PUT OUTPUT
2 ('Subcommands:-ENTER - FIX - REPORT')
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))
STATUS = LIB$PUT OUTPUT
2 ('Press CTRL/Z-to exit')
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))
! Get first subcommand
STATUS
CLI$DCL_PARSE (%VAL (0),
2
INCOME SUBCOMMANDS,
CLD module
LIB$GET INPUT,
Parameter routine
2
Command routine
2
LIB$GET=INPUT,
2
'INCOME> ')
Command prompt
Do it until user presses CTRL/Z
DO WHILE (STATUS .NE. RMS$ EOF)
! If no error on dcl_parseIF (STATUS) THEN
! Dispatch depending on subcommand
STATUS = CLI$DISPATCH ()
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))
! Do not signal warning again
ELSE IF (IBITS (STATUS, O, 3) .NE. STS$K_WARNING) THEN
CALL LIB$SIGNAL (%VAL (STATUS))
END IF

(continued on next page)

CLl-3

Command Language (CLI) Routines
3.2 Using the CLI Routines:An Example

Example 3-1 (Cont.)

Using the CLI Routines to Retrieve Information
About Command Lines in a FORTRAN Program

! Get another subcommand
STATUS
CLI$DCL_PARSE (%VAL (0),
2
INCOME SUBCOMMANDS,
2
LIB$GET INPUT,
2
LIB$GET=INPUT,
2
' INCOME> ' )
END DO
END

CLD module
Parameter routine
Command routine
Command prompt

INTEGER FUNCTION ENTER ()
INCLUDE' ($SSDEF)'
TYPE *, 'ENTER invoked'
ENTER = SS$_NORMAL
END
INTEGER FUNCTION FIX ()
INTEGER STATUS,
2
CLI$PRESENT,
2
CLI$GET_VALUE
CHARACTER*15 HOUSE NUMBER
INTEGER*2
HN SIZE
INCLUDE' ($SSDEF)'
EXTERNAL CLI$ ABSENT
TYPE *, 'FIX Invoked'
! If user types /house_numbers=(n, ... )
IF (CLI$PRESENT ('HOUSE NUMBERS')) THEN
! Get first value for /house_numbers
STATUS
CLI$GET VALUE ('HOUSE NUMBERS',
2
HOUSE_NUMBER,
2
HN_SIZE)
Do it until the list is depleted
DO WHILE (STATUS)
TYPE*, 'House number=', HOUSE_NUMBER (l:HN_SIZE)
STATUS
CLI$GET_VALUE ('HOUSE_NUMBERS',
2
HOUSE_NUMBER,
2
HN_SIZE)
END DO
! Make sure termination status was correct
IF (STATUS .NE. %LOC (CLI$ ABSENT)) THEN
CALL LIB$SIGNAL (%VAL (STATUS))
END IF
END IF
FIX = SS$_NORMAL
END
INTEGER FUNCTION REPORT ()
INTEGER STATUS,
2
CLI$GET_VALUE
CHARACTER*64 FILENAME
INTEGER*2
FN SIZE
INCLUDE' ($SSDEF)'
TYPE *, 'REPORT entered'
(continued on next page)

CLl-4

Command Language (CLI) Routines
3.2 Using the CLI Routines:An Example

Example 3-1 (Cont.)

Using the CLI Routines to Retrieve Information
About Command Lines in a FORTRAN Program

! Get value for /output
STATUS = CLI$GET_VALUE ('OUTPUT',
2
FILENAME,
2
FN SIZE)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))
TYPE *, 'Output file: ', FILENAME (l:FN_SIZE)
REPORT = SS$_NORMAL
END

3.3

CLI Routines
The following pages describe the individual CLI routines.

CLl-5

Command Language (CLI) Routines
CLl$DCL_PARSE

CLl$DCL_PARSE

Parse DCL Command String

The CLl$DCL_PARSE routine supplies a command string to DCL for parsing.
DCL separates the command string into its individual elements according to
the syntax specified in the command table.

FORMAT

CLl$DCL_PARSE

RETURNS

VMS usage:
type:
access:
mechanism:

[command_string] ,table
[,param_routine] [,prompt_routine]
[,prompt_ string]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

command_string
char_strlng
character string
read only
by descriptor-fixed length
Character string containing the command to be parsed. The command_
string argument is the address of a descriptor specifying the command
string to be parsed. If the command string includes a comment (delimited
by an exclamation mark), DCL ignores the comment.
VMS usage:
type:
access:
mechanism:

If the command string contains a hyphen to indicate that the string is

being continued, DCL uses the routine specified in the prompt_routine
argument to obtain the rest of the string. The command string is limited
to 256 characters. However, if the string is continued with a hyphen,
CLI$DCL_PARSE can prompt for additional input until the total number
of characters is 1024.
If you specify the command_string argument as zero and specify a

prompt routine, then DCL prompts for the entire command string.
However, if you specify the command_string argument as zero and
also specify the prompt_routine argument as zero, then DCL restores
the parse state of the command string that originally invoked the image.
CLI$DCL_PARSE does not perform DCL-style symbol substitution on the
command string.

table
VMS usage:
type:
access:
mechanism:

CLl-6

address
address
read only
by value

Command Language {CLI) Routines
CLl$DCL_PARSE

Address of the compiled command tables to be used for command parsing.
The command tables are compiled separately by the Command Definition
Utility using the DCL command SET COMMAND/OBJECT, and are then
linked with your program. A global symbol is defined by the Command
Definition Utility that provides the address of the tables. The global
symbol's name is taken from the module name given on the MODULE
statement in the command definition file, or from the file name if no
MODULE statement is present.
·

param_routine
VMS usage: procedure
procedure entry mask
access:
read only
mechanism: by reference
Name of a routine to obtain a required parameter not supplied in the
command text. The param_routine argument is the address of a routine
containing a required parameter that was not specified in the command_
string argument.
type:

To specify the parameter routine, use the address of LIB$GET_INPUT or
the address of a routine of your own that has the same three-argument
calling format as LIB$GET_INPUT. See the description of LIB$GET_
INPUT in the VMS RTL Library (LIB$) Manual for information about
the calling format. If LIB$GET_INPUT returns error status, CLI$DCL_
PARSE propagates the error status outward or signals RMS$_EOF in the
cases listed in the "Description" section.
You can obtain the prompt string for a required parameter from the
command table specified in the table argument.

prompt_ routine
VMS usage: procedure
procedure entry mask
access:
read only
mechanism: by reference
Name of a routine to obtain all or part of the text of a command. The
prompt_routine argument is the address of a routine to obtain the text
or the remaining text of the command depending on the command_string
argument. If you specify a zero in the command_string argument, DCL
uses this routine to obtain an entire command line. DCL uses this routine
to obtain a continued command line if the command string (obtained from
the command_string argument) contains a hyphen to indicate that the
string is being continued.
type:

To specify the prompt routine, use the address of LIB$GET_INPUT or the
address of a routine of your own that has the same three-argument calling
format as LIB$GET_INPUT. See the description of LIB$GET_INPUT in
the VMS RTL Library (LIB$) Manual for information about the calling
format.
If LIB$GET_INPUT returns error status, CLI$DCL_PARSE propagates
the error status outward or signals RMS$_EOF in the cases listed in the
"Description" section.

CLl-7

Command Language {CLI) Routines
CLl$DCL_PARSE

prompt_string
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Character string containing a prompt. The prompt_string argument
is the address of a string descriptor pointing to the prompt string to be
passed as the second argument to the prompt_routine argument.
If DCL is using the prompt routine to obtain a continuation line, DCL
inserts an underscore character before the first character of the prompt
string to create the continuation prompt. If DCL is using the prompt
routine to obtain an entire command line (that is, a zero was specified as
the command_string argument), DCL uses the prompt string exactly as
specified.

The prompt string is limited to 32 characters. The string COMMAND> is
the default prom pt string.

DESCRIPTION

The CLI$DCL_PARSE routine supplies a command string to DCL for
parsing. DCL parses the command string according to the syntax in the
command table specified in the table argument.
The CLI$DCL_PARSE routine can prompt for required parameters if you
specify a parameter routine in the routine call. In addition, the CLI$DCL_
PARSE routine can prompt for entire or continued command lines if you
supply the address of a prompt routine.
If you do not specify a command string to parse and the user enters a null

string in response to the DCL prompt for a command string, CLI$DCL_
PARSE immediately terminates and returns the status RMS$_EOF.
If DCL prompts for a required parameter and the user enters CTRUZ,

CLI$DCL_PARSE immediately terminates and returns the status CLI$_
NOCMD, regardless of whether you specify or do not specify a command
string to parse. If DCL prompts for a parameter that is not required
and the user enters CTRUZ, CLI$DCL_PARSE returns the status CLI$_
NORMAL.
Whenever CLI$DCL_Pl}RSE encounters an error, it both signals and
returns the error.

CONDITION
VALUES
RETURNED

CLl-8

CLl$1VVERB

Invalid or missing verb.

CLl$_NORMAL

Normal successful completion.

CLl$_NOCOMD

Routine terminated. You entered a null string in
response to a prompt from the prompt_routine
argument, causing the CLl$DCL_PARSE routine to
terminate.

RMS$_EOF

Routine terminated. You pressed CTRUZ in response
to a prompt, causing the CLl$DCL_PARSE routine to
terminate.

Command Language (CLI) Routines
CLl$DISPATCH

CLl$DISPATCH

Dispatch to Action Routine

The CLl$DISPATCH routine invokes the subroutine associated with the verb
most recently parsed by a CLl$DCL_PARSE routine call.

FORMAT

CLl$DISPATCH

RETURNS

VMS usage:
type:
access:
mechanism:

{userarg]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. The condition value that this routine can return is listed under
CONDITION VALUE RETURNED.

ARGUMENT

userarg
longword_unsigned
longword (unsigned)
read only
by value
Data to be passed to the action routine. The userarg argument is a
longword that contains the data to be passed to the action routine. This
data can be used in any way you want.
VMS usage:
type:
access:
mechanism:

DESCRIPTION

CONDITION
VALUE
RETURNED

The CLI$DISPATCH routine invokes the subroutine associated with the
verb most recently parsed by a CLI$DCL_PARSE routine call. If the
routine is successfully invoked, the return status is the status returned by
the action routine. Otherwise, a status of CLI$_INVROUT is returned.

CLl$_1NVROUT

CL1$DISPATCH unable to invoke the routine. An
invalid routine is specified in the command table, or
no routine is specified.

CLl-9

Command Language {CLI) Routines
CLl$GET_VALUE

CLl$GET_VALUE Get Value of Entity in Command
String
The CL1$GET_VALUE routine retrieves a value associated with a specified
qualifier, parameter, keyword, or keyword path from the parsed command
string.

entity_desc, retdesc [,retlength]

FORMAT

CLl$GET_VALUE

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

entity_ desc
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Character string containing the label (or name if no label is defined) of
the entity. The entity_desc argument is the address of a string descriptor
that points to an entity that may appear on a command line. The entity_
desc argument can be expressed as one of the following:

•

A parameter, qualifier, or keyword name or label

•

A keyword path

The entity_desc argument can contain qualifier, parameter, or keyword
names, or can contain labels that were assigned with the LABEL clause
in the command definition file. If you used the LABEL clause to assign a
label to an entity, you must specify the label in the entity_desc argument.
Otherwise, use the name of the entity.
You use a keyword path to reference keywords used as values of
parameters, qualifiers, or other keywords. A keyword path contains a
list of entity names or labels separated by periods. If the LABEL clause
was used to assign a label to an entity, you must specify the label in the
keyword path. Otherwise, you must use the name of the entity.
The following command string illustrates a situation where keyword paths
are needed to uniquely identify keywords. In this command string, you
can use the same keywords with more than one qualifier. (This is defined
in the command definition file by having two qualifiers refer to the same
DEFINE TYPE statement.)
$ NEWCOMMAND/QUAL1=(START=5,END=l0)/QUAL2=(START=2,END=5)

CLl-10

Command Language (CLI} Routines
CLl$GET_VALUE

The keyword path QUALl.START identifies the START keyword when
it is used with QUALl; the keyword path QUAL2.START identifies the
keyword START when it is used with QUAL2. Because the name START
is an ambiguous reference if used alone, the keywords QUALl and QUAL2
are needed to resolve the ambiguity.
You can omit keywords from the beginning of a keyword path if they are
not needed to unambiguously resolve a keyword reference. A keyword
path can be no more than eight names long.
If you use an ambiguous keyword reference, DCL resolves the reference by

checking, in the following order:
1

The parameters in your command definition file, in the order they are
listed

The qualifiers in your command definition file, in the order they are
listed

The keyword paths for each parameter, in the order the parameters
are listed

The keyword paths for each qualifier, in the order the qualifiers are
listed

DCL uses the first occurrence of the entity as the keyword path. Note
that DCL does not issue an error message if you provide an ambiguous
keyword. However, because the keyword search order may change
in future releases of VMS, you should never use ambiguous keyword
references.
If the entity_desc argument does not exist in the command table,

CLI$GET_VALUE signals a syntax error (by means of the signaling
mechanism described in the VMS Run-Time Library Routines Volume).

retdesc
VMS usage: char_string
character string
access:
write only
mechanism: by descriptor

type:

Character string containing the value retrieved by CLI$GET_VALUE.
The retdesc argument is the address of a string descriptor pointing to
the buffer to receive the string value retrieved by CLI$GET_VALUE. The
string is returned using the STR$COPY_DX VAX-11 Run-Time Library
routine.
If there are errors in the specification of the return descriptor or in

copying the results using that descriptor, the STR$COPY_DX routine
will signal the errors. For a list of these errors, see the VMS RTL String
Manipulation (STR$) Manual.

retlength
VMS usage: word_unsigned
word (unsigned)
access:
write only
mechanism: by reference

type:

Word containing the number of characters DCL returns to retdesc. The
retlength argument is the address of the word containing the length of
the retrieved value.
CLl-11

Command Language {CLI) Routines
CLl$GET_VALUE

DESCRIPTION

The CLI$GET_VALUE routine retrieves a value associated with a specified
qualifier, parameter, keyword, or keyword path from the parsed command
string.
You can use the following label names with CLI$GET_VALUE to retrieve
special strings:
$VERB

Describes the verb in the command string (the first four letters of the
spelling as defined in the command table, instead of the string that was
actually typed).

$LINE

Describes the entire command string as stored internally by DCL. In the
internal representation of the command string, multiple spaces and tabs
are removed, alphabetic characters are converted to uppercase, and
comments are stripped. Integers are converted to decimal. If dates and
times are specified in the command string, DCL fills in any defaulted fields.
Also, if date-time strings (such as YESTERDAY) are used, DCL substitutes
the corresponding absolute time value.

To obtain the values for a list of entities, call CLI$GET_VALUE repeatedly
until all values have been returned. After each CLI$GET_VALUE call, the
returned condition value indicates whether there are more values to be
obtained. You should call CLI$GET_VALUE until you receive a condition
value of CLI$_ABSENT.
When you are using CLI$GET_VALUE to obtain a list of qualifier or
keyword values, you should get all values in the list before starting to
parse the next entity.

CONDITION
VALUES
RETURNED

CLl-12

CLl$_COMMA

Returned value terminated by a comma. This shows
there are additional values in the list.

CLl$_CONCAT

Returned value concatenated to the next value with a
plus sign. This shows there are additional values in
the list.

SS$_NORMAL

Returned value terminated by a blank or an end-ofline. This shows that the value is the last, or only,
value in the list.

CLl$_ABSENT

No value returned. The value is not present, or the
last value in the list was already returned.

Command Language (CLI) Routines
CLl$PRESENT

CLl$PRESENT Determine Presence of Entity in
Command String
The CLl$PRESENT routine examines the parsed command string to
determine whether the entity referred to by the entity_desc argument is
present.

FORMAT

CLl$PRESENT

RETURNS

VMS usage:
type:
access:
mechanism:

entity_desc

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

entity_ desc
char_string
character string
read only
by descriptor
Character string containing the label (or name if no label is defined) of
the entity. The entity_desc argument is the address of a string descriptor
that points to an entity that may appear on a command line. An entity
can be expressed as one of the following:
VMS usage:
type:
access:
mechanism:

•

A parameter, qualifier, or keyword name or label

•

A keyword path

A keyword path is used to reference keywords that are accepted by
parameters, qualifiers, or other keywords. A keyword path contains a list
of entity names separated by periods. See the description of the entity_
desc argument in the CLI$GET_VALUE routine for more information
about specifying keyword paths as arguments for CLI routines.
The entity_desc argument can contain parameter, qualifier, or keyword
names, or can contain labels that were assigned with the LABEL clause
in the command definition file. If the LABEL clause was used to assign a
label to a qualifier, parameter, or keyword, you must specify the label in
the entity_desc argument. Otherwise, you must use the actual name of
the qualifier, parameter, or keyword.
If the---entity_desc argument does not exist in the command table,

CLI$PRESENT signals a syntax error (by means of the signaling
mechanism described in the VMS Run-Time Library Routines Volume).

CLl-13

Command Language {CLI) Routines
CLl$PRESENT

DESCRIPTION

The CLI$PRESENT routine examines the parsed command string to
determine whether the entity referred to by the entity_desc argument is
present.
When CLI$PRESENT tests whether a qualifier is present, the condition
value indicates whether the qualifier is used globally or locally. You can
use a global qualifier anywhere in the command line; you use a local
qualifier only after a parameter. A global qualifier is defined in the
command definition file with PLACEMENT=GLOBAL; a local qualifier is
defined with PLACEMENT=LOCAL.
When you test for the presence of a global qualifier, CLI$PRESENT
determines if the qualifier is present anywhere in the command string. If
the qualifier is present in its positive form, CLI$PRESENT returns CLI$_
PRESENT; if the qualifier is present in its negative form, CLI$PRESENT
returns CLI$_NEGATED.
You can test for the presence of a local qualifier when you are parsing
parameters that can be followed by qualifiers. After you call CLI$GET_
VALUE to fetch the parameter value, call CLI$PRESENT to determine
whether the local qualifier is present. If the local qualifier is present in
its positive form, CLI$PRESENT returns CLI$_LOCPRES; if the local
qualifier is present in its negative form, CLI$PRESENT returns CLI$_
LOCNEG.
A positional qualifier affects the entire command line if it appears after the
verb but before the first parameter. A positional qualifier affects a single
parameter if it appears after a parameter. A positional qualifier is defined
in the command definition file with the PLACEMENT=POSITIONAL
clause.
To determine whether a positional qualifier is used globally, call
CLI$PRESENT to test for the qualifier before you call CLI$GET_VALUE
to fetch any parameter values. If the positional qualifier is used globally,
CLI$PRESENT returns either CLI$_PRESENT or CLI$_NEGATED.
To determine whether a positional qualifier is used locally, call
CLI$PRESENT immediately after a parameter value has been fetched
by CLI$GET_VALUE. The most recent CLI$GET_VALUE call to fetch
a parameter defines the context for a qualifier search. Therefore,
CLI$PRESENT tests whether a positional qualifier was specified after
the parameter that was fetched by the most recent CLI$GET_VALUE call.
If the positional qualifier is used locally, CLI$PRESENT returns either
CLI$_LOCPRES or CLI$_LOCNEG.

CONDITION
VALUES
RETURNED

CLl-14

CLl$_PRESENT

Specified entity present in the command string. This
status is returned for all entities except local qualifiers
and positional qualifiers that are used locally.

CLl$_NEGATED

Specified qualifier present in negated form (with /NO)
and used as a global qualifier.

Command Language (CLI) Routines
CLl$PRESENT

CLl$_LOCPRES

Specified qualifier present and used as a local
qualifier.

CLl$_LOCNEG

Specified qualifier present in negated form (with /NO)
and used as a local qualifier.

CLl$_DEFAULTED

Specified entity not present, but it is present by
default.

CLl$_ABSENT

Specified entity not present, and it is not present by
default.

CLl-15

Convert (CONV) Routines

This chapter describes the Convert routines. These routines perform the
functions of both the VMS RMS Convert and Convert/Reclaim Utilities.

4.1

Introduction to Convert Routines
The Convert Utility copies records from one or more files to an output file,
changing the record format and file organization to that of the output file.
You can invoke the functions of the Convert Utility from within a program
by calling the following series of three routines, in this order:
1

CONV$PASS_FILES

CONV$PASS_OPTIONS

CONV$CONVERT

Note that the application program should declare referenced contants and
return status symbols as external symbols; these symbols are resolved
upon linking with utility shareable image.
The Convert/Reclaim Utility reclaims empty buckets in Prolog 3 indexed
files so that new records can be written in them. You can invoke the
functions of the Convert/Reclaim Utility from within a program by calling
the CONV$RECLAIM routine.
These routines cannot be called from AST level.

4.2

Using the Convert Routines: Examples
Example 4-1 shows how to use the Convert routines in a FORTRAN
program.

CONV-1

Convert (CONV) Routines
4.2 Using the Convert Routines: Examples

Example 4-1

Using the Convert Routines in a FORTRAN Program

*
*

This program calls the routines that perform the
functions of the Convert Utility. It creates an
indexed output file named CUSTDATA.DAT from the
specifications in an FDL file named INDEXED.FDL.
The program then loads CUSTDATA.DAT with records
from the sequential file SEQ.DAT. No exception
file is created. This program also returns all
the CONVERT statistics.

Program declarations

*
*
*

IMPLICIT

Set up parameter list: number of options, CREATE,
NOSHARE, FAST_LOAD, MERGE, APPEND, SORT, WORK_FILES,
KEY=O, NOPAD, PAD CHARACTER, NOTRUNCATE,
NOEXIT, NOFIXED_CONTROL, FILL_BUCKETS, NOREAD_CHECK,
NOWRITE_CHECK, FDL, and NOEXCEPTION.

*
*
*
*
*

INTEGER*4 (A - Z)

INTEGER*4
OPTIONS(l9}
1 /18,1,0,1,0,0,1,2,0,0,0,0,0,0,0,0,0,1,0/
Set up statistics list. Pass an array with the
number of statistics that you want. There are four
--- number of files, number of records, exception
records, and good records, in that order.

*
*
*

INTEGER*4

STATSBLK(S} /4,0,0,0,0/

Declare the file names.

CHARACTER
1
1

IN FILE*? /'SEQ.DAT'/,
OUT FILE*12 /'CUSTDATA.DAT' /,
FDL=FILE*ll /'INDEXED.FOL'/

Call the routines in their required order.

STATUS = CONV$PASS_FILES (IN_FILE, OUT_FILE, FDL_FILE}
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))
STATUS = CONV$PASS OPTIONS (OPTIONS}
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))
STATUS = CONV$CONVERT (STATSBLK}
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))
*
1000

Display the statistics information.
WRITE (6, 1000) (STATSBLK (I) I I=2, 5)
FORMAT (lX,'Number of files processed: ',IS/,
1
lX,'Number of records: ',IS/,
1
lX,'Number of exception records: ',IS/,
1
lX,'Number of valid records: ',IS}
END

Example 4-2 shows how to use the Convert routines in a MACRO
program.

CONV-2

Convert (CONV} Routines
4.2 Using the Convert Routines: Examples

Example 4-2

Using the Convert Routines in a MACRO Program

.TITLE CONVSTAT.MAR
This module calls the routines that perform the functions
of the Convert Utility.
It creates an indexed output file
named CUSTDATA.DAT from the specifications in an FDL file
named INDEXED.FDL, and loads CUSTDATA.DAT with records from
the sequential file SEQ.DAT. No exception file is created.
This module also returns all the CONVERT statistics.
Declare the file names.
FILEIN:
FILEOUT:
FDLFILE:

.ASCID
.ASCID
.ASCID

/SEQ.DAT/
/CUSTDATA.DAT/
/INDEXED.FOL/

Set up parameter list.
PARAM LIST:

.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG

18
1
0
1
0
0
1
2
0
0
0
0
0
0
0
0
0
1
0

;NUMBER OF LONGWORDS FOLLOWING
;CREATE
;NOSHARE
;FAST_LOAD
;MERGE
;APPEND
;SORT
;WORK_FILES
;KEY=O
;NOPAD
;PAD CHARACTER
;NOTRUNCATE
;NOEXIT
;NOFIXED_CONTROL
;FILL_BUCKETS
;NOREAD_CHECK
;NOWRITE_CHECK
;FDL
;NOEXCEPTION

Have to use Formatted ASCII Output (FAO) conversion
Declare FAO info for statistics
FAO DESC:

.LONG
132
.LONG
FAO BUFFER
FAO BUFFER:
.BLKB
132
FAO LEN:
.BLKL
1
OUTSTUFF:
.ASCID
#Number of files processed:
Number of records: !UL !/Number of exception records: !UL !/Number of valid records: !UL !/#

!UL !/-

(continued on next page)

CONV-3

Convert (CONV) Routines
4.2 Using the Convert Routines: Examples

Example 4-2 (Cont.)

Using the Convert Routines in a MACRO Program

Have to pass a longword to the CONV$CONVERT ROUTINE with the
number of statistics that we want. There are 4 -- number of
files, number of records, exception records, good records,
in that order.
STATSBLK:

.LONG 4

;The value 4 is the number of statistics
;that we want. we pass this value to
;the END_CONVERT routine.

STATS:

.BLKL 4

;Where we place the statistics. This block
;must follow the longword that tells how
;many stats we want.

TIMES:

. BLKL 5

;Where we place the timing info .

Declare the external routines .
. EXTRN

CONV$PASS FILES,CONV$PASS OPTIONS,CONV$CONVERT,LIB$PUT_OUTPUT,LIB$INIT_TIMER,LIB$SYS_FAOL

.ENTRY

CONV,AM<R2,R3,R4,R5,R6,R7>

Perform operations.

;SAVE THOSE REGISTERS;

Push addresses on arg stack, call routines.

PUS HAL
CALLS

TIMES
#l,GALIB$INIT_TIMER

PUS HAL
PUS HAL
PUS HAL
CALLS
BLBC

FDLFILE
FILEOUT
FILE IN
#3,GACONV$PASS_FILES
R0,10$

PUS HAL
CALLS
BLBC

PARAM LIST
#l,GACONV$PASS_OPTIONS
R0,10$

;Push parameter list
;Make the second call

PUS HAL

STATSBLK

CALLS
BLBC

#l,GACONV$CONVERT
R0,10$

;Push address of the number of
;Statistics
;Perform conversion

;Start the timer

;Push filenames on arg stack
;Pass filenames

Now need an FAO routine to format the counts
$FAOL_S CTRSTR=OUTSTUFF,OUTLEN=FAO_LEN,OUTBUF=FAO_DESC,PRMLST=STATS
BLBC
R0,10$
PUSHAL
CALLS

FAO DESC
#1,GALIB$PUT_OUTPUT

BLBC

R0,10$

;Push output buffer on stack
;Send the output buffer to
;SYS$0UTPUT

(continued on next page)

CONV-4

Convert {CONV) Routines
4.2 Using the Convert Routines: Examples

Example 4-2 {Cont.)

Using the Convert Routines in a MACRO Program

Display times
PUSHAL
CALLS
BLBC
MOVL
10$:

TIMES
#1,GALIB$SHOW_TIMER
R0,10$
#SS$_NORMAL,RO

RET
.END

CONV

Example 4-3 shows how to use the CONV$RECLAIM routine in a
FORTRAN program.
Example 4-3

Using the CONV$RECLAIM Routine in a FORTRAN
Program

*
*

This program calls the routine that performs the
function of the Convert/Reclaim Utility. It
reclaims empty buckets from an indexed file named
PROL3.DAT. It also returns all the CONVERT/RECLAIM
statistics.
Program declarations

*
*
*

IMPLICIT

INTEGER*4 (A - Z)

Set up a statistics block. There are four --- data
buckets scanned, data buckets reclaimed, index
buckets reclaimed, total buckets reclaimed.

*
*

INTEGER*4

OUTSTATS(S) /4,0,0,0,0/

Declare the input file.

CHARACTER

IN FILE*9 /'PROL3.DAT' /

Call the routine.

STATUS = CONV$RECLAIM (IN FILE, OUTSTATS)
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

*
1000

Display the statistics.
WRITE (6, 1000) (OUTSTATS (I), I=2, 5)
FORMAT (lX,'Number of data buckets scanned: ',IS/,
1
lX,'Number of data buckets reclaimed: ',IS/,
1
lX,'Number of index buckets reclaimed: ',IS/,
1
lX,'Total buckets reclaimed: ',IS)
END

Example 4-4 shows how to use the CONV$RECLAIM routine in a MACRO
program.

CONV-5

Convert (CONV) Routines
4.2 Using the Convert Routines: Examples

Example 4-4

Using the CONV$RECLAIM Routine in a MACRO Program

.TITLE CONVREC.MAR
This module calls the routine that performs the
function of the CONVERT/RECLAIM Utility.
It reclaims
empty buckets from an indexed file named PROL3.DAT.
This module also returns all of the CONVERT/RECLAIM
statistics.
Declare the file name .
FILEIN:

. ASCID

/PROL3.DAT/

Declare statistics blocks
OUTSTATS:

.LONG
.BLKL

Declare FAO info for statistics
FAO DESC:

.LONG
132
FAO BUFFER
.LONG
FAO BUFFER:
.BLKB
132
FAO_LEN:
.BLKL
1
OUTSTUFF:
.ASCID #Data buckets scanned:
Data buckets reclaimed: !UL !/Index buckets reclaimed: !UL !/Total buckets reclaimed: !UL !/#

!UL !/-

Looking for four statistics back from the end call.
Use FAO conversion.
Declare the external routines .
. EXTRN

CONV$RECLAIM,LIB$PUT_OUTPUT

.ENTRY

CONV,AM<>

Perform operations.
routines.
PUSHAL
PUSHAL
CALLS
BLBC

Push addresses on arg stack, call

OUTSTATS
FILEIN
#2,GACONV$RECLAIM
R0,10$

;PUSH FILENAME ON ARG STACK
;PASS FILENAME

(continued on next page)

CONV-6

Convert (CONV) Routines
4.2 Using the Convert Routines: Examples

Example 4-4 (Cont.)

Using the CONV$RECLAIM Routine in a MACRO Program

Now need an FAO routine to format the counts.
$FAOL_S

10$:

BLBC

CTRSTR=OUTSTUFF,OUTLEN=FAO_LEN,OUTBUF=FAO_DESC,PRMLST=OUTSTATS+4
R0,10$

PUSHAL
CALLS

FAO DESC
#l,GALIB$PUT_OUTPUT

BLBC
MOVL
RET

R0,10$
#SS$_NORMAL,RO

;PUSH OUTPUT BUFFER ON STACK
;SEND THE OUTPUT BUFFER TO
;SYS$0UTPUT

.END CONV

4.3

Convert Routines
The following pages describe the individual Convert routines.

CONV-7

Convert (CONV) Routines
CONV$CONVERT

CONV$CONVERT Initiate Conversion
The CONV$CONVERT routine uses the Convert Utility to perform the actual
conversion begun with CONV$PASS_FILES and CONV$PASS_OPTIONS.
Optionally, the routine can return statistics about the conversion.

FORMAT

CONV$CONVERT [status_block_address] [,flags]

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword {unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

status_block_address
VMS usage:
type:
access:
mechanism:

vector_longword_unsigned
longword {unsigned)
write only
by reference

The conversion statistics. The status_block_address argument is the
address of a variable-length array of longwords that receives statistics
about the conversion. The format of the array is as follows:
number of statistics
number of files
number of records
number of exception records
number of valid records

flags
VMS usage:
type:
access:
mechanism:

mask_longword
longword {unsigned)
read only
by reference

Flags (or masks) that control how the fdl_filespec argument is interpreted
and how errors are signalled. The flags argument is the address of a
longword containing control flags (or a mask). If you omit the flags
argument or specify it as zero, no flags are set. The flags and their
meanings are described in the following table.

CONV-8

Convert (CONV) Routines
CONV$CONVERT

Flag

Function

CONV$V_FDL_STRING

Interprets the fdl_fllespec argument supplied in the call
to CONV$PASS_FILES as an FOL specification in string
form. By default, this argument is interpreted as a file
name of an FOL file.

CONV$V_SIGNAL

Signals any error. By default, the status code is returned
to the calling image.

This argument is optional. By default, an error status is returned rather
than signalled.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

CONV$_BADBLK

Invalid option block.

CONV$_BADLOGIC

Internal logic error detected.

CONV$_BADSORT

Error trying to sort input file.

CONV$_CLOSEIN

Error closing file specification as input.

CONV$_CLOSEOUT

Error closing file specification as output.

CONV$_CONFQUAL

Conflicting qualifiers.

CONV$_CREA_ERR

Error creating output file.

CONV$_CREATEDSTM

File specification has been created in stream format.

CONV$_DELPRI

Cannot delete primary key.

CONV$_DUP

Duplicate key encountered.

CONV$_EXTN_ERR

Unable to extend output file.

CONV$_FATALEXC

Fatal exception encountered.

CONV$_FILLIM

Exceeded open file limit.

CONV$_1DX_LIM

Exceeded maximum index level.

CONV$_1LL_KEY

Illegal key or value out of range.

CONV$_1LL_VALUE

Illegal parameter value.

CONV$_1NP_FILES

Too many input files.

CONV$_1NSVIRMEM

Insufficient virtual memory.

CONV$_KEY

Invalid record key.

CONV$_LOADIDX

Error loading secondary index n.

CONV$~NARG

Wrong number of arguments.

CONV$_NOKEY

No such key.

CONV$_NOTIDX

File is not an indexed file.

CONV$_NOTSEQ

Output file is not a sequential file.

CONV$_NOWILD

No wildcard permitted.

CONV$_0PENEXC

Error opening exception file specification.

CONV$_0PENIN

Error opening file specification as input.

CONV$_0PENOUT

Error opening file specification as output.

CONV$_0RDER

Routine called out of order.

CONV-9

Convert {CONV) Routines
CONV$CONVERT

CONV-10

CONV$_PAD

PAD option ignored; output record format not fixed.

CONV$_PLV

Unsupported prolog version.

CONV$_PROERR

Error reading prolog.

CONV$_PROL_WRT

Prolog write error.

CONV$_READERR

Error reading file specification.

CONV$_REX

Record already exists.

CONV$_RMS

Record caused RMS severe error.

CONV$_RSK

Record shorter than primary key.

CONV$_RSZ

Record does not fit in block/bucket.

CONV$_RTL

Record longer than maximum record length.

CONV$_RTS

Record too short for fixed record format file.

CONV$_SEQ

Record not in order.

CONV$_UDF_BKS

Cannot convert UDF records into spanned file.

CONV$_UDF_BLK

Cannot fit UDF records into single block bucket.

CONV$_VALERR

Specified value is out of legal range.

CONV$_VFC

Record too short to fill fixed part of VFC record.

CONV$_WRITEERR

Error writing file specification.

Convert (CONV) Routines
CONV$PASS_FILES

CONV$PASS_FILES Specify Conversion Files
The CONV$PASS_FILES routine specifies a file to be converted using the
CONV$CONVERT routine.

input_filespec ,output_filespec
,[fd/_filespec]
,[exception_ filespec]
,[flags]

FORMAT

CONV$PASS_FILES

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

input_filespec
VMS usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor-fixed-length string descriptor
The name of the file to be converted. The input_filespec argument is
the address of a string descriptor pointing to the name of the file to be
converted.

output_filespec
VMS usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor-fixed-length string descriptor
The name of the file that receives the records from the input file. The
output_filespec argument is the address of a string descriptor pointing to
the name of the file that receives the records from the input file.

fd/_filespec
VMS usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor-fixed-length string descriptor
The name of the FDL file that defines the output file. The fdl_filespec
argument is the address of a string descriptor pointing to the name of the
FDL file.

CONV-11

Convert (CONV) Routines
CONV$PASS_FILES

exception_filespec
VMS usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor-fixed-length string descriptor
The name of the file that receives copies of records that cannot be written
to the output file. The exception_filespec argument is the address of a
· string descriptor pointing to this name.

flags
VMS usage: mask_longword
type:
longword (unsigned)
access:
read only
mechanism: by reference
Flags (or masks) that control how the fdl_filespec argument is interpreted
and how errors are signalled. The :flags argument is the address of a
longword containing the control flags (or mask). If you omit this argument
or specify it as zero, no flags are set. If you specify a flag, it remains in
effect until you explicitly reset it in a subsequent call to a Convert routine.

The flags and their meanings are described in the following table.
Flag

Function

CONV$V_FOL_STRING

Interprets the fdl_filespec argument as an FOL
specification in string form. By default, this argument
is interpreted as a file name of an FOL file.

CONV$V_SIGNAL

Signals any error. By default, the status code is returned
to the calling image.

This argument is optional. By default, an error status is returned rather
than signalled.

DESCRIPTION

The CONV$PASS_FILES routine specifies a file to be converted using the
CONV$CONVERT routine. A single call to CONV$PASS_FILES allows
you to specify an input file, an output file, an FDL file, and an exception
file. If you have multiple input files, you must call CONV$PASS_FILES
once for each file. You need to specify only the input_filespec argument
for the additional files, as follows:
status = CONV$PASS_FILES (input_filespec)

The additional calls must immediately follow the original call that
specified the output file specification. You may specify as many as 9
additional files for a maximum total of 10.
Wildcard characters are not allowed in the file specifications passed to the
Convert routines.

CONV-12

Convert (CONV) Routines
CONV$PASS_FILES

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

CONV$_1NP_FILES

Too many input files.

CONV$_1NSVIRMEM

Insufficient virtual memory.

CONV$_NARG

Wrong number of arguments.

CONV$_0RDER

Routine called out of order.

CONV-13

Convert {CONV) Routines
CONV$PASS_OPTIONS

CONV$PASS_OPTIONS Specify Processing Options
The CONV$PASS_OPTIONS routine specifies which qualifiers are to be used
by the Convert Utility (CONVERT).

FORMAT

CONV$PASS_OPTIONS

RETURNS

VMS usage:
type:
access:
mechanism:

[parameter_list_address}
[,flags]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this :routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

parameter_list_address
vector_longword_unsigned
longword (unsigned)
read only
by reference
Parameter list specifying information about the CONVERT qualifiers. The
parameter_list_address argument is the address of a variable-length
array of longwords. The first longword in the array is the number of
parameters in the array. Each subsequent longword in the array (from the
second one on) is associated with one of the CONVERT qualifiers. These
functions are described in the VMS Convert and Convert I Reclaim Utility
VMS usage:
type:
access:
mechanism:

Manual.
To set one of the CONVERT qualifiers, you place a 1 in the longword
associated with that qualifier. If you do not want to set one of the
qualifiers (which has the same effect as using the negative form of
the qualifier on the CONVERT command), you place a 0 in the correct
longword.
If you do not specify parameter_list_address, then the following default

values apply. You can also take all default values by passing the address of
a longword that contains 0, which means a parameter list of 0 longwords.
If you have specified all the values you want set, you may want to take the

default values for all subsequent qualifiers in the list. You may omit the
subsequent ones if you give the array length in the first longword. This is
why the first longword contains a count of the qualifiers.
The qualifiers must appear in the following order.

CONV-14

Convert (CONV) Routines
CONV$PASS_OPTIONS

Qualifier

Default Value (in
Longwords)

CREATE

Default CONVERT Value

/CREATE

/NOS HARE

FAST_LOAD

1
0
0

/FAST_LOAD

MERGE
APPEND
SORT

/NOMERGE
/NOAPPEND
/SORT

WORK_FILES

/WORK_FILES=2

KEY

/KEY=O

PAD

/NO PAD

Pad character

Pad character=O

TRUNCATE

/NOTRUNCATE

EXIT

/NOEXIT

FIXED_CONTROL

/NOFIXED_CONTROL

FILL_BUCKETS

/NOFILL_BUCKETS

READ_CHECK

/NOREAD_CHECK

WRITE_CHECK

/NOWRITE_CHECK

FOL

/NOFDL

EXCEPTION

/NOEXCEPTION

PROLOG

No default

System or process default

If you want to use the default null character for the PAD qualifier, you
should specify 0 in the pad character longword. You can also specify the

default null character by omitting the pad character longword. However,
in this case, you must also take the default values for all subsequent
qualifiers. To specify a pad character other than 0, place the ASCII value
of the character you want to use in the PAD qualifier longword.
If you specify /EXIT and the utility encounters an exception record, then

CONVERT returns with a fatal exception status.
If you specify an FDL file specification in the CONV$PASS_FILES routine,
you must place a 1 in the FDL longword. If you also specify an exceptions
file specification in the CONV$PASS_FILES routine, you must place a 1

in the EXCEPTION longword. You may specify either, both, or neither of
these files, but the values in the CONV$PASS_FILES call must match the
values in the parameter list. If they do not, the routine returns an error.
If you specify the PROLOG longword, note that this overrides the KEY

PROLOG attribute supplied by the FDL file. You must supply one of three
values for the PROLOG longword if you use it. The three values are 0,
2, and 3. The value 0 means that you want to use the system or process
prolog type. The value 2 means that you want to create a Prolog 1 or 2
file in all instances, even when circumstances would allow you to create
a Prolog 3 file. The value 3 means that you want to create a Prolog 3 file
and, if circumstances do not allow you to, you want the conversion to fail.

CONV-15

Convert (CONV) Routines
CONV$PASS_OPTIONS

flags
VMS usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by reference

Flags (or masks) that control how the fdl_filespec argument is interpreted
and how errors are signalled. The :flags argument is the address of
a longword containing the control flags (or a mask). If you omit this
argument or specify it as zero, no flags. are set. If you specify a flag, it
remains in effect until you explicitly reset it in a subsequent call to a
Convert routine.
The flags and their meanings are described in the following table.
Flag

Function

CONV$V_FOL_STRING

Interprets the fdl_fllespec argument supplied in the call
to CONV$PASS_FILES as an FOL specification in string
form. By default, this argument is interpreted as a file
name of an FOL file.

FDL$V_SIGNAL

Signals any error. By default, the status code is returned
to the calling image.

This argument is optional. By default, an error status is returned rather
than signalled.

DESCRIPTION

The following example shows how to use the option array to reflect the
CONVERT command:
$

CONVERT/FAST_LOAD/SORT/WORK_FILES=6/EXIT

Specifies that 12 longwords follow

Specifies the /CREATE option

Specifies the /NOSHARE option

Specifies the /FASTLOAO option

Specifies the /NOMERGE option

Specifies the /NOAPPENO option

Specifies the /SORT option

Specifies the /WORKFILES=6 option

Specifies the /KEY=0 option

Specifies the /NOPAO option

Specifies the null pad character

Specifies the /NOTRUNCATE option
Specifies the /EXIT option

CONV-16

Convert (CONV) Routines
CONV$PASS_OPTIONS

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

CONV$_BADBLK

Invalid option block.

CONV$_CONFQUAL

Conflicting qualifiers.

CONV$_1NSVIRMEM

Insufficient virtual memory.

CONV$_NARG

Wrong number of arguments.

CONV$_0PENEXC

Error opening exception file filespec.

CONV$_0RDER

Routine called out of order.

CONV-17

Convert (CONY) Routines
CONV$RECLAIM

CONV$RECLAIM

Invoke Convert/Reclaim Utility

The CONV$RECLAIM routine invokes the functions of the Convert/Reclaim
Utility.

FORMAT

CONV$RECLAIM

RETURNS

VMS usage:
type:
access:
mechanism:

input_filespec [,statistics_blk]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

input_filespec
VMS usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor-fixed-length string descriptor
Name of the Prolog 3 indexed file to be reclaimed. The input_filespec
argument is the address of a string descriptor pointing to the name of the
Prolog 3 indexed file.

statistics blk
VMS usage: vector_longword_unsigned
type:
longword (unsigned)
access:
modify
mechanism: by reference
Bucket reclamation statistics. The statistics_blk argument is the
address of a variable-length array of longwords to receive statistics on
the bucket reclamation. You can choose which statistics you want returned
by specifying a number in the first element of the array. This number
determines how many of the four possible statistics the routine returns.
Depending on the number chosen, the routine returns the statistics in the
statistics array in the order specified by the following format:
A:

Number of statistics
Data buckets scanned
Data buckets reclaimed
Index buckets reclaimed
Total buckets reclaimed

CONV-18

Convert (CONV) Routines
CONV$RECLAIM

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

CONV$_BADLOGIC

Internal logic error detected.

CONV$_1NSVIRMEM

Insufficient virtual memory.

CONV$_1NVBKT

Invalid bucket at VBN n.

CONV$_NOTIDX

File is not an index file.

CONV$_0PENIN

Error opening fi/espec as input.

CONV$_PLV

Unsupported prolog version.

CONV$_PROERR

Error reading prolog.

CONV$_PROL_WRT

Prolog write error.

CONV$_READERR

Error reading filespec.

CONV$_NOWILD

No wildcard permitted.

CONV$_WRITEERR

Error writing output file.

CONV-19

Data Compression/Expansion (DCX) Routines

The set of routines described in this chapter comprises the VMS Data
Compression/Expansion (DCX) facility. There is no DCL-level interface to
this facility nor is there a DCX Utility.

5.1

Introduction to DCX Routines
Using the DCX routines described in this chapter, you can decrease the
size of text, binary data, images, and any other type of data. Compressed
data uses less space, but there is a trade-off in terms of access time to the
data. Compressed data must first be expanded to its original state before
it is usable. Thus, infrequently accessed data makes a good candidate for
data compression.
The DCX facility provides routines that analyze and compress data records
and expand the compressed records to their original state. In this process,
no information is lost. A data record that has been compressed and then
expanded is in the same state as it was before it was compressed.
Most collections of data can be reduced in size by DCX. However, there
is no guarantee that the size of an individual data record will always be
smaller after compression; in fact, some may grow larger.
The DCX facility allows for the independent analysis, compression, and
expansion of more than one stream of data records at the same time.
This capability is provided by means of a "context variable," which is an
argument in each DCX routine. Most applications have no need for this
capability; for these applications, there is a single context variable.
The procedure for using the DCX routines to perform data compression
and expansion consists of three major steps. The list under each of the
following steps shows the DCX routines used to perform that step:
1

Analyze some or all of the data records in the data file to produce a
mapping function (or map).
DCX$ANALYZE_INIT
DCX$ANALYZE_DATA
DCX$MAKE_MAP
DCX$ANALYZE_DONE

Compress the data records in the file on the basis of the mapping
function.
DCX$COMPRESS_INIT
DCX$COMPRESS_DATA
DCX$COMPRESS_DONE

DCX-1

Data Compression/Expansion (DCX) Routines
5.1 Introduction to DCX Routines

Expand the compressed data records on the basis of the mapping
function.
DCX$EXPAND_INIT
DCX$EXPAND_DATA
DCX$EXPAND_DONE

Some of the DCX routines make calls to various Run-Time Library (RTL)
routines, LIB$GET_VM, for example. If any of these RTL routines should
fail, a return status code indicating the cause of the failure is returned. In
such a case, you must refer to the documentation of the appropriate RTL
routine to determine the cause of the failure. The status codes documented
in this chapter are primarily DCX status codes.
Note also that the application program should declare referenced constants
and return status symbols as external symbols; these symbols are resolved
upon linking with the utility shareable image.

5.2

Using the DCX Routines: Examples
Examples 5-1 and 5-2 show how to use the DCX routines in VAX
FORTRAN programs.
Example 5-1

Compressing a File in a VAX FORTRAN Program

PROGRAM COMPRESS FILES
! COMPRESSION OF FILES

! status variable
INTEGER STATUS,
2
IOSTAT,
2
IO_OK,
2
STATUS OK
PARAMETER (IO_OK = 0)
PARAMETER (STATUS_OK = 1)
INCLUDE I ($FORDEF)'
EXTERNAL DCX$_AGAIN
! context variable
INTEGER CONTEXT
! compression/expansion function
INTEGER MAP,
2
MAP LEN

! normal .file name, length, and logical unit number
CHARACTER*256 NORM NAME
INTEGER*2 NORM LEN
INTEGER NORM LUN
! compressed-file name, length, and logical unit number
CHARACTER*256 COMP NAME
INTEGER*2 COMP LEN
INTEGER COMP LUN
(continued on next page)

DCX-2

Data Compression/Expansion (DCX) Routines
5.2 Using the DCX Routines: Examples

Example 5-1 (Cont.)

Compressing a File in a VAX FORTRAN Program

! Logical end-of-file
LOGICAL EOF
! record buffers;
32764 is maximum record size
CHARACTER*32764 RECORD,
2
RECORD2
INTEGER RECORD_LEN,
2
RECORD2 LEN
! user routine
INTEGER GET_MAP,
2
WRITE MAP
! Library procedures
INTEGER DCX$ANALYZE INIT,
2
DCX$ANALYZE-DONE,
2
DCX$COMPRESS_INIT,
2
DCX$COMPRESS DATA,
2
DCX$COMPRESS-DONE,
2
LIB$GET INPUT,
2
LIB$GET-LUN,
2
LIB$FREE_VM

get name of file to be compressed and open it
STATUS
LIB$GET INPUT (NORM NAME,
2
'File to compress: ',
2
NORM LEN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
STATUS = LIB$GET LUN (NORM LUN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
OPEN (UNIT = NORM_LUN,
2
FILE= NORM_NAME(l:NORM_LEN),
2
CARRIAGECONTROL ='NONE',
2
STATUS= 'OLD')

************
ANALYZE DATA
************
initialize work area
STATUS = DCX$ANALYZE INIT (CONTEXT)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
! get compression/expansion function (map)
STATUS
GET MAP (NORM LUN,
2
CONTEXT,
2
MAP,
2
MAP LEN)
DO WHILE (STATUS .EQ.-%LOC(DCX$_AGAIN))
! go back to beginning of file
REWIND (UNIT = NORM_LUN)
! try map again
STATUS = GET MAP (NORM_LUN,
2
CONTEXT,
2
MAP,
2
MAP_LEN)
END DO
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
! clean up work area
STATUS = DCX$ANALYZE_DONE (CONTEXT)
(continued on next page)

DCX-3

Data Compression/Expansion (DCX) Routines
5.2 Using the DCX Routines: Examples

Example 5-1 (Cont.)

Compressing a File in a VAX FORTRAN Program

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))

*************
COMPRESS DATA

*************
go back to beginning of file to be compressed
REWIND (UNIT = NORM LUN)
! open file to hold-compressed records
STATUS = LIB$GET LUN (COMP LUN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
STATUS
LIB$GET INPUT (COMP NAME,
2
'File for compressed records: '
2
COMP LEN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
OPEN (UNIT = COMP_LUN,
2
FILE= COMP_NAME(l:COMP_LEN),
2
STATUS= 'NEW',
2
FORM= 'UNFORMATTED')
initialize work area
STATUS = DCX$COMPRESS_INIT (CONTEXT,
2
MAP)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
! write compression/expansion function to new file
CALL WRITE MAP (COMP_LUN,
2
%VAL(MAP),
2
MAP_LEN)
read record from file to be compressed
EOF = .FALSE.
READ (UNIT = NORM_LUN,
2
FMT = ' (Q, A) ',
2
IOSTAT = IOSTAT) RECORD_LEN,
2
RECORD(l:RECORD_LEN)
IF (IOSTAT .NE. IO_OK) THEN
CALL ERRSNS (,,,,STATUS)
IF (STATUS .NE. FOR$ ENDDURREA) THEN
CALL LIB$SIGNAL (%VAL(STATUS))
ELSE
EOF = .TRUE.
STATUS
STATUS OK
END IF
END IF
(continued on next page)

DCX-4

Data Compression/Expansion (DCX) Routines
5.2 Using the DCX Routines: Examples

Example 5-1 (Cont.)

Compressing a File in a VAX FORTRAN Program

DO WHILE ( . NOT. EOF)
! compress the record
STATUS = DCX$COMPRESS_DATA (CONTEXT,
2
RECORD ( 1 : RECORD- LEN) I
2
RECORD2,
2
RECORD2 LEN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
! write compressed record to new file
WRITE (UNIT = COMP_LUN) RECORD2_LEN
WRITE (UNIT = COMP LUN) RECORD2 (l:RECORD2 LEN)
! read from file to be compressed
READ (UNIT = NORM_LUN,
2
FMT = I (Q, A) I I
2
IOSTAT = IOSTAT) RECORD_LEN,
2
RECORD (l:RECORD_LEN)
IF (IOSTAT .NE. IO_OK) THEN
CALL ERRSNS (,,,,STATUS)
IF (STATUS .NE. FOR$ ENDDURREA) THEN
CALL LIB$SIGNAL (%VAL(STATUS))
ELSE
EOF = .TRUE.
STATUS
STATUS_OK
END IF
END IF
END DO
close files and clean up work area
CLOSE (NORM_LUN)
CLOSE (COMP LUN)
STATUS = LIB$FREE VM (MAP LEN,
2
MAP)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
STATUS = DCX$COMPRESS DONE (CONTEXT)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
END
INTEGER FUNCTION GET MAP (LUN,
passed
2
CONTEXT,
passed
2
MAP,
returned
2
MAP LEN)
returned
Analyzes records in file opened on logical
unit LUN and then attempts to create a
compression/expansion function using
DCX$MAKE_MAP.
dummy arguments
context variable
INTEGER CONTEXT
! logical unit number
INTEGER LUN
! compression/expansion function
INTEGER MAP,
2
MAP LEN

(continued on next page)

DCX-5

Data Compression/Expansion (DCX) Routines
5.2 Using the DCX Routines: Examples

Example 5-1 (Cont.)

Compressing a File in a VAX FORTRAN Program

l status variable
INTEGER STATUS,
.2
IOSTAT,
2
IO_OK,
2
STATUS OK
PARAMETER (IO_OK = 0)
PARAMETER (STATUS OK = 1)
INCLUDE ' ($FORDEF)'
! Logical end-of-file
LOGICAL EOF
! record buffer;
32764 is the maximum record size
CHARACTER*32764 RECORD
INTEGER RECORD LEN

! library procedures
INTEGER DCX$ANALYZE DATA,
2
DCX$MAKE_MAP
! analyze records
EOF = .FALSE.
READ (UNIT = LUN,
2
FMT = I (QI A) I I
2
IOSTAT = IOSTAT) RECORD_LEN,RECORD
IF (IOSTAT .NE. IO_OK) THEN
CALL ERRSNS (,,,,STATUS)
IF (STATUS .NE. FOR$ ENDDURREA) THEN
CALL LIB$SIGNAL (%VAL(STATUS))
ELSE
EOF = .TRUE.
STATUS
STATUS OK
END IF
END IF

DO WHILE (.NOT. EOF)
STATUS = DCX$ANALYZE_DATA (CONTEXT,
2
RECORD(l:RECORD LEN))
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
READ (UNIT = LUN,
2
FMT = I (QI A) I I
2
IOSTAT = IOSTAT) RECORD_LEN,RECORD
IF (IOSTAT .NE. IO_OK) THEN
CALL ERRSNS (,,,,STATUS)
IF (STATUS .NE. FOR$ ENDDURREA) THEN
CALL LIB$SIGNAL (%VAL(STATUS))
ELSE
EOF = .TRUE.
STATUS
STATUS OK
END IF
END IF
END DO
STATUS
2

2
GET MAP

DCX$MAKE_MAP (CONTEXT,
MAP,
MAP_LEN)
STATUS

END
{continued on next page)

DCX-6

Data Compression/Expansion (DCX) Routines
5.2 Using the DCX Routines: Examples

Example 5-1 (Cont.)

Compressing a File in a VAX FORTRAN Program

SUBROUTINE WRITE_MAP (LUN,
passed
2
MAP,
passed
2
MAP_LEN)
passed
IMPLICIT INTEGER(A-Z)
write compression/expansion function
! to file of compressed data
! dummy arguments
INTEGER LUN,
2
MAP LEN
BYTE MAP (MAP_LEN)

logical unit of file
length of function
compression/expansion function

! write map length
WRITE (UNIT
LUN) MAP LEN
! write map
WRITE (UNIT = LUN) MAP

END

Example 5-2

Expanding a Compressed File in a VAX FORTRAN
Program

PROGRAM EXPAND FILES
IMPLICIT INTEGER(A-Z)
! EXPANSION OF COMPRESSED FILES
! file names, lengths, and logical unit numbers
CHARACTER*256 OLD FILE,
2
NEW-FILE
INTEGER*2 OLD_LEN,
2
NEW LEN
INTEGER OLD_LUN,
2
NEW LUN
! length of compression/expansion function
INTEGER MAP,
2
MAP LEN
! user routine
EXTERNAL EXPAND DATA

! library procedures
INTEGER LIB$GET LUN,
2
LIB$GET-INPUT,
2
LIB$GET-VM,
2
LIB$FREE_VM

(continued on next page)

DCX-7

Data Compression/Expansion (DCX) Routines
5.2 Using the DCX Routines: Examples

Example 5-2 (Cont.)

Expanding a Compressed File in a VAX FORTRAN
Program

! open file to expand
STATUS = LIB$GET LON (OLD LON)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
STATUS
LIB$GET_INPUT (OLD_FILE,
2
'File to expand: ',
2
OLD LEN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
OPEN (UNIT = OLD_LUN,
2
STATUS= 'OLD',
2
FILE= OLD_FILE(l:OLD_LEN),
2
FORM= 'UNFORMATTED')
open file to hold expanded data
STATUS = LIB$GET LON (NEW LON)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
STATUS
LIB$GET INPUT (NEW FILE,
2
'File to hold expanded data: '
2
NEW LEN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
OPEN (UNIT = NEW_LUN,
2
STATUS = 'NEW',
2
CARRIAGECONTROL ='LIST',
2
FILE= NEW_FILE(l:NEW_LEN))

expand file
get length of compression/expansion function
READ (UNIT = OLD LUN) MAP LEN
STATUS = LIB$GET=VM (MAP_LEN,
2
MAP)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
! expand records
CALL EXPAND DATA (%VAL (MAP) ,
2
MAP_LEN,
length of function
2
OLD_LUN,
compressed data file
2
NEW_LUN)
expanded data file
delete virtual memory used for function
STATUS = LIB$FREE_VM (MAP_LEN,
2
MAP)
IF ( . NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
END
SUBROUTINE EXPAND DATA (MAP,
2
MAP_LEN,
2
OLD_LUN,
2
NEW_LUN)
expand data program
dummy arguments
INTEGER MAP LEN,
2
OLD=LUN,
2
NEW LUN
BYTE MAP(MAP_LEN)

passed
passed
passed
passed

length of expansion function
logical unit of compressed file
logical unit of expanded file
array containing the function
(continued on next page)

DCX-8

.Data Compression/Expansion (DCX) Routines
5.2 Using the DCX Routines: Examples

Example 5-2 (Cont.)

Expanding a Compressed File in a VAX FORTRAN
Program

! status variables
INTEGER STATUS,
2
IOSTAT,
2
IO_OK,
2
STATUS OK
PARAMETER (IO_OK = 0)
PARAMETER (STATUS_OK
INCLUDE' ($FORDEF)'

! context variable
INTEGER CONTEXT
! logical end_of_file
LOGICAL EOF
! record buffers
CHARACTER*32764 RECORD,
2
RECORD2
INTEGER RECORD_LEN,
2
RECORD2 LEN

! library procedures
INTEGER DCX$EXPAND INIT,
2
DCX$EXPAND-DATA,
2
DCX$EXPAND=DONE

read data compression/expansion function
READ (UNIT = OLD LUN) MAP
! initialize work area
STATUS = DCX$EXPAND_INIT (CONTEXT,
2
%LOC(MAP(l)))
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
! expand records
EOF = .FALSE.
! read length of compressed record
READ (UNIT = OLD LUN,
2
IOSTAT = IOSTAT) RECORD_LEN
IF (IOSTAT .NE. IO_OK) THEN
CALL ERRSNS (,,,,STATUS)
IF (STATUS .NE. FOR$ ENDDURREA) THEN
CALL LIB$SIGNAL (%VAL(STATUS))
ELSE
EOF = .TRUE.
STATUS
STATUS OK
END IF
END IF
DO WHILE (.NOT. EOF)
! read compressed record
READ (UNIT = OLD_LUN) RECORD (l:RECORD_LEN)
! expand record
STATUS = DCX$EXPAND_DATA (CONTEXT,
2
RECORD(l:RECORD_LEN),
2
RECORD2,
2
RECORD2_LEN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
! write expanded record to new file
WRITE (UNIT = NEW_LUN,
2
FMT ='(A)') RECORD2(l:RECORD2_LEN)
! read length of compressed record
(continued on next page)

DCX-9

Data Compression/Expansion {DCX) Routines
5.2 Using the DCX Routines: Examples

Example 5-2 (Cont.)

Expanding a Compressed File in a VAX FORTRAN
Program

READ (UNIT = OLD_LUN,
IOSTAT = IOSTAT) RECORD_LEN
IF (IOSTAT .NE. IO_OK) THEN
CALL ERRSNS (,,,,STATUS)
IF (STATUS .NE. FOR$ ENDDURREA) THEN
CALL LIB$SIGNAL (%VAL(STATUS))
ELSE
EOF = .TRUE.
STATUS = STATUS OK
END IF
END IF
END DO

clean up work area
STATUS = DCX$EXPAND DONE (CONTEXT)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
END

5.3

DCX Routines
The following pages describe the individual DCX routines.

DCX-10

Data Compression/Expansion {DCX) Routines

DCX$ANALYZE_DATA

Perform Statistical Analysis
on a Data Record

The DCX$ANALYZE_DATA routine performs statistical analysis on a data
record.
The results of the analysis are accumulated internally in the context area and
are used by the DCX$MAKE_MAP routine to compute the mapping function.

FORMAT

DCX$ANALVZE_DATA

RETURNS

VMS usage:
type:
access:
mechanism:

context ,record

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
read only
by reference

Value identifying the data stream that DCX$ANALYZE_DATA analyzes.
The context argument is the address of a longword containing this value.
DCX$ANALYZE_INIT initializes this value; you should not modify it. You
can define multiple context arguments to identify multiple data streams
that are processed simultaneously.

record
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Record to be analyzed. DCX$ANALYZE_DATA reads the record
argument, which is the address of a descriptor for the record string.
The maximum length of the record string is 65,535 characters.

DESCRIPTION

The DCX$ANALYZE_DATA routine performs statistical analysis on a
single data record. This routine is called once for each data record to be
analyzed.

DCX-11

Data Compression/Expansion {DCX) Routines

DCX$ANALVZE_DATA
During analysis, the data compression facility gathers information that
DCX$MAKE_MAP uses to create the compression/expansion function
for the file. After the data records have been analyzed, you call the
DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status code
from DCX$MAKE_MAP, you must again analyze the same data records (in
the same order) using DCX$ANALYZE_DATA and then call DCX$MAKE_
MAP again. On the second iteration, DCX$MAKE_MAP returns the
DCX$_NORMAL status code, and the data analysis is complete.

CONDITION
VALUES
RETURNED

DCX$_1NVCTX

Error. The context variable is invalid, or the context
area is invalid or corrupted. This may be caused by
a failure to call the appropriate routine to initialize the
context variable or by an application program error.

DCX$_NORMAL

Successful completion.

This routine also returns any condition values returned by
LIB$ANALYZE_SDESC_R2.

DCX-12

Data Compression/Expansion {DCX) Routines

DCX$ANALVZE_DONE

Specify Analysis Completed

The DCX$ANALYZE_DONE routine deletes the context area and sets the
context variable to zero, thus undoing the work of the DCX$ANALYZE_INIT
routine.
You call DCX$ANALYZE_DONE after data records have been analyzed and
the DCX$MAKE_MAP routine has created the map.

FORMAT

DCX$ANALYZE_DONE

RETURNS

VMS usage:
type:
access:
mechanism:

context

cond_value
longword
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

context
context
longword
modify
by reference
Value identifying the data stream that DCX$ANALYZE_DONE deletes.
The context argument is the address of a longword containing this value.
DCX$ANALYZE_INIT initializes this value; you should not modify it. You
can define multiple context arguments to identify multiple data streams
that are processed simultaneously.
VMS usage:
type:
access:
mechanism:

CONDITION
VALUES
RETURNED

DCX$_1NVCTX

DCX$_NORMAL

Successful completion.

This routine also returns any condition values returned by
LIB$FREE_VM.

DCX-13

Data Compression/Expansion {DCX) Routines
DCX$ANALYZE_INIT

DCX$ANALYZE_INIT Initialize Analysis Context
The DCX$ANALYZE_INIT routine initializes the context area for a statistical
analysis of the data records to be compressed.

FORMAT

DCX$ANALVZE_INIT

RETURNS

VMS usage:
type:
access:
mechanism:

context [,item_ code ,item_ value]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage:
type:
access:
mechanism:

context
longword {unsigned)
write only
by reference

Value identifying the data stream that DCX$ANALYZE_INIT initializes.
The context argument is the address of a longword containing this value.
DCX$ANALYZE_INIT writes this context into the context argument; you
should not modify its value. You can define multiple context arguments
to identify multiple data streams that are processed simultaneously.

item code
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword {unsigned)
read only
by reference

Item code specifying information that you want DCX$ANALYZE_INIT to
use in its analysis of data records and in its computation of the mapping
function. DCX$ANALYZE_INIT reads this item_code argument, which is
the address of the longword contained in the item code.
For each item_code argument specified in the call, you must also specify a
corresponding item_value argument. The item_value argument contains
the interpretation of the item_code argument.
The following symbolic names are the five legal values of the item_code
argument:
DCX$C_BOUNDED
DCX$C_EST_BYTES
DCX$C_EST_RECORDS
DCX$C_LIST
DCX$C_ONE_PASS

DCX-14

Data Compression/Expansion {DCX) Routines
DCX$ANALVZE_INIT

item_value
VMS usage: longword_unsigned
type:

longword (unsigned)

access:
read only
mechanism: by reference
Value of the corresponding item_code argument. DCX$ANALYZE_INIT
reads the item_value argument, which is the address of a longword
containing the item value.

The item_code and item_value arguments always occur as a pair, and
together they specify one piece of "advice" for the DCX routines to use in
computing the map function. Note that, unless stated otherwise in the list
of item codes and item values, no piece of "advice" is binding on DCX; that
is, DCX is free to follow or not to follow the "advice."
The following table shows, for each item_code argument, the possible
values for the corresponding item_value argument.
Item Code

Corresponding Item Value

DCX$C_BOUNDED

A Boolean variable. If bit <0> is true (equals 1), you
are stating your intention to submit for analysis all data
records that will be compressed; doing so often enables
DCX to compute a better compression algorithm. If bit
<0> is false (equals 0) or if the DCX$C_BOUNDED item
code is not specified, DCX computes a compression
algorithm without regard for whether all records to be
compressed will also be submitted for analysis.

DCX$C_EST_BYTES

A longword value containing your estimate of the
total number of data bytes that will be submitted for
compression. This estimate is useful in those cases
where fewer than the total number of bytes are presented
for analysis. If you do not specify the DCX$C_EST_
BYTES item code, DCX submits for compression the
same number of bytes that was presented. for analysis.
Note that you may specify DCX$C_EST_RECORDS or
DCX$C_EST_BYTES, or both.

DCX$C_EST_RECORDS

A longword value containing your estimate of the
total number of data records that will be submitted
for compression. This estimate is useful in those
cases where fewer than the total number of records
are presented for analysis. If you do not specify the
DCX$C_EST_RECORDS item code, DCX submits
for compression the same number of bytes that was
presented for analysis.

DCX-15

Data Compression/Expansion (DCX) Routines
DCX$ANALYZE_INIT

DESCRIPTION

CONDITION
VALUES
RETURNED

Item Code

Corresponding Item Value

DCX$C_LIST

Address of an array of 2* n+ 1 longwords. The first
longword in the array contains the value 2* n+ 1. The
remaining longwords are paired; there are n pairs. The
first member of the pair is an item code, and the second
member of the pair is the address of its corresponding
item value. The DCX$C_LIST item code allows you to
construct an array of item-code and item-value pairs
and then to pass the entire array to DCX$ANALYZE_
INIT. This is useful when your language has difficulty
interpreting variable-length argument lists. Note that the
DCX$C_LIST item code may be specified, in a single
call, alone or together with any of the other item-code
and item-value pairs.

DCX$C_ONE_PASS

A Boolean variable. If bit <0> is true (equals 1), you
make a binding request that DCX make only one
pass over the data to be analyzed. If bit <0> is false
(equals 0) or if the DCX$C_ONE_PASS item code is not
specified, DCX may make multiple passes over the data,
as required. Typically, DCX makes one pass.

The DCX$ANALyzE_INIT routine initializes the context area for a
statistical analysis of the data records to be compressed. The first (and
typically the only) argument passed to DCX$ANALYZE_INIT is an integer
variable to contain the context value. The data compression facility
assigns a value to the context variable and associates the value with the
created work area. Each time you want a record analyzed in that area,
specify the associated context variable. You can analyze two or more files
at once by creating a different work area for each file, giving each area
a different context variable, and analyzing the records of each file in the
appropriate work area.

DCX$_1NVITEM

Error; invalid item code. The number of arguments
specified in the call was incorrect (this number should
be odd}, or an unknown item code was specified.

DCX$_NORMAL

Successful completion.

This routine also returns any condition values returned by LIB$GET_VM.

DCX-16

Data Compression/Expansion (DCX) Routines

DCX$COMPRESS_DATA

DCX$COMPRESS_DATA Compress a Data Record
The DCX$COMPRESS_DATA routine compresses a data record. You call this
routine for each data record to be compressed.

FORMAT

DCX$COMPRESS_DATA

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

context ,in_rec ,ouLrec
[, ouL length]

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage: context
type:
longword (unsigned)
access:
read only
mechanism: by reference
Value identifying the data stream that DCX$COMPRESS_DATA
compresses. The context argument is the address of a longword
containing this value. DCX$COMPRESS_INIT initializes the value;
you should not modify it. You can define multiple context arguments to
identify multiple data streams that are processed simultaneously.

in_rec
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Data record to be compressed. The in_rec argument is the address of the
descriptor of the data record string.

out_rec
VMS usage: char_string
type:
character string
access:
write only
mechanism: by descriptor
Data record that has been compressed. The out_rec argument is the
address of the descriptor of the compressed record that LIB$COMPRESS_
DATA returns.

DCX-17

Data Compression/Expansion (DCX) Routines

DCX$COMPRESS_DATA
out_ length
VMS usage: word_signed
word integer (signed)
access:
write only
mechanism: by reference
Length (in bytes) of the compressed data record. The out_length
argument is the address of a word into which LIB$COMPRESS_DATA
returns the length of the compressed data record.

type:

DESCRIPTION

CONDITION
VALUES
RETURNED

The DCX$COMPRESS_DATA routine compresses a data record. You call
this routine for each data record to be compressed. As you compress
each record, write the compressed record to the file containing the
compression/expansion map. For each record, write the length of the
record and substring string containing the record to the same file. See the
COMPRESS DATA section in Example 5-1.

DCX$_1NVCTX

DCX$_1NVDATA

Error. You specified the item value DCX$C_
BOUNDED in the DCX$ANALYZE_INIT routine
and attempted to compress a data record (using
DCX$COMPRESS_DATA) that was not presented for
analysis (using DCX$ANALYZE_DATA). Specifying
the DCX$C_BOUNDED item value means that
you must analyze all data records that are to be
compressed.

DCX$_1NVMAP

Error; invalid map. The map argument was not
specified correctly or the context area is invalid.

DCX$_NORMAL

Successful completion.

DCX$_TRUNC

Error. The compressed data record has been
truncated because the out_rec descriptor did not
specify enough memory to accommodate the record.

This routine also returns any condition values returned by
LIB$ANALYZE_SDESC_R2 and LIB$SCOPY_R_DX.

DCX-18

Data Compression/Expansion (DCX) Routines

DCX$COMPRESS_DONE

DCX$COMPRESS_DONE Specify Compression
Complete
The DCX$COMPRESS_DONE routine deletes the context area and sets the
context variable to zero.

FORMAT

DCX$COMPRESS_DONE

RETURNS

VMS usage:
type:
access:
mechanism:

context

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

context
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
write only
by reference

Value identifying the data stream that DCX$COMPRESS_DONE deletes.
The context argument is the address of a longword containing this value.
DCX$COMPRESS_INIT writes the value into context; you should not
modify its value. You can define multiple context arguments to identify
multiple data streams that are processed simultaneously.

DESCRIPTION

CONDITION
VALUES
RETURNED

The DCX$COMPRESS_DONE routine deletes the context area and
sets the context variable to zero, thus undoing the work of the
DCX$COMPRESS_INIT routine. You call DCX$COMPRESS_DONE
when all data records have been compressed (using DCX$COMPRESS_
DATA). After calling DCX$COMPRESS_DONE, call LIB$FREE_VM to
free the virtual memory that DCX$MAKE_MAP used for the compression
/expansion function.

DCX$_1NVCTX

Error. The context variable is invalid or the context
area is invalid or corrupted. This may be caused by
a failure to call the appropriate routine to initialize the
context variable or by an application program error.

DCX$_NORMAL

Successful completion.

This routine also returns any condition values returned by
LIB$FREE_VM.
DCX-19

Data Compression/Expansion (DCX) Routines
DCX$COMPRESS_INIT

DCX$COMPRESS_INIT Initialize Compression
Context
The DCX$COMPRESS_INIT routine initializes the context area for the
compression of data records.

FORMAT

DCX$COMPRESS_INIT

RETURNS

VMS usage:
type:
access:
mechanism:

context ,map

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
write only
by reference

Value identifying the data stream that DCX$COMPRESS_INIT initializes.
The context argument is the address of a longword containing this value.
You should not modify the context value after DCX$COMPRESS_INIT
initializes it. You can define multiple context arguments to identify
multiple data streams that are processed simultaneously.

map
VMS usage:
type:
access:
mechanism:

address
longword (unsigned)
read only
by reference

The function created by DCX$MAKE_MAP. The map argument is the
address of the compression/expansion function's virtual address.
The map argument must remain at this address until data compression
is completed and the context is deleted by means of a call to
DCX$COMPRESS_DONE.

DESCRIPTION

The DCX$COMPRESS_INIT routine initializes the context area for the
compression of data records.
You call the DCX$COMPRESS_INIT routine after the call to
DCX$ANALYZE_DONE.

DCX-20

Data Compression/Expansion (DCX) Routines
DCX$COMPRESS_INIT

CONDITION
VALUES
RETURNED

DCX$_1NVMAP

Error; invalid map. The map argument was not
specified correctly, or the context area is invalid.

DCX$_NORMAL

Successful completion.

This routine also returns any condition values returned by LIB$GET_VM
and LIB$FREE_VM.

DCX-21

Data Compression/Expansion {DCX) Routines
DCX$EXPAND_DATA

DCX$EXPAND_DATA

Expand a Compressed Data
Record

The DCX$EXPAND_DATA routine expands (or restores) a compressed data
record to its original state.

FORMAT

DCX$EXPAND_DATA

RETURNS

VMS usage:
type:
access:
mechanism:

context ,in_rec ,ouLrec
[,ouLlength]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
read only
by reference

Value identifying the data stream that DCX$EXPAND_DATA expands.
The context argument is the address of a longword containing this value.
DCX$EXPAND_INIT initializes this value; you should not modify it. You
can define multiple context arguments to identify multiple data streams
that are processed simultaneously.

in_rec
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Data record to be expanded. The in_rec argument is the address of the
descriptor of the data record string.

out_rec
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

Data record that has been expanded. The out_rec argument is
the address of the descriptor of the expanded record returned by
DCX$EXPAND_DATA.

DCX-22

Data Compression/Expansion (DCX) Routines
DCX$EXPAND_DATA

out_ length
word_signed
word integer (signed)
write only
by reference
Length (in bytes) of the expanded data record. The out_length argument
is the address of a word into which DCX$EXPAND_DATA returns the
length of the expanded data record.
VMS usage:
type:
access:
mechanism:

DESCRIPTION

CONDITION
VALUES
RETURNED

The DCX$EXPAND_DATA routine expands (or restores) a compressed
data record to its original state. You call this routine for each data record
to be expanded.

DCX$_1NVCTX

DCX$_1NVDATA

Error. A compressed data record is invalid (probably
truncated) and therefore cannot be expanded.

DCX$_1NVMAP

Error; invalid map. The map argument was not
specified correctly, or the context area is invalid.

DCX$_NORMAL

Successful completion.

DCX$_TRUNC

Warning. The expanded data record has been
truncated because the out_rec descriptor did not
specify enough memory to accommodate the record.

This routine also returns any condition values returned by
LIB$ANALYZE_SDESC_R2 and LIB$SCOPY_R_DX.

DCX-23

Data Compression/Expansion {DCX) Routines
DCX$EXPAND_DONE

DCX$EXPAND_DONE

Specify Expansion Complete

The DCX$EXPAND_DONE routine deletes the context area and sets the
context variable to zero.

FORMAT

DCX$EXPAND_DONE

RETURNS

VMS usage:
type:
access:
mechanism:

context

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

context
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
write only
by reference

Value identifying the data stream that DCX$EXPAND_DONE deletes.
The context argument is the address of a longword containing this value.
DCX$EXPAND_INIT initializes this value; you should not modify it. You
can define multiple context arguments to identify multiple data streams
that are processed simultaneously.

DESCRIPTION

CONDITION
VALUES
RETURNED

The DCX$EXPAND_DONE routine deletes the context area and sets the
context variable to zero, thus undoing the work of the DCX$EXPAND_
INIT routine. You call DCX$EXPAND_DONE when all data records have
been expanded (using DCX$EXPAND_DATA).

DCX$_1NVCTX

DCX$NORMAL

Successful completion.

This routine also returns any condition values returned by
LIB$FREE_VM.

DCX-24

Data Compression/Expansion (DCX) Routines
DCX$EXPAND_INIT

DCX$EXPAND_INIT

Initialize Expansion Context

The DCX$EXPAND_INIT routine initializes the context area for the expansion
of data records.

FORMAT

DCX$EXPAND_INIT

RETURNS

VMS usage:
type:
access:
mechanism:

context ,map

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
write only
by reference

Value identifying the data stream that DCX$EXPAND_INIT initializes.
The context argument is the address of a longword containing this value.
After DCX$EXPAND_INIT initializes this context value, you should not
modify it. You can define multiple context arguments to identify multiple
data streams that are processed simultaneously.

map
VMS usage:
type:
access:
mechanism:

address
longword (unsigned)
read only
by reference

Compression/expansion function (created by DCX$MAKE_MAP). The map
argument is the address of the compression/expansion function's virtual
address.
The map argument must remain at this address until data expansion is
completed and context is deleted by means of a call to DCX$EXPAND_
DONE.

DESCRIPTION

The DCX$EXPAND_INIT routine initializes the context area for the
expansion of data records.
You call the DCX$EXPAND_INIT routine as the first step in the expansion
(or restoration) of compressed data records to their original state.

DCX-25

Data Compression/Expansion {DCX) Routines
DCX$EXPAND_INIT

Before you call DCX$EXPAND_INIT, read the length of the compressed file
from the compression/expansion function (the map). Invoke LIB$GET_VM
to get the necessary amount of storage for the function. LIB$GET_VM
returns the address of the first byte of the storage area.

CONDITION
VALUES
RETURNED

DCX$_1NVMAP

Error; invalid map. The map argument was not
specified correctly, or the context area is invalid.

DCX$_NORMAL

Successful completion.

This routine also returns any condition values returned by LIB$GET_VM.

DCX-26

Data Compression/Expansion (DCX) Routines
DCX$MAKE_MAP

DCX$MAKE_MAP Compute the
Compression/Expansion
Function
The DCX$MAKE_MAP routine uses the statistical information gathered by
DCX$ANALYZE_DATA to compute the compression/expansion function.

FORMAT

DCX$MAKE_MAP

RETURNS

VMS usage:
type:
access:
mechanism:

context ,map_addr [,map_size]

cond_value
longword {unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage: context
type:
longword {unsigned)
access:
write only
mechanism: by reference
Value identifying the data stream that DCX$MAKE_MAP maps. The
context argument is the address of a longword containing this value.
DCX$ANALYZE_INIT initializes this value; you should not modify it. You
can define multiple context arguments to identify multiple data streams
that are processed simultaneously.

map_addr
VMS usage: address
type:
longword {unsigned)
access:
write only
mechanism: by reference
Starting address of the compression/expansion function. The map_addr
argument is the address of a longword into which DCX$MAKE_MAP
stores the virtual address of the compression/expansion function.

map_size
VMS usage: longword_signed
type:
longword {unsigned)
access:
write only
mechanism: by reference
Length of the compression/expansion function. The map_size argument
is the address of the longword into which DCX$MAKE_MAP writes
the length of the compression/expansion function. This is an optional
argument.
DCX-27

Data Compression/Expansion {DCX) Routines
DCX$MAKE_MAP

DESCRIPTION

The DCX$MAKE_MAP routine uses the statistical information gathered
by DCX$ANALYZE_DATA to compute the compression/expansion function.
In essence, this map is the algorithm used to shorten (or compress) the
original data records as well as to expand the compressed records to their
original form.
The map must be available in memory when any data compression or
expansion takes place; the address of the map is passed as an argument
to the DCX$COMPRESS_INIT and DCX$EXPAND_INIT routines, which
initialize the data compression and expansion procedures, respectively.
The map is stored with the compressed data records, because the
compressed data records are indecipherable without the map. When
compressed data records have been expanded to their original state and
no further compression is desired, you should delete the map using the
LIB$FREE_VM routine.
DCX requires that you submit data records for analysis and then call the
DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status code,
you must again submit data records for analysis (in the same order) and
call DCX$MAKE_MAP again; on the second iteration, DCX$MAKE_MAP
returns the DCX$_NORMAL status code.

CONDITION
VALUES
RETURNED

DCX$_AGAIN

Informational. The map has not been created and the

map_addr and map_size arguments have not been
written because further analysis is required. The data
records must be analyzed (using DCX$ANALYZE_
DATA) again, and DCX$MAKE_MAP must be called
again before DCX$MAKE_MAP will create the map
and return the DCX$_NORMAL status code.
DCX$_1NVCTX

DCX$_NORMAL

Successful completion.

This routine also returns any condition values returned by LIB$GET_VM
and LIB$FREE_VM.

DCX-28

EDT Routines

On VMS operating systems, the EDT editor can be called from a program.
Calling programs can be written in any VAX language that generates calls
using the VAX Procedure Calling and Condition Handling Standard.
You can set up your call to EDT so that the program handles all the
editing work, or you can make EDT run interactively so that you can edit
a file while the program is running.
This chapter on callable EDT assumes that you know how to call an
external facility from the language you are using. Callable EDT is a
shareable image, which means that you save physical memory and disk
space by having all processes access a single copy.

6.1

Introduction to EDT Routines
You must include a statement in your program accessing the EDT entry
point. This reference statement is similar to a library procedure reference
statement. The EDT entry point is referenced as EDT$EDIT. You can pass
arguments to EDT$EDIT; for example, you can pass EDT$FILEIO or your
own routine. When you refer to the routines you pass, call them FILEIO,
WORKIO, and XLATE. Therefore, FILEIO can be either a routine provided
by EDT (named EDT$FILEIO) or a routine that you write.

6.2

Using EDT Routines: An Example
Example 6-1 shows a VAX BASIC program that calls EDT. All three
routines (FILEIO, WORKIO, and XLATE) are called. Note the reference to
the entry point EDT$EDIT in line number 500.

EDT-1

EDT Routines
6.2 Using EDT Routines: An Example

Example 6-1

Using the EDT Routines in a VAX BASIC Program

100
200
250
300
400

EXTERNAL INTEGER EDT$FILEIO
EXTERNAL INTEGER EDT$WORKIO
EXTERNAL INTEGER AXLATE
EXTERNAL INTEGER FUNCTION EDT$EDIT
DECLARE INTEGER RESULT

450
460
465
470
480
485

DIM INTEGER PASSFILE (1%) 8
DIM INTEGER PASSWORK(1%)
DIM INTEGER PASSXLATE(1%)
PASSFILE(0%) = LOC(EDT$FILEIO)
PASSWORK(0%) = LOC(EDT$WORKIO)
PASSXLATE(0%) = LOC(AXLATE)

500

RESULT= EDT$EDIT('FILE.BAS' , ' ' ,'EDTINI' , ' ' ,0%,
PASSFILE(0%)BY REF, PASSWORK(0%) BY REF, 8
PASSXLATE(0%) BY REF) @)
600 IF (RESULT AND 1%) = 0%
THEN
PRINT "SOMETHING WRONG"
CALL LIB$STOP(RESULT BY VALUE)
900 PRINT "EVERYTHING O.K."
1000 END

0 The external entry points EDT$FILEIO, EDT$WORKIO, and AXLATE
are defined so that they can be passed to callable EDT.

8 Arrays are used to construct the two-longword structure needed for
data type BPV.

8 Here is the call to EDT. The input file is FILE.BAS, the output and
journal files are defaulted, and the command file is EDTINI. A 0 is
passed for the options word to get the default EDT options.

8 The array PASSFILE points to the entry point for all file 1/0, which is
set up in this example to be the EDT-supplied routine with the entry
point EDT$FILEIO. Similarly, the array PASSWORK points to the
entry point for all work 110, which is the EDT-supplied routine with
the entry point EDT$WORKIO.

0 PASSXLATE points to the entry point that EDT will use for all XLATE
processing. PASSXLATE points to a user-supplied routine with the
entry point AXLATE.

6.3

EDT Routines
The following pages describe the individual EDT routines.

EDT-2

EDT Routines
EDT$EDIT

EDT$EDIT Edit a File
The EDT$EDIT routine invokes the EDT editor.

FORMAT

EDT$EDIT

RETURNS

VMS usage:
type:
access:
mechanism:

in_file [,ouLfile] [,com_file] [,jou_file]
[,options] [,fileio] [, workio] [,xlate]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

in_file
VMS usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
by descriptor

File specification of the input file that EDT$EDIT is to edit. The in_:file
argument is the address of a descriptor pointing to this file specification.
The string that you enter in this calling sequence is passed to the FILEIO
routine to open the primary input file. This is the only required argument.

out file
VMS usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
by descriptor

File specification of the output file that EDT$EDIT creates. The out_file
argument is the address of a descriptor pointing to this file specification.
The default is that the input file specification is passed to the FILEIO
routine to open the output file for the EXIT command.

com_file
VMS usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
by descriptor

File specification of the startup command file to be executed when EDT is
invoked. The com_file argument is the address of a descriptor pointing
to this file specification. The com_file string is passed to the FILEIO
routine to open the command file. The default is the same as that for EDT
command file defaults.

EDT-3

EDT Routines
EDT$EDIT

jou_file
VMS usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor
File specification of the journal file to be opened when EDT is invoked.
The jou_file argument is the address of a descriptor pointing to this file
specification. The jou_file string is passed to the FILEIO routine to open
the journal file. The default is to use the same file name as in_file.

options
VMS usage: mask_longword
type:
aligned bit string
access:
read only
mechanism: by reference
Bit vector specifying options for the edit operation. The options argument
is the address of an aligned bit string containing this bit vector. Only bits
<5:0> are currently defined; all others must be 0. The default options have
all bits set to 0. This is the same as the default setting when you invoke
EDT to edit a file from DCL.

Symbols and their descriptions follow:

EDT-4

EDT$M_RECOVER

If set, bit <0> causes EDT to read the journal file and
execute the commands in it, except for the EXIT or QUIT
commands, which are ignored. After the journal file
commands are processed, editing continues normally. If
bit <0> is set, the FILEIO routine is asked to open the
journal file for both input and output; otherwise FILEIO
is asked only to open the journal file for output. Bit <0>
corresponds to the /RECOVER qualifier on the EDT
command line.

EDT$M_COMMAND

If set, bit <1 > causes EDT to signal if the startup command
file cannot be opened. When bit <1> is 0, EDT intercepts
the signal from the FILEIO routine indicating that the
startup command file could not be opened. Then, EDT
proceeds with the editing session without reading any
startup command file. If no command file name is supplied
with the call to the EDT$EDIT routine, EDT tries to open
SYS$LIBRARY:EDTSYS.EDT or, if that fails, EDTINl.EDT.
Bit <1 > corresponds to the /COMMAND qualifier on the
EDT command line. If EDT$M_NOCOMMAND (bit <4>) is
set, bit <1 > is overridden because bit <4> prevents EDT
from trying to open a command file.

EDT$M_NOJOURNAL

If set, bit <2> prevents EDT from opening the journal file.
Bit <2> corresponds to the /NOJOURNAL or /READ_
ONLY qualifier on the EDT command line.

EDT Routines
EDT$EDIT

EDT$M_NOOUTPUT

If set, bit <3> prevents EDT from using the input file name
as the default output file name. Bit <3> corresponds to
the /NOOUTPUT or /READ_ONLY qualifier on the EDT
command line.

EDT$M_NOCOMMAND

If set, bit <4> prevents EDT from opening a startup
command file. Bit <4> corresponds to the /NOCOMMAND
qualifier on the EDT command line.

EDT$M_NOCREATE

If set, bit <5> causes EDT to return to the caller if the
input file is not found. The status returned is the error
code EDT$_1NPFILNEX.

fileio
VMS usage: vector_longword_unsigned
type:
bound procedure value
access:
function call
mechanism: by reference
User-supplied routine called by EDT to perform file 1/0 functions. The
fileio argument is the address of a bound procedure value containing
the user-supplied routine. When you do not need to intercept any file
1/0, either use the entry point EDT$FILEIO for this argument or omit
it. When you only need to intercept some amount of file 110, call the
EDT$FILEIO routine for the other cases.

To avoid confusion, note that EDT$FILEIO is a routine provided by EDT
whereas FILEIO is a routine that you provide.
In order to accommodate routines written in high-level languages that do
up-level addressing, this argument must have a data type of BPV (bound
procedure value). BPV is a two-longword ·entity in which the first longword
contains the address of a procedure entry mask and the second longword
is the environment value. When the bound procedure is called, EDT loads
the second longword into Rl. If you use EDT$FILEIO for this argument,
set the second longword to <0>. You can pass a <0> for the argument,
and EDT will set up EDT$FILEIO as the default and set the environment
word
to 0.

workio
VMS usage: vector_longword_unsigned
type:
bound procedure value
access:
function call
mechanism: by reference
User-supplied routine called by EDT to perform 1/0 between the work file
and EDT. The workio argument is the address of a bound procedure value
containing the user-supplied routine. Work file records are addressed only
by number and are always 512 bytes long. If you do not need to intercept
work file I/O, you can either use the entry point EDT$WORKIO for this
argument or omit it.

In order to accommodate routines written in high-level languages that do
up-level addressing, this argument must have a data type of BPV (bound
procedure value). This means that EDT loads Rl with the second longword
addressed before calling it. If EDT$WORKIO is used for this argument,
set the second longword to 0. You can pass a 0 for this argument, and EDT
will set up EDT$WORKIO as the default and set the environment word
to 0.
EDT-5

EDT Routines
EDT$EDIT

xiate
vector_longword_unsigned
bound procedure value
function call
by reference
User-supplied routine that EDT calls when it encounters the nokeypad
command XLATE. The x:late argument is the address of a bound procedure
value containing the user-supplied routine. The XLATE routine allows you
to gain control of your EDT session. If you do not need control of EDT
during the editing session, you can either use the entry point EDT$XLATE
for this argument or omit it.
VMS usage:
type:
access:
mechanism:

In order to acc~mmodate routines written in high-level languages that do
up-level addressing, this argument must have a data type of BPV (bound
procedure value). This means that EDT loads Rl with the second longword
addressed before calling it. If EDT$XLATE is used for this argument, set
the second longword to 0. You can pass a 0 for this argument, and EDT
will set up EpT$XLAT~ a~ the default and set the environment word to 0.

DESCRIPTION

If.the EDT sessfon is terminated by EXIT or QUIT, the status will be a
succe~sful value (bit <0> = 1). If the session is terminated because the file
was not found and if the /NOCREATE qualifier was in effect, the failure
code EDT$_INPFILNEX is returned. In an unsuccessful termination
caused by an EDT error, a failure code corresponding to that error is
returned. Each error status from the FILEIO and WORKIO routines is
explained separately.
Three of the arguments to the EDT$EDIT routine, fileio, workio, and
x:late are the entry point names of user-supplied routines.

CONDITION
VALUES
RETURNED

EDT-6

SS$_NORMAL

Successful completion.

EDT$_1NPFILNEX

/NOCREATE specified and input file does not exist.

This routine also returns any condition values returned by user-supplied
routines.

EDT Routines
FILEIO

FILEIO
The user-supplied FILEIO routine performs file 1/0 functions. You call it by
specifying it as an argument in the EDT$EDIT routine. It cannot be called
independently.

FORMAT

FILEIO

code ,stream ,record ,rhb

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

A VMS status code that your FILEIO routine returns to EDT$EDIT. The
fileio argument is a longword containing the status code. The only failure
code that is normally returned is RMS$_EOF from a GET call. All other
VMS RMS errors are signaled, not returned. The VMS RMS signal should
include the file name and both longwords of the RMS status. Any errors
detected with the FILEIO routine can be indicated by setting status to an
error code. That special error code will be returned to the program by the
EDT$EDIT routine. There is a special status value EDT$_NONSTDFIL
for nonstandard file opening.
Condition values are returned in RO.

ARGUMENTS

code
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

A code from EDT that specifies what function the FILEIO routine is
to perform. The code argument is the address of a longword integer
containing this code. Following are the valid function codes:
Function Code

Description

EDT$K_OPEN_INPUT

The record argument names a file to be
opened for input. The rhb argument is the
default file name.

EDT$K_OPEN_OUTPUT_SEQ

The record argument names a file to be
opened for output as a sequenced file. The
rhb argument is the default file name.

EDT$K_OPEN_OUTPUT_NOSEQ

The record argument names a file to be
opened for output. The rhb argument is the
default file name.

EDT-7

EDT Routines
FILEIO

Function Code

Description

EDT$K_OPEN_IN_OUT

The record argument names a file to be
opened for both input and output. The rhb
argument is the default file name.

EDT$K_GET

The record argument is to be filled with data
from the next record of the file. If the file has
record prefixes, rhb is filled with the record
prefix. If the file has no record prefixes, rhb
is not written. When you attempt to read past
the end of file, status is set to RMS$_EOF.

EDT$K_PUT

The data in the record argument is to be
written to the file as its next record. If the file
has record prefixes, the record prefix is taken
from the rhb argument. For a file opened for
both input and output, EDT$K_PUT is valid
only at the end of the file, indicating that the
record is to be appended to the file.

EDT$K_CLOSE_DEL

The file is to be closed and then deleted. The
record and rhb arguments are not used in the
call.

EDT$K_CLOSE

The file is to be closed. The record and rhb
arguments are not used in the call.

stream
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
A code from EDT that indicates which file is being used. The stream
argument is the address of a longword integer containing the code.
Following are the valid codes.

EDT-8

Function Code

Description

EDT$K_COMMAND_FILE

The command file.

EDT$K_INPUT_FILE

The primary input file.

EDT$K_INCLUDE_FILE

The secondary input file. Such a file is opened in
response to an INCLUDE command. It is closed
when the INCLUDE command is complete and will be
reused for subsequent INCLUDE commands.

EDT Routines
FILEIO

Function Code

Description

EDT$K_JOURNAL_FILE

The journal file. If bit O of the options is set, it
is opened for both input and output and is read
completely. Otherwise, it is opened for output only.
After it is read or opened for output only, it is used
for writing. On a successful termination of the editing
session, the journal file is closed and deleted. EXIT
/SAVE and QUIT/SAVE close the journal file without
deleting it.

EDT$K_OUTPUT_FILE

The primary output file. It is not opened until you
enter the EXIT command.

EDT$K_WRITE_FILE

The secondary output file. Such a file is opened
in response to a WRITE or PRINT command. It is
closed when the command is complete and will be
reused for subsequent WRITE or PRINT commands.

record
char_string
character-coded text string
modify
by descriptor
Text record passed by descriptor from EDT to the user-supplied FILEIO
routine; the code argument determines how the record argument is
used. The record argument is the address of a descriptor pointing to
this argument. When the code argument starts with EDT$K_OPEN, the
record is a file name. When the code argument is EDT$K_GET, the
record is a place to store the record that was read from the file. For code
argument EDT$K_PUT, the record is a place to find the record to be
written to the file. This argument is not used if the code argument starts
with EDT$K_CLOSE.
VMS usage:
type:
access:
mechanism:

Note that for EDT$K_GET, EDT uses a dynamic or varying string
descriptor; otherwise, EDT has no way of knowing the length of the
record being read. EDT uses only string descriptors that can be handled
by the Run-Time Library (RTL) routine STR$COPY_DX.

rhb
char_string
character-coded text string
modify
by descriptor
Text record passed by descriptor from EDT to the user-supplied FILEIO
routine; the code argument determines how the rhb argument is used.
When the code argument starts with EDT$K_OPEN, the rhb argument
is the default file name. When the code is EDT$K_GET and the file has
record prefixes, the prefixes are put in this argument. When the code
is EDT$K_PUT and the file has record prefixes, the prefixes are taken
from this argument. Like the record argument, EDT uses a dynamic or
varying string descriptor for EDT$K_GET and uses only string descriptors
that can be handled by the RTL routine STR$COPY_DX.
VMS usage:
type:
access:
mechanism:

EDT-9

EDT Routines
FILEIO

DESCRIPTION

If you do not need to intercept any file I/O, you can use the entry point
EDT$FILEIO for this argument or you can omit it. If you need to intercept

only some file I/O, call the EDT$FILEIO routine for the other cases.
When you use EDT$FILEIO as a value for. the fileio argument, files are
opened as follows:

CONDITION
VALUES
RETURNED

EDT-10

•

The record argument is always the RMS file name.

•

The rhb argument is always the RMS default file name.

•

There is no related name for the input file.

•

The related name for the output file is the input file with OFP (output
file parse). EDT passes the input file name, the output file name, or
the name from the EXIT command in the record argument.

•

The related name for the journal file is the input file name with the
output file parse (OFP) RMS bit set.

•

The related name for the INCLUDE file is the input file name with the
OFP set. This is unusual because the file is being opened for input.

SS$_NORMAL

Successful completion.

EDT$_NONSTDFIL

File is not in standard text format.

RMS$_EOF

End of file on a GET.

EDT Routines
WORKIO

WORKIO
The user-supplied WORKIO routine is called by EDT when it needs temporary
storage for the file being edited. You· call it by specifying it as an argument in
the EDT$EDIT routine. It cannot be called independently.

FORMAT

WORKIO

RETURNS

VMS usage:
type:
access:
mechanism:

code ,recordno ,record
cond_value
longword (unsigned)
write only
by immediate value

Longword value returned as a VMS status code. It is generally a success
code, because all VMS RMS errors should be signaled. The signal should
include the file name and both longwords of the VMS RMS status. Any
errors detected within work l/O can be indicated by setting status to an
error code, which will be returned by the EDT$EDIT routine.
The condition value is returned in RO.

ARGUMENTS

code
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

A code from EDT that specifies the operation to be performed. The code
argument is the address of a longword integer containing this argument.
The valid function codes are as follows:
Function Code

Description

EDT$K_OPEN_IN_OUT

Open the work file for both input and output. Neither the
record nor recordno argument is used.

EDT$K_GET

Read a record. The recordno argument is the number
of the record to be read. The record argument gives the
location where the record is to be stored.

EDT$K_PUT

Write a record. The recordno argument is the number of
the record to be written. The record argument tells the
location of the record to be written.

EDT$K_CLOSE_DEL

Close the work file. After a successful close, the file is
deleted. Neither the record nor recordno argument is
used.

EDT-11

EDT Routines
WORKIO

recordno
VMS usage: longword_signed
longword integer (signed)
access:
read only
mechanism: by reference
Number of the record to be read or written. The recordno argument is
the address of a longword integer containing this argument. EDT always
writes a record before reading that record. This argument is not used for
open or close calls.
type:

record
VMS usage: char_string
character string
access:
modify
mechanism: by descriptor
Location of the record to be read or written. This argument always refers
to a 512-byte string during GET and PUT calls. This argument is not used
for open or close calls.
type:

DESCRIPTION

CONDITION
VALUE
RETURNED

EDT-12

Work file records are addressed only by number and are always 512 bytes
long. If you do not need to intercept work file I/O, you can use the entry
point EDT$WORKIO for this argument or you can omit it.

SS$_NORMAL

Successful completion.

EDT Routines

XLATE

XLATE
The user-supplied XLATE routine is called by EDT when it encounters the
nokeypad command XLATE. You cause it to be called by specifying it as an
argument in the EDT$EDIT routine. It cannot be called independently.

FORMAT

XLATE

string

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword value returned as a VMS status code. It is generally a success
code. If the XLATE routine cannot process the passed string for some
reason, it sets status to an error code. Returning an error code from
the XLATE routine aborts the current key execution and displays the
appropriate error message.
The condition value is returned in RO.

ARGUMENT

string
VMS usage:
type:
access:
mechanism:

char_string
character-coded text string
modify
by descriptor

Text string passed to the nokeypad command XLATE. You can use the
nokeypad command XLATE by defining a key to include the following
command in its definition:
XLATEtext"Z

The text is passed by the string argument. The string argument is one
that can be handled by the Run-Time Library (RTL) routine STR$COPY_
DX.
This argument is also a text string returned to EDT. The string is made
up of nokeypad commands that EDT is to execute.

DESCRIPTION

The nokeypad command XLATE allows you to gain control of the EDT
session. (See the VAX EDT Reference Manual for more information about
the XLATE command.) If you do not need to gain control of EDT during
the editing session, you can use the entry point EDT$XLATE for this
argument or you can omit it.

EDT-13

EDT Routines

XLATE

CONDITION

VALUE
RETURNED

EDT-14

SS$_NORMAL

Successful completion.

File Definition Language (FOL) Routines

This chapter describes the File Definition Language (FDL) routines.
These routines perform many of the functions of the RMS File Definition
Language.

7.1

Introduction to FOL Routines
The FDL$CREATE routine is the one most likely to be called from a highlevel language. It creates a file from an FDL specification and then closes
the file.
The following three FDL routines provide a way to specify all the options
RMS allows when it executes create, open, or connect operations. They
also allow you to specify special processing options required for your
applications.
The FDL$GENERATE routine produces an FDL specification by
interpreting a set of RMS control blocks. It then writes the FDL
specification either to an FDL file or to a character string.
The FDL$PARSE routine parses an FDL specification, allocates RMS
control blocks, and fills in the relevant fields.
The FDL$RELEASE routine deallocates the virtual memory used by the
RMS control blocks created by FDL$PARSE.
These routines cannot be called from AST level.
An FDL specification can be either in a file or in a character string.
When specifying an FDL specification in a character string, delimit the
statements of the FDL specification with semicolons.

7.2

Using the FOL Routines: Examples
Example 7-1 shows how to use the FDL$CREATE routine in a FORTRAN
program.

FDL-1

File Definition Language (FOL) Routines
7.2 Using the FOL Routines: Examples

Example 7-1

*
*

*
*
*

Using FDL$CREATE in a FORTRAN Program

This program calls the FDL$CREATE routine.
It
creates an indexed output file named NEW MASTER.DAT
from the specifications in the FDL file named
INDEXED.FOL. You can also supply a default filename
and a result name (that receives the name of the
created file) . The program also returns all the
statistics.
IMPLICIT
EXTERNAL
CHARACTER
1
1
1

INTEGER*4

INTEGER*4
LIB$GET_LUN,
IN FILE*ll
OUT FILE*14
DEF FILE*ll
RES FILE*50
FIDBLK (3)

(A -

FDL$CREATE
/'INDEXED.FOL'/,
/'NEW MASTER.DAT'/,
/'DEFAULT.FOL'/,
/0,0,0/

STATUS = FDL$CREATE (IN_FILE,OUT_FILE,
DEF FILE,RES FILE,FIDBLK,,)
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))
STATUS=LIB$GET_LUN(LOG_UNIT)
OPEN (UNIT=LOG_UNIT,FILE=RES_FILE,STATUS='OLD')
CLOSE (UNIT=LOG_UNIT, STATUS='KEEP')
WRITE (6, 1000)
WRITE (6, 2000)

(RES_FILE)
(FIDBLK (I) I

I=l, 3)

1000

FORMAT

(lX,'The result filename is: ',A50)

2000

FORMAT
1
1

(/lX,'FID-NUM: I ,IS/,
lX,'FID-SEQ: ',I5/,
lX,'FID-RVN: ',I5)

END

Example 7-2 shows how to use the FDL$PARSE and FDL$RELEASE
routines in a MACRO program.
Example 7-2

Using FDL$PARSE and FDL$RELEASE in a MACRO Program

This program calls the FDL utility routines FDL$PARSE and
FDL$RELEASE. First, FDL$PARSE parses the FDL specification
PART.FOL. Then the data file named in PART.FOL is accessed
using the primary key.
Last, the control blocks allocated
by FDL$PARSE are released by FDL$RELEASE.
(continued on next page)

FDL-2

File Definition Language (FOL) Routines
7.2 Using the FOL Routines: Examples

Example 7-2 (Cont.)

MY FAB:
MY RAB:
FDL FILE:
REC SIZE=80
LF=lO
REC RESULT:
REC BUFFER:
HEADING:

Using FDL$PARSE and FDL$RELEASE in a MACRO Program

.TITLE

FDLEXAM

.PSECT

DATA,WRT,NOEXE

.LONG
.LONG
.ASCID

0
0
/PART.FOL/

.LONG
REC SIZE
.ADDRESS REC BUFFER
.BLKB
REC SIZE
.ASCID /ID
PART
SUPPLIER
.PSECT

Declare FDL file

COLOR I jg:]

CODE

Declare the external routines
.EXTRN

FDL$PARSE, FDL$RELEASE

.ENTRY

FDLEXAM,"M<>
PUSHAL MY RAB
PUSHAL MY FAB
PUSHAL FDL FILE
CALLS
#3,G"FDL$PARSE
BLBS
RO,KEYO
BRW
ERROR

KEYO:

MOVL
MY FAB,RlO
; Move address of FAB to RlO
MY-RAB,R9
MOVL
; Move address of RAB to R9
MOVL
#REC SIZE,RAB$W USZ(R9)
MOVAB
REC BUFFER,RAB$L UBF(R9)
FAB~(RlO)
$OPEN
Open the file
BLBC
RO,ERROR
$CONNECT RAB=(R9)
Connect to the RAB
BLBC
RO,ERROR
PUS HAQ HEADING
Display the heading
CALLS
#1,G"LIB$PUT_OUTPUT
BLBC
RO, ERROR

GET REC:

$GET
CMPL
BEQLU
BLBC
MOVZWL
PUS HAL
CALLS
BLBC
BRB
$CLOSE
BLBC
PUS HAL
PUSHAL
CALLS
BLBC
BRB

CLEAN:

Set up entry mask
Get set up for call with
addresses to receive the
FAB and RAB allocated by
FDL$PARSE

RAB=(R9)
Get a record
#RMS$_EOF,RO
If not end of file,
CLEAN
continue
RO,ERROR
RAB$W_RSZ(R9),REC_RESULT
Move a record into
REC RESULT
the buff er
#1,G"LIB$PUT_OUTPUT
Display the record
RO,ERROR
GET REC
Get another record
FAB= (RlO)
Close the FAB
RO,ERROR
MY RAB
Push RAB addr on stack
MY FAB
Push FAB addr on stack
#2~G"FDL$RELEASE
Release control blocks
RO,ERROR
FINI
(continued on next page)

FDL-3

Fi.le Definition Language (FOL) Routines
I

7.2 Using the FDL Routines: Examples

Example 7-2 (Cont.)

Using FDL$PARSE and FDL$RELEASE in a MACRO Program

ERROR:

PUSHL
CALLS
$CLOSE

RO
U,G"LIB$SIGNAL
FAB= (RlO)

RAB_ERROR:

PUSHL
PUSHL
BRB

RAB$L STV (R9)
RAB$(~STS (R9)
RMS ERR

FAB ERROR:

PUSHL
PUSHL

FAB$L_STV (RlO)
FAB$L_STS (RlO)

RMS_ERR:

CALLS
BRB

#2,G"LIB$SIGNAL
FINI

FINI:

RET
.END FDLEXAM

Example 7-3 shows how to use the FDL$PARSE and FDL$GENERATE
routines in a VAX Pascal program.
Example 7-3

Using FDL$PARSE and FDL$GENERATE in a VAX Pascal
Program

[INHERIT ('SYS$LIBRARY:STARLET')]
PROGRAM FDLexample (input,output,order_master);
(*
(*
(*
(*
(*

This program fills in its own FAB, RAB, and
XABs by calling FDL$PARSE and then generates
an FDL specification describing them.
It requires an existing input FDL file
(TESTING.FOL) for FDL$PARSE to parse.
TYPE

*)
*)
*)
*)
*)

(*+

(* FDL CALL INTERFACE CONTROL FLAGS

(*-

$BIT1 = [BIT(l),UNSAFE] BOOLEAN;
FDL2$TYPE = RECORD CASE INTEGER OF
1: (FDL$_FDLDEF_BITS : [BYTE(l)] RECORD END;
);

2: (FDL$V SIGNAL : [POS(O)] $BIT1;
(* Signal errors; don't return
FDL$V FDL STRING: [POS(l)] $BIT1;
(* Main-FDL spec is a char string
FDL$V DEFAULT STRING : [POS(2)] $BIT1;
(* Default FDL spec is a char string
FDL$V_FULL_OUTPUT : [POS(3)] $BIT1;
(* Produce a complete FDL spec
FDL$V $CALLBACK : [POS(4)] $BIT1;
(* Used by EDIT/FDL on input (DEC only)

*)
*)
*)
*)
*)

END;
(continued on next page)

FDL-4

File Definition Language {FOL) Routines
7.2 Using the FOL Routines: Examples

Example 7-3 {Cont.)

mail order

Using FDL$PARSE and FDL$GENERATE in a VAX
Pascal Program

RECORD
order_num: [KEY(O)] INTEGER;
name : PACKED ARRAY[l .. 20] OF CHAR;
address : PACKED ARRAY[l .. 20] OF CHAR;
city: PACKED ARRAY[l .. 19] OF CHAR;
state : PACKED ARRAY[l .. 2] OF CHAR;
zip_code : [KEY(l)] PACKED ARRAY[l .. 5]
OF CHAR;
item num
[KEY(2)] INTEGER;
shipping : REAL;
END;

order file = [UNSAFE] FILE OF mail_order;
ptr to FAB = AFAB$TYPE;
ptr=to=RAB = ARAB$TYPE;
byte = 0 .. 255;
VAR
order master
flags
order rec
temp_FAB
temp_RAB
status

order file;
FDL2$TYPE;
mail_order;
ptr_to_FAB;
ptr to RAB;
integer;

FUNCTION FDL$PARSE
(%STDESCR FDL_FILE : PACKED ARRAY. [L .. U:INTEGER]
OF CHAR;
VAR FAB_PTR : PTR_TO_FAB;
VAR RAB_PTR : PTR_TO_RAB)
INTEGER; EXTERN;
FUNCTION FDL$GENERATE
(%REF FLAGS : FDL2$TYPE;
FAB_PTR : PTR_TO_FAB;
RAB PTR : PTR TO RAB;
%STDESCR FDL_FILE_DST: PACKED ARRAY [L .. U:INTEGER]
OF CHAR) : INTEGER;
EXTERN;
BEGIN
status := FDL$PARSE ('TESTING' ,TEMP_FAB,TEMP_RAB);
flags::byte := O;
status := FDL$GENERATE (flags,
temp_FAB,
temp RAB,
'SYS$OUTPUT:');
END.

7.3

FOL Routines
The following pages describe the individual FDL routines.

FDL-5

File Definition Language (FOL) Routines
FDL$CREATE

FDL$CREATE Create a File from an FOL
Specification and Close the
File
The FDL$CREATE routine creates a file from an FDL specification and then
closes the file.

FORMAT

FDL$CREATE

RETURNS

VMS usage:
type:
access:
mechanism:

fd/_desc [,filename] [,default_name]
[,resu/t_name] [,fid_block] [,flags]
[,stmnt_num] [,retlen] [,sts] [,stv]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

fd/_desc
VMS usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor-fixed-length string descriptor
Name of a file that contains the FDL specification or the actual FDL
specification to be parsed. The fdl_desc argument is the address of a
character string descriptor pointing to this information.

If the FDL$V_FDL_STRING flag is set in the mask argument,
FDL$CREATE interprets this argument as an FDL specification in string
form. Otherwise, FDL$CREATE interprets this argument as a file name.

filename
VMS usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor-fixed-length string descriptor
Name of the VMS RMS file to be created using the FDL specification.
The filename argument is the address of a character string descriptor
pointing to the VMS RMS file name. This name overrides the default_
name parameter given in the FDL specification.

This argument is optional.

FDL-6

File Definition Language (FOL) Routines
FDL$CREATE

default_ name
VMS usage: char_string
character-coded text string
access:
read only
mechanism: by descriptor-fixed-length string descriptor
Default name of the file to be created using the FDL specification. The
default_name argument is the address of a character string descriptor
pointing to the default file name. This name overrides any name given in
the FDL specification.
type:

This argument is optional.

result_ name
VMS usage: char_string
type:
character-coded text string
access:
write only
mechanism: by descriptor-fixed-length string descriptor
Resultant name of the file created by FDL$CREATE. The result_name
argument is the address of a character string descriptor that receives the
resultant file name.

This argument is optional.

fid_block
VMS usage: vector_longword_unsigned
longword (unsigned)
access:
write only
mechanism: by reference
File identification of the VMS RMS file created by FDL$CREATE. The
fid_block argument is the address of an array of longwords that receives
the VMS RMS file identification information. The first longword contains
the FID_NUM; the second contains the FID_SEQ; and the third contains
the FID_RVN. They have the following definitions:
type:

FID_NUM

The location of the file on the disk. Its value can range from 1 up to the
number of files the disk can hold.

FID_SEQ

The file sequence number, which is the number of times the file number
has been used.

FID_RVN

The relative volume number, which is the volume number of the volume
on which the file is stored. If the file is not stored on a volume set, the
relative volume number is 0.

This argument is optional.

flags
VMS usage: mask_longword
type:
longword (unsigned)
access:
read only
mechanism: by reference
Flags (or masks) that control how the fdl_desc argument is interpreted
and how errors are signaled. The :flags argument is the address of a
longword containing the control flags (or a mask). If you omit this
argument or specify it as zero, no flags are set. The table that follows
shows the flags and their meanings.

FDL-7

File Definition Language (FOL) Routines
FDL$CREATE

Flag

Description

FDL$V_FDL_STRING

Interprets the fdl_desc argument as an FDL specification
in string form. By default, the fdl_desc argument is
interpreted as the file name of an FDL file.

FDL$V_SIGNAL

Signals any error. By default, the status code is returned
to the calling image.

This argument is optional. By default, an error status is returned rather
than signaled.

stmnt_num
VMS usage: longword_unsigned
longword (unsigned)
access:
write only
mechanism: by reference
FDL statement number. The stmnt_num argument is the address of
a longword that receives the FDL statement number. If the routine
completes successfully, the stmnt_num argument is the number of
statements in the FDL specification. If the routine does not complete
successfully, the stmnt_num argument receives the number of the
statement that caused the error. In general, however, line numbers and
statement numbers are not the same. Null statements (blank lines) are
not counted. Also, an FDL specification in string form has no "lines."
type:

This argument is optional.

retlen
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
write only
mechanism: by reference
Number of characters returned in the result_name argument. The retlen
argument is the address of a longword that receives this number.

This argument is optional.

sts
VMS usage: longword_unsigned
type:
longword_unsigned
access:
write only
mechanism: by reference
VMS RMS status value FAB$L_STS. The sts argument is the address of
a longword that receives the VMS RMS status value FAB$L_STS from
SYS$CREATE.

stv
VMS usage: longword_unsigned
longword (unsigned)
access:
write only
mechanism: by reference
VMS RMS status value FAB$L_STv. The stv argument is the address of
a longword that receives the VMS RMS status value FAB$L_STV from
SYS$CREATE.
type:

FDL-8

File Definition Language {FOL) Routines
FDL$CREATE

DESCRIPTION

FDL$CREATE calls the FDL$PARSE routine to parse the FDL
specification. The FDL specification can be either in a file or a character
string. FDL$CREATE opens (creates) the specified VMS RMS file, and
then closes it without putting any data in it.
FDL$CREATE does not create the output file if an error status is either
returned or signaled.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

FDL$_ABKW

Ambiguous keyword in statement
'number' <CRLF>' reference-text'.

FDL$_ABPRIKW

Ambiguous primary keyword in statement
'number' <CRLF>' reference-text'.

FDL$_BADLOGIC

Internal logic error detected.

FDL$_CLOSEIN

Error closing 'filename' as input.

FDL$_CLOSEOUT

Error closing 'filename' as output.

FOL$_CREATE

Error creating 'filename'.

FDL$_CREATED

'filename' created.

FDL$_CREATED_STM

'filename' created in stream format.

FDL$_FDLERROR

Error parsing FOL file.

FDL$_1LL_ARG

Wrong number of arguments.

FDL$_1NSVIREM

Insufficient virtual memory.

FDL$_1NVBLK

Invalid VMS RMS control block at virtual address
' hex-offset' .

FDL$_MULPRI

Multiple primary definition in statement ' number' .

FDL$_0PENFDL

Error opening 'fil.ename' .

FDL$_0PENIN

Error opening ' filename' as input.

FDL$_0PENOUT

Error opening 'filename' as output.

FDL$_0UTORDER

Key or area primary defined out of order in statement
'number'.

FDL$_READERR

Error reading ' filename' .

FDL$_RFLOC

Unable to locate related file.

FDL$_SYNTAX

Syntax error in statement ' number' ' reference-text' .

FDL$_UNPRIKW

Unrecognized primary keyword in statement
'number' <CRLF> ' reference-text' .

FDL$_UNQUAKW

Unrecognized qualifier keyword in statement
'number' <CRLF> 'reference-text' .

FDL$_UNSECKW

Unrecognized secondary keyword in statement
'number' <CRLF> 'reference-text' .

FOL$_VALERA

Specified value is out of legal range.

FDL$_VALPRI

Value required on primary in statement ' number' .

FDL$_WARNING

Parsed with warnings.

FDL-9

File Definition Language {FOL) Routines
FDL$CREATE

FDL-10

FDL$_WRITEERR

Error writing 'filename'.

RMS$_ACT

File activity precludes operation.

RMS$_CRE

ACP file create failed.

RMS$_CREATED

File was created, not opened.

RMS$_DNF

Directory not found.

RMS$_DNR

Device not ready or not mounted.

RMS$_EXP

File expiration date not yet reached.

RMS$_FEX

File already exists, not superseded.

RMS$_FLK

File currently locked by another user.

RMS$_PRV

Insufficient privilege or file protection violation.

RMS$_SUPERSEDE

Created file superseded existing version.

RMS$_WLK

Device currently write locked.

File Definition Language (FOL) Routines
FDL$GENERATE

FDL$GENERATE Generate an FOL Specification
The FOL$GENERATE routine produces an FOL specification and writes it to
either an FOL file or a character string.

FORMAT

FDL$GENERATE

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

flags ,fab_pointer ,rab_pointer
[,fd/_fi/e_dst] [,fd/_file_resnam]
lfd/_su_dsQLbad_blk_addry
[,retlen]

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

flags
VMS usage: mask_longword
type:
longword (unsigned)
access:
read only
mechanism: by reference
Flags (or masks) that control how the fd.l_str_dst argument is interpreted
and how errors are signalled. The flags argument is the address of
a longword containing the control flags (or a mask). If you omit this
argument or specify it as zero, no flags are set. The flags and their
meanings are as follows:
Flag

Description

FOL$V_FOL_STRING

Interprets the fdl_str_dst argument as an FOL
specification in string form. By default, the fdl_str_
dst argument is interpreted as a file name ·of an FOL file.

FOL$V_FULL_OUTPUT

Includes the FOL attributes to describe all the bits and·
fields in the VMS RMS control blocks, including runtime options. If this flag is set, every VMS RMS field
is inspected before being written. By default, only the
FOL attributes that describe permanent file attributes are
included (producing a much shorter FOL specification).

FOL$V_SIGNAL

Signals any error. By default, the status code is returned
to the calling image.

This argument is optional. By default, an error status is returned rather
than signaled.
FDL-11

File Definition Language {FOL) Routines
FDL$GENERATE

fab_pointer
VMS usage: address
type:
longword (unsigned)
access:
read only
mechanism: by reference
VMS RMS file access block (FAB). The fab_pointer argument is the
address of a longword containing the address of a VMS RMS file access
block (FAB).

rab_pointer
VMS usage: address
type:
longword (unsigned)
access:
read only
mechanism: by reference
VMS RMS record access block (RAB). The rab_pointer argument is the
address of a longword containing the address of a VMS RMS record access
block (RAB).

fdl_file_dst
VMS usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor
Name of the FDL file to be created. The fdl_file_dst argument is the
address of a character string descriptor containing the file name of the
FDL file to be created. If the FDL$V_FDL_STRING flag is set in the flags
argument, this argument is ignored; otherwise, it is required. The FDL
specification is written to the file named in this argument.

fdl_file_resnam
VMS usage: char_string
type:
character-coded text string
access:
write only
mechanism: by descriptor-fixed-length string descriptor
Resultant name of the FDL file created. The fdl_file_resnam argument
is the address of a variable character string descriptor that receives the
resultant name of the FDL file created (if FDL$GENERATE is directed to
create an FDL file).

This argument is optional.

fd/_str_dst
VMS usage: char_string
type:
character-coded text string
access:
write only
mechanism: by descriptor-fixed-length string descriptor
FDL specification. The fdl_str_dst argument is the address of a variable
character string descriptor that receives the FDL specification created. If
the FDL$V_FDL_STRING bit is set in the flags argument, this argument
is required; otherwise, it is ignored.

FDL-12

File Definition Language (FOL) Routines
FDL$GENERATE

bad_blk_addr
VMS usage: address
type:

longword (unsigned)

access:
write only
mechanism: by reference
Address of an invalid VMS RMS control block. The bad_blk_addr
argument is the address of a longword that receives the address of an
invalid VMS RMS control block. If an invalid control block (a fatal error)
is detected, this argument is returned; otherwise, it is ignored.

This argument is optional.

retlen
VMS usage: longword_unsigned
type:

longword (unsigned)

access:
write only
mechanism: by reference
Number of characters received in either the fdl_file_resnam or the fdl_
str_dst argument. The retlen argument is the address of a longword that
receives this number.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

FDL$_1NVBLK
RMS$_ACT

Invalid VMS RMS control block at virtual address
' hex-offset' .
File activity precludes operation.

RMS$_CONTROLC

Operation completed under CTRUC.

RMS$_CONTROLO

Output completed under CTRUO.

RMS$_CONTROLY

Operation completed under CTRUY.

RMS$_DNR

Device not ready or mounted.

RMS$_EXT

ACP file extend failed.

RMS$_0K_ALK

Record already locked.

RMS$_0K_DUP

Record inserted had duplicate key.

RMS$_0K_IDX

Index update error occurred.

RMS$_PENDING

Asynchronous operation pending completion.

RMS$_PRV

Insufficient privilege or file protection violation.

RMS$_REX

Record already exists.

RMS$_RLK

Target record currently locked by another stream.

RMS$_RSA

Record stream currently active.

RMS$_WLK

Device currently write locked.

SS$_ACCVIO

Access violation.

STR$_FATINERR

Fatal internal error in Run-Time Library.

STR$_1LLSTRCLA

Illegal string class.

STR$_1NSVIRMEM

Insufficient virtual memory.

FDL-13

File Definition Language (FOL) Routines
FDL$PARSE

FDL$PARSE

Parse an FOL Specification
The FDL$PARSE routine parses an FOL specification, allocates VMS RMS
control blocks (FABs, RABs, or XABs), and fills in the relevant fields.

FORMAT

FDL$PARSE

RETURNS

VMS usage: cond_value
type:
longword {unsigned)
access:
write only
mechanism: by value

fdLspec ,fdLfab_pointer ,fdLrab_pointer
[,flags] [,df/t_fdLspc] [,stmnt_num]

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

fd/_spec
VMS usage: char_strlng
type:
character-coded text string
access:
read only
mechanism: by descriptor-fixed-length string descriptor
Name of the FDL file or the actual FDL specification to be parsed. The
fdl_spec argument is the address of a character string descriptor pointing
to either the name of the FDL file or the actual FDL specification to be
parsed. If the FDL$V_FDL_STRING flag is set in the flags argument,
FDL$PARSE interprets this argument as an FDL specification in string
form. Otherwise, FDL$PARSE interprets this argument as a file name of
an FDL file.

fd/_fab_pointer
VMS usage: address
type:
longword {unsigned)
access:
write only
mechanism: by reference
Address of an RMS file access block (FAB). The fdl_fab_pointer argument
is the address of a longword that receives the address of an RMS file access
block (FAB). FDL$PARSE both allocates the FAB and fills in its relevant
fields.

fd/_rab_pointer
VMS usage: address
type:
longword {unsigned)
access:
write only
mechanism: by reference
Address of an RMS record access block (RAB). The fdl_rab_pointer
argument is the address of a longword that receives the address of an
FDL-14

File Definition Language (FOL) Routines
FDL$PARSE

RMS record access block (RAB). FDL$PARSE both allocates the RAB and
fills in its relevant fields.

flags
mask_longword
longword {unsigned)
read only
by reference
Flags (or masks) that control how the dflt_fdl_spc argument is
interpreted and how errors are signaled. The :flags argument is the
address of a longword containing the control flags. If you omit this
argument or specify it as zero, no :flags are set. The :flags and their
meanings are as follows:
VMS usage:
type:
access:
mechanism:

Flag

Description

FOL$V_OEFAULT_STRING

Interprets the dflt_fdl_spc argument as an FOL
specification in string form. By default, the dflt_fdl_
spc argument is interpreted as a file name of an
FOL file.

FOL$V_FOL_STRING

Interprets the fdl_spec argument as an FOL
specification in string form. By default, the fdl_
spec argument is interpreted as a file name of an
FOL file.

FOL$V_SIGNAL

Signals any error. By default, the status code is
returned to the calling image.

This argument is optional. By default, an error status is returned rather
than signaled.

dflt_fdl_spc
char_string
character-coded text string
read only
by descriptor-fixed-length string descriptor
Name of the default FDL file or the default FDL specification itself. The
dflt_fd.l_spc argument is the address of a character string descriptor
pointing to either the default FDL file or the default FDL specification.
If the FDL$V_DEFAULT_STRING flag is set in the :flags argument,
FDL$PARSE interprets this argument as an FDL specification in string
form. Otherwise, FDL$PARSE interprets this argument as a file name of
an FDL file.
VMS usage:
type:
access:
mechanism:

This argument allows you to specify default FDL attributes. In other
words, FDL$PARSE processes the attributes specified in this argument,
unless you override them with the attributes you specify in the fdl_spec
argument.
You can code the FDL defaults directly into your program, typically with
an FDL specification in string form.
This argument is optional.

FDL-15

File Definition Language {FOL) Routines
FDL$PARSE

stmnt_num
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned}
write only
by reference

FDL statement number. The stmnt_num argument is the address of
a longword that receives the FDL statement number. If the routine
completes successfully, the stmnt_num argument is the number of
statements in the FDL specification. If the routine does not complete
successfully, the stmnt_num argument receives the number of the
statement that caused the error. In general, however, line numbers and
statement numbers are not the same.
This argument is optional. By default, an error status is returned rather
than signaled.

CONDITION
VALUES
RETURNED

FDL-16

SS$_NORMAL

Normal successful completion.

LIB$_BADBLOADR

Bad block address.

LIB$_BADBLOSIZ

Bad block size.

LIB$_1NSVIRMEM

Insufficient virtual memory.

RMS$_DNF

Directory not found.

RMS$_DNR

Device not ready or not mounted.

RMS$_WCC

Invalid wildcard context (WCC) value.

File Definition Language (FOL) Routines

FDL$RELEASE

Free Virtual Memory Obtained By
FDL$PARSE

The FDL$RELEASE routine deallocates the virtual memory used by the VMS
RMS control blocks created by FDL$PARSE. You must use FDL$PARSE
to populate the control blocks if you plan to deallocate memory with
FDL$RELEASE later.

FORMAT

FDL$RELEASE [fab_pointer] [,rab_pointer] [,flags]
[,badblk_addr]

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

fab_pointer
VMS usage:
type:
access:
mechanism:

address
longword (unsigned)
read only
by reference

File access block (FAB) to be deallocated using the LIB$FREE_VM
system service. The fab_pointer argument is the address of a longword
containing the address of the file access block (FAB). The FAB must be
the same one returned by the FDL$PARSE routine. Any name blocks
(NAMs) and extended attribute blocks (XABs) connected to the FAB are
also released.
This argument is optional. If you omit this argument or specify it as zero,
the FAB (and any associated NAM blocks and XABs) is not released.

rab_pointer
VMS usage:
type:
access:
mechanism:

address
longword (unsigned)
read only
by reference

Record access block (RAB) to be deallocated using the LIB$FREE_VM
system service. The rab_pointer argument is the address of a longword
containing the address of the record access block (RAB). The address of
the RAB must be the same one returned by the FDL$PARSE routine. Any
XABs connected to the RAB are also released.
This argument is optional. If you omit this argument or specify it as zero,
the RAB (and any associated XABs) is not released.
FDL-17

File Definition Language {FOL) Routines

FDL$RELEASE
flags
VMS usage: mask_longword
type:
longword (unsigned)
access:
read only
mechanism: by reference
Flag (or mask) that controls how errors are signalled. The :ftags argument
is the address of a longword containing the control flag (or a mask). If you
omit this argument or specify it as zero, no flag is set. The flag is defined
as follows:
FDL$V_SIGNAL

Signals any error. By default, the status code is returned to the
calling image.

This argument is optional.

badblk_addr
VMS usage: address
type:
longword (unsigned)
access:
write only
mechanism: by reference
Address of an invalid VMS RMS control block. The badblk_addr
argument is the address of a longword that receives the address of an
invalid VMS RMS control block. If an invalid control block (a fatal error)
is detected, this argument is returned; otherwise, it is ignored.

CONDITION
VALUES
RETURNED

FDL-18

SS$_NORMAL

Normal successful completion.

FDL$_1NVBLK

Invalid VMS RMS control block at virtual address
' hex-offset' .

LIB$_BADBLOADR

Bad block address.

RMS$_ACT

File activity precludes operation.

RMS$_RNL

Record not locked.

RMS$_RSA

Record stream currently active.

SS$_ACCVIO

Access violation.

Librarian (LBR) Routines

Libraries are files that provide a convenient way to organize frequently
used modules of code or text. The librarian routines allow you to create
and maintain libraries and their modules and to use the data stored in
library modules.

8.1

Introduction to LBR Routines
You can also create and maintain libraries at the DCL level, using the
DCL command LIBRARY. For details, see the VMS DCL Dictionary.

8.1.1

Types of Library
You can use the librarian routines to maintain the following types of
library:
•

Object libraries, which contain the object modules of frequently called
routines. The VMS Linker Utility searches specified object module
libraries when it encounters a reference it cannot resolve in one of its
input files. For more information about how the linker uses libraries,
see the description of the VMS Linker Utility in the VMS Linker
Utility Manual.
An object library has a default file type of OLB and defaults the file
type of input files to OBJ.

•

Macro libraries, which contain macro definitions used as input to the
assembler. The assembler searches specified macro libraries when it
encounters a macro that is not defined in the input file. See the VAX
MACRO and Instruction Set Reference Manual for information about
defining macros.
A macro library has a default file type of MLB and defaults the file
type of input files to MAR.

•

Help libraries, which contain modules of help messages that provide
user information about a program. You can retrieve help messages
at DCL level by executing the DCL command HELP, or in your
program by calling the appropriate librarian routines. For information
about creating help modules for insertion into help libraries, see the
description of the Librarian Utility in the VMS Librarian Utility
Manual.
A help library has a default file type of HLB and defaults the file type
of input files to HLP.

•

Text libraries, which contain any sequential record files that you
want to retrieve as data for a program. For example, some compilers
can retrieve program source code from text libraries. Each text
file inserted into the library corresponds to one library module.
LBR-1

Librarian {LBR) Routines
8.1 Introduction to LBR Routines

Your programs can retrieve text from text libraries by calling the
appropriate librarian routines.
A text library has a default file type of TLB and defaults the file type
of input files to TXT.
•

Shareable image libraries, which contain the symbol tables of
shareable images used as input to the linker. For information about
how to create a shareable image· library, see the descriptions of the
Librarian and Linker Utilities in the VMS Librarian Utility Manual
and the VMS Linker Utility Manual.
A shareable image library has a default type of OLB and defaults the
file type of input files to EXE.

•

8.1.2

User-developed libraries, which have characteristics specified when you
call the LBR$0PEN routine to create a new library. User-developed
libraries allow you to use the librarian routines to create and maintain
libraries that are not structured in the form assigned by default to
the other library types. Note that you cannot use the DCL command
LIBRARY to access user-developed libraries.

Structure of Libraries
You create libraries by executing the DCL command LIBRARY or by
calling the LBR$0PEN routine. When object, macro, text, help, or
shareable image libraries are created, the Librarian Utility structures
them as described in Figures 8-1 and 8-2. You can create user-developed
libraries only by calling LBR$0PEN; they are structured as described in
Figure 8-3.
8.1.2.1

Library Headers

Every library contains a library header that describes the contents of
the library, for example, its type, size, version number, creation date, and
number of indexes. You can retrieve data from a library's header by calling
the LBR$GET_HEADER routine.
8.1.2.2

Modules

Each library module consists of a header and data. The data is the
data you inserted into the library; the header associated with the data
is created by the librarian routine and provides information about the
module, including its type, attributes, and date of insertion into the library.
You can read and update a module's header by calling the LBR$SET_
MODULE routine.
8.1.2.3

Indexes and Keys

Libraries contain one or more indexes, which can be thought of as
directories of the library's modules. The entries in each index are keys,
and each key consists of a key name and a module reference. The module
reference is a pointer to the module's header record and is called that
record's file address (RFA). Macro, text, and help libraries (see Figure 8-1)
contain only one index, called the module name table. The names of the
keys in the index are the names of the modules in the library.
LBR-2

Librarian (LBR) Routines
8.1 Introduction to LBR Routines

Object and shareable image libraries (see Figure 8-2) contain two indexes:
the module name table and a global symbol table. The global symbol table
consists of all the global symbols defined in the modules in the library.
Each global symbol is a key in the index and points to the module in
which it was defined.
If you need to point to the same module with several keys, you should

create a user-developed library, which can have up to eight indexes
(see Figure 8-3). Each index consists of keys that point to the library's
modules.
The librarian routines differentiate library indexes by numbering them,
starting with 1. For all but user-developed libraries, the module name
table is index number 1 and the global symbol table, if present, is index
number 2. You number the indexes in user-developed libraries. When you
access libraries that contain more than one index, you may have to call
LBR$SET_INDEX to tell the librarian routines which index to use.
Figure 8-1

Structure of a Macro, Text, or Help Library

Library Header

Index (Module Name Table)

IKey-1j IKey-2j IKey-3j

IKey-nj

•••

Each key in the index points to a module.
Modules
Header

Header

Data

ZK-1871-GE

LBR-3

Librarian (LBR) Routines
8.1 Introduction to LBR Routines

Figure 8-2 Structure-of an Object or Shareable Image Library

Library Header

Index (Module Name Table)

IKey-11 IKey-21

IKey-3f

IKey-nf

•••

Each key in the index points to a module.
Index (Global Symbol Table)
Global
Symbol

Global
Symbol

Each global symbol is a key in the index, and points to the module in
which it was defined.
Modules
Header

Header

Data

ZK-1872-GE

LBR-4

Librarian (LBR) Routines
8.1 Introduction to LBR Routines

Figure 8-3 Structure of a User-Developed Library

Library Header
Index

Each key in an index points to one module. More than one key (from
the same or a different index) may point to the same module.

~ ~

IKeyl ~ 8 ~ IKeyl

Can have up to
8 indexes.

•
•
•
Index

IKeyl ~ ~ IKeyl IKeyj jKeyf ~
Modules
Header

Header

Data

ZK-1873-GE

8.1.2.4

Summary of Routines

All the librarian routines begin with the characters LBR$. Your programs
can call these routines by using the VMS Procedure Calling and Condition
Handling Standard, which is documented in the Introduction to VMS
System Routines. When you call a librarian routine, you must provide
whatever arguments the routine requires; when the routine completes
execution, it returns a status value to your program. In addition to the
condition values listed with the descriptions of each routine, some routines
may return the success code SS$_NORMAL as well as various RMS or
SS error codes. When you link programs that contain calls to librarian
LBR-5

Librarian {LBR) Routines
8.1 Introduction to LBR Routines

routines, the linker locates the routines during its default search of
SYS$SHARE:LBRSHR.
The following table lists the routines and summarizes their functions.

LBR-6

Routine Name

Function

LBR$CLOSE

Closes an open library.

LBR$DELETE_DATA

Deletes a specified module's header and data.

LBR$DELETE_KEY

Deletes a key from a library index.

LBR$FIND

Finds a module by using an address returned by a
preceding call to LBR$LOOKUP_KEY.

LBR$FLUSH

Writes the contents of modified blocks to the library file and
returns the virtual memory that contained those blocks.

LBR$GET_HEADER

Retrieves information from the library header.

LBR$GET_HELP

Retrieves help text from a specified library.

LBR$GET_HISTORY

Retrieves library update history records and calls a usersupplied routine with each record returned.

LBR$GET_INDEX

Calls a routine to process modules associated with some or
all of the keys in an index.

LBR$GET_RECORD

Reads a data record from the module associated with a
specified key.

LBR$1N I_CONTROL

Initializes a control index that the librarian uses to identify a
library.

LBR$1NSERT_KEY

Inserts a new key in the current library index.

LBR$LOOKUP_KEY

Looks up a key in the current index.

LBR$0PEN

Opens an existing library or creates a new one.

LBR$0UTPUT_HELP

Retrieves help text from an explicitly named library or from
user-supplied default libraries, and optionally prompts you
for additional help queries.

LBR$PUT_END

Terminates a sequence of records written to a module with
LBR$PUT_RECORD.

LBR$PUT_HISTORY

Inserts a library update history record.

LBR$PUT_RECORD

Writes a data record to the module associated with the
specified key.

LBR$REPLACE_KEY

Replaces an existing key in the current library index.

LBR$RET_RMSSTV

Returns the last VMS RMS status value.

LBR$SEARCH

Finds index keys that point to specified data.

LBR$SET_INDEX

Sets the index number to be used during processing of the
library.

LBR$SET_LOCATE

Sets librarian subroutine record access to locate mode.

LBR$SET_MODULE

Reads and optionally updates a module header.

LBR$SET_MOVE

Sets librarian subroutine record access to move mode.

Librarian {LBR) Routines
8.2 Using the LBR Routines: Examples

8.2

Using the LBR Routines: Examples
This section provides programming examples that show how to call LBR$
routines to create a library, insert a module into a library, extract a module
from a library, and delete a module from a library. Although the examples
do not use all of the librarian routines, they do provide an introduction to
the data structures needed and the calling syntax required to use any of
the routines.
For each library you want to work with, you must call LBR$INI_
CONTROL and LBR$0PEN before calling any other routine (except
LBR$0UTPUT_HELP).
When you call LBR$INI_CONTROL, this routine sets up a control index
(do not confuse this with a library index) that is used, in the calls to the
other librarian routines, to identify the library to which the routine applies
(because you may want your program to work with more than one library
at a time). LBR$INI_CONTROL also specifies whether you want to create,
read, or modify the library.
After you call LBR$INI_CONTROL, you call LBR$0PEN to open the
library and specify its type. When you finish working with a library,
you should call LBR$CLOSE to close it. Remember to call LBR$INI_
CONTROL again, if you want to reopen the library. LBR$CLOSE
deallocates all the memory associated with the library including the
control index. The order in which you call the routines between
LBR$0PEN and LBR$CLOSE depends upon the library operations
you need to perform. You may want to call LBR$LOOKUP_KEY or
LBR$GET_INDEX to find a key, then perform some operation on the
module associated with the key. You can think of a module as being both
the module itself and its associated keys. To access a module, you first
need to access a key that points to it; to delete a module, you first need to
delete any keys that point to it.
The examples are written in VAX Pascal. In VAX Pascal, all data items,
functions (such as the librarian routines), and procedures must be
declared at the beginning of the program. Following the declarations
is the executable section, which performs the actions of the program. The
executable section makes extensive use of the structured control constructs
IF-THEN-ELSE and WHILE-condition-DO. Note that code between a
BEGIN END pair is treated as a unit.
The listing of each example contains many comments (any code between a
pair of asterisks ( * * ) is a comment), and each listing is followed by notes
about the program. The highlighted numbers in the notes are keyed to the
highlighted numbers in the examples.
Example 8-1 illustrates the use of LBR routines to create a new library.

LBR-7

Librarian {LBR) Routines
8.2 Using the LBR Routines: Examples

Example 8-1

Creating a New Library Using VAX Pascal

PROGRAM createlib(INPUT,OUTPUT);
(*This program creates a text library*)
TYPE
(*Data type of*)
Create_Array =ARRAY (1 .. 20] OF INTEGER;
(*create options array*)
VAR
(*Constants and return status error
codes for LBR$ OPEN & LBR$INI CONTROL.
These are defined in $LBRDEF macro*)
LBR$C CREATE,LBR$C TYP TXT,LBR$ ILLCREOPT,LBR$ ILLCTL,
tt
LBR$_ILLFMT,LBR$_NOFILNAM,LBR$_0LDMISMCH,LBR$_TYPMISMCH :
[EXTERNAL] INTEGER;
(*Create options array codes. These
are defined in $CREDEF macro*)
CRE$L TYPE,CRE$L KEYLEN,CRE$L ALLOC,CRE$L IDXMAX,CRE$L ENTALL, ~
CRE$L-LUHMAX,CRE$L VERTYP,CRE$L IDXOPT,CRE$C MACTXTCAS~
CRE$C-VMSV3 :
[EXTERNAL] INTEGER;
Lib Name : VARYING [128] OF CHAR;
(*Name of library to create*)
Options : Create Array;
(*Create options array*)
File Type : PACKED ARRAY [1 .. 4]
(*Character string that is default*)
OF CHAR:=' .TLB';
(*file type of created lib file*)
lib_index_ptr : UNSIGNED;
(*Value returned in library init*)
status : UNSIGNED;
(*Return Status for function calls*)
(*-*-*-*-Function and Procedure Definitions-*-*-*-*)
(*Function that returns library
control index used by librarian*)
FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED;
.,
func: UNSIGNED;
typ: UNSIGNED;
VAR namblk: ARRAY[l .. u:INTEGER]
OF INTEGER := %IMMED 0):
INTEGER; EXTERN;
(*Function that creates/opens library*)
FUNCTION LBR$0PEN
(library index: UNSIGNED;
fns: [class_s]PACKED ARRAY[l .. u:INTEGER] OF CHAR;
create_options: Create_Array;
dns: [CLASS S] PACKED ARRAY [13 .. u3:INTEGER] OF CHAR;
rlfna: ARRAY [14 .. u4:INTEGER] OF INTEGER:= %IMMED O;
rns: [CLASS_S] PACKED ARRAY [15 .. uS:INTEGER] OF CHAR:=
%IMMED 0;
VAR rnslen: INTEGER := %IMMED 0):
INTEGER; EXTERN;
(*Function that closes library*)
FUNCTION LBR$CLOSE (library_index: UNSIGNED):
INTEGER; EXTERN;
(*Error handler to check error codes
if open/create not successful*)
(continued on next page)

LBR-8

Librarian (LBR) Routines
8.2 Using the LBR Routines: Examples

Example 8-1 {Cont.)

Creating a New Library Using VAX Pascal

PROCEDURE Open_Error;
Gt
BEGIN
WRITELN('Open Not Successful'); (*Now check specific error codes*)
IF status = IADDRESS(LBR$_ILLCREOPT) THEN
WRITELN('
Create Options Not Valid Or Not Supplied');
IF status= IADDRESS(LBR$ ILLCTL) THEN
WRITELN('
Invalid Library Index');
IF status = IADDRESS(LBR$ ILLFMT) THEN
WRITELN('
Library Not In Correct Format');
IF status = IADDRESS(LBR$ NOFILNAM) THEN
WRITELN('
Library Name Not Supplied');
IF status = IADDRESS(LBR$ OLDMISMCH) THEN
WRITELN('
Old Library Conflict');
IF status = IADDRESS(LBR$ TYPMISMCH) THEN
WRITELN ('
Library Type Mismatch')
END; (*of procedure Open_Error*)
BEGIN
(* *************** DECLARATIONS COMPLETE *************************
*************** MAIN PROGRAM BEGINS HERE ********************** *)
(*Prompt for Library Name*)
WRITE('Library Name: '); READLN(Lib_Name);
(*Fill Create Options Array. Divide
by 4 and add 1 to get proper subscript*)
Options[IADDRESS(CRE$L TYPE) DIV 4 + 1)
:= IADDRESS(LBR$C TYP TXT);
Options [IADDRESS (CRE$L=KEYLEN) DIV 4 + 1) := 31;
8
- Options[IADDRESS(CRE$L ALLOC) DIV 4 + 1)
:= 8;
Options[IADDRESS(CRE$L=IDXMAX) DIV 4 + 1] := 1;
Options[IADDRESS(CRE$L_ENTALL) DIV 4 + 1] := 96;
Options[IADDRESS(CRE$L_LUHMAX) DIV 4 + 1) := 20;
Options[IADDRESS(CRE$L_VERTYP) DIV 4 + 1) := IADDRESS(CRE$C VMSV3);
Options[IADDRESS(CRE$L IDXOPT) DIV 4 + 1) := IADDRESS(CRE$C-MACTXTCAS);
(*Initialize library co~trol index*)
status := LBR$INI_CONTROL
(lib_index_ptr,
(!)
IADDRESS(LBR$C CREATE),
(*Create access*)
IADDRESS(LBR$C=TYP_TXT));
(*Text library*)
IF NOT ODD(status) THEN
(*Check return status*)
WRITELN('Initialization Failed')
ELSE
(*Initialization was successful*)
BEGIN
(*Create and open the library*)
( lib_index_ptr,
status ·= LBR$0PEN
Lib_Name,
Options,
8
File_Type);
IF NOT ODD(status) THEN (*Check return status*)
Open_Error
(*Call error handler*)
.,
ELSE
(*Open/create was successful*)
BEGIN
(*Close the library*)
status := LBR$CLOSE(lib_index_ptr);
IF NOT ODD(status) THEN (*Check return status*)
WRITELN('Close Not Successful')
END
END
END. (*of program creatlib*)

Each item in the following list corresponds to a number highlighted in
Example 8-1.

LBR-9

Librarian {LBR) Routines
8.2 Using the LBR Routines: Examples

8 To gain access to these LBR$ symbols in your program, write the
following two-line MACRO program:
$LBRDEF GLOBAL
.END

Then assemble the program into an object module by executing the
command:
MACRO program-name

Finally, link the resultant object module with the object module created
when your source program is compiled or assembled. (Note: Pascal
programmers alternatively may use the INHERIT attribute to include
these symbols from SYS$LIBRARY:STARLET.PEN.)

fl To gain access to the CRE$ symbols, write a two-line MACRO program
as described in item 1, substituting $CREDEF for $LBRDEF.

8 Start the declarations of the librarian routines that are used by the
program. Each argument to be passed to the librarian is specified
on a separate line and includes the name (which just acts as a
placeholder) and data type (for example: UNSIGNED, which means an
unsigned integer value, and PACKED ARRAY OF CHAR, which means
a character string). If the argument is preceded by VAR, then a value
for that argument is returned by the librarian to the program.

8 Declare the procedure Open_Error, which is called in the executable
section if the librarian returns an error when LBR$0PEN is called.
Open_Error checks the librarian's return status value to determine the
specific cause of the error. The return status values for each routine
are listed in the descriptions of the routines.

8 Initialize the array called Options with the values the librarian needs
to create the library.
•

Call LBR$INI_CONTROL, specifying that the function to be performed
is create and that the library type is text.

8 Call LBR$0PEN to create and open the library; pass the Options
array initialized in item 5 to the librarian.

fD If the call to LBR$0PEN was unsuccessful, call the procedure Open_
Error (see item 4) to determine the cause of the error.
Example 8-2 illustrates the use of LBR routines to insert a new module
into a library.

LBR-10

Librarian (LBR) Routines
8.2 Using the LBR Routines: Examples

Example 8-2

Inserting a Module Into a Library Using VAX Pascal

PROGRAM insertmod(INPUT,OUTPUT);
(*This program inserts a module into a library*)
TYPE
Rfa Ptr =ARRAY [0 •• 1] OF INTEGER;
(*Data type of RFA of module*)
VAR
LBR$C_UPDATE,
(*Constants for LBR$INI_CONTROL*)
LBR$C TYP TXT,
(*Defined in $LBRDEF macro*)
LBR$_KEYNOTFND : [EXTERNAL] INTEGER; (*Error code for LBR$LOOKUP KEY*)
Lib Name : VARYING [128] OF CHAR;
(*Name of library receiving-module*)
Module Name : VARYING [31] OF CHAR; (*Name of module to insert*)
Text Data Record : VARYING [255] OF CHAR; (*Record in new module*)
Textin : FILE OF VARYING [255] OF CHAR; (*File containing new module*)
lib index ptr : UNSIGNED;
(*Value returned in library init*)
status : UNSIGNED;
(*Return status for function calls*)
txtrfa_ptr : Rfa_Ptr;
(*For key lookup and insertion*)
Key Not Found : BOOLEAN := FALSE;
(*True if new mod not already in lib*)
(*-*-*-*-Function Definitions-*-*-*-*)
(*Function that returns library
control index used by librarian*)
FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED;
func: UNSIGNED;
typ: UNSIGNED;
VAR namblk: ARRAY[l .. u:INTEGER]
OF INTEGER := %IMMED 0):
INTEGER; EXTERN;
(*Function that creates/opens library*)
FUNCTION LBR$0PEN
(library index: UNSIGNED;
fns: [class s]PACKED ARRAY[l .. u:INTEGER] OF CHAR;
create options: ARRAY [12 .. u2:INTEGER] OF INTEGER:=
%IMMED O;
dns: [CLASS_S] PACKED ARRAY [13 .. u3:INTEGER] OF CHAR
:= %IMMED 0;
rlfna: ARRAY [14 .. u4:INTEGER] OF INTEGER:= %IMMED 0;
rns: [CLASS_S] PACKED ARRAY [15 .. u5:INTEGER] OF CHAR:=
%IMMED O;
VAR rnslen: INTEGER := %IMMED 0) :
INTEGER; EXTERN;
(*Function that finds a key in index*)
FUNCTION LBR$LOOKUP_KEY (library_index: UNSIGNED;
key_name: [CLASS_S] PACKED ARRAY [l .. u:INTEGER] OF
CHAR;
VAR txtrfa: Rfa_Ptr):
INTEGER; EXTERN;
(*Function that inserts key in index*)
FUNCTION LBR$INSERT_KEY (library_index: UNSIGNED;
key_name: [CLASS_S] PACKED ARRAY [l .. u:INTEGER] OF
CHAR;
txtrfa: Rfa_Ptr):
INTEGER; EXTERN;
(*Function that writes data records*)

(continued on next page)

LBR-11

Librarian (LBR) Routines
8.2 Using the LBR Routines: Examples

Example 8-2 (Cont.)

Inserting a Module Into a Library Using VAX Pascal

FUNCTION LBR$PUT_RECORD (library index: UNSIGNED;
(*to modules*)
textline: [CLASS_S] PACKED ARRAY [l .. u:INTEGER] OF
CHAR;
txtrfa: Rfa_Ptr):
INTEGER; EXTERN;
(*Function that marks end of a module*)
FUNCTION LBR$PUT_END (library_index: UNSIGNED):
INTEGER; EXTERN;
(*Function that closes library*)
FUNCTION LBR$CLOSE (library_index: UNSIGNED):
INTEGER; EXTERN;
BEGIN
(* *************** DECLARATIONS COMPLETE *************************
*************** MAIN PROGRAM BEGINS HERE ********************** *)
(*Prompt for library name and
module to insert*)
WRITE('Library Name: '); READLN(Lib_Name);
WRITE('Module Name:
'); READLN(Module Name);
(*Initialize lib for update access*)
status := LBR$INI_CONTROL
(lib index ptr,
tt
IADDRESS(LBR$C UPDATE),
(*Update access*)
IADDRESS(LBR$C=TYP_TXT));
(*Text library*)
IF NOT ODD(status) THEN
(*Check error status*)
WRITELN('Initialization Failed')
ELSE
(*Initialization was successful*)
BEGIN
status := LBR$0PEN
(lib index ptr, (*Open the library*)
Lib_Name);
IF NOT ODD(status) THEN
(*Check error status*)
WRITELN('Open Not Successful')
ELSE
(*Open was successful*)
BEGIN
(*Is module already in the library?*)
status := LBR$LOOKUP_KEY
(lib_index_ptr,
~
Module_Name,
txtrfa_ptr) ;
IF ODD(status) THEN (*Check status. Should not be odd*)
WRITELN('Lookup key was successful.',
'The module is already in the library.')
ELSE
(*Did lookup key fail because key not found?*)
IF status= IADDRESS(LBR$_KEYNOTFND) THEN.,
Key_Not_Found := TRUE
END
END;
(continued on next page)

LBR-12

Librarian (LBR) Routines
8.2 Using the LBR Routines: Examples

Example 8-2 (Cont.)

Inserting a Module Into a Library Using VAX Pascal

(******If LBR$LOOKUP_KEY failed because the key was not found
(as expected), we can open the file containing the new module,
and write the module's records to the library file*******)
IF Key_Not_Found THEN
BEGIN
OPEN(Textin,Module_Name,old);
RESET(Textin);
WHILE NOT EOF(Textin) DO
(*Repeat until end of file*)
BEGIN
READ(Textin,Text_Data_Record);
(*Read record from
external file*)
status := LBR$PUT_RECORD
(lib index ptr,
(*Write*)
Text-Data Record, (*record to*)
txtrfa__ptr);
(*library*)
IF NOT ODD(status) THEN
WRITELN('Put Record Routine Not Successful')
END; (*of WHILE statement*)
IF ODD(status) THEN (*True if all the records have been
successfully written into the library*)
BEGIN
status ·= LBR$PUT_END (lib_index_ptr); (*Write end of
module record*)
IF NOT ODD(status) THEN
WRITELN('Put End Routine Not Successful')
ELSE
(*Insert key for new module*)
BEGIN
8
(lib_index_pt r,
status := LBR$INSERT_KEY
Module_Name,
txtrfa_ptr);
IF NOT ODD(status) THEN
WRITELN('Insert Key Not Successful')
END
END
END;
status := LBR$CLOSE(lib_index__ptr);
IF NOT ODD(status) THEN
WRITELN('Close Not Successful')
END. (*of program insertmod*)

Each item in the following list corresponds to a number highlighted in
Example 8-2.

0 Call LBR$INI_CONTROL, specifying that the function to be performed
is update and that the library type is text.

8 Call LBR$LOOKUP_KEY to see whether the module to be inserted is
already in the library.

0 Call LBR$LOOKUP_KEY to see whether the lookup key failed because
the key was not found. (In this case, the status value is LBR$_
KEYNOTFND.)

8 Read a record from the input file, then use LBR$PUT_RECORD to
write the record to the library. When all the records have been written
to the library, use LBR$PUT_END to write an end of module record.

LBR-13

Librarian {LBR) Routines
8.2 Using the LBR Routines: Examples

Use LBR$INSERT_KEY to insert a key for the module into the current
index.

Example 8-3 illustrates the use of LBR routines to extract a module from
a library.
Example 8-3

Extracting a Module from a Library Using VAX Pascal

PROGRAM extractmod(INPUT,OUTPUT,Textout);
(*This program extracts a module from a library*)
TYPE
Rfa Ptr =ARRAY [0 .. l] OF INTEGER;
(*Data type of RFA of module*)
VAR
LBR$C UPDATE,
(*Constants for LBR$INI CONTROL*)
LBR$C-TYP TXT,
(*Defined in $LBRDEF macro*)
RMS$_EOF - [EXTERNAL] INTEGER;
(*RMS return status; defined in
$RMSDEF macro*)
Lib_Name : VARYING [128] OF CHAR;
(*Name of library receiving module*)
Module Name : VARYING [31] OF CHAR; (*Name of module to insert*)
Extracted_File : VARYING [31] OF CHAR;
(*Name of file to hold
extracted module*)
(*Extracted mod put here,*)
Outtext : PACKED ARRAY [1 .. 255] OF CHAR;
Outtext2 : VARYING [255] OF CHAR;
(*
then moved to here*)
i : INTEGER;
(*For loop control*)
Textout : FILE OF VARYING [255] OF CHAR;
(*File containing extracted
module*)
nullstring : CHAR;
(*nullstring, pos, and len used to*)
pos, len : INTEGER;
(*find string in extracted file recd*)
lib_index_ptr : UNSIGNED;
(*Value returned in library init*)
status : UNSIGNED;
(*Return status for function calls*)
txtrfa_ptr : Rfa_Ptr;
(*For key lookup and insertion*)
(*-*-*-*-Function Definitions-*-*-*-*)
(*Function that returns library
control index used by librarian*)
FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED;
func: UNSIGNED;
typ: UNSIGNED;
VAR namblk: ARRAY[l .. u:INTEGER]
OF INTEGER := %IMMED 0):
INTEGER; EXTERN;
(*Function that creates/opens library*)
FUNCTION LBR$0PEN
(library_index: UNSIGNED;
fns: [class_s]PACKED ARRAY[l .. u:INTEGER] OF CHAR;
create_options: ARRAY [12 .. u2:INTEGER] OF INTEGER:=
%IMMED 0;
dns: [CLASS_S] PACKED ARRAY [13 .. u3:INTEGER] OF CHAR
:= %IMMED O;
rlfna: ARRAY [14 .. u4:INTEGER] OF INTEGER := %IMMED 0;
rns: [CLASS_S] PACKED ARRAY [15 .. u5:INTEGER] OF CHAR:=
%IMMED 0;
VAR rnslen: INTEGER := %IMMED 0):
INTEGER; EXTERN;
(*Function that finds a key in an index*)
FUNCTION LBR$LOOKUP_KEY (library_index: UNSIGNED;
key_name: [CLASS_S] PACKED ARRAY [l .. u:INTEGER] OF
CHAR;
VAR txtrfa: Rfa_Ptr):
INTEGER; EXTERN;
(continued on next page)

LBR-14

Librarian {LBR) Routines
8.2 Using the LBR Routines: Examples

Example 8-3 (Cont.) Extracting a Module from a Library Using VAX Pascal
(*Function that retrieves records from modules*)
FUNCTION LBR$GET_RECORD (library index: UNSIGNED;
var textline: [CLASS_S] PACKED ARRAY [l .. u:INTEGER] OF
CHAR):
INTEGER;
EXTERN;
(*Function that closes library*)
FUNCTION LBR$CLOSE (library_index: UNSIGNED):
INTEGER; EXTERN;
BEGIN
(* *************** DECLARATIONS COMPLETE *************************
*************** MAIN PROGRAM BEGINS HERE ********************** *)
(* Get Library Name, Module To Extract, And File To Hold Extracted Module *)
WRITE('Library Name: '); READLN(Lib_Name);
WRITE{'Module Name:
'); READLN{Module Name);
WRITE{'Extract Into File: '); READLN(Extracted_File);
status := LBR$INI_CONTROL

(lib_index_ptr,
..
IADDRESS(LBR$C UPDATE),
IADDRESS(LBR$C=TYP_TXT));

IF NOT ODD{status) THEN
WRITELN('Initialization Failed')
ELSE
BEGIN
status := LBR$0PEN
(lib index ptr,
Lib_Name);IF NOT ODD{status) THEN
WRITELN('Open Not Successful')
ELSE
BEGIN
•
status := LBR$LOOKUP_KEY

(lib_index_ptr,
Module_Name,
txtrfa_ptr);

IF NOT ODD(status) THEN
WRITELN{'Lookup Key Not Successful')
ELSE
BEGIN
OPEN(Textout,Extracted_File,new);
REWRITE(Textout)
END
END
END;
WHILE ODD{status) DO
BEGIN
nullstring := ' ' (0);
FOR i := 1 TO 255 DO
Outtext[i] := nullstring;
status := LBR$GET_RECORD
(lib_index_ptr,
Outtext);
IF NOT ODD(status) THEN
BEGIN
IF status = IADDRESS(RMS$_EOF) THEN
WRITELN('
RMS end of file')
END

•
•

(continued on next page}

LBR-15

Librarian (LBR) Routines
8.2 Using the LBR Routines: Examples

Example 8-3 (Cont.)

Extracting a Module from a Library Using VAX Pascal

ELSE
BEGIN
pos := INDEX(Outtext, nullstring);

(*find first null
in Outtext*)
(*length of Outtext to first null*)

len := pos - 1;
IF len >= 1 THEN
BEGIN
Outtext2 ·= SUBSTR(Outtext,1,LEN);
WRITE(Textout,Outtext2)
END
END
END; (*of WHILE*)
status := LBR$CLOSE(lib_index_ptr);
IF NOT ODD(status) THEN
WRITELN('Close Not Successful')
END. (*of program extractmod*)

Each item in the following list corresponds to a number highlighted in
Example 8-3.

0 Call LBR$INI_CONTROL, specifying that the function to be performed
is update and that the library type is text.

8 Call LBR$LOOKUP_KEY to find the key that points to the module you
want to extract.

0 Open an output file to receive the extracted module.

8 Initialize the variable that is to receive the extracted records to null
characters.

8 Call LBR$GET_RECORD to see ifthere are more records in the file
(module). A failure indicates that the end of the file has been reached.

<t Write the extracted record data to the output file. This record should
consist only of the data up to the first null character.
Example 8-4 illustrates the use of LBR routines to delete a library.

LBR-16

Librarian (LBR) Routines
8.2 Using the LBR Routines: Examples

Example 8-4 Deleting a Module from a Library Using VAX Pascal
PROGRAM deletemod(INPUT,OUTPUT);
(*This program deletes a module from a library*)
TYPE
Rfa Ptr =ARRAY [0 .. 1] OF INTEGER;
(*Data type of RFA of module*)
VAR
LBR$C UPDATE,
(*Constants for LBR$INI CONTROL*)
LBR$C-TYP TXT,
(*Defined in $LBRDEF macro*)
LBR$_KEYNOTFND : [EXTERNAL] INTEGER; (*Error code for LBR$LOOKUP_KEY*)
Lib_Name : VARYING [128] OF CHAR;
(*Name of library receiving module*)
Module_Name : VARYING [31] OF CHAR; (*Name of module to insert*)
Text Data Record : VARYING [255] OF CHAR; (*Record in new module*)
Textin : FILE OF VARYING [255] OF CHAR; (*File containing new module*)
lib_index_ptr : UNSIGNED;
(*Value returned in library init*)
status : UNSIGNED;
(*Return status for function calls*)
txtrfa_ptr : Rfa_Ptr;
(*For key lookup and insertion*)
Key_Not_Found : BOOLEAN := FALSE;
(*True if new mod not already in lib*)
(*-*-*-*-Function Definitions-*-*-*-*)
(*Function that returns library
control index used by librarian*)
FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED;
func: UNSIGNED;
typ: UNSIGNED;
VAR namblk: ARRAY[l .. u:INTEGER]
OF INTEGER := %IMMED 0):
INTEGER; EXTERN;
(*Function that creates/opens library*)
FUNCTION LBR$0PEN
(library_index: UNSIGNED;
fns: [class_s]PACKED ARRAY[l .. u:INTEGER] OF CHAR;
create_options: ARRAY [12 .. u2:INTEGER] OF INTEGER·=
%IMMED O;
dns: [CLASS_S] PACKED ARRAY [13 .. u3:INTEGER] OF CHAR
:= %IMMED 0;
rlfna: ARRAY [14 .. u4:INTEGER] OF INTEGER:= %IMMED 0;
rns: [CLASS_S] PACKED ARRAY [15 .. u5:INTEGER] OF CHAR:=
%IMMED 0;
VAR rnslen: INTEGER := %IMMED 0):
INTEGER; EXTERN;
(*Function that finds a key in index*)
FUNCTION LBR$LOOKUP_KEY (library_index: UNSIGNED;
key_name: [CLASS_S] PACKED ARRAY [l .. u:INTEGER] OF
CHAR;
VAR txtrfa: Rfa_Ptr):
INTEGER; EXTERN;
(*Function that removes a key from an index*)
FUNCTION LBR$DELETE_KEY (library_index: UNSIGNED;
key_name: [CLASS_S] PACKED ARRAY [l .. u:INTEGER] OF
CHAR):
INTEGER;
EXTERN;
(continued on next page)

LBR-17

Librarian (LBR) Routines
8.2 Using the LBR Routines: Examples

Example 8-4 (Cont.) Deleting a Module from a Library Using VAX Pascal
(*Function that deletes all the records
associated with a module*)
FUNCTION LBR$DELETE_DATA (library_index: UNSIGNED;
txtrfa: Rfa_Ptr):
INTEGER;
EXTERN;
(*Function that closes library*)
FUNCTION LBR$CLOSE (library_index: UNSIGNED):
INTEGER; EXTERN;
BEGIN

(* *************** DECLARATIONS COMPLETE *************************
*************** M..AIN PROGR.A.M BEGINS HERE ********************** *)
(* Get Library Name and Module to Delete *)
WRITE('Library Name: '); READLN(Lib_Name);
WRITE('Module Name:
'); READLN(Module Name);
(*Initialize lib for update access*)
status := LBR$INI_CONTROL
(lib_index_ptr,
~
IADDRESS(LBR$C UPDATE),
(*Update access*)
IADDRESS(LBR$C=TYP_TXT));
(*Text library*)
IF NOT ODD(status) THEN
(*Check error status*)
WRITELN('Initialization Failed')
ELSE
(*Initialization was successful*)
BEGIN
status := LBR$0PEN
(lib_index_ptr, (*Open the library*)
Lib_Name);
IF NOT ODD(status) THEN
(*Check error status*)
WRITELN('Open Not Successful')
ELSE
(*Open was successful*)
BEGIN
fj (*Is module in the library?*)
status := LBR$LOOKUP_KEY
(lib_index_ptr,
Module_Name,
txtrfa_ptr);
IF NOT ODD(status) THEN (*Check status*)
WRITELN('Lookup Key Not Successful')
END
END;
IF ODD(status) THEN
(*Key was found; delete it*)
BEGIN
status := LBR$DELETE_KEY
(lib_index_ptr,
Module_Name);
IF NOT ODD(status) THEN
WRITELN('Delete Key Routine Not Successful')
ELSE
(*Delete key was successful*)
BEGIN
(*Now delete module's data records*)
(lib_index_ptr,
~
status ·= LBR$DELETE_DATA
txtrfa_ptr);
IF NOT ODD(status) THEN
WRITELN('Delete Data Routine Not Successful')
END
END;
status := LBR$CLOSE(lib_index_ptr); (*Close the library*)
IF NOT ODD(status) THEN
WRITELN('Close Not Successful');
END. (*of program deletemod*)

•

LBR-18

Librarian {LBR) Routines
8.2 Using the LBR Routines: Examples

Each item in the following list corresponds to a number highlighted in
Example 8-4.

0 Call LBR$INl_CONTROL, specifying that the function to be performed
is update and the library type is text.

8 Call LBR$LOOKUP_KEY to find the key associated with the module
you want to delete.

8 Call LBR$DELETE_KEY to delete the key associated with the module
you want to delete. If more than one key points to the module, you
need to call LBR$LOOKUP_KEY and LBR$DELETE_KEY for each
key.

8 Call LBR$DELETE_DATA to delete the module (the module header
and data) from the library.

8.3

LBR Routines
The following pages describe the individual LBR routines.

LBR-19

Librarian {LBR) Routines

LBR$CLOSE

Close a Library
The LBR$CLOSE routine closes an open library.

FORMAT

LBR$CLOSE

RETURNS

VMS usage:
type:
access:
mechanism:

library_index

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

library_index
longword_unsigned
longword (unsigned)
read only
by reference
Library control index returned by the LBR$INl_CONTROL routine. The
library_index argument is the address of the longword that contains the
index.
VMS usage:
type:
access:
mechanism:

DESCRIPTION

CONDITION
VALUES
RETURNED

LBR-20

When you are finished working with a library, you should call
LBR$CLOSE to close it. Upon successful completion, LBR$CLOSE closes
the open library and deallocates all of the memory used for processing it.

LBR$_1LLCTL

Specified library control index not valid.

LBR$_LIBNOTOPN

Specified library not open.

Librarian {LBR) Routines
LBR$DELETE_DATA

LBR$DELETE_DATA

Delete a Module's Data

The LBR$DELETE_DATA routine deletes the module header and data
associated with the specified module.

FORMAT

LBR$DELETE_DATA

RETURNS

VMS usage:
type:
access:
mechanism:

library_index ,txtrfa

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

txtrfa
VMS usage: vector_longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference

Record's file address (RFA) of the module header for the module you want
to delete. The txtrfa argument is the address of the 2-longword array that
contains the RFA. You can obtain the RFA of a module header by calling
LBR$LOOKUP_exit KEY or LBR$PUT_RECORD.

DESCRIPTION

If you want to delete a library module, you must first call LBR$DELETE_
KEY to delete any keys that point to it. If no library index keys are

pointing at the module header, LBR$DELETE_DATA deletes the module
header and associated data records; otherwise, this routine returns the
error LBR$_STILLKEYS.
Note that other librarian routines may reuse data blocks that contain no
data.

LBR-21

Librarian (LBR) Routines
LBR$DELETE_DATA

CONDITION
VALUES
RETURNED

LBR-22

LBR$_1LLCTL

Specified library control index not valid.

LBR$_1NVRFA

Specified RFA not valid.

LBR$_LIBNOTOPN

Specified library not open.

LBR$_STILLKEYS

Keys in other indexes still point at the module header.
Therefore, the specified module was not deleted.

Librarian {LBR) Routines

LBR$DELETE_KEV

LBR$DELETE_KEY

Delete a Key

The LBR$DELETE_KEY routine deletes a key from a library index.

FORMAT

LBR$DELETE_KEY

RETURNS

VMS usage:
type:
access:
mechanism:

library_index ,key_name

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

key_name
longword_unsigned
longword (unsigned)
read only
by reference
Key to be deleted from the library index. For libraries with binary
keys, the key_name argument is the address of an unsigned longword
containing the key number.
VMS usage:
type:
access:
mechanism:

For libraries with ASCII keys, the key_name argument is the address
of the string descriptor pointing to the key with the following argument
characteristics.
Argument
Characteristics

Entry

VMS Usage

Char_string

Type

Character string

Access

Read only

Mechanism

By descriptor

LBR-23

Librarian {LBR) Routines

LBR$DELETE_KEY

DESCRIPTION

If LBR$DELETE_KEY finds .the key specified by key_name in the current
index, it deletes the key. Note that, if you want to delete a library module,
you should first use LBR$DELETE_KEY to delete any keys that point
to it, then use LBR$DELETE_DATA to delete the module's header and
associated data.

You cannot call LBR$DELETE_KEY from within the user-supplied routine
specified in LBR$SEARCH or LBR$GET_INDEX.

CONDITION
VALUES
RETURNED

LBR-24

LBR$_1LLCTL

Specified library control index not valid.

LBR$_KEYNOTFND

Specified key not found.

LBR$_LIBNOTOPN

Specified library not open.

LBR$_UPDURTRAV

Specified index update not valid in a user-supplied
routine specified in LBR$SEARCH or LBR$GET_
INDEX.

Librarian (LBR) Routines
LBR$FIND

LBR$FIND

Look Up a Module by Its RFA
The LBR$FIND routine sets the current internal read context for the library to
the library module specified.

FORMAT

LBR$FIND

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

library_index ,txtrfa

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

library_index
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
Library control index returned by the LBR$INI_CONTROL routine. The
library_index argument is the address of the longword that contains the
index.

txtrfa
VMS usage: vector_longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
RFA (record's file address) of the module header for the module you want
to access. The txtrfa argument is the address of a 2-longword array
containing the RFA. You can obtain the RFA of a module header by calling
LBR$LOOKUP_KEY or LBR$PUT_RECORD.

DESCRIPTION

You use the LBR$FIND routine to access a module that you had accessed
earlier in your program. For example, if you look up several keys with
LBR$LOOKUP_KEY, you can save the RFAs returned by LBR$LOOKUP_
KEY and later use LBR$FIND to reaccess the modules. Thus, you do not
have to look up the module header's key every time you want to access the
module. If the specified RFA is valid, LBR$FIND initializes internal tables
so that you can read the associated data.

LBR-25

Librarian (LBR) Routines
LBR$FIND

CONDITION
VALUES
RETURNED

LBR-26

LBR$_1LLCTL

Specified library control index not valid.

LBR$_1NVRFA

Specified RFA not valid.

LBR$_LIBNOTOPN

Specified library not open.

Librarian (LBR) Routines
LBR$FLUSH

LBR$FLUSH

Recover Virtual Memory
The LBR$FLUSH routine writes modified blocks back to the library file and
frees the virtual memory the blocks had been using.

FORMAT

LBR$FLUSH

RETURNS

VMS usage:
type:
access:
mechanism:

library_index ,block_type

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

block_type
longword_unsigned
longword (unsigned)
read only
by value
Extent of the flush operation. The block_type argument contains the
longword value that indicates how the flush operation proceeds. If you
specify LBR$C_FLUSHDATA, the data blocks are flushed. If you specify
LBR$C_FLUSHALL, first the data blocks and then the current library
index are flushed.
VMS usage:
type:
access:
mechanism:

The LBR$ symbols LBR$C_FLUSHDATA and LBR$C_FLUSHALL are
defined in the macro $LBRDEF (found in SYS$LIBRARY:STARLET.MLB),
which must be assembled and then linked with your program.

DESCRIPTION

LBR$FLUSH cannot be called from other librarian routines that reference
cache addresses or by routines called by librarian routines.

LBR-27

Librarian (LBR) Routines
LBR$FLUSH

CONDITION

VALUES
RETURNED

LBR-28

LBR$_NORMAL

Operation completed successfully.

LBR$_8ADPARAM

Error. A value passed to the LBR$FLUSH routine was
either out of range or an illegal value.

LBR$_WRITERR

Error. An error occurred during the writing of the
cached update blocks to the library file.

Librarian (LBR) Routines
LBR$GET_HEADER

LBR$GET_HEADER

Retrieve Library Header
Information

The LBR$GET_HEADER routine returns information from the library's header
to the caller.

FORMAT

LBR$GET_HEADER

RETURNS

VMS usage:
type:
access:
mechanism:

library_index ,retary

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

retary
VMS usage: vector_longword_unsigned
type:
longword (unsigned)
access:
write only
mechanism: by reference

Array of 128 longwords that receives the library header. The retary
argument is the address of the array that contains the header
information. The information returned in the array is listed in the
following table (the symbols are defined by the $LHIDEF macro in
SYS$LIBRARY:STARLET.MLB).
Offset in
Longwords

Symbolic Name

Contents

LHl$L_TYPE

Library type (see LBR$0PEN for possible
values)

LH1$L_NINDEX

Number of indexes

LHl$L_MAJORID

Library format major identification

LHl$L_MINORID

Library format minor identification

LBR-29

Librarian (LBR) Routines
LBR$GET_HEADER

Offset in
Longwords

Symbolic Name

Contents

LHl$T_LBRVER

ASCIC version of Librarian

LHl$L_CREDAT

Creation date/time

LHl$L_UPDTIM

Date/time of last update

LHl$L_UPDHIS

VBN of start of update history

LHl$L_FREEVBN

First logically deleted block

18
19

LHl$L_FREEBLK

Number of deleted blocks

LHl$8_NEXTRFA

Record's File Address (RFA) of end of
library

LHl$L_NEXTVBN

Next VBN to allocate at end of file

LHl$L_FREIDXBLK

Number of free preallocated index blocks

4
12
14
16

21
22
23
24
25
26
27

LHl$L_FREEIDX

Listhead for preallocated index blocks

LH1$L_HIPREAL

VBN of highest preallocated block

LHl$L_IDXBLKS

Number of index blocks in use

LH1$L_IDXCNT

Number of index entries (total)

LHl$L_MODCNT

Number of entries in index 1 (module
names)

LHl$L_MHDUSZ

Number of bytes of additional information
reserved in module header

LHl$L_MAXLUHREC

Maximum number of library update history
records maintained

LHl$L_NUMLUHREC

Number of library update history records in
history

LHl$L_LIBSTATUS

Library status (false if there was an error
closing the library)

32-128

DESCRIPTION

Reserved by Digital

On successful completion, LBR$GET_HEADER places the library header
information into the array of 128 longwords.
Note that the offset is the byte offset of the value into the header
structure. You can convert the offset to a longword subscript by
dividing the offset by 4 and adding 1 (assuming that subscripts in your
programming language begin with 1).

CONDITION
VALUES
RETURNED

LBR-30

LBR$_LIBNOTOPN

Specified library not open.

LBR$_1LLCTL

Specified library control index not valid.

Librarian (LBR) Routines
LBR$GET_HELP

LBR$GET_HELP

Retrieve Help Text

The LBR$GET_HELP routine retrieves help text from a help library, displaying
it on SYS$0UTPUT or calling your routine for each record returned.

FORMAT

LBR$GET_HELP

RETURNS

VMS usage:
type:
access:
mechanism:

library_index [,line_ width] [,routine]
[,data] [,key_ 1} [,key_2 ... ,key_ 10]

cond_value
longword {unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

library_index
VMS usage: longword_unsigned
type:
longword {unsigned)
access:
read only
mechanism: by reference
Library control index returned by the LBR$1Nl_CONTROL routine. The
library_index argument is the address of the longword that contains the
index.

line_width
VMS usage: longword_signed
type:
longword {signed)
access:
read only
mechanism: by reference
Width of the help text line. The line_width argument is the address of a
longword containing the width of the listing line. If you do not supply a
line width or if you specify 0, the line width defaults to 80 characters per
line.

routine
VMS usage: procedure
type:
procedure entry mask
access:
read only
mechanism: by reference
Routine called for each line of text you want output. The routine
argument is the address of the entry mask for this user-written routine.
If you do not supply a routine argument, LBR$GET_HELP calls the
Run-Time Library procedure LIB$PUT_OUTPUT to send the help text
lines to the current output device (SYS$0UTPUT). However, if you want
SYS$0UTPUT for your program to be a disk file rather than the terminal,
you should supply a routine to output the text.

LBR-31

Librarian (LBR) Routines
LBR$GET_HELP

The routine you specify is called with an argument list of four longwords:
1

The first argument is the address of a string descriptor for the output
line.

The second argument is the address of an unsigned longword
containing flag bits that describe the contents of the text being passed.
The possible flags are as follows:
HLP$M_NOHLPTXT

Specified help text cannot be found.

HLP$M_KEYNAMLIN

Text contains key names of the printed text.

HLP$M_OTHERINFO

Text is part of the information provided on additional
help available.

(The $HLPDEF macro in SYS$LIBRARY:STARLET.MLB defines these
flag symbols.)
Note that, if no flag bit is set, help text is passed.
3

The third argument is the address stipulated in the data argument
specified in the call to LBR$GET_HELP (or the address of a 0 constant
if the data argument is zero or was omitted).

The fourth argument is a longword containing the current key level.

The routine you specify must return with success or failure status. A
failure status (low bit = 0) terminates the current call to LBR$GET_HELP.

data
VMS usage: longword_unsigned
longword (unsigned)
access:
write only
mechanism: by reference
Data passed to the routine specified in the routine argument. The data
argument is the address of data for the routine. The address is passed to
the routine specified in the routine argument. If you omit this argument
or specify it as zero, then the argument passed in your routine will be the
address of a zero constant.

type:

key_1,key_2, ... ,key_10
VMS usage: longword_signed
longword (signed)
access:
read only
mechanism: by descriptor
Level of the help text to be output. Each key_l,key_2, ••• ,key_lO
argument is the address of a descriptor pointing to the key for that level.

type:

If the key_l descriptor is 0 or if it is not present, LBR$GET_HELP
assumes that the key_1 name is HELP, and it ignores all the other keys.
For key_2 through key_10, a descriptor address of 0, or a length of 0, or a
string address of 0 terminates the list.

LBR-32

Librarian (LBR) Routines
LBR$GET_HELP

The key argument may contain any of the following special character
strings:

DESCRIPTION

String

Meaning

Return all level 1 help text in the library.

KEY ...

Return all help text associated with the specified key and its subkeys
(valid for level 1 keys only).

Return all help text in the library.

LBR$GET_HELP returns all help text in the same format as the output
returned by the DCL command HELP; that is, it indents two spaces for
every key level of text displayed. (Because of this formatting, you may
want to make your help messages shorter than 80 characters, so they fit
on one line on terminal screens with the width set to 80.) If you do not
want the help text indented to the appropriate help level, you must supply
your own routine to change the format.
Note that most application programs use LBR$0UTPUT_HELP instead of
LBR$GET_HELP.

CONDITION
VALUES
RETURNED

LBR$_1LLCTL

Specified library control index not valid.

LBR$_LIBNOTOPN

Specified library not open.

LBR$_NOTHLPLIB

Specified library not a help library.

LBR-33

Librarian {LBR) Routines
LBR$GET_HISTORY

LBR$GET_HISTORY

Retrieve a Library Update
History Record

The LBR$GET_HISTORY routine returns each library update history record to
a user-specified action routine.

FORMAT

LBR$GET HISTORY

RETURNS

VMS usage:
type:
access:
mechanism:

library_index ,action_routine

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

action_routine
VMS usage: procedure
type:
procedure entry mask
access:
modify
mechanism: by reference
User-supplied routine for processing library update history records. The
action_routine argument is the address of the entry mask of this usersupplied routine. The routine is invoked once for each update history
record in the library. One argument is passed to the routine, namely, the
address of a descriptor pointing to a history record.

DESCRIPTION

LBR-34

This routine retrieves the library update history records written by the
routine LBR$PUT_HISTORY.

Librarian (LBR) Routines
LBR$GET_HISTORV

CONDITION
VALUES
RETURNED

LBR$_NORMAL

Normal exit from the routine.

LBR$_EMPTYHIST

History empty. This is an informational code, not an
error code.

LBR$_NOHISTORY

No update history. This is an informational code, not
an error code.

LBR$_1NTRNLERR

Internal librarian routine error occurred.

LBR-35

Librarian (LBR) Routines
LBR$GET_INDEX

LBR$GET_INDEX

Call a Routine for Selected Index
Keys

The LBR$GET_INDEX routine calls a user-supplied routine for selected keys
in an index.

FORMAT

LBR$GET_INDEX

RETURNS

VMS usage:
type:
access:
mechanism:

library_index ,index_number
,routine_name [,match_desc]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

index_number
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
Number of the library index. The index_number argument is the address
of a longword containing the index number. This is the index number
associated with the keys you want to use as input to the user-supplied
routine (see Section 8.1.2.3).

routine_name
VMS usage: procedure
type:
procedure entry mask
access:
read only
mechanism: by reference
User-supplied routine called for each of the specified index keys. The
routine_name argument is the address of the entry mask for this usersupplied routine.

LBR-36

Librarian (LBR) Routines
LBR$GET_INDEX

LBR$GET_INDEX passes two arguments to the routine:
•

•

Akey name.
-

For libraries with ASCII keys, the key_name argument is the
address of a string descriptor pointing to the key. Note that the
string and the string descriptor passed to the routine are valid only
for the duration of that call. The string must be privately copied if
you need it again for more processing.

For libraries with binary keys, the key_name argument is the
address of an unsigned longword containing the key number.

The record's file address (RFA) of the module's header for this key
name. The RFA argument is the address of a 2-longword array that
contains the RFA.

The routine must return a value to indicate success or failure. If the
routine returns a false value (low bit= 0), LBR$GET_INDEX stops
searching the index and returns the status value of the user-specified
routine to the calling program.
The routine cannot contain calls to either LBR$DELETE_KEY or
LBR$INSERT_KEY.

match_desc
VMS usage: char_string
character string
access:
read only
mechanism: by descriptor
Key matching identifier. The match_desc argument is the address of a
string descriptor pointing to a string used to identify which keys result in
calls to the user-supplied routine. Wildcard characters are allowed in this
string. If you omit this argument, the routine is called for every key in
the index. The match_desc argument is valid only for libraries that have
ASCII keys.
type:

DESCRIPTION

LBR$GET_INDEX searches through the specified index for a key that
matches the argument match_desc. Each time it finds a match, it calls
the routine specified by the routine_name argument. If you do not
specify the match_desc argument, it calls the routine for every key in the
index.
For example, if you call LBR$GET_INDEX with match_desc equal to TR*
and index_number set to 1 (module name table), then LBR$GET_INDEX
calls routine_name for each module whose name begins with TR.

CONDITION
VALUES
RETURNED

LBR$_1LLCTL

Specified library control index not valid.

LBR$_1LLIDXNUM

Specified index number not valid.

LBR$_LIBNOTOPN

Specified library not open.

LBR$_NULIDX

Specified library empty.

LBR-37

Librarian (LBR) Routines
LBR$GET_RECORD

LBR$GET_RECORD

Read a Data Record

The LBR$GET_RECORD routine returns the next data record in the module
associated with a specified key.

FORMAT

LBR$GET_RECORD

RETURNS

VMS usage:
type:
access:
mechanism:

library_index [,inbufdes]
[,outbufdes]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

library_index
longword_unsigned
longword (unsigned)
read only
by reference
Library control index returned by the LBR$INI_CONTROL routine. The
library_index argument is the address of the longword that contains the
index. The library must be open and LBR$LOOKUP_KEY or LBR$FIND
must have been called to find the key associated with the module whose
records you want to read.
VMS usage:
type:
access:
mechanism:

inbufdes
char_string
character string
write only
by descriptor
User buffer to receive the record. The inbufdes argument is the address
of a string descriptor that points to the buffer that receives the record
from LBR$GET_RECORD. This argument is required when the librarian
subroutine record access is set to move mode (which is the default). This
argument is not used if the record access mode is set to locate mode. The
DESCRIPTION section contains more information about the locate and
move modes.

VMS usage:
type:
access:
mechanism:

outbufdes
char_string
character string
write only
by descriptor
String descriptor that receives the actual length and address of the data
for the record returned. The outbufdes argument is the address of the

VMS usage:
type:
access:
mechanism:

LBR-38

Librarian (LBR) Routines
LBR$GET_RECORD

string descriptor for the returned record. The length and address fields
of the string descriptor are filled in by the LBR$GET_RECORD routine.
This parameter must be specified when Librarian subroutine record access
is set to locate mode. This parameter is optional if record access mode is
set to move mode. The DESCRIPTION section contains more information
about the locate and move modes.

DESCRIPTION

Before calling LBR$GET_RECORD, you must first call LBR$LOOKUP_
KEY or LBR$FIND to set the internal library read context to the record's
file address (RFA) of the module header of the module whose records you
want to read.
LBR$GET_RECORD uses two record access modes: locate mode and
move mode. Move mode is the default. The LBR$SET_LOCATE and
LBR$SET_MOVE subroutines set these modes. The record access modes
are mutually exclusive; that is, when one is set the other is turned off.
If move mode is set, LBR$GET_RECORD copies the record to the userspecified buffer described by inbufdes. If you have optionally specified the
output buffer string descriptor, outbufdes, the librarian fills it with the
actual length and address of the data. Iflocate mode is set, LBR$GET_
RECORD returns the record by way of an ·internal subroutine buffer,
pointing the outbufdes descriptor to the internal buffer. The second
parameter, inbufdes, is not used when locate mode is set.

CONDITION
VALUES
RETURNED

LBR$_1LLCTL

Specified library control index not valid.

LBR$_LIBNOTOPN

Specified library not open.

LBR$_LKPNOTDON

Requested key lookup not done.

RMS$_EOF

Error. An attempt has been made to read past the
logical end of the data in the module.

LBR-39

Librarian (LBR) Routines
LBR$1Nl_CONTROL

LBR$1Nl_CONTROL Initialize a Library Control
Structure
The LBR$1Nl_CONTROL routine initializes a control structure, called a library
control index, to identify the library for use by other Librarian routines.

FORMAT

LBR$1Nl_CONTROL

RETURNS

VMS usage:
type:
access:
mechanism:

library_index ,tune £type]
£namblk]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

library_index
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
write only
mechanism: by reference

Library control index returned by the LBR$INI_CONTROL routine. The
library_index argument is the address of a longword that is to receive
the index.

tune
longword_unsigned
longword (unsigned)
read only
by reference
Library function to be performed. The func argument is the address
of the longword that contains the library function. Valid functions are
LBR$C_CREATE, LBR$C_READ, and LBR$C_UPDATE. (These symbols
are defined by the $LBRDEF macro in SYS$LIBRARY:STARLET.MLB.)

VMS usage:
type:
access:
mechanism:

type
longword_unsigned
longword (unsigned)
read only
by reference
Library type. The type argument is the address of the longword
containing the library type. Valid library types are LBR$C_TYP_OBJ
(object or shareable image), LBR$C_TYP_MLB (macro), LBR$C_TYP_
HLP (help), LBR$C_TYP_TXT (text), LBR$C_TYP_UNK (unknown), or,

VMS usage:
type:
access:
mechanism:

LBR-40

Librarian (LBR) Routines
LBR$1Nl_CONTROL

for user-developed libraries, a type in the range of LBR$C_TYP_USRLW
through LBR$C_TYP_USRHI.

namblk
VMS usage: nam
type:

longword (unsigned)

access:
read only
mechanism: by reference
VMS RMS name block (NAM). The namblk argument is the address of
a variable-length data structure containing an RMS NAM block. The
LBR$0PEN routine fills in the information in the NAM block so that
it can be used later to open the library. If the NAM block has this file
identification in it from previous use, the LBR$0PEN routine uses the
VMS RMS open-by-NAM block option. This argument is optional and
should be used if the library will be opened many times during a single
run of the program. For a detailed description of VMS RMS NAM blocks,
see the VMS Record Management Services Manual.

DESCRIPTION

Except for the LBR$0UTPUT_HELP routine, you must call LBR$INI_
CONTROL before calling any other librarian routine. After you initialize
the library control index, you must open the library or create a new one
using the LBR$0PEN routine. You can then call other librarian routines
that you need. After you finish working with a library, close it with the
LBR$CLOSE routine.
LBR$1Nl_CONTROL initializes a library by filling the longword referenced
by the library_index argument with the control index of the library.
Upon completion of the call, the index can be used to refer to the current
library in all future routine calls. Therefore, your program must not alter
this value.
You can have up to 16 libraries open simultaneously in your program.

CONDITION
VALUES
RETURNED

LBR$_NORMAL

Library control index initialized successfully.

LBR$_1LLFUNC

Requested function not valid.

LBR$_1LLTYP

Specified library type not valid.

LBR$_TOOMNYLIB

Error. An attempt was made to allocate more than 16
control indexes.

LBR-41

Librarian {LBR) Routines
LBR$1NSERT_KEV

LBR$1NSERT_KEY

Insert a New Key

The LBR$1NSERT_KEY routine inserts a new key in the current library index.

FORMAT

LBR$1NSERT_KEY

RETURNS

VMS usage:
type:
access:
mechanism:

library_index ,key_name ,txtrfa

cond_value
longword (unsigned)
write oniy
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

key_name
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
Name of the new key you are inserting.
If the library uses binary keys, the key_name argument is the address of

an unsigned longword containing the value of the key.
If the library uses ASCII keys, the key_name argument is the address of

a string descriptor of the key with the following argument characteristics.

LBR-42

Argument
Characteristics

Entry

VMS Usage

Char_string

Type

Character string

Access

Read only

Mechanism

By descriptor

Librarian {LBR) Routines
LBR$1NSERT_KEY

txtrfa
VMS usage: vector_longword_unsigned
longword (unsigned)
access:
modify
mechanism: by reference
Record file address (RFA) of the module associated with the new key you
are inserting. The txtrfa argument is the address of a 2-longword array
containing the RFA. You can use the RFA returned by the first call to
LBR$PUT_RECORD.
type:

DESCRIPTION

CONDITION
VALUES
RETURNED

You cannot call LBR$INSERT_KEY within the user-supplied routine
specified in LBR$SEARCH or LBR$GET_INDEX.

LBR$_1LLCTL

Specified library control index not valid.

LBR$_1NVRFA

Specified RFA does not point to valid data.

LBR$_DUPKEY

Index already contains the specified key.

LBR$_LIBNOTOPN

Specified library not open.

LBR$_UPDURTRAV

LBR$1NSERT_KEY was called by the user-defined
routine specified in LBR$SEARCH or LBR$GET_
INDEX.

LBR-43

Librarian (LBR) Routines
LBR$LOOKUP_KEY

LBR$LOOKUP_KEY

Look Up a Library Key

The LBR$LOOKUP_KEY routine looks up a key in the library's current index
and prepares to access the data in the module associated with the key.

FORMAT

LBR$LOOKUP_KEY

RETURNS

VMS usage:
type:
access:
mechanism:

library_index ,key_name ,txtrfa

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

key_name
longword_unsigned
longword (unsigned)
read only
by reference
Name of the library key. If the library uses binary keys, the key_name
argument is the address of the unsigned longword value of the key.

VMS usage:
type:
access:
mechanism:

If the library uses ASCII keys, the key_name argument is the address of

a string descriptor for the key with the following argument characteristics.

LBR-44

Argument Characteristics

Entry

VMS Usage

Char_string

Type

Character string

Access

Read only

Mechanism

By descriptor

Librarian (LBR) Routines
LBR$LOOKUP_KEY

txtrfa
VMS usage: vector_longword_unsigned
type:
longword (unsigned)
access:
write only
mechanism: by reference
The record's file address (RFA) of the library module header. The txtrfa
argument is the address of the 2-longword array that receives the RFA of
the module header.

DESCRIPTION

If LBR$LOOKUP_KEY finds the specified key, it initializes internal tables
so that you can access the associated data.

This routine returns the RFA (consisting of the virtual block number
(VBN) and the byte offset) to the 2-longword array referenced by txtrfa.
Note that the RFA is only 6 bytes long.

CONDITION
VALUES
RETURNED

LBR$_1LLCTL

Specified library control index not valid.

LBR$_1NVRFA

RFA obtained not valid.

LBR$_KEYNOTFND

Specified key not found.

LBR$_LIBNOTOPN

Specified library not open.

LBR-45

Librarian {LBR) Routines
LBR$0PEN

LBR$0PEN

Open or Create a Library
The LBR$0PEN routine opens an existing library or creates a new one.

FORMAT

LBR$0PEN library_index [,fns] [,create_ options] [,dns]
[,rlfna] [,rns] [,rnslen]

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

library_index
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference

Library control index returned by the LBR$INI_CONTROL routine. The
library_index argument is the address of a longword containing the
index.

fns
char_string
character string
read only
by descriptor
File specification of the library. The fns argument is the address of a
string descriptor pointing to the file specification. Unless the VMS RMS
NAM block address was previously supplied in the LBR$INl_CONTROL
routine and contained a file specification, this argument must be included.
Otherwise, the librarian returns an error (LBR$_NOFILNAM).

VMS usage:
type:
access:
mechanism:

create_ options
vector_longword_unsigned
longword (unsigned)
read only
by reference
Library characteristics. The create_options argument is the address
of an array of 20 longwords that define the characteristics of the library
you are creating. If you are creating a library with LBR$C_CREATE, you
must include the create-options argument. The following table shows
the entries that the array must contain (the $LBRDEF and $CREDEF
macros in SYS$LIBRARY:STARLET.MLB define the symbols listed).

VMS usage:
type:
access:
mechanism:

LBR-46

Librarian (LBR) Routines
LBR$0PEN

Offset in
Longwords

Symbolic Name

Contents

CRE$L_TYPE

Library type:

LBR$C_TYP_UNK (0)

Unknown/unspecified

LBR$C_TYP_OBJ(1)

Object and/or shareable image

LBR$C_TYP_MLB (2)

Macro

LBR$C_TYP_HLP(3)

Help

LBR$C_TYP_TXT(4)

Text

(5-127)

Reserved by Digital

LBR$C_TYP_USR (128-255)

User-defined

CRE$L_KEYLEN

Maximum length of ASCII keys
or, if 0, indicates 32-bit unsigned
keys (binary keys)

CRE$L_ALLOC

Initial library file allocation

CRE$L_IDXMAX

Number of library indexes
(maximum of 8)

CRE$L_UHDMAX

Number of additional bytes to
reserve in module header

CRE$L_ENTALL

Number of index entries to
preallocate

CRE$L_LUHMAX

Maximum number of library
update history records to
maintain

CRE$L_VERTYP

Format of library to create:

CRE$C_VMSV2

VMS Version 2.0

CRE$C_VMSV3

VMS Version 3.0

9-20

CRE$l_IDXOPT

Index key casing option:

CRE$C_HLPCASING

Treat character case as it is for
help libraries

CRE$C_OBJCASING

Treat character case as it is for
object libraries

CRE$C_MACTXTCAS

Treat character case as it is for
macro and text libraries
Reserved by Digital

The input of uppercase and lowercase characters is treated differently for
help, object, macro, and text libraries. For details, see the VMS Librarian
Utility Manual.

dns
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Default file specification. The dns argument is the address of the string
descriptor that points to the default file specification. See the VMS Record
Management Services Manual for details about how defaults are processed.
LBR-47

Librarian (LBR) Routines
LBR$0PEN

rlfna
VMS usage: longword_unsigned
longword (unsigned)
access:
read only
mechanism: by reference
Related file name. The rlfna argument is the address of a VMS RMS
NAM block pointing to the related file name. If you do not specify rlfna,
no related file name processing occurs. If a related file name is specified,
only the file name, type, and version fields of the NAM block are used
for related name block processing. The device and directory fields are not
used. See the VMS Record Management Services Manual for details on
processing related ft.le names.
type:

rns
VMS usage: char_string
type:
character string
access:
write only
mechanism: by descriptor
Resultant file specification returned. The rns argument is the address
of a string descriptor pointing to a buffer that is to receive the resultant
file specification string. If an error occurs during an attempt to open the
library, the expanded name string is returned instead.

rnslen
VMS usage: longword_signed
type:
longword (signed)
access:
write only
mechanism: by reference
Length of the resultant or expanded file name. The rnslen argument
is the address of a longword receiving the length of the resultant file
specification string (or the length of the expanded name string if there was
an error in opening the library).

DESCRIPTION

You can call this routine only after you call LBR$INI_CONTROL and
before you call any other librarian routine except LBR$0UTPUT_HELP.
When the library is successfully opened, the librarian routine reads the
library header into memory and sets the default index to 1.
If the library cannot be opened because it is already open for a write
operation, LBR$0PEN retries the open operation every second for a
maximum of 30 seconds before returning the VMS RMS error, RMS$_FLK,
to the caller.

LBR-48

Librarian {LBR) Routines
LBR$0PEN

CONDITION
VALUES
RETURNED

LBR$_OLDLIBRARY

Success. The specified library has been opened; the
library was created with an old library format.

LBR$_ERRCLOSE

Error. When the library was last modified while
opened for write access, the write operation was
interrupted. This left the library in an inconsistent
state.

LBR$_1LLCREOPT

Requested create options not valid or not supplied.

LBR$_1LLCTL

Specified library control index not valid.

LBR$_1LLFMT

Specified library format not valid.

LBR$_1LLFUNC

Specified library function not valid.

LBR$_LIBOPN

Specified library already open.

LBR$_NOFILNAM

Error. The fns argument was not supplied or the VAX
RMS NAM block was not filled in.

LBR$_0LDMISMCH

Requested library function conflicts with old library
type specified.

LBR$_TYPMISMCH

Library type does not match the requested type.

LBR-49

Librarian (LBR) Routines
LBR$0UTPUT_HELP

LBR$0UTPUT_HELP Output Help Messages
The LBR$0UTPUT_HELP routine outputs help text to a user-supplied
output routine. The text is obtained from an explicitly named help library
or, optionally, from user-specified default help libraries. An optional prompting
mode is available that enables LBR$0UTPUT_HELP to interact with you and
continue to provide help information after the initial help request has been
satisfied.

---···t'Ut1MAI

LBR$0UTPUT_HELP

RETURNS

VMS usage:
type:
access:
mechanism:

output_routine j,output_widthj
[,line_desc] [,library_name]
[,flags] [,input_routine]

cond_value
longword {unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

output_ routine
VMS usage: procedure
type:
procedure entry mask
access:
write only
mechanism: by reference

Name of a routine that writes help text a line at a time. The output_
routine argument is the address of the entry mask of the routine to call.
You should specify either the address of LIB$PUT_OUTPUT or a routine
of your own that has the same calling format as LIB$PUT_OUTPUT.

output_ width
VMS usage:
type:
access:
mechanism:

longword_signed
longword (signed)
read only
by reference

Width of the help-text line to be passed to the user-supplied output
routine. The output_width argument is the address of a longword
containing the width of the text line to be passed to the user-supplied
output routine. If you omit output_width or specify it as 0, the default
output width is 80 characters per line.

LBR-50

Librarian {LBR) Routines
LBR$0UTPUT_HELP

line desc
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Contents of the help request line. The line_desc argument is the address
of a string descriptor pointing to a character string containing one or more
help keys defining the help requested, for example, the HELP command
line minus the HELP command and HELP command qualifiers. The
default is a string descriptor for an empty string.

library_name
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Name of the main library. The library_name argument is the address
of a string descriptor pointing to the main library file specification string.
The default is a null string, which means you should use the default help
libraries. If you omit the device and directory specifications, the default is
SYS$HELP. The default file type is HLB.

flags
VMS usage: mask_longword
type:
longword {unsigned)
access:
read only
mechanism: by reference
Flags specifying help output options. The flags argument is the address of
an unsigned longword that contains the following flags.
Flag

Description

HLP$M_PROMPT

When set, interactive help prompting is in effect.

HLP$M_PROCESS

When set, the process logical name table is searched for
default help libraries.

HLP$M_GROUP

When set, the group logical name table is searched for group
default help libraries.

HLP$M_SYSTEM

When set, the system logical name table is searched for
system default help libraries.

HLP$M_LIBLIST

When set, the list of default libraries available is output with the
list of topics available.

HLP$M_HELP

When set, the list of topics available in a help library is
preceded by the major portion of the text on HELP.

(The $HLPDEF macro in SYS$LIBRARY:STARLET.MLB defines these flag
symbols.)
If you omit this longword, the default is for prompting and all default
library searching to be enabled, but no library list will be generated and
no help text will precede the list of topics.

LBR-51

Librarian (LBR) Routines
LBR$0UTPUT_HELP

input_ routine
VMS usage:
type:
access:
mechanism:

procedure
procedure entry mask
read only
by reference

Routine used for prompting. The input_routine argument is the address
of the entry mask of the prompting routine. You should specify either the
address of LIB$GET_INPUT or a routine of your own that has the same
calling format as LIB$GET_INPUT. This argument must be supplied when
the HELP command is run in prompting mode (that is, HLP$M_PROMPT
is set or defaulted).

DESCRIPTION

The LBR$0UTPUT_HELP routine provides a simple, one-call method to
initiate an interactive help session. Help library bookkeeping functions,
such as LBR$INI_CONTROL and LBR$0PEN, are handled internally.
You should not call LBR$INI_CONTROL or LBR$0PEN before you issue a
call to LBR$0UTPUT_HELP.
LBR$0UTPUT_HELP accepts help keys in the same format as LBR$GET_
HELP, with the following qualifications:
•

If the keyword HELP is supplied, help text on HELP is output,
followed by a list of HELP subtopics available.
If no help keys are provided or ifthe line_desc argument is 0, a list of

topics available in the root library is output.
•

If the line_desc argument contains a list of help keys, then each key

must be separated from its predecessor by a slash (I) or by one or
more spaces.
•

The first key can specify a library to replace the main library as the
root library (the first library searched) in which LBR$0UTPUT_HELP
searches for help. A key used for this purpose must have the form
<@filespec>, where filespec is subject to the same restrictions as the
library_name argument. If the specified library is an enabled userdefined default library, then filespec can be abbreviated as any unique
substring of that default library's logical name translation.

In default library searches, you can define one or more default libraries
for LBR$0UTPUT_HELP to search for help information not contained in
the root library. You do this by equating logical names (HLP$LIBRARY,
HLP$LIBRARY_l, ... ,HLP$LIBRARY_999) to the file specifications
of the default help libraries. You can define these logical names in the
process, group, or system logical name table.
If default library searching is enabled by the flags argument,

LBR$0UTPUT_HELP uses those flags to determine which logical name
tables are enabled and then automatically searches any user default
libraries that have been defined in those logical name tables. The library
search order proceeds as follows: root library, main library (if specified
and different from the root library), process libraries (if enabled), group
libraries (if enabled), system libraries (if enabled). If the requested help
information is not found in any of these libraries, LBR$0UTPUT_HELP
returns to the root library and issues a "help not found" message.
LBR-52

Librarian (LBR) Routines
LBR$0UTPUT_HELP

To enter an interactive help session (after your initial request for help
has been satisfied), you must set the HLP$M_PROMPT bit in the flags
argument.
You can encounter four different types of prompt in an interactive help
session. Each type represents a different level in the hierarchy of help
available to you:
1

If the root library is the main library and you are not currently
examining HELP for a particular topic, the prompt Topic? is output.

If the root library is a library other than the main library and if you
are not currently examining HELP for a particular topic, a prompt of
the form @<library-spec>Topic? is output.

If you are currently examining HELP for a particular topic (and
subtopics), a prompt of the form <keyword... >subtopic? is output.

A combination of 2 and 3.

When you encounter one of these prompt messages, you can respond
in any one of several ways. Each type of response and its effect on
LBR$0UTPUT_HELP in each prompting situation is described in the
following table.
Response

Action in the Current Prompt Environment1

keyword [ ... ]

( 1,2) Search all enabled libraries for these keys.
( 3,4) Search additional help for the current topic (and
subtopic) for these keys.

@filespec [keyword[ ... ]]

( 1,2) Same as above, except that the root library is
the library specified by filespec. If the specified library
does not exist, treat @filespec as a normal key.
( 3,4) Same as above; treat @filespec as a normal
key.

( 1,2) Display a list of topics available in the root
library.
( 3,4) Display a list of subtopics of the current topic
(and subtopics) for which help exists.

Carriage Return

( 1 ) Exit from LBR$0UTPUT_HELP.
( 2) Change root library to main library.
( 3,4) Strip the last keyword from a list of keys defining
the current topic (and subtopic) environment.

CTRUZ

(1,2,3,4) Exit from LBR$0UTPUT_HELP.

1 Keyed to the prompt in the preceding list.

LBR-53

Librarian (LBR) Routines
LBR$0UTPUT_HELP

CONDITION
VALUES
RETURNED

LBR-54

LBR$_1LLINROU

Input routine improperly specified or omitted.

LBR$_1LLOUTROU

Output routine improperly specified or omitted.

LBR$_NOHLPLIS

Error. No default help libraries can be opened.

LBR$_TOOMNYARG

Error. Too many arguments were specified.

LBR$_USRINPERR

Error. An error status was returned by the usersupplied input routine.

Librarian {LBR) Routines

LBR$PUT_END

LBR$PUT_END Write an End-of-Module Record
The LBR$PUT_END routine marks the end of a sequence of records written
to a library by the LBR$PUT_RECORD routine.

FORMAT

LBR$PUT_END

RETURNS

VMS usage:
type:
access:
mechanism:

library_index

cond_value
longword (unsigned}
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

library_index
VMS usage: longword_unsigned
type:
longword (unsigned}
access:
read only
mechanism: by reference

Library control index returned by the LBR$INI_CONTROL routine. The
library_index argument is the address of a longword containing the
index.

DESCRIPTION

CONDITION
VALUES
RETURNED

Call LBR$PUT_END after you write data records to the library with the
LBR$PUT_RECORD routine. LBR$PUT_END terminates a module by
attaching a 3-byte logical end-of-file record (hexadecimal 77 ,00, 77) to the
data.

LBR$_1LLCTL

Specified library control index not valid.

LBR$_LIBNOTOPN

Specified library not open.

LBR-55

Librarian {LBR) Routines
LBR$PUT_HISTORY

LBR$PUT_HISTORY Write an Update History
Record
The LBR$PUT_HISTORY routine adds an update history record to the end of
the update history list.

FORMAT

LBR$PUT_HISTORY

RETURNS

VMS usage:
type:
access:
mechanism:

library_index ,record_desc

cond_value
longword {unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

library_index
longword_unsigned
longword {unsigned)
read only
by reference
Library control index returned by the LBR$INI_CONTROL routine. The
library_index argument is the address of the longword that contains the
index.
VMS usage:
type:
access:
mechanism:

record_desc
char_string
character string
read only
by descriptor
Library history record. The record_desc argument is the address of a
string descriptor pointing to the record to be added to the library update
history.

VMS usage:
type:
access:
mechanism:

DESCRIPTION

LBR-56

LBR$PUT_HISTORY writes a new update history record. If the library
already contains the maximum number of history records (as specified at
creation time by CRE$L_LUHMAX, see LBR$0PEN for details), the oldest
history record is deleted before the new record is added.

Librarian (LBR) Routines
LBR$PUT_HISTORV

CONDITION
VALUES
RETURNED

LBR$_NORMAL

Normal exit from the routine.

LBR$_NOHISTORY

No update history. This is an informational code, not
an error code.

LBR$_1NTRNLERR

Internal librarian error.

LBR$_RECLNG

Record length greater than that specified by LBR$C_
MAXRECSIZ. The record was not inserted or
truncated.

LBR-57

Librarian (LBR). Routines
LBR$PUT_RECORD

LBR$PUT_RECORD

Write a Data Record

The LBR$PUT_RECORD routine writes a data record beginning at the next
free location in the library.

FORMAT

LBR$PUT_RECORD

RETURNS

VMS usage:
type:
access:
mechanism:

library_incjex ,bufdes ,txtrfa

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

library_index
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
Library control index returned by the LBR$INl_CONTROL routine. The
library_index argument is the address of the longword that contains the
index.

bufdes
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Record to be written to the library. The bufdes argument is the address
of a string descriptor pointing to the buffer containing the output record.

txtrfa
VMS usage: vector_longword_unsigned
type:
longword (unsigned)
access:
write only
mechanism: by reference
Record's file address (RFA) of the module header. The txtrfa argument is
the address of a 2-longword array receiving the RFA of the newly created
module header upon the first call to LBR$PUT_RECORD.

LBR-58

Librarian {LBR) Routines
LBR$PUT_RECORD

DESCRIPTION

If this is the first call to LBR$PUT_RECORD, this routine first writes a

module header and returns its RFA to the 2-longword array pointed to by

txtrfa. LBR$PUT_RECORD then writes the supplied data record to the
library. On subsequent calls to LBR$PUT_RECORD, this routine writes
the data record beginning at the next free location in the library (after the
previous record). The last record written for the module should be followed
by a call to LBR$PUT_END.

CONDITION
VALUES
RETURNED

LBR$_1LLCTL

Specified library control index not valid.

LBR$_LIBNOTOPN

Specified library not open.

LBR-59

Librarian (LBR) Routines

LBR$REPLACE_KEY

Replace a Library Key

The LBR$REPLACE_KEY routine inserts a key in an index by changing the
pointer associated with an existing key or by inserting a new key.

FORMAT

LBR$REPLACE_KEY

RETURNS

VMS usage:
type:
access:
mechanism:

library_index ,key_name ,oldrfa
,newrfa

cond_value
longword {unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

key_name
char_string
character string
read only
by descriptor
Library key (for libraries with ASCII keys). The key_name argument is
the address of a string descriptor for the key.

VMS usage:
type:
access:
mechanism:

key_name
longword_unsigned
longword {unsigned)
read only
by reference
Library key (for libraries with binary keys). The key_name argument is
the address of an unsigned longword value for the key.

VMS usage:
type:
access:
mechanism:

oldrfa
VMS usage:
type:
access:
mechanism:

LBR-60

vector_longword_unsigned
longword {unsigned)
read only
by reference

Librarian {LBR) Routines

LBR$REPLACE_KEV
Old RFA. The oldrfa argument is the address of a 2-longword array
containing the original RFA (returned by LBR$LOOKUP_KEY) of the
module header associated with the key you are replacing.

newrfa
VMS usage: vector_longword_unsigned
type:

longword {unsigned)

access:
read only
mechanism: by reference
New RFA. The newrfa argument is the address of a 2-longword array
containing the RFA (returned by LBR$PUT_RECORD) of the module
header associated with the new key.

DESCRIPTION

CONDITION
VALUES
RETURNED

IfLBR$REPLACE_KEY does not find the key in the current index, it calls
the LBR$1NSERT_KEY routine to insert the key. If LBR$REPLACE_KEY
does find the key, it modifies the key entry in the index so that it points to
the new module header.

LBR$_1LLCTL

Specified library control index not valid.

LBR$_LIBNOTOPN

Specified library not open.

LBR$_1NVRFA

Specified RFA not valid.

LBR-61

Librarian (LBR) Routines
LBR$RET_RMSSTV

LBR$RET_RMSSTV

Return VMS RMS Status Value

The LBR$RET_RMSSTV routine returns the status value of the last VMS
Record Management Services (RMS) function performed by any librarian
subroutine.

FORMAT

LBR$RET_RMSSTV

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

None.

DESCRIPTION

The LBR$RET_RMSSTV routine returns, as the status value, the status of
the last RMS operation performed by the librarian. RMS status codes are
defined by the $RMSDEF macro in SYS$LIBRARY:STARLET.MLB.

CONDITION
VALUES
RETURNED

This routine returns any condition values returned by VMS RMS routines.

LBR-62

Librarian (LBR) Routines
LBR$SEARCH

LBR$SEARCH

Search an Index

The LBR$SEARCH routine finds index keys that point to specified data.

FORMAT

LBR$SEARCH

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

library_index ,index_number
,rfa_to_find ,routine_name

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

library_index
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Library control index returned by the LBR$INI_CONTROL routine. The
library_index argument is the address of the longword that contains the
index.

index_ number
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
Library index number. The index_number argument is the address of
a longword containing the number of the index you want to search (see
Section 8.1.2.3).

rfa_to_find
VMS usage:
type:
access:
mechanism:

vector_longword_unsigned
longword (unsigned)
write only
by reference

Record's file address (RFA) of the module whose keys you are searching for.
The rfa_to_find argument is the address of a 2-longword array containing
the RFA (returned earlier by LBR$LOOKUP_KEY or LBR$PUT_
RECORD) of the module header.

LBR-63

Librarian (LBR) Routines

LBR$SEARCH
routine_name
VMS usage: procedure
type:
procedure entry mask
access:
read only
mechanism: by reference
Name of a user-supplied routine to process the keys. The routine_name
argument is the address of the entry mask of a user-supplied routine to
call for each key entry containing the RFA (in other words, for each key
that points to the same module header).

This user-supplied routine cannot contain any calls to LBR$DELETE_KEY
or LBR$INSERT_KEY.

DESCRIPTION

Use LBR$SEARCH to find index keys that point to the same module
header. Generally, in index number 1 (the module name table), just one
key points to any particular module; thus, you would probably use this
routine only to search library indexes where more than one key points to a
module. For example, you might call LBR$SEARCH to find all the global
symbols associated with an object module in an object library.
If LBR$SEARCH finds an index key associated with the specified RFA, it
calls a user-supplied routine with two arguments:

•

The key argument, which is the address of either of the following:
-

A string descriptor for the keyname (libraries with ASCII
keynames).

An unsigned longword for the key value (libraries with binary
keys).

The RFA argument, which is the address of a 2-longword array
containing the RFA of the module header.

The routine must return a value to indicate success or failure. If the
specified routine returns a false value (low bit= 0), then the index search
terminates.
Note that the key found by LBR$SEARCH is valid only during the call to
the user-supplied routine. If you want to use the key later, you must copy
it.

CONDITION
VALUES
RETURNED

LBR-64

LBR$_1LLCTL

Specified library control index not valid.

LBR$_1LLIDXNUM

Specified library index number not valid.

LBR$_KEYNOTFND

Librarian did not find any keys with the specified RFA.

LBR$_LIBNOTOPN

Specified library not open.

Librarian {LBR) Routines
LBR$SET_INDEX

LBR$SET_INDEX Set the Current Index Number
The LBR$SET_INDEX routine sets the index number to use when processing
libraries that have more than one index.

FORMAT

LBR$SET_INDEX

RETURNS

VMS usage:
type:
access:
mechanism:

library_index ,index_number

cond_value
longword {unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

index number
longword_unsigned
longword {unsigned)
read only
by reference
Index number you want to establish as the current index number. The
library_index is the address of the longword that contains the number of
the index you want to establish as the current index. (See Section 8.1.2.3.)
VMS usage:
type:
access:
mechanism:

DESCRIPTION

When you call LBR$INI_CONTROL, the librarian sets the current library
index to 1 (the module name table, unless the library is a user-developed
library). If you need to process another library index, you must use
LBR$SET_INDEX to change the current library index.
Note that macro, help, and text libraries contain only one index; therefore,
you do not need to call LBR$SET_INDEX. Object libraries contain two
indexes. If you want to access the global symbol table, you must call
the LBR$SET_INDEX routine to set the index number. User-developed
libraries can contain more than one index; therefore, you may need to call
LBR$SET_INDEX to set the index number.

LBR-65

Librarian (LBR) Routines
LBR$SET_INDEX

Upon successful completion, LBR$SET_INDEX sets the current library
index to the requested index number. The librarian routines number
indexes starting with 1.

CONDITION
VALUES
RETURNED

LBR-66

LBR$_1LLCTL

Specified library control index not valid.

LBR$_1LLIDXNUM

Library index number specified not valid.

LBR$_LIBNOTOPN

Specified library not open.

Librarian {LBR) Routines
LBR$SET_LOCATE

LBR$SET_LOCATE

Set Record Access to Locate
Mode

The LBR$SET_LOCATE routine sets the record access of librarian
subroutines to locate mode.

FORMAT

LBR$SET_LOCATE

RETURNS

VMS usage:
type:
access:
mechanism:

library_index

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

library_index
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Library control index returned by the LBR$INI_CONTROL routine. The
library_index argument is the address of the longword that contains the
index.

DESCRIPTION

Librarian record access may be set to move mode (the default set by
LBR$SET_MOVE) or locate mode. The setting affects the operation of the
LBR$GET_RECORD routine.
If move mode is set (the default), LBR$GET_RECORD copies the
requested record to the specified user buffer. If locate mode is set, the
record is not copied. Instead, the outbufdes descriptor is set to reference
the internal librarian subroutine buffer that contains the record.

CONDITION
VALUES
RETURNED

LBR$_1LLCTL

Specified library control index not valid.

LBR$_LIBNOTOPN

Specified library not open.

LBR-67

Librarian (LBR) Routines
LBR$SET_MODULE

LBR$SET_MODULE

Read or Update a Module
Header

The LBR$SET_MODULE routine reads, and optionally updates, the module
header associated with a given record's file address (RFA).

FORMAT

LBR$SET_MODULE

library_index ,rfa [,bufdesc]
f.buflenl f.uodatedescl

•'

RETURNS

VMS usage:
type:
access:
mechanism:

•"'

cond_value
longword {unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

library_index
VMS usage: longword_unsigned
type:
longword {unsigned)
access:
read only
mechanism: by reference
Library control index returned by the LBR$INI_CONTROL routine. The
library_index argument is the address of the longword that contains the
index.

rfa
VMS usage: vector_longword_unsigned
type:
longword {unsigned)
access:
read only
mechanism: by reference
Record's file address (RFA) associated with the module header. The
rfa argument is the address of a 2-longword array containing the RFA
returned by LBR$PUT_RECORD or LBR$LOOKUP_KEY.

bufdesc
VMS usage: char_string
type:
character string
access:
write only
mechanism: by descriptor
Buffer that receives the module header. The bufdesc argument is the
address of a string descriptor pointing to the buffer that receives the
module header. The buffer must be the size specified by the symbol
MHD$B_USRDAT plus the value of the CRE$L_UHDMAX create option.
The MHD$ and CRE$ symbols are defined in the modules $MHDDEF and
$CREDEF, which are stored in SYS$LIBRARY:STARLET.MLB.
LBR-68

Librarian (LBR) Routines
LBR$SET_MODULE

but/en
VMS usage: longword_signed
type:
longword {signed)
access:
write only
mechanism: by reference
Length of the module header. The buft.en argument is the address of a
longword receiving the length of the returned module header.

updatedesc
VMS usage: char_string
character string
access:
read only
mechanism: by descriptor
Additional information to be stored with the module header. The
updatedesc argument is the address of a string descriptor pointing to
additional data that the librarian stores with the module header. If you
include this argument, the librarian updates the module header with the
additional information.
type:

DESCRIPTION

If you specify bufdesc, the librarian routine returns the module header

into the buffer. If you specify bu:ften, the librarian routine also returns
the buffer's length. If you specify updatedesc, the routine updates the
header information.
You define the maximum length of the update information (by specifying
a value for CRE$L_UHDMAX) when you create the library. The librarian
zero-fills the information if it is less than the maximum length or
truncates it if it exceeds the maximum length.

CONDITION
VALUES
RETURNED

LBR$_HDRTRUNC

Buffer supplied to hold the module header was too
small.

LBR$1LLCTL

Specified library control index not valid.

LBR$_1LLOP

Error. The updatedesc argument was supplied and
the library was a Version 1.0 library or the library was
opened only for read access.

LBR$_1NVRFA

Specified RFA does not point to a valid module
header.

LBR$_LIBNOTOPN

Specified library not open.

LBR-69

Librarian {LBR) Routines
LBR$SET_MOVE

LBR$SET_MOVE

Set Record Access to Move Mode

The LBR$SET_MOVE routine sets the record access of Librarian subroutines
to move mode.

FORMAT

LBR$SET_MOVE

RETURNS

VMS usage:
type:
access:
mechanism:

library_index

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

DESCRIPTION

CONDITION
VALUES
RETURNED

LBR-70

Librarian record access may be set to move mode (the default, set by
LBR$SET_MOVE) or locate mode. The setting affects the operation of the
LBR$GET_RECORD routine. If move mode is set, LBR$GET_RECORD
copies the requested record to the specified user buffer. For details, see the
description of LBR$GET_RECORD.

LBR$_1LLCTL

Specified library control index not valid.

LBR$_LIBNOTOPN

Specified library not open.

MAIL Routines

9.1

Introduction to MAIL Routines
The callable interface of the VMS Mail Utility (MAIL) lets you send
messages to users on your system or on any other VAX computer
connected to your system with DECnet-VAX. This chapter describes
how application programs using callable MAIL routines can perform the
following functions:
•

Create and access mail files

•

Access and manipulate a message or group of messages

•

Create and send messages to a user or group of users

•

Access and manipulate the user common database

For information about the DCL interface to the VMS Mail Utility, see the
VMS Mail Utility Manual.

9.2

Messages
Messages are files that contain information you want to send to other
users. Short messages, smaller than 3 blocks, are part of a mail file, while
long messages, larger than 3 blocks, are external sequential files.
External files reside in the same directory as the mail file that points to
them.
Structure of a Message

A message consists of header information and the bodypart. The
message bodypart consists of text records that contain information you
want to send to another user.
Figure 9-1 illustrates the format of a mail message.

MAIL-1

MAIL Routines
9.2 Messages

Figure 9-1
From:
To:
CC:
Subj:

Standard Message Format

MYNODE: : USER
NODE: :J DOE

"The Celestial Navigator" 0

••
•

USER

Perseids ...

Get ready. Tuesday of this week (August 12th), one
Cit
of the most abundant meteor showers of the year will occur.
The Perseids, also known as the St. Laurence's Tears, stream
across earth's orbit at 319.3 degrees. Radiant 3h4m +58 degrees.
Fine for photography with an average magnitude of 2.27.
There will be some fireballs, fainter white or yellow
meteors, and brighter

green or orange or red ones. About one

third of the meteors, including all the brightest, leave
yellowish trains, which may be spectacular, up to 2
degrees wide and lasting up to 100 seconds. Brighter
meteors often end in flares or bursts.
8

The parts of a message are as follows:
•

Header information

0 From: field specifies the sender and an optional personal name
string

8 To: field specifies the direct addressee.
8 CC: field specifies the carbon copy addressee.
8 Subj: field specifies the topic of the message.
•

Bodypart

Cit First line of the bodypart
8 Last line of the bodypart
External Message Identification Number

In addition, the file name of an external message uses the following
format:
MAIL$nnnnnnnnnnnnnnnn.MAI

where n . . . n is the external message identification number.

9.3

Folders
MAIL organizes messages by date and time received and, secondarily,
by folder name. All messages are associated with a folder name-either
default folders or user-specified folders. VMS MAIL associates mail
messages with one of three default mail folder names. Table 9-1 describes
the three default MAIL folders.

MAIL-2

MAIL Routines
9.3 Folders

Table 9-1

Default Mail Folders

Folder

Contents

NEWMAIL

Newly received, unread messages

MAIL

Messages that have been read and not deleted

WASTEBASKET

Messages designated for deletion

You can also place messages in any user-defined mail folder.

9.4

Mail Files
A mail file is an indexed sequential (ISAM) file that contains the following
types of data:
•

Header information for all messages

•

Text of short messages

•

Pointers to long messages

In addition, you can select messages from mail files as well as copy or
move messages to or from mail files.
Mail File Format

The indexed sequential mail file format offers two advantages: use of
folders and faster access time than sequential access. ISAM mail files use
two keys to locate messages-a primary key denoting the date and time
received and a secondary key using the folder name.

9.5

User Common Database
VMS MAIL maintains an indexed sequential data file VMSMAIL_
PROFILE.DATA that serves as a system-wide database of user profile
entries. A user profile entry is a record that contains data describing a
user's default processing characteristics and whose primary key is the
username. Table 9-2 summarizes information contained in a user profile
entry.
Table 9-2 User Profile Information
Field

Function

Directory

Default MAIL subdirectory

Form

Default print form

Forwarding address

Personal name string

User-specified character string included in the
message header

Queue name

Default print queue name
(continued on next page)

MAIL-3

MAIL Routines
9.5 User Common Database

Table 9-2 (Cont.) User Proflle Information
Function

Fie Id
Flags
Automatic purge
CC: prompt
Copy self forward
Copy self reply
Copy self send

Purging of the wastebasket folder on exiting
Carbon copy prompt
Copy to self when forwarding a message
Copy to self when replying to a message
Copy to self when sending a message

Both the callable and user interfaces of the VMS MAIL utility use the
common database to determine default processing characteristics.

9.6

MAIL Processing Contexts
VMS MAIL defines four discrete levels of processing, or contexts for
manipulating mail files, messages, folders, and the user common database
as shown in Table 9-3.
Table 9-3 Levels of MAIL Processing
Context

Entity

Mail file

Mail files and folders

Message

Mail files, folders, and messages

Send

Messages

User

User common database

Within each context, your application processes specific entities in certain
ways using callable MAIL routines as described in the sections that follow.
Initiating a MAIL Context

You must explicitly begin and end each MAIL context. Each group of
routines contains a pair of context-initiating and terminating routines.
When you begin processing in any context, VMS MAIL performs the
following functions:
1

Allocates sufficient virtual memory to manage context information

Initializes context variables and internal structures

Terminating a MAIL Context

Terminating a MAIL processing context deallocates virtual memory.
You must explicitly terminate processing in any context by calling a
context-terminating routine.

MAIL-4

MAIL Routines
9.6 MAIL Processing Contexts

9.6.1

Callable MAIL Routines
There are four types of callable MAIL routines, each corresponding to
the context within which they execute. A prefix identifies each functional
group-MAIL$MAILFILE_, MAIL$MESSAGE_, MAIL$SEND_, and
MAIL$USER_.
Table 9-4 lists MAIL routines according to context.
Table 9-4 Callable MAIL Routines

9.6.2

Context

Routine

Mail file

MAIL$MAILFILE_BEGIN
MAIL$MAILFILE_CLOSE
MAIL$MAILFILE_COMPRESS
MAIL$MAILFILE_END
MAIL$MAILFILE_INFO_FILE
MAIL$MAILFILE_MODIFY
MAIL$MAILFILE_OPEN
MAIL$MAILFILE_PURGE_WASTE

Message

MAIL$MESSAGE_BEGIN
MAIL$MESSAGE_COPY
MAIL$MESSAGE_DELETE
MAIL$MESSAGE_END
MAIL$MESSAGE_GET
MAIL$MESSAGE_INFO
MAIL$MESSAGE_MODIFY
MAIL$MESSAGE_SELECT

Send

MAIL$SEND_ABORT
MAIL$SEND_ADD_ADDRESS
MAIL$SEND_ADD_ATIRIBUTE
MAIL$SEND_ADD_BODYPART
MAIL$SEND_BEGIN
MAIL$SEND_END
MAIL$SEND_MESSAGE

User

MAIL$USER_BEGIN
MAIL$USER_DELETE_IN FO
MAIL$USER_END
MAIL$USER_GET_INFO
MAIL$USER_SET_INFO

Single and Multiple Threads
Once you have successfully initiated MAIL processing in a context, you
have created a thread. A thread is a series of calls to MAIL routines that
uses the same context information. Applications can contain one or more
threads.
Single Threads

For example, an application that begins mail file processing; opens,
compresses, and closes a mail file; and ends mail file context processing
executes a single thread of procedures that reference the same context
variable names and pass the same context information.
MAIL-5

MAIL Routines
9.6 MAIL Processing Contexts

Multiple Threads

You can create up to 31 concurrent threads. Applications that contain
more than one thread must maintain unique context variables for each
thread in order to pass thread-specific context information.
VMS MAIL returns the condition value MAIL$_NOMORECTX when your
process attempts to exceed the maximum number of allowable threads.

9.7

Programming Considerations
The calling sequence for all MAIL routines consists of a status variable,
an entry point name, and an argument list. .All arguments wit:bJn the
argument list are required. All callable MAIL routines use the same
arguments in their calling sequences as described in the following
example:
STATUS=MAIL$MAILFILE_BEGIN(CONTEXT, IN_ITEM_LIST, OUT_ITEM_LIST)

The variable status receives the condition value, and the argument
context receives the context information. The arguments in_item_list
and out_item_list are input and output item lists that contain one or
more input or output item descriptors.

9.7.1

Condition Handling
At run time, a hardware- or software-related event can occur that
determines whether or not the application executes successfully. VMS
MAIL processes such an event, or condition in the following ways:
•

Signals the condition value

•

Returns the error code

You can establish your own condition handler or allow the program to
signal the default VAX Condition Handler Facility (CHF).
Returning Condition Values

You can disable signaling for any call by specifying the item code MAIL$_
NOSIGNAL as an item in the input item list.

9.7.2

Item Lists and Item Descriptors
Your application passes data to callable MAIL routines and receives data
from routines through data structures called item lists defined in your
program.

MAIL-6

MAIL Routines
9.7 Programming Considerations

9.7.2.1

Structure of an Item Descriptor
An input or output item list is a data structure that consists of one or
more input or output item descriptors.

The following table summarizes the characteristics of item lists:
Item Descriptor

Characteristics

Input

Each descriptor points to a buffer or file from which MAIL
reads data.

Output

Each descriptor points to a buffer or file to which MAIL writes
data.

An item descriptor is a data structure consisting of three longwords as
described in Figure 9-2.
Figure 9-2 Item Descriptor

Item Code

Buffer Length

Buffer Address
Return Length Address
ZK-1705-GE

Item descriptor fields are described as follows:
Field

Function

Item code

Specifies an action the routine is to perform.

Buffer length

Specifies the length in bytes of an input or output
buffer.

Buffer address

Specifies the address of the input or output buffer.

Return length address

Depends on the type of item code specified as
summarized below.
Item
Code

Use

Input

Not used; specify 0.

Output

Address of a longword that receives
the length of the result.

Note: You can specify item descriptors in any order within an item list.

MAIL-7

MAIL Routines
9.7 Programming Considerations

Item Codes

The item code defines an action that the routine is to perform. Input
and output item codes are specified in input and output item descriptors,
respectively.
Boolean input and output item codes request an operation but do not pass
data tO the called routine. For example, the item code MAIL$_USER_
SET_CC_PROMPT sets the CC prompt flag enabling use of CC: field text.
For a complete list of input and output item codes, see Tables 9-9 and
9-10.
9.7.2.2

Null Item Lists

Both the input and output item list arguments in the MAIL routine calling
sequence are required. However, there might be situations when you do
not want to request an operation or no input or output item codes are
listed for the routine. In such cases, you must pass the value 0 in the
function call.
9.7.2.3

Declaring Item Lists and Item Descriptors

Depending on the programming language you are using, refer to the
appropriate language reference manual for more information about
declaring data structures and creating variables.
9.7.2.4

Terminating an Item List

Terminate an item list with a null item descriptor. Assign the value 0 to
each field in the item descriptor.

9.7.3

Action Routines
Certain callable MAIL routines allow you to specify an action routine.
An action routine transfers control to a user-written subroutine that
performs specific tasks.
9.7.3.1

Types of Action Routines

The mail file, message, and send contexts permit the use of action routines
for specific reasons. The following table summarizes the types of action
routines and the contexts in which they are used:
Context

Routine

Action Routine

Mail file

MAIL$MAILFILE_INFO_FILE

Folder action

Message

MAIL$MESSAGE_COPY

Mail file action
Folder action

Send

MAIL$SEND_MESSAGE

Success
Error

The preceding table summarizes typical uses of action routines. However,
an action routine can perform any task you specify. See the Guide to
Creating VMS Modular Procedures for more information about action
routines.
MAIL-8

MAIL Routines
9. 7 Programming Considerations

Mall Fiie and Folder Action Routine Calllng Sequence

The main portion of the application calls the action routine and passes
values to it using parameters. The calling sequence of a mail file or folder
action routine is as follows:
entry-point-name(userdata, foldername)

The argument userdata is the address of an optional longword that
contains user-specified data, and the argument foldername is the address
of a descriptor of the foldername.
Send Action Routine Calllng Sequence

The calling sequence of a send action routine is as follows:
entry-point-name(username,signal-array,userdata)

The argument username is the address of a descriptor of the username
to which the application successfully sent a message; signal-array is the
address of a signal array containing the success message; userdata is the
address of an optional longword that contains user-specified data.

9.8

Mail File Context
Mail file context processing involves accessing and manipulating one or
more mail files. Table 9-5 summarizes each mail file routine and its
function.
Table 9-5

Mall Fiie Routines

Routine

Description

MAIL$MAILFILE_BEGIN

Initiates mail file processing

MAIL$MAILFILE_CLOSE

Closes a mail file

MAIL$MAILFILE_COMPRESS

Compresses a mail file

MAIL$MAILFILE_END

Terminates mail file processing

MAIL$MAILFILE_INFO_FILE

Obtains information about the mail file

MAIL$MAILFILE_MODIFY

Changes the wastebasket folder name

MAIL$MAILFILE_OPEN

Opens a mail file

MAIL$MAILFILE_PURGE_WASTE

Purges a mail file

Initiating the Mail File Context

Your application must call MAIL$MAILFILE_BEGIN to perform mail file
context processing.
When you call MAIL$MAILFILE_BEGIN successfully and begin
processing in the mail file context, you have created a thread. You must
specify the same context variable name in routine calls within the same
thread.

MAIL-9

MAIL Routines
9.8 Mail File Context

Terminating the Mail File Context

Terminate processing in the mail file context calling MAIL routines in the
following order:

9.8.1

Terminate message context processing (if applicable) using
MAIL$MESSAGE_END.

Close the currently open mail file using MAIL$MAILFILE_CLOSE.

Terminate mail file context processing using MAIL$MAILFILE_END.

Managing Mail Files
Using mail files involves opening and closing MAIL default and
user-created mail files, using MAIL default and alternate mail file
specifications, and purging and compressing mail files.
9.8.1.1

Opening and Closing Mail Files

Before you perform any activities on existing messages, folders, and mail
files, you must first open a mail file. Whenever you open a mail file, you
must do so explicitly using MAIL$MAILFILE_OPEN. You can open only
one mail file per mail file thread.
Note that each routine references the same context variable. An open mail
file must be explicitly closed with a call to MAIL$MAILFILE_CLOSE.
9.8.1.1.1

Using the Default Specification for Mail Files

To open a mail file, MAIL must first locate it using either a default or a
user-specified mail file specification. A mail file specification consists of
the following components: disk and directory, file name, and file type.
If you use the default file specification, VMS MAIL locates and opens the
default mail file using the following information:

9.8.1.1.2

Component

Source

User's disk and directory

Retrieved from the user authorization file (UAF)

MAIL subdirectory

Retrieved from the user profile entry

Mail file name and type

MAIL.MAI

Specifying an Alternate Mail File Specification

You can use the default specication for mail files or specify all or part of an
alternate mail file specification.
When to Specify an Alternate Mail File Specification

The following mail file routines accept alternate mail file specifications
when you use the item codes MAIL$_MAILFILE_DEFAULT_NAME or
MAIL$_MAILFILE_NAME or both:

MAIL-10

•

MAIL$MAILFILE_COMPRESS

•

MAIL$MAILFILE_INFO_FILE

•

MAIL$MAILFILE_MODIFY

MAIL Routines
9.8 Mail File Context

•

MAIL$MAILFILE_OPEN

How VMS MAIL Creates an Alternate Mail File Specification

VMS MAIL constructs an alternate mail file specification by modifying
the default specification for mail files with your program-supplied mail file
specifications in the following order of importance:
1

Program-supplied file specification (MAIL$_MAILFILE_NAME)
•

Program-supplied disk and directory

•

Program-supplied file name and type

Program-supplied default file specification (MAIL$_MAILFILE_
DEFAULT_NAME)
•

Program-supplied disk and directory

•

Program-supplied file name and type

Default specification

If you are using MAIL$_MAILFILE_DEFAULT_NAME and you specify
0 as the buffer size and address, VMS MAIL uses the current device and

directory.
The default specification for mail files applies unless overridden by your
program-supplied mail file specifications. Mail file specifications defined
with MAIL$_MAILFILE_NAME override those defined with MAIL$_
MAILFILE_DEFAULT_NAME.
For example, an application can override the default specification
$DISKO:[USER]MAIL.MAIL by defining an alternate device
type $DISK99: using MAIL$_MAILFILE_NAME. The result is
$DISK99:[USER]MAIL.MAI. The application can further modify the
specification by defining a different mail file MYMAILFILE.MAI using
MAIL$_MAILFILE_DEFAULT_NAME. The new mail file specification is
$DISK99:[USER]MYMAILFILE.MAI.
9.8.1.2

Displaying Folder Names

As the size of your mail files increases with messages and folders, you
might want to display your folder names. A user-written folder action
routine lets you do this.
In the mail file context, MAIL$MAILFILE_INFO_FILE can be used to
invoke a folder action routine that displays folder names in a mail file.
If you specify the item code MAIL$_MAILFILE_FOLDER_ROUTINE,
MAIL$MAILFILE_INFO passes a descriptor of a folder name to the action
routine repeatedly until it encounters no more folder names and passes a
null descriptor.

MAIL-11

MAIL Routines
9.8 Mail File Context

9.8.1.3

Purging Mail Files Using the Wastebasket Folder

VMS MAIL associates messages designated for deletion with a
wastebasket folder. Purging mail files of messages in the wastebasket
folder that are designated for deletion is one way to conserve disk space.
You can also use VMS MAIL to conserve disk space by reclaiming disk
space and compressing mail files, as described in the sections that follow.
Note that purging the wastebasket folder removes the messages from the
wastebasket folder but might not reclaim disk space.
9.8.1.3.1

Reclalmlng Disk Space

However, simply deleting the messages does not mean you will
automatically reclaim the disk space. VMS MAIL uses a system-defined
threshold of bytes designated for deletion to determine when to reclaim
disk space. When the total number of total bytes designated for deletion
exceeds the threshold, VMS MAIL performs a reclaim operation.
You can override the deleted bytes threshold and request a reclaim
operation using MAIL$MAILFILE_PURGE_WASTE with the input item
code MAIL$_MAILFILE_RECLAIM.
See the VMS Convert and Convert I Reclaim Utility Manual for more
information.
9.8.1.3.2

Compressing Mall Flies

Compressing mail files is a way of conserving disk space. Mail file
compression provides faster access to the folders and messages within the
mail file. When you call MAIL$MAILFILE_COMPRESS, MAIL removes
unused space within the specified mail file.

9.9

Message Context
Message context processing involves manipulating existing messages as
well as creating and deleting folders and mail files. Table 9-6 summarizes
routines used in the message context.
Table 9-6

Message Routines

Routine

Description

MAIL$MESSAGE_BEGIN

Initiates message processing

MAIL$MESSAGE_COPY

Copies messages

MAIL$MESSAGE_DELETE

Deletes messages

MAIL$MESSAGE_END

Terminates message processing

MAIL$MESSAGE_GET

Retrieves a message
(continued on next page)

MAIL-12

MAIL Routines
9.9 Message Context

Table 9-6 (Cont.) Message Routines
Routine

Description

MAIL$MESSAGE_INFO

Obtains information about a specified message

MAIL$MESSAGE_MODIFY

ldentfies a message as replied, new, or marked

MAIL$MESSAGE_SELECT

Selects a message or messages from the currently
open mail file

Initiating the Message Context

The message context is the only MAIL context that your application cannot
invoke directly. Message context processing can begin only after a mail file
has been opened. Your application must explicitly call MAIL$MESSAGE_
BEGIN in order to execute message context processing.
VMS MAIL passes mail file context information to the message context
when you call MAIL$MESSAGE_BEGIN with the input item code MAIL$_
MESSAGE_FILE_CTX.
Terminating the Message Context

To terminate message level processing for a specific thread, you must call
MAIL$MESSAGE_END to deallocate memory.

9.9.1

Selecting Messages
Applications select messages using MAIL$MESSAGE_SELECT to copy
and move messages between folders as well as to read, modify, or delete
messages. You must select messages before you can use them. You must
specify a folder name when you select messages.
You can select messages based on the following criteria: matching
character strings, message arrival date' and time, and message
characteristics.
Matching Character Strings

You can select a message or set of messages from a mail file by specifying
one or more character substrings that you want to match with a character
substring in the header information of a message or group of messages.
You must specify the specific bodypart in the message header where the
substring is located.
•

From: line

•

To: line

•

CC: line

•

Subject: line

VMS MAIL searches the specified folder for message headers that contain
the matching character substring. This method of selection is useful when
you want to select and use messages from or to a particular user that are
associated with many folder names.
MAIL-13

MAIL Routines
9.9 Message Context

When you specify more than one character substring, VMS MAIL performs
a logical AND operation to find the messages that contain the correct
substring.
Message Arrival Date and Time

You can also select a message or group of messages based on their arrival
time, that is, when you received them. Applications select messages
according to two criteria as follows:
•

Messages received before a specified date or time or both.

•

Messages received since a specified date or time or both.

VMS MAIL searches the mail file and selects messages whose primary key
(date and time) matches the date and time specified in your application.
Message Characteristics

You can select messages based on MAIL system flag values that indicate
the following message characteristics:
•

New

•

Marked

•

Replied

For example, you can select unread messages in order to display them or
to display a message you have marked.

9.9.2

Reading and Printing Messages
After a message is selected, an applico.tion iteratively retrieves the
contents of the bodypart record by record. The message can be retrieved
using MAIL$MESSAGE_GET and can then be stored in a buffer or file.
Displaying a Message

To display a message on the terminal screen, you should store the message
in a buffer and use the host programming language command that directs
data to the screen.
Printing a Message

To print a message on a print queue on your system, you should write the
message to an external file and use the SYS$SNDJBC system service to
manage print jobs and define queue characteristics.

9.9.3

Modifying Messages
Message modification using MAIL$MESSAGE_MODIFY involves setting
flags that identify a message or group of messages as having certain
characteristics. The following table summarizes bit offsets that modify flag
settings:

MAIL-14

MAIL Routines
9.9 Message Context

9.9.4

Symbol

Meaning

MAIL$V_REPLIED

Flagged as answered

MAIL$V_MARKED

Flagged for display purposes

Copying and Moving Messages
You can copy messages between folders within a mail file or between
folders in different mail files using MAIL$MESSAGE_COPY. VMS MAIL
copies the message from the source folder to the destination folder leaving
the original message intact.
Similarly, you can move messages between folders within a mail file or
between folders in different mail files using MAIL$MESSAGE_COPY with
the item code MAIL$_MESSAGE_DELETE. VMS MAIL moves a message
by copying the message from the source folder and copying the message to
the destination folder. You must specify a folder name.
When you move a message to another folder within the same mail file, you
are changing the message's secondary key-its folder name.
9.9.4.1

Creating Folders

You can create a folder in a specified mail file whenever you attempt to
copy or move a message to a nonexistent folder. When you create a folder,
you are assigning a previously nonexistent folder name to a message as its
secondary key.
Your application can include a user-written folder action routine that
notifies you that the folder does not exist and accepts input to create the
folder.
9.9.4.2

Deleting Folders

You can delete a folder by moving all of the messages within the source
folder to another folder in the same mail file or to a folder in another mail
file. In this case, MAIL associates messages that are moved with a new
folder name.
You can also delete a folder by deleting all of the messages in a folder.
MAIL associates messages designated for deletion with the wastebasket
folder name.
In either case, the original folder name-the secondary key-no longer
exists.
9.9.4.3

Creating Mail Files

Similarly, you can create a mail file whenever you attempt to copy or move
a message to a nonexistent mail file.
Your application can include a user-written mail file action routine that
notifies you that the mail file does not exist and accepts input to create the
mail file.

MAIL-15

MAIL Routines
9.9 Message Context

Mail file creation involves creating the mail file and then copying or
moving the message to the new mail file. If the message is shorter than
3 blocks, VMS MAIL stores the message in the mail file. Otherwise, VMS
MAIL places a pointer to the message in the newly created mail file.

9.9.5

Deleting Messages
To delete a message, you need to know its message identification number.
Applications can retrieve the message identification number by specifying
the item code MAIL$_MESSAGE_ID when selecting a message or group of
messages with MAIL$MESSAGE_SELECT.
When you delete all messages with the same secondary key (folder name)
using MAIL$MESSAGE_DELETE and specifying the item code MAIL$_
MESSAGE_ID, you have deleted the folder.

9.10

Send Context
Send context processing involves creating and sending new and existing
messages. Table 9-7 summarizes send routines.
Table 9-7 Send Routines
Routine

Description

MAIL$SEND_ABORT

Aborts a send operation

MAIL$SEND_ADD_ADDRESS

Adds an addressee to the address list

MAIL$SEND_ADD_ATTRIBUTE

Constructs the message header

MAIL$SEND_ADD_BODYPART

Constructs the body of the message

MAIL$SEND_BEGIN

Initiates send processing

MAIL$SEND_END

Terminates send processing

MAIL$SEND_MESSAGE

Sends a message

Initiating the Send Context

You can invoke the send context directly if you are ereating a new message.
Otherwise, to access an existing message, you must open the mail file that
contains the message, select the message, and retrieve it.
Terminating the Send Context

You must terminate the send context explicitly using MAIL$SEND_END.

MAIL-16

MAIL Routines
9.10 Send Context

9.10.1

Sending New Messages
You can send new or existing messages to yourself and other users.
9.10.1.1

Creating a Message
You create new messages using send context routines. If you want to
create and send a new message, you do not need to initiate any other
context. As mentioned earlier, a message consists of two parts-the
message header and the message bodypart.

Constructing a message involves building each part of the message
separately using the following routines:

9.10.1.1.1

•

MAIL$SEND_ADD_ATTRIBUTE

•

MAIL$SEND_ADD_BODYPART

Constructing the Message Header
Each field of the message header is a message attribute. You can
specify one or more attributes for inclusion in the message header
using MAIL$SEND_ADD_ATTRIBUTE. During successive calls to
MAIL$SEND_ADD_ATTRIBUTE, an application specifies the specific
message attribute to be constructed.
If you do not specify the From: or To: fields, MAIL provides this

information from the address list.
9.10.1.1.2

Constructing the Body of the Message
To construct a message, an application must specify a series of calls to
MAIL$SEND_ADD_BODYPART to build a message from successive text
records contained in a buffer or file.
If the body of the message is located in a file, you can build the bodypart

with one call to MAIL$SEND_ADD_BODYPART by specifying its file
name.
9.10.1.2

Creating an Address List
You must create an address list in order to send a message. The address
list is a file or buffer of addressees to whom you want to send the message.
Each entry in the address list is a valid username on your system or on
another system connected to your system by DECnet-VAX.
Adding Usernames to the Address List

U sernames are added one at a time to the address list using one or more
calls to MAIL$SEND_ADD_ADDRESS.
Username Types

There are two types of usernames-direct and carbon copy addressees.
Direct and carbon copy addressees correspond to usernames in the To: and
CC: fields of the message header.

MAIL-17

MAIL Routines
9.10 Send Context

9.10.2

Sending Existing Messages
Sending an existing message involves many tasks as well as initiating the
mail file context and message context. The following table summarizes the
tasks and routines involved in sending an existing message:

9.10.3

Task

Routine

Open a mail file

MAIL$MAILFILE_OPEN

Select the message

MAIL$MESSAGE_SELECT

Retrieve the message

MAIL$MESSAGE_GET

Construct the message
Construct the message header
Construct the message bodypart

MAIL$SEND_ADD_ATTRIBUTE
MAIL$SEND_ADD_BODYPART

Create an address list

MAIL$SEND_ADD_ADDRESS

Send the message

MAIL$SEND_MESSAGE

Send Action Routines
Once you have created an address list and constructed a message, you
can send the message using MAIL$SEND_MESSAGE. Optional success
and error action routines handle signaled success and error events in a
synchronous manner.
For example, If DECnet-VAX returns messages indicating that it might
not be possible to complete a send operation to some users in your address
list, a user-specified send action routine might prompt the sender for
permission to continue the send operation.
9.10.3.1

Success Action Routines

A success action routine performs a task upon successful completion of a
send operation.
9.10.3.2

Error Handling Routines
An error action routine is a user-written error handler that signals error

conditions during a send operation.
9.10.3.3

Aborting a Send Operation

Under certain circumstances, you might want to terminate a send
operation in progress using MAIL$SEND_ABORT. In this instance, you
can use an asynchronous system trap (AST) routine that contains a call
to MAIL$SEND_ABORT to abort the send operation whenever the user
presses the Ctrl/c key sequence.

MAIL-18

MAIL Routines
9.11 User Profile Context

9.11

User Profile Context
The user profile processing context functions as a system management
tool for customizing the programming and interactive VMS MAIL
environments. It lets individual users modify their default processing
characteristics.
The user common database VMSMAIL_PROFILE.DATA contains
information that application programs and VMS MAIL use for processing
in any context.
User Context Routines

Table 9-8 summarizes the user context routines.
Table 9-8 User Profile Context Routines
Routine

Description

MAIL$USER_BEGIN

Initiates user profile context

MAIL$USER_DELETE_INFO

Deletes a user profile entry

MAIL$USER_END

Terminates user profile context

MAIL$USER_GET_INFO

Retrieves information about a user from the user
profile

MAIL$USER_SET_INFO

Adds or modifies a user profile entry

Initiating the User Context

You can invoke the user context directly.
Terminating the User Context

You must terminate the user context with MAIL$USER_END. Terminating
the user context deallocates virtual memory.

9.11.1

User Profile Entries
A user profile entry is a dynamic record. VMS MAIL creates a user profile
entry automatically for the calling process if it does not exist. The callable
and user interfaces of the MAIL utility use the data contained in the user
profile entry. The user profile consists of fields as described in the sections
that follow.
MAIL Subdirectory

A MAIL subdirectory is the location-that is, the disk and directory
specification-of your mail files. When you define a MAIL subdirectory,
you are creating a subdirectory in which the specified mail file and
associated external messages are to reside. For example:
$DISKS: [MAILUSER.COMMON.MAIL]

MAIL-19

MAIL Routines
9.11 User Profile Context

The subdirectory [.common.mail] represents the MAIL subdirectory
specification defined in the user profile entry. This subdirectory contains
the mail file (for example, MAIL.MAI) and any external messages
associated with the mail file. The disk and directory specification
$DISK5:[MAILUSER] is defined in the user authorization file (UAF).
Flags

User profile flags can be set to enable or disable automatic purging of
deleted mail, automatic self-copy when forwarding, replying, or sending
messages, and use of the CC prom pt.
Form

The form field of the user profile entry defines the default print form to be
used by print batch jobs. The string you specify as the default form must
match a valid print form in use on your system.
Forwarding Address

A forwarding address lets you receive messages to your account on
another system or to have your messages sent to another user either
on your system or another system. You must specify valid nodenames and
usernames.
Personal Name

A personal name is a user-specified character string. For example, a
personal name might include your entire name and phone number. Any
phrase beginning with alphabetic characters up to a maximum of 255
alphanumeric characters is valid.
Queue Name

The queue name field defines the default print queue on your system
where your print jobs are sent.
9.11.1.1

Adding User Profile Entries to the User Common Database
Ordinarily, VMS MAIL creates a user profile entry for the calling process
if one does not already exist. A system management application might
create entries for other users. When you specify the item code MAIL$_
USER_CREATE_IF using MAIL$USER_SET_INFO, VMS MAIL creates a
user profile entry if it does not already exist.

9.11.1.2

Modifying or Deleting User Profile Entries
The calling process can modify, delete, or retrieve its own user profile entry
without privileges.

The following table summarizes the privileges required to modify or delete
user profile entries that do not belong to the calling process:

MAIL-20

Procedure

Privilege

Function

MAIL$USER_SET_INFO

SYSPRV

To modify another user's
profile entry

MAIL Routines
9.11 User Profile Context

9.12

Procedure

Privilege

Function

MAIL$USER_GET_INFO

SYSNAM or SYSPRV

To retrieve information about
another user

Input Item Codes
Input item codes direct the called routine to read data from a buffer or file
and perform a task. Table 9-9 summarizes input item codes.
Table 9-9

Input Item Codes

Item Code

Function

Mail File Context
MAIL$_MAILFILE_DEFAULT_NAME

Specifies the location (disk and directory) of the default mail file
MAIL.MAI.

MAIL$_MAILFILE_FOLDER_ROUTINE

Displays folder names within a specified mail file.

MAIL$_MAILFILE_FULL_CLOSE

Requests that the wastebasket folder be purged and that a convert
/reclaim operation be performed, if necessary.

MAIL$_MAILFILE_NAME

Specifies the name of a mail file to be opened.

MAIL$_MAILFILE_RECLAIM

Overrides the deleted bytes threshold and and requests a reclaim
operation.

MAIL$_MAILFILE_USER_DATA

Passes a longword of user context data to an action routine.

MAIL$_MAILFILE_WASTEBASKET_NAME

Specifies a new name for the wastebasket in a specified mail file.

Message Context
MAIL$_MESSAGE_AUTO_NEWMAIL

Places newly read messages in the MAIL folder automatically.

MAIL$_MESSAGE_BACK

Returns the first record of the preceding message.

MAIL$_MESSAGE_BEFORE

Selects a message before a specified date and time.

MAIL$_MESSAGE_CC_SUBSTRING

Specifies a character string that must match a substring in the CC:
field of the specified message.

MAIL$_MESSAGE_CONTINUE

Returns the next text record of the current message.

MAIL$_MESSAGE_DEFAULT_NAME

Specifies the default mail file specification.

MAIL$_MESSAGE_DELETE

Deletes a message in the current folder after the message has
been copied to a new folder.

MAIL$_MESSAGE_FILE_ACTION

Specifies a user-written routine that is called if a mail file is to be
created.

MAIL$_MESSAGE_FILE_CTX

Specifies mail file context received from MAIL$MAILFILE_BEGIN.

MAIL$_MESSAGE_FILENAME

Specifies the name of a mail file to which the message is to be
moved.

MAIL$_MESSAGE_FOLDER_ACTION

Specifies a user-written routine that is called if a folder is to be
created.
(continued on next page)

MAIL-21

MAIL Routines
9.12 Input Item Codes

Table 9-9 (Cont.) Input Item Codes
Item Code

Function

Message Context

MAIL$_MESSAGE_FLAGS

Specifies MAIL system flags to use when selecting messages.

MAIL$_MESSAGE_FLAGS_MBZ

Specifies MAIL system flags that must be zero.

MAIL$_MESSAGE_FOLDER

Specifies the name of the target folder for moving messages.

MAIL$_MESSAGE_FROM_SUBSTRING

Specifies a character string that must match a substring in the
From: field of the specified message.

MAIL$_MESSAGE_ID

Specifies the message identification number of the message on
which an operation is to be performed.

MAIL$_MESSAGE_NEXT

Returns the first record of the message following the current
message.

MAIL$_MESSAGE_SINCE

Selects a message received since a specified date and time.

MAIL$_MESSAGE_SUBJ_SUBSTRING

Specifies a character string that must match a substring in the
Subject: field of the specified message.

MAIL$_MESSAGE_TO_SUBSTRING

Specifies a character string that must match a substring in the To:
field of the specified message.

MAIL$_MESSAGE_USER_DATA

Specifies a longword to be passed to the folder and mail file action
routines.

Send Context

MAIL$_SEND_CC_LINE

Specifies the CC: field text.

MAIL$_SEND_DEFAULT_NAME

Specifies the default file specification of a text file to be opened.

MAIL$_SEND_ERROR_ENTRY

Specifies a user-written routine to process errors that occur during
a send operation.

MAIL$_SEND_FID

Specifies the file identifier.

MAIL$_SEND_FILENAME

Specifies the input file specification of a text file to be opened.

MAIL$_SEND_FROM_LINE

Specifies the From: field text.

MAIL$_SEND_PERS_NAME
MAIL$_SEND_NO_PERS_NAME

Specifies the personal name string
Specifies that no personal string be used.

MAIL$_SEND_RECORD

Specifies the descriptor of a text record to be added to the body of
a message.

MAIL$_SEND_SUBJECT

Specifies the Subject: field text.

MAIL$_SEND_SUCCESS_ENTRY

Specifies a user-written routines to process successfully completed
events during a send operation.

MAIL$_SEND_TO_LINE

Specifies the To: field text.

MAIL$_SEND_USER_DATA

Specifies a longword passed to the send action routines.

MAIL$_SEND_USERNAME

Adds a specified username to the address list.

MAIL$_SEND_USERNAME_TYPE

Specifies the type of username added to the address list.
(continued on next page)

MAIL-22

MAIL Routines
9.12 Input Item Codes

Table 9-9 (Cont.) Input Item Codes
Item Code

Function

User Context

9.13

MAIL$_USER_CREATE_IF

Creates a user profile entry.

MAIL$_USER_FIRST

Returns information about the first user in the user profile database.

MAIL$_USER_NEXT

Returns information about the next user in the user profile
database.

MAIL$_USER_SET_AUTO_PURGE
MAIL$_USER_SET_NO_AUTO_PURGE

Sets the automatic purge flag.
Clears the automatic purge flag.

MAIL$_USER_SET_CC_PROMPT
MAIL$_USER_SET_NO_CC_PROMPT

Sets the CC prompt flag.
Clears the CC prompt flag.

MAIL$_USER_SET_COPY_FORWARD
MAIL$_USER_SET_NO_COPY_FORWARD

Sets the copy self forward flag.
Clears the copy self forward flag.

MAIL$_USER_SET_COPY_REPLY
MAIL$_USER_SET_NO_COPY_REPLY

Sets the copy self reply flag.
Clears the copy self reply flag.

MAIL$_USER_SET_COPY_SEND
MAIL$_USER_SET_NO_COPY_SEND

Sets the copy self send flag.
Clears the copy self send flag.

MAIL$_USER_SET_EDITOR
MAIL$_USER_SET_NO_EDITOR

Specifies the default editor.
Clears the default editor field.

MAIL$_USER_SET_FORM
MAIL$_USER_SET_NO_FORM

Specifies the default print form string.
Clears the default print form field.

MAIL$_USER_SET_FORWARDING
MAIL$_USER_SET_NO_FORWARDING

Specifies the forwarding address string.
Clears the forwarding address field.

MAIL$_USER_SET_NEW_MESSAGES

Specifies the new messages count.

MAIL$_USER_SET_PERSONAL_NAME
MAIL$_USER_SET_NO_PERSONAL_
NAME

Specifies the personal name string.
Clears the personal name field.

MAIL$_USER_SET_QUEUE
MAIL$_USER_SET_NO_QUEUE

Specifies the default print queue name string.
Clears the default print queue name field.

MAIL$_USER_SET_SUB_DIRECTORY
MAIL$_USER_SET_NO_SUB_DIRECTORY

Specifies a MAIL subdirectory.
Clears the MAIL subdirectory field.

MAIL$_USER_USERNAME

Specifies the user profile entry to be modified.

Output Item Codes
Output item codes direct the called routine to return data to a buffer or file
which is then available for use by the application. Table 9-10 summarizes
output item codes.

MAIL-23

MAIL Routines
9.13 Output Item Codes

Table 9-10 Output Item Codes
Item Code

Function

Mail File Context

MAIL$_MAILFILE_INDEXED

Determines whether the mail file format is indexed-sequential.

MAIL$_MAILFILE_DIRECTORY

Returns the mail file subdirectory specification to the caller.

MAIL$_MAILFILE_RESULTSPEC

Returns the result mail file specification.

MAIL$_MAILFILE_WASTEBASKET

Returns the wastebasket folder name for the specified file.

MAIL$_MAILFILE_DELETED_BYTES

Returns the number of deleted bytes in a specified mail file.

MAIL$_MAILFILE_MESSAGES_DELETED

Returns the number of deleted messages.

MAIL$_MAILFILE_DATA_RECLAIM

Returns the number of data buckets reclaimed.

MAIL$_MAILFILE_DATA_SCAN

Returns the number of data buckets scanned.

MAIL$_MAILFILE_INDEX_RECLAIM

Returns the number of index buckets reclaimed.

MAIL$_MAILFILE_TOTAL_RECLAIM

Returns the total number of bytes reclaimed.

Message Context

MAIL$_MESSAGE_BINARY_DATE

Returns the date and time received as a binary value.

MAIL$_MESSAGE_CC

Returns the text in the CC: field of the current message.

MAIL$_MESSAGE_CURRENT_ID

Returns the message identification number of the current message.

MAIL$_MESSAGE_DATE

Returns the message creation date string.

MAIL$_MESSAGE_EXTID

Returns the external message identification number of the current
message.

MAIL$_MESSAGE_FILE_CREATED

Returns the value of the mail file created flag.

MAIL$_MESSAGE_FOLDER_CREATED

Returns the value of the folder created flag.

MAIL$_MESSAGE_FROM

Returns the text in the From: field of the current messsage.

MAIL$_MESSAGE_RECORD

Returns a record from the current message.

MAIL$_MESSAGE_RECORD_TYPE

Returns the record type.

MAIL$_MESSAGE_REPLY_PATH

Returns the reply path.

MAIL$_MESSAGE_RESULTSPEC

Returns the resultant mail file specification.

MAIL$_MESSAGE_RETURN_FLAGS

Returns the MAIL system flag value of the current message.

MAIL$_MESSAGE_SELECTED

Returns the number of selected messages.

MAIL$_MESSAGE_SENDER

Returns the name of the sender of the current message.

MAIL$_MESSAGE_SIZE

Returns the size in records of the current message.

MAIL$_MESSAGE_SUBJECT

Returns the text in the Subject: field of the specified message.

MAIL$_MESSAGE_TO

Returns the text in the To: field of the specified message.
(continued on next page)

MAIL-24

MAIL Routines
9.13 Output Item Codes

Table 9-10 (Cont.) Output Item Codes
Item Code

Function

Send Context

MAIL$_SEND_COPY_FORWARD

Returns the value of the caller's copy forward flag.

MAIL$_SEND_COPY_REPLY

Returns the value of the caller's copy reply flag.

MAIL$_SEND_COPY_SEND

Returns the value of the caller's copy send flag.

MAIL$_SEND_RESULTSPEC

Returns the resultant file specification of the file to be sent.

MAIL$_SEND_USER

Returns the process owner's username.

User Context

9.14

MAIL$_USER_AUTO_PURGE

Returns the value of the automatic purge mail flag.

MAIL$_USER_CAPTIVE

Returns the value of the UAF captive flag.

MAIL$_USER_CC_PROMPT

Returns the value of the CC prompt flag.

MAIL$_USER_COPY_FORWARD

Returns the value of the copy self forward flag.

MAIL$_USER_COPY_REPLY

Returns the value of the copy self reply flag.

MAIL$_USER_COPY_SEND

Returns the value of the copy self send flag.

MAIL$_USER_EDITOR

Returns the name of the default editor.

MAIL$_USER_FORM

Returns the default print form string.

MAIL$_USER_FORWARDING

Returns the forwarding address string.

MAIL$_USER_FULL_DIRECTORY

Returns the complete directory path of the mail file subdirectory.

MAIL$_USER_NEW_MESSAGES

Returns the new message count.

MAIL$_USER_PERSONAL_NAME

Returns the personal name string.

MAIL$_USER_QUEUE

Returns the default queue name string.

MAIL$_USER_RETURN_USERNAME

Returns the username string.

MAIL$_USER_SUB_DIRECTORY

Returns the subdirectory specification.

Examples of Using MAIL Routines
The following section contains programming examples. Example 9-1 is a
C program that sends a MAIL message to another user.

MAIL-25

MAIL Routines
9.14 Examples of Using MAIL Routines

Example 9-1

Sending a File

I* send_message.c */
#include <stdio>
#include <descrip>
#include <ssdef>
#include <maildef>
#include <nam>
typedef struct itmlst
{

short buffer_length;
short item_code;
long buffer_address;
long return_length_address;
ITMLST;
int
send context = 0
ITMLST
nulllist []

{ {0,0,0,0} };

int
getline(char *line, int max)
if (fgets(line, max, stdin) ==NULL)
return O;
else
return strlen(line);
int
main (int argc, char *argv[])
char
to user[NAM$C MAXRSS],
subject line[NAM$C MAXRSS],
file[NAM$C MAXRSS]~
resultspec(NAM$C_MAXRSS]
long resultspeclen;
int
status = SS$ NORMAL,
file_len = o~
subject_line_len = 0,
to user len = 0

(continued on next page)

MAIL-26

MAIL Routines
9.14 Examples of Using MAIL Routines

Example 9-1 (Cont.) Sending a File
ITMLST
address itmlst[] = {
{sizeof(to_user), MAIL$_SEND USERNAME, to_user, &to_user_len},
{0,0,0,0}},
bodypart itmlst[] = {
{sizeof(file), MAIL$_SEND FILENAME, file, &file_len},
{0,0,0,0}},
out bodypart itmlst[] = {
{;izeof(re;ultspec), MAIL$ SEND RESULTSPEC, resultspec, &resultspeclen},
{0,0,0,0}},°
attribute itmlst[] = {
{sizeof(to user), MAIL$ SEND TO LINE, to user, &to user len},
{sizeof(subject_line), MAIL$=SEND_SUBJECT, subject_line, &subject_line_len},
{0,0,0,0}}

status= mail$send begin(&send context, &nulllist, &nulllist);
if (status != SS$ NORMAL)
exit(status); -

/* Get the destination and add it to the message */
printf("To: ");
to_user[getline(to_user, NAM$C_MAXRSS) - 1] =NULL;
address_itmlst[O] .buffer_length = strlen(to_user);
address_itmlst[O] .buffer_address = to_user;
status= mail$send add address(&send context, address_itmlst, &nulllist);
if (status != SS$_NORMAL)
return(status);
/* Get the subject line and add it to the message header */
printf ("Subject: ") ;
subject_line[getline(subject_line, NAM$C_MAXRSS) - 1] =NULL;

/* Displayed TO: line */
attribute itmlst[O] .buffer length= strlen(to user);
attribute=itmlst[O] .buffer=address = to_user;/* Subject: line */
attribute itmlst[l] .buffer length= strlen(subject line);
attribute=itmlst[l] .buffer=address = subject_line;status = mail$send add attribute(&send context, attribute_itmlst, &nulllist);
if (status != SS$_NORMAL)
return(status);

/* Get the file to send and add it to the bodypart of the message */
printf("File: ");
file[getline(file, NAM$C_MAXRSS) - 1] =NULL;
bodypart_itmlst[O] .buffer_length = strlen(file);
bodypart_itmlst[O] .buffer_address = file;
status= mail$send add bodypart(&send context, bodypart_itmlst, out_bodypart_itmlst);
if (status != SS$_NORMAL)
return(status);
resultspec[resultspeclen] = '\0';
printf("Full file spec actually sent:

[%s]\n", resultspec);
(continued on next page)

MAIL-27

MAIL Routines
9.14 Examples of Using MAIL Routines

Example 9-1 (Cont.)

Sending a File

/* Send the message */
status= mail$send message(&send context, nulllist, nulllist);
if (status != SS$_NORMAL)
return (status);
/* Done processing witht the SEND context */
status= mail$send end(&send context, nulllist, nulllist);
if (status != SS$_NORMAL)
return (status);
return (status);

Example 9-2 is a C program that displays a user's folders and returns how
many messages are in each folder.
Example 9-2

Displaying Folders

/* show_folders.c */
#include
#include
#include
#include
#include

typedef struct itmlst
{

short buffer_length;
short item_code;
long buffer_address;
long return_length_address;
ITMLST;
struct node
{

struct node *next;
char *folder_name;

/* Next folder name node */
/* Zero terminated folder name */

};

int
folder_routine(struct node *list, struct dsc$descriptor *name)
if (name->dsc$w_length)
{

while (list->next)
list = list->next;
list->next = malloc(sizeof(struct node));
list = list->next;
list->next = O;
list->folder name= malloc(name->dsc$w length+ 1);
strncpy(list->folder name,name->dsc$a pointer,name->dsc$w length);
list->folder_name[name->dsc$w_length]-= '\0';
(continued on next page)

MAIL-28

MAIL Routines
9.14 Examples of Using MAIL Routines

Example 9-2 (Cont.)

Displaying Folders

return(SS$_NORMAL);
main (int argc, char *argv[])
{

struct node list = {0,0};
int
message context = 0,
file_context = o,
messages_selected
O,
total_folders = 0,
total_messages = 0
ITMLST
null list [] = { { 0, 0, 0, 0} } ,
message in itmlst[] = {
{sizeof(file_context),MAIL$_MESSAGE FILE CTX,&file context,O},
{0,0,0,0}},
mailfile info itmlst[] = {
{4,MAIL$ MAILFILE FOLDER ROUTINE, folder routine,O},
{4,MAIL$-MAILFILE-USER DATA,&list,0},

{o,o,o,oT},

message select in itmlst[) = {
{0,MAIL$_MESSAGE_FOLDER,0,0},
{O,O,O,O}},
message select out itmlst[] = {
{sizeof(messages=selected),MAIL$_MESSAGE_SELECTED,&messages_selected,0},
{0,0,0,0}};
if (mail$mailfile begin(&file context, nulllist, nulllist) == SS$ NORMAL) {
if (mail$mailfile open(&file context, nulllist, nulllist) == ss$ NORMAL) {
if (mail$mailfile info file(&file context,
mailfile_info_itmlst, nulllist) == SS$ NORMAL) {
if (mail$message_begin(&message_context,
message in itmlst,
nulllist) ~= SS$ NORMAL)
struct node *tmp = &list;
while(tmp->next) {
tmp = tmp->next;
message select in itmlst[O] .buffer address= tmp->folder name;
message-select-in-itmlst[O] .buffer-length= strlen(tmp->folder name);
if (mail$message select(&message context,
message select in itmlst,
message-select-out itmlst) == SS$ NORMAL)
printf ("Folder %s has %d messages\n",
tmp->folder_name, messages_selected);
total_messages += messages_selected;
total_folders++;

.l
(continued on next page}

MAIL-29

MAIL Routines
9.14 Examples of Using MAIL Routines

Example 9-2 (Cont.)

Displaying Folders

printf("Total of %d messages in %d folders\n",total_messages, total_folders);
mail$message_end(&message_context, nulllist, nulllist);
}

mail$mailfile_close(&file_context, nulllist, nulllist);
}

mail$mailfile_end(&file_context, nulllist, nulllist);

Example 9-3 is a C program that displays fields in the user's MAIL
profile.
Example 9-3

Displaying User Profile Information

/* show_profile.c */
#include <stdio>
#include <ssdef>
#include <jpidef>
#include <maildef>
#include <stsdef>
#include <ctype>
#include <nam>
struct itmlst
{

short buff er length;
short item code;
long buffer address;
long return-length address;
};
int
user_context

struct
itmlst nulllist[]

{

{0,0,0,0} };

int
main (int argc, char *argv[])
int
userlen = 0,
/* return length of strings */
editor_len = O,
form len = O,
forwarding len = o,
full directory len = O,
personal name len = o,
queue_len = o-;
/* Flags */
auto purge = 0,
cc_prompt = o,
copy forward = 0,
copy-reply = 0,
copy:=send = 0

(continued on next page)

MAIL-30

MAIL Routines
9.14 Examples of Using MAIL Routines

Example 9-3 {Cont.)

Displaying User Profile Information

char
user[13],
editor[NAM$C MAXRSS],
form[NAM$C MAXRSS),
forwarding(NAM$C MAXRSS],
full directory[NAM$C MAXRSS],
personal name[NAM$C MAXRSS],
queue[NAM$C_MAXRSS)short
new_messages

struct itmlst
jpi list[] = {
{sizeof(user) - 1, JPI$_USERNAME, user, &userlen},
{o, o, o, 0}},
user itmlst[J = {
{0~ MAIL$ USER USERNAME, O, 0},
{0,0,0,0}},
out itmlst[] = {
/* Full directory spec */
{sizeof(full directory),MAIL$ USER FULL DIRECTORY,full directory,&full directory len},
/*New message count-*/ {sizeof(new messages), MAIL$ USER NEW MESSAGES, &new messages, 0},
/*-Forwarding field-*/ {sizeof(forwarding), MAIL$ USER FORWARDING, forwarding, &forwarding len},
/* Personal name field-*/
{sizeof(personal name), MAIL$ USER PERSONAL NAME, personal name, &personal_name_len},
/* Editor field */ {sizeof(editor), MAIL$ USER EDITOR, editor, &editor len},
/* cc prompti;g flag */
{sizeof(cc prompt), MAIL$ USER CC PROMPT, &cc_prompt, 0},
I* Copy send flag */ - {sizeof(copy send), MAIL$ USER COPY SEND, &copy_send, 0},
!* copy reply flag */{sizeof(copy reply), MAIL$ USER COPY REPLY, &copy reply, 0},
/* Copy forward flag *7
{sizeof(copy forward), MAIL$ USER COPY FORWARD, &copy forward, 0},
/* Auto purge flag *I
{sizeof(auto_purge), MAIL$_USER_AUTO_PURGE, &auto_purge, 0},
I* Queue field */
{sizeof(queue), MAIL$ USER QUEUE, queue, &queue len},
/* Form field */ {sizeof(form), MAIL$_USER_FORM, form, &form_len},
{0,0,0,0}};
int
status = SS$_NORMAL
/* Get a mail user context */
status = MAIL$USER_BEGIN(&user_context,
&nulllist,
&nulllist) ;
if (status != SS$_NORMAL)
return(status);
i f (argc > 1)

{
strcpy(user,argv[l]);

else
{

sys$getjpiw(O,O,O,jpi list,o,o,o);
user[userlen] = '\0';};

while(isspace(user[--userlen]))
user[userlen] = '\0';
user itmlst[O].buffer length= strlen(user);
user=itmlst[O].buffer=address =user;

(continued on next page)

MAIL-31

MAIL Routines
9.14 Examples of Using MAIL Routines

Example 9-3 (Cont.)

Displaying User Profile Information

status= MAIL$USER GET INFO(&user context, user_itmlst, out_itmlst);
if (status != SS$_NORMAL)
return (status);
/* Release the mail USER context */
status= MAIL$USER END(&user context, &nulllist, &nulllist);
if (status != SS$_NORMAL)
return(status);

/* display the information just gathered */
full directory[full directory len) = '\0';
printf("Your mail file directory is %s.\n", full directory);
printf("You have %d new messages.\n", new_messages);
forwarding[forwarding len] = '\0';
if (strlen(forwarding) == 0)
printf("You have not set a forwarding address.\n");
else
printf("Your mail is being forwsrded to %s.\n", forwarding);
personal name[personal name len) = '\0';
printf("Your personal name is \"%s\"\n", personal_name);
editor[editor len) = '\0';
if (strlen(form) == 0)
printf("You have not specified an editor.\n");
else
printf("Your editor is %s\n", editor);
printf("CC prompting is %s.\n",

(cc_prompt

TRUE) ? "disabled"

"enabled");

printf("Automatic copy to yourself on");
if (copy send == TRUE)
printfC" SEND");
if (copy reply == TRUE) {
if (copy send == TRUE)
printf(", ");
printf(" REPLY");
if (copy forward == TRUE) {
if ((copy reply== TRUE) I I (copy_send
printf(",");
printf(" FORWARD");

TRUE))

}

if ((copy reply== FALSE) && (copy_send
printf(" Nothing");
printf("\n");

FALSE) && (copy_forward

printf("Automatic deleted message purge is %s.\n",

(auto_purge

queue[queue len] = '\0';
if (strlen(form) == 0)
printf("You have not specified a default queue.\n");
else
printf("Your default print queue is %s.\n", queue);
form[form len] = '\0';
if (strlen(form) == 0)
printf("You have not specified a default print form.\n");
else
printf("Your default print form is %s.\n", form);

MAIL-32

FALSE))

TRUE)

"disabled"

"enabled");

MAIL Routines
9.15 MAIL Routines

9.15

MAIL Routines
The following pages describe the individual MAIL routines~

MAIL-33

MAIL Utility Routines
MAIL$MAILFILE_BEGIN

MAIL$MAILFILE_BEGIN
lnititates mail file processing.

FORMAT

RETURNS

MAIL$MAILFILE_BEGIN

context, in- item- list,
out_item_list

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
context
longword (unsigned)
modify
by reference
Mail file context information to be passed to other mail file routines. The
context argument is the address of a longword that contains mail file
context information.
VMS usage:
type:
access:
mechanism:

You should specify the value of this argument as 0 in the first of a
sequence of calls to mail file routines. In the following calls, you should
specify the mail file context value returned by this routine.

in_item_list
itmlst_3
longword (unsigned)
read only
by reference
Item list specifying options for the routine. The in_item_list argument is
the address of a list of item descriptors, each of which specifies an option
and provides the information needed to perform the operation.

VMS usage:
type:
access:
mechanism:

The item list is terminated by a longword value of 0.

MAIL-34

MAIL Utility Routines
MAIL$MAILFILE_BEGIN

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

Item Code

0
Buffer Length

Buffer Address
Return Length Address
ZK-1705-GE

ln_item_list Item Descriptor Fields
buffer length
A word specifying the length (in bytes) of the buffer that supplies the
information needed by the routine to process the specified item code. The
required length of the buffer depends on the item code specified in the
item code field of the item descriptor. If the value of buffer length is too
small, the routine truncates the data.
item code
A word containing a user-supplied symbolic code that specifies an option
for the MAIL operation. These codes are defined by the $MAILDEF macro.
See Input Item Codes for a description of these codes.
buffer address
A longword containing the address of the buffer that supplies information
to the routine.
return length address
This field is not used.
Input Item Codes
None.

ouLitem_list
VMS usage: itmlst_3
type:
longword
access:
write only
mechanism: by reference
Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.

MAIL-35

MAIL Utility Routines
MAIL$MAILFILE_BEGIN

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

Item Code

0
Buffer Length

Buffer Address
Return Length Address
ZK-1705-GE

Out_item_iist item Descriptor fieids
buffer length
A word containing a user-supplied integer specifying the length (in bytes)
of the buffer in which the routine is to write the information. The length
of the buffer needed depends on the item code specified in the item code
field of the item descriptor. If the value of buffer length is too small, the
routine truncates the data.
item code
A word containing a user-supplied symbolic code specifying the item of
information that the routine is to return. These codes are defined by
the $MAILDEF macro. See Output Item Codes for a description of these
codes.
buffer address
A longword containing the user-supplied address of the buffer in which the
routine is to write the information.
return length address
A longword containing the user-supplied address of a word in which the
routine writes the actual length in bytes of the information it returns.
Output Item Codes
MAIL$_MAILFILE_MAIL_DIRECTORY

When you specify MAIL$_MAILFILE_MAIL_DIRECTORY,
MAIL$MAILFILE_BEGIN returns the mail directory specification to
the caller. The buffer address field of the item descriptor points to a
buffer that receives a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

DESCRIPTION

MAIL-36

MAIL$MAILFILE_BEGIN creates and initiates a mail file context for calls
to other mail file routines.

MAIL Utility Routines
MAIL$MAILFILE_BEGIN

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

SS$_ACCVIO

Access violation.

Any condition value returned by LIB$GET_VM, $GETJPIW, and $GETSYI.

MAIL-37

MAIL Utility Routines
MAIL$MAILFILE_CLOSE

MAIL$MAILFILE_CLOSE
Closes the currently open mail file.

FORMAT

MAIL$MAILFILE_CLOSE

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_list,
out_item_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
context
longword (unsigned)
modify
by reference
Mail file context information to be passed to mail file routines. The
context argument is the address of a longword that contains mail file
context information returned by MAIL$MAILFILE_BEGIN.
VMS usage:
type:
access:
mechanism:

The item list is terminated by longword value of 0.
See MAIL$MAILFILE_BEGIN for a description of an input item
descriptor.
Input Item Codes
MAIL$_MAILFILE_FULL_CLOSE
The Boolean item code MAIL$_MAILFILE_FULL_CLOSE specifies that
MAIL$MAILFILE_CLOSE should purge the wastebasket folder when it
closes the mail file. If the number of bytes deleted by the purge operation
exceeds a system-defined threshold, MAIL reclaims the deleted space from
the mail file.

Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL-38

MAIL Utility Routines
MAIL$MAILFILE_CLOSE

The system-defined threshold is reserved by Digital.

out- item- list

VMS usage: itmlst_3
longword
access:
write only
mechanism: by reference
Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.
type:

See MAIL$MAILFILE_BEGIN for a description of an output item
descriptor.
Output Item Codes
MAIL$_MAILFILE_DATA_RECLAIM
When you specify MAIL$_MAILFILE_DATA_RECLAIM,
MAIL$MAILFILE_CLOSE returns the number of data buckets reclaimed
during the reclaim operation as a longword value.
MAIL$_MAILFILE_DATA_SCAN
When you specify MAIL$_MAILFILE_DATA_SCAN, MAIL$MAILFILE_
CLOSE returns the number of data buckets scanned during the reclaim
operation as a longword value.
MAIL$_MAILFILE_INDEX_RECLAIM
When you specify MAIL$_MAILFILE_INDEX_RECLAIM,
MAIL$MAILFILE_CLOSE returns the number of index buckets reclaimed
during a reclaim operation as a longword value.
MAIL$_MAILFILE_MESSAGES_DELETED
When you specify MAIL$_MAILFILE_MESSAGES_DELETED,
MAIL$MAILFILE_CLOSE returns the number of messages deleted as
a longword value.
MAIL$_MAILFILE_TOTAL_RECLAIM
When you specify MAIL$_MAILFILE_TOTAL_RECLAIM,
MAIL$MAILFILE_CLOSE returns the number of bytes reclaimed during
a reclaim operation as a longword value.

DESCRIPTION

If you specify the input item code MAIL$_MAILFILE_FULL_CLOSE, this

procedure purges the wastebasket folder automatically before it closes the
file. If the number of bytes deleted by this procedure exceeds the deleted
byte threshold, the system performs a convertlreclaim operation on the
file.

MAIL-39

MAIL Utility Routines
MAIL$MAILFILE_CLOSE

CONDITION
VALUES
RETURNED

MAIL-40

SS$_NORMAL

Normal successful completion.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOFILEOPEN

No mail file is open.

SS$_ACCVIO

Access violation.

MAIL Utility Routines
MAIL$MAILFILE_COMPRESS

MAIL$MAILFILE_COMPRESS
Compresses a mail file.

FORMAT

RETURNS

MAIL$MAILFILE_COMPRESS

context, in_item_list,
out_item_list

VMS usage: cond_value
longword (unsigned)
access:
write only
mechanism: by value

type:

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage: context
type:
longword (unsigned)
access:
modify
mechanism: by reference
Mail file context information to be passed to various mail file routines.
The context argument is the address of a longword that contains mail file
context information returned by MAIL$MAILFILE_BEGIN.

in_item_list
VMS usage: itmlst_3
longword (unsigned)
access:
read only
mechanism: by reference
Item list specifying options for the routine. The in_item_list argument is
the address of a list of item descriptors, each of which specifies an option
and provides the information needed to perform the operation.
type:

The item list is terminated by longword value of 0.
See MAIL$MAILFILE_BEGIN for a description of an input descriptor.
Input Item Codes

MAIL$_MAILFILE_DEFAULT_NAME
MAIL$_MAILFILE_DEFAULT_NAME specifies the default file
specification MAIL should use when opening a mail file. The buffer
address field points to a character string 0 to 255 characters long that
defines the default file specification.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

MAIL-41

MAIL Utility Routines
MAIL$MAILFILE_COMPRESS

If you specify the value 0 in buffer length field of the item descriptor,
MAIL$MAILFILE_COMPRESS uses the current default directory as the
default mail file specification.

If you do not specify MAIL$_MAILFILE_DEFAULT_NAME,
MAIL$MAILFILE_COMPRESS creates the default mail file specification
from the following sources:
•

Disk and directory defined in the caller's user authorization file (UAF)

•

Subdirectory defined in the MAIL user profile

•

Default file type of MAI

MAIL$_MAiLFiLE_FULL_CLOSE

The Boolean item code MAIL$_MAILFILE_FULL_CLOSE requests that
the wastebasket folder be purged and that convert and reclaim operations
be performed, if necessary.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL$_MAILFILE_NAME

MAIL$_MAILFILE_NAME specifies the name of a mail file to be opened.
The buffer that the buffer address field points to contains a character
string of 0 to 255 characters.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
If you do not specify MAIL$_MAILFILE_NAME, the default mail file name
is MAIL.

out- item- list

VMS usage:
type:
access:
mechanism:

itmlst_3
longword
write only
by reference

Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.
See MAIL$MAILFILE_BEGIN for a description of an output item
descriptor.
Output Item Codes
MAIL$_MAILFILE_RESULTSPEC

When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL returns the
resultant mail file specification. The buffer address field of the item
descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

MAIL-42

MAIL Utility Routines
MAIL$MAILFILE_COMPRESS

DESCRIPTION

CONDITION
VALUES
RETURNED

If you do not specify an input file, the MAIL$MAILFILE_COMPRESS
routine compresses the currently open MAIL file. The MAIL$MAILFILE_
COMPRESS routine signals informational messages concerning the phase
of the compression.

SS$_NORMAL

Normal successful completion.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOTISAM

The message file format is not ISAM.

RMS$_FNF

The specified file cannot be found.

RMS$_SHR

The specified file is not shareable.

SS$_ACCVIO

Access violation.

SS$_1VDEVNAM

The specified device name is invalid.

Any condition value returned by LIB$FIND_IMAGE_SYMBOL, LIB$RENAME_FILE,
$CREATE, $OPEN, $PARSE, and $SEARCH.

MAIL-43

MAIL Utility Routines
MAIL$MAILFILE_END

MAIL$MAILFILE_END
Terminates mail file processing.

FORMAT

MAIL$MAILFILE_END

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_list,
out_item_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage: context
type:
longword (unsigned)
access:
modify
mechanism: by reference
Mail file context information to be passed to mail file routines. The
context argument is the address of a longword that contains MAILFILE
context information returned by MAIL$MAILFILE_BEGIN.
If mail file processing is terminated successfully, MAIL sets the value of
the argument context to 0.

in_item_list
VMS usage: itmlst_3
type:
longword (unsigned)
access:
read only
mechanism: by reference
Item list specifying options for the routine. The in_item_list argument is
the address of a list of item descriptors, each of which specifies an option
and provides the information needed to perform the operation.

The item list is terminated by longword value of 0.
See MAIL$MAILFILE_BEGIN for a description of an input item
descriptor.
Input Item Codes
MAIL$_MAILFILE_FULL_CLOSE

The Boolean item code MAIL$_MAILFILE_FULL_CLOSE requests that
the wastebasket folder be purged and that convert and reclaim operations
be performed, if necessary.

MAIL-44

MAIL Utility Routines
MAIL$MAILFILE_END

Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.

out_item_list
itmlst_3
longword
write only
by reference
Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.

VMS usage:
type:
access:
mechanism:

See MAIL$MAILFILE_BEGIN for a description of an output item
descriptor.
Output Item Codes
None.

DESCRIPTION

CONDITION
VALUES
RETURNED

The MAIL$MAILFILE_END routine deallocates the mail file context
created by MAIL$MAILFILE_BEGIN as well as any dynamic memory
allocated by other mail file processing routines.

SS$_NORMAL

Normal successful completion.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

SS$_ACCVIO

Access violation.

Any condition value returned by LIB$FREE_VM.

MAIL-45

MAIL Utility Routines
MAIL$MAILFILE_INFO_FILE

MAIL$MAILFILE_INFO_FILE
Obtains information about a specified mail file.

FORMAT

MAIL$MAILFILE_INFO_FILE

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

context, in_item_/ist,
out_item_list

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage: context
type:
longword (unsigned)
access:
modify
mechanism: by reference
Mail file context information to be passed to mail file routines. The
context argument is the address of a longword that contains mail file
context information returned by MAIL$MAILFILE_BEGIN.

The item list is terminated by longword value of 0.
See MAIL$MAILFILE_BEGIN for a description of an input descriptor.
Input Item Codes

MAIL$_MAILFILE_DEFAULT_NAME
MAIL$_MAILFILE_DEFAULT_NAME specifies the default mail file
specification MAIL$MAILFILE_INFO_FILE should use when opening
a mail file. The buffer address field of the item descriptor points to a
character string of 0 to 255 characters that defines the default mail file
specification.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL-46

MAIL Utility Routines
MAIL$MAILFILE_INFO_FILE

If you specify the value 0 in buffer length field of the item descriptor,
MAIL$MAILFILE_INFO_FILE uses the current default directory as the
default mail file specification.
If you do not specify MAIL$_MAILFILE_DEFAULT_NAME,

MAIL$MAILFILE_INFO_FILE creates the default mail file specification
from the following sources:
•

Disk and directory defined in the caller's user authorization file (UAF)

•

Subdirectory defined in the MAIL user profile

•

Default file type of MAI

MAIL$_MAILFILE_FOLDER_ROUTINE

MAIL$_MAILFILE_FOLDER_ROUTINE specifies an entry point longword
address of a user-written routine that MAIL$MAILFILE_INFO_FILE
should use to display folder names. MAIL$MAILFILE_INFO_FILE calls
the user-written routine for each folder in the mail file.
MAIL$_MAILFILE_NAME

MAIL$_MAILFILE_NAME specifies the name of the mail file to be opened.
The buffer address field points to a buffer that contains a character
string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
If you do not specify MAIL$_MAIFILE_NAME, the default mail file name

is MAIL.
MAIL$_MAILFILE_USER_DATA

MAIL$_MAILFILE_USER_DATA specifies a longword that
MAIL$MAILFILE_INFO_FILE should pass to the user-defined folder
name action routine.
This item code is valid only when used with the item code MAIL$_
MAILFILE_FOLDER_ROUTINE.

See MAIL$MAILFILE_BEGIN for a description of an output item
descriptor.
Output Item Codes
MAIL$_MAILFILE_DELETED_BYTES

When you specify MAIL$_MAILFILE_DELETED_BYTES,
MAIL$MAILFILE_INFO_FILE returns the number of deleted bytes in
a specified mail file as longword value.
MAIL-47

MAIL Utility Routines
MAIL$MAILFILE_INFO_FILE

MAIL$_MAILFILE_RESULTSPEC

When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL$MAILFILE_
INFO_FILE returns the resultant mail file specification. The buffer
address field of the item descriptor points to a buffer that receives a
character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MAILFILE_WASTEBASKET

When you specify MAIL$_MAILFILE_WASTEBASKET,
MAIL$MAILFILE_INFO_FILE returns the name of the wastebasket folder
of the specified mail file. The buffer address field of the item descriptor
points to a buffer that receives a character string 0 to 39 characters long.
Specify a value from 0 to 39 in the buffer length field of the item
descriptor.

DESCRIPTION

If you do not specify an input file, the MAIL$MAILFILE_INFO_FILE
returns information about the currently open MAIL file.
Folder Action Routines
If you use the item code MAIL$_MAILFILE_FOLDER_ROUTINE to

specify a folder name routine, MAIL$MAILFILE_INFO_FILE passes
control to a user-specified routine. For example, the folder action routine
could display folder names. The folder action routine passes a pointer
to the descriptor of a folder name as well as the user data longword. A
descriptor of zero length indicates that the MAIL$MAILFILE_INFO_FILE
routine has displayed all folder names. If you do not specify the item code
MAIL$_MAILFILE_FOLDER_ROUTINE, MAIL$MAILFILE_INFO_FILE
does not call any folder action routines.

CONDITION
VALUES
RETURNED

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOFILEOPEN

The mail file is not open.

MAIL$_NOTISAM

The format of the message file is not ISAM.

MAIL$_0PENIN

MAIL cannot open the file as input.

SS$_ACCVIO

Access violation.

Any condition value returned by $CLOSE, $OPEN, $PARSE, and $SEARCH.

MAIL-48

MAIL Utility Routines
MAIL$MAILFILE_MODIFV

MAIL$MAILFILE_MODIFV
Modifies the informational record of an ISAM-format mail file.

FORMAT

MAIL$MAILFILE_MODIFY

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_list,
out_item_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage: context
type:
longword (unsigned)
access:
modify
mechanism: by reference
Mail File context information to be passed to mail file routines. The
context argument is the address of a longword that contains mail file
context information returned by MAIL$MAILFILE_BEGIN.

in- item- list

VMS usage: itmlst_3
type:
longword (unsigned)
access:
read only
mechanism: by reference
Item list specifying options for the routine. The in_item_list argument is
the address of a list of item descriptors, each of which specifies an option
and provides the information needed to perform the operation.

The item list is terminated by longword value of 0.
See MAIL$MAILFILE_BEGIN for a description of an input item
descriptor.
Input Item Codes

MAIL$_MAILFILE_DEFAULT_NAME
MAIL$_MAILFILE_DEFAULT_NAME specifies the default file
specification MAIL should use when opening a mail file. The buffer
address field points to a buffer that contains a character string of 0 to 255
characters that defines the default mail file specification.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL-49

MAIL Utility Routines
MAIL$MAILFILE_MODIFY

If you specify the value 0 in buffer length field of the item descriptor,

MAIL$MAILFILE_MODIFY uses the current default directory as the
default mail file specification.
If you do not specify MAIL$_MAILFILE_DEFAULT_NAME,

MAIL$MAILFILE_MODIFY creates the default mail file specification
from the following sources:
•

Disk and directory defined in the caller's user authorization file (UAF)

•

Subdirectory defined in the MAIL user profile

•

Default file type of MAI

MAIL$_MAILFILE_NAME

MAIL$_MAILFILE_NAME specifies the name of the mail file that MAIL
should open. The buffer address field points to a buffer that contains a
character string of 0 to 255 characters.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
If you do not specify MAIL$_MAILFILE_NAME, the default mail file name

is MAIL.
MAIL$_MAILFILE_WASTEBASKET_NAME

MAILFILE_WASTEBASKET_NAME specifies a new folder name for the
wastebasket in the specified mail file. The buffer address field points to
a buffer that contains a character string of 1 to 39 characters.

out_item_list
VMS usage: itmlst_3
longword
access:
write only
mechanism: by reference
Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.

type:

See MAIL$MAILFILE_BEGIN for a description of an output descriptor.
Output Item Codes
MAIL$_MAILFILE_RESULTSPEC

When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL returns the
resultant mail file specification. The buffer address field points to a
buffer that receives a character string from 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

DESCRIPTION

MAIL-50

If a mail file is not specified, the currently open mail file is used.

MAIL Utility Routines
MAIL$MAILFILE_MODIFV

CONDITION
VALUES
RETURNED

MAIL$_1LLFOLNAM

The specified folder name is illegal.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOTISAM

The format of the message file is not ISAM.

MAIL$_OPEN IN

MAIL cannot open the file as input.

SS$_ACCVIO

Access violation.

Any condition value returned by $CLOSE, $FIND, $PUT, and $UPDATE.

MAIL-51

MAIL Utility Routines
MAIL$MAILFILE_OPEN

MAIL$MAILFILE_OPEN
Opens a specified mail file for processing. You must use this routine to open
a mail file before you can do either of the following:
Call any mail file routines to manipulate mail files
Call message routines to read messages from the specified mail file

FORMAT

MAIL$MAILFILE_OPEN

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_list,
ouLitem_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
modify
by reference

Mail file context information to be passed to mail file routines. The
context argument is the address of a longword that contains mail file
context information returned by MAIL$MAILFILE_BEGIN.

in_item_list
VMS usage:
type:
access:
mechanism:

ltmlst_3
longword (unsigned)
read only
by reference

Item list specifying options for the routine. The in_item_list argument is
the address of a list of item descriptors, each of which specifies an option
and provides the information needed to perform the operation.
The item list is terminated by longword value of 0.
See MAIL$MAILFILE_BEGIN for a description of an input item
descriptor.
Input Item Codes

MAIL$_MAILFILE_DEFAULT_NAME

MAIL$_MAILFILE_DEFAULT_NAME specifies the default file
specification MAIL$MAILFILE_OPEN should use when opening a mail
MAIL-52

MAIL Utility Routines
MAIL$MAILFILE_OPEN

file. The buffer address field points to a character string of 0 to 255
characters that defines the default file specification.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
If you specify the value 0 in buffer length field of the item descriptor,

MAIL$MAILFILE_OPEN uses the current default directory as the default
mail file specification.
If you do not specify MAIL$_MAILFILE_DEFAULT_NAME,

MAIL$MAILFILE_OPEN creates the default mail file specification from
the following sources:
•

Disk and directory defined in the caller's user authorization file (UAF)

•

Subdirectory defined in the MAIL user profile

•

Default file type of MAI

MAIL$_MAILFILE_NAME
MAIL$_MAILFILE_NAME specifies the name of the mail file
MAIL$MAILFILE_OPEN should open. The buffer address field points to
a buffer that contains a character string of 0 to 255 characters.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
If you do not MAIL$_MAILFILE_NAME, the default mail file name is
MAIL.

out_item_list
VMS usage: ltmlst_3
type:
longword
access:
write only
mechanism: by reference
Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.

See MAIL$MAILFILE_BEGIN for a description of an output item
descriptor.
Output Item Codes

MAIL$_MAILFILE_DELETED_BYTES
When you specify MAIL$_MAILFILE_DELETED_BYTES,
MAIL$MAILFILE_OPEN returns the number of deleted bytes in the
specified mail file as a longword value.
MAIL$_MAILFILE_INDEXED
When you specify MAIL$_MAILFILE_INDEXED, MAIL$MAILFILE_
OPEN returns a Boolean TRUE if the opened mail file format is ISAM.
The buffer length field points to a longword that receives the Boolean
value.

MAIL-53

MAIL Utility Routines
MAIL$MAILFILE_OPEN

MAIL$_MAILFILE_RESULTSPEC

When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL$MAILFILE_
OPEN returns the resultant mail file specification. The buffer address
field of the item descriptor points to a buffer that receives a character
string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MAILFILE_WASTEBASKET

When you specify MAIL$_MAILFILE_WASTEBASKET,
MAIL$MAILFILE_OPEN returns the name of the wastebasket for the
specified mail file. The buffer address field of the item descriptor points
to a buffer that receives a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

DESCRIPTION
CONDITION
VALUES
RETURNED

The default mail file specification is MAIL.MAI in the mail subdirectory.

MAIL$_FILEOPEN

The mail file is already open.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOMSGS

No messages are available.

SS$_ACCVIO

Access violation.

Any condition value returned by LIB$GET_VM and $CONNECT, and $OPEN.

MAIL-54

MAIL Utility Routines
MAIL$MAILFILE_PURGE_WASTE

MAIL$MAILFILE_PURGE_WASTE
Deletes messages contained in the wastebasket folder of the currently open
mail file.

FORMAT

MAIL$MAILFILE_PURGE_WASTE

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

context,
in_item_list,
out_item_list

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage: context
type:
longword (unsigned)
access:
modify
mechanism: by reference
Mail file context information to be passed to other mail file routines. The
context argument is the address of a longword that contains mail file
context information.

The item list is terminated by longword value of 0.
See MAIL$MAILFILE_BEGIN for a description of an input item
descriptor.
Input Item Codes
MAIL$_MAILFILE_RECLAIM

The Boolean item code MAIL$_MAILFILE_RECLAIM specifies that
MAIL$MAILFILE_PURGE_WASTE purge the wastebasket folder and
reclaim deleted space in the mail file.
Specify the value 0 in the buffer length field of the item descriptor.
MAIL-55

MAIL Utility Routines
MAIL$MAILFILE_PURGE_WASTE

MAIL$_MAILFILE_RECLAIM explicitly requests a reclaim operation and
overrides the deleted bytes threshold regardless of the number of deleted
bytes during a mail file purge operation.

out_item_list
VMS usage:
type:
access:
mechanism:

itmlst_3
longword
write only
by reference

MAIL$_MAILFILE_DATA_RECLAIM

When you specify MAIL$_MAILFILE_DATA_RECLAIM,
MAIL$MAILFILE_PURGE_WASTE returns the number of data buckets
reclaimed during the reclaim operation as a longword value.
MAIL$_MAILFILE_DATA_SCAN

When you specify MAIL$_MAILFILE_DATA_SCAN, MAIL$MAILFILE_
PURGE_WASTE returns the number of data buckets scanned during the
reclaim operation as a longword value.
MAIL$_MAILFILE_INDEX_RECLAIM

When you specify MAIL$_MAILFILE_INDEX_RECLAIM, MAIL returns
the number of index buckets reclaimed during a reclaim operation as a
longword value.
MAIL$_MAILFILE_DELETED_BVTES

When you specify MAIL$_MAILFILE_DELETED_BYTES,
MAIL$MAILFILE_PURGE_WASTE returns the number of bytes deleted
from the mail file as a longword value.
MAIL$_MAILFILE_MESSAGES_DELETED

When you specify MAIL$_MAILFILE_MESSAGES_DELETED,
MAIL$MAILFILE_PURGE_WASTE returns the number of deleted
messages as a longword value.
MAIL$_MAILFILE_TOTAL_RECLAIM

When you specify MAIL$_MAILFILE_TOTAL_RECLAIM,
MAIL$MAILFILE_PURGE_WASTE returns the number of bytes reclaimed
due to a reclaim operation as a longword value.

DESCRIPTION

If you specify the MAIL$_MAILFILE_RECLAIM item descriptor, all the

bytes deleted from the mail file by this routine are reclaimed.

MAIL-56

MAIL Utility Routines
MAIL$MAILFILE_PURGE_WASTE

CONDITION
VALUES
RETURNED

MAIL$_NORMAL

Normal successful completion.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOFILEOPEN

No mail file is currently open.

MAIL$_NOTISAM

The message file format is not ISAM.

SS$_ACCVIO

Access violation.

MAIL-57

MAIL Utility Routines
MAIL$MESSAGE_BEGIN

MAIL$MESSAGE_BEGIN
Begins message processing. You must call this routine before calling any
other message routines.

FORMAT

MAIL$MESSAGE_BEGIN

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

context, in_item_list,
out_item_list

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage:
type:
access:
mechanism:

context
longword {unsigned)
modify
by reference

Message context information to be passed to various message routines.
The context argument is the address of a longword that contains message
context information.
You should specify the value of this argument as 0 in the first of a
sequence of calls to message routines. In following calls, you should
specify the message context value returned by this routine.

in_item_list
VMS usage:
type:
access:
mechanism:

itmlst_3
longword {unsigned)
read only
by reference

MAIL-58

MAIL Utility Routines
MAIL$MESSAGE_BEGIN

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

Item Code

Buffer Length

Buffer Address
Return Length Address
ZK-1705-GE

ln_item_list Item Descriptor Fields
buffer length

A word specifying the length (in bytes) of the buffer that supplies the
information needed by the routine to process the specified item code. The
required length of the buffer depends on the item code specified in the
item code field of the item descriptor. If the value of buffer length is too
small, the routine truncates the data.
item code

A word containing a user-supplied symbolic code that specifies an option
for the MAIL operation. These codes are defined by the $MAILDEF macro.
See Input Item Codes for a description of these codes.
buffer address

A longword containing the address of the buffer that supplies information
to the routine.
return length address

This field is not used.
MAIL$MESSAGE_BEGIN Input Item Codes
MAIL$_MESSAGE_FILE_CTX

MAIL$_MESSAGE_FILE_CTX specifies the mail file context received
from MAIL$MAILFILE_BE(HN to be passed to the message routines.
The buffer address field of the item descriptor points to a longword that
contains mail file context information.
The item code MAIL$_MESSAGE_FILE_CTX is required.

out_item_list
VMS usage: itmlst_3
type:
longword
access:
write only
mechanism: by reference

MAIL-59

MAIL Utility Routines
MAIL$MESSAGE_BEGIN

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

Item Code

0
Buffer Length

Buffer Address
Return Length Address
ZK-1705-GE

Out_ltem_list Item Descriptor Fields
buffer length
A word containing a user-supplied integer specifying the length (in bytes)
of the buffer in which the routine is to write the information. The length
of the buffer needed depends on the item code specified in the item code
field of the item descriptor. If the value of buffer length is too small, the
routine truncates the data.
Item code
A word containing a user-supplied symbolic code specifying the item of
information that the routine is to return. These codes are defined by
the $MAILDEF macro. See Output Item Codes for a description of these
codes.
buffer address
A longword containing the user-supplied address of the buffer in which the
routine is to write the information.
return length address
A longword containing the user-supplied address of a word in which the
routine writes the actual length in bytes of the information it returned.
Output Item Codes
MAIL$_MESSAGE_SELECTED .

When you specify MAIL$_MESSAGE_SELECTED, MAIL$MESSAGE_
BEGIN returns the number of messages selected (from sequential mail
files only) as a longword value.

DESCRIPTION

MAIL-60

MAIL$MESSAGE_BEGIN creates and initializes a message context for
subsequent calls to message routines.

MAIL Utility Routines
MAIL$MESSAGE_BEGIN

CONDITION
VALUES
RETURNED

MAIL$_1LLCTXADR

The context block address is illegal.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOFILEOPEN

The mail file is not open.

MAIL$_WRONGCTX

The context block is incorrect.

MAIL$_WRONG FILE

The specified file is incorrect in this context.

SS$_ACCVIO

Access violation.

Any condition value returned by $GET and LIB$GET_VM.

MAIL-61

MAIL Utility Routines
MAIL$MESSAGE_COPY

MAIL$MESSAGE_COPY
Copies messages between files or folders.

FORMAT

MAIL$MESSAGE_COPY

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_/ist,
out_item_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage: context
type:
longword (unsigned)
access:
modify
mechanism: by reference
Message context information to be passed to message routines. The
context argument is the address of a longword that contains message
context information returned by MAIL$MESSAGE_BEGIN.

You should specify this argument as 0 in the first of a sequence of calls
to message routines. In following calls, you should specify the message
context value returned by the previous routine.

in- item- list

The item list is terminated by longword value of 0.
See MAIL$MESSAGE_BEGIN for a description of an input item
descriptor.
Input Item Codes
MAIL$_MESSAGE_BACK

When you specify the Boolean item code MAIL$_MESSAGE_BACK,
MAIL$MESSAGE_COPY copies the message preceding the current
message.
MAIL-62

MAIL Utility Routines
MAIL$MESSAGE_COPY

Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
Do not specify MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and
MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_COPY.
MAIL$_MESSAGE_DEFAULT_NAME

MAIL$_MESSAGE_DEFAULT_NAME specifies the default file
specification of a mail file to open in order to copy a message .. The buffer
address field of the item descriptor points to a buffer that contains a
character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_DELETE

When you specify the Boolean item code MAIL$_MESSAGE_DELETE,
MAIL$MESSAGE_COPY deletes the message in the current folder after
the message has been copied to a destination folder.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
Specify MAIL$_MESSAGE_DELETE to emulate the operation of MAIL
MOVE or FILE command.
MAIL$_MESSAGE_FILE_ACTION

MAIL$_MESSAGE_FILE_ACTION specifies the address of the mail file
action routine called if a mail file is to be created. Two parameters are
passed as follows:
•

User data longword

•

Address of the descriptor of the file name to be created

The buffer address field of the item descriptor points to a longword that
denotes a procedure entry mask.
MAIL$_MESSAGE_FILENAME

MAIL$_MESSAGE_FILENAME specifies the name of the mail file to
which the current message will be moved. The buffer address field of the
item descriptor points to a buffer that contains a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_FOLDER

MAIL$_MESSAGE_FOLDER specifies the name of the target folder for
moving mail messages. The buffer address field of the item descriptor
points to a buffer that contains a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
The item code MAIL$_MESSAGE_FOLDER is required.

MAIL-63

MAIL Utility Routines
MAIL$MESSAGE_COPV

MAIL$_MESSAGE_FOLDER_ACTION

MAIL$_MESSAGE_FOLDER_ACTION specifies the entry point address of
the folder action routine called if a folder is to be created. Two parameters
are passed as follows:
•

User data longword

•

Address of a descriptor of the folder name to be created.

The buffer address field of the item descriptor points to a longword that
specifies a procedure entry mask.
MAIL$_MESSAGE_ID

MAIL$_MESSAGE_ID specifies the message identification number of the
message on which the operation is to be performed. The buffer address
field of the item descriptor points to a longword that contains the message
identification number.
Do not specify MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and
MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_COPY.
MAIL$_MESSAGE_NEXT

When you specify the Boolean item code MAIL$_MESSAGE_NEXT, MAIL
copies the message following the current message.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
Do not specify MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and
MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_COPY.
MAIL$_MESSAGE_USER_DATA

MAIL$_MESSAGE_USER_DATA specifies data passed to the folder
action and mail file action routines. The buffer address field of the
item descriptor points to a user data longword.
Specify MAIL$_MESSAGE_USER_DATA with the item codes MAIL$_
MESSAGE_FILE_ACTION and MAIL$_MESSAGE_FOLDER_ACTION
only.

type:

See MAIL$MESSAGE_BEGIN for a description of an output item
descriptor.

MAIL-64

MAIL Utility Routines
MAIL$MESSAGE_COPV

Output Item Codes
MAIL$_MESSAGE_FILE_CREATED

When you specify the Boolean item code MAIL$_MESSAGE_FILE_
CREATED, MAIL$MESSAGE_COPY returns the value of the file created
flag as longword value.
MAIL$_MESSAGE_FOLDER_CREATED

When you specify the Boolean item code MAIL$_MESSAGE_FOLDER_
CREATED, MAIL$MESSAGE_COPY returns the value of the folder
created flag as a longword value.
MAIL$_MESSAGE_RESULTSPEC

When you specify MAIL$_MESSAGE_RESULTSPEC, MAIL$MESSAGE_
COPY returns the mail file resultant file specification. The buffer
address field of the item descriptor points to a buffer that receives a
character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

DESCRIPTION

If you do not specify a file name, the routine copies the message to another

folder in the currently open mail file. The target mail file must be an
ISAM-format file.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

MAIL$_MSGINFO

Informational records are successully returned.

MAIL$_MSGTEXT

Text record is successfully returned.

MAIL$_BADVALUE

The specified keyword value is invalid.

MAIL$_CONITMCOD

The specified item codes define conflicting operations.

MAIL$_DATIMUSED

The date and time is currently used in the specified
file.

MAIL$_DELMSG

The message is deleted.

MAIL$_1LLCTXADR

The context block address is illegal.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOFILEOPEN

The mail file is not open.

MAIL$_NOMOREREC

No more records can be found.

MAIL$_NOTREADIN

The operation is invalid; you are not reading a
message.

MAIL-65

MAIL Utility Routines
MAIL$MESSAGE_COPV

MAIL$_RECTOBIG

The record is too large for the MAIL buffer.

MAIL$_WRONGCTX

The context block is incorrect.

MAIL$_WRONG FILE

The specified file is incorrect in this context.

SS$_1VDEVNAM

The device name is invalid.

SS$_ACCVIO

Access violation.

Any condition value returned by $CONNECT, $CREATE, $OPEN, $WRITE, $READ,
and $PUT.

MAIL-66

MAIL Utility Routines
MAIL$MESSAGE_DELETE

MAIL$MESSAGE_DELETE
Deletes a specified message from the currently selected folder.

FORMAT

MAIL$MESSAGE_DELETE

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

context, in_item_list,
out_item_list

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

The item list is terminated by longword value of 0.
See MAIL$MESSAGE_BEGIN for a description of an input item
descriptor.
Input Item Codes
MAIL$_MESSAGE_ID

MAIL$_MESSAGE_ID specifies the message identification number of the
message on which the operation is to be performed. The buffer address
field points to a longword that contains the message identification number.
The item code MAIL$_MESSAGE_ID is required.

MAIL-67

MAIL Utility Routines
MAIL$MESSAGE_DELETE

out_item_list
VMS usage: itmlst_3
type:
longword
access:
write only
mechanism: by reference
Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.

See MAIL$MESSAGE_BEGIN for a description of an output item
descriptor.
Output 'Item Codes
None.

DESCRIPTION

CONDITION
VALUES
RETURNED

MAIL-68

When you delete a message from a selected folder, it is moved to the
wastebasket folder. You cannot delete a message from the wastebasket
folder. You must use the MAIL$MESSAGE_PURGE_WASTE routine to
empty the wastebasket folder.

SS$NORMAL

Normal successful completion.

MAIL$_1LLCTXADR

The context block address is illegal.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOFILEOPEN

The mail file is not open.

MAIL$_WRONGCTX

The context block is incorrect.

MAIL$_WRONG FILE

The specified file is incorrect in this context.

SS$_ACCVIO

Access violation.

MAIL Utility Routines
MAIL$MESSAGE_END

MAIL$MESSAGE_END
Ends message processing.

FORMAT

MAIL$MESSAGE_END

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_/ist,
out- item- list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
context
longword (unsigned)
modify
by reference
Message context information to be passed to message routines. The
context argument is the address of a longword that contains message
context information returned by MAIL$MESSAGE_BEGIN. If message
processing ends successfully, the argument context is changed to 0.
VMS usage:
type:
access:
mechanism:

VMS usage:
type:
access:
mechanism:

The item list is terminated by longword value of 0.
See MAIL$MESSAGE_BEGIN for a description of an input item
descriptor.
Input Item Codes
None.

MAIL-69

MAIL Utility Routines
MAIL$MESSAGE_END

out_item_list
VMS usage: itmlst_3
type:
longword
access:
write only
mechanism: by reference

Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.
See MAIL$MESSAGE_BEGIN for a description of an output item
descriptor.
Output Item Codes
None.

DESCRIPTION

CONDITION
VALUES
RETURNED

The MAIL$MESSAGE_END routine deallocates the message context
created by MAIL$MESSAGE_BEGIN as well as any dynamic memory
allocated by other message routines.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

SS$_ACCVIO

Access violation.

Any condition value returned by LIB$FREE_VM.

MAIL-70

MAIL Utility Routines
MAIL$MESSAGE_GET

MAIL$MESSAGE_GET
Retrieves a message from the set of currently selected messages.

FORMAT

MAIL$MESSAGE_GET

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_list,
ouLitem_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

The item list is terminated by longword value of 0.
See MAIL$MESSAGE_BEGIN for a description of an input item
descriptor.
Input Item Codes
MAIL$_MESSAGE_AUTO_NEWMAIL

When you specify the Boolean item code MAIL$_MESSAGE_AUTO_
NEWMAIL, MAIL$MESSAGE_GET places a new message in the MAIL
folder as it is read automatically.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.

MAIL-71

MAIL Utility Routines
MAIL$MESSAGE_GET

MAIL$_MESSAGE_BACK
When you specify the Boolean item code MAIL$_MESSAGE_BACK,
MAIL$MESSAGE_GET reads the message identification number of a
specified message to return the first record of the preceding message.

Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_
MESSAGE_CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_
NEXT in the same call to MAIL$MESSAGE_GET.
MAIL$_MESSAGE_CONTINUE
When you specify the Boolean item code MAIL$_MESSAGE_CONTINUE,
MAIL$MESSAGE_GET reads the message identification number of a
specified message to return the next text record of the current message.

Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_
MESSAGE_CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_
NEXT in the same call to MAIL$MESSAGE_GET.
MAIL$_MESSAGE_ID
MAIL$_MESSAGE_ID specifies the message identification number of a
message on which an operation is to be performed. The buffer address
field of the item descriptor points to a longword that contains the message
identification number.

Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_
MESSAGE_CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_
NEXT in the same call to MAIL$MESSAGE_GET.
MAIL$_MESSAGE_NEXT
When you specify the Boolean item code MAIL$_MESSAGE_NEXT,
MAIL$MESSAGE_GET reads the message identification number of a
specified message to return the first record of the message following the.
current message.

See MAIL$MESSAGE_BEGIN for a description of an output item
descriptor.
MAIL-72

MAIL Utility Routines
MAIL$MESSAGE_GET

Output Item Codes
MAIL$_MESSAGE_BINARY_DATE

When you specify MAIL$_MESSAGE_BINARY_DATE, MAIL$MESSAGE_
GET returns the message arrival date as a quadword binary value.
MAIL$_MESSAGE_CC

When you specify MAIL$_MESSAGE_CC, MAIL$MESSAGE_GET returns
the CC: field of the current message. The buffer address field of the
item descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_CURRENT_ID

When you specify MAIL$_MESSAGE_CURRENT_ID, MAIL$MESSAGE_
GET returns the message identification number of the current message.
The buffer address field of the item descriptor points to a longword that
receives the message identifier number.
MAIL$_MESSAGE_DATE

When you specify MAIL$_MESSAGE_DATE, MAIL$MESSAGE_GET
returns the message creation date string. The buffer address field of the
item descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_EXTID

MAIL$MESSAGE_EXTID specifies the external message identification
number of the current message. The buffer address field of the item
descriptor points to a buffer that contains a character string 0 to 255
characters long.
MAIL$_MESSAGE_FROM

When you specify MAIL$_MESAGE_FROM, MAIL$MESSAGE_GET
returns the From: field of the specified message. The buffer address
field of the item descriptor points to a buffer that receives a character
string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_RECORD

When you specify MAIL$_MESSAGE_RECORD, MAIL$MESSAGE_GET
returns a record of the message. The buffer address field of the item
descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_RECORD is valid only when specified with the item
code MAIL$_MESSAGE_CONTINUE.

MAIL-73

MAIL Utility Routines
MAIL$MESSAGE_GET

Do not specify MAIL$_MESSAGE_RECORD with the following item codes:
•

MAIL$_MESSAGE_BACK

•

MAIL$_MESSAGE_ID

•

MAIL$_MESSAGE_NEXT

MAIL$...;.MESSAGE_RECORD_TYPE

When you specify MAIL$_MESSAGE_RECORD_TYPE,
MAIL$MESSAGE_GET returns the record type. A record may be either
header information (MAIL$_MESSAGE_HEADER) or text (MAIL$_
MESSAGE_TEXT). The buffer address field of the item descriptor points
to a word that receives the record type.
MAIL$_MESSAGE_RETURN_FLAGS

When you specify MAIL$_MESSAGE_RETURN_FLAGS,
MAIL$MESSAGE_GET returns the ·MAIL system flag for the current
message as a 2-byte bitmask value.
MAIL$_MESSAGE_SENDER

When you specify MAIL$_MESSAGE_SENDER, MAIL$MESSAGE_GET
returns the name of the sender of the current message. The buffer
address field of the item descriptor points to a buffer that receives a
character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_SIZE

When you specify MAIL$_MESSAGE_SIZE, MAIL$MESSAGE_GET
returns the size in records of the current message as a longword value.
MAIL$_MESSAGE_SUBJECT

When you specify MAIL$_MESSAGE_SUBJECT, MAIL$MESSAGE_GET
returns the Subject: field of the specified message. The buffer address
field of the item descriptor points to a buffer that receives a character
string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_TO

When you specify MAIL$_MESSAGE_TO, MAIL$MESSAGE_GET returns
the To: field of the specified message. The buffer address field of the
item descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

DESCRIPTION

MAIL-74

The first time the MAIL$MESSAGE_GET routine is called, the message
information is returned for the first requested message, and the status
returned is MAIL$_MSGINFO. Subsequent calls to MAIL$MESSAGE_
GET with the MAIL$_MESSAGE_CONTINUE item code return the
message text records with the status MAIL$_MSGTEXT, until no more
records are left, when MAIL$_NOMOREREC is returned.

MAIL Utility Routines
MAIL$MESSAGE_GET

CONDITION
VALUES
RETURNED

MAIL$_MSGINFO

Informational records are successully returned.

MAIL$_MSGTEXT

Text record is successfully returned.

MAIL$_tLLCTXADR

The context block address is illegal.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOFILEOPEN

The mail file is not open.

MAIL$_NOMOREREC

No more records can be found.

MAIL$_NOTREADIN

The operation is invalid; you are not reading a
message.

MAIL$_RECTOBIG

The record is too large for the MAIL buffer.

MAIL$_WRONGCTX

The context block is incorrect.

MAIL$_WRONG FILE

The specified file is incorrect in this context.

SS$_ACCVIO

Access violation.

Any condition value returned by $FIND and $UPDATE.

MAIL-75

MAIL Utility Routines
MAIL$MESSAGE_INFO

MAIL$MESSAGE_INFO
Obtains information about a specified message contained in the set of
currently selected messages.

FORMAT

MAIL$MESSAGE_INFO

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_list,
out_item_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

VMS usage:
type:
access:
mechanism:

The item list is terminated by longword value of 0.
See MAIL$MESSAGE_BEGIN for a description of an input descriptor.
Input ~l~m Codes
MAIL$_MESSAGE_BACK

When you specify Boolean item code MAIL$_MESSAGE_BACK,
MAIL$MESSAGE_INFO reads the message identification number of the
current message and returns the message preceding the current message.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.

MAIL-76

MAIL Utility Routines
MAIL$MESSAGE_INFO

Do not specify MAIL$_MESSAGE_BACK,MAIL$_MESSAGE_ID, and
MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_INFO.
MAIL$_MESSAGE_ID

MAIL$_MESSAGE_ID specifies the message identification number of the
message on which the operation is to be performed. The buffer address
field of the item descriptor points to a longword that contains the message
identification number.
Do not specify MAIL$_MESSAGE_BACK,MAIL$_MESSAGE_ID, and
MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_INFO.
MAIL$_MESSAGE_NEXT

When you specify the Boolean item code MAIL$_MESSAGE_NEXT,
MAIL$MESSAGE_INFO reads the message identification number of
the current message and returns the message that follows it.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
Do not specify MAIL$_MESSAGE_BACK,MAIL$_MESSAGE_ID, and
MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_INFO.

out_item_list
VMS usage: itmlst_3
type:
longword
access:
write only
mechanism: by reference

Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.
See MAIL$MESSAGE_BEGIN for a description of an output item
descriptor.
Output Item Codes
MAIL$_MESSAGE_BINARY_DATE

When you specify MAIL$_MESSAGE_BINARY_DATE, MAIL$MESSAGE_
INFO returns the message arrival date as a quadword binary value.
MAIL$_MESSAGE_CC

When you specify MAIL$_MESSAGE_CC, MAIL$MESSAGE_INFO
returns the CC: field of the current message. The buffer address field of
the item descriptor points to a buffer that receives a character string 0 to
255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_CURRENT_ID

When you specify MAIL$_MESSAGE_ID, MAIL$MESSAGE_INFO returns
the message identification number of the current message. The buffer
address field of the item descriptor points to a longword that receives the
message identification number of the current message.

MAIL-77

MAIL Utility Routines
MAIL$MESSAGE_INFO

MAIL$_MESSAGE_DATE
When you specify MAIL$_MESSAGE_DATE, MAIL$MESSAGE_INFO
returns the message creation date string. The buffer address field of the
item descriptor points to a buffer that receives a character string 0 to 255
characters long.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
·
MAIL$_MESSAGE_EXTID
When you specify MAIL$_MESSAGE_EXTID, MAIL$MESSAGE_INFO
returns the external identification number of the current message as a
string. The buffer address field of the item descriptor points to a buffer
that receives a character string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_FROM
When you specify MAIL$_MESSAGE_FROM, MAIL$MESSAGE_INFO
returns the From: field of the specified message. The buffer address
field of the item descriptor points to a buffer that receives a character
string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_REPLY_PATH
When you specify MAIL$_MESSAGE_REPLY_PATH, MAIL$MESSAGE_
INFO returns the reply path of the specified message. The buffer
address field of the item descriptor points to a buffer that receives a
character string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_RETURN_FLAGS
When you specify MAIL$_MESSAGE_RETURN_FLAGS,
MAIL$MESSAGE_INFO returns the MAIL system flag values for· the
current message as a 2-byte bitvector value.
MAIL$_MESSAGE_SENDER
When you specify MAIL$_MESSAGE_SENDER, MAIL$MESSAGE_INFO
returns the name of the sender of the current message. The buffer
address field of the item descriptor points to a buffer that receives a
character string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_SIZE
When you specify MAIL$_MESSAGE_SIZE, MAIL$MESSAGE_INFO
returns the size of the current message in records as a longword value.

MAIL-78

MAIL Utility Routines
MAIL$MESSAGE_INFO

MAIL$_MESSAGE_SUBJECT

When you specify MAIL$_MESSAGE_SUBJECT, MAIL$MESSAGE_INFO
returns the Subject: field of the specified message. The buffer address
field of the item descriptor points to a buffer that receives a character
string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_TO

When you specify MAIL$_MESSAGE_TO, MAIL$MESSAGE_INFO
returns the Tu: field of the specified message. The buffer address field of
the item descriptor points to a buffer that receives a character string 0 to
255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

DESCRIPTION

CONDITION
VALUES
RETURNED

MAIL$MESSAGE_INFO and MAIL$MESSAGE_GET perform the same
function. MAIL$MESSAGE_INFO returns information about messages
faster than MAIL$MESSAGE_GET; however, MAIL$MESSAGE_INFO
does not return the actual text of the messages.

MAIL$_CONITMCOD

The specified item codes define conflicting operations.

MAIL$_DELMSG

The message is deleted.

MAIL$_1LLCTXADR

The context block address is illegal.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOFILEOPEN

The mail file is not open.

MAIL$_NOMOREMSG

No more messages.

MAIL$_WRONGCTX

The context block is incorrect.

MAIL$_WRONG FILE

The specified file is incorrect in this context.

SS$_ACCVIO

Access violation.

Any condition value returned by LIB$GET_VM.

MAIL-79

MAIL Utility Routines
MAIL$MESSAGE_MODIFY

MAIL$MESSAGE_MODIFY
Modifies message information.

FORMAT

MAIL$MESSAGE_MODIFY

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_list,
out_item_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

The item list is terminated by longword value of 0.
See MAIL$MESSAGE_BEGIN for a description of an input item
descriptor.
Input Item Codes
MAIL$_MESSAGE_BACK

When you specify the Boolean item code MAIL$_MESSAGE_BACK,
MAIL$MESSAGE_MODIFY reads the message identification number of
the specified message in order to return the first record in the preceding
message.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL-80

MAIL Utility Routines
MAIL$MESSAGE_MODIFY

Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_
MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same call to
MAIL$MESSAGE_MODIFY.
MAIL$_MESSAGE_FLAGS

MAIL$_MESSAGE_FLAGS specifies system flags for new mail. The
buffer address field of the item descriptor points to a word that contains
bitvector offsets. The following offsets can be used to modify the 2-byte
bitvector:
•

MAIL$V_REPLIED

•

MAIL$V_MARKED

MAIL$_MESSAGE_ID

MAIL$_MESSAGE_ID specifies the message identification number of the
message on which an operation is to be performed. The buffer address
field of the item descriptor points to a longword that contains the message
identification number.
Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_
MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same call to
MAIL$MESSAGE_MODIFY.
MAIL$_MESSAGE_NEXT

When you specify the Boolean item code MAIL$_MESSAGE_NEXT,
MAIL$MESSAGE_NEXT reads the message identification number of a
message and returns the first record in the message following the current
message.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_
MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same call to
MAIL$MESSAGE_MODIFY.

out_item_list
VMS usage:
type:
access:
mechanism:

itmlst_3
longword
write only
by reference

Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.
See MAIL$MESSAGE_BEGIN for a description of an output item
descriptor.
Output Item Codes
MAIL$_MESSAGE_CURRENT_ID

When you specify MAIL$_MESSAGE_CURRENT_ID, MAIL$MESSAGE_
MODIFY returns the message identification number of the current
message. The buffer address field of the item descriptor points to a
longword that receives the message identification number.

MAIL-81

MAIL Utility Routines
MAIL$MESSAGE_MODIFY

CONDITION
VALUES
RETURNED

MAIL$_CONITMCOD

The specified item codes define conflicting operations.

MAIL$_DELMSG

The message is deleted.

MAIL$_1LLCTXADR

The context block address is illegal.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOFILEOPEN

The mail file is not open.

MAIL$_NOMOREMSG

No more messages.

MAIL$_WRONGCTX

The context block is incorrect.

MAIL$_WRONG FILE

The specified file is incorrect in this context.

SS$_ACCVIO

Access violation.

Any condition value returned by $FIND and $UPDATE.

MAIL-82

MAIL Utility Routines
MAIL$MESSAGE_SELECT

MAIL$MESSAGE_SELECT
Selects a message or messages from the currently open mail file. Before you
attempt to read a message, you must select it.

FORMAT

MAIL$MESSAGE_SELECT context, in_item_list,
ouLitem_list

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
modify
by reference

Message context information to be passed to message routines. The
context argument is the address of a longword that contains message
context information returned by MAIL$MESSAGE_BEGIN.

in_item_list
VMS usage:
type:
access:
mechanism:

itmlst_3
longword (unsigned)
read only
by reference

Item list specifying options for the routine. The in_item_list argument is
the address of a list of item descriptors, each of which specifies an option
and provides the information needed to perform the operation.
The item list is terminated by longword value of 0.
See MAIL$MESSAGE_BEGIN for a description of an input item
descriptor.
Input Item Codes
MAIL$_MESSAGE_BEFORE

When you specify MAIL$_MESSAGE_BEFORE, MAIL$MESSAGE_
SELECT selects a message received before a specified date and time.
The buffer address field of the item descriptor points to a buffer that
contains a character string 0 to 255 characters long in absolute time.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL-83

MAIL Utility Routines
MAIL$MESSAGE_SELECT

MAIL$_MESSAGE_CC_SUBSTRING

MAIL$_MESSAGE_CC_SUBSTRING specifies a character string that
must match a substring contained in the CC: field of the specified message.
If the strings match, the message is selected. The buffer address field of
the item descriptor points to a buffer that receives a character string 0 to
255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_FLAGS

MAIL$_MESSAGE_FLAGS specifies bit masks that must be initialized
to 1.
MAIL$_MESSAGE_FLAGS_MBZ

MAIL$_MESSAGE_FLAGS_MBZ specifies MAIL system flags that must
be set to 0.
MAIL$_MESSAGE_FOLDER

MAIL$_MESSAGE_FOLDER specifies the name of the folder that contains
messages to be selected.
The buffer address field of the item descriptor points to a buffer that
contains a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
This item code is required.
MAIL$_MESSAGE_FROM_SUBSTRING

MAIL$_MESSAGE_FROM_SUBSTRING specifies a user-specified
character string that must match the substring contained in the From:
field of a specified message. If the strings match, the message is selected.
The buffer address field of the item descriptor points to a buffer that
receives a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_SINCE

When you specify MAIL$_MESSAGE_SINCE, MAIL selects a message
received since a specified date and time.
The buffer address field of the item descriptor points to a buffer that
contains a character string 0 to 255 characters long in absolute time.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_TO_SUBSTRING

MAIL$_MESSAGE_TO_SUBSTRING specifies a user-specified character
string that must match a substring contained in the To: field of a specified
message. If the strings match, the message is selected.
The buffer address field of the item descriptor points to a buffer that
contains a character string 0 to 255 characters long.

MAIL-84

MAIL Utility Routines
MAIL$MESSAGE_SELECT

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_MESSAGE_SUBJ_SUBSTRING
MAIL$_MESSAGE_SUBJ_SUBSTRING specifies a user-specified
character string that must match a substring contained in the Subject:
field of a specified message. If the strings match, the message is selected.

The buffer address field of the item descriptor points to a buffer that
contains a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

See MAIL$MESSAGE_BEGIN for a description of an output item
descriptor.
Output Item Codes
MAIL$_MESSAGE_SELECTED
When you specify MAIL$_MESSAGE_SELECTED, MAIL$MESSAGE_
SELECT returns the number of selected messages as a longword value.

DESCRIPTION

CONDITION
VALUES
RETURNED

MAIL$MESSAGE_SELECT deselects previously selected messages
whether or not you request a valid selection.

MAIL$_1LLCTXADR

The context block address is illegal.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_1NVQUAVAL

The specified qualifier is invalid

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOFILEOPEN

The mail file is not open.

MAIL$_NOTEXIST

The specified folder does not exist.

MAIL$_NOTISAM

The operation cannot be performed on a non-ISAM
file.

MAIL-85

MAIL Utility Routines
MAIL$MESSAGE_SELECT

MAIL$_WRONGCTX

The context block is incorrect.

MAIL$_WRONGFILE

The specified file is incorrect in this context.

SS$_ACCVIO

Access violation.

Any condition value returned by LIB$GET_ VM.

MAIL-86

MAIL Utility Routines
MAIL$SEND_ABORT

MAIL$SEND_ABORT
Cancels a currently executing send operation.

FORMAT

MAIL$SEND_ABORT context, in_item_list,
out_ item_list

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
context
longword (unsigned)
modify
by reference
Send context information to be passed to send routines. The context
argument is the address of a longword that contains send context
information returned by MAIL$SEND_BEGIN.
VMS usage:
type:
access:
mechanism:

VMS usage:
type:
access:
mechanism:

The item list is terminated by longword value of 0.
See MAIL$SEND_BEGIN for a description of an input item descriptor.
Input Item Codes
None.

MAIL-87

MAIL Utility Routines
MAIL$SEND_ABORT

out_item_list
VMS usage:
type:
access:
mechanism:

itmlst_3
longword
write only
by reference

Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.
See MAIL$SEND_BEGIN for a description of an output item descriptor.
Output Item Codes
None.

DESCRIPTION

CONDITION
VALUES
RETURNED

MAIL-88

MAIL$SEND_ABORT is useful when, for example, the user enters the key
sequence Ctrl/c during the execution ofMAIL$SEND_MESSSAGE.

SS$NORMAL

Normal successful completion.

MAIL Utility Routines
MAIL$SEND_ADD_ADDRESS

MAIL$SEND_ADD_ADDRESS
Adds an address to the address list. If an address list does not exist,
MAIL$SEND_ADD_ADDRESS creates one.

FORMAT

MAIL$SEND_ADD_ADDRESS

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_list,
ouLitem_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
modify
by reference

Send context information to be passed to send routines. The context
argument is the address of a longword that contains send context
information returned by MAIL$SEND_BEGIN.

in_item_list
VMS usage:
type:
access:
mechanism:

itmlst_3
longword (unsigned)
read only
by reference

Item list specifying options for the routine. The in_item_list argument is
the address of a list of item descriptors, each of which specifies an option
and provides the information needed to perform the operation.
The item list is terminated by longword value of 0.
See MAIL$SEND_BEGIN for a description of an input item descriptor.
Input Item Codes
MAIL$_SEND_USERNAME

MAIL$_SEND_USERNAME specifies that MAIL add a specified username
to the address list. The buffer address field of the item descriptor points
to a buffer that receives a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
The item code MAIL$_SEND_USERNAME is required.
MAIL-89

MAIL Utility Routines
MAIL$SEND_ADD_ADDRESS

MAIL$_SEND_USERNAME_TYPE
MAIL$_SEND_USERNAME_TYPE specifies the type ofusemame added
to the address list. The buffer address field of the item descriptor points
to a word that contains the username type.

There are two types of usemames, as follows:
•

Username specified as a To: address (default)

•

Username specified as a CC: address

Note: Currently, the symbols MAIL$_TO and MAIL$_CC define username
types.

See MAIL$SEND_BEGIN for a description of an output item descriptor.
Output Item Codes
None.

DESCRIPTION

CONDITION
VALUES
RETURNED

If you do not specify a MAIL$_SEND_USERNAME_TYPE, MAIL$SEND_
ADD_ADDRESS uses MAIL$_TO. You can specify only one username per
call to MAIL$SEND_ADD_ADDRESS.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

SS$_ACCVIO

Access violation.

Any condition values returned by LIB$TPARSE.

MAIL-90

MAIL Utility Routines
MAIL$SEND_ADD_ATTRIBUTE

MAIL$SEND_ADD_ATTRIBUTE
Adds an attribute to the message you are currently constructing.

FORMAT

MAIL$SEND_ADD_ATTRIBUTE context, in_item_list,

ouLitem_list
RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage: context
type:
longword (unsigned)
access:
modify
mechanism: by reference
Send context information to be passed to send routines. The context
argument is the address of a longword that contains send context
information returned by MAIL$SEND_BEGIN.

You should specify this argument as 0 in the first of a sequence of calls to
MAIL routines. In following calls, you should specify the SEND context
value returned by the previous routine.

in_item_list
VMS usage: itmlst_3 "·
type:
longword (unsigned)
access:
read only
mechanism: by reference
Item list specifying options for the routine. The in_item_list argument is
the address of a list of item descriptors, each of which specifies an option
and provides the information needed to perform the operation.

The item list is terminated by longword value of 0.
See MAIL$SEND_BEGIN for a description of an input item descriptor.
Input Item Codes
MAIL$_SEND_CC_LINE

MAIL$_SEND_CC_LINE specifies a descriptor of the CC: field text. The
buffer address field of the item descriptor points to a buffer that contains
a character string 0 to 255 characters long.

MAIL-91

MAIL Utility Routines
MAIL$SEND_ADD_ATTRIBUTE

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_SEND_FROM_LINE

MAIL$_SEND_FROM_LINE specifies a descriptor of the From: field text
of the message to be sent. The buffer address field of the item descriptor
points to a buffer that contains a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
The SYSPRV privilege is required to alter the From: of a message.
MAIL$_SEND_SUBJECT

MAIL$_SEND_SUBJECT specifies a descriptor of the Subject: field text
of a message to be sent. The buffer address field of the item descriptor
points to a buffer that contains a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_SEND_TO_LINE

MAIL$_SEND_TO_LINE specifies a descriptor of the To: field text of the
message. The buffer address field of the item descriptor points to a
buffer that receives a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

out_item_list
VMS usage: itmlst_3
type:
longword
access:
write only
mechanism: by reference

Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.
See MAIL$SEND_BEGIN for a description of an output item descriptor.
Output Item Codes
None.

DESCRIPTION

If you do not specify a To: line, MAIL supplies a To: line composed of
usernames on the To: address list. If you do not specify a CC: line, MAIL
supplies a CC: line composed of usernames on the CC: address list. In
either of the above cases, commas separate the usernames used.

To modify a message's From: field, you must have the SYSPRV privilege.

MAIL-92

MAIL Utility Routines
MAIL$SEND_ADD_ATTRIBUTE

CONDITION
VALUES
RETURNED

SS$NORMAL

Normal successful completion.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

SS$_ACCVIO

Access violation.

MAIL-93

MAIL Utility Routines
MAIL$SEND_BEGIN

MAIL$SEND_BEGIN
Initiates processing to send a message to the users on the address list. You
must call MAIL$SEND_BEGIN before you call any other send routine.

FORMAT

MAIL$SEND_BEGIN

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_list,
out_item_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
context
longword (unsigned}
modify
by reference
Send context information to be passed to other send routines. The
context argument is the address of a longword that contains send context
information.

VMS usage:
type:
access:
mechanism:

You should specify the value of this argument as 0 in the first of a
sequence of calls to send routines. In following calls, you should specify
the send context value returned by this routine.

in- item- list

itmlst_3
longword (unsigned}
read only
by reference
Item list specifying options for the routine. The in_item_list argument is
the address of a list of item descriptors, each of which specifies an option
and provides the information needed to perform the operation.

VMS usage:
type:
access:
mechanism:

The item list is terminated by longword value of 0.
The following diagram depicts the format of a single item descriptor:

MAIL-94

MAIL Utility Routines
MAIL$SEND_BEGIN

Item Code

Buffer Length

Buffer Address
Return Length Address
ZK-1705-GE

ln_item_list Item Descriptor Fields
buffer length

A longword containing the address of the buffer that supplies information
to the routine.
return length address

This field is not used.
MAIL$SEND_BEGIN Input Item Codes
MAIL$_SEND_PERS_NAME
MAIL$_SEND_NO_PERS_NAME

MAIL$_SEND_PERS_NAME specifies the personal name text to be used
in the message header. The buffer address field of the item descriptor
points to a buffer that contains a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
The Boolean item code MAIL$_SEND_NO_PERS_NAME specifies that no
personal name string be used during message construction.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.

MAIL Utility Routines
MAIL$SEND_BEGIN

of which describes an item of information. The list of item descriptors
is terminated by longword value of 0. The following diagram depicts the
format of a single item descriptor:
31

Item Code

Buffer Length

Buffer Address
Return Length Address
ZK-1705-GE

Out_item_list Item Descriptor Fields
buffer length
A word containing a user-supplied integer specifying the length (in bytes)
of the buffer in which the routine is to write the information. The length
of the buffer needed depends on the item code specified in the item code
field of the item descriptor. If the value of buffer length is too small, the
routine truncates the data.
item code
A word containing a user-supplied symbolic code specifying the item of
information that the routine is to return. These codes are defined by
the $MAILDEF macro. See Output Item Codes for a description of these
codes.
buffer address
A longword containing the user-supplied address of the buffer in which the
routine is to write the information.
return length address
A longword containing the user-supplied address of a word in which the
routine writes the actual length in bytes of the information it returned.
Output Item Codes
MAIL$_SEND_COPY_FORWARD
When you specify the Boolean item code MAIL$_SEND_COPY_FORWARD,
MAIL$SEND_BEGIN returns the value of the caller's copy forward flag as
a longword value.
MAIL$_SEND_COPY_SEND
When you specify the Boolean item code MAIL$_SEND_COPY_SEND,
MAIL$SEND_BEGIN returns the value of the caller's copy send flag as a
longword value.
MAIL$_SEND_COPY_REPLY
When you specify the Boolean item code MAIL$_SEND_COPY_REPLY,
MAIL$SEND_BEGIN returns the value of the caller's copy reply flag as a
longword value.

MAIL-96

MAIL Utility Routines
MAIL$SEND_BEGIN

MAIL$_SEND_USER

When you specify MAIL$_SEND_USER, MAIL$SEND_BEGIN returns the
process owner's usemame. The buffer address field of the item descriptor
points to a buffer that receives a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

DESCRIPTION

CONDITION
VALUES
RETURNED

MAIL$SEND_BEGIN creates and initializes a send context for subsequent
calls to send routines.

SS$NORMAL

Normal successful completion.

MAIL$_CODERR

Internal system error.

MAIL$_CONITMCOD

The specified item codes perform conflicting
operations.

MAIL$_1LLPERNAME

The specified personal name string is illegal.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

SS$_ACCVIO

Access violation.

Any condition values returned by $GETJPIW, LIB$FREE_VM, and LIB$GET_VM.

MAIL-97

MAIL Utility Routines
MAIL$SEND_ADD_BODVPART

MAIL$SEND_ADD_BODYPART
Builds the body of a message.

FORMAT

MAIL$SEND_ADD_BODYPART context, in_item_list,
out_item_list

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

VMS usage:
type:
access:
mechanism:

The item list is terminated by longword value of 0.
See MAIL$SEND_BEGIN for a description of an input item descriptor.
Input Item Codes
MAIL$_SEND_DEFAULT_NAME

MAIL$_SEND_DEFAULT_NAME specifies the default file specification of
a text file to be opened. The buffer address field of the item descriptor
points to a buffer that contains a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

MAIL-98

MAIL Utility Routines
MAIL$SEND_ADD_BODYPART

MAIL$_SEND_FID
MAIL$_SEND_FID specifies the file identifier of the text file to be opened.
The buffer address field of the item descriptor points to a buffer that
contains the file identifier.
MAIL$_SEND_FILENAME
MAIL$_SEND_FILENAME specifies the input file specification of the text
file to be opened. The buffer address field of the item descriptor points
to a buffer that receives a character string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_SEND_RECORD
MAIL$_SEND_RECORD specifies a descriptor of a text record to be
added to the body of the message. The buffer address field of the item
descriptor points to a buffer that receives a character string 0 to 255
characters long.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
When creating a message, do not specify MAIL$_SEND_RECORD in the
same call (or series of calls) to MAIL$SEND_ADD_BODYPART with the
following item codes:
•

MAIL$_SEND_DEFAULT_NAME

•

MAIL$_SEND_FILENAME

See MAIL$SEND_BEGIN for a description of an output item descriptor.
Output Item Codes
MAIL$_SEND_RESULTSPEC
When you specify MAIL$_SEND_RESULTSPEC, MAIL$SEND_ADD_
BODYPART returns the resultant file specification identified with MAIL$_
SEND_FILENAME. The buffer address field of the item descriptor points
to a buffer that receives a character string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

MAIL-99

MAIL Utility Routines
MAIL$SEND_ADD_BODYPART

DESCRIPTION

You can use MAIL$SEND_ADD_BODYPART to specify a file that contains
the entire message or to add a single· record to a message. If the message
is contained in a file, you call MAIL$SEND_ADD_BODYPART once,
specifying the filename. If you want to add to the message record-byrecord, you can call MAIL$SEND_ADD_BODYPART repeatedly, specifying
a different record each time until you complete the message.
You cannot specify both a filename and a record for the same message.
You can specify MAIL$_SEND_FILENAME once or specify MAIL$_SEND_
RECORD one or more times.

CONDITION
VALUES
RETURNED

MAIL-100

SS$NORMAL

Normal successful completion.

MAIL$_CONITMCOD

The specified item codes define conflicting operations.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_OPEN IN

The required file is missing.

SS$_ACCVIO

Access violation.

MAIL Utility Routines
MAIL$SEND_END

MAIL$SEND_END
Terminates send processing.

FORMAT

MAIL$SEND_END

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_list, out_item_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

If send processing is successfully terminated, the value of the context
argument is changed to 0.

in_item_list
VMS usage: itmlst_3
type:
longword (unsigned}
access:
read only
mechanism: by reference
Item list specifying options for the routine. The in_item_list argument is
the address of a list of item descriptors, each of which specifies an option
and provides the information needed to perform the operation.

The item list is terminated by a longword of 0.
See MAIL$SEND_BEGIN for a description of an input item descriptor.
Input Item Codes
None.

MAIL-101

MAIL Utility Routines
MAIL$SEND_END

out_item_list
VMS usage: itmlst_3
longword
access:
write only
mechanism: by reference

type:

Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.
See MAIL$SEND_BEGIN for a description of an output item descriptor.
Output Item Codes
None.

DESCRIPTION

CONDITION
VALUES
RETURNED

The MAIL$SEND_END routine deallocates the send context as well as
any dynamic memory allocated by previous send routine calls.

SS$_NORMAL

Normal successful completion

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

SS$_ACCVIO

Access violation.

Any condition value returned by LIB$FREE_VM

MAIL-102

MAIL Utility Routines
MAIL$SEND_MESSAGE

MAIL$SEND_MESSAGE
Begins the actual sending of the message after the message has been
constructed.

FORMAT

MAIL$SEND_MESSAGE

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_Jist,
out_item_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

The item list is terminated by longword value of 0.
See MAIL$SEND_BEGIN for a description of input item descriptor.
Input Item Codes
MAIL$_SEND_ERROR_ENTRY
MAIL$_SEND_ERROR_ENTRY specifies the longword address of an entry
point to process errors during a send operation. The descriptor of the
recipient that failed, the address of the signal array, and the user-specified
data are passed as input to the routine.

MAIL-103

MAIL Utility Routines
MAIL$SEND_MESSAGE

MAIL$_SEND_SUCCESS_ENTRY
MAIL$_SEND_SUCCESS_ENTRY specifies the longword address of an
entry point to process successes during a send operation. The descriptor
of the recipient that succeeded, the address of the signal array, and the
user-specified data are passed as input to the routine.
MAIL$_SEND_USER_DATA
MAIL$_SEND_USER_DATA specifies a longword that MAIL$SEND_
MESSAGE passes to the SEND action routines.

See MAIL$SEND_BEGIN for a description of an output item descriptor.
Output Item Codes
None.

DESCRIPTION

The MAIL$SEND_MESSAGE routine sends a message built with the
MAIL$SEND_ADD_BODYPART routine to every user on the address
list. If you have not used MAIL$SEND_ADD_BODYPART to construct a
message, MAIL$SEND_MESSAGE sends only a message header.
If MAIL$SEND_MESSAGE encounters errors sending to an addressee, it

calls the routine specified by MAIL$_SEND_ERROR_ENTRY. Otherwise,
it calls the routine specified by MAIL$_SEND_SUCCESS_ENTRY.
If either routine is not specified, MAIL$SEND_MESSAGE calls no other

routines.

CONDITION
VALUES
RETURNED

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

SS$_ACCVIO

Access violation.

Any condition value returned by $CONNECT.

MAIL-104·

MAIL Utility Routines
MAIL$USER_BEGIN

MAIL$USER_BEGIN
Initiates access to the MAIL common user data base. You must call
MAIL$USER_BEGIN before you call any other user routines.

FORMAT

MAIL$USER_BEGIN

RETURNS

VMS usage:
type:
access:
mechanism:

context, in- item- list,
out_item_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
context
longword (unsigned)
modify
by reference
User context information to be passed to other user routines. The
context argument is the address of a longword that contains user context
information.
VMS usage:
type:
access:
mechanism:

You should specify the value of this argument as 0 in the first of a
sequence of calls to MAIL routines. In following calls, you should specify
the user context value returned by the previous routine.

VMS usage:
type:
access:
mechanism:

The item list must include at least one device item descriptor. The item
list is terminated by longword value of 0.

MAIL-105

MAIL Utility Routines
MAIL$USER_BEGIN

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

Item Code

Buffer Length

Buffer Address
Return Length Address
ZK-1705-GE

ln_item_list Item Descriptor Fields
buffer length

A longword containing the address of the buffer that supplies information
to the routine.
return length address

This field is not used.
MAIL$USER_BEGIN Input Item Codes
None.

MAIL-106

MAIL Utility Routines
MAIL$USER_BEGIN

Item Code

Buffer Length

Buffer Address
Return Length Address
ZK-1705-GE

Out_item_list Item Descriptor Fields
buffer length

A word containing a user-supplied integer specifying the length (in bytes)
of the buffer in which the routine is to write the information. The length
of the buffer needed depends on the item code specified in the item code
field of the item descriptor. If the value of buffer length is too small, the
routine truncates the data.
item code

A word containing a user-supplied symbolic code specifying the item of
information that the routine is to return. These codes are defined by
the $MAILDEF macro. See Output Item Codes for a description of these
codes.
buffer address

A longword containing the user-supplied address of the buffei" in which the
routine is to write the information.
return length address

A longword containing the user-supplied address of a word in which the
routine writes the actual length in bytes of the information it returned.
Output Item Codes
MAIL$_USER_AUTO_PURGE

When you specify the Boolean item code MAIL$_USER_AUTO_PURGE,
MAIL$USER_BEGIN returns the value of the automatic purge mail flag
as a longword value.
MAIL$_USER_CAPTIVE

When you specify the Boolean item code MAIL$_USER_CAPTIVE,
MAIL$USER_BEGIN returns the value of the UAF CAPTIVE flag as
a longword value.
MAIL$_USER_CC_PROMPT

When you specify the Boolean item code MAIL$_USER_CC_PROMPT,
MAIL$USER_BEGIN returns the value of the cc prompt flag as a longword
value.
MAIL$_USER_COPY_FORWARD

When you specify the Boolean item code MAIL$_USER_COPY_FORWARD,
MAIL$USER_BEGIN returns the value of the copy self forward flag as a
longword value.
MAIL-107

MAIL Utility Routines
MAIL$USER_BEGIN

MAIL$_USER_COPY_REPLY

When you specify the Boolean item code MAIL$_USER_COPY_REPLY,
MAIL$USER_BEGIN returns the value of the copy self reply :flag as a
longword value.
MAIL$_USER_COPY_SEND

When you specify the Boolean item code MAIL$_USER_COPY_SEND,
MAIL$USER_BEGIN returns the value of the copy self send :flag as a
longword value.
MAIL$_USER_FORWARDING

When you specify MAIL$_USER_FORWARDING, MAIL$USER_BEGIN
returns the forwarding address string. The buffer address field of the
item descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_USER_FORM

When you specify MAIL$_USER_FORM, MAIL$USER_BEGIN returns the
default print form string. The buffer address field of the item descriptor
points to a buffer that receives a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_USER_FULL_DIRECTORY

When you specify MAIL$_USER_FULL_DIRECTORY, MAIL$USER_
BEGIN returns complete directory path of the MAIL subdirectory. The
buffer address field of the item descriptor points to a buffer that receives
a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_USER_NEW_MESSAGES

When you specify MAIL$_USER_NEW_MESSAGES, MAIL$USER_
BEGIN returns the new message count. The buffer address field of
the item descriptor points to a word that receives the new message count.
MAIL$_USER_PERSONAL_NAME

When you specify MAIL$_USER_PERSONAL_NAME, MAIL$USER_
BEGIN returns the personal name string. The buffer address field of the
item descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_USER_QUEUE

When you specify MAIL$_USER_QUEUE, MAIL$USER_BEGIN returns
the default print queue name. The buffer address field of the item
descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL-108

MAIL Utility Routines
MAIL$USER_BEGIN

MAIL$_USER_RETURN_USERNAME

When you specify MAIL$_USER_RETURN_USERNAME, MAIL$USER_
BEGIN returns the username string. The buffer address field of the
item descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_USER_SUB_DIRECTORY

When you specify MAIL$_USER_SUB_DIRECTORY, MAIL$USER_BEGIN
returns the subdirectory specification. The buffer address field of the
item descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

DESCRIPTION

CONDITION
VALUES
RETURNED

MAIL$USER_BEGIN creates and initializes a user data base context for
subsequent calls to other user routines.

SS$NORMAL

Normal successful completion.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

SS$_ACCVIO

Access violation.

MAIL-109

MAIL Utility Routines
MAIL$USER_DELETE_INFO

MAIL$USER_DELETE_INFO
Removes a user record from the user common data base.

FORMAT

MAIL$USER_DELETE_INFO

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_list,
out- item- list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage: context
type:
longword (unsigned)
access:
modify
mechanism: by reference
User context information to be passed to send routines. The context
argument is the address of a longword that contains user context
information returned by MAIL$USER_BEGIN.

in_item_list
VMS usage: itmlst_3
type:
longword (unsigned)
access:
read .only
mechanism: by reference
Item list specifying options for the routine. The in_item_list argument is
the address of a list of item descriptors, each of which specifies an option
and provides the information needed to perform the operation.

The item list must include at least one device item descriptor. The item
list is terminated by longword value of 0.
See MAIL$USER_BEGIN for a description of an input item descriptor.
Input Item Codes

MAIL$_USER_USERNAME
MAIL$_USER_USERNAME specifies the record to be deleted from the
user profile data file. The buffer address field of the item descriptor
points to a buffer that contains a character string 0 to 31 characters long.

Specify a value from 0 to 31 in the buffer length field of the item
descriptor.
The item code MAIL$_USER_USERNAME is required.
MAIL-110

MAIL Utility Routines
MAIL$USER_DELETE_INFO

out- item- list

VMS usage: itmlst_3
longword
access:
write only
mechanism: by reference

type:

Item list specifying the information you want the routine to return. The

out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.
See MAIL$USER_BEGIN for a description of an output item descriptor.
Output Item Codes
None.

DESCRIPTION

CONDITION
VALUES
RETURNED

To delete a record from the MAIL common user data base, you must have
SYSPRV privilege.

SS$NORMAL

Normal successful completion.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOSUCHUSR

The specified username is not valid.

MAIL$_NOSYSPRV

The operation requires the SYSPRV privilege.

SS$_ACCVIO

Access violation.

MAIL-111

MAIL Utility Routines
MAIL$USER_END

MAIL$USER_END
Terminates access to the MAIL common user data base.

context, in_item_list, ouLitem_list

FORMAT

MAIL$USER_END

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
modify
by reference

User context information to be passed to user routines. The context
argument is the address of a longword that contains user context
information.
If MAIL terminates access to the user common database successfully, the

value of the argument context is changed to 0.

in_item_list
VMS usage:
type:
access:
mechanism:

itmlst_3
longword (unsigned)
read only
by reference

Item list specifying options for the routine. The in_item_list argument is
the address of a list of item descriptors, each of which specifies an option
and provides the information needed to perform the operation.
The item list must include at least one device item descriptor. The item
list is terminated by a longword of 0.
See MAIL$USER_BEGIN for a description of an input item descriptor.
Input Item Codes
None.

MAIL-112

MAIL Utility Routines
MAIL$USER_END

VMS usage:
type:
access:
mechanism:

See MAIL$USER_BEGIN for a description of an output item descriptor.
Output Item Codes
None.

DESCRIPTION

CONDITION

VALUES
RETURNED

The MAIL$USER_END routine deallocates the user database context
created by MAIL$USER_BEGIN as well as all dynamic memory allocated
by previous user routines.

SS$_NORMAL

Normal successful completion.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

SS$_ACCVIO

Access violation.

Any condition value returned by LIB$FREE_VM

MAIL-113

MAIL Utility Routines
MAIL$USER_GET_INFO

MAIL$USER_GET_INFO
Obtains information about a user from the user common data base.

FORMAT

MAIL$USER_GET_INFO

RETURNS

VMS usage:
type:
access:
mechanism:

context, in_item_/ist,
out_item_list

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned·by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
context
longword (unsigned)
modify
by reference
User context information to be passed to user routines. The context
argument is the address of a longword that contains user context
information returned by MAIL$USER_BEGIN.

VMS usage:
type:
access:
mechanism:

in- item- list

itmlst_3
longword (unsigned)
read only
by reference
Item list specifying options for the routine. The in_item_list argument is
the address of a list of item descriptors, each of which specifies an option
and provides the information needed to perform the operation.

VMS usage:
type:
access:
mechanism:

The item list must include at least one device item descriptor. The item
list is terminated by longword value of 0.
See MAIL$USER_BEGIN for a description of an input item descriptor.
Input Item Codes
MAIL$_USER_FIRST

The Boolean item code MAIL$_USER_FIRST specifies that MAIL$USER_
GET_INFO return information in the user profile about the first user in
the user common database.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.

MAIL-114

MAIL Utility Routines
MAIL$USER_GET_INFO

Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT or MAIL$_
USER_USERNAME in the same call to MAIL$USER_GET_INFO.
MAIL$_USER_NEXT
The Boolean item code MAIL$_USER_NEXT specifies that MAIL$USER_
GET_INFO return information in the user profile about the next user.

Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT or MAIL$_
USER_USERNAME in the same call to MAIL$USER_GET_INFO.
MAIL$_USER_USERNAME
The Boolean item code MAIL$_USER_USERNAME specifies
MAIL$USER_GET_INFO return information in the user profile about
a specified user.

Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT and MAIL$_
USER_USERNAME in the same call to MAIL$USER_GET_INFO.

out_item_list
VMS usage: itmlst_3
type:

longword

access:
write only
mechanism: by reference
Item list specifying the information you want the routine to return. The
out_item_list argument is the address of a list of item descriptors, each
of which describes an item of information. The list of item descriptors is
terminated by longword value of 0.

See MAIL$USER_BEGIN for a description of an output item descriptor.
Output Item Codes

MAIL$_USER_AUTO_PURGE
When you specify the Boolean item code MAIL$_USER_AUTO_PURGE,
MAIL$USER_GET_INFO returns the value of the automatic purge mail
flag as a longword value.
MAIL$_USER_CC_PROMPT
When you specify the Boolean item code MAIL$_USER_CC_PROMPT,
MAIL$USER_GET_INFO returns the value of the CC prompt flag as a
longword value.
MAIL$_USER_COPY_FORWARD
When you specify the Boolean item code MAIL$_USER_COPY_FORWARD,
MAIL$USER_GET_INFO returns the value of the copy self forward mail
flag as a longword value.
MAIL$_USER_COPY_REPLV
When you specify the Boolean item code MAIL$_USER_COPY_REPLY,
MAIL$USER_GET_INFO returns the value of the copy self reply mail flag
as a longword value.
MAIL-115

MAIL Utility Routines
MAIL$USER_GET_INFO

MAIL$_USER_COPY_SEND

When you specify the Boolean item code MAIL$_USER_COPY_SEND,
MAIL$USER_GET_INFO returns the value of the copy self send mail flag
as a longword value.
MAIL$_USER_EDITOR

When you specify MAIL$_USER_EDITOR, MAIL$USER_GET_INFO
returns the name of the default editor. The buffer address field of the
item descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_USER_FORWARDING

When you specify MAIL$_USER_FORWARDING, MAIL$USER_GET_
INFO returns the forwarding address. The buffer address field of the
item descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_USER_FORM

When you specify MAIL$_USER_FORM, MAIL$USER_GET_INFO returns
the default print form string. The buffer address field of the item
descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_USER_FULL_DIRECTORY

When you specify MAIL$_USER_FULL_DIRECTORY, MAIL$USER_GET_
INFO returns the complete directory path of the MAIL subdirectory string.
The buffer address field of the item descriptor points to a buffer that
receives a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_USER_NEW_MESSAGES

When you specify MAIL$_USER_NEW_MESSAGES, MAIL$USER_GET_
INFO returns the new messages count. The buffer address field of the
item descriptor points to a word that receives the new message count as a
longword value.
MAIL$_USER_PERSONAL_NAME

When you specify MAIL$_USER_PERSONAL_NAME, MAIL$USER_GET_
INFO returns the personal name string. The buffer address field of the
item descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

MAIL-116

MAIL Utility Routines
MAIL$USER_GET_INFO

MAIL$_USER_QUEUE

When you specify MAIL$_USER_QUEUE, MAIL$USER_GET_INFO
returns the default print queue name string. The buffer address field of
the item descriptor points to a buffer that receives a character string 0 to
255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_USER_RETURN_USERNAME

When you specify MAIL$_USER_RETURN_USERNAME, MAIL$USER_
GET_INFO returns the username. The buffer address field of the item
descriptor points to a buffer that receives a character string 0 to 255
characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
MAIL$_USER_SUB_DIRECTORY

When you specify MAIL$_USER_SUB_DIRECTORY, MAIL$USER_GET_
INFO returns the MAIL subdirectory specification string. The buffer
address field of the item descriptor points to a buffer that receives a
character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

DESCRIPTION

CONDITION
VALUES
RETURNED

The MAIL$USER_GET_INFO routine can return information about anyuser in the user common data base. If you do not specify a username,
MAIL$USER_GET_INFO returns information about the username
associated with the calling process. To obtain information about a
username other than that associated with the calling process, you must
have SYSNAM privilege.

SS$NORMAL

Normal successful completion.

MAIL$_CONITMCOD

The specified item codes perform conflicting
operations.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

MAIL$_NOSUCHUSR

The specified username is invalid.

MAIL$_NOSYSPRV

The specified operation requires the SYSPRV
privilege.

SS$_ACCVIO

Access violation.

MAIL-117

MAIL Utility Routines
MAIL$USER_SET_INFO

MAIL$USER_SET_INFO
Adds or modifies a specified user record in the user common data base.

FORMAT

MAIL$USER_SET_INFO

RETURNS

VMS usage:
type:
access:
mechanism:

context, in- item- list,
out_item_list

cond_value
longword (unsigned}
write only
by value

Longword condition value. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
VMS usage: context
type:
longword (unsigned}
access:
modify
mechanism: by reference
User context information to be passed to user routines. The context
argument is the address of a longword that contains user context
information returned by MAIL$USER_BEGIN.

The item list must include at least one device item descriptor. The item
list is terminated by longword value of 0.
See MAIL$USER_BEGIN for a description of an input item descriptor.
Input Item Codes

MAIL$_USER_CREATE_IF
The Boolean item code MAIL$_USER_CREATE_IF specifies that
MAIL$USER_SET_INFO should create the record for the specified user if
it does not already exist.
·

Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.

MAIL-118

MAIL Utility Routines
MAIL$USER_SET_INFO

MAIL$_USER_SET_AUTO_PURGE
MAIL$_USER_SET_NO_AUTO_PURGE

The Boolean item codes MAIL$_USER_SET_AUTO_PURGE and MAIL$_
USER_SET_NO_AUTO_PURGE set and clear the auto purge flag for the
specified user.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL$_USER_SET_CC_PROMPT
MAIL$_USER_SET_NO_CC_PROMPT

The Boolean item codes MAIL$_USER_SET_CC_PROMPT and MAIL$_
USER_SET_NO_CC_PROMPT set and clear the cc prompt flag for the
specified user.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL$_USER_SET_COPY_FORWARD
MAIL$_USER_SET_NO_COPY_FORWARD

The Boolean item codes MAIL$_USER_SET_COPY_FORWARD and
MAIL$_USER_SET_NO_COPY_FORWARD set and clear the copy self
forward flag for the specified user.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL$_USER_SET_COPY_REPLY
MAIL$_USER_SET_NO_COPY_REPLY

The Boolean item codes MAIL$_USER_SET_COPY_REPLY and MAIL$_
USER_SET_NO_COPY_REPLY set and clear the copy self reply flag for
the specified user.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL$_USER_SET_COPY_SEND
MAIL$_USER_SET_NO_COPY_SEND

The Boolean item codes MAIL$_USER_SET_COPY_SEND and MAIL$_
USER_SET_NO_COPY_SEND set and clear the copy self send flag for the
specified user.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL$_USER_SET_EDITOR
MAIL$_USER_SET_NO_EDITOR

MAIL$_USER_SET_EDITOR specifies the name of a default editor to be
used by the specified user. The buffer address field of the item descriptor
points to a buffer that contains a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
The Boolean item code MAIL$_USER_SET_NO_EDITOR clears the default
editor field for the specified user.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL-119

MAIL Utility Routines
MAIL$USER_SET_INFO

MAIL$_USER_SET_FORM
MAIL$_USER_SET_NO_FORM
MAIL$_USER_SET_FORM specifies the default print form string for the
specified user. The buffer address field of the item descriptor points to a
buffer that contains a character string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
The Boolean item code MAIL$_USER_SET_NO_FORM clears the default
print form field for the specified user.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL$_USER_SET_FORWARDING
MAIL$_USER_SET_NO_FORWARDING
MAIL$_USER_SET_FORWARDING specifies a forwarding address string
for the specified user. The buffer address field of the item descriptor
points to a buffer that contains a character string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
The Boolean item code MAIL$_USER_SET_NO_FORWARDING clears the
forwarding address field for the specified user.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL$_USER_SET_NEW_MESSAGES
MAIL$_USER_SET_NEW_MESSAGES specifies the new message count
for the specified user. The buffer address field of the item descriptor
points to a word that contains the new number of new messages.
MAIL$_USER_SET_PERSONAL_NAME
MAIL$_USER_SET_NO_PERSONAL_NAME
MAIL$_USER_SET_PERSONAL_NAME specifies a personal name string
for the specified user. The buffer address field of the item descriptor
points to a buffer that contains a character string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
The Boolean item code MAIL$_USER_SET_NO_PERSONAL_NAME clears
the personal field for the specified user.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL$_USER_SET_QUEUE
MAIL$_USER_SET_NO_QUEUE
MAIL$_USER_SET_QUEUE specifies a default print queue name string
for the specified user. The buffer address field of the item descriptor
points to a buffer that contains a character string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item
descriptor.

MAIL-120

MAIL Utility Routines
MAIL$USER_SET_INFO

The Boolean item code MAIL$_USER_SET_NO_QUEUE clears the default
print queue field for the specified user.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL$_USER_SET_SUB_DIRECTORY
MAIL$_USER_SET_NO_SUB_DIRECTORY

MAIL$_USER_SET_SUB_DIRECTORY specifies a MAIL subdirectory.
The buffer address field of the item descriptor points to a buffer that
contains a character string 0 to 255 characters long.
Specify a value from 0 to 255 in the buffer length field of the item
descriptor.
The Boolean item code MAIL$_USER_SET_NO_SUB_DIRECTORY
disables the use of a MAIL subdirectory for the specified user.
Specify the value 0 in the buffer length and buffer address fields of the
item descriptor.
MAIL$_USER_USERNAME

MAIL$_USER_USERNAME specifies the record to be modified in the mail
common database and points to the username string. The buffer address
field of the item descriptor points to a buffer that contains a character
string 0 to 31 characters long.
Specify a value from 0 to 31 in the buffer length field of the item
descriptor.

See MAIL$USER_BEGIN for a description of an output item descriptor.
Output Item Codes
None.

DESCRIPTION

The MAIL$USER_SET_INFO routine can modify any record in the user
common data base. If you do not specify a username, the routine modifies
the user record associated with the calling process.
To modify any user record other than that associated with the calling
process, you must have SYSPRV privilege. However, if you want to add or
modify only the forwarding address of another user, SYSNAM privilege is
sufficient.

MAIL-121

MAIL Utility Routines
MAIL$USER_SET_INFO

CONDITION
VALUES
RETURNED

MAIL-122

SS$NORMAL

Normal successful completion.

MAIL$_CONITMCOD

The specified item codes perform conflicting
operations.

MAIL$_1NVITMCOD

The specified item code is invalid.

MAIL$_1NVITMLEN

The specified item length is invalid.

MAIL$_MISREQITEM

The required item is missing.

SS$_ACCVIO

Access violation.

10 National Character Set (NCS) Utility Routines
This chapter describes the National Character Set (NCS) Utility routines.
The NCS Utility provides a common facility for defining and accessing
collating sequences and conversion functions. Collating sequences are
used to compare strings for sorting purposes. Conversion functions are
used to derive an altered form of an input string based on an appropriate
conversion algorithm.

10.1

Introduction to NCS Routines
Using NCS, you can formulate collating sequences and conversion
functions and register them in an NCS library. The NCS routines
provide a programming interface to NCS that lets you access the collating
sequences and conversion functions from an NCS library for doing string
comparisons.
Typically, NCS collating sequences are selective subsets of the
multinational character set. They are used extensively in programming
applications involving various national character sets. For example, a
program might use the Spanish collating sequence to assign appropriate
collating weight to characters from the Spanish national character set.
Another program might use the French collating sequence to assign
appropriate collating weight to characters in the French national character
set.
In addition to providing program access to· collating sequences and
conversion functions in an NCS library, the NCS routines provide a means
for saving definitions in a local file for subsequent use by the comparison
and conversion routines.
Table 10-1 lists the NCS routines.
Table 10-1

NCS Routines

Routine

Description

NCS$COMPARE

Compares two strings using specified collating sequence as
comparison basis

NCS$CONVERT

Converts a string using the specified conversion function

NCS$END_CS

Terminates the use of a collating sequence by the calling
program

NCS$END_CF

Terminates the use of a conversion function by the calling
program

NCS$GET_CF

Retrieves the definition of the named conversion function
from the NCS library
(continued on next page)

NCS-1

National Character Set (NCS) Utility Routines
10.1 Introduction to NCS Routines

Table 10-1 (Cont.) NCS Routines
Routine

Description

NCS$GET_CS

Retrieves the definition of the named collating sequence
from the NCS library

NCS$RESTORE_CF

Permits the calling program to restore the definition of a
"saved" conversion function from a database or an RMS file

NCS$RESTORE_CS

Permits the calling program to restore the definition of a
"saved" collating sequence from a database or an RMS file

NCS$SAVE_CF

Provides the calling program with information that permits
the application to store the definition of a converslon
function in a local database or an RMS file

NCS$SAVE_CS

Provides the calling program with information that permits
the application to store the definition of a collating sequence
in a local database or an RMS file

In a typical application, the program does the following:
1

Prepares a string for comparison

Makes a call to the NCS$GET routine, specifying the appropriate
collating sequence

Makes one or more calls to the NCS$COMPARE routine, which does
the actual comparison

Terminates the comparison with a call to the NCS$END routine

The program can also include the use of conversion functions in
preparation for the comparison routines.

10.2

Examples of How to Use NCS Utility Routines
This section includes two examples of how to use NCS utility routines in
program applications. Example 10-1 illustrates the use of NOS utility
routines in a FORTRAN program.

NCS-2

National Character Set (NCS) Utility Routines
10.2 Examples of How to Use NCS Utility Routines

Example 10-1

Using NCS Routines in a FORTRAN Program

PROGRAM NCS EXAMPLE
CHARACTER*80 CSSTRING,STRING1,STRING2
INTEGER*4
CSLENGTH,LENGTH1,LENGTH2,CSID,STATUS,RESULT
INTEGER*4
NCS$GET_CS,NCS$COMPARE,NCS$END_CS
CHARACTER*l

c
C

CMP(3)

CMP (1)
'<'
CMP (2) = '='
CMP (3) = '>'
Read the name of the collating sequence ..

c
30

WRITE (6,30)
READ (5,15,END=999) CSLENGTH,CSSTRING
FORMAT(' Collating Sequence: ')

c
C

Get the collating sequence from the NCS library

c
CSID = 0
STATUS= NCS$GET_CS (CSID, CSSTRING(l:CSLENGTH))
IF ((STATUS .AND. 1) .NE. 1) THEN
CALL LIB$SIGNAL (%VAL(STATUS))
ENDIF

c
C

Read two strings to be compared according to the collating sequence

C·

100

WRITE (6,10)
READ (5,15,END=999) LENGTHl,STRINGl
WRITE (6,20)
READ (5,15,END=999) LENGTH2,STRING2
IF (LENGTHl .EQ. 0 .AND. LENGTH2 .EQ. 0) THEN
GOTO 200
ENDIF

10
20
15

FORMAT(' Stringl: ')
FORMAT(' String2: ')
FORMAT (q,a80)
(continued on next page)

NCS-3

National Character Set {NCS) Utility Routines
10.2 Examples of How to Use NCS Utility Routines

Example 10-1 (Cont.)

Using NCS Routines in a FORTRAN Program

c
C

Compare the strings

c
result= ncs$compare (csid, stringl(l:lengthl), string2(1:length2))

c
C

Display the results of the comparison

c
40

WRITE (6,40) STRINGl(l:LENGTHl), CMP(RESULT+2), STRING2(1:LENGTH2)
FORMAT (' ' , A, ' ' , A, ' ' , A)
GOTO 100

c
C
C

Come here if both inputs are blank -- we are done.
Call NCS$END_CS to free any storage used to hold the CS.

c
200

STATUS = NCS$END_CS (CSID)
IF ((STATUS .AND. 1) .NE. 1) THEN
CALL LIB$SIGNAL (%VAL(STATUS))
ENDIF
CALL EXIT

999

CONTINUE
END

Example 10-2 illustrates the use of NCS routines in a MACR0-32
program.
Example 10-2 Using NCS Routines in a MACR0-32 Program
.TITLE /NCS Conversion Function Example/
$NAMDEF
.PSECT

DATA

LONG,NOEXE,WRT

CFID:
.LONG
LENGTH: . WORD
CFNAME D:
.ASCID
PROMPT D:
.ASCID

/EDT_VT2xx/
/_File:

SIZE = 1024
INFAB:
INRAB:

.ALIGN
$FAB
$RAB

LONG
FNA=FILE,FNS=NAM$C_MAXRSS
FAB=INFAB,UBF=REC,USZ=SIZE

FILE:
.BLKB
NAM$C_MAXRSS
FILE D: .LONG
NAM$C_MAXRSS
.ADDRESS FILE
(continued on next page)

NCS-4

National Character Set {NCS) Utility Routines
10.2 Examples of How to Use NCS Utility Routines

Example 10-2 (Cont.)
REC:
REC D:

.BLKB

Using NCS Routines in a MACR0-32 Program

SIZE

.LONG
SIZE
.ADDRESS REC
DEST:
DEST D:

.BLKB
SIZE
.LONG
SIZE
.ADDRESS DEST
.PSECT

CODE EXE,NOWRT

.ENTRY

NCS$EXAMPLE, AM<>

Get the EDT VT2xx conversion function from default library.
PUS HAL
PUS HAL
CALLS
BSBW

CFNAME D
CFID
#2,GANCS$GET_CF
ERROR

Get the file to be converted.
PUS HAL
PUS HAL
PUS HAL
CALLS
BSBW
MOVW

LENGTH
PROMPT D
FILE D
#3,GALIB$GET_INPUT
ERROR
LENGTH,FILE_D

Open the file to be converted.
$OPEN
FAB=INFAB
BSBW
ERROR
$CONNECT RAB=INRAB
BSBW
ERROR
Read each record from the file.
LOOP:

$GET
BLBC

RAB=INRAB
RO,STATUS

Call NCS$CONVERT to convert the input string to EDT fallback.
(e.g., Convert form feed to <FF>, escape to <ESC>, etc ... )
MOVW
PUS HAL
PUS HAL
PUS HAL
PUS HAL
CALLS
BSBW
MOVW

INRAB+RAB$W_RSZ,REC_D
LENGTH
DEST D
REC D
CFID
#4,GANCS$CONVERT
ERROR
LENGTH,DEST_D

Write result to SYS$0UTPUT.

(continued on next page)

NCS-5

National Character Set (NCS) Utility Routines
10.2 Examples of How to Use NCS Utility Routines

Example 10-2 (Cont.)
PUSHAL
CALLS
MOVW
BRB
STATUS: CMPL
BEQL
BSBW

Using NCS Routines in a MACR0-32 Program

DEST D

#1,G~LIB$PUT OUTPUT
#SIZE,DEST_DLOOP

RO,#RMS$_EOF
DONE
ERROR

Call NCS$END_CF to free any storage used to hold the conversion function.
DONE:

PUSHAL
CALLS
BSBW
RET

CFID
#l,GANCS$END_CF
ERROR

Error handling.
ERROR:

BLBC
RSB

10$:

$EXIT_S RO
.END

10.3

R0,10$

NCS$EXAMPLE

NCS Routines
The following pages describe the NCS routines.

NCS-6

National Character Set {NCS) Utility Routines
NCS$COMPARE

NCS$COMPARE Compare Strings
The NCS$COMPARE routine compares two strings using a specified collating
sequence as a comparison basis.

FORMAT

NCS$COMPARE

RETURNS

VMS usage:
type:
access:
mechanism:

cs_id, string_ 1, string_2

integer
longword integer (signed)
write only
by value

Longword condition value. Most routines return a condition value in
RO but the NCS$COMPARE routine uses RO to return the result of the
comparison, as shown in the following table:
Returned Value

Comparison Result

-1

string_1 is less than string_2

string_1 is equal to string_2

string_1 is greater than string_2

The NCS$COMPARE routine uses the VAX Signaling Mechanism to
indicate completion status as described under CONDITION VALUE
SIGNALED.

ARGUMENTS

cs_id
VMS usage:
type:
access:
mechanism:

identifier
longword integer (unsigned)
read only
by reference

Address of a longword that NCS uses to identify a collating sequence.
The cs_id argument is required and can be obtained by a call to the
NCS$GET_CS routine.
All calls to the NCS$COMPARE routine and the call to the NCS$END_CS
routine that terminates the comparison must pass this longword identifier.
Upon completion, the NCS$END_CS routine releases the memory used to
store the collating sequence and sets the value of the longword identifier
to zero.

string_1
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Descriptor (length and address) of the first string.
NCS-7

National Character Set {NCS) Utility Routines
NCS$COMPARE

string_2
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Descriptor of the second string.

DESCRIPTION

CONDITION
VALUE
SIGNALED

NCS-8

The NCS$COMPARE routine compares two strings using the specified
collating sequence as the comparison basis. The routine indicates whether
the value of the first string is greater than, less than, or equal to the value
of the second string.

STR$_1LLSTRCLA

Illegal string class. Severe error. The descriptor of
stri.ng_1 or string_2, or both, contains a class code
not supported by the VAX Procedure Calling and
Condition Handling Standard.

National Character Set (NCS) Utility Routines
NCS$CONVERT

NCS$CONVERT Convert String
The NCS$CONVERT routine converts a string using the specified conversion
function.

FORMAT

NCS$CONVERT

RETURNS

VMS usage:
type:
access:
mechanism:

cf_id, source, dest ,[ret_length]
,[not_cvt]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

cf id
VMS usage: identifier
type:
longword integer (unsigned)
access:
read only
mechanism: by reference
Address of a longword that NCS uses to identify a conversion function.
The cf_id argument is required and can be obtained by a call to the
NCS$GET_CF routine.

All calls to the NCS$CONVERT routine and the call to the NCS$END_CF
routine that terminates the conversion must pass this longword identifier.
Upon completion, the NCS$END_CF routine releases the memory used to
store the conversion function and sets the value of the longword identifier
to zero.

source
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Descriptor of source string.

dest
VMS usage: char_string
type:
character string
access:
write only
mechanism: by descriptor
Descriptor of destination string.

NCS-9

National Character Set (NCS) Utility Routines
NCS$CONVERT

ret_length
VMS usage: word unsigned
type:
word (unsigned)
access:
write only
mechanism: by reference
Length of converted string.

not cvt
VMS usage: word unsigned
type:
word (unsigned)
access:
write only
mechanism: by reference
Number of characters in the source string that were not fully converted.

DESCRIPTION

CONDITION
VALUES
RETURNED

CONDITION
VALUES
SIGNALED

NCS-10

Using the specified conversion function, the NCS$CONVERT routine
converts the source string and stores the result in the specified destination.
Optionally, the calling program can request that the routine return the
length of the converted string as well as the number of characters which
were not fully converted.

NCS$_NOT_CF

Name of identifier does not refer to a conversion
function.

SS$_NORMAL

Successful completion.

STR$_TRU

Successful completion. However, the resultant string
was truncated because the storage allocation for the
destination string was inadequate.

LBR messages (prefaced by an NCS message) might signal errors detected while the
process is accessing the NCS library.
Any value signaled by STR$COPY_DX or STR$ANALYZE_SDESC.

National Character Set {NCS) Utility Routines

NCS$END_CF

NCS$END_CF End Conversion Function
The NCS$END_CF routine terminates a conversion function.

FORMAT

NCS$END_CF

RETURNS

VMS usage: cond_value
type:
longword {unsigned)
access:
write only
mechanism: by value

cf_id

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

cf id
VMS usage: identifier
type:
longword integer {unsigned)
access:
modify
mechanism: by reference
Address of a longword that NCS uses to store a nonzero value identifying
a conversion function.

The cf_id argument is required.

DESCRIPTION

CONDITION

VALUES
RETURNED

The NCS$END_CF routine indicates to NCS that the calling program no
longer needs the conversion function. NCS releases the memory space
allocated for the coversion function and sets the value of the longword
identifier to zero.

NCS$_NORMAL

Normal successful completion. The longword identifier
value is set to zero.

NCS$_NOT_CF

Name of identifier does not refer to a conversion
function.

NCS-11

National Character Set (NCS) Utility Routines
NCS$END_CS

NCS$END_CS

End Collating Sequence

The NCS$END_CS routine terminates a collating sequence.

FORMAT

NCS$END_CS

RETURNS

VMS usage:
type:
access:
mechanism:

cs_id

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

cs id
VMS usage: identifier
type:
longword integer (unsigned)
access:
modify
mechanism: by reference
Address of a longword that NCS uses to store a nonzero value identifying
a collating sequence.

The cs_id argument is required.

DESCRIPTION

CONDITION
VALUES
RETURNED

NCS-12

The NCS$END_CS routine indicates to NCS that the calling program
no longer needs the collating sequence. NCS releases the memory space
allocated for the collating sequence and sets the value of the longword
identifier to zero.

NCS$_NORMAL

Normal successful completion. The longword identifier
value is set to zero.

NCS$_NOT_CS

Name of identifier does not refer to a collating
sequence.

National Character Set {NCS) Utility Routines
NCS$GET_CF

NCS$GET_CF Get Conversion Function
The NCS$GET_CF routine retrieves the definition of the named conversion
function from the NCS library.

FORMAT

NCS$GET_CF

RETURNS

VMS usage:
type:
access:
mechanism:

cf_id[,cfname][,librar]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

cf_ id
VMS usage:
type:
access:
mechanism:

identifier
longword integer (unsigned)
modify
by reference

Address of a longword used by NCS to identify a conversion function.
The calling program must ensure that the longword contains zero before
invoking the NCS$GET_CF routine because the routine stores a nonzero
value in the longword. The nonzero value identifies the conversion
function. All subsequent calls to the NCS$CONVERT routine and the call
to the NCS$END_CF routine to terminate the conversion function pass the
longword identifier. When it completes the conversion, the NCS$END_CF
routine releases the memory used to store the conversion function and sets
the value of the longword identifier to zero.
The conversion function identifier enhances modular programming and
permits concurrent use of multiple conversion functions within a program.
The calling program should not attempt to interpret the contents of the
longword identifier.
The cf_id argument is required.

cfname
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Name of the conversion function being retrieved.

NCS-13

National Character Set (NCS) Utility Routines
NCS$GET_CF

librar
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Name of the library where the conversion function is stored.

DESCRIPTION

The NCS$GET_CF routine extracts the named conversion function from
the specified NCS lil;>rary.
If the calling program omits the cfname argument, an "identity"

conversion function padded with NUL characters (hex 0) is provided. The
identity conversion function effectively leaves each character unchanged by
converting each character to itself. For example, A becomes A, B becomes
B, C becomes C, and so forth.
If the calling program omits the librar argument, NCS accesses the

default NCS library.

CONDITION
VALUES
RETURNED

CONDITION
VALUES
SIGNALED

NCS-14

NCS$_DIAG

Operation completed with signaled diagnostics.

NCS$_NOT_CF

Name of identifier does not refer to a conversion
function.

NCS$_NOT_FOUND

Name of identifier not found in the NCS library.

LBR messages (prefaced by an NCS message) might signal errors detected while the
process is accessing the NCS library.

National Character Set (NCS) Utility Routines
NCS$GET_CS

NCS$GET_CS Get Collating Sequence
The NCS$GET_CS routine retrieves the definition of the named collating
sequence from the NCS library.

FORMAT

NCS$GET_CS

RETURNS

VMS usage:
type:
access:
mechanism:

cs_id[,csname][,librar]

cond_value
longword {unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

cs_id
VMS usage:
type:
access:
mechanism:

identifier
longword integer {unsigned)
modify
by reference

Address of a longword that NCS uses to store a nonzero value identifying
a collating sequence. The calling program must ensure that the longword
identifier contains zero before invoking the NCS$GET_CS routine.
All subsequent calls to the NCS$COMPARE routine and the call to the
NCS$END_CS routine that terminates the use of the collating sequence
must pass this longword identifier. Upon completion of the comparisons,
the NCS$END_CS routine releases the memory used to store the collating
sequence and sets the value of the longword identifier to zero.
The collating sequence identifier enhances modular programming and
permits concurrent use of multiple collating sequences within a program.
The calling program should not attempt to interpret the contents of the
longword identifier.
The cs_id argument is required.

csname
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Name of the collating sequence being retrieved.

NCS-15

National Character Set {NCS) Utility Routines
NCS$GET_CS

librar
VMS usage: char_string
character string
access:
read only
mechanism: by descriptor
File specification of the library where the collating sequence is stored.

type:

DESCRIPTION

The NCS$GET_CS routine extracts the named collating sequence from the
specified NCS library. If the calling program omits the csname argument,
NCS creates a collating sequence that uses the "native" collating sequence
as a basis for the comparisons. This collating sequence is padded with
NUL characters (hex 0).
If the calling program omits the librar argument, NOS accesses the

default NOS library.

CONDITION
VALUES
RETURNED

CONDITION
VALUES
SIGNALED

NCS-16

NCS$_DIAG

Operation completed with signaled diagnostics.

NCS$_NOT_CS

Name of identifier does not refer to a collating
sequence.

NCS$_NOT_FOUND

Name of identifier not found in the NCS library.

LBR messages (prefaced by an NCS message) might signal errors detected while the
process is accessing the NCS library.

National Character Set (NCS) Utility Routines
NCS$RESTORE_CF

NCS$RESTORE_CF Restore Conversion Function
The NCS$RESTORE_CF routine permits the calling program to restore the
definition of a saved conversion function from a database or a file.

FORMAT

NCS$RESTORE_CF cf_id[,length][,address]

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Longword condition value. Most utility routines return a condition value
in RO. The condition value that this routine can return is listed under
CONDITION VALUE RETURNED.

ARGUMENTS

cf_ id
VMS usage: identifier
type:
longword integer (unsigned)
access:
write only
mechanism: by reference
Address of a longword that NCS uses to identify a conversion function.

The cf_id argument is required.

length
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
Longword that the calling program uses to indicate the length of the
conversion function being restored.

address
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
Longword that the calling program uses as a pointer to the conversion
function being restored.

NCS-17

National Character Set {NCS) Utility Routines

NCS$RESTORE_CF

DESCRIPTION

The NCS$RESTORE_CF routine, used in conjunction with the
NCS$SAVE_CF routine, permits the application program to keep a local
copy of the conversion function. The NCS$SAVE_CF routine obtains
the length and location of the conversion fµnction and returns it to the
application program. The application program subsequently provides this
information to the NCS$RESTORE_CF routine, which uses it to access the
conversion function.
This routine also does some integrity checking on the conversion function
as it is being processed.

CONDITION
VALUE
RETURNED
CONDITION
VALUES
SIGNALED

NCS-18

NCS$_NOT_CF

Name of identifier does not refer to a conversion
function.

LBR messages (prefaced by an NCS message) might signal errors detected while the
process is accessing the NCS library.

National Character Set {NCS) Utility Routines

NCS$RESTORE_CS

Restore Collating Sequence

The NCS$RESTORE_CS routine permits the calling program to restore the
definition of a "saved" collating sequence from a database or a file.

FORMAT

NCS$RESTORE_CS

RETURNS

VMS usage:
type:
access:
mechanism:

cs_id[,length][,address]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. The condition value that this routine can return is listed under
CONDITION VALUE RETURNED.

ARGUMENTS

cs_id
identifier
longword integer (unsigned)
write only
by reference
Address of a longword that NCS uses to identify a collating sequence.
VMS usage:
type:
access:
mechanism:

The cs_id argument is required.

length
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Longword that the calling program uses to indicate the length of the
collating sequence being restored.

address
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Longword that the calling program uses as a pointer to the collating
sequence being restored.

NCS-19

National Character Set (NCS) Utility Routines
NCS$RESTORE_CS

DESCRIPTION

The NCS$RESTORE_CS routine, used in conjunction with the
NCS$SAVE_CS routine, permits the application program to keep a
local copy of the collating sequence. The NCS$SAVE_CS routine obtains
the length and location of the collating sequence and returns it to the
application program. The application program subsequently provides this
information to the NCS$RESTORE_CS routine, which uses it to access the
collating sequence.
This routine also does some integrity checking on the collating sequence as
it is being processed.

CONDITION
VALUE
RETURNED
CONDITION
VALUES
SIGNALED

NCS-20

NCS$_NOT_CS

Name of identifier does not refer to a collating
sequence.

LBR messages (prefaced by an NCS message) might signal errors detected while the
process is accessing the NCS library.

National Character Set {NCS) Utility Routines
NCS$SAVE CF

NCS$SAVE_CF Save Conversion Function
The NCS$SAVE_CF routine provides the calling program with information that
permits the application to store the definition of a conversion function in a
local database or a file rather than in the NCS library.

FORMAT

NCS$SAVE_CF cf_id[,length][,address]

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. The condition value that this routine can return is listed under
CONDITION VALUE RETURNED.

ARGUMENTS

cf id
VMS usage: identifier
type:
longword integer (unsigned)
access:
read only
mechanism: by reference
Address of a longword that NCS uses to identify a conversion function.

The cf_id argument is required.

length
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
write only
mechanism: by reference
Longword used to store the length of the specified conversion function.

address
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
write only
mechanism: by reference
Longword used to store the address of the specified conversion function.

NCS-21

National Character Set (NCS) Utility Routines

NCS$SAVE_CF

DESCRIPTION

The NCS$SAVE_CF routine, used in conjunction with the NCS$_
RESTORE_CF routine, permits the application program to store a
conversion function definition in a local file or in a database. When
the calling program specifies the conversion function identifier, NCS
returns the location of the definition and its length in bytes, permitting
the calling program to store the definition locally, rather than in an NCS
library. Subsequently, the application supplies this information to the
NCS$RESTORE_CF routine, which restores the conversion function to a
form that can be used by the NCS$CONVERT routine.
This routine also does some integrity checking on the conversion function
as it is being processed.

CONDITION
VALUE
RETURNED
CONDITION
VALUES
SIGNALED

NCS-22

NCS$_NOT_CF

Name of identifier does not refer to a conversion
function.

LBR messages (prefaced by an NCS message) might signal errors detected while the
process is accessing the NCS library.

National Character Set {NCS) Utility Routines
NCS$SAVE_CS

NCS$SAVE_CS Save Collating Sequence
The NCS$SAVE_CS routine provides the calling program with information that
permits the application program to store the definition of a collating sequence
in a database or a file rather than in the NCS library.

FORMAT

NCS$SAVE_CS

RETURNS

VMS usage:
type:
access:
mechanism:

cs_id[,length][,address]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. The condition value that this routine can return is listed under
CONDITION VALUE RETURNED.

ARGUMENTS

cs id
VMS usage:
type:
access:
mechanism:

identifier
longword integer (unsigned)
read only
by reference

Address of a longword that NCS uses to identify a collating sequence.
The cs_id argument is required.

length
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
write only
by reference

Longword that NCS uses to indicate the length of the specified collating
sequence to the calling program.

address
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
write only
by reference

Longword that NCS uses to indicate the address of the specified collating
sequence to the calling program.

NCS-23

National Character Set {NCS) Utility Routines
NCS$SAVE_CS

DESCRIPTION

The NCS$SAVE_CS routine, used in conjunction with the NCS$_
RESTORE_CS routine, permits the application program to store a
collating sequence definition in a local file or in a database. When the
calling program specifies the collating sequence identifier, NCS returns the
location of the definition sequence and its length in bytes, permitting
the calling program to store the definition locally, rather than in a
library. Subsequently, the application supplies this information to the
NCS$RESTORE_CS routine, which restores the collating sequence to a
form that can be used by the NCS$COMPARE routine.
This routine also does some integrity checking on the collating sequence as
it is being processed.

CONDITION
VALUE
RETURNED
CONDITION
VALUES
SIGNALED

NCS-24

NCS$_NOT_CS

Name of identifier does not refer to a collating
sequence.

LBR messages (prefaced by an NCS message) might signal errors detected while the
process is accessing the NCS library.

Print Symbiont Modification {PSM) Routines

The print symbiont modification (PSM) routines allow you to modify the
behavior of the print symbiont supplied with the VMS operating system.

11.1

Introduction to PSM Routines
The VMS print symbiont processes data for output to standard line
printers and printing terminals by performing the following functions:
•

Reading the data from disk

•

Formatting the data

•

Sending the data to the printing device

•

Composing separation pages (flag, burst, and trailer pages) and
inserting them into the data stream for printing

Some of the reasons for modifying the print symbiont include the following:
•

To include additional information on the separation pages (flag, burst,
and trailer) or to format them differently

•

To filter and modify the data stream sent to the printer

•

To change some of the ways that the symbiont controls the printing
device

You might not always be able to modify the print symbiont to suit your
needs. For example, you cannot do the following:
•

Modify the VMS symbiont's control logic or the sequence in which the
symbiont calls routines

•

Modify the interface between the VMS symbiont and the job controller

If you cannot modify the VMS print symbiont to suit your needs, you might
want to write your own symbiont. Section 11.3 describes how to write your
own symbiont and integrate it with the VMS operating system. However,
you should modify the VMS print symbiont, when possible, rather than
write your own symbiont.
The rest of this chapter contains the following information about PSM
routines:
•

Section 11.2 contains an overview of the VMS print symbiont and of
symbionts in general. It explains concepts such as "symbiont streams";
describes the relationship between a symbiont, a device driver, and
the job controller; and gives an overview of the VMS print symbiont's
internal logic.
This section is recommended for those who want to either modify the
VMS print symbiont or write a new symbiont.
PSM-1

Print Symbiont Modification (PSM) Routines
11.1 Introduction to PSM Routines

11.2

•

Section 11.3 details the procedure for modifying the VMS print
symbiont. It includes an overview of the entire procedure, followed
by a detailed description of each step.

•

Section 11.4 contains an example of a simple modification to the VMS
print symbiont.

•

Section 11.5 describes each PSM routine and the interface used by the
routines you substitute for the standard PSM routines.

VMS Print Symbiont Overview
The VMS operating system supplies two symbionts: a print symbiont,
which is an output symbiont, and a card reader, which is an input
symbiont. An output symbiont receives tasks from the job controller,
whereas an input symbiont sends jobs to the job controller. The card
reader symbiont cannot be modified. You can modify the print symbiont,
described in this section, using PSM routines.
There are two types of output symbiont: device and server. A device
symbiont processes data for output to a device, for example, a printer. A
server symbiont also processes data but not necessarily for output to a
device, for example, a symbiont that copies files across a network. The
VMS operating system supplies no server symbionts.

11.2.1

Components of the VMS Print Symbiont
The VMS print symbiont includes the following major components:
•

PSM routines that are used to modify the print symbiont

•

Routines that implement input, format, and output services in the
VMS print symbiont

•

Routines that implement the internal logic of the VMS print symbiont

The VMS print symbiont is implemented using the Symbiont Services
Facility. This facility provides communication and control between the
job controller and symbionts through a set of Symbiont/Job Controller
Interface Routines (SMB routines), which are documented in Chapter
Chapter 12.
All of these routines are contained in a shareable image with the file
specification SYS$SHARE:SMBSRVSHR.EXE.

11.2.2

Creation of the Print Symbiont Process
The print symbiont is a device symbiont, receiving tasks from the job
controller and processing them for output to a printing device. In the VMS
operating system, the existence of a print symbiont process is linked to the
existence of at least one print execution queue that is started.

PSM-2

Print Symbiont Modification {PSM) Routines
11.2 VMS Print Symbiont Overview

The job controller creates the print symbiont process by calling the Create
Process ($CREPRC) system service; it does this whenever either of the
following conditions occur:
•

A print execution queue is started (from the stopped state) and no
symbiont process is running the image specified with the START
/QUEUE command.
A print execution queue is started by means of the DCL command
START/QUEUE. You can use the /PROCESSOR qualifier with the
START/QUEUE command to specify the name of the symbiont image
that is to service an execution queue; if you omit /PROCESSOR, then
the default symbiont image is PRTSMB.

•

Currently existing symbiont processes suited to a print execution
queue cannot accept additional devices; that is, the symbionts have
no more available streams. In such a case, the job controller creates
another print symbiont process. The next section discusses symbiont
streams.

The print symbiont process runs as a detached process.

11.2.3

Symbiont Streams
A stream is a logical link between a print execution queue and a printing
device. When the queue is started (by means of START/QUEUE), the job
controller creates a stream linking the queue with a symbiont process.
Because each print execution queue has a single associated printing
device (specified with the /ON=device_name qualifier in the INITIALIZE
/QUEUE or START/QUEUE command), each stream created by the job
controller links a print execution queue, a symbiont process, and the
queue's associated printer.
A symbiont that can support multiple streams simultaneously (that
is, multiple print execution queues and multiple devices) is termed a
multithreaded symbiont. The job controller enforces an upper limit of 16
on the number of streams that any symbiont can service simultaneously.
Therefore, in the VMS operating system environment, only one print
symbiont process is needed as long as the number of print execution
queues (and associated printers) does not exceed 16. If there are more
than 16 print execution queues, the job controller creates another print
symbiont process.
The VMS print symbiont is, therefore, a multithreaded symbiont that can
service as many as 16 queues and devices, but you can modify it to service
any number of queues and devices as long as the number is less than or
equal to 16.
A symbiont stream is said to be "active" when a queue is started on
th at stream. The print symbiont maintains a count of active streams.

It increments this count each time a queue is started and decrements it
when a queue is stopped with the DCL command STOP/QUEUE/NEXT or
STOP/QUEUE/RESET. When the count falls to zero, the symbiont process
exits. The symbiont does not decrement the count when the queue is
paused by STOP/QUEUE.
PSM-3

Print Symbiont Modification {PSM) Routines
11.2 VMS Print Symbiont Overview

Figure 11-1 shows the relationship of generic print queues, execution print
queues, the job controller, the print symbiont, printer device drivers, and
printers. The lines connecting the boxes denote streams.
Figure 11-1

G Q
e u
n e
e u
r e
i
c

Multithreaded Symbiont

Execution
Queue

c
0

Execution

Queue

Execution
Queue

Printer
Driver 2

Printer

Printer
Driver 3

Printer
3

s
y

m
b
i

n
t

Printer

Printer
Driver 1

ZK-2007-GE

11.2.4

Symbiont and Job Controller Functions
This section compares the roles of the symbiont and job controller in the
execution of print requests. You issue print requests using the PRINT
command.
The job controller uses the information specified on the PRINT command
line to determine the following:
•

Which queue to place the job in (!QUEUE, /REMOTE, /LOWERCASE,
and /DEVICE)

•

How many copies to print (!COPIES and /JOB_COUNT)

•

Scheduling constraints for the job (/PRIORITY, /AFTER, /BLOCK_
LIMIT, /HOLD, /FORM, /CHARACTERISTICS, and /RESTART)

•

How and whether to display the status of jobs and queues (/NOTIFY,
/OPERATOR, and /IDENTIFY)

The print symbiont, on the other hand, interprets the information supplied
with the qualifiers that specify this information:

PSM-4

•

Whether to print file separation pages (/BURST, /FLAG, and
/TRAILER)

•

Information to include when printing the separation pages (/NAME
and/NOTE)

•

Which pages to print (/PAGES)

•
•

How to format the print job (/FEED, /SPACE, and /PASSALL)
How to set up the job (!SETUP)

Print Symbiont Modification (PSM) Routines
11.2 VMS Print Symbiont Overview

The print symbiont, not the job controller, performs all necessary devicerelated functions. It communicates with the printing device driver. For
example, when a print execution queue is started (by means of START
/QUEUE/ON=device_name) and the stream is established between the
queue and the symbiont, the symbiont parses the device name specified by
the /ON qualifier in the START/QUEUE command, allocates the device,
assigns a channel to it, obtains the device characteristics, and determines
the device class. In versions of the VMS operating system prior to Version
4.0, the job controller performed these functions.
The print symbiont's output routine returns an error to the job controller
if the device class is neither printer nor terminal.

11.2.5

Print Symbiont Internal Logic
The job controller deals with units of work called jobs, while the print
symbiont deals with units of work called tasks. A print job can consist
of several print tasks. Thus, in the processing of a print job, the job
controller's role is to divide a print job into one or more print tasks, which
the symbiont can process. The symbiont reports the completion of each
task to the job controller, but the symbiont contains no logic to determine
that the print job as a whole is complete.
In the processing of a print task, the symbiont performs three basic
functions: input, format, and output. The symbiont performs these
functions by calling routines to perform each function.
The following steps describe the action taken by the symbiont in processing
a task:
1

The symbiont receives the print request from the job controller and
stores it in a message buffer.

The symbiont searches its list of input routines and selects the first
input routine that is applicable to the print task.

The input routine returns a data record to the symbiont's input buffer
or in a buffer supplied by the input routine.

Data in the input buffer is moved to the symbiont's output buffer by
the formatting routines, which format it in the process.

Data in the output buffer is sent to the printing device by the output
routine.

When an input routine completes execution, that is, when it has no
more input data to process, the symbiont selects another applicable
input routine. Steps 3, 4, and 5 are repeated until all applicable input
routines have executed.

The symbiont informs the job controller that the task is complete.

PSM-5

Print Symbiont Modification (PSM) Routines
11.2 VMS Print Symbiont Overview

Figure 11-2 illustrates the steps taken by the symbiont in the processing
of a print task.
Figure 11-2 Symbiont Execution Sequence or Flow of Control

Input
Routines

Input
Buffer
Formatting
Routine
Output
Buffer
Output
Routine
Printing
Device
ZK-2008-GE

As Figure 11-2 shows, most of the input routines execute in a specified
sequence. This sequence is defined by the symbiont's main control routine.
You cannot modify this main control routine; thus, you cannot modify the
sequence in which symbiont routines are called.
The input routines that do not execute in sequence are called "demand
input routines." These routines are called whenever the service they
provide is required and include the page header, page setup, and library
module input routines.
The symbiont can perform input, formatting, and output functions
asynchronously; that is, the order in which the symbiont calls the input,
formatting, and output routines can vary. For example, the symbiont can
call an input routine, which returns a record to the input buffer; it can
then call the format routine, which moves that record to the output buffer;
and then it can call the output routine to move that data to the printing
device. This sequence results in the movement of a single data record from
disk to printing device.
On the other hand, the symbiont can call the input and formatting
routines several times before calling the output routine for a single buffer.
The buffer can contain one or more formatted input records. In some cases
an output buffer might contain only a portion of an input record.
In this way the symbiont can buffer input records; then call the format
routine, which moves one of those records to the output buffer; and finally
call the output routine, which moves that data to the printing device.

PSM-6

Print Symbiont Modification (PSM) Routines
11.2 VMS Print Symbiont Overview

Note, however, that the formatting routine must be called once for each
input record.
Similarly, the symbiont can buffer several formatted records before calling
the output routine to move them to the printing device.
The symbiont requires this flexibility in altering the sequence in which
input, format, and output routines are called for reasons of efficiency (high
rate of throughput) and adaptability to various system parameters and
system events.
The value specified with the call to PSM$PRINT determines the maximum
size of the symbiont's output buffer, which cannot be larger than the
value of the SYSGEN parameter MAXBUF. If the buffer is very small, the
symbiont might need to call its output routine one or more times for each
record formatted. If the buffer is large, the symbiont will buffer several
formatted records before calling the output routine to move them to the
printing device.

11.3

Symbiont Modification Procedure
To modify the VMS print symbiont, perform the following steps. These
steps are described in more detail in the sections that follow.
1

Determine the modification needed. The modification might involve
changing the way the symbiont performs a certain function, or it might
involve adding a new function.

Determine where to make the modification. This involves selecting a
function and determining where that function is performed within the
symbiont's execution sequence. You specify a function by calling the
PSM$REPLACE routine and specifying the code that identifies the
function.
Some codes correspond to symbiont-supplied routines. When you
specify one of these codes, you replace that ;routine with your routine.
Other codes do not correspond to symbiont-supplied routines. When
you specify one of these codes, you add your routine to the set of
routines the symbiont executes. Table 11-1 lists these codes.

Write the routine. Because the symbiont calls your routine, your
routine must have one of three call interfaces, depending on whether
it is an input, format, or output routine. See the descriptions of the
USER-INPUT-ROUTINE, USER-FORMAT-ROUTINE, and USEROUTPUT-ROUTINE routines, which follow the descriptions of the
PSM routines.

Write the symbiont-initialization routine. This routine executes when
the symbiont is first activated by the job controller. It initializes the
symbiont's internal database; specifies, by calling PSM$REPLACE,
the routines you have supp~ied; activates the symbiont by calling
PSM$PRINT; and performs any necessary cleanup operations when
PSM$PRINT completes.

Construct the modified symbiont. This involves compiling your
routines, then linking them.
PSM-7

Print Symbiont Modification {PSM) Routines
11.3 Symbiont Modification Procedure

Integrate the modified symbiont with the system. This involves placing
the executable image in SYS$SYSTEM, identifying the symbiont image
to the job controller, and debugging the symbiont.

As mentioned previously, you identify each routine you write for the
symbiont by calling the PSM$REPLACE routine. The code argument for
this routine specifies the point within the symbiont's execution sequence
at which you want your routine to execute. You should know which code
you will use to identify your routine before you begin to write the routine.
Section 11.3.6 provides more information about these codes.

11.3.1

Guidelines and Restrictions
The following guidelines and restrictions apply to the writing of any
symbiont routine:
•

Do not use the process-permanent files identified by the logical names
SYS$INPUT, SYS$0UTPUT, SYS$ERROR, and SYS$COMMAND.

•

The symbiont code should be linked against SMBSRVSHR.EXE in
order to define the following status codes:
PSM$_FLUSH
PSM$_FUNNOTSUP
PSM$_PENDING
PSM$_SUSPEND
PSM$_EOF
PSM$_BUFFEROVF
PSM$_NEWPAGE
PSM$_ESCAPE
PSM$_INVVMSOSC
PSM$_MODNOTFND
PSM$_NOFILEID
PSM$_0SCTOOLON
PSM$_TOOMANYLEV
PSM$_INVITMCOD

PSM-8

•

Do not use the system services SYS$HIBER and SYS$WAKE.

•

Use the following two Run-Time-Library routines for allocation and
deallocation of memory: LIB$GET_VM and LIB$FREE_VM.

•

Minimize the amount of time that your routine spends executing
at AST level. The job controller sends messages to the symbiont by
means of user-mode ASTs; the symbiont cannot receive these ASTs
while your user routine is executing at AST level.

•

The symbiont can call your routines at either AST level or non-AST
level.

Print Symbiont Modification (PSM) Routines
11.3 Symbiont Modification Procedure

•

If your routine returns any error-condition value (low bit clear), the

symbiont aborts the current task and notifies the job controller.
Note that, by default, an error-condition value returned during the
processing of a task causes the job controller to abort the entire job.
However, this default behavior can be overridden. See the description
of the /RETAIN qualifier of the DCL commands START/QUEUE,
INITIALIZE/QUEUE, and SET QUEUE in the VMS DCL Dictionary.
The symbiont stores the first error-condition value (low bit clear)
returned during the processing of a task. The symbiont's file-errors
routine, an input routine (code PSM$K_FILE_ERRORS), places the
message text associated with this condition value in the symbiont's
input stream. The symbiont prints this text at the end of the listing,
immediately before the trailer pages.
The symbiont sends this error-condition value to the job controller; the
job controller then stores this condition value with the job record in the
job controller's queue file. The job controller also writes this condition
value in the accounting record for the job.
If you choose to return a condition value when an error occurs, you
should choose one from the system message file. This lets system
programs access the message text associated with the condition
value. Specifically, the Accounting and SHOW/QUEUE utilities
and the job controller will be able to translate the condition value
to its corresponding message text and to display this message text as
appropriate.
This guideline applies to input, input-filter, and output-filter routines,
and to the symbiont's use of dynamic string descriptors in these
routines.
The simplest way for an input routine to pass the data record to the
symbiont is for it to use an RTL string-handling routine (for example,
STR$COPY_R). These routines use dynamic string descriptors to
point to the record they have handled to copy the record from your
input buffer to the symbiont-supplied buffer specified in the funcdesc
argument to the input routine.
By default, the symbiont initializes a dynamic string descriptor that
your input routine can use to describe the data record it returns.
Specifically, the symbiont initializes the DSC$B_DTYPE field of the
string descriptor with the value DSC$K_DTYPE_T (which indicates
that the data to which the descriptor points is a string of characters)
and initializes the DSC$B_CLASS field with the value DSC$K_
CLASS_D (which indicates that the descriptor is dynamic).
Alternatively, the input routine can pass a data record to the symbiont
by providing its own buffer and passing a static string descriptor that
describes the buffer. To do this, you must redefine, using the following
steps, the fields of the descriptor to which the fu.ncdesc argument
points:
1

Initialize the field DSC$B_CLASS with the value DSC$K_CLASS_
S (which indicates that the descriptor points to a scalar value or a
fixed-length string).
PSM-9

Print Symbiont Modification (PSM) Routines
11.3 Symbiont Modification Procedure

Initialize the field DSC$A_POINTER with the address of the buffer
that contains the data record.

Initialize the field DSC$W_LENGTH with the length, in bytes, of
the data record.

Each time the symbiont calls the routine to read some data, the
symbiont reinitializes the descriptor to make it a dynamic descriptor.
Consequently, if you want to use the descriptor as a static descriptor,
your input routine must initialize the descriptor as described
previously every time it is called to perform a reading operation.
Input-filter routines and output-filter routines return a data record to
the symbiont by means of the func_desc_2 argument. The symbiont
initializes a descriptor for this argument the same way it does for
descriptors used by input routine described previously. Thus, the
guidelines described for the input routine apply to the input-filter
routine and output-filter routine.

11.3.2

Writing an Input Routine
This section provides an overview of the logic used in the VMS print
symbiont's main input routine, and it discusses the way in which the VMS
print symbiont handles carriage-control effectors.
The print symbiont calls your input routine, supplying it with arguments.
Your routine must return arguments and condition values to the print
symbiont. For this reason, your input routine must use the interface
described in the description of the USER-INPUT-ROUTINE.
When the print symbiont calls your routine, it specifies a particular
request in the func argument. Each function has a corresponding code.
Your routine must provide the functions identified by the codes PSM$K_
OPEN, PSM$K_READ, and PSM$K_CLOSE. Your routine need not
respond to the other function codes, but it can if you want it to. If your
routine does not provide a function that the symbiont requests, it must
return the condition value PSM$_FUNNOTSUP to the symbiont.
The description of the func argument of the USER-INPUT-ROUTINE
describes the codes that the symbiont can send to an input routine.
See Section 11.3.5 for additional information about other function codes
used in the user-written input routine.
For each task that the symbiont processes, it calls some input routines
only once, and some more than once; it always calls some routines and
calls others only when needed.
Table 11-1 lists the codes that you can specify when you call the
PSM$REPLACE routine to identify your input routine to the symbiont.
The description of the PSM$REPLACE routine describes these routines.

PSM-10

Print Symbiont Modification (PSM) Routines
11.3 Symbiont Modification Procedure

11.3.2.1

Internal Logic of the Symbiont's Main Input Routine

The internal logic of the symbiont's main input routine, as described in
this section, is subject to change without notice. This logic is summarized
here. This summary is not intended as a tutorial on the writing of a
symbiont's main input routine, although it does provide insight into such a
task.
A main input routine is one that the symbiont calls to read data from the
file that is to be printed. A main input routine must perform three sets of
tasks: one set when the symbiont calls the routine with an OPEN request,
one set when the symbiont calls with a READ request, and one set when
the symbiont calls with a CLOSE request.
The following table names the codes that identify each of these three
requests and describes the tasks that the VMS symbiont's main input
routine performs for each of these requests:
Code

Action Taken by the Input Routine

PSM$K_OPEN

An OPEN request. When the main input routine receives this
request code, it does the following:

2
3

Opens the input file.
Stores information about the input file.
Returns the type of carriage control used in the input file. If
this routine cannot open the file, it returns an error.

Note that the VMS print symbiont's main input routine performs
these tasks when it receives the PSM$K_START_TASK function
code, rather than the PSM$K_OPEN function code.
This atypical behavior occurs because some of the information
stored by the main input routine must be available for other
input routines that execute before the main input routine. For
example, information about file attributes and record formats is
needed by the symbiont's separation-page routines, which print
flag and burst pages.
Consequently, if you supply your own main input routine, some
of the information about the file being printed that appears on
the standard separation pages is not available, and the symbiont
prints a message on the separation page stating so.
The symbiont receives the file-identification number from the job
controller in the SMBMSG$K_FILE_IDENTIFICATION item of
the requesting message and uses this value rather than the file
specification to open the main input file.
PSM$K_READ

A READ request. When the main input routine receives this
request, it returns the next record from the file. In addition, when
the carriage control used by the data file is PSM$K_CC_PRINT,
the main input routine returns the associated record header.

PSM$K_CLOSE

A CLOSE request. When the main input routine receives this
request, it closes the input file.

PSM-11

Print Symbiont Modification (PSM) Routines
11.3 Symbiont Modification Procedure

11.3.2.2

Symbiont Processing of Carriage Control

Each input record can be thought of as consisting of three parts: leading
carriage control, data, and trailing carriage control. Taken together, these
three parts are called the composite data record.
Leading and trailing carriage control are determined by the type of
carriage control used in the file and explicit carriage-control information
returned with each record. For embedded carriage control, however,
leading and trailing carriage control is always null.
The type of carriage control returned by the main input routine on the
PSM$K_OPEN request code determines, for that invocation of the input
routine, how the symbiont applies carriage control to each record that the
main input routine returns on the PSM$K_READ request code.
Note that, for all four carriage control types, the first character returned
on the first PSM$K_READ call to an input routine receives special
processing. If that character is a linefeed or a formfeed and if the symbiont
is currently at line 1, column 1 of the current page, then the symbiont
discards that linefeed or formfeed.
The Four Types of Carriage Control

The following table briefly describes each type of carriage control and how
the symbiont's main input routine processes it. For a detailed explanation
of each of these types of carriage control, refer to the description of the
FAB$B_RAT field of the FAB block in the VMS Record Management
Services Manual.

PSM-12

Type of Carriage Control

Symbiont Processing

Embedded

Leading and trailing carriage control are embedded
in the data portion of the input record. Therefore,
the symbiont supplies no special carriage control
processing; it assumes that leading and trailing
carriage control are null.

FORTRAN

The first byte of each data record contains a
FORTRAN carriage-control character. This character
specifies both the leading and trailing carriage control
for the data record. The symbiont extracts the first
byte of each data record and interprets that byte as
a FORTRAN carriage-control character. If the data
record is empty, the symbiont generates a leading
carriage control of linefeed and a trailing carriage
control of carriage return.

Print Symbiont Modification (PSM) Routines
11.3 Symbiont Modification Procedure

Type of Carriage Control

Symbiont Processing

PRN

Each data record contains a two-byte header that
contains the carriage-control specifier. The first byte
specifies the carriage control to apply before printing
the data portion of the record. The second byte
specifies the carriage control to apply after printing
the data portion. The abbreviation PRN stands for
print-file format.
Unlike other types of carriage control, PRN carriage
control information is returned through the funcarg
argument of the main input routine; this occurs with
the PSM$K_READ request. The funcarg argument
specifies a longword; your routine writes the 2-byte
PRN carriage control specifier into the first two bytes
of this longword.

Implied

11.3.3

The symbiont provides a leading linefeed and a
trailing carriage return. But if the data record consists
of a single formfeed, the symbiont sets to null the
leading and trailing carriage control for that record,
and the leading carriage control for the record that
follows it.

Writing a Format Routine
To write a format routine, follow the modification procedure described in
Section 11.3. Do not replace the VMS symbiont's main format routine.
Instead, modify its action by writing input and output filter routines.
These execute immediately before and after the main format routine,
respectively. The main formatting routine uses an undocumented and
nonpublic interface; you cannot replace the main formatting routine. The
DCL command PRINT/PASSALL bypasses the main format routine of the
print symbiont.
See Section 11.3.5 for additional information about other function codes
used in the user-written formatting routine.
11.3.3.1

Internal Logic of the Symbiont's Main Format Routine
The main format routine contains all the logic necessary to convert
composite data records to a data stream for output. Actions taken by
the format routine include the following:

•

Tracking the current column and line

•

Implementing the special processing of the first character of the first
record

•

Implementing the alignment data mask specified by the DCL command
START/QUEUE/ALIGN=MASK

•

Handling margins as specified by the forms definition

•

Initiating processing of page headers when specified by the DCL
command PRINT/HEADER

•

Expanding leading and trailing carriage control
PSM-13

Print Symbiont Modification (PSM) Routines
11.3 Symbiont Modification Procedure

•

Handling line overflow

•

Handling page overflow

•

Expanding tab characters to spaces for some devices

•

Handling escape sequences

•

Accumulating accounting information

•

Implementing double-spacing when specified by the DCL command
PRINT/SPACE

•

Implementing automatic page ejection when specified by the DCL
command PRINT/FEED

The symbiont's main format routine uses a special rule when processing
the first character of the first composite data record returned by an input
routine. (A composite data record is the input data record and a longword
that contains carriage-control information for the input data record.) This
rule is that if the first character is a vertical format effector (formfeed or
linefeed) and if the symbiont has processed no printable characters on the
current page (that is, the current position is column 1, line 1), then that
vertical format effector is discarded.

11.3.4

Writing an Output Routine
To write an output routine, follow the modification procedure described in
Section 11.3.
The print symbiont calls your output routine. Input arguments are
supplied by the print symbiont; output arguments and status values
are returned by your routine to the print symbiont. For this reason,
your output routine must have the call interface that is described in the
USER-OUTPUT-ROUTINE routine.
When the print symbiont calls your routine, it specifies in one of the input
arguments-the func argument-the reason for the call. Each reason has
a corresponding function code.
There are several function codes that the print symbiont can supply when
it calls your output routine. Your routine must contain the logic to respond
to the following function codes: PSM$K_OPEN, PSM$K_WRITE, PSM$K_
WRITE_NOFORMAT, and PSM$K_CLOSE.
It is not required that your output routine contain the logic to respond to
the other function codes, but you can provide this logic if you want to.
A complete list and description of all relevant function codes for output
routines is provided in the description of the func argument of the USEROUTPUT-ROUTINE routine.
See Section 11.3.5 for additional information about other function codes.

PSM-14

Print Symbiont Modification (PSM) Routines
11.3 Symbiont Modification Procedure

11.3.4.1

Internal Logic of the Symbiont's Main Output Routine

When the symbiont calls the main output routine with the PSM$K_OPEN
function code, the main output routine takes the following steps:
1

Allocates the print device

Assigns a channel to the device

Obtains the device characteristics

Returns the device-status longword in the funcarg argument (for
more information, see the description of the SMBMSG$K_DEVICE_
STATUS message item in Chapter 12

Returns an error if the device is not a terminal or a printer

When this routine receives a PSM$K_WRITE service request code, it sends
the contents of the symbiont output buffer to the device for printing.
When this routine receives a PSM$K_WRITE_NOFORMAT service request
code, it sends the contents of the symbiont output buffer to the device for
printing and suppresses device drive formatting as appropriate for the
device in use.
When this routine receives a PSM$K_CANCEL service request code, it
requests the device driver to cancel any outstanding output operations.
When this routine receives a PSM$K_CLOSE service request code, it
deassigns the channel to the device and deallocates the device.

11.3.5

Other Function Codes
A status PSM$_PENDING might not be r~turned whenever the symbiont
notifies user-written input, output, and format routines using the following
message function codes:
Function Code

Description

PSM$K_START_STREAM

Job controller sends a message to the symbiont to
start a queue

PSM$K_START_TASK

Symbiont parses a message from job controller
directing it to start a queue

PSM$K_PAUSE_TASK

Job controller sends a message to the symbiont to
suspend processing of the current task

PSM$K_STOP_STREAM

Job controller sends a message to the symbiont to
stop the queue

PSM$K_STOP_TASK

Job controller sends a message to the symbiont to
stop the task

PSM$K_RESUME_TASK

Job controller sends a message to the symbiont to
resume processing of the current task

PSM$K_RESET~STREAM

Same as PSM$K_STOP_STREAM

PSM-15

Print Symbiont Modification {PSM) Routines
11.3 Symbiont Modification Procedure

11.3.6

Writing a Symbiont Initialization Routine
Writing a symbiont initialization routine involves writing a program that
calls the following:
1

PSM$REPLACE once for each routine (input, output, or format) that
you have written. PSM$REPLACE identifies your routines to the
symbiont.

PSM$PRINT exactly once after you have identified all your service
routines using PSM$REPLACE.

Table 11-1 lists all routine codes that you can specify in the
PSM$REPLACE routine. Choosing the correct routine code for your
routine is important because the routine code specifies when the symbiont
will call your routine. The functions of these routines are described further
in the description of the PSM$REPLACE routine.
Column one in Table 11-1 lists each routine code.
For those input routines that execute in a predefined sequence, the second
column contains a number showing the order in which that input routine
is called relative to the other input routines for a single file job. If the
routine does not execute in a predefined sequence, the second column
contains the character x.
Column three specifies whether the routine is an input, format, or output
routine; this information directs you to the section describing how to write
a routine of that type.
Column four specifies whether there is a symbiont-supplied routine
corresponding to that routine code. The codes for the input-filter and
output-filter routines, which have no corresponding routines in the VMS
symbiont, allow you to specify new routines for inclusion in the symbiont.
Table 11-1

Routine Codes for Specification to PSM$REPLACE

Routine Code

Sequence

PSM$K_JOB_SETUP

Function

Supplied

Input

Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes

PSM$K_FORM_SETUP

Input

PSM$K_JOB_FLAG

Input

PSM$K_JOB_BURST

Input

PSM$K_FILE_SETUP

Input

PSM$K_FILE_FLAG

Input

PSM$K_FILE_BURST

Input

PSM$K_FILE_SETUP_2

Input

PSM$K_MAIN_INPUT

Input

PSM$K_FILE_INFORMATION

Input

PSM$K_FILE_ERRORS

Input

(continued on next page)

PSM-16

Print Symbiont Modification (PSM) Routines
11.3 Symbiont Modification Procedure

Table 11-1 (Cont.)

Routine Codes tor Specification to PSM$REPLACE

Routine Code

Sequence

Function

Supplied

PSM$K_FILE_TRAILER

Input

PSM$K_JOB_RESET

Input

PSM$K_JOB_TRAILER

Input

PSM$K_JOB_COMPLETION

Input

PSM$K_PAGE_SETUP

PSM$K_INPUT_FILTER

x
x
x
x

Yes
Yes
Yes
Yes
Yes
Yes
Yes

Formatting

PSM$K_MAIN_FORMAT

Formatting

Yes

PSM$K_OUTPUT_FILTER

Formatting

PSM$K_OUTPUT

Output

Yes

PSM$K_PAGE_HEADER
PSM$K_LIBRARY_INPUT

11.3.7

Input
Input
Input

Integrating a Modified Symbiont
To integrate your user routine and the symbiont initialization routine,
perform the following steps; note that the sequence of steps described here
assumes that you will be debugging the modified symbiont:
1

Compile or assemble the user routine and the symbiont initialization
routine into an object module.

Enter the following DCL command:
$

LINK/DEBUG your-symbiont

The file name your-symbiont is the object module built in step
1. Symbols necessary for this link operation are located in
the shareable images SYS$SHARE:SMBSRVSHR.EXE and
SYS$LIBRARY:IMAGELIB.EXE. The linker automatically searches
these shareable images and extracts the necessary information.
3

Place the resulting executable symbiont image in SYS$SYSTEM.

Locate two unallocated terminals: one at which to issue DCL
commands and one at which to debug the symbiont image.

Log in on one of the terminals under UIC [1,4], which is the system
manager's account. This terminal is the one at which you enter DCL
commands. Do not log in at the other terminal.

Enter the following DCL command:
$

SET TERMINAL/NODISCONNECT/PERMANENT

TTcu:

The variable _TTcu: is the physical terminal name of the terminal at
which you want to debug (the terminal you are not logged in at). The
underscore ( _) and colon ( : ) characters must be specified.

PSM-17

Print Symbiont Modification (PSM) Routines
11.3 Symbiont Modification Procedure

Enter the following DCL commands:
$ DEFINE/GROUP DBG$INPUT
TTcu:
$ DEFINE/GROUP DBG$0UTPUT =TTcu:

The variable _TTcu: specifies the physical terminal name of the
terminal at which you will be debugging. Note that other users having
a UIC with group number 1 should not use the debugger at the same
time.
8

Initialize the queue by entering the following DCL command:
$ INITIALIZE/QUEUE/PROCESSOR= your-symbiont /ON= printer_name

The symbiont image specified by the file name your-symbiont must
reside in SYS$SYSTEM. Note too that the /PROCESSOR qualifier
accepts only a file name; the device, directory, and file type default to
SYS$SYSTEM:.EXE.
The /ON qualifier specifies the device that will be served by the
symbiont while you debug the symbiont.
9

Enter the following DCL command to execute the modified symbiont
routine:
$ PRINT/HEADER/QUEUE=queue-id

Enter the following DCL command to start the queue and invoke the
debugger:
$ START/QUEUE queue-name

10 After you debug your symbiont, relink the symbiont by entering the

following DCL command:
$ LINK/NOTRACEBACK/NODEBUG your-symbiont

11 Deassign the logical names DBG$INPUT and DBG$0UTPUT so that
they will not interfere with other users in UIC group 1.

11.4

Example of Using the PSM Routines
Example 11-1 shows how to use PSM routines to supply a page header
routine in a MACRO program.

PSM-18

Print Symbiont Modification {PSM) Routines
11.4 Example of Using the PSM Routines

Example 11-1

Using PSM Routines to Supply a Page Header Routine in a MACRO Program

.TITLE
.IDENT

EXAMPLE - Example user modified symbiont
'V03-000'

;++
THIS PROGRAM SUPPLIES A USER WRITTEN PAGE HEADER
ROUTINE TO THE STANDARD SYMBIONT. THE PAGE HEADER
INCLUDES THE SUBMITTER'S ACCOUNT NAME AND USER NAME,
THE FULL FILE SPECIFICATION, AND THE PAGE NUMBER.
THE HEADER LINE IS UNDERLINED BY A ROW OF DASHES
PRINTED ON A SECOND HEADER LINE .
. LIBRARY

/SYS$LIBRARY:LIB.MLB/

System definitions
$PSMDEF
$SMBDEF
$DSCDEF

Symbiont definitions
Message item definitions
Descriptor definitions

Define argument offsets for user supplied services called by symbiont
CONTEXT
WORK AREA
FUNC
FUNC DESC
FUNC ARG

04
08
12
16
20

symbiont context
user context
function code
function dependent descriptor
function dependent argument

Macro to create dynamic descriptors
.MACRO

D DESC
.WORD
.BYTE
.BYTE
.LONG

DSC$W LENGTH = 0
DSC$B=DTYPE = STRING
DSC$B_CLASS = DYNAMIC
DSC$A_POINTER = 0

0
DSC$K DTYPE T
DSC$K=CLAS(~D
0

.ENDM
Storage for page header information
FILE:
USER:
ACCOUNT:

D DESC
D DESC
D_DESC

PAGE:
LINE:

.LONG
.LONG

file name descriptor
user name descriptor
account name descriptor
page number
line number

0
0

FAO control string and work buffer. Header format:
"[account,name] filename ........ Page 9999"
FAO CTRL:
FAO CTRL 2:
FAO DESC:
FAO BUFF:

.ASCID /!71<[!AS,
.ASCID I! 4UL/
.LONG
80
.ADDRESS FAO BUFF
.BLKB
80

!AS]

!AS!>Page 9999/
work buffer descriptor
work buff er
(continued on next page)

PSM-19

Print Symbiont Modification {PSM) Routines
11.4 Example of Using the PSM Routines

Example 11-1 (Cont.) Using PSM Routines to Supply a Page Header Routine in a MACRO
Program
Own storage for values passed by reference
CODE:
STREAMS:
BUFSIZ:
LINSIZ:

.LONG
.LONG
.LONG
.WORD

Main routine
START:

.WORD

1
2048
81

service or item code
number of simultaneous streams
output buff er size
line size for underlines

invoked at image startup
0

save nothing because this routine uses only RO and Rl

Supply private page header routine
MOVZBL
PUSHAL
PUSHAL
CALLS
BLBC

#PSM$K_PAGE_HEADER,CODE
HEADER
CODE
#2,GAPSM$REPLACE
R0,10$

set the service code
address of modified routine
address of service code
replace the routine
exit if any errors

Transfer control to the standard symbiont

10$:

PUSHAL
PUSHAL
CALLS
RET

BUFSIZ
STREAMS
#2,GAPSM$PRINT

address of output buffer size
address of number of streams
invoke standard symbiont

Page header routine
HEADER:

.WORD

save nothing

Check function code

15$:
16$:

CMPL
BEQL
CMPL
BNEQ
BRW
CMPL
BNEQ
BRW
MOVL
RET

#PSM$K START TASK,@FUNC(AP)
20$
#PSM$K_READ,@FUNC(AP)
15$
50$
#PSM$K OPEN, @FUNC(AP)
16$
66$
#PSM$_FUNNOTSUP,RO

new task?
branch if so
READ function?
branch if so
OPEN function?
branch if so
unsupported function
return to symbiont

Starting a new file
20$:
CLRL
MOVZBL

PAGE
#2,LINE

reset the page number
and the line number
(continued on next page)

PSM-20

Print Symbiont Modification (PSM) Routines
11.4 Example· of Using the PSM Routines

Example 11-1 (Cont.)

Using PSM Routines to Supply a Page Header Routine in a MACRO
Program

Get the account name
MOVZBL
PUS HAL
PUS HAL
PUS HAL
CALLS
BLBC

#SMBMSG$K_ACCOUNT NAME,CODE
ACCOUNT
CODE
@CONTEXT(AP)
#3,GAPSM$READ_ITEM DX
R0,40$

set item code
address of descriptor
address of item code
address of symbiont ctx value
read it
branch if any errors

Get the file name
MOVZBL
PUS HAL
PUS HAL
PUS HAL
CALLS
BLBC

#SMBMSG$K_FILE SPECIFICATION,CODE
set item code
FILE
address of descriptor
CODE
address of item code
@CONTEXT(AP)
address of symbiont ctx value
#3,GAPSM$READ_ITEM DX
read it
R0,40$
branch if any errors

Get the user name
MOVZBL
PUSHAL
PUSHAL
PUSHAL
CALLS
BLBC

#SMBMSG$K_USER NAME,CODE
USER
CODE
@CONTEXT(AP)
#3,GAPSM$READ_ITEM DX
R0,40$

set item code
address of descriptor
address of item code
address of symbiont ctx value
read it
branch if any errors

Set up the static header information that is constant for the task
$FAO_S

40$:
;
;

BLBC
MOVL
RET

CTRSTR
FAO_CTRL, OUTBUF
FAO DESC, Pl
#ACCOUNT, P2
#USER, P3
#FILE
R0,40$
#PSM$_FUNNOTSUP,RO

FAO control string desc
output buffer descriptor
account name descriptor
user name descriptor
file name descriptor
branch if any errors
unsupported function
return usupported status or error

Read a page header

50$:
DECL
BEQL
BLSS

LINE
60$
70$

decrement the line number
branch if second read
branch if third read
(continued on next page)

PSM-21

Print Symbiont Modification (PSM) Routines
11.4 Example of Using the PSM Routines

Example 11-1 (Cont.)

Using PSM Routines to Supply a Page Header Routine in a MACRO
Program

Insert the page number into the header
INCL
MOVAB
$FAO_S
MOVAB
BLBC

PAGE
FAO_BUFF+76,FAO_DESC+4
CTRSTR
FAO_CTRL_2, OUTBUF = FAO_DESC, Pl
= PAGE
FAQ BUFF,FAO DESC+4
RO,S5$
-

increment the page number
point to page number buff er
FAO control string desc
output buff er descriptor
page number
point to work buff er
return if error

Copy the line to the symbiont's buffer

55$:

PUSHAB
PUSHL
CALLS
RET

FAO DESC
FUNC DESC(AP)
#2,GASTR$COPY_DX

work buff er descriptor
symbiont descriptor
copy to symbiont buff er
return success or any error

Second line -- underline header
60$:

65$:

66$:
67$:

PUSHL
PUSHAL
CALLS
BLBC
MOVL
MOVL
MOVAB
MOVB
CMPL
BGTRU
MOVB
MOVZBL
RET

FUNC_DESC(AP)
LINSIZ
#2,GASTR$GET1 DX
R0,67$
FUNC_DESC(AP),Rl
4(Rl),Rl
80(Rl),RO
#AA/-/, (Rl)+
RO,Rl
65$
#10, (Rl)+
#SS$_NORMAL,RO

symbiont descriptor
number of bytes to reserve
reserve the space
exit if error
get address of descriptor
get address of buffer
set up transfer limit
fill with dashes
reached limit?
branch if not
extra line feed
set success
return

Done with this page header
70$:

11.5

MOVL
MOVZBL
RET

#PSM$ EOF,RO
#2,LINE

.END

START

return end of input
reset line counter
return

PSM Routines
The following pages describe the individual PSM routines.

PSM-22

Print Symbiont Modification {PSM) Routines
PSM$PRINT

PSM$PRINT Invoke VMS-Supplied Print Symbiont
The PSM$PRINT routine invokes the VMS-supplied print symbiont.
PSM$PRINT must be called exactly once after all user service routines have
been specified using PSM$REPLACE.

FORMAT

PSM$PRINT [streams] [,bufsiz] [,worksiz]

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

streams
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Maximum number of streams that the print symbiont is to support. The
streams argument is the address of a longword containing this number,
which must be in the range 1 to 16. If you do not specify streams, a
default value of 1 is used. Thus, by default, a user-modified print symbiont
supports one stream, which is to say that it is a single-threaded symbiont.
A stream (or thread) is a logical link between a print execution queue
and a printing device. When a symbiont process can accept simultaneous
links to more than one queue, that is, when it can service multiple queues
simultaneously, the symbiont is said to be multithreaded.

bufsiz
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Maximum buffer size in bytes that the print symbiont is to use for output
operations. The bufsiz argument is the address of a longword containing
the specified number of bytes.
The print symbiont actually uses a buffer size that is the smaller of ( 1 )
the value specified by bufsiz or ( 2) the SYSGEN parameter MAXBUF.
If you do not specify bufsiz, then the print symbiont uses the value of
MAXBUF.
The print symbiont uses this size limit only for output operations. Output
operations involve the placing of processed or formatted pages into a buffer
that will be passed to the output routine.
PSM-23

Print Symbiont Modification (PSM) Routines
PSM$PRINT

The print symbiont uses the value specified by bufsiz only as an upper
limit; most buffers that it writes will be smaller than this value.

worksiz
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
Size in bytes of a work area to be allocated for the use of user routines.
The worksiz argument is the address of a longword containing this size
in bytes. If you do not specify worksiz, no work area is allocated.

A separate area of the specified size is allocated for each active symbiont
stream.

DESCRIPTION

The PSM$PRINT routine must be called exactly once after all user
routines have been specified to the print symbiont. Each user routine
is specified to the symbiont in a call to the PSM$REPLACE routine.
The PSM$PRINT routine allows you to specify whether the print symbiont
is to be single-threaded or multithreaded, and if multithreaded, how many
streams or threads it can have. In addition, this routine allows you to
control the maximum size of the output buffer.

CONDITION
VALUES
RETURNED

PSM-24

SS$_NORMAL

Normal successful completion.

This routine also returns any condition values returned by the $SETPRV,
$GETSYI, $PURGWS, and $DCLAST system services, as well as any
condition values returned by the SMB$INITIALIZE routine documented in
Chapter 12.

Print Symbiont Modification (PSM) Routines
PSM$READ_ITEM_DX

PSM$READ_ITEM_DX Obtain Value of Message
Items
The PSM$READ_ITEM_DX routine obtains the value of message items that
are sent by the job controller and stored by the VMS symbiont.

FORMAT

PSM$READ_ITEM_DX

RETURNS

VMS usage:
type:
access:
mechanism:

request_id ,item ,buffer

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

req.uest_id
address
longword (unsigned)
read only
by reference
Request identifier supplied by the symbiont to the user routine currently
calling PSM$READ_ITEM_DX. The symbiont always supplies a request
identifier when it calls a user routine with a service request. The
request_id argument is the address of a longword containing this request
identifier value.
VMS usage:
type:
access:
mechanism:

Your user routine must copy the request identifier value that the symbiont
supplies (in the request_id argument) when it calls your user routine.
Then, when your user routine calls PSM$READ_ITEM_DX, it must supply
(in the request_id argument) the address of the request identifier value
that it copied.

item
longword_unsigned
longword (unsigned)
read only
by reference
Item code that identifies the message item that PSM$READ_ITEM_DX is
to return. The item argument is the address of a longword that specifies
the item's code.

VMS usage:
type:
access:
mechanism:

For a complete list and description of each item code, refer to the
documentation of the item argument in the SMB$READ_MESSAGE_
ITEM routine in Chapter 12.

PSM-25

Print Symbiont Modification (PSM) Routines
PSM$READ_ITEM_DX

buffer
VMS usage: char_string
type:
character string
access:
write only
mechanism: by descriptor
Buffer into which PSM$READ_ITEM_DX returns the specified
informational item. The buffer argument is the address of a descriptor
pointing to this buffer.

The PSM$READ_ITEM_DX routine returns the specified informational
item by copying that item to the buffer using one of the STR$COPY_xx
routines documented in the VMS Run-Time Library Routines Volume.

DESCRIPTION

CONDITION
VALUES
RETURNED

PSM-26

The PSM$READ_ITEM_DX routine obtains the value of message items
that are sent by the job controller and stored by the VMS symbiont.
You use PSM$READ_ITEM_DX to obtain information about the task
currently being processed, for example, the name of the file being printed
(SMBMSG$K_FILE_SPECIFICATION) or the name of the user who
submitted the job (SMBMSG$K_USER_NAME).

SS$_NORMAL

Normal successful completion.

PSM$_1NVITMCOD

Invalid item code specified in the item argument.

This routine also returns any condition values returned by any of the
STR$COPY_xx routines documented in the VMS Run-Time Library
Routines Volume.

Print Symbiont Modification (PSM) Routines

PSM$REPLACE

Declare User Service Routine

The PSM$REPLACE routine substitutes a user service routine for a symbiont
routine or adds a user service routine to the set of symbiont routines.
You must call PSM$REPLACE once for each routine that you replace or add.

code ,routine

FORMAT

PSM$REPLACE

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Longword condition value. Most utility routines return a condition value
in RO. The condition value that this routine can return is listed under
CONDITION VALUE RETURNED.

ARGUMENTS

code
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
Routine code that identifies the symbiont routine to be replaced by a
user service routine. The code argument is the address of a longword
containing the routine code.

Some routine codes identify routines that are supplied with the VMS
symbiont; when you specify such a routine code, you replace the symbiontsupplied routine with your service routine.
Two routine codes identify routines that are not supplied with the VMS
symbiont; when you specify such a routine code, your service routine is
added to the set of symbiont routines.
Table 11-1 lists each routine code in the order in which it is called within
the symbiont execution stream; this table also specifies whether a routine
code identifies an input, formatting, or output routine and whether the
routine is supplied with the VMS symbiont.
The routine codes are defined by the $PSMDEF macro. The following
pages list each routine code in alphabetical order; the description of each
code includes the following information about its corresponding routine:
•

Whether the routine is supplied by the VMS symbiont

•

Whether the routine is an input, formatting, or output routine

•

Under what conditions the routine is called

•

What task the routine performs

PSM-27

Print Symbiont Modification {PSM) Routines

PSM$REPLACE
Routine Codes
PSM$K_FILE_BURST
This code identifies a symbiont-supplied input routine; it is called
whenever a file burst page is requested. This routine obtains information
about the job, formats the file burst page, and returns the contents of
the page to the input buffer. A file burst page follows a file flag page and
precedes the contents of the file.
PSM$K_FILE_ERRORS
This code identifies a symbiont-supplied input routine; it is called when
errors have occurred during the job. This routine places the error message
text in the input buffer.
PSM$K_FILE_FLAG
This code identifies a symbiont-supplied input routine; it is called
whenever a file flag page is requested. This routine obtains information
about the job, formats the file flag page, and returns the contents of the
page to the input buffer. A flag page follows the job burst page (if any)
and precedes the file burst page (if any). It contains such information as
the file specification of the file and the name of the user issuing the print
request.
PSM$K_FILE_INFORMATION
This code identifies a symbiont-supplied input routine; it is called when
the file information item has been specified by the job controller. This
routine expands the file information item to text and returns it to the
input buffer.
PSM$K_FILE_SETUP
This code identifies a symbiont-supplied input routine; it is always called.
This routine queues any specified file-setup modules for insertion in the
input stream when the PSM$K_FILE_SETUP routine closes.
PSM$K_FILE_SETUP_2
This code identifies a symbiont-supplied input routine; it is always called.
This routine returns a formfeed to ensure that printing of the file begins
at the top of the page. This routine is called just before the main input
routine.
PSM$K_FILE_TRAILER
This code identifies a symbiont-supplied input routine; it is called
whenever a file trailer page is requested. This routine obtains information
about the job, formats the file trailer page, and returns the contents of the
page to the input buffer. A trailer page follows the last page of the file
contents.
PSM$K_MAIN_FORMAT
This code identifies the symbiont-supplied formatting routine; it is always
called. This routine performs numerous formatting functions. You cannot
replace this routine.
PSM$K_FORM_SETUP
This code identifies a symbiont-supplied input routine; it is always called.
This routine queues any specified form-setup modules for insertion in the
input stream when the PSM$K_FORM_SETUP routine closes.
PSM-28

Print Symbiont Modification (PSM) Routines

PSM$REPLACE
PSM$K_INPUT_FILTER
This code identifies a format routine that is not supplied by the VMS
symbiont. If the routine is supplied by the user, it is always called
immediately prior to the symbiont-supplied formatting routine (routine
code PSM$K_MAIN_FORMAT). An input-filter service routine is useful
for modifying input data records and their carriage control before they are
formatted by the symbiont.
PSM$K_JOB_BURST
This code identifies a symbiont-supplied input routine; it is called
whenever a job burst page is requested. This routine obtains information
about the job, formats the job burst page, and returns the contents of the
page to the input buffer. A job burst page follows the job flag page and
precedes the file flag page (if any) of the first file in the job. It is similar to
a file burst page except that it appears only once per job and only at the
beginning of the job.
PSM$K_JOB_COMPLETION
This code identifies a symbiont-supplied input routine; it is always called.
This routine returns a formfeed, which causes any output buffered by the
device to be printed.
PSM$K_JOB_FLAG
This code identifies a symbiont-supplied input routine; it is called
whenever a job flag page is requested. This routine obtains information
about the job, formats the job flag page, and returns the contents of the
page to the input buffer. A job flag page is similar to a file flag page except
that it appears only once per job, preceding the job burst page (if any).
PSM$K_JOB_RESET
This code identifies a symbiont-supplied input routine; it is always called.
This routine queues any specified job-reset modules for insertion in the
input stream when the PSM$K_JOB_RESET routine closes.
PSM$K_JOB_SETUP
This code identifies a symbiont-supplied input routine; it is always called.
This routine checks to see if this is the first job to be printed on the device,
and if so, it issues a formfeed and then performs a job reset. See the
description of the PSM$K_JOB_RESET routine for information about job
reset.
PSM$K_JOB_TRAILER
This code identifies a symbiont-supplied input routine; it is called
whenever a job trailer page is requested. This routine obtains information
about the job, formats the job trailer page, and returns the contents of the
page to the input buffer. A job trailer page is similar to a file trailer page
except that it appears only once per job, as the last page in the job.
PSM$K_MAIN_INPUT
This code identifies a symbiont-supplied input routine; it is always called.
This routine opens the file to be printed, returns input records to the input
buffer, and closes the file.

PSM-29

Print Symbiont Modification {PSM) Routines

PSM$REPLACE
PSM$K_LIBRARV_INPUT
This code identifies a symbiont-supplied input routine; it is called when an
input routine closes and when modules have been requested for insertion
in the input stream. This routine returns the contents of the specified
modules, one record per call. You cannot replace this routine.

PSM$K_OUTPUT_FILTER
This code identifies a formatting routine that is not supplied by the
VMS symbiont. If the routine is supplied by the user, it is always called.
This routine executes prior to the symbiont output routine (routine code
PSM$K_OUTPUT). An output-filter service routine is useful for modifying
output data buffers before they are passed to the output routine.
At the point where the output-filter routine executes within the symbiont
execution stream, the input data is no longer in record format; instead, the
data exists as a stream of characters. The carriage control, for example, is
embedded in the data stream. Thus, the output buffer might contain what
was once a complete record, part of a record, or several records.

PSM$K_PAGE_HEADER
This code identifies a symbiont-supplied input routine; it is called once at
the beginning of each page if page headers are requested. This routine
returns to the input buffer one or more lines containing information about
the file being printed and the current page number. This routine is called
only while the main input routine is open.

PSM$K_PAGE_SETUP
This code identifies a symbiont-supplied routine; it is called at the
beginning of each page if page-setup modules were specified. This routine
queues any specified page-setup modules for insertion in the input stream
when the PSM$K_PAGE_SETUP routine closes. This routine is called
only while the main input routine is open.

PSM$K_OUTPUT
This code identifies the symbiont-supplied output routine; it is always
called. This routine writes the contents of the output buffer to the printing
device, but it also performs many other functions.

routine
VMS usage: procedure
procedure entry mask
access:
read only
mechanism: by reference
User service routine that is to replace a symbiont routine or to be included.
The routine argument is the address of the user routine entry point.
type:

DESCRIPTION

The PSM$REPLACE routine must be called each time a user service
routine replaces a symbiont routine or is added to a set of symbiont
routines.
The code argument specifies the symbiont routine to be replaced. The
routine codes that can be specified in the code argument are of two types:
those that identify existing print symbiont routines and those that do not.
All the routine codes are similar, however, in the sense that each supplies

PSM-30

Print Symbiont Modification (PSM) Routines

PSM$REPLACE
a location within the print symbiont execution stream where your routine
can execute.
By selecting a routine code that identifies an existing symbiont routine,
you effectively disable that symbiont routine. The service routine that
you specify might or might not perform the function that the disabled
symbiont routine performs. If it does not, the net effect of the replacement
is to eliminate that function from the list of functions performed by the
print symbiont. Exactly what your service routine does is up to you.
By selecting a routine code that does not identify an existing symbiont
routine (those that identify the input-filter and output-filter routines), your
service routine has a chance to execute at the location signified by the
routine code. Because the service routine you specify to execute at this
location does not replace another symbiont routine, your service routine is
an addition to the set of symbiont routines.
As mentioned, each routine code identifies a location in the symbiont
execution stream, whether or not it identifies a symbiont routine.
Table 11-1 lists each routine code in the order in which the location it
identifies is reached within the symbiont execution stream.

CONDITION
VALUE
RETURNED

SS$_NORMAL

Normal successful completion.

PSM-31

Print Symbiont Modification (PSM) Routines

PSM$REPORT

Report Completion Status

The PSM$REPORT routine reports to the print symbiont the completion status
of an asynchronous operation initiated by a user routine.
Such a user routine must return the completion status PSM$_PENDING.
PSM$REPORT must be called exactly once for each time a user routine
returns the status PSM$_PENDING.

FORMAT

PSM$REPORT requesLid [,status]

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. The condition value that this routine can return is listed under
CONDITION VALUE RETURNED.

ARGUMENTS

request_ id
VMS usage:
type:
access:
mechanism:

address
longword (unsigned)
read only
by reference

Request identifier supplied by the symbiont to the user routine at the time
the symbiont called the user routine with the service request. The user
routine must return the completion status PSM$_PENDING on the call
for this service request. The request_id argument is the address of a
longword containing the request identifier value.
The symbiont calls the user routine with a request code that specifies the
function that the symbiont expects the user routine to perform. In the call,
the symbiont also supplies a request identifier, which serves to identify
the request. If the user routine initiates an asynchronous operation, a
mechanism is required for notifying the symbiont that the asynchronous
operation has completed and for providing the completion status of the
operation.
The PSM$REPORT routine conveys the above two pieces of information.
In addition, PSM$REPORT returns to the symbiont (in the request_
id argument) the same request identifier value as that supplied by the
symbiont to the user routine that initiated the operation. In this way, the
symbiont synchronizes the completion status of an asynchronous operation
with that invocation of the user routine that initiated the operation.
Any user routine that initiates an asynchronous operation must, therefore,
copy the request identifier value that the symbiont supplies (in the
request_id argument) when it calls the user routine. The user routine
will later need to supply this value to PSM$REPORT.
PSM-32

Print Symbiont Modification (PSM) Routines
PSM$REPORT

In addition, when the user routine returns, which it does before the
asynchronous operation has completed, the user routine must return the
status PSM$_PENDING.

status
VMS usage: cond_value
type:
longword (unsigned)
access:
read only
mechanism: by reference
Completion status of the asynchronous operation that has completed. The
status argument is the address of a longword containing this completion
status. The status argument is optional; if it is not specified, the symbiont
assumes the completion status SS$_NORMAL.

The user routine that initiates the asynchronous operation must test
for the completion of the operation and must supply the operation's
completion status as the status argument to the PSM$REPORT routine.
The DESCRIPTION section describes this procedure in greater detail.
If the completion status specified by status has the low bit clear, the

symbiont aborts the task.

DESCRIPTION

An asynchronous operation is an operation that, once initiated, executes
"off to the side" and need not be completed before other operations can
begin to execute. Asynchronous operations are common in symbiont
applications because a symbiont, if it is multithreaded, must handle
concurrent I/O operations.

One example of a user routine that performs an asynchronous operation
is an output routine that calls the $QIO system service to write a record
to the printing device. When the user output routine completes execution,
the I/O request queued by $QIO might not have completed. In order to
synchronize this I/O request, that is, to associate the I/O request with the
service request that initiated it, you should use the following mechanism:
1

In making the call to $QIO, specify the astadr and iosb arguments.
The astadr argument specifies an AST routine to execute when
the queued output request has completed, and the iosb argument
specifies an I/O status block to receive the completion status of the I/O
operation. Item 3 describes some functions that your AST routine will
need to do.

Have the user output routine return the status PSM$_PENDING.

Write the AST routine to perform the following functions:

a. Copy the completion status word from the I/O status block to a
longword location that you will specify as the status argument in
the call to PSM$REPORT.
b. Call PSM$REPORT. Specify as the request_id argument the
request identifier that was supplied by the print symbiont in the
original call to the user output routine.

PSM-33

Print Symbiont Modification (PSM) Routines
PSM$REPORT

CONDITION
VALUE
RETURNED

PSM-34

SS$_NORMAL

Normal successful completion.

Print Symbiont Modification (PSM) Routines
USER-FORMAT-ROUTINE

USER-FORMAT-ROUTINE Invoke User-Written
Format Routine
The user-written USER-FORMAT-ROUTINE performs format operations.
The symbiont's control logic routine calls your format routine at one of two
possible points within the symbiont's execution stream. You select this point
by specifying one of two routine codes when you call the PSM$REPLACE
routine.
A user format routine can be an input filter routine (routine code PSM$K_
INPUT_FILTER) or an output filter routine (routine code PSM$K_OUTPUT_
FILTER). The main format routine (routine code PSM$K_MAIN_FORMAT)
cannot be replaced.
A user format routine must use the call interface described here.

FORMAT

USER-FORMAT-ROUTINE

RETURNS

VMS usage:
type:
access:
mechanism:

requesLid, work_ area
,tune ,func_desc_ 1
,func_arg_ 1 ,func_desc_2
,func_arg_2

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

request_ id
VMS usage:
type:
access:
mechanism:

address
longword (unsigned)
read only
by reference

Request identifier supplied by the symbiont when it calls your format
routine. The request_id argument is the address of a longword containing
this request identifier value.

work area
VMS usage:
type:
access:
mechanism:

address
longword (unsigned)
write only
by reference

Work area supplied by the symbiont for the use of your format routine.
The symbiont supplies the address of this area when it calls your routine.
The work_area argument is a longword containing the address of the
PSM-35

Print Symbiont Modification (PSM) Routines
USER-FORMAT-ROUTINE

work area. The work area is a section of memory that your format routine
can use for buffering and other internal operations.
The size of the work area allocated is specified by the work_size argument
in the PSM$PRINT routine. If you do not specify work_size in the call to
PSM$PRINT, no work area is allocated.
In a multithreaded symbiont, a separate work area is allocated for each
thread. This work area is shared by all user routines. The work area is
initialized to zero when the symbiont is first started.

lune
VMS usage: function_code
type:
longword (unsigned)
access:
read only
mechanism: by reference
Function code specifying the service that the symbiont expects your format
routine to perform. The func argument is the address of a longword into
which the symbiont writes this function code.

The function code specifies the reason the symbiont is calling your format
routine or, in other words, the service that the symbiont expects your
routine to perform at this time.
The PSM$K_FORMAT function code is the only one to which your format
routine must respond. When the symbiont calls your format routine with
this function code, your routine must move a record from the input buffer
to the output buffer.
The symbiont can call your format routine with other function codes.
Your routine should return the status PSM$_FUNNOTSUP (function not
supported) when it is called with any of the following function codes
or with any undocumented function code. When the status PSM$_
FUNNOTSUP is returned, the symbiont performs its normal action as
if no format routine were supplied. To suppress the symbiont's normal
action, you should return SS$_NORMAL.

PSM$K_START_STREAM
PSM$K_START_TASK
PSM$K_RESUME_TASK
PSM$K_RESET_STREAM

PSM$K_STOP_STREAM
PSM$K_PAUSE_TASK
PSM$K_STOP_TASK

These function codes correspond to message items, which are discussed in
more detail in Section 11.3.5, sent by the job controller to the symbiont.
Other function codes correspond to internal symbiont mechanisms that are
not part of the public interface to the print symbiont.
Your format routine should return the status PSM$_FUNNOTSUP or
SS$_NORMAL when it is called with a message function code or with a
private function code.

func_desc_1
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor

PSM-36

Print Symbiont Modification (PSM) Routines
USER-FORMAT-ROUTINE

Descriptor supplying an input record to be processed by the format routine.
The func_desc_l argument is the address of a string descriptor. By using
this argument, the symbiont supplies the input record that your format
routine is to process. Because this descriptor can be of any valid string
type, your format routine should use the Run-Time Library string routines
to analyze this descriptor and to manipulate the input record.

func_arg_1
VMS usage: vector_byte_unsigned
type:
byte (unsigned)
access:
read only
mechanism: by reference
Carriage control for the input record supplied by func_desc_l. The func_
arg_l argument is the address of a 4-byte vector that specifies the carriage
control for the input record. The following diagram depicts the format of
this 4-byte vector.

Character

Count

Trailing Carriage-Control
Information

Character

Count

Leading Carriage-Control
Information
ZK-2009-GE

Bytes 0 and 1 describe the leading carriage control to apply to the input
data record; bytes 2 and 3 describe the trailing carriage control.
Byte 0 is a number specifying the number of times the carriage control
specifier in byte 1 is to be repeated preceding the input data record. Byte
2 is a number specifying the number of times the carriage control specifier
in byte 3 is to be repeated following the input data record.
For values of the carriage control specifier from 1 to 255, the specifier is
the ASCII character to be used as carriage control. Value 0 represents the
ASCII "newline" sequence. Newline consists of a carriage return followed
by a linefeed.
The func_arg_l argument is not used if your format routine is an
output filter routine (routine code PSM$K_OUTPUT_FILTER). See the
DESCRIPTION section for more information.

func_desc_2
VMS usage: char_string
type:
character string
access:
write only
mechanism: by reference
Descriptor of a buffer to which your format routine writes the formatted
output record. The func_desc_2 argument is the address of a string
descriptor.

Your format routine must return the formatted data record by using the
func_desc_2 argument.
Your format routine should use the Run-Time Library string routines to
write into the buffer specified by this descriptor.
PSM-37

Print Symbiont Modification {PSM) Routines
USER-FORMAT-ROUTINE

func_arg_2
VMS usage: vector_byte_unsigned
type:
byte (unsigned)
access:
write only
mechanism: by reference
Carriage control for the output record returned in func_desc_2. The
func_arg_2 argument is the address of a 4-byte vector that specifies the
carriage control for the output record. See the description of func_arg_l
for the contents and format of this 4-byte vector.
If you do not process the carriage-control information supplied in func_
arg_l , then you should copy that value into func_arg_2. Otherwise, the
carriage-control information will be lost.

The func_arg_2 argument is not used if your format routine is an
output filter routine (routine code PSM$K_OUTPUT_FILTER). See the
DESCRIPTION section for more information.

DESCRIPTION

When used, the func_arg_l argument describes carriage-control
information for the input data record, and the func_arg_2 argument
describes carriage-control information for the output data record.
The input data record is passed to the format routine (input filter or
output filter) for processing, and the output data record is returned by the
format routine (input filter or output filter).
One of the tasks performed by the main format routine (routine code
PSM$K_MAIN_FORMAT) is that of embedding the carriage-control
information (specified by func_arg_l) into the data record (specified by
func_desc_l). Thus, the output data (specified by func_desc_2) contains
embedded carriage control and is thus no longer in record format; it is,
therefore, properly referred to as an output data stream rather than an
output data record.
Similarly, the output filter routine (routine code PSM$K_OUTPUT_
FILTER), which executes after the main format routine, uses neither
the func_arg_l nor func_arg_2 argument; the data it receives (via func_
desc_l) and the data it returns (via func_desc_2) are data streams, not
data records.
However, the input filter routine (routine code PSM$K_INPUT_FILTER),
which executes before the main format routine, uses both func_arg_l
and func_arg_2. This is so because the main format routine has not
yet executed, and so the carriage control information has not yet been
embedded in the data record.

PSM-38

Print Symbiont Modification (PSM) Routines
USER-FORMAT-ROUTINE

CONDITION
VALUES
RETURNED

SS$_NORMAL

Successful completion. The user format routine has
completed the function that the symbiont requested.

PSM$_FUNNOTSUP

Function not supported. The user format routine
does not support or does not recognize the function
code supplied by the symbiont. To ensure future
compatibility, your format routine should return this
status for any unrecognized status codes.

This routine also returns any error condition values that you have coded
your format routine to return. Refer to Section 11.3.1 for more information
about error condition values.

PSM-39

Print Symbiont Modification (PSM) Routines
USER-INPUT-ROUTINE

USER-INPUT-ROUTINE Invoke User-Written Input
Routine
The user-written USER-INPUT-ROUTINE performs input operations. The
symbiont calls your routine at a specified point in its execution stream; you
specify this point using the PSM$REPLACE routine.

FORMAT

USER-INPUT-ROUTINE

RETURNS

VMS usage:
type:
access:
mechanism:

request_id, work_area ,tune
,funcdesc ,funcarg

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

request_ id
VMS usage: address
type:
longword (unsigned)
access:
read only
mechanism: by reference
Request identifier value supplied by the symbiont when it calls your input
routine. The request_id argument is the address of a longword containing
this request identifier value.

If your input routine initiates an asynchronous operation (for example,
a call to the $QIO system service), your input routine must copy the
request identifier value specified by request_id because this value must
later be passed to the PSM$REPORT routine. See the description of the
PSM$REPORT routine for more information.

work area
VMS usage: address
type:
longword (unsigned)
access:
write only
mechanism: by reference
Work area supplied by the symbiont for the use of your input routine. The
symbiont supplies the address of this area when it calls your routine. The
work_area argument is a longword into which the symbiont writes the
address of the work area. The work area is a section of memory that your
input routine can use for buffering and for other internal operations.

The size of the work area allocated is specified by the work_size argument
in the PSM$PRINT routine. If you do not specify work_size in the call to
PSM$PRINT, no work area is allocated.
PSM-40

Print Symbiont Modification {PSM) Routines
USER-INPUT-ROUTINE

In a multithreaded symbiont, a separate work area is allocated for each

thread. This work area is shared by all user routines. The work area is
initialized to zero when the symbiont is first started.

tune
VMS usage: function_code
longword (unsigned)
access:
read only
mechanism: by reference
Function code supplied by the symbiont when it calls your input routine.
The func argument is the address of a longword containing this code.
type:

The function code specifies the reason the symbiont is calling your input
routine or, in other words, the function that the symbiont expects your
routine to perform at this time.
Most function codes require or allow additional information to be passed
in the call by means of the funcdesc and funcarg arguments. The
description of each input function code, therefore, includes a description of
how these two arguments are used with that function code.
Following is a list of all the function codes that the symbiont can specify
when it calls your input routine (function codes applicable only to format
and output routines are explained in the descriptions of the USERFORMAT-ROUTINE and USER-OUTPUT-ROUTINE, respectively); all
function codes are defined by the $PSMDEF macro.
Function Codes for Input Routines

PSM$K_CLOSE
When the symbiont calls your routine with this function code, your routine
must terminate processing by releasing any resources it might have
allocated.

The symbiont calls your routine with PSM$K_CLOSE when ( 1 ) your
routine returns from a PSM$K_READ function call with the status PSM$_
EOF (end of input) or with any error condition, or ( 2) the symbiont
receives a task-abortion request from the job controller.
In any event, the symbiont always calls your input routine with
PSM$K_CLOSE if your routine returns successfully from a PSM$K_OPEN
function call. This guaranteed behavior ensures that any resources your
routine might have allocated on the OPEN will be released on the CLOSE.
PSM$K_GET_KEY
Typically, the use of both the PSM$K_GET_KEY and PSMK$K_
POSITION_TO_KEY function codes is appropriate only for a main input
routine (routine code PSM$K_MAIN_INPUT).

When the symbiont calls your routine with this function code, your routine
can do one of two things: ( 1) return PSM$_FUNNOTSUP (function not
supported) or ( 2) return an input marker string to the symbiont.
If your routine returns PSM$_FUNNOTSUP to this function code, then
your routine must also return PSM$_FUNNOTSUP if the symbiont
subsequently calls your routine with the PSM$K_POSITION_TO_KEY
function code. By returning PSM$_FUNNOTSUP, your routine is choosing
not to respond to the symbiont request.
PSM-41

Print Symbiont Modification (PSM) Routines
USER-INPUT-ROUTINE

If your routine chooses to respond to the PSM$K_GET_KEY function code,
your routine. must return an input marker string to the symbiont; this
input marker string identifies the input record that your input routine
most recently returned to the symbiont. Subsequently, when the symbiont
calls your input routine with the PSM$K_POSITION_TO_KEY function
code, the symbiont passes your input routine one of the input marker
strings that your input routine has returned on a previous PSM$K_GET_
KEY function call. Using this marker string, your input routine must
position itself so that, on the next PSM$K_READ call from the symbiont,
your input routine will return (or reread) the input record identified by the
marker string.

Coding your input routine to respond to PSM$K_GET_KEY and PSM$K_
POSITION_TO_KEY allows the modified symbiont to perform the filepositioning functions specified by the DCL commands START/QUEUE
/FORWARD, START/QUEUE/ALIGN, START/QUEUE/TOP_OF_FILE,
START/QUEUE/SEARCH, and START/QUEUE/BACKWARD. These file
positioning functions also depend on the job controller's checkpointing
capability for print jobs.
Note that your input routine might be called with a marker string that
was originally returned in a different process context from the current
one. This can occur because marker strings are sometimes stored in the
queue-data file across system shutdowns or different invocations of your.
symbiont.
The funcdesc argument specifies the address of a string descriptor. Your
routine must return the marker string by way of this argument. Digital
recommends that you use one of the Run-Time Library string routines to
copy the marker string to the descriptor.
The symbiont periodically calls your input routine with the PSM$K_
GET_KEY function code when the symbiont wants to save a marker to a
particular input record.

PSM$K_OPEN
When the symbiont calls your routine with this function code, your routine
should prepare for input operations by performing such tasks as allocating
necessary resources, initializing storage areas, opening an input file, and
so on. Typically, the next time the symbiont calls your input routine, the
symbiont will specify the PSM$K_READ function code. Note, however,
that under some circumstances the symbiont might follow an OPEN call
immediately with a CLOSE call.
The funcdesc argument points to the name of the file to be opened. Your
routine can use this file specification or the file identifcation to open the
file.
The funcarg argument specifies the address of a longword. Your input
routine must return, in this longword, the carriage control type that is to
be applied to the input records that your input routine will provide.
The symbiont formatting routine requires this information to determine
where to apply leading and trailing carriage control characters to the input
records that your input routine will provide.

PSM-42

Print Symbiont Modification (PSM) Routines
USER-INPUT-ROUTINE

The $PSMDEF macro defines the following four carriage control types:
Carriage Type

Description

PSM$K_CC_IMPLIED

Implied carriage control. For this type, the symbiont
inserts a leading linefeed ( LF) and trailing carriage
return (CR) in each input record. This is the default
carriage control type; it is used if your routine does not
supply a carriage control type in the funcarg argument
in response to the PSM$K_OPEN function call.

PSM$K_CC_FORTRAN

FORTRAN carriage control. For this type, the symbiont
extracts the first byte of each input record and interprets
the byte as a FORTRAN carriage control character,
which it then applies to the input record.

PSM$K_CC_PRINT

PRN carriage control. For this type, the symbiont
generates carriage control from a 2-byte record header
that your input routine supplies, with each READ call, in
the funcarg argument. The funcarg argument specifies
the address of a longword to receive this two-byte header
record, which appears only in PRN print files.

PSM$K_CC_INTERNAL

Embedded carriage control. For this type, the symbiont
supplies no carriage control to input records. Carriage
control is assumed to be embedded in the input records.

PSM$K_POSITION_TO_KEY
When the symbiont calls your routine with this function code, your routine
must locate the point in the input stream designated by the marker string
that your routine returned to the symbiont on the PSM$K_GET_KEY
function call.

The next time the symbiont calls your routine, the symbiont specifies the
PSM$K_READ function call, expecting to receive the next sequential input
record. After rereading this record, subsequent READ calls proceed from
this new position of the file. This is not a one-time rereading of a single
record but a repositioning of the file. The symbiont calls your routine with
this function code when the job controller receives a request to resume
printing at a particular page.
Refer to the description of the PSM$K_GET_KEY for more information.
PSM$K_READ
When the symbiont calls your routine with this function code, your routine
must return an input record. The symbiont repeatedly calls your input
routine with the PSM$K_READ function code until ( 1) your routine
indicates end of input by returning the status PSM$_EOF, ( 2) your
routine or another routine returns an error status, or ( 3) the symbiont
receives an asynchronous task-abortion request from the job controller.

The funcdesc argument specifies the address of a string descriptor. Your
routine must return the input record by using this argument. Digital
recommends that you use one of the Run-Time Library string routines to
copy the input record to the descriptor.

PSM-43

Print Symbiont Modification {PSM) Routines
USER-INPUT-ROUTINE

The funcarg argument specifies the address of a longword. This argument
is used only if the carriage control type returned by your input routine on
the PSM$K_OPEN function call was PSM$K_CC_PRINT. In this case,
your input routine must supply, in the funcarg argument, the 2-byte
record header found at the beginning of each input record.
PSM$K_REWIND

When the symbiont calls your routine with this function code, your routine
must do one of two things: ( 1 ) return PSM$_FUNNOTSUP (function not
supported) or ( 2) locate the point in the input stream designated as the
beginning of the file.
If your routine returns PSM$_FUNNOTSUP to this function code, then
the symbiont subsequently calls your input routine with a PSM$K_
CLOSE function call followed by a PSM$K_OPEN function call. By
returning PSM$_FUNNOTSUP, your routine is choosing not to support
the repositioning of the input service to the beginning of the file. The
symbiont, therefore, performs the desired function by closing and then
reopening the input routine.

You cannot use the funcdesc and the funcarg arguments with this
function code.
This function call allows the modified symbiont to perform the
file-positioning functions specified by the DCL commands START
/QUEUE/TOP_OF_FILE, START/QUEUE/FORWARD, START/QUEUE
/BACKWARD, START/QUEUE/SEARCH, and START/QUEUE/ALIGN.
This is a required repositioning of the file.
Other Input Function Codes
The symbiont can call your input routine with other function codes.
Your routine must return the status PSM$_FUNNOTSUP (function not
supported) when it is called with any of the following function codes
or with any undocumented function code. When the status PSM$_
FUNNOTSUP is returned, the symbiont performs its normal action as
if no input routine were supplied. To suppress the symbiont's normal
action, you should return SS$_NORMAL.

PSM$K_START_STREAM
PSM$K_START_TASK
PSM$K_RESUME_TASK
PSM$K_RESET_STREAM

PSM$K_STOP_STREAM
PSM$K_PAUSE_TASK
PSM$K_STOP_TASK

These function codes correspond to message items, which are discussed in
detail in Section 11.3.5, sent by the job controller to the symbiont.
Other function codes correspond to internal symbiont mechanisms that are
not part of the public interface to the print symbiont.
Your input routine should return the status PSM$_FUNNOTSUP or SS$_
NORMAL when it is called with a message function code or with a private
function code.

funcdesc
VMS usage:
type:
access:
mechanism:
PSM-44

char_string
character string
read only
by descriptor

Print Symbiont Modification {PSM) Routines
USER-INPUT-ROUTINE

Function descriptor supplying information related to the function specified
by the func argument. The funcdesc argument is the address of this
descriptor.
The contents of the function descriptor vary for each function. Refer to the
description of each function code to determine the contents of the function
descriptor. In some cases, the function descriptor is not used at all.

funcarg
VMS usage: longword_unsigned
longword (unsigned)
access:
read only
mechanism: by reference
Function argument supplying information related to the function specified
by the func argument. The funcarg argument is the address of a
longword containing this function argument. This argument can be an
input or an output argument, depending on the function request, but is
usually used as an output argument.
type:

CONDITION
VALUES
RETURNED

SS$_NORMAL

Successful completion. The user input routine has
completed the function that the symbiont requested.

PSM$_FLUSH

Flush output stream. The user input routine can
return this status only when called with the PSM$K_
READ function code. When this status is returned
to the symbiont, the symbiont stops calling the input
routine with the PSM$K_READ function code until
all outstanding format and output operations have
completed.

PSM$_FUNNOTSUP

Function not supported. The user input routine
does not support or does not recognize the function
code supplied by the symbiont. To ensure future
compatibility, your input routine should return this
status for any unrecognized status codes.

PSM$_PENDING

Requested function accepted but not completed.
Your input routine can return this status only with
the PSM$K_READ function call. Further, if your
routine returns PSM$_PENDING, your routine must
eventually signal completion via the PSM$REPORT
routine. Refer to the description of the PSM$REPORT
routine for more information about asynchronous
operations and the PSM$_PENDING condition value.

This routine also returns any error condition values that you have coded
your format routine to return. Refer to Section 11.3.1 for more information
about error condition values.

PSM-45

Print Symbiont Modification (PSM) Routines
USER-OUTPUT-ROUTINE

USER-OUTPUT-ROUTINE Invoke User-Written
Output Routine
The user-written USER-OUTPUT-ROUTINE performs output operations. You
supply a user output routine by calling the PSM$REPLACE routine with the
routine code PSM$K_OUTPUT.

FORMAT

USER-OUTPUT-ROUTINE

RETURNS

VMS usage:
type:
access:
mechanism:

request_id, work_ area
,tune ,funcdesc ,funcarg

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

request_ id
VMS usage: address
type:
longword (unsigned)
access:
read only
mechanism: by reference
Request identifier value supplied by the symbiont when it calls your
output routine. The request_id argument is the address of a longword
containing this value.
If your output routine initiates an asynchronous operation (for example,

a call to the Queue I/O Request (SYS$QIO) system service), you must
save the request_id argument because you will need to store the request
identifier value for later use with the PSM$REPORT routine. See the
description of the PSM$REPORT routine for more information.

work_area
VMS usage: address
type:
longword (unsigned)
access:
write only
mechanism: by reference
Work area supplied by the symbiont for the use of your format routine.
The symbiont supplies the address of this area when it calls your routine.
The work_area argument is a longword containing the address of the
work area. The work area is a section of memory that your format routine
can use for buffering and other internal operations.

The size of the work area allocated is specified by the work_size argument
in the PSM$PRINT routine. If you do not specify work_size in the call to
PSM$PRINT, no work area is allocated.
PSM-46

Print Symbiont Modification (PSM) Routines
USER-OUTPUT-ROUTINE

In a multithreaded symbiont, a separate work area is allocated for each
thread. This work area is shared by all user routines. The work area is
initialized to zero when the symbiont is first started.

tune
VMS usage:
type:
access:
mechanism:

function_code
longword (unsigned)
read only
by reference

Function code supplied by the symbiont when it calls your output routine.
The func argument is the address of a longword containing this code.
The function code specifies the reason the symbiont is calling your output
routine or, in other words, the function that the symbiont expects your
routine to perform at this time.
Most function codes require or allow additional information to be passed
in the call via the funcdesc and funcarg arguments. The description of
each output function code, therefore, includes a description of how these
two arguments are used for that function code.
The following list describes all the function codes that the symbiont might
supply when it calls your output routine (function codes applicable only to
input and formatting routines are explained in the descriptions of the user
input routine and user formatting routine, respectively); all function codes
are defined by the $PSMDEF macro.
Function Codes for Output Routines

PSM$K_OPEN
When the symbiont calls your output routine with this function code, your
routine should prepare to move data to the device by performing such
tasks as allocating the device, assigning a channel to the device, and so
on. The next time the symbiont calls your output routine, the symbiont
specifies one of the WRITE function codes (PSM$K_WRITE or PSM$K_
WRITE_NOFORMAT).
The symbiont calls your output routine with the PSM$K_OPEN function
code when the symbiont receives the SMBMSG$K_START_STREAM
message from the job controller.
If your output routine returns an error condition value (low bit clear) to
the PSM$K_OPEN function call, the job controller stops processing on
the stream and reports the error to whomever entered the DCL command
START/QUEUE.
The funcdesc argument is the address of a descriptor that identifies the
name of the device the output routine is to write to. This device name is
established by the DCL command INITIALIZE/QUEUE/ON=device-name.
The funcarg argument is the address of a longword into which the user
output routine returns the device status longword. For the contents of
the device status longword, refer to the description of the SMBMSG$K_
DEVICE_STATUS item in the SMB$READ_MESSAGE_ITEM routine,
which is documented in Chapter 12.

PSM-47

Print Symbiont Modification (PSM) Routines
USER-OUTPUT-ROUTINE

Your output routine sets bits in the device status longword to indicate
to the job controller whether the device falls into one of the following
categories:
•

Can print lowercase letters

•

Is a terminal

•

Is connected to the CPU by means of a modem (remote)

If your output routine does not set any of these bits in the device status

longword, the job controller assumes, by default, that the device is a line
printer that prints only uppercase letters.
PSM$K_WRITE
When the symbiont calls your routine with this function code, your routine
must write data to the device. The symbiont supplies the data to be
written in the funcdesc argument. Digital recommends that you use one
of the Run-Time Library string routines to access the data in the buffer
described by the funcdesc argument.
PSM$K_WRITE_NOFORMAT
When the symbiont calls your routine with this function code, your routine
must write data to the device and must indicate to the device driver that
the data is not to be formatted.

The symbiont calls your routine with this function code when ( 1 ) the print
request specifies the PASSALL option or ( 2) data is introduced by the
ANSI DCS (device control string) escape sequence.
The symbiont supplies the data to be written in the funcdesc argument.
Digital recommends that you use one of the Run-Time Library string
routines to move the data from the descriptor to the device.
The output routine of the symbiont informs the device driver not to format
the data in the following way:
•

When the device is a line printer, the symbiont's output routine
specifies the IO$_WRITEPBLK function code when it calls the $QIO
system service.

•

When the device is a terminal, the symbiont's output routine specifies
the IO$M_NOFORMAT function modifier when it calls the $QIO
system serivce.

PSM$K_CANCEL
When the symbiont calls your routine with this function code, your routine
must abort any outstanding asynchronous 1/0 requests.

The output routine supplied by the symbiont aborts outstanding 1/0
requests by calling the $CANCEL system service with the I0$_CANCEL
function code.

PSM-48

Print Symbiont Modification {PSM) Routines
USER-OUTPUT-ROUTINE

If your output routine returned the condition value PSM$_PENDING to
one or more previous write requests that are still outstanding (that is,
PSM$REPORT has not yet been called to report completion), then your
output routine must call PSM$REPORT one time for each outstanding
write request that is canceled with this call. That is, canceling an
asynchronous write request does not relieve the user output routine of
the requirement to call PSM$REPORT once for each asynchronous write
request.
You cannot use the funcdesc and funcarg arguments with this function
code.

PSM$K_CLOSE
When the symbiont calls your routine with this function code, your output
routine must terminate processing and release any resources it allocated
(for example, channels assigned to the device).
You cannot use the funcdesc and funcarg arguments with this function
code.
Other Output Function Codes
The symbiont can call your output routine with other function codes.
Your routine should return the status PSM$_FUNNOTSUP (function not
supported) when it is called with any of the following function codes
or with any undocumented function code. When the status PSM$_
FUNNOTSUP is returned, the symbiont performs its normal action as
if no output routine were supplied. To suppress the symbiont's normal
action, you should return SS$_NORMAL.

PSM$K_START_STREAM
PSM$K_START_TASK
PSM$K_RESUME_TASK
PSM$K_RESET_STREAM

PSM$K_STOP_STREAM
PSM$K_PAUSE_TASK
PSM$K_STOP_TASK

These function codes correspond to message items, which are discussed in
more detail in Section 12.1.6, sent by the job controller to the symbiont.
Other function codes correspond to internal symbiont mechanisms that are
not part of the public interface to the print symbiont.
Your output routine should return the status PSM$_FUNNOTSUP or
SS$_NORMAL when it is called with a message function code or with a
private function code.

funcdesc
VMS usage: char_string
character string
access:
read only
mechanism: by descriptor
Function descriptor supplying information related to the function specified
by the func argument. The funcdesc argument is the address of this
descriptor.
type:

The contents of the function descriptor vary for each function. Refer to the
description of each function code to determine the contents of the function
descriptor. In some cases, the function descriptor is not used at all.

PSM-49

Print Symbiont Modification (PSM) Routines
USER-OUTPUT-ROUTINE

funcarg
VMS usage: user_arg
type:
longword (unsigned)
access:
read only
mechanism: by reference
Function argument supplying information related to the function specified
by the func argument. The funcarg argument is the address of a
longword containing this function argument.

The contents of the function argument vary for each function. Refer to the
description of each function code to determine the contents of the function
argument. In some cases, the function argument is not used.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Successful completion. The user output routine has
completed the function that the symbiont requested.

PSM$_FUNNOTSUP

Function not supported. The user output routine
does not support or does not recognize the function
code supplied by the symbiont. To ensure future
compatibility, your output routine should return this
status for any unrecognized status codes.

PSM$_PENDING

Requested function accepted but not completed.
Your output routine can return this status only with
PSM$K_WRITE and PSM$K_WRITE_NOFORMAT
function calls. Further, if your routine returns PSM$_
PENDING, your routine must eventually signal
completion by way of the PSM$REPORT routine.
Refer to the description of the PSM$REPORT
routine for more information about asynchronous
write operations and the PSM$_PENDING condition
value.

This routine also returns any error condition values that you have coded
your output routine to return. Refer to Section 11.3.1 for more information
about error condition values.

PSM-50

12 Symbiont/Job Controller Interface (SMB) Routines
The Symbiont/Job Controller Interface (SMB) routines provide the
interface between the job controller and symbiont processes. A userwritten symbiont must use these routines to communicate with the VMS
job controller.

12.1

Introduction to SMB Routines
Always use the SMB interface routines or the SYS$SNDJBC or
SYS$GETQUI system services to communicate with the job controller.
You need not and should not attempt to communicate directly with the job
controller.
To write your own symbiont, you need to understand how symbionts work
and, in particular, how the standard VMS print symbiont behaves.

12.1.1

Types of Symbiont
There are two types of symbiont:
•

Device symbiont, either an input symbiont or an output symbiont.
An input symbiont is one that transfers data from a slow device to
a fast device, for example, from a card reader to a disk. A cardreader symbiont is an input symbiont. An output symbiont is one that
transfers data from a fast device to a slow device, for example, from a
disk to a printer or terminal. A print symbiont is an output symbiont.

•

Server symbiont, a symbiont that processes or transfers data but is
not associated with a particular device; one example is a symbiont that
transfers files across a network.

The VMS operating system does not supply any server symbionts.

12.1.2

Symbionts Supplied with the VMS Operating System
The VMS operating system supplies two symbionts:
•

SYS$SYSTEM:PRTSMB.EXE (PRTSMB for short), an output symbiont
for use with printers and printing terminals.
PRTSMB performs such functions as inserting flag, burst, and trailer
pages into the output stream; reading and formatting input files; and
writing formatted pages to the printing device.
You can modify PRTSMB using the Print Symbiont Modification (PSM)
routines.

•

SYS$SYSTEM:INPSMB.EXE (INPSMB for short) an input symbiont
for use with card readers.
SMB-1

Symbiont/Job Controller Interface (SMB) Routines
12.1 Introduction to SMB Routines

This symbiont handles the transferring of data from a card reader to
a disk file. You cannot modify INPSMB, nor can you write an input
symbiont using the SMB routines.

12.1.3

Symbiont Behavior in the VMS Environment
In the VMS environment, a symbiont is a process under the control of the
VMS job controller that transfers or processes data.
Figure 12-1 depicts the VMS components that take part in the handling
of user requests that involve symbionts. This figure shows two symbionts:
( 1 ) the print symbiont supplied by the VMS operating system, PRTSMB,
and ( 2) a user-written symbiont, GRAPHICS.EXE, which services a
graphics plotter. The numbers in the figure correspond to the numbers in
the list that follows.
This list does not reflect the activities that must be performed by the
hypothetical, user-written symbiont, GRAPHICS.EXE. This symbiont is
represented in the figure to illustrate the correspondence between a userwritten symbiont and the print symbiont supplied by the VMS operating
system.
Although SMB routines can be used for a different kind of symbiont, many
of their arguments and associated symbols have names related to the print
symbiont. The print symbiont is presented here as an example of a typical
symbiont and illustrates points that are generally true for symbionts.

8 You request a printing job with the DCL command PRINT. DCL calls
the Send to Job Controller (SYS$SNDJBC) system service, passing the
name of the file to be printed to the job controller, along with any other
information specified by qualifiers for the PRINT command.

8 The job controller places the print request in the appropriate queue
and assigns the request a job number.

8 The job controller breaks the print job into a number of tasks (for
example, printing three copies of the same file is three separate tasks).
The job controller makes a separate request to the symbiont for each
task.
Each request that the job controller makes consists of a message. Each
message consists of a code that indicates what the symbiont is to do
and a number of items of information that the symbiont needs to carry
out the task (the name of the file, the name of the user, and so on.)

8 PRTSMB interprets the information it receives from the job controller.

0 PRTSMB locates and opens the file it is to print by using the fileidentification number the job controller specified in the start-task
message.

Gt PRTSMB sends the data from the file to the printer's driver.

8 The device driver sends the data to the printer.

SMB-2

Symbiont/Job Controller Interface {SMB) Routines
12.1 Introduction to SMB Routines

Figure 12-1

Symbionts in the VMS Operating System Environment

User's Print Request

Job
Controller

Queue File

3
Job Controller/Symbiont
Interface

4
PRTSMB.EXE

GRAPHICS.EXE

5
Disk
File

Graphics
Device
Driver

Disk
File

6
Printer
Device
Driver

7
Graphics
Plotter

Standard
Printer
ZK-2010-GE

12.1.4

Writing a Symbiont
Writing your own symbiont permits you to use the queueing mechanisms
and control functions of the VMS job controller. You might want to do this
if you need a symbiont for a device that cannot be served by PRTSMB (or a
modified form of PRTSMB) or if you need a server symbiont. The interface
between the job controller and the symbiont permits the symbiont you
write to use the many features of the job controller.
For example, when you use the DCL command PRINT to print a file,
the job controller sends a message to the print symbiont telling it to
print the file. However, when a user-written symbiont receives the same
message (caused by entering a PRINT command), it might interpret
it to mean something quite different. A robot symbiont, for example,
might interpret the message as a command for movement and the
file specification (specified with the PRINT command) might be a file
describing the directions in which the robot is to move.

SMB-3

Symbiont/Job Controller Interface (SMB) Routines
12.1 Introduction to SMB Routines

Note: Modifying PRTSMB is easier than writing your own symbiont;
choose this option if possible. The Print Symbiont Modification
(PSM) routines describe how to modify PRTSMB to suit your
needs.

12.1.5

Guidelines for Writing a Symbiont
Although you can write a symbiont to use the queuing mechanisms and
other features of the job controller in whatever way you want, you must
follow these guidelines to ensure that your symbiont works correctly:
•

The symbiont must not use any of the process-permanent channels,
which are assigned to the following logical names:
-

SYS$INPUT

SYS$0UTPUT

SYS$ERROR

SYS$COMMAND

•

The symbiont must allocate and deallocate memory using the RTL
routines LIB$GET_VM and LIB$FREE_VM.

•

To be compatible with future releases of the VMS operating system,
you should write the symbiont to ignore unknown message-item codes
and unknown message-request codes. (See the SMB$READ_ITEM_
MESSAGE routine.)

•

The symbiont must communicate with the job controller by using the
Job-Controller/Symbiont Interface (SMB) routines, the SYS$SNDJBC
system service, and the SYS$GETQUI system service.

•

The symbiont should not perform lengthy operations within the context
of an AST routine. The symbiont can only receive messages from the
job controller when it is not executing within the context of an AST
routine.

•

The symbiont code should be linked against SMBSRVSHR.EXE in
order to define the SMB routine address and the following status
codes:
SMB$_INVSTMNBR
SMB$_1NVSTRLEV
SMB$_NOMOREITEMS

•

To assign a symbiont to a queue after it is compiled and linked, the
executable image of the symbiont must reside in SYS$SYSTEM, and
you must enter either of the following commands:
IN ITIALIZE/QUEUE/PROCESSOR=symbiont_filename
START/QUEUE/PROCESSOR=symbiont_filename

You should specify only the file name in the command. The disk and
directory default to SYS$SYSTEM, and all fields except the file name
are ignored.
SMB-4

Symbiont/Job Controller Interface (SMB) Routines
12.1 Introduction to SMB Routines

•

12.1.6

To help debug symbionts, you should define the logical names
DBG$INPUT and DBG$0UTPUT in the LNM$GROUP_000001 logical
name table to point to your debugging terminal.

The Symbiont/Job-Controller Interface Routines
The five SMB routines form a public interface to the VMS job controller.
The job controller delivers requests to symbionts by means of this
interface, and the symbionts communicate their responses to those
requests through this interface. A user-written symbiont uses the
following routines to exchange messages with the job controller:
SMB$1NITIALIZE

Initializes the SMB facility's internal database,
establishes the interface to the job controller, and
defines whether
Messages from the job controller are to be
delivered to the symbiont synchronously or
asyn_chronously with respect to execution of
the symbiont.
The symbiont is to be single-threaded or
multithreaded; these concepts are described
in the sections that follow.

SMB$CHECK_FOR_MESSAGE

Checks to see if a message from the job
controller to the symbiont has arrived (used
with synchronous symbionts)

SMB$READ_MESSAGE

Reads the job controller's message into a buffer

SMB$READ_MESSAGE_ITEM

Returns one item of information from the job
controller's message (which can have several
informational items)

SMB$SEND_TO_JOBCTL

Sends a message from the symbiont to the job
controller

The following sections discuss how to use the SMB routines when writing
your symbiont.

12.1.7

Choosing the Symbiont Environment
The first SMB routine that a symbiont must call is the SMB$INITIALIZE
routine. In addition to allocating and initializing the SMB facility's
internal database, it offers you two options for your symbiont environment:
synchronous or asynchonous delivery of messages from the job controller
and single streaming or multistreaming the symbiont.
12.1.7.1

Synchronous Versus Asynchronous Delivery of Requests
When you initialize your job controller/symbiont interface, the symbiont
has the option of accepting requests from the job controller sychronously
or asynchronously.

SMB-5

Symbiont/Job Controller Interface {SMB) Routines
12.1 Introduction to SMB Routines

Synchronous Environment

The address of an AST routine is an optional argument to the
SMB$INITIALIZE routine; if it is not specified, the symbiont receives
messages from the job controller synchronously. A symbiont that receives
messages synchronously must call SMB$CHECK_FOR_MESSAGE
periodically during the processing of tasks in order to ensure the timely
delivery of STOP_TASK, PAUSE_TASK, and RESET_STREAM requests.
SMB$CHECK_FOR_MESSAGE checks to see if a message from the
job controller is waiting. If a message is waiting, SMB$CHECK_FOR_
MESSAGE returns a success code. The caller of SMB$CHECK_FOR_
MESSAGE can then call SMB$READ_MESSAGE to read the message and
take the appropriate action.
If no message is waiting, SMB$CHECK_FOR_MESSAGE returns a zero in
RO. The caller of SMB$CHECK_FOR_MESSAGE can continue to process
the task at hand.
Figure 12-2 is a flowchart for a synchronous, single-threaded symbiont.
The flowchart does not show all the details of the logic the symbiont needs
and does not show how the symbiont handles Pause-task, Resume-task, or
Reset-stream requests.
Asynchronous Environment

To receive messages asynchronously, a symbiont specifies a messagehandling AST routine as the second argument to the SMB$INITIALIZE
routine. In this scheme, whenever the job controller sends messages to the
symbiont, the AST routine is called.
The AST routine is called with no arguments and returns no value. You
have the option of having the AST routine read the message within the
context of its execution or of having the AST routine wake a suspended
process to read the message outside the context of the execution of the
AST routine.
Be aware that an AST can be delivered only while the symbiont is not
executing within the context of an AST routine. Thus, in order to ensure
delivery of messages from the job controller, the symbiont should not
perform lengthy operations at AST level.
This is particularly important to the execution of STOP_TASK, PAUSE_
TASK, and RESET_STREAM requests. If a STOP_TASK request cannot
be delivered during the processing of a task, for example, it is useless.
One technique that ensures delivery of STOP and PAUSE requests in an
asynchronous environment is to have the AST routine set a flag if it reads
a PAUSE_TASK, STOP_TASK, or a RESET_STREAM request and to have
the symbiont's main routine periodically check the flag.
Figure 12-3 and Figure 12-4 show a logic chart for a single-threaded,
asynchronous symbiont. The figures do not show many details that your
symbiont might include, such as a call to the $QIO system service.

SMB-6

Symbiont/Job Controller Interface {SMB) Routines
12.1 Introduction to SMB Routines

Figure 12-2 Flowchart for a Single-Threaded, Synchronous Symbiont
w

i
N

B ~~I

-f2=~

~~'

~
w

i
U)

~t.s

.9!

2!i2,:e~
§!!;r:j!!

~ I

t::

Ii
0

d!
z

(!)

::ii

2!!2,

'fti~
m

~I
~

~:ii

1!1
a.~l

gr
~

(!)

e !5~I eI, e I,
o'

B'""1Ei;,1
~;r:~

af2~€~

nti

Note that the broken lines in Figure 12-3 that connect the calls to
SYS$HIBER with the AST routine's calls to SYS$WAKE show that the
next action to take place is the call to SYS$WAKE. They do not accurately
represent the flow of control within the symbiont but represent the action
of the job controller in causing the AST routine to execute.
SMB-7

Symbiont/Job Controller Interface {SMB) Routines
12.1 Introduction to SMB Routines

Figure 12-3

Flow Chart for a Single-Threaded, Asynchronous Symbiont (MAIN Routine)

MAIN Routine

Call
SMB$1NITIALIZE

.---------------'
I
I

Call
SYS$HIBER

I
I

Call to
SYSSWAKE
Received

Reset Messages

to Process
y
Open Fae
for Input

Call
SMB$SEND TO JOBCTL
wTth SMBMSG$K_START_TASK

ReadAeoord

Call

Close
Input File

SMB$SEN~~O_JOBCTL

SMBMSG$K..TASK_COMPLETE

Format.Write
Record

Call

SMB$SEN~~O_JOBCTL

Reset Messages
tobeProcetsed

SMBMSGSK_STOP_TASK

Call
SMB$SEND 'TO JOBCTL

wTth -

SMBMSG$K_PAUSE_TASK

Clear
Pa1S&-TaskRag

Call
SYS$HIBER

Call to
SYS$WAKE
Received

Reset Messages

toProceaa

ZK-201911-GE

SMB-8

Symbiont/Job Controller Interface (SMB) Routines
12.1 Introduction to SMB Routines

Figure 12-4

Flow Chart for a Single-Threaded, Asynchronous Symbiont (AST Routine)

AST Routine

Call
SMBSREAD_MESSAGE

Call
SMB$READ_MESSAGE_ITEM

Prcceas

Message-Item

lndcate

Cal
SYS$WAKE

:r~
N

Set
Stop-Task Flag

Call
SMBSSEND_TO_JOBCTL
with
SMBMSGSK_START_STREAM

$ASSIGN
Device

Set
Pause-Task Flag

SMBSSEN~hO_JOBCTL

Call

Messages to

Indicate

SMBMSGSK_RESUME_TASK

be Prcc8ssed

Call
SYS$WAKE

RElURN

Call
SMBSSEND TO JOBCTL
With SMBMSGSK_STOP_STREAM

$DEASSIGN

Device

BUGCHECK

Cancel
Outstanding VO

Close
File

Cal
$DEASSIGN

Cal

SMB$SEN~~O_JOBCTL

$EXIT

SMBMSG$K_RESET_STREAM
ZK-201912-GE

12.1.7.2

Single-Streaming Versus Multistreaming

A single-stream (or thread) is a logical link between a queue and a
symbiont process. When a symbiont process is linked to more than
one queue and serves those queues simultaneously, it is called a
multithreaded symbiont.

SMB-9

Symbiont/Job Controller Interface {SMB) Routines
12.1 Introduction to SMB Routines

The argument to the SMB$READ_MESSAGE routine provides a way for
a multithreaded symbiont to keep track of the stream referred to by a
request. Writing your own multithreaded symbiont, however, can be a
complex undertaking.

12.1.8

Reading Job Controller Requests
There are seven general functions that the job controller can request of the
symbiont:

SMBMSG$K_START_STREAM
SMBMSG$K_START_TASK
SMBMSG$K_RESUME_TASK
SMBMSG$K_RESET_STREAM

SMBMSG$K_STOP_STREAM
SMBMSG$K_PAUSE_TASK
SMBMSG$K_STOP_TASK

The job controller passes these requests to the symbiont in a structure
that contains ( 1 ) a code that identifies the requested function and ( 2 )
optional items of information that the symbiont might need to perform the
requested function.
By calling SMB$READ_MESSAGE, the symbiont reads the function code
and writes the associated items of information, if any, into a buffer. The
symbiont then parses the message items stored in the buffer by calling the
SMB$READ_MESSAGE_ITEM routine. SMB$READ_MESSAGE_ITEM
reads one message item each time it is called.
Each message item consists of a code that identifies the type of
information the item contains, and the information itself. For example, the
SMBMSG$K_JOB_NAME code tells the symbiont that the item contains a
string, which is the name of a job.
The number of message items in a request message varies with each
type of request. Therefore, to ensure that all message items are read,
SMB$READ_MESSAGE_ITEM must be called repeatedly for each request.
SMB$READ_MESSAGE_ITEM returns status SMB$_NOMOREITEMS
after it has read the last message item in a given request.
Typically, a symbiont checks the code of a message item against a case
table and stores the message string in an appropriate variable until all the
message items are read and the processing of the request can begin.
See the description of the SMB$READ_MESSAGE_ITEM routine for a
table that shows the message items that make up each type of request.

12.1.9

Processing Job Controller Requests
After a request is read, it must be processed. The way a request is
processed depends on the type of request. The following section lists,
for each request that the job controller sends to the print symbiont, the
actions that the standard symbiont (PRTSMB) takes when the message is
received. These actions are oriented toward print symbionts in particular
but can serve as a guideline for other kinds of symbionts as well.

SMB-10

Symbiont/Job Controller Interface {SMB) Routines
12.1 Introduction to SMB Routines

The symbiont you write can respond to requests in a similar way or in
a different way appropriate to the function of your symbiont. Digital
suggests that your routines follow the guidelines described in this
document. (Note that the behavior of the standard symbiont is subject
to change without notice in future versions of the VMS operating system.)

SMBMSG$K_START_STREAM
•

Reset all stream-specific information that might have been altered by
previous START_STREAM requests on this stream (for multithreaded
symbionts).

•

Read and store the message items associated with the request.

•

Allocate the device specified by the SMBMSG$K_DEVICE_NAME
item.

•

Assign a channel to the device.

•

Obtain the device characteristics.

•

If the device is neither a terminal nor a printer, then abort processing

and return an error to the job controller by means of the SMB$SEND_
TO_JOBCTL routine. Note that, even though an error has occurred,
the stream is still considered started. The job controller detects the
error and sends a STOP_STREAM request to the symbiont.
•

Set temporary device characteristics suited to the way the symbiont
will use the device.

•

For remote devices (devices connected to the system by means of a
modem) establish an AST to report loss of the carrier signal.

•

Report to the job controller that the request has been completed
and that the stream is started, by specifying SMBMSG$K_START_
STREAM in the call to SMB$SEND_TO_JOBCTL.

SMBMSG$K_START_TASK
•

Reset all task-specific information that might have been altered by
previous START_TASK requests on this stream number.

•

Read and store the message items associated with the request.

•

Open the main input file.

•

Report to the job controller that the task has been started by specifying
SMBMSG$K_START_TASK in the call to the SMB$SEND_TO_
JOBCTL routine.

•

Begin processing the task.

•

When the task is complete, notify the job controller by specifying
SMBMSG$K_TASK_COMPLETE in the call to the SMB$SEND_TO_
JOBCTL routine.

SMB-11

Symbiont/Job Controller Interface (SMB) Routines
12.1 Introduction to SMB Routines

SMBMSG$K_PAUSE_TASK
•

Read and store the message items associated with the request.

•

Set a flag that will cause the main processing routine to pause at the
beginning of the next output page.

•

When the main routine pauses, notify the job controller by specifying
SMBMSG$K_PAUSE_TASK in the call to the SMB$SEND_TO_
JOBCTL routine.

SMBMSG$K_RESUME_TASK
•

Read and store the message items associated with the request.

•

Perform any positioning functions specified by the message items.

•

Clear the flag that causes the main input routine to pause, and resume
processing the task.

•

Notify the job controller that the task has been resumed by specifying
SMBMSG$K_RESUME_TASK in the call to the SMB$SEND_TO_
JOBCTL routine.

SMBMSG$K_STOP_TASK
•

Read and store the message items associated with the request.

•

If processing of the current task has paused, then resume it.

•

Cancel any outstanding 1/0 operations.

•

Close the input file.

•

If the job controller specified, in the START_TASK message, that
a trailer page should be printed when the task is stopped or if it
specified that the device should be reset when the task is stopped, then
perform those functions.

•

Notify the job controller that the task has been stopped abnormally by
specifying SMBMSG$K_STOP_TASK and by specifying an error vector
in the call to SMB$SEND_TO_JOBCTL. PRTSMB specifies the value
passed by the job controller in the SMBMSG$K_STOP_CONDITION
item as the error condition in the error vector.

SMBMSG$K_STOP_STREAM

SMB-12

•

Read and store the message items associated with the request.

•

Release any stream-specific resources: ( 1 ) deassign the channel to the
device, and ( 2 ) deallocate the device.

•

Notify the job controller that the stream has been stopped by
specifying SMBMSG$K_STOP_STREAM in the call to SMB$SEND_
TO_JOBCTL.

•

If this is a single-threaded symbiont or if this is a multithreaded
symbiont but all other streams are currently stopped, then call the
SYS$EXIT system service with the condition code SS$_NORMAL.

Symbiont/Job Controller Interface (SMB) Routines
12.1 Introduction to SMB Routines
SMBMSG$K_RESET_STREAM
•

Read and store the message items associated with the request.

•

Abort any task in progress-you do not need to notify the job controller
that the task has been aborted, but you can do so if you want.

•

If the job controller specified, in the START_TASK message, that

a trailer page should be printed when the task is stopped or if it
specified that the device should be reset when the task is stopped, then
suppress those functions.
The job controller sends the symbiont a RESET_STREAM request
to regain control of a queue or a device that has failed to respond to
a STOP_TASK request. The RESET_STREAM request should avoid
any further 1/0 activity if possible. The printer might be disabled,
for example, and requests for output on that device will never be
completed.
•

Continue as if this were a STOP_STREAM request.

Note: A STOP_STREAM request and a RESET_STREAM request each
stop the queue; but a RESET_STREAM request is an emergency
stop and is used, for example, when the device has failed. A
RESET_STREAM request should prevent any further 1/0 activity
because the printer might not be able to complete it.

12.1.10 Responding to Job Controller Requests
The symbiont uses the SMB$SEND_TO_JOBCTL routine to send
messages to the job controller.
Most messages that the symbiont sends to the job controller are responses
to requests made by the job controller. Such messages inform the
job controller that the request has been completed successfully or
unsuccessfully. The function code that the symbiont returns to the
controller in the call to SMB$SEND_TO_JOBCTL indicates what request
has been completed.
For example, if the job controller sends a START_TASK request using
the SMBMSG$K_START_TASK code, the symbiont responds by calling
SMB$SEND_TO_JOBCTL using SMBMSG$K_START_TASK as the
request argument to indicate that task processing has begun. Until
the symbiont responds, the DCL command SHOW QUEUE indicates that
the queue is starting.
The responses to some requests use additional arguments to send more
information than just the request code. See the SMB$SEND_TO_JOBCTL
routine for a table showing the additional arguments allowed in response
to each request.
In addition to sending messages in response to requests, the symbiont can
send other messages to the job controller. In these messages the symbiont
sends either the SMBMSG$K_TASK_COMPLETE code, indicating that it
has completed a task, or SMBMSG$K_TASK_STATUS, indicating that the
message contains information on the status of a task.

SMB-13

Symbiont/Job Controller Interface {SMB) Routines
12.1 Introduction to SMB Routines

Note that, when a START_TASK request is delivered, the symbiont
responds with a SMB$SEND_TO_JOBCTL message with the
SMBMSG$K_START_TASK code. This response means the task has
been started. It does not mean the task has been completed. When the
symbiont completes the task, it calls SMB$SEND_TO_JOBCTL with the
SMBMSG$K_TASK_COMPLETE code.

12.2

SMB Routines
The following pages describe the individual SMB routines.

SMB-14

Symbiont/Job Controller Interface (SMB) Routines

SMB$CHECK_FOR_MESSAGE

Check for Message
from Job Controller

The SMB$CHECK_FOR_MESSAGE routine determines whether a message
sent from the job controller to the symbiont is waiting to be read.

FORMAT

SMB$CHECK_FOR_MESSAGE

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

None.

DESCRIPTION

When your symbiont calls the SMB$INITIALIZE routine to initialize the
interface between the symbiont and the job controller, you can choose to
have requests from the job controller delivered by means of an AST. If
you choose not to use ASTs, your symbiont must call SMB$CHECK_FOR_
MESSAGE during the processing of tasks in order to see if a message
from the job controller is waiting to be read. If a message is waiting,
SMB$CHECK_FOR_MESSAGE returns a success code; if not, it returns a
zero.
If a message is waiting, the symbiont should call SMB$READ_MESSAGE

to read it to determine if immediate action should be taken (as in the case
of STOP_TASK, RESET_STREAM or PAUSE_TASK).
If a message is not waiting, SMB$CHECK_MESSAGE returns a zero. If

this condition is detected, the symbiont should continue processing the
request at hand.

CONDITION
VALUES
RETURNED

SS$_NORMAL

One or more messages waiting.

No messages waiting.

SMB-15

Symbiont/Job Controller Interface (SMB) Routines
SMB$1NITIALIZE

SMB$1NITIALIZE Initialize User-Written Symbiont
The SMB$1NITIALIZE routine initializes the user-written symbiont and the
interface between the symbiont and the job controller. It allocates and
initializes the internal databases of the interface and sets up the mechanism
that is to wake up the symbiont when a message is received.

FORMAT

SMB$1NITIALIZE

RETURNS

VMS usage:
type:
access:
mechanism:

structure_/evel [,ast_routine]
[,streams]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

structure level
VMS usage: Tongword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference

Version of the job-controller/symbiont interface. The structure_level
argument is the address of a longword containing the version of the
job-controller/symbiont interface used when the symbiont was compiled.
Always place the value of the symbol SMBMSG$K_STRUCTURE_LEVEL
in the longword addressed by this argument. This symbol is defined by the
$SMBDEF macro. The $SMBDEF macro is defined in the macro library
SYS$LIBRARY:LIB.MLB.

ast_routine
ast_procedure
procedure entry mask
read only
by reference
Message-handling routine called at AST level. The ast_routine argument
is the address of the entry point of the message-handling routine to be
called at AST level when the symbiont receives a message from the job
controller. The AST routine is called with no parameters and returns no
value. If an AST routine is specified, the routine is called once each time
the symbiont receives a message from the job controller.
VMS usage:
type:
access:
mechanism:

The AST routine typically reads the message and determines if immediate
action must be taken. Be aware that an AST can be delivered only while
the symbiont is operating at non-AST level. Thus, to ensure delivery of
messages from the job controller, the symbiont should not perform lengthy
operations at AST level.
SMB-16

Symbiont/Job Controller Interface (SMB) Routines
SMB$1NITIALIZE

The ast_routine argument is optional. If you do not specify it, the
symbiont must call the SMB$CHECK_FOR_MESSAGE routine to check
for waiting messages.

streams
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
Maximum number of streams the symbiont is to support. The streams
argument is the address of a longword containing the number of streams
that the symbiont is to support. The number must be in the range 1to32.
If you do not specify this argument, a default value of 1 is used. Thus,

by default, a symbiont supports one stream. Such a symbiont is called a
single-threaded symbiont.
A stream (or thread) is a logical link between a queue and a symbiont.
When a symbiont is linked to more than one queue, and serves those
queues simultaneously, it is called a multithreaded symbiont.

DESCRIPTION

Your symbiont must call SMB$INITIALIZE before calling any other SMB$
routines. It calls SMB$INITIALIZE in order to do the following:
•

Allocate and initialize the SMB$ facility's internal database.

•

Establish the interface between the job controller and the symbiont.

•

Determine the threading scheme of the symbiont.

•

Set up the mechanism to wake your symbiont when a message is
received.

After the symbiont calls SMB$INITIALIZE, it can communicate with the
job controller using the other SMB$ services.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Routine successfully completed.

SMB$_1NVSTRLEV

Invalid structure level.

This routine also returns any codes returned by $ASSIGN and
LIB$GET_VM.

SMB-17

Symbiont/Job Controller Interface (SMB) Routines

SMB$READ_MESSAGE

SMB$READ_MESSAGE Obtain Message Sent by
Job Controller
The SMB$READ_MESSAGE routine copies a message that the job controller
has sent into the caller's specified buffer.

FORMAT

SMB$READ_MESSAGE

RETURNS

VMS usage:
type:
access:
mechanism:

stream ,buffer ,request

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

stream
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
write only
mechanism: by reference
Stream number specifying the stream to which the message refers.
The stream argument is the address of a longword into which the job
controller writes the number of the stream referred to by the message. In
single-threaded symbionts, the stream number is always 0.

buffer
VMS usage: char_string
type:
character string
access:
write only
mechanism: by descriptor
Address of the descriptor that points to the buffer into which the job
controller writes the message. SMB$READ_MESSAGE uses the RTL
STR$ string-handling routines to copy the message into the buffer you
supply. The buffer should be specified by a dynamic string descriptor.

request
VMS usage: identifier
type:
longword (unsigned)
access:
write only
mechanism: by reference
Code that identifies the request. The request argument is the address
of a longword into which SMB$READ_MESSAGE writes the code that
identifies the request.

SMB-18

Symbiont/Job Controller Interface {SMB) Routines

SMB$READ_MESSAGE
There are seven request codes. Each code is interpreted as a message by
the symbiont. The codes and their descriptions follow:

DESCRIPTION

SMBMSG$K_START_STREAM

Initiates processing on an inactive symbiont
stream. The job controller sends this message
when a START/QUEUE or an INITIALIZE/QUEUE
/START command is issued on a stopped queue.

SMBMSG$K_STOP_STREAM

Stops processing on a started queue. The job
controller sends this message when a STOP
/QUEUE/NEXT command is issued, after the
symbiont completes any currently active task.

SMBMSG$K_RESET_STREAM

Aborts all processing on a started stream and
requeues the current job. The job controller
sends this message when a STOP/QUEUE
/RESET command is issued.

SMBMSG$K_START_TASK

Requests that the symbiont begin processing a
task. The job controller sends this message when
a file is pending on an idle, started queue.

SMBMSG$K_STOP_TASK

Requests that the symbiont abort the processing
of a task. The job controller sends this messag.e
when a STOP/QUEUE/ABORT or STOP/QUEUE
/REQUEUE command is issued. The item
SMBMSG$K_STOP_CONDITION identifies
whether this is an abort or a requeue request.

SMBMSG$K_PAUSE_TASK

Requests that the symbiont pause in the
processing of a task but retain the resources
necessary to continue. The job controller sends
this message when a STOP/QUEUE command is
issued without the /ABORT, /ENTRY, /REQUEUE,
or /NEXT qualifier for a queue that is currently
printing a job.

SMBMSG$K_RESUME_TASK

Requests that the symbiont continue processing a
task that has been stopped with a PAUSE_TASK
request. This message is sent when a START
/QUEUE command is issued for a queue served
by a symbiont that has paused in processing the
current task.

Your symbiont calls SMB$READ_MESSAGE to read a message that the
job controller has sent to the symbiont.
Each message from the job controller consists of a code identifying the
function the symbiont is to perform and a number of message items.
There are seven codes. Message items are pieces of information that the
symbiont needs to carry out the requested function.
For example, when you enter the DCL command PRINT, the job controller
sends a message containing a START_TASK code and a message item
containing the specification of the file to be printed.
SMB$READ_MESSAGE writes the code into a longword (specified by the
request argument) and writes the accompanying message items, if any,
into a buffer (specified by the buffer argument).

SMB-19

Symbiont/Job Controller Interface {SMB) Routines

SMB$READ_MESSAGE
See the description of the SMB$READ_MESSAGE_ITEM routine for
information about processing the individual message items.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Routine completed successfully.

LIB$_1NVARG

Routine completed unsuccessfully because of an
invalid argument.

This routine also returns any of the condition codes returned by the
Run-Time Library string-handling (STR$) routines.

SMB-20

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

SMB$READ_MESSAGE_ITEM

Parse Next Item from
Message Buffer

The SMB$READ_MESSAGE_ITEM routine reads a buffer that was filled in
by the SMB$READ_MESSAGE routine, parses one message item from the
buffer, writes the item's code into a longword, and writes the item into a buffer.

FORMAT

SMB$READ_MESSAGE_ITEM

RETURNS

VMS usage:
type:
access:
mechanism:

message ,context
,item_code ,buffer
[,size]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

message
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Message items that SMB$READ_MESSAGE_ITEM is to read. The
message argument is the address of a descriptor of a buffer. The buffer
is the one that contains the message items that SMB$READ_MESSAGE_
ITEM is to read. The buffer specified here must be the same as that
specified with the call to the SMB$READ_MESSAGE routine, which fills
the buffer with the contents of the message.

context
context
longword (unsigned)
modify
by reference
Value initialized to 0 specifying the first message item in the buffer
VMS usage:
type:
access:
mechanism:

to be read. The context argument is the address of a longword that
the SMB$READ_MESSAGE_ITEM routine uses to determine the next
message item to be returned. When this value is 0, it indicates that
SMB$READ_MESSAGE_ITEM is to return the first message item.
The SMB$READ_MESSAGE_ITEM routine updates this value each time
it reads a message item. SMB$READ_MESSAGE_ITEM sets the value to
0 when it has returned all the message items in the buffer.

SMB-21

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

item code
VMS usage: smb_item
type:
longword (unsigned)
access:
write only
mechanism: by reference
Item code specified in the message item that identifies its type. The item_
code argument is the address of a longword into which SMB$READ_
MESSAGE_ITEM writes the code that identifies what item it is returning.

The codes that identify message items are defined at the end of the
DESCRIPTION section for this routine.

buffer
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor
Message item. The buffer argument is the address of a descriptor of a

buffer. The buffer is the one in which the SMB$READ_MESSAGE_ITEM
routine is to place the message item data. SMB$READ_MESSAGE_ITEM
uses the RTL STR$ string-handling routines to copy the message item
data into the buffer.

size
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

Size of the message item. The size argument is the address of a word in
which the SMB$READ_MESSAGE_ITEM is to place the size, in bytes, of
the item's data.

DESCRIPTION

The job controller can request seven functions from the symbiont. They
are identified by the following codes:

SMBMSG$K_START_STREAM
SMBMSG$K_START_TASK
SMBMSG$K_RESUME_TASK
SMBMSG$K_RESET_STREAM

SMBMSG$K_STOP_STREAM
SMBMSG$K_PAUSE_TASK
SMBMSG$K_STOP_TASK

The job controller passes the symbiont a request containing a code and,
optionally, a number of message items containing information the symbiont
might need to perform the function. The code specifies what function
the request is for, and the message items contain information that the
symbiont needs to carry out the function.
By calling SMB$READ_MESSAGE, the symbiont reads the request
and writes the message items into the specified buffer. The symbiont
then obtains the individual message items by calling the SMB$READ_
MESSAGE_ITEM routine.
Each message item consists of a code that identifies the information the
item represents, and the item itself. For example, the SMB$K_JOB_
NAME code tells the symbiont that the item specifies a job's name.
SMB-22

Symbiont/Job Controller ·Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

The number of items in a request varies with each type of request.
Therefore, you must call SMB$READ_MESSAGE_ITEM repeatedly for
each request to ensure that all message items are read. Each time
SMB$READ_MESSAGE_ITEM reads a message item, it updates the
value in the longword specified by the context argument. SMB$READ_
MESSAGE_ITEM returns the code SMB$_NOMOREITEMS after it has
read the last message item.
The following table shows the message items that can be delivered with
each request:
Request

Message Item

SMBMSG$K_START_TASK

SMBMSG$K_ACCOUNT_NAME
SMBMSG$K_AFTER_TIME
SMBMSG$K_BOTTOM_MARGIN
SMBMSG$K_CHARACTERISTICS
SMBMSG$K_CHECKPOINT_DATA
SMBMSG$K_ENTRY_NUMBER
SMBMSG$K_FILE_COPIES
SMBMSG$K_FILE_COUNT
SMBMSG$K_FILE_IDENTIFICATION
SMBMSG$K_FILE_SETUP_MODULES
SMBMSG$K_FILE_SPECIFICATION
SMBMSG$K_FIRST_PAGE
SMBMSG$K_FORM_LENGTH
SMBMSG$K_FORM_NAME
SMBMSG$K_FORM_SETUP_MODULES
SMBMSG$K_FORM_WIDTH
SMBMSG$K_JOB_COPIES
SMBMSG$K_JOB_COUNT
SMBMSG$K_JOB_NAME
SMBMSG$K_JOB_RESET_MODULES
SMBMSG$K_LAST_PAGE
SMBMSG$K_LEFT_MARGIN
SMBMSG$K_MESSAGE_VECTOR
SMBMSG$K_NOTE
SMBMSG$K_PAGE_SETUP_MODULES
SMBMSG$K_PARAMETER_1

SMBMSG$K_PARAMETER_8
SMBMSG$K_PRINT_CONTROL

SMB-23

Symbiont/Job Controller Interface {SMB) Routines
SMB$READ_MESSAGE_ITEM

Request

Message Item

SMBMSG$K_SEPARATION_CONTROL
SMBMSG$K_REQUEST_CONTROL
SMBMSG$K_PRIORITY
SMBMSG$K_QUEUE
SMBMSG$K_RIGHT_MARGIN
SMBMSG$K_TIME_QUEUED
SMBMSG$K_TOP_MARGIN
SMBMSG$K_UIC
SMBMSG$K_USER_NAME
SMBMSG$K_STOP_TASK

SMBMSG$K_STOP_CONDITION

SMBMSG$K_PAUSE_TASK

None

SMBMSG$K_RESUME_TASK

SMBMSG$K_ALIGNMENT_PAGES
SMBMSG$K_RELATIVE_PAGE
SMBMSG$K_REQUEST_CONTROL
SMBMSG$K_SEARCH_STRING

SMBMSG$K_START_STREAM

SMBMSG$K_DEVICE_NAME
SMBMSG$K_EXECUTOR_QUEUE
SMBMSG$K_JOB_RESET_MODULES
SMBMSG$K_LIBRARY_SPECIFICATION

SMBMSG$K_STOP_STREAM

None

SMBMSG$K_RESET_STREAM

None

The following Jist enumerates each item code. For each code, the list
describes the contents of the message item identified by the code and
whether the code identifies an item sent from the job controller to the
symbiont or from the symbiont to the job controller.
Many of the codes described are specifically oriented toward print
symbionts. The symbiont you implement, which might not print files
or serve an output device, need not recognize all these codes. In addition,
it need not respond in the same way as the VMS print symbiont to the
codes it recognizes. The descriptions in the list describe how the standard
VMS print symbiont (PRTSMB.EXE) processes these items.

Note: Because new codes might be added in the future, you should write
your symbiont so that it ignores codes it does not recognize.
Codes for Message Items
SMBMSG$K_ACCOUNT_NAME

This code identifies a string containing the name of the account to be
charged for the job, that is, the account of the process that submitted the
print job.
SMBMSG$K_AFTER_TIME

This code identifies a 64-bit, absolute-time value specifying the system
time after which the job controller can process this job.
SMB-24

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

SMBMSG$K_ALIGNMENT_PAGES
This code identifies a longword specifying the number of alignment pages
that the symbiont is to print.
SMBMSG$K_BOTTOM_MARGIN
This code identifies a longword containing the number of lines to be left
blank at the bottom of a page.

The symbiont inserts a formfeed character into the output stream if it
determines that all of the following conditions are true:
•

The number of lines left at the bottom of the page is equal to the value
in SMBMSG$K_BOTTOM_MARGIN

•

Sending more data to the printer to be output on this page would
cause characters to be printed within this bottom margin of the page

•

The /FEED qualifier was specified with the PRINT command that
caused the symbiont to perform this task

(Linefeed, formfeed, carriage-return, and vertical-tab characters in the
output stream are collectively known as embedded carriage control.)
SMBMSG$K_CHARACTERISTICS
This code identifies a 16-byte structure specifying characteristics of the job.
A detailed description of the format of this structure is contained in the
description of the QUI$_CHARACTERISTICS code in the SYS$GETQUI
system service in the VMS System Services Reference Manual.
SMBMSG$K_DEVICE_NAME
This code identifies a string that is the name of the device to which the
symbiont is to send data. The symbiont interprets this information. The
name need not be the name of a physical device, and the symbiont can
interpret this string as something other than the name of a device.
SMBMSG$K_ENTRY_NUMBER
This code identifies a longword containing the number that the job
controller assigned to the job.
SMBMSG$K_EXECUTOR_QUEUE
This code identifies a string that is the name of the queue on which the
symbiont stream is to be started.
SMBMSG$K_FILE_COPIES
This code identifies a longword containing the number of copies of the file
that were requested.
SMBMSG$K_FILE_COUNT
This code identifies a longword that specifies, out of the number of copies
requested for this job (SMBMSG$K_FILE_COPIES), the number of the
copy of the file currently printing.
SMBMSG$K_FILE_IDENTIFICATION
This code identifies a 28-byte structure identifying the file to be processed.
This structure consists of the following three file-identification fields in the
RMS NAM block:
1

The 16-byte NAM$T_DVI field
SMB-25

Symbiont/Job Controller Interface {SMB) Routines
SMB$READ_MESSAGE_ITEM

The 6-byte NAM$W_FID field

The 6-byte NAM$W_DID field

These fields occur consecutively in the NAM block in the order listed.
SMBMSG$K_FILE_SETUP_MODULES
This code identifies a string specifying the names (separated by commas)
of one or more text modules that the symbiont should copy from the library
into the output stream before processing the file.
SMBMSG$K_FILE_SPECIFICATION
This code identifies a string specifying the name of the file that the
symbiont is to process. This file name is formatted as a standard RMS file
specification.
SMBMSG$K_FIRST_PAGE
This code identifies a longword containing the number of the page at which
the symbiont should begin printing. The job controller sends this item to
the symbiont. When not specified, the symbiont begins processing at
page 1.
SMBMSG$K_FORM_LENGTH
This code identifies a longword value specifying the length (in lines) of the
physical form (the paper).
SMBMSG$K_FORM_NAME
This code identifies a string specifying the name of the form.
SMBMSG$K_FORM_SETUP_MODULES
This code identifies a string consisting of the names (separated by commas)
of one or more modules that the symbiont should copy from the devicecontrol library before processing the file.
SMBMSG$K_FORM_WIDTH
This code identifies a longword specifying the width (in characters) of the
print area on the physical form (the paper).
SMBMSG$K_JOB_COPIES
This code identifies a longword specifying the requested number of copies
of the job.
SMBMSG$K_JOB_COUNT
This code identifies a longword specifying, out of the number of copies
requested (SMBMSG$K_JOB_COPIES), the number of the copy of the job
currently printing.
SMBMSG$K_JOB_NAME
This code identifies a string specifying the name of the job.
SMBMSG$K_JOB_RESET_MODULES
This code identifies a string specifying a list of one or more modules names
(separated by commas) that the symbiont should copy from the devicecontrol library after processing the task. These modules can be used to
reset programmable devices to a known state.
SMB-26

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

SMBMSG$K_LAST_PAGE
This code identifies a longword specifying the number of the last page that
the symbiont is to print. When not specified, the symbiont attempts to
print all the pages in the file.
SMBMSG$K_LEFT_MARGIN
This code identifies a longword specifying the number of spaces to be
inserted at the beginning of each line.
SMBMSG$K_LIBRARY_SPECIFICATION
This code identifies a string specifying the name of the device-control
library.
SMBMSG$K_MESSAGE_VECTOR
This code identifies a vector of longword condition codes, each of which
contains information about the job to be printed.

When LOGINOUT cannot open a log file for a batch job, a code in the
message vector specifies the reason for the failure. The job controller does
not send the SMBMSG$K_FILE_IDENTIFICATION item if it has detected
such a failure but instead sends the message vector, which the symbiont
prints, along with a message stating that there is no file to print.
SMBMSG$K_NOTE
This code identifies a user-supplied string that the symbiont is to print on
the job-flag page and on the file-flag page.
SMBMSG$K_PAGE_SETUP_MODULES
This code identifies a string consisting of the names (separated by commas)
of one or more modules that the symbiont should copy from the devicecontrol library before printing each page.
SMBMSG$K_PARAMETER_J through SMBMSG$K_PARAMETER_8
Each of these eight codes identifies a user-supplied string. Both the
semantics and syntax of each string are determined by the user-defined
symbiont. The VMS-supplied symbiont makes no use of these eight items.
SMBMSG$K_PRINT_CONTROL
This code identifies a longword bit vector, each bit of which supplies
information that the symbiont is to use in controlling the printing of the
file.

SMB-27

Symbiont/Job Controller Interface {SMB) Routines
SMB$READ_MESSAGE_ITEM

The $SMBDEF macro defines the following symbols for each bit in the bit
vector:
Symbol

Description

SMBMSG$V_DOUBLE_SPACE

The symbiont uses a double-spaced format; it
skips a line after each line it prints.

SMBMSG$V_NORECORD_
BLOCKING

The symbiont performs single record output,
issuing a single output record for each input
record.

SMBMSG$V_PAGE_HEADER

The symbiont prints a page header at the top of
each page.

SMBMSG$V_PAGINATE

The symbiont inserts a formfeed character when it
detects an attempt to print in the bottom margin of
the current form.

SMBMSG$V_PASSALL

The symbiont prints the file without formatting
and bypasses all formatting normally performed.
Furthermore, the symbiont outputs the file without
formatting, by causing the output QIO to suppress
formatting by the driver.

SMBMSG$V_RECORD_
BLOCKING

The symbiont performs record blocking, buffering
output to the device.

SMBMSG$V_SEQUENCED

This bit is reserved by Digital.

SMBMSG$V_SHEET_FEED

The symbiont pauses the queue after each page it
prints.

SMBMSG$V_TRUNCATE

The symbiont truncates input lines that exceed the
right margin of the current form.

SMBMSG$V_WRAP

The symbiont wraps input lines that exceed the
right margin, printing the additional characters on a
new line.

SMBMSG$K_PRIORITY
This code identifies a longword specifying the priority this job has in the
queue in which it is entered.
SMBMSG$K_QUEUE
This code identifies a string specifying the name of the queue in which this
job is entered. When generic queues are used, this item specifies the name
of the generic queue, and the SMBMSG$K_EXECUTOR item specifies the
name of the device queue or the server queue.
SMBMSG$K_RELATIVE_PAGE
This code identifies a signed, longword value specifying the number of
pages that the symbiont is to move forward (positive value) or backward
(negative value) from the current position in the file.
SMBMSG$K_REQUEST_CONTROL
This code identifies a longword bit vector each bit of which specifies
information that the symbiont is to use in processing the request that
the job controller is making. The $SMBDEF macro defines the following
symbols for each bit:

SMB-28

Symbiont/Job Controller Interface {SMB) Routines
SMB$READ_MESSAGE_ITEM

Symbol

Description

SMBMSG$V_ALIGNMENT_MASK

The symbiont is to replace all alphabetic
characters with the letter X, and all numeric
characters with the number 9. Other characters
(punctuation, carriage control, and so on} are
left unchanged. This bit is ordinarily specified in
connection with the SMBMSG$K_ALIGNMENT_
PAGES item.

SMBMSG$V_PAUSE_COMPLETE

The symbiont is to pause when it completes the
current request.

SMBMSG$V_RESTARTING

Indicates that this job was previously interrupted
and requeued, and is now restarting.

SMBMSG$V_TOP_OF_FILE

The symbiont is to rewind the input file before it
resumes printing.

SMBMSG$K_RIGHT_MARGIN

This code identifies a longword specifying the number of character
positions to be left empty at the end of each line. When the right margin
is exceeded, the symbiont truncates the line, wraps the line, or continues
processing, depending on the settings of the WRAP and TRUNCATE bits
in the SMBMSG$K_PRINT_CONTROL item.
SMBMSG$K_SEARCH_STRING

This code identifies a string containing the value specified in the START
/QUEUE/SEARCH command. This string identifies the page at which to
restart the current printing task on a paused queue.
SMBMSG$K_SEPARATION_CONTROL

This code identifies a longword bit vector, each bit of which specifies an
operation that the symbiont is to perform between jobs or between files
within a job. The $SMBDEF macro defines the following symbols for each
bit:
Symbol

Description

SMBMSG$V_FILE_BU RST

The symbiont is to print a file-burst page.

SMBMSG$V_FILE_FLAG

The symbiont is to print a file-flag page.

SMBMSG$V_FILE_TRAILER

The symbiont is to print a file-trailer page.

SMBMSG$V_FILE_TRAILER_ABORT

The symbiont is to print a file-trailer page
when a task completes abnormally.

SMBMSG$V_FIRST_FILE_OF_JOB

The current file is the first file of the job.
When specified with SMBMSG$V_LAST_
FILE_OF_JOB, the current job contains a
single file.

SMBMSG$V_JOB_FLAG

The symbiont is to print a job-flag page.

SMBMSG$V_JOB_BURST

The symbiont is to print a job-burst page.

SMBMSG$V_JOB_RESET

The symbiont is to execute a job-reset
sequence when the task completes.

SMB-29

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

Symbol

Description

SMBMSG$V_JOB_RESET_ABORT

The symbiont is to execute a job-reset
sequence when a task completes
abnormally.

SMBMSG$V_JOB_TRAILER

The symbiont is to print a job-trailer page.

SMBMSG$V_JOB_TRAILER_ABORT

The symbiont is to print a job-trailer page
when a task completes abnormally.

SMBMSG$V_LAST_FILE_OF_JOB

The current file is the last file of the job.
When specified with SMBMSG$V_FIRST_
FILE_OF_JOB, the current job contains a
single job.

SMBMSG$K_STOP_CONDITION
This code identifies a longword containing a condition specifying the
reason the job controller issued a STOP_TASK request.
SMBMSG$K_TIME_QUEUED
This code identifies a quadword specifying the time the file was entered
into the queue. The time is expressed as 64-bit, absolute time.
SMBMSG$K_TOP_MARGIN
This code identifies a longword specifying the number of lines that the
symbiont is to leave blank at the top of each page. PRTSMB inserts
linefeeds into the output stream after every formfeed until the margin is
cleared.
SMBMSG$K_UIC
This code identifies a longword specifying the User Identification Code
(UIC) of the user who submitted the job.
SMBMSG$K_USER_NAME
This code identifies a string specifying the name of the user who submitted
the job.

CONDITION
VALUES
RETURNED

SMB-30

SS$_NORMAL

Routine completed successfully.

SMB$_NOMOREITEMS

End of item list reached.

This routine also returns any condition code returned by the Run-Time
Library string-handling (STR$) routines.

Symbiont/Job Controller Interface {SMB) Routines

SMB$SEND_TO_JOBCTL

SMB$SEND_TO_JOBCTL Send Message to Job
Controller
The SMB$SEND_TO_JOBCTL routine is used by your symbiont to send
messages to the job controller. Three types of message can be sent: requestcompletion messages, task-completion messages, and task-status messages.

FORMAT

SMB$SEND_TO_JOBCTL

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

stream [,request]
[,accounting][, checkpoint]
{,device_status] [,error]

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

stream
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
Stream number specifying the stream to which the message refers. The
stream argument is the address of a longword containing the number of
the stream to which the message refers.

request
VMS usage: identifier
type:
longword (unsigned)
access:
read only
mechanism: by reference
Request code identifying the request being completed. The r~quest
argument is the address of a longword containing the code that identifies
the request that has been completed.

The code usually corresponds to the code the job controller passed to the
symbiont by means of a call to SMB$READ_MESSAGE. But the symbiont
can also initiate task-completion and task-status messages that are not in
response to a request. (See the DESCRIPTION section.)

SMB-31

Symbiont/Job Controller Interface (SMB) Routines

SMB$SEND_TO_JOBCTL
accounting
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Accounting information about a task. The accounting argument is the
address of a descriptor pointing to the accounting information about a
task. Note that this structure is passed by descriptor and not by reference.

The job controller accumulates task statistics into a job-accounting record,
which it writes to the accounting file when the job is completed.
The following diagram depicts the contents of the 16-byte structure:
0

Number of Pages Printed for the Job
Number of Reads from Disk or Tape
Number of Writes to the Printing Device
Unused
ZK-2012-GE

checkpoint
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Checkpoint data about the currently executing task. The checkpoint
argument is the address of the descriptor that points to checkpointing
information that relates to the status of a task. When the symbiont sends
this information to the job controller, the job controller saves it in the
queue database. When a restart-from-checkpoint request is executed for
the queue, the job controller retrieves the checkpointing information from
the queue database and sends it to the symbiont in the SMBMSG$K_
CHECKPOINT_DATA item that accompanies a SMBMSG$K_START_
TASK request.
Print symbionts can use the checkpointing information to reposition the
input file to the point corresponding to the page being output when the last
checkpoint was taken. Other symbionts might use checkpoint information
to specify restart information for partially completed tasks.
Note: Because each checkpoint causes information to be written
into the job controller's queue database, taking a checkpoint
incurs significant overhead. Use caution in regard to the size
and frequency of checkpoints. When determining how often to
checkpoint, weigh processor and file-system overhead against the
convenience of restarting.

SMB-32

Symbiont/Job Controller Interface (SMB) Routines

SMB$SEND_TO_JOBCTL
device_ status
longword_unsigned
longword (unsigned)
read only
by reference
Status of the device served by the symbiont. The device_status argument
is the address of a longword passed to the job controller, which contains
the status of the device to which the symbiont is connected.
VMS usage:
type:
access:
mechanism:

This longword contains a longword bit vector, each bit of which specifies
device-status information. The $SMBDEF macro defines these devicestatus bits. The following table describes each bit:
Device Status Bit

Description

SMBMSG$V_LOWERCASE

The device to which the symbiont is connected
supports lowercase characters.

SMBMSG$V_PAUSE_TASK

The symbiont sends this message to inform the job
controller that the symbiont has paused on its own
initiative.

SMBMSG$V_REMOTE

The device is connected to the symbiont by means
of a modem.

SMBMSG$V_SERVER

The symbiont is not connected to a device.

SMBMSG$V_STALLED

Symbiont processing is temporarily stalled.

SMBMSG$V_STOP_STREAM

The symbiont requests that the job controller stop
the queue.

SMBMSG$V_TERMINAL

The symbiont is connected to a terminal.

SMBMSG$V_UNAVAILABLE

The device to which the symbiont is connected is
not available.

error
vector_longword_unsigned
longword (unsigned)
read only
by reference
Condition codes returned by the requested task. The error argument is
the address of a vector of longword condition codes. The first longword
contains the number of longwords following it.

VMS usage:
type:
access:
mechanism:

If the low bit of the first condition code is clear, the job controller aborts
further processing of the job. Output of any remaining files, copies of files,
or copies of the job is canceled. In addition, the job controller saves up to
three condition values in the queue database. The first condition value
is included in the job-accounting record that is written to the system's
accounting file (SYS$MANAGER:ACCOUNTNG.DAT).

SMB-33

Symbiont/Job Controller Interface (SMB) Routines

SMB$SEND_TO_JOBCTL

DESCRIPTION

The symbiont uses the SMB$SEND_TO_JOBCTL routine to send
messages to the job controller.
Most messages the symbiont sends to the job controller are responses
to requests made by the job controller. These responses inform the job
controller that the request has been completed, either successfully or with
an error. When the symbiont sends the message, it usually indicates that
the request has been completed.
In such messages, the request argument corresponds to the function code
of the request that has been completed. Thus, if the job controller sends a
request using the SMBMSG$K_START_TASK code, the symbiont responds
by sending a SMB$SEND_TO_JOBCTL message using SMBMSG$K_
START_TASK as the request argument.
The responses to some requests use additional arguments to send more
information in addition to the request code. The following table shows
which additional arguments are allowed in response to each different
request:
Request

Arguments

SMBMSG$K_START_STREAM

request
device_status
error

SMBMSG$K_STOP_STREAM

request

SMBMSG$K_RESET_STREAM

request

SMBMSG$K_START_TASK

request

SMBMSG$K_PAUSE_TASK

request

SMBMSG$K_RESUME_TASK

request

SMBMSG$K_STOP_TASK

request
error1

1
This is usually the value specified in the SMBMSG$K_STOP_CONDITION item that was sent
by the job controller with the SMBMSG$K_STOP_TASK request.

In addition to responding to requests from the job controller, the
symbiont can send other messages to the job controller. If the symbiont
sends a message that is not a response to a request, it uses either
the SMBMSG$K_TASK_COMPLETE or SMBMSG$K_TASK_STATUS
code. Following are the additional arguments that you can use with the
messages identified by these codes:

SMB-34

Symbiont/Job Controller Interface (SMB) Routines

SMB$SEND_TO_JOBCTL
Code

Arguments

SMBMSG$K_TASK_COMPLETE

request
accounting
error

SMBMSG$K_TASK_STATUS

request
checkpoint
device_status

The symbiont uses the SMBMSG$K_TASK_STATUS message to update
the job controller on the status of a task during the processing of that
task. The checkpoint information passed to the job controller with this
message permits the job controller to restart an interrupted task from an
appropriate point. The device-status information permits the symbiont to
report changes in device's status (device stalled, for example).
The symbiont can use the SMBMSG$K_TASK_STATUS message to
request that the job controller send a stop-stream request. It does this
by setting the stop-stream bit in the device-status argument.
The symbiont can also use the SMBMSG$K_TASK_STATUS message to
notify the job controller that the symbiont has paused in processing a task.
It does so by setting the pause-task bit in the device-status argument.
The symbiont uses the SMBMSG$K_TASK_COMPLETE message to
signal the completion of a task. Note that, when the symbiont receives a
START_TASK request, it responds by sending a SMB$SEND_TO_JOBCTL
message with SMBSMG$K_START_TASK as the request argument. This
response means that the symbiont has started the task; it does not mean
the task has been completed. When the symbiont has completed a task,
it sends a SMB$SEND_TO_JOBCTL message with SMBMSG$K_TASK_
COMPLETE as the request argument.
Optionally, the symbiont can specify accounting information when sending
a task-completion message. The accounting statistics accumulate to give a
total for the job when the job is completed.
Also, if the symbiont is aborting the task because of a symbiont-detected
error, you can specify up to three condition values in the error argument.
Aborting a task causes the remainder of the job to be aborted.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Routine completed successfully.

This routine also returns any condition value returned by the $QIO system
service and the LIB$GET_VM routine.

SMB-35

13 Sort/Merge (SOR) Routines
The SOR routines allow you to integrate a sort or merge operation into a
program application. Using these callable routines, you can process some
records, sort or merge them, and then process them again.

13.1

Introduction to SOR Routines
The following SOR routines are available for use in a sort or merge
operation:
SOR$BEGIN_MERGE

Sets up key arguments and performs the merge. This is the
only routine unique to MERGE.

SOR$BEGIN_SORT

Initializes sort operation by passing key information and sort
options. This is the only routine unique to SORT.

SOR$DTYPE

Defines a key data-type that is not normally supported by
SORT/MERGE.

SOR$END_SORT

Performs cleanup functions, such as closing files and
releasing memory.

SOR$PASS_FILES

Passes names of input and output files to SORT or MERGE;
must be repeated for each input file.

SOR$RELEASE_REC

Passes one input record to SORT or MERGE; must be
called once for each record.

SOR$RETURN_REC

Returns one sorted or merged record to a program; must be
called once for each record.

SOR$SORT_MERGE

Sorts the records.

SOR$SPEC_FILE

Passes a specification file or specification text. A call to this
routine must precede all other calls to the SOR routines.

SOR$STAT

Returns a statistic about the sort or merge operation.

Note: You can still call SOR$DO_MERGE (from VMS Version 3.0) as
the equivalent of SOR$END_SORT; you can still call SOR$1NIT_
MERGE and SOR$INIT_SORT (from VMS Version 3.0) as the
equivalent of SOR$BEGIN_SORT and SOR$BEGIN_MERGE.
However, for any new programs that you are creating, you
are advised to use SOR$END_SORT, SOR$BEGIN_SORT, and
SOR$BEGIN_MERGE.
You can callthese SOR routines from any language that supports the
VAX Procedure Calling and Condition Handling Standard. Note that the
application program should declare referenced constants and return status
symbols as external symbols; these symbols will be resolved upon linking
with utility shareable image.
After being called, each of these routines performs its function and
returns control to a program. It also returns a 32-bit condition code
value indicating success or error, which a program can test to determine
success or failure conditions.
SOR-1

Sort/Merge (SOR) Routines
13.1 Introduction to SOR Routines

13.1.1

Arguments to SOR Routines
For a sort operation, the arguments to the SOR routines provide SORT
with file specifications, key information, and instructions about the sorting
process. For a merge operation, the arguments to the SOR routines
provide MERGE with the number of input files, input and output file
specifications, record information, key information, and input routine
information.
There are both mandatory and optional arguments. The mandatory
arguments appear first in the argument list. You must specify all
arguments in the order in which they are positioned in the argument
list, separating each with a comma. Pass a zero by value to specify any
optional arguments that you are omitting from within the list. You can
end the argument list any time after specifying all the mandatory and
desired optional arguments.

13.1.2

Interfaces to SOR Routines
You can submit data to the SOR routines as complete files or as single
records. When your program submits one or more files to SORT or
MERGE, which then creates one sorted or merged output file, you are
using the file interface. When your program submits records one at a time
and then receives the ordered records one at a time, you are using the
record interface.
You can combine the file interface with the record interface by submitting
files on input and receiving the ordered records on output or by releasing
records on input and writing the ordered records to a file on output.
Combining the two interfaces provides greater :flexibility. If you use the
record interface on input, you can process the records before they are
sorted; if you use the record interface on output, you can process the
records after they are sorted.
The SOR routines used and the order in which they are called depend
on the type of interface used in a sorting or merging operation. The
following sections detail the calling sequence for each of the interfaces.
Note, however, that if you use the SOR$STAT routine, it must be called
before any other SOR routine.
13.1.2.1

Sort Operation Using File Interface

For a sort operation using the file interface, pass the input and output
file specifications to SORT by calling SOR$PASS_FILES. You must call
SOR$PASS_FILES for each input file specification. Pass the output file
specification in the first call. If no input files are specified before the call
to SOR$BEGIN_SORT, the record interface is used for input; if no output
file is specified, the record interface is used for output.
Next, call SOR$BEGIN_SORT to pass instructions about keys and sort
options. At this point, you must indicate whether you want to use
your own key comparison routine. SORT automatically generates a key
comparison routine that is efficient for key· data types; however, you might
want to provide your own comparison routine to handle special sorting
requirements. (For example, you might want names beginning with "Mc"
SOR-2

Sort/Merge {SOR) Routines
13.1 Introduction to SOR Routines

and "Mac" to be placed together.) If you use your own key comparison
routine, you must pass its address with the user_compare argument.
Call SOR$SORT_MERGE to execute the sort and direct the sorted records
to the output file. Finally, call SOR$END_SORT to end the sort and
release resources. The SOR$END_SORT routine can be called at any time
to abort a sort or to merge and release all resources allocated to the sort or
merge process.
13.1.2.2

Sort Operation Using Record Interface

For a sort operation using the record interface, first call SOR$BEGIN_
SORT. As in the file interface, this routine sets up work areas and passes
arguments that define keys and sort options. Note that, if you use the
record interface, you must use a record-sorting process (not a tag, address,
or index process).
Next, call SOR$RELEASE_REC to release a record to SORT. Call
SOR$RELEASE_REC once for each record to be released. After all records
have been passed to SORT, call SOR$SORT_MERGE to perform the
sorting.
After the sort has been performed, call SOR$RETURN_REC to return a
record from the sort operation. Call this routine once for each record to be
returned. Finally, call the last routine, SOR$END_SORT, to complete the
sort operation and release resources.
13.1.2.3

Merge Operation Using File Interface

For a merge operation using the file interface, pass the input and output
file specifications to MERGE by calling SOR$PASS_FILES. You can merge
up to 10 input files by calling SOR$PASS_FILES once for each file. Pass
the file specification for the merged output file in the first call. If no input
files are specified before the call to SOR$BEGIN_MERGE, the record
interface is used for input; if no output file is specified, the record interface
is used for output.
Next, to execute the merge, call SOR$BEGIN_MERGE to pass key
information and merge options. At this point, you must indicate whether
you want to use your own key comparison routine tailored to your data.
Finally, call SOR$END_SORT to release resources.
13.1.2.4

Merge Operation Using Record Interface

For a merge operation using the record interface, first call SOR$BEGIN_
MERGE. As in the file interface, this routine passes arguments that define
keys and merge options. It also issues the first call to the input routine,
which you must create, to begin releasing records to the merge.
Next, call SOR$RETURN_REC to return the merged records to your
program. You must call this routine once for each record to be returned.
SOR$RETURN_REC continues to call the input routine. MERGE, unlike
SORT, does not need to hold all the records before it can begin returning
them in the desired order. Releasing, Merging, and Returning of records
all take place in this phase of the merge.
Finally, after all the records have been returned, call the last routine,
SOR$END_SORT, to clean up and release resources.
SOR-3

Sort/Merge (SOR) Routines
13.1 Introduction to SOR Routines

13.1.3

Reentrancy
The SOR routines are reentrant; that is, a number of sort or merge
operations can be active at the same time. Thus, a program does not
need to finish one sort or merge operation before beginning another. For
example, reentrancy lets you perform multiple sorts on a file such as a
mailing list and to create several output files, one with the records sorted
by name, another sorted by state, another sorted by zip code, and so on.
The context argument, which can optionally be passed with any of the
SOR routines, distinguishes among multiple sort or merge operations.
When using multiple sort or merge operations, the context argument
is required. On the first call, the context longword must be zero. It is
then set (by SORT/MERGE) to a value identifying the sort or merge
operation. Additional calls to the same sort or merge operation must
pass the same context longword. The SOR$END_SQRT routine clears the
context longword.

13.2

Examples of Using SOR Routines
Example 13-1 is a VAX FORTRAN program demonstrating a merge
operation using a record interface.
Example 13-1

Using SOR Routines to Perform a Merge Using Record Interface in a VAX
FORTRAN Program

FORTRAN Program

c ...
C...
C...

This program demonstrates the FORTRAN calling sequences
for the merge record interface.

THE INPUT FILES ARE LISTED BELOW.

c ...
c

c
C

INFILEl.DAT

c
c 1 BBBBBBBBBB REST OF DATA IN RECORD ................................ END OF RECORD
c 2 UUUUUUUUUU REST OF DATA IN RECORD ................................ END OF RECORD
c
c
INFILE2.DAT
c
c 1 AAAAA.AAAAA REST OF DATA IN RECORD ................................ END OF RECORD
c 2 TTTTTTTTTT REST OF DATA IN RECORD ................................ END OF RECORD

c
c
INFILE3 .DAT
c
c 1 TTTTTTTTTT REST OF DATA IN RECORD ................................ END OF RECORD

c 2 BBBBBBBBBB REST OF DATA IN RECORD ................................ END OF RECORD
c

(continued on next page)

SOR-4

Sort/Merge (SOR} Routines
13.2 Examples of Using SOR Routines

Example 13-1 (Cont.)
c
c

Using SOR Routines to Perform a Merge Using Record Interface in a VAX
FORTRAN Program

FOROUT.DAT

c 1 AAAAAAAAAA REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
c 1 BBBBBBBBBB REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD

c 1 TTTTTTTTTT REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
c 2 BBBBBBBBBB REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
c 2 TTTTTTTTTT REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
c 2 uuuuuuuuuu REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD

c
c

c ................................................................................ .

c
c

IMPLICIT INTEGER (A-Z)

c ...
c ...
c ...

CHARACTER*80 REC

A record.

EXTERNAL READ REC
EXTERNAL KOMPAR
EXTERNAL SS$_ENDOFFILE

Routine to read a record.
Routine to compare records.
System end-of-file value

INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*2

SORT/MERGE function names

SOR$BEGIN MERGE
SOR$RETURN_REC
SOR$END_SORT
ISTAT
LENGTH
LRL

storage for SORT/MERGE function value
length of the returned record
Longest Record Length (LRL)

LOGICAL*l ORDER

#files to merge (merge order)

DATA ORDER,LRL/3,80/

Order of the merge=3,LRL=80

First open all the input files.

*
*
*

OPEN (UNIT=lO, FILE='INFILEl.DAT' ,TYPE=' OLD' ,READONLY,
FORM=' FORMATTED')
OPEN (UNIT=ll, FILE='INFILE2.DAT' ,TYPE='OLD' ,READONLY,
FORM='FORMATTED')
OPEN (UNIT=12, FILE='INFILE3.DAT' ,TYPE='OLD' ,READONLY,
FORM=' FORMATTED')

c
c ...

Open the output file.

c
OPEN (UNIT=8, FILE='TEMP.TMP', TYPE='NEW')

c ...

c ...
c ...

Initialize the merge. Pass the merge order, the largest
record length, the compare routine address, and the
input routine address.

c ...

ISTAT = SOR$BEGIN_MERGE (,LRL,,ORDER,
KOMPAR,,READ_REC)
IF (.NOT. ISTAT) GOTO 10
! Check for error.
{continued on next page)

SOR-5

Sort/Merge (SOR) Routines
13.2 Examples of Using SOR Routines

Example 13-1 (Cont.)

Using SOR Routines to Perform a Merge Using Record Interface in a VAX
FORTRAN Program

c ...
C...
C...

Now loop getting merged records. SOR$RETURN_REC will
call READ_REC when it needs input.

c ...
5

200

ISTAT = SOR$RETURN REC (REC, LENGTH)
IF (ISTAT .EQ. %LOC(SS$_ENDOFFILE)) GO TO 30
! Check for end of file.
IF (.NOT. ISTAT) GO TO 10
! Check for error.
WRITE(8,200) REC
FORMAT(' ',A)
GOTO 5

Output the record.
And loop back.

c ...
C...

Now tell SORT that we are all done.

ISTAT = SOR$END_SORT()
IF (.NOT. ISTAT) GOTO 10
CALL EXIT

c ...

Check for error.

c ...
C...
C...

Here if an error occurred.
and exit.

Write out the error status

c ...
10
201

WRITE(8,201)ISTAT
FORMAT(' ?ERROR CODE', I20)
CALL EXIT
END
FUNCTION READ_REC (RECX, FILE, SIZE)

c ...
C...
C...
C...
C...

c .. .
c .. .
c .. .
c .. .
c .. .
c .. .
c .. .
c .. .
c .. .
c .. .
c .. .
c .. .

This routine reads a record from one of the input files
for merging. It will be called by SOR$BEGIN_MERGE and by
SOR$RETURN_REC.
Parameters:
RECX.wcp.ds

character buff er to hold the record after
it is read in.

FILE. rl. r

indicates which file the record is
to be read from.
1 specifies the
first file, 2 specifies the second
etc.

LENGTH.wl.r

is the actual number of bytes in
the record. This is set by READ_REC.

IMPLICIT INTEGER (A-Z)
PARAMETER MAXFIL=lO

Max number of files.

EXTERNAL SS$_ENDOFFILE
EXTERNAL SS$_NORMAL

End of file status code.
Success status code.

LOGICAL*l FILTAB(MAXFIL)
CHARACTER*(80) RECX

MAX LRL =80

DATA FILTAB/10,11,12,13,14,15,16,17,18,19/ ! Table of I/O unit numbers.
(continued on next page)

SOR-6

Sort/Merge (SOR) Routines
13.2 Examples of Using SOR Routines

Example 13-1 (Cont.)

Using SOR Routines to Perform a Merge Using Record Interface in a VAX
FORTRAN Program

READ_REC = %LOC(SS$_ENDOFFILE)
! Give end of file return
IF (FILE .LT. 1 .OR. FILE .GT. MAXFIL) RETURN
if illegal call.
100

READ (FILTAB(FILE), 100, ERR=75, END=50) RECX
FORMAT (A)
READ REC = %LOC(SS$_NORMAL)
SIZE = LEN (RECX)
RETURN

c ...
50
C...
75

Here if end of file.
READ_REC = %LOC(SS$_ENDOFFILE)
RETURN

Read the record.

Return success code.
Return size of record.

Return "end of file" code.

Here if error while reading
READ REC = 0
SIZE = 0
RETURN
END
FUNCTION KOMPAR (REC1,REC2)

c ...
C...

c...
C...
C...

This routine compares two records. It returns -1
if the first record is smaller than the second,
0 if the records are equal, and 1 if the first record
is larger than the second.

c ...
PARAMETER KEYSIZ=lO
IMPLICIT INTEGER (A-Z)
LOGICAL*l RECl(KEYSIZ),REC2(KEYSIZ)

DO 20 I=l,KEYSIZ
KOMPAR = RECl(I) - REC2(I)
IF (KOMPAR .NE. 0) GOTO 50
CONTINUE
RETURN

KOMPAR = ISIGN (1, KOMPAR)
RETURN
END

Example 13-2 is a VAX FORTRAN program demonstrating a sort
operation using a file interface on input and a record interface on output.

SOR-7

Sort/Merge {SOR) Routines
13.2 Examples of Using SOR Routines

Example 13-2

Using SOR Routines to Sort Using Mixed Interface in a VAX FORTRAN Program

Program
PROGRAM CALLSORT

c
c
C
C
C
C
C
C
C

This is a sample FORTRAN program that calls the SOR
routines using the file interface for input and the
record interface for output. This program requests
a record sort of the file 'ROlOSQ.DAT' and writes
the records to SYS$0UTPUT. The key is an 80-byte
character ascending key starting in position 1 of
each record.

c
C

A short version of the input and output files follows:

c
c
Input file ROlOSQ.DAT
c 1 BBBBBBBBBB REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
c 2 UUUUUUUUUU REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
c 1 AAAAAAAAAA REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
c 2 TTTTTTTTTT REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
c 1 TTTTTTTTTT REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
c 2 BBBBBBBBBB REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
c 1 QQQQQQQQQQ REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
c 2 AAAAAAAAAA REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
c 1 UUUUUUUUUU REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
c 2 QQQQQQQQQQ REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD

c
c

Output file SYS$0UTPUT

C 1 AAAAAAAAAA REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
C 1 BBBBBBBBBB REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
C 1 QQQQQQQQQQ REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
C 1 TTTTTTTTTT REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
C 1 UUUUUUUUUU REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
C 2 AAAAAAAAAA REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
C 2 BBBBBBBBBB REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
C 2 QQQQQQQQQQ REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
C 2 TTTTTTTTTT REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD
C 2 UUUUUUUUUU REST OF DATA IN RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . END OF RECORD

c----------------------------------------------------------------------------c

Define external functions and data.

c
CHARACTER*80 RECBUF
CHARACTER*lO INPUTNAME
INTEGER*2 KEYBUF(S)
INTEGER*4 SOR$PASS FILES
INTEGER*4 SOR$BEGIN SORT
INTEGER*4 SOR$SORT MERGE
INTEGER*4 SOR$RETURN REC
INTEGER*4 SOR$END SORT
INTEGER*4 ISTATUSEXTERNAL SS$ ENDOFFILE
EXTERNAL DSC$K DTYPE T
EXTERNAL SOR$GK_RECORD
INTEGER*4 SRTTYPE

!Input file name
!Key definition buffer
!SORT function names

!Storage for SORT function value

(continued on next page)

SOR-8

Sort/Merge {SOR) Routines
13.2 Examples of Using SOR Routines

Example 13-2 {Cont.)

Using SOR Routines to Sort Using Mixed Interface in a VAX FORTRAN
Program

c
C
C
C

Initialize data -- first the file names, then the key buffer for
one 80-byte character key starting in position 1, 3 work files,
and a record sort process.

c
DATA INPUTNAME/'ROlOSQ.DAT' /
KEYBUF(l)
1
KEYBUF(2)
%LOC(DSC$K_DTYPE_T)
KEYBUF(3)
0
KEYBUF(4)
0
KEYBUF(5)
80
SRTTYPE = %LOC(SOR$GK_RECORD)

c
C

Call the SORT -- each call is a function.

c
c
C

Pass SORT the file names.

c
ISTATUS = SOR$PASS_FILES(INPUTNAME)
IF (.NOT. ISTATUS) GOTO 10

c
C

Initialize the work areas and keys.

c
ISTATUS = SOR$BEGIN_SORT(KEYBUF,,,,,,SRTTYPE,%REF(3))
IF (.NOT. ISTATUS) GOTO 10

c
C

Sort the records.

c
ISTATUS = SOR$SORT_MERGE( )
IF (.NOT. ISTATUS) GOTO 10

c
C

Now retrieve the individual records and display them.

c
5

ISTATUS = SOR$RETURN_REC(RECBUF)
IF (.NOT. ISTATUS) GOTO 6
ISTATUS = LIB$PUT_OUTPUT(RECBUF)
GOTO 5
IF (ISTATUS .EQ. %LOC(SS$_ENDOFFILE)) GOTO 7
GOTO 10

c
C

Clean up the work areas and files.

c
7
10

ISTATUS = SOR$END_SORT()
IF (.NOT. ISTATUS) GOTO 10
STOP 'SORT SUCCESSFUL'
STOP 'SORT UNSUCCESSFUL'
END

Example 13-3 is a VAX Pascal program demonstrating a merge operation
using a file interface.

SOR-9

Sort/Merge (SOR) Routines
13.2 Examples of Using SOR Routines

Example 13-3 Using SOR Routines to Merge Three Input Files in a VAX Pascal Program
Program

(* This program merges three input files, (IN_FILE.DAT,
IN_FILE2.DAT IN_FILE3.DAT), and creates one merged output file.

program mergerecs( output, in_filel, in_file2, in_file3, out file);
CONST
SS$ NORMAL = 1;
SS$-ENDOFFILE = %X870;
SOR$GK_RECORD = 1;
SOR$M STABLE = 1;
SOR$M-SEQ CHECK = 4;
SOR$M-SIGNAL = 8;
DSC$K=DTYPE_T = 14;
TYPE
$UBYTE
$UWORD

[BYTE] 0 .. 255;
[WORD] 0 .. 65535;

con st
num_of_keys
merge_order
lrl
ascending
descending

1;
3;
131;
0;
1;

type
key_buffer block=
packed record
key_type:
key_order:
key_offset:
key_length:
end;
key_buffer type=
packed record
key_count:
blocks:
end;
record buff er

$uword;
$uword;
$uword;
$uword;

$uword;
packed array[l .. num_of_keys] of key_buffer_block;
packed array[l .. lrl] of char;

record buff er descr
packed record
length: $uword;
dummy: $uword;
addr:
Arecord_buffer;
end;
(continued on next page)

SOR-10

Sort/Merge (SOR) Routines
13.2 Examples of Using SOR Routines

Example 13-3 (Cont.)

Using SOR Routines to Merge Three Input Files in a VAX Pascal Program

var
in filel,
in-file2,
in~)ile3,
out file:
key_buffer:
rec buffer:
rec_length:
status:
i:

text;
key_buffer_type;
record buffer;
$uword;
integer;
integer;

function sor$begin_merge(
var buffer:
key_buffer_type;
lrl:
$uword;
mrg_options:
integer;
merge_order:
$ubyte;
%immed cmp_rtn: integer := O;
%immed eql_rtn: integer := O;
%immed [unbound] function
read_record(
var rec:
record buffer descr;
var filenumber: integer;
var recordsize: $uword): integer
) : integer; extern;
function sor$return rec(
%stdescr rec:
record buffer;
$uwordvar rec size:
) : integer; extern;
function sor$end_sort: integer; extern;
procedure sys$exit( %immed status : integer); extern;
function read_record(
var rec:
record_buffer_descr;
var filenumber: integer;
var recordsize: $uword
) : integer;
procedure readone( var filename: text);
begin
recordsize := O;
if eof(filename)
then
read record ·= ss$_endoffile
else
begin
while not eoln(filename) and (recordsize < rec.length) do
begin
recordsize := recordsize + 1;
read(filename,rec.addrA[recordsize]);
end;
readln(filename);
end;
end;

(continued on next page)

SOR-11

Sort/Merge (SOR) Routines
13.2 Examples of Using SOR Routines

Example 13-3 (Cont.)

Using SOR Routines to Merge Three Input Files in a VAX Pascal Program

begin
read record := ss$ normal;
case-filenumber of1: readone(in_filel);
2: readone(in_file2);
3: readone(in file3);
otherwise
read record := ss$_endoffile;
end;
end;
procedure initfiles;
begin
open( in_filel, 'infilel.dat', old);
open( in file2, 'infile2.dat', old);
open( in=file3, 'infile3.dat', old);
open( out file, 'temp.tmp' );
reset( in=filel );
reset( in_file2 );
reset( in file3 );
rewrite( out_file );
end;
procedure error( status : integer);
begin
writeln( 'merge unsuccessful.
status=%x', status:8 hex);
sys$exit(status);
end;
begin
with key_buffer do
begin
key count := 1;
with blocks[l] do
begin
key type := dsc$k dtype t;
key=order := ascending;
key_offset := 0;
key_length ·= 5;
end;
end;
initfiles;
status := sor$begin merge( key buffer, lrl,
sor$m_seq_check + sor$m_signal,
merge_order, O, 0, read_record );
repeat
begin
rec length := O;
status := sor$return rec( rec_buffer, rec_length );
if odd(status)
then
begin
for i := 1 to rec length do write(out_file, rec_buffer[i]);
writeln(out_file);
end;
end
until not odd(status);
(continued on next page)

SOR-12

Sort/Merge (SOR) Routines
13.2 Examples of Using SOR Routines

Example 13-3 (Cont.)

Using SOR Routines to Merge Three Input Files in a VAX Pascal Program

if status<> ss$_endoffile then error(status);
status := sor$end sort;
if not odd(status) then error(status);
writeln( 'merge successful.' );
end.

Example 13-4 is a VAX Pascal program demonstrating a sort operation
using a record interface.
Example 13-4 Using SOR Routines to Sort Records from Two Input Files in a VAX Pascal
Program
Pascal Program
PROGRAM FILETORECORDSORT (OUTPUT,SORTOUT);

This program calls SOR routines to read and sort records from
two input files, (PASINPUTl.DAT and PASINPUT2.DAT) and to return
sorted records to this program to be written to the output file,
(TEMP . TMP) .
*)

Declarations for external status codes, and data structures, such as
the types $UBYTE (an unsigned byte) and $UWORD (an unsigned word) . *)

CONST
SS$_NORMAL = l;
SS$ ENDOFFILE = %X870;
SOR$GK RECORD = l;
SOR$M STABLE = l;
SOR$M-SEQ CHECK = 4;
SOR$~SIGNAL = 8;
DSC$K=DTYPE_T = 14;
TYPE
$UBYTE
$UWORD

[BYTE] 0 .. 255;
[WORD] 0 .. 65535;

CONST
Numberofkeys
LRL = 131 ;

(* Number of keys for this sort *)

(* Longest Record Length for output records *)

( * Key orders *)
Ascending = 0
Descending = 1 ;
TYPE
Keybuf f erblock= packed record
Keytype : $UWORD
Keyorder : $UWORD ;
Keyoff set
$UWORD
Keylength : $UWORD
end ;

(* The keybuffer. Note that the field buffer is a one-component array in
this program. This type definition would allow a multikeyed sort. *)
(continued on next page)

SOR-13

Sort/Merge (SOR) Routines
13.2 Examples of Using SOR Routines

Example 13-4 (Cont.)

Using SOR Routines to Sort Records from Two Input Files in a VAX
Pascal Program

Keybuf fer= packed record
Numkeys : $UWORD
Blocks : packed array[l .. Numberofkeys] OF Keybufferblock
end ;

(* The record buffer. This buffer will be used to hold the returned
records from SORT. *)
Recordbuffer =packed array[l .. LRL] of char

(* Name type for input and output files. A necessary fudge for %stdescr
mechanism.
*)
nametype= packed array[l .. 13) of char
VAR
Sortout : text ;
Buff er : Keybuf fer
Sortoptions : integer
Sorttype : $UBYTE ;
Numworkf iles : $UBYTE
Status : integer ;
Rec : Recordbuff er ;
Recordlength : $UWORD
Inputname:
nametype
i : integer ;

(*
(*
(*
(*
(*
(*

(*
(*
(*
(*

the output file *)
the actual keybuffer *)
flag for sorting options *)
sorting process *)
number of work files *)
function return status code *)
a record buffer *)
the returned record length *)
input file name *)
loop control variable *)

(* function and procedure declarations *)
(* Declarations of SORT functions *)
(* Note that the following SORT routine declarations
do not use all of the possible routine parameters. *)
(* The parameters used MUST have all preceding parameters specified,
however. *)

FUNCTION SOR$PASS_FILES
(%STDESCR Inname : nametype
: INTEGER ; EXTERN ;
FUNCTION SOR$BEGIN_SORT(
VAR Buff er : Keybuf fer
Lrlen : $UWORD ;
VAR Sortoptions : INTEGER
%IMMED Filesize : INTEGER
%IMMED Usercompare : INTEGER
%IMMED Userequal : INTEGER ;
VAR Sorttype : $UBYTE ;
VAR Numworkfiles : $UBYTE
: INTEGER ; EXTERN ;
(continued on next page)

SOR-14

Sort/Merge (SOR) Routines
13.2 Examples of Using SOR Routines

Example 13-4 (Cont.)

Using SOR Routines to Sort Records from Two Input Files in a VAX
Pascal Program

FUNCTION SOR$SORT_MERGE
: INTEGER ; EXTERN ;
FUNCTION SOR$RETURN_REC(
%STDESCR Rec : Recordbuf fer
VAR Recordsize : $UWORD )
: INTEGER ; EXTERN
FUNCTION SOR$END_SORT
: INTEGER ; EXTERN
(* End of the SORT function declarations *)
(* The CHECKSTATUS routine checks the return status for errors. *)
(* If there is an error, write an error message and exit via sys$exit *)
PROCEDURE CHECKSTATUS( var status : integer ) ;

procedure sys$exit( status : integer ) ; extern ;
begin
(* begin checkstatus *)
if odd(status) then
begin
writeln( ' SORT unsuccessful. Error status
SYS$EXIT( status ) ;
end ;
end ;
(* end checkstatus *)

status: 8 hex )

(* end function and routine declarations *)
BEGIN

(* begin the main routine *)

(* Initialize data for one 8-byte character key, starting at record
offset 0, 3 work files, and the record sorting process *)
Inputname := 'PASINPUTl.DAT'
WITH Buff er DO
BEGIN
Numkeys : = 1;
WITH Blocks[l] DO
BEGIN
Keytype := DSC$K_DTYPE_T

(* Use VMS descriptor data types to
define SORT data types. *)

Keyorder := Ascending
Keyoffset ·= 0
Keylength ·= 8 ;
END;
END;
(continued on next page)

SOR-15

Sort/Merge (SOR) Routines
13.2 Examples of Using SOR Routines

Example 13-4 (Cont.)

Using SOR Routines to Sort Records from Two Input Files in a VAX
Pascal Program

Sorttype := SOR$GK_RECORD ;
Sortoptions := SOR$M_STABLE

(* Use the global SORT constant to
define the sort process. *)
(* Use the global SORT constant to
define the stable sort option. *)

Numworkfiles := 3 ;

(* call the sort routines as a series of functions *)
(* pass the first filename to SORT *)
Status := SOR$PASS_FILES( Inputname )

(* Check status for error. *)
CHECKSTATUS( Status ) ;
(* pass the second filename to SORT *)
Inputname := 'PASINPUT2.DAT' ;
Status := SOR$PASS_FILES( Inputname ) ;

(* Check status for error. *)
CHECKSTATUS( Status ) ;
(* initialize work areas and keys *)
Status := SOR$BEGIN_SORT( Buffer, 0, Sortoptions, 0, 0, 0,
Sorttype, Numworkfiles ) ;
(* Check status for error. *)
CHECKSTATUS( Status ) ;

(* sort the records *)
Status := SOR$SORT_MERGE
(* Check status for error. *)
CHECKSTATUS( Status ) ;

(* Ready output file for writing returned records from SORT. *)
OPEN( SORTOUT, 'TEMP.TMP' ) ;
REWRITE( SORTOUT ) ;
(* Now get the sorted records from SORT. *)
Recordlength := 0 ;
REPEAT
Status := SOR$RETURN_REC( Rec, Recordlength ) ;
if odd( Status
then
(* if successful, write record to output file. *)
begin
for i := 1 to Recordlength do
(* write each character *)
write( sortout, Rec[i] ) ;
writeln (sortout)
(* end output line *)
end;
UNTIL not odd( Status ) ;

(* If there was just no more data to be returned (eof) continue, otherwise
exit with an error. *)
if Status <> SS$_ENDOFFILE then
CHECKSTATUS( Status ) ;
(* The sort has been successful to this point. *)
(* Close the output file *)
CLOSE( sortout ) ;
(continued on next page)

SOR-16

Sort/Merge (SOR) Routines
13.2 Examples of Using SOR Routines

Example 13-4 {Cont.)

Using SOR Routines to Sort Records from Two Input Files in a VAX
Pascal Program

(* clean up work areas and files *)
Status := SOR$END_SORT ;
(* Check status for error. *)
CHECKSTATUS( Status );
WRITELN ('SORT SUCCESSFUL') ;
END.

13.3

SOR Routines
The following pages describe the individual SOR routines.

SOR-17

Sort/Merge (SOR) Routines
SOR$BEGIN_MERGE

SOR$BEGIN_MERGE Initialize a Merge Operation
The SOR$BEGIN_MERGE routine initializes the merge operation by opening
the input and output files and by providing the number of input files, the key
specifications, and the merge options.

FORMAT

SOR$BEGIN_MERGE

RETURNS

VMS usage:
type:
access:
mechanism:

[key-buffer] [,Ir/]
[,options] [,merge_order]
[,user_compare] [,user_equal]
[,user_input][, context]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
. CONDITION VALUES RETURNED.

ARGUMENTS

key_buffer
VMS usage:
type:
access:
mechanism:

vector_word_unsigned
word (unsigned)
read only
by reference

Array of words describing the keys on which you plan to merge. The
key_buffer argument is the address of an array containing the key
descriptions.
The first word of this array contains the number of keys described (up to
255). Following the first word, each key is described (in order of priority)
in blocks of four words. The four words specify the key's data type, order,
offset, and length, respectively.
The first word of the block specifies the key's data type. The following data
types are accepted:

DSC$K_DTYPE_Z
DSC$K_DTYPE_B
DSC$K_DTYPE_BU
DSC$K_DTYPE_W
DSC$K_DTYPE_WU
DSC$K_DTYPE_L
DSC$K_DTYPE_LU
DSC$K_DTYPE_Q

SOR-18

Unspecified (uninfluenced by collating sequence)
Byte integer (signed)
Byte (unsigned)
Word integer (signed)
Word (unsigned)
Longword integer (signed)
Longword (unsigned)
Quadword integer (signed)

Sort/Merge (SOR) Routines
SOR$BEGIN_MERGE

DSC$K_DTYPE_QU

Quadword (unsigned)

DSC$K_DTYPE_O

Octaword integer (signed)

DSC$K_DTYPE_OU

Octaword (unsigned)

DSC$K_DTYPE_F

Single-precision floating

DSC$K_DTYPE_D

Double-precision floating

DSC$K_DTYPE_G

G-format floating

DSC$K_DTYPE_H

H-format floating

DSC$K_DTYPE_T

Text (may be influenced by collating sequence)

DSC$K_DTYPE_NU

Numeric string, unsigned

DSC$K_DTYPE_NL

Numeric string, left separate sign

DSC$K_DTYPE_NLO

Numeric string, left overpunched sign

DSC$K_DTYPE_NR

Numeric string, right separate sign

DSC$K_DTYPE_NRO

Numeric string, right overpunched sign

DSC$K_DTYPE_NZ

Numeric string, zoned sign

DSC$K_DTYPE_P

Packed decimal string

The VAX Procedure Calling and Condition Handling Standard,
documented in the Introduction to VMS System Routines, describes each of
these data types.
The second word of the block specifies the key order: 0 for ascending order,
1 for descending order. The third word of the block specifies the relative
offset of the key in the record. (Note that the first byte in the record is at
position 0.) The fourth word of the block specifies the key length in bytes
(in digits for packed decimal-DSC$K_DTYPE_P).
If you do not specify the key_buffer argument, you must pass either a
key comparison routine or use a specification file to define the key.

Ir/
VMS usage: word_unsigned
type:
word (unsigned)
access:
read only
mechanism: by reference
Length of the longest record that will be released for merging. The lrl
argument is the address of a word containing the length. If the input file
is on a disk, this argument is not required. It is required when you use
the record interface. For VFC records, this length must include the length
of the fixed-length portion of the record.

options
VMS usage: mask_longword
type:
longword (unsigned)
access:
read only
mechanism: by reference
Flags that identify merge options. The options argument is the address of
a longword bit mask whose settings determine the merge options selected.
The following table lists and describes the bit mask values available.

SOR-19

Sort/Merge {SOR) Routines
SOR$BEGIN_MERGE

Flag

Description

SOR$M_STABLE

Keeps records with equal keys in the same order as they
appeared on input.

SOR$M_EBCDIC

Orders ASCII character keys according to EBCDIC collating
sequence. No translation takes place.

SOR$M_MULTI

Orders character keys according to the multinational
collating sequence, which collates the international
character set.

SOR$M_NOSIGNAL

Returns a status code instead of signaling errors. (This is
the default behavior.)

SOR$M_NODUPS

Omits records with duplicate keys. You cannot use this
option if you specify your own equal-key routine.

SOR$M_SEQ_CHECK

Requests an "out of order" error return if an input file is not
already in sequence. By default, this check is not done.
You must request sequence checking if you specify an
equal-key routine.

All other bits in the longword are reserved and must be zero.

merge_order
VMS usage: byte_unsigned
type:
byte (unsigned)
access:
read only
mechanism: by reference
Number of input streams to be merged. The merge_order argument is
the address of a byte containing the number of files (1through10) to be
merged. When you use the record interface on input, this argument is
required.

user_compare
VMS usage: procedure
type:
procedure entry mask
access:
function call
mechanism: by reference
Routine that compares records to determine their merge order. The user_
compare argument is the address of the entry mask for this user-written
routine. If you do not specify the key_buffer argument or if you define
key information in a specification file, this argument is required.

MERGE calls the comparison routine with five reference argumentsADRSl, ADRS2, LENG1, LENG2, CNTX-corresponding to the addresses
of the two records to be compared, the lengths of these two records, and
the context longword.
The comparison routine must return a 32-bit integer value:

SOR-20

•

-1 if the first record collates before the second

•

0 if the records collate as equal

•

1 if the first record collates after the second

Sort/Merge (SOR) Routines
SOR$BEGIN_MERGE

user_equal
procedure
procedure entry mask
function call
by reference
Routine that resolves the merge order when records have duplicate keys.
The user_equal argument is the address of the entry mask for this userwritten routine. If you specify SOR$M_STABLE or SOR$M_NODUPS in
the options argument, do not use this argument.
VMS usage:
type:
access:
mechanism:

MERGE calls the duplicate key routine with five reference argumentsADRSl, ADRS2, LENG1, LENG2, CNTX-corresponding to the addresses
of the two records that compare equally, the lengths of the two records
that compare equally, and the context longword.
The routine must return one of the following 32-bit condition codes.
Code

Description

SOR$_DELETE1

Delete the first record from the merge.

SOR$_DELETE2

Delete the second record from the merge.

SOR$_DELBOTH

Delete both records from the merge.

SS$_NORMAL

Keep both records in the merge.

Any other failure value causes the error to be signaled or returned. Any
other success value causes an undefined result.

user_input
procedure
procedure entry mask
function call
by reference
Routine that releases records to the merge operation. The user_input
argument is the address of the entry mask for this user-written routine.
SOR$BEGIN_MERGE and SOR$RETURN_REC call this routine until all
records have been passed.

VMS usage:
type:
access:
mechanism:

This input routine must read (or construct) a record, place it in a record
buffer, store its length in an output argument, and then return control to
MERGE.
The input routine must accept the following four arguments:
•

A descriptor of the buffer where the routine must place the record

•

A longword, passed by reference, containing the stream number from
which to input a record (the first file is 1, the second 2, and so on)

•

A word, passed by reference, where the routine must return the actual
length of the record

•

The context longword, passed by reference

The input routine must also return one of the following status values:
•

SS$_NORMAL or any other success status causes the merge operation
to continue.
SOR-21

Sort/Merge (SOR) Routines
SOR$BEGIN_MERGE

•

SS$_ENDOFFILE indicates that no more records are in the file. The
contents of the buffer are ignored.

•

Any other error status terminates the merge operation and passes
the status value back to the caller of SOR$BEGIN_MERGE or
SOR$RETURN_REC.

context
VMS usage: context
longword (unsigned)
access:
modify
mechanism: by reference
Value that distinguishes between multiple, concurrent SORT/MERGE
operations. The context argument is the address of a longword containing
the context value. When your program makes its first call to a SORT
/MERGE routine for a particular sort or merge operation, the context
longword must equal zero. SORT/MERGE then stores a value in the
longword to identify the operation just initiated. When you make
subsequent routine calls for the same operation, you must pass the context
value that was supplied by SORT/MERGE.
type:

DESCRIPTION

The SOR$BEGIN_MERGE routine initializes the merge process by
passing arguments that provide the number of input streams, the key
specifications, and any merge options.
You must define the key by passing either the key buffer address argument
or your own comparison routine address. (You can also define the key in a
specification file and call the SOR$SPEC_FILE routine.)
The SOR$BEGIN_MERGE routine initializes the merge process in the file,
record, and mixed interfaces. For record interface on input, you must also
pas~ the merge order, the input routine address, and the longest record
length. For files not on disk, you must pass the longest record length.
Some of the following condition values are used with different severities,
depending on whether SORT/MERGE can recover. Thus, you should use
LIB$MATCH_COND if you want to check for a specific status.

CONDITION
VALUES
RETURNED

SOR-22

SS$_NORMAL

Success.

SOR$_BADDTYPE

Invalid or unsupported CDD datatype.

SOR$_BADLENOFF

Length and offset must be multiples of 8 bits.

SOR$_BADLOGIC

Internal logic error detected.

SOR$_BADOCCURS

Invalid OCCURS clause.

SOR$_BADOVRLAY

Invalid overlay structure.

SOR$_BADPROTCL

Node is an invalid COD object.

SOR$_BAD_KEY

Invalid key specification.

SOR$_BAD_LRL

Record length n greater than specified longest record
length.

Sort/Merge (SOR) Routines
SOR$BEGIN_MERGE

SOR$_BAD_MERGE

Number of work files must be between 0 and 10.

SOR$_BAD_ORDER

Merge input is out of order.

SOR$_BAD_SRL

Record length n is too short to contain keys.

SOR$_BAD_TYPE

Invalid sort process specified.

SOR$_CDDERROR

COD error at node 'name'.

SOR$_CLOSE IN

Error closing 'file' as input.

SOR$_CLOSEOUT

Error closing 'file' as output.

SOR$_COL_CHAR

Invalid character definition.

SOR$_COL_CMPLX

Collating sequence is too complex.

SOR$_COL_PAD

Invalid pad character.

SOR$_COL_THREE

Cannot define 3-byte collating values.

SOR$_ENDDIAGS

Completed with diagnostics.

SOR$_1LLBASE

Nondecimal base is invalid.

SOR$_1LLLITERL

Record containing symbolic literals is unsupported.

SOR$_1LLSCALE

Nonzero scale invalid for floating-point data item.

SOR$_1NCDIGITS

Number of digits is not consistent with the type or
length of item. ·

SOR$_1NCNODATA

Include specification references no data, at line n.

SOR$_1NCNOKEY

Include specification references no keys, at line n.

SOR$_1ND_OVR

Indexed output file must already exist.

SOR$_KEYAMBINC

Key specification is ambiguous or inconsistent.

SOR$_KEYED

Mismatch between SORT/MERGE keys and primary
file key.

SOR$_KEY_LEN

Invalid key length, key number n, length n.

SOR$_LRL_MISS

Longest record length must be specified.

SOR$_MISLENOFF

Length and offset required.

SOR$_MISS_PARAM

A required subroutine argument is missing.

SOR$_MULTIDIM

Invalid multidimensional OCCURS.

SOR$_NODUPEXC

Equal-key routine and no-duplicates option cannot
both be specified.

SOR$_NOTRECORD

Node ' name' is a name, not a record definition.

SOR$_NUM_KEY

Too many keys specified.

SOR$_OPEN IN

Error opeFling 'file' as input.

SOR$_0PENOUT

Error opening 'file' as output.

SOR$_READERR

Error reading ' file' .

SOR$_RTNERROR

Unexpected error status from user~written routine.

SOR$_SIGNCOMPQ

Absolute Date and Time data type represented in
one-second units.

SOR$_SORT_ON

Sort or merge routines called in incorrect order.

SOR$_SPCIVC

Invalid collating sequence specification at line n.

SOR$_SPCIVD

Invalid data type at line n.

SOR-23

Sort/Merge (SOR) Routines
SOR$BEGIN_MERGE

SOR-24

SOR$_SPCIVF

Invalid field specification at line n.

SOR$_SPCIVI

Invalid include or omit specification at line n.

SOR$_SPCIVK

Invalid key or data specification at linen.

SOR$_SPCIVP

Invalid sort process at linen.

SOR$_SPCIVS

Invalid specification at line n.

SOR$_SPCIVX

Invalid condition specification at line n.

SOR$_SPCMIS

Invalid merge specification at line n.

SOR$_SPCOVR

Overridden specification at linen.

SOR$_SPCSIS

Invalid sort specification at line n.

SOR$_SRTIWA

Insufficient space. The specification file is too
complex.

SOR$_STABLEEX

Equal-key routine and stable option cannot both be
specified.

SOR$_SYSERROR

System service error.

SOR$_UNDOPTION

Undefined option flag was set.

SOR$_UNSUPLEVL

Unsupported core level for record ' name' .

SOR$_WRITEERR

Error writing 'file' .

Sort/Merge (SOR) Routines
SOR$BEGIN_SORT

SOR$BEGIN_SORT

Begin a Sort Operation

The SOR$BEGIN_SORT routine initializes a sort operation by opening input
and output files and by passing the key information and any sort options.

FORMAT

SOR$BEGIN_SORT [key_buffer] [,Ir/] [,options]
[,file_alloc] [,user_compare]
[,user_ equal][, sort_process]
[,work_files][, context]

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

key_buffer
VMS usage:
type:
access:
mechanism:

vector_word_unsigned
word (unsigned)
read only
by reference

Array of words describing the keys on which you plan to sort. The
key_buffer argument is the address of an array containing the key
descriptions.
The first word of this array contains the number of keys described (up to
255). Following the first word, each key is described (in order of priority)
in blocks of four words. The four words specify the key's data type, order,
offset, and length, respectively.
The first word of the block specifies the data type of the key. The following
data types are accepted:

DSC$K_DTYPE_Z
DSC$K_DTYPE_B
DSC$K_DTYPE_BU
DSC$K_DTYPE_W
DSC$K_DTYPE_WU
DSC$K_DTYPE_L
DSC$K_DTYPE_LU
DSC$K_DTYPE_Q
DSC$K_DTYPE_QU

Unspecified (uninfluenced by collating sequence)
Byte integer (signed)
Byte (unsigned)
Word integer (signed)
Word (unsigned}
Longword integer (signed)
Longword (unsigned)
Quadword integer (signed)
Quadword (unsigned)

SOR-25

Sort/Merge (SOR) Routines
SOR$BEGIN_SORT

DSC$K_DTYPE_O

Octaword integer (signed)

DSC$K_DTYPE_OU

Octaword (unsigned)

DSC$K_DTYPE_F

Single-precision floating

DSC$K_DTYPE_D

Double-precision floating

DSC$K_DTYPE_G

G-format floating

DSC$K_DTYPE_H

H-format floating

DSC$K_DTYPE_T

Text (may be influenced by collating sequence)

DSC$K_DTYPE_NU

Numeric string, unsigned

DSC$K_DTYPE_NL

Numeric string, left separate sign

DSC$K_DTYPE_NLO

Numeric string, left overpunched sign

DSC$K_DTYPE_NR

Numeric string, right separate sign

DSC$K_DTYPE_NRO

Numeric string, right overpunched sign

DSC$K_DTYPE_NZ

Numeric string, zoned sign

DSC$K_DTYPE_P

Packed decimal string

The VAX Procedure Calling and Condition Handling Standard,
documented in the Introduction to VMS System Routines, describes each of
these data types.
The second word of the block specifies the key order: 0 for ascending order,
1 for descending order. The third word of the block specifies the relative
offset of the key in the record. Note that the first byte in the record is at
position 0. The fourth word of the block specifies the key length in bytes
(in digits for packed decimal-DSC$K_DTYPE_P).
The key_buffer argument specifies the address of the key buffer in the
data area. If you do not specify this argument, you must either pass a key
comparison routine or use a specification file to define the key.

Ir/
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
read only
by reference

Length of the longest record that will be released for sorting. The lrl
argument is the address of a word containing the length. This argument
is not required if the input files are on disk but is required when you use
the record interface. For VFC records, this length must include the length
of the fixed-length portion of the record.

options
VMS usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by reference

Flags that identify sort options. The options argument is the address of
a longword bit mask whose settings determine the merge options selected.
The following table lists and describes the bit mask values available:

SOR-26

Sort/Merge (SOR) Routines
SOR$BEGIN_SORT

Flags

Description

SOR$M_STABLE

Keeps records with equal keys in the same order in which
they appeared on input. With multiple input files that have
records that collate as equal, records from the first input file
are placed before the records from the second input file, and
so on.

SOR$M_EBCDIC

Orders ASCII character keys according to EBCDIC collating
sequence. No translation takes place.

SOR$M_MULTI

Orders character keys according to the multinational collating
sequence, which collates the international character set.

SOR$M_NOSIGNAL

Returns the condition code instead of signaling an error. The
default is SOR$M_NOSIGNAL.

SOR$M_NODUPS

Omits records with duplicate keys. You cannot use this option
if you specify your own equal-key routine.

All other bits in the longword are reserved and must be zero.

file a/lac
VMS usage: longword_unsigned
longword (unsigned)
access:
read only
mechanism: by reference
Input file size in blocks. The file_alloc argument is the address of a
longword containing the size. This argument is never required because,
by default, SORT uses the allocation of the input files. If you are using
the record interface or if the input files are not on disk, the default is 1000
blocks.
type:

However, you can use this optional argument to improve the efficiency of
the sort by adjusting the amount of resources the sort process allocates.

user_compare
VMS usage: procedure
procedure entry mask
access:
function call
mechanism: by reference
User-written routine that compares records to determine their sort order.
The user_compare argument is the address of the entry mask for this
user-written routine. If you do not specify the key_bu:ffer argument
or if you define key information in a specification file, this argument is
required.
type:

SORT/MERGE calls the comparison routine with five reference
arguments-ADRSl, ADRS2, LENG1, LENG2, CNTX--corresponding
to the addresses of the two records to be compared, the lengths of these
two records, and the context longword.
The comparison routine must return a 32-bit integer value:
•

-1 if the first record collates before the second

•

0 if the records collate as equal

•

1 if the first record collates after the second

SOR-27

Sort/Merge {SOR) Routines
SOR$BEGIN_SORT

user_equal
VMS usage: procedure
type:

procedure entry mask

access:
function call
mechanism: by reference
User-written routine that resolves the sort order when records have
duplicate keys. The user_equal argument is the address of the entry
mask for this user-written routine. If you specify SOR$M_STABLE or
SOR$M_NODUPS in the options argument, do not use this argument.

SORT/MERGE calls the duplicate key routine with five reference
arguments-ADRSl, ADRS2, LENGl, LENG2, CNTX-corresponding
to the addresses of the two records that compare equally, the lengths of
the two records that compare equally, and the context longword.
The routine must return one of the following 32-bit integer condition codes:
Code

Description

SOR$_DELETE1

Delete the first record from the sort.

SOR$_DELETE2

Delete the second record from the sort.

SOR$_DELBOTH

Delete both records from the sort.

SS$_NORMAL

Keep both records in the sort.

Any other failure value causes the error to be signaled or returned. Any
other success value causes an undefined result.

sort_process
VMS usage: byte_unsigned
type:

byte (unsigned)

access:
read only
mechanism: by reference
Code indicating the type of sort process. The sort_process argument
is the address of a byte whose value indicates whether the sort type is
record, tag, index, or address. The default is record. If you select the
record interface on input, you can use only a record sort process.

To specify a byte containing the value for the type of sort process you
want, enter one of the following:
•

SOR$GK_RECORD (record sort)

•

SOR$GK_TAG (tag sort)

•

SOR$GK_ADDRESS (address sort)

•

SOR$GK_INDEX (index sort)

work_files
VMS usage: byte_unsigned
type:

byte (unsigned)

access:
read only
mechanism: by reference
Number of work files to be used in the sorting prt:>cess. The work_files
argument is the address of a byte containing the number of work files;
permissible values range from 0 through 10.
SOR-28

Sort/Merge (SOR) Routines
SOR$BEGIN_SORT

By default, SORT creates two temporary work files when it needs them
and determines their size from the size of your input files. By increasing
the number of work files, you can reduce their individual size so that each
fits into less disk space. You can also assign each of them to different
disk-structured devices.

context
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
write only
by reference

Value that distinguishes between multiple, concurrent SORT/MERGE
operations. The conte-xt argument is the address of a longword containing
the context value. When your program makes its first call to a SORT
/MERGE routine for a particular sort or merge operation, the context
longword must equal zero. SORT/MERGE then stores a value in the
longword to identify the operation just initiated. When you make
subsequent routine calls for the same operation, you must pass the context
value supplied by SORT/MERGE.

DESCRIPTION

The SOR$BEGIN_SORT routine initializes the sort process by setting up
sort work areas and provides key specification and sort options.
Specify the key information with the key_buffer argument, with the
user_compare argument, or in a specification file. If no key information
is specified, the default (character for the entire record) is used.
You must use the SOR$BEGIN_SORT routine to initialize the sort process
for the file, record, and mixed interfaces. For record interface on input,
you must use the lrl (longest record length) argument.
Some of the following condition values are used with different severities,
depending on whether SORT/MERGE can recover. Thus, if you want to
check for a specific status, you should use LIB$MATCH_COND.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Success.

SOR$_BADLOGIC

Internal logic error detected.

SOR$_BAD_KEY

Invalid key specification.

SOR$_BAD_LRL

Record length n greater than specified longest record
length.

SOR$_BAD_MERGE

Number of work files must be between 0 and 10.

SOR$_BAD_TYPE

Invalid sort process specified.

SOR$_ENDDIAGS

Completed with diagnostics.

SOR$_1NSVIRMEM

Insufficient virtual memory.

SOR$_KEYAMBINC

Key specification is ambiguous or inconsistent.

SOR$_KEY_LEN

Invalid key length, key number n, length n.

SOR$_LRL_MISS

Longest record length must be specified.

SOR-29

Sort/Merge (SOR) Routines
SOR$BEGIN_SORT

SOR-30

SOR$_NODUPEXC

Equal-key routine and no-duplicates option cannot
both be specified.

SOR$_NUM_KEY

Too many keys specified.

SOR$_RTNERROR

Unexpected error status from user-written routine.

SOR$_SORT_ON

Sort or merge routine called in incorrect order.

SOR$_STABLEEXC

Equal-key routine and stable option cannot both be
specified.

SOR$_SYSERROR

System service error.

SOR$_UNDOPTION

Undefined option flag was set.

Sort/Merge {SOR) Routines
SOR$DTVPE

SOR$DTYPE

Define Data Type
The SOR$DTYPE routine defines a key data type that is not normally
supported by SORT/MERGE. This routine returns a key data type code
that can be used in the key_buffer argument to SOR$BEGIN_SORT or
SOR$BEGIN_MERGE to describe special key data types (such as extended
data types and NCS collating sequences}.

FORMAT

SOR$DTYPE [context], dtype_code, usage, p1

RETURNS

VMS usage:
type:
access:
mechanism:

Cond_value
longword {unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

context
context
longword {unsigned)
modify
by reference
Value that distinguishes between multiple, concurrent SORT/MERGE
operations. The context argument is the address of a longword containing
the context value. When your program makes its first call to a SORT
/MERGE routine for a particular sort or merge operation, the context
longword must equal zero. SORT/MERGE then stores a value in the
longword to identify the operation just initiated. When you make
subsequent routine calls for the same operation, you must pass the context
value supplied by SORT/MERGE.
VMS usage:
type:
access:
mechanism:

dtype_code
word_unsigned
word {unsigned)
write only
by reference
Returned key data type code. The dtype_code argument is the address of
a word into which SORT/MERGE writes the key data type code that can be
used in the key_buffer argument to SOR$BEGIN_SORT or SOR$BEGIN_
MERGE.
VMS usage:
type:
access:
mechanism:

usage
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword {unsigned)
read only
by reference
SOR-31

Sort/Merge (SOR) Routines

SOR$DTYPE
Address of a longword containing a code that indicates the interpretation
of the pl argument. The following table lists and describes the valid usage
codes.
Flag

Description

SOR$K_ROUTINE

The p1 argument should be interpreted as the address of
the entry mask of a routine that SORT/MERGE will call
to compare keys described by the dtype_code returned
by the call to SOR$DTYPE.

SOR$K_NCS_TABLE

The p1 argument should be interpreted as the address
of a collating sequence identification returned by a call
to NCS$GET_CS. SORT/MERGE will use this collating
sequence to compare keys described by the dtype_code
returned by the call to SOR$DTYPE.

If SOR$K_ROUTINE is returned, SORT/MERGE will call this routine with

five reference arguments-ADRSl, ADRS2, LENG1, LENG2, CNTXcorresponding to the addresses of the two keys to be compared, the lengths
of the two keys, and the context longword.
The comparison routine must return a 32-bit integer value:
•

-1 if the first key collates before the second

•

0 if the keys collate as equal

•

+1 if the first key collates after the second

p1
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference

Address of an entry mask of a routine or the address of a collating
sequence identification, depending on the usage argument.

DESCRIPTION

Call SOR$DTYPE to define a key data type not normally supported by
SORT/MERGE.
If your SORT/MERGE application needs to compare dates (for example)
that are stored in text form and that is the only key in the records, then

use the user_compare argument to SOR$BEGIN_SORT or SOR$BEGIN_
MERGE. However, if the records contain several keys besides the dates
in text form, it may be easier to call SOR$DTYPE to allocate a key data
type code that can then be used in the the key_buffer argument to
SOR$BEGIN_SORT or SOR$BEGIN_MERGE.
If your SORT/MERGE application has a string key that should be collated

by a collating sequence defined by the VMS National Character Set (NCS)
Utility, the NCS$GET_CS routine can be used to fetch the collating
sequence definition, and SOR$DTYPE can be called to allocate a key data
type code for the collating sequence. This key data type code can then be
used to describe keys that should be compared by this collating sequence.
SOR-32

Sort/Merge (SOR) Routines
SOR$DTYPE

CONDITION
VALUES
RETURNED

SS$_NORMAL

Success.

SOR$_SORT_ON

Sort or merge routine called in incorrect order.

SOR-33

Sort/Merge (SOR) Routines
SOR$END_SORT

SOR$END_SORT

End a Sort Operation

The SOR$END_SORT routine does cleanup functions, such as closing files
and releasing memory.

FORMAT

SOR$END_SORT

RETURNS

VMS usage:
type:
access:
mechanism:

[context]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

context
VMS usage: context
type:
longword
access:
write only
mechanism: by reference
Value that distinguishes between multiple, concurrent SORT/MERGE
operations. The cont.ext argument is the address of a longword containi~g
the context value. When your program makes its first call to a SORT
/MERGE routine for a particular sort or merge operation, the context
longword must equal zero. SORT/MERGE then stores a value in the
longword to identify the operation just initiated. When you make
subsequent routine calls for the same operation, you must pass the context
value supplied by SORT/MERGE.

DESCRIPTION

The SOR$END_SORT routine ends a sort or merge operation, either at the
end of a successful process or between calls because of an error. If an error
status is returned, you must call SOR$END_SORT to release all allocated
resources. In addition, this routine can be called at any time to close files
and release memory.
The value of the optional context argument is cleared when the
SOR$END_SORT routine completes its operation.
Some of the following condition values are used with different severities,
depending on whether SORT/MERGE can recover. Thus, if you want to
check for a specific status, you should use LIB$MATCH_COND.

SOR-34

Sort/Merge (SOR) Routines
SOR$END_SORT

CONDITION
VALUES
RETURNED

SS$_NORMAL

Success.

SOR$_CLOSEIN

Error closing 'file' as input.

SOR$_CLOSEOUT

Error closing 'file' as output.

SOR$_ENDDIAGS

Completed with diagnostics.

SOR$_END_SORT

SORT/MERGE terminated, context = 'context' .

SOR$_SYSERROR

System service error.

SOR-35

Sort/Merge {SOR) Routines
SOR$PASS_FILES

SOR$PASS_FILES

Pass File Names

The SOR$PASS_FILES routine passes the names of input and output files
and output file characteristics to SORT or MERGE.

FORMAT

SOR$PASS_FILES

RETURNS

VMS usage:
type:
access:
mechanism:

[inp_desc] [,ouLdesc] [,org] [,rfm]
[,bks] [,bis] [,mrs] [,alq] [,fop] [,fsz]
[,context]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

inp_desc
char_string
character-coded text string
read only
by descriptor
Input file specification. The inp_desc argument is the address of a
descriptor pointing to the file specification. In the file interface, you
must call SOR$PASS_FILES to pass SORT the input file specifications.
For multiple input files, call SOR$PASS_FILES once for each input file,
passing one input file specification descriptor each time.

VMS usage:
type:
access:
mechanism:

In the mixed interface, if you are using the record interface on input, pass
only the output file specification; do not pass any input file specifications.
If you are using the record interface on output, pass only the input file
specifications; do not pass an output file specification or any of the optional
output file arguments.

out_desc
char_string
character-coded text string
read only
by descriptor
Output file specification. The out_desc argument is the address of a
descriptor pointing to the file specification. In the file interface, when
you call SOR$PASS_FILES, you must pass the output file specification.
Specify the output file specification and characteristics only once, as part
of the first call, as in the following:

VMS usage:
type:
access:
mechanism:

Call SOR$PASS FILES(Inputl,Output)
Call SOR$PASS-FILES(Input2)
Call SOR$PASS=FILES(Input3)

SOR-36

Sort/Merge (SOR) Routines
SOR$PASS_FILES

org
VMS usage: byte_unsigned
type:

byte (unsigned)

access:
read only
mechanism: by reference
File organization of the output file, if different from the input file. The org
argument is the address of a byte whose value specifies the organization of
the output file; permissible values include the following:
FAB$C_SEQ
FAB$C_REL
FAB$C_IDX

For the record interface on input, the default value is sequential. For the
file interface, the default value is the file organization of the first input file
for record or tag sort and sequential for address and index sort.
For more information about the FAB fields, see the VMS Record
Management Services Manual.

rfm
VMS usage: byte_unsigned
type:

byte (unsigned)

access:
read only
mechanism: by reference
Record format of the output file, if different from the input file. The rfm.
argument is the address of a byte whose value specifies the record format
of the output file; permissible values include the following:
FAB$C FIX
FAB$C=VAR
FAB$C_VFC

For the record interface on input, the default value is variable. For the
file interface, the default value is the record format of the first input
file for record or tag sort and fixed format for address or index sort. For
the mixed interface with record interface on input, the default value is
variable format.

bks
VMS usage: byte_unsigned
type:

byte (unsigned)

access:
read only
mechanism: by reference
Bucket size of the output file, if different from the first input file. The bks
argument is the address of a byte containing this size. Use this argument
with relative and indexed-sequential files only. If the bucket size of the
output file is to differ from that of the first input file, specify a byte to
indicate the bucket size. Acceptable values are from 1 to 32. If you do
not pass this argument-and the output file organization is the same as
that of the first input file-the bucket size defaults to the value of the first
SOR-37

Sort/Merge {SOR) Routines
SOR$PASS_FILES

input file. If the file organizations differ or if the record interface is used
on input, the default value is 1 block.

bis
VMS usage: word_unsigned
word (unsigned)
access:
read only
mechanism: by reference
Block size of a magnetic tape output file. The bis argument is the address
of a word containing this size. Use this argument with magnetic tapes
only. Permissible values range from 20 to 65,532. However, to ensure
compatibility with non-Digital systems, ANSI standards require that the
block size be less than or equal to 2048.

type:

The block size defaults to the block size of the input file magnetic tape. If
the input file is not on magnetic tape, the output file block size defaults to
the size used when the magnetic tape was mounted.

mrs
VMS usage: word_unsigned
word (unsigned)
access:
read only
mechanism: by reference
Maximum record size for the output file. The mrs argument is the address
of a word specifying this size. Following are acceptable values for each
type of file.
type:

File Organization

Acceptable Value

Sequential

Oto 32,767

Relative

Oto 16,383

Indexed sequential

Oto 16,362

If you omit this argument or if you specify a value of 0, SORT does not

check maximum record size.
If you do not specify this argument, the default is based on the output

file organization and format, unless the organization is relative or the
format is fixed. The longest output record length is based on the longest
calculated input record length, the type of sort, and the record format.

alq
VMS usage: longword_unsigned
longword (unsigned)
access:
read only
mechanism: by reference
Number of preallocated output file blocks. The alq argument is the
address of a longword specifying the number of blocks you want to
preallocate to the output file. Acceptable values range from 1 to
4,294,967 ,295.

type:

SOR-38

Sort/Merge {SOR) Routines
SOR$PASS_FILES

Pass this argument if you know your output file allocation will be larger
or smaller than that of your input files. The default value is the total
allocation of all the input files. If the allocation cannot be obtained for any
of the input files or if record interface is used on input, the file allocation
defaults to 1000 blocks.

fop
VMS usage: mask_longword
type:

longword (unsigned)

access:
read only
mechanism: by reference
File-handling options. The fop argument is the address of a longword
whose bit settings determine the options selected. For a list of valid
options, see the description of the FAB$L_FOP field in the VMS Record
Management Services Manual. By default, only the DFW (deferred write)
option is set. If your output file is indexed, you should set the CIF (create
if) option.

fsz
VMS usage: byte_unsigned
type:

byte (unsigned)

access:
read only
mechanism: by reference
Size of the fixed portion of VFC records. The fsz argument is the address
of a byte containing this size. If you do not pass this argument, the default
is the size of the fixed portion of the first input file. If you specify the VFC
size as 0, RMS defaults the value to 2 bytes.

context
VMS usage: context
type:

longword (unsigned)

access:
write only
mechanism: by reference
Value that distinguishes between multiple concurrent SORT/MERGE
operations. The context argument is the address of a longword containing
the context value. When your program makes its first call to a SORT
/MERGE routine for a particular sort or merge operation, the context
longword must equal zero. SORT/MERGE then stores a value in the
longword to identify the operation just initiated. When you make
subsequent routine calls for the same operation, you must pass the context
value supplied by SORT/MERGE.

DESCRIPTION

The SOR$PASS_FILES routine passes input and output file specifications
to SORT. The SOR$PASS_FILES routine must be repeated for multiple
input files. The output file name string and characteristics should be
specified only in the first call to SOR$PASS_FILES.
This routine also accepts optional arguments that specify characteristics
for the output file. By default, the output file characteristics are the same
as the first input file; specified output file characteristics are used to
change these defaults.

SOR-39

Sort/Merge {SOR) Routines
SOR$PASS_FILES

Some of the following condition values are used with different severities,
depending on whether SORT/MERGE can recover. Thus, if you want to
check for a specific status, you should use LIB$MATCH_COND.

CONDITION
VALUES
RETURNED

SOR-40

SS$_NORMAL

Success.

SOR$_DUP_OUTPUT

Output file has already been specified.

SOR$_ENDDIAGS

Completed with diagnostics.

SOR$_1NP_FILES

Too many input files specified.

SOR$_SORT_ON

Sort or merge routine called in incorrect order.

SOR$_SYSERROR

System service error.

Sort/Merge {SOR) Routines
SOR$RELEASE_REC

SOR$RELEASE_REC

Pass One Record to Sort

The SOR$RELEASE_REC routine is used with the record interface to pass
one input record to SORT or MERGE.

FORMAT

SOR$RELEASE_REC

RETURNS

VMS usage:
type:
access:
mechanism:

desc [,context]

cond_value
longword {unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

desc
VMS usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor
Input record buffer. The desc argument is the address of a descriptor
pointing to the buffer containing the record to be sorted. If you use the
record interface, this argument is required.

context
VMS usage: context
type:
longword
access:
modify
mechanism: by reference
Value that distinguishes between multiple, concurrent SORT/MERGE
operations. The context argument is the address of a longword containing
the context value. When your program makes its first call to a SORT
/MERGE routine for a particular sort or merge operation, the context
longword must equal zero. SORT/MERGE then stores a value in the
longword to identify the operation just initiated. When you make
subsequent routine calls for the same operation, you must pass the context
value supplied by SORT/MERGE.

DESCRIPTION

Call SOR$RELEASE_REC to pass records to SORT or MERGE with the
record interface. SOR$RELEASE_REC must be called once for each record
to be sorted.
Some of the following condition values are used with different severities,
depending on whether SORT/MERGE can recover. Thus, if you want to
check for a specific status, you should use LIB$MATCH_COND.

SOR-41

Sort/Merge (SOR) Routines
SOR$RELEASE_REC

CONDITION

VALUES
RETURNED

SOR-42

SS$_NORMAL

Success.

SOR$_BADLOGIC

Internal logic error detected.

SOR$_BAD_LRL

Record length n greater than longest specified record
length.

SOR$_BAD_SRL

Record length n too short to contain keys.

SOR$_ENDDIAGS

Completed with diagnostics.

SOR$_EXTEND

Unable to extend work file for needed space.

SOR$_MISS_PARAM

The desc argument is missing.

SOR$_NO_WRK

Work files required, cannot do sort in memory as
requested.

SOR$_0PENOUT

Error opening 'file' as output.

SOR$_0PERFAIL

Error requesting operator service.

SOR$_0PREPLY

Operator reply is 'reply'.

SOR$_READERR

Error reading 'file'.

SOR$_REQ_ALT

Specify alternate 'name' file (or nothing to try again).

SOR$_RTNERROR

Unexpected error status from user-written routine.

SOR$_SORT_ON

Sort or merge routines called in incorrect order.

SOR$_SYSERROR

System service error.

SOR$_USE_ALT

Using alternate file ' name' .

SOR$_WORK_DEV

Work file ' name' must be on random access local
device.

Sort/Merge {SOR) Routines

SOR$RETURN_REC

Return One Sorted Record

The SOR$RETURN_REC routine is used with the record interface to return
one sorted or merged record to a program.

FORMAT

SOR$RETURN_REC

RETURNS

VMS usage:
type:
access:
mechanism:

desc [,length] [,context]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

desc
VMS usage:
type:
access:
mechanism:

char_string
character-coded text string
write only
by descriptor

Output record buffer. The desc argument is the address of a descriptor
pointing to the buffer that receives the sorted or merged record.

length
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

Length of the output record. The length argument is the address of a
word receiving the length of the record returned from SORT/MERGE.

context
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
modify
by reference

Value that distinguishes between multiple, concurrent SORT/MERGE
operations. The context argument is the address of a longword containing
the context value. When your program makes its first call to a SORT
/MERGE routine for a particular sort or merge operation, the context
longword must equal zero. SORT/MERGE then stores a value in the
longword to identify the operation just initiated. When you make
subsequent routine calls for the same operation, you must pass the context
value supplied by SORT/MERGE.

SOR-43

Sort/Merge {SOR) Routines

SOR$RETURN_REC

DESCRIPTION

Call the SOR$RETURN_REC routine to release the sorted or merged
records to a program. Call this routine once for each record to be returned.
SOR$RETURN_REC places the record into a record buffer that you set
up in the program's data area. After SORT has successfully returned all
the records to the program, it returns the status code SS$_ENDOFFILE,
which indicates that there are no more records to return.
Some of the following condition values are used with different severities,
depending on whether SORT/MERGE can recover. Thus, if you want to
check for a specific status, you should use LIB$MATCH_COND.

CONDITION
VALUES
RETURNED

SOR-44

SS$_NORMAL

Success.

SOR$_BADLOGIC

Internal logic error detected.

SOR$_ENDDIAGS

Completed with diagnostics.

SOR$_EXTEND

Unable to extend work file for needed space.

SOR$_MISS_PARAM

A required subroutine argument is missing.

SOR$_0PERFAIL

Error requesting operator service.

SOR$_0PREPLY

Operator reply is 'reply'.

SOR$_READERR

Error reading 'file' .

SOR$_REQ_ALT

Specify alternate 'name' file (or nothing to simply try
again).

SOR$_RTNERROR

Unexpected error status from user-written routine.

SOR$_SORT_ON

Sort or merge routines called in incorrect order.

SOR$_SYSERROR

System service error.

SOR$_USE_ALT

Using alternate file ' name' .

SOR$_WORK_DEV

Work file ' name' must be on random access local
device.

Sort/Merge (SOR) Routines
SOR$SORT_MERGE

SOR$SORT_MERGE

Sort

The SOR$SORT_MERGE routine sorts the input records.

FORMAT

SOR$SORT_MERGE

RETURNS

VMS usage:
type:
access:
mechanism:

[context]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

context
VMS usage: context
type:
longword (unsigned)
access:
modify
mechanism: by reference
Value that distinguishes between multiple, concurrent SORT/MERGE
operations. The context argument is the address of a longword containing
the context value. When your program makes its first call to a SORT
/MERGE routine for a particular sort or merge operation, the context
longword must equal zero. SORT/MERGE then stores a value in the
longword to identify the operation just initiated. When you make
subsequent routine calls for the same operation, you must pass the context
value supplied by SORT/MERGE.

DESCRIPTION

After you have passed either the file names or the records to SORT, call
the SOR$SORT_MERGE routine to sort the records. For file interface
on input, the input files are opened and the records are released to the
sort. For the record interface on input, the record must have already been
released (by calls to SOR$RELEASE_REC). For file interface on output,
the output records are reformatted and directed to the output file. For the
record interface on output, SOR$RELEASE_REC must be called to get the
sorted records.
Some of the return values are used with different severities depending
on whether SORT/MERGE can recover. Thus, if you want to check for a
specific status, you should use LIB$MATCH_COND.

SOR-45

Sort/Merge (SOR) Routines
SOR$SORT_MERGE

CONDITION
VALUES
RETURNED

SOR-46

SS$_NORMAL

Success.

SOR$_BADDTYPE

Invalid or unsupported COD data type.

SOR$_BADLENOFF .

Length and offset must be multiples of 8 bits.

SOR$_BADLOGIC

Internal logic error detected.

SOR$_BADOCCURS

Invalid OCCURS clause.

SOR$_BADOVRLAY

Invalid overlay structure.

SOR$_BADPROTCL

Node is an invalid COD object.

SOR$_BAD_LRL

Record length n greater than longest specified record
length.

SOR$_BAD_TYPE

Invalid sort process specified.

SOR$_CDDERROR

COD error at node ' name' .

SOR$_CLOSEIN

Error closing 'file' as input.

SOR$_CLOSEOUT

Error closing ' file' as output.

SOR$_COL_CHAR

Invalid character definition.

SOR$_COL_CMPLX

Collating sequence is too complex.

SOR$_COL_PAD

Invalid pad character.

SOR$_COL_THREE

Cannot define 3-byte collating values.

SOR$_ENDDIAGS

Completed with diagnostics.

SOR$_EXTEND

Unable to extend work file for needed space.

SOR$_1LLBASE

Nondecimal base is invalid.

SOR$_1LLLITERL

Record containing symbolic literals is unsupported.

SOR$_1LLSCALE

Nonzero scale invalid for floating-point data item.

SOR$_1NCDIG ITS

Number of digits is inconsistent with the type or length
of item.

SOR$_1NCNODATA

Include specification references no ' data' keyword,
at linen.

SOR$_1NCNOKEY

Include specification references no ' keys' keyword,
at linen.

SOR$_1ND_OVR

Indexed output file must already exist.

SOR$_KEYED

Mismatch between SORT/MERGE keys and primary
file key.

SOR$_LRL_MISS

Longest record length must be specified.

SOR$_MISLENOFF

Length and offset required.

SOR$_MULTIDIM

Invalid multidimensional OCCURS.

SOR$_NOTRECORD

Node 'name' is a name, not a record definition.

SOR$_NO_WRK

Work files required, cannot do sort in memory as
requested.

SOR$_0PENIN

Error opening 'file' as input.

SOR$_0PENOUT

Error opening 'file' as output.

SOR$_0PERFAIL

Error requesting operator service.

SOR$_0PREPLY

Operator reply is 'reply'.

Sort/Merge {SOR) Routines
SOR$SORT_MERGE

SOR$_READERR

Error reading 'file' .

SOR$_REQ_ALT

Specify alternate 'name' file (or nothing to try again).

SOR$_RTNERROR

Unexpected error status from user-written routine.

SOR$_SIGNCOMPQ

Absolute Date and Time data type represented in
one-second units.

SOR$_SORT_ON

Sort or merge routines called in incorrect order.

SOR$_SPCIVC

Invalid collating sequence specification, at line n.

SOR$_SPCIVD

Invalid data type, at line n.

SOR$_SPCIVF

Invalid field specification, at line n.

SOR$_SPCIVI

Invalid include or omit specification, at line n.

SOR$_SPCIVK

Invalid key or data specification, at line n.

SOR$_SPCIVP

Invalid sort process, at line n.

SOR$_SPCIVS

Invalid specification, at line n.

SOR$_SPCIVX

Invalid condition specification, at line n.

SOR$_SPCMIS

Invalid merge specification, at linen.

SOR$_SPCOVR

Overridden specification, at linen.

SOR$_SPCSIS

Invalid sort specification, at Jine n.

SOR$_SRTIWA

Insufficient space. Specification file is too complex.

SOR$_SYSERROR

System service error.

SOR$_UNSUPLEVL

Unsupported core level for record 'name'.

SOR$_USE_ALT

Using alternate file ' name' .

SOR$_WORK_DEV

Work file 'name' must be on random access local
device.

SOR$_WRITEERR

Error writing ' file' .

SOR-47

Sort/Merge (SOR) Routines
SOR$SPEC_FILE

SOR$SPEC_FILE

Pass a Specification File Name

The SOR$SPEC_FILE routine is used to pass a specification file or
specification text to a sort or merge operation.

FORMAT

SOR$SPEC_FILE

RETURNS

VMS usage:
type:
access:
mechanism:

[spec_file] [,spec_buffer] [,context]

cond_value
longword {unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

spec_file
VMS usage:
type:
access:
mechanism:

char_string
character-coded text string
read-only
by descriptor

Specification file name. The spec_file argument is the address of a
descriptor pointing to the name of a file that contains the text of the
options requested for the sort or merge. The specification file name string
and the specification file buffer arguments are mutually exclusive.

spec_buffer
VMS usage:
type:
access:
mechanism:

char_string
character-coded text string
read-only
by descriptor

Specification text buffer. The spec_buffer argument is the address of a
descriptor pointing to a buffer containing specification text. This text has
the same format as the text within the specification file. The specification
file name string and the specification file buffer arguments are mutually
exclusive.

context
VMS usage:
type:
access:
mechanism:

context
longword {unsigned)
modify
by reference

Sort/Merge (SOR) Routines
SOR$SPEC_FILE

subsequent routine calls for the same operation, you must pass the context
value supplied by SORT/MERGE.

DESCRIPTION

Call SOR$SPEC_FILE to pass a specification file name or a buffer with
specification text to a sort or merge operation. Through the use of a
specification file, you can selectively omit or include particular records
from the sort or merge operation and specify the reformatting of the
output records. (See the Sort Utility in the VMS Sort I Merge Utility
Manual for a complete description of specification files.)
If you call the SOR$SPEC_FILE routine, you must do so before you call
any other routines. You must pass either the spec_file or spec_buffer
argument, but not both.

Some of the return condition values are U$ed with different severities,
depending on whether SORT/MERGE can recover. Thus, if you want to
check for a specific status, you should use LIB$MATCH_COND.

CONDITION
VALUES
RETURNED

SOR$_ENDDIAGS

Completed with diagnostics.

SOR$_SORT_ON

Sort or merge routine called in incorrect order.

SOR$_SYSERROR

System service error.

SOR-49

Sort/Merge (SOR) Routines
SOR$STAT

SOR$STAT Obtain a Statistic
The SOR$STAT routine returns one statistic about the sort or merge operation
to the user program.

FORMAT

SOR$STAT code ,result [,context]

RETURNS

VMS usage: cond_value
type:
longword {unsigned)
access:
write only
mechanism: by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

code
VMS usage: longword_unsigned
type:
longword {unsigned)
access:
read only
mechanism: by reference
SORT/MERGE statistic code. The code argument is the address of
a longword containing the code that identifies the statistic you want
returned in the result argument. The following values are accepted:

SOR-50

Code

Description

SOR$K_IDENT

Address of ASCII string for version number

SOR$K_REC_INP

Number of records input

SOR$K_REC_SOR

Records sorted

SOR$K_REC_OUT

Records output

SOR$K_LRL_INP

Longest Record Length (LRL) for input

SOR$K_LRL_INT

Internal LRL

SOR$K_LRL_OUT

LRL for output

SOR$K_NODES

Nodes in sort tree

SOR$K_INl_RUNS

Initial dispersion runs

SOR$K_MRG_ORDER

Maximum merge order

SOR$K_MRG_PASSES

Number of merge passes

SOR$K_WRK_ALQ

Work file allocation

Sort/Merge (SOR) Routines
SOR$STAT

Code

Description

SOR$K_MBC_INP

Multiblock count for input

SOR$K_MBC_OUT

Multiblock count for output

SOR$K_MBF_INP

Multibuffer count for input

SOR$K_MBF_OUT

Multibuffer count for output

Note that performance statistics (such as direct I/O, buffered I/O,
and elapsed and CPU times) are not available because user-written
routines may affect those values. However, they are available if you call
LIB$GETJPI.

result
VMS usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
write only
by reference

SORT/MERGE statistic value. The result argument is the address of
a longword into which SORT/MERGE writes the value of the statistic
identified by the code argument.

context
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
modify
by reference

DESCRIPTION

The SOR$STAT routine returns one statistic about the sort or merge
operation to your program. You can call the SOR$STAT routine at any
time while the sort or merge is active.
Some of the following condition values are used with different severities,
depending on whether SORT/MERGE can recover. Thus, if you want to
check for a specific status, you should use LIB$MATCH_COND.

CONDITION
VALUES
RETURNED

SOR$_ENDDIAGS

Completed with diagnostics.

SOR$_MISS_PARAM

A required subroutine argument is missing.

SOR$_NYI

Functionality is not yet implemented.

SOR$_SYSERROR

System service error.

SOR-51

14 VAX Text Processing Utility {VAXTPU) Routines
This chapter describes callable VAX. Text Processing (VAX.TPU) Utility
Routines. It describes the purpose of the VAX.TPU callable routines, the
parameters for the routine call, and the primary status returns. The
parameter in the call syntax represents the object that you pass to a
VAX.TPU routine. Each parameter description lists the data type and
the passing mechanism for the object. The data types are standard VMS
data types. The passing mechanism indicates how the parameter list is
interpreted.

14.1

Introduction to VAXTPU Routines
Callable VAX.TPU Routines make VAX.TPU accessible from within other
VAX. languages and applications. VAX.TPU can be called from a program
written in any VAX. language that generates calls using the VAX. Procedure
Calling and Condition Handling Standard. You can also call VAX.TPU from
VMS utilities, for example, MAIL. Callable VAXTPU lets you perform text
processing functions within your program.
Callable VAX.TPU consists of a set of callable routines that resides in the
VAX.TPU shareable image, TPUSHR.EXE. You access callable VAXTPU by
linking against this shareable image, which includes the callable interface
routine names and constants. As with the DCL-level VAX.TPU interface,
you can use files for input to and output from callable VAXTPU. You
can also write your own routines for processing file input, output, and
messages.
This chapter is written for system programmers who are familiar with the
following:
•

The VAX. Procedure Calling and Condition Handling Standard

•

The VMS Run-Time Library (RTL)

•

The precise manner in which data types are represented on a VAX.
computer

•

The method for calling routines written in a language other than the
one you are using for the main program

The calling program must ensure that parameters passed to a called
procedure, in this case VAXTPU, are of the type and form that the
VAXTPU procedure accepts.
The VAX.TPU routines described in this chapter return condition values
indicating the routine's completion status. When comparing a returned
condition value with a test value, you should use the LIB$MATCH routine
from the Run-Time Library. Do not test the condition value as if it were a
simple integer.

TPU-1

VAX Text Processing Utility (VAXTPU) Routines
14.1 Introduction to VAXTPU Routines

14.1.1

Two Interfaces to Callable VAXTPU
There are two interfaces you can use to access callable VAXTPU: the
simplified callable interface and the full callable interface.
Simplified Callable Interface

The easiest way to use callable VAXTPU is to use the simplified callable
interface. VAXTPU provides two alternative routines in its simplified
callable interface. These routines in turn call additional routines that do
the following:
•

Initialize the editor

•

Provide the editor with the parameters necessary for its operation

•

Control the editing session

•

Perform error handling

When using the simplified callable interface, you can use the TPU$TPU
routine to specify a VMS command line for VAXTPU, or you can call the
TPU$EDIT routine to specify an input file and an output file. TPU$EDIT
builds a command string that is then passed to the TPU$TPU routine.
These two routines are described in detail in Section 14.2.
If your application parses information that is not related to the operation

ofVAXTPU, make sure the application obtains and uses all non-VAXTPU
parse information before the application calls the simplified callable
interface. You must do this because the simplified callable interface
destroys all parse information obtained and stored before the simplified
callable interface was called.
If your application calls the DECwindows version of VAXTPU, the

application can only call TPU$EDIT or TPU$TPU a single time. Also,
the application cannot call Xtinitialize before calling VAXTPU. These
restrictions will be lifted in a future version of VAXTPU and DECwindows.
Full Callable Interface

To use the full callable interface, you have your program access the main·
callable VAXTPU routines directly. These routines do the following:
•

Initialize the editor (TPU$INTIALIZE)

•

Execute VAXTPU procedures (TPU$EXECUTE_INIFILE and
TPU$EXECUTE_COMMAND)

•

Give control to the editor (TPU$CONTROL)

•

Terminate the editing session (TPU$CLEANUP)

When using the full. callable interface, you must provide values for certain
parameters. In some cases, the values you supply are actually addresses
for additional routines. For example, when you call TPU$INITIALIZE,
you must include the address of a routine that specifies initialization
options. Depending on your particular application, you might also have to
write additional routines. For example, you might need to write routines
for performing file operations, handling errors, and otherwise controlling
TPU-2

VAX Text Processing Utility {VAXTPU) Routines
14.1 Introduction to VAXTPU Routines

the editing session. Callable VAXTPU provides utility routines that can
perform some of these tasks for you. These utility routines can do the
following:
•

Parse the VMS command line and build the item list used for
initializing the editor

•

Handle file operations

•

Output error messages

•

Handle conditions

If your application calls the DECwindows version of VAXTPU, the
application can call TPU$INITIALIZE only once. Also, the application
cannot call Xtlnitialize before calling VAXTPU. These restrictions will be
lifted in a future version ofVAXTPU and DECwindows.
Various topics relating to the full callable interface are discussed in the
following sections:
•

Section 14.3 begins by briefly describing the interface. However,
most of this section describes the main callable VAXTPU routines
(TPU$INITIALIZE, TPU$EXECUTE_INIFILE, TPU$CONTROL,
TPU$EXECUTE_COMMAND, and TPU$CLEANUP).

•

Section 14.3.2 discusses additional routines that VAXTPU provides for
use with the full callable interface.

•

Section 14.3.3 defines the requirements for routines that you can write
for use with the full callable interface.

The full callable interface consists of the main callable VAXTPU routines
and the VAXTPU Utility routines.

14.1.2

Shareable Image
Whether you use the simplified callable interface or the full callable
interface, you access callable VAXTPU by linking against the VAXTPU
shareable image, TPUSHR.EXE. This image contains the routine
names and constants available for use by an application. In addition,
TPUSHR.EXE provides the following symbols:
•

TPU$GL_VERSION-The version of the shareable image

•

TPU$GL_UPDATE-The update number of the shareable image

•

TPU$_FACILITY-The VAXTPU facility code

For more information about how to link to the shareable image
TPUSHR.EXE, refer to the VMS System Services Reference Manual.

TPU-3

VAX Text Processing Utility {VAXTPU) Routines
14.1 Introduction to VAXTPU Routines

14.1.3

Passing Parameters to Callable VAXTPU Routines
Parameters are passed to callable VAXTPU routines by reference or by
descriptor. When the parameter is a routine, the parameter is passed by
descriptor as a bound procedure value (BPV) data type.
A bound procedure value is a two-longword entity in which the first
longword contains the address of a procedure entry mask and the
second longword is the environment value (see the following figure). The
environment value is determined in a language-specific manner when the
original bound procedure value is generated. When the bound procedure is
called, the calling program loads the second longword into Rl.
Name Of Your Routine
Environment
ZK-4046-GE

14.1.4

Error Handling
When you use the simplified callable interface, VAXTPU establishes its
own condition handler, TPU$HANDLER, to handle all errors. When you
use the full callable interface, there are two ways to handle errors:
•

You can use VAXTPU's default condition handler, TPU$HANDLER.

•

You can write your own condition handler to process some of the errors
and call TPU$HANDLER to process the rest.

The default condition handler, TPU$HANDLER, is described in
Section 14.5. Information about writing your own condition handler
can be found in the Introduction to VMS System Routines.

14.1.5

Return Values
All VAXTPU condition codes are declared as universal symbols. Therefore,
you automatically have access to these symbols when you link your
program to the shareable image. The condition code values are returned
in RO. Return codes for VAXTPU can be found in the VAX Text Processing
Utility Manual. VAXTPU return codes and their messages are included in
the VMS System Messages and Recovery Procedures Reference Volume.
Additional information about condition codes is provided in the
descriptions of callable VAXTPU routines found in subsequent sections.
This information is provided under the heading CONDITION VALUES
RETURNED and indicates the values that are returned when the default
condition handler is established.

TPU-4

VAX Text Processing Utility (VAXTPU) Routines
14.2 The Simplified Callable Interface

14.2

The Simplified Callable Interface
The VAXTPU simplified callable interface consists of two routines:
TPU$TPU and TPU$EDIT. These entry points to VAXTPU are useful
for the following kinds of applications:
•

Those able to specify all the editing parameters on a single command
line

•

Those that need to specify only an input file and an output file

If your application parses information that is not related to the operation

14.2.1

Examples of the Simplified Interface
The following example calls TPU$EDIT to edit text in the file INFILE.DAT
and writes the result to OUTFILE.DAT. Note that the parameters to
TPU$EDIT must be passed by descriptor.
/*
Sample C program that calls VAXTPU. This program uses TPU$EDIT to
provide the names of the input and output files

*/
#include descrip
int return_status;
static $DESCRIPTOR (input_file, "infile.dat");
static $DESCRIPTOR (output_file, "outfile.dat");
main (argc, argv)
int argc;
char *argv [];
{

/*
Call VAXTPU to edit text in "infile.dat" and write the result
to "outfile.dat". Return the condition code from VAXTPU as the
status of this program.

*/
return_status = TPU$EDIT (&input_file, &output_file);
exit (return_status);

The next example performs the same task as the previous example. This
time, the TPU$TPU entry point is used. TPU$TPU accepts a single
argument which is a command string starting with the verb ''TPU". The
command string can contain all of the qualifiers that are accepted by the
EDIT/TPU command.

TPU-5

VAX Text Processing Utility (VAXTPU) Routines
14.2 The Simplified Callable Interface

I*
Sample C program that calls VAXTPU.
specifies a command string

This program uses TPU$TPU and

*I
#include descrip
int return_status;
static
static
static
static

$DESCRIPTOR
$DESCRIPTOR
$DESCRIPTOR
$DESCRIPTOR

(command prefix, "TPU/NOJOURNAL/NOCOMMAND/OUTPUT=");
(input tile, "infile.dat");
(output_file, "outfile.dat");
(space_desc, " ");

char command line (100];
static $DESCRIPTOR (command_desc, command_line);
main (argc, argv)
int argc;
char *argv[];
{

/*
Build the command line for VAXTPU. Note that the command verb
is "TPU" instead of "EDIT/TPU". The string we construct in the
buff er command line will be
"TPU/NOJOURNAL/NOCOMMAND/OUTPUT=outfile.dat infile.dat"

*I
return status = STR$CONCAT (&command_desc,
&command_pref ix,
&output_file,
&space desc,
&inpu(~file);
if (! return status)
exit (return_status);

I*
Now call VAXTPU to edit the file

*/
return status= TPU$TPU (&command_desc);
exit (return_status);
}

The following section contains detailed information about the routines in
the full VAXTPU callable interface. If you use the simplified interface,
that interface calls these routines for you. If you use the full interface,
your code calls these routines directly.

14.3

The Full Callable Interface
The VAXTPU full callable interface consists of a set of routines that you
can use to perform the following tasks:

TPU-6

•

Specify initialization parameters

•

Control file input/output

•

Specify commands to be executed by the editor

•

Control how conditions are handled

VAX Text Processing Utility {VAXTPU) Routines
14.3 The Full Callable Interface

When you use the simplified callable interface, these operations are
performed automatically. The individual VAXTPU routines that perform
these functions can be called from a user-written program and are
known as VAXTPU's full callable interface. This interface has two sets
of routines: the main VAXTPU callable routines and the VAXTPU Utility
routines. These VAXTPU routines, as well as your own routines that
pass parameters to the VAXTPU routines, are the mechanism that your
application uses to control VAXTPU.
The following sections describe the main callable routines, how parameters
are passed to these routines, the VAXTPU Utility routines, and the
requirements of user-written routines.

14.3.1

Main Callable VAXTPU Utility Routines
The following callable VAXTPU routines are described in this chapter:
•

TPU$INITIALIZE

•

TPU$EXECUTE_INIFILE

•

TPU$CONTROL

•

TPU$EXECUTE_COMMAND

•

TPU$CLEANUP

Note: Before calling any of these routines, you must establish
TPU$HANDLER or provide your own condition handler. See the
routine description of TPU$HANDLER at the end of this chapter
and the "VAX Condition Handling Standard" in the Introduction
to VMS System Routines for information about establishing a
condition handler.

14.3.2

OtherVAXTPU Utility Routines
The full callable interface includes several utility routines for which you
can provide parameters. Depending on your application, you might be able
to use these routines rather than write your own routines. These VAXTPU
Utility routines and their descriptions follow:
•

TPU$CLIPARSE-Parses a command line and builds the item list for
TPU$INITIALIZE

•

TPU$PARSEINFO-Parses a command and builds an item list for
TPU$INITIALIZE

•

TPU$FILEIO-The default file l/O routine

•

TPU$MESSAGE-Writes error messages and strings using the built-in
procedure MESSAGE

•

TPU$HANDLER-The default condition handler

•

TPU$CLOSE_TERMINAL-Closes VAXTPU's channel to the terminal
(and its associated mailbox) for the duration of a CALL_USER routine

TPU-7

VAX Text Processing Utility {VAXTPU) Routines
14.3 The Full Callable Interface

Note that TPU$CLIPARSE and TPU$PARSEINFO destroy the context
maintained by the CLI$ routines for parsing commands.

14.3.3

User-Written Routines
This section defines the requirements for user-written routines. When
these routines are passed to VAXTPU, they must be passed as bound
procedure values. (See Section 14.1.3 for a description of bound procedure
values.) Depending on your application, you might have to write one or all
of the following routines:

14.4

•

Routine for initialization callback-This is a routine that
TPU$1NITIALIZE calls to obtain values for initialization parameters.
The initialization parameters are returned as an item list.

•

Routine for file 1/0-This is a routine that handles file operations.
Instead of writing your own file 1/0 routine, you can use the
TPU$FILEIO utility routine. VAXTPU does not use this routine
for journal file operations or for operations performed by the built-in
procedure SAVE.

•

Routine for condition handling-This is a routine that handles error
conditions. Instead of writing your own condition handler, you can use
the default condition handler, TPU$HANDLER.

•

Routine for the built-in procedure CALL_USER-This is a routine
that is called by the built-in procedure CALL_USER. You can use this
mechanism to cause your program to get control during an editing
session.

Examples of Using VAXTPU Routines
Example 14--1, Example 14--2, Example 14--3, and Example 14--4 use
callable VAXTPU. These examples are included here for illustrative
purposes only; Digital does not assume responsibility for supporting
these examples.

TPU-8

VAX Text Processing Utility {VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-1

Sample VAX BLISS Template for Callable VAXTPU

MODULE file_io_example

(MAIN = top_level,
ADDRESSING_MODE (EXTERNAL

GENERAL))

BEGIN
FORWARD ROUTINE
top_level,
tpu init,

Main routine of this example
Initialize TPU
File I/0 routine for TPU

tpu~)o;

Declare the stream data structure passed to the file I/O routine
MACRO
stream file id
stream rat =
stream rfm =
stream file - nm

O, O, 32, 0 %
6,
7,

8, 0,

8, 0 %
8, 0 % '
0, 0 % '

File ID
Record attributes
Record format
File name descriptor

Declare the routines that would actually do the I/O.
in another module
EXTERNAL ROUTINE
my_io_open,
my io close,
my-io-get record,
my=ioyut=record;

Routine
Routine
Routine
Routine

These must be supplied

to open a file
to close a file
to read a record
to write a record

Declare the VAXTPU routines
EXTERNAL ROUTINE
tpu$fileio,
tpu$handler,
tpu$initialize,
tpu$execute inifile,
tpu$execute-command,
tpu$contro1-;tpu$cleanup;

VAXTPU's internal file I/O routine
VAXTPU's condition handler
Initialize VAXTPU
Execute the initial procedures
Execute a VAXTPU statement
Let user interact with VAXTPU
Have VAXTPU cleanup after itself

Declare the VAXTPU literals
EXTERNAL LITERAL
tpu$k close,
tpu$k-close delete,
tpu$k-open,tpu$k-get,
tpu$kyut,
tpu$k access,
tpu$k-io,
tpu$k-input,
tpu$k=output,

File I/O operation codes

File access codes

(continued on next page)

TPU-9

VAX Text Processing Utility {VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-1 (Cont.)

Sample VAX BLISS Template for Callable VAXTPU

tpu$ calluser,
tpu$-fileio,
tpu$-outputfile,
tpu$-sectionfile,
tpu$-commandfile,
tpu$-filename,
tpu$-journalfile,
tpu$=:options,

! Item list entry codes

tpu$m recover,
tpu$m-journal,
tpu$m-read,
tpu$m-command,
tpu$m-create,
tpu$m-section,
tpu$m-display,
tpu$m=:output,

Mask for values in options bitvector

tpu$m reset terminal,
tpu$m-kill processes,
tpu$m-delete exith,
tpu$m=:last_time,

Masks for cleanup bitvector

tpu$ nof ileaccess,
tpu$-openin,
tpu$-inviocode,
tpu$-failure,
tpu$-closein,
tpu$-closeout,
tpu$-readerr,
tpu$-writeerr,
tpu$=:success;

VAXTPU status codes

ROUTINE top_level
BEGIN
!++
! Main entry point of your program
!--

Your_initialization_routine must be declared as a BPV
{continued on next page)

TPU-10

VAX Text Processing Utility (VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-1 (Cont.)

Sample VAX BLISS Template for Callable VAXTPU

LOCAL
initialize_bpv: VECTOR [2],
status,
cleanup_flags;
First establish the condition handler
ENABLE
tpu$handler ();
Initialize the editing session, passing TPU$INITIALIZE the address of
the bound procedure value which defines the routine which VAXTPU is
to call to return the initialization item list
initialize bpv [0] = tpu_init;
initialize-bpv [1] = 0;
tpu$initialize (initialize_bpv);
Call VAXTPU to execute the contents of the command file, the debug file
! or the TPU$INIT_PROCEDURE from the section file.
tpu$execute_inifile();
! Let VAXTPU take over.

tpu$control();
! Have VAXTPU cleanup after itself

cleanup_flags

tpu$m reset terminal OR
tpu$m=kill_P"rocesses OR
tpu$m delete exith OR
tpu$m=last_time;

Reset the terminal
Delete Subprocesses
Delete the exit handler
Last time calling the editor

tpu$cleanup (cleanup_flags);
RETURN tpu$_success;
END;
ROUTINE tpu_init
BEGIN

(continued on next page)

TPU-11

VAX Text Processing Utility {VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-1 (Cont.)

Sample VAX BLISS Template for Callable VAXTPU

Allocate the storage block needed to pass the file I/O routine as a
bound procedure variable as well as the bitvector for the initialization
options
OWN
file_io_bpv: VECTOR [2, LONG]
INITIAL (TPU_IO, 0),
options;
These macros define the file names passed to VAXTPU
MACRO
out file
com file
sec-file
inp_file

'OUTPUT.TPU' % ,
'TPU$COMMAND' %
'TPU$SECTION' %
'FILE.TPU' % ;

Create the item list to pass to VAXTPU. Each item list entry consists of
two words which specify the size of the item and its code, the address of
the buffer containing the data, and a longword to receive a result (always
zero, since VAXTPU does not return any result values in the item list)

+--------------------------------+
I Item Code
I Item Length
I
+----------------+---------------+
I
Buff er Address
I
+--------------------------------+
I
Return Address (always 0)
I
+--------------------------------+
Remember that the item list is always terminated with a longword containing
a zero
BIND
item_list = UPLIT BYTE (
WORD (4),
WORD (tpu$ options),
LONG (options),
LONG (0),

Options bitvector

WORD
WORD
LONG
LONG

(4),
(tpu$ fileio),
(file=io_bpv),
(0),

File I/0 routine

WORD
WORD
LONG
LONG

(%CHARCOUNT (out_file)),
(tpu$ outputfile),
(UPLIT (%ASCII out_file)),
(0),

Output file

WORD
WORD
LONG
LONG

(%CHARCOUNT (com file)),
(tpu$ commandfile),
(UPLIT (%ASCII com file)),
(0),
-

Command file

(continued on next page)

TPU-12

VAX Text Processing Utility (VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-1 (Cont.)

Sample VAX BLISS Template for Callable VAXTPU

WORD
WORD
LONG
LONG

(%CHARCOUNT (sec file)),
(tpu$ sectionfile),
(UPLIT (%ASCII sec file)),
(0),
-

! Section file

WORD
WORD
LONG
LONG

(%CHARCOUNT (inp file)),
(tpu$_filename),(UPLIT (%ASCII inp_file)),

Input file

(0),

LONG (0));

Terminating longword of 0

Initialize the options bitvector
options = tpu$m_display OR
tpu$m_section OR
tpu$m_create OR

We have a display
We have a se·ction file
Create a new file if one does not
exist
We have a section file
We supplied an output file spec

tpu$m_command OR
tpu$m_output;

Return the item list as the value of this routine for VAXTPU to interpret
RETURN item_list;
END;
ROUTINE tpu_io (p_opcode, stream: REF BLOCK

End of routine tpu_init
, byte], data)

This routine determines how to process a TPU I/O request
BEGIN
LOCAL
status;
Is this one of ours, or do we pass it to TPU's file I/0 routines?
IF ( .. p_opcode NEQ tpu$k_open) AND (.stream [stream_file_id] GTR 511)
THEN
RETURN tpu$fileio (.p_opcode, .stream, .data);
Either we're opening the file, or we know it's one of ours
Call the appropriate routine (not shown in this example)
SELECTONE .. p_opcode OF
SET
[tpu$k_open]:
status= my_io_open (.stream,

.data);

[tpu$k_close, tpu$k_close_delete]:
status= my_io_close (.stream,

.data);

[tpu$k_get]:
status= my_io_get_record (.stream,

.data);

[tpu$k_put]:
status= my_io_put_record (.stream,

.data);

(continued on next page)

TPU-13

VAX Text Processing Utility (VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-1 (Cont.)

Sample VAX BLISS Template for Callable VAXTPU

[OTHERWISE] :
tpu$ _failure;
status
TES;
RETURN .status;
End of routine TPU_IO

END;

End Module file_io_example

END
ELUDOM

Example 14-2 Normal VAXTPU Setup in VAX FORTRAN
C
C

A sample FORTRAN program that calls VAXTPU to act
normally, using the programmable interface.

c
C

IMPLICIT NONE

INTEGER*4
CLEAN OPT
INTEGER*4
STATUS
INTEGER*4
BPV_PARSE(2)
INTEGER*4
LOC PARSE
declare the VAXTPU functions

INTEGER*4
TPU$CONTROL
TPU$CLEANUP
INTEGER*4
TPU$EXECUTE INIFILE
INTEGER*4
INTEGER*4
TPU$INITIALIZE
INTEGER*4
TPU$CLIPARSE
declare a local copy to hold the values of VAXTPU cleanup variables

INTEGER*4
RESET TERMINAL
INTEGER*4
DELETE JOURNAL
INTEGER*4
DELETE BUFFERS,DELETE_WINDOWS
INTEGER*4
DELETE_EXITH,EXECUTE_PROC
INTEGER*4
PRUNE_CACHE,KILL_PROCESSES
INTEGER*4
CLOSE SECTION
declare the VAXTPU functions used as external

C
C
C

100

!options for clean up routine
!return status from VAXTPU routines
!set up a Bound Procedure Value
!a local function call

EXTERNAL
EXTERNAL

TPU$HANDLER
TPU$CLIPARSE

EXTERNAL

TPU$_SUCCESS

EXTERNAL

LOC PARSE

EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL

TPU$M RESET TERMINAL
TPU$M-DELETE JOURNAL
TPU$M-DELETE-BUFFERS,TPU$M DELETE WINDOWS
TPU$M-DELETE-EXITH,TPU$M EXECUTE PROC
TPU$M=PRUNE_CACHE,TPU$M_KILL_PROCESSES

!external error message

!user supplied routine to
call TPUCLIPARSE and setup
declare the VAXTPU cleanup variables as external these are the
external literals that hold the value of the options

CALL LIB$ESTABLISH ( TPU$HANDLER )

!establish the condition handler
(continued on next page)

TPU-14

VAX Text Processing Utility (VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-2 (Cont.)

Normal VAXTPU Setup in VAX FORTRAN

set up the Bound Procedure Value for the call to TPU$INITIALIZE

BPV_PARSE( 1 ) = %LOC( LOC_PARSE
BPV_PARSE( 2 ) = 0
call the VAXTPU initialization routine to do some set up work
STATUS = TPU$INITIALIZE ( BPV_PARSE )

Check the status if it is not a success then signal the error
IF ( STATUS .NE. %LOC ( TPU$_SUCCESS ) ) THEN
CALL LIB$SIGNAL( %VAL( STATUS ) )
GOTO 9999

C
C

ENDIF
execute the TPU$ init files and also a command file if it
was specified in-the command line call to VAXTPU
STATUS = TPU$EXECUTE_INIFILE ( )
IF ( STATUS .NE. %LOC ( TPU$_SUCCESS ) ) THEN !make sure everything is ok
CALL LIB$SIGNAL( %VAL( STATUS ) )
GOTO 9999

ENDIF
invoke the editor as it normally would appear
STATUS = TPU$CONTROL ( )

!call the VAXTPU editor

IF ( STATUS .NE. %LOC ( TPU$_SUCCESS ) ) THEN !make sure everything is ok

CALL LIB$SIGNAL( %VAL( STATUS ) )
GOTO 9999

C
C
C
C

ENDIF
Get the value of the option from the external literals. In FORTRAN you
cannot use external literals directly so you must first get the value
of the literal from its external location. Here we are getting the
values of the options that we want to use in the call to TPU$CLEANUP.

C
C

DELETE JOURNAL
%LOC
TPU$M DELETE JOURNAL
DELETE EXITH
%LOC
TPU$M-DELETE-EXITH )
DELETE BUFFERS
%LOC
TPU$M-DELETE-BUFFERS
DELETE_WINDOWS
%LOC
TPU$M-DELETE-WINDOWS
EXECUTE PROC
%LOC
TPU$M-EXECUTE PROC )
RESET TERMINAL
%LOC
TPU$M-RESET TERMINAL
KILL_PROCESSES
%LOC
TPU$M-KILL PROCESSES )
CLOSE SECTION
%LOC
TPU$M-CLOSE SECTION )
Now that we have the local copies of-the variables we can do the
logical OR to set the multiple options that we need.
CLEAN OPT = DELETE JOURNAL .OR. DELETE EXITH .OR.
1
- DELETE BUFFERS .OR. DELETE WINDOWS .OR. EXECUTE PROC
1
.OR. RESET TERMINAL .OR. KILL PROCESSES .OR. CLOSE SECTION
(continued on next page)

TPU-15

VAX Text Processing Utility (VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-2 (Cont.)
C
C
C

Normal VAXTPU Setup in VAX FORTRAN

do the necessary clean up
TPU$CLEANUP wants the address of the flags as the parameter so
pass the %LOC of CLEAN_OPT which is the address of the variable
STATUS = TPU$CLEANUP ( %LOC ( CLEAN_OPT ) )
IF ( STATUS .NE. %LOC (TPU$_SUCCESS) ) THEN
CALL LIB$SIGNAL( %VAL(STATUS) )
END IF

9999

CALL LIB$REVERT

!go back to normal processing -- handlers

STOP
END

c
c
INTEGER*4
INTEGER*4

FUNCTION LOC PARSE
BPV(2)

!A local Bound Procedure Value

CHARACTER*12
EDIT COMM
!A command line to send to TPU$CLIPARSE
Declare the VAXTPU f~nctions used

C
C

INTEGER*4
TPU$FILEIO
INTEGER*4
TPU$CLIPARSE
Declare this routine as external because it is never called directly and
we need to tell FORTRAN that it is a function and not a variable
EXTERNAL

TPU$FILEIO

BPV(l) = %LOC(TPU$FILEIO)
BPV(2) = 0
C
9999

EDIT_COMM(1:12) = 'TPU TEST.TXT'
parse the command line and build the item list for TPU$INITIALIZE
LOC_PARSE = TPU$CLIPARSE (EDIT_COMM, BPV , 0)
RETURN
END

TPU-16

!set up the BOUND PROCEDURE VALUE

VAX Text Processing Utility {VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-3

Building a Callback Item List with VAX FORTRAN

PROGRAM

TEST TPU

c
IMPLICIT NONE

c
c
c

Define the expected VAXTPU return statuses
EXTERNAL
EXTERNAL
EXTERNAL

c
c
c

TPU$ SUCCESS
TPU$-QUITTING
TPU$=EXITING

Declare the VAXTPU routines and symbols used
EXTERNAL
EXTERNAL
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4

c
c
c

TPU$M DELETE CONTEXT
TPU$HANDLER TPU$M DELETE CONTEXT
TPU$INITIALIZE
TPU$EXECUTE INIFILE
TPU$CONTROLTPU$CLEANUP

Use LIB$MATCH_COND to compare condition codes
INTEGER*4

c
c
c

LIB$MATCH_COND

Declare the external callback routine
EXTERNAL
INTEGER*4

TPU STARTUP
TPU STARTUP

the VAXTPU set-up function

INTEGER*4

BPV(2)

Set up a bound procedure value

c
C

Declare the functions used for working with the condition handler

c
INTEGER*4
INTEGER*4

LIB$ESTABLISH
LIB$REVERT

c
C

Local Flags and Indices

c
INTEGER*4
INTEGER*4
INTEGER*4

CLEANUP FLAG
RET STATUS
MATCH STATUS

flag(s) for VAXTPU cleanup

c
C

Initializations

c
RET_STATUS
CLEANUP FLAG

0
%LOC(TPU$M_DELETE CONTEXT)

c
C

Establish the default VAXTPU condition handler

c
CALL LIB$ESTABLISH(%REF(TPU$HANDLER))

c
C

Set up the bound procedure value for the initialization callback

c
BPV(l)
BPV(2)

%LOC (TPU_STARTUP)
0

(continued on next page)

TPU-17

VAX Text Processing Utility (VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-3 {Cont.)

Building a Callback Item List with VAX FORTRAN

c
C

Call the VAXTPU procedure for initialization

c
RET_STATUS = TPU$INITIALIZE(BPV)
IF (RET STATUS .NE. %LOC(TPU$ SUCCESS)) THEN
CALL LIB$SIGNAL (%VAL(RET_STATUS))
END IF

c
C

Execute the VAXTPU initialization file

c
RET_STATUS = TPU$EXECUTE_INIFILE()
IF (RET STATUS .NE. %LOC(TPU$ SUCCESS)) THEN
CALL LIB$SIGNAL (%VAL(RET_STATUS))
END IF

c
C

Pass control to VAXTPU

c
RET STATUS = TPU$CONTROL()

c
C
C
C

Test for valid exit condition codes. You must use LIB$MATCH_COND
because the severity of TPU$_QUITTING can be set by the TPU
application

c
MATCH STATUS= LIB$MATCH_COND (RET_STATUS, %LOC (TPU$ QUITTING),
1
%LOC (TPU$=EXITING))
IF (MATCH STATUS .EQ. 0) THEN
CALL LIB$SIG~AL (%VAL(RET_STATUS))
END IF

c
C

Clean up after processing

c
RET_STATUS = TPU$CLEANUP(%REF(CLEANUP_FLAG))
IF (RET STATUS .NE. %LOC(TPU$ SUCCESS)) THEN
CALL LIB$SIGNAL (%VAL(RET_STATUS))
END IF

c
C

Set the condition handler back to the default

c
RET STATUS = LIB$REVERT()
END
INTEGER*4 FUNCTION TPU STARTUP
IMPLICIT NONE
INTEGER*4
CHARACTER*44

OPTION MASK
SECTION NAME

temporary variable for VAXTPU
temporary variable for VAXTPU
(continued on next page)

TPU-18

VAX Text Processing Utility (VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-3 (Cont.)

Building a Callback Item List with VAX FORTRAN

c
C

External VAXTPU routines and symbols

c
EX Tl!: RNAL
EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL
INTEGER*4

TPU$K OPTIONS
TPU$M-READ
TPU$M-SECTION
TPU$M-DISPLAY
TPU$K-SECTIONFILE
TPU$K-FILEIO
TPU$FILEIO
TPU$FILEIO

c
C

The bound procedure value used for setting up the file I/O routine

c
INTEGER*4

BPV(2)

c
C

Define the structure of the item list defined for the callback

c
STRUCTURE /CALLBACK/
INTEGER*2
BUFFER LENGTH
INTEGER*2
ITEM CODE
INTEGER*4
BUFFER ADDRESS
INTEGER*4
RETURN ADDRESS
END STRUCTURE

c
C

There are a total of four items in the item list

c
RECORD /CALLBACK/ CALLBACK (4)

c
C

Make sure it is not optimized!

c
VOLATILE /CALLBACK/

c
C

Define the options we want to use in the VAXTPU session

c
OPTION MASK= %LOC(TPU$M SECTION)
1
- .OR. %LOC(TPU$M_DISPLAY)

.OR. %LOC(TPU$M_READ)

c
C

Define the name of the initialization section file

c
SECTION_NAME = 'TPU$SECTION'

c
C

Set up the required I/O routine.

Use the VAXTPU default.

BPV(l) = %LOC(TPU$FILEIO)
BPV(2) = 0

c
C

Build the callback item list

c
C

Set up the edit session options

c
CALLBACK(l) .ITEM_CODE = %LOC(TPU$K_OPTIONS)
CALLBACK(l) .BUFFER_ADDRESS = %LOC(OPTION_MASK)
CALLBACK(l) .BUFFER_LENGTH = 4
CALLBACK(l) .RETURN_ADDRESS = 0
(continued on next page)

TPU-19

VAX Text Processing Utility (VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-3 (Cont.)

Building a Callback Item List with VAX FORTRAN

c
C

Identify the section file to be used

c
CALLBACK{2) .ITEM_CODE = %LOC{TPU$K_SECTIONFILE)
CALLBACK{2) .BUFFER_ADDRESS = %LOC{SECTION_NAME)
CALLBACK{2) .BUFFER_LENGTH = LEN{SECTION_NAME)
CALLBACK{2) .RETURN_ADDRESS = 0

c
C

Set up the I/O handler

c
CALLBACK{3) .ITEM_CODE = %LOC{TPU$K_FILEIO)
CALLBACK{3) .BUFFER_ADDRESS = %LOC{BPV)
CALLBACK{3) .BUFFER_LENGTH = 4
CALLBACK{3) .RETURN_ADDRESS = 0

c
C

End the item list with zeros to indicate we are finished

c
CALLBACK{4) .ITEM_CODE = 0
CALLBACK{4) .BUFFER_ADDRESS = 0
CALLBACK{4) .BUFFER_LENGTH = 0
CALLBACK{4) .RETURN_ADDRESS = 0

c
C

Return the address of the item list

c
TPU STARTUP = %LOC{CALLBACK)
RETURN
END

Example 14-4

Specifying a User-Written File 1/0 Routine in VAX C

I*
Simple example of a C program to invoke TPU. This program provides its
own FILEIO routine instead of using the one provided by TPU.

*I
#include descrip
#include stdio

I* data structures needed */
struct bpv_arg

/* bound procedure value */

{

int *routine add
int env
-

/* pointer to routine */
I* environment pointer */

} ;

struct item_list_entry

/* item list data structure */

{

short int buff er length;
short int item code;
int *buff er add;
int *return=len_add;

I* buffer length */
/* item code */
/* buff er address */
I* return address *I

} ;

(continued on next page)

TPU-20

VAX Text Processing Utility (VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-4 (Cont.) Specifying a User-Written File 1/0 Routine in VAX C
struct stream_type
{

int ident;
short int alloc;
short int flags;
short int length;
short int stuff;
int nam_add;

/*
/*
/*
/*

stream id */
file size */
file record attributes/format */
resultant file name length */
I* file name descriptor class & type */
/* file name descriptor text pointer */

} ;

globalvalue tpu$ success;
globalvalue tpu$=quitting;

/* TPU Success code */
/* Exit code defined by TPU */

globalvalue
/* Cleanup codes defined by TPU */
tpu$m delete journal, tpu$m delete exith,
tpu$m-delete-buffers, tpu$m-delete-windows, tpu$m delete cache,
tpu$m=:yrune_cache, tpu$m_execute_file, tpu$m_execute_proc,
tpu$m_delete_context, tpu$m_reset_terminal, tpu$m_kill_processes,
tpu$m close section, tpu$m delete others, tpu$m last time;
globalvalue
- /* Item codes for item list entries */
tpu$k fileio, tpu$k options, tpu$k sectionfile,
tpu$k-commandfile ;globalvalue
/* Option codes for option item */
tpu$m_display, tpu$m_section, tpu$m_command, tpu$m_create ;
globalvalue
/* Possible item codes in item list */
tpu$k access, tpu$k filename, tpu$k defaultfile,
tpu$k-relatedfile, tpu$k record attr, tpu$k maximize ver,
tpu$k=flush, tpu$k_f ilesize;
globalvalue
/* Possible access types for tpu$k_access */
tpu$k_io, tpu$k_input, tpu$k_output;
globalvalue
/* RMS File Not Found message code */
rms$_fnf;
globalvalue
/* FILEIO routine functions */
tpu$k open, tpu$k close, tpu$k_close delete,
tpu$k=get, tpu$k_'Put;
int lib$establish ();
/* RTL routine to establish an event handler */
int tpu$cleanup ();
/* TPU routine to free resources used */
int tpu$control ();
I* TPU routine to invoke the editor */
int tpu$execute inifile ();
I* TPU routine to execute initialization code */
int tpu$handler-();
/* TPU signal handling routine */
int tpu$initialize ();
I* TPU routine to initialize the editor */

I*
This function opens a file for either read or write access, based upon
the itemlist passed as the data parameter. Note that a full implementation
of the file open routine would have to handle the default file, related
file, record attribute, maximize version, flush and file size item code
properly.

*I
open_file (data, stream)
int *data;
struct stream_type *stream;
struct item_list_entry *item;
char *access;
/* File access type */
char filename[256];
/*Max file specification size*/

(continued on next page)

TPU-21

VAX Text Processing Utility (VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-4 (Cont.)

Specifying a User-Written File 1/0 Routine in VAX C

FILE *fopen () ;

I* Process the item list */
item = data;
while (item->item_code != 0 && item->buffer_length != 0)
{

if (item->item_code == tpu$k_access)
{

if (item->buffer add == tpu$k io) access = "r+";
else if (item->buffer add== tpu$k input) access = "r";
else if (item->buffer=add == tpu$k=output) access = "w";
}

else if (item->item_code == tpu$k_filename)
{

strncpy (filename, item->buffer add, item->buffer length);
filename [item->buffer length] ~ O;
lib$scopy_r_dx (&item->buffer_length, item->buffer_add,
&stream->length);
tpu$k defaultfile)
I* Add code to handle default file */
/* spec here
. */
tpu$k relatedf ile)
(item->item_code
I* Add code to handle related
*/
/* file spec here
*/
(item->item_code
tpu$k record attr)
!*Add code to handle record
*/
/* attributes for creating files
*/
(item->item_code
tpu$k maximize ver)
I* Add code to maximize version
*/
/* number with existing file here
*/
(item->item_code
tpu$k flush)
I* Add code to cause each record
*/
/* to be flushed to disk as written */
(item->item_code
tpu$k f ilesize)
I* Add code to handle specification */
/* of initial file allocation here */
/* get next item */

else if (item->item_code
{
}

else if
{
}

++item;
}

stream->ident
fopen(filename,access);
if (stream->ident != 0)
return tpu$_success;
else
return rms$_fnf;
}

I*
This procedure closes a file

*I
close_file (data,stream)
struct stream_type *stream;
close(stream->ident);
return tpu$_success;

(continued on next page)

TPU-22

VAX Text Processing Utility (VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-4 {Cont.)

Specifying a User-Written File 1/0 Routine in VAX C

I*
This procedure reads a line from a file

*I
read_line(data,stream)
struct dsc$descriptor *data;
struct stream_type *stream;
char textline[984];
int len;

I* max line size for TPU records */

globalvalue rms$_eof;

/* RMS End-Of-File code */

if (fgets(textline,984,stream->ident) ==NULL)
return rms$_eof;
else
{

len

strlen(textline);

i f (len > 0)

len = len - 1;
return lib$scopy_r_dx (&len, textline, data);
}

}

/*
This procedure writes a line to a file

*I
write_line(data,stream)
struct dsc$descriptor *data;
struct stream_type *stream;
char textline[984];

/* max line size for TPU records */

strncpy (textline, data->dsc$a pointer, data->dsc$w_length);
textline [data->dsc$w length] ~ O;
fputs(textline,stream=>ident);
fputs("\n",stream->ident);
return tpu$_success;
}

I*
This procedure will handle I/O for TPU
*/
fileio(code,stream,data)
int *code;
int *stream;
int *data;
int status;
/* Dispatch based on code type. Note that a full implementation of the
*/
I* file I/O routines would have to handle the close and delete code properly */
/* instead of simply closing the file
*/
if (*code == tpu$k_open)
status= open file (data,stream);
else if (*code ==-tpu$k close)
status= close file-(data,stream);
else if (*code == tpu$k close delete)
status= close_file-(data~stream);

/* Initial access to file */

I* End access to file */
/* Treat same as close */

(continued on next page)

TPU-23

VAX Text Processing Utility (VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-4 (Cont.) Specifying a User-Written File 1/0 Routine in VAX C
else if (*code == tpu$k get)
status= read line (data,stream);
else if (*code ==-tpu$k put)
status
write_line-(data,stream);
else

/* Read a record from a file */
/* Write a record to a file */

{
/* Who knows what we got? */
status
tpu$ success;
printf ("Bad FILEIO I/O function requested");
}

return status;
}

I*
This procedure formats the initialization item list and returns it as
its return value.

*I
callrout ()
{

static struct bpv arg add block =
{ fileio, 0 }-;
/* BPV for fileio routine */
int options ;
char *section name = "TPUSECTION";
static struct-item list entry arg[)
{/* length code
buffer add return add */
{ 4,tpu$k fileio,
O,
0 }'
{ 4,tpu$k-options,
0,
0 }'
{ O,tpu$k-sectionfile,O,
0 }'
{ 0,0,
0,
0 }
};

I* Setup file I/O routine item entry */
arg[O] .buffer_add = &add_block;
/* Setup options item entry. Leave journaling off. */
options = tpu$m display I tpu$m section;
arg[l] .buffer_add = &options; /* Setup section file name */
arg[2) .buffer length= strlen(section name);
arg[2] .buffer=add
section_name;
return arg;

/*
Main program.

Initializes TPU, then passes control to it.

*/
main()
{

int return_status ;
int cleanup_options;
struct bpv_arg add_block;

I* Establish as condition handler the normal VAXTPU handler */
lib$establish(tpu$handler);

I* Setup a BPV to point to the callback routine */
add block.routine add = callrout ;
add=block.env =

(continued on next page)

TPU-24

VAX Text Processing Utility (VAXTPU) Routines
14.4 Examples of Using VAXTPU Routines

Example 14-4 (Cont.) Specifying a User-Written File 1/0 Routine in VAX C
/* Do the initialize of VAXTPU */
return status= tpu$initialize(&add block);
if (!return_status)
exit(return_status);

I* Have TPU execute the procedure TPU$INIT PROCEDURE from the section file */
/* and then compile and execute the code from the command file */
return_status = tpu$execute_inifile();
if (!return_status)
exit (return_status);

/* Turn control over to VAXTPU */
return_status = tpu$control ();
if (!return_status)
exit(return_status);

/* Now clean up. */
cleanup_options = tpu$m last time I tpu$m delete context;
return_status = tpu$cleanup (&cleanup_options); exit (return_status);
printf("Experiment complete");

14.5

VAXTPU Routines
The following pages describe the individual VAXTPU routines.

TPU-25

VAX Text Processing Utility {VAXTPU) Routines

TPU$CLEANUP

Free System Resources Used
During VAXTPU Session

The TPU$CLEANUP routine cleans up internal data structures, frees memory,
and restores terminals to their initial state.
This is the final routine called in each interaction with VAXTPU.

flags

FORMAT

TPU$CLEANUP

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Longword condition value. Most utility routines return a condition value
in RO. The condition value that this routine can return is listed under
CONDITION VALUE RETURNED.

ARGUMENT

flags
VMS usage: mask_longword
type:
longword (unsigned)
access:
read only
mechanism: by reference
Flags (or mask) defining the cleanup options. The flags argument is the
address of a longword bit mask defining the cleanup options or the address
of a 32-bit mask defining the cleanup options. This mask is the logical
OR of the flag bits you want to set. TPU$V ... indicates a bit item and
TPU$M ... indicates a mask. Following are the various cleanup options.
Symbol1

Function

TPU$M_DELETE_JOURNAL

Closes and deletes the journal file if it is open.

TPU$M_DELETE_EXITH

Deletes VAXTPU's exit handler.

TPU$M_DELETE_BUFFERS

Deletes all text buffers. If this is not the last time
you are calling VAXTPU, then all variables referring
to these data structures are reset, as if by the builtin procedure DELETE. If a buffer is deleted, then
all ranges and markers within that buffer, and any
subprocesses using that buffer, are also deleted.

TPU$M_DELETE_WINDOWS

Deletes all windows. If this is not the last time you
are calling VAXTPU, then all variables referring to
these data structures are reset, as if by the built-in
procedure DELETE.

1The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific
field in which the bit is set. TPU$V_ is a bit number.

TPU-26

VAX Text Processing Utility (VAXTPU) Routines

TPU$CLEANUP
Symbol1

Function

TPU$M_DELETE_CACHE

Deletes the virtual file manager's data structures
and caches. If this deletion is requested, then all
buffers are also deleted. If the cache is deleted,
the initialization routine has to reinitialize the virtual
file manager the next time it is called.

TPU$M_PRUNE_CACHE

Frees up any virtual file manager caches that have
no pages allocated to buffers. This frees up any
caches that may have been created during the
session but are no longer needed.

TPU$M_EXECUTE_FILE

Reexecutes the command file if TPU$EXECUTE_
INIFILE is called again. You must set this bit if you
plan to specify a new file name for the command
file. This option is used in conjunction with the
option bit passed to TPU$1NITIALIZE indicating the
presence of the /COMMAND qualifier.

TPU$M_EXECUTE_PROC

Looks up TPU$1NIT_PROCEDURE and executes it
the next time TPU$EXECUTE_INIFILE is called.

TPU$M_DELETE_CONTEXT

Deletes the entire context of VAXTPU. If this option
is specified, then all other options are implied,
except for executing the initialization file and
initialization procedure.

TPU$M_RESET_TERMINAL

Resets the terminal to the state it was in upon
entry to VAXTPU. The terminal mailbox and all
windows are deleted. If the terminal is reset, then
it is reinitialized the next time TPU$1NITIALIZE is
called.

TPU$M_KILL_PROCESSES

Deletes all subprocesses created during the
session.

TPU$M_CLOSE_SECTION 2

Closes the section file and releases the associated
memory. All buffers, windows, and processes
are deleted. The cache is purged and the flags
are set for reexecution of the initialization file
and initialization procedure. If the section is
closed and if the option bit indicates the presence
of the SECTION qualifier, then the next call to
TPU$1NITIALIZE attempts a new restore operation.

TPU$M_DELETE_OTHERS

Deletes all miscellaneous preallocated data
structures. Memory for these data structures
is reallocated the next time TPU$1NITIALIZE is
called.

TPU$M_LAST_TIME

This bit should be set only when you are calling
VAXTPU for the last time. Note that if you set
this bit and then recall VAXTPU, the results are
unpredictable.

1 The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific
field in which the bit is set. TPU$V_ is a bit number.

2 Using the simplified callable interface does not set TPU$_CLOSE_SECTION. This feature
allows you to make multiple calls to TPU$TPU without. requiring you to open and close the
section file on each call.

TPU-27

VAX Text Processing Utility (VAXTPU) Routines

TPU$CLEANUP

DESCRIPTION

The cleanup routine is the final routine called in each interaction with
VAXTPU. It tells VAXTPU to clean up its internal data structures and
prepare for additional invocations. You can control what is reset by this
routine by setting or clearing the flags described previously.
When you finish with VAXTPU, call this routine to free the memory and
restore the characteristics of the terminal to their original settings.
If you intend to exit after calling TPU$CLEANUP, do not delete the data
structures; VMS does this automatically. Allowing VMS to delete the
structures improves the performance of your program.

Notes
1

CONDITION
VALUE
RETURNED

TPU-28

When you use the simplified interface, VAXTPU automatically sets the
following flags:
•

TPU$V_RESET_TERMINAL

•

TPU$V_DELETE_BUFFERS

•

TPU$V_DELETE_JOURNAL

•

TPU$V_DELETE_WINDOWS

•

TPU$V_DELETE_EXITH

•

TPU$V_EXECUTE_PROC

•

TPU$V_EXECUTE_FILE

•

TPU$V_PRUNE_CACHE

•

TPU$V_KILL_PROCESSES

If this routine does not return a success status, no other calls to the
editor should be made.

TPU$_SUCCESS

Normal successful completion.

VAX Text Processing Utility {VAXTPU) Routines
TPU$CLIPARSE

TPU$CLIPARSE

Parse a Command Line

The TPU$CLIPARSE routine parses a command line and builds the item list
for TPU$1NITIALIZE.
It calls CL1$DCL_PARSE to establish a command table and a command
to parse. It then calls TPU$PARSEINFO to build an item list for
TPU$1NITIALIZE.
If your application parses information that is not related to the operation of
VAXTPU, make sure the application obtains and uses all non-VAXTPU parse
information before the application calls TPU$CLIPARSE. You must do this
because TPU$CLIPARSE destroys all parse information obtained and stored
before TPU$CLIPARSE was called.

FORMAT

TPU$CLIPARSE

RETURNS

VMS usage:
type:
access:
mechanism:

string, fileio, ca/Luser

item_list
longword (unsigned)
read only
by reference

This routine returns the address of an item list.

ARGUMENTS

string
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Command line. The string argument is the address of a descriptor of a
VAXTPU command.

fileio
vector_longword_unsigned
bound procedure value
read only
by descriptor
File I/O routine. The :6.leio argument is the address of a descriptor of a

VMS usage:
type:
access:
mechanism:

file I/O routine.

call_ user
VMS usage:
type:
access:
mechanism:

vector_longword_unsigned
bound procedure value
read only
by descriptor

Call-user routine. The call_user argument is the address of a descriptor
of a call-user routine.

TPU-29

VAX Text Processing Utility {VAXTPU) Routines
TPU$CLOSE_TERMINAL

TPU$CLOSE_TERMINAL

Close Channel to Terminal

The TPU$CLOSE_TERMINAL routine closes VAXTPU's channel to the
terminal.

FORMAT

TPU$CLOSE_TERMINAL

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. The condition value that this routine can return is listed under
CONDITION VALUE RETURNED.

ARGUMENTS

None.

DESCRIPTION

This routine is used with the built-in procedure CALL_USER and its
associated call-user routine to control VAXTPU's access to the terminal.
When a call-user routine invokes TPU$CLOSE_TERMINAL, VAXTPU
closes its channel to the terminal and the channel of VAXTPU's associated
mailbox.
When the call-user routine returns control to it, VAXTPU automatically
reopens a channel to the terminal and redisplays the visible windows.
A call-user routine can use TPU$CLOSE_TERMINAL at any point in the
program and as many times as necessary. If the terminal is already closed
to VAXTPU when TPU$CLOSE_TERMINAL is used, the call is ignored.

CONDITION
VALUE
RETURNED

TPU-30

TPU$_SUCCESS

Normal successful completion.

VAX Text Processing Utility (VAXTPU) Routines
TPU$CONTROL

TPU$CONTROL

Pass Control to VAXTPU

The TPU$CONTROL routine is the main processing routine of the VAXTPU
editor. It is responsible for reading the text and commands, and executing
them. When you call this routine (after calling TPU$1NITIALIZE), control is
turned over to VAXTPU.

FORMAT

TPU$CONTROL

RETURNS

VMS usage:
type:
access:
mechanism:

[integer]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

integer
VMS usage:
type:
access:
mechanism:

integer
longword (unsigned)
read only
by reference

Prevents VAXTPU from displaying the message "Editing session is not
being journaled" when the calling program gives control to VAXTPU.
Specify a true (odd) integer to preserve compatibility in future releases. If
you omit the parameter, VAXTPU displays the message if journaling is not
enabled.

DESCRIPTION

This routine controls the editing session. It is responsible for reading the
text and commands and for executing them. Windows on the screen are
updated to reflect the edits made.

Note: Control is returned to your program only if an error occurs or
after you enter either the built-in procedure QUIT or the built-in
procedure EXIT.

CONDITION
VALUES
RETURNED

TPU$_EXITING

A result of EXIT (when the default condition handler is
established).

TPU$_QUITTING

A result of QUIT (when the default condition handler
is established).

TPU$_RECOVERFAIL

A recovery operation was terminated abnormally.

TPU-31

VAX Text Processing Utility (VAXTPU) Routines
TPU$EDIT

TPU$EDIT

Edit a File
The TPU$EDIT routine builds a command string from its parameters and
passes it to the TPU$TPU routine.
TPU$EDIT is another entry point to VAXTPU's simplified callable interface.

FORMAT

TPU$EDIT

RETURNS

VMS usage:
type:
access:
mechanism:

input, output

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

input
char_string
character string
read only
by descriptor
Input file name. The input argument is the address of a descriptor of a
file specification.
VMS usage:
type:
access:
mechanism:

output
char_string
character string
read only
by descriptor
Output file name. The output argument is the address of a descriptor
of an output file specification. It is used with the /OUTPUT command
qualifier.

VMS usage:
type:
access:
mechanism:

DESCRIPTION

This routine builds a command string and passes it to TPU$TPU. If the
length of the output string is greater than 0, you can include it in the
command line using the /OUTPUT qualifier, as follows:
TPU [/OUTPUT= output] input

If your application parses information that is not related to the operation

ofVAXTPU, make sure the application obtains and uses all non-VAXTPU
parse information before the application calls TPU$EDIT. Your application
must do this because TPU$EDIT destroys all parse information obtained
and stored before TPU$EDIT is called.

TPU-32

VAX Text Processing Utility (VAXTPU) Routines
TPU$EDIT

CONDITION
VALUES
RETURNED

This routine returns any value returned by TPU$TPU.

TPU-33

VAX Text Processing Utility (VAXTPU) Routines

TPU$EXECUTE_COMMAND

Execute One or More
VAXTPU Statements

The TPU$EXECUTE_COMMAND routine allows your program to execute
VAXTPU statements.

FORMAT

TPU$EXECUTE_COMMAND

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

string

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

string
VMS usage: char_string
type:
character string
access:
read only
mechanism: by value
VAXTPU statement. The string argument is the address of a descriptor of
a character string denoting one or more VAXTPU statements.

DESCRIPTION

CONDITION
VALUES
RETURNED

TPU-34

This routine performs the same function as the built-in procedure
EXECUTE described in the VAX Text Processing Utility Manual.

TPU$_SUCCESS

Normal successful completion.

TPU$_EXITING

EXIT built-in procedure was invoked.

TPU$_QUITTING

QUIT built-in procedure was invoked.

TPU$_EXECUTEFAIL

Execution aborted. This could be because of
execution errors or compilation errors.

VAX Text Processing Utility (VAXTPU) Routines
TPU$EXECUTE_INIFILE

TPU$EXECUTE_INIFILE

Execute Initialization Files

The TPU$EXECUTE_INIFILE routine allows you to execute a user-written
initialization file.
This routine must be executed after the editor is initialized and before any
other commands are processed.

FORMAT

TPU$EXECUTE_INIFILE

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

None.

DESCRIPTION

Calling the TPU$EXECUTE_INIFILE routine causes VAXTPU to perform
the following steps:
1

The command file is read into a buffer. The default is
TPU$COMMAND.TPU. If you specified a file on the command line
that cannot be found, an error message is displayed and the routine is
aborted.

If you specified the /DEBUG qualifier on the command
line, the DEBUG file is read into a buffer. The default is
SYS$SHARE:TPU$DEBUG.TPU.

The DEBUG file is compiled and executed (if available).

TPU$INIT_PROCEDURE is executed (if available).

The Command buffer is compiled and executed (if available).

TPU$INIT_POSTPROCEDURE is executed (if available).

Note: If you call this routine after calling TPU$CLEANUP, you must set
the flags TPU$_EXECUTEPROCEDURE and TPU$_EXECUTEFILE.
Otherwise, the initialization file does not execute.

TPU-35

VAX Text Processing Utility {VAXTPU) Routines
TPU$EXECUTE_INIFILE

CONDITION
VALUES
RETURNED

TPU-36

TPU$_SUCCESS

Normal successful completion.

TPU$_EXITING

A result of EXIT. If the default condition handler is
being used, the session is terminated.

TPU$_QUITTING

A result of QUIT. If the default condition handler is
being used, the session is terminated.

TPU$_COMPILEFAIL

The compilation of the initialization file was
unsuccessful.

TPU$_EXECUTEFAIL

The execution of the statements in the initialization file
was unsuccessful.

TPU$_FAILURE

General code for all other errors.

VAX Text Processing Utility {VAXTPU) Routines
TPU$FILEIO

TPU$FILEIO

Perform File Operations
The TPU$FILEIO routine handles all VAXTPU file operations. Your own file
110 routine can call this routine to perform some operations for it. However,
the routine that opens the file must perform all operations for that file. For
example, if TPU$FILEIO opens the file, it must also close it.

FORMAT

TPU$FILEIO

RETURNS

VMS usage:
type:
access:
mechanism:

code, stream, data

cond_value
longword (unsigned)
write only
by val"!e

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

code
longword_unsigned
longword (unsigned)
read only
by reference
Item code specifying a VAXTPU function. The code argument is the
address of a longword containing an item code from VAXTPU specifying a
function to perform. Following are the item codes that you can specify in
the file 1/0 routine:
VMS usage:
type:
access:
mechanism:

•

TPU$K_OPEN-This item code specifies that the data parameter is
the address of an item list. This item list contains the information
necessary to open the file. The stream parameter should be filled in
with a unique identifying value to be used for all future references to
this file. The resultant file name should also be copied with a dynamic
string descriptor.

•

TPU$K_CLOSE-The file specified by the stream argument is to be
closed. All memory being used by its structures can be released.

•

TPU$K_CLOSE_DELETE~The file specified by the stream argument
is to be closed and deleted. All memory being used by its structures
can be released.

•

TPU$K_GET-The data parameter is the address of a dynamic string
descriptor to be filled with the next record from the file specified by the
stream argument. The routine should use the routines provided by
the VMS Run-Time Library to copy text into this descriptor. VAXTPU
frees the memory allocated for the data read when the file 1/0 routine
indicates that the end of the file has been reached.

•

TPU$K_PUT-The data parameter is the address of a descriptor for
the data to be written to the file specified by the stream argument.
TPU-37

VAX Text Processing Utility (VAXTPU) Routines
TPU$FILEIO

stream
VMS usage: unspecified
type:
longword (unsigned)
access:
modify
mechanism: by reference
File description. The stream argument is the address of a data structure
consisting of four longwords. This data structure is used to describe the
file to be manipulated.

This data structure is used to refer to all files. It is written to when
an open file request is made. All other requests use information in this
structure to determine which file is being referenced.
The following figure shows the stream data structure:

File Identifier
RFM
Class

Allocation

Type

Length

Address of Name
ZK-4045-GE

The first longword is used to hold a unique identifier for each file. The
user-written file 1/0 routine is restricted to values between 0 and 511.
Thus, you can have up to 512 files open simultaneously.
The second longword is divided into three fields. The low word is used to
store the allocation quantity, that is, the number of blocks allocated to this
file from the FAB CFAB$L_ALQ). This value is used later to calculate the
output file size for preallocation of disk space. The low-order byte of the
second word is used to store the record attribute byte (FAB$B_RAT) when
an existing file is opened. The high-order byte is used to store the record
format byte CFAB$B_RFM) when an existing file is opened. The values in
the low word and the low-order and high-order bytes of the second word
are used for creating the output file in the same format as the input file.
These three fields are to be filled in by the routine opening the file.
The last two longwords are used as a descriptor for the resultant or the
expanded file name. This name is used later when VAXTPU processes
EXIT commands. This descriptor is to be filled in with the file name
after an open operation. It should be allocated with either the routine
LIB$SCOPY_R_DX or the routine LIB$SCOPY_DX from the Run-Time
Library. This space is freed by VAXTPU when it is no longer needed.

data
VMS usage: item_list_3
type:
longword (unsigned)
access:
modify
mechanism: by reference
Stream data. The data argument is either the address of an item list or
the address of a descriptor.

TPU-38

VAX Text Processing Utility (VAXTPU) Routines
TPU$FILEIO

Note: The meaning of this parameter depends on the item code specified
in the code field.
When the TPU$K_OPEN item code is issued, the data parameter is the
address of an item list containing information about the open request.
The following VAXTPU item codes are available for specifying information
about the open request:
•

TPU$K_ACCESS item code lets you specify one of three item codes in
the buffer address field, as follows:
-

TPU$K_IO

TPU$K_INPUT

TPU$K_OUTPUT

•

TPU$K_FILENAME item code is used for specifying the address of a
string to use as the name of the file you are opening. The length field
contains the length of this string, and the address field contains the
address.

•

TPU$K_DEFAULTFILE item code is used for assigning a default file
name to the file being opened. The buffer length field contains the
length, and the buffer address field contains the address of the default
file name.

•

TPU$K_RELATEDFILE item code is used for specifying a related file
name for the file being opened. The buffer length field contains the
length, and the buffer address field contains the address of a string to
use as the related file name.

•

TPU$K_RECORD_ATTR item code specifies that the buffer address
field contains the value for the record attribute byte in the FAB
(FAB$B_RAT) used for file creation.

•

TPU$K_RECORD_FORM item code specifies that the buffer address
field contains the value for the record format byte in the FAB CFAB$B_
RFM) used for file creation.

•

TPU$K_MAXIMIZE_VER item code specifies that the version number
of the output file should be one higher than the highest existing
version number.

•

TPU$K_FLUSH item code specifies that the file should have every
record flushed after it is written.

•

TPU$K_FILESIZE item code is used for specifying a value to be used
as the allocation quantity when creating the file. The value is specified
in the buffer address field.

TPU-39

VAX Text Processing Utility {VAXTPU) Routines
TPU$FILEIO

DESCRIPTION

By default, TPU$FILEIO creates variable-length files with carriage-return
record attributes (fab$b_rfm = var, fab$b_rat = er). If you pass to it the
TPU$K_RECORD_ATTR or TPU$K_RECORD_FORM item, that item is
used instead. The following combinations of formats and attributes are
acceptable:
Format

Attributes

STM,STMLF,STMCR

O,BLK,CR,BLK+CR

VAR

O,BLK,FTN,CR,BLK+FTN,8LK+CR

All other combinations are converted to VAR format with CR attributes.
This routine always puts values greater than 511 in the first longword
of the stream data structure. Because a user-written file 1/0 routine is
restricted to the values 0 through 511, you can easily distinguish the file
control blocks (FCB) this routine fills in from the ones you created.

Note: VAXTPU uses TPU$FILEIO by default when you use the simplified
callable interface. When you use the full callable interface, you
must explicitly invoke TPU$FILEIO or provide your own file 1/0
routine.

CONDITION
VALUES
RETURNED

TPU-40

The TPU$FILEIO routine returns an RMS status code to VAXTPU. The
file I/O routine is responsible for signaling all errors if any messages are
desired.

VAX Text Processing Utility {VAXTPU) Routines

TPU$HANDLER

VAXTPU Condition Handler

The TPU$HANDLER routine is VAXTPU's condition handler.
The VAXTPU condition handler invokes the Put Message (SYS$PUTMSG)
system service, passing it the address of TPU$MESSAGE.

FORMAT

TPU$HANDLER

RETURNS

VMS usage:
type:
access:
mechanism:

signaL vector, mechanism_ vector

cond_value
longword (unsigned)
write only
by value

Longword condition value.

ARGUMENTS

signal_ vector
VMS usage:
type:
access:
mechanism:

arg_list
longword (unsigned)
modify
by reference

Signal vector. See the VMS System Services Reference Manual for
information about the signal vector passed to a condition handler.

mechanism_ vector
VMS usage:
type:
access:
mechanism:

arg_list
longword (unsigned)
read only
by reference

Mechanism vector. See the VMS System Services Reference Manual for
information about the mechanism vector passed to a condition handler.

DESCRIPTION

The TPU$MESSAGE routine performs the actual output of the message.
The Put Message (SYS$PUTMSG) system service only formats the
message. It gets the settings for the message flags and facility name from
the variables described in Section 14.1.2. Those values can be modified
only by the VAX.TPU built-in procedure SET.
If the condition value received by the handler has a FATAL status or does
not have VAX.TPU's facility code, the condition is resignaled.
If the condition is TPU$_QUITTING, TPU$_EXITING, or TPU$_
RECOVERFAIL, a request to UNWIND is made to the establisher of
the condition handler.

TPU-41

VAX Text Processing Utility (VAXTPU) Routines

TPU$HANDLER
After handling the message, the condition handler returns with a continue
status. VAXTPU error message requests are made by signaling a condition
to indicate which message should be written out. The arguments in the
signal array are a correctly formatted message argument vector. This
vector sometimes contains multiple conditions and formatted ASCII output
(FAQ) arguments for the associated messages. For example, if the editor
attempts to open a file that does not exist, the VAXTPU message TPU$_
NQFILEACCESS is signaled. The FAQ argument to this message is a
string for the name of the file. This condition has an error status, followed
by the VMS RMS status field (STS) and status value field (STV). Because
this condition does not have a fatal severity, the editor continues after
handling the error.
The editor does not automatically return from TPU$CONTROL. If you call
the TPU$CONTRQL routine, you must explicitly establish a way to regain
control (for example, using the built-in procedure CALL_USER). Also, if
you establish your own condition handler but call the VAXTPU handler for
certain conditions, the default condition handler must be established at
the point in your program where you want to return control.
See the Introduction to VMS System Routines for information about the
VAX Condition Handling Standard.

TPU-42

VAX Text Processing Utility (VAXTPU) Routines
TPU$1NITIALIZE

TPU$1NITIALIZE

Initialize VAXTPU for Editing

The TPU$1NITIALIZE routine initializes VAXTPU for editing. This routine
allocates global data structures, initializes global variables, and calls the
appropriate setup routines for each of the major components of the editor,
including the Virtual File Manager, Screen Manager, and 1/0 subsystem.

FORMAT

TPU$1NITIALIZE

RETURNS

VMS usage:
type:
access:
mechanism:

callback [,user_arg]

cond_value
longword (unsigned)
write only
by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

callback
VMS usage: vector_longword_unsigned
type:
bound procedure value
access:
read only
mechanism: by descriptor
Callback routine. The callback argument is the address of a user-written
routine that returns the address of an item list containing initialization
parameters or a routine for handling file 1/0 operations. This callback
routine must call a parsing routine, which can be TPU$CLIPARSE or a
user-written parsing routine.

Callable VAXTPU defines thirteen item codes that can be used for
specifying initialization parameters. You do not have to arrange the
item codes in any particular order in the list. The following figure shows
the general format of an item descriptor. For information about how to
build an item list, refer to the VMS programmer's manual associated with
the language you are using.
Item Code

T Buffer Length

Buffer Address
Return Address
ZK-4044-GE

The return address in an item descriptor is usually 0.

TPU-43

VAX Text Processing Utility (VAXTPU) Routines
TPU$1NITIALIZE

The following item codes are available:

TPU-44

Item Code

Description

TPU$_0PTIONS

Enables the command qualifiers. Ten bits in the buffer
address field correspond to the various TPU command
qualifiers. The remaining 22 bits in the buffer address
field are reserved.

TPU$_JOURNALFILE

Passes the string specified with the /JOURNAL qualifier.
The buffer length field is the length of the string, and
the buffer address field is the address of the string.
This string is available with GET_INFO (COMMAND_
LINE,"JOURNAL_FILE"). This string can be a null string.

TPU$_SECTIONFILE

Passes the string that is the name of the binary
initialization file (section file) to be mapped in. The
buffer length field is the length of the string and the
buffer address field is the address of the string. The
VAXTPU CLO file has a default value for this string. If
the TPU$V_SECTION bit is set, this item code must be
specified.

TPU$_OUTPUTFILE

Passes the string specified with the /OUTPUT qualifier.
The buffer length field is the length of the string, and the
buffer address field specifies the address of the string.
This string is returned by the built-in procedure GET_
INFO (COMMAND_LINE, "OUTPUT_FILE"). The string
can be a null string.

TPU$_DISPLAYFILE

Passes the string specified with the /DISPLAY qualifier.
The buffer length field is the length of the string, and the
buffer address field specifies the address of the string.

TPU$_COMMANDFILE

Passes the string specified with the /COMMAND qualifier.
The buffer length field is the length of the string, and the
buffer address field is the address of the string. This
string is returned by the built-in procedure GET_INFO
(COMMAND_LINE, "COMMAND_FILE"). The string can
be a null string.

TPU$_FILENAME

Passes the string that is the name of the input file
specified in the command line. The buffer length field
specifies the length of this string, and the buffer address
field specifies its address. This string is returned by the
built-in procedure GET_INFO (COMMAND_LINE, "FILE_
NAME"). This file name can be a null string.

TPU$_FILEIO

Passes the bound procedure value of a routine to be
used for handling file operations. You can provide
your own file 1/0 routine, or you can call TPU$FILEIO,
the utility routine provided by VAXTPU for handling
file operations. The buffer address field specifies the
address of a two-longword vector. The first longword
of the vector contains the address of the routine. The
second longword specifies the environment value that
TPU loads into R1 before calling the routine.

VAX Text Processing Utility {VAXTPU) Routines
TPU$1NITIALIZE

Item Code

Description

TPU$_CALLUSER

Passes the bound procedure value of the user-written
routine that the built-in procedure CALL_USER is to
call. The buffer address field specifies the address
of a two-longword vector. The first longword of the
vector contains the address of the routine. The second
longword specifies the environment value that TPU loads
into R1 before calling the routine.

TPU$_1NIT_FILE

Passes the string specified with the /INITIALIZATION
qualifier. The buffer length field is the length of the
string, and the buffer address field is the address of the
string. This string is returned by the built-in procedure
GET_INFO (COMMAND_LINE,"INIT_FILE").

TPU$_START_LINE

Passes the· starting line number for the edit. The
buffer address field 9ontains the first of the two integer
values you specified as part of the /START_POSITION
command qualifier. The value is available using the builtin procedure GET_INFO (COMMAND_LINE,"LINE").
Usually an initialization procedure uses this information
to set the starting position in the main editing buffer. The
first line in the buffer is line 1.

TPU$_START_CHAR

Passes the starting column position for the edit. The
buffer address field contains the second of the two
integer values you specified as part of the /START_
POSITION command qualifier. The value is available
using the built-in procedure GET_INFO (COMMAND_
LINE, "CHARACTER"). Usually an initialization
procedure uses this information to set the starting
position in the main editing buffer. The first column
on a line corresponds to character 1.

TPU$_CONTROLC

Passes the bound procedure value of a routine to be
used for handling Ctrl/c ASTs. VAXTPU calls the routine
when a Ctrl/c AST occurs. If the routine returns a
FALSE value, VAXTPU assumes that the Ctrl/c has been
handled. If the routine returns a TRUE value, VAXTPU
aborts any currently executing VAXTPU procedure.
The buffer address field specifies the address of a
two-longword vector. The first longword of the vector
contains the address of the routine. The second
longword specifies the environment value that TPU
loads into R1 before calling the routine.

TPU$_DEBUGFILE

Passes the string specified with the /DEBUG command
qualifier. The buffer length field is the length of the string,
and the buffer address field is the address of the string.

TPU-45

VAX Text Processing Utility (VAXTPU) Routines
TPU$1NITIALIZE

The following table shows the bits and corresponding masks enabled by
the item code TPU$K_OPTIONS:
Mask

Bit

TPU$M_RECOVER1

TPU$V_RECOVER2

Performs a recovery operation.

TPU$M_JOURNAL

TPU$V_JOURNAL

Journals the edit session.

TPU$M_READ

TPU$V_READ

Makes this a READ_ONLY edit session for the
main buffer.

TPU$M_SECTION

TPU$V_SECTION

Maps in a binary initialization file (a VAXTPU
section file) during startup.

TPU$M_CREATE

TPU$V_CREATE

Creates an input file if the one specified does
not exist.

TPU$M_OUTPUT

TPU$V_OUTPUT

Writes the modified input file upon exiting.

TPU$M_COMMAND

TPU$V_COMMAND

Executes a command file during startup.

TPU$M_DISPLAY

TPU$V_DISPLAY

Attempts to use the terminal for screen
oriented editing and display purposes.

TPU$M_INIT

TPU$V_INIT

Indicates the presence of an initialization file.

TPU$M_COMMAND_DFLTED

TPU$V_COMMAND_DFLTED

Indicates whether the user defaulted the name
of the command line. A setting of TRUE
means the user did not specify a command
file. If this bit is set to FALSE and the user did
not specify a file, TPU$1NITIALIZE fails.

TPU$M_WRITE

TPU$V_WRITE

Indicates whether /WRITE was specified on
the command line.

TPU$M_MODIFY

TPU$V_MODIFY

Indicates whether /MODIFY was specified on
the command line.

TPU$M_NOMODIFY

TPU$V_NOMODIFY

Indicates whether /NOMODIFY was specified
on the command line.

Function

1TPU$M ... indicates a mask.

2 TPU$V ... indicates a bit item.

To create the bits, start with the value 0, then use the OR operator on the
mask (TPU$M . . . ) of each item you want to set. Another way to create
the bits is to treat the 32 bits as a bit vector and set the bit (TPU$V . . . )
corresponding to the item you want.

user_arg
VMS usage: user_arg
longword (unsigned}
access:
read only
mechanism: by value
User argument. The user_arg argument is passed to the user-written
initialization routine INITIALIZE.
type:

The user_arg parameter is provided to allow an application to pass
information through TPU$INITIALIZE to the user-written initialization
routine. VAX.TPU does not interpret this data in any way.

TPU-46

VAX Text Processing Utility (VAXTPU) Routines
TPU$1NITIALIZE

DESCRIPTION

This is the first routine that must be called after establishing a condition
handler.
This routine initializes the editor according to the information received
from the callback routine. The initialization routine defaults all file
specifications to the null string and all options to off. However, it does not
default the file 1/0 or call-user routine addresses.
If you do not specify a section file, the software features of the editor are

limited.

CONDITION
VALUES
RETURNED

TPU$_SUCCESS

Initialization was completed successfully.

TPU$_SYSERROR

A system service did not work correctly.

TPU$_NONANSICRT

The input device (SYS$1NPUT) is not a supported
terminal.

TPU$_RESTOREFAIL

An error occurred during the restore operation.

TPU$_NOFILEROUTINE

No routine has been established to perform file
operations.

TPU$_1NSVIRMEM

Insufficient virtual memory exists for the editor to
initialize.

TPU$_FAILURE

General code for all other errors during initialization.

TPU-47

VAX Text Processing Utility (VAXTPU) Routines

TPU$MESSAGE

TPU$MESSAGE Write Message String
The TPU$MESSAGE routine writes error messages and strings using the
built-in procedure, MESSAGE.
You can call this routine to have messages written and handled in a
manner consistent with VAXTPU. This routine should be used only after
TPU$EXECUTE_INIFILE.

FORMAT

TPU$MESSAGE

RETURNS

VMS usage:
type:
access:
mechanism:

string

cond_value
longword (unsigned)
write only
by value

Longword condition value.

Note: The return status should be ignored because it is intended for use
by the Put Message (SYS$PUTMSG) system service.

ARGUMENT

string
char_string
character string
read only
by descriptor
Formatted message. The string argument is the address of a descriptor
of text to be written. It must be completely formatted. This routine does
not append the message prefixes. However, the text is appended to the
message buffer if one exists. In addition, if the buffer is mapped to a
window, the window is updated.
VMS usage:
type:
access:
mechanism:

TPU-48

VAX Text Processing Utility (VAXTPU) Routines
TPU$PARSEINFO

TPU$PARSEINFO

Parse Command Line and Build
Item List

The TPU$PARSEINFO routine parses a command and builds the item list for
TPU$1NITIALIZE.

FORMAT

TPU$PARSEINFO

RETURNS

VMS usage:
type:
access:
mechanism:

fileio, ca/Luser

item_list
longword (unsigned)
read only
by reference

The routine returns the address of an item list.

ARGUMENTS

fileio
VMS usage: vector_longword_unsigned
type:
bound procedure value
access:
read only
mechanism: by descriptor
File I/O routine. The fileio argument is the address of a descriptor of a
file I/O routine.

call_ user
VMS usage: vector_longword_unsigned
type:
bound procedure value
access:
read only
mechanism: by descriptor
Call-user routine. The call_user argument is the address of a descriptor
of a call-user routine.

DESCRIPTION

The TPU$PARSEINFO routine parses a command and builds the item list
for TPU$INITIALIZE.
This routine uses the Command Language Interpreter (CL!) routines
to parse the current command. It makes queries about the command
parameters and qualifiers that VAXTPU expects. The results of these
queries are used to set up the proper information in an item list. The
addresses of the user routines are used for those items in the list. The
address of this list is the return value of the routine.
If your application parses information that is not related to the operation

ofVAXTPU, make sure the application obtains and uses all non-VAXTPU
parse information before the application calls TPU$PARSEINFO interface.
This is because TPU$PARSEINFO destroys all parse information obtained
and stored before TPU$PARSEINFO was called.
TPU-49

VAX Text Processing Utillty (VAXTPU) Routines
TPU$TPU

TPU$TPU

Invoke VAXTPU
The TPU$TPU routine invokes VAXTPU and is equivalent to the DCL
command EDIT/TPU.

command

FORMAT

TPU$TPU

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENT

command
VMS usage: char_strlng
type:
character string
access:
read only
mechanism: by descriptor
Command string. Note that the verb is TPU instead of EDIT/TPU. The
command argument is the address of a descriptor of a command line.

DESCRIPTION

This routine takes the command string specified and passes it to the editor.
VAXTPU uses the information from this command string for initialization
purposes, just as though you had entered the command at the DCL level.
Using the simplified callable interface does not set TPU$CLOSE_
SECTION. This feature lets you make multiple calls to TPU$TPU without
requiring you to open and close the section file on each call.
If your application parses information that is not related to the operation
ofVAXTPU, make sure the application obtains and uses all non-VAXTPU
parse information before the application calls TPU$TPU. This is because
TPU$TPU destroys all parse information obtained and stored before
TPU$TPU was called.

CONDITION
VALUES
RETURNED

TPU-50

This routine returns any condition value returned by TPU$INITIALIZE,
TPU$EXECUTE_INFILE, TPU$CONTROL, and TPU$CLEANUP.

VAX Text Processing Utility (VAXTPU) Routines
FILEIO

FILEIO

User-Written Routine to Perform File
Operations
The user-written FILEIO routine is used to handle VAXTPU file operations.
The name of this routine can be either your own file 1/0 routine or the name
of the VAXTPU file 1/0 routine (TPU$FILEIO).

code, stream, data

FORMAT

FILEIO

RETURNS

VMS usage: cond_value
type:
longword (uslgned)
access:
write only
mechanism: by reference

Longword condition value. Most utility routines return a condition value
in RO. Condition values that this routine can return are listed under
CONDITION VALUES RETURNED.

ARGUMENTS

code
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by reference
Item code specifying a VAXTPU function. The code argument is the
address of a longword containing an item code from VAXTPU, which
specifies a function to perform.

stream
VMS usage: unspecified
type:
longword (unsigned)
, access:
modify
mechanism: by reference
File description. The stream argument is the address of a data structure
containing four longwords. This data structure is used to describe the file
to be manipulated.

data
VMS usage: item_list_3
type:
longword (unsigned)
access:
modify
mechanism: by reference
Stream data. The data argument is either the address of an item list or
the address of a descriptor.

Note: The value of this parameter depends on which item code you
specify.

TPU-51

VAX Text Processing Utility (VAXTPU) Routines
FILEIO

DESCRIPTION

The bound procedure value of this routine is specified in the item list built
by the callback routine. This routine is called to perform file operations.
Instead of using your own file I/O routine, you can call TPU$FILEIO
and pass it the parameters for any file operation that you do not want to
handle. Note, however, that TPU$FILEIO must handle all I/O requests
for any file it opens. Also, if it does not open the file, it cannot handle
any I/O requests for the file. In other words, you cannot intermix the
file operations between your own file I/O routine and the one supplied by
VAXTPU.

CONDITION
VALUES
RETURNED

The condition values returned are determined by the user and should
indicate success or failure of the operation.

TPU-52

VAX Text Processing Utility {VAXTPU) Routines
HANDLER

HANDLER

User-Written Condition Handling Routine
The user-written HANDLER routine performs condition handling ..

FORMAT

HANDLER

RETURNS

VMS usage:
type:
access:
mechanism:

signaLvector, mechanism_vector

cond_value
longword (unsigned)
write only
by value

Longword condition value.

ARGUMENTS

signal_ vector
VMS usage: arg_list
type:
longword (unsigned)
access:
modify
mechanism: by reference
Signal vector. See the VMS System Services Reference Manual for
information about the signal vector passed to a condition handler.

mechanism_ vector
VMS usage: arg_list
type:
longword (unsigned)
access:
read only
mechanism: by reference
Mechanism vector. See the VMS System Services Reference Manual for
information about the mechanism vector passed to a condition handler.

DESCRIPTION

If you need more information about writing condition handlers and the

VAX. Condition Handling Standard, refer to the Introduction to VMS
System Routines.
Instead of writing your own condition handler, you can use the default
condition handler, TPU$HANDLER. If you want to write your own
routine, you must call TPU$HANDLER with the same parameters that
your routine received to handle VAX.TPU internal signals.

TPU-53

VAX Text Processing Utlllty (VAXTPU) Routines
INITIALIZE

INITIALIZE User-Written Initialization Routine
The user-written initialization callback routine is passed to TPU$1NITIALIZE as
a bound procedure value and called to supply information needed to Initialize
VAXTPU.

FORMAT

INITIALIZE [user_arg]

RETURNS

VMS usage: ltem_llst
type:
longword (unsigned)
access:
read only
mechanism: by reference

This routine returns the address of an item list.

ARGUMENTS

DESCRIPTION

user_arg
VMS usage: user_arg
type:
longword (unsigned)
access:
read only
mechanism: by value
User argument.

The user-written initialization call-back routine is passed to
TPU$INITIALIZE as a bound procedure value and called to supply
information needed to initialize VAXTPU.
If the user_arg parameter was specified in the call to TPU$INITIALIZE,
the initialization call-back routine is called with only that parameter.
If user_arg was not specified in the call to TPU$INITIALIZE, the
initialization call-back routine is called with no parameters.
The user_arg parameter is provided to allow an application to pass
information through TPU$INITIALIZE to the user-written initialization
routine. VAXTPU does not interpret this data in any way.
The user-written call-back routine is expected to return the address of
an item list containing initialization parameters. Because the item list is
used outside the scope of the initialization call-back routine, it should be
allocated in static memory.
The item list entries are discussed in the section on TPU$INITIALIZE.
Most of the initialization parameters have a default value; strings
default to the null string, and flags default to false. The only required
initialization parameter is the address of a routine for file 1/0. If an
entry for the file 1/0 routine address is not present in the item list,
TPU$INITIALIZE returns with a failure status.

TPU-54

VAX Text Processing Utility (VAXTPU) Routines
USER

USER User-Written Routine Called from a VAXTPU
Editing Session
The user-written USER routine allows your program to get control during a
VAXTPU editing session (for example, to leave the editor temporarily and
perform a calculation).
This user-written routine is invoked by the VAXTPU built-in procedure CALL_
USER. The built-in procedure CALL_USER passes three parameters to this
routine. These parameters are then passed to the appropriate part of your
application to be used as specified. (For example, they can be used as
operands in a calculation within a FORTRAN program.) Using the string
routines provided by the VMS Run-Time Library, your application fills in the
strlngout parameter in the call-user routine, which returns the strlngout value
to the built-in procedure CALL_USER.

integer, stringin, stringout

FORMAT

USER

RETURNS

VMS usage: cond_value
type:
longword (unsigned)
access:
write only
mechanism: by value

Longword condition value.

ARGUMENTS

integer
VMS usage: longword_unslgned
type:
longword (unsigned)
access:
read only
mechanism: by descriptor
First parameter to the built-in procedure CALL_USER. This is an inputonly parameter and must not be modified.

stringin
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Second parameter to the built-in procedure CALL_USER. This is an
input-only parameter and must not be modified.

stringout
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Return value for the built-in procedure CALL_USER. Your program should
fill in this descriptor with a dynamic string allocated by the string routines
TPU-55

VAX Text Processing Utility {VAXTPU) Routines
USER

provided by the VMS Run-Time Library. The VAXTPU editor frees this
string when necessary.

DESCRIPTION

The description of the built-in procedure CALL_USER in the VAX Text
Processing Utility Manual shows an example of a BASIC program that is
a call-user routine.

EXAMPLE
INTEGER FUNCTION TPU$CALLUSER (x,y,z)
IMPLICIT NONE
INTEGER X
CHARACTER*(*) Y
STRUCTURE /dynamic/ Z
INTEGER*2 length
BYTE
dtype
BYTE
class
INTEGER ptr
END STRUCTURE
RECORD /dynamic/ Z
CHARACTER*80 local_copy
INTEGER rs,lclen
INTEGER STR$COPY DX
local copy= '<'-// y // '>'
lclen-= LEN(Y) + 2
RS= STR$COPY DX(Z,local copy(l:lclen))
TPU$CALLUSER ~ RS
END

You can call this FORTRAN program with a VAXTPU procedure. The
following is an example of one such procedure:
PROCEDURE MY CALL
local status;
status :=CALL USER (0,'ABCD');
MESSAGE('"' + I Ill);
END PROCEDURE

TPU-56

Index
Command string (Cont.)

A
Access control list (ACL)
See also ACL Editor routine
editing • ACL-3
manipulating• ACL-1
Access Control List Editor routine
See ACL Editor routine
ACLEDIT$EDIT routine• ACL-3
ACL Editor routine
example of use in BLISS program• ACL-1
introduction• ACL-1
options available • ACL-3
ACLEDT$SECTION logical name
defined • ACL-5

B
Binary data
compression of • DCX-1
Buckets
reclaiming with CONV$RECLAIM routine •
CONV-18
reclamation statistics • CONV-18

c
CLl$DCL_PARSE routine • CLl-6
CLl$DISPATCH routine• CLl-9
CU$GET_VALUE routine• CLl-10
CU$PRESENT routine• CU-13
CU routines
See also Command string
example of use in FORTRAN program • CU-2
introduction • CU-1
list of • CLl-1
when to use • CU-1
Command language routines
See CLI routines
Command string
See also CU routines
action routine• CU-9

checking for presence of command string entities •
CU-13
dispatching to action routine • CU-9
keyword path • CLl-13
labels
list of label names • CLl-12
obtaining values of command string entities •
CLl-10
parsing a DCL command string • CLl-6
positional qualifiers• CLl-14
processing with CU routines • CLl-1
prompting for input• CU-7
symbol substitution • CU-6
Command table
with CU routines• CU-1, CLl-7
Context variable
use with DCX routines • DCX-16
CONV$CONVERT routine • CONV-8
CONV$PASS_FILES routine• CONV-11
CONV$PASS_OPTIONS routine • CONV-14
CONV$RECLAIM routine• CONV-18
CONVERT command
list of qualifiers • CONV-14
passing options • CONV-14
passing options in an array • CONV-16
setting qualifiers • CONV-14
Convert routines
See CONV routines
CONV routines
examples• CONV-1 to CONV-7
introduction• CONV-1
list of • CONV-1
using wildcard characters • CONV-12

D
Data compression
See also DCX routines
analysis preceding compression • DCX-13
compression algorithm
submitting all data records• DCX-15
size of data after compression• DCX-1
Data Compression/Expansion routines
See DCX routines
Data expansion • DCX-22

lndex-1

Index

Data expansion (Cont.)

FOL routines

See also DCX routines
initializing • DCX-25
Data record
analysis• DCX-11
compression• DCX-1
conversion• CONV-1
conversion statistics • CONV-8
expansion • DCX-1
DCL Command string

See also FOL specification
examples• FDL-1 to FDL-5
introduction• FDL-1
FOL specification

See Command string
DCX$ANALYZE_DATA routine• DCX-11
DCX$ANALYZE_DONE routine• DCX-13
DCX$ANALYZE_INIT routine• DCX-14
DCX$COMPRESS_DATA routine• DCX-17
DCX$COMPRESS_DONE routine• DCX-19
DCX$COMPRESS_INIT routine• DCX-20
DCX$EXPAND_DATA routine• DCX-22
DCX$EXPAND_DONE routine• DCX-24
DCX$EXPAND_INIT routine• DCX-25
DCX$MAKE_MAP routine • DCX-27
DCX routines
examples• DCX-2 to DCX-1 O
introduction• DCX-1
procedure for use• DCX-1
when to use • DCX-1
with multiple streams of data records• DCX-1
Device access
controlling through access control lists• ACL-1

E
EDT$EDIT routine • EDT-3
EDT routines
examples• EDT-1 to EDT-2
introduction• EDT-1
user-written
FILEIO • EDT-7
WORKIO• EDT-11
XLATE • EDT-13

F
FDL$CREATE routine • FDL-6
FDL$GENERATE routine• FDL-11
FDL$PARSE routine• FDL-14
FDL$RELEASE routine• FDL-17

lndex-2

See also FOL routines
creating • FDL-6
default attributes• FDL-15
generating• FDL-11
in character string • FDL-8
use of semicolons as delimiters• FDL-1
parsing• FDL-14
with CONV routines • CONV-15
File access
controlling through access control lists• ACL-1
File Definition Language routines
See FOL routines
File organization
changing with CONV routines• CONV-1
Files
Prolog 3 indexed files • CONV-1, CONV-18
File specifications
with CONV routines• CONV-12
Full callable interface
See VAXTPU routines

G
Global sections
controlling access through access control lists •
ACL-1

I
Images
compression of• DCX-1
Item list
with ACL Editor routine • ACL-3
with TPU routines • TPU-49

J
Job controller
function • PSM-4
request to symbiont• SMB-5

Index

K
Keyword path
obtaining values of command string keywords •
CLl-10
referencing command string keywords• CLl-13

L
LBR$CLOSE routine • LBR-20
LBR$DELETE_DATA routine• LBR-21
LBR$DELETE_KEY routine • LBR-23
LBR$FIND routine• LBR-25
LBR$FLUSH routine • LBR-27
LBR$GET_HEADER routine• LBR-29
LBR$GET_HELP routine• LBR-31
LBR$GET_HISTORY routine• LBR-34
LBR$GET_INDEX routine • LBR-36
LBR$GET_RECORD routine • LBR-38
LBR$1Nl_CONTROL • LBR-40
LBR$1NSERT_KEY routine • LBR-42
LBR$LOOKUP_KEY routine• LBR-44
LBR$0PEN routine • LBR-46
LBR$0UTPUT_HELP routine • LBR-50
LBR$PUT_END routine• LBR-55
LBR$PUT_HISTORY routine• LBR-56
LBR$PUT_RECORD routine • LBR-58
LBR$REPLACE_KEY routine • LBR-60
LBR$RET_RMSSTV routine • LBR-62
LBR$SEARCH routine • LBR-63
LBR$SET_INDEX routine• LBR-65
LBR$SET_LOCATE routine • LBR-67
LBR$SET_MODULE routine • LBR-68
LBR$SET_MOVE routine • LBR-70
LBR routines
control index• LBR-7
current index number
setting• LBR-65
data record
reading • LBR-38
writing• LBR-58
end-of-module record
writing • LBR-55
examples• LBR-7 to LBR-19
creating a new library• LBR-7 to LBR-1 O
deleting a module from a library• LBR-16 to
LBR-19

LBR routines
examples (Cont.)
extracting a module from a library• LBR-14
to LBR-16
inserting a module into a library• LBR-10 to
LBR-14
header • LBR-2
help text
outputting • LBR-50
retrieving • LBR-31
index • LBR-2
searching • LBR-63
introduction• LBR-1 to LBR-19
library
closing • LBR-20
creating• LBR-46
opening • LBR-46
shareable image • LBR-1
structure • LBR-2 to LBR-5
types • LBR-1
user-developed• LBR-1
library file
flushing • LBR-27
library header information
reading • LBR-29
retrieving • LBR-29
library index
getting contents • LBR-36
initializing • LBR-40
searching for key • LBR-36
library key • LBR-2
·creating ASCII or binary• LBR-47
deleting • LBR-23
finding • LBR-25
inserting • LBR-42
looking up • LBR-44
replacing • LBR-60
library update history record
retrieving • LBR-34
locate mode
setting record access mode to • LBR-67
module • LBR-2
accessing with RFA • LBR-25
deleting data records • LBR-21
deleting header• LBR-21
module header
reading • LBR-68
setting • LBR-68
updating • LBR-68
move mode
setting record access to• LBR-70
summary • LBR-5 to LBR--6

lndex-3

Index

LBR routines (Cont.}
update history records
writing • LBR-56
virtual memory
recovering • LBR-27
VMS RMS status value
returning• LBR-62
Librarian routines
See LBR routines
Logical name tables
controlling access through access control lists •
ACL-1

M
MAIL• MAIL-1
action routine • MAIL-8
calling sequence • MAIL-9
folder• MAIL-11, MAIL-15
mail file• MAIL-15
send• MAIL-18
address list• MAIL-17
creating• MAIL-17
username type• MAIL-17
bodypart
creating• MAIL-17
condition handling• MAIL-6
context • MAIL-4
initiating • MAIL-4
mail file • MAIL-9
message• MAIL-12
send • MAIL-16
terminating• MAIL-4
user profile• MAIL-19
deleted bytes threshold• MAIL-12
disk space
reclaim• MAIL-12
folder• MAIL-2
creating• MAIL-15
deleting• MAIL-15
folder names
displaying• MAIL-11
introduction• MAIL-1
item code • MAIL-8
Boolean • MAIL-8
input• MAIL-8, MAIL-21
output• MAIL-8, MAIL-23
item descriptor
declaring• MAIL-8
null• MAIL-8

lndex-4

MAIL (Cont.}
item list• MAIL-6
declaring • MAIL-8
terminating • MAIL-8
mail file • MAIL-3
alternate• MAIL-1 O
closing• MAIL-10
compressing• MAIL-12
creating• MAIL-15
default• MAIL-10
opening• MAIL-10
purging • MAIL-12
specifying• MAIL-10 to MAIL-11
wastebasket • MAIL-12
mail file context
initiating • MAIL-9
terminating • MAIL-9
message• MAIL-1
attribute• MAIL-17
copying• MAIL-15
creating• MAIL-17
deleting• MAIL-16
displaying• MAIL-14
marking• MAIL-14
modifying• MAIL-14
moving• MAIL-15
printing• MAIL-14
reading • MAIL-14
selecting• MAIL-13
sending• MAIL-17, MAIL-18
message attribute
creating• MAIL-17
message context
initiating• MAIL-13
terminating• MAIL-13
message format
standard• MAIL-1
message header
creating• MAIL-17
message ID
external • MAIL-2
null item list• MAIL-8
programming examples • MAIL-25
send context
initiating• MAIL-16
terminating• MAIL-16
signaling error• MAIL-6
disabling • MAIL-6
thread • MAIL-5 to MAIL-6
user common database• MAIL-3, MAIL-19

Index

MAlL
user context
initiating• MAIL-19
terminating• MAIL-19
user profile
flags • MAIL-20
form • MAIL-20
forward addressing• MAIL-20
personal name • MAIL-20
queue name • MAIL-20
user profile entry• MAIL-3, MAIL-19
adding • MAIL-20
deleting• MAIL-20
modifying • MAIL-20
MAIL$MAILFILE_BEGIN • MAIL-34
MAIL$MAILFILE_CLOSE • MAIL-38
MAIL$MAILFILE_COMPRESS • MAIL-41
MAIL$MAILFILE_END • MAIL-44
MAIL$MAILFILE_INFO_FILE • MAIL-46
MAIL$MAILFILE_MODIFY • MAIL-49
MAIL$MAILFILE_OPEN • MAIL-52
MAIL$MAILFILE_PURGE_WASTE • MAIL-55
MAIL$MESSAGE_BEGIN • MAIL-58
MAIL$MESSAGE_COPY • MAIL-62
MAIL$MESSAGE_DELETE • MAIL-67
MAIL$MESSAGE_END • MAIL-69
MAIL$MESSAGE_GET • MAIL-71
MAIL$MESSAGE_INFO • MAIL-76
MAIL$MESSAGE_MODIFY • MAIL-80
MAIL$MESSAGE_SELECT • MAIL-83
MAIL$SEND_ABORT • MAIL-87
MAIL$SEND_ADD_ADDRESS • MAIL-89
MAIL$SEND_ADD_ATTRIBUTE • MAIL-91
MAIL$SEND_ADD_BODYPART • MAIL-98
MAIL$SEND_BEGIN • MAIL-94
MAIL$SEND_END • MAIL-101
MAIL$SEND_MESSAGE • MAIL-103
MAIL$USER_BEGIN • MAIL-105
MAIL$USER_DELETE_INFO • MAIL-110
MAIL$USER_END • MAIL-112
MAIL$USER_GET_INFO • MAIL-114
MAIL$USER_SET_INFO • MAIL-118
Mailboxes
controlling access through access control lists •
ACL-1

N
NCS$COMPARE routine • NCS-7
NCS$CONVERT routine • NCS-9

NCS$END_CF routine• NCS-11
NCS$END_CS routine• NCS-12
NCS$GET_CF routine• NCS-13
NCS$GET_CS routine• NCS-15
NCS$RESTORE_CF routine• NCS-17
NCS$RESTORE_CS routine• NCS-19
NCS$SAVE_Cf routine • NCS-21
NCS$SAVE_CS routine• NCS-23
NCS collating sequence end routine
See NCS$END_CS routine
NCS compare strings routine
See NCS$COMPARE routine
NCS conversion function end routine
See NCS$END_CF routine
NCS convert string routine
See NCS$CONVERT routine
NCS get collating sequence routine
See NCS$GET_CS routine
NCS get conversion function routine
See NCS$GET_CF routine
NCS restore collating sequence routine
See NCS$RESTORE_CS routine
NCS restore conversion function routine
See NCS$RESTORE_CF routine
NCS routines
example of use in FORTRAN program• NCS-2
example of use in MACR0-32 program • NCS-4
list of• NCS-1
typical application of • NCS-2
NCS save collating sequence routine
See NCS$SAVE_CS routine
NCS save conversion function routine
See NCS$SAVE_CF routine

p
Print symbiont
See Symbiont
invoking • PSM-23
Print Symbiont Modification routines
See PSM routines
Prolog 3 file
creating with CONV routines• CONV-15
Prolog 3 indexed files
reclaiming • CONV-18
with Convert/Reclaim Utility • CONV-1
Prolog files
with CONV routines • CONV-15

lndex-5

Index

Prompt string
setting with CLl$DCL_PARSE • CLl-8
PSM$PRINT routine • PSM-23
PSM$READ_ITEM_DX routine• PSM-25
PSM$REPLACE routine • PSM-27
PSM$REPORT routine • PSM-32
PSM$_FUNNOTSUP•PSM-36
PSM routines
examples • PSM-18 to PSM-22
introduction• PSM-1
user-written
USER-FORMAT-ROUTINE• PSM-35
USER-INPUT-ROUTINE• PSM-40
USER-OUTPUT-ROUTINE• PSM-46

SOR$END_SORT routine• SOR-34
SOR$PASS_FILES routine • SOR-36
SOR$RELEASE_REC routine • SOR-41
SOR$RETURN_REC routine• SOR-43
SOR$SORT_MERGE routine • SOR-45
SOR$SPEC_FILE routine • SOR-48
SOR routines
examples• SOR-4 to SOR-17
interface
file• SOR-2
record • SOR-2
introduction• SOR-1
list of• SOR-1
reentrancy
using context argument • SOR-4
Sort/Merge routines

See SOR routines
Symbiont

Queues
execution • PSM-4
generic • PSM-4

R
Record
See Data record
RMS control blocks
with FOL routines• FDL-14, FDL-17

s
Simplified callable interface
See VAXTPU routines
SMB$CHECK_FOR_MESSAGE routine• SMB-15
SMB$1NITIALIZE routine• SMB-16
SMB$READ_MESSAGE routine• SMB-18
SMB$READ_MESSAGE_ITEM routine• SMB-21
SMB$SEND_TO_JOBCTL routine• SMB-31
SMB routines
See also Job Controller
See also Symbiont
introduction • SMB-1
SOR$$STAT routine• SOR-50
SOR$BEGIN_MERGE routine• SOR-18
SOR$BEGIN_SORT routine• SOR-25
SOR$DTYPE routine• SOR-31

lndex-6

See also Queues
allocating memory • SMB-4
carriage control
processing of• PSM-12
connecting to a device• SMB-4
device • PSM-2
environments • SMB-5
function • PSM-4, SMB-2
input• PSM-2, SMB-1
INPSMB.EXE file• SMB-1
input routines
demand • PSM-6
internal logic • PSM-5
main format routine • PSM-13
main input routine• PSM-11
main output routine• PSM-15
invoking VMS print symbiont • PSM-23
job controller
communication with • SMB-1
job controller request • SMB-5
asynchronous • SMB-6
processing • SMB-1 O
reading• SMB-10
responding• SMB-13
synchronous • SMB-6
modifying• PSM-7, SMB-4
format routine • PSM-13
guidelines • PSM-8
initialization routine • PSM-16
input routine • PSM-1 O
integration of routines • PSM-17
output routine • PSM-14
restrictions • PSM-8

Index

Symbiont (Cont.)
multistream • SMB-9
multithreaded • PSM-3
output• PSM-2, SMB-1
PRTSMB.EXE file• SMB-1
print symbiont
internal logic• PSM-5
modifying• PSM-1
processing it performs • PSM-1
user-written• PSM-1
processing it performs• PSM-5
process-permanent file • SMB-4
server• PSM-2, SMB-1
single stream• SMB-9
stream
active • PSM-3
multiple streams • PSM-3
single stream • PSM-3
SYSGEN MAXBUF parameter• PSM-7
type• SMB-1
user-written• SMB-1, SMB-3
guidelines • SMB-4
user-written routines
interfaces• PSM-7
VMS printer• SMB-1
Symbiont/Job Controller Interface routine
See SMB routines
Symbiont/Job Controller Interface routines
See SMB routines
Symbiont thread • PSM-3

T
Text
compression of • DCX-1
Text processing routines
See VAXTPU routines
TPU$CLEANUP routine• TPU-26
TPU$CLIPARSE routine • TPU-29
TPU$CLOSE_TERMINAL routine• TPU-30
TPU$CONTROL routine • TPU-31
TPU$EDIT routine • TPU-32
TPU$EXECUTE_COMMAND routine• TPU-34
TPU$EXECUTE_INIFILE routine• TPU-35
TPU$FILEIO routine • TPU-37
TPU$HANDLER routine • TPU-41
TPU$1NITIALIZE routine• TPU-43
TPU$MESSAGE routine• TPU-48
TPU$PARSEINFO routine• TPU-49

TPU$TPU routine • TPU-50

u
User-written VAXTPU routines
See VAXTPU routines

v
VAX Text Processing Utility Routines
See VAXTPU routines
VAXTPU callable interface
See VAXTPU routines
VAXTPU routines
callable VAXTPU • TPU-1
error handling • TPU-3
full interface • TPU-2, TPU-6
overview • TPU-1
simplified interface • TPU-2, TPU-5
condition handler
condition codes • TPU-4
default • TPU-4
return values • TPU-4
universal symbols • TPU-4
examples • TPU-5, TPU-8 .to TPU-25
introduction • TPU-1
parameter
bound procedure value • TPU-4
shareable image • TPU-1 , TPU-3
constants • TPU-3
symbols • TPU-3
user-written
FILEIO • TPU-51
HANDLER• TPU-53
INITIALIZE• TPU-54
requirements • TPU-8
USER • TPU-55
VMS print symbiont
See Symbiont

w
Wildcard characters
with CONV routines • CONV-12

lndex-7

How to Order Additional Documentation

Technical Support
If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing

your electronic, telephone, or direct mail order.

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

Telephone and Direct Mail Orders
Your Location

Call

Contact

Continental USA,
Alaska, or Hawaii

800-DIGITAL

Puerto Rico
Canada

809-754-7575
800-267-6215

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire 03061
Local Digital subsidiary
Digital Equipment of Canada
Attn: DECdirect Operations KA02/2
P.O. Box 13000
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6
Local Digital subsidiary or
approved distributor
USASSB Order Processing - WMO/E15

International
Intemal 1

U.S. Area Software Supply Business
Digital Equipment Corporation
Westminster, Massachusetts 01473
1

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

Reader's Comments

VMS Utlllty Routines
Manual

AA-LA678-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
D
D
D
D
D
D
D
D

Good
D
D
D
D
D
D
D
D

Fair
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

Poor
D
D
D
D
D
D
D
D

·-;;~~;~:d

Here ~d Ta~ ------------------~lllr-------;~~;~---

I
I
I
I

in the
United States

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

DIGIT AL EQUIPMENT CORPORATION
Corporate User Publications-Spit Brook
ZKO 1-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 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

...

1•
c

'J
t

<II!