Digital PDFs

AA-Z504B-TE

April 1986

386 pages

Original

41MB

Document:	VMS 4.4 VAX VMS Utility Routines Reference Manual
Order Number:	AA-Z504B-TE
Revision:
Pages:	386
Original Filename:	https://archive.org/download/stx_AA-Z504B-TE_VMS_4.4_VAX_VMS_Utility_Routines_Reference_Manual_Apr86/AA-Z504B-TE_VMS_4.4_VAX_VMS_Utility_Routines_Reference_Manual_Apr86.pdf

OCR Text

VAX/VMS
Utility Routines
Reference Manual
Order Number: AA-Z504B-TE

April 1986

This manual describes VAX/VMS utility routines, a set of routines that
provide a programming interface to various VAX/VMS utilities.

Revision/Update Information:

This manual supersedes the
VAX/VMS Utility Routines Reference
Manual, Version 4.0.

Software Version:

digital equipment corporation
maynard, massachusetts

VAX/VMS Version 4.4

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

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

DIBOL
EduSystem
IAS
MASSBUS
PDP
PDT
RSTS
RSX

UNIBUS
VAX
VAXcluster
VMS
VT

□Bsoasu
ZK-2824

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

CANADA

INTERNATIONAL

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

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

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

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

Contents
PREFACE

NEW AND CHANGED FEATURES

xiii

SECTION 1
1.1

INTRODUCTION TO UTILITY ROUTINES

INTRO-1

OVERVIEW

INTRO-1

SECTION 2 ACCESS CONTROL LIST (ACL) EDITOR ROUTINE

ACL-1

2.1

INTRODUCTION TO THE ACL EDITOR ROUTINE

ACL-1

2.2

EXAMPLE OF USING THE ACL EDITOR ROUTINE

ACL-1

2.3

ACL EDITOR ROUTINE
ACLEDITSEDIT

ACL-2
ACL-3

SECTION 3 COMMAND LANGUAGE (CLI) ROUTINES

CLI-1

3.1

INTRODUCTION TO CLI ROUTINES

CLI-1

3.2

EXAMPLE OF USING THE CLI ROUTINES

CLI-1

3.3

CLI ROUTINES
CLISDCI_PARSE
CLISDISPATCH
CLI$GET_VALUE
CLISPRESENT

CLI-4
CLI-5
CLI-8
CLI-9
CLI-12

Contents

SECTION 4 CONVERT (CONV) ROUTINES

CONV-1

4.1

INTRODUCTION TO CONVERT ROUTINES

CONV-1

4.2

EXAMPLES OF USING THE CONV ROUTINES

CONV-1

4.3

CONV ROUTINES
CONVSCONVERT

CONV-7

SECTION 5

CONV$PASS_FILES

CONV-8
CONV-11

CONV$PASS_OPTIONS

CONV-14

CONVSRECLAIM

CONV-18

DATA COMPRESSION/EXPANSION (DCX)
ROUTINES

DCX-1

5.1

INTRODUCTION TO DCX ROUTINES

DCX-1

5.2

EXAMPLE OF USING THE DCX ROUTINES

DCX-2

5.3

DCX ROUTINES
DCX$ANALYZE_DATA

SECTION 6

DCX-11

DCX$ANALYZE_DONE

DCX-12
DCX-14

DCXSANALYZE—INIT

DCX-15

DCX$COMPRESS_DATA
DCXSCOM PRESS-DONE

DCX-18

DCX$COMPRESS_INIT

DCX-20
DCX-21

DCX$EXPAND_DATA

DCX-23

DCXSEXPAND—DONE

DCX-25

DCXSEXPAND—INIT

DCX-26

DCXSMAKE—MAP

DCX-28

EDT ROUTINES

EDT-1

6.1

INTRODUCTION TO EDT ROUTINES

EDT-1

6.2

EXAMPLE OF USING EDT ROUTINES

EDT-1

Contents

6.3

SECTION 7

EDT ROUTINES
EDTSEDIT

EDT-2
EDT-3

FILEIO

EDT-7

WORKIO

EDT-11

XLATE

EDT-13

FILE DEFINITION LANGUAGE (FDL) ROUTINES

FDL-1

7.1

INTRODUCTION TO FDL ROUTINES

FDL-1

7.2

EXAMPLES OF USING THE FDL ROUTINES

FDL-1

7.3

FDL ROUTINES
FDLSCREATE

SECTION 8

FDL-6
FDL-7

FDLSGENERATE
FDLSPARSE

FDL-12

FDLSRELEASE

FDL-18

FDL-15

LIBRARIAN (LBR) ROUTINES

LBR-1

8.1

INTRODUCTION TO LBR ROUTINES
8.1.1
Types of Libraries
8.1.2
Structure of Libraries
8.1.2.1
Library Headers • LBR-2
8.1.2.2
Modules • LBR-2
8.1.2.3
Indexes and Keys • LBR-2
8.1.2.4
Summary of Routines • LBR-6

LBR-1
LBR-1
LBR-2

8.2

EXAMPLES OF USING THE LBR ROUTINES

LBR-7

8.3

LBR ROUTINES
LBRSCLOSE
LBRSDELETE—DATA
LBR$DELETE_KEY
LBRSFIND
LBRSFLUSH
LBR$GET_HEADER
LBR$GET_HELP
LBR$GET_HISTORY

LBR-19
LBR-20
LBR-21
LBR-23
LBR-25
LBR-27
LBR-29
LBR-31
LBR-34
V

Contents

LBR$GET_INDEX

LBR-36

LBR$GET_RECORD

LBR-38

LBR$INI—CONTROL

LBR-40
LBR-42

LBR$INSERT_KEY
LBR$LOOKUP_KEY
LBRSOPEN

LBR-44

LBR$OUTPUT_HELP
LBR$PUT_END

LBR-50
LBR-55

LBR$PUT_HISTORY

LBR-56

LBR$PUT_RECORD
LBR$REPLACE_KEY

LBR-58

LBR$RET_RMSSTV

LBR-62

LBRSSEARCH

LBR-63

LBR$SET_INDEX
LB R$S ET—LOC ATE

LBR-65
LBR-67

LBR$SET—MODULE

LBR-68

LBR$SET_MOVE

LBR-70

LBR-46

LBR-60

SECTION 9 PRINT SYMBIONT MODIFICATION (PSM)
ROUTINES

PSM-1

9.1

INTRODUCTION TO PSM ROUTINES

PSM-1

9.2

VAX/VMS PRINT SYMBIONT OVERVIEW
9.2.1
Cnmnonents of the VAX A/MS Print Svmbiont
Creation of the Print Symbiont Process
9.2.2
Symhiont Streams
9.2.3
Symbiont and Joh Controller Functions
9.2.4
Print Symhiont Internal Logic
9.2.5

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

9.3

MODIFICATION PROCEDURE
9.3.1
Overview
Guidelines and Restrictions
9.3.2
Writing an Input Routine
9.3.3
9.3.3.1
Internal Logic of the Symbiont's Main Input
Routine • PSM-10
9.3.3.2
Symbiont Processing of Carriage
Control • PSM-11
Writing
a
Format
Routine
9.3.4
9.3.4.1
Internal Logic of the Symbiont's Main Format
Routine • PSM-13

PSM-7
PSM-7
PSM-8
PSM-9

PSM-12

Contents

9.3.5

9.3.6
9.3.7
9.3.8

Writing an Output Routine _
9.3.5.1 Internal Logic of the Symbiont's Main Output
Routine • PSM-14
Other Function Codes _
Writing a Symbiont Initialization Routine _
Integrating a Modified Symbiont _

9.4

EXAMPLE OF USING THE PSM ROUTINES

9.5

PSM ROUTINES
PSMSPRINT

PSM-14
PSM-15
PSM-16

PSM-18

PSM-21
PSM-22

PSM$READ_ITEM_DX

PSM-24

PSMSREPLACE

PSM-26

PSMSREPORT

PSM-31

USER-FORMAT-ROUTINE

PSM-33
PSM-38
PSM-44

USER-INPUT-ROUTINE
USER-OUTPUT-ROUTINE

PSM-13

SECTION 10 SYMBIONT/JOB CONTROLLER INTERFACE (SMB)
ROUTINES

SMB-1

10.1 INTRODUCTION TO SMB ROUTINES
10.1.1 Types of Symbionts _
10.1.2 Symbionts Supplied with the VAX/VMS Operating
System _
10.1.3 Symbiont Behavior in the VAX/VMS Environment _
10.1.4 Why Write a Symbiont? _
10.1.5 Guidelines for Writing a Symbiont _
10.1.6 The Symbiont/Job-Controller Interface Routines _
10.1.7 Choosing the Symbiont Environment _
10.1.7.1
Synchronous Versus Asynchronous Delivery of
Requests • SMB-6
10.1.7.2 Single Streaming Versus
Multistreaming • SMB-11
10.1.8 Reading Job Controller Requests _
10.1.9 Processing Job Controller Requests _
10.1.10 Responding to Job Controller Requests _

SMB-11
SMB-12
SMB-14

10.2

SMB-15

SMB ROUTINES
SMBSCHECK.FOR-MESSAGE

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

SMB-16

SMBSINITIALIZE

SMB-17

SMB$READ_MESSAGE
SMB$READ_MESSAGE_ITEM

SMB-19
SMB-22
vii

Contents

SMB$SEND_TO_JOBCTL

SECTION 11

SMB-35

SORT/MERGE (SOR) ROUTINES

SOR-1

INTRODUCTION TO SOR ROUTINES
11.1.1 Arguments to SOR Routines _
11.1.2 Interfaces to SOR Routines 11.1.2.1
Sort Operation Using File Interface • SOR-2
11.1.2.2 Sort Operation Using Record Interface • SOR-3
11.1.2.3 Merge Operation Using File Interface • SOR-3
11.1.2.4 Merge Operation Using Record Interface • SOR-3
11.1.3 Reentrancy -

SOR-1
SOR-2
SOR-2

11.2

EXAMPLES OF USING SOR ROUTINES

SOR-4

11.3

SOR ROUTINES
SOR$BEGIN_MERGE

11.1

SOR-19
SOR-20

SORSBEGIN-SORT

SOR-27

SOR$END_SORT

SOR-33

SOR$PASS_FILES

SOR-35

SOR$RELEASE_REC

SOR-40

SOR$RETURN_REC
SOR$SORT_MERGE

SOR-42

SOR$SPEC_FILE

SOR-47

SORSSTAT

SOR-49

SOR-44

SECTION 12 VAX TEXT PROCESSING UTILITY (VAXTPU)
ROUTINES

VIII

SOR-3

TPU-1

12.1 INTRODUCTION TO VAXTPU ROUTINES
12.1.1 Two Interfaces to Callable VAXTPU 12.1.2 Shareable Image 12.1.3 Passing Parameters to Callable VAXTPU Routines _
12.1.4 Error Handling _
12.1.5 Return Values _

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

12.2

TPU-4
TPU-5

THE SIMPLIFIED CALLABLE INTERFACE
12.2.1 Example of the Simplified Interface

Contents

12.3

THE FULL CALLABLE INTERFACE
12.3.1 Main Callable VAXTPU Utility Routines _
12.3.2 Other VAXTPU Utility Routines _
12.3.3 User-Written Routines _

TPU-5
TPU-6
TPU-6
TPU-6

12.4

EXAMPLES OF USING VAXTPU ROUTINES

TPU-7

12.5

VAXTPU ROUTINES

TPU-22

TPUSCLEANUP
TPUSCLIPARSE

TPU-23
TPU-27

TPUSCONTROL

TPU-28

TPUSEDIT
TPU$EXECUTE_COMMAND

TPU-29
TPU-30

TPU$EXECUTE_INIFILE

TPU-31

TPUSFILEIO
TPUSHANDLER

TPU-36

TPUSINITIALIZE

TPU-38

TPUSMESSAGE

TPU-42

TPUSPARSEINFO

TPU-43

TPUSTPU

TPU-44

FILEIO
HANDLER
INITIALIZE

TPU-45
TPU-47

USER

TPU-32

TPU-48
TPU-49

INDEX

EXAMPLES
ACL—1
CLI—1

Calling the ACL Editor With a VAX BLISS Program _
Using the CLI Routines to Retrieve Information About
Command Lines in a FORTRAN Program _
CONV-1 Using the CONVERT Routines in a FORTRAN Program _
CONV-2 Using the CONVERT Routines in a MACRO Program _
CONV-3 Using the CONVERT/RECLAIM Routine in a FORTRAN
Program _
CONV-4 Using the CONVERT/RECLAIM Routine in a MACRO Program .
DCX—1 Example of Compressing a File in a VAX FORTRAN Program _
DCX—2 Example of Expanding a Compressed File in a VAX FORTRAN
Program _
EDT—1 Using the EDT Routines in a VAX BASIC Program _
FDL-1 Using FDLSCREATE in a FORTRAN Program _

ACL-2
CLI-2
CONV-2
CONV-3
CONV-5
CONV-6
DCX-3
DCX-9
EDT-2
FDL-2
IX

Contents

FDL-2
FDL-3

Using FDL$PARSE and FDL$RELEASE in a MACRO Program _
Using FDL$PARSE and FDL$GENERATE in a VAX PASCAL
Program _
LBR—1 Creating A New Library Using VAX PASCAL _
LBR—2 Inserting Module Into Library Using VAX PASCAL _
LBR—3 Extracting Module From Library Using VAX PASCAL _
LBR—4 Deleting Module From Library Using VAX PASCAL _
PSM-1 Using PSM Routines to Supply a Page Header Routine in a
Macro Program _
SOR—1 Using SOR Routines to Perform a Merge Using Record
Interface in a FORTRAN Program _
SOR—2 Using SOR Routines to Sort Using Mixed Interface in a
VAX FORTRAN Program _
SOR—3 Using SOR Routines to Merge Three Input Files in a
VAX PASCAL Program _
SOR-4 Using SOR Routines to Sort Records from Two Input Files in a
VAX PASCAL Program _
TPU-1 Sample VAX BLISS Template for Callable VAXTPU _
TPU-2 Normal VAXTPU Setup in VAX FORTRAN _
TPU—3 Building a Callback Item List with VAX FORTRAN _
TPU—4 Specifying a User-Written File I/O Routine in VAX C _

FDL-3
FDL-5
LBR-8
LBR-11
LBR-14
LBR-17
PSM-18
SOR-5
SOR-9
SOR-11
SOR-15
TPU-8
TPU-12
TPU-14
TPU-17

FIGURES
ACL-1 Item List _
LBR—1 Structure of a Macro, Text, or Help Library _
LBR—2 Structure of an Object or Shareable Image Library _
LBR—3 Structure of a User-Developed Library _
PSM—1 Multithreaded Symbiont _
PSM—2 Symbiont Execution Sequence or Flow of Control _
SMB—1 Symbionts in the VAX/VMS Operating System Environment _
SMB—2 Flowchart for a Single-Threaded, Synchronous Symbiont _
SMB—3 Flow Chart for a Single-Threaded, Asynchronous Symbiont _
TPU—1 Bound Procedure Value _
TPU—2 Stream Data Structure _
TPU—3 Format of an Item Descriptor _

ACL-3
LBR-3
LBR-4
LBR-5
PSM-4
PSM-6
SMB-3
SMB-7
SMB-9
TPU-4
TPU-33
TPU-38

TABLES
PSM-1 Routine Codes for Specification to PSMSREPLACE

PSM-16

Preface

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

Structure of This Document
This document contains 12 sections. Section 1 introduces utility routines and
describes the documentation format that is used to describe each set of utility
routines, as well as individual routines in each set.
Sections 2 through 12 each describe one set of utility routines. Each section
contains an introduction to that set of utility routines, a programming example
to illustrate the use of the routines in the set, and a detailed decription of each
routine.

Associated Documents
The VAX Procedure Calling and Condition Handling Standard, which is
documented in the Introduction to VAX/VMS System Routines, contains useful
information for all programmers. The Introduction to VAX/VMS System
Routines also describes in detail the documentation format of the routine
descriptions.
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.
•

VAX/VMS Access Control List Editor Reference Manual

•

VAX/VMS Command Definition Utility Reference Manual

•

VAX/VMS Convert and Convert/Reclaim Utility Reference Manual

•

VAX EDT Reference Manual

•

VAX/VMS File Definition Language Facility Reference Manual

•

VAX/VMS Librarian Reference Manual

•

VAX/VMS Sort/Merge Utility Reference Manual

•

VAX Text Processing Utility Reference Manual

Preface

Conventions Used in This Document
The documentation template for utility routines, which is described in the
Introduction to VAX/VMS System Routines, describes 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 may appear in this
manual.

Convention

Meaning

[ret]

A symbol with a one- to six-character
abbreviation indicates that you press a key
on the terminal, for example, 1 RET| .

|CTRL/x|

The phrase CTRL/x indicates that you
must press the key labeled CTRL while you
simultaneously press another key, for example,
CTRL/C, CTRL/Y, CTRL/O.

$ SHOW TIME
05-JUN-1985 1 1:55:22

Command examples show all output lines or
prompting characters that the system prints
or displays in black letters. All user-entered
commands are shown in red letters.

$ TYPE MYFILE.DAT

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

file-spec,...

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

[logical-name]

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

quotation marks
apostrophes

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

New and Changed Features

New Sets of Utility Routines
The following sets of utility routines are new with VAX/VMS Version 4.4:
•

Access Control List (ACL) Editor Routine

•

VAX Text Processing Utility (VAXTPU) Routines

Argument Characteristics
The descriptions of each argument in the utility routines contains information
about the argument's characteristics—VMS Usage, type, access, and
mechanism.

xiii

Introduction to Utility Routines

1.1

Overview
A set of utility routines is a set of routines that perform a particular task or set
of tasks. For example, the Print Symbiont Modification (PSM) routines can be
used to modify the VAX/VMS print symbiont, and the EDT routines can be
used to invoke the EDT editor from a program.
Some of the tasks performed by utility routines documented in this manual
can also be performed by users at the DCL level. For example, the DCL
command EDIT invokes the EDT editor.
Some DCL commands invoke VAX/VMS utilities that allow users to perform
tasks at their terminals, and some of these tasks can also be performed at the
programming level through the use of the utility routines documented in this
manual.
When using a set of utility routines that performs the same tasks as a
VAX/VMS utility, you should read the documentation for that utility; doing
so will provide you with additional information on the tasks that the routines
can, as a set, perform. The following list shows which VAX/VMS utilities
have corresponding utility 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

Sort/Merge Utility

SOR routines

VAX Text Processing Utility

VAXTPU routines

When a set of utility routines performs functions that cannot be performed by
invoking a VAX/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

The utility routines described in this manual are called in the same way as
all other system routines in the VAX/VMS operating system environment.

INTRO-1

Introduction to Utility Routines
Overview

which is to say that utility routines conform to the VAX Procedure Calling
and Condition Handling Standard.
Each set of utility routines is documented in one section of this book.
Each section has the following three major components, each of which is
documented as a major heading.

INTRO-2

•

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

•

A programming example that illustrates how the utility routines are used.

•

A series of descriptions of each utility routine in the set. Each utility
routine is documented according to the format described in the following
section.

Access Control List (ACL) Editor Routine

2.1

Introduction to the ACL Editor Routine
This section describes the Access Control List (ACL) routine, ACLEDIT$EDIT.
User-written applications can use this callable interface of the ACL Editor to
manipulate Access Control Lists.
The ACL Editor is a VAX/VMS utility that allows users to create and maintain
access control lists. Using ACLs, you can finely 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
application program to define an object for editing.

ACL—1

Access Control List (ACL) Editor Routine
Example of Using the ACL Editor Routine

2.2

Example of Using the ACL Editor Routine
Example ACL-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, ! Routine return status
ITMLST : 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
CLI$GET_VALUE, ! Get qualifier value
CLI$PRESENT, ! See if qualifier present
LIB$PUT_OUTPUT, ! General output routine
STR$COPY_DX; ! 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[0, ITM$W_ITMCOD] =
ITMLST[0, ITM$W_BUFSIZ] =
ITMLST[0, ITM$L_BUFADR] =
ITMLST[1, ITM$W_ITMCOD] =
ITMLST[1. ITM$W_BUFSIZ] =
ITMLST[1, ITM$L_BUFADR] =
ITMLST[2, ITM$W_ITMC0D] =
ITMLST[2, ITM$W_BUFSIZ] =
ITMLST [2, ITM$L_BUFADR] =
1 - ACLEDIT$V_JOURNAL);

ITMLST);
ACLEDIT$C_OBJNAM;
7.CHARC0UNT ( ' YOUR.OBJECT.NAME' ) ;
$DESCRIPTOR ('YOUR.OBJECT.NAME');
ACLEDIT$C_OBJTYP;
4;
UPLIT (ACL$C_FILE);
ACLEDIT$C_OPTIONS;
4;
UPLIT (1 ~ ACLEDIT$V_PROMPT_MODE OR

RETURN ACLEDIT$EDIT (ITMLST);
END; ! End of routine STARTUP
END
ELUDOM

2.3

ACL Editor Routine
The following pages describe the ACL Editor routine in routine template
format.

Access Control List (ACL) Editor Routine
ACLEDIT$EDIT

ACLEDIT$EDIT—Edit Access Control List
Creates or modifies the access control list of any object in the
system.

FORMAT

ACLEDIT$EDIT item-list

RETURNS

VMS Usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return by value a condition
value in RO. Condition values that can be returned by this routine are listed
in "CONDITION VALUES RETURNED."

ARGUMENT

item-list
VMS Usage:
type:
access:
mechanism:

item_list_3
longword (unsigned)
read only
by descriptor

Item list. The item-list argument is the address of one or more descriptors
of arrays, routines, or longword bitmasks that control various aspects of the
editing session.
The item list used by the callable ACL editor is used to provide the needed
information. Each entry in item list is in the standard format as shown in
Figure ACL-1.

Figure ACL-1

Item List

ACL—3

Access Control List (ACL) Editor Routine
ACLEDIT$EDIT

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 SACLDEF.
The default object type is a file (ACL$C_FILE).

ACLEDIT$C_OPTIONS

Represents a longword bitmask 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 section 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 ACEs.

Specifies a vector of quadword descriptors, to be
used when parsing or formatting an ACE, which will
be used to define the names of the bits present in
the access mask.

The ACLEDIT$EDIT routine is used 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 the user
finishes or aborts the editing session.
You also wish to use a customized version of the ACL editor section file,
the logical name ACLSECINI should be defined. See the VAX/VMS Access
Control List Editor Reference Manual for more information.

ACL—4

Command Language (CLI) Routines

3.1

Introduction to CLI Routines
The CLI routines are used 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 on using the Command Definition Utility, see the
VAX/VMS Command Definition Utility Reference Manual.
The CLI routines include:
•

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 that is
invoked by the new command. These routines retrieve information about
the command string that invoked 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.

3.2

Example of Using the CLI Routines
The following example 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, issue 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.

CLI—1

****************************************************
SUBCOMMANDS.CLD
****************************************************
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)1
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 (7.VAL (STATUS))
STATUS * LIBIPUT.OUTPUT
2 ('Press CTRL/Z to exit')
IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL (STATUS))
! Get first subcommand
STATUS = CLI$DCL_PARSE C/.VAL (0),
2
INCOME.SUBCOMMANDS, ! CLD module
2
LIB$GET_INPUT,
! Parameter routine
2
LIB$GET_INPUT,
! Command routine
2
'INCOME> ')
! Command prompt

(Continued on n

CLI—2

! Do it until user presses CTRL/Z
DO WHILE (STATUS .NE. RMS$_E0F)
! If no error on dcl_parse
IF (STATUS) THEN
! Dispatch depending on subcommand
STATUS = CLIIDISPATCH ()
IF (.NOT. STATUS) CALL LIB$SIGNAL C/.VAL (STATUS))
! Do not signal warning again
ELSE IF (IBITS (STATUS, 0, 3) .NE. STS$K_WARNING) THEN
CALL LIBISIGNAL (7.VAL (STATUS))
END IF
! Get another subcommand
STATUS =* CLIIDCL.PARSE (7.VAL (0),
2
INCOME.SUBCOMMANDS. ! CLD module
2
LIBlGET.INPUT,
! Parameter ro
2
LIBIGET.INPUT,
! Command rout
2
'INC0ME> ')
! Command prom
END DO
END
INTEGER FUNCTION ENTER 0
INCLUDE '(ISSDEF)'
TYPE *, 'ENTER invoked'
ENTER = SSI.NORMAL
END
INTEGER FUNCTION FIX ()
INTEGER STATUS,
2
CLIlPRESENT,
2
CLI$GET_VALUE
CHARACTER*15 HOUSE.NUMBER
INTEGER*2
HN.SIZE
INCLUDE 1(ISSDEF)1
EXTERNAL CLII.ABSENT
TYPE *, 'FIX invoked'
! If user types /house_numbers=(n,...)
IF (CLIlPRESENT ('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 (1:HN_SIZE)
STATUS = CLIIGET.VALUE ('HOUSE.NUMBERS*,
2
HOUSE.NUMBER,
2
HN.SIZE)
END DO
! Make sure termination status was correct
IF (STATUS .NE. %L0C (CLII.ABSENT)) THEN
CALL LIBISIGNAL (%VAL (STATUS))
END IF
END IF
FIX = SSI.NORMAL
END

(Co

Command Language (CLI) Routines
Example of Using the CLI Routines

Example CLI-1

(Cont.)

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

INTEGER FUNCTION REPORT ()
INTEGER STATUS.
2
CLI$GET_VALUE
CHARACTER*64 FILENAME
INTEGER*2
FN.SIZE
INCLUDE '($SSDEF)'
TYPE *, 'REPORT entered'
! Get value for /output
STATUS = CLIlGET.VALUE ('OUTPUT',
2
FILENAME.
2
FN.SIZE)
IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL (STATUS))
TYPE *. 'Output file: '. FILENAME (IrFN.SIZE)
REPORT = SSI.NORMAL
END

3.3

CLI Routines
The following pages describe the individual CLI routines in routine template
format.

CLI—4

Command Language (CLI) Routines
CLI$DCI_PARSE

CLI$DCI_-PARSE—Parse DCL Command
String
Routine parses a command string using the command definition
supplied in the specified command table.

FORMAT

CLI$DCI_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. 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

command-string
VMS Usage:
type:
access:
mechanism:

char_string
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.
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 you also specify
a prompt routine, then DCL will prompt for the entire command string.
However if you specify the command-string argument as zero and you also
specify the prompt-routine argument as zero, then DCL will restore 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.

CLI-5

Command Language (CLI) Routines
CLISDCL.-PARSE

table
VMS Usage:
type:
access:
mechanism:

char_string
unspecified
read only
by reference

Name of the module containing the command language description. The
table argument is the address of the command table that describes the syntax
by which the command line should be parsed. This is usually represented by
a global symbol that is created by the Command Definition Utility when it
processes the MODULE statement in the command definition file.
The command table is created with the DCL command SET COMMAND
/OBJECT, and is linked with your image.

param-routine
VMS Usage:
type:
access:
mechanism:

procedure
procedure entry mask
read only
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.
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
VAX/VMS Run-Time Library Routines Reference Manual for information about
the calling format. The status returned by LIB$GET_INPUT must be success
or the CLI$DCL—PARSE routine exits and propagates the error outward.
The prompt string for a required parameter is obtained from the command
table specified in the table argument.

prompt-routine
VMS Usage:
type:
access:
mechanism:

procedure
procedure entry mask
read only
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. DCL uses this routine to obtain an entire command line if a zero
is specified in the command-string argument. 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.
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
VAX/VMS Run-Time Library Routines Reference Manual for information about
the calling format. The status returned by LIB$GET_INPUT must be success
or the CLI$DCL_PARSE routine exits and propagates the error outward.

CLl-6

Command Language (CLI) Routines
CLI$DCI_PARSE

prompt-string
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
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 prompt string.

DESCRIPTION The CLI$DCL_JPARSE 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 a CTRL/Z is entered or if RMS$_EOF is returned as a response to any
prompt, CLI$DCL_PARSE immediately terminates and returns the status
RMS$_EOF. If a null string is entered in response to a prompt for an entire or
a continued command string (specified with the prompt-routine argument),
CLI$DCL_PARSE terminates and returns the status CLI$_NOCOMD. If
a null string is entered in reponse to a prompt for a required parameter,
CLI$DCL_PARSE reissues the prompt.
Whenever CLI$DCL—PARSE encounters an error, it both signals and returns
the error.

CONDITION
VALUES
RETURNED

CLI$_NORMAL

Normal successful completion

CLI$_NOCOMD

A null string was entered in response to a prompt
from the prompt-routine argument. This causes
the CLI$DCL_PARSE routine to terminate.

RMSS—EOF

A CTRL/Z was entered in response to a prompt.
This causes the CLI$DCL_PARSE routine to
terminate

CLI—7

Command Language (CLI) Routines
CLI$DISPATCH

CLI$DISPATCH—Dispatch to Action
Routine
Invokes the subroutine associated with the verb most recently
parsed by a CLI$DCL_PARSE routine call.

FORMAT

CLISDISPATCH

RETURNS

VMS Usage:
type:
access:
mechanism:

[userarg]

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

ARGUMENT

userarg
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by value

Data passed to the action routine. The userarg argument is a longword that
contains the data passed by the action routine. This data can be used in any
way that you want.

DESCRIPTION

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.

CONDITION
VALUES
RETURNED

CLI$_INVROUT

CLI—8

CLI$DISPATCH is unable to invoke the routine
because an invalid routine is specified in the
command table, or no routine is specified.

Command Language (CLI) Routines
CLI$GET_VALUE

CLI$GET_VALUE—Get Value of Entity in
Command String
Retrieves the value associated with a specified qualifier, parameter,
or keyword path.

FORMAT

CLI$GET_VALUE entity-desc ,retdesc[,retlength]

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

entity—desc
VMS Usage:
type:
access:
mechanism:

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. The entity_desc
argument can be expressed as:
•

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 the LABEL clause was used to assign a label to an
entity, you must specify the label in the entity-desc argument. Otherwise,
use the name of the entity.
A keyword path is used to reference keywords that may be used as values of
parameters, qualifiers, or other keywords. A keyword path contains a list of
entity names or labels that are 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.)
$ NEWC0MMAND/QUAL1=(START=5.END=10)/QUAL2=(START=2,END=5)

CLI—9

Command Language (CLI) Routines
CLI$GET_VALUE

The keyword path QUAL1.START identifies the START keyword when it is
used with QUAL1; the keyword path QUAL2.START identifies the keyword
START when it is used with QUAL2. The name START is an ambiguous
reference if used alone.
Keywords that are not needed to unambiguously resolve a keyword reference
can be omitted from the beginning of a keyword path. The 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

2 The qualifiers in your command definition file, in the order they are listed
3 The keyword paths for each parameter, in the order the parameters are
listed

4 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, you should never use ambiguous keyword references because the
keyword search order may change in future releases of VAX/VMS.
If the entity_desc argument does not exist in the command table,
CLI$GET_VALUE will signal a syntax error (via the signaling mechanism
described in the VAX/VMS Run-Time Library Routines Reference Manual.

retdesc
VMS Usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

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 VAX/VMS Run-Time Library Routines
Reference Manual.

retlength
VMS Usage:
type:
access:
mechanism:

word-unsigned
word (unsigned)
write only
by reference

Word containing the number of characters DCL returned to RETDESC. The
retlength argument is the address of the word containing the length of the
retrieved value.

CLI—10

Command Language (CLI) Routines
CLI$GET_VALUE

DESCRIPTION

The CLI$GET_VALUE 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 were specified in the command string, DCL fills in any
defaulted fields. Also, if date-time strings (such as YESTERDAY) were
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 will indicate 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

CLI$_COMMA

The returned value is terminated by a comma; this
shows there are additional values in the list.

cli$_concat

The returned value is concatenated to the next
value with a plus sign; this shows there are
additional values in the list.

SS$_NORMAL

The returned value is terminated by a blank or an
end-of-line; this shows that the value is the last, or
only, value in the list

CLIS—ABSENT

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

CLI—11

Command Language (CLI) Routines
CLI$PRESENT

CLI$PRESEIMT—Determine Presence of
Entity in Command String
Determines whether a parameter, qualifier, or keyword is present in
the command string.

FORMAT

CLI$PRESENT entity—desc

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

ARGUMENT

entity— desc
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

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 on 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 will signal a syntax error (via the signaling mechanism
described in the VAX/VMS Run-Time Library Routines Reference Manual).

CLI—12

Command Language (CLI) Routines
CLI$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. A global
qualifier can be used anywhere in the command line; a local qualifier must
be used 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 the qualifier can be specified after. 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 will test 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$_JLOCNEG.

CONDITION
VALUES
RETURNED

CLI$_PRESENT

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

CLI$_NEGATED

The specified qualifier was present in its negated
form (with /NO) and was used as a global qualifier.

CLI$_LOCPRES

The specified qualifier was present and was used
as a local qualifier.

CLI—13

Command Language (CLI) Routines
CLI$PRESENT

CLI—14

CLI$_LOCNEG

The specified qualifier was present in its negated
form (with /NO) and was used as a local qualifier.

CLI$_DEFAULTED

The specified entity was not present but there is a
default value.

CLI$_ABSENT

The specified entity was not present and there is
no default value.

Convert (CONV) Routines

4.1

Introduction to Convert Routines
This section describes the Convert Routines. These routines perform the
functions of both the VAX RMS Convert and Convert/Reclaim Utilities.
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 this series of three routines.
1

CONV$PASS_FILES

2 CONV$PASS_OPTIONS
3 CONV$CONVERT
The routines must be called in this order.
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

Examples of Using the CONV Routines
The following example shows how to use the Convert routines in a
FORTRAN program.

CONV—1

*
*

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

*
*
*
*
*

INTEGERS (A - Z)

Set up parameter list: number of options, CREATE,
NOSHARE, FAST.LOAD, MERGE, APPEND, SORT, WORK.FILES,
KEY=0, NOPAD, PAD CHARACTER, NOTRUNCATE,
NOEXIT, NOFIXED.CONTROL, FILL.BUCKETS. NOREAD.CHECK,
NOWRITE_CHECK, FDL, and NOEXCEPTION.

INTEGER*4
OPTIONS(19),
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(5) /4,0,0,0.0/

Declare the file names.
CHARACTER
1
1

IN_FILE*7 /•SEQ.DAT'/,
0UT_FILE*12 /'CUSTDATA.DAT'/,
FDL_FILE*11 /'INDEXED.FDL'/

Call the routines in their required order.
STATUS = CONV$PASS_FILES (IN.FILE, OUT.FILE, FDL_FILE)
IF (.NOT. STATUS) CALL LIB$ST0P (7.VAL(STATUS))
STATUS = C0NV$PASS_0PTI0NS (OPTIONS)
IF (.NOT. STATUS) CALL LIB$ST0P (7.VAL(STATUS))
STATUS = C0NV$C0NVERT (STATSBLK)
IF (.NOT. STATUS) CALL LIB$ST0P (7.VAL(STATUS))

*
1000

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

The following example shows how to use the Convert routines in a
program.

CONV—2

;

This module calls the routines that perform the func
of the Convert Utility.
It creates an indexed outpu
named CUSTDATA.DAT from the specifications in am FDL
named INDEXED.FDL, and loads CUSTDATA.DAT with recor
the sequential file SEQ.DAT.
No exception file is c
This module also returns all the CONVERT statistics.

;

Declare the file names.

FILEIN:
FILEOUT:
FDLFILE:
;

/SEQ.DAT/
/CUSTDATA.DAT/
/INDEXED.FDL/

Set up parameter list.

PARAM_LIST:

;
;

.ASCID
.ASCID
.ASCID

.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 FOLL
CREATE
NOSHARE
FAST.LOAD
MERGE
APPEND
SORT
WORK.FILES
KEY=0
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
1L
OUTSTUFF:
.ASCID
#Number of files processe
Number of records: SUL !/Number of exception records: SUL !/Number of valid records: SUL !/#

files, number of records, exception records, good records,
in that order.
STATSBLK:

.LONG 4

;The value 4 is the number of statistic
;that we want,
we pass this value to
;the END.CONVERT routine.

STATS:

.BLKL 4

;Where we place the statistics.
This b
;must follow the longword that tells ho
;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,~M<R2,R3,R4,R5,R6,R7>

Perform operations.

;SAVE THOSE REGISTERS;

Push addresses on arg stack, call routines.

PUSHAL
CALLS

TIMES
#i,G~LIB$INIT_TIMER

PUSHAL
PUSHAL
PUSHAL
CALLS
BLBC

FDLFILE
FILEOUT
FILEIN
#3,G~CONV$PASS_FILES
RO,10$

PUSHAL
CALLS
BLBC

PARAM.LIST
#1,G~C0NV$PASS_0PTI0NS
RO,10$

;Push parameter list
;Make the second call

PUSHAL

STATSBLK

CALLS
BLBC

#1,G~C0NV$C0NVERT
RO,10$

;Pu8h address of the number
;Statistics
;Perform conversion

;Start the timer

;Push filenames on arg stack
;Pass filenames

need an FAO routine to format the count8
$FAOL_S CTRSTR=OUTSTUFF,0UTLEN=FA0_LEN,0UTBUF=FA0_DESC,PRMLST=STATS
RO,10$
BLBC
PUSHAL
CALLS

FAO.DESC
#1,G~LIB$PUT_OUTPUT

BLBC

RO,10$

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

(Continued

CONV—4

Display times
PUSHAL
CALLS
BLBC
MOVL

TIMES
#1,G~LIB$SHOW_TIMER
RO,10$
#SS$_N0RMAL,RO

RET
.END

CONV

The following example shows how to use the CONV$R
FORTRAN program.

Example CONV-3

*
*
*
*
*

Using the CONVERT/RECL
FORTRAN Program

This program calls the routine that performs th
function of the Convert/Reclaim Utility.
It
reclaims empty buckets from an indexed file nam
PR0L3.DAT.
It also returns all the CONVERT/REC
statistics.

Program declarations
IMPLICIT

*
*
*

INTEGER*4 (A - Z)

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

0UTSTATS(5) /4,0,0,0,0/

Declare the input file.
CHARACTER

IN_FILE*9 /'PR0L3.DAT'/

Call the routine.
STATUS * CONV$RECLAIM (IN.FILE, OUTSTATS)
IF (.NOT. STATUS) CALL LIB$ST0P (7,VAL(STATUS))

*
1000

Display the statistics.

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

The following example shows how to use the CONV$R
MACRO program.

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

.ASCID

Declare statistics blocks

OUTSTATS:

;

/PR0L3.DAT/

.LONG
.BLKL

4
4

Declare FAO info for statistics

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

!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,~M<>

Perform operations.
routines.
PUSHAL
PUSHAL
CALLS
BLBC

Push addresses on arg stack, call

OUTSTATS
FILEIN
#2,G~CONV$RECLAIM
RO,10$

;PUSH FILENAME ON ARG STACK
;PASS FILENAME

(Continued

CONV—6

Convert (CONV) Routines
Examples of Using the CONV Routines

Example CONV-4 (Cont.)

Using the CONVERT/RECLAIM
Routine in a MACRO Program

Now need an FAQ routine to format the counts.

BLBC

CTRSTR=OUTSTUFF,OUTLEN==FA0_LEN,0UTBUF=FA0_DESC,PRMLST=0UTSTATS+4
RO,10$

PUSHAL
CALLS

FAO.DESC
#1 ,G~LIB$PUT_OUTPUT

BLBC
MOVL
RET

RO,10$
#SS$_N0RMAL,RO

$FA0L_S

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

.END CONV

4.3

CONV Routines
The following pages describe the individual Convert routines in routine
template format.

CONV—7

Convert (CONV) Routines
CONV$CONVERT

CON V$CON VERT—Initiate Conversion
Invokes the Convert Utility to copy records from one or more
source data files to a second output data file, which can differ in
file organization and format from the first. The routine can also
return statistics about the conversion.

FORMAT

CONVSCONVERT

RETURNS

VMS Usage:
type:
access:
mechanism:

[status-block-address][.flags]

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

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 shown below:
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-file-spec argument is interpreted
and how errors are signalled. The flags argument is the address of a
longword containing control flags (or a mask). If the flags argument is
omitted or is specified as zero, no flags are set. The flags and their meanings
are described below.

CONV—8

Convert (CONV) Routines
CONV$CONVERT

Flag

Function

CONV$V_FDL_STRING

Interprets the fdl-file_spec argument supplied in the
call to CONV$PASS_FILES as an FDL specification in
string form. By default, this argument is interpreted
as a file name of an FDL 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

CONDITION
VALUES
RETURNED

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.

SSS—NORMAL

Normal successful completion.

CONV$_BADBLK

Invalid option block.

CONV$_BADLOGIC

Internal logic error detected.

CONVS—BADSORT

Error trying to sort input file.

CONV$_CLOSEIN

Error closing file specification as input.

CONV$_CLOSEOUT

Error closing file specification as output.

CONVS—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$_F AT ALEXC

Fatal exception encountered.

CONV$_FILLIM

Exceeded open file limit.

CONV$_IDX_LIM

Exceeded maximum index level.

CON V$_ILL _KEY

Illegal key or value out of range.

CONVS—INR_FILES

Too many input files.

CONV$_INSVIRMEM

Insufficient virtual memory.

CONVS—KEY

Invalid record key.

CONVS—LOADIDX

Error loading secondary index n.

CONV$_NARG

Wrong number of arguments.

CONVS—NOKEY

No such key.

CONVS—NOTIDX

File is not an indexed file.

CONVS—NOTSEQ

Output file is not a sequential file.

CONVS—NOWILD

No wildcard permitted.

CONVS—OPENEXC

Error opening exception file specification.

CONVS—OPENIN

Error opening file specification as input.

CONV—9

Convert (CONV) Routines
CONV$CONVERT

CONV—10

CONV$_OPENOUT

Error opening file specification as output.

CONV$_ORDER

Routine called out of order.

CONV$_PAD

PAD option ignored, output record format
not fixed.

CONV$_PROERR

Error reading prolog.

CONV$_PROI_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 will 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 (COIMV) Routines
CONV$PASS_FILES

COIMV$PASS_FILES—Specify Conversion
Files
Specifies the files on which CONVERT will operate.

FORMAT

CONV$PASS_FILES input-file-spec
, output-file-spec [, fdl-file-spec]
[, exception-file-spec] [, flags]

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

input- file-spec
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
by descriptor-fixed length string descriptor

The name of the file to be converted. The input-file-spec argument is the
address of a string descriptor pointing to the name of the file to be converted.

output-file-spec
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
by descriptor-fixed length string descriptor

The name of the file that receives the records from the input file. The outputfile-spec argument is the address of a string descriptor pointing to the name
of the file that receives the records from the input file.

fdl-file-spec
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
by descriptor-fixed length string descriptor

The name of the FDL file that defines the output file. The fdl-file-spec
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-file-spec
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
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-file-spec argument is the address of a string
descriptor pointing to this name.

flags
VMS Usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by reference

Flags (or masks) that control how the fdl-file-spec argument is interpreted and
how errors are signalled. The flags argument is the address of a longword
containing the control flags (or mask). If this argument is omitted or is
specified 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

CON V$ V_FDL _STRI NG

Interprets the fdl-file-spec argument as an FDL
specification in string form. By default, this argument
is interpreted as a file name of an FDL 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-file-spec argument for the
additional files, as follows:
status = CONV$PASSJFILES (input-file-spec)

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 (COIMV) Routines
CONV$PASS_FILES

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

CONV$_INP_FILES

Too many input files.

CONV$_INSVIRMEM

Insufficient virtual memory.

CONV$_NARG

Wrong number of arguments.

CONV$_ORDER

Routine called out of order.

CONV-13

Convert (CONV) Routines
CONV$PASS_OPTIONS

CON V$PASS—.OPTIONS—Specify
Processing
Options
Specifies the CONVERT qualifiers to be used.

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

parameter-list-address
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
longword (unsigned)
read only
by reference

A 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 following longword in the array (from the second one
on) is associated with one of the CONVERT qualifiers. These functions are
described in the VAX/VMS Convert and Convert/Reclaim Utility Reference

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 form /NOQUALIFIER on the
CONVERT command), you place a 0 in the correct longword.
If you do not specify parameter-list-address, then the default values shown
below 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 wish 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
reason is why the first longword contains a count of the qualifiers.
The qualifiers must appear in the following order.

CONV—14

Convert (COIMV) Routines
CONV$PASS_OPTIONS

Default Value
(in Longwords)

Default CONVERT
Value

CREATE

/CREATE

/NOSHARE

FAST_LOAD

/FAST_LOAD

MERGE

/NOMERGE

APPEND

/NOAPPEND

Qualifier

SORT

/SORT

WORK—FILES

/WORK—FILES=2

KEY

/KEY=0

PAD

/NOPAD

pad character

pad character^)

TRUNCATE

/NOTRUNCATE

EXIT

/NOEXIT

FIXED_CONTROL

/NOFIXED—CONTROL

FILL—BUCKETS

/NOFILL -BUCKETS

READ-CHECK

/NOREAD-CHECK

WRITE_CHECK

/NOWRITE-CHECK

FDL

/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 will return with a fatal exception status.
If you specified an FDL file specification in the CONV$PASS_FILES routine,
you must place a 2 in the FDL longword. If you have also specified an
exceptions file specification in the CONV$PASS_FILES routine, you must
place a 2 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, you will receive 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 . A 0 value means that you want to use the system or process prolog
type. A 2 value 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.
A 3 value 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-1 5

Convert (COIMV) Routines
CON V$PASS_OPTIONS

flags
VMS Usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by reference

Flags (or masks) that control how the fdl-file-spec 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 this argument is omitted
or is specified 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 below.
Flag

Function

CONV$V_FDL —STRING

Interprets the fdl-file-spec argument supplied in the
call to CONV$PASS_FILES as an FDL specification in
string form. By default, this argument is interpreted
as a 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
signalled.

DESCRIPTION

The following example shows how to invoke CONVERT with only the
qualifiers /FAST_LOAD /SORT /WORK_FILES=6 /EXIT. You must set up
an array of longwords with the values shown below:
A:

COIMV-16

Specifies that 12 longwords follow

Specifies the /NOCREATE option

Specifies the /NOSHARE option

Specifies the /FASTLOAD option

Specifies no /MERGE option

Specifies the /NOAPPEND option

Specifies the /SORT option

Specifies the /WORKFILES=6 option

Specifies the /KEY=0 option

Specifies the /NOPAD option

Specifies the null pad character

Specifies the /NOTRUNCATE option

Specifies the /EXIT option

Convert (COIMV) Routines
CONV$PASS_OPTIONS

CONDITION
VALUES
RETURNED

SS$_NORMAL
CONV$_BADBLK

Normal successful completion.

CONV$_CONFQUAL
CONV$_INSVIRMEM

Conflicting qualifiers.

CONV$_NARG

Wrong number of arguments.

CONV$_OPENEXC
CONV$_ORDER

Error opening exception file file-spec.

Invalid option block.
Insufficient virtual memory.

Routine called out of order.

CONV-17

Convert (CONV) Routines
CONVSRECLAIM

CONV$RECLAIM—CONVERT/Reclaim
Invokes the functions of the Convert/Reclaim Utility.

FORMAT

CONV$RECLAIM input-file-spec[,statistics—blk]

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

input-file-spec
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
by descriptor-fixed length string descriptor

The name of the Prolog 3 indexed file to be reclaimed. The input-file-spec
argument is the address of a string descriptor pointing to the name of the
Prolog 3 indexed file.

statistics—blk
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
longword (unsigned)
write only
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. The format of the statistics array is shown below:
A:

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

CONDITION
VALUES
RETURNED

CONV—18

SS$_NORMAL

Normal successful completion.

CONV$_BADLOGIC

Internal logic error detected.

CONV$_INSVIRMEM

Insufficient virtual memory.

CONV$_INVBKT

Invalid bucket at VBN n.

Convert (CONV) Routines
CONV$RECLAIM

CONV$_NOTIDX

File is not an index file.

CONV$_OPENIN

Error opening file-spec as input.

CONV$_PLV

Unsupported prolog version.

CONV$_PROERR

Error reading prolog.

CON V$_PROL _WRT

Prolog write error.

CONV$_READERR

Error reading file-spec.

CONV$_NOWILD

No wildcard permitted.

CONV$_WRITEERR

Error writing output file.

CONV—19

Data Compression/Expansion (DCX)
Routines

5.1

Introduction to DCX Routines
The set of routines described in this section comprises the VAX/VMS Data
Compression/Expansion (DCX) facility. There is no DCL-level interface to
this facility, nor is there a DCX Utility.
Using the DCX routines described in this section, a user can decrease the size
of any kind of data: text, binary data, images, and so on.
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 back 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 that expand the compressed records to their original state. In this process,
no information whatsoever is lost. A data record that has been compressed
and then expanded is in the same state 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 will have no need for this capability;
for these applications, there will be 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 which DCX routines are used to perform the step:
1

Analyzing some or all of the data records in the data file to produce a
mapping function (or map)
DCX$ AN ALYZE _INIT
DCX$ AN ALYZE _D ATA
DCX$M AKE _MAP
DCX$ AN ALYZE _DONE

2 Compressing 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
Introduction to DCX Routines

3 Expanding 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, for example, to LIB$GET_VM. If any of these RTL routines should
fail, a return status code indicating the cause of the failure is returned. In
such a case, the user must refer to the documentation of the appropriate RTL
routine to determine the cause of the failure. The status codes documented in
this section are primarily DCX status codes.

5.2

Example of Using the DCX Routines
The following example shows how to use the DCX routines in a VAX
FORTRAN program.

DCX—2

INTEGER STATUS.
2
IOSTAT,
2
IO.OK,
2
STATUS.OK
PARAMETER (I0_0K = 0)
PARAMETER (STATUS.OK = 1)
INCLUDE '($F0RDEF)'
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
! Logical end-of-file
LOGICAL EOF
! record buffers;
32767 is maximum record size
CHARACTER*32767 RECORD,
2
REC0RD2
INTEGER RECORD.LEN,
2
REC0RD2.LEN
! user routine
INTEGER GET.MAP,
2
WRITE.MAP

Data Compression /Expansion (DCX) Routines
Example of Using the DCX Routines

Example DCX-1

(Cont.)

Example of Compressing a File in a
VAX FORTRAN Program

! 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 (y.VAL(STATUS))
STATUS = LIB$GET_LUN (NORM.LUN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS))
OPEN (UNIT = NORM.LUN,
2
FILE = N0RM_NAME(1:N0RM_LEN),
2
CARRIAGECONTROL = 'NONE',
2
STATUS = 'OLD')

1 ************
! ANALYZE DATA

j ************

! initialize work area
STATUS = DCX$ANALYZE_INIT (CONTEXT)
IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS))
! get compression/expansion function (map)
STATUS = GET.MAP (NORM.LUN.
2
CONTEXT,
2
MAP,
2
MAP.LEN)
DO WHILE (STATUS .EQ. 7.L0C(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 (7.VAL(STATUS))
! clean up work area
STATUS = DCX$ANALYZE_DONE (CONTEXT)
IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS))

(Continued on next page)

DCX—4

Data Compression/Expansion (DCX) Routines
Example of Using the DCX Routines

Example DCX—1

(Cont.)

Example of Compressing a File in a
VAX FORTRAN Program

! *************
! COMPRESS DATA
i

*************

! 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 (7.VAL(STATUS))
STATUS = LIB$GET_INPUT (COMP.NAME,
2
'File for compressed records:
2
COMP.LEN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS))
OPEN (UNIT = COMP.LUN.
2
FILE = C0MP_NAME(1:COMP.LEN),
2
STATUS = 'NEW',
2
FORM = 'UNFORMATTED')
! initialize work area
STATUS = DCX$COMPRESS_INIT (CONTEXT.
2
MAP)
IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS))
! write compression/expansion function to new file
CALL WRITE.MAP (COMP.LUN.
2
7.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(1:RECORD.LEN)
IF (IOSTAT .NE. IO.OK) THEN
CALL ERRSNS (,...STATUS)
IF (STATUS .NE. FOR$_ENDDURREA) THEN
CALL LIB$SIGNAL (7.VAL (STATUS) )
ELSE
EOF = .TRUE.
STATUS = STATUS.OK
END IF
END IF

(Continued on next page)

DCX—5

Data Compression/Expansion (DCX) Routines
Example of Using the DCX Routines

Example DCX-1

(Cont.)

Example of 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),
2
REC0RD2,
2
REC0RD2.LEN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (*/.VAL(STATUS))
! write compressed record to new file
WRITE (UNIT = COMP.LUN) REC0RD2.LEN
WRITE (UNIT = COMP.LUN) REC0RD2 (1:REC0RD2.LEN)
! read from file to be compresses
READ (UNIT = NORM.LUN,
2
FMT = '(Q,A)',
2
IOSTAT = IOSTAT) RECORD.LEN,
2
RECORD (1:RECORD.LEN)
IF (IOSTAT .NE. IO.OK) THEN
CALL ERRSNS (,.,.STATUS)
IF (STATUS .NE. FOR$_ENDDURREA) THEN
CALL LIB$SIGNAL (y.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
! passed
INTEGER FUNCTION GET.MAP (LUN,
2
CONTEXT,
! passed
! returned
2
MAP.
! returned
2
MAP.LEN)
! Analyzes records in file opened on logical
! unit LUN and then attempts to create a
! compression/expansion function using
! DCX$MAKE_MAP.

(Continued on next page)

DCX—6

! logical unit number
INTEGER LUN
! compression/expan8ion function
INTEGER MAP,
2
MAP.LEN
! status variable
INTEGER STATUS.
2
IOSTAT,
2
IO.OK,
2
STATUS.OK
PARAMETER (IO.OK = 0)
PARAMETER (STATUS.OK = 1)
INCLUDE '($F0RDEF)'
! Logical end-of-file
LOGICAL EOF
! record buffer;
32767 is the maximum record size
CHARACTER*32767 RECORD
INTEGER RECORD.LEN
! library procedures
INTEGER DCX$ANALYZE_DATA,
2
DCX$MAKE_MAP
! analyze records
EOF = .FALSE.
READ (UNIT = LUN,
2
FMT = '(Q,A)',
2
IOSTAT = IOSTAT) RECORD.LEN,RECORD
IF (IOSTAT .NE. IO.OK) THEN
CALL ERRSNS (,,,.STATUS)
IF (STATUS .NE. FOR$_ENDDURREA) THEN
CALL LIB$SIGNAL (7.VAL(STATUS) )
ELSE
EOF * .TRUE.
STATUS = STATUS.OK
END IF
END IF

Data Compression/Expansion (DCX) Routines
Example of Using the DCX Routines

Example DCX-1

(Cont.)

Example of Compressing a File in a
VAX FORTRAN Program

DO WHILE (.NOT. EOF)
STATUS = DCX$ANALYZE_DATA (CONTEXT,
2
RECORD(1:RECORD_LEN))
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
READ (UNIT = LUN,
2
FMT = '(Q,A)',
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 = DCX$MAKE_MAP (CONTEXT,
MAP,
2
MAP.LEN)
2
GET.MAP = STATUS
END
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

DCX—8

Data Compression/Expansion (DCX) Routines
Example of Using the DCX Routines

Example DCX-2

Example of 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
! open file to expand
STATUS = LIB$GET_LUN (OLD.LUN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS))
STATUS = LIB$GET_INPUT (OLD.FILE,
2
'File to expand:
2
OLD.LEN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS))
OPEN (UNIT = OLD.LUN,
2
STATUS = 'OLD',
2
FILE = 0LD_FILE(1:0LD_LEN),
2
FORM = 'UNFORMATTED')
! open file to hold expanded data
STATUS = LIB$GET_LUN (NEW.LUN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS))
STATUS = LIB$GET_INPUT (NEW.FILE,
2
'File to hold expanded data:
2
NEW.LEN)
IF (.NOT. STATUS) CALL LIB$SIGNAL (7.VAL(STATUS))
OPEN (UNIT = NEW.LUN,
2
STATUS = 'NEW',
2
CARRIAGECONTROL = 'LIST',
2
FILE = NEW_FILE(1:NEW.LEN))

(Continued on next page)

DCX—9

! 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 (7.VAL(STATUS))
! expand records
CALL EXPAND.DATA (7.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 (7.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

! status variables
INTEGER STATUS.
2
IOSTAT,
2
IO.OK,
2
STATUS.OK
PARAMETER (IO.OK = 0)
PARAMETER (STATUS.OK = 1)
INCLUDE '($F0RDEF)1
! context variable
INTEGER CONTEXT
! logical end.of.file
LOGICAL EOF
! record buffers
CHARACTER*32767 RECORD,
2
REC0RD2
INTEGER RECORD.LEN,
2
REC0RD2.LEN

(Continued on n

DCX—10

Data Compression/Expansion (DCX) Routines
Example of Using the DCX Routines

Example DCX-2 (Cont.)

Example of Expanding a Compressed
File in a VAX FORTRAN Program

! library procedures
INTEGER DCX$EXPAND_INIT,
2
DCXlEXPAND.DATA,
2
DCX$EXPAND_DONE
! read data compression/expansion function
READ (UNIT = OLD.LUN) MAP
! initialize work area
STATUS = DCX$EXPAND_INIT (CONTEXT,
2
7,L0C(MAP(1) ) )
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 (7.VAL(STATUS) )
ELSE
EOF = .TRUE.
STATUS = STATUS.OK
END IF
END IF
DO WHILE (.NOT. EOF)
! read compressed record
READ (UNIT = OLD.LUN) RECORD (1:RECORD.LEN)
! expand record
STATUS = DCX$EXPAND_DATA (CONTEXT,
2
RECORD(1:RECORD.LEN),
2
REC0RD2,
2
REC0RD2.LEN)
IF (.NOT. STATUS) CALL LIBlSIGNAL OiVAL(STATUS))
! write expanded record to new file
WRITE (UNIT = NEW.LUN,
2
FMT = '(A)') REC0RD2(1:REC0RD2.LEN)
! 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. FORl.ENDDURREA) THEN
CALL LIBlSIGNAL (7.VAL(STATUS))
ELSE
EOF = .TRUE.
STATUS = STATUS.OK
END IF
END IF
END DO
! clean up work area
STATUS = DCXIEXPAND.DONE (CONTEXT)
IF (.NOT. STATUS) CALL LIBlSIGNAL (7.VAL(STATUS))
END

5.3

DCX Routines
The following pages describe the individual DCX routines in routine template
format.

DCX—11

Data Compression/Expansion (DCX) Routines
DCX$ANALYZE_DATA

DCX$AN ALYZE —DATA
Performs statistical analysis on a data record. The results of analysis
are accumulated internally in the context area and will be used by
the DCX$MAKE_MAP routine to compute the mapping function.

FORMAT

DCX$ANALYZE_DATA context,record

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)
read only
by reference

Value identifying the data stream which DCX$ AN ALYZE—DATA analyzes.
The context argument is the address of a longword containing this context
value. DCX$ANALYZE—INIT initializes this context; you should not modify
its value. Multiple context arguments may be defined to identify multiple
data streams which are processed simultaneously.

record
VMS Usage:
type:
access:
mechanism:

char—string
character string
read only
by descriptor

The record which is analyzed. DCX$ANALYZE_DATA reads the record
argument, which is the address of a descriptor for the record string.
Maximum length of the record string is 65535 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.
During analysis, the data compression facility gathers information that
DCX$MAKE—MAP will use to create the compression/expansion function
for the file. After the data records have been analyzed, the user calls the
DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status
code from DCX$MAKE_MAP, the user 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.

DCX—12

Data Compression/Expansion (DCX) Routines
DCX$ANALYZE_DATA

CONDITION
VALUES
RETURNED

DCX$_INVCTX

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.

Any condition values returned by LIB$ANALYZE_SDESC_R2.

DCX—13

Data Compression/Expansion (DCX) Routines
DCX$ANALYZE_DONE

DCX$AN ALYZE -DONE
Deletes the context area and sets to zero the context variable, thus
undoing the work of the DCX$ANALYZE_INIT routine. The user
calls 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
long word
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."

ARGUMENT

context
VMS Usage:
type:
access:
mechanism:

context
longword
write only
by reference

Value identifying the data stream which DCX$ AN ALYZE _DONE deletes.
The context argument is the address of a longword containing this context
value. DCX$ AN ALYZE _INIT initializes this context; you should not modify
its value. Multiple context arguments may be defined to identify multiple
data streams which are processed simultaneously.

DESCRIPTION

The DCX$ANALYZE—DONE routine deletes the context area and
sets to zero the context variable, thus undoing the work of the
DCX$ AN ALYZE _INIT routine. The user calls DCX$ AN ALYZE-DONE after
data records have been analyzed and the DCX$MAKE_MAP routine has
created the mapping function.

CONDITION
VALUES
RETURNED

DCX$_INVCTX

DCX$_NORMAL

Successful completion.

Any condition values returned by LIB$FREE_VM.

DCX—14

Data Compression/Expansion (DCX) Routines
DCX$ANALYZE_INIT

DCX$AN ALYZE _l N IT
Initializes the context area for a statistical analysis of the data
records to be compressed.

FORMAT

DCX$ANALYZE_INIT

context [,item-code
Jtem-value]

The second and third arguments are both optional but, if specified, must be
specified together. Further, this pair of arguments may be repeated, with
different values, in the same call.

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)
write only
by reference

Value identifying the data stream which DCX$ AN ALYZE _INIT initializes.
The context argument is the address of a longword containing this context
value. DCX$ AN ALYZE _INIT writes this context into the context argument;
you should not modify its value. Multiple context arguments may be defined
to identify multiple data streams which are processed simultaneously.

item-code
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

A symbolic code specifying information that the user wishes
DCX$ AN ALYZE—INIT to use in its analysis of data records and in its
computation of the mapping function. DCX$ AN ALYZE _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, the user must also
specify a corresponding item-value argument. The item-value contains
the interpretation of the item-code argument.
The following five symbolic names are the five legal values of the item-code
argument:
DCX$C_BOUNDED

DCX—15

Data Compression/Expansion (DCX) Routines
DCX$ANALYZE_INIT

DCX$C_EST_BYTES
DCX$C_EST_RECORDS
DCX$C_LIST
DCX$C_ONE —PASS

item-value
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

Value of the corresponding item-code argument. DCX$ANALYZE_JNIT
reads the item-value argument, which is the address of a longword
containing item-value.
Item-code and item-value 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 follow the "advice."
The following list shows, for each item-code argument, the possible values of
the corresponding item-value argument.

DCX—16

Item-code

Corresponding item-value

DCX$C_BOUNDED

A Boolean variable. If bit <0> is true (equals 1 ),
the user is stating his intention to submit for analysis
all data records that will be compressed; doing so will
often enable 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 the user's 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 the DCX$C_EST_BYTES
item code is not specified, DCX assumes that the
number of bytes presented for analysis is the number
of bytes that will be submitted for compression. Note
that the user may specify one of or both
DCX$C_EST_RECORDS and DCX$C_EST_BYTES.

DCX$C_EST_RECORDS

A longword value containing the user's 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 the
DCX$C_EST_RECORDS item code is not specified,
DCX assumes that the number of records presented
for analysis is the number of records that will be
submitted for compression.

Data Compression/Expansion (DCX) Routines
DCX$ANALYZE_INIT

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 a user 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 the
user's language has difficulty interpreting variablelength 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),
the user makes 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.

DESCRIPTION

The DCX$ANALYZE_JNIT 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.

CONDITION
VALUES
RETURNED

DCX$_INVITEM

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.

Any condition values returned by LIB$GET_VM.

DCX—17

Data Compression/Expansion (DCX) Routines
DCX$COMPRESS_DATA

DCX$COMPRESS_DATA
Compresses a data record. The user calls this routine for each data
record to be compressed.

FORMAT

DCX$COMPRESS_DATA

RETURNS

VMS Usage:
type:
access:
mechanism:

context ,'m-rec ,out-rec
[,out-length]

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)
read only
by reference

Value identifying the data stream which DCX$COMPRESS_DATA
compresses. The context argument is the address of a longword containing
this context. DCX$COMPRESS_INIT initializes the value; you should not
modify it. Multiple context arguments may be defined to identify multiple
data streams which are processed simultaneously.

in-rec
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The data record to be compressed. 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

The data record that has been compressed. The out-rec argument is the
address of the descriptor of the compressed record which
LIB$COMPRESS_DATA returns.

DCX—18

Data Compression/Expansion (DCX) Routines
DCX$CO M PR ESS-DATA

out-length
VMS Usage:
type:
access:
mechanism:

word_signed
word integer (signed)
write only
by reference

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

DESCRIPTION

The DCX$COMPRESS_DATA routine compresses a data record. The
user calls 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 the example.

CONDITION
VALUES
RETURNED

DCX$_INVCTX

DCX$_IN VD AT A

Error; the user has specified the item value
DCX$C_BOUNDED in the DCX$ANALYZE_INIT
routine and has 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$_INVMAP

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.

Any condition values returned by LIB$ANALYZE_SDESC_R2 and
LIB$SCOPY_R_DX.

DCX-19

Data Compression/Expansion (DCX) Routines
DCX$COMPRESS_DONE

DCX$COMPRESS_DONE
Deletes the context area and sets to zero the context variable, thus
undoing the work of the DCX$COMPRESS_INIT routine. The user
calls DCX$COMPRESS_DONE when all data records have been
compressed (using DCX$COMPRESS_DATA).

FORMAT

DCX$COMPRESS_DONE

RETURNS

VMS Usage:
type:
access:
mechanism:

context

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

ARGUMENT

context
VMS Usage:
type:
access:
mechanism:

context
longword (unsigned)
write only
by reference

Value identifying the data stream which DCX$COMPRESS_DONE deletes.
The context argument is the address of a longword containing this context
value. DCX$COMPRESS_JNIT writes the context into context; you should
not modify its value. Multiple context arguments may be defined to identify
multiple data streams which are processed simultaneously.

DESCRIPTION

The DCX$COMPRESS_DONE routine deletes the context area and sets to
zero the context variable, thus undoing the work of the DCX$COMPRESS_
INIT routine. The user calls 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.

CONDITION
VALUES
RETURNED

DCX$_INVCTX

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.

Any condition values returned by LIB$FREE_VM.

DCX—20

Data Compression/Expansion (DCX) Routines
DCX$COM PR ESS_I N IT

DCX$COMPRESS_INIT
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. 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)
write only
by reference

Value identifying the data stream which DCX$COMPRESS_INIT initializes.
The context argument is the address of a longword containing this context
value. You should not modify the context value after DCX$COMPRESS_INIT
initializes it. Multiple context arguments may be defined to identify multiple
data streams which 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 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.
The user calls the DCX$COMPRESS_INIT routine after the call to
DCX$ ANALYZE _DONE.

DCX—21

Data Compression/Expansion (DCX) Routines
DCX$COMPRESS_INIT

CONDITION
VALUES
RETURNED

DCX$_INVMAP

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

DCX$_NORMAL

Successful completion.

Any condition values returned by LIB$GET_VM and LIB$FREE_VM.

DCX—22

Data Compression/Expansion (DCX) Routines
DCX$ EXPAN D—DATA

DCX$EXP AN D_D AT A
Expands (or restores) a compressed data record to its original
state. The user calls this routine for each data record that is to be
expanded.

FORMAT

DCX$EXPAN D_DATA

RETURNS

VMS Usage:
type:
access:
mechanism:

context , in-rec, out-rec
[, out-length]

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)
read only
by reference

Value identifying the data stream which DCX$EXPAND_DATA expands. The
context argument is the address of a longword containing this context value.
DCX$EXPAND_INIT initializes this context; you should not modify its value.
Multiple context arguments may be defined to identify multiple data streams
which are processed simultaneously.

in-rec
VMS Usage:
type:
access:
mechanism:

char__string
character string
read only
by descriptor

The 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

The data record that has been expanded. The out-rec argument is the address
of the descriptor of the expanded record which DCX$EXPAND_DATA
returns.

DCX—23

Data Compression/Expansion (DCX) Routines
DCX$EXPAND_DATA

out-length
VMS Usage:
type:
access:
mechanism:

word—signed
word integer (signed)
write only
by reference

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

DESCRIPTION The DCX$EXPAND—DATA routine expands (or restores) a compressed data
record to its original state. The user calls this routine for each data record that
is to be expanded.

CONDITION
VALUES
RETURNED

DCX$_INVCTX

DCX$_IN VDAT A

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

DCX$_INVMAP

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.

Any condition values returned by LIB$ANALYZE—SDESC—R2 and
LIB$SCOPY_R_DX.

DCX—24

Data Compression/Expansion (DCX) Routines
DCX$EXPAND_DONE

DCX$EXPAND_DONE
Deletes the context area and sets to zero the context variable, thus
undoing the work of the DCX$EXPAND_INIT routine. The user calls
DCX$EXPAND_DONE when all data records have been expanded
(using DCX$EXPAND_DATA).

FORMAT

DCX$EXPAND_DONE

RETURNS

VMS Usage:
type:
access:
mechanism:

context

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

ARGUMENT

context
VMS Usage:
type:
access:
mechanism:

context
longword (unsigned)
write only
by reference

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

DESCRIPTION The DCX$EXPAND_DONE routine deletes the context area and sets to zero
the context variable, thus undoing the work of the DCX$EXPAND_INIT
routine. The user calls DCX$EXPAND_DONE when all data records have
been expanded (using DCX$EXPAND_DATA).

CONDITION
VALUES
RETURNED

DCX$_INVCTX

DCX$NORMAL

Successful completion.

Any condition values returned by LIB$FREE_VM.

DCX—25

Data Compression /Expansion (DCX) Routines
DCX$EXPAND_INIT

DCX$EXP AN D_l N IT
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. 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)
write only
by reference

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

map
VMS Usage:
type:
access:
mechanism:

address
longword (unsigned)
read only
by reference

DESCRIPTION

The DCX$EXPAND_INIT routine initializes the context area for the
expansion of data records.
The user calls the DCX$EXPAND_INIT routine as the first step in the
expansion (or restoration) of compressed data records to their original state.
Before calling 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.

DCX—26

Data Compression/Expansion (DCX) Routines
DCX$EXPAND_INIT

CONDITION

DCX$_INVMAP

Error; invalid map.

VALUES

DCX$_NORMAL

Successful completion.

RETURNED

Any condition values returned by LIB$GET_VM.

DCX—27

Data Compression/Expansion (DCX) Routines
DCX$MAKE_MAP

DCX$M AKE -MAP
Computes the mapping function, allocates a contiguous area of
memory (using the LIB$GET_VM routine) in which it stores the
compression/expansion function (or map), and returns the address
and (optionally) the size of the map.

FORMAT

DCX$MAKE_MAP context ,map-addr[,map-size]

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)
write only
by reference

Value identifying the data stream which DCX$MAKE_MAP maps. The
context argument is the address of a longword containing this context value.
DCX$ANALYZE_INIT initializes this context value; you should not modify it.
Multiple context arguments may be defined to identify multiple data streams
which are processed simultaneously.

map-addr
VMS Usage:
type:
access:
mechanism:

address
longword (unsigned)
write only
by reference

Starting address of the compression/expansion function (or map). The

map-addr is the address of a longword into which DCX$MAKE_MAP stores
the virtual address of the compression/expansion function.

map-size
VMS Usage:
type:
access:
mechanism:

longword_signed
longword (unsigned)
write only
by reference

The length of the compression/expansion function. The map-size 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—28

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.
This map is, in essence, 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, since the compressed
data records are indecipherable without the map. When compressed data
records have been expanded to their original state and further compression is
not desired, the user should delete the map using the LIB$FREE_VM routine.
DCX requires that the user submit data records for analysis and then call the
DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status code,
the user 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

DCXS—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$_INVCTX

DCX$_NORMAL

Successful completion.

VALUES
RETURNED

Any condition values returned by LIB$GET_VM and LIB$FREE_VM.

DCX—29

EDT Routines

6.1

Introduction to EDT Routines
EDT can be called on VAX/VMS operating systems by programs. 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 a user at the terminal
can edit a file while the program is running.
This section 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.
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.

Example of Using EDT Routines
The following VAX BASIC program 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
Example of Using EDT Routines

Example EDT-1

Using the EDT Routines in a VAX BASIC
Program

100
200
250
300
400

EXTERNAL INTEGER EDT$FILEIO O
EXTERNAL INTEGER EDT$W0RKI0
EXTERNAL INTEGER AXLATE
EXTERNAL INTEGER FUNCTION EDT$EDIT
DECLARE INTEGER RESULT

450
460
465
470
480
485

DIM INTEGER PASSFILE(1%)
©
DIM INTEGER PASSW0RK(1%)
DIM INTEGER PASSXLATE(iy.)
PASSFILE(OX) = L0C(EDT$FILEI0)
PASSW0RK(0%) = L0C(EDT$W0RKI0)
PASSXLATE(0%) = LOC(AXLATE)

500

RESULT = EDT$EDIT('FILE.BAS'. " .'EDTINI1,•',0%.
PASSFILE(0%)BY REF. PASSW0RK(0y.) BY REF. ©
PASSXLATE(0%) BY REF)
©
600 IF (RESULT AND 1%) * 0%
THEN
PRINT "SOMETHING WRONG"
CALL LIBtSTOP(RESULT BY VALUE)
900 PRINT "EVERYTHING O.K."
1000 END

© The external entry points EDT$FILEIO, EDT$WORKIO, and AXLATE are
defined so that they can be passed to callable EDT.
© Arrays are used to construct the two-longword structure needed for data
type BPV.
© 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.
© The array PASSFILE points to the entry point for all file I/O, which
is set up above to be the EDT supplied routine with the entry point
EDT$FILEIO. Similarly, the array PASSWORK points to the entry point
for all work I/O, which is the EDT supplied routine with the entry point
EDT$WORKIO.
© PASSXLATE points to the entry point that will be used by EDT 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 in routine template
format.

EDT—2

EDT Routines
EDTSEDIT

EDT$EDIT —Edit a File
Invokes the EDT editor.

FORMAT

EDT$EDIT in—file [,out—file][,com—file][,jou—file]
[, options] [, fileio] [, workio] [,xlate]

RETURNS

VMS Usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

The Condition Values Returned can indicate: (1) a successful completion, (2)
a termination caused by an internal EDT error, or (3) a termination caused
by problems in one of the procedures, fileio or workio.

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 start-up 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:
type:
access:
mechanism:

char-string
character-coded text string
read only
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 uses the same file name as in_file.

options
VMS Usage:
type:
access:
mechanism:

mask_Jongword
aligned bit string
read only
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. Once the journal
file commands have been processed, editing continues
normally. If bit <0> is set, the fileio routine will
be asked to open the journal file for both input and
output; otherwise fileio will only be asked 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 start¬
up command file cannot be opened. When bit
< 1 > is 0 , EDT will intercept the signal from the
fileio routine indicating that the start-up command
file could not be opened. Then, EDT will simply
proceed with the editing session, without reading
any start-up command file. If no command file name
is supplied with the call to the EDTSEDIT routine,
EDT tries to open SYS$LIBRARY:EDTSYS.EDT or, if
that fails, EDTINI.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 since 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$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 Routines
EDT$EDIT

EDT$M_NOCOMMAND

If set, bit <4> prevents EDT from opening a start¬
up 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$_INPFILNEX.

fileio
VMS Usage:
type:
access:
mechanism:

vector_longword—unsigned
bound procedure value
function call
by reference

User-supplied routine that is called by EDT to perform file I/O 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 I/O, either
use the entry point EDT$FILEIO for this argument or omit it. When you only
need to intercept some amount of file I/O, 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 provided by the user.
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 simply 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:
type:
access:
mechanism:

vector_longword_unsigned
bound procedure value
function call
by reference

User-supplied routine that is called by EDT to perform I/O 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 the user does not need to
intercept work file I/O, you can use the entry point EDT$WORKIO for this
argument or it can be omitted.
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 will load 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 simply 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

xlate
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
bound procedure value
function call
by reference

User-supplied routine that EDT calls when it encounters the nokeypad
command XLATE. The xlate argument is the address of a bound procedure
value containing the user-supplied routine. XLATE allows you to gain control
of your EDT session. If you do not need to have control of EDT during the
editing session, you can use the entry point EDT$XLATE for this argument or
you can 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 will load R1 with the second
longword addressed before calling it. If EDT$XLATE is used for this
argument, set the second longword to 0 . You can simply pass a 0 for
this argument, and EDT will set up EDT$XLATE as the default and set the
environment word to 0 .

DESCRIPTION

If the EDT session is terminated by EXIT or QUIT, the status will be a
successful 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 xlate
are the entry point names of user-supplied routines.

CONDITION
VALUES
RETURNED

EDT—6

SS$_NORMAL

Successful completion

EDT$_INPFILNEX

/NOCREATE specified and input file does not exit

Any condition values returned by user-supplied routines.

EDT Routines
FILEIO

FILEIO
Is a user-supplied routine that performs file I/O functions. It cannot
be independently called and is called specifying it as an argument in
the EDT$EDIT routine.

FORMAT

FILEIO code,stream,record,rhb

RETURNS

VMS Usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

A VAX/VMS status code that the user's 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 VAX RMS errors are signaled, not returned. The VAX 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. The valid function codes follow.
EDT$K_OPEN_INPUT

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

EDT$K_OPEN_OUTPUT_SEQ

The record argument names a file that is 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 that is to
be opened for output. The rhb argument is
the default file name.

EDT$K_OPEN_IN_OUT

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

EDT—7

EDT Routines
FILEIO

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:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
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. The
valid codes are:

EDT—8

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

The journal file. If bit 0 of the options is set, it
is opened for both input and output and is read
completely. Otherwise, it is opened for output
only. Once it has been 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 the
EXIT command is given.

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.

EDT Routines
FILEIO

record
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
modify
by descriptor

An argument that is a line of text passed by descriptor from EDT to the usersupplied FILEIO routine. The record argument is the address of a descriptor
pointing to this argument. The code argument determines how the record
argument is used. 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.
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 RTL (Run-Time
Library) routine STR$COPY_DX.

rhb
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
modify
by descriptor

This argument also depends on the code argument. 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 will use only string descriptors that can be handled by the RTL routine
STR$COPY_DX.

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 only need to
intercept 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:
•

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 either 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 OFP
(output file parse) 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.

EDT—9

EDT Routines
FILEIO

CONDITION

SSS—NORMAL

Successful completion.

VALUES

EDT$_NONSTDFIL

File is not in standard text format.

RETURNED

RMS$_EOF

End of file on a GET.

EDT—10

EDT Routines
WORKIO

WORKIO
Is a user-supplied routine that is called by EDT when it needs
temporary storage for the file being edited. It cannot be
independently called and is called by specifying it as an argument in
the EDT$EDIT routine.

FORMAT

WORKIO

RETURNS

VMS Usage:
type:
access:
mechanism:

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

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

ARGUMENTS

code
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

An argument that refers to the operation to be performed. The code argument
is the address of a longword integer containing this argument. The valid
function codes are:
Function Code

Descriptors

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 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 write. 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:
type:
access:
mechanism:

longword_signed
longword integer (signed)
read only
by reference

This argument is not used for open or close calls. The recordno argument is
the address of a longword integer containing this argument. For EDT$K_GET
and EDT$K_PUT, this argument contains the number of the record to be read
or written. EDT always writes a record before reading that record.

record
VMS Usage:
type:
access:
mechanism:

char_string
character string
modify
by descriptor

This argument is not used for open or close calls. For read operations, record
contains the location of the record to be read. For write operations, record
tells where the record is to be written. This argument always refers to a
512-byte string during GET and PUT calls.

DESCRIPTION

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 it can be omitted.

CONDITION
VALUES
RETURNED

EDT—12

SSS—NORMAL

Successful completion.

EDT Routines
XLATE

XLATE
Is a user-supplied routine that EDT calls when it encounters the
nokeypad command XLATE. It cannot be independently called and
is called by specifying it as an argument in the EDT$EDIT routine.

FORMAT

XLATE

RETURNS

VMS Usage:
type:
access:
mechanism:

string
cond_value
longword (unsigned)
write only
by value

Longword value returned as a VAX/VMS status code. It is normally 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 will abort the current key execution and display the appropriate error
message.
Condition value 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 in its definition the
following command:
XLATEtext~Z

The text is passed by the string argument. The string argument will be one
that can be handled by the RTL (Run-Time Library) routine STR$COPY_DX.
This argument is also a text string returned to EDT. The string is made up of
nokeypad commands that EDT will 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.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Successful completion.

EDT—13

File Definition Language (FDL) Routines

7.1

Introduction to FDL Routines
This section describes the File Definition Language (FDL) routines. These
routines perform many of the functions of RMS File Definition Language.
The FDL$CREATE routine is the FDL routine most likely to be called from
a high-level 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 (populates) 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.

7.2

Examples of Using the FDL Routines
The following example shows how to use the FDL$CREATE routine in a
FORTRAN program.

FDL—1

♦
*
*

This program calls the FDL$CREATE routine.
It
creates an indexed output file named NEW_MASTER.DAT
from the specifications in the FD1 file named
INDEXED.FDL.
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.

♦

(A - Z)
IMPLICIT
INTEGERS
FDL$CREATE
EXTERNAL
LIB$GET_LUN,
CHARACTER
IN_FILE*11
/'INDEXED.FDL'/,
1
0UT_FILE*14
/'NEW.MASTER.DAT'/,
1
DEF_FILE*11
/'DEFAULT.FDL'/,
1
RES_FILE*50
0 0 0
INTEGERS
FIDBLK(3)
1 = 1
STATUS = FDL$CREATE (IN_FILE,OUT_FILE,
DEF.FILE,RES.FILE.FIDBLK,,)
IF (.NOT. STATUS) CALL LIB$ST0P C/,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) (RES.FILE)
WRITE (6,2000) (FIDBLK (I), 1*1,3)
1000

FORMAT

(IX.'The result filename is:

2000

FORMAT
1
1

(/IX,'FID-NUM:
lX.'FID-SEQ:
lX.'FID-RVN:

',A50)

'.15/.
',15/,
M5)

END

The following example shows how to use the FDL$PARSE and
FDL$RELEASE routines in a MACRO program.

FDL—2

This program calls the FDL utility routines FDL$PARSE an
FDLlRELEASE.
First, FDL$PARSE parses the FDL specificat
PART.FDL.
Then the data file named in PART.FDL is acces
using the primary key.
Last, the control blocks allocat
by FDL$PARSE are released by FDLlRELEASE.

MY.FAB:
MY.RAB:
FDL.FILE:
REC_SIZE=80
LF=10
REC.RESULT:
REC.BUFFER:
HEADING:

.TITLE

FDLEXAM

.PSECT

DATA,WRT,NOEXE

.LONG
.LONG
.ASCID

0
0
/PART.FDL/

;

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

Declare FDL fil

COLOR /<L

CODE

Declare the external routines
.EXTRN

FDL$PARSE, FDLlRELEASE

•

.ENTRY

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

; Set up entry ma
; Get set up for
; addresses to re
; FAB and RAB all
; FDLIPARSE

KEYO:

MOVL
MOVL
MOVL
MOVAB
I0PEN

; Move address of
MY.FAB,RIO
MY.RAB,R9
; Move address of
♦REC.SIZE,RABIW.USZ(R9)
REC.BUFFER,RABlL.UBF(R9)
FAB=(RIO)
; Open the file

BLBC
RO,ERROR
ICONNECT RAB=(R9)
RO.ERROR
BLBC
PUSHAQ
HEADING
#1,G~LIB$PUT_OUTPUT
CALLS
BLBC

;

Connect to the

;

Display the hea

RO.ERROR

GET.REC:

$GET
CMPL
BEQLU
BLBC
MOVZWL
PUSHAL
CALLS
BLBC
BRB

RAB=(R9)
; Get a record
; If not end of file.
#RMS$_EOF,RO
CLEAN
; continue
RO,ERROR
RAB$W_RSZ(R9),REC_RESULT ; Move a record into
; the buffer
REC.RESULT
; Display the record
#1,G~LIB$PUT_OUTPUT
RO.ERROR
; Get another record
GET.REC

CLEAN:

$CLOSE
BLBC
PUSHAL
PUSHAL
CALLS
BLBC
BRB

FAB=(RIO)
RO,ERROR
MY.RAB
MY.FAB
#2,G ~FDLlRELEASE
RO,ERROR
FINI

ERROR:

PUSHL
CALLS
$CLOSE

RO
#1,G~LIB$SIGNAL
FAB=(R10)

RAB.ERROR:

PUSHL
PUSHL
BRB

RAB$L_STV(R9)
RAB$L_STS(R9)
RMS.ERR

FAB.ERROR:

PUSHL
PUSHL

FAB$L_STV(RIO)
FAB$L_STS(RIO)

RMS.ERR:

CALLS
BRB

#2,G~LIB$SIGNAL
FINI

FINI:

RET
.END FDLEXAM

; Close the FAB
; Push RAB addr on stack
; Push FAB addr on stack
; Release control blocks

The following example shows how to use the FDL$GENERATE routi
VAX PASCAL program.

FDL—4

File Definition Language (FDL) Routines
Examples of Using the FDL Routines

Example FDL—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.FDL) for FDL$PARSE to parse.

*)
*)
*)
*)
*)

TYPE

(*+
(* FDL CALL INTERFACE CONTROL FLAGS
(*-

*)
*)
*)

$BIT1 = [BIT(1).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 : [P0S(1)] $BIT1;
(* Main FDL spec is a char string
FDL$V_DEFAULT_STRING : [P0S(2)] $BIT1;
(* Default FDL spec is a char string
FDL$V_FULL.OUTPUT : [P0S(3)] $BIT1;
(* Produce a complete FDL spec
FDL$V_$CALLBACK : [P0S(4)] $BIT1;
(* Used by EDIT/FDL on input (DEC only)

*)
*)
*)
*)
*)

)
END;
mail_order =

RECORD
order.num : [KEY(0)] INTEGER;
name : PACKED ARRAY[1..20] OF CHAR;
address : PACKED ARRAY[i..20] OF CHAR;
city : PACKED ARRAY[1..19] OF CHAR;
state ; PACKED ARRAY[1..2] OF CHAR;
zip.code : [KEY(l)] PACKED ARRAY[1..5]
OF CHAR;
item.num : [KEY(2)] INTEGER:
shipping : REAL;
END;

order.file = [UNSAFE] FILE OF mail.order;
ptr.to.FAB = ~FAB$TYPE;
ptr.to.RAB = “RAB$TYPE;
byte = 0..255;

(Continued on next page)

FDL—5

File Definition Language (FDL) Routines
Examples of Using the FDL Routines

Example FDL-3 (Cont.)

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

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
(y.STDESCR FDL.FILE

PACKED

OF CHAR;
VAR FAB.PTR : PTR_T0_FAB;
VAR RAB.PTR : PTR.TO.RAB)

ARRAY [L..U:INTEGER]

INTEGER; EXTERN;

FUNCTION FDL$GENERATE
OiREF FLAGS : FDL2$TYPE;
FAB.PTR : PTR.TO.FAB;
RAB.PTR : PTR.TO.RAB;
XSTDESCR FDL.FILE.DST : PACKED ARRAY [L..U:INTEGER]
OF CHAR) : INTEGER;
EXTERN;
BEGIN
status := FDL$PARSE ('TESTING',TEMP_FAB,TEMP.RAB);
flags::byte := 0;
status

FDL$GENERATE (flags.
temp.FAB,
temp.RAB,
'SYS$OUTPUT:

);

END.

7.3

FDL Routines
The following pages describe the individual FDL routines in routine template
format.

FDL—6

File Definition Language (FDL) Routines
FDL$CREATE

FDL$CREATE—Create
Creates a file from an FDL specification and then closes the file.

FORMAT

FDL$CREATE fdl—desc [,file—name][,default—name]
[,result—name] [, fid—block] [, flags]
[, stmnt—num] [,retlen] [, sts] [, stv]

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

fdl—desc
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
by descriptor-fixed length string descriptor

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

file—name
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
by descriptor-fixed length string descriptor

The name of the VAX RMS file to be created using the FDL specification. The
file—name argument is the address of a character string descriptor pointing to
the VAX RMS file name. This name overrides the default—name parameter
given in the FDL specification.
This argument is optional.

FDL—7

File Definition Language (FDL) Routines
FDL$CREATE

default-name
char_string
character-coded text string
read only
by descriptor-fixed length string descriptor

VMS Usage:
type:
access:
mechanism:

The 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.
This argument is optional.

result—name
char—string
character-coded text string
write only
by descriptor-fixed length string descriptor

VMS Usage:
type:
access:
mechanism:

The 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:
type:
access:
mechanism:

vector—longword—unsigned
longword (unsigned)
write only
by reference

The file identification of the VAX RMS file created by FDL$CREATE. The
fid—block argument is the address of an array of longwords that receives
the VAX RMS file identification information. The first longword contains the
FID—NUM, the second contains the FID_SEQ, and the third contains the
FID—RVN. Their meanings are as follows:
FID—NUM

is 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

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

FID—RVN

is 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:
type:
access:
mechanism:

mask—longword
longword (unsigned)
read only
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 this argument is omitted or is
specified as zero, no flags are set. The flags and their meanings are described
below.

FDL—8

File Definition Language (FDL) 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:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
write only
by reference

The 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 'Tines."
This argument is optional.

retlen
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
write only
by reference

The 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:
type:
access:
mechanism:

longword—unsigned
longword—unsigned
write only
by reference

The VAX RMS status value FAB$L_STS. The sts argument is the address
of a longword that receives the VAX RMS status value FAB$L_STS from
SYS$CREATE.

stv
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
write only
by reference

The VAX RMS status value FAB$L_STV. The stv argument is the address
of a longword that receives the VAX RMS status value FAB$L_STV from
SYSSCREATE.

FDL—9

File Definition Language (FDL) 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 VAX RMS file, and then closes it
without putting any data in it.
FDL$CREATE will not create the output file if an error status is either
returned or signaled. The return codes, which follow, are defined in the
modules $FDLDEF and $RMSDEF.

CONDITION
VALUES

SS$_NORMAL

Normal successful completion.

FDL$_ABKW

Ambiguous keyword in statement n.

RETURNED

fdl$_abprikw

Ambiguous primary keyword in statement n.

FDL$_BADLOGIC

Internal logic error detected.

FDL$_CLOSEIN

Error closing file specification as input.

FDL$_CLOSEOUT

Error closing file specification as output.

FDL$_CREATE

Error creating file specification.

FDL$_CREATED

File specification created.

FDL$_CREATED_STM

File specification has been created in stream
format.

FDL—10

FDL$_FDLERROR

Error parsing FDL file.

FDL$_ILL_ARG

Wrong number of arguments.

FDLS—INSVIREM

Insufficient virtual memory.

FDL$_INVBLK

Invalid VAX RMS control block at virtual address n.

FDL$_MULPRI

Multiple primary definition in statement n.

FDL$_OPENFDL

Error opening file specification.

FDL$_OPENIN

Error opening file specification as input.

FDL$_OPENOUT

Error opening file specification as output.

FDL$_OUT ORDER

Key or area primary defined out of order in
statement n.

FDL$_READERR

Error reading file specification.

FDL$_RFLOC

Unable to locate related file.

FDL$_SYNTAX

Syntax error in statement n.

FDL$_UNPRIKW

Unrecognized primary keyword in statement n.

FDL$_UNQUAKW

Unrecognized qualifier keyword in statement n.

FDL$_UNSECKW

Unrecognized secondary keyword in statement n.

FDL$_VALERR

Specified value is out of legal range.

FDL$_VALPRI

Value required on primary in statement n.

FDL$_WARNING

Parsed with warnings.

FDL$_WRITEERR

Error writing file specification.

RMS$_ACT

File activity precludes operation.

RMS$_CRE

ACP file create failed.

RMS$_CREATED

File was created, not opened.

RMSS—DNF

Directory not found.

File Definition Language (FDL) Routines
FDL$CREATE

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.

FDL—11

File Definition Language (FDL) Routines
FDL$GENERATE

FDL$GENERATE—Generate
Produces an FDL specification and writes it either to an FDL file or to
a character string.

FORMAT

FDL$GENERATE

RETURNS

VMS Usage:
type:
access:
mechanism:

flags ,fab—pointer jab—pointer
[, fdl—file—dst] [, fdl—file—resnam]
[, fdl—str—dst] [,bad—blk—addr]
[jetlen]

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

flags
VMS Usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by reference

Flags (or masks) that control how the fdl__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 this argument is omitted or is
specified as zero, no flags are set. The flags and their meanings are described
below.
Flag

Description

FDL$V_FDI_STRING

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

FDL$V_FULI_OUTPUT

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

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.

FDL—12

File Definition Language (FDL) Routines
FDL$GENERATE

fab—pointer
VMS Usage:
type:
access:
mechanism:

address
longword (unsigned)
read only
by reference

The VAX RMS file access block (FAB). The fab—pointer argument is the
address of a longword containing the address of an VAX RMS file access
block (FAB).

rab—pointer
VMS Usage:
type:
access:
mechanism:

address
longword (unsigned)
read only
by reference

The VAX RMS record access block (RAB). The rab_pointer argument is the
address of a longword containing the address of an VAX RMS record access
block (RAB).

fdl—file—dst
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
by descriptor

The 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:
type:
access:
mechanism:

char_string
character-coded text string
write only
by descriptor-fixed length string descriptor

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

fdlstr—dst
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
write only
by descriptor-fixed length string descriptor

The 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—1 3

File Definition Language (FDL) Routines
FDL$GENERATE

bad—blk—addr
VMS Usage:
type:
access:
mechanism:

address
longword (unsigned)
write only
by reference

Address of an invalid VAX RMS control block. The bad—blk—addr argument
is the address of a longword that receives the address of an invalid VAX
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:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
write only
by reference

The 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
which receives this number.

CONDITION
VALUES
RETURNED

FDL—14

SS$_NORMAL

Normal successful completion.

FDL$_INVBLK

Invalid VAX RMS control block at virtual address n.

Rms$_act
RMSS—CONTROLC

Operation complete under CTRL/C.

RMS$_CONTROLO

Output completed under CTRL/O.

RMS$_CONTROLY

Operation completed under CTRL/Y.

RMSS—DNR

Device not ready or mounted.

RMSS—EXT

ACP file extend failed.

File activity precludes operation.

RMS$_OK_ALK

Record is already locked.

RMS$_OK_DUP

Record inserted had duplicate key.

RMS$_OK_IDX

Index update error occurred.

RMS$_PENDING

Asynchronous operation pending completion.

RMS$_PRV

Insufficient privilege or file protection violation.

RMSS—REX

Record already exists.

RMS$_RLK

Target record currently locked by another stream.

RMSS—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$_ILLSTRCLA

Illegal string class.

STR$_INSVIRMEM

Insufficient virtual memory.

File Definition Language (FDL) Routines
FDL$PARSE

FDL$PARSE—Parse
Parses an FDL specification, allocates VAX RMS control blocks
(FABs, RABs, or XABs), and fills in the relevant fields.

FORMAT

FDL$PARSE fdlspec ,fdl—fab—pointer
, fdl—rab—pointer [, flags] [, dflt—fdlspc]
[,stmnt—num]

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

fdlspec
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
by descriptor-fixed length string descriptor

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

fdl—fab—,pointer
VMS Usage:
type:
access:
mechanism:

address
longword (unsigned)
write only
by reference

Address of an RMS file access block (FAB). The fdl—fab_pointer argument is
the address of a longword which receives the address of an RMS file access
block (FAB). FDL$PARSE both allocates the FAB and fills in its relevant fields.

File Definition Language (FDL) Routines
FDL$PARSE

fdl—rab—pointer
VMS Usage:
type:
access:
mechanism:

address
longword (unsigned)
write only
by reference

Address of an RMS record access block (RAB). The fdl_rab_pointer
argument is the address of a longword which receives the address of an
RMS record access block (RAB). FDL$PARSE both allocates the RAB and fills
in its relevant fields.

flags
VMS Usage:
type:
access:
mechanism:

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 this argument is omitted or is specified as zero,
no flags are set. The flags and their meanings are described below.
Flag

Description

FDL$V_DEFAULT_STRING

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

FDL$V_FDI_STRING

Interprets the fdl_spec argument as an FDL
specification in string form. By default, the
fdl_spec argument is interpreted as a 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.

dflt—fdl—spc
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
by descriptor-fixed length string descriptor

The name of the default FDL file or the default FDL specification itself. The
dflt__fdl_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 interpets this argument as a file name of an FDL file.
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.
The FDL defaults can be coded directly into your program, typically with an
FDL specification in string form.

FDL—16

File Definition Language (FDL) Routines
FDL$PARSE

This argument is optional.

stmnt—num
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
write only
by reference

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

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

LIB$_BADBLOADR

Bad block address.

LIB$_BADBLOSIZ

Bad block size.

LIB$_INSVIRMEM

Insufficient virtual memory.

RMSS—DNF

Directory not found.

RMSS—DNR

Device not ready or mounted.

RMS$_WCC

Invalid wild card context (WCC) value.

FDL—17

File Definition Language (FDL) Routines
FDL$RELEASE

FDL$RELEASE—Release
Deallocates the virtual memory used by the VAX 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

RETURNS

VMS Usage:
type:
access:
mechanism:

[fab—pointer][,rab—pointer][,flags]
[, badblk—addr]

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

fab—pointer
VMS Usage:
type:
access:
mechanism:

address
longword (unsigned)
read only
by reference

The 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 NAM and XAB blocks connected
to the FAB are also released.
This argument is optional. If this argument is omitted or is specified 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

The 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 this argument is omitted or is specified as zero,
the RAB (and any associated XABs) is not released.

FDL—18

File Definition Language (FDL) Routines
FDL$RELEASE

flags
VMS Usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by reference

Flag (or mask) that controls how errors are signalled. The flags argument
is the address of a longword containing the control flag (or a mask). If this
argument is omitted or is specified as zero, no flag is set. The flag and its
meaning are described below.
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:
type:
access:
mechanism:

address
longword (unsigned)
write only
by reference

The address of an invalid VAX RMS control block. The badblk_addr
argument is the address of a longword which receives the address of an
invalid VAX RMS control block. If an invalid control block (a fatal error) is
detected, this argument is returned; otherwise, it is ignored.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

FDL$_INVBLK

Invalid VAX RMS control block at virtual address n.

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.

FDL—19

Librarian (LBR) Routines

8.1

Introduction to 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.
You can also create and maintain libraries at DCL level, using the DCL
command LIBRARY. For details, see the VAX/VMS DCL Dictionary.

8.1.1

Types of Libraries
You can use the librarian routines to maintain the following types of libraries:
•

Object libraries, which contain the object modules of frequently called
routines. The VAX/VMS Linker searches specified object module libraries
when it encounters a reference it cannot resolve in one of its input files.
For more information on how the linker uses libraries, see the description
of the VAX/VMS Linker Utility in the VAX/VMS Linker Reference 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 Volume for information on 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 VAX/VMS Librarian Reference 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. 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.

LBR—1

Librarian (LBR) Routines
Introduction to LBR Routines

•

Shareable image libraries, which contain the symbol tables of shareable
images used as input to the linker. For information on how to create a
shareable image library, see the descriptions of the librarian and linker
utilities in the VAX/VMS Linker Reference Manual and the VAX/VMS
Librarian Reference 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$OPEN 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$OPEN routine. When object, macro, text, help, or shareable image
libraries are created, the Library Utility structures them as described in
Figures LBR-1 and LBR-2. User-developed libraries can be created only by
calling LBR$OPEN; they are structured as described in Figure LBR-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. 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 LBR-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.
Object and shareable image libraries (see Figure LBR-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. Each index
consists of keys which point to the library's modules.

LBR-2

Librarian (LBR) Routines
Introduction to LBR Routines

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. The indexes in user-developed libraries are numbered by the user. 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 LBR-1

Structure of a Macro, Text, or Help Library

library header

index (module name table)

key-1

key-2

• • •

key-3

key-n

Each key in the index points to a module.

modules

header

data

ZK-187 1 -84

LBR—3

Librarian (LBR) Routines
Introduction to LBR Routines

Figure LBR-2

Structure of an Object or Shareable Image Library

library header

index (module name table)

key-1

• • •

key-3

key-2

key-n

Each key in the index points to a module.

index (global symbol table)

global
symbol

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

modules

header

data

ZK-1872-84

LBR—4

Librarian (LBR) Routines
Introduction to LBR Routines

Figure LBR—3

Structure of a User-Developed Library

library header

index

key

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.

index

key

Can have up to
8 indexes.

index

key

modules

header

data

ZK-1873-84

LBR—5

Librarian (LBR) Routines
Introduction to LBR Routines

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 VAX Procedure Calling and Condition
Handling Standard, which is documented in the Introduction to VAX/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 routines, the linker locates the routines during its default search
of SYS$SHARE:LBRSHR.
The librarian routines are described in detail in Section 3. Following are a list
of the routines and a summary of their functions.

LBR—6

Routine name

Function

LBR$CLOSE

Closes an open library

LBR$DELETE_DAT A

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 which was returned
by a preceding call to LBR$LOOKUP_KEY

LBRSFLUSH

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
user-supplied 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$INI_CONTROL

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

LBR$INSERT_KEY

Inserts a new key in the current library index

LBR$LOOKUP_KEY

Looks up a key in the current index

LBRSOPEN

Opens an existing library or creates a new one

LBR$OUTPUT_HELP

Retrieves help text from an explicitly named library
or from user-supplied default libraries, and optionally
prompts the user 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 VAX RMS status value

Librarian (LBR) Routines
Introduction to LBR Routines

8.2

Routine name

Function

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

Examples of Using the LBR Routines
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 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$OPEN before calling any other routine (except
LBR$OUTPUT_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$OPEN 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 wish 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$OPEN 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 will first need to access a key that points to it, and to delete a module
you will 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
the pair (* *) is a comment), and each listing is followed by notes about the
program. The circled numbers in the notes are keyed to the circled numbers
in the examples.

LBR—7

(♦This program creates a text library*)
(*Data type of*)
Create.Array * ARRAY [1..20] OF INTEGER;
(*create options array*)
VAR
(*Constants and return status err
codes for LBRl.OPEN & LBR$INI.CON
These are defined in SLBRDEF mac
LBR$C_CREATE,LBR$C_TYP_TXT,LBR$_ILLCREOPT,LBR$_ILLCTL,
LBR$_ILLFMT,LBR$_NOFILNAM,LBR$_OLDMISMCH,LBR$_TYPMISMCH :
[EXTERNAL] INTEGER;
(♦Create options array codes.
T
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;
(♦Name of library to create*)
Lib.Name : VARYING [128] OF CHAR;
Options : Create_Array;
(♦Create options array*)
(♦Character string that is defau
File.Type : PACKED ARRAY [1..4]
OF CHAR := '.TLB';
(♦file type of created lib file
(♦Value returned in library init*
lib_index_ptr : UNSIGNED;
(♦Return Status for function call
status : UNSIGNED;
Definitions-*-*-*-*)
(♦-♦-♦-♦-Function and Procedu
(♦Function that returns library
control index used by librarian*)
TYPE

FUNCTION LBRIINI.CONTROL (VAR library.index: UNSIGNED;
©
func: UNSIGNED;
typ: UNSIGNED;
VAR namblk: ARRAY[1..u:INTEGER]
OF INTEGER := 7.IMMED 0):
INTEGER; EXTERN;
(♦Function that creates/opens lib
FUNCTION LBRIOPEN
(library.index: UNSIGNED;
fns: [class.s]PACKED ARRAY[1..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 : = 7.IMMED 0;
rns: [CLASS.S] PACKED ARRAY [15..u5:INTEGER] OF CHAR
'/,IMMED 0;
INTEGER;

VAR rnslen:
EXTERN;

INTEGER :* %IMMED 0):

(♦Function that closes library*)
FUNCTION LBRICLOSE (library.index: UNSIGNED):
INTEGER; EXTERN;
(♦Error handler to check error co
if open/create not successful*)

(Continued on

LBR—8

Librarian (LBR) Routines
Examples of Using the LBR Routines

Example LBR-1

(Cont.)

Creating A New Library Using VAX
PASCAL

PROCEDURE Open.Error;
©
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*)
WRITEOLibrary 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;
©
Options[IADDRESS(CRE$L_ALLOC) DIV 4
1]
:= 8;
Options[IADDRESS(CRE$L_IDXMAX) DIV 4
1] := 1;
Options[IADDRESS(CRE$L_ENTALL) DIV
+ 1] := 96;
Options[IADDRESS(CRE$L_LUHMAX) DIV
+ 1] := 20;
Options[IADDRESS(CRE$L_VERTYP) DIV
+ 1] := IADDRESS(CRE$C_VMSV3);
Options[IADDRESS(CRE$L_IDXOPT) DIV
+ 1] := IADDRESS(CRE$C_MACTXTCAS);
(♦Initialize library control 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*)
status := LBR$0PEN
(lib_index_ptr,
Lib_Name,
Options,
O
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*)

(Continued on next page)

LBR—9

Librarian (LBR) Routines
Examples of Using the LBR Routines

Example LBR-1

(Cont.)

Creating A New Library Using VAX
PASCAL

O 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.)
© To gain access to the CRE$ symbols, write a two-line MACRO program as
described in item 1, substituting $CREDEF for $LBRDEF.
© 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.
© Declare the procedure Open—Error, which is called in the executable
section if the librarian returns an error when LBR$OPEN 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.
© 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 the library type is text.
© Call LBR$OPEN to create and open the library; pass the Options array
initialized in item 5 to the librarian.
© If the call to LBR$OPEN was unsuccessful, call the procedure Open—Error
(see item 4) to determine the cause of the error.

LBR-10

Librarian (LBR) Routines
Examples of Using the LBR Routines

Example LBR-2

Inserting Module Into 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 ILBRDEF macro*)
LBR$_KEYNOTFND : [EXTERNAL] INTEGER;(*Error code for LBR$L00KUP_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*)
(t-t-t-t-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[1..u:INTEGER]
OF INTEGER := DIMMED 0):
INTEGER; EXTERN;
(♦Function that creates/opens library*)
FUNCTION LBR$0PEN
(library.index: UNSIGNED;
fns: [class.s]PACKED ARRAY[1..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 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$L00KUP_KEY (library.index: UNSIGNED;
key.name:[CLASS.S] PACKED ARRAY [1..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 [1..u:INTEGER] OF
CHAR;
txtrfa: Rfa.Ptr):
INTEGER; EXTERN;
(♦Function that writes data records*)

(Continued on next page)

LBR—11

Librarian (LBR) Routines
Examples of Using the LBR Routines

Example LBR-2

(Cont.)

Inserting Module Into Library Using
VAX PASCAL

FUNCTION LBR$PUT_RECORD (library.index: UNSIGNED;
(*to modules*)
textline:[CLASS.S] PACKED ARRAY [1..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.
IADDRESS(LBR$C_UPDATE),
(*Update access*)
IADDRESS(LBR$C_TYP_TXT));
(*Text library*)
IF NOT ODD(status) THEN
(*Check error status*)
WRITELNCInitialization 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*)
WRITELNCOpen Not Successful')
ELSE
(*Open was successful*)
BEGIN
(*I8 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
Examples of Using the LBR Routines

Example LBR-2

(Cont.)

Inserting Module Into Library Using
VAX PASCAL

(******if LBR$L00KUP_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
O
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
©
status := LBR$INSERT_KEY
(lib.index.ptr,
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*)

© Call LBR$INI—CONTROL, specifying that the function to be performed is
update, and the library type is text.
© Call LBR$LOOKUP_KEY to see whether the module to be inserted is
already in the library.
© The call to LBR$LOOKUP_KEY should fail with the status value
LBR$_KE YN OTFND.
© 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.
© Use LBR$INSERT_KEY to insert a key for the module into the current
index.

LBR—13

Librarian (LBR) Routines
Examples of Using the LBR Routines

Example LBR-3

Extracting Module From Library Using VAX
PASCAL

PROGRAM extractmod(INPUT,OUTPUT,Textout);
(♦This program extracts 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_C0NTR0L*)
LBR$C_TYP_TXT,
(♦Defined in $LBRDEF macro*)
(*RMS return status; defined in
RMS$_EOF : [EXTERNAL] INTEGER;
$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*)
Outtext : PACKED ARRAY [1..255] OF CHAR;
(*Extracted mod put here,*)
0uttext2 : 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 reed*)
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[1..u:INTEGER]
OF INTEGER
7.IMMED 0):
INTEGER; EXTERN;
(♦Function that creates/opens library*)
FUNCTION LBR$0PEN
(library.index: UNSIGNED;
fns: [class.s]PACKED ARRAY[1..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 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 an index*)
FUNCTION LBRILOOKUP.KEY (library.index: UNSIGNED;
key.name:[CLASS.S] PACKED ARRAY [1..u:INTEGER] OF
CHAR;
VAR txtrfa: Rfa.Ptr):
INTEGER; EXTERN;
(♦Function that retrieves records from modules*)
FUNCTION LBR$GET_RECORD (library.index: UNSIGNED;
var textline:[CLASS.S] PACKED ARRAY [1..u:INTEGER] OF
CHAR):
INTEGER;

(Continued on next page)

LBR—14

Librarian (LBR) Routines
Examples of Using the LBR Routines

Example LBR-3

(Cont.)

Extracting Module From Library Using
VAX PASCAL

EXTERN;
(♦Function that closes library*)
FUNCTION LBR$CL0SE (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
O
Outtext[i] := nullstring;
status := LBR$GET_RECORD
(lib.index.ptr,
Outtext);
IF NOT ODD(status) THEN
BEGIN
©
IF status = IADDRESS(RMS$_E0F) THEN
WRITELN('
RMS end of file')
END

(Continued on next page)

LBR—15

Librarian (LBR) Routines
Examples of Using the LBR Routines

Example LBR-3

(Cont.)

Extracting Module From Library Using
VAX PASCAL

ELSE
BEGIN
pos

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

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

O Call LBR$INI—CONTROL, specifying that the function to be performed is
update and the library type is text.
© Call LBR$LOOKUP_KEY to find the key that points to the module you
want to extract.
© Open an output file to receive the extracted module.
© Initialize the variable that is to receive the extracted records to null
characters.
© If the call to LBR$GET_RECORD fails, it should be because the end of the
file (module) was reached.
© The extracted record should consist only of the data up to the first null
character. Write that data to the output file.

LBR—16

Librarian (LBR) Routines
Examples of Using the LBR Routines

Example LBR-4

Deleting Module From 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.C0NTR0L*)
LBR$C_TYP_TXT,
(*Defined in $LBRDEF macro*)
LBR$_KEYNOTFND : [EXTERNAL] INTEGER;(*Error code for LBR$L00KUP_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[1..u:INTEGER]
OF INTEGER := '/.IMMED 0):
INTEGER; EXTERN;
(♦Function that creates/opens library*)
FUNCTION LBR$0PEN
(library.index: UNSIGNED;
fns: [class.s]PACKED ARRAY[1..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 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$L00KUP_KEY (library.index: UNSIGNED;
key.name:[CLASS.S] PACKED ARRAY [1..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 [1..u:INTEGER] OF
CHAR):
INTEGER;
EXTERN;

(Continued on next page)

LBR-17

Librarian (LBR) Routines
Examples of Using the LBR Routines

Example LBR-4

(Cont.)

Deleting Module From 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$CL0SE (library.index: UNSIGNED):
INTEGER; EXTERN;
BEGIN

(* *************** DECLARATIONS COMPLETE *************************
*************** MAIN PROGRAM BEGINS HERE ********************** *)
(♦ Get Library Name and Module to Delete *)
WRITE('Library Name: '); READLN(Lib.Name);
WRITE('Module Name:
'); READLN(Module.Name);
(♦Initialize lib lor 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*)
WRITELNCInitialization Failed')
ELSE
(*Initialization was successful*)
BEGIN
status := LBR$0PEN
(lib_index.ptr. (*0pen the library*)
Lib.Name);
IF NOT ODD(status) THEN
(*Check error status*)
WRITELNCOpen Not Successful')
ELSE
(*0pen was successful*)
BEGIN
©
(*Is module in the library?*)
status := LBRSLOOKUP.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*)
status := LBR$DELETE_DATA
(lib.index.ptr,
©
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*)

(Continued on next page)

Librarian (LBR) Routines
Examples of Using the LBR Routines

Example LBR-4

(Cont.)

Deleting Module From Library Using
VAX PASCAL

O Call LBR$INI—CONTROL, specifying that the function to be performed is
update and the library type is text.
© Call LBR$LOOKUP—KEY to find the key associated with the module you
want to delete.
© 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 will have
to call LBR$LOOKUP_KEY and LBR$DELETE —KEY for each of the keys.
O 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 in routine template
format.

LBR—19

Librarian (LBR) Routines
LBR$CLOSE

LBR$CLOSE—Close a Library
Closes an open library.

FORMAT

LBR$CLOSE

RETURNS

VMS Usage: cond_value
type:
iongword (unsigned)
access:
write only
mechanism: by value

library-index

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

ARGUMENT

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

DESCRIPTION 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 the library.

CONDITION
VALUES
RETURNED

LBR—20

LBR$_ILLCTL

The specified library control index is not valid.

LBR$_LIBNOTOPN

The specified library is not open.

Librarian (LBR) Routines
LBR$DELETE_DATA

LBR$DELETE_DATA—Delete a Module's
Data
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. 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

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

txtrfa
VMS Usage: vector—longword—unsigned
type:
longword (unsigned)
access:
read only
mechanism:
by reference
The record's file address (RFA) of the module header for the module you
want to delete. The txtrfa argument is the address of a 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 will delete the module header and
associated data records; otherwise, this routine returns the error
LBR$_STILLKE Y S.

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

The specified library control index is not valid.

LBR$_INVRFA

The specified RFA is not valid.

LBR$_LIBNOT OPN

The specified library is 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_KEY

LBR$DELETE_KEY—Delete a Key
Deletes a key from a library index.

FORMAT

LBR$DELETE_KEY library-index ,key-name

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

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

key-name
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The 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.
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 within the user-supplied routine specified
in LBR$SEARCH or LBR$GET_INDEX.

CONDITION
VALUES
RETURNED

LBR$_ILLCTL

The specified library control index is not valid.

LBR$_KEYNOTFND

The specified key has not been found.

LBR$_LIBNOT OPN

The specified library is not open.

LBR$_UPDURTRAV

The specified index update is not valid in a usersupplied routine specified in LBRSSEARCH or
LBR$GET_INDEX.

Note: In the key-name argument, two types of situations are described. One
description applies to libraries with ASCII keys, the other applies to
libraries with binary keys. Only one of the key-name arguments will
apply, depending upon the type of keys in the library. Disregard the
key-name argument which does not apply.

LBR—24

Librarian (LBR) Routines
LBR$FIND

LBR$FIND—Lookup a Module by its RFA
Sets the current internal read context for the specified library to the
library module specified.

FORMAT

LBR$FIND library-index,txtrfa

RETURNS

VMS Usage:
type:
access:
mechanism:

cond—value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return (by immediate value) a
condition value in RO. Condition values that can be returned by this routine
are listed under "CONDITION VALUES RETURNED."

ARGUMENTS

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

txtrfa
VMS Usage:
type:
access:
mechanism:

vector—longword—unsigned
longword (unsigned)
read only
by reference

The 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
that contains 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$_ILLCTL

The specified library control index is not valid.

LBR$_INVRFA

The specified RFA is not valid,

LBR$_LIBNOTOPN

The specified library is not open.

Librarian (LBR) Routines
LBR$FLUSH

LBR$FLUSH—Recover Virtual Memory
Writes blocks that have been modified back to the library file and
frees the virtual memory they had been using.

FORMAT

LBR$FLUSH library-index,block-type

RETURNS

VMS Usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return (by immediate value) a
condition value in RO. Condition values that can be returned by this routine
are listed under "CONDITION VALUES RETURNED."

ARGUMENTS

library-index
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

block-type
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by value

The extent of the flush operation. The block-type argument contains a
longword value that indicates how the flush operation proceeds. If you
specify LBR$C_FLUSHDATA, the data blocks will be flushed. If you specify
LBR$C_FLUSH ALL, first the data blocks and then the current library index
will be flushed.
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

The operation completed successfully.

LBR$_BADPARAM

A value passed to the LBRSFLUSH routine was
either out of range or an illegal value.

LBR$_WRITERR

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
Returns information from the library's header to the caller.

FORMAT

LBR$GET_HEADER library-index ,retary

RETURNS

VMS Usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return (by immediate value) a
condition value in RO. Condition values that can be returned by this routine
are listed under "CONDITION VALUES RETURNED."

ARGUMENTS

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI_CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

retary
VMS Usage: vector_longword—signed
longword (signed)
type:
write only
access:
mechanism:
by reference
An 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 follows (the symbols are defined by the
$LHIDEF macro in SYS$LIBRARY:STARLET.MLB.).
Offset in
Longwords

Symbolic Name

Contents

LHI$I_TYPE

Library type; see LBRSOPEN for possible
values

LHI$L_NINDEX

Number of indexes

LHI$L_MAJORID

Library format major identification

LHI$L_MINORID

Library format minor identification

LHI$T_LBRVER

ASCIC version of Librarian

LHI$L _CRED AT

Creation date/time

LBR—29

Librarian (LBR) Routines
LBR$GET_HEADER

Offset in
Longwords

Symbolic Name

Contents

LHI$I_UPDTIM

Date/time of last update

LHI$I_UPDHIS

VBN of start of update history

LHI$I_FREEVBN

First logically deleted block

LHlSl_FREEBLK

Number of deleted blocks

LHI$B_NEXTRFA

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

LHI$I_NEXTVBN

Next VBN to allocate at end of file

LHI$I_FREIDXBLK

Number of free preallocated index blocks

LHI$I_FREEIDX

Listhead for preallocated index blocks

LHI$I_HIPREAL

VBN of highest preallocated block

LHI$L_IDXBLKS

Number of index blocks in use

LHI$I_IDXCNT

Number of index entries (total)

LHISL _MODCNT

Number of entries in index 1 (module
names)

LHI$L _MHDUSZ

Number of bytes of additional information
reserved in module header

LHI$L_MAXLUHREC

Maximum number of library update
history records maintained

LHlSl_NUMLUHREC

Number of library update history records
in history

LHI$I_LIBST ATUS

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

32-128

DESCRIPTION

Reserved to 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$_LIBNOT OPN

The specified library is not open.

LBR$_ILLCTL

The specified library control index is not valid.

Librarian (LBR) Routines
LBR$GET_HELP

LBR$GET_.HELP—Retrieve Help Text
Retrieves help text from a help library, displaying it on
SYS$OUTPUT or calling your routine for each record returned.
Note that most application programs will use LBR$OUTPUT_HELP
instead of LBR$GET_HELP.

FORMAT

LBR$GET_HELP library-index[,line-width][,routine]
[,data][,key-1][,key-2... ,key-10]
If the key-1 descriptor is 0, or if it is not present, LBR$GET_HELP will
assume 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 will terminate the list.

RETURNS

VMS Usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return (by immediate value) a
condition value in R0. Condition values that can be returned by this routine
are listed under "CONDITION VALUES RETURNED."

ARGUMENTS

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

line-width
VMS Usage:
type:
access:
mechanism:

longword—signed
longword (signed)
read only
by reference

The width of the help text line. The line-width argument is the address of
a longword that contains 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.

LBR—31

Librarian (LBR) Routines
LBR$GET_HELP

routine
VMS Usage:
type:
access:
mechanism:

procedure
procedure entry mask
read only
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$OUTPUT). However, if you want
SYS$OUTPUT for your program to be a disk file, rather than the terminal, it
is recommended that you supply a routine to output the text.
The routine that you specify will be called with an argument list of four
longwords:
1

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

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

The specified help text cannot be found.

HLP$M_KEYNAMLIN

The text contains the key names of the printed
text.

HLP$M_OTHERINFO

The 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 being passed.
3

The third argument is the address specified 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 that 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:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
write only
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 will be 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.

LBR—32

Librarian (LBR) Routines
LBR$GET_HELP

key-1,key-2,...,key-10
VMS Usage: longword—signed
longword (signed)
type:
read only
access:
mechanism:
by descriptor
The level of the help text to be output. Each key-l,key-2,...,key-10 argument
is the address of a descriptor pointing to the key for that level.
If the key-1 descriptor is 0 or if it is not present, LBR$GET_HELP will assume
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 will terminate the list.
The key argument may contain any of the following special character strings:
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

DESCRIPTION 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. (Note that, 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.

CONDITION
VALUES
RETURNED

LBRS—ILLCTL

The specified library control index is not valid.

LBR$_LIBNOTOPN

The specified library is not open.

LBR$_NOTHLPLIB

The specified library is not a help library.

LBR—33

Librarian (LBR) Routines
LBR$GET_HISTORY

LBR$GET_-HISTORY—Retrieve a Library
Update History
Record
Returns each library update history record to a user-specified action
routine.

FORMAT

LBR$GET_HISTORY library-index,action-routine

RETURNS

VMS Usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return (by immediate value) a
condition value in RO. Condition values that can be returned by this routine
are listed under "CONDITION VALUES RETURNED."

ARGUMENTS

library-index
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI_CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

action-routine
VMS Usage:
type:
access:
mechanism:

procedure
procedure entry mask
modify
by reference

A 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: the address of a
descriptor pointing to a history record.

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

LBR—34

Librarian (LBR) Routines
LBR$GET_HISTORY

CONDITION
VALUES
RETURNED

LBR$_NORMAL

A normal exit from the routine occurred.

LBR$_EMPTYHIST

The history is empty. This is an informational
code, not an error code

LBR$_NOHISTORY

This library does not have an update history. This
is an informational code, not an error code

LBR$_INTRNLERR

An internal librarian routine error occurred.

LBR—35

Librarian (LBR) Routines
LBR$GET_INDEX

LBR$GET_.INDEX—Call a Routine for
Selected Index Keys
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. All utility routines return (by immediate value) a
condition value in RO. Condition values that can be returned by this routine
are listed under "CONDITION VALUES RETURNED."

ARGUMENTS

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

index-number
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
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:
type:
access:
mechanism:

procedure
procedure entry mask
read only
by reference

Routine called for each of the specified index keys. The routine-name
argument is the address of the entry mask for this user-supplied routine.

LBR—36

Librarian (LBR) Routines
LBR$GET_INDEX

LBR$GET_INDEX passes two arguments to the routine:
1

A key-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.

2 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:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The key matching identifier. The match-desc argument is the address of a
string descriptor pointing to a string which is used to identify which keys will
result in calls to the user-supplied routine. Wildcard characters are allowed
in this string. If this argument is omitted, the routine is called for every key
in the index. The match-desc argument is valid only for libraries that have
ASCII keys.

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 the match-desc argument is not
specified, 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 will call
routine-name for each module whose name begins with TR.

CONDITION
VALUES
RETURNED

LBR$_ILLCTL

The specified library control index is not valid,

LBR$_ILLIDXNUM

The specified index number is not valid,

LBR$_LIBNOTOPN

The specified library is not open,

LBR$_NULIDX

The specified library is empty.

LBR—37

Librarian (LBR) Routines
LBR$GET_RECORD

LBR$GET_.RECORD—Read a Data Record
Returns the next data record in the module associated with a
specified key.

FORMAT

RETURNS

LBR$GET_RECORD

VMS Usage:
type:
access:
mechanism:

library-index[Jnbufdes]
[r outbufdes]

cond—value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return (by immediate value) a
condition value in RO. Condition values that can be returned by this routine
are listed under "CONDITION VALUES RETURNED."

ARGUMENTS

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a 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.

inbufdes
VMS Usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

A user buffer to receive the record. The inbufdes argument is the address of
a string descriptor that points to the buffer that will receive 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
below contains a description of the locate and move modes.

outbufdes
VMS Usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

A string descriptor that receives the actual length and address of the data
for the record returned. The outbufdes argument is the address of the string
descriptor for the returned record. The length and address fields of the string

LBR—38

Librarian (LBR) Routines
LBR$GET_RECORD

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 below contains a description of 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 user-specified
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. If locate 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$_ILLCTL

The specified library control index is not valid.

LBR$_LIBNOTOPN

The specified library is not open.

LBR$_LKPNOTDON

The requested key lookup has not been done.

RMS$_EOF

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

LBR—39

Librarian (LBR) Routines
LBR$INI_CONTROL

LBR$IIMI_COI\ITROL—Initialize a Library
Control Structure
Initializes a control structure, called a library control index, to identify
the library for use by other Librarian routines. You may have up to
16 libraries open simultaneously in your program.

FORMAT

LBR$INI_CONTROL library-index,func[,type]
[,namblk]

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

library-index
VMS Usage: longword—unsigned
longword (unsigned)
type:
write only
access:
by reference
mechanism:
The library control index returned by the LBR$INI_CONTROL routine. The
library-index argument is the address of a longword that will receive the
index.

func
VMS Usage:
type:
access:
mechanism:

function _code
longword (unsigned)
read only
by reference

The library function to be performed. The func argument is the address of a
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.)

type
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library type. The type argument is the address of a longword that
contains 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, for

LBR—40

Librarian (LBR) Routines
LBR$INI—CONTROL

user_developed libraries, a type in the range of LBR$C_TYP_USRLW
through LBR$C_TYP_USRHI.

namblk
VMS Usage:
type:
access:
mechanism:

nam
longword (unsigned)
read only
by reference

A VAX Record Management Services (VAX RMS) name (NAM) block. The
namblk argument is the address of a variable length data structure containing
an RMS NAM block. The LBR$OPEN 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$OPEN routine will
use the VAX 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 VAX RMS NAM blocks, see the
VAX Record Management Services Reference Manual.

DESCRIPTION Except for the LBR$OUTPUT_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$OPEN routine. You can then call other librarian routines
that you need. Once you have completed working with a library, close it with
the LBR$CLOSE routine.
LBR$INI_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.

CONDITION
VALUES
RETURNED

LBR$_NORMAL

The library control index was initialized
successfully.

LBR$_ILLFUNC

The requested function is not valid.

LBR$_ILLTYP

The specified library type is not valid.

LBR$_TOOMNYLIB

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

LBR—41

Librarian (LBR) Routines
LBR$INSERT_KEY

LBR$INSERT_KEY—Insert a New Key
Inserts a new key in the current library index.

FORMAT
RETURNS

LBR$INSERT_KEY

VMS Usage:
type:
access:
mechanism:

library-index,key-name ,txtrfa

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

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

key-name
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
write only
by reference

The 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

Write only

Mechanism

By descriptor

Librarian (LBR) Routines
LBR$INSERT_KEY

txtrfa
VMS Usage: vector_longword_unsigned
type:
longword (unsigned)
access:
modify
mechanism:
by reference
The record's 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
that contains the RFA. You can use the RFA returned by the first call to
LBR$PUT_RECORD.

DESCRIPTION

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

CONDITION
VALUES
RETURNED

LBR$_ILLCTL

The specified library control index is not valid.

LBR$_INVRFA

The specified RFA does not point to valid data.

LBR$_DUPKEY

The index already contains the specified key.

LBR$_LIBNOTOPN

The specified library is not open.

LBR$_UPDURTRAV

LBR$INSERT_KEY was called by the user-defined
routine specified in LBR$SEARCH or
LBR$GET_INDEX.

Note: In the key-name argument, only one of the two definitions will apply.

LBR—43

Librarian (LBR) Routines
LBR$LOOKUP_KEY

LBR$LOOKUP_KEY—Look Up a Library
Key
Looks up a key in the library’s current index, and prepares to access
the data in the module associated with the key.

FORMAT
RETURNS

LBR$LOOKUP_KEY

VMS Usage:
type:
access:
mechanism:

library-index,key-name, txtrfa

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

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

key-name
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The 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.
If the library uses ASCII keys, the key-name argument is the address of a
string descriptor for the key.

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 a 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$_JLLCTL

The specified library control index is not valid.

LBR$_INVRFA

The RFA obtained is not valid.

LBR$_KEYNOTFND

The specified key was not found.

LBR$_LIBNOTOPN

The specified library is not open.

Note: In the key-name argument, only one of the two descriptions applies,
depending upon whether the library has ASCII keys or binary keys.

LBR—45

Librarian (LBR) Routines
LBR$OPEN

LBR$OPEIM—Open or Create a Library
Opens an existing library or creates a new one.

FORMAT

LBR$OPEN library-index [, fns] [, create-options] [,dns]
[, rlfna] [,rns] [, rnslen]
The fns argument and the create-options argument are required in some
circumstances. See the descriptions of these arguments for more information.

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

library-index
VMS Usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism:
by reference
The library control index which was returned by the LBR$INI_CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

fns
VMS Usage:
type:
access:
mechanism:

char—string
character string
read only
by descriptor

The file specification of the library. The fns argument is the address of a
string descriptor that points to the file specification. Unless the VAX RMS
NAM block address was previously supplied in the LBR$INI—CONTROL
routine and it contained a file specification, this argument must be included.
Otherwise, the librarian returns an error (LBR$_NOFILNAM).

create-options
VMS Usage:
type:
access:
mechanism:

vector—longword—unsigned
longword (unsigned)
read only
by reference

The 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

LBR—46

Librarian (LBR) Routines
LBRSOPEN

entries that the array must contain (the $LBRDEF and $CREDEF macros in
SYS$LIBRARY:STARLET.MLB define the symbols listed):
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 to DIGITAL

LBR$C_TYP_USR (128-255)

User-defined

CRESI_KEYLEN

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

CRE$L _ALL0C

Initial library file allocation

CRESI_IDXMAX

Number of library indexes
(maximum of 8)

CRESI_UHDMAX

Number of additional bytes to
reserve in module header

CRESL-ENTALL

Number of index entries to
preallocate

CRESI_LUHMAX

Maximum number of library
update history records to
maintain

CRESL—VERTYP

Format of library to create:

CRE$C_VMSV2

VAX/VMS Version 2.0

CRE$C_VMSV3

VAX/VMS Version 3.0

9-20

CRESL-IDXOPT

Index key casing option:

CRESC—HLPCASING

Treat character case as it is for
help libraries

CRESC-OBJCASING

Treat character case as it is for
object libraries

CRESC—M ACTXTC AS

Treat character case as it is for
macro and text libraries
Reserved to DIGITAL

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

LBR—47

Librarian (LBR) Routines
LBR$OPEN

dns
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The default file specification. The dns argument is the address of a string
descriptor that points to the default file specification. See the VAX Record
Management Services Reference Manual for details about how defaults are
processed.

rlfna
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

The related file name. The rlfna argument is the address of a VAX 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
VAX Record Management Services Reference Manual for details on processing
related file names.

rns
VMS Usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

The resultant file specification returned. The rns argument is the address of a
string descriptor pointing to a buffer to receive the resultant file specification
string. If an error occurs during an attempt to open the library, the expanded
name string will be returned instead.

rnslen
VMS Usage:
type:
access:
mechanism:

longword—signed
longword (signed)
write only
by reference

The length of the resultant or expanded file name. The rnslen argument
is the address of a longword that receives 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

This routine must be called after you call LBR$INI—CONTROL and before
you call any other Librarian routine except LBR$OUTPUT-HELP.
When the library is successfully opened, the Librarian 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$OPEN will retry the open operation every second for a
maximum of 30 seconds before returning the VAX RMS error, RMS$_FLK, to
the caller.

LBR—48

Librarian (LBR) Routines
LBR$OPEN

CONDITION
VALUES
RETURNED

LBR$_OLDLIBRARY

The specified library has been opened; the library
was created with an old library format. This is a
success code.

LBR$_ERRCLOSE

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

The requested create options are not valid or not
supplied.

LBR$_ILLCTL

The specified library control index is not valid.

LBRS—ILLFMT

The specified library format is not valid.

LBR$_ILLFUNC

The specified library function is not valid.

LBR$_LIBOPN

The specified library is already open.

LBR$_NOFILNAM

The fns argument was not supplied or the VAX
RMS NAM block was not filled in.

LBR$_OLDMISMCH

The requested library function conflicts with the
old library type specified.

LBR$_TYPMISMCH

The library type does not match the requested
type.

LBR—49

Librarian (LBR) Routines
LBR$OUTPUT_HELP

LBR$OUTPUT_HELP—Output Help
Messages
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$OUTPUT_HELP to interact with a user
and continue to provide help information after the initial help request
has been satisfied.

FORMAT

LBR$OUTPUT_HELP output-routine [,output-width]
[Jine-desc] [,library-name]
[, flags] [,input-routine]

RETURNS

VMS Usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return (by immediate value) a
condition value in RO. Condition values that can be returned by this routine
are listed under "CONDITION VALUES RETURNED."

ARGUMENTS

output-routine
VMS Usage:
type:
access:
mechanism:

procedure
procedure entry mask
write only
by reference

The name of a routine that writes help text a line at a time. The outputroutine 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

The width of the help text line. The output-width argument is the address
of a longword that contains the width of the text line to be passed to the
user-supplied output routine. If output-width is omitted or 0, the default
output-width is 80 characters per line.

LBR—50

Librarian (LBR) Routines
LBR$OUTPUT_HELP

line-desc
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The 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:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The 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 use the default help libraries. If the
device and directory specifications are omitted, the default is SYS$HELP. The
default file type is HLB.

flags
VMS Usage:
type:
access:
mechanism:

mask-Jongword
longword (unsigned)
read only
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 this longword is omitted, 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$OUTPUT_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

LBR$OUTPUT_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$OPEN, are handled internally. You should
not call LBR$INI_CONTROL or LBR$OPEN before you issue a call to
LBR$OUTPUT_HELP.
LBR$OUTPUT_HELP accepts help keys in the same format as
LBR$GET_HELP, with the following qualifications:
1

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 if the 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 (/) 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$OUTPUT_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 user-defined 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$OUTPUT_HELP to search for help information not contained in the
root library. You do this by equating the logical names HLP$LIBRARY,
HLP$LIBRARY_1,...,HLP$LIBRARY_999 to the file specifications of the
default help libraries. These logical names can be defined in the process,
group, or system logical name tables.
If default library searching is enabled by the flags argument,
LBR$OUTPUT_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$OUTPUT_HELP returns to the root library and
issues a help not found message.
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.

LBR—52

Librarian (LBR) Routines
LBR$OUTPUT_HELP

You can encounter four different types of prompts 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.

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

3 If you are currently examining help for a particular topic (and subtopics), a
prompt of the form " < keyword... > subtopic?" is output.

4 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$OUTPUT_HELP in each prompting situation, are described below:
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$OUTPUT_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.

CTRL/Z

(1,2,3,4) Exit from LBR$OUTPUT_HELP.

1 Keyed to the prompt in the preceding list.

Librarian (LBR) Routines
LBR$OUTPUT_HELP

CONDITION
VALUES
RETURNED

LBR—54

LBR$_ILLINROU

The input routine was improperly specified or
omitted.

LBR$_ILLOUTROU

The output routine was improperly specified or
omitted.

LBR$_NOHLPLIS

No default help libraries can be opened.

LBR$_T OOMN Y ARG

Too many arguments were specified.

LBR$_USRINPERR

An error status was returned by the user-supplied
input routine.

Librarian (LBR) Routines
LBR$PUT_END

LBR$PUT_.END—Write an End-of-Module
Record
Marks the end of a sequence of records written to a library by the
LBR$PUT_RECORD routine.

FORMAT

LBR$PUT_END library-index

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

ARGUMENT

library-index
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI_CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

DESCRIPTION

CONDITION
VALUES
RETURNED

Call LBR$PUT_END after you have written 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$_ILLCTL

The specified library control index is not valid.

LBR$_LIBNOTOPN

The specified library is not open.

LBR—55

Librarian (LBR) Routines
LBR$PUT_HISTORY

LBR$PUT_.HISTORY—Write an Update
History Record
Adds an update history record to the end of the update history list.

FORMAT

LBR$PUT_HISTORY library-index ,record-desc

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

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

record-desc
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

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

DESCRIPTION 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$OPEN for details), the oldest
history record is deleted before the new record is added.

LBR—56

Librarian (LBR) Routines
LBR$PUT_HISTORY

CONDITION
VALUES
RETURNED

LBR$_NORMAL

A normal exit from the routine occurred.

LBR$_NOHIST ORY

This library does not have an update history. This
is an informational code, not an error code

LBRS—INTRNLERR

An internal Librarian error occurred.

LBR$_RECLNG

The record length was 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
Writes a data record beginning at the next free location in the library.

FORMAT

LBR$PUT_RECORD library-index ,bufdes txtrfa

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

library-index
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI_CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

bufdes
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The record to be written to the library. The bufdes argument is the address
of a string descriptor that points to the buffer containing the output record.

txtrfa
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
longword (unsigned)
write only
by descriptor

The record's file address (RFA) of the module header. The txtrfa argument is
the address of a 2-longword array that receives 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$_ILLCTL

The specified library control index is not valid.

LBR$_LIBNOTOPN

The specified library is not open.

LBR—59

Librarian (LBR) Routines
LBR$REPLACE_KEY

LBR$R EPLACE _KEY—Replace a Library
Key
Inserts a key in an index by changing the pointer associated with an
existing key, or by inserting a new key.

FORMAT

LBR$REPI_ACE_KEY library-index ,key-name,oldrfa
,newrfa

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

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

key-name
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The library key. The key-name argument is the address of a string descriptor
for the key (for libraries with ASCII keys).

key-name
VMS Usage: longword—unsigned
type:
longword (unsigned)
access:
read only
mechanism:
by reference
The library key. The key-name argument is the address of an unsigned
longword value for the key (for libraries with binary keys).

LBR—60

Librarian (LBR) Routines
LBR$REPLACE_KEY

oldrfa
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
longword (unsigned)
write only
by reference

The old RFA. The oldrfa argument is the address of a 2-longword array that
contains the original RFA (returned by LBR$LOOKUP__KEY) of the module
header associated with the key you are replacing.

newrfa
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
longword (unsigned)
read only
by reference

The new RFA. The newrfa argument is the address of a 2-longword array
that contains the RFA (returned by LBR$PUT_RECORD) of the module
header associated with the new key.

DESCRIPTION If LBR$REPLACE _KEY does not find the key in the current index, it calls the
LBR$INSERT—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.

CONDITION
VALUES
RETURNED

LBR$_ILLCTL

The specified library control index is not valid,

LBR$_LIBNOTOPN

The specified library is not open.

LBR$_INVRFA

The specified RFA is not valid.

LBR—61

Librarian (LBR) Routines
LBR$RET_RMSSTV

LBR$RET_.RMSSTV—Return VAX RMS
Status Value
Returns the status value from the last VAX 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. 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

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 is SYS$LIBRARY:STARLET.MLB.

CONDITION
VALUES
RETURNED

LBR—62

Any condition values returned by VAX RMS routines.

Librarian (LBR) Routines
LBR$SEARCH

LBR$SEARCH—Search an Index
Finds index keys that point to specified data.

FORMAT

LBR$SEARCH library-index ,index-number
,rfa-to-find,routine-name

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

library-index
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI_CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

index-number
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

The library index number. The index-number argument is the address of
a longword that contains the number of the index you want to search (see
Section 1.2.3).

rfa-to- find
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
longword (unsigned)
write only
by reference

The 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 that
contains 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:
type:
access:
mechanism:

procedure
procedure entry mask
read only
by reference

The name of a routine to process the keys. The routine-name argument is
the address of the entry mask of a user-written 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-written 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.
1

The key argument is the address of either:
•

A string descriptor for the keyname (libraries with ASCII keynames).

•

An unsigned longword for the key value (libraries with binary keys).

2 The RFA. The RFA argument is the address of a 2-longword array which
contains 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$_ILLCTL

The specified library control index is not valid.

LBR$_ILLIDXNUM

The specified library index number is not valid.

LBR$_KEYNOTFND

The librarian did not find any keys with the
specified RFA.

LBR$_LIBNOTOPN

The specified library is not open.

Librarian (LBR) Routines
LBR$SET_INDEX

LBR$SET_INDEX—Set the Current Index
Number
Sets the index number to use during processing of libraries that have
more than one index.

FORMAT

LBR$SET_I N DEX library-index, index-number

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

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

index-number
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The index number you want to establish as the current index number. The
library-index is the address of a longword that contains the number of the
index you want to establish as the current index. (See Section 8.1.2.3.)

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

The specified library control index is not valid,

LBR$_ILLIDXNUM

The library index number specified is not valid,

LBR$_LIBNOTOPN

The specified library is not open.

Librarian (LBR) Routines
LBR$SET_LOCATE

LBR$SET_LOCATE—Set Record Access to
Locate Mode
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. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
"CONDITION VALUES RETURNED."

ARGUMENT

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI_CONTROL
routine. The library-index argument is the address of a 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 will copy 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 an internal
librarian subroutine buffer which contains the record.

CONDITION
VALUES
RETURNED

LBR$_ILLCTL

The specified library control index is not valid.

LBR$_LIBNOTOPN

The specified library is not open.

LBR—67

Librarian (LBR) Routines
LBR$SET_MODULE

LBR$SET_-MODULE—Read or Update a
Module Header
Reads, and optionally updates, the module header associated with a
given record's file address (RFA).

FORMAT

LBR$SET_MODULE library-index ,rfa [,bufdesc]
[, buflen] [, updatedesc]

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

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI—CONTROL
routine. The library-index argument is the address of a longword that
contains the index.

rfa
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
longword (unsigned)
write only
by reference

The record's file address (RFA) associated with the module header. The rfa
argument is the address of a 2-longword array containing the RFA which was
returned by LBR$PUT_RECORD or LBR$LOOKUP_KEY.

bufdesc
VMS Usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

The 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

buflen
VMS Usage:
type:
access:
mechanism:

longword—signed
longword (signed)
write only
by reference

The length of the module header. The buflen argument is the address of a
longword that receives the length of the returned module header.

updatedesc
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Additional information for 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
will update the module header with the additional information.

DESCRIPTION If you specify bufdesc, the librarian routine will return the module header

into the buffer. If you specify buflen, the librarian routine will also return the
buffer's length. If you specify updatedesc, the routine will update 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 will
zero-fill the information if it is less than the maximum length, or will truncate
it if it exceeds the maximum length.

CONDITION
VALUES
RETURNED

LBR$_HDRTRUNC

The buffer supplied to hold the module header was
too small.

LBRSILLCTL

The specified library control index is not valid.

LBR$_ILLOP

The updatedesc argument was supplied and the
library was a Version 1.0 library or the library was
opened only for read access.

LBR$_INVRFA

The specified RFA does not point to a valid module
header.

LBR$_LIBNOT OPN

The specified library is not open.

LBR—69

Librarian (LBR) Routines
LBR$SET_MOVE

LBR$SET_-MOVE—Set Record Access to
Move Mode
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. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
"CONDITION VALUES RETURNED."

ARGUMENT

library-index
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

The library control index which was returned by the LBR$INI_CONTROL
routine. The library-index argument is the address of a 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, LBR$GET_RECORD will
copy the requested record to the specified user buffer. For details, see the
description of LBR$GET_RECORD.

CONDITION
VALUES
RETURNED

LBR$_ILLCTL

The specified library control index is not valid.

LBR$_LIBNOTOPN

The specified library is not open.

LBR—70

Print Symbiont Modification (PSM) Routines

9.1

Introduction to PSM Routines
The print symbiont modification (PSM) routines allow you to modify the
behavior of the print symbiont that is supplied with the VAX/VMS operating
system.
The VAX/VMS print symbiont processes data for output to standard line
printers and printing terminals. It performs the following functions:
•

Reads the data from disk

•

Formats the data

•

Sends the data to the printing device

•

Composes separation pages (flag, burst, and trailer pages) and inserts them
into the data stream for printing

Some of the reasons for modifying the print symbiont include the following:
•

You want the separation pages (flag, burst, and trailer pages) to include
additional information or to be formatted differently

•

You want to filter and modify the data stream sent to the printer

•

You want 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 make the following modifications:
•

Modify the VAX/VMS symbiont's control logic or the sequence in which
the symbiont calls routines.

•

Modify the interface between the VAX/VMS symbiont and the job
controller.

If you cannot modify the VAX/VMS print symbiont to suit your needs, you
might want to write your own symbiont. Section 9.3 describes how to write
your own symbiont and integrate it with the VAX/VMS operating system.
However, it is recommended that you modify the VAX/VMS print symbiont,
when possible, rather than write your own symbiont.
The following list describes the content of the remaining major sections on
PSM routines:
•

Section 9.2 contains an overview of the VAX/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 VAX/VMS print symbiont's
internal logic.
This section is recommended for those who want either to modify the
VAX/VMS print symbiont or to write a new symbiont.

PSM-1

Print Symbiont Modification (PSM) Routines
Introduction to PSM Routines

9.2

•

Section 9.3 details the procedure to follow in modifying the VAX/VMS
print symbiont. It includes an overview of the entire procedure, followed
by a detailed description of each step.

•

Section 9.4 contains an example of a simple modification to the VAX/VMS
print symbiont.

•

Section 9.5 describes each PSM routine, and describes the interface that
routines you substitute for the standard PSM routines must use.

VAX/VMS Print Symbiont Overview
This section describes the VAX/VMS print symbiont, which is an output
symbiont. An output symbiont receives tasks from the job controller, whereas
an input symbiont sends jobs to the job controller.
There are two types of output symbiont: device symbionts and server
symbionts. A device symbiont processes data for output to a device. A server
symbiont also processes data, but not necessarily for output to a device. One
example of a server symbiont is a symbiont that copies files across a network.
The VAX/VMS operating system supplies no server symbionts.
The VAX/VMS operating system supplies two symbionts: a print symbiont
and a card reader symbiont. The card reader symbiont, which is an input
symbiont, cannot be modified. The print symbiont, which is an output device
symbiont, can be modified using the PSM routines.

9.2.1

Components of the VAX/VMS Print Symbiont
The VAX/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
VAX/VMS print symbiont

•

Routines that implement the internal logic of the VAX/VMS print
symbiont

The VAX/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 Section 10.
All the routines described above are contained in a shareable image with the
file specification SYS$SHARE:SMBSRVSHR.EXE.

PSM—2

Print Symbiont Modification (PSM) Routines
VAX/VMS Print Symbiont Overview

9.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
VAX/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.
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. The /PROCESSOR qualifier can be used with the START
/QUEUE command to specify the name of the symbiont image that is to
service an execution queue; if /PROCESSOR is omitted, 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.

9.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. Since
each print execution queue has a single associated printing device (specified
with the /ON=device_name qualifier with the INITIALIZE/QUEUE or
START/QUEUE commands), each stream created by the job controller will
link 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 on
the number of streams that any symbiont can service simultaneously; this
limit is 16.
Therefore, in the VAX/VMS operating system environment, only one print
symbiont process is needed so 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 will create another print symbiont
process.
The VAX/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 so long as the number is less than
or equal to 16.

PSM—3

Print Symbiont Modification (PSM) Routines
VAX/VMS Print Symbiont Overview

A symbiont stream is said to be "active" when a queue is started on that
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.
Figure PSM-1 shows the relationship between generic print queues, execution
print queues, the job controller, the print symbiont, printer device drivers,
and printers. The dotted lines connecting the boxes denote streams.

Figure PSM-1

Multithreaded Symbiont

ZK-2007-84

9.2.4

Symbiont and Job Controller Functions
This section compares the roles of the symbiont and job controller in the
execution of print requests. Print requests are issued 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)

Print Symbiont Modification (PSM) Routines
VAX/VMS Print Symbiont Overview

•

How to set up the job (/SETUP)

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 VAX/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".

9.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, it is the job
controller's role 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.

2 The symbiont searches its list of input routines and selects the first input
routine that is applicable to the print task.

3 The input routine returns a data record to the symbiont's input buffer or
in a buffer supplied by the input routine.

4 Data in the input buffer is moved to the symbiont's output buffer by the
formatting routines, which format it in the process.

5 Data in the output buffer is sent to the printing device by the output
routine.
6

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.

7 The symbiont informs the job controller that the task is complete.
Figure PSM-2 pictures the steps taken by the symbiont in the processing of a
print task:

PSM—5

Print Symbiont Modification (PSM) Routines
VAX/VMS Print Symbiont Overview

Figure PSM-2

INPUT
ROUTINES

Symbiont Execution Sequence or Flow of
Control

. . .and so on

ZK-2008-84

As Figure PSM-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, and so 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. The demand input routines 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. 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.

PSM—6

Print Symbiont Modification (PSM) Routines
VAX/VMS Print Symbiont Overview

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.

9.3

Modification Procedure

9.3.1

Overview
To modify the VAX/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.

2 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 PSM-1 lists these codes.

3 Write the routine. Since 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-INPUTROUTINE, USER-FORMAT-ROUTINE, and USER-OUTPUT-ROUTINE
routines, which follow the descriptions of the PSM routines.

4 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 supplied; activates the symbiont by calling PSM$PRINT; and
performs any necessary cleanup operations when PSM$PRINT completes.

5 Construct the modified symbiont. This involves compiling your routines,
then linking them.
6

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.

PSM—7

Print Symbiont Modification (PSM) Routines
Modification Procedure

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 9.3.6 provides more information about these codes.

9.3.2

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$OUTPUT, SYS$ERROR, and SYS$COMMAND.

•

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.

•

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 may be overridden. See the description of the /RETAIN qualifier
of the DCL commands START/QUEUE, INITIALIZE/QUEUE, and SET
QUEUE in the VAX/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.
It is recommended that, if you choose to return a condition value when
an error occurs, you choose one from the system message file. This
allows system programs to 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.

•

PSM—8

This guideline applies to input, input-filter, and output-filter routines, and
to the symbiont's use of dynamic string descriptors in these routines.

Print Symbiont Modification (PSM) Routines
Modification Procedure

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 as follows the fields of
the descriptor to which the funcdesc 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).

2 Initialize the field DSC$A_POINTER with the address of the buffer
that contains the data record.

3 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 be a dynamic descriptor. Consequently, if
you want to use the descriptor as a static descriptor, your input routine
must initialize the descriptor as described above 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 above. Thus the guidelines
described for the input routine apply to the input-filter routine and
output-filter routine.

9.3.3

Writing an Input Routine
To write an input routine, follow the modification procedure described in
Section 9.3.
This section provides additional information on the writing of an input
routine. It provides an overview of the logic used in the VAX/VMS print
symbiont's main input routine, and it discusses the way in which the
VAX/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.

PSM—9

Print Symbiont Modification (PSM) Routines
Modification Procedure

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 9.3.6 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 PSM-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.

9.3.3.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 the routine 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 list names the codes that identify each of these three requests
and describes the tasks that the VAX/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:
1

Opens the input file.

2 Stores information about the input file.
3

PSM-10

Returns the type of carriage control used in the input file.
If this routine cannot open the file, it returns an error.

Print Symbiont Modification (PSM) Routines
Modification Procedure

Action Taken by the Input Routine

Code

Note: 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, record formats, and so on, 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.

9.3.3.2

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.

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.

PSM—11

Print Symbiont Modification (PSM) Routines
Modification Procedure

The Four Types of Carriage Control
The following list 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 VAX Record Management Services
Reference Manual.
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 carriagecontrol character. If the data record is empty, the
symbiont generates a leading carriage control of
linefeed and a trailing carriage control of carriage
return.

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

9.3.4

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, you follow the modification procedure described in
Section 9.3. Do not replace the VAX/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 may not replace the main formatting routine. The DCL command PRINT
/PASSALL bypasses the main format routine of the print symbiont.

PSM—12

Print Symbiont Modification (PSM) Routines
Modification Procedure

See Section 9.3.6 for additional information about other function codes used
in the user-written formatting routine.

9.3.4.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=M ASK

•

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

•

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

9.3.5

Writing an Output Routine
To write an output routine, you follow the modification procedure described
in Section 9.3.
The print symbiont is the caller of 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-OUTPUTROUTINE 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.

PSM—1 3

Print Symbiont Modification (PSM) Routines
Modification Procedure

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 in the description
of the USER-OUTPUT-ROUTINE routine.
See Section 9.3.6 for additional information about other function codes.

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

2 Assigns a channel to the device
3 Obtains the device characteristics
4

Returns the device-status longword in the funcarg argument (see the
description of the SMBMSG$K—DEVICE—STATUS message item in
Section 10, Symbiont/Job-Controller Interface (SMB) Routines, for more
information)

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

9.3.6

Other Function Codes
Whenever the symbiont notifies user-written input, output, and format
routines using the following message function codes, a status
PSM$_PENDING may not be returned.

PSM—14

Print Symbiont Modification (PSM) Routines
Modification Procedure

Function Code

Description

PSM$K_ST ART_STRE AM

Job controller sends a message to the symbiont to
start a queue.
Symbiont parses message from job controller
directing it to start a queue.

PSM$K_ST ART_T ASK
PSM$K_PAUSE_T ASK

Job controller sends message to the symbiont to
suspend processing of the current task.

PSM$K_STOP_STREAM

Job controller sends message to the symbiont to
stop the queue.

PSM$K_STOP_TASK

Job controller sends a message to the symbiont to
stop the task.

PSMSK -RESUME _T ASK

Job controller sends a message to the symbiont to
resume processing of the current task.
Same as PSM$K_STOP_STREAM

PSM$K_RESET_STREAM

9.3.7

Writing a Symbiont Initialization Routine
Writing a symbiont initialization routine involves writing a program which
does the following:
1

Calls PSM$REPLACE once for each routine (input, output, or format)
that you have written. PSM$REPLACE identifies your routines to the
symbiont.

2 Calls PSM$PRINT exactly once after you have identified all your service
routines using PSM$REPLACE.
Table PSM-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 PSM-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 outputfilter routines, which have no corresponding routines in the VAX/VMS
symbiont, allow you to specify new routines for inclusion in the symbiont.

PSM-15

Print Symbiont Modification (PSM) Routines
Modification Procedure

Table PSM-1

Routine Codes for Specification to
PSM$REPLACE
Sequence

Function

Supplied

PSM$K_JOB_SETUP

Input

Yes

PSM$K_FORM_SETUP

Input

Yes

PSM$K_JOB_FLAG

Input

Yes

PSM$K_JOB_BURST

Input

Yes

PSM$K_FILE_SETUP

Input

Yes

PSM$K_FILE_FLAG

Input

Yes

PSM$K_FILE_BURST

Input

Yes

PSM$K_FILE_SETUP_2

Input

Yes

PSM$K_MAIN_INPUT

Input

Yes

PSM$K_FILE—INFORMATION

Input

Yes

PSM$K_FILE_ERRORS

Input

Yes

PSM$K_FILE—TRAILER

Input

Yes

PSM$K_JOB—RESET

Input

Yes

PSM$K_JOB—TRAILER

Input

Yes

PSM$K_JOB—COMPLETION

Input

Yes

PSM$K_P AGE-SETUP

Input

Yes

PSM$K_P AGE-HEADER

Input

Yes

Routine Code

9.3.8

PSM$K_LIBRARY—INPUT

Input

Yes

PSMSK—INPUT—FILTER

Formatting

PSM$K_MAIN-FORMAT

Formatting

Yes

PSM$K_OUTPUT—FILTER

Formatting

PSM$K_OUTPUT

Output

Yes

Integrating a Modified Symbiont
To integrate your user routine(s) 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(s) and the symbiont initialization
routine into an object module.

2 Issue the following DCL command:
$ LINK/DEBUG your-symbiont

where 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:.
4 Locate two unallocated terminals, one at which to issue DCL commands
and one at which to debug the symbiont image.

PSM-16

Print Symbiont Modification (PSM) Routines
Modification Procedure

5 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 will be issuing
DCL commands. Do not log in at the other terminal.

6 Issue the following DCL command:
$ SET TERMINAL/NODISCONNECT/PERMANENT _TTcu:

where _TTcu: is the physical terminal name of the terminal at which you
want to debug (the terminal you are not logged in at).

7 Issue the following DCL commands:
$ DEFINE/GROUP DBG$INPUT

_TTcu:

$ DEFINE/GROUP DBG$OUTPUT _TTcu:

where —TTcu: specifies the physical terminal name of the terminal
at which you will be debugging. The underscore (_) and colon (:)
characters must be specified. 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 issuing the following DCL command:
$ INITIALIZE/QUEUE/PROCESSOR= your-symbiont /0N= 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 are forced 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

Issue the following DCL command to start the queue and invoke the
debugger:
$ START/QUEUE queue-name

I 0 After you debug your symbiont, relink the symbiont by issuing the
following DCL command:
$ LINK/NOTRACEBACK/NODEBUG your-symbiont

II Deassign the logical names DBG$INPUT and DBG$OUTPUT so that they
will not interfere with other users in UIC group 1.

PSM—1 7

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.

System definitions

;

IPSMDEF
$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 desc
function dependent argum

;
;
;
;

DSC$W_LENGTH = 0
DSC$B_DTYPE = STRING
DSC$B_CLASS = DYNAMIC
DSC$A_POINTER = 0

;
;
;

file name descriptor
user name descriptor
account name descriptor

;
;

page number
line number

Macro to create dynamic descriptors
.MACRO

D JDESC
WORD
BYTE
BYTE
LONG

.
.
.
.

0
DSC$K_DTYPE_T
DSC$K_CLASS_D
0

. ENDM

Storage for page header information
FILE:
USER:
ACCOUNT:

D.DESC
D.DESC
D.DESC

PAGE:
LINE:

.LONG
.LONG

0
0

FAO control string and work buffer.
Header format:
"[account.name] filename . Page 9999"
FAO.CTRL:
FA0_CTRL_2:
FAO.DESC:
FAO.BUFF:

.ASCID
/!71<[!AS,
.ASCID
/!4UL/
.LONG
80
.ADDRESS FAO.BUFF
.BLKB
80

! AS]

!AS!>Page 9999/
;

work buffer descriptor

;

work buffer

(Continued on n

PSM-18

.LONG
.LONG
.WORD

STREAMS
BUFSIZ:
LINSIZ:

1
2048
81

; num
; outp
; line

; Main routine -- invoked at image startup
START:

.WORD

; save nothing because this ro

; Supply private page header routine
MOVZBL
PUSHAL
PUSHAL
CALLS
BLBC

#PSM$K_PAGE_HEADER,CODE
HEADER
CODE
#2,G~PSM$REPLACE
RO,10$

;
;
;
;
;

set
add
add
repl
exi

; Transfer control to the standard symbiont

10$:

PUSHAL
PUSHAL
CALLS
RET

BUFSIZ
STREAMS
#2,G~PSM$PRINT

; add
; add
; invo

Page header routine
HEADER:

.WORD

; save

;

Check function code

15$:

16$:

CMPL
BEQL
CMPL
BNEQ
BEQL
CMPL
BNEQ
BEQL
MOVL
RET

#PSM$K_START_TASK.©FUNC(AP)
20$
#PSM$K_READ,©FUNC(AP)
15$
50$
#PSM$K_0PEN, ©FUNC(AP)
16$
66$
#PSM$_FUNNOTSUP,RO

; new
; bran
; READ

; bran
; OPEN

; bran
; unsu
; retu

Starting a new file
20$:
CLRL
MOVZBL

PAGE
#2,LINE

reset the page number
and the line number

Get the account name
MOVZBL
PUSHAL
PUSHAL
PUSHAL
CALLS
BLBC

#SMBMSG$K_ACCOUNT_NAME,CODE
ACCOUNT
CODE
©CONTEXT(AP)
#3,G~PSM$READ_ITEM_DX
RO,40$

;
;
;
;

set item code
address of descriptor
address of item code
address of symbiont ctx
; read it
; branch if any errors

Get the file name
MOVZBL
PUSHAL
PUSHAL
PUSHAL
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
#3,G~PSM$READ_ITEM_DX
; read it
RO,40$
; branch if any errors

he user name
MOVZBL
PUSHAL
PUSHAL
PUSHAL
CALLS
BLBC

#SMBMSG$K_USER_NAME,CODE
USER
CODE
©CONTEXT(AP)
#3.G~PSM$READ_ITEM_DX
RO,40$

;
;
;
;
;
;

set item code
address of descriptor
address of item code
address of symbiont ctx
read it
branch if any errors

p the static header information that is constant for the task
$FA0_S

40$:

RET

CTRSTR
OUTBUF
PI
P2
P3

= FAO.CTRL, = FAO.DESC, = #ACCOUNT, = #USER, = #FILE

;
;
;
;
;
;

FAO control string desc
output buffer descripto
account name descriptor
user name descriptor
file name descriptor
return success or any e

(Continued on n

PSM—20

50$:
DECL
BEQL
BLSS

LINE
60$
70$

; decre
; branc
; branc

the page number into the header
INCL
MOVAB
$FA0_S

MOVAB
BLBC

PAGE
FAO.BUFF+76,FAO.DESC+4
CTRSTR = FA0_CTRL_2, 0UTBUF = FAO.DESC, PI
= PAGE
FAO.BUFF,FAO.DESC+4
R0,55$

;
;
;
;
;
;
;

increm
point
FAO c
outpu
page
point
retur

Copy the line to the symbiont's buffer

55$:

PUSHAB
PUSHL
CALLS
RET

FAO.DESC
FUNC.DESC(AP)
#2,G~STR$C0PY_DX

work
symb
copy
retur

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,G~STR$GET1_DX
R0,67$
FUNC.DESC(AP),R1
4(R1),R1
80(Rl),RO
#~A/-/.(Ri)+
R0,R1
65$
#10,(Rl)+
#SS$_N0RMAL,RO

symb
numbe
reser
exit
get a
get a
set u
fill
reach
branc
extra
set s
retur

Done with this page header
70$:

9.5

MOVL
MOVZBL
RET

#PSM$_E0F.R0
#2,LINE

.END

START

retur
reset
retur

PSM Routines

The following pages describe the individual PSM r
format.

Print Symbiont Modification (PSM) Routines
PSM$PRINT

PSM$PRINT
Invokes the VAX/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. 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

streams
VMS Usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: 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 2 to 26 . If streams is not specified, a default
value of 2 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 multi-threaded.

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 and (2) the SYSGEN parameter MAXBUF. If bufsiz
is not specified, 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—22

Print Symbiont Modification (PSM) Routines
PSM$PRII\IT

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:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
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 worksiz is not specified, 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 multi-threaded, and if multi-threaded, 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

SS$_NORMAL

Normal successful completion.

Any condition values returned by the $SETPRV, $GETSYI, $PURGWS, and
$DCLAST system services.
Any condition values returned by the SMB$INITIALIZE routine documented
in Chapter 10.

PSM—23

Print Symbiont Modification (PSM) Routines
PSM$READ_ITEM_DX

PSM$READ_ITEM_DX
Returns an item of information stored by the VAX/VMS print
symbiont. These items of information are sent to the symbiont
from the job controller.

FORMAT

PSM$READ_ITEM_DX request—id,item ,buffer

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

request—id
VMS Usage:
type:
access:
mechanism:

address
longword (unsigned)
read only
by reference

Request identifier that was supplied by the symbiont to the user routine that
is 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.
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
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
write 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.
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 10, Symbiont/Job-Controller Interface (SMB) Routines.

PSM—24

Print Symbiont Modification (PSM) Routines
PSM$READ_ITEM_DX

buffer
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
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 VAX/VMS Run-Time Library Routines Reference Manual.

DESCRIPTION

PSM$READ_ITEM_DX obtains the value of message items that are sent
by the job controller and stored by the VAX/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).

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

PSM$_INVITMCOD

The item argument specified an invalid item code.

Any condition values returned by any of the STR$COPY_xx routines
documented in the VAX/VMS Run-Time Library Routines Reference Manual.

PSM—25

Print Symbiont Modification (PSM) Routines
PSM$REPLACE

PSM$REPLACE
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.

FORMAT

PSM$REPLACE code,routine

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

code
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Routine code that identifies a symbiont routine. The code argument is the
address of a longword containing the routine code.
Some routine codes identify routines that are supplied with the VAX/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 VAX/VMS
symbiont; when you specify such a routine code, your service routine is
added to the set of symbiont routines.
Table PSM-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 VAX/VMS symbiont.
The routine codes are defined by the $PSMDEF macro. The following lists
each routine code in alphabetical order; the description of each code includes
the following information about its corresponding routine:

PSM—26

•

Whether the routine is supplied by the VAX/VMS symbiont

•

Whether the routine is an input, formatting, or output routine

•

Under what conditions the routine is called

•

What task the routine performs

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 it 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 it 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_IN FORMATION
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 it 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—27

Print Symbiont Modification (PSM) Routines
PSM$REPLACE

PSM$K_INPUT_FILTER
This code identifies a format routine that is not supplied by the VAX/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 it 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 it 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 it 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—28

Print Symbiont Modification (PSM) Routines
PSM$REPLACE

PSM$K_LIBRARY_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 VAX /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 may 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:
type:
access:
mechanism:

procedure
procedure entry mask
read only
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.

DESCRIPTION

The routine codes that may 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 a location within the print symbiont execution stream where your
routine can execute.

PSM—29

Print Symbiont Modification (PSM) Routines
PSM$REPLACE

By selecting a routine code that identifies an existing symbiont routine, you
effectively disable that symbiont routine. The service routine that you specify
may perform the function that the disabled symbiont routine performs or it
may not. 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 entirely 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.
Since 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
PSM-1 lists each routine code in the order in which the location it identifies is
reached within the symbiont execution stream.

CONDITION
VALUES
RETURNED

PSM—30

SS$_NORMAL

Normal successful completion.

Print Symbiont Modification (PSM) Routines
PSM$REPORT

PSM$REPORT
Reports to the print symbiont the completion status of an
asynchronous operation that was initiated by a user routine.
Such a user routine must have returned the completion status
PSM$_PENDING.
PSMSREPORT must be called exactly once for each time that a user
routine has returned the status PSM$_PENDING.

FORMAT

PSMSREPORT

RETURNS

VMS Usage:
type:
access:
mechanism:

requestsid [^status]

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

request—id
VMS Usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Request identifier that was 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 have returned 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—31

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:
type:
access:
mechanism:

cond—value
longword (unsigned)
write only
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 may 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:

CONDITION
VALUES
RETURNED
PSM—32

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 below describes some necessary functions that you will want your AST
routine to do.

Have the user output routine return the status PSM$_PENDING.

Write the AST routine to perform the following functions:

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.

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.

SS$_NORMAL

Normal successful completion.

Print Symbiont Modification (PSM) Routines
USER-FORMAT-ROUTINE

USER-FORMAT-ROUTINE
Is a user-written routine that 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 may 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) may not be replaced.
A user format routine must use the call interface described here.

FORMAT

USER-FORMAT-ROUTINE request-id,work_area
,func ,func—desc— 1
,func—arg_ 1
,func—desc—2
,func—arg—2
The func_arg__1 and func_arg—2 arguments are not used in some cases; see
the Description section for more information.

RETURNS

VMS Usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return (by value) a condition
value in RO. Condition values that can be returned by this routine are listed
under "CONDITION VALUES RETURNED."

ARGUMENTS

request—id
VMS Usage:
type:
access:
mechanism:

identifier
longword (unsigned)
write only
by reference

Request identifier that is 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.

PSM—33

Print Symbiont Modification (PSM) Routines
USER-FORMAT-ROUTINE

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 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 work_size is not specified 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.

func
VMS Usage:
type:
access:
mechanism:

function _code
longword (unsigned)
write only
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 why 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 function code 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 may 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.
The following function codes correspond to message items sent by the job
controller to the symbiont; Section 9.3.6, discusses these message items in
greater detail:
PSM$K_ST ART—STREAM

PSM$K_STOP_STREAM

PSM$K_ST ART_T ASK

PSM$K_PAUSE_T ASK

PSM$K_RESUME_T ASK

PSM$K_STOP_TASK

PSM$K_RESET_STREAM
Other function codes correspond to internal symbiont mechanisms that are
not part of the public interface to the print symbiont.
In conclusion, your format routine should return the status
PSM$_FUNNOTSUP or SS$_NORMAL when it is called with message
function code or with a private function code.

PSM—34

Print Symbiont Modification (PSM) Routines
USER-FORMAT-ROUTINE

func—desc_ 7
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Descriptor supplying an input record to be processed by the format routine.
The func_desc_l argument is the address of a string descriptor. The
symbiont supplies, by using this argument, the input record that your format
routine is to process. Since this descriptor may be of any valid string type,
it is recommended that your format routine use the Run-Time Library string
routines to analyze this descriptor and manipulate the input record.

func—arg_ 7
VMS Usage:
type:
access:
mechanism:

vector_byte_unsigned
byte (unsigned)
read only
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:
3
1

1
5

2
3

character

count

TRAILING CARRIAGE-CONTROL
INFORMATION

character

0
count

LEADING CARRIAGE-CONTROL
INFORMATION

ZK-2009-84

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

PSM-35

Print Symbiont Modification (PSM) Routines
USER-FORMAT-ROUTINE

func—desc—2
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
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.
It is recommended that your format routine use the Run-Time Library string
routines to write into the buffer specified by this descriptor.

func—arg—2
VMS Usage:
type:
access:
mechanism:

vector_byte_unsigned
byte (unsigned)
read only
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—1 for
the contents and format of this 4-byte vector.
If you do not process the carriage-control information supplied in
func—arg—1 , 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—1 argument describes carriage control information
for the input data record, and the func_arg_2 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—1) into the data record (specified by
func_desc_1). Thus, the output data (specified by func—desc—2) contains
embedded carriage control and is therefore 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_1
nor func—arg—2 arguments; the data it receives (via func—desc_1) and the
data it returns (via func—desc—2) are data streams, not data records.

PSM—36

Print Symbiont Modification (PSM) Routines
USER-FORMAT-ROUTINE

However, the input filter routine (routine code PSM$K_INPUT_PILTER),
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.

CONDITION
VALUES
RETURNED

SSS—NORMAL

Successful completion. The user format routine
has completed the function that the symbiont
requested.

PSM$_FUNNOTSUP

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.

Any error condition values that you have coded your format routine to return.
Refer to Section 9.3.2 for more information about error condition values.

PSM—37

Print Symbiont Modification (PSM) Routines
USER-INPUT-ROUTINE

USER-INPUT-ROUTINE
Is a user-written routine that 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-1 NPUT-ROUTINE request—id, work—area
,func ,funcdesc ,funcarg

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

request—id
VMS Usage: identifier
type:
longword (unsigned)
access:
write only
mechanism: by reference
Request identifier value that is 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:
type:
access:
mechanism:

address
longword (unsigned)
write only
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 other internal operations.
The size of the work area allocated is specified by the work—size argument
in the PSM$PRINT routine. If work—size is not specified in the call to
PSM$PRINT, no work area is allocated.

PSM—38

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.

func
VMS Usage:
type:
access:
mechanism:

function _code
longword (unsigned)
read only
by reference

Function code that is supplied by the symbiont when it calls your input
routine. The func argument is the address of a longword containing this
code.
The function code specifies the reason why 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.
The following lists 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 USER-FORMATROUTINE 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 may 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 will always call your input routine with
PSM$K_CLOSE if your routine has returned successfully from a
PSM$K_OPEN function call. This guaranteed behavior ensures that any
resources your routine may 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
may 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—39

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
will pass 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 file
positioning functions specified by the DCL commands START/QUEUE
/FORWARD, START/QUEUE/ALIGN, START/QUEUE/TOP—OF_FILE,
START/QUEUE/SEARCH, and START/QUEUE/BACKWARD, and by 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 via this argument. It is recommended
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 wishes 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 allocation of
necessary resources, initialization of storage areas, opening of 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.
The $PSMDEF macro defines the following four carriage control types.

PSM—40

Print Symbiont Modification (PSM) Routines
USER-INPUT-ROUTINE

Carriage Type

Description

PSM$K_CC_IMPLIED

Implied carriage control. For this type, the symbiont
inserts a leading linefeed (If) 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 two-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 will specify 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 either (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. It is
recommended that you use one of the Run-Time Library string routines to
copy the input record to the descriptor.

PSM—41

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 two-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
may do one of two things: (1) return PSM$_FUNNOTSUP (function not
supported) or (2) must 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 will subsequently call your input routine with a
PSM$K_CLOSE function call followed by a PSM$K_OPEN function call. By
returning PSM$K_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, reopenning of
the input routine.
The funcdesc and the funcarg arguments are not used 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 may 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.
The following function codes correspond to message items sent by the job
controller to the symbiont; Section 9.3.6 discusses these message items in
depth:
PSM$K_ST ART_STRE AM

PSM$K_STOP_STREAM

PSM$K_ST ART_T ASK

PSM$K_PAUSE_TASK

PSM$K _RESUME _T ASK

PSM$K_STOP_TASK

PSM$K_RESET_STREAM
Other function codes correspond to internal symbiont mechanisms that are
not part of the public interface to the print symbiont.
In conclusion, your input routine should return the status
PSM$K_FUNNOTSUP or SS$_NORMAL when it is called with a message
function code or with a private function code.

PSM—42

Print Symbiont Modification (PSM) Routines
USER-INPUT-ROUTINE

funcdesc
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

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 varies 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:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
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.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Successful completion. The user input routine
has completed the function that the symbiont
requested.

PSM$_FLUSH

The user input routine requests that the symbiont
flush the output stream. The user input routine
can only return this status 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

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

The user input routine has accepted but has
not completed the requested function. Your
input routine may 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.

Any error condition values that you have coded your format routine to return.
Refer to Section 9.3.2 for more information about error condition values.

PSM—43

Print Symbiont Modification (PSM) Routines
USER-OUTPUT-ROUTINE

USER-OUTPUT-ROUTINE
Is a user-written routine that 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 request—id,work—area
,func ,funcdesc ,funcarg

RETURNS

ARGUMENTS

request—id
VMS Usage: identifier
type:
longword (unsigned)
access:
write only
mechanism: by reference
Request identifier value that is 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 work—size is not specified in the call to
PSM$PRINT, no work area is allocated.

PSM—44

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.

func
VMS Usage:
type:
access:
mechanism:

function_code
longword (unsigned)
read only
by reference

Function code that is 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 why 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 lists all the function codes that the symbiont may 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 will specify
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 the user that issued the DCL command
START/QUEUE.
The funcdesc argument is the address of a descriptor that identifies the name
of the device that 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_DE VICE-STATUS item in the SMB$RE AD-MESS AGE-ITEM
routine, which is documented in Section 9, Symbiont/Job-Controller Interface
(SMB) Routines.

PSM—45

Print Symbiont Modification (PSM) Routines
USER-OUTPUT-ROUTINE

Your output routine sets bits in the device status longword to indicate the
following to the job controller:
•

Whether the device can print lowercase letters

•

Whether the device is a terminal

•

Whether the device 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
lineprinter 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. It is recommended 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. It
is recommended 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 lineprinter, 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 I/O requests.
The output routine supplied by the symbiont aborts outstanding I/O requests
by calling the $QIO system service with the IO$_CANCEL function code.
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 to say, 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.
The funcdesc and funcarg arguments are not used.

PSM—46

Print Symbiont Modification (PSM) Routines
USER-OUTPUT-ROUTINE

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).
The funcdesc and funcarg arguments are not used.

Other Output Function Codes
The symbiont may 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.
The following function codes correspond to message items sent by the job
controller to the symbiont; Section 10.2 discusses these message items in
depth:
PSM$K_ST ART_STREAM

PSM$K_STOP_STREAM

PSM$K_START_TASK

PSM$K_PAUSE_TASK

PSM$K_RESUME_T ASK

PSM$K_STOP_TASK

PSM$K_RESET_STREAM
Other function codes correspond to internal symbiont mechanisms that are
not part of the public interface to the print symbiont.
In conclusion, your output routine should return the status
PSM$K_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:

char_string
character string
read only
by descriptor

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:
type:
access:
mechanism:

user_arg
longword (unsigned)
read only
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 at all.

PSM—47

Print Symbiont Modification (PSM) Routines
USER-OUTPUT-ROUTINE

CONDITION
VALUES

SS$_NORMAL

Successful completion. The user output routine
has completed the function that the symbiont
requested.

RETURNED

psm$_funnotsup

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

The user output routine has accepted but has not
completed the requested function. Your output
routine may 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 via 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.

Any error condition values that you have coded your output routine to return.
Refer to Section 9.3.2 for more information about error condition values.

PSM—48

10 Symbiont/Job Controller Interface (SMB)
Routines

10.1 Introduction to SMB Routines
The SMB routines provide the interface between the job controller and
symbiont processes. A user-written symbiont must use these routines to
communicate with the VAX/VMS job controller.
Always use the SMB interface routines or SYS$SNDJBC system service to
communicate with the job controller. You do not need to, and should not
attempt to, communicate directly with the job controller.
To write a symbiont of your own it is useful to understand how symbionts
work and, in particular, how the standard VAX/VMS print symbiont behaves.

10.1.1 Types of Symbionts
There are two types of symbionts:
•

Device symbiont, either an input symbiont or an output symbiont. An
input symbiont is a symbiont that transfers data from a slow device to
a fast device, for example, from a card reader to a disk. A card-reader
symbiont is an input symbiont. An output symbiont is a symbiont 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 VAX/VMS operating system does not supply any server symbionts.

10.1.2 Symbionts Supplied with the VAX/VMS Operating System
The VAX/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.
This symbiont handles the transferring of data from a card reader to a disk
file.

SMB-1

Symbiont/Job Controller Interface (SMB) Routines
Introduction to SMB Routines

You cannot modify INPSMB. Nor can you write an input symbiont using
the SMB routines.

10.1.3 Symbiont Behavior in the VAX/VMS Environment
In the VAX/VMS environment, a symbiont is a process under the control of
the VAX/VMS job controller that transfers or processes data.
Figure SMB-1 depicts the VAX/VMS components that take part in the
handling of user requests that involve symbionts. This figure shows two
symbionts: (1) the VAX/VMS operating system-supplied print symbiont,
PRTSMB and (2) a user-written symbiont, GRAPHICS.EXE, which services a
graphics plotter. The numbers that appear in the figure refer to the activities
listed below the figure.
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 VAX/VMS operating system-supplied print
symbiont.
Although SMB routines can be used for a different kind of symbiont, many
of their arguments and associated symbols have names that are 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.

SMB-2

Symbiont/Job Controller Interface (SMB) Routines
Introduction to SMB Routines

Figure SMB-1

Symbionts in the VAX/VMS Operating System
Environment

ZK-2010-84

O You request a printing job with the DCLs PRINT command. 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.
© The job controller places the print request in the appropriate queue and
assigns the request a job number.
© 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.)
O PRTSMB interprets the information it receives from the job controller.

SMB-3

Symbiont/Job Controller Interface (SMB) Routines
Introduction to SMB Routines

© PRTSMB locates and opens the file it is to print by using the fileidentification number the job controller specified in the start-task message.
© PRTSMB sends the data from the file to the printer's driver.
© The device driver sends the data to the printer, which prints it.

10.1.4 Why Write a Symbiont?
Writing your own symbiont permits you to use the queueing mechanisms and
control functions of the VAX/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 DCL PRINT command to print a file, the job
controller sends to the print symbiont a message that tells it to print a file.
When a user-written symbiont receives the same message, however, (caused
by a user typing 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.
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.

10.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:
•

SMB-4

The symbiont must not use any of the process-permanent channels, which
are assigned to the logical names:
•

SYS$INPUT

•

SYS$OUTPUT

•

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 VAX/VMS operating system,
the symbiont should be written 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 and the $SNDJBC
system service.

Symbiont /Job Controller Interface (SMB) Routines
Introduction to SMB Routines

•

The symbiont can receive messages only from the job controller when it
is not executing within the context of an AST routine. It is recommended
that the symbiont not perform lengthy operations within the context of an
AST routine.

•

To assign a symbiont to a queue once it has been compiled and linked,
the executable image of the symbiont must reside in SYS$SYSTEM, and
either of the following commands must be issued:
$ INITIALIZE/QUEUE/PROCESSOR*symbiont_file_name
$ START/QUEUE/PROCESSOR*symbiont_file_name

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.

10.1.6 The Symbiont/Job-Controller Interface Routines
The five SMB routines form a public interface to the VAX/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:
SMBSINITIALIZE

Initializes the SMB facility's internal database,
establishes the interface to the job controller,
and defines whether:
1

Messages from the job controller are to be
delivered to the symbiont synchronously or
asynchronously with respect to execution
of the symbiont

2 The symbiont is to be single-threaded
or multithreaded; these concepts are
described below
SMB$CHECK_FOR_MESSAGE

Checks to see if a message from the job
controller to the symbiont has arrived

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_I0BCTL

Sends a message from the symbiont to the
job controller

The remaining sections of this introduction discuss how to use the SMB
routines when writing your symbiont.

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

SMB-5

Symbiont/Job Controller Interface (SMB) Routines
Introduction to SMB Routines

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

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 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 SMB-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. Figure SMB-3 is a flowchart for an asynchronous,
single-threaded symbiont.

SMB-6

Asynchronous Enviro

To receive messages as
AST routine as the sec
scheme, whenever the
AST routine is called.

Symbiont/Job Controller Interface (SMB) Routines
Introduction to SMB Routines

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.
The following figure is a logic chart for a single-threaded, asynchronous
symbiont. The figure does not show many details that your symbiont might
include, such as a call to the $QIO system service.
Note that the broken lines 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-8

SMB-10

Symbiont/Job Controller Interface (SMB) Routines
Introduction to SMB Routines

10.1.7.2

Single Streaming Versus Multistreaming
A 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, it can serve those
queues simultaneously, and is called a multithreaded symbiont.
The argument to the SMB$READ_MESSAGE routine provides a way for a
multithreaded symbiont to keep track of the stream to which a request refers.
Writing your own multi threaded symbiont, however, can be a complex
undertaking.

10.1.8 Reading Job Controller Requests
There are seven general functions that the job controller can request of the
symbiont:
SMBMSG$K_ST ART_STRE AM

SMBMSG$K_STOP_STREAM

SMBMSG$K_ST ART_T ASK

SMBMSG$K_PAUSE_T ASK

SMBMSG$K_RESUME_T ASK

SMBMSG$K_STOP_TASK

SMBMSG$K_RESET_STREAM
The job controller passes the symbiont these requests 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$RE AD_MESS AGE _ITEM routine. SMB$RE AD-MESS AGE-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
SMB$K_JOB—NAME code tells the symbiont that the item contains a string,
the name of a job.
The number of message-items in a request message varies with each type of
request. Therefore, SMB$READ_MESSAGE—ITEM must be called repeatedly
for each request to ensure that all message-items are read.
SMB$RE AD-MESS AGE-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.

SMB-11

Symbiont/Job Controller Interface (SMB) Routines
Introduction to SMB Routines

10.1.9 Processing Job Controller Requests
Once a request has been 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.
The symbiont you write can respond to requests in a similar way or in a
different way appropriate to the function of your symbiont. We suggest 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 VAX/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 to be 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 device will be
used by the symbiont.

•

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

SMB-12

•

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
SMBSMG$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.

Symbiont /Job Controller Interface (SMB) Routines
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 has paused, 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 I/O operations.

•

Close the input file.

•

If the job controller specified, in the START_TASK message, that a trailer
page 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
•

Read and store the message-items associated with the request.

•

Release any stream-specific resources; (1) deassign the channel to the
device, (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 multi threaded symbiont
but all other streams are currently stopped, then call the SYS$EXIT system
service with the condition code SS$_NORMAL.

SMB-13

Symbiont/Job Controller Interface (SMB) Routines
Introduction to SMB Routines

SMBMSG$K_RESET_STREAM
•

Read and store the message-items associated with the request.

•

Abort any task that is in progress—it is not necessary to notify the job
controller that the task has been aborted, but you can do so if you wish.

•

If the job controller specified, in the START-TASK message, that a trailer
page 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 I/O
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 stops
the queue; but a RESET—STREAM request is an emergency stop, uses, for
example, when the device has failed. A RESET—STREAM request should
prevent any further I/O activity because the printer might not be able to
complete it.

10.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 SHOW QUEUE command 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.
Note that when a START—TASK request is delivered, the symbiont responds
with a SMB$SEND_TO—JOBCTL message with the SMBSMG$K-STARTTASK code. This response means that 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 SMBSMG$K—TASK—COMPLETE
code.

SMB-14

Symbiont/Job Controller Interface (SMB) Routines
SMB Routines

10.2

SMB Routines
The following pages describe the individual SMB routines in routine template
format.

SMB-15

Symbiont/Job Controller Interface (SMB) Routines
SMB$CHECK_FOR_MESSAGE

SMB$CHECK_FOR—MESSAGE
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. 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

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 be 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 and 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

SMB-16

SS$_NORMAL

One or more messages are waiting

No messages are waiting

Symbiont/Job Controller Interface (SMB) Routines
SMB$INITIALIZE

SMB$IIMITIALIZE
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 which
will wake up symbiont when a message is received.

FORMAT

SMB$INITIALIZE structure—le\/el[,ast— routine]
[,streams]

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

structure—level
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

Version of the job-controller/symbiont interface. The structure—level
argument is the address of a longword that contains the version of the
job-con troller/symbiont interface that was 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
VMS Usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
read only
by reference

Message-handling routine called at AST level. The AST—routine 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.
The AST routine typically reads the message and determines if immediate
action must be taken. Be aware that an AST can only be delivered while the
symbiont is operating at non-AST level. Thus, in order to ensure delivery of
messages from the job controller, the symbiont should not perform lengthy
operations at AST level.

SMB-17

Symbiont/Job Controller Interface (SMB) Routines
SMB$INITIALIZE

The AST_routine argument is optional. If it is not specified the symbiont
must call the SMB$CHECK_FOR_MESSAGE routine to check for waiting
messages.

streams
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

Maximum number of streams that the symbiont will support. The streams
argument is the address of a longword that contains the number of streams
that the symbiont will support. The number must be in the range 1 to 16 .
If this argument is not specified, 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, it can serve those queues
simultaneously, and is called a multi threaded symbiont.

DESCRIPTION Your symbiont must call SMB$INITIALIZE before calling any other SMB$
routines. It calls SMB$INITIALIZE in order to:
•

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 which will wake your symbiont when a message is
received.

Once the symbiont calls SMB$INITIALIZE, it can communicate with the job
controller using the other SMB$ services.

CONDITION

SS$_NORMAL

Routine successfully completed

VALUES

SMB$_INVSTRLEV

Invalid structure level

RETURNED

Any codes returned by $ ASSIGN and LIB$GET_VM.

SMB-18

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE

SM B$RE AD_M ESS AGE
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. 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

stream
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
write only
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 to which the message refers. In singlethreaded symbionts the stream number is always 0.

buffer
VMS Usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

Message. The buffer argument is the address of a 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. It is recommended that the buffer be
specified by a dynamic string-descriptor.

request
VMS Usage:
type:
access:
mechanism:

identifier
longword (unsigned)
write only
by reference

The address of a longword into which SMB$READ_MESSAGE writes the
code that identifies the request.

SMB-19

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 corresponding messages follow:

DESCRIPTION

SMBMSG$K_ST ART_STRE AM

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_ST ART_T ASK

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_ST OP_T ASK

Requests that the symbiont abort the
processing of a task. The job controller sends
this message 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_T ASK

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 qualifiers 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 that identifies 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 issue DCL's PRINT command, the job controller
sends a message that contains a START-TASK code and a message-item that
contains 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-20

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE

See the description of the SMB$READ_MESSAGE_ITEM routine for
information on processing the individual message-items.

CONDITION

SS$_NORMAL

Routine completed successfully

VALUES

LIB$_INVARG

Routine completed unsuccessfully due to an invalid
argument

RETURNED

Any of the condition codes returned by the Run-Time Library string-handling
(STR$) routines.

SMB-21

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

SMB$READ_MESSAGE_ITEM
Performs the following activities:
1

Reads a buffer that was filled by the SMB$READ_MESSAGE
routine.

2 Parses one message-item from the buffer.
3 Writes the item's code into a longword.
4

Writes the item into a buffer.

FORMAT

SMB$READ_MESSAGE_ITEM

RETURNS

VMS Usage:
type:
access:
mechanism:

message,context
, item—code, buffer
[rsize]

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return (by value) a condition
value in RO. Condition values that can be returned by this routine 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
VMS Usage:
type:
access:
mechanism:

context
longword (unsigned)
read only
by reference

A value initalized to 0 specifying the first message item in the buffer to
be read. The context argument is the address of a longword that the
SMB$READ_MESSAGE—ITEM routine uses to determine the next messageitem to be returned. When this value is 0 , it indicates that
SMB$READ_MESSAGE—ITEM is to return the first message-item.

SMB-22

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

The SMB$READ_MESSAGE_JTEM 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.

item—code
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
write only
by reference

Item code specified in the message item that identifies the type of message
item. 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. The following diagram depicts the
format of a single message item:

15
ITEM
SIZE

ITEM
CODE
VARIABLE-LENGTH
MESSAGE

ZK-2037-84

SMB$READ_MESSAGE _ITEM copies the code from the second word in the
message-item to the longword specified by the item—code argument.
SMB$READ_MESSAGE—ITEM uses the item-size field in the message-item
to determine the length, in bytes, of the variable-length message.

buffer
VMS Usage:
type:
access:
mechanism:

char_string
character string
read 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. SMB$READ_MESSAGE—ITEM uses the RTL
STR$ string-handling routines to copy the message-item into the buffer.

SMB-23

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

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.

DESCRIPTION

There are seven functions that the job controller can request of the symbiont.
They are identified by the following codes:
SMBMSG$K_ST ART-STREAM

SMBMSG$K_STOP_STREAM

SMBMSG$K_ST ART_T ASK

SMBMSG$K_PAUSE_T ASK

SMBMSG$K_RESUME_TASK

SMBMSG$K_STOP_TASK

SMBMSG$K_RESET_STREAM
The job controller passes the symbiont a request that contains a code and,
optionally, a number of message-items that contain information that 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 cany 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.
The number of items in a request varies with each type of request. Therefore,
SMB$READ_MESSAGE—ITEM must be called repeatedly for each request to
ensure that all message-items are read. Each time SMB$READ_MESSAGEITEM 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 list shows the message-items that can be delivered with each
request:

REQUEST

message-item

SMBMSG$K_ST ART_T ASK

SMBMSG$K_ACCOUNT_NAME
SMBMSG$K_AFTER_TIME
SMBMSG$K_BOTTOM—MARGIN
SMBMSG$K_CHARACTERISTICS
SMBMSG$K_CHECKPOINT_DAT A
SMBMSG$K_ENTRY_NUMBER
SMBMSG$K_FILE_COPIES
SMBMSG$K_FILE_COUNT

SMB-24

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

REQUEST

message-item
SMBMSG$K_SETUP_MODULES
SMBMSG$K_FIRST_PAGE
SMBMSG$K_FORM_LENGTH
SMBMSG$K_FORM_NAME
SMBMSG$K_FORM_SETUP_MODULES
SMBMSG$K_FORM_WIDTH
SMBMSG$K_FILE_IDENTIFICATION
SMBMSG$K_MESSAGE_VECTOR
SMBMSG$K_FILE_SPECIFICATION
SMBMSG$K_JOB_COPIES
SMBMSG$K_JOB_COUNT
SMBMSG$K_JOB_NAME
SMBMSGSK_IOB_RESET_MODULES
SMBMSG$K_LAST_PAGE
SMBMSG$K_LEFT_MARGIN
SMBMSG$K_NOTE
SMBMSG$K_PAGE_SETUP_MODULES
SMBMSG$K_PARAMETER_1
SMBMSG$K_SEPARATION_CONTROL
SMBMSG$K_REQUEST_CONTROL
SMBMSG$K_PRIORITY
SMBMSG$K_QUEUE
SMBMSG$K_TIME_QUEUED
SMBMSG$K_TOP_MARGIN
SMBMSG$K_UIC
SMBMSG$K_USER_NAME
SMBMSG$K_RIGHT_MARGIN

SMBMSG$K_STOP_T ASK

SMBMSG$K_STOP_CONDITION

SMBMSG$K_PAUSE_T ASK

None

SMBMSG$K_RESUME_TASK

SMBMSG$K_ALIGNMENT_PAGES
SMBMSG$K_RELATIVE_PAGE
SMBMSGSK _REQUEST_CONTROL
SMBMSG$K_SEARCH_STRING

SMBMSG$K_ST ART_STRE AM

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

SMB-25

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

The following table shows the message-items that the symbiont can send to
the job controller:
•

SMBMSG$K -ACCOUNTING -DATA

•

SMBMSG$K_CHECKPOINT—DATA

•

SMBMSG$K_CONDITION—VECTOR

•

SMBMSG$K_DE VICE-STATUS

•

SMBMSG$K_REQUEST—RESPONSE

The following list 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 below 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 VAX/VMS print symbiont to the codes it
recognizes. The descriptions in the list describe how the standard VAX/VMS
print symbiont (PRTSMB.EXE) processes these items.
Note: Since 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_ACCOUNTING—DATA
This code identifies a 16-byte structure that the symbiont sends to the job
controller. This structure contains accounting statistics that the symbiont has
accumulated for the task. 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:
3
1

NUMBER OF PAGES PRINTED FOR THE JOB
NUMBER OF READS FROM DISK
NUMBER OF WRITES TO THE PRINTING DEVICE
UNUSED

ZK-2011 -84

SMBMSG$K—ACCOUNT—NAME
This code identifies a string that contains the name of the account to be
charged for the job, the account of the process that submitted the print job.
The job controller sends this item to the symbiont.

SMB—26

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

SMBMSG$K_AFTER_TIME
This code identifies a 64-bit, absolute-time value that specifies the system
time after which the job controller can process this job. The job controller
sends this item to the symbiont.

SMBMSG$K_ALIGNMENT_PAGES
This code identifies a longword that specifies the number of alignment
pages that the symbiont is to print. The job controller sends this item to the
symbiont.

SMBMSG$K_BOTTOM—MARGIN
This code identifies a longword that contains the number of lines that are to
be left blank at the bottom of a page. The job controller sends this item to
the symbiont.
If the symbiont determines that:
1

The number of lines left at the bottom of the page is equal to this value

2 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, and

3 The /FEED qualifier was specified with the PRINT command that caused
the symbiont to perform this task,
then the symbiont inserts a formfeed character into the output stream.
(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 32-byte structure that specifies characteristics of the
job. A detailed description of the format of this structure is contained in the
description of the SJC$_CHARACTERISTIC code in the SYS$SNDJBC system
service in the VAX/VMS System Services Reference Manual. The job controller
sends this item to the symbiont.

SMBMSG$K_CHECKPOINT-DATA
This code identifies a user-defined structure that contains checkpointing
information. The symbiont sends this item to the job controller, which saves
it in the queue's data file.
When a restart-from-checkpoint request is executed for the queue, the job
controller retrieves the checkpointing information from the queue's data file
and sends it to the symbiont with a SMBMSG$K_START—TASK request. The
symbiont uses the checkpointing information to reposition the input file to
the point corresponding to the last page output at the time of the checkpoint.

SMBMSGSK—CONDITION—VECTOR
This code identifies an array of longwords, each longword containing a code
that specifies a termination status for the current request. The symbiont sends
this item to the job controller. For example, the STS and STV values from an
RMS control block might be two longwords in the array.

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.

SMB-27

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

SMBMSG$K_DEVICE_STATUS
This code identifies a longword bit-vector, each bit of which specifies device¬
status information. The symbiont sends this item to the job controller. The
$SMBDEF macro defines these device-status bits. The following describes the
effect of setting each bit in the longword.

Device Status Bit

Description

SMBMSG$V_LOWERCASE

The device to which the symbiont is connected
supports lowercase characters.

SMBMSG$V_PAUSE_T ASK

Informs 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_ST ALLED

Symbiont processing is temporarily stalled.

SMBMSG$ V_ST OR_STRE AM

The symbiont requests that the job controller
stop the queue.

SMBMSG$V_TERMINAL

The symbiont is connected to a terminal.

SMBMSG$V_UN AVAILABLE

The device to which the symbiont is assigned is
not available.

SMBMSG$K_ENTRY_NUMBER
This code identifies a longword that contains the number that the job
controller assigned to the job. The job controller sends this item to the
symbiont.

SMBMSG$K_EXECUTOR_QUEUE
This code identifies a string that is the name of the queue on which the
currently executing job is listed. The job controller sends this item to the
symbiont.

SMBMSG$K__FILE_COPIES
This code identifies a longword that contains 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. The job controller sends this item to the
symbiont.

SMBMSG$K_FILE—IDENTIFICATION
This code identifies a 28-byte structure that identifies the file to be processed.
This structure consists of the following three file-identification fields in the
RMS NAM block:
•

The 16-byte NAM$T_DVI field

•

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 above.
The job controller sends this item to the symbiont.

SMB-28

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

SMBMSG$K_FILE _SETUP_MODULES
This code identifies a string that specifies the names of one or more text
modules that the symbiont should copy from the library into the output
stream before processing the file. When more than one name is given,
commas separate them. The job controller sends this item to the symbiont.

SMBMSG$K_FILE_SPECIFICATION
This code identifies a string that specifies the name of the file that the
symbiont is to process. This file name is formatted as a standard RMS file
specification. The job controller sends this item to the symbiont.

SMBMSG$K_FIRST_PAGE
This code identifies a longword that contains 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). The job controller sends this item to the symbiont.

SMBMSG$K_FORM_NAME
This code identifies a string that specifies the name of the form. The job
controller sends this item to the symbiont.

SMBMSG$K__FORM_SETUP_MODULES
This code identifies a string that consists of the names of one or more
modules that the symbiont should copy from the device-control library
before processing the file. When more than one name is given, commas must
separate them. The job controller sends this item to the symbiont.

SMBMSG$K_FORM_WIDTH
This code identifies a longword that specifies the width (in characters) of the
print-area on the physical form (the paper). The symbiont sends this item to
the job controller.

SMBMSG$K^JOB_COPIES
This code identifies a longword that specifies the number of copies of the job
that were requested. The job controller sends this item to the symbiont.

SMBMSG$K_JOB_COUNT
This code identifies a longword that specifies, out of the number of copies
requested (SMBMSG$K_JOB_COPIES), the number of the copy of the job
currently printing. The job controller sends this item to the symbiont.

SMBMSG$K_JOB_NAME
This code identifies a string that specifies the name of the job. The job
controller sends this item to the symbiont.

SMBMSG$K^JOB_RESET_MODULES
This code identifies a string that specifies the names of one or more modules
that the symbiont should copy from the device-control library after processing
the task. These modules can be used to reset programmable devices to a
known state. When more than one name is given, commas must separate
them. The job controller sends this item to the symbiont.

SMB-29

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

SMBMSG$K_LAST_PAGE
This code identifies a longword that specifies the number of the last page that
the symbiont is to print. The job controller sends this item to the symbiont.
When not specified, the symbiont attempts to print all the pages in the file.

SMBMSG$K_LEFT_MARGIN
This code identifies a longword that specifies the number of spaces to be
inserted at the beginning of each line. The job controller sends this item to
the symbiont.

SMBMSG$K__LIBRARY_SPECIFICATION
This code identifies a string that specifies the name of the device-control
library. The job controller sends this item to the symbiont.

SMBMSG$K_MESSAGE_VECTOR
This code identifies a vector of longword condition-codes, each of which
contains information about the job to be printed. The job controller sends
this item to the symbiont.
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. The job controller sends this item to
the symbiont.

SMBMSG$K_PAGE_SETUP_MODULES
This code identifies a string that consists of the names of one or more modules
that the symbiont should copy from the device-control library before printing
each page. When more than one name is given, commas must separate them.
The job controller sends this item to the symbiont.

SMBMSG$K_PARAMETER_1 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 your symbiont. The VAX/VMSsupplied symbiont makes no use of these eight items. The job controller
sends these items to the symbiont.

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. The job controller sends this item to the symbiont.
The $SMBDEF macro defines the following symbols for each bit in the
bit-vector:

SMB-30

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

Symbol

Description

SMBMSGS V_DOUBLE -SPACE

When specified, the symbiont uses a double¬
spaced format; it skips a line after each line it
prints.

SMBMSG$V_NORECORD_
BLOCKING

When specified, the symbiont performs single
record output, issuing a single output record for
each input record.

SMBMSGS V_PAGE_HEADER

When specified, the symbiont prints a page
header at the top of each page.

SMBMSG$V_P AGIN ATE

When specified, the symbiont inserts a
formfeed character when it detects an attempt
to print in the bottom margin of the current
form.

SMBMSG$V_PASSALL

When specified, the symbiont prints the file
without formatting. The symbiont bypasses all
formatting normally performed. Furthermore,
the symbiont outputs the file without formatting
by causing the output QIO to suppress
formatting by the driver.

SMBMSGS V_RECORD_
BLOCKING

When specified, the symbiont performs record
blocking, buffering output to the device.

SMBMSG$V_SEQUENCED

This bit is reserved to DIGITAL.

SMBMSG$V_SHEET_FEED

When specified, the symbiont pauses after each
page that it prints.

SMBMSG$V_TRUNCATE

When specified, the symbiont truncates input
lines that exceed the right margin of the current
form.

SMBMSGSV—WRAP

When specified, 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 that specifies the priority that this job has
in the queue in which it is entered. The job controller sends this item to the
symbiont.

SMBMSG$K_QUEUE
This code identifies a string that specifies the name of the queue in which
this job is entered. The job controller sends this item to the symbiont. 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 that specifies the number of
pages that the symbiont is to move forward (positive value) or backward
(negative value) from the current position in the file. The job controller sends
this item to the symbiont.

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 job controller sends this item to the symbiont.
The $SMBDEF macro defines the following symbols for each bit:

SMB-31

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

Symbol

Description

SMBMSG$V_ALIGNMENT_MASK

When specified, 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

When specified, the symbiont is to pause
when it has completed the current request.

SMBMSG$V_RESTARTING

When specified, indicates that this job was
previously interrupted and requeued, and is
now restarting.

SMBMSG$V_TOP_OF_FILE

When specified, the symbiont is to rewind
the input file before it resumes printing.

SMBMSG$K_REQUEST_RESPONSE
This code identifies a longword that specifies the type of request for which
the symbiont is currently signalling completion. The symbiont sends this item
to the job controller. The following symbols define types of requests that can
be specified in this item:
SMBMSG$K_ST ART_STRE AM

SMBMSG$K_STOP_STREAM

SMBMSG$K_ST ART_T ASK

SMBMSG$K_PAUSE_TASK

SMBMSG$K_RESUME_T ASK

SMBMSG$K_STOP_T ASK

SMBMSG$K_RESET_STREAM

SMBMSG$K_COMPLETE_T ASK

SMBMSG$K_T ASK_ST ATUS

SMBMSG$K_RIGHT_MARGIN
This code identifies a longword that specifies the number of character
positions to be left empty at the end of each line. The job controller sends
this item to the symbiont. 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 that contains the value that the user specified in
the START/QUEUE/SEARCH command. The job controller sends this item
to the symbiont. This string identifies the page at which to restart the printing
task current 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 job controller sends this item to the symbiont. The
$SMBDEF macro defines the following symbols for each bit:

SMB-32

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

Symbol

Description

SMBMSG$V_FILE _BURST

When specified, the symbiont is to
print a file-burst page.

SMBMSG$V_FILE_FLAG

When specified, the symbiont is to
print a file-flag page.

SMBMSG$V_FILE_TRAILER

When specified, the symbiont is to
print a file-trailer page.

SMBMSG$V_FILE_TRAILER_ABORT

When specified, the symbiont is to
print a file-trailer page when a task is
completed abnormally.

SMBMSG$V_FIRST_FILE_OF_JOB

When specified, 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.

SMBMSGSV_IOB—FLAG

When specified, the symbiont is to
print a job-flag page.

SMBMSG$V_JOB_BURST

When specified, the symbiont is to
print a job-burst page.

SMBMSG$V_JOB_RESET

When specified, the symbiont is to
execute a job-reset Sequence when the
task is completed.

SMBMSG$V_JOB_RESET_ABORT

When specified, the symbiont is to
execute a job-reset sequence when a
task is completed abnormally.

SMBMSG$V_JOB_TRAILER

When specified, the symbiont is to
print a job-trailer page.

SMBMSG$V_JOB_TRAILER_ABORT

When specified, the symbiont is to
print a job-trailer page when a task is
completed abnormally.

SMBMSG$V_LAST_FILE_OF_JOB

When specified, 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 that contains a condition that specifies the
reason the job controller issued a STOP-TASK request. The job controller
sends this item to the symbiont.

SMBMSG$K—TIME—QUEUED
This code identifies a quadword that specifies the time when the file was
entered into the queue. The time is expressed as 64-bit, absolute time. The
job controller sends this item to the symbiont.

SMBMSG$K—TOP—MARGIN
This code identifies a longword that specifies 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.

SMBMSGSK-UIC
This code identifies a longword that specifies the User Identification Code
(UIC) of the user who submitted the job.

SMB-33

Symbiont/Job Controller Interface (SMB) Routines
SMB$READ_MESSAGE_ITEM

SMBMSG$K_USER_NAME
This code identifies a string that specifies the name of the user who submitted
the job.

CONDITION

SS$_NORMAL

Routine completed successfully

VALUES

SMB$_NOMOREITEMS

End of item list reached

RETURNED

Any condition code returned by the Run-Time Library string-handling (STR$)
routines.

SMB-34

Symbiont/Job Controller Interface (SMB) Routines
SMB$SEND_TO^JOBCTL

SMB$SEND_TO—JOBCTL
Used by your symbiont to send messages to the job controller.
Three types of messages can be sent: request-completion
messages, task-completion messages, and task-status messages.

FORMAT

SMB$SEND_TO_JOBCTL

RETURNS

VMS Usage:
type:
access:
mechanism:

stream [,request]
[,accounting]
[,checkpoint]
[, device—status] [, error]

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

stream
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

Stream number specifying the stream to which the message refers. The
stream argument is the address of a longword that contains the number of
the stream to which the message refers.

request
VMS Usage:
type:
access:
mechanism:

identifier
longword (unsigned)
read only
by reference

Request code identifying the request being completed. The request argument
is the address of a longword that contains the code that identifies the request
that has been completed.
The code usually corresponds to the code that 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-35

Symbiont/Job Controller Interface (SMB) Routines
SMB$SEND_TO_JOBCTL

accounting
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Accounting information about a task. The accounting argument is the address
of a descriptor that points to the accounting information about a task. Note
that this structure is passed by descriptor and not by reference.
See the description of the SMBMSG$K_ACCOUNTING_DATA item for
more information on this accounting information.
The following diagram depicts the contents of the 16-byte structure:

NUMBER OF PAGES PRINTED FOR THE JOB
READS FROM DISK OR TAPE
NUMBER OF READS
NUMBER OF WRITES
WRITES TO THE PRINTING DEVICE
UNUSED

ZK-2012-84

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 a 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's
data file. When a restart-from-checkpoint request is executed for the queue,
the job controller retrieves the checkpointing information from the queue's
data file 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-data file, 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 with the convenience of restarting.

SMB-36

Symbiont/Job Controller Interface (SMB) Routines
SMB$SEND_TO_JOBCTL

device—status
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

The status of the device served by the symbiont. The device_status
argument is the address of a longword passed to the job controller that
contains the status of the device to which the symbiont is connected.
This longword contains a longword bitvector, each bit of which specifies
device-status information. The $SMBDEF macro defines these device-status
bits. The following describes each bit and its meaning.
Device Status Bit

Description

SMBMSG$V_LOWERCASE

The device to which the symbiont is connected
supports lowercase characters.

SMBMSG$V_PAUSE_T ASK

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_ST ALLED

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_UN AVAILABLE

The device to which the symbiont is connected
is not available.

error
VMS Usage:
type:
access:
mechanism:

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.
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's data file. The first condition value is included
in the job-accounting record that is written to the system's accounting file
(SYSSMANAGER: ACCOUNTNG.DAT).

SMB-37

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. The
fact that the symbiont sends the message 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 —STARTTASK as the request argument.
The responses to some requests use additional arguments to send more
information in addition to the request code. The following list shows which
additional arguments are allowed in response to each different request.
Request

Arguments

SMBMSG$K_ST ART-STREAM

request
device_status
error

SMBMSG$K_STOP_STREAM

request

SMBMSG$K_RESET_STREAM

request

SMBMSG$K_ST ART_T ASK

request

SMBMSG$K_PAUSE_TASK

request

SMBMSG$K_RESUME_TASK

request

SMBMSG$K_STOP_TASK

request
error *

*—(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 codes. The following
table shows the additional arguments that can be used with the messages
identified by these codes.
Code
SMBMSG$K_TASK_COMPLETE

Arguments
request
accounting
error

SMBMSG$K_T ASK_ST ATUS

request
checkpoint
device_status

The symbiont uses the SMB$K_TASK —STATUS message to update the job
controller on the status of a task during the processing of that task. The

SMB-38

Symbiont/Job Controller Interface (SMB) Routines
SMB$SEND_TO_JOBCTL

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 SMB$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 SMB$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 SMB$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 SMBSMG$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

Any conditions returned by $QIO system service and LIB$GET_VM routine.

SMB-39

1 1

Sort/Merge (SOR) Routines

11.1

Introduction To 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.
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 that is unique to MERGE.

SOR$BEGIN_SORT

Initializes sort operation by passing key information and
sort options. This is the only routine that is unique to
SORT.

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.

SORSRELEASE—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.

SORSSTAT

Returns a statistic about the sort or merge operation.

Note: SOR$DO_MERGE (from VAX/VMS Version 3.0) can still be called as
the equivalent of SOR$END-SORT; SOR$INIT—MERGE and SOR$INIT_
SORT (from VAX/VMS Version 3.0) can still be called 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.
These SOR routines can be called from any language that supports the VAX
Procedure Calling and Condition Handling Standard.
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 that a program can test to determine success or failure
conditions.

SOR—1

Sort/Merge (SOR) Routines
Introduction To SOR Routines

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

11.1.2 Interfaces to SOR Routines
You can submit data to the SOR routines as complete file(s) 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
file(s) 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 depends 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 the SOR$STAT routine is used, it must be called before any other SOR
routine.

11.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 if you want to use your own key
comparison routine. SORT automatically generates a key comparison routine
that is efficient for key data type(s); however, you may want to provide your
own comparison routine to handle special sorting requirements. (For example,
you may want names beginning with "Me" 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 may be called at any time to abort a
sort, or merge and release all resources allocated to the sort or merge process.

SOR—2

Sort/Merge (SOR) Routines
Introduction To SOR Routines

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

11.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; call 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, call SOR$BEGIN —MERGE to pass key information and merge options,
to execute the merge. At this point, you must indicate if you want to use your
own key comparison routine tailored to your data. Finally, call
SOR$END_SORT to release resources.

11.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. The 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.

11.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
allows you to 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 may 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 that identifies the sort or merge operation. Additional calls to the

SOR—3

Sort/Merge (SOR) Routines
Introduction To SOR Routines

same sort or merge operation must pass the same context longword. The
SOR$END_SORT routine clears the context longword.

11.2

Examples Of Using SOR Routines
The following example is a FORTRAN program demonstrating a merge
operation using a record interface.

SOR—4

C...

for the merge record interface.

C. . .
C
C

THE INPUT FILES ARE LISTED BELOW.

C
C

INFILE1.DAT

C 1 BBBBBBBBBB REST OF DATA IN RECORD

C 2 UUUUUUUUUU REST OF DATA IN RECORD
C
C

INFILE2.DAT

C 1 AAAAAAAAAA REST OF DATA IN RECORD

C 2 TTTTTTTTTT REST OF DATA IN RECORD
C
C

INFILE3.DAT

C 1 ttttttTTTT REST OF DATA IN RECORD

C 2 BBBBBBBBBB REST OF DATA IN RECORD
C
C

FOROUT.DAT

C 1 AAAAAAAAAA REST OF DATA IN RECORD

C 1 BBBBBBBBBB REST OF DATA IN RECORD

C 1 TTTTTTTTTT REST OF DATA IN RECORD

C 2 BBBBBBBBBB REST OF DATA IN RECORD

C 2 TTTTTTTTTT REST OF DATA IN RECORD

C 2 UUUUUUUUUU REST OF DATA IN RECORD
C
C

C
C
C
IMPLICIT INTEGER (A-Z)
CHARACTER * 80 REC

A record

EXTERNAL READ.REC

Routine

EXTERNAL KOMPAR

Routine

EXTERNAL SS$_ENDOFFILE

System e

INTEGERS SOR$BEGIN_MERGE

SORT/MER

INTEGER*4 SOR$RETURN_REC
INTEGERS SOR$END_SORT
INTEGER*4 ISTAT

storage

INTEGER*4 LENGTH

length

INTEGER*2 LRL

Longest

LOGICAL*! ORDER

#files

DATA ORDER,LRL/3,80/

Order o

c...
C...
C. . .

First open all the input files.

*
*
*
C
C...
C

OPEN (UNIT=10, FILE='INFILE1.DAT'.TYPE*'OLD'.READONLY,
F0RM='FORMATTED')
OPEN (UNIT=11, FILE*•INFILE2.DAT',TYPE='OLD',READONLY,
FORM-'FORMATTED')
OPEN (UNIT*12. FILE*'INFILE3.DAT•,TYPE*'OLD',READONLY,
FORM*'FORMATTED')
Open the output file.
OPEN (UNIT=8, FILE*'TEMP.TMP', TYPE*'NEW')

C. . .
C...
C...
C...
C. . .

Initialize the merge.
Pass the merge order, the largest
record length, the compare routine address, and the
input routine address.

C. . .
C...
C...
C. . .
5

200
C. . .
C...
C. . .
30

C. . .
C. ..
C...
C. . .
10
201

ISTAT = SOR$BEGIN_MERGE (.LRL,,ORDER,
KOMPAR,,READ_REC)
IF (.NOT. ISTAT) GOTO 10
! Check for error.

Now loop getting merged records.
SOR$RETURN_REC will
call READ_REC when it needs input.

ISTAT = SOR$RETURN_REC (REC, LENGTH)
IF (ISTAT .EQ. */.LOC(SS$_ENDOFFILE)) GO TO 30
! Check for end of
IF (.NOT. ISTAT) GO TO 10
! Check for error.
WRITE(8.200) REC
FORMAT(' '.A)
GOTO 5

! Output the record.
! And loop back.

Now tell SORT that we are all done.
ISTAT = S0R$END_S0RT()
IF (.NOT. ISTAT) GOTO 10
CALL EXIT
Here if an error occurred.
and exit.

! Check for error.

Write out the error status

WRITE(8.201)ISTAT
FORMAT(' TERROR CODE', 120)
CALL EXIT
END

(Continued on n

SOR—6

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 inp
for merging.
It will be called by SOR$BEGIN.ME
SOR$RETURN_REC.
Parameters:
RECX.wcp.ds

character buffer to hol
it is read in.

FILE.rl.r

indicates which file th
to be read from.
1 spe
first file, 2 specifies
etc.

LENGTH.wl.r

is the actual number of
the record.
This is se

IMPLICIT INTEGER (A-Z)
PARAMETER MAXFIL=10

! Max n

EXTERNAL SS$_ENDOFFILE
EXTERNAL SS$_NORMAL

! End o
! Succe

LOGICAL+1 FILTAB(MAXFIL)
CHARACTER*(80) RECX

! MAX L

DATA FILTAB/10,11,12,13,14,15,16,17,18,19/ ! Ta

READ.REC = */.L0C(SS$_END0FFILE)
! Give e
IF (FILE .LT. 1 .OR. FILE .GT. MAXFIL) RETURN
100

READ (FILTAB(FILE). 100, ERR=75, END=50) RECX
FORMAT(A)
READ.REC = */,L0C (SS$_N0RMAL)
SIZE = LEN (RECX)
RETURN

c.. .
50
C...
75

Here if end of file.
READ.REC = 7.L0C (SS$_ENDOFFILE)
RETURN
Here if error while reading
READ.REC = 0
SIZE = 0
RETURN
END

! Retur
! Retur

! Retur

Sort/Merge (SOR) Routines
Examples Of Using SOR Routines

Example SOR-1

(Cont.)

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

FUNCTION KOMPAR (REC1.REC2)
C. . .
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.
PARAMETER KEYSIZ=10
IMPLICIT INTEGER (A-Z)
LOGICAL*1 REC1(KEYSIZ),REC2(KEYSIZ)

DO 20 1=1,KEYSIZ
KOMPAR = RECl(I) - REC2(I)
IF (KOMPAR .NE. 0) GOTO 50
CONTINUE
RETURN

KOMPAR = ISIGN (1, KOMPAR)
RETURN
END

The following example is a FORTRAN program demonstrating a sort
operation using a file interface on input and a record interface on output.

SOR—8

C
C
C
This is a sample FORTRAN program that calls the
C
routines using the file interface for input and
C
record interface for output.
This program requ
C
a record sort of the file 'R010SQ.DAT'
and w
C
the records to SYS$OUTPUT.
The key is an 80C
character ascending key starting in position
C
each record.
C
C
A short version of the input and output files f
C
C
Input file R010SQ.DAT
C 1 BBBBBBBBBB REST OF DATA IN RECORD
C 2 UUUUUUUUUU REST OF DATA IN RECORD
C 1 AAAAAAAAAA REST OF DATA IN RECORD
C 2 TTTTTTTTTT REST OF DATA IN RECORD
C i TTTTTTTTTT REST OF DATA IN RECORD
C 2 BBBBBBBBBB REST OF DATA IN RECORD
C 1 QQQQQQQQQQ REST OF DATA IN RECORD
C 2 AAAAAAAAAA REST OF DATA IN RECORD
C 1 UUUUUUUUUU REST OF DATA IN RECORD
C 2 QQQQQQQQQQ REST OF DATA IN RECORD
C
C
Output file SYSSOUTPUT
C
C 1 AAAAAAAAAA REST OF DATA IN RECORD
C 1 BBBBBBBBBB REST OF DATA IN RECORD
C 1 QQQQQQQQQQ REST OF DATA IN RECORD
C 1 TTTTTTTTTT REST OF DATA IN RECORD
C i UUUUUUUUUU REST OF DATA IN RECORD
C 2 AAAAAAAAAA REST OF DATA IN RECORD
C 2 BBBBBBBBBB REST OF DATA IN RECORD
C 2 QQQQQQQQQQ REST OF DATA IN RECORD
C 2 TTTTTTTTTT REST OF DATA IN RECORD
C 2 UUUUUUUUUU REST OF DATA IN RECORD
C
C...C
C
Define external functions and data.
C
CHARACTER*80 RECBUF
!Input file nam
CHARACTER*10 INPUTNAME
!Key definition
INTEGER*2 KEYBUF(5)
ISORT function
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
!Storage for SO
INTEGER*4 ISTATUS
EXTERNAL SS$_ENDOFFILE
EXTERNAL DSC$K_DTYPE_T
EXTERNAL SOR$GK_RECORD
INTEGER*4 SRTTYPE

Sort/Merge (SOR) Routines
Examples Of Using SOR Routines

Example SOR-2

(Cont.)

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

c
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.
DATA INPUTNAME/'R010SQ.DAT'/
KEYBUF(1) = 1
KEYBUF(2) = */,L0C (DSC$K_DTYPE_T)
KEYBUF(3) = 0
KEYBUF(4) = 0
KEYBUF(5) = 80
SRTTYPE = '/,L0C (S0R$GK_REC0RD)

C
C
C
C
C
C

Call the SORT -- each call is a function.

Pass SORT the file names.
ISTATUS = SOR$PASS_FILES(INPUTNAME)
IF (.NOT. ISTATUS) GOTO 10

C
C
C

Initialize the work areas and keys.
ISTATUS = S0R$BEGIN_S0RT (KEYBUF,,,,,, SRTTYPE,‘/.REF (3))
IF (.NOT. ISTATUS) GOTO 10

C
C
C

Sort the records.
ISTATUS = S0R$S0RT_MERGE( )
IF (.NOT. ISTATUS) GOTO 10

C
C
C
5

6
C
C
C
7

Now retrieve the individual records and display them.
ISTATUS = SOR$RETURN_REC(RECBUF)
IF (.NOT. ISTATUS) GOTO 6
ISTATUS = LIB$PUT_OUTPUT(RECBUF)
GOTO 5
IF (ISTATUS .EQ. 7.L0C(SS$_END0FFILE)) GOTO 7
GOTO 10
Clean up the work areas and files.
ISTATUS = S0R$END_S0RT()
IF (.NOT. ISTATUS) GOTO 10
STOP 'SORT SUCCESSFUL'
STOP 'SORT UNSUCCESSFUL'
END

The following example is a Pascal program demonstrating a merge operation
using a file interface.

SOR—10

Sort/Merge (SOR) Routines
Examples Of Using SOR Routines

Example SOR-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 = i;
SS$_ENDOFFILE * 7.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 = [BYTE] 0..255;
$UW0RD = [WORD] 0..65535;
const
num_of_keys = 1;
merge.order = 3;
lrl
= 131;
ascending
descending

= 0;
= 1;

type
key_bufferJblock=
packed record
key_type:
key_order:
key_offset:
key.length:
end;
key_buffer_type=
packed record
key.count:
blocks:
end;
record_buffer =

$uword;
$uword;
$uword;
$uword;

$uword;
packed array[1..num_of_keys] of key.buffer_block;
packed array[1..lrl] of char;

record_buffer_descr =
packed record
length: $uword;
dummy:
$uword;
addr:
~record_buffer;
end;

(Continued on next page)

SOR—11

Sort/Merge (SOR) Routines
Examples Of Using SOR Routines

Example SOR-3

in.filel,
in_file2,
in_file3,
out_file:
key_buffer:
rec.buffer:
rec_length:
status:
i:

(Cont.)

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

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 := 0;
%immed eql.rtn: integer := 0;
Rimmed [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;
var rec.size:
$uword
): integer; extern;
function sor$end_sort: integer; extern;
procedure sys$exit( dimmed 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 :■ 0;
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.addr~[recordsize]);
end;
readln(filename);
end;
end;

(Continued on next page)

SOR—12

Sort/Merge (SOR) Routines
Examples Of Using SOR Routines

Example SOR-3

(Cont.)

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

begin
read.record := ss$_normal;
case filenumber of
1: 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^Xx', status:8 hex );
sys$exit(status);
end;
begin
with key.buffer do
begin
key_count := 1;
with blocks[1] 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,
8or$m_seq_check + sor$m_signal,
merge_order, 0, 0, read_record );

(Continued on next page)

SOR—13

Sort/Merge (SOR) Routines
Examples Of Using SOR Routines

Example SOR-3

(Cont.)

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

repeat
begin
rec_length := 0;
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);
if status <> ss$_endoffile then error(status);
status := sor$end_sort;
if not odd(status) then error(status);
writeln(

'merge successful.'

);

end.

The following example is a Pascal program demonstrating a sort operation
using a record interface.

SOR—14

Sort/Merge (SOR) Routines
Examples Of Using SOR Routines

Example SOR-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, (PASINPUT1.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 $UW0RD (an unsigned word). *)

CONST
SSS.NORMAL = 1;
SSS.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 = [BYTE] 0..255;
$UW0RD = [WORD] 0..65535;
CONST
Numberofkeys = 1 ;
LRL = 131 ;

(* Number of keys for this sort *)
(* Longest Record Length for output records *)

(* Key orders *)
Ascending = 0 ;
Descending = 1 ;
TYPE
Keybufferblock= packed record
Keytype : $UW0RD ;
Keyorder : $UW0RD ;
Keyoffset : $UW0RD ;
Keylength : $UW0RD
end ;
(* The keybuffer. Note that the field buffer is a one-component array in
this program. This type definition would allow a multikeyed sort. *)
Keybuffer= packed record
Numkeys : $UW0RD ;
Blocks : packed array[1..Numberofkeys] OF Keybufferblock
end ;

(Continued on next page)

SOR—15

Sort/Merge (SOR) Routines
Examples Of Using SOR Routines

Example SOR-4

(Cont.)

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

(* The record buffer. This buffer will be used to hold the returned
records from SORT. *)
Recordbuffer * packed array[1..LRL] of char ;
(« Name type for input and output files. A necessary fudge for %stdescr
mechanism.
*)
nametype= packed array[1..13] of char ;
VAR
Sortout : text ;
Buffer : Keybuffer ;
Sortoptions : integer ;
Sorttype : $UBYTE ;
Numworkfiles : $UBYTE ;
Status : integer ;
Rec : Recordbuffer ;
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 Buffer : Keybuffer ;
Lrlen : $UWORD ;
VAR Sortoptions : INTEGER ;
RIMMED Filesize : INTEGER ;
•/.IMMED Usercompare : INTEGER ;
DIMMED Userequal : INTEGER ;
VAR Sorttype : lUBYTE ;
VAR Numworkfiles : $UBYTE )
: INTEGER ; EXTERN ;

(Continued on next page)

SOR—16

FUNCTION SOR$RETURN_REC(
'/.STDESCR Rec : Recordbuffer ;
VAR Recordsize : $UW0RD )
: INTEGER ; EXTERN ;
FUNCTION SOR$END_SORT
: INTEGER ; EXTERN ;
(* End of the SORT function declarations *)

(* The CHECKSTATUS routine checks the return status for
(* If there is an error, write an error message and 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 *)
(* end function and routine declarations *)
BEGIN

(* begin the main routine *)

(* Initialize data for one 8-byte character key, startin
offset 0, 3 work files, and the record sorting proces
Inputname := 'PASINPUT1.DAT' ;
WITH Buffer DO
BEGIN
Numkeys := 1;
WITH Blocks[1] DO
BEGIN
Keytype := DSC$K_DTYPE_T ;
Keyorder := Ascending ;
Keyoffset := 0 ;
Keylength := 8 ;
END;
END;

(* Use VMS desc
define S

(* Use the global SORT constant to
define the sort process. *)
(* Use the global SORT constant to
define the stable sort option

Sorttype := S0R$GK_REC0RD ;
Sortoptions := SOR$M_STABLE ;
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. *)
CHECKSTATUSC Status ) ;
(* pass the second filename to SORT *)
Inputname :» 'PASINPUT2.DAT' ;
Status := SOR$PASS_FILES( Inputname )

;

(* Check status for error. *)
CHECKSTATUSC Status ) ;
(* initialize work areas and keys *)
Status
S0R$BEGIN_S0RT( Buffer, 0, Sortoptions, 0, 0, 0,
Sorttype, Numworkfiles ) ;
C* Check status for error. *)
CHECKSTATUSC Status ) ;
C* sort the records *)
Status := S0R$S0RT_MERGE ;
C* Check status for error. *)
CHECKSTATUSC Status ) ;
C* Ready output file for writting returned records from SORT. *)
OPENC S0RT0UT, 'TEMP.TMP' ) ;
REWRITEC S0RT0UT ) ;
C* Now get the sorted records from SORT. *)
Recordlength := 0 ;
REPEAT
Status := S0R$RETURN_RECC Rec, Recordlength )

;

if oddC Status )
then
C* if successful, write record to output file. *)
begin
for i := 1 to Recordlength do
writeC sortout, Rec[i] ) ;
C* write each character *)
writeln Csortout) ;
C* end output line *)
end;
UNTIL not oddC Status ) ;

(Continued on n

SOR—18

Sort/Merge (SOR) Routines
Examples Of Using SOR Routines

Example SOR-4

(Cont.)

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

(* 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 ) ;
(* clean up work areas and files *)
Status := S0R$END_S0RT ;
(* Check status for error.
CHECKSTATUSC Status );

WRITELN ('SORT SUCCESSFUL')

;

END.

11.3

SOR Routines
The following pages describe the individual SOR routines in routine template
format.

SOR—19

Sort/Merge (SOR) Routines
SOR$BEGIN_MERGE

SOR$BEGIN_MERGE—Initialize a Merge
Operation
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][,lrl]
[, options] [, merge—order]
[, user—compare]
[, user—equal] [, user—input]
[, context]

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

key—buffer
VMS Usage:
type:
access:
mechanism:

vector_word_unsigned
word (unsigned)
read only
by reference

Array of words describing the key(s) on which you plan to merge. The
key_buffer argument is the address of an array containing the key
descrip tion(s).
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:

SOR—20

DSC$K_DTYPE_Z

Unspecified (uninfluenced by collating sequence)

DSC$K_DTYPE_B

Byte integer (signed)

DSC$K_DTYPE_BU

Byte (unsigned)

DSC$K_DTYPE_W

Word integer (signed)

DSC$K_DTYPE_WU

Word (unsigned)

DSC$K_DTYPE_L

Longword integer (signed)

Sort/Merge (SOR) Routines
SOR$BEGIIM—MERGE

DSC$K_DTYPE_LU

Longword (unsigned)

DSC$K_DTYPE_Q

Quadword integer (signed)

DSC$K _DTYPE _QU

Quadword (unsigned)

DSC$K_DTYPE_0

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 Section 2 in the Introduction to VAX/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.

Irl
VMS Usage:
type:
access:
mechanism:

word—unsigned
word (unsigned)
read only
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. This argument is
not required if the input file is on a disk. 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:
type:
access:
mechanism:

mask—longword
longword (unsigned)
read only
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
bit mask values available are as follows:

SOR—21

Sort/Merge (SOR) Routines
SOR$BEGI INI—MERGE

Flag

Description

SORSM-STABLE

Keeps records with equal keys in the same order in
which they appeared on input.

SOR$M_EBCDIC

Orders ASCII character keys according to EBCDIC
collating sequence. No translation takes place.

SORSM-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 signalling 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:
type:
access:
mechanism:

byte_unsigned
byte (unsigned)
read only
by reference

Number of input streams to be merged. The merge—order argument is the
address of a byte containing the number of files (1-10) to be merged. This
argument is required when you use the record interface on input.

user—compare
VMS Usage:
type:
access:
mechanism:

procedure
procedure entry mask
function call
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. This argument is required if you do not specify the key—buffer
argument, or if you define key information in a specification file.
MERGE calls the comparison routine with five reference arguments—ADRS1,
ADRS2, LENG1, LENG2, CNTX—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—22

•

-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
VMS Usage:
type:
access:
mechanism:

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. Do not use this argument if you specify SOR$M—STABLE or
SOR$M—NODUPS in the options argument.
MERGE calls the duplicate key routine with five reference arguments—
ADRS1, ADRS2, LENG1, LENG2, CNTX—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 a 32-bit condition code:

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
VMS Usage:
type:
access:
mechanism:

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.
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 a status value.
•

SS$_NORMAL or any other success status causes the merge operation to
continue

•

SS$_ENDOFFILE indicates that no more records are in the file. The
contents of the buffer are ignored.

SOR—23

Sort/Merge (SOR) Routines
SOR$BEGIN_MERGE

•

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:
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 that was supplied by
SORT/MERGE.

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
pass 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 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
R ETU R NED

SOR—24

SSS—NORMAL

Success.

SOR$_BADDTYPE

Invalid or unsupported CDD datatype.

sor$_b adlenoff

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 CDD object.

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

Sort/Merge (SOR) Routines
SOR$BEGIN_MERGE

SOR$_CDDERROR

CDD error at node 'name'.

SOR$_CLOSEIN

Error closing 'file' as input.

SOR$_CLOSEOUT

Error closing 'file' as output.

SORS—COL _CH AR

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

Nondecimal base is invalid.

SOR$_ILLLITERL

Record containing symbolic literals is unsupported.

SOR$_ILLSCALE

Nonzero scale invalid for floating-point data-item.

SOR$_INCDIGITS

Number of digits is not consistent with the type or
length of item.

SORS—INCNOD AT A

Include specification references no data, at line n.

SOR$_INCNOKEY

Include specification references no keys, at line n.

SOR$_IND_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$_LRI_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 _ke y

Too many keys specified.

SOR$_OPENIN

Error opening 'file' as input.

SOR$_OPENOUT

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 datatype 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—25

Sort/Merge (SOR) Routines
SOR$BEGIN_MERGE

SOR—26

SOR$_SPCIVX

Invalid condition specification at line n.

SOR$_SPCMIS

Invalid merge specification at line n.

SOR$_SPCOVR

Overridden specification at line n.

SORS—SPCSIS

Invalid sort specification at line n.

SOR$_SRTIWA

Insufficient space; specification file is too complex.

SOR$_ST ABLEEX

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$BEGII\l_SORT—Begin a Sort
Operation
Initializes a sort operation by opening input and output files and by
passing the key information and any sort options.

FORMAT

SORSBEGIN-SORT

RETURNS

VMS Usage:
type:
access:
mechanism:

[key-buffer][,lrl][,options]
[, file—alloc] [, user—compare]
[,user— equal] [,sort—process]
[, work— files] [, context]

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

key—buffer
VMS Usage: vector_word_unsigned
type:
word (unsigned)
access:
read only
mechanism: by reference
Array of words describing the key(s) on which you plan to sort. The
key-buffer argument is the address of an array containing the key
description(s).
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

Unspecified (uninfluenced by collating sequence)

DSC$K_DTYPE_B

Byte integer (signed)

DSC$K_DTYPE_BU

Byte (unsigned)

DSC$K_DTYPE_W

Word integer (signed)

DSC$K_DTYPE_WU

Word (unsigned)

DSC$K_DTYPE_L

Longword integer (signed)

DSC$K_DTYPE_LU

Longword (unsigned)

DSC$K_DTYPE_Q

Quadword integer (signed)

SOR—27

Sort/Merge (SOR) Routines
SOR$BEGIN_SORT

DSC$K_DTYPE_QU

Quadword (unsigned)

DSC$K_DTYPE_0

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 Section 2 in the Introduction to VAX/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 address 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.

Irl
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 file(s) is 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
bit mask values available are as follows:

SOR—28

Sort/Merge (SOR) Routines
SOR$BEGIN_SORT

Flags

Description

SOR$M _ST ABLE

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 signalling an error.
SOR$M—NOSIGNAL is the default.

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—alloc
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
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.
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:
type:
access:
mechanism:

procedure
procedure entry mask
function call
by reference

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. This argument is required if you do not specify the key_buffer
argument, or if you define key information in a specification file.
SORT/MERGE calls the comparison routine with five reference arguments—
ADRS1, ADRS2, LENG1, LENG2, CNTX—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—29

Sort/Merge (SOR) Routines
SOR$BEGIN_SORT

user—equal
VMS Usage:
type:
access:
mechanism:

procedure
procedure entry mask
function call
by reference

Routine that resolves the sort order when records have duplicate keys.
The user—equal argument is the address of the entry mask for this userwritten routine. Do not use this argument if you specify SOR$M—STABLE or
SOR$M_NODUPS in the options argument.
SORT/MERGE calls the duplicate key routine with five reference
arguments—ADRS1, ADRS2, LENG1, LENG2, CNTX—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 a 32-bit integer condition code:
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:
type:
access:
mechanism:

byte_unsigned
byte (unsigned)
read only
by reference

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.
Specify a byte containing the value for the type of sort process you want:
•

SOR$GK_RECORD (record sort)

•

SOR$GK_TAG (tag sort)

•

SOR$GK_ADDRESS (address sort)

•

SOR$GK—INDEX (index sort)

work—files
VMS Usage:
type:
access:
mechanism:

byte—unsigned
byte (unsigned)
read only
by reference

Number of work files to be used in the sorting process. The work—files
argument is the address of a byte containing the number of work files;
permissible values range from 0 through 10.

SOR—30

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 file(s). You can increase
the number of work files to reduce their individual size so that each will
then fit 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

DESCRIPTION The SOR$BEGIN_SORT 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, 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 longest record length argument.
Some of the following 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

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

Insufficient virtual memory.

SOR$_KEYAMBINC

Key specification is ambiguous or inconsistent.

SOR$_KEY_LEN

Invalid key length, key number n, length n.

SORS—LRI_MISS

Longest record length must be specified.

SORS—NODUPEXC

Equal-key routine and no-duplicates option cannot
both be specified.

SOR—31

Sort/Merge (SOR) Routines
SOR$BEGIN_SORT

SOR—32

SOR$_NUM_KEY

Too many keys specified.

SOR$_RTNERROR

Unexpected error status from user-written routine.

SOR$_SORT_ON

Sort or merge routines called in incorrect order.

SOR$_ST ABLEEXC

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

SOR$END..SORT—End a Sort Operation
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. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
"CONDITION VALUES RETURNED."

ARGUMENT

context
VMS Usage:
type:
access:
mechanism:

context
longword
write only
by reference

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

SOR-33

Sort/Merge (SOR) Routines
SOR$END_SORT

CONDITION
VALUES
RETURNED

SOR—34

SS$_NORMAL

Success.

SORS—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.

Sort/Merge (SOR) Routines
SOR$PASS_FILES

SOR$PASS_FILES—Pass File Names
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] out—desc]],org]
[, rfm] [, bks] [, bis] [, mrs] alq]
[, fop] [, fsz] ], context]

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

inp—desc
VMS Usage:
type:
access:
mechanism:

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 specification(s). For multiple
input files, call SOR$PASS_FILES once for each input file, passing one input
file specification descriptor each time.
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 specification(s).
If you are using the record interface on output, pass only the input file
specification(s); do not pass an output file specification or any of the optional
output file arguments.

out—desc
VMS Usage:
type:
access:
mechanism:

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.
Call SOR$PASS_FILES(Input1,Output)
Call S0R$PASS_FILES(Input2)
Call S0R$PASS_FILES(Input3)

SOR—35

Sort/Merge (SOR) Routines
SOR$PASS_FILES

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
specification(s); do not pass an output file specification or any of the optional
output file arguments.

org
VMS Usage:
type:
access:
mechanism:

byte_unsigned
byte (unsigned)
read only
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:
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 on the FAB fields, see the VAX Record Management
Services Reference Manual.

rfm
VMS Usage:
type:
access:
mechanism:

byte_unsigned
byte (unsigned)
read only
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:
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:
type:
access:
mechanism:

byte_unsigned
byte (unsigned)
read only
by reference

Bucket size of the output file, if different from the first input file. The bks
argument is the address of a byte that contains 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 input file. If the

SOR—36

Sort/Merge (SOR) Routines
SOR$PASS_FILES

file organizations differ or if the record interface is used on input, the default
value is 1 block.

bis
VMS Usage:
type:
access:
mechanism:

word—unsigned
word (unsigned)
read only
by reference

Block size of a magnetic tape output file. The bis argument is the address of
• a word that contains 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.
The block size defaults to the block size of the input file tape. If the input file
is not on tape, the output file block size defaults to the size used when the
tape was mounted.

mrs
VMS Usage:
type:
access:
mechanism:

word—unsigned
word (unsigned)
read only
by reference

Maximum record size for the output file. The mrs argument is the address
of a word that specifies this size. The following table contains acceptable for
each type of file.
File Organization

Acceptable Value

Sequential

0 to 32,767

Relative

0 to 16,383

Indexed sequential

0 to 16,362

SORT will not check maximum record size if you omit this argument, or if
you specify a value of 0 .
If this argument is not specified, 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 calculated input
longest record length, the type of sort, and the record format.

alq
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

Number of preallocated output file blocks. The alq argument is the address
of a longword that specifies the number of blocks you want to preallocate to
the output file. Acceptable values are from 1 to 4,294:,967,295 .
Pass this argument if you know that your output file allocation will be larger
or smaller than that for your input file(s). 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.

SOR-37

Sort/Merge (SOR) Routines
SOR$PASS_FILES

fop
VMS Usage:
type:
access:
mechanism:

mask—longword
longword (unsigned)
read only
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 VAX Record Management Services
Reference Manual. By default, only the DFW (deferred write) option is set. If
your output file is indexed, you should set the CIF option (create if).

fsz
VMS Usage:
type:
access:
mechanism:

byte_unsigned
byte (unsigned)
read only
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:
type:
access:
mechanism:

context
longword (unsigned)
write only
by reference

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 in
only 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.
Some of the following 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.

SOR—38

Sort/Merge (SOR) Routines
SOR$PASS_FILES

CONDITION
VALUES
RETURNED

SS$_NORMAL

Success.

SOR$_DUP_OUTPUT

Output file has already been specified.

SOR$_ENDDIAGS

Completed with diagnostics.

SOR$_INP_FILES

Too many input files specified.

SOR$_SORT_ON

Sort or merge routines called in incorrect order.

SORS—SYSERROR

System service error.

SOR—39

Sort/Merge (SOR) Routines
SOR$RELEASE_REC

SOR$RELEASE_REC—Pass One Record to
Sort
Used with the record interface to pass one input record to SORT or
MERGE.

FORMAT

SOR$RELEASE_REC desc [,context]

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

desc
VMS Usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
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:
type:
access:
mechanism:

context
longword
modify
by reference

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

SOR—40

Sort/Merge (SOR) Routines
SOR$RELEASE_REC

CONDITION
VALUES
RETURNED

SSS—NORMAL

Success.

SOR$_BADLOGIC

Internal logic error detected.

sor$_b ad_lrl

Record length n greater than specified longest
record length.

SOR$_BAD_SRL

Record length n is 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$_OPENOUT

Error opening 'file' as output.

SOR$_OPERFAIL

Error requesting operator service.

SOR$_OPREPLY

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.

SORS—SYSERROR

System service error.

SOR$_USE_ALT

Using alternate file 'name7.

SOR$_WORK_DEV

Work file 'name7 must be on random access local
device.

SOR—41

Sort/Merge (SOR) Routines
SOR$RETURN_REC

SOR$RETURN_REC—Return One Sorted
Record
Used with the record interface to return one sorted or merged
record to a program.

FORMAT

SOR$RETURN_REC desc[,length][^context]

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

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
that receives the length of the record returned from SORT/MERGE.

context
VMS Usage:
type:
access:
mechanism:

context
longword (unsigned)
modify
by reference

SOR—42

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

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

Error requesting operator service.

SOR$_OPREPLY

Operator reply is "reply".

SOR$_READERR

Error reading 'file7.

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 'name7 must be on random access local
device.

SOR—43

Sort/Merge (SOR) Routines
SOR$SORT_MERGE

SOR$SORT_MERGE—Sort
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. All utility routines return a condition value in
RO. Condition values that can be returned by this routine are listed under
"CONDITION VALUES RETURNED."
\

ARGUMENT

context
VMS Usage:
type:
access:
mechanism:

context
longword (unsigned)
modify
by reference

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, you should use
LIB$MATCH_COND if you want to check for a specific status.

CONDITION

SS$_NORMAL

VALUES

SOR$_BADDTYPE

Invalid or unsupported CDD datatype.

RETURNED

SOR$_BADLENOFF

Length and offset must be multiples of 8 bits.

SOR$_BADLOGIC

Internal logic error detected.

SOR—44

Success.

Sort/Merge (SOR) Routines
SOR$SORT_MERGE

SOR$_BADOCCURS

Invalid OCCURS clause.

SOR$_BADOVRLAY

Invalid overlay structure.

SOR$_BADPROTCL

Node is an invalid CDD object.

SOR$_BAD_LRL

Record length n greater than specified longest
record length.

SOR$_BAD_TYPE

Invalid sort process specified.

SOR$_CDDERROR

CDD error at node 'name'.

SOR$_CLOSEIN

Error closing 'file' as input.

SOR$_CLOSEOUT

Error closing 'file' as output.

SOR$_COI_CHAR

Invalid character definition.

SORS—COI_CMPLX

Collating sequence is too complex.

SOR$_COI_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$_ILLBASE

Nondecimal base is invalid.

SOR$_ILLLITERL

Record containing symbolic literals is unsupported.

SOR$_ILLSCALE

Nonzero scale invalid for floating-point data-item.

SOR$_INCDIGITS

Number of digits is not consistent with the type or
length of item.

SORS—INCNOD AT A

Include specification references no data, at line n.

SOR$_INCNOKEY

Include specification references no keys, at line n.

SOR$_IND—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.

SORS-NOTRECORD

Node 'name' is a 'name', not a record definition.

SOR$_NO_WRK

Work files required, cannot do sort in memory as
requested.

SOR$_OPENIN

Error opening 'file' as input.

SOR$_OPENOUT

Error opening 'file' as output.

SOR$_OPERFAIL

Error requesting operator service.

SOR$_OPREPLY

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

Absolute Date and Time datatype 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—45

Sort/Merge (SOR) Routines
SOR$SORT_MERGE

SOR—46

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 line n.

SOR$_SPCOVR

Overridden specification, at line n.

SOR$_SPCSIS

Invalid sort specification, at line 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'.

Sort/Merge (SOR) Routines
SOR$SPEC_FILE

SOR$SPEC_FILE—Pass a Specification
File Name
Used to pass a specification file or specification text.

FORMAT

SOR$SPEC_FILE [spec-file][,spec-buffer]
[, context]

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

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

SOR—47

Sort/Merge (SOR) Routines
SOR$SPEC_FILE

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.

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 may 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 VAX/VMS Sort/Merge Utility Reference
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 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

SORS—ENDDIAGS

Completed with diagnostics.

VALUES

SOR$_SORT_ON

Sort or merge routines called in incorrect order.

RETURNED

SORS—SYSERROR

System service error.

SOR—48

Sort/Merge (SOR) Routines
SORSSTAT

SOR$STAT—Obtain a Statistic
Returns one statistic about the sort or merge operation to the user
program.

FORMAT

SOR$STAT code,result[,context]

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

code
VMS Usage:
type:
access:
mechanism:

word-unsigned
word (unsigned)
read only
by reference

SORT/MERGE statistic code. The code argument is the address of a word
containing the code that identifies the statistic you want returned in the result
argument. The following values are accepted:
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_LRI_INP

LRL for input

SOR$K_LRI_INT

Internal LRL

SOR$K_LRI_OUT

LRL for output

SOR$K_NODES

Nodes in sort tree

SOR$K_INI _RUNS

Initial dispersion runs

SOR$K_MRG_ORDER

Maximum merge order

SOR$K_MRG_P ASSES

Number of merge passes

SOR$K_WRK—ALQ

Work file allocation

SOR$K_MBC_INP

Multiblock count for input

SOR$K _MBC—OUT

Multiblock count for output

SORSK—MBF—INP

Multibuffer count for input

SOR$K_MBF_OUT

Multibuffer count for output

SOR—49

Sort/Merge (SOR) Routines
SOR$STAT

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 by calling 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 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—50

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.

1 2 VAX Text Processing Utility (VAXTPU)
Routines

12.1

Introduction to VAXTPU Routines
Callable VAXTPU makes VAXTPU accessible from within other VAX
languages and applications. VAXTPU can be called from a program written
in any VAX language that generates calls using the VAX/VMS Procedure
Calling and Condition Handling Standard. You can also call VAXTPU from
VAX/VMS utilities, for example, MAIL. Callable VAXTPU allows you to
perform text processing functions within your program.
Callable VAXTPU consists of a set of callable routines that resides in the
VAXTPU 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 VAXTPU interface, you
can use files for input to and output from callable VAXTPU. You can also
write your own routines for processing input, output, and messages.
This section describes callable VAXTPU. It describes the purpose of the
VAXTPU 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 VAXTPU routine. Each parameter description lists the data
type and the passing mechanism for the object. The data types are standard
VAX/VMS data types. The passing mechanism indicates how the parameter
list is interpreted.
This section is written for systems programmers and it assumes that you are
familiar with the following:
•

The VAX/VMS Procedure Calling and Condition Handling Standard

•

The VAX/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.

TPU-1

VAX Text Processing Utility (VAXTPU) Routines
Introduction to VAXTPU Routines

12.1.1 Two Interfaces to Callable VAXTPU
There are two ways in which you can 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 this simplified form of callable VAXTPU, you can use the
TPU$TPU routine to specify a VAX/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 12.2, The
Simplified Callable Interface.

Full Callable Interface
Another way to use callable VAXTPU is to have your program directly access
the main callable VAXTPU routines. These routines do the following:
•

Initialize the editor (TPU$INTIALIZE)

•

Execute VAXTPU procedures (TPU$EXECUTE_INIFILE and
TPU$EXECUTE —COMMAND)

•

Control the editor (TPU$CONTROL)

•

Terminate the calling session (TPU$CLEANUP)

When using callable VAXTPU in this way, you must provide values for certain
parameters. In some cases, the values that 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 may also have to write
additional routines. For example, you may need to write routines for
performing file operations, handling errors, and otherwise controlling the
editing session. Callable VAXTPU provides utility routines that can perform
some of these tasks for you. These utility routines can do the following:

TPU-2

•

Parse the VAX/VMS command line and build the item list used for
initializing the editor

•

Handle file operations

•

Write error messages

•

Handle conditions

VAX Text Processing Utility (VAXTPU) Routines
Introduction to VAXTPU Routines

Various topics relating to the full callable interface are discussed in the
following sections:
•

Section 12.3, The Full Callable Interface, begins by briefly describing the
interface. However, most of this section is devoted to a description of the
main callable VAXTPU routines (TPU$INITIALIZE, TPU$EXECUTE_
INIFILE, TPU$CONTROL, TPU$EXECUTE-COMMAND, and
TPU$CLEANUP).

•

Section 12.3.2, Other VAXTPU Utility Routines, discusses additional
routines that VAXTPU provides for use with the full callable interface.

•

Section 12.3.3, User-Written Routines, 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. Note that these routines are not visible to you
when you use the simplified interface.

12.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 that are
available for use by an application. In addition, TPUSHR.EXE provides the
following symbols:
•

TPU$VERSION—the version of the shareable image.

•

TPU$UPDATE—the update number of the shareable image.

•

TPU$FACILITY—the VAXTPU facility number.

For more information on how to link to the shareable image TPUSHR.EXE,
refer to the VAX/VMS System Services Reference Manual.

12.1.3 Passing Parameters to Callable VAXTPU Routines
Parameters are passed to callable VAXTPU 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 Figure TPU-1. 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.

TPU—3

VAX Text Processing Utility (VAXTPU) Routines
Introduction to VAXTPU Routines

Figure TPU-1

Bound Procedure Value

NAME OF YOUR ROUTINE
ENVIRONMENT

ZK-4046-85

12.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 three ways to handle errors:
1

You can use VAXTPU's default condition handler, TPU$HANDLER.

2 You can write your own condition handler to replace VAXTPU's default
condition handler.

3 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 the routine
description section of this chapter. Information about writing your own
condition handler can be found in the Introduction to VAX/VMS System
Routines.

12.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. VAXTPU returns the condition code value in RO.
VAXTPU return codes can be found in the VAX Text Processing Utility
Reference Manual. VAXTPU return codes and their messages are included
in the VAX/VMS System Messages and Recovery Procedures Reference Manual.
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 "Possible Return Values," and indicates the
values that are returned when the default condition handler is established.

12.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:

TPU—4

•

Applications that are able to specify all the editing parameters on a single
command line

•

Applications that need to specify only an input file and an output file

VAX Text Processing Utility (VAXTPU) Routines
The Simplified Callable Interface

12.2.1 Example of the Simplified Interface
The following example shows how the simplified interface might be used to
call VAXTPU.
/* Sample C program that calls VAXTPU. This program uses TPU$EDIT
to provide the names of the input and output files, and TPU$TPU
to pass a complete command line to the editor. */
♦include descrip
int return.status;
char command.line [100];
static $DESCRIPTOR(input_file,"infile.dat");
static $DESCRIPTOR(output_file,"outfile.dat");
static $DESCRIPT0R(command_de8c,command_line);
static $DESCRIPTOR(first_part_de8C,"EDIT/TPU/NOJOURNAL/NOCOMMAND/OUTPUT=");
static $DESCRIPTOR(space_desc," M);
main (argc,argv)
int argc;
char *argv[] ;
/* Call the routine that accepts the name of the input and output file. */
/* This passes the name of the input file and output file to VAXTPU. */
/* These values are made available to VAXTPU procedures for processing. */
retum.status = TPU$EDIT(Ainput_f ile, &output_f ile) ;
if (! retum.status)
exit (retum.status);
/*
/*
/*
/*

Now we build a command line and pass it to VAXTPU.
*/
Note that in this case we want to do more than just specify the
file names.
Our command also includes the /NOJOURNAL and /NOCOMMAND
qualifiers.

/* Concatenate all the command information into one string

*/
*/
*/

return_8tatus = STR$CONCAT(Acommand.desc, trt irst_part_desc,Aoutput_file,
fespace.desc,&input_file);
if (! retum_status)
exit (retum.status) ;
/* Now call VAXTPU
*/
retum.status = TPU$TPU(Acommand.desc) ;
exit(return.status);
>

The following section contains detailed information about the routines called
by the simplified interface. For example, there is information about the
default parameters used when initializing the editor and when exiting the
editor.

12.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:
•

Specify initialization parameters

•

Control file input/output

•

Specify commands to be executed by the editor

•

Control how conditions are handled

When you use the simplified callable interface, the preceding 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, and your own routines that pass parameters to the

TPU-5

VAX Text Processing Utility (VAXTPU) Routines
The Full Callable Interface

VAXTPU routines, are the mechanism that your application uses to control
VAXTPU.
This section describes the main callable routines, how parameters are passed
to these routines, the VAXTPU utility routines, and the requirements of
user-written routines.

12.3.1 Main Callable VAXTPU Utility Routines
The following callable VAXTPU routines are described in this section:
•

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/VMS Condition
Handling Standard" in the Introduction to VAX/VMS System Routines for
information on establishing a condition handler.

12.3.2 Other VAXTPU Utility Routines
The full callable interface includes several other utility routines for which you
can provide parameters. Depending on your application, you may be able to
use these routines rather than writing your own routines. The following five
VAXTPU utility routines are described in this section:
•

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 I/O routine.

•

TPU$MESSAGE—writes error messages and strings using the built-in
procedure MESSAGE.

•

TPU$HANDLER—the default condition handler.

12.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 12.1.3 for a description of bound procedure values.)
Depending on your application, you may have to write one or all of the
following routines:
•

TPU-6

Routine for initialization callback—This is a routine that TPU$INITIALIZE
calls to obtain values for initialization parameters. Instead of writing your
own initialization callback routine, you can use the TPU$CLIPARSE or
TPU$PARSEINFO utility routine.

VAX Text Processing Utility (VAXTPU) Routines
The Full Callable Interface

12.4

•

Routine for file I/O—This is a routine that handles file operations. Instead
of writing your own file I/O routine, you can use the TPU$FILEIO utility
routine. You cannot use this routine for journal file operations or for
operations done 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
The following examples use Callable VAXTPU. The examples are included
in the manual for illustrative purposes only. DIGITAL does not assume
responsibility for supporting this example.

TPU-7

VAX Text Processing Utility (VAXTPU) Routines
Examples of Using VAXTPU Routines

Example TPU-1

Sample VAX BLISS Template for Callable
VAXTPU

! How to declare the VAXTPU routines
external routine
tpu$FILEIO,
tpu$HANDLER,
tpulINITIALIZE,
tpu$EXECUTE_INIFILE,
tpu|EXECUTE_COMMAND,
tpu$C0NTR0L,
tpulCLEANUP;
! How to declare the VAXTPU literals
external literal
i

! File I/O operation codes
tpulk.close,
tpu$k_clo8e_delete,
tpu$k_open,
tpu$k_get,
tpu$k_put,
i

! File access codes
tpulk.access,
tpu$k_io,
tpu$k_input,
tpu$k_output,
!
!

Item codes
tpu$k_calluser,
tpu$k_fileio,
tpu$k_output!ile,
tpu$k_sectionfile,
tpu$k_commandfile,
tpu|k_filename,
tpu$k_j ournalfile,
tpu$k_options,

!
! Mask for values in options
tpu$m_recover,
tpu$m_j ournal,
tpu$m_read,
tpu$m_command,
tpu$m_create,
tpu$m_section,
tpu$m_display,
tpu$m_output,
i

! Bit positions for values in options
tpu$v_display,
tpu$v_recover,
tpulv_journal,
tpulv.read,
tpu$v_create,
tpu$v_command,
tpu$v_section,
tpu$v_output,

(Continued on next page)

TPU-8

tpu$_nofileaccess,
tpu$_openin,
tpu$_inviocode,
tpu$_failure,
tpu$_closein,
tpu$_closeout,
tpu$_readerr,
tpu$_writeerr,
tpu$_8uccess;
own
OPTIONS:
bitvector [32];
! OPTIONS will be passed to VAXTPU
GLOBAL ROUTINE top.level =
BEGIN
!++

! Main entry point of your program
! -! Your_initialization_routine must be declared as a BPV
local

BPV:

vector[2,long] initial (TPU_INIT,0);! P

! First establish the condition handler
LIB$ESTABLISH (tpu$handler);

! Call the intialization routine and pass it the addres
! which has the address of your initialization routine
! calls this)
tpu$initialize (BPV);

! Use the following call if the options word passed to
! an initialization file needs to be executed and/or th
! in the section file needs to be executed.
tpu$execute_inifile();
! Let VAXTPU take over.
tpu$control();

! To break out of VAXTPU, use call.user from within a V
! Upon return from tpufcontrol, the editing session is
tpu$cleanup();
! Loop and start the sequence over or exit
return tpu$_success;
END;
ROUTINE TPU.INIT =
BEGIN
i
i --

own

BPV:

vector[2,long] initial (TPU_I0,O);! Pro

bind
OUTFILE.D
COMFILE.D
SECFILEJ)
FILE.D

=
=
=
=

'/.ascid'OUTPUT.TPU1 : block [8.byte] ,
‘/.ascid'TPUINI.TPU' : block [8,byte] ,
'/.ascid'SYS$LIBRARY:EDTSECINI.TPU$SE
Xascid'FILE.TPU': block [8.byte];

! Set VAXTPU options I want to enable
OPTIONS [tpu$v_display] = 1;
OPTIONS[tpu$v_section] = 1;
OPTIONS[tpu$v_create]
= 1;
OPTIONS[tpu$v_command] = 1;
OPTIONS[tpu$v_recover] = 0;
OPTIONS[tpu$v_journal] = 0;
OPTIONS[tpu$v_read] = 0;
OPTIONS[tpu$v_output] = 1;
begin
IJust for BIND
bind
! Set up item list to pass back to VAXTPU to tell it what to do
! VAXTPU calls me back later
ITEMLIST = uplit byte (
!buffer length,
word
word
word
word
word
word
long

(4),
(4),
(0),
(0),
(0),
(0),
(0) );

word
word
word
word
word
word

buffer address,

item code.
(tpu$k_options),
(tpu$k_fileio),
(tpu$k_outputfile),
(tpu$k_commandfile),
(tpu$k_filename),
(tpu$k_sectionfile),

return ITEMLIST;
end;
END;

long
long
long
long
long
long

return address

(OPTIONS),
(BPV),
(OUTFILE.D),
(COMFILE.D),
(FILE_D),
(SECFILE.D),

long
long
long
long
long
long

(0),
(0),
(0),
(0),
(0),
(0),

! End of routine TPU_INIT

GLOBAL ROUTINE TPU.IO (P.OPCODE, FILE.BLOCK, DATA: ref block [.byte]) =
BEGIN
i

!
local
item: ref block [3,long],
status;
!
!
!
!
!
!
!

! Item list entry

Look at the opcode (operation) that VAXTPU wants me to perform
and if I don't want to do it, just call it back
if (..P.OPCODE NEQ tpu$k_open)
then
return (tpu$fileio (.p_opcode, .file_block, .data));
Else set what operation to do

selectone ..P.OPCODE of
set
[tpu$k_open]:
! Time to open a file
|
begin
item = .data;
end;
return tpu$_success;
end;
[tpu$k_get]:
! Time to read a record
begin
end;
[tpu$k_put]:
begin

! Point to the FILENAME item list entry
! End of tpu$k_open
! If none exists, then no data

! Time to write a record

return tpu$_success;
end;

(Continued on n

TPU-10

VAX Text Processing Utility (VAXTPU) Routines
Examples of Using VAXTPU Routines

Example TPU-1

(Cont.)

[tpu$k_clo8e]:

Sample VAX BLISS Template for
Callable VAXTPU
ITime to close a file

begin
return tpu$_success;
end;
[tpu$k_clo8e_delete]:

lib$stop

[otherwise]:

(..p_opcode);

lib$stop

(..p_opcode);

tea;
return tpu$_success;
END;

End of routine TPU.IO

TPU-11

INTEGERS
INTEGERS
INTEGER*4
INTEGER*4

c
c
c

TPUICONTROL
TPU$CLEANUP
TPU$EXECUTE.INIFILE
TPU$INITIALIZE
TPU$CLIPARSE

declare a local copy to hold the values of VAXTPU cleanup va
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4
INTEGER*4

!options for clean up routine
!return status from VAXTPU ro
!set up a Bound Procedure Va
!a local function call

declare the VAXTPU functions
INTEGERS
INTEGER+4
INTEGERS
INTEGER*4
INTEGER*4

CLEAN.OPT
STATUS
BPV_PARSE(2)
LOC.PARSE

RESET.TERMINAL
DELETE.JOURNAL
DELETE.BUFFERS.DELETE.WINDOWS
DELETE.EXITH,EXECUTE.PROC
PRUNE.CACHE,KILL.PROCESSES
CLOSE.SECTION

declare the VAXTPU functions used as external
EXTERNAL
EXTERNAL

TPU$HANDLER
TPU$CLIPARSE

EXTERNAL

TPU$_SUCCESS

{external error message

EXTERNAL

LOC.PARSE

{user supplied routine to
call TPUCLIPARSE and setup

declare the VAXTPU cleanup variables as external these are th
external literals that hold the value of the options
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

100

CALL LIB$ESTABLISH ( TPU$HANDLER )

set up the Bound Procedure Value for the call to TPUlINITIAL

{establish the cond

BPV.PARSEC 1 ) = 7.L0C ( LOC.PARSE )
BPV_PARSE( 2 ) = 0

call the VAXTPU initialization routine to do some set up wor

Check the status if it is not a success then signal the erro

STATUS = TPUIINITIALIZE ( BPV.PARSE )

IF ( STATUS .NE. y.L0C ( TPU$_SUCCESS ) ) THEN
CALL LIB$SIGNAL( */.VAL( STATUS ) )
GOTO 9999
END IF

c
c

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. */.L0C ( TPU$_SUCCESS ) ) THEN {make sure eve
CALL LIB$SIGNAL( */.VAL( STATUS ) )
GOTO 9999
END IF

invoke the editor as it normally would appear
STATUS = TPU$C0NTR0L ( )

{call the VAXTPU editor

IF ( STATUS .NE. %L0C ( TPU$_SUCCESS ) ) THEN {make sure eve

CALL LIB$SIGNAL( */.VAL( STATUS ) )
GOTO 9999

(Continued
TPU-12

c
c
c

of the literal from its external location.
He
values of the options that we want to use in th
DELETE.JOURNAL
DELETE.EXITH
DELETE.BUFFERS
DELETE.WINDOWS
EXECUTE.PROC
RESET.TERMINAL
KILL.PROCESSES
CLOSE.SECTION

c
c

=
=
=
=
=
=
=
=

7.L0C
7.L0C
7.L0C
7.L0C
7.L0C
7.L0C
7.L0C
7.L0C

(
(
(
(
(
(
(
(

TPU$M_DELETE_JOURNAL
TPU$M_DELETE_EXITH )
TPU$M_DELETE_BUFFERS
TPU$M_DELETE_WINDOWS
TPU$M_EXECUTE_PROC )
TPU$M_RESET_TERMINAL
TPU$M_KILL_PROCESSES
TPU$M.CLOSE_SECTION )

Now that we have the local copies of the varia
logical OR to set the multiple options that we

CLEAN.OPT = DELETE.JOURNAL .OR. DELETE.EXITH .
1
DELETE.BUFFERS .OR. DELETE.WINDOWS .OR
1
.OR. RESET.TERMINAL .OR. KILL.PROCESSE

c
c
c

do the necessary clean up

TPU$CLEANUP wants the address of the flags as
pass the 7.L0C of CLEAN.OPT which is the addres
STATUS = TPU$CLEANUP ( 7.L0C ( CLEAN.OPT ) )
IF ( STATUS .NE. 7.L0C (TPUl.SUCCESS) ) THEN
CALL LIB$SIGNAL( 7.VAL(STATUS) )
ENDIF

9999

CALL LIB$REVERT

!go back to normal pro

STOP
END
C
C
INTEGERS

INTEGER*4

BPV(2)

!A local Bound

CHARACTER*12

EDIT.COMM

!A command line

Declare the VAXTPU functions used
INTEGER*4
INTEGER*4

C
C

FUNCTION LOC.PARSE

TPU$FILEIO
TPU$CLIPARSE

Declare this routine as external because it is
we need to tell FORTRAN that it is a function
EXTERNAL

TPU$FILEIO

BPV(l) = 7.L0C(TPU$FILEI0)
BPV(2) = 0

! set up the BO

EDIT_C0MM(1:12) = 'TPU TEST.TXT'
C

parse the command line and build the item list

9999

LOC.PARSE = TPU$CLIPARSE (EDIT.COMM, BPV , 0)
RETURN
END

IMPLICIT NONE
C
C
C

Define the expected VAXTPU return statuses
EXTERNAL
EXTERNAL

C
C
C

TPU$_SUCCESS
TPU$_QUITTING

Declare the VAXTPU routines and symbols used
EXTERNAL
EXTERNAL
INTEGER*4
INTEGERS
INTEGER*4
INTEGER*4
INTEGER*4

C
C
C

TPU$M_DELETE_CONTEXT
TPU$HANDLER
TPU$M_DELETE_CONTEXT
TPU$INITIALIZE
TPU$EXECUTE_INIFILE
TPUICONTROL
TPU$CLEANUP

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

Declare the functions used for working with the condition han
INTEGER*4
INTEGER*4

C
C
C

LIB$ESTABLISH
LIB$REVERT

Local Flags and Indices
INTEGER*4
INTEGER*4

C
C
C

CLEANUP.FLAG
RET.STATUS

Initializations
RET.STATUS
CLEANUP .FLAG

C
C
C

! flag(s) for VAXTPU cleanu

= 0
= y.LOC (TPU$M_DELETE_CONTEXT)

Establish the default VAXTPU condition handler
CALL LIB$ESTABLISH(*/.REF(TPU$HANDLER) )

C
C
C

Set up the bound procedure value for the initialization callba
BPV(l)
BPV(2)

C
C
C

=
*

%LOC (TPU.STARTUP)
0

Call the VAXTPU procedure for initialization
RET.STATUS - TPU$INITIALIZE(BPV)
IF (RET.STATUS .NE. %LOC(TPU$_SUCCESS)) THEN
CALL LIBISIGNAL (%VAL(RET.STATUS))
ENDIF

(Continued

TPU-14

c
c

Execute the VAXTPU initialization file
RET.STATUS = TPU$EXECUTE_INIFILE()
IF (RET.STATUS .NE. y.LOC(TPU$_SUCCESS)) THEN
CALL LIB$SIGNAL (%VAL(RET.STATUS))
END IF

c
c
c

Pass control to VAXTPU
RET.STATUS = TPU$CONTROL()
IF (RET.STATUS .NE. */.LOC(TPU$_QUITTING)
1
.OR. y,LOC(TPU$_QUITTING)) THEN
CALL LIB$SIGNAL OiVAL(RET.STATUS))
END IF

c
c
c

Clean up after processing
RET.STATUS = TPU$CLEANUP ('/.REF (CLEANUP.FLAG) )
IF (RET.STATUS .NE. %LOC(TPU$_SUCCESS)) THEN
CALL LIB$SIGNAL (*/.VAL(RET.STATUS))
ENDIF

c
c
c

Set the condition handler back to the default
RET.STATUS = LIB$REVERT()
END
INTEGERS FUNCTION TPU.STARTUP
IMPLICIT NONE
INTEGER*4
CHARACTER*44

c
c
c

TPU$K_OPTIONS
TPU$M.READ
TPU$M_SECTION
TPU$M_DISPLAY
TPU$K_SECTIONFILE
TPU$K_FILEIO
TPU$FILEIO
TPUIFILEIO

The bound procedure value used for setting up the fil
INTEGERS

c
c
c

! temporary variabl
! temporary var

External VAXTPU routines and symbols
EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL
INTEGERS

c
c
c

OPTION.MASK
SECTION.NAME

BPV (2)

Define the structure of the item list defined for th
STRUCTURE /CALLBACK/
INTEGER*2
BUFFER LENGTH
ITEM.CODE
INTEGER*2
INTEGER*4
BUFFER.ADDRESS
INTEGER*4
RETURN.ADDRESS
END STRUCTURE

c
c
c

There are a total of four items in the item list
RECORD /CALLBACK/ CALLBACK (4)

(Co

VAX Text Processing Utility (VAXTPU) Routines
Examples of Using VAXTPU Routines

Example TPU-3

(Cont.)

Building a Callback Item List with VAX
FORTRAN

c
C
C

Make sure it is not optimized!
VOLATILE /CALLBACK/

C
C
C

Define the options we want to use in the VAXTPU session
OPTION.MASK = %LOC(TPU$M_SECTION)
1
.OR. %L0C(TPU$M_DISPLAY)

C
C
C

.OR. y,LOC(TPU$M_READ)

Define the name of the initialization section file
SECTION.NAME = 'device:[user]TPUSECTION.TPUlSECTION'

C
C
C

Set up the required I/O routine.

Use the VAXTPU default.

BPV(l) = '/.LOC (TPU$FILEIO)
BPV(2) = 0
C
C
C
C
C

Build the callback item list
Set up the edit session options
CALLBACK(1).ITEM.CODE = %LOC(TPU$K_OPTIONS)
CALLBACK(l).BUFFER.ADDRESS = KLOC(OPTION.MASK)
CALLBACK(1).BUFFER.LENGTH *
CALLBACK(1).RETURN.ADDRESS = 0

C
C
C

Identify the section file to be used
CALLBACKS) .ITEM.CODE = %LOC(TPU$K_SECTIONFILE)
CALLBACK(2).BUFFER.ADDRESS = %L0C(SECTION.NAME)
CALLBACK(2).BUFFER.LENGTH = LEN(SECTION.NAME)
CALLBACK(2).RETURN.ADDRESS = 0

C
C
C

Set up the I/O handler
CALLBACK(3).ITEM.CODE * %LOC(TPU$K.FILEIO)
CALLBACK(3).BUFFER.ADDRESS = %L0C(BPV)
CALLBACK(3).BUFFER.LENGTH = 4
CALLBACK(3).RETURN.ADDRESS = 0

C
C
C

End the item list with zeros to indicate we are finished
CALLBACK(4).ITEM.CODE = 0
CALLBACK(4).BUFFER.ADDRESS = 0
CALLBACK(4).BUFFER.LENGTH = 0
CALLBACK(4).RETURN.ADDRESS = 0

C
C
C

Return the address of the item list
TPU.STARTUP = y.LOC (CALLBACK)
RETURN
END

TPU-16

*/
♦include descrip
♦include stdio
/* data structures needed */
struct bpv_arg

/* bound procedure valu

int *routine_add ;
int env ;
> ;

/* pointer to routine *
/* environment pointer

struct item_list_entry
X
\
short int buffer_length;
short int item.code;
int *buffer_add;
int *retura_len_add;

/* item list data struc
/*
/*
/*
/*

buffer length */
item code */
buffer address */
return address */

/*
/*
/*
/*
/*
/*

stream id */
file size */
file record attribute
resultant file name
file name descriptor
file name descriptor

struct 8tream_type

{
int ident;
short int alloc;
short int flags;
short int length;
short int stuff;
int nam_add;

> ;
globalvalue tpu$_success;
globalvalue tpu$_quitting;

/* TPU Success code */
/* Exit code defined by

globalvalue
/* Cleanup codes define
tpu$m_delete_journal, tpu$m_delete_exith,
tpu$m_delete_buffers, tpu$m_delete_windows, tpu$m_
tpu$m_prune_cache, tpu$m_execute_file, tpu$m_execu
tpu$m_delete_context, tpu$m_reset.terminal, tpu$m_
tpu$m_clo8e_section, tpu$m_delete_others, tpu$m_las
globalvalue
/* Item codes for item
tpu$k_fileio, tpu$k_options, tpu$k_sectionfile,
tpu$k_commandfile ;
globalvalue
/* Option codes for opt
tpu$m_display, tpu$m_section, tpu$m_command, tpu$m

globalvalue
/* Possible item codes
tpu$k_acce88, tpu$k_filename, tpu$k_defaultfile,
tpu$k_relatedfile, tpu$k_record_attr, tpu$k_maximiz
tpu$k_flush, tpu$k_file8ize;

globalvalue
/* RMS File Not Found message code */
rms$_fnf;
globalvalue
/* FILEIO routine functions */
tpu$k_open, tpu$k_close, tpu$k_clo8e_delete.
tpu$k_get, tpu$k_put;
int lib$establish ();
/* RTL routine to establish an event
int tpu$cleanup ();
/* TPU routine to free resources used
int tpu$control ();
/* TPU routine to invoke the editor *
int tpu$execute_inifile ();
/* TPU routine to execute initializat
int tpu$handler ();
/* TPU signal handling routine */
int tpu$initialize ();
/* TPU routine to initialize the edit
/*

This function opens a file for either read or write access, based
the itemlist passed as the data parameter.
Note that a full imple
of the file open routine would have to handle the default file, re
file, record attribute, maximize version, flush and file size item
properly.
*/
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 */
FILE *f openQ ;
/* 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 = Mr+M;
else if (item->buffer_add == tpu$k_input) access = "r";
else if (item->buffer_add == tpu$k_output) access * "w";
>

(Continued

TPU—18

VAX Text Processing Utility (VAXTPU) Routines
Examples of Using VAXTPU Routines

Example TPU-4

(Cont.)

Specifying a User-Written File I/O
Routine in VAX C

else if (item->item_code == tpu$k_filename)

i
8trncpy (filename, item->buffer_add, item->buffer.length);
filename [item->buffer_length] = 0;
lib$scopy_r_dx (&item->buffer_length, item->buffer_add,
&stream->length);
>
else if (item->item_code == tpu$k_defaultfile)
/* Add code to handle default file
/* spec here
>
else if (item->item_code == tpu$k_relatedfile)
/* Add code to handle related
/* file spec here
>
else if (item->item_code == tpu$k_record_attr)
/* Add code to handle record
/* attributes for creating files
>
else if (item->item_code == tpu$k_maximize_ver)
/* Add code to maximize version
/* number with existing file here
>
else if (item->item_code == tpu$k_flush)
/* Add code to cause each record
<
/* to be flushed to disk as written
>
else if (item->item_code == tpu$k_filesize)
/* Add code to handle specification
/* of initial file allocation here
>
++item;
/* get next item */
>
stream->ident = fopen(filename,access);
if (stream->ident != 0)
return tpu$_success;
else
return rms$_fnf;

*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/

>
/*
This procedure closes a file
*/
close.file (data.stream)
struct stream.type *stream;
clo8e(8tream->ident);
return tpu$_success;
>
/*
This procedure reads a line from a file
*/
read_line(data,stream)
struct dscldescriptor *data;
struct stream_type *stream;

<
char textline[984];
int len;

/* 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);
if (len > 0)
len - len - 1;
return lib$scopy_r_dx (Alen, textline, data);
>
>

(Continued on next page)

TPU—19

write_line(data.stream)
struct dsc$descriptor ♦data;
struct stream_type *stream;
char textline[984];

/♦ max line size lor TPU reco

strncpy (textline, data->dsc$a_pointer, data->dsc$w_length);
textline [data->dsc$w_length] = 0;
fputs(textline,stream->ident);
fputs("\n",stream->ident);
return tpu$_success;

>
/*
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 t
/♦ file I/O routines would have to handle the close and delete code p
/♦ instead of simply closing the file

/♦ Initial access to
if (*code == tpu$k_open)
status = open.file (data,stream);
/♦ End access to file
else if (♦code == tpu$k_close)
status = close_file (data,stream);
/♦ Treat same as clos
else if (♦code == tpu$k_close_delete)
status = close_file (data,stream);
/♦ Read a record from
else if (*code == tpu$k_get)
status = read.line (data,stream);
/* Write a record to
else if (*code == tpu$k_put)
status = write.line (data,stream);
else
{
/♦ Who knows what we
status = tpu$_success;
printf ("Bad FILEI0 I/O function requested");
>
return status;

(Continued

TPU-20

VAX Text Processing Utility (VAXTPU) Routines
Examples of Using VAXTPU Routines

Example TPU-4

(Cont.)

Specifying a User-Written File I/O
Routine in VAX C

/*
This procedure formats the initialization item list and returns it as
is return value.

*/
callrout()

<
static struct bpv.arg add_block =
{ fileio,
int options

0 >

;

/* BPV for fileio routine */

;

char *section_name =

"TPUSECINI";

static struct item.list.entry arg[]
{/* length code

buffer add return add */

i 4,tpu$k_fileio.

0 >.

{ 4,tpu$k.options,

0 >.

{ 0,tpu$k_sectionfile,0,

0 >.

0 >

*C 0.0,

>;
/* Setup file I/O routine item entry */
arg[0].buffer.add = fcadd.block;
/* Setup options item entry.
options * tpu$m_display

Leave journaling off.

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.

*/
mainO
int return.status

;

int cleanup.options;
struct bpv.arg add.block;
/* Establish as condition handler the normal VAXTPU handler

lib$establish(tpu$handler);
/* Setup a BPV to point to the callback routine */
add_block.routine_add = callrout

;

add.block.env * 0;
/* Do the initialize of VAXTPU */
return.status = tpu$initialize(&add_block);
if

(!return_status)
exit(return.status);

/* 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);

(Continued on next page)

TPU—21

VAX Text Processing Utility (VAXTPU) Routines
Examples of Using VAXTPU Routines

Example TPU-4

(Cont.)

Specifying a User-Written File I/O
Routine in VAX C

/* Turn control over to VAXTPU */
return.status = tpu$control
i1

();

(!return_status)
exit(return_status);

/* Now clean up.

cleanup_option8 * tpu$m_last_time
return.status * tpu$cleanup
exit

tpu$m_delete_context;

(fccleanup.options);

(return.status);

printi("Experiment complete");

12.5

VAXTPU Routines
The following pages describe the individual VAXTPU routines in routine
template format.

TPU-22

VAX Text Processing Utility (VAXTPU) Routines
TPU$CLEANUP

TPU$CLEANUP
Cleans up internal data structures, free memory, and restores
terminals to their initial state. This is the last routine that you call.

FORMAT

TPUSCLEANUP

RETURNS

VMS Usage:
type:
access:
mechanism:

flags

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

ARGUMENT

flags
VMS Usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by reference

Longword bit mask. The flags argument is the address of a longword bit
mask defining the cleanup options. The address of a 32-bit mask defining the
cleanup options. This mask is the logical OR of the flag bits that you wish 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

Delete 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
in the built-in 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 in
the built-in procedure DELETE.

Prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask in which the bit is
set corresponds to the specific field; TPU$V_ is a bit number.

TPU-23

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

TPU$M .EXECUTE -FILE

Reexecutes the command file if
TPU$EXECUTE_INIFILE is called again. You
must set this bit if you plan on specifying a new
file name for the command file. This option is
used in conjunction with the option bit passed
to TPUSlNITIALIZE indicating the presence of
the /COMMAND qualifier.

TPU$M -EXECUTE _PROC

Looks up TPU$INIT_PROCEDURE and executes
it the next time TPU$EXECUTE_INIFILE is
called.

TPUSM _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.

TPUSM _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
TPUSlNITIALIZE is called.

TPUSM -KILL -PROCESSES

Deletes all subprocesses created during the
session.

TPUSM—CLOSE—SECTION2

Closes the section file and releases the
associated memory. All buffers, windows
and processes are deleted. The cache is pruned
and the flags for re-execution of the initialization
file and initialization procedure are set. If the
section is closed, and if the option bit indicates
the presence of the SECTION qualifier, then the
next call to TPUSlNITIALIZE attempts a new
restore operation.

TPUSM—DELETE—OTHERS

Deletes all miscellaneous preallocated data
structures. Memory for these data structures
is reallocated the next time TPUSlNITIALIZE is
called.

Prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask in which the bit is
set corresponds to the specific field; TPU$V_ is a bit number.
2Using the simplified callable interface does not set TPU$_CLOSE_SECTION. This
feature allows you to make multiple calls to TPUSTPU without requiring you to
open and close the section file on each call.

TPU-24

VAX Text Processing Utility (VAXTPU) Routines
TPUSCLEANUP

Symbol1

Function

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.

Prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask in which the bit is
set corresponds to the specific field; TPU$V_ is a bit number.

The following bits in the mask can also be set.
•

TPU$V_DELETE-JOURNAL

•

TPU$V_DELETE _EXITH

•

TPU$ V—DELETE —BUFFERS

•

TPU$ V—DELETE —WINDOW S

•

TPU$V_DELETE—CACHE

•

TPU$V_PRUNE-CACHE

•

TPU$V_EXECUTE—FILE

•

TPU$V_EXECUTE—PROC

•

TPU$V_DELETE-CONTEXT

•

TPU$V_RESET—TERMINAL

•

TPU$V_KILL -PROCESSES

•

TPU$V_CLOSE—SECTION

•

TPU$V_DELETE—OTHERS

•

TPU$V_LAST—TIME

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 above.
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; this is done automatically by the system. Allowing the VAX/VMS
system to delete the structures improves the performance of your program.
Notes
1

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

VAX Text Processing Utility (VAXTPU) Routines
TPU$CLEANUP

•

TPU$V_DELETE_WINDOWS

•

TPU$ V—DELETE _EXITH

•

TPU$ V—EXECUTE _PROC

•

TPU$ V—EXECUTE —FILE

•

TPU$V_PRUNE—CACHE

•

TPU$V_KILL-PROCESSES

2 If this routine does not return a success status, no other calls to the editor
should be made.

TPU-26

VAX Text Processing Utility (VAXTPU) Routines
TPU$CLI PARSE

TPU$CLIPARSE
Parses a command line and build the item list for TPU$INITIALIZE.
It calls CLI$DCI_PARSE to establish a command table and a
command to parse. It then calls TPU$PARSEINFO to build an item
list for TPUSINITIALIZE.

FORMAT

TPU$CLIPARSE string, fileio, calluser

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

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
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
bound procedure value
read only
by descriptor

File I/O routine. The fileio argument is the address of a descriptor of a file
I/O routine.

calluser
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
bound procedure value
read only
by descriptor

Calluser routine. The calluser argument is the address of a descriptor of a
calluser routine.

TPU-27

VAX Text Processing Utility (VAXTPU) Routines
TPU$CONTROL

TPU$CONTROL
Is the main processing routine of the VAXTPU editor. When you
call this routine (after calling TPU$INITIALIZE), control is turned over
to VAXTPU.

FORMAT

TPU$CONTROL

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

None.

DESCRIPTION This routine controls the edit session. It is responsible for reading the text

and commands and executing them. Windows on the screen are updated to
reflect the edits that are performed.

Note: Control is returned to your program only if an error occurs or after you
issue either the built-in procedure QUIT or the built-in procedure EXIT.

CONDITION
VALUES
RETURNED

TPU-28

TPU$_EXITING

Returning as a result of EXIT (when the default
condition handler is established).

TPU$_QUITTING

Returning as a result of QUIT (when the default
condition handler is established).

TPU$_RECOVERFAIL

Returning because a recovery operation was
abnormally terminated.

VAX Text Processing Utility (VAXTPU) Routines
TPU$EDIT

TPU$EDIT
Is another entry point to VAXTPU's simplified callable interface.
TPU$EDIT builds a command string from its parameters and passes
it to the TPU$TPU routine.

FORMAT

TPU$EDIT input, output

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

input
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Input file passed by descriptor. The input argument is the address of a
descriptor of a file specification.

output
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Character string to be used with the /OUTPUT command qualifier. The
output argument is the address of a descriptor of an output file specification.

DESCRIPTION This routine builds a command string and passes it to TPU$TPU. If the length

of the output string is greater than 0, it is included in the command line using
the /OUTPUT qualifier as follows:

TPU [/0UTPUT= output] input

CONDITION
VALUES
RETURNED

Any value returned by TPU$TPU

TPU-29

VAX Text Processing Utility (VAXTPU) Routines
TPU$EXECUTE_COMMAND

TPU$EXECUTE_COMMAND
Gives your program access to the execution of VAXTPU
commands.

FORMAT

TPU$EXECUTE_COMMAND string

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

ARGUMENT

string
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by value

Character string. The string argument is the address of a descriptor of a
character string denoting a VAXTPU command.

DESCRIPTION This routine performs the same function as the built-in procedure EXECUTE
procedure described in the VAX Text Processing Utility Reference Manual.

CONDITION
VALUES
RETURNED

TPU-30

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
Allows you to execute a user-written initialization file. If you intend
to use this routine, it must be executed after initializing the editor,
and before processing any other commands.

FORMAT

TPU$EXECUTE_INIFILE

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

None.

DESCRIPTION This routine first checks to see if a section file has been mapped in

successfully. If so, it looks up the symbol TPU$INIT__PROCEDURE, and
if this symbol is a procedure it executes it. Next, the routine checks to see if
the /COMMAND qualifier is specified. If so, it creates a buffer and reads the
file into it. This buffer is then compiled and executed.

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.

CONDITION
VALUES
RETURNED

TPU$_SUCCESS

Normal successful completion.

TPU$_EXITING

Returning as a result of EXIT. If the default
condition handler is being used, the session is
terminated.

TPU$_QUITTING

Returning as 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.

TPU-31

VAX Text Processing Utility (VAXTPU) Routines
TPUSFILEIO

TPU$FILEIO
Handles file operations. Your own file I/O 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.
This routine always puts values greater than 511 in the first
longword. Because a user-written file I/O routine is restricted to
the values 0-511, you can easily distinguish the file control blocks
(FCB) this routine fills in from the ones you created.

FORMAT

TPU$FILEIO

RETURNS

VMS Usage:
type:
access:
mechanism:

code, stream, data

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."
The file I/O routine returns an RMS status code to VAXTPU. The file I/O
routine is responsible for signaling all errors if any messages are desired.

ARGUMENTS

code
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by reference

Item code. The code argument is the address of a longword that contains an
item code from VAXTPU which specifies a function to perform.
Following are the item codes that can be specified in the file I/O routine:

TPU-32

•

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 stream is to be closed. All memory
being used by its structures can be released.

•

TPU$K_CLOSE—DELETE—The file specified by stream 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
stream. The routine should use the routines provided by the VAX/VMS
Run-Time Library to copy text into this descriptor. VAXTPU will free the

VAX Text Processing Utility (VAXTPU) Routines
TPU$FILEIO

memory allocated for the data read when the file I/O routine indicates 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 stream.

stream
VMS Usage:
type:
access:
mechanism:

unspecified
longword (unsigned)
modify
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 structure consists of a block of 4 longwords. Figure TPU-2 shows the
stream data structure.

Figure TPU-2

Stream Data Structure

FILE IDENTIFIER

RFM

RAT

ALLOCATION

CLASS

TYPE

LENGTH

ADDRESS OF NAME

ZK-4045-85

The first longword is used to hold a unique identifier for each file. The userwritten file I/O 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 3 fields. The low word is used to store
the allocation quantity from the FAB (FAB$L_ALQ), that is, the number of
blocks allocated to this file. This value is later used 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 byte is used to store the record format byte (FAB$B_RFM)
when an existing file is opened. These are used for creating the output file
in the same format as the input file. These 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 processing EXITs. 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.

TPU-33

VAX Text Processing Utility (VAXTPU) Routines
TPU$FILEIO

data
VMS Usage:
type:
access:
mechanism:

item_list_3
longword (unsigned)
modify
by reference

Stream data. The data argument is either the address of an item list
Note: The data is the address of a descriptor depending on the item code you
choose.
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—This item code allows you to specify one of the
following item codes in the buffer address field. These three set indicators
in the RMS file access block (FAB) indicate the type of access desired:
TPU$K_IO—OFP = TRUE (output file parse)
TPU$K_INPUT—PUT = FALSE (no write access to file)
TPU$K_OUTPUT—OFP = TRUE (output file parse), GET = FALSE (no
read access to a file)
If you need further information on these indicators see the VAX Record
Management Services Reference Manual.

TPU-34

•

TPU$K_FILENAME—This 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—This 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—This 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—This 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—This item code specifies that the buffer
address field contains the value for the record format byte in the FAB
(FAB$B_RFM) used for file creation.

•

TPU$K_MAXIMIZE_VER—This item code specifies that the version
number of the output file should be maximized with those that currently
exist.

•

TPU$K_FLUSH—This item code specifies that the file should have every
record flushed after it is written.

VAX Text Processing Utility (VAXTPU) Routines
TPU$FILEIO

•

DESCRIPTION

TPU$K_FILESIZE—This 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.

By default, TPU$FILEIO creates variable length files with carriage return
record attributes (fab$b_rfm = var, fab$b_rat = cr). If you pass it the
TPU$K_RECORD_ATTR or TPU$K_RECORD_FORM items, they are used
instead. The following combinations of formats and attributes are acceptable:

FORMAT

ATTRIBUTES

STM,STMLF,STMCR

0,BLK,CR,BLK+CR

VAR

0,BLK,FTN^R,BLK4FTN,BLK+C^

All other combinations are converted to VAR format with CR attributes.
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 I/O routine.

TPU-35

VAX Text Processing Utility (VAXTPU) Routines
TPU$HANDLER

TPU$HANDLER
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

TPUSHANDLER

RETURNS

VMS Usage:
type:
access:
mechanism:

signal_vector, mechanism— vector

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

signal—vector
VMS Usage:
type:
access:
mechanism:

arg_list
longword (unsigned)
modify
by reference

Signal vector. See the VAX/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

See the VAX/VMS System Services Reference Manual for information about the
mechanism vector passed to a condition handler.

DESCRIPTION

The TPU$MESSAGE routine does 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 12.1.2. Those values can only be modified by the
VAXTPU built-in procedure SET.
If the condition value received by the handler has a FATAL status, or does
not have VAXTPU'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—36

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 (FAO)
arguments for the associated messages. For example, if the editor attempts to
open a file that does not exist, the VAXTPU message TPU$_NOFILEACCESS
is signaled. The FAO argument to this message is a string for the name of
the file. This condition has an error status, followed by the VAX RMS fields
STS and 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$CONTROL 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 VAX/VMS System Routines for information about the
VAX Condition Handling Standard.

TPU-37

VAX Text Processing Utility (VAXTPU) Routines
TPU$INITIALIZE

TPU$INITIALIZE
Initializes VAXTPU for editing. This routine allocates global data
structures, initializes global variables, and calls the appropriate set¬
up routines for each of the major components of the editor, including
the Virtual File Manager, Screen Manager, and I/O subsystem.

FORMAT

TPUSINITIALIZE callback

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
R0. Condition values that can be returned by this routine are listed under
"CONDITION VALUES RETURNED."

ARGUMENT

callback
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
bound procedure value
read only
by descriptor

Callback routine. The callback argument is the address of a routine that
returns the address of an item list containing initialization parameters or a
routine for handling file I/O operations.
The DCL interface routine provided by VAXTPU TPU$CLI_PARSE can be
used as the callback routine. Callable VAXTPU defines nine item codes that
can be used for specifying intialization parameters. You don't have to arrange
the item codes in any particular order in the list. Figure TPU-3 shows the
general format of an item descriptor. For information about how to build an
item list, refer to the VAX/VMS programmer's manual associated with the
language you are using.
Figure TPU-3

ITEM CODE

Format of an Item Descriptor

BUFFER LENGTH

BUFFER ADDRESS
RETURN ADDRESS

ZK-4044-85

The return address in an item descriptor is usually 0.

TPVJ—38

VAX Text Processing Utility (VAXTPU) Routines
TPU$INITIALIZE

The following item codes are available to you:

Item code

Description

TPU$K_OPTIONS

Enables the command qualifiers. Seven bits in the
buffer address field correspond to the various TPU
command qualifiers. The remaining 25 bits in the
buffer address field are reserved.

TPU$K_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 is the string that is available with
GET_INFO (COMMAND—LINE, "JOURNAL—FILE"). This
string may be a null string.

TPU$K_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 CLD file has a default value for this string.
This item code must be specified if the
TPU$V_SECTION bit is set.

TPU$K_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 is the string that
is returned by the built-in procedure GET_INFO
(COMMAND_LINE, "OUTPUT_FILE"). The string may
be a null string.

TPU$K_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$K_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 may be a null string.

TPU$K_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 is the string
that is returned by the built-in procedure GET—INFO
(COMMAND—LINE, "FILE—NAME"). This file name
may be a null string.

TPU$K_FILEIO

Passes the bound procedure value of a routine to be
used for handling file operations. You may provide
your own file I/O routine or you can call TPU$FILEIO,
the utility routine provided by VAXTPU for handling
file operations. The address of the file I/O routine is
specified in the buffer address field.

TPU-39

VAX Text Processing Utility (VAXTPU) Routines
TPU$INITIALIZE

Item code

Description

TPU$K_C ALLUSER

Passes the bound procedure value of the user-written
routine that the built-in procedure CALL_USER is to
call. The address of this routine is specified in the
buffer address field.

Flag

Function

TPUSM—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

TPUSV—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.

Mask

^PUSM... indicates a mask.
2TPU$V... indicates a bit item.
To create the flags, 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 flags is to treat the 32 bits as a bitvector and set the bit (TPU$V...)
corresponding to the item you want.
Note: If this routine does not return a success status, no other calls to the editor
should be made.

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 I/O
or calluser routine addresses.
If you do not specify a section file, the software features of the editor are
limited.

TPU-40

VAX Text Processing Utility (VAXTPU) Routines
TPUSINITIALIZE

CONDITION
VALUES
RETURNED

TPU$_SUCCESS

Initialization was successfully completed.

TPU$_SYSERROR

A system service did not work correctly.

TPU$_NONANSICRT

The input device (SYS$INPUT) is not a supported
terminal.

TPUS—RESTOREFAIL

An error occurred during the restore operation.

TPU$_NOFILEROUTINE

No routine has been established to perform file
operations.

TPU$_INSVIRMEM

Insufficient virtual memory exists for the editor to
initialize.

TPU$_FAILURE

General code for all other errors during initialization.

TPU—41

VAX Text Processing Utility (VAXTPU) Routines
TPUSMESSAGE

TPU$MESSAGE
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
only be used after TPU$EXECUTE_INIFILE.

FORMAT

TPUSMESSAGE

RETURNS

VMS Usage:
type:
access:
mechanism:

string

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."
Note: The return status should be ignored because it is intended for use by the
Put Message (SYS$PUTMSG) system service.

ARGUMENT

string
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

Message. The string argument is the address of a descriptor of a 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.

TPU-42

VAX Text Processing Utility (VAXTPU) Routines
TPUSPARSEINFO

TPU$PARSEINFO
Parses a command and builds the item list for TPU$INITIALIZE. This
routine uses the Command Language Interpreter (CLI) 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. It
takes two parameters.

FORMAT

TPUSPARSEINFO fileio, calluser

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

fileio
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
bound procedure value
read only
by descriptor

File I/O routine. The fileio argument is the address of a descriptor of a file
I/O routine

calluser
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
bound procedure value
read only
by descriptor

Calluser routine. The calluser argument is the address of a descriptor of a
calluser routine.

TPU—43

VAX Text Processing Utility (VAXTPU) Routines
TPU$TPU

TPU$TPU
Invokes VAXTPU and is equivalent to the DCL EDIT/TPU command.

FORMAT

TPU$TPU command

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

ARGUMENT

command
VMS Usage:
type:
access:
mechanism:

char—string
character string
read only
by descriptor

Command string. The command argument is the address of a descriptor of a
command line. Specify TPU as the command string.

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 typed in the command at the DCL level.

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.

CONDITION
VALUES
RETURNED

TPU—44

Any condition value returned by TPU$INITIALIZE, TPU$EXECUTE —INFILE,
TPU$CONTROL, and TPU$CLEANUP.

VAX Text Processing Utility (VAXTPU) Routines
FILEIO

FILEIO
The name of this routine can be either your own file I/O routine or
the name of the VAXTPU file I/O routine (TPU$FILEIO).

FORMAT

FILEIO code, stream, data

RETURNS

VMS Usage:
type:
access:
mechanism:

cond_value
longword (usigned)
write only
by reference

Longword condition value. All utility routines return a condition in RO.
Condition values that can be returned by this routine are listed under
"CONDITION VALUES RETURNED."

ARGUMENTS

code
VMS Usage:
type:
access:
mechanism:

longword_unsigned
longword (unsigned)
read only
by reference

an item code from VAXTPU that specifies what function to perform.

stream
VMS Usage:
type:
access:
mechanism:

unspecified
longword (unsigned)
modify
by reference

File description. The stream argument is the address of a data structure
containing 4 longwords. This data structure is used to describe the file to be
manipulated.

data
VMS Usage:
type:
access:
mechanism:

item _list _3
longword (unsigned)
modify
by reference

Stream data. The data argument is the address of an item list.
Note: The data argument is the address of a descriptor depending on the item
code you choose.
The value of this parameter depends on which item code you specify.

TPU-45

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.

TPU-46

VAX Text Processing Utility (VAXTPU) Routines
HANDLER

HANDLER
A user-written routine that performs condition handling.

FORMAT

HANDLER signal—vector, mechanism—vector

RETURNS

VMS Usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. All utility routines return by value a condition
value in RO. Condition values that can be returned by this routine are listed
under "CONDITION VALUES RETURNED."

ARGUMENTS

signal—vector
VMS Usage:
type:
access:
mechanism:

arg_list
longword (unsigned)
modify
by reference

See the VAX/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

See the VAX/VMS System Services Reference Manual for information about the
mechanism vector passed to a condition handler.

DESCRIPTION If you need more information on writing condition handlers and the VAX

Condition Handling Standard, refer to the Introduction to VAX/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 can refer to the routine description of TPU$HANDLER to see what
VAXTPU's default condition handler does.

TPU—47

VAX Text Processing Utility (VAXTPU) Routines
INITIALIZE

INITIALIZE
Defaults all file specifications to a null string and all options to off
(0). However, it does not have a default for the file I/O or calluser
routine addresses. As a minimum requirement, the file I/O routine
must be specified. Otherwise the routine TPU$INITIALIZE returns a
failure status.

FORMAT

INITIALIZE callback

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

ARGUMENT

callback
VMS Usage:
type:
access:
mechanism:

vector_longword_unsigned
bound procedure value
read only
by reference

User-written callback initialization routine. The callback argument is the
address of a routine that you must call to get initialization information (such
as the address of a routine for handling file I/O). The DCL interface routine
provided by VAXTPU (TPU$CLI_PARSE) can be used as the callback routine.
A callback routine is a routine that you specify in a call to VAXTPU, which
is in turn invoked by VAXTPU. The callback routine is passed to VAXTPU
by specifying the address of the callback routine as a parameter to the
TPU$INITIALIZE routine. The callback routine itself has no parameters.
Rather, it returns the address of an item list that specifies initialization
parameters. The following section describes the structure of the item list.
Initialization parameters are listed by item code. This item list may be built at
any time, but it must be available during the execution of TPU$INITIALIZE.
The items for the list cannot be on the stack in the initial callback procedure.
Therefore, they should not be stored in local variables in the language from
which you are calling VAXTPU.

TPU-48

VAX Text Processing Utility (VAXTPU) Routines
USER

USER
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 CALI_USER. The built-in procedure CALI_USER passes
two parameters to this routine. These parameters are then passed
to the appropriate part of your application to be used as specified.
(For example, they may be used as operands in a calculation within
a FORTRAN program). Using the string routines provided by the
VAX/VMS Run-Time Library, your application fills in the stringout
parameter in the calluser routine, which returns the stringout value
to the built-in procedure CALL_USER.

FORMAT

USER integer, stringin, stringout

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

integer
VMS Usage:
type:
access:
mechanism:

longword—unsigned
longword (unsigned)
read only
by descriptor

The first parameter to the built-in procedure CALL—USER. This is an inputonly parameter and must not be modified.

stringin
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The second parameter to the built-in procedure CALL—USER. This is an
input-only parameter and must not be modified.

TPU—49

VAX Text Processing Utility (VAXTPU) Routines
USER

stringout
VMS Usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

This string is the 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 provided by the VAX/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 Reference Manual has an example of a BASIC program that
is a calluser routine.

EXAMPLES
Q

INTEGER FUNCTION TPU$CALLUSER

(x.y.z)

IMPLICIT NONE
INTEGER X
CHARACTER*(*)

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 *

'<’

lclen = LEN(Y)

// y //

’>'

♦ 2

RS = STR$COPY_DX(Z,local_copy(1:lclen))
TPU$CALLUSER = RS
END

You can call the preceding FORTRAN program with a VAXTPU procedure.
An example of such a procedure is as follows:
0

PROCEDURE MY.CALL
local status;
status

:= CALL.USER

MESSAGE('"'
ENDPROCEDURE

TPU-50

♦

(0,'ABCD');

Index
A
Access Control List Editor routine
See ACL Editor routine
ACLEDIT$EDIT • ACL-3
ACL Editor routine
example* ACL-1
introduction • ACL-1

c
CLI$DCL _PARSE • CLI-5 to CLI-7
CLISDISPATCH • CLI-8
CLI$GET_VALUE • CLI-9
CLI$PRESENT • CLI-12 to CLI-14
CLI routine
example*CLI-1 to CLI-4
introduction* CLI-1
Command language routine

DCX$MAKE_MAP • DCX-28
DCX routine
example • DCX-2 to DCX-1 1
introduction • DCX-1

E
EDT$EDIT • EDT-3
EDT routine
examples *EDT-1 to EDT-2
introduction • EDT-1
user-written
FILEIO • EDT-7
WORKIO* EDT-11
XLATE*EDT-13

F
FDL$CREATE • FDL-7
FDL$GENER ATE • FDL-12
FDL$PARSE • FDL-15
FDL$RELE ASE • FDL-18
FDL routine
examples*FDL-1 to FDL-6
introduction • FDL-1
File Definition Language routine

See CLI routine
CONVSCON VERT • CONV-8
CON V$PASS_FILES • CONV-11
CON V$PASS_OPTIONS • CONV-14
CONVSRECLAIM • CONV-18
Convert routine
See CONV routine
CONV routine
examples*CONV-1 to CONV-7
introduction • CONV-1

See FDL routine
Full callable interface
See VAXTPU routine

Data Compression/Expansion routine

Job controller
request to symbiont • SMB-6

see DCX routine
DCX$AN ALYZE_DAT A • DCX-12
DCX$AN ALYZE_DONE•DCX-14
DCX$ AN ALYZE_INIT • DCX-15
DCX$COMPRESS_D AT A • DCX-18
DCX$COMPRESS_DONE • DCX-20
DCX$COMPRESS_INIT • DCX-21
DCX$EXPAND_D AT A • DCX-23
DCX$EXPAND_DONE • DCX-25
DCX$EXPAND_INIT • DCX-26

L
LBRSCLOSE•LBR-20
LBR$DELETE_DATA • LBR-21 to LBR-22
LBR$DELETE_KEY • LBR-23 to LBR-24
LBRSFIND • LBR-25 to LBR-26

Index—1

Index

LBRSFLUSH • LBR-27 to LBR-28
LBR$GET_HELP • LBR-31 to LBR-33
LBR$GET_HISTORY • LBR-34 to LBR-35
LBR$GET__INDEX • LBR-36 to LBR-37
LBR$GET_RECORD • LBR-38 to LBR-39
LBRSGET_HEADER »LBR-29 to LBR-30
LBR$INI_CONTROL» LBR-40 to LBR-41
LBR$INSERT_KEY • LBR-42 to LBR-43
LBR$LOOKUP_KEY • LBR-44 to LBR-45
LBR$OPEN • LBR-46 to LBR-49
LBR$OUTPUT_HELP • LBR-50 to LBR-54
LBR$PUT_END • LBR-55
LBR$PUT_HISTORY»LBR-56 to LBR-57
LBR$PUT_RECORD • LBR-58 to LBR-59
LBR$REPLACE_KEY • LBR-60 to LBR-61
LBR$RET_RMSSTV • LBR-62
LBR$SEARCH • LBR-63 to LBR-64
LBR$SET_INDEX • LBR-65 to LBR-66
LBR$SET_LOCATE • LBR-67
LBR$SET_MODULE • LBR-68 to LBR-69
LBR$SET_MOVE • LBR-70
LBR routine
control index* LBR-7
current index number
setting • LBR-65 to LBR-66
data record
reading*LBR-38 to LBR-39
writing • LBR-58 to LBR-59
end-of-module record
writing • LBR-55
examples*LBR-7 to LBR-19
creating a new library • LBR-7 to LBR-10
deleting a module from a library • LBR-16 to
LBR-19
extracting a module from a library • LBR-13
to LBR-16
inserting a module into a library • LBR-10 to
LBR-13
header* LBR-2
help text
outputting • LBR-50 to LBR-54
retrieving • LBR-31 to LBR-33
index* LBR-2
searching • LBR-63 to LBR-64
introduction • LBR-1 to LBR-19
library
closing • LBR-20
creating • LBR-46 to LBR-49
help* LBR-1
macro* LBR-1
object* LBR-1
opening • LBR-46 to LBR-49

LBR routine
library (cont'd.)
shareable image*LBR-1
structure*LBR-2 to LBR-5
text • LBR-1
types*LBR-1 to LBR-2
user-developed • LBR-1
library file
flushing*LBR-27 to LBR-28
library header information
reading*LBR-29 to LBR-30
retrieving *LBR-29 to LBR-30
library index
getting contents • LBR-36 to LBR-37
initializing • LBR-40 to LBR-41
searching for key*LBR-36 to LBR-37
library key • LBR-2
creating ASCII or binary • LBR-47
deleting *LBR-23 to LBR-24
finding • LBR-25 to LBR-26
inserting • LBR-42 to LBR-43
looking up*LBR-44 to LBR-45
replacing • LBR-60 to LBR-61
library update history record
retrieving • LBR-34 to LBR-35
locate mode
setting record access mode to*LBR-67
module* LBR-2
accessing with RFA* LBR-25 to LBR-26
deleting data records • LBR-21 to LBR-22
deleting header*LBR-21 to LBR-22
module header
reading*LBR-68 to LBR-69
setting*LBR-68 to LBR-69
updating • LBR-68 to LBR-69
move mode
setting record access to*LBR-70
summary *LBR-6 to LBR-7
update history records
writing • LBR-56 to LBR-57
VAX RMS status value
returning* LBR-62
virtual memory
recovering*LBR-27 to LBR-28
Librarian routine
See LBR routine

p
Print Symbiont Modification routine
See PSM routine

Index—2

Index

PSM$_FUNNOTSUP • PSM-34
PSM$PRINT »PSM-22
PSM$READ_ITEM_DX • PSM-24
PSM$REPLACE • PSM-26
PSM$REPORT • PSM-31
PSM routine* PSM-21
example • PSM-17 to PSM-21
introduction • PSM-1
user-written
USER-FORMAT-ROUTINE • PSM-33
USER-INPUT-ROUTINE • PSM-38
USER-OUTPUT-ROUTINE • PSM-44

Q
Queue
execution • PSM-4
generic* PSM-4

s
Simplified callable interface
See VAXTPU routine
SMB$CHECK_FOR_MESSAGE • SMB-16
SMBSINITIALIZE • SMB-17
SMBSRE AD_MESS AGE • SMB-19
SMB$READ_MESSAGE_ITEM • SMB-22
SMB$SEND__TO_IOBCTL • SMB-35
SMB routine*SMB-15
See also Job Controller
See also Symbiont
introduction • SMB-1
SOR$$STAT *S0R-49
SOR$BEGIN_MERGE • SOR-20
SOR$BEGIN_SORT • SOR-27
SOR$END_SORT • SOR-33
SOR$PASS_FILES • SOR-35
SOR$RELEASE_REC • SOR-40
SOR$RETURN_REC • SOR-42
SOR$SORT_MERGE • SOR-44
SOR$SPEC_FILE • SOR-47
SOR routine *SOR-19
examples *SOR-4 to SOR-19
interface
file* SOR-2
record • SOR-2
introduction • SOR-1

SOR routine (cont'd.)
reentrancy
using context argument • SOR-3
Sort/Merge routine
See SOR routine
Symbiont
See also Queue
allocating memory*SMB-4
carriage control
processing of*PSM-1 1
connecting to a device*SMB-5
device* PSM-2
environments • SMB-5
function • PSM-4, SMB-3
input*PSM-2, SMB-1
INPSMB.EXE file*SMB-1
internal logic *PSM-5
main format routine • PSM-13
main input routine*PSM-10
main output routine*PSM-14
job controller
communication with*SMB-1
job controller request • SMB-6
asynchronous • SMB-7
processing • SMB-12
reading* SMB-1 1
responding • SMB-14
synchronous • SMB-6
modification • PSM-7
format routine • PSM-12
guidelines • PSM-8
initialization routine • PSM-15
input routine*PSM-9
integration of routines • PSM-16
output routine*PSM-13
restrictions • PSM-8
modifying • SMB-4
multistream • SMB-1 1
multithreaded • PSM-3
output • PSM-2, SMB-1
PRTSMB.EXE file*SMB-1
Process-permanent file*SMB-4
server*PSM-2, SMB-1
single stream • PSM-3, SMB-1 1
SYSGEN MAXBUF parameter • PSM-7
type* SMB-1
user-written • SMB-1, SMB-4
guidelines • SMB-4
VAX/VMS printer*SMB-1
Symbiont/Job Controller Interface routine
See SMB routine
Symbiont thread • PSM-3

Index—3

Index

T
TPUSCLE ANUP • TPU-23
TPU$CLIPARSE • TPU-27
TPUSCONTROL•TPU-28
TPU$EDIT *TPU-29
TPU$EXECUTE_COMM AND • TPU-30
TPU$EXECUTE_INIFILE • TPU-31
TPU$FILEIO • TPU-32
TPUSH ANDLER • TPU-36
TPU$INITI ALIZE • TPU-38
TPUSMESSAGE • TPU-42
TPUSPARSEINFO • TPU-43
TPU$TPU • TPU-44

User-written VAXTPU routine
See VAXTPU routine

VAX Text Processing Utility Routine
See VAXTPU routine
VAXTPU Callable interface
See VAXTPU routine
VAXTPU routine
Callable VAXTPU* TPU-1
error handling • TPU-3
full interface *TPU-2, TPU-5
overview* TPU-1
simplified interface *TPU-2, TPU-4
condition handler
condition codes*TPU-4
default* TPU-4
return values*TPU-4
universal symbols • TPU-4
example*TPU-5, TPU-7 to TPU-22
introduction • TPU-1
parameter
bound procedure value*TPU-3
shareable image*TPU-1, TPU-3
constants • TPU-3
symbols* TPU-3
user-written
FILEIO • TPU-45
HANDLER *TPU-47

Index—4

VAXTPU routine
user-written (cont'd.)
INITIALIZE •TPU-48
requirements • TPU-6
USER • TPU-49
user-written routine • TPU-6
VMS print symbiont
See Symbiont

VAX/VMS
Utility Routines
Reference Manual
AA-Z504B-TE

READER'S
COMMENTS

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

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

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

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

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

Name _Date_
Organization _
Street City _State_Zip Code_
or Country

—

Do Not Tear - Fold Here and Tape

mmm

No Postage
Necessary
if Mailed in the
United States

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

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

iimIIiIImiiIIiihIiIIiIiiIiIhIiIhII.Ml
Do Not Tear - Fold Here

Cut Along Dotted Line

— —

VAX/VMS
Utility Routines
Reference Manual
AA-Z504B-TE

READER'S
uUmlYltnl I O

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

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

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

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

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

Name _Date_
Organization _
Street _
City _State_Zip Code_
or Country

No Postage
Necessary
if Mailed in the
United States

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

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

m11

—

1 11 1 1 1 1 1 11

11 ii 1

1 11 1 11 1

..Ml

Do Not Tear - Fold Here

Cut Along Dotted Line

Do Not Tear - Fold Here and Tape