Digital PDFs

AA-LA97C-TE

December 1990

463 pages

Original

19MB

Document:	. VMS VMS Version 5.4 New Features Manual
Order Number:	AA-LA97C-TE
Revision:
Pages:	463
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/5.4/AA-LA97C-TE_VMS_5.4_New_Features_Manual_Jun1990.pdf

OCR Text

· VMS

VMS Version 5.4 New
Features Manual

Order Number: AA-LA97C-TE

o
VMS Version 5.4 New

Features Manual

Order Number: AA-LA97C-TE

June 1990

This manual describes the new features of the VMS Version 5.4 operating
system. It also describes features that were new for Versions 5.1, 5.2, and
5.3 of the VMS operating system but are not yet documented in other printed
manuals.

Revision/Update Information:

This manual supersedes previous versions
of the VMS New Features Manual.

Software Version:

VMS Version 5.4

digital equipment corporation
maynard, massachusetts

c
June 1990

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

c:)

© Digital Equipment Corporation 1990.
All Rights Reserved.
Printed in U.S.A.
The postpaid Reader's Comments forms at the end of this document request your
critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
CDA
DDIF
DEC
DECdtm
DECnet
DECUS
DECwindows
DECwriter

DEONA
Desktop-VMS
DIGITAL
GIGI
HSC
Live Link
LN03
MASSBUS

MicroVAX
PrintServer 40
O-bus
ReGIS
ULTRIX
UNIBUS
VAX
VAXcluster

VAX RMS
VAXserver
VAXstation
VMS
VT
XUI

mamaDmo™

The following are third-party trademarks:
Adobe, Display PostScript, and PostScript are registered trademarks of Adobe
Systems Incorporated.
ITC Avant Garde Gothic is a registered trademark of International Typeface
Corporation.
X Window System, Version 10 and its derivations (X, X10, X Version 10, X Window
System) are trademarks of the Massachusetts Institute of Technology.
X Window System, Version 11 and its derivations (X, X11, X Version 11, X Window
System) are trademarks of the Massachusetts Institute of Technology.

ZK5481

o
Production Note

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

o
Contents
xxiii

PREFACE

PART 1 : OVERVIEW OF MAJOR NEW FEATURES

o
0

CHAPTER 1 SUMMARY OF NEW VMS VERSION 5.4 SOFTWARE
FEATURES

1-1

CHAPTER 2 INTRODUCTION TO VECTOR PROCESSING

2-1

2.1
2.1.1
2.1.2
2.1.3

2.1.3.1
2.1.3.2

2.2
2.2.1
2.2.2
2.2.3

2.2.3.1
2.2.3.2
2.2.4
2.2.5

2.2.5.1
2.2.5.2
2.2.5.3
2.2.5.4
2.2.5.5
2.2.5.6

2.2.6
2.2.7

OVERVIEW OF THE VECTOR PROCESSING ENVIRONMENT
VAX Vector Processing Systems
Vectorized Programs
VMS Support for Vector Processing
Life of a Vector Consumer • 2-5
VAX Vector Instruction Emulation Facility (VVIEF) • 2-7

2-1
2-2
2-3
2-5

MANAGING THE VECTOR PROCESSING ENVIRONMENT
Loading the VMS Vector Processing Support Code
Configuring a VMS Vector Processing System
Managing Vector Processes
Adjusting System Resources and Process Quotas • 2-10
Distributing Scalar and Vector Resources Among
Processes • 2-11
Restricting Access to the Vector Processor by Using ACLs
Obtaining Information About a Vector Processing System
DCl lexical Functions F$GETJPI and F$GETSYI • 2-13
SHOW CPU Command • 2-13
SHOW PROCESS and lOGOUT/FUll Commands • 2-13
Vector Processing Support Within the VMS Accounting Utility
(ACCOUNTING) • 2-14
Vector Support Within the Error log Utility (ERROR lOG) • 2-14
Vector Support Within the VMS Monitor Utility (MON ITOR) • 2-14
Loading the VAX Vector Instruction Emulation Facility (VVIEF)
System Messages Related to Vector Processing Activities - -

2-8
2-8
2-8
2-9

2-11
2-12

2-15
2-15

Contents

0
2.3
2.3.1
2.3.2
2.3.3
2.3.4
2.3.5
2.3.5.1
2.3.5.2

2.3.5.3
2.3.5.4
2.3.6
2.3.7
2.3.7.1
2.3.7.2
2.3.7.3
2.3.7.4
2.3.7.5
2.3.7.6
2.3.8
2.3.9

PROGRAMMING IN A VECTOR PROCESSING ENVIRONMENT
Vector Routines in the MTH$ Run-Time Library
Obtaining Information About a Vector Processing System
Releasing the Vector Processor
Preserving and Restoring a Routine's Vector State
Debugging a Vectorized Program
Vector Processing Support Within the VMS Debugger • 2-25
Vector Processing Support Within the VMS System Dump
Analyzer (SDA) • 2-25
Vector Processing Support Within the VMS Delta/XDelta
Utility • 2-26
Vector Processing Support Within the VMS Patch Utility • 2-27
Servicing Vector Exceptions
Requirements of the VAX Procedure Calling and Condition Handling
Standard for Vector Processing
Vector Register Usage • 2-32
Vector and Scalar Processor Synchronization • 2-32
Memory Synchronization • 2-32
Exception Synchronization • 2-32
Synchronization Summary • 2-33
Condition Handler Parameters and Invocation • 2-33
VMS Accounting Utility (ACCOUNTING) Resource Packet
Format
VMS Monitor Utility (MONITOR) VECTOR Class Record

CHAPTER 3 INTRODUCTION TO DECDTM SERVICES

2-19
2-21
2-22
2-23
2-23
2-25

2-27

~.
'~ )

2-31

0
2-34
2-34

3-1

3.1

CHARACTERISTICS OF DISTRIBUTED TRANSACTIONS

3-1

3.2
3.2.1
3.2.2
3.2.3

TRANSACTION PROCESSING SYSTEM MODEL
Resource Manager
Transaction Manager
Log Manager

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

3.3

OVERVIEW OF TWO-PHASE COMMIT PROTOCOL

3-6

3.4

MANAGING DECDTM SERVICES USING VMS UTILITIES

3-7

0
vi

Contents

3.5

NEW TRANSACTION_ID DATA TYPE FOR PROGRAMMING
ROUTINES

3-8

PART 2: GENERAL USER FEATURES

CHAPTER 4 DCl COMMANDS AND lEXICAL FUNCTIONS

4-1

CHAPTER 5 EVE EDITOR

5-1

5.1

BOX EDITING

5-1

5.2

NEW COMMAND: CONVERT TABS

5-2

5.3

NEW QUALIFIERS: !WORK AND IINTERFACE

5-2

5.4

ADDITIONAL SOURCES OF NEW EVE INFORMATION

5-2

CHAPTER 6 SYSTEM MESSAGES

6-1

6.1

VMS FACILITIES WITH NEW OR MODIFIED SYSTEM MESSAGES

6-1

6.2

SYSTEM MESSAGES AVAILABLE FROM ONLINE HELP

6-2

CHAPTER 7 DECWINDOWS USER AND DESKTOP APPLICATIONS
7.1
7.1.1
7.1.2

SESSION MANAGER
Setting Another Session Language
Changing Your Target Screen

7-1
7-1
7-1
7-1

o
vii

Contents

G
7.2
7.2.1
7.2.2

CDA VIEWER
Viewing a PostScript File
New Processing Options for Viewing PostScript Files

7-2
7-3
7-3

7.3

CALCULATOR

7-5

7.4

CLOCK

7-5

7.5

MAIL: DISPLAYING POSTSCRIPT FILES

7-5

C'
PART 3: SYSTEM MANAGEMENT FEATURES
CHAPTER 8 AUTOGEN COMMAND PROCEDURE

8-1

8.1

PARAMETER NAME VALIDATION

8-1

8.2

AGEN$FEEDBACK.REPORT REPLACED BY NEW FILE

8-1

8.3

MODPARAMS.DAT INCLUDES EXTERNAL PARAMETER FILES

8-2

8.4

MIN_, MAX_, AND ADD_ VALUES ALLOWED FOR PAGE AND SWAP
FILES

8-3

8.5

NEW FEEDBACK PARAMETERS

8-4

8.6

LOGICAL NAMES DEFINED BY AUTOGEN

8-4

8.7

NEW TECHNIQUE FOR RUNNING AUTOGEN IN BATCH MODE

8-4

8.8

USING MAIL TO SEND AGEN$PARAMS.REPORT

8-7

0
viii

Contents

c
CHAPTER 9 USER ENVIRONMENT TEST PACKAGE (UETP)
9.1

RRD40 COMPACT DISC DRIVE SUPPORT

9-1

9.2

VECTOR PROCESSING SUPPORT

9-1

CHAPTER 10 SYSMAN ,UTILITY

RUNNING A SYSMAN COMMAND PROCEDURE

10-1

10.2

DEFINING KEYS WITH THE DEFINE COMMAND

10-1

10.3

SPAWNING A SUBPROCESS FROM WITHIN SYSMAN

10-1

10.4

USING DCl VERIFICATION

10-1

10.5

USING lOADABlE IMAGE COMMANDS

10-1

VAXCLUSTER MANAGEMENT

11-1

11.1

CI ARCHITECTURE EXTENSIONS

11-1

11.2

MSCP SERVER lOAD SHARING

11-1

11.3

PREFERRED PATH SUPPORT FOR DSA DISKS

11-2

CHAPTER 12 SYSTEM GENERATION UTILITY (SYSGEN)

12-1

12.1

10-1

10.1

CHAPTER 11

9-1

12.2

SCSI_NOAUTO PARAMETER

12-1

12-2

Contents

0
12.3

LOAD_SYS_IMAGES PARAMETER

12-2

12.4

SUPPORTED DEVICE NAMES FOR VAXFT 3000 SYSTEMS

12-3

12.S

NEW SYSGEN COMMANDS
SHOW/BI=BIINDEX
SHOW/BUS=BUSID
SHOW/XMI=BIINDEX

12-3
12-4
12-S
12-6

CHAPTER 13 ERROR LOG UTILITY (ERROR LOG)
13.1

SUPPORTED DEVICE TYPES FOR VAXFT 3000 SYSTEMS

13-1

13.2

NEW KEYWORDS FOR IEXCLUDE AND IINCLUDE QUALIFIERS

13-1

13.3

NEW QUALIFIER: INODE

13-2

CHAPTER 14 SYSTEM SECURITY
14.1
14.1.1
14.1 .1 .1
14.1.1.2

14.1.2

SITE-DEFINED PASSWORD POLICY
Screening New Passwords
Password History List • 14-2
Site-Specific Filter • 14-2
Specifying a Password Algorithm

CHAPTER 15 LOG MANAGER CONTROL PROGRAM UTILITY (LMCP)
1S.1
1S.1.1
1S.1.2
1S.1.3
1S.1.4
1S.1.S
1S.1.6
1S.1.7

13-1

MANAGING TRANSACTION LOG FILES
Defining SYS$JOURNAL
Placing a Transaction Log File
VAXcluster Failover
Determining Transaction Log File Size
Creating Transaction Log Files
Example of Creating a Transaction Log File
Resizing and Moving Transaction Log Files

~)
c __

()

14-1

14-1
14-1
(\

~---)
14-3

1S-1

1S-1
1S-1
1S-2
1S-3
1S-4
1S-4
1S-S
1S-7

Contents

C
15.2

15-12

LMCP Commands

15-13
CONVERT
CREATE
DUMP
HELP
REPAIR
ABORT
COMMIT
EXIT
FORGET
HELP
NEXT

15-14
15-16
15-18
15-22

SHOW

15-33

CHAPTER 16 MONITOR UTILITY (MONITOR)

15-23
15-26
15-27
15-28
15-29
15-30
15-32

16-1

16.1

MONITOR TRANSACTION COMMAND

16-1

16.2

TRANSACTION CLASS RECORD

16-5

16.3

MONITOR VECTOR COMMAND

16-7

16.4

VECTOR CLASS RECORD

16-9

CHAPTER 17 NETWORK CONTROL PROGRAM UTILITY (NCP)
17.1

15-9

LMCP Usage Summary

FORMAT OF TRANSACTION LOG FILES

17.2

17-1

LINE AND CIRCUIT NAME SUPPORT FOR VAXFT 3000
SYSTEMS

17-1

LINE AND CIRCUIT NAMES FOR NEW ETHERNET/820
CONTROLLERS

17-1

Contents

o
CHAPTER 18 VMS VOLUME SHADOWING PHASE II

18-1

PART 4: PROGRAMMING FEATURES
CHAPTER 19 VMS DEBUGGER

19-1

19.1

DEBUGGING VECTORIZED PROGRAMS

19-1

19.2

COMMAND INTERFACE: NEW AND ENHANCED COMMANDS AND
QUALIFIERS

19-1

19.3

DECWINDOWS INTERFACE: ENHANCEMENTS TO MENUS AND DIALOG
BOXES
19-2

CHAPTER 20 LINKER UTILITY (LINK)

20-1

CHAPTER 21

21-1

UTILITY ROUTINES: MAIL

CHAPTER 22 SYSTEM SERVICES

xii

22-1

22.1

SUMMARY OF NEW SYSTEM SERVICES

22-1

22.2
22.2.1
22.2.2
22.2.3
22.2.4
22.2.5
22.2.6

USING TRANSACTION MANAGEMENT SYSTEM SERVICES
Transaction Processing System Model
Transaction Management
Starting a Transaction
Completing a Transaction
Calling a Planned Abort
Example of Using Transaction Management System Services

22-2
22-3
22-4
22-4
22-6
22-6
22-7

22.3

USING THE INITIALIZE VOLUME ($INIT_VOL) SYSTEM SERVICE

22-9

C_J-_"')

Contents

C
22.4

22.5
22.5.1
22.5.1.1
22.5.1.2
22.5.2

DESCRIPTIONS OF NEW SYSTEM SERVICES

22-10

$ABORT_TRANS

22-11

$ABORT_TRANSW

22-15

$END_TRANS

22-16

$END_TRANSW

22-20

$FORMAT_AUDIT

22-21

$HASH_PASSWORD

22-25

$INIT_VOL

22-28

$RELEASE_VP

22-41

$RESTORE_VP_EXCEPTION

22-42

$RESTORE_VP_STATE

22-44

$SAVE_VP_EXCEPTION

22-46

$START_TRANS

22-48

$START_TRANSW

22-52

22.5.3
22.5.4
22.5.5
22.5.5.1
22.5.5.2
22.5.6
22.5.6.1
22.5.6.2
22.5.7
22.5.8
22.5.9
22.5.10

MODIFIED SYSTEM SERVICES
$CHANGE_ACL
Vector Processing: New Object Type • 22-53
System Security: New Item Codes • 22-53
$CHECK_ACCESS: Vector Processing and System Security
Support
$ENQ: Enhanced Lock Manager Support
$GETDVI: New Device Classes
$GETJPI
Vector Processing: New Item Codes • 22-55
System Security: New Item Codes • 22-56
$GETSYI
Vector Processing: New Item Codes • 22-58
System Security: New Item Code • 22-58
$GETUAI: New Item Codes for Enhanced Password Screening
$MOD_IDENT: New Status Code
$MOUNT: Volume Shadowing Flags
$SETUAI: New Item Codes for Enhanced Password Screening

22.6
22.6.1
22.6.1.1
22.6.1.2
22.6.2
22.6.2.1
22.6.2.2

IMPLEMENTING SITE-SPECIFIC SECURITY POLICIES
Creating Loadable Security Services
Preparing and Loading a System Service • 22-63
Removing an Executive Loaded Image • 22-64
Installing Site-Specific Password Policy Filters
Creating a Shareable Image • 22-65
Installing a Shareable Image • 22-65

22-53
22-53

22-54
22-54
22-55
22-55

22-58

22-58
22-60
22-60
22-60

22-62
22-62

22-64

xiii

Contents

o
CHAPTER 23 RUN-TIME LIBRARY ROUTINES

23-1

23.1

PARALLEL PROCESSING (PPL$)

23-1

23.2

MATHEMATICS (MTH$)

23-2

CHAPTER 24 VMS RECORD MANAGEMENT SERVICES

24-1

24.1

VMS RMS ASYNCHRONOUS SUPPORT FOR PROCESS-PERMANENT
24-1
FILES

24.2

LOCAL BUFFER MAXIMUM INCREASED

24-1

24.3
24.3.1
24.3.2

ACCESS-MODE PROTECTION FOR VMS RMS
Access-Mode Protected Services
Access-Mode Protected Memory

24-2
24-2
24-3

24.4
24.4.1
24.4.2

EXPIRED-DATE SUPPRESSION
- The Role of XAB$_NORECORD XABITM
Applications for XAB$_NORECORD XABITM

24-3
24-3
24-4

CHAPTER 25 1/0 DRIVER SUPPORT

25-1

25.1

PSEUDOTERMINAL DRIVER

25-1

25.2

SHADOW SET VIRTUAL UNIT DRIVER

25-1

25.3

NEW MODIFIER BITS FOR TRM$_MODIFIERS ITEM CODE

25-1

25.4

ITEMLIST READ FUNCTION I/O STATUS BLOCK

25-2

25.5

NEW ACP-QIO FUNCTION ATTRIBUTES

25-2

0
xiv

Contents

o
CHAPTER 26 SYSTEM DUMP ANALYZER UTILITY (SDA)
26.1

NEW SHOW PROCESS QUALIFIER: IIMAGES

26-1

26.2

NEW SHOW PROCESS QUALIFIER: IVECTOR_REGISTERS

26-2

CHAPTER 27 DEVICE SUPPORT

26-1

27-1

27.1

VAX 9000 HARDWARE CONSIDERATIONS

27-1

27.2

VAX 9000 SYSTEM ADDRESS SPACE

27-1

27.3

DRIVER DEBUGGING WITH POOL CHECKING

27-7

CHAPTER 28 VAX TEXT PROCESSING UTILITY (VAXTPU)

28-1

28.1

NEW QUALIFIER: IINTERFACE

28-1

28.2

NEW AND ENHANCED BUILT-IN PROCEDURES

28-1

28.3

WORK FILE SUPPORT

28-2

CHAPTER 29 VAX RMS JOURNALING: SUPPORT FOR DECDTM
SERVICES

29-1

29.1

SUPPORT FOR DECDTM TRANSACTIONS

29-1

29.2

RUF SERVICES EMULATED

29-1

29.3

NETWORK SUPPORT

29-2

0
xv

Contents

0
29.4
29.4.1
29.4.2

RECORD STREAM ASSOCIATION
How Streams Become Associated with a Transaction
Stream Association Using RUF and DECdtm Services

29-3
29-3
29-3

29.5
29.5.1
29.5.2

DETACHED RECOVERY
Synchronous and Asynchronous Recovery
Partial Recovery

29-4
29-4
29-4

29.6

PLACEMENT OF RECOVERY UNIT JOURNALS

29-5
(

29.7

MULTIPLE LONG-TERM JOURNALS ALLOWED

29-6

29.8

MIXED-VERSION CLUSTERS

29-6

CHAPTER 30 VMSINSTAL
30.1

30.2

CHAPTER 31

~-.)

30-1

NEW PARAMETER FOR THE VMSINSTAL SPKITBLD.COM
PROCEDURE

30-1

NEW AND ENHANCED VMSINSTAL CALLBACKS

30-1

DECWINDOWS AND CDA PROGRAMMING FEATURES

31-1

31.1.1
31.1.2
31.1.3
31.1.4

NEW PROGRAMMING EXAMPLES IN DECW$EXAMPLES
DIRECTORY
BTrap (Broadcast Message Trapper)
TestVHist (Histogram Widget Exerciser)
TestVList (VList Widget Exerciser)
VDragExample (VDrag Exerciser)

31-1
31-1
31-2
31-2
31-3

31.2

XUI TOOLKIT: ENHANCEMENTS TO COLOR MIXING WIDGET

31-3

31.3

VMS DECWINDOWS DISPLAY POSTSCRIPT SYSTEM

31-4

31.1

0
xvi

Contents

c
31.4
31.4.1
31.4.2
31.4.3

COMPOUND DOCUMENT ARCHITECTURE (CDA)
PostScript Support for CDA VIEW Command
CDA Viewer Support of Adobe Font Metrics and DECmath
Fonts
New CDA Documentation

APPENDIX A VMS VERSION 5.3 FEATURES

A.1
A.1.1
A.1.2
A.1.3
A.1.4

VMS VERSION 5.3 SYSTEM MANAGEMENT FEATURES
Extension of Lock Manager Limit
NCP Executor Command Changes
Parameter for SET/DEFINE EXECUTOR
SHOW EXECUTOR CHARACTERISTICS Command

A.2

VMS VERSION 5.3 SUPPORT FOR THE VMS DISTRIBUTED NAME
SERVICE
Introduction to the Distributed Name Service
The DNS Namespace
Planning Namespace Objects • A-4
Restrictions • A-4
Usi ng the Namespace • A-5
Object Names • A-5
Object Attributes • A-5
Structure of a Namespace
Naming Syntax • A-7
Logical Names • A-8
Valid Characters for DNS Names • A-8
Creating Objects
Modifying Objects
Distributing the Namespace
Replicating Directories • A-15
Types of Directories· A-16
Setting Confidence • A-16
Maintaining Consistency in Data • A-17
Requesting Information from DNS
Reading Objects • A-18
Listing Information • A-21
How the Clerk Locates Data • A-24
DNS System Services
A-26
$DNS
A-50
$DNSW
DNS Run-Time Routines

A.2.1
A.2.2
A.2.2.1
A.2.2.2
A.2.2.3
A.2.2.4
A.2.2.S
A.2.3
A.2.3.1
A.2.3.2
A.2.3.3
A.2.4
A.2.5
A.2.6
A.2.6.1
A.2.6.2
A.2.6.3
A.2.6.4
A.2.7
A.2.7.1
A.2.7.2
A.2.7.3
A.2.8

A.2.9

31-5
31-5
31-6
31-6

A-1

A-1
A-1
A-1
A-1
A-2

A-3
A-3
A-4

A-6

A-10
A-12
A-15

A-17

A-25

A-51
xvii

Contents

A.2.10
A.2.11

DNS$APPEND_ SIMPLENAME_TO_RIGHT

A-52

DNS$COMPARE_FULLNAME

A-54

DNS$COMPARE_SIMPLENAME

A-55

DNS$CONCATENATE_NAME

A-56

DNS$COUNT_SIMPLENAMES

A-58

DNS$CVT_DNSADDRESS_TO_BINARY

A-59

DNS$CVT_DNSADDRESS_TO_NODENAME

A-61

DNS$CVT_NODENAME_TO_DNSADDRESS

A-63

DNS$CVT_TO_USERNAME_STRING

A-65

DNS$PARSE_USERNAME_STRING

A-67

DNS$REMOVE_FIRST_SET_VALUE

A-70

DNS$REMOVE_LEFT_SIMPLENAME

A-73

DNS$REMOVE_RIG HT_ SIMPLENAME
Starting the DNS Clerk
DECnet Event Messages

A-75

APPENDIX B VMS VERSION 5.2 FEATURES
8.1
8.1.1
B.1.1.1
B.1.1.2
B.1.2
B.1.2.1
B.1.2.2
B.1.2.3
8.1.3
B.1.3.1
B.1.3.2
B.1.4
B.1.4.1
B.1.4.2
B.1.4.3
B.1.4.4
B.1.4.5
B.1.4.6
B.1.4.7

VMS VERSION 5.2 SYSTEM MANAGEMENT FEATURES
System Generation Utility (SYSGEN)
DEINSTALL Command Description • B-1
ERLBUFFERPAGES Parameter • B-2
NETCONFIG.COM Security Enhancements
Default Access Options • B-2
Security Benefits • B-4
Questions Posed by NETCONFIG.COM • B-4
New NETCONFIG_UPDATE.COM for Existing Networks
Benefits of NETCONFIG_UPDATE.COM • B-5
Using NETCONFIG_UPDATE.COM in a VAXcluster • B-5
Backup Utility (BACKUP)
Performance Enhancements • 8-5
Setting Up the BACKUP Account • B-6
Setting System Generation Utility (SYSGEN) Parameters • B-7
Understanding Why the Output Device Seems Idle • 8-8
IBUFFER_COUNT Command Qualifier Is Now Obsolete • B-8
Cyclic Redundancy Checking Emulation Improvements • B-8
Pressing CtrllT to Obtain Information About BACKUP
Operations • B-8

0
A-77
A-77

8-1

8-1
8-1

8-2

B-4

8-5

0
xviii

Contents

c
8.2
8.2.1
8.2.2
8.2.3
8.2.4
8.2.5
8.2.6
8.2.7

8.2.8
8.2.9
8.2.10
8.2.11
8.2.12
8.2.13
8.2.14
8.2.15
8.2.16
8.2.17
8.2.18
8.2.19
8.2.20

8.2.21
8.2.22
8.2.23
8.2.24
8.2.25
8.2.26
8.2.27
8.2.28
8.2.29
8.2.30

8-9
VMS VERSION 5.2 SYSTEM SERVICES FEATURES
8-10
Modifications to $SETUAI and $GETUAI
New Item Codes for $SETUAI and $GETUAI
8-11
New Authorization Flags for $SETUAI and $GETUAI
8-12
8-12
Modifications to $MOUNT
8-13
Modifications to $DISMOUNT
8-14
Modification to $MOD_'DENT
Modifications to Existing System Services for Clusterwide Process
8-14
Accessibility
8-15
Process Information Services
Overview of $GETJPI and $GETJPI with $PROCESS_SCAN
8-15
Using the Process ID to Obtain Information
8-16
8-17
Using the Process Name to Obtain Information
Modifications to $GETJPI
8-18
8-18
Using $GETJPI Alone
8-19
Requesting Information About a Single Process
Requesting Information About All Processes on the Local
8-20
System
8-22
Using $GETJPI with $PROCESS~SCAN
8-22
Using the $PROCESS_SCAN Item List and Item-Specific Flags
Requesting Information About Processes That Match One
Criterion
8-24
Requesting Information About Processes That Match Multiple Values for
One Criterion
8-26
Requesting Information About Processes That Match Multiple
8-27
Criteria
8-28
Specifying a Node as Selection Criterion
8-29
Scanning All Nodes on the Cluster for Processes
8-29
Scanning Specific Nodes on the Cluster for Processes
Conducting Multiple Simultaneous Searches with
8-30
$PROCESS_SCAN
8-31
Programming Considerations for GETJPI$
8-31
Using Item Lists Correctly
Improving Performance by Using 8uffered $GETJPI
8-31
Operations
Meeting Remote $GETJPI Quota Requirements
8-33
Using $GETJPI Control Flags
8-33
8-38
Descriptions of New VMS Version 5.2 System Services
8-39
$DEVICE_SCAN
8-42
$PROCESS_SCAN

o
xix

Contents

0
APPENDIX C VMS VERSION 5.1 FEATURES

C-1

C.1.4
C.1.5

VMS VERSION 5.1 SUPPORT FOR COMPOUND DOCUMENTS
VMS Commands and Utilities
Displaying RMS File Tags • C-2
C.1.1.1.1
DIRECTORY/FULL • C-2
C.1.1.1.2 ANALYZE/RMS_FILE • C-3
Creating RMS File Tags • C-3
Preserving RMS File Tags and DDIF Semantics • C-4
C.1.1.3.1
COpy Command • C-4
C.1.1.3.2 VMS Mail Utility • C-5
APPEND Command • C-5
DDIF Support in a Heterogeneous Environment
EXCHANGE/NETWORK Command • C-6
COpy Command • C-6
VMS Mail Utility • C-7
DDIF File Access Within a Mixed Version Cluster • C-7
VMS RMS Interface Changes
Programming Interface for File Tagging • C-8
$XA8ITM
C-9
Accessing a Tagged File • C-11
C.1.3.2.1
File Accesses That Do Not Sense Tags • C-12
C.1.3.2.2 File Accesses That Sense Tags • C-12
Preserving Tags • C-14
Distributed File System Support for DDIF Tagged Files
VMS RMS Errors

C-15
C-15

C.2

EXCHANGE/NETWORK COMMAND

C-16

C.1
C.1.1
C.1.1.1

C.1.1.2
C.1.1.3

C.1.1.4

C.1.2
C.1.2.1
C.1.2.2
C.1.2.3
C.1.2.4
C.1.3
C.1.3.1
C.1.3.2

C.1.3.3

C-1
C-2

C-6

C~~I

C-7

("',\
~

INDEX

EXAMPLES
Sample AUTOGEN Command Procedure

15-1

Sample Transaction Log File

15-10

22-1

Using Transaction Management Services

22-7

8-1

Using $GETJPI to Obtain Information About the Calling
Process

8-19

Using $GETJPI and the Process Name to Obtain Information
About a Process

8-20

Using $GETJPI to Request Information About All Processes
on the Local System

8-21

8-2
8-3

8-5

8-1

Contents

C
Using $GETJPI and $PROCESS_SCAN to Select Process
Information by User Name

8-24

Using $GETJPI and $PROCESS_SCAN with Multiple Values
for One Criterion

8-27

8-6

Selecting Processes That Match Multiple Criteria

8-28

8-7

Searching the Cluster for Process Information

8-29

8-8

Searching for Process Information on Specific Nodes in the
Cluster

8-30

8-9

Using a $GETJPI 8uffer to Improve Performance

8-32

8-10

Using $GETJPI Control Flags to Avoid Swapping a Process
into the 8alance Set

8-35

C-1

Tagging a File

C-10

C-2

Accessi ng a Tagged File

C-13

8-4
8-5

FIGURES
2-1

VAX 6000-400 Series Vector-Present Processor
Configuration

2-3

2-2

VAX 9000 Series Vector-Present Processor Configuration

2-4

2-3

Life of a Vector Consumer

2-6

3-1

Sample Debit/Credit Transaction Execution

3-3

3-2

Participants in a Distributed Transaction Example

3-5

7-1

DECwindows Screen Number Dialog 80x

7-2

DECwindows Screen Number Dialog 80x

7-2

12-1

SCSLNOAUTO System Parameter

12-1

15-1

Sample Transaction Log File Configuration on Two-Node
VAXcluster

15-6

16-1

TRANSACTION Class Record Format

16-5

16-2

VECTOR Class Record Format

16-9

22-1

Transaction Processing Components

22-3

27-1

VAX 9000 System Architecture

27-2

VAX 9000 XMI Address Space

27-3

SCUIXMI Systems 1/0 Address Space

27-4

SCU 8us Address Allocation

27-5

XJA Private Space Address Allocation

27-6

SCU/XMI Systems Address 8it Structure

27-7

A-1

A DNS Namespace

A-6

A-2

Valid Character Codes for DNS Simple Names

A-9

A-3

Additional Character Codes Allowed in Quoted Simple
Names

A-9

A Partitioned Namespace

A-15

A-4

xxi

Contents

A-5

A Namespace with Replicated Directories

A-16

TABLES
1-1

Summary of VMS Version 5.4 Software Features

1-1

2-1

Settings of VECTOR_PROC System Parameter

2-8

2-2

System Messages Relating to Vector Processing

2-16

2-3

Summary of Exception Conditions

2-29

4-1

Summary of New and Enhanced DCl Commands

4-1
4-3

4-2

Summary of New and Enhanced lexical Functions

5-1

EVE Box Editing Commands

5-1

14-1

Arguments to the /ALGORITHM Qualifier

14-4

16-1

Descriptions of TRANSACTION Class Record Fields

16-6

16-2

Descriptions of VECTOR Class Record Fields

16-10

16-3

Descriptions of Additions to System Record Fields

16-10

21-1

Mail Utility Routines

21-1

22-1

New VMS Version 5.4 System Services

22-1

22-2

$ABORT_TRANS Operation Flag

22-12

22-3

$END_TRANS Operation Flag

22-17

22-4

$START_TRANS Operation Flags

22-49

22-5

legal QUECVT Conversions

22-55

22-6

Values Returned by the OEVClASS Item

22-55

22-7

Attributes of an Identifier

22-56

31-1

Display PostScript Documentation

31-5

A-1

DNS Item Code Arguments

A-43

B-1

UAF Process Quotas for the BACKUP Account

B-6

B-2

Suggested Values for UAF Process Quotas

B-7

B-3

Process Identification

B-17

C-1

Tag Support Item Codes

C-8

C)
0

o
xxii

o
Preface
Intended Audience
This book is intended for general users, system managers, and
programmers who use the VMS operating system.

Structure of This Document
This manual is organized as follows:

•

Part 1, Overview of Major New Features, contains a complete
summary of the new VMS Version 5.4 software features. Part 1 also
includes separate chapters describing the following major, systemwide
enhancements to the VMS operating system:
•

Vector processing support

•

DECdtm services

Note: It is important that you read Part 1 first for a complete
overview of the VMS Version 5.4 new features and for a
complete description of VMS support for vector processing
and DECdtm services. In addition to providing essential
information, Part 1 (particularly the vector processing and
DECdtm chapters) also directs you to relevant material located
elsewhere within this manual and others.
•

Part 2, General User Features, describes new features primarily of
interest to general users of the VMS operating system. The chapters
within provide information about the following:
DCL commands and lexical functions

EVE editor
System messages
DECwindows user and desktop applications
•

Part 3, System Management Features, describes new features
primarily of interest to system managers. The chapters within provide
information about the following components of the VMS operating
system:
AUTOGEN
UETP
SYSMAN Utility
VAXcluster management

System Generation Utility (SYSGEN)
Error Log Utility (ERROR LOG)
System security

xxiii

Preface

Log Manager Control Program Utility (LMCP)

Monitor Utility (MONITOR)
Network Control Program Utility (NCP)
VMS Volume Shadowing Phase II
•

Part 4, Programming Features, describes new features primarily of
interest to programmers. The chapters within provide information
about the following components of the VMS operating system:
VMS Debugger
Linker Utility (LINK)
Mail Utility routines
System Services
Run-Time Library Routines
Record Management Services (RMS)
I/O Driver support
System Dump Analyzer (SDA)
Device Support
VAX Text Processing Utility (VAXTPU)
VAX RMS Journaling
VMSINSTAL
Compound Document Architecture (CDA) support
VMS DECwindows Display PostScript system
XUI Toolkit

The VMS Version 5.4 New Features Manual also has three appendixes
documenting features that were new to Versions 5.3, 5.2, and 5.1 of
the VMS operating system but are not yet documented in other printed
manuals.

(\
~~....:)

Associated Documents
Refer to the following documents for more detailed information about
the VMS Version 5.4 software features described in this manual. For
more information about these documents, see the Overview of VMS
Documentation or contact your Digital representative.

xxiv

•

VMS Version 5.4 Release Notes

•

VMS DeL Dictionary

•

VMS EVE Reference Manual

•

VMS System Messages and Recovery Procedures Reference Manual:
Part I

O·

Preface

•

VMS System Messages and Recovery Procedures Reference Manual:
Part II

•

VMS SYSMAN Utility Manual

•

VMS Volume Shadowing Manual

•

VMS VAXcluster Manual

•

VMS Debugger Manual

•

Introduction to VMS System Routines

•

VMS Utility Routines Manual

•

VMS RTL Mathematics (MTH$) Manual

•

VMS RTL Parallel Processing (PPL$) Manual

•

VAX MACRO and Instruction Set Reference Manual

•

VAX RMS Journaling Manual

•

VMS Developer's Guide to VMSINSTAL

•

VMS I/O User's Reference Manual: Part I

•

VAX Text Processing Utility Manual

•

VMS Device Support Manual

•

CDA Reference Manual

•

Introduction to the CDA Services

•

Guide to Creating Compound Documents with the CDA Toolkit

•

VMS DECwindows Toolkit Routines Reference Manual

•

VMS DECwindows Display PostScript System Programming
Supplement

The following manuals are published by Adobe Systems Incorporated but
are available through Digital. See Section 31.3 of this manual for more
information.

•

Display PostScript System Perspective for Software Developers

•

Display PostScript System pswrap Reference Manual

•

PostScript Language Extensions for the Display PostScript System

•

PostScript Language Color Extensions

•

Display PostScript System Client Library Reference Manual

•

PostScript Document Structuring Conventions Specification

o
xxv

Preface

o
Conventions
The following conventions are used in this manual:
mouse

The term mouse is used to refer to any pointing
device, such as a mouse, a puck, or a stylus.

MB1, MB2, MB3

MB1 indicates the left mouse button, MB2 indicates
the middle mouse button, and MB3 indicates the right
mouse button. (The buttons can be redefined by the
user.)

PB1, PB2, PB3, PB4

PB1, PB2, PB3, and PB4 indicate buttons on the
puck.

SB1, SB2

SB1 and SB2 indicate buttons on the stylus.

Ctrl/x

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

PF1 x

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

xxvi

()

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

[]

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

{}

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

Preface

red ink

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

boldface text

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

italic text

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

UPPERCASE TEXT

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

numbers

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

C;I

o
xxvii

c
Part 1: Overview of Major New Features
This part contains the following chapters:
Chapter 1, Summary of New VMS Version 5.4 Software Features
Chapter 2, Introduction to Vector Processing
Chapter 3, Introduction to DECdtm Services

C/
./

o
c

In addition to providing essential information about VMS Version 5.4 software
features, the chapters in Part 1 also direct you to relevant material located
elsewhere within this manual and others.

o
1

Summary of New VMS Version 5.4 Software Features

This chapter provides a summary (in Table 1-1) of the new VMS Version
5.4 software features described throughout this manual and in the other
new and revised manuals associated with this release (see the Preface for
a complete list).

For information about new and enhanced hardware, see the VMS Version
5.4 Release Notes.
Table 1-1

Summary of VMS Version 5.4 Software Features
VMS Version 5.4 Systemwide Features

Vector processing

Systemwide support for vector processing on VAX 9000 series and VAX
6000-400 series computers includes the VAX Vector Instruction Emulation
Facility (VVIEF), specific Del commands and lexical functions, and the
Accounting, Error Log, Monitor, SDA, Debugger, Patch, and RTl MTH$
facilities. See Chapter 2 for a complete description of vector processing
support.

DECdtm services

Systemwide support for DECdtm services includes the new log Manager
Control Program Utility (lMCP), new MONITOR TRANSACTION
command, new and modified system services, new TRANSACT'ON_'D
data type, and enhanced VAX RMS Journaling support. See Chapter 3
for a complete description of DECdtm services.
VMS Version 5.4 General User Features

DCl commands

New and enhanced DCL commands let you control date compaction
on the TA90E tape drive, convert procedures written in PostScript to
callable routines, compile fonts for the DECwindows server, use new
keywords and qualifiers with SET ACL and SHOW ACL, use expanded
SET HOST/DTE functions and subcommands, use symbol scoping, set
characteristics for the VT400 family of terminals, and control and monitor
specific processors and VAXft 3000 systems.

DCL lexical functions

New and enhanced functions return information about cluster
identification numbers, device names, account status, verb scoping
state, volume shadowing status, vector processing, active and recognized
CPUs in an SMP system, and symbol creation (by other lexical functions).

EVE text editor

Enhancements include box editing, replacement of tab characters with
spaces, and new qualifiers that let you edit large files and specify either
the character-cell or DECwindows interface.

System Messages

New or modified messages are now available within specific VMS
facilities and online Help.

(continued on next page)

1-1

Summary of New VMS Version 5.4 Software Features

o
Table 1-1 (Cont.)

Summary of VMS Version 5.4 Software Features
VMS Version 5.4 General User Features

DECwindows User

You can now set another session language or change the target
screen on the Session Manager, view PostScript files with the CDA
Viewer, change to hexadecimal or octal mode in Calculator, use new
File, Customize, and Help menus for interacting with Clock, and use
DECwindows Mail to display PostScript files,
VMS Version 5.4 System Management Features

AUTOGEN

This command procedure now includes support for parameter name
validation, SYS$SYSTEM:AGEN$PARAMS,REPORT (a new file that
replaces AGEN$FEEDBACK,REPORT), reading external parameter
files, controlling the size of page and swap files, new feedback
parameters, new defined process logical names, a new technique for
running AUTOGEN in batch mode, and the ability to use MAil to send
AGEN$PARAMS,REPORT.

UETP

Enhancements to the User Environment Test Package include loading
and testing of all installed and enabled vector processors, testing of the
VAX Vector Instruction Emulation Facility (VVIEF), and support for the
RRD40 compact disc drive, including SCSI disk configurations,

SYSMAN Utility

Enhancements let you run a SYSMAN command procedure, define keys,
spawn a subprocess, use DCl verification, and use loadable image
commands,

VAXcluster software

Enhancements include CI architecture extensions that allow multiple CI
interfaces per CPU and multiple star couplers per VAXcluster system;
MSCP server load sharing; and preferred path support for DSA disks
(including RA series disks and disks accessed through the MSCP
server),

SYSGEN Utility

Enhancements include a new parameter for MicroVAX and VAXstation
configurations that include third-party Small Computer System Interface
(SCSI) devices, new parameters that support site-specific password
policies, and new SHOW commands that display information such as bus
identification statistics, device addresses mapped in the 110 space for the
VAXBI bus, and device addresses mapped in the 110 space for the XMI
bus,

Error log Utility

Enhancements include support for VAXft 3000 device types, new deviceclass and entry-type keywords (to support vector processing and VAX
9000 systems) used with the IEXClUDE and IINClUDE qualifiers, and
support for the new INODE qualifier, which lets you produce a report of
error log entries for specific nodes in a VAXcluster,

System Security

System security enhancements enable you to implement a site-defined
password policy by screening new passwords and specifying password
algorithms, This support includes enhancements to DCl commands,
the SYSGEN Utility, the SYSMAN Utility, and system services, See
Chapter 14 for more information,

o
()

(continued on next page)

o
1-2

Summary of New VMS Version 5.4 Software Features

o
Table 1-1 (Cant.)

Summary of VMS Version 5.4 Software Features
VMS Version 5.4 System Management Features

LMCP Utility

The new Log Manager Control Program Utility (LMCP) lets the system
manager create and manage transaction log files in a DECdtm services
environment. See Chapter 15 for a complete description of this new
utility.

Monitor Utility

Enhancements include support for vector processing with the new
MONITOR VECTOR command and VECTOR class, and support for
DECdtm services with the new MONITOR TRANSACTION command and
TRANSACTION class.

NCP Utility

The Network Control Program Utility now includes support for a new line
and circuit name specific to the VAXft 3000 system.

VMS Volume Shadowing

VMS Volume Shadowing phase II includes support for distributed,
clusterwide shadowing of all MSCP-compliant DSA disks (with the same
number of logical blocks) and shadowing of all DSA devices.
VMS Version 5.4 Programming Features

VMS Debugger

Enhancements to the debugger's command and DECwindows interfaces
let you debug programs containing VAX vector instructions.

Linker Utility

A new command line qualifier, IBPAGE, lets you specify larger page
sizes.

Mail Utility routines

New callable mail routines let you create applications that can perform
a variety of Mail Utility functions and communicate with users on remote
nodes connected to the system with DECnet-VAX.

System Services

New and enhanced system services support DECdtm services, system
security enhancements, vector processing, volume shadowing, volume
initialization, and the procedure for creating site-specific loadable images.

Run-Time Library

New parallel processing (PPL$) routines let you inform the PPL$ facility
when a new caller is forming or joining a parallel application, implement
work queues, delete a PPL$ application or object, set and adjust a
semaphore maximum, disable event notification, or read a spin lock state.

New and enhanced mathematics routines (MTH$) let you manipulate and
perform operations on vectors.
RMS

Enhancements provide asynchronous support for process-permanent
files, an increase in the local buffer maximum, access-mode protection
for RMS services and for specific data structures and their associated 1/0
buffers, and the ability for all applications to selectively suppress updates
to the Expiration Date and Time, using XAB$_NORECORD XABITM.

110 Drivers

Enhancements include support for the Pseudoterminal driver (FTDRIVER)
and Shadow Set Virtual Driver (SHDRIVER), modifications to the itemlist
read function of the 1/0 status block (IOS8) and to the itemlist terminal
driver read verify operations for the TRIM$_MODIFIERS item code, and
the addition of three new ACP-QIO functions.
(continued on next page)

o
1-3

Summary of New VMS Version 5.4 Software Features

o
Table 1-1 (Cont.)

Summary of VMS Version 5.4 Software Features
VMS Version 5.4 Programming Features

System Dump Analyzer

New qualifiers to the SHOW PROCESS command let you display
statistics about an image (/IMAGE) or about the values of the registers
from the process's vector context area (/VECTOR_REGISTERS).

Device Support

Enhanced support includes VAX 9000 and VAX 6000 series systems.
Programmers can write and debug driver software for non-Digital-supplied
devices attached to a VAX 9000 system.

VAXTPU

Enhancements include work file support, a qualifier you can use to
specify either character-cell or DECwindows interface, and new built-in
procedures, including GET_INFO, that support journal recovery, pop-up
menus, column context values for a buffer, markers within a buffer, and
scrolling.

RMS Journaling

Enhancements support DECdtm services as well as existing applications
and affect the Recovery Unit Facility (RUF), network support of remote
files, RMS record streams, the RMS Detached Recovery server,
placement of recovery unit journals, and access of files in a mixed-version
cluster.

VMSINSTAL

A new data-file parameter (P4) in the Software Product Kit Building
Procedure (SPKITBLD.COM) lets you specify the name of a data file.
New callbacks affect messages displayed-and booting procedures
required-during product installations, and how you obtain a systemgenerated or installer-specified password.

DECwindows Programming

Enhancements include new programming examples in the
DECW$EXAMPLES directory, new support for the XUI Toolkit color
mixing widget (both the Hue Lightness Saturation and Red, Green, Blue
color models), support for the Display PostScript system (which provides
text and image display capability for bitmapped workstations), and CDA
Viewer support for PostScript files, Adobe Font metrics, and DECmath
fonts.

o
o

o
1-4

Introduction to Vector Processing

The VMS Version 5.4 operating system supports vector processing on
VAX 9000 series and VAX 6000-400 series computers. This chapter
describes how vector processing works, how to manage resources, and how
to write programs within a vector processing environment. The following
sources in this manual and in other documents also describe aspects of
VMS Version 5.4 vector processing support:

c
2.1

•

Chapter 9 (of this manual) and the VMS Version 5.4 Upgrade and
Installation Manual describe modifications to UETP.

•

Chapter 4 (of this manual) and the VMS DeL Dictionary describe new
and modified DCL commands, qualifiers, and lexical functions.

•

Chapter 19 (of this manual) and the VMS Debugger Manual describe
how to debug vectorized programs.

•

Chapter 22 describes new and modified system services.

•

The VMS RTL Mathematics (MTH$) Manual describes new and
modified RTL mathematics routines.

Overview of the Vector Processing Environment
A single data item having one value is known as a scalar. A group of
related scalar values, or elements, all of the same data type is known as a
vector.

Traditional scalar computers operate only on scalar values and must
process vector elements sequentially. Vector computers, on the other hand,
recognize vectors as native data structures and can operate on an entire
vector with a single vector instruction.
A vector processor can routinely process a vector four to five times faster
than a traditional computer using only scalar instructions can. Vector
processors gain this speed advantage over scalar processors by their
use of special hardware techniques designed for the fast processing of
streams of data. These techniques include data pipelining, chaining,
and other forms of hardware parallelism in memory and in arithmetic
and logical functional units. Pipelined functional units allow the vector
processor to overlap the execution of successive computations with
previous computations. Chaining allows the results of one instruction
to be forwarded to another before the first instruction has been completely
processed.

o
2-1

Introduction to Vector Processing
2.1 Overview of the Vector Processing Environment

2.1.1

VAX Vector Processing Systems
An extension to the VAX architecture defines an optional design for
integrated vector processing that has been adopted by several VAX
processing systems. The VAX vector architecture includes 16 64-bit vector
registers (VO through VI5), each containing 64 elements; vector control
registers, including the vector count register (VCR), vector length register
(VLR), and vector mask register (VMR); vector functional units; and a set
of vector instructions. VAX vector instructions transfer data between the
vector registers and memory, perform integer and floating-point arithmetic,
and execute processor control functions. A more detailed description of the
VAX vector architecture, vector registers, and vector instructions appears
in the VAX MACRO and Instruction Set Reference Manual.
Those VAX systems that comply with the VAX vector architecture are
known as vector-capable systems.
A VAX vector processing system configuration includes one or more
integrated scalar-vector processor pairs, or vector-present processors.
Such a configuration can either be symmetric, including a vector
coprocessor for each scalar, or asymmetric, incorporating additional scalaronly processors. Depending on the model of the VAX vector processing
system, the scalar and vector CPUs of vector-present processors can
be either a single, integral physical module or separate, physicallyindependent modules. In either case the scalar and vector CPUs are
logically integrated, sharing the same memory and transferring data over
a dedicated, high-speed internal path. Because the CPU s are thus tightlycoupled, use of the vector CPU foregoes the expense of I/O operations.
The scalar and vector CPUs operate asynchronously with respect to each
other. The scalar CPU fetches and decodes all instructions issued by the
current image and executes all scalar instructions. When it encounters a
vector instruction, the scalar CPU passes it to the vector CPU. While the
vector CPU is executing this instruction, the scalar CPU continues to fetch
and decode instructions, executing any scalar instruction it encounters
and sending any vector instructions it encounters to the vector CPU.
The vector processor maintains a queue of pending instructions in which
it places instructions it receives while it is busy. The VMS operating
system and its vectorizing compilers help ensure that the activities of both
scalar and vector CPU s are synchronized. (Section 2.3.7 describes those
situations in which vectorized VAX MACRO programs must enforce scalar
and vector CPU synchronization.)

(--"'\

~ -)
..

o
()

Certain VAX system models offer a vector processing option. In
VAX 6000-400 series systems, the vector CPU occupies a slot on the
memory interconnect; the scalar-vector interconnect joins it to the scalar
CPU, which resides in an adjacent slot (see Figure 2-1). In VAX. 9000
series systems, the vector processor is an integral part of the CPU, as
shown in Figure 2-2.

o
2-2

Introduction to Vector Processing

2.1 Overview of the Vector Processing Environment

Figure 2-1

VAX 6000-400 Series Vector-Present Processor
Configuration

XMI

Scalar
CPU

VAXBI Bus
Adapter

Memory
Controller

o
ZK-1945A-G E

Like VAX scalar processing systems, a VAX vector processing system can
participate as a member of a VAXcluster or as a node in a network, or it
can be run as a standalone system.

2.1.2

Vectorized Programs
The benefits of vectorization depend, to a large degree, on the specific
techniques and algorithms of an application. CPU-intensive applications
involving repeated operations on groups of simple elements are well-suited
to vectorization. VAX vector processing systems are particularly beneficial
in the fields of seismic analysis, weather forecasting, molecular modeling,
computational fluid dynamics, signal processing, financial modeling, and
finite element analysis.

2-3

Introduction to Vector Processing
2.1 Overview of the Vector Processing Environment

Figure 2-2

VAX 9000 Series Vector-Present Processor Configuration

Scalar

CPU

CPU
Vector

..
CPU

Memory

.. .. Vector

System Control Unit

I/O Control Unit

ZK-1944A-GE

There are several methods you can use to produce a vectorized program in
a VMS system.
Most applications that benefit from vector processing can be developed
as scalar programs in a high-level language and then submitted to a
vectorizing compiler for that language. A vectorizing compiler, such
as the VAX Fortran High Performance Option (HPO), can recognize
sections of code within a program, usually inside formal loops, that can
be vectorized. It analyzes data dependences, identifies other inhibitors to
vector processing, and restructures code sequences to allow the compiler to
generate optimized VAX vector instruction sequences.

~
(,-)

Additionally, applications can be vectorized by a call to the vectorized
routines in the VMS Run-Time Library mathematics facility (RTL MTH$)
or to the vectorized routines within the optional DIGITAL Extended Math
Library (DXML):
•

2-4

The vectorized RTL MTH$ routines that can be called by a highlevel language application include the Level 1 Basic Linear Algebra
Subroutines (BLAS) and First-Order Linear Recurrence (FOLR)
routines. In addition, VAX vectorizing compilers (and programs
written in VAX MACRO) can generate calls to vectorized versions
of the standard scalar RTL MTH$ routines. (The vectorized RTL
MTH$ routines are introduced in Section 2.3.1 and fully discussed in
the VMS RTL Mathematics (MTH$) Manual.)

Introduction to Vector Processing

2.1 Overview of the Vector Processing Environment

•

The DIGITAL Extended Math Library (DXML) is an optional software
product that provides additional vectorized mathematics routines such
as BLAS Level I-extended, 2, and 3, plus signal processing routines.

Finally, those programs that require strict control over the VAX vector
hardware can be written in VAX MACRO and use the VAX vector
instructions directly.
The terms vectorized program, vectorized application, and
vectorized image all refer to programs produced by a vectorizing
compiler, programs that call one or more vectorized routines, and programs
written in VAX MACRO that issue VAX vector instructions. A vectorized
image from any of these categories eventually results in the execution of
one or more vector instructions that transform its process into a vector
consumer.

See Section 2.3 for an overview of the VMS vector processing programming
environment.

2.1.3

VMS Support for Vector Processing
The VMS operating system provides fully-shared, multiprogramming
support for VAX vector processing systems. By default, VMS loads vector
processing support code when initializing a VAX system that includes
vector-present processors but does not load it when initializing vectorabsent systems. (A system manager can control this behavior by using the
SYSGEN parameter VECTOR_PROC, as described in Section 2.2.1.) The
presence of vector support code in a system has little effect on processes
running in a scalar-only system or on scalar processes running in a vectorpresent system. If many processes must simultaneously compete for
vector processor resources in a system, the system manager can maintain
good performance by adjusting system resources and process quotas as
indicated in Section 2.2.3.1.

c
o

The VMS operating system makes the services of the vector processor
available to system users by means of a software abstract known as a
capability. A system manager can restrict the use of the vector processor
to users holding a particular identifier by associating an access control list
(ACL) with the vector capability object. (See Section 2.2.4 for additional
information. )
2.1.3.1

Life of a Vector Consumer
As shown in Figure 2-3, a process begins execution as a scalar
consumer, partaking of the resources of a scalar processor or the scalar
component of a vector-present processor.

When the image executing within the process's context issues its first
vector instruction, VMS marks the process as requiring the system's vector
capability. It also allocates sufficient system nonpaged dynamic memory
in which to store this process's vector context. The vector context of a
process consists of the contents of the vector registers VO through V15, the
contents of the vector control registers (VCR, VLR, and VMR), the vector
processor status, and the vector exception state.

2-5

Introduction to Vector Processing

2.1 Overview of the Vector Processing Environment

Figure 2-3

Life of a Vector Consumer

can be scheduled on
scalar processor or
scalar/vector processor pair

requires system vector
capability, must be scheduled
on scalarlvector processor pair

image activation
issues vector :
instruction :

CJ
ZK-1943A-GE

A process requiring the vector capability and having a vector context is
known as a vector consumer. VMS must schedule a vector consumer
on a vector-present processor. As long as it remains a vector consumer, a
process is effectively prohibited from executing on any scalar processor in
the system.

C..)
...-/

However, over the course of its execution, a typical vectorized image
issues sequences of scalar instructions intermixed with sequences of vector
instructions. For those periods in which it performs scalar operations
exclusively, a process can relinquish its need for the vector capability
and become eligible for execution on any processor in the system. VMS
preserves the vector context of any such marginal vector consumer in
the expectation that it will eventually issue another vector instruction and
again become a vector consumer.
In a system in which many vector consumers are competing for the vector
processor, the dynamic transition of vector consumers to marginal vector
consumers (and back again) allows VMS to more efficiently distribute
vector processor resources and enhances the performance of vectorized
applications. Note that a system manager can control the transition of a
vector consumer to a marginal vector consumer by setting the SYSGEN
parameter VECTOR_MARGIN (as discussed in Section 2.2.3.2).
Ultimately, a vector consumer or marginal vector consumer reverts to
being a scalar consumer when the vectorized image it is executing exits.

2-6

Introduction to Vector Processing
2.1 Overview of the Vector Processing Environment

In the course of system activity, another process could preempt the
execution of a vector consumer on a vector-present processor. When
this occurs, VMS immediately saves the vector consumer's scalar context,
as it does for traditional scalar processes. However, VMS allows its vector
context to remain intact in the vector CPU. Depending upon the nature of
the intervening processes scheduled on that processor, VMS, in most cases,
tries to reschedule a vector consumer on the vector-present processor on
which it was last scheduled.
Because scalar consumers and marginal vector consumers do not use the
vector CPU, they do not disturb the vector context of the latest vector
consumer on the vector-present processor on which they are scheduled.
If only processes of these types were scheduled on the vector-present
processor since the vector consumer last ran, the vector consumer can
resume execution on that processor without the overhead associated with
a restoration of its vector context from memory. This is known as "fast"
vector context switch.

Other vector consumers, however, do use the vector CPU. When placing a
vector consumer into execution on a vector-present processor, VMS stores
in memory the vector context of the processor's latest vector consumer.
When it later reschedules this vector consumer, VMS can place it into
execution on any vector-present processor in the system, but it must
restore its vector context from memory. This is known as "slow" vector
context switch.

o
o

Slow vector processing context switches are most likely when there are
more vector consumers than vector-present processors in the systems. A
system manager can adjust system parameters (including the VECTOR_
MARGIN parameter) and system resources to help reduce the number of
slow vector context switches as described in Section 2.2.
2.1.3.2

VAX Vector Instruction Emulation Facility (VVIEF)
The VAX Vector Instruction Emulation Facility (VVIEF) is a standard
feature of the VMS operating system that allows vectorized applications to
be written and debugged on a VAX system in which vector processors are
not available. VVIEF emulates the VAX vector processing environment,
including the nonprivileged VAX vector instructions and the VMS vector
system services (described in Sections 2.3.2, 2.3.3, and 2.3.4). Use of
VVIEF is restricted to user mode code.

VVIEF is strictly a program development tool and not a run-time
replacement for vector hardware. There is no performance benefit from
vectorizing applications to run under VVIEF; vectorized applications
running under VVIEF typically execute five times slower than their scalar
counterparts.

VMS supplies the VVIEF bootstrap code as an executive loadable
image. The system manager invokes· the command procedure
SYS$UPDATE:VVIEF$INSTAL.COM to cause VMS to load VVIEF at
the neY.it system boot and each successive system boot. Note that, in the
presence of VMS vector support code, VVIEF remains inactive. Although it
is possible to prevent the loading of VMS vector support code in a vectorpresent system (see Section 2.2.1) and activate VVIEF, there are few
benefits. Should the only scalar-vector processor pair in the system fail,
2-7

Introduction to Vector Processing
2.1 Overview of the Vector Processing Environment

the execution of preempted vectorized applications will not be resumed
under the emulator.
See Section 2.2.6 for additional information on loading and unloading
VVIEF.

2.2

Managing the Vector Processing Environment
Managing a VAX vector processing system includes the following tasks:
•

Loading the VMS vector processing support code

•

Configuring a vector processing system

•

Managing processes requiring the system's vector processing resources

•

Obtaining information about the status and use of the system's vector
processing resources

•

Loading the VAX vector emulation facility (VVIEF) bootstrap code

This section describes the features VMS has introduced or enhanced to
facilitate the accomplishment of these tasks. It concludes with a list of
messages VMS uses to report information about the condition of the vector
processing system.

2.2.1

Loading the VMS Vector Processing Support Code

()

By default, in a VAX vector processing system, VMS automatically loads
the vector processing support code at boot time. You can override the
default behavior by setting the static system parameter VECTOR_PROC
as described in Table 2-1.
Table 2-1

Settings of VECTOR_PROC System Parameter

Value

Result

Do not load the vector processing support code, regardless of the system
configuration.

Load the vector processing support code if there is at least one vectorpresent processor. This is the default value.
2

2.2.2

Load the vector processing support code if the system is vector capable.
This setting is most useful for a system in which processors have separate
power supplies. With this setting, you can reconfigure a vector processor
into the system without rebooting the VMS operating system.

Configuring a VMS Vector Processing System
You can add or remove a vector-present processor to or from a VMS
multiprocessing configuration at boot time by using the SYSGEN
parameter SMP_CPUS or at run time by using the DCL commands START
/CPU and STOP/CPU. Note that VMS treats the scalar and vector C P U - .
components of a vector-present processor as a single processor, starting
them and stopping them together.

2-8

Introduction to Vector Processing
2.2 Managing the Vector Processing Environment

At boot time, the setting of the SYSGEN parameter SMP_CPUS identifies
which secondary processors in a VMS multiprocessing system are to be
configured, including those processors that are vector present. (VMS
always configures the primary processor.) The default value of-1
boots all available processors, scalar and vector-present alike, into the
configuration. (See the VMS System Generation Utility Manual for
additional information on this parameter.) Note that, prior to starting a
vector-present processor, you should make sure that the vector processing
support code (see Section 2.2.1) is loaded at boot time. Otherwise,
processes will only be able to use the scalar CPU component of the
vector-present processor.
To bring secondary processors into a running VMS multiprocessing system,
you use the DCL command START/CPU. To remove secondary processors
from the system, use the STOP/CPU commands. Again, you must make
sure that the vector processing support code has been loaded at boot time
for the vector CPU component of vector-present processors started in this
way to be utilized.

However, note that if you enter a STOP/CPU command that would cause
the removal of a vector-present processor that is the sole provider of the
vector capability for currently active vector consumers, the command
fails and generates a message. In extreme cases, such as the removal
of a processor for repair, you can override this behavior by entering the
command STOP/CPU/OVERRIDE. This command stops the processor,
despite stranding processes.

When a STOP/CPU/OVERRIDE command is entered for a vector-present
processor, or when a vector-present processor fails, VMS puts all stranded
vector consumers into a CPU-capability-wait (RSN$_CPUCAP) state until
a vector-present processor is returned to the configuration. To any other
process that subsequently issues a vector instruction (including a marginal
vector consumer), VMS returns a "requested CPU not active" message
(CPUNOTACT).

See the VMS DeL Dictionary for additional information on the
START/CPU and STOP/CPU commands.

2.2.3

Managing Vector Processes
As described in Section 2.1.3, VMS scheduling algorithms automatically
distribute vector and scalar processing resources among vector consumers,
marginal vector consumers, and scalar consumers. However, VAX vector
processing configurations vary in two important ways:
•

The amount of vector processing activity the configuration must
accommodate

•

The number of vector-present processors available in the configuration
to service vector processing needs

o
2-9

Introduction to Vector Processing
2.2 Managing the Vector Processing Environment

In a configuration in which there are more vector consumers in a system
than there are scalar-vector processor pairs to service them, vector
consumers share vector-present processors according to process priority.
At a given priority, VMS schedules vector consumers on a vector-present
processor in a round-robin fashion. Each time VMS must schedule a new
vector consumer on a vector-present processor, it must save the vector
context of the current vector consumer in memory and restore the vector
context of the new vector consumer from memory. When such "slow"
vector context switches occur too frequently, a significant portion of the
processing time is spent on vector context switches relative to actual
computation.
Systems that have heavy vector processing needs should be adequately
configured to accommodate those needs. There are, however, some
mechanisms a system manager can use to tune the performance of an
existing configuration.
2.2.3.1

Adjusting System Resources and Process Quotas

Systems in which several vector consumers are active simultaneously
might experience increased paging activity as processes share the available
memory. To reduce process paging, you might need to use the Authorize
Utility to adjust the working set limits and quotas of the processes running
vectorized applications. An increase of the process maximum working set
size (SYSGEN parameter WSMAX) might also be necessary. Additionally,
a vectorized application can use the Lock Pages in Working Set system
service (SYS$LKWSET) to enhance its own performance.
VMS allots to each vector consumer 8 kilobytes of system nonpaged
dynamic memory in which VMS stores vector context information.
Depending on how many vector consumers are active in the system
simultaneously, you might need to adjust the SYSGEN parameter
NPAGEDYN. To determine the current usage of nonpaged pool, use the
DCL command SHOW MEMORY/POOLIFULL, which displays the current
size of nonpaged pool in bytes.
See the VMS System Generation Utility Manual and the VMS Authorize
Utility Manual for additional information on these mechanisms.

0-\..
... .

To obtain optimal performance of a VAX vector processing system, you
should take some care to set up generic batch queues that avoid saturating
the system's vector resources. If a queue contains more active vectorized
batch jobs than there are vector-present processors in the system, a
significant portion of the processing time will be spent on vector context
switches.
The recommended means for dispatching vectorized batch jobs to a VAX
vector processing system is to set up a separate queue (for instance,
VECTOR_BATCH) with a job limit equal to the number of vector-present
processors in the system. When submitting vectorized batch jobs, users
should be encouraged to submit them to this generic vector processing
batch queue.

2-10

Introduction to Vector Processing
2.2 Managing the Vector Processing Environment

o
2.2.3.2

Distributing Scalar and Vector Resources Among Processes
As a vector consumer, a process must be scheduled only on a vectorpresent processor. If the image the process is executing issues only scalar
instructions for a period of time and must share the scalar-vector processor
pair with other vector consumers, its inability to run on an available scalar
processor could hamper its performance and the overall performance of the
system.
By default, VMS assumes that, if a vector consumer has not issued a
vector instruction for a certain period of time, it is unlikely that it will
issue a vector instruction in the near future. VMS relinquishes this
process's need for the vector capability, classifying it as a marginal vector
consumer.

In an asymmetric vector processing configuration, detection of marginal
vector consumers achieves the following desirable effects:

•

Because a marginal vector consumer is eligible to run on a larger set
of processors, its response time will improve.

•

The scheduling of marginal vector consumers on scalar processors
reduces the contention for vector-present processors.

•

Because vector consumers issuing vector instructions are more likely
the be scheduled on vector-present processors, the vector CPU is more
efficiently used.

A system manager uses the SYSGEN parameter VECTOR_MARGIN to
establish the interval of time at which VMS checks the status of all vector
consumers. The VECTOR_MARGIN parameter accepts an integer value
between 1 and -1 (FFFFFFFF16). This value represents a number of
consecutive process quanta (as determined by the SYSGEN parameter
QUANTUM). If the process has not issued any vector instructions in the
specified number of quanta, VMS declares it a marginal vector consumer.
A value of -1 disables the checking mechanism.

The default value of the VECTOR_MARGIN parameter is 10010.

2.2.4

Restricting Access to the Vector Processor by Using ACLs
Using the SET ACL and SHOW ACL commands, a system manager
can restrict the use of the vector processor to users holding a particular
identifier. By associating an access control list (ACL) with the vector
capability, a university might limit use of the vector processor to faculty
and students in an image processing course, or a service bureau might
charge users for access to the vector capability, time spent on the vector
processor, or both.

When using either the SET ACL or SHOW ACL command with Version
5.4 of the VMS operating system, the system manager can specify a
new object type, CAPABILITY, as the argument to the /OBJECT_TYPE
qualifier. This object type is a system capability, such as the ability to
process VAX vector instructions. Currently, the only defined object name
for the CAPABILITY object type is VECTOR. Therefore, when using the
SHOW ACL or SET ACL command, the system manager must supply

2-11

Introduction to Vector Processing
2.2 Managing the Vector Processing Environment

the capability name (VECTOR) as the argument to the object type, as in
the following examples. (For additional information on the SET ACL and
SHOW ACL commands, see the VMS DCL Dictionary.)
The following DCL command establishes one or more access control entries
(ACEs) on the vector capability.
$

SET ACL/OBJECT=CAPABILITY VECTOR/ACL[=(ace[, ... J) J

Note that you must be in the SYSTEM user category (as described in VMS
DCL Concepts Manual) to set an ACL on the vector capability.
The following DCL command displays the ACL on the vector capability.
$

SHOW ACL/OBJECT=CAPABILITY VECTOR

Note that the ACL is on the vector capability, not on the use of any or all
vector-present processors in the system. For this reason, VMS can still
schedule processes without permission to use the vector capability on a
vector-present processor. However, these processes can use only the scalar
CPU component of the processor and cannot execute vector instructions.
Likewise, because the ACL is on the vector capability and not on a vectorpresent processor, you cannot establish an ACL to force long-running jobs
to a specific processor.
The Change ACL ($CHANGE_ACL) and Check Access ($CHECIC
ACCESS) system services provide means for setting and removing ACLs
on the VECTOR capability and for checking a process's ability to use
vector processing resources. See Section 22.5 for additional information.

2.2.5

Obtaining Information About a Vector Processing System
You can obtain information about the status of the vector processing
system and the use of the system by individual processes through various
means, including:
•

The DCL lexical functions F$GETJPI and F$GETSYI

•

The DCL command SHOW CPU

•

The DCL commands SHOW PROCESS and LOGOUTIFULL

•

The Accounting Utility (ACCOUNTING)

•

The Error Log Utility (ERROR LOG)

•

The Monitor Utility (MONITOR)

o
2-12

Introduction to Vector Processing

2.2 Managing the Vector Processing Environment

2.2.5.1

DCl lexical Functions F$GETJPI and F$GETSVI
The DeL lexical function F$GETJPI accepts the following items and
returns the corresponding information regarding the vector status of a
specified process:

Item

Return
Type

FAST_ VP_SWITCH

Integer

Number of times this process has issued a vector instruction that
resulted in an inactive vector processor being enabled without the
expense of a vector context switch

SLOW_VP_SWITCH

Integer

Number of times this process has issued a vector instruction that
resulted in an inactive vector processor being enabled with a full vector
context switch

VP_CONSUMER

Boolean

Flag indicating whether the process is a vector consumer

VP_CPUTIM

Integer

Total amount of time the process has accumulated as a vector
consumer

Information Returned

The DCL lexical function F$GETSYI accepts the following items and
returns the corresponding information regarding the status of the vector
processing system:

Item

Return
Type

Information Returned

VP_NUMBER

Integer

Number of vector processors in the system

VP_MASK

Integer

Mask indicating which processors in the system have vector
coprocessors

VECTOR_EMULATOR

Integer

Flag indicating the presence of the VAX vector instruction emulator
facility (VVIEF) in the system

See the VMS DCL Dictionary for additional information about the DCL
lexicals F$GETJPI and F$GETSYI.

2.2.5.2

SHOW CPU Command
The SHOW CPU/FULL command lists the capabilities of the specified
CPU. The manager of a VAX vector processing system can issue this
command to determine the presence of the vector capability in the system
prior to executing a STOP/CPU command.

See the VMS DCL Dictionary for additional information about the SHOW
CPU command.

2.2.5.3

SHOW PROCESS and lOGOUT/FUll Commands
If the target process has accrued any time as a vector consumer scheduled
on a vector-present processor, the DCL commands SHOW PROCESS and
LOGOUTIFULL display the elapsed vector CPU time and the charged
vector CPU time, respectively.

2-13

Introduction to Vector Processing
2.2 Managing the Vector Processing Environment

To accumulate vector CPU time, a process must be a vector consumer (that
is, require the system vector capability) and be scheduled on a vectorpresent processor. VMS still charges the vector consumer vector CPU
time, even if, when scheduled on the vector-present processor, it does not
actually use the vector CPU. Note that, because scalar consumers and
marginal vector consumers do not use the vector CPU, they do not accrue
vector CPU time, even when scheduled on a vector-present processor.

See the VMS DeL Dictionary for additional information about the SHOW
PROCESS and LOGOUT commands.
2.2.5.4

Vector Processing Support Within the VMS Accounting Utility (ACCOUNTING)

In its full listing format, the VMS Accounting Utility displays the vector
CPU time accumulated by a process or an image during its life span.
A process accumulates vector CPU time while it is a vector consumer
(that is, requiring the system vector capability) and it is scheduled on a
vector-present processor. VMS still charges the vector consumer vector
CPU time, even if, when scheduled on the vector-present processor, it does
not actually use the vector CPU. Note that, because scalar consumers and
marginal vector consumers do not use the vector CPU, they do not accrue
vector CPU time, even when scheduled on a vector-present processor.
An image accrues vector CPU time while it is executing within the context
of a vector consumer on a vector-present processor. Because VMS marks
all processes, including vector consumers, as scalar consumers at image
rundown, it is impossible for an image that issues only scalar instructions
to accumulate vector CPU time.
The ISORT qualifier to the ACCOUNTING command accepts the
VECTOR_PROCESSOR keyword and sorts the accounting records
according to ascending or descending vector CPU time. The !REPORT
qualifier also accepts the VECTOR_PROCESSOR keyword and produces a
summary report of vector CPU usage.
See Section 2.3.8 for a description of the vector CPU time field in the
ACCOUNTING resource packet. The VMS Accounting Utility Manual
provides a complete description of the VMS Accounting Utility.
2.2.5.5

o
o

Vector Support Within the Error Log Utility (ERROR LOG)

With Version 5.4 of the Error Log Utility, the /INCLUDE qualifier to the
ANALYZEIERROR_LOG command accepts the device-class keyword
VECTOR, which produces an error log report that includes vector
processing errors. (Specifying the VECTOR keyword with the IEXCLUDE
qualifier excludes vector processing errors from the error log report.)
2.2.5.6

Vector Support Within the VMS Monitor Utility (MONITOR)

With Version 5.4 of the VMS Monitor Utility, the new MONITOR VECTOR
command initiates monitoring of the VECTOR class and displays the
number of lO-millisecond clock ticks per second in which one or more
vector consumers have been scheduled on each currently configured vector
processor.

2-14

Introduction to Vector Processing
2.2 Managing the Vector Processing Environment

See Section 16.3 for a complete description of the MONITOR VECTOR
command and the VECTOR class. See Section 2.3.9 and Section 16.4 for
related information about the VECTOR class record and format. Refer to
the VMS Monitor Utility Manual if you need additional information about
the VMS Monitor Utility.

2.2.6

Loading the VAX Vector Instruction Emulation Facility (VVIEF)
The VAX Vector Instruction Emulation Facility (VVIEF) is a standard
feature of the VMS operating system that allows vectorized applications
to be written and debugged on a VAX system in which vector processors
are not available. VVIEF is intended strictly as a program development
tool and not as a run-time replacement for vector hardware. There is no
performance benefit from vectorizing applications to run under VVIEF;
vectorized applications running under VVIEF typically execute five times
slower than their scalar counterparts.

VMS supplies the VVIEF bootstrap code as an executive loadable
image. To cause VMS to load VVIEF at the next system boot and
at each subsequent system boot, invoke the command procedure
SYS$UPDATE:VVIEF$INSTAL.COM. To unload VVIEF, invoke the
command procedure SYS$UPDATE:VVIEF$DEINSTAL.COM and reboot
the system. You can determine the presence or absence of VVIEF on a
system by issuing the following DeL commands:

$
$

x == F$GETSYI ("VECTOR_EMULATOR")
SHOW SYMBOL X

X = 1

Hex = 00000001

Octal = 0000000001

A return value of 1 indicates the presence of VVIEF; a value of 0 indicates
its absence.
Note that, although VVIEF might be loaded into the system, in the
presence of VMS vector support code, it remains inactive. Although it is
possible to prevent the loading of VMS vector processing support code in
a vector-present system (see Section 2.2.1) and activate VVIEF, there are
few benefits. Should the only vector-present processor in the system fail,
the execution of preempted vectorized applications will not resume under
the emulator.

o
2.2.7

System Messages Related to Vector Processing Activities
Table 2-2 lists the system messages that might result from vector activity
in a VAX vector processing system. It describes the conditions that
might have resulted in the message and suggests how you can repair
the condition causing the error.
For information on how VMS reports exception conditions to condition
handlers, see Section 2.3.6.

o
2-15

Introduction to Vector Processing
2.2 Managing the Vector Processing Environment

0
,

Table 2-2

. .

System Messages Relating to Vector Processing

Message

Message Text

Description and Recovery

ACCVIO

access violation, reason mask =
xx, virtual address = location, PC =
location, PSL = xxxxxxx

See the VMS System Messages and Recovery
Procedures Reference Manual for a description of
the ACCVIO message. The lowest three bits of the
reason mask indicate that an instruction has caused
a length violation (bit 0), referenced the process page
table (bit 1), and attempted a read or modify operation
(bit 2). VMS defines two additional bits to reflect vector
processing memory management exceptions: a vector
operation on an improperly-aligned vector element in
memory (bit 3) and vector instruction reference to an I/O
space address (bit 4).

BADCONTEXT

invalid or corrupted context
encountered

The vector state of a mainline routine as saved in
process P1 space has been corrupted and cannot be
restored. A call to the Restore Vector State system
service (SYS$RESTORE_VP_STATE) can result in this
error, if some coding error has overwritten the saved
vector state. (See Chapter 22 for more on this system
service.)

CPUNOTACT

requested CPU not active

The current process requires system capabilities that are
not available or no longer available among the active
processors in the system. If this message is associated
with a vector disabled (VECDIS) status code, a vectorpresent processor within the system is not available, has
failed, or has been removed from the system.

See Section 2.2.2.
EXQUOTA

exceeded quota

If this message is associated with a vector disabled
(VECDIS) status code, the process's paging file quota
prohibits the allocation of sufficient process memory for
storing its mainline vector state. (See Section 2.2.3.1.)

ILLVECOP

illegal vector opcode fault,
opcode='xx', PC='location',
PSL='xxxxxxxx'

An operation code designated as an illegal vector opcode
by the VAX architecture has been encountered during
the execution of an image.

See Section 2.3.6 and the VAX MACRO and Instruction
Set Reference Manual for additional information about
this exception.
IMGVEXC

image exiting with pending vector
exceptions

An exception has resulted due to the execution of a
vector instruction issued by an image, but the image has
exited before the exception could be delivered.
See Section 2.3.7.4.

INSFMEM

insufficient dynamic memory

If this message is associated with a vector disabled
(VECDIS) status code, the current process has issued
a vector instruction, but insufficient system nonpaged
dynamic memory exists to establish the process as a
vector consumer. (See Section 2.2.3.1.)
(continued on next page)

2-16

Introduction to Vector Processing
2.2 Managing the Vector Processing Environment

Table 2-2 (Cont.)
Message

Message. Text

Description and Recovery

INSFWSL

insufficient working set limit

If this message is associated with a vector disabled
(VECDIS) status code, the process's current working set
list limit does not allow its mainline vector state to be
resident in memory. (See Section 2.2.3.1.)

NOPRIV

no privilege for attempted operation

If this message is associated with a vector disabled
(VECDIS) status code, an ACL on the system's vector
capability has prevented the process from executing
vector instructions. (See Section 2.2.4.)

NOSAVPEXC

no saved vector exception for the
exception-id

A call was made to the Restore Vector Processing State
system service (SYS$RESTORE_VP_EXCEPTION)
that specified a value for an exception ID that does not
correspond to that of any saved vector exception state.
(See Chapter 22 for more on this system service.)

VARITH

vector arithmetic fault, summary=xx,
mask=xx, PC=location,
PSL=xxxxxxxx

A vector operate instruction, executing within the current
context, has resulted in a vector arithmetic trap. (See
Section 2.3.6 for assistance in interpreting the exception
summary mask, vector register mask, PC, and PSL.)

c
o

System Messages Relating to Vector Processing

Because arithmetic operations are performed in a
substantially different manner on vectors than on
scalars, the resolution of vector arithmetic exceptions
requires some special techniques. (See Section 2.3.6
for information on the mechanisms by which exceptions
are reported and identified.) One or a combination of
several debugging strategies can help you determine
which calculations resulted in the reported error or errors:
Recompile the source with the IDEBUG,
INOVECTOR, ICHECK=BOUNDS qualifiers; relink
using the IDEBUG and IMAP qualifiers; and run the
resulting scalar image with the IDEBUG qualifier.
A scalar arithmetic exception should occur at the
calculation that caused the original vector arithmetic
exception.
Recompile the source using the IDEBUG,
ILlST, and !VECTOR qualifiers; relink using
the IDEBUG and IMAP qualifiers; and run the
resulting image with the IDEBUG qualifier. (If the
IASSUME=NOACCURACY_SENSITIVE qualifier
was used in the original compilation, specify
IASSUME=ACCURACY_SENSITIVE.) Use the
SET VECTOR_MODE SYNCHRONIZED or
the SYNCHRONIZE VECTOR_MODE debugger
command to guarantee that all exceptions resulting
from vector operations be delivered before the
execution of the next scalar instruction. Step
through the program, inspecting the contents of
those vector registers that are involved in each
vector operation.
(continued on next page)

2-17

Introduction to Vector Processing
2.2 Managing the Vector Processing Environment

Table 2-2 (Cont.)
Message

System Messages Relating to Vector Processing

Message Text

Description and Recovery

When a vector operate instruction causes an
floating-point exception in a vector element, the
exception result is encoded into the corresponding
element of the destination register. When the
destination vector register is the target of an
EXAMINE/FLOAT debugger command, the debugger
displays the decoded exception message in the
associated vector element.
When a vector operate instruction causes an integer
overflow in a vector element, the corresponding
element of the destination register contains a value
that is larger than 32 bits, but of a different sign than
the instruction's operands. When the destination
vector register is the target of an EXAMINE
debugger command, you must inspect each element
for such results.
VASFUL

virtual address space is full

If this message is associated with a vector disabled
(VECDIS) status code, insufficient process virtual
address space exists to allow the current process's
mainline vector state to be saved. (See Section 2.2.3.1.)

VECALIGN

access violation, reason mask =
xx, virtual address = location, PC =
location, PSL = xxxxxxx

The current process has issued a VAX vector memory
access instruction that has attempted an operation
on an improperly-aligned vector element. The VAX
architecture requires that vector operands to vector
memory access instructions be naturally aligned in
memory. Longwords must be aligned on longword
boundaries; quadwords must be aligned on quadword
boundaries. See Section 2.3.6. and the VAX MACRO
and Instruction Set Reference Manual for additional
information.
(continued on next page)

;-\
II~)

o
C)

o
2-18

Introduction to Vector Processing

2.2 Managing the Vector Processing Environment

Table 2-2 (Cont.)

System Messages Relating to Vector Processing

Message

Message Text

Description and Recovery

VECDIS

vector disabled fault, code=xx, PC =
location, PSL = xxxxxxx

The current process has issued a vector instruction
that requires that a vector processor become active.
Under normal circumstances, this event is not reported
to a system user. However, if the vector processor was
unavailable due to some previously unreported condition,
the VECDIS message is issued in association with one
of the following messages.
BADCONTEXT
CPUNOTACT
EXQUOTA
INSFMEM
INSFWSL
MCHECK
NOPRIV
VASFUL

See the description of the associated message in this
table and the VMS System Messages and Recovery
Procedures Reference Manual for additional information
on any specific error.

o
2.3

Programming in a Vector Processing Environment
Most applications that benefit from vector processing can be developed
as scalar programs in a high-level language and then submitted to a
vectorizing compiler for that language.

•

The DIGITAL Extended Math Library (DXML) is an optional software
product that provides additional vectorized mathematics routines such
as BLAS Levell-extended, 2, and 3, plus signal processing routines.

Finally, those programs that require strict control over the VAX vector
hardware can be written in VAX MACRO and use the VAX vector
instructions directly.

2-19

Introduction to Vector Processing
2.3 Programming in a Vector Processing Environment

Use of high-level interfaces to VAX vector processing systems, such as the
VAX Fortran High Performance Option (HPO) vectorizing compiler and
the vectorized RTL MTH$ routines, provide a mechanism for quickly
developing a vectorized program that conforms to the requirements
of the VAX Procedure Calling and Condition Handling Standard and
the VAX vector architecture. For instance, VAX vectorizing compilers
and vectorized library routines automatically handle the complexities of
properly handling scalar-vector synchronization, vector memory alignment,
and the preservation of vector state across procedure calls. Additionally,
the VAX Fortran HPO vectorizing compiler can recognize sections of code
within a program, usually inside formal loops, that can be vectorized. It
analyzes data dependences, identifies inhibitors to vector processing, and
restructures code sequences to allow the compiler to generate optimized
VAX vector instruction sequences.
By contrast, VAX MACRO programmers must themselves ensure that
vector code conforms to the rules stated in the VAX MACRO and
Instruction Set Reference Manual and Section 2.3.7.
If you must write a vectorized program in VAX MACRO, you should be
aware of the following:
•

You must specifically enable the processing of vector instructions by
the VAX MACRO assembler by assembling with the /ENABLE or
INODISABLE qualifier to the MACRO command and supplying the
keyword VECTOR. You can also explicitly enable the assembly of
vector instructions by using the .ENABLE VECTOR directive.

•

The VAX MACRO assembler parses the assembler notation form of
vector instructions and produces binary code in the instruction stream
form prescribed by the VAX vector architecture. The VAX MACRO
and Instruction Set Reference Manual describes both vector instruction
forms and presents the assembler notation form in its instruction
pages.

•

VAX MACRO programs must synchronize the vector CPU's memory
references across procedure calls, as well as guarantee that pending
vector exceptions are raised before crossing procedure boundaries. VAX
MACRO programs must also ensure that the vector CPU's memory
references are synchronized with the scalar CPU's memory references.
Section 2.3.7 and the VAX MACRO and Instruction Set Reference
Manual describes the mechanisms by which VAX MACRO code can
comply with these requirements.

•

The VAX MACRO and Instruction Set Reference Manual lists several
additional restrictions, including the following:

o
0,'

VAX MACRO programs must naturally align vector operands to
vector memory access instructions. Longwords must be aligned
on longword boundaries; quadwords must be aligned on quadword
boundaries.
VAX MACRO instructions cannot reference addresses in I/O space.

2-20

Introduction to Vector Processing

2.3 Programming in a Vector Processing Environment

Vector instructions cannot be issued at elevated interrupt priority
levels (IPLs), specifically at or above IPL$_RESCHED. The vector
disabled handler will force a system crash with the VPIPLHIGH
bugcheck code ("IPL too high to use the Vector Facility") when user
vector instruction is issued at or above IPL$_RESCHED.
The remainder of this section discusses the following topics:

2.3.1

•

Vector routines in the MTH$ Run-Time Library

•

Obtaining information about a vector processing system

•

Releasing the vector processor

•

Preserving and restoring a routine's vector state

•

Issuing vector instructions at high IPLs

•

Debugging a vector application

•

Servicing vector processing exceptions

•

Utilizing vector information contained within the informational
packets generated by the VMS Accounting Utility and VMS Monitor
Utility

Vector Routines in the MTH$ Run-Time Library
The RTL MTH$ facility provides three sets of routines that allow
manipulation of vectors and perform operations on vectors:
•

The Basic Linear Algebra Subroutines (BLAS) Levell copy vectors,
swap the elements of two vectors, scale vector elements, perform
reduction operations on vectors, and effect a Givens plane rotation.
Scalar and vector versions of the BLAS Level 1 are provided in the
new BLASl$ and VBLASl$ facilities, respectively. BLAS Levell
forms an integral part of many standaqilibraries such as LINPACK
and EISPACK. The version of the subroutines in the RTL VBLASl$
facility have been tuned to the VAX architecture to take advantage of
vectorization.

•

The First Order Linear Recurrence (FOLR) routines provide a
vectorized algorithm for the linear recurrence relation. (The
traditional algorithm generally inhibits vectorization by using the
result of a previous pass through a loop as an operand in subsequent
passes through the loop.)

The FOLR routines in the RTL MTH$ facility perform addition,
multiplication, or both addition and multiplication on recursion
elements, saving the result of each iteration in an array or saving
only the last result in a variable. The RTL MTH$ facility supplies
these routines in four groups, each accepting any of four data types:
longword integer, F -floating, D-floating, or G-floating.
•

Certain key MTH$ routines have been vectorized to support Digital's
vectorizing compilers, such as the VAX FORTRAN High Performance
Option (HPO). Vectorized versions of key F -floating, D-floating, and
G-floating scalar routines employ vector hardware to the fullest,

2-21

Introduction to Vector Processing
2.3 Programming in a Vector Processing Environment

while maintaining results that are identical to those of their scalar
counterparts.
Vectorized MTH$ routines are never called directly from a highlevel language program. At a call to a scalar version of one of these
routines, a vectorizing compiler automatically determines whether
an operation should be performed by the vector or scalar version of
a routine. VAX MACRO programs, however, can call the vectorized
MTH$ routines directly.
See the VMS RTL Mathematics (MTH$) Manual for complete information
about these routines.
Note that the VAX FORTRAN HPO detects usage of the vectorizable
constructs within source code and automatically issues a call to the
appropriate RTL MTH$ routines. See the description of the !BLAS
qualifier in the compiler documentation.

2.3.2

(~I
~_/)

Obtaining Information About a Vector Processing System
The Get Job/Process Information system service (SYS$GETJPl) accepts
the following item codes and returns the indicated information about the
vector status of one or more processes in the system:
Item Code

Return Value

Unsigned longword containing the number of times
this process has issued a vector instruction that
resulted in an inactive vector processor being enabled
without the expense of a vector context switch. This
count reflects those instances in which the process
has reenabled a vector processor on which the
process's vector context has remained intact.
Unsigned longword containing the number of times
this process has issued a vector instruction that
resulted in an inactive vector processor being enabled
with a full vector context switch. This vector context
switch involves the saving of the vector context of
the process that last used the vector processor and
the restoration of the vector context of the current
process.

Byte, the low-order bit of which, when set, indicates
that the process is a vector consumer.
Unsigned longword that contains the total amount
of time the process has accumulated as a vector
consumer.

The Get Systemwide Information system service (SYS$GETJPl) accepts
the following item codes and returns the indicated information about the
vector status of the system:

2-22

Introduction to Vector Processing

2.3 Programming in a Vector Processing Environment

Return Value

SYI$_VP_NUMBER

Unsigned longword containing the number of vector
processors in the system.

SYI$_VP_MASK

Longword mask, the bits of which, when set,
indicate which processors in the system have vector
coprocessors.

SYI$_VECTOR_EMULATOR

Byte, the low-order bit of which, when set, indicates
the presence of the VAX vector instruction emulator
facility (VVIEF) in the system.

See Section 22.5 (of this manual) and the VMS System Services Reference
Manual for additional information on the $GETJPI and $GETSYI system
services.

o
2.3.3

Releasing the Vector Processor
The Release Vector Processor system service (SYS$RELEASE_VP)
terminates the current process's status as a vector consumer. Because
$RELEASE_VP declares that the process no longer needs the system's
vector capability, VMS is no longer restricted to scheduling it on a vectorpresent processor. As a result, the process can be placed into execution on
other CPU s in the system.

See Chapter 22 for a full description of the invocation format and functions
of this service.

2.3.4

Item Code

Preserving and Restoring a Routine's Vector State
The vector context of a process consists of the contents of the vector
registers VO through V15, the contents of the vector control registers (VLR,
VCR, and VMR), the vector processor status, and the vector exception
state. When a vectorized application involves calls among two or more
routines, each of which issues vector instructions, two components of a
process's vector context must be considered:
•

The vector registers that are shared across procedure calls

•

The vector exception state that exists just prior to a procedure call or
return

The VAX Procedure Calling and Condition Handling Standard (see
Section 2.3.7.1) requires that calling and called procedures agree as to the
conventions by which they preserve and manipulate vector registers. For
languages such as VAX MACRO, which allows direct access of registers,
either the calling procedure or called procedure can save or restore vector
registers shared between routines.

The standard also requires that, if a procedure executes a vector
instruction that might possibly raise an exception, the procedure must
ensure that this exception is reported before it calls another procedure,
returns to its caller, or exits. If a vector exception were pending at the
time a procedure transferred control, it would be reported in the context
of a procedure that did not incur the exception. VAX vectorizing compilers

2-23

Introduction to Vector Processing
2.3 Programming in a Vector Processing Environment

ensure that compiled code properly follows this requirement; calls to vector
routines in the RTL MTH$ facility (as described in Section 2.3.1) also
comply with this prescription. However, vectorized code written in VAX
MACRO must adhere to the rules discussed in Section 2.3.7.4.
For those routines that can run asynchronously with respect to the
mainline routine-such as asynchronous system trap CAST) routines,
condition handlers, and exit handlers-VMS automatically handles the
saving and restoring of vector context. VMS supports vector usage in
these asynchronous routines by providing each routine that is active
asynchronously within a process with its own vector state.
The vector state of a routine reflects the vector context of the process
at the time of the routine's execution or preemption, as the case may
be, when an AST is delivered to the process or a condition handler is
triggered. A process can have several vector states; for instance, one for
its mainline routine and one for an AST routine that has interrupted the
mainline. However, a process has only a single vector context, reflecting
its current vector state.
VMS automatically preserves the vector state of a routine as follows:
•

When a user mode AST routine issues a vector instruction, VMS saves
the vector state of the mainline routine. It restores the mainline vector
state when the AST routine exits.

•

When a user mode condition handler issues a vector instruction, VMS
saves the vector state of the mainline routine. It restores the mainline
vector state on continuing from the exception and on stack unwind.

•

When calling an exit handler, VMS clears the vector exception state.

By default, when an asynchronous routine interrupts the execution of a
mainline routine, VMS creates a new vector state when the routine issues
its first vector instruction. At this point, the vector state of the mainline
routine is inaccessible to the asynchronous routine.
In certain cases, however, an AST routine or condition handler might
need to read or modify the saved exception state of the mainline routine.
To do so, the routine must call the Restore Vector State system service
(SYS$RESTORE_VP_STATE). $RESTORE_VP _STATE restores the vector
state of the process's mainline routine.

In very rare cases, a procedure might need to preserve and restore the
current vector exception state across individual contexts that it creates
and maintains. For instance, a task manager could set up several discrete
tasks, each of which has its own vector state. To implement such a system,
the routine saves the contents of the appropriate vector registers and calls
the Save Vector Exception State (SYS$SAVE_VP _EXCEPTION) and
Restore Vector Exception State (SYS$RESTORE_VP_EXCEPTION) system
serVIces.
The Save Vector Exception State service saves in memory any pending
vector exception state and clears the vector processor's current exception
state. ' The Restore Vector Exception State service restores from memory
the vector state saved by a prior call to $SAVE_VP _EXCEPTION. Mter a

2-24

Introduction to Vector Processing

2.3 Programming in a Vector Processing Environment

routine invokes this service, the next vector instruction issued within the
process causes the restored vector exception to be reported.
See Chapter 22 for a full description of the syntax and use of
the $ SAVE_VP_EXCEPTION, $RESTORE_VP_EXCEPTION, and
$RESTORE_VP_STATE system services.

2.3.5

Debugging a Vectorized Program
The Version 5.4 of the VMS operating system supports the debugging
of vector applications by adding new capabilities to the VMS Debugger,
the VMS System Dump Analyzer (SDA), the debuggers of the VMS Delta
lXDelta Utility (DELTAlXDELTA), and the Patch Utility. Additionally, the
VMS exception detecting and reporting mechanism collects information
regarding the nature and context of vector processing errors. Section 2.3.6
describes the information VMS provides when reporting a vector
processing exception.

o
2.3.5.1

o
o

Vector Processing Support Within the VMS Debugger
Through enhancements and additions to its existing command set, the
VMS Debugger allows you to correct and tune vectorized applications.
VMS Debugger commands enable you to perform the following tasks:

•

Control and monitor the execution of vector instructions with
breakpoints, watchpoints, and other mechanisms

•

Examine and deposit into the vector control registers (VCR, VLR, and
VMR) and the vector registers (VO through V15)

•

Examine and deposit vector instructions

•

Perform masked operations on vector registers to display only certain
register elements or override the masking associated with a vector
instruction

•

Control synchronization between the scalar and vector processors

•

Save and restore the current vector state when using the CALL
command to execute a routine that might affect the vector state

•

Display vector register data using a screen-mode display

•

Display the decoded results of vector arithmetic exceptions

See Chapter 19 (of this manual) and the VMS Debugger Manual for
complete information about these and other functions of the VMS
Debugger.
2.3.5.2

Vector Processing Support Within the VMS System Dump Analyzer (SDA)
The System Dump Analyzer (SDA) provides several mechanisms for
examining vector instructions and vector context from a system dump file
or in a running system. They include the following:

•

You can decode and display vector instructions using the EXAMINE
/INSTRUCTION command. This command displays the vector opcodes,
switches, and operands in the form and order defined by the VAX
MACRO assembler notation. Note that, when you use SDA to display
2-25

Introduction to Vector Processing
2.3 Programming in a Vector Processing Environment

the contents of memory locations, vector instructions appear in the
instruction stream format defined by the VAX architecture: that is, an
opcode followed by the vector control word in immediate addressing
mode. (See the VAX MACRO and Instruction Set Reference Manual for
descriptions of the assembler notation and instruction stream formats
of vector instructions.)

2.3.5.3

•

You can examine the values of a process's vector registers and
vector control registers by entering the SHOW PROCESSNECTOR_
REGISTERS command. This command obtains the values of the
registers from the process's vector context area. Note that the names
of these registers (VO through V15, VCR, VLR, and VMR) are not
defined in the SDA symbol table. You cannot display the current
contents of any of these registers using the EXAMINE or EVALUATE
command.

•

You can format the contents of a memory location as a process's vector
context block. The symbol table SYS$SYSTEM:SYSDEF.STB contains
a definition of this structure. You must use the READ command to
load the symbols defined within this file into the SDA symbol table.

•

You can determine the presence and location of the VMS vector
processing support code (VECTOR_PROCESSING.EXE) and the
VAX Vector Instruction Emulation Facility (VVIEF) bootstrap code
(VVIEF$BOOTSTRAP.EXE) by entering the SDA command SHOW
EXECUTIVE. Both are executive loadable images. You can also use
the SDA command READIEXECUTIVE to load definitions of locations
within these images into the SDA symbol table.

Vector Processing Support Within the VMS Delta/XDelta Utility

The VMS DeltalXDelta Utility (DELTAlXDELTA) provides mechanisms for
stepping through vector code, examining and decoding vector instructions,
and setting breakpoints at vector instructions. You can use the following
commands to debug a vectorized application:

2-26

•

The Open Location and Display Instruction in Instruction Mode
command (!) displays the vector opcodes, switches, and operands in
the form and order defined by the VAX MACRO assembler notation.
Note that, when you use DELTAlXDELTA to display the contents of
memory locations, vector instructions appear in the instruction stream
format defined by the VAX architecture: that is, an opcode followed
by the vector control word in immediate addressing mode. (See the
VAX MACRO and Instruction Set Reference Manual for descriptions
of the assembler notation and instruction stream formats of vector
instructions. )

•

The Step Instruction command (S) enables you to single step through
vector instructions.

•

The List Names and Locations of Loaded Executive Images command
(;L) enables you to determine the presence and location of the VMS
vector processing support code (VECTOR_PROCESSING.EXE) and
the VAX Vector Instruction Emulation Facility (VVIEF) bootstrap code
(VVIEF$BOOTSTRAP.EXE).

,. ,
.....

Introduction to Vector Processing

2.3 Programming in a Vector Processing Environment

• The Breakpoint (;B) and Proceed from Breakpoint (;P) commands allow
you to set and proceed from breakpoints at a vector instruction.
Note that, because the names of the vector registers (VO through V15)
and vector control registers (VCR, VLR, and VMR) are not defined in
the DELTAlXDELTA symbol table, you cannot display their values using
DELTAlXDELTA.

2.3.5.4

Vector Processing Support Within the VMS Patch Utility

Enhancements to the VMS Patch Utility allow it to interpret and display
vector instructions that are replaced or deposited in a VAX MACRO
program image file.
When issuing a REPLACEIINSTRUCTION instruction, you must supply
the vector opcode, switches, and operands in the form and order defined
by the VAX MACRO assembler notation. When displaying the contents
of an image in instruction format, the Patch Utility produces vector
instructions in this format. However, its hexadecimal listings present
vector instructions in the instruction stream format defined by the VAX
architecture: that is, an opcode followed by the vector control word in
immediate addressing mode. (See the VAX MACRO and Instruction
Set Reference Manual for descriptions of the assembler notation and
instruction stream formats of vector instructions.)

o
c

2.3.6

Servicing Vector Exceptions
During the execution of an image, the image can incur a fatal error known
as an exception condition. If the image has not declared a condition
handler, the system forces the image to exit and displays a message
indicating the reason for the exception. If the image has declared a
condition handler, VMS transfers control to the handler to manage the
exception. (See Introduction to VMS System Services for a description of
how to write and declare a condition handler.)
There are two major classes of vector processing exceptions:
•

Memory management exceptions, including access violations, vector
alignment faults, and vector instruction references to I/O space

•

Vector arithmetic exceptions

VMS reports exceptions in the first category (memory management
exceptions) as forms of access violation, using the signals SS$_ACCVIO
and SS$_VECALIGN (see Table 2-3). The exception argument list
VMS supplies when signaling vector memory management exceptions
is identical to the one it supplies with scalar access violations, except that
VMS defines two additional bits in the reason mask to indicate the nature
of the vector exception: a vector operation on an improperly-aligned vector
element in memory (bit 3) and vector instruction reference to an I/O space
address (bit 4).

2-27

Introduction to Vector Processing
2.3 Programming in a Vector Processing Environment

VMS reports exceptions in the second category (vector arithmetic
exceptions) using the signal SS$_VARITH (see Table 2-3). As defined
by the VAX vector architecture (see the VAX MACRO and Instruction
Set Reference Manual), vector operate instructions always execute to
completion. If an exception occurs, the default result is written as follows:
•

The low-order 32 bits of the true result for integer overflow.

•

Zero for floating underflow if exceptions are disabled.

•

An encoded reserved operand for floating divide by zero, floating
overflow, reserved operand, and enabled floating underflow. For vector
convert instructions that convert floating-point data to integer data,
where the source element is a reserved operand, the value written to
the destination element is UNPREDICTABLE.

Table 2-3 provides a summary of the means by which VMS signals
vector processing exceptions and the arguments it provides for condition
handlers. For information on how these exception conditions are reported
by the VMS message facility, see Section 2.2.7.

o
2-28

Introduction to Vector Processing

2.3 Programming in a Vector Processing Environment

Table 2-3
Exception

Summary of Exception Conditions
Type

Description

Arguments

Fault

Access violation

Two, as follows:
Reason for access violation. This is a mask with the
following format:

Bit

Description

Type of access violation:
Clear if page table entry protection code did
not permit intended access

Set if POLR, P1 LR, or SLR length violation
Page table entry reference:
Clear if specified virtual address is not
accessible
Set if associated page table entry is not
accessible
2

Intended access:
Clear if read

Set if modify

Vector alignment exception:
Set if vector element is not properly aligned in
memory1

Vector instruction reference of I/O space
Set if vector instruction referred to an I/O
space address

o
Fault

Illegal vector
opcode. 2

Four, as follows:
1
2
3

Virtual address to which access was attempted or, on
some processors, virtual address within the page to
which access was attempted. For access violations
that occur due to a vector alignment exception or a
vector instruction reference to I/O space, this virtual
address is a/ways an address within the page to
which access was attempted.

Signal name, SS$_ILLVECOP
Illegal opcode that caused the exception
Program counter (PC) of the vector instruction that
caused the exception to be reported. (Note that
this instruction is not always that that caused the
exception.)
Processor status longword (PSL) at the time the
exception is reported.

Note that the VM8 operating system reports this exception with an 88$_VECALIGN fault.

2 Note that some processors report illegal vector opcodes with the 88$_OPCDEC exception.

(continued on next page)

2-29

Introduction to Vector Processing
2.3 Programming in a Vector Processing Environment

""
'.

0··

Table 2-3 (Cont.)

Summary of Exception Conditions

Exception

Type

Description

Arguments

88$_VARITH

Trap

Vector arithmetic
trap

Five, as follows:

2
Bit

Meaning

Floating underflow

Floating divide by zero

Floating reserved operand

Floating overflow

Integer overflow

5
88$_VECALIGN

Fault

Vector alignment
exception

8ignal name, 88$_VARITH.
Exception summary. This is a mask, the bits of which,
when set, signify the following:

\ /'
..

Vector register mask, the bits of which (0 through
15) correspond to the VAX vector registers (VO
through V15). When set, a bit indicates that an
element of the associated vector register was involved
in an operation that caused one or more of the
vector arithmetic exceptions reported in the exception
summary argument.
Program counter (PC) of the vector instruction that
caused the exception to be reported. (Note that this
instruction is not always the one that caused the
exception.)
Processor status longword (P8L) at the time the
exception is reported.

Identical to the argument list for 88$_ACCVIO
(~\

(continued on next page)

,,-)

o
2-30

Introduction to Vector Processing

2.3 Programming in a Vector Processing Environment

Table 2-3 (Cont.)

Summary of Exception Conditions

Exception

Type

Description

Arguments

Fault

Vector processor
disabled

Three, as follows:
Reason for vector disabled exception. The reason
argument can have any of the following values:
SS$_NOPRIV-An ACL on the vector capability has
denied a user mode program access to the vector
processor.
SS$_MCHECK-The vector processor has been
disabled due to the detection of a hardware error.
SS$_INSFMEM-Insufficient nonpaged dynamic
memory exists to turn the current process into a
vector consumer.

SS$_CPUNOTACT-The VAX system contains no
vector-present processor on which to schedule the
current process.
SS$_BADCONTEXT-The vector state of the mainline
routine is corrupt and cannot be restored.
SS$_EXQUOTA-The VMS operating system cannot
allocate sufficient space to save the vector state of
the mainline routine because the process in which the
routine is executing has exceeded process paging file
quota.

SS$_INSFWSL-The VMS operating system cannot
allocate sufficient space to save the vector state of
the mainline routine because the working set limit of
the process in which the routine is executing is too
low.

c
2

2.3.7

SS$_VASFUL-The VMS operating system cannot
allocate sufficient space to save the vector state of
the mainline routine because the address space (PO
space) of the process in which the routine is executing
is full.
Program counter (PC) of the vector instruction that
caused the exception to be reported. (Note that
this instruction is not always that that caused the
exception.)
Processor status longword (PSL) at the time the
exception is reported.

Requirements of the VAX Procedure Calling and Condition Handling
Standard for Vector Processing
This section contains excerpts from the VAX Procedure Calling Standard
that describe the requirements that procedures must follow when using
the system's vector processing resources.
Code generated by VAX vectorizing compilers adheres to the rules
described in this section. VAX MACRO code containing vector instructions
must be written to comply with these requirements.
2-31

Introduction to Vector Processing
2.3 Programming in a Vector Processing Environment

2.3.7.1

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

2.3.7.2

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

2.3.7.3

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

•

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

•

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

•

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

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

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

However, if it can be determined that the only possible exceptions that
can occur are ensured to be reported by an MSYNC instruction that
is otherwise needed for memory synchronization, then the SYNC is
redundant and can be omitted as an optimization.

2-32

Introduction to Vector Processing
2.3 Programming in a Vector Processing Environment

Moreover, if it can be determined that the only possible exceptions that
can occur are ensured to be reported by one or more MFVP instructions
that read the vector control registers, then the SYNC is redundant and
can be omitted as an optimization.

2.3.7.5

Synchronization Summary

Memory synchronization with the caller of a procedure that uses the
vector processor is required because there might be scalar machine
writes (to main memory) still pending at the time of entry to the called
procedure. The various forms of write-cache strategies allowed by the
VAX architecture combined with the possibly independent scalar and
vector memory access paths imply that a scalar store followed by a CALL
followed by a vector load is not safe without an intervening MSYNC.

Within a procedure that uses the vector processor, proper memory and
exception synchronization might require use of an MSYNC instruction or
a SYNC instruction, or both, prior to calling another procedure or upon
being called by another procedure. Further, for calls to other procedures,
the requirements may vary from call to call depending on details of actual
vector usage.
An MSYNC instruction (without SYNC) at procedure entry, procedure
exit, and prior to a call, should provide proper synchronization in most
cases. A SYNC instruction (without an MSYNC prior to a CALL or RET)
will sometimes be appropriate. The remaining two cases, where both or
neither MSYNC and SYNC are needed, are probably rare.

Refer to the VAX MACRO and Instruction Set Reference Manual in the
VAX Vector Architecture section for the specific rules on what exceptions
are ensured to be reported by MSYNC and other MFVP instructions.

2.3.7.6

Condition Handler Parameters and Invocation

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

o
2-33

Introduction to Vector Processing
2.3 Programming in a Vector Processing Environment

2.3.8

VMS Accounting Utility (ACCOUNTING) Resource Packet Format
The VMS Accounting Utility uses the longword field ACR$L_VP_
CPUTIME in the resource packet (ACR$K_RESOURCE) to record the
vector CPU time (measured in lO-millisecond clock ticks) accrued by a
process or image.
See the VMS Accounting Utility Manual for a complete description of the
format and contents of ACCOUNTING records.

2.3.9

VMS Monitor Utility (MONITOR) VECTOR Class Record
As discussed in VMS Monitor Utility Manual, the VMS Monitor Utility
(MONITOR) writes binary performance data to a VAX RMS sequential
file known as the MONITOR recording file. Once per recording interval,
MONITOR writes to this file a record containing data pertinent to each
currently selected class. Version 5.4 of the VMS Monitor Utility includes
the VECTOR class record, which contains data describing the time during
which vector consumers have been scheduled on a vector-present processor.
See Section 16.3 for a complete description of the MONITOR VECTOR
command and the VECTOR class. See Section 16.4 for specific information
about the VECTOR class record and format.

(-~,

~_ /'!

o
2-34

Introduction to DECdtm Services

The VMS Version 5.4 operating system includes DECdtm services, which
provide system services that demarcate and coordinate distributed
transactions. By using the two-phase commit protocol, these services
ensure consistent execution of distributed transaction on the VMS
operating system. In turn, these system services make use of underlying
logging and communication primitives necessary to enable distributed
transaction commitment.

This chapter describes how the DECdtm services coordinate distributed
transaction processing. The following sources in this manual also describe
aspects of VMS Version 5.4 support for DECdtm services:

•

Chapter 15 (Log Manager Control Program Utility (LMCP))

•

Section 16.1 (MONITOR TRANSACTION Command and
TRANSACTION class)

•

Chapter 22 (new and modified system services)

•

Chapter 29 (of this manual) and the VAX RMS Journaling Manual
(RMS Journaling support)

•

VMS Version 5.4 Release Notes

Note: By default, processes for DECdtm services are started when a full
VMS boot is executed. Before any transactions can be started,
however, you must first use the Log Manager Control Program
Utility (LMCP) to create a transaction log file (as described in
Chapter 15).

If you do not want to run DECdtm software, you can
prevent the startup of DECdtm processes by defining the
systemwide logical name SYS$DECDTM_INHIBIT in the
SYS$MANAGER:SYLOGICALS.COM command procedure. You
can define SYS$DECDTM_INHIBIT to be any string. For example:
$ DEFINE/SYSTEM/EXEC SYS$DECDTM_INHIBIT "yes"

See the Guide to Setting Up a VMS System for more information
about the SYLOGICALS.COM command procedure.

3.1

Characteristics of Distributed Transactions
In business terminology, a transaction is a discrete unit of work. One
example of a transaction is the purchasing of tickets from an airline
reservation system. Another example is the transferring of funds between
customer accounts using an automated teller machine (ATM). In both
examples, the processing of the transaction involves interaction with
databases.

3-1

Introduction to OECdtm Services
3.1 Characteristics of Distributed Transactions

Characteristically, transaction processing incorporates large, corporatelevel applications that support many users for critical business functions.
In transaction processing applications, there are usually many users
simultaneously performing predefined functions (query and update) to
a collection of shared data, generally a database. Results are usually
expected immediately.
Another characteristic of transaction processing is that it is usually
distributed. Transaction execution typically involves communication
between a client program and one or more databases that can be locally
or remotely located. This communication between client and server
might typically take place through a network of systems distributed at
various geographic locations; hence, the operation can be called distributed
transaction processing. In the example of funds transfers at an ATM, the
central system-or database-acts as a server, providing services to the
customer-or client-at the ATM.

'(\
\'
",-" ,;/

A single transaction represents the execution of a set of procedures. A
client and the server must communicate using read and write operations
to enable the client program to perform the desired task, for example, to
perform a debit/credit operation to transfer funds in customer accounts.
Figure 3-1 shows the execution flow of a simple debit/credit application.
A user at the ATM requests a financial operation, such as a transfer of
funds from one account to another. A client program on Node A receives
this request from the ATM. The client program forwards the request to
a debit/credit program on Node B, and the debit/credit program updates
the customer accounts database. The transaction shown in this figure
is distributed because the cooperating programs are located on different
computer systems.
For transaction processing to be reliable, every required operation
involved in the execution of the transaction must be completed before
the transaction is made permanent; otherwise none of the operations are
completed. A transaction that has this characteristic, known as atomicity,
is considered an atomic transaction.
An atomic transaction must execute in its entirety or must have no effect
at all. A transaction that executes in its entirety is called committed. One
that terminates prematurely (and therefore has no effect) is called aborted.

(

\
.~

The DECdtm services implement a commit protocol to guarantee atomic
transaction processing. This protocol, known as the two-phase commit
protocol, ensures atomicity by sequencing the commit process in such
a way as to ensure that all resources (for example, databases) will be
committed.
In the funds transfer example, it is vital that each of the customer's
accounts is properly debited or credited and the account files updated
only after it has been acknowledged that the transfer has occurred. If
a system failure occurs while the transaction is processing, all of the
previous operations of the transaction must be nullified. This arrangement
keeps the database consistent; no operation is ever partially applied to the
database.

3-2

.- ,.

Introduction to OECdtm Services

3.2 Transaction Processing System Model

Figure 3-1

Sample Debit/Credit Transaction Execution

Node B
Client

NodeC
SeNer

Debit/Credit Program
Begin Transaction
Processing
Account
Database

Node A

'--

Send Request

.--'

Send
Result

Print Transaction
Receipt

End Transaction
Processing

_._._._._._._._._._._._._._._._._._._._._.J

ZK-1221A-GE

3.2

Transaction Processing System Model
In Digital's model for transaction processing, several components work
together to execute atomic transactions.

At the end-user level, user-written application programs define the task
to be accomplished, such as query, update, and debit/credit. Application
programs also specify how transactions are to be executed. The application
programs initiate transaction execution using calls to VMS system
services.

At the system level, the execution of the transaction depends on the
interaction of the three main transaction processing components:

3.2.1

•

Resource managers

•

Transaction managers

•

Log managers

Resource Manager
A resource manager controls shared access to a set of recoverable resources
on behalf of applications programs. A resource is usually a database. The
term recoverable means that all updates to the resources on behalf of the
transaction can be made permanent or can be undone.
A resource manager participates in the two-phase commit protocol to
commit or abort a transaction.
3-3

Introduction to DECdtm Services
3.2 Transaction Processing System Model

Resource managers provide recovery mechanisms that work together with
the DECdtm services and perform any necessary logging and recovery
operations. The most common type of resource manager is a database
system. Several Digital products can act as resource managers, including
VAX RMS Journaling, RdbNMS, and VAX DBMS.
The execution of a transaction can span several nodes. The root
application program can use the services of one or more resource managers
on its home node. An application can also communicate with applications
on other nodes, and these remote applications can also use other resource
managers.

3.2.2

Transaction Manager
A transaction manager supports the services issued from application
programs to start, end, and abort transactions. A transaction manager
coordinates the action of a distributed transaction by sending instructions
to resource managers about how to complete the transaction.
In a distributed network of transaction processing systems, each VMS
node normally contains one DECdtm object. This object contains the
transaction manager for transactions initiated from that node. The
transaction manager maintains a list of participants in a transaction.
In the execution of a transaction, participants may include:
•

Resource managers on a local node, spanning one more or processes

•

Transaction managers on other nodes within a network, which may
also have associated resource manager and transaction manager
participants

In this way, a hierarchy, or "tree," of resource managers and transaction
managers can be established within the execution of a single transaction.
The node on which a transaction is created is the "root" of the transaction.
This is the coordinating or home node. Nodes containing the participating
transaction managers and resource managers branch off from the root
node. On each node, a transaction manager communicates only with its
local resource managers, the transaction managers that are its immediate
subordinates and the transaction manager that is its superior. A
subordinate node is also referred to as a child node. A superior transaction
manager is also referred to as a parent transaction manager.

In Figure 3-2, Node A is the coordinating node. It contains the parent
transaction manager (TM) and the local resource manager (RM). The
parent transaction manager coordinates the transaction started by
the application program (AP) Node A with participating transaction
managers and resource managers on other nodes. Nodes B, C, and Dare
all subordinates of Node A.

o
3-4

Introduction to DECdtm Services

3.2 Transaction Processing System Model

Figure 3-2

Participants in a Distributed Transaction Example

Coordinator
Node A

Node B

NodeC

Database

Node D

o
ZK-1870A-GE

3.2.3

Log Manager
A log manager provides the mechanism for storing a permanent record
of the execution of distributed transactions in log files. Each recoverable
resource manager implements its own log manager component, which
consists of a set of logging services. Logging services are also provided
by the DECdtm services. During normal operation, resource managers
and transaction managers write log files containing records of transaction
state information. After recovering from a failure, a resource manager
or transaction manager can read the log file to determine the state of a
transaction at the time of failure.

3-5

Introduction to OECdtm Services
3.3 Overview of Two-Phase Commit Protocol

3.3

Overview of Two-Phase Commit Protocol
Specific transaction management system services called from application
programs mark the start and end of a transaction. The DECdtm system
services include:
•

Start Transaction ($START_TRANS)

•

Start Transaction and Wait ($START_TRANSW)

•

End Transaction ($END_TRANS)

•

End Transaction and Wait ($END_TRANSW)

•

Abort Transaction ($ABORT_TRANS)

•

Abort Transaction and Wait ($ABORT_TRANSW)

The transaction manager component of the DECdtm services coordinates
the execution of these system services. See Chapter 22 for more detailed
descriptions of the DECdtm system services new for Version 5.4 of the
VMS operating system.
The processing of a distributed transaction begins when an application
calls the $START_TRANS or $START_TRANSW service. In response,
the transaction manager generates a unique transaction identifier (TID)
for the transaction so that it can keep track of the transaction. The
transaction manager uses the TID to identify all actions performed by
resource managers and transaction managers on behalf of the transaction.
Each resource manager is responsible for providing recovery capabilities
for its own resources by performing transaction logging. The transaction
manager is responsible for notifying all resource managers involved in a
transaction of all relevant transaction state transitions. The transaction
manager keeps track of the state of each transaction in case a system or
process fails before the transaction completes.
The transaction manager maintains a list of resource managers and
transaction managers that participate in a transaction's execution. The
transaction manager uses this list of participants to execute the two-phase
commit protocol. During the execution of this protocol, each participating
transaction manager writes transaction information to a log file. A log file
contains a permanent record of transaction states. By having access to a
log file, a transaction manager can resume the execution of the two-phase
commit protocol after recoveri~g from a system failure.

o
0

. ..

For a complete description of transaction log files, see Chapter 15.
Each participating resource manager supports atomic transactions on
its resources. To do this, the resource manager notifies the transaction
manager as soon as that resource manager is first accessed by the
application. A resource manager logs enough information to allow it to
undo or redo operations it performed on behalf of a transaction. Similar to
a transaction manager, a resource manager logs transaction state changes
to a log file.

3-6

Introduction to DECdtm Services

3.3 Overview of Two-Phase Commit Protocol

The processing of a transaction completes when one of the following calls
is made:
•

Commit-Using $END_TRANS or $END_TRANSW

•

Planned abort-Using $ABORT_TRANS or $ABORT_TRANSW

(See Chapter 22 for more detailed descriptions of the DECdtm system
services introduced in Version 5.4 of the VMS operating system.)
Upon receiving an End Transaction call, the DECdtm services implement
the two-phase commit protocol to inform all participants how to proceed
with the execution of the transaction.
The first phase of the two-phase commit protocol is the prepare phase.
During this phase, the transaction manager uses a polling mechanism
to determine if the participants can complete all the steps involved in a
given transaction and can therefore commit the transaction. A participant
that has successfully prepared casts a "yes" vote. If an error occurs during
the polling that prevents a participant from responding-for example, if
a resource manager fails or if a network link goes down-a "no" vote is
assumed.

A "yes" vote indicates that the participating resource manager can either
commit or abort the operations performed within this transaction, even if
a failure occurs.

If all of the participants declare that they can commit by voting "yes,"
the transaction manager makes a decision to commit and proceeds to the
second phase, known as the commit phase.
The transaction manager now orders the participants to commit the
transaction. At this point all participants complete their transaction
operations.
If any of the participants fails to prepare successfully, the transaction
is aborted. The transaction manager orders all remaining participants
to abort the transaction and roll back their transaction processing
work. Thus, none of the actions of the distributed transaction are made
permanent.

o
3.4

Managing DECdtm Services Using VMS Utilities
The VMS operating system provides the following utilities to manage the
information provided by the DECdtm services:

•

The Log Manager Control Program Utility (LMCP) is used to create
and manage log files that are used by transaction managers. See
Chapter 15 for a complete description.

•

The VMS Monitor Utility can be used to monitor the st~tus of
transactions executing on the system. See Chapter 16 for more
information.

3-7

Introduction to DECdtm Services
3.5 New TRANSACTION_ID Data Type for Programming Routines

3.5

New TRANSACTION_ID Data Type for Programming Routines
To support DECdtm programming routines, there is a new VMS data type,
or structure, for low- and high-level languages. The transaction_id data
type is an octaword that stores a unique transaction identifier.

o
o

o
3-8

C'"
'

Part 2: General User Features
This part contains the following chapters:
Chapter 4, DCl Commands and lexical Functions
Chapter 5, EVE Editor
Chapter 6, System Messages
Chapter 7, DECwindows User and Desktop Applications

o
o

o
4

DCl Commands and lexical Functions

This chapter includes the following information:

Table 4-1 contains a summary of DCL commands that are new or
enhanced in the VMS Version 5.4 operating system.

•

Table 4-2 contains a summary of the lexical functions that are new or
enhanced in the VMS Version 5.4 operating system.

Refer to the revised VMS DeL Dictionary for complete descriptions of all
new and enhanced VMS Version 5.4 DCL commands and lexical functions.

Table 4-1

•

Summary of New and Enhanced DCl Commands

Command

Enhancements

BACKUP

Now includes new IMEDIA_FORMAT qualifier, which controls data compaction on
a TA90E tape drive.

FONT

New command that compiles fonts for use by the DECwindows server and
converts an ASCII bitmap distribution format (BDF) into binary server natural form
(SNF).

INITIALIZE

Now includes new IMEDIA_FORMAT qualifier, which controls data compaction on
a TA90E tape drive.

MOUNT

Now includes new IMEDIA_FORMAT qualifier, which controls data compaction on
a TA90E tape drive.

PSWRAP

New command that invokes the PSWRAP translator, which converts procedures
written in PostScript to callable routines.

SET ACL

Now includes the new CAPABILITY keyword for the IOBJECT_TYPE qualifier,
which lets you specify a system capability such as the ability to process vector
instructions.
Also includes the following new qualifiers:
IBACKUP
Modifies the time value from ISINCE or IBEFORE to
select files according to their most recent BACKUP
IEXPIRED

Modifies the time value from ISINCE or IBEFORE to
select files according to their expiration date

IMODIFIED

Modifies the time value from ISINCE or IBEFORE to
select files according to their last modification date
(continued on next page)

o
4-1

DCl Commands and lexical Functions

o
Table 4-1 (Cont.)

Summary of New and Enhanced DCl Commands

Command

Enhancements

SET HOST/DTE

Now includes new qualifiers and subcommands that provide a greater ability to
control and customize the SET HOST/DTE operation. Specific enhancements
include the following:
Using DTEPAO, you can now control and customize the configuration of a
connection to a remote system through a terminal line.
New qualifiers let you select all configurational characteristics, such as XON
/XOFF flow control, the maximum number of buffers, read, delay, and parity.
A new interactive command mode lets you configure the SET HOST/OTE
session while the session is in progress.
The following new subcommands help you effectively control the SET HOST
/OTE operation:
CLEAR-Disconnects your local system from OTEPAO
EXIT-Returns the session to DCl emulation mode
QUIT-Disconnects your local system from OTEPAD
SAVE-Saves the current configuration settings
SEND BREAK-Sends a break to the remote system
SET OTE-Modifies characteristics of DTEPAO
SHOW DTE-Displays the configurable characteristics of DTEPAD
SPAWN-Creates a subprocess of your local process
See the VMS DeL Dictionary for complete information about the SET HOST/OTE
oomma~.

SET MAGTAPE

Now includes new /MEDIA_FORMAT qualifier, which controls data compaction on
a TA90E tape drive.

SET SYMBOL

Now includes the following new qualifiers to control symbol scoping: /All,
/GENERAl, and /VERB.

SET TERMINAL

Now includes a new value for the /DEC_CRT qualifier that sets characteristics for
the VT 400 family of terminals.

SHOW ACl

Now includes the new CAPABILITY keyword for the /OBJECT_TYPE qualifier,
which lets you display a system capability such as the ability to process vector
instructions.

SHOW CPU

New command that displays the current state of the processors in a VMS
multiprocessing system.

SHOW ZONE

New command that displays the current state of a VAXft 3000 system.

START/CPU

New command that starts a secondary processor in a VMS multiprocessing
system.

START/ZONE

New command that adds a zone to a running VAXft 3000 system.

STOP/CPU

New command that stops a secondary processor in a VMS multiprocessing
system.

STOP/ZONE

New command that removes a zone from a running VAXft 3000 system.

VIEW

Now accepts new PS input format, which lets you use the CDA Viewer to view
PostScript files (which use the file extension .PS). See Section 31.4.1 for additional
information.

4-2

~../

DCl Commands and lexical Functions

Table 4-2

Summary of New and Enhanced Lexical Functions

Lexical Function

Enhancements

F$CSID

New function that returns the cluster identification numbers for nodes in a cluster.

F$DEVICE

New function that returns the device names of devices on the system.

F$ENVIRONMENT

Now includes the following new item codes:
DISIMAGE
Reports whether you are logged into an account that
allows the RUN, MCR, or foreign commands.
RESTRICTED

Reports whether you are logged into a restricted account.

VERB_SCOPE

Reports the current verb scoping state.

F$GETDVI

Now includes the following new item codes:
Volume shadowing
Provide the volume-shadowing status of a device.
item codes

F$GETJPI

Includes the following new item codes:
Vector item codes
Provide information on the process's use of vector
processing.

Reports whether a terminal is a Digital CRT4 terminal.

Process rights item
codes

o
o

F$GETSYI

Provide information about the process's rights.

Now includes the new parameter cluster-id, which specifies the cluster node for
which information is to be returned.
Also includes the following new item codes:
ACTIVECPU_CNT
Returns the number of CPUs active in an SMP system.

F$TYPE

AVAILCPU_CNT

Returns the number of CPUs recognized by an SMP
system.

SYSTEM_RIGHTS

Contents of the system rights list.

Vector item codes

New item codes provide information about the vector
processors in the system.

Now includes the following new return values:
PROCESS_CONTEXT
Indicates whether a symbol was created by
the F$PID lexical function.
CLUSTER_SYSTEM_
CONTEXT

Indicates whether a symbol was created by
the F$CSID lexical function.

o
4-3

EVE Editor

This chapter describes the EVE Version 2.6 new features that are included
in Version 5.4 of the VMS operating system. See the revised VMS EVE
Reference Manual for more detailed information.

5.1

Box Editing
The new box editing feature lets you edit text using rectangular areas, or
boxes, as well as standard, linear ranges. For example, you can select
a box containing a list or columns in a table, and then cut and paste or
perform some other editing operation on the box. Table 5-1 lists the new
commands for box editing.
Table 5-1

o
c

EVE Box Editing Commands

Command

Usage

BOX COPY

Copies a box of text, without removing it, so you can
paste it elsewhere.

BOX CUT

Cuts a box of text so you can paste it elsewhere,
usually padding the area with spaces to keep the
column alignment of text to the right of the box.

BOX CUT INSERT

Cuts a box, making text to the right of the box
"collapse" to the left, closing the gap.

BOX CUT OVERSTRIKE

Cuts a box, padding the area with spaces to keep
the column alignment of text to the right of the box.

BOX PASTE

Pastes a box of text you copied or cut, usually,
overwriting existing text.

BOX PASTE INSERT

Pastes a box, pushing existing text to the right.

BOX PASTE OVERSTRIKE

Pastes a box, overwriting existing text.

BOX SELECT

Selects a box of text. Typically, you start at the
upper left corner of the box and move the cursor to
where you want the lower right corner.

RESTORE BOX SELECTION

Puts back (undeletes) a box erased with pending
delete, usually overwriting existing text.

SET BOX NOPAD

Disables padding and overstriking for box editing
unless the mode of the buffer is overstrike.

SET BOX NOSELECT

(Default.) Disables box selection, cutting, and
pasting. Commands such as SELECT, COPY,
REMOVE, and so on, use standard, linear ranges.
To edit boxes, use BOX commands.
(continued on next page)

5-1

EVE Editor
5.1 Box Editing

o
Table 5-1 (Cont.)

5.2

EVE Box Editing Commands

Command

Usage

SET BOX PAD

(Default.) Enables automatic padding and
overstriking for box editing, regardless of the mode
of the buffer.

SET BOX SELECT

Enables box selection, making commands such
as SELECT, REMOVE, and INSERT HERE the
same as the corresponding BOX commands, without
having to redefine keys.

New Command: CONVERT TABS
This command replaces tab characters with the appropriate number of
spaces. This is useful if your file will be printed or displayed on devices
with tab stops different from your settings in EVE.

5.3

New Qualifiers: IWORK and IINTERFACE
The !WORK qualifier (used with the EDIT/TPU command) determines the
work file that is used to swap memory, allowing you to edit very large files.
The !INTERFACE qualifier, which you use with the EDITITPU command
to specify either the character-cell or DECwindows interface, has been
added for compatibility with other DECwindows applications. It is
virtually the same as the /DISPLAY qualifier.

5.4

()
J.

. ...

Additional Sources of New EVE Information
In addition to reading the revised VMS EVE Reference Manual to learn
more about the new and changed features, you should also read the
section about EDIT/TPU in the VMS DeL Dictionary (particularly the
descriptions of the IJOURNAL and !RECOVER qualifiers) and review t h e - - · .
following online help topics within EVE:

Attributes

Names For Keys

Defaults

New Features

Journal Files

Pending Delete

List Of Topics

Ranges And Boxes

o
5-2

System Messages

This chapter lists the VMS facilities that have new or modified system
messages in Version 5.4 of the VMS operating system. There is also
information about installing and accessing an online Help version of the
VMS System Messages and Recovery Procedures Reference Manual.

6.1

VMS Facilities with New or Modified System Messages
The following VMS facilities have new or modified system messages in
Version 5.4 of the VMS operating system. Refer to the VMS System
Messages and Recovery Procedures Reference Manual for additional
information.

•
•

ANALDISK, AnalyzelDisk_Structure Utility
BACKUP, Backup Utility

• BUGCHECK, System Bugcheck

•
•
•
•

CDA, Compound Document Architecture
CLI, Command Language Interpreter (DCL)
DISMOUNT, DISMOUNT Command
FDL, CreateIFDL Utility

• FDL, EditIFDL Utility

•
•
•

JBC, Job Controller

•
•

MTH, Mathematics Facility

LMCP, Log Manager Control Program
MOUNT, Mount Utility
NCP, Network Control Program

• PTD, Pseudoterminal

•
•
•
•
•

REM, Set Host Facility
RMS, VMS Record Management Services
SDA, System Dump Analyzer
SET, SET Facility
SET PASSWORD Facility

• SYSBOOT, System Bootstrap Facility

•
•
•

SYSGEN, System Generation Facility
SYSTEM, VMS System Services
UETP, User Environment Test Package
6-1

System Messages
6.1 VMS Facilities with New or Modified System Messages

6.2

•

VAXTPU, VAX Text Processing Utility

•

Volume Processing Facility

System Messages Available from Online Help
With Version 5.4 of the VMS operating system, you can now install and
access an optional online Help version of the VMS System Messages and
Recovery Procedures Reference Manual. Because this is a large file, it is
not included as part of the default root library, SYS$HELP:HELPLIB.HLB.
You can access the file, named SYS$HELP:SYSMSGHELP.HLB, as follows:
•

Use the ILIBRARY qualifier with the HELP command. For example:
$

•

HELP/LIBRARY=SYS$HELP:SYSMSGHELP.HLB ERRORS ACCVIO

Define a logical name that instructs the Help Facility to search the
new help library when it it does not find the specified topic in the VMS
root help library. For example:
$
$

\~--~

DEFINE HLP$LIBRARY DISK$2: [QUAIL]SYSMSGHELP
HELP ERRORS DISMAL

In this example, the DEFINE statement creates a logical name for the
help library that the Help Facility is to search after it has searched
the root library, SYS$HELP:HELPLIB.HLB.
The Help Facility first searches the root library for ERRORS.
When it does not find error, l it then searches the library defined
by HLP$LIBRARY until it finds ERRORS and displays the appropriate
information. For information on defining logical names and search
patterns for the Help facility, see the HELP COMMAND in the VMS
DeL Dictionary.
•

(-\

Using the VMS Librarian Utility, you can extract the ERRORS module
from SYSMSGHELP.HLB and insert it into the default root help
library HELPLIB.HLB. This allows direct access without using extra
HELP qualifiers or logical names. For more information, see the VMS
Librarian Utility Manual.

o
~

The system messages help library is in compressed format. Decompressing
the library gives you faster access to it but requires an additional 1600
blocks of disk space. To decompress the library, enter a command similar
to the following:
$ LIBRARY/DATA=EXPAND/OUTPUT=device: [directory]SYSMSGHELP.HLB $ device: [directory]SYSMSGHELP.HLB

In this example, device is the name of the device where the file is located,
and directory is the name of the directory.

Note: The system messages help library is not decompressed when you
execute the LIBDECOMP.COM procedure described in the VMS
Version 5.4 Upgrade and Installation Manual.

Previous versions of HELPLIB.HLB provided information about system messages format under the name
ERROR. This information is now named FORMAT_OF_ERROR.

6-2

System Messages

6.2 System Messages Available from Online Help

You can use the VMS tailoring utility (VMSTAILOR) to add or delete the
system messages help library. Deleting this library does not affect the
other help libraries.

o
c

o
6-3

c
7

DECwindows User and Desktop Applications

This chapter describes new features of interest to DECwindows users.
These features include enhancements to the Session Manager, the CDA
Viewer, Calculator, Clock, and Mail.

7.1

Session Manager
Enhancements to the Session Manager include the addition of new
languages to the Customize language dialog box and the ability to
change your target screen, as described in Section 7.1.1 and Section 7.1.2
respectively.

7.1.1

Setting Another Session Language
The following languages have been added to the Customize Language
dialog box in the Session Manager:

•

Australian

• Austrian

•
•

Belgian Dutch
Belgian French

• Danish

•

Fiji

•
•
•
•
•

Finnish
Hebrew
New Zealand
Papua New Guinea
Portuguese

For more information about setting another session language, see the
Version 5.3 edition of the VMS DECwindows User's Guide.

7.1.2

Changing Your Target Screen
When you run an application or choose Print Screen on a workstation that
supports more than one screen display, by default DECwindows displays a
dialog box asking you which screen you want to use (see Figure 7-1).

7-1

DECwindows User and Desktop Applications
7.1 Session Manager

Figure 7-1

DECwindows Screen Number Dialog Box

Use Screen Number:

(1)0
OK

I Cancel Operation I

ZK-1959A-GE

If you want to use the same screen every time you run an application or
use PrintScreen, you can disable the screen number prompt and choose
your target screen. To disable the screen number prompt or change
your target screen, choose Screen Number... from the Session Manager's
Customize menu. The Session Manager displays the Customize Screen
Number dialog box (see Figure 7-2).
Figure 7-2

DECwindows Screen Number Dialog Box

Customize Screen Number
Application Display

o Prompt For Screen Number
Display On Screen:

(1)0

l~IEiJ
OK

Apply

Print Screen

I cancel I

o Prompt For Screen Number
Use Screen Number:

(1)0

~-\

()

01
ZK-1958A-GE

When you choose your target screen in the Customize Screen Number
dialog box, DECwindows will run applications (or PrintScreen) on the
screen you designated. If you click on the Prompt for Screen buttons,
DECwindows will not display the screen number dialog box.

7.2

CDA Viewer
The DECwindows CDA Viewer now lets you view PostScript files.
Section 7.2.1 describes how to view a PostScript file and Section 7.2.2
describes the new processing options available.

7-2

0
.

DECwindows User and Desktop Applications

7.2 CDA Viewer

7.2.1

Viewing a PostScript File
To view a PostScript file, select the CDA Viewer menu item from the
FileView Applications menu. In the Open window, click on PS in the File
Format box and then select the PostScript file you want to view.
From a DCL window, enter the VIEW command in the following format to
open a PostScript document for viewing:
VIEW filename.PS IFORMAT=PS IINTERFACE=DECWINDOWS

When you invoke the CDA Viewer from the DCL prompt, you do not need
to specify processing options for the PostScript files.
PostScript file viewing is supported only in the DECwindows CDA.Viewer
and only when running to displays with servers containing the Display
PostScript Extension. The CDA Viewer does not provide support for
PostScript files on character cell terminals.

When viewing a PostScript file, after you select or turn to a particular
page, you can click on the CDA Viewer Cancel button if you decide not to
view the page while it is being processed. The CDA Viewer immediately
stops processing that page.

7.2.2

New Processing Options for Viewing PostScript Files
In addition to the Default Paper Size option, new processing options
specific to viewing PostScript files are available in the Paper Size dialog
box. The additional PostScript options are highlighted, unless you already
chose PS as the file format to display.
These options are valid only for viewing PostScript files and are ignored
for all other file formats:

•

Orientation radio box
The Orientation radio box lets you select the orientation for displaying
PostScript files. By default, the CDA Viewer displays files in the same
portrait or landscape mode in which they were created. You can use
the Orientation radio box to select different orientations to view files
in reverse landscape mode or upside down.

•

Scale Factor option
The Scale Factor option lets you scale the page display size of your
PostScript file. The number you select indicates whether the CDA
Viewer will shrink or enlarge the page display. If the scale factor is
less than 1.0, the page display will shrink. If the number is greater
than 1.0, the page display will expand. You can specify a scale factor
in the range of 0.1 to 4.0 times the size of the original page display. By
default, a typical page display has a scale factor of 1.0.

• Use Comments toggle button
The Use Comments option specifies that the CDA Viewer should
interpret File structure comments that often appear in PostScript files.
This enables the CDA Viewer to detect the location of page breaks in a
PostScript file, for example.

7-3

DECwindows User and Desktop Applications

0,"

7.2 COA Viewer

I',

The Use Comments option is enabled by default. This is indicated by
the highlighted Use Comments toggle button.
You can disable the Use Comments option by clicking on it before
opening your PostScript file. This is recommended in instances where
the PostScript file contains comments that are not correct, causing the
CDA Viewer to either display the PostScript file incorrectly or generate
an error message. In most cases, disabling the Use Comments option
and reopening the file corrects the problem.
•

Use Bitmap Widths toggle button
The Use Bitmap Widths option adjusts the display of your PostScript
file for improved viewing on the screen. By default, a printed
PostScript file has a finer resolution, or more dots per inch, than a
~ostScripft fiple dIS'splayefidlon a lscreen · If youltry to vielwbthehPrinted
C~~)
lormat 0 a ost cript e on ine, t h e page ayout wi i e t e s a m e , / "
but the text may be dense and difficult to read.
To clarify your PostScript file for on line viewing, you can specify
the Use Bitmap Widths option so that the CDA Viewer will use
spacing formulas designed for bitmaps (screen images) instead of
those designed for print.
The Use Bitmap Widths option is disabled by default. If you select
the Use Bitmap Widths option, the next time you open a PostScript
file, the CDA Viewer will use bitmap widths to display your file. Text
characters will appear well spaced and easy to read. However, the
file may look slightly different on screen than it would when printed.
Columns may not be aligned precisely or a paragraph formatted for
right justification may appear instead with a ragged right margin.

•

0\,
" " ""

Use Fake Trays toggle button
The Use Fake Trays option lets you view a PostScript file that contains
tray size directives. Tray size directives are instructions that tell the
printer what paper tray size to use. These directives, however, are
specific to certain printers (such as the LPS40) and are not part of the
Display PostScript language.

0""/'
j

By default, the CDA Viewer ignores tray size directives if you try to
display a PostScript file that contains them. To override that default
behavior and view tray size directives in a PostScript file (to identify
occurrences of nonstandard PostScript, for example), click on the Use
Fake Trays option and reopen the file.
•

Watch Progress toggle button
The Watch Progress option lets you view a PostScript file while it is
being processed for display in the CDA Viewer window. You can view
a page as it is being processed, rather than waiting to view the entire
page after it has been processed.

o
7-4

DECwindows User and Desktop Applications
7.3 Calculator

7.3

Calculator
Calculator now has two additional modes: hexadecimal and octal. When
you first start the Calculator, it is in decimal mode. A new Mode menu
contains Hexadecimal and Octal menu entries for changing modes. The
keyboard display and functions change according to the mode.

7.4

Clock
Clock now has a menu bar with File, Customize, and Help menus for
interacting with Clock. The menu bar provides an alternative to the
previous method of pressing MB2 while pointing to the Clock display.
The only menu item under File is Quit. Choose Quit to exit from Clock.

The Customize menu lets you change the Clock display. The Customize
Menu has three menu items. The menu items correspond to the Settings ... ,
Save Settings, and Use System Settings previously available on a pop-up
menu. Choosing the Settings... menu item displays the Clock Settings
dialog box. The only change to the dialog box is the addition of a toggle
button for Menu Bar. By default, the Menu Bar button is shaded and the
menu bar is displayed. If you do not want the menu bar displayed, click
on the Menu Bar button.

Help is now available directly as a menu on the menu bar, rather than
from a pop-up dialog box.

7.5

Mail: Displaying PostScript Files
Mail can now display PostScript files, provided the files you send or receive
contain only PostScript language. A PostScript file always begins with a
percent sign and an exclamation point (%!). If any other text precedes the
%!, Mail cannot display the file. For example, when mail is forwarded,
additional text (in the form of extra mail headers) is often inserted at
the beginning of the file. Because this additional text precedes the %!,
Mail cannot display the PostScript file correctly. To avoid this problem,
use an editor to remove all headers before you forward a mail message in
PostScript format. Similarly, if you receive a PostScript file that does not
display properly, use an editor to remove all headers (or any other text
that precedes the %!), and forward the file to yourself. The file should then
display properly.

o
7-5

o
o

Part 3: System Management Features
This part contains the following chapters:
Chapter 8, AUTOGEN Command Procedure
Chapter 9, User Environment Test Package (UETP)
Chapter 10, SYSMAN Utility
Chapter 11, VAXcluster Management

Chapter 12, System Generation Utility (SYSGEN)
Chapter 13, Error Log Utility (ERROR LOG)
Chapter 14, System Security
Chapter 15, Log Manager Control Program Utility (LMCP)
Chapter 16, Monitor Utility (MONITOR)
Chapter 17, Network Control Program Utility (NCP)

o
c

Chapter 18, VMS Volume Shadowing Phase II

c
8

AUTOGEN Command Procedure

This chapter describes changes to the AUTOGEN command procedure in
Version 5.4 of the VMS operating system.

8.1

Parameter Name Validation
When AUTOGEN reads a parameter file such as MODPARAMS.DAT, it
now checks to determine if the parameter names specified in the file are
valid. If a parameter name is invalid, a warning message is written to
AGEN$PARAMS.REPORT (a new file described further in Section 8.2).
The following is an example of this warning message:

** WARNING ** - Invalid parameter name: LPRCOUNT
The following record is suspect:
LPRCOUNT = 34

AUTOGEN checks only the parameter name. It does not check the validity
of the value specified for the parameter.

If a parameter name is invalid, the line is not ignored. AUTOGEN
attempts to use the specified value.

A parameter name is not checked if it is specified in a line that contains
a DCL expression other than the symbol assignment (=). For example,
AUTOGEN does not check the validity of a parameter name specified in
a line with a DCL IF statement. Instead, AUTOGEN writes a warning
message to AGEN$PARAMS.REPORT. The following is an example of this
message:
** WARNING ** - DCL command detected

()

Parameter validation turned off for:
IF WINDOW SYSTEM = 1 THEN NPAGEDYN

8.2

250000

AGEN$FEEDBACK.REPORT Replaced by New File
The file SYS$SYSTEM:AGEN$FEEDBACK.REPORT has been replaced
by a new file called SYS$SYSTEM:AGEN$PARAMS.REPORT. This
new file includes all of the information previously contained in
AGEN$FEEDBACK.REPORT, as well as information about the nonfeedback parameters and additional messages. Many of the warning
and informational messages that AUTOGEN previously displayed on the
screen are now written to AGEN$PARAMS.REPORT.

o
8-1

AUTOGEN Command Procedure
8.2 AGEN$FEEDBACK.REPORT Replaced by New File

For example, when AUTOGEN finds multiple MIN_, MAX_, or ADD_
values for a single parameter, AUTOGEN writes a warning message to
AGEN$PARAMS.REPORT. The warning message includes the parameter
name, the value being used for the MIN_, MAX_, or ADD_ value, and
the value being superseded. The following are examples of this type of
message:
** WARNING ** - Multiple ADD records for ADD_LRPCOUNT found.
VMS value (300) combining with MODPARAMS value (400)
Value used is 700
** WARNING ** - Multiple MIN values found for MIN_LRPCOUNTV.
Using VMS value (1000) which is superseding MODPARAMS value (800)
** WARNING ** - Multiple MAX values found for MAX_SWAPFILE2_SIZE.
Using MODPARAMS value (1000) which is superseding VMS value (1200)

When AUTOGEN uses feedback information to calculate the value for a
new parameter, this information is written to AGEN$PARAMS.REPORT.
The following is an example of this type of message:
MAXPROCESSCNT parameter information:
Feedback information.
Old value was 41. New value is 50
Maximum Observed Processes: 35

When an AUTOGEN calculation is overridden by a value specified in a
parameter file, AUTOGEN writes a message to AGEN$PARAMS.REPORT.
This message includes the new parameter value and the reason why the
parameter was overridden. AUTOGEN will write this message for any
parameter value that overrides AUTOGEN's calculations, whether the
value is supplied by the system manager or by Digital. The following is an
example of this type of message:
LONGWAIT parameter information:
Override Information - parameter calculation has been overridden.
The calculated value was 30.
The new value is 10.
LONGWAIT has been disabled by a hard-coded value of 10.

8.3

MODPARAMS.DAT Includes External Parameter Files
To aid in cluster management, AUTOGEN can now read external
parameter files specified within MODPARAMS.DAT. This feature allows
system managers to maintain both clusterwide and system-specific
versions of AUTOGEN parameters.
To include a parameter file, place the following command in
MODPARAMS.DAT or in any subsequent parameter file:
AGEN$INCLUDE_PARAMS full-directory-specification:filename

Note: If an include statement is the first line in MODPARAMS.DAT,
AUTOGEN attempts to resolve all subsequent parameter settings.
For example, if AUTOGEN finds two MIN_ statements for the same
parameter, it uses the higher value. If the statements cannot be
resolved, AUTOGEN uses the parameter setting specified after the
include file.

8-2

AUTOGEN Command Procedure

8.3 MODPARAMS.DAT Includes External Parameter Files

The following is an example of a MODPARAMS.DAT that includes an
external parameter file:
! include system wide parameter settings

AGEN$INCLUDE_PARAMS SYS$COMMON: [SYSMGR]COMMON_CI_NODE MODPARAMS.DAT
MIN LRPCOUNT = 45
DUMPSTYLE = 0

This example reads the parameter file named
SYS$COMMON:[SYSMGR]COMMON_CI_NODE_MODPARAMS.DAT
before reading the parameters specified after the include statement in
MODPARAMS.DAT. If the included file in this example specified the
parameter setting DUMPSTYLE = 1, AUTOGEN would override this
setting with the statement DUMP STYLE = 0, which is specified after the
include statement in MODPARAMS.DAT.

The format of all included parameter files should be the same as
MODPARAMS.DAT. For information on MODPARAMS.DAT, see the
description of AUTOGEN in Guide to Setting Up a VMS System.

8.4

MIN_, MAX_, and ADD_ Values Allowed for Page and Swap Files
You can now control the size of page and swap files by specifying MIN_,
MAX_, and ADD_ values in a parameter file. The syntax for specifying
MIN_, MAX_, and ADD_ values is identical to that used with other
parameters.
For example, you can control the size of general page and swap files by
including one or more of the following lines in a parameter file:

()

PAGEFILE = 20000
ADD PAGEFILE
5000
MIN SWAPFILE = 1500
MAX SWAPFILE = 4000

You can also specify the sizes of individual page and swap files (including
secondary files) by including one or more of the following lines in a
parameter file:
SWAPFILE1 SIZE = 2000
ADD - PAGEFILE1 - SIZE
2000
MIN- PAGEFILE2 - SIZE = 3000
MAX- SWAPFILE3 - SIZE = 3000

Note: You cannot specify a MIN_, MAX_, or ADD_ value for both a general
page or swap file and a specific page or swap file.

o
8-3

AUTOGEN Command Procedure
8.5 New Feedback Parameters

8.5

New Feedback Parameters
The existing parameters LRPCOUNT and LNMSHASHTBL are now
feedback parameters. This means that AUTOGEN can set these
parameters using data collected in AUTOGEN feedback mode. You
should remove any values for LRPCOUNT and LNMSHASHTBL that are
specified in MODPARAMS.DAT, including MIN_, MAX_ and ADD_ values,
so that AUTOGEN can set these parameters using feedback information.

8.6

Logical Names Defined by AUTOGEN
To aid in system management, AUTOGEN defines three process logical
names to indicate how AUTOGEN was last run. These logical names
are assigned a character string value each time AUTOGEN is run on a
system. The following table lists and describes the logical names:

8.7

Logical Name

Description

AGEN$P1

The starting phase of AUTOGEN, for example, SAVPARAMS.

AGEN$P2

The end phase of AUTOGEN, for example, TESTFILES. If an error
occurred which caused AUTOGEN to abort, then "_E" is appended
to the phase name, for example, GENPARAMS_E.

AGEN$P3

The mode of execution, that is, either FEEDBACK or NOFEEDBACK.

(\
~...//

New Technique for Running AUTOGEN in Batch Mode
As of Version 5.2-1 of the VMS operating system, Digital recommends
a new technique for running AUTOGEN. This technique automates
AUTOGEN feedback, allowing the system manager to receive reports
from multiple systems on a regular basis. To use this technique, create a
batch-oriented procedure which runs AUTOGEN in two stages. A sample
command procedure is shown in Example 8-1.
The first stage of the command procedure runs AUTOGEN at peak
times to collect data on realistic system loads. The following command
accomplishes this task:
$ @SYS$UPDATE:AUTOGEN SAVPARAMS SAVPARAMS FEEDBACK

Executing this command does not affect the performance of the system.
The second stage of the command procedure runs AUTOGEN again during
off-peak hours to interpret the data collected in the first stage. The
following command accomplishes this task:
$ @SYS$UPDATE:AUTOGEN GETDATA TESTFILES FEEDBACK

The procedure sends the resulting report, contained in the file
AGEN$PARAMS.REPORT, to the SYSTEM account using the following
MAIL command:
$ MAIL/SUBJECT="AUTOGEN FEEDBACK REPORT FOR system-name" SYS$SYSTEM:AGEN$PARAMS.REPORT SYSTEM

8-4

AUTOGEN Command Procedure

8.7 New Technique for Running AUTOGEN in Batch Mode

Review this report on a regular basis to see whether the load on a system
has changed. If AUTOGEN's calculations are different from the current
values, correct the tuning by executing AUTOGEN with one of two
commands:
•

If the system can be shut down and rebooted immediately, execute the
following command:
$

•

If the system cannot be shut down and rebooted immediately, execute
the following command to reset the system parameters:
$

@SYS$UPDATE:AUTOGEN GETDATA SETPARAMS FEEDBACK

The new parameters will take effect the next time the system boots.
The sample command procedure shown in Example 8-1 will run
AUTOGEN in the new technique described. Use this procedure only
as an example; create a similar command procedure as necessary to meet
your requirements.
Example 8-1

@SYS$UPDATE:AUTOGEN GETDATA REBOOT FEEDBACK

Sample AUTOGEN Command Procedure

! ++++++++++ AGEN BATCH.COM ++++++++++
$ BEGIN$:
$ on warning then goto errorS
$
on error then goto errorS
on severe_error then goto errorS
$
$ on control_y then goto errorS
$!
$! Setup process
$!
$! Set process information
set process/priv=all/name="AUTOGEN Batch"
$
$! Keep log files to a reasonable amount
$ purge/keep=5 AGEN_Batch.log
$ time = f$time()
! Fetch current time
$ hour = f$integer (f$cvtime (time, , "hour")) ! Get hour
today = f$cvtime(time,,"WEEKDAY")
! Get Day of the week
$
$ if f$integer (f$cvtime (time, , "minute")) . ge. 30 then hour
$!
$! Start of working day ...
$!
$ lAM$:
$ if hour .le. 2
then
$
$
next time
"today+O-14"
$
gosub submitS
! Resubmit yourself
$
set noon

hour + 1

(continued on next page)

o
8-5

AUTOGEN Command Procedure
8.7 New Technique for Running AUTOGEN in Batch Mode

Example 8-1 (Cont.)

Sample AUTOGEN Command Procedure

$!
$!
$!
$

Run AUTOGEN to setparams using the parameter values collected earlier
in the day (i.e., yesterday at 2:00pm)
if today . eqs. "Tuesday" . OR. today . eqs. "Thursday" . OR. today .eqs. "Saturday"
$
then
$
@sys$update:autogen getdata testfiles feedback
$
mail/sub="Autogen Feedback Report for system-name" sys$system:agen$params.report system
$! Clean up
$
purge/keep=7 sys$system:agen$feedback.report
$
purge/keep=7 sys$system:agen$feedback.dat
$
purge/keep=7 sys$system:params.dat
$
purge/keep=7 sys$system:autogen.par
$
purge/keep=7 sys$system:setparams.dat
$
purge/keep=7 sys$system:agen$addhistory.tmp
$
purge/keep=7 sys$system:agen$addhistory.dat
$
endif
$
goto endS
$
endif
$!
$ 2PM$:
$ if hour .le. 15
$
then
$
next_time = "today+O-17"
$
gosub submitS
$
if today .eqs. "Monday" .OR. today .eqs. "Wednesday" .OR. today . eqs. "Friday"
$
then
$
@sys$update:autogen savparams savparams feedback
$
endif
$
goto endS
$
endif
$!
$ 5PM$:
$ if hour .le. 18
$
then
$
next time = "tomorrow+O-l"
$
gosub submitS
$
endif
$!
$! End of working day ...
$!
$ END$:
---------- BATCH.COM ---------$ exit
$!++
$! Subroutines
$!--

(continued on next page)

o
8-6

AUTOGEN Command Procedure

8.7 New Technique for Running AUTOGEN in Batch Mode

Example 8-1 (Cont.)

Sample AUTOGEN Command Procedure

$!
$ SUBMIT$:
$ submit/name="AGEN_Batch"/restart/noprint/log=AGEN_batch.log /queue=sys$batch/after=""next_time'" sys$system:AGEN batch.com
$ return
$!++
$! Error handler
$!-$ ERROR$:
$ mail/sub="AGEN BATCH.COM - Procedure failed." nl: system
$ goto endS

0 / 8.8
"

Using MAIL to Send AGEN$PARAMS.REPORT
After closing the AGEN$PARAMS.REPORT file, AUTOGEN now checks
for the existence of a file named SYS$UPDATE:AGEN$MAIL.COM. If this
file exists, it is executed from within AUTOGEN. (Note, however, that
AUTOGEN does not execute AGEN$MAIL.COM during VMS upgrades or
installations or after minimum system boots.)
You can use AGEN$MAIL.COM alone or with the batch-oriented procedure
described in Section 8.7 to send AGEN$PARAMS.REPORT to the SYSTEM
account or to an account of your choice. To do so, create a command
procedure named SYS$UPDATE:AGEN$MAIL.COM that includes the
following command:
$ MAIL/SUBJECT="AUTOGEN FEEDBACK REPORT FOR system-name" SYS$SYSTEM:AGEN$PARAMS.REPORT SYSTEM

If you use the AGEN$MAIL.COM procedure along with the batch-oriented
procedure described in Section 8.7, AGEN$MAIL.COM replaces the MAIL
command line in the batch-oriented command procedure.

o
8-7

,'
0
,

o
o

c
9

User Environment Test Package (UETP)

This chapter describes enhancements to the User Environment Test
Package (UETP) that are new for Version 5.4 of the VMS operating
system. For additional information about UETP, see the VMS Version 5.4
Upgrade and Installation Manual.

o
o

9.1

RRD40 Compact Disc Drive Support
With Version 5.4 of the VMS operating system, the User Environment Test
Package (UETP) now supports the following:

9.2

•

The RRD40 compact disc drive, including multiple RRD40 units

•

SCSI disk configurations that allow both read-only compact discs and
standard read/write disks to use the same device controller name

Vector Processing Support
With Version 5.4 of the VMS operating system, the User Environment
Test Package (UETP) now automatically loads and tests all installed and
enabled vector processors. It also lets you test the VAX Vector Instruction
Emulation Facility (VVIEF).
The vector processor device test, UETVECTOR.EXE, performs simple
vector-scalar and vector-vector arithmetic operations and compares the
results with expected values. The test also uses vector-related system
service extensions and forces the system to generate arithmetic and
memory management exceptions.
For information on using UETP to test vector processors and VVIEF, see
the VMS Version 5.4 Upgrade and Installation Manual. For complete
information about vector processing support, see Chapter 2.

o
9-1

,/'"--~

~--)

o
o

o
10 SVSMAN Utility
This chapter briefly describes enhancements to the VMS System
Management Utility (SYSMAN) that are new for Version 5.4 of the VMS
operating system. For complete information about these new features, see
the revised VMS SYSMAN Utility Manual.

10.1

The SYSMAN command @ now executes the specified SYSMAN command
procedure on each node in the environment.

10.2

o
o

Running a SVSMAN Command Procedure

Defining Keys with the DEFINE command
SYSMAN lets you define keys to execute SYSMAN commands. By defining
keys, you can avoid typing lengthy SYSMAN commands. You can also put
your key definitions in a SYSMAN initialization file, which executes each
time you invoke SYSMAN.

10.3

Spawning a Subprocess from Within SVSMAN
If you are in SYSMAN but want to leave temporarily to perform other
functions (such as displaying a directory listing or printing a file) and then
return to SYSMAN, you can use the SPAWN and ATTACH commands.
These commands function in much the same way as the DCL commands
SPAWN and ATTACH.

10.4

Usi ng DCl Verification
Using the SYSMAN command SET PROFILENERIFY, you. can set DCL
verification (both procedure and image) for future DO commands. This lets
you view the lines of DCL command procedures as they execute.

10.5

Using loadable Image Commands
Caution: SYS_LOADABLE commands are not intended for general use. Only
advanced system programmers should use these commands.

The SYS_LOADABLE command set adds and removes executive loaded
images from the list of images that are loaded by the SYSINIT process
during the bootstrap. This new feature is intended primarily for system
programmers to use when writing routines that implement site-specific
policies or special algorithms. These routines can either replace or
augment the built-in VMS policies.

10-1

SYSMAN Utility
10.5 Using Loadable Image Commands

In addition to consulting the VMS SYSMAN Utility Manual for a
more detailed description of the SYS_LOADABLE command set, see
Chapter 14 and Section 22.6 in this manual for related information about
implementing site-specific policies.

()

o
10-2

o
11

VAXcluster Management

This chapter describes enhancements to the following VAXcluster
components:

Computer interconnect (CD architecture extensions

•

Mass Storage Control Protocol (MSCP) server load sharing

•

Preferred path support for DIGITAL Storage Architecture (DSA) disks

See the revised VMS VAXcluster Manual for more information.

11.1

•

CI Architecture Extensions
Extensions to the computer interconnect (CD architecture allow the
application of multiple CI interfaces per CPU and multiple star couplers
per VAXcluster system. These extensions make possible VAXcluster
systems with many times the data throughput capacity of current
VAXcluster systems with a single star coupler.

11.2

MSCP Server Load Sharing
Beginning with Version 5.4 of the VMS operating system, Mass Storage
Control Protocol (MSCP) servers monitor their I/O traffic and periodically
calculate a Load Available rating to indicate available capacity for I/O
requests.

Load Available is calculated by counting the read and write requests sent
to the server and periodically converting this to requests per second and
subtracting this calculated value from the server's Load Capacity (also
specified in requests per second).
This information is communicated to the VMS Version 5.4 MSCP class
driver (DUDRlVER and DSDRlVER). When a disk is mounted or a failover
occurs, the class driver selects the server with the highest Load Available
rating to access the disk.
Load Balancing is enabled and controlled by the SYSGEN parameters
MSCP_LOAD and MSCP_SERVE_ALL. In most cases, the values
established by CLUSTER_CONFIG.COM are appropriate.

MSCP_SERVE_ALL determines whether the server participates in load
balancing. If it is set to 2 (serve only local disks), the server does not
monitor its 1/0 traffic and does not participate in load balancing. Other
valid settings for MSCP_SERVE_ALL (0, 1) result in the server monitoring
I/O traffic and communicating Load Available information to the class
drivers.

11-1

VAXcluster Management
11.2 MSCP Server Load Sharing

MSCP_LOAD is used to communicate Load Capacity to the server, in
addition to its existing function of controlling the loading of the MSCP
server. If it is set to 1, the MSCP server is loaded and its Load Capacity
is set to a default value based upon CPU type. If MSCP_LOAD is set to a
value greater than one, the server is loaded and its Load Capacity set to
that value.
As before, setting MSCP_LOAD to zero disables loading of the MSCP
server.

11.3

Preferred Path Support for DSA disks
The VMS Version 5.4 operating system lets you specify a preferred path
for DIGITAL Storage Architecture (DSA) disks. This includes RA series
disks and disks accessed through the MSCP server.

C_~

If a preferred path is specified for a disk, the MSCP disk class drivers
(DUDRIVER and DSDRIVER) uses the path as their first attempt to
locate the disk and bring it online as a result of a DCL MOUNT command
or fail over of an already mounted disk.
In addition, it is possible to initiate fail over of a mounted disk to force the
disk to the preferred path or to use load balancing information for disks
accessed via MSCP servers.
The preferred path is specified by a $QIO function IO$_SETPRFPTH,
with the PI parameter containing the address of a counted ASCII string
(.ASCIC). This string is the node name of the HSC or VMS system that
is to be the preferred path. The node name must match an existing node
known to the local node and, if it is a VMS system, it must be running the
MSCP server. This function does not move the disk to the preferred path.
For more information on the IO$_SETPRFPTH function, refer to the VMS
I/O User's Reference Manual: Part I.

(~~>
~

o
11-2

o
12

System Generation Utility (SYSGEN)

This chapter describes enhancements to the VMS System Generation
Utility (SYSGEN) that are new for Version 5.4 of the VMS operating
system.

12.1

o
o

SCSI NOAUTO Parameter
The VMS Version 5.4 operating system defines the special SYSGEN
parameter SCSI_NOAUTO for use with MicroVAX or VAXstation
configurations that include third-party Small Computer System Interface
(SCSI) devices. (See VMS Device Support Manual for more about SCSI
devices.) The SYSGEN parameter SCSI_NOAUTO replaces the SYSGEN
parameter VMSD 1.
SYSGEN's auto configuration facility automatically loads the VMS SCSI
disk or tape class driver for a device on the SCSI bus that identifies itself
as either a random-access or sequential-access device. If this SCSI device
is to be supported instead by the VMS generic SCSI class driver or a thirdparty SCSI class driver, the automatic loading of a VMS SCSI class driver
for the device must be disabled.
The SCSI_NOAUTO parameter, as shown in Figure 12-1, allows a
configuration including a SCSI third-party device to prevent the loading of
a VMS disk or tape SCSI class driver for any given device ID.

Figure 12-1

SCSI_NOAUTO System Parameter

o +- SCSI Device 10

+- SCSI Port 10
ZK-1371 A-GE

The SCSI_NOAUTO system parameter stores a bit mask of 32 bits, where
the low-order byte corresponds to the first SCSI bus (PKAO), the second
byte corresponds to the second SCSI bus (PKBO), and so on. For each
SCSI bus, setting the low-order bit inhibits automatic configuration of the
device with SCSI device ID 0; setting the second low-order bit inhibits
automatic configuration of the device with SCSI device ID 1, and so forth.
For instance, the value 0000200016 would prevent the device with SCSI
ID 5 on the bus identified by SCSI port ID B from being configured. By

12-1

System Generation Utility (SYSGEN)
12.1 SCSI NOAUTO Parameter

default, all of the bits in the mask are cleared, allowing all devices to be
configured.

12.2

LOAD PWD POLICY Parameter
The SYSGEN parameter LOAD_PWD_POLICY works in conjunction with
the SET PASSWORD Utility and with LOGINOUT (if you are forced to
change your password at login). This parameter controls whether or not
the SET PASSWORD Utility or LOGINOUT attempts to use site-specific
password policy routines, which are contained in the shareable image
SYS$LIBRARY:VMS$PASSWORD_POLICY.EXE. The default is O.
Installing and enabling a site-specific password policy image requires
both SYSPRV and CMKRNL privileges. To set the LOAD_PWD_POLICY
parameter, enter the following commands:

Ccc./

$
RUN SYS$SYSTEM:SYSGEN
SYSGEN>
USE ACTIVE
SYSGEN>
SET LOAD PWD POLICY 1
SYSGEN>
WRITE ACTIVE
SYSGEN>
WRITE CURRENT

To make the changes permanent, modify the system parameter file,
MODPARAMS.DAT so the parameter LOAD_PWD_POLICY is set
to 1.
For descriptions of site-defined password filters for the VMS Version 5.4
operating system, see Chapter 14 and Section 22.6.

12.3

LOAD- SYS- IMAGES Parameter
The LOAD_SYS_lMAGES parameter controls the loading of system images
described in the system image data file, VMS$SYSTEM_IMAGES.DATA.
Currently, you can replace three system services with services specific to
your site:
•

$ERAPAT-Generates a security erase pattern

•

$MTACCESS-Controls magnetic tape access

•

$HASH_PASSWORD-Applies a hash algorithm to an ASCII password

Section 22.6 describes how to create a system service image and how to
copy the image into the SYS$LOADABLE_IMAGES directory and add an
entry for it in the VMS system images file using the SYSMAN Utility.
After generating a new system image data file, you reboot the system to
load in your service.

If you have difficulty booting with the site-specific system services and
therefore do not want the site-specific system services loaded, you can set
the parameter of LOAD_SYS_IMAGES to 0 during SYSBOOT. The default
is 1.

12-2

System Generation Utility (SYSGEN)

12.4 Supported Device Names for VAXft 3000 Systems

12.4

Supported Device Names for VAXft 3000 Systems
With Version 5.4 of the VMS operating system, the System Generation
Utility (SYSGEN) supports the following device types in VAXft 3000
systems:
Code Name

o
12.5

Device Type

Environmental control monitor

DMA driver

Logical Ethernet driver

Physical Ethernet driver

DSSI disk driver

Logical DSF driver

Physical DSF driver

New SYSGEN Commands
This section describes the following new SYSGEN commands:

•

SHOW/BI=BIindex

•

SHOW/BUS=busld

•

SHOWIXMI=Blindex

o
12-3

SHOW/BI=Blindex

o
SHOW/BI=Blindex
The SHOW/BI=Blindex command displays device addresses that are currently
mapped in the 1/0 space for the VAXBI bus. It also displays node and nexus
numbers and generic names of UNIBUS and MASSBUS adapters, VAXBI
adapters, memory controllers, and interconnection devices such as the DR32
and CI.
Use of the SHOW/BI=Blindex command requires the CMEXEC privilege.

SHOW/BI=Blindex

FORMAT

(~\

~-_/

EXAMPLE
SYSGEN>

(CPU Type:

SHow/B1

VAX 8800

Cpu Connection: NM1

** Bus map for B1 00 on 28-FEB-1990 14:13:02.95 **
Address 20000000 (node 00) responds with value 0108 C1
Address 20004000 (node 02) responds with value 0106 B1 - NM1 Adapter (NB1B)
Address 2000EOOO (node 07) responds with value 0109 B1 Combo Board (DMB32)
** Bus map for B1 01 on 28-FEB-1990 14:13:03.00 **
Address 22000000 (node 00) responds with value 0102 UB
Address 22004000 (node 02) responds with value 0106 B1 - NM1 Adapter (NB1B)
Address 2200EOOO (node 07) responds with value 410F B1 - N1 Adapter (DEBNA»

The command in this example displays device addresses that are currently
mapped in the I/O space for the BI bus and additional information about
the BI bus adapters.

o
C)

o
12-4

SHOW/BUS=busld

c
SHOWIBUS=busld
The SHOW/BUS=busld command displays the buses and any subsequent
attached buses and all attached device node numbers, generic names of
processors, memory modules, adapters, VAXBI adapters, memory controllers,
and interconnection devices such as the NI.
Use of the SHOW/BUS command requires the CMEXEC privilege.

EXAMPLE
SYSGEN>

SHOW/BUS=busld

FORMAT

SHOW/BUS

Cpu Type: VAX 8800

Cpu Connection: NMI

Bus

Node

Generic Name

Nexus (hex)

BI 00
BI 00
BI 0

00
02
07

CI
BI - NMI Adapter (NBIB)
BI Combo Board (DMB32)

0000
0002
0007

BI 01
BI 01
BI 01

00
02
07

UB
BI - NMI Adapter (NBIB)
BI - NI Adapter (DEBNA)

0010
0012
0017

Connection Address

The command in this example displays information about all the adapters
on the system buses.

o
12-5

SHOW/XMI=Blindex

c
SHOW/XMI=Blindex
The SHOW/XMI=Blindex command displays device addresses that are
currently mapped in the I/O space for the XMI bus. It also displays node and
nexus numbers and generic names of processors, adapters, VAXBI adapters,
memory controllers, and interconnection devices such as the NI.
Use of the SHOW/XMI=Blindex command requires the CMEXEC privilege.

FORMAT

SHOW/XMI=Blindex

EXAMPLE
SYSGEN>

SHOW/XMI

** Bus map for XMI 00 on 28-FEB-1990 14:14:50.48 **

Address
Address
Address
Address
Address
Address
Address
Address
Address
Address
Address
Address
Address
Address

21880000
21900000
21980000
21AOOOOO
21A80000
21BOOOOO
21B80000
21COOOOO
21C80000
21DOOOOO
21D80000
21EOOOOO
21E80000
21FOOOOO

(node
(node
(node
(node
(node
(node
(node
(node
(node
(node
(node
(node
(node
(node

01)
02)
03)
04)
05)
06)
07)
08)
09)
OA)
OB)
OC)
OD)
OE)

responds
responds
responds
responds
responds
responds
responds
responds
responds
responds
responds
responds
responds
responds

with value
with value
with value
with value
with value
with value
with value
with value
with value
with value
with value
with value
with value
with value

8082
8082
8082
8082
8082
4001
4001
4001
4001
4001
4001
OC03
2001
2001

XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI
XMI

6000-400 processor
6000-400 processor
6000-400 processor
6000-400 processor
6000-400 processor
memory module
memory module
memory module
memory module
memory module
memory module
NI adapter (DEMNA)
BI Adapter (DWMBA/A)
BI Adapter (DWMBA/A)

The command in this example displays device addresses that are currently
mapped in the I/O space for the XMI bus and additional information about
the XMI bus adapters.

o
12-6

o
13

Error Log Utility (ERROR LOG)

This chapter describes enhancements to the VMS Error Log Utility
(ERROR LOG) that are new for Version 5.4 of the VMS operating system.

13.1

Supported Device Types for VAXft 3000 Systems
With Version 5.4 of the VMS operating system, the Error Log Utility
supports the following device types in VAXft 3000 systems:

Code Name

o
13.2

Device Type

Environmental control monitor

DSF32

Synchronous communications adapter

DMA driver

Logical Ethernet driver

Physical Ethernet driver

DSSI disk driver

RF31

DSSI fixed hard disk

Logical DSF driver

Physical DSF driver

TF70

DSSI magnetic tape drive

New Keywords for IEXCLUDE and IINCLUOE Qualifiers
The IEXCLUDE and /INCLUDE qualifiers accept new device-class and
entry-type keywords, described in the following table:

Device-Class Keyword

Function

ADAPTER

Includes or excludes entries for adapter errors

CACHE

Includes or excludes entries for memory caching
errors

INFORMATIONAL

Includes or excludes error log entries such as media
quality reports from magnetic tape devices

VECTOR

Includes or excludes entries for vector processing
errors

Entry-Type Keyword

Function

CONFIGURATION

Includes or excludes entries that describe system
configuration

13-1

Error Log Utility (ERROR LOG)
13.2 New Keywords for IEXCLUOE and IINCLUOE Qualifiers

13.3

Entry-Type Keyword

Function

SYNDROME

Includes or excludes VAX 9000 console-generated
entries that provide encoded syndrome values used
by Customer Services

New Qualifier: INODE
The Error Log Utility now accepts the INODE qualifier. This qualifier
enables you to generate a report consisting of error log entries for specific
nodes in a VAXcluster.

FORMAT

INODE

=(node-name[, ...J)

Parameter
node-name

Specifies the names of one or more VAXcluster members. Names cannot
exceed six characters. If more than one node name is entered, you must
specify a comma-separated list of node names enclosed in parentheses.
Example
$

ANALYZE/ERROR_LOG/NODE=(ORANGE,NASSAU) ERRLOG.OLD;72

In this example, a VAXcluster includes members ORANGE, PUTNAM, and
NASSAU. The output consists of only those entries that were logged for
VAXcluster members ORANGE and NASSAU.

o
13-2

c
14

System Security

This chapter describes new features of the VMS Version 5.4 operating
system that system managers can use to enhance the security of their
systems. The following sources contain related information as well:

o
14.1

•

Chapter 4 (of this manual) and the VMS DeL Dictionary (SET ACL
and SHOW ACL)

•

Section 10.5 (using loadable image commands within SYSMAN)

•

Section 12.2 and Section 12.3 (relevant SYSGEN parameters)

•

Chapter 22 (new and modified system services; implementing sitespecific security policies)

Site-Defined Password Policy
Starting with the VMS Version 5.4 operating system, passwords selected
by users can be screened for acceptability. The VMS system automatically
compares new passwords against a system dictionary to ensure that a
password is not a native language word. It also maintains a history list of
a user's passwords and compares each new password against this list to
guarantee that an old password is not reused. Sites can screen passwords
further by developing and installing an image that filters passwords for
words that are particularly sensitive to the installation.

In addition, a site with contractual obligations to use special algorithms
for encrypting passwords will be able to use them.

This chapter describes these security enhancements. For descriptions of
security-related system services new for the VMS Version 5.4 operating
system, see Chapter 22.

14.1.1

Screening New Passwords
Sites that choose to let users select their own passwords rather than
use the password generator can now screen user-selected passwords. As
of Version 5.4, the VMS system automatically compares new passwords
against a system dictionary, which is stored in SYS$LIBRARY, to ensure
that a password is not a native language word. The VMS system also
maintains a list of all the passwords a user has had during the year and
compares each new password against this history list to guarantee that an
old password is not reused.

Both the dictionary and the history search can be disabled through the
Authorize Utility. You disable the dictionary search with the DISPWDDIC
option to the IFLAGS qualifier; you disable the history search with the
DISPWDHIS option to the !FLAGS qualifier.

14-1

System Security

14.1 Site-Defined Password Policy

14.1.1.1

Password History List
VMS keeps a year's worth of data in the password history list. If
the password limit is exceeded, the system forces a user to accept
generated passwords. By default, the list stores 60 passwords. A security
administrator can change the defaults for the length of time passwords are
retained and the maximum number of passwords per user.
System Logical Name

Default

SYS$PASSWORD_HISTORY_LIFETIME
SYS$PASSWORD_HISTORYJIMIT

Min

Max

Units

365

28000

days

2000

absolute count

Using the DCL command DEFINE, you can change the defaults for the
capacity and lifetime of the password history list. For example, to increase
the capacity of the history list from 60 passwords to 100, you would add
the following line to the command procedure SYLOGICALS.COM, which is
located in SYS$MANAGER:
$ DEFINE/SYSTEM/EXEC SYS$PASSWORD_HISTORY_LIMIT 100

There is a correspondence between the lifetime of a password history list
and the number of passwords allowed on the list. For example, if you
increase the password history lifetime to four years and your passwords
expire every two weeks, you would need to increase the password history
limit to at least 104 (4 years times 26 passwords a year). The password
history lifetime and limit can be changed dynamically, but they should be
consistent across all nodes on the cluster.
Sites using secondary passwords might need to double the password limit
to account for the secondary password storage.
The password history list is located in SYS$SYSTEM. The list can be
redirected off the system disk using the logical name VMS$PASSWORD_
HISTORY. This logical name should also be defined ISYSTEM/EXEC and
placed in SYS$MANAGER: SYLOGICALS. COM.
14.1.1.2

Site-Specific Filter
Security administrators can develop a site-specific password filter to
ensure that passwords are not words readily associated with their site, for
example, product names or personnel names. A filter can also check for
particular character variations.

To create a list of site-specific words, you write the source code, create
a shareable image, install the image, and, finally, enable the policy
by setting a SYSGEN parameter. See Section 22.6 for step-by-step
instructions. Installing and enabling a site-specific password filter requires
both SYSPRV and CMKRNL privileges. In addition, if INSTALL and
SYSPRV file access auditing are enabled, multiple security alarms are
generated when the password filter image is installed and the required
change to the SYSGEN parameter is noted on the operator console.

14-2

System Security

14.1 Site-Defined Password Policy

The shareable image contains two global routines that are called by the
VMS Set Password Utility whenever a user changes a password.

Warning: The two global routines allow a security administrator to obtain
both the proposed plaintext password and its equivalent quadword
hash value. All security administrators should be aware of this
feature as its subversion by a malicious privileged user will
compromise your system's security.
Digital recommends that you place security alarm ACEs on the
password filter image and its parent directory. See Section 22.6 for
instructions.

o
o

14.1.2

Specifying a Password Algorithm
The VMS operating system protects passwords from disclosure through
encryption. VMS algorithms transform passwords from plaintext strings
into cipher text, which is then stored in the user authorization file (UAF).
Whenever a password check is done, the check is based on the encrypted
password, not the plaintext password. The system password is always
encrypted with an algorithm known to the VMS system.
The /ALGORITHM qualifier in the Authorize Utility allows you to define
which algorithm the VMS system should use to encrypt a user's password,
both primary and secondary. Your choices are the current VMS algorithm
or a site-specific algorithm. The syntax is as follows:
IALGORITHM=keyword=type [=value]

Table 14-1 lists all the keywords and types you can specify with the
/ALGORITHM qualifier.

To assign the VMS password encryption algorithm for a user, you would
enter the following command.
UAF>

MODIFY HOBBIT/ALGORITHM=PRIMARY=VMS

If a site-specific algorithm is selected, you must give a value to identify the
algorithm.
UAF>

MODIFY HOBBIT/ALGORITHM=CURRENT=CUSTOMER=128

Section 22.6.1 provides directions for using a customer algorithm. You
must create a site-specific $HASH_PASSWORD in which you define an
algorithm number. This number has to correspond with the number used
in the AUTHORIZE command MODIFY/ALGORITHM.
Whenever a user is assigned a site-specific algorithm, the Authorize Utility
reports this information in the display provided by the SHOW command.

o
14-3

System Security
14.1 Site-Defined Password Policy

Table 14-1

Arguments to the / ALGORITHM Qualifier

Keyword

Function

BOTH

Set the algorithm for primary and secondary passwords.

CURRENT

Set the algorithm for the primary, secondary, both, or no
passwords depending on account status. Current is the default
value.

PRIMARY

Set the algorithm for the primary password only.

SECONDARY

Set the algorithm for the secondary password only.

Type

Definition

VMS

The algorithm used in the version of VMS that is running on your
system.

CUSTOMER

A numeric value in the range 128-255 identifies a customer
algorithm.

o
o

o
14-4

c
15

Log Manager Control Program Utility (LMCP)

The Log Manager Control Program Utility (LMCP) is a component of
DECdtm services residing within the VMS Version 5.4 operating system.
The log manager ensures that, as each transaction is processed, a record
of each transaction state is recorded in a log file on disk.
The DECdtm transaction manager invokes the log manager to write these
transaction records as necessary, ensuring that a consistent transaction
outcome is achieved even in the event of a system failure. Writing log
records is necessary for the consistent recovery of the transaction-specific
data.

This chapter describes how a system manager can use the Log Manager
Control Program Utility (LMCP) to create and manage transaction log
files, and it provides a complete description of all the LMCP commands.
See Chapter 3 for a complete overview of DECdtm services.

15.1

Managing Transaction Log Files
To optimize the execution of distributed transactions on your system, you
need to consider a number of factors relating to transaction log files. This
section discusses these factors, providing recommendations and guidelines
in the following areas:

•

U sing the SYS$JOURNAL logical name

•

Where to place a transaction log file

•

How VAXcluster failover works

•

Determining the initial size required for a transaction log file

•

Creating a transaction log file

•

Resizing a transaction log file

Note: To use LMCP commands, you must have SYSPRV privilege. To use
the LMCP command CONVERT, you must have CMKRNL privilege.
It is assumed throughout this section that system managers or
other individuals who have these privileges will be implementing
the procedures described herein.

15.1.1

Defining SYS$JOURNAL
The logical name SYS$JOURNAL defines the directory location
where DECdtm services expect to find log files. SYS$JOURNAL is
a system-table, executive-mode logical name, normally defined in the
SYS$STARTUP:SYLOGICALS.COM command procedure.
If SYS$JOURNAL is not defined in SYS$STARTUP:SYLOGICALS.COM,
then a default logical name value is defined as SYS$COMMON:[SYSEXE].

15-1

Log Manager Control Program Utility (LMCP)
15.1 Managing Transaction Log Files

You can define SYS$JOURNAL using the following command format:
DEFINE/SYSTEM/EXEC SYS$JOURNAL device:[directory]

The logical name SYS$JOURNAL can be defined as a search list. For
example, the following command defines a search list consisting of two
directories.
$

DEFINE/SYSTEM/EXEC SYS$JOURNAL DISK1: [LOGFILES], DISK2: [LOGFILES]

This example shows DISK1:[LOGFILES] to be the primary, or local,
directory that DECdtm services always search first. DISK2:[LOGFILES]
is the secondary directory, DECdtm services search this directory after the
directory DISK1:[LOGFILES] is searched. If you create a transaction log
file using the LMCP CREATE command, then the log file is placed in the
first directory DISK1:[LOGFILES].
If a transaction log file is created on a different node using
DISK2:[LOGFILES] as the primary-or local-directory and
DISK1:[LOGFILES] as the secondary directory, then the search list
should specify the local log file directory first. Thus, the following
command defines a search list consisting of two directories, where
DISK2:[LOGFILES] is the local directory and the first to be searched
by DECdtm services:
$

DEFINE/SYSTEM/EXEC SYS$JOURNAL DISK2: [LOGFILESJ, DISK1: [LOGFILESJ

If you create a transaction log file using the LMCP CREATE command,
then the log file is placed in the first directory DISK2:[LOGFILES].

15.1.2

\_-)

()

Placing a Transaction Log File
Transactions cannot be started until you have created a transaction
log file, using the LMCP CREATE command. But before you create
a transaction log file, you should consider where to locate it for best
performance on your system.
A log file can be placed on any file-structured device that is available to
the processor. The following list includes possible alternate locations for
log files, in the recommended order:
1

Shadowed nonsystem disk

N onsystem disk

Shadowed system disk

System disk

For increased performance, follow the general guidelines for installing a
secondary page/swap file. Use a high-performance, HSC-based disk that
has little activity.
You should also take into account the following considerations when
locating a log file:
•

15-2

Shadowed versus nonshadowed disk

Log Manager Control Program Utility (LMCP)

15.1 Managing Transaction Log Files

Because a transaction log file is almost exclusively write-only
during normal processing, a shadowed disk may be slower than a
nonshadowed disk. However, a shadowed disk provides increased data
availability in the event of media failure.
•

Although a disk on a local node can provide higher performance,
particularly in an NI-based VAXcluster, if that VAXcluster member
node fails, other nodes in the VAXcluster will not be able to access the
failed nodes disk. (See Section 15.1.3.) Therefore, it is better if disks
are mounted VAXcluster-wide and correctly defined using the logical
name SYS$JOURNAL. That way, if a node fails, other nodes can still
access the failed nodes disk.

In a VAXcluster, log files should be placed on disks accessible to all
members of the VAXcluster. This practice facilitates VAXcluster fail over
by making the log files on each VAXcluster member node available to other
VAXcluster members.

15.1.3

o
c

Local versus cluster disk

VAXcluster Failover
VAXcluster failover is a mechanism that DECdtm services provide to
enable VAXcluster nodes to perform recovery for a member node that has
failed.
To make VAXcluster fail over work, you need to correctly define
SYS$JOURNAL (as described in Section 15.1.1) so that DECdtm services
can locate all transaction log files in use in the VAXcluster.
VAXcluster failover only occurs within a VAXcluster environment and
is completely automatic and transparent to applications and resource
managers using DECdtm services. VAXcluster failover starts when a
VAXcluster member node fails and holds information that surviving
VAXcluster member nodes need to process their transactions.
When VAXcluster failover is initiated, recovery proceeds while the failed
node is rebooting. This allows other nodes that need information from the
failed node to resolve transactions. It also allows resource managers to
release locks on database records without waiting for the failed node to
reboot.
Normally, each VAXcluster member node is primarily responsible for
accessing its own transaction log file. Any node that requires information
from a log file it does not have open must send a request for that
information to the VAXcluster node member that currently has the log
file open-the node normally responsible for that log file.

During VAXcluster failover, the first requesting node that requires
information from a failed node opens the failed node's transaction log
file to perform recovery. This action lets recovery on the failed node's
log file begin while the failed node is rebooting. Normally, transaction
recovery on the log file completes before the failed node has rebooted.
Therefore, nodes that had their transactions blocked by the failure of the
VAXcluster node have their transactions resolved before the failed node

15-3

Log Manager Control Program Utility (LMCP)

15.1 Managing Transaction Log Files

reboots. The surviving VAXcluster members proceed as if the failed node
had already rebooted.
Once a VAXcluster member node has opened the log file of a failed node,
all further requests from other VAXcluster member nodes are directed to
the node that has opened the log file. Only one VAXcluster member node
can access a failed node's log file at anyone time. When the failed node
has rebooted, it reacquires access to its log file and requests are passed to
that rebooted VAXcluster node member once again.

15.1.4

Determining Transaction Log File Size
Use the LMCP CREATE command to create transaction log files. The
ISIZE qualifier of this command specifies the size of the log file in blocks.
By default, the file size is 4000 blocks. However, since performance of
transaction processing applications depend on transaction logging, Digital
recommends that you plan ahead when creating log files.
A number of factors must be considered when estimating transaction
log file requirements. These factors include the rate of transactions
executed per second and the duration of the transactions. As a quick way
to estimate log file size, Digital recommends the following algorithm:
Transaction start rate*Transaction duration*40 = log file size in disk blocks

You can use the MONITOR TRANSACTION command of the Monitor
Utility to determine the start rate and duration for transactions already
executing on your system. (See Section 16.1 for more information about
the MONITOR TRANSACTION command.)

()

For example, if the start rate is 5 transactions per second and the duration
is 10 seconds, the calculation is:
5 * 10 * 40 = 2000 blocks

The recommended file size for a log file in this example is 2000 blocks.
Due to a number of factors, file size requirements can vary widely from one
system to the next. Therefore, the guidelines listed here for determining
log file size can provide only very rough estimates. When planning for log
files, it is recommended that you overestimate, rather than underestimate,
the file size.

15.1.5

Creating Transaction Log Files
Transactions cannot be started until a transaction log file exists. By
default, processes for DECdtm services are started when a full VMS
boot is executed. 1 The DECdtm process TP_SERVER then checks for the
existence of a transaction log file on the system and continues checking
every 15 seconds for the existence of a transaction log file on the system
so that recovery can occur automatically, even if a log file's disk is not
available when the system first boots.

-----------------------1

If you do not want to run DECdtm software, you can prevent the startup of DECdtm processes by defining
the systemwide logical name SYS$DECDTM_INHIBIT. See the note at the beginning of Chapter 3 for more
information.

15-4

Log Manager Control Program Utility (LMCP)

15.1 Managing Transaction Log Files

To create a log file, use the LMCP CREATE command. Before creating a
log file, you should understand the recommendations for placing and sizing
log files, as described in Section 15.1.2 and Section 15.1.4.
A log file must be named with the file name SYSTEM$node-name, where
node-name is the name of the node on which the log file will be used. For
example, a log file created on node ORANGE should be given the file name
SYSTEM$ORANGE. The default file type is LM$JOURNAL.
The default file specification for the log file is:
SYS$JOURNAL: .LM$JOURNAL

15.1.6

Example of Creating a Transaction Log File
This section summarizes the steps involved in creating transaction log files
for a sample VAXcluster system.

o
o

In this example, the conditions are as follows:
•

The sample VAXcluster consists of two nodes, RED and BLUE, with
shared access to the devices named DISK1 and DISK2.

•

The system manager wants to set up an initial configuration
of transaction log files that allows DECdtm services to perform
VAXcluster failover.

•

The system manager needs to create two log files, one for each node.

•

The system manager has determined that the initial log file size will be
1000 blocks on node RED and 2000 blocks on node BLUE. Figure 15-1
shows the desired configuration.

o
15-5

Log Manager Control Program Utility (LMCP)
15.1 Managing Transaction Log Files

Figure 15-1

Sample Transaction Log File Configuration on Two-Node VAXcluster

VAX

BLUE

o
o
[LOGFILES]SYSTEM$RED.LM$JOURNAL

[LOGFILES]SYSTEM$BLUE.LM$JOURNAL

(1,000 Blocks)

(2,000 Blocks)
ZK-1894A-GE

Based on the conditions established for this example, the system manager
would follow these steps to configure the VAXcluster:
1

15-6

On node RED, the system manager would establish a search list for log
files by adding the following line to the SYS$STARTUP:SYLOGICALS
command procedure:

Log Manager Control Program Utility (LMCP)
15.1 Managing Transaction Log Files

c
$

DEFINE/SYSTEM/EXEC SYS$JOURNAL DISKl: [LOGFILES], DISK2: [LOGFILES]

On node BLUE, the system manager would define a similar search
list for transaction log files by adding the following line to the
SYS$STARTUP:SYLOGICALS command procedure. Because the
CREATE command creates a log file in the first directory pointed to
by SYS$JOURNAL, this search list will specify the local node log file
directory first.

DEFINE/SYSTEM/EXEC SYS$JOURNAL DISK2: [LOGFILES], DISKl: [LOGFILES]

Assuming that SYS$JOURNAL is defined, the system manager
would then create the log files for each node using the LMCP
CREATE command. On node RED, for example, the system manager
would enter the following LMCP command to create the log file
SYSTEM$RED.LM$JOURNAL with the desired file size:
LMCP>

If SYS$JOURNAL has not been defined, all transactions will abort
until the DECdtm services locate the transaction log file. Therefore,
in this case, the system manager would also need to specify the device
and directory when creating the log file. For example:
LMCP>

CREATE LOGFILE/SIZE=1000 DISKl: [LOGFILES]SYSTEM$RED

The system manager would then repeat a similar procedure on node
BLUE by entering following LMCP command to create the transaction
log file SYSTEM$BLUE.LM$JOURNAL with the desired log file size:
LMCP>

15.1.7

CREATE LOGFILE/SIZE=1000 SYSTEM$RED

CREATE LOGFILE/SIZE=2000 SYSTEM$BLUE

Resizing and Moving Transaction Log Files
If transaction processing performance degrades on your system (indicated
by the rate of transaction stalls), you might need to use the LMCP
CONVERT command to increase the size of the transaction log file, or
you might need to move the log file to a higher performance disk.

To check for the rate of transaction stalls, use the LMCP command SHOW
LOG/CURRENT, which displays information about the currently active
transaction log file. This display shows the number of checkpoints
and stalls that have occurred since DECdtm services were started and
indicates whether a checkpoint or stall is currently in progress.
Checkpoints are normal, regular, log manager events that are used to
maintain the log file during transaction execution; they do not indicate
degradation in log file performance.

The log manager stalls transactions when insufficient space is available
in the log file for correct and successful transaction execution. A high
rate of stalls or a permanent stall condition indicates that the log file size
should be increased. In such a case, use the LMCP command CONVERT
to increase the size of the log file. Occasional stall events might be caused
by transitory system activities such as VAXc1uster transition events and
do not necessarily indicate a permanent shortage of space in the log file.

15-7

Log Manager Control Program Utility (LMCP)
15.1 Managing Transaction Log Files

You can also use the Monitor Utility to check for transaction processing
degradation.
The necessary capacity for a log file depends on the number of
simultaneous transactions and other factors. Because these factors are
variable, Digital cannot recommend the amount of increased size for a
transaction log file. You should estimate the percentage of increased
transaction workload that caused the log to stall.
Prior to moving or resizing a log file, the system manager must do the
following:
1

Disable the transaction log file.
The log file should be disabled before the system is rebooted so that
DECdtm services will not re-open the log file after the reboot. The
recommended method of disabling a log file is to rename it so that
it cannot be found by DECdtm services. Rename the log file with
the file type LM$OLD. For example, if the original log file is called
SYS$JOURNAL:SYSTEM$ORANGE.LM$JOURNAL, it should be
renamed SYS$JOURNAL:SYSTEM$ORANGE.LM$OLD.

-"
C

Reboot the system.
A reboot is necessary because DECdtm services are an integral part
of the VMS Executive and cannot be started or stopped independently
of the VMS operating system. Because of this requirement, serious
considerations should be given to the initial configuration of log files.

U·
' _ ..

After these steps have been completed successfully, the system manager
must perform the following convert procedure to change the size of the
transaction log file:
1

Use the LMCP command CONVERT to move the transaction records
from the old log file to the new log file and increase its size. Name the
new file SYSTEM$node-name.LM$JOURNAL.

If the convert is successful, delete the old log file.

The system manager can move the log file to an alternate location by
following these steps:
1

Edit SYS$STARTUP:SYLOGICAL8.COM on all nodes in the
VAXcluster to include a new definition for the logical name
SYS$JOURNAL, as follows:
$ DEFINE/SYSTEM/EXEC SYS$JOURNAL device: [directory]

Reboot the system.

Copy the log file to the new location, using the following command:
$
$

15-8

COpy DEVICE: [DIRECTORY]SYSTEM$node-name.LM$OLD SYS$JOURNAL: SYSTEM$node-name. LM$JOURNAL

If the copy is successful, delete the old log file.

Log Manager Control Program Utility (LMCP)
15.2 Format of Transaction Log Files

C\
,I

15.2

Format of Transaction Log Files
A transaction log file consists of a file header, section headers, and
transaction records.
A log file header contains information about the log file, such as its
version number, size, unique identifier, and checkpoints. Checkpoints
are mechanisms that bound the search for active transaction records.
Therefore, in the event of a system failure, the log manager can efficiently
locate the active transaction records needed for system recovery. (An
active transaction is one that has not completed.)

o
o

A log file is organized into sections and each section has a section header
containing information about its own characteristics. This information is
used by the log manager to find and read transaction records efficiently.
The transaction record header identifies the record number and
information about the transaction, such as the transaction's state and
its unique transaction identifier (TID). A transaction can be in any of three
states:
•

PREPARED-The transaction is in a state where it can be either
committed or rolled back.

•

COMMITTED-The transaction manager has enough information
to complete the transaction even though the participants in the
transaction have not finished all their operations.

•

FORGOTTEN-The participants have enough information to
complete processing the transaction and will no longer ask about
the transaction. Therefore, the transaction can be forgotten.

The transaction record data gives information about the DECdtm version
number, the log identifier, and the name and type of resource manager the
transaction is involved with.
Example 15-1 shows a portion of a sample transaction log file.

o
15-9

Log Manager Control Program Utility (LMCP)
15.2 Format of Transaction Log Files

Example 15-1

Sample Transaction Log File

Dump of log file DISKl: [MASTER.JOURNALS]SYSTEM$BLUE.LM$JOURNAL;l
End of file block 4000 / Allocated 4000
Log Version 1.0
..
Log File UID:
9D519DCO-698E-0092-DF95-00000000B20D (21-JUN-1989 09:19:44.54)
Penultimate Checkpoint: 00000012C45E 005E
Last Checkpoint:
000000133E39 0039
Dump of log file DISK1: [MASTER.JOURNALS]SYSTEM$BLUE.LM$JOURNALi1
Present Length:
166 (000000A6) Last Length:
512 (00000200)
VBN Offset:
2503 (000009C7) Virtual Block:
2505 (000009C9)
Section:
4 (00000004)

Record number 3 (00000003)~, 77 (004D) bytes ~
Transaction state (1): PREPARED
Transaction ID: 2B065A40-6E88-0092-EC42-00000000B208 ~ (27-JUN-1989 17:16:11.62)
DECdtm Services Log Format V1.0
Type (3): LOCAL RM ~
Log ID:OOOOOOOO-OOOO-OOOO-OOOO-OOOOOOOOOOOO ~
Name (6): "SERVER" 0(5245 56524553)
Type (4): PARENT NODE ~ Log ID:6900BCOO-6B4F-0092-C8BD-00000000B208 ~
Name (10): "SYSTEM$RED" 0 (4445 52244D45 54535953)

CD
tt

.. Log header-Contains information about the log's characteristics.

4t Section header-The section header of multiple transaction records.
@) Record number-A unique record number in decimal and hexadecimal.

•

Record size-The record size in decimal and hexadecimal.

CD Transaction state-The three states a transaction can be in are
PREPARED, COMMITTED, and FORGOTTEN.

o Transaction ID (TID)-Each transaction has its own unique

transaction identifier assigned by the transaction manager.
•

DECdtm services version number-The software version number of
DECdtm services.

@) Participant type-The types of participant in the transaction.

Participant types include:
•

CHILD NODE-A subordinate transaction manager

•

PARENT NODE-The immediate parent transaction manager

•

LOCAL RM-The recoverable resource manager on the local node

o Participant name-The name of the participant in the transaction,
also given in hexadecimal.

41> Log ID-A unique hexadecimal log identifier the participant uses to
write its own recovery records.

15-10

0·.'

Log Manager Control Program Utility (LMCP)

15.2 Format of Transaction Log Files

In Example 15-1, the fields labeled. comprise the log header,. comprise
the section header, 6) through CD comprise the record header, and.
through I) comprise the record data.

o
o

o
15-11

o
LMCP Usage Summary
The Log Manager Control Program is a VMS utility that lets you create and
maintain log files of transaction records.

FORMAT

$ RUN SYS$SYSTEM:LMCP

usage summary

To invoke LMCP, enter the following DCL command:
$

RUN SYS$SYSTEM: LMCP

LMCP returns the following prompt:
LMCP>

At the LMCP> prompt, you can enter LMCP commands. To exit LMCP,
enter EXIT at the LMCP> prompt, or press CtrllZ.
You can also execute a single LMCP command by using a DCL string
assignment statement, as shown in the following example:
$

LMCP : == $LMCP
LMCP SHOW LOGFILE SYSTEM$YELLOW

In this example, LMCP executes the SHOW command and returns control
to DCL.
To use LMCP commands, you must have SYSPRV privilege. To use the
LMCP command CONVERT, you must have CMKRNL privilege.

o
15-12

c
LMCP Commands
This section describes the following LMCP commands and provides
examples of how to use them:

• CONVERT

•

CREATE

• DUMP
• HELP
• REPAIR, including the following REPAIR subcommands:
ABORT
COMMIT
EXIT
FORGET
HELP
NEXT

•

SHOW

o
15-13

LMCP
CONVERT

CONVERT
Converts a log file on a given node by transferring the active transaction
records from the specified source log file to the specified destination log file.
To use the CONVERT command, you need CMKRNL privilege.

FORMAT

PARAMETER

CONVERT LOGFILE

source_filespec
destination_filespec
[qualifier...J

source_filespec
Specifies the file specification of the log file from which active transaction
records are to be copied.

destination_filespec
Specifies the file specification of the log file where active transaction
records are to be written.

QUALIFIERS

IOWNER=owner id

()

Associates an owner oruser identification code (UIC) with the log file
to be created. You specify the UIC using the standard VIC format as
described in the VMS DCL Concepts Manual. The default VIC is one of
the following:
•

The owner UIC of an existing version of the file if the file creator has
extended privileges

•

The owner VIC of the parent directory if the file creator has extended
privileges

•

The owner UIC of the creator

ISIZE=file size
Specifies the size of the log file in blocks. The minimum log file size
is 100 blocks.

DESCRIPTION

Use the CONVERT command to resize a log file. For example, if
transaction processing performance degrades on your system, then
you may need to increase the log file size. See Section 15.1.7 for more
information about resizing and moving log files.

c
15-14

LMCP
CONVERT

c
EXAMPLE
LMCP>

CONVERT LOGFILE SYSTEM$RED.LM$OLD SYSTEM$RED/SIZE=8000

This command transfers all active transaction records from the log file
SYSTEM$RED.LM$OLD to SYSTEM$RED and specifies a log file size of
8000 blocks.

o
c

o
15-15

LMCP
CREATE

CREATE
Creates a log file for a specific node.

FORMAT
PARAMETER

CREATE LOGFILE

filespec [qualifier... ]

filespec
Specifies the file specification of the log file to be created. DECdtm services
expect the file name to be in the format SYSTEM$node-name, where
node-name is the name of the node that will use the log file.

QUALIFIERS

INEW VERSION

Creates new version of a log file if a log file with an identical specification
already exists. The new log file is created with the same name and type
but with a version number one higher than the highest existing version.
Note that, once the new version of the transaction log file is created, then
any transaction records in the previous log cannot be accessed.
If the /NEW_VERSION qualifier is specified for a log file that does not
exist, no new file will be created. Instead, an error will be returned.

IOWNER=owner id
Associates an owner or user identification code (VIC) with the log file to
be created. Specify the VIC using the standard VIC format as described
in the VMS DCL Concepts Manual. The default VIC will be one of the
following:
•

The owner VIC of an existing version of the file if the file creator has
extended privileges

•

The owner VIC of the parent directory if the file creator has extended
privileges

•

The owner VIC of the creator

ISIZE=file size
Specifies the size of the log file in blocks. The minimum log file size
is 100 blocks, and the default log file size is 4000 blocks.

DESCRIPTION

By default, log files are created in the directory specified by
SYS$JOVRNAL, with a file extension of LM$JOVRNAL and a size of
4000 blocks. To identify the name of the node that will use the log file, the
file name must be in the following format:
SYSTEM$node-name

15-16

LMCP

CREATE

EXAMPLES

LMCP>

CREATE LOGFILE SYSTEM$BLUE/OWNER=GONZALES/SIZE=4400

This command creates a log file called SYSTEM$BLVE.LM$JOVRNAL,
associates it with user GONZALES and specifies a file size of 4400 blocks.
~

LMCP>

CREATE LOGFILE SYSTEM$YELLOW/OWNER= [USER, FRED] /SIZE=4000

This command creates a log file called SYSTEM$YELLOW.LM$JOVRNAL,
associates it with the VIC group USER, member FRED, and specifies a log
file size of 4000 blocks.
LMCP>

CREATE LOGFILE SYSTEM$BLUE/NEW_VERSION/OWNER=GONZALES/SIZE=4400

This command creates a new log file that supersedes the current highest
version of SYSTEM$BLUE.LM$JOVRNAL and is given a version number
one higher. Also, the new log file is associated with user GONZALES and
specifies a file size of 4400 blocks.

c
15-17

LMCP

DUMP

DUMP
Displays (or "dumps") the contents of a specified log file.

FORMAT
PARAMETER

DUMP

filespec [qualifier.. .]

filespec
Specifies the file specification of the log file.

QUALIFIERS

IACTIVE
Specifies that only records relating to active transactions within the log
file are to be displayed.

IFORMAT(default)
INOFORMAT
Displays the contents of the log file as formatted records. If the
INOFORMAT qualifier is specified, only the log file header is displayed.

IHEX
Specifies that the contents of the log file dump are displayed as ASCII
characters and hexadecimallongwords. Use both the INOFORMAT and
/HEX qualifiers to format a DUMP operation in hexadecimal only.

ILOGID=log_identifier
Specifies the log identifier, in hexadecimal format, associated with a
specific resource manager. The ILOGID qualifier can be used only in
conjunction with the IRM qualifier.

IOUTPUT[=filespec1
Specifies that the output is written to the file specified. By default,
the DUMP command writes the output to SYS$OUTPUT. If you enter
/OUTPUT with no file specification, LMCP_DUMP is the default file name
and LIS is the default type.

IRM=rm identifier
Selects thetransactions to be displayed according to the resource manager
participating in the transaction. The argument supplied for the rm_
identifier can be either the ASCII character string for the resource
manager name or its hexadecimal equivalent. When specifying a
hexadecimal string, you must prefix the characters %X to the hexadecimal
string.
If a partial resource manager name is supplied as the argument for the
rm_identifier, LMCP selects all resource managers having names that
begin with the supplied string.

15-18

LMCP

DUMP

ISTATE=transaction state
Selects the transactions to be displayed according to their transaction
states. A value of either PREPARED or COMMITTED can be supplied
as an argument to the /STATE qualifier. If the /STATE qualifier is not
supplied, all transactions records are selected.

ITID=transaction id
Selects the transactions to be displayed according to the transaction
identifier. The argument supplied for the transaction_id must be a
hexadecimal character string.

DESCRIPTION

If you entered the DUMP command, the contents of the log file you
specified are displayed. By default the log file records are displayed as
formatted records.

EXAMPLES
D

LMCP>

DUMP SYSTEM$BLUE/HEX/NOFORMAT

Dump of log file DISK1: [MASTER.JOURNALSjSYSTEM$BLUE.LM$JOURNAL;2
End of file block 4000 / Allocated 4000
Log Version 1.0
Log File UID:
9D519DCO-698E-0092-DF95-00000000B20D (21-JUN-1989 09:19:44.54)
Penultimate Checkpoint: 00000012C45E 005E
Last Checkpoint:
000000133E39 0039
Dump of log file DISK1: [MASTER. JOURNALSj SYSTEM$BLUE. LM$JOURNAL; 2
Present Length:
68 (00000044) Last Length:
512 (00000200)
VBN Offset:
2504 (000009C8) Virtual Block:
2506 (000009CA)
Section:
3 (00000003)
Record number 1 (00000001), 48 (0030) bytes
Transaction state (2):
COMMITTED
Transaction ID: 2B065A40-6E88-0092-EC42-00000000B208 (27-JUN-1989 17:16:11.62)
01000000 00B20842 EC00926E 882B065A 40020030 O.. @Z.+.n .. iB . ..... 0000
00060000 00000000 00000000 00000000 00000300 . . . . . . . . . . . . . . . . . . . . 0014
00305245 56524553 SERVERO.
0028
Dump of log file DISK1: [MASTER.JOURNALSjSYSTEM$BLUE.LM$JOURNAL;2
Present Length:
166 (000000A6) Last Length:
512 (00000200)
VBN Offset:
2503 (000009C7) Virtual Block:
2505 (000009C9)
Section:
4 (00000004)
Record number 3 (00000003), 77 (004D) bytes
Transaction state (1):
PREPARED
Transaction ID: 2B065A40-6E88-0092-EC42-00000000B208 (27-JUN-1989 17:16:11.62)
01000000 00B20842 EC00926E 882B065A 4001004D M.. @Z.+.n .. iB.' ..... 0000
00060000 00000000 00000000 00000000 00000300 . . . . . . . . . . . . . . . . . . . . 0014
00B208BD C800926B 4F6900BC 00045245 56524553 SERVER .. l;,j.iOk .. El,,;,.,
0028
00 4D444552 244D4554 53595300 OAOOOOOO .... . SYSTEM$REDM.
003C

Record number 2 (00000002), 21 (0015) bytes
Transaction state (0): FORGOTTEN
Transaction ID: 2A6DC3CO-6E88-0092-EC42-00000000B208 (27-JUN-1989 17:16:10.62)
15000000 00B20842 EC00926E 882A6DC3 C0000015 ... AAm*.n .. iB.
0000
00 .
0014

15-19

LMCP

DUMP

Record number 1 (00000001), 48 (0030) bytes
Transaction state (2):
COMMITTED
Transaction ID: 2A6DC3CO-6E88-0092-EC42-00000000B208 (27-JUN-1989 17:16:10.62)
01000000 00B20842 EC00926E 882A6DC3 C0020030 O.. Mm*.n .. iB.: ..... 0000
00060000 00000000 00000000 00000000 00000300 . . . . . . . . . . . . . . . . . . . . 0014
00305245 56524553 SERVERO.
0028

This command produces a dump-in hexadecimal format-of the specified
log file.
~

LMCP>

DUMP SYSTEM$BLUE/HEX/OUTPUT=EXAMPLE

This command writes a dump-in hexadecimal format-of the specified log
file to the file EXAMPLE.LIS.

LMCP>

DUMP SYSTEM$PURPLE/ACTIVE

Dump of log file DISK1: [MASTER.JOURNALSJSYSTEM$PURPLE.LM$JOURNAL;l
End of file block 4000 / Allocated 4000
Log Version 1.0
Log File UID:
2F99A820-BAB2-0092-9310-00000000B1FE ( 2-0CT-1989 15:28:26.53)
Penultimate Checkpoint: 000000000000 0000
Last Checkpoint:
000000010BD9 01D9
Transaction state (2):
COMMITTED
Transaction ID: 84C67760-BAB2-0092-8243-00000000B1FE ( 2-0CT-1989 15:30:49.43)
DECdtm Services Log Format V1.0
Type (3): LOCAL RM
Log ID: 00000000-0000-0000-0000-000000000000
Name (11): "THREAD_5.29" (39322E 355F4441 45524854)
Type (2): CHILD NODE
Log ID: 748FFOCO-B52A-0092-9011-00000000B204
Name (13): "SYSTEM$ORANGE" (45 474E4152 4F244D45 54535953)
Transaction state (2):
COMMITTED
Transaction ID: 84C1E380-BAB2-0092-8243-00000000B1FE ( 2-0CT-1989 15:30:49.40)
DECdtm Services Log Format V1.0
Type (3): LOCAL RM
Log ID: 00000000-0000-0000-0000-000000000000
Name (11): "THREAD_4.29" (39322E 345F4441 45524854)
Type (2): CHILD NODE
Log ID: 748FFOCO-B52A-0092-9011-00000000B204
Name (13): "SYSTEM$ORANGE" (45 474E4152 4F244D45 54535953)

Total of 2 transactions active, 0 prepared and 2 committed.

This command displays a dump of all active transactions of the specified
log file.

IJMCP>

DUMP SYSTEM$GREEN/STATE=PREPARED

Dump of log file DISK1: [MASTER.JOURNALSJSYSTEM$GREEN.LM$JOURNAL;l
End of file block 4000 / Allocated 4000
Log Version 1.0
Log File UID:
748FFOCO-B52A-0092-9011-00000000B204 (25-SEP-1989 14:34:14.86)
Penultimate Checkpoint: 00000002DDB7 01B7
Last Checkpoint:
00000002FC41 0241
Dump of log file DISK1: [MASTER.JOURNALSjSYSTEM$GREEN.LM$JOURNAL;l
Present Length:
169 (OOOOOOA9) Last Length:
512 (00000200)
VBN Offset:
380 (0000017C) Virtual Block:
382 (0000017E)
Section:
2 (00000002)

15-20

LMCP

DUMP

Record number 3 (00000003), 80 (0050) bytes
Transaction state (1):
PREPARED
Transaction ID: F30CAF60-BA84-0092-8FA6-00000000B24B ( 2-0CT-1989 10:04:37.59)
DECdtm Services Log Format V1.0
Type (3): LOCAL RM
Log 10: 00000000-0000-0000-0000-000000000000
Name (6): "SERVER" (5245 56524553)
Type (4): PARENT NODE Log ID: 68165820-BA84-0092-FC95-00000000B24B
Name (13): "SYSTEM$ORANGE" (45 474E4152 4F244D45 54535953)
Dump of log file DISK1: [MASTER.JOURNALS]SYSTEM$GREEN.LM$JOURNAL;l
Present Length:
100 (00000064) Last Length:
512 (00000200)
VBN Offset:
379 (0000017B) Virtual Block:
381 (00000170)
Section:
3 (00000003)

Record number 1 (00000001), 80 (0050) bytes
Transaction state (1):
PREPARED
Transaction 10: F2F8D940-BA84-0092-8FA6-00000000B24B ( 2-0CT-1989 10:04:37.46)
DECdtm Services Log Format V1.0
Type (3): LOCAL RM
Log ID: 00000000-0000-0000-0000-000000000000
Name (6): "SERVER" (5245 56524553)
Type (4): PARENT NODE Log ID: 68165820-BA84-0092-FC95-00000000B24B
Name (13): "SYSTEM$ORANGE" (45 474E4152 4F244D45 54535953)

Dump of log file DISK1: [MASTER. JOURNALS] SYSTEM$GREEN.LM$JOURNAL; 1
Present Length:
100 (00000064) Last Length:
0 (00000000)
VBN Offset:
0 (00000000) Virtual Block:
2 (00000002)
Section:
376 (00000178)
Record number 1 (00000001), 80 (0050) bytes
Transaction state (1): PREPARED
Transaction ID: 809D5600-BA84-0092-8FA6-00000000B24B ( 2-0CT-1989 10:01:25.60)
DECdtm Services Log Format V1.0
Type (3): LOCAL RM
Log ID: 00000000-0000-0000-0000-000000000000
Name (6): "SERVER" (5245 56524553)
Type (4): PARENT NODE Log ID: 68165820-BA84-0092-FC95-00000000B24B
Name (13): "SYSTEM$ORANGE" (45 474E4152 4F244D45 54535953)

This command displays a dump of all prepared records of the specified log
file.
LMCP> DUMP SYSTEM$GREEN/TID=FAC21DE2-BA88-0092-8FA6-00000000B24B/ACTIVE
Dump of log file DISK1: [MASTER. JOURNALS] SYSTEM$GREEN.LM$JOURNAL; 1
End of file block 4000 / Allocated 4000
Log Version 1.0
Log File UID:
68165820-BA84-0092-FC95-00000000B24B ( 2-0CT-1989 10:00:44.45)
Penultimate Checkpoint: 0000000711D3 13D3
Last Checkpoint:
000000072742 1542

Transaction state (2):
COMMITTED
Transaction ID: FAC21DE2-BA88-0092-8FA6-00000000B24B ( 2-0CT-1989 10:33:28.51)
DECdtm Services Log Format V1.0
Type (3): LOCAL RM
Log ID: 00000000-0000-0000-0000-000000000000
Name (11): "THREAD 13.4" (342E33 315F4441 45524854)
Total of 2 transactions active, 0 prepared and 2 committed.

This command displays a dump of the record for the specified active
transaction. (If the transaction is not active, only the active transaction
count number is displayed.)

15-21

LMCP

HELP

HE·LP
Provides information about LMCP commands and parameters.

HELP

FORMAT
PARAMETER

[help-topic [help-subtopic]]

help-topiC
Specifies the command to be explained.

help-subtopic
Specifies the qualifier to be explained.

EXAMPLES
D LMCP> HELP
Information available:
CONVERT
REPAIR

CREATE
SHOW

Description

DUMP

EXIT

HELP

This command invokes help and displays all commands for which further
information exists.

LMCP>

HELP CREATE

CREATE
Creates a log file.
Format:
CREATE LOGFILE filespec [qualifier ... J

('\.

Additional information available:
filespec
/OWNER
Example

qualifiers
/SIZE

This command provides a description of the CREATE command.

o
15-22

LMCP
REPAIR

o
REPAIR

Selects records within a log file so that transactions can be repaired by having
their transaction states changed. Once the transaction records have been
selected, REPAIR subcommands can be used to change the transaction
states.

Note: Because the REPAIR command lets you change transaction
states locally without regard to the global state, you must use
this command with caution. If you do not change all necessary
characteristics of a transaction record, the transaction could be
placed in an inconsistent state, resulting in potential data loss.

FORMAT
PARAMETER

REPAIR

filespec [qualifier...]

filespec
Specifies the file specification of the log file containing the transaction
records to be repaired.

QUALIFIERS

ILOGID=log_ identifier
Specifies the log identifier, in hexadecimal format, associated with a
specific resource manager. The ILOGID qualifier can be used only in
conjunction with the IRM qualifier.

IRM=rm identifier

Selects the transactions to be repaired according to the resource manager
participating in the transaction. The argument supplied for the rm_
identifier can be either the ASCII character string for the resource
manager name or its hexadecimal equivalent. When specifying a
hexadecimal string, you must prefix the characters %X to the hexadecimal
string.
If a partial resource manager name is supplied as the argument for the
rID_identifier, LMCP selects all resource managers having names that
begin with the supplied string.

ISTATE=transaction state
Selects the transactions to be repaired according to their transaction
states. A value of either PREPARED or COMMITTED can be supplied
as an argument to the ISTATE qualifier. If the 1STATE qualifier is not
supplied, all active transactions (both PREPARED and COMMITTED) are
selected.

ITID=transaction id

Selects the transactions to be repaired according to the transaction
identifier. The argument supplied for the transaction_id must be a
hexadecimal character string.

15-23

LMCP
REPAIR

DESCRIPTION

The REPAIR command allows you to manually modify active transaction
records in a log file.
When you enter the REPAIR command, LMCP enters the REPAIR
command mode and produces a listing of the log file's contents, as selected
by the specified REPAIR command qualifier. Each transaction record is
displayed sequentially so that you can modify its characteristics. After
each record in the filtered log file is displayed, the REPAIR> prompt
returns. You can then enter REPAIR subcommands to change the
transaction states of specific records. The REPAIR subcommands are
as follows:
ABORT
COMMIT
EXIT
FORGET
HELP
NEXT
Once you finish modifying a transaction record, you can use the REPAIR
subcommand NEXT to advance to the next sequential record in the file.
To return to the LMCP> prompt, you must exit the REPAIR command
mode by entering the EXIT subcommand or by pressing CtrllZ.
The sections that follow the REPAIR command examples describe each of
the REPAIR subcommands.

l~
___...

EXAMPLES

LMCP>

REPAIR SYSTEM$ORANGE/STATE=PREPARED/RM=LOGL

This command selects all PREPARED transaction records in the log file
SYSTEM$ORANGE. It specifies that only records from participating
resource managers having names beginning with "LOGL" are to be
selected.
~

c._-\.).

LMCP> REPAIR SYSTEM$ORANGE/RM=LOGLOAD LMCP> /LOGID=68165820-BA84-0092-FC95-00000000B24B

This command selects all active transaction records in the log file
SYSTEM$ORANGE. It specifies that only records with a participating
resource manager called LOGLOAD and associated log identifier of
68165820-BA84-0092-FC95-00000000B24B are to be selected.
~

LMCP>

REPAIR SYSTEM$ORANGE/RM=%X534552564552

This command selects all active transaction records in the log file
SYSTEM$ORANGE. It specifies that only records from a participating
resource manager with a hexadecimal name 534552564552 are to be
selected.

15-24

LMCP

REPAIR

LMCP> REPAIR SYSTEM$ORANGE LMCP> /TID=8C689380-BA84-0092-8FA6-00000000B24B

This command selects the active transaction record in the log file
SYSTEM$ORANGE. It specifies that only the record for the transaction
with a hexadecimal TID 8C689380-BA84-0092-8FA6-00000000B24B is to
be selected.

c
o

c
15-25

REPAIR
ABORT

ABORT
Changes the state of a transaction from PREPARED to ABORTED.

FORMAT

ABORT

EXAMPLE
LMCP>

REPAIR SYSTEM$RED

Dump of log file DISK$MASTER: [MASTER.JOURNALS]SYSTEM$RED.LM$JOURNAL;l
End of file block 4000 / Allocated 4000
Log Version 1.0
Log File UID:
748FFOCO-B52A-0092-9011-00000000B204 (25-SEP-1989 14:34:14.86)
Penultimate Checkpoint: 000000073E2D 042D
Last Checkpoint:
000000077D7C 037C

(~----"\

~-)

Transaction state (1): PREPARED
Transaction ID: FACFD981-BA88-0092-8FA6-00000000B24B ( 2-0CT-1989 10:33:28.60)
DECdtm services V1.0
Type (3): LOCAL RM
Log ID: 00000000-0000-0000-0000-000000000000
Name (6): "SERVER" (5245 56524553)
Type (4): PARENT NODE Log ID: 68165820-BA84-0092-FC95-00000000B24B
Name (13): "SYSTEM$ORANGE" (45 47 4E4152 4F24 4D4 5 54535953)
REPAIR> ABORT
REPAIR> EXIT
LMCP>

The initial REPAIR command selects all active transaction records in
the log file SYSTEM$RED. The ABORT subcommand changes the state
of the presented transaction from PREPARED to ABORTED. The EXIT
subcommand exits the REPAIR command mode.

(" )
\.

o
15-26

REPAIR
COMMIT

c
COMMIT

Changes the state of a transaction from PREPARED to COMMITTED.

FORMAT

COMMIT

EXAMPLE
LMCP>

REPAIR SYSTEM$RED

Dump of log file DISK$MASTER: [MASTER. JOURNALS] SYSTEM$RED.LM$JOURNAL; 1
End of file block 4000 / Allocated 4000
Log Version 1.0
Log File UID:
748FFOCO-B52A-0092-9011-00000000B204 (25-SEP-1989 14:34:14.86)
Penultimate Checkpoint: 000000073E2D 042D
Last Checkpoint:
000000077D7C 037C

Transaction state (1): PREPARED
Transaction ID: FACFD981-BA88-0092-8FA6-00000000B24B ( 2-0CT-1989 10:33:28.60)
DECdtm Services Log Format V1.0
Type (3): LOCAL RM
Log ID: 00000000-0000-0000-0000-000000000000
Name (6): "SERVER" (5245 56524553)
Type (4): PARENT NODE Log ID: 68165820-BA84-0092-FC95-00000000B24B
Name (13): "SYSTEM$ORANGE" (45 474E4152 4F244D45 54535953)
REP AI R> COMMI T
REPAIR> EXIT
LMCP>

The initial REPAIR command selects all active transaction records in
the log file SYSTEM$RED. The COMMIT subcommand changes the
state of the transaction from PREPARED to COMMITTED. The EXIT
subcommand exits the REPAIR command mode.

o
15-27

REPAIR
EXIT

EXIT
Exits the REPAIR command mode and returns the LMCP> prompt.

FORMAT

EXIT

o
15-28

REPAIR

FORGET

FORGET
Specifies that a transaction with a state of COMMITTED can be forgotten,
which means the committed transaction record can be removed from the log
file.

FORMAT

FORGET

EXAMPLE
LMCP>

REPAIR SYSTEM$RED

Transaction state (2): COMMITTED
Transaction ID: F2F8D940-BA84-0092-8FA6-00000000B24B ( 2-0CT-1989 10:04:37.46)
DECdtm Services Log Format V1.0
Type (3): LOCAL RM
Log ID: 00000000-0000-0000-0000-000000000000
Name (10): "THREAD_6. 4" (342E 365F4441 45524854)
REPAIR> FORGET
REPAIR> NEXT

The initial REPAIR command selects all active transaction records in
the log file SYSTEM$RED. The FORGET subcommand specifies that the
transaction can be forgotten. The NEXT subcommand advances to the
next record.

o
15-29

REPAIR

HELP

HELP
Provides information about REPAIR subcommands and parameters.

HELP

FORMAT
PARAMETER

[help-topic [help-subtopic]]

help-topic
Specifies the subcommand to be explained.

help-subtopic
Specifies the qualifier to be explained.

EXAMPLES

REPAIR>

HELP

REPAIR
SUBCOMMANDS
Entering the REPAIR command produces a listing of the log file's
contents, as selected by the optional REPAIR command qualifiers. Each
transaction record is displayed sequentially, so that a user can modify
its characteristics.

After each record in the filtered log file is displayed,
the REPAIR> prompt is returned.
A user can then issue REPAIR
subcommands to change the transaction states of specific records.
A user must issue a NEXT subcommand to advance to the next sequential
record in the file.
To return to the LMCP> prompt, a user must exit the REPAIR command
mode by entering the EXIT subcommand or by pressing Ctrl/Z.

Additional information available:
ABORT

COMMIT

EXIT

FORGET

This command invokes help and displays all subcommands for which
further information exists.

o
15-30

REPAIR

HELP

REPAIR>

HELP ABORT

REPAIR
SUBCOMMANDS
ABORT
Changes the state of a transaction from PREPARED to ABORTED.
Format:
ABORT

This command provides a description of the ABORT subcommand.

o
15-31

REPAIR

NEXT
Advances to the next record in a transaction log.

FORMAT

o
15-32

LMCP

SHOW

SHOW
Lists information about transaction log files.

FORMAT
PARAMETER

SHOW LOGFILE

filespec [qualifier.. .]

filespec
Specifies one or more log files to be listed. The syntax of the file
specification determines which files will be listed, as follows:

o
QUALIFIER

•

If you enter a file name or a file name containing a wildcard character,
the SHOW command lists each file matching the name specified.

•

If you do not enter a file specification, the SHOW command lists all log
files in the directory SYS$JOURNAL.

ICURRENT
Specifies that information about the currently active log file, is shown.
This information includes the number of checkpoints and stalls that have
occurred since DECdtm services were started up and indicates whether a
checkpoint or stall is currently in progress.
Note that no file specification is necessary when the qualifier /CURRENT
is used.

IFULL
Lists all log file attributes.

/OUTPUT[=filespec]
Specifies that the output be written to the file specified. By default,
the SHOW command writes the output to SYS$OUTPUT. If you enter
/OUTPUT with no file specification, then LMCP_SHOW is the default file
name and LIS is the default type.

DESCRIPTION

The SHOW command produces a list of existing log files matching the
selection criteria specified. The asterisk and percent sign wildcard
characters can be passed to the SHOW command to represent file names.

EXAMPLES

LMCP> SHOW LOGFILE SYSTEM$B*/FULL
Directory of DISK$MASTER: [MASTER. JOURNALS]
DISK$MASTER: [MASTER.JOURNALS]SYSTEM$BLUE.LM$JOURNAL;l
End of file block 4000 / Allocated 4000
Log Version 1.0
Log File UID:
275300CO-7A71-0092-D3A8-00000000B232 (12-JUL-1989 21:01:40.94)
Penultimate Checkpoint: 0000CE644AF2 02F2
Last Checkpoint:
0000CE6457F2 03F2

15-33

LMCP

SHOW

DISK$MASTER: [MASTER. JOURNALSl SYSTEM$BLACK.LM$JOURNAL;l
End of file block 4000 / Allocated 4000
Log Version 1.0
Log File UID:
9D519DCO-698E-0092-DF95-00000000B20D (21-JUN-1989 09:19:44.54)
Penultimate Checkpoint: 00000012C45E 005E
Last Checkpoint:
000000133E39 0039
DISK$MASTER: [MASTER.JOURNALSlSYSTEM$BRONZE.LM$JOURNAL;l
End of file block 4000 / Allocated 4000
Log Version 1.0
Log File UID:
21847980-5F78-0092-3F5D-00000000B1FF ( 8-JUN-1989 13:13:36.28)
Penultimate Checkpoint: OOOOOOECADE5 41E5
Last Checkpoint:
000000F105FC 41FC
DISK$MASTER: [MASTER. JOURNALSl SYSTEM$BROWN.LM$JOURNAL; 1
End of file block 4000 / Allocated 4000
Log Version 1.0
Log File UID:
A6173DCO-3DE2-0092-0000-00000000B1FF (26-APR-1989 19:30:25.82)
Penultimate Checkpoint: OOOOOC8B4819 2019
Last Checkpoint:
00000C8BC15B 335B

(\,
\, .... )

Total of 4 files.

This command lists all log files with file names beginning with
SYSTEM$B.
LMCP> SHOW LOGFILE
Directory of DISK1: [MASTER. LOGFILES]

SYSTEM$BLACK.LM$JOURNAL;l
SYSTEM$BLUE.LM$JOURNAL;l
Total of 2 files.
Directory of DISK1: [MASTER.NAMESl
SYSTEM$GREEN.LM$JOURNAL;l
SYSTEM$ORANGE.LM$JOURNAL;l
SYSTEM$RED.LM$JOURNAL;l
Total of 3 files.

Grand total of 2 directories 5 files.

This command lists all directories equivalent to SYS$JOURNAL and their
log files.
~

LMCP>

SHOW LOGFILE SYSTEM$RED/FULL/OUTPUT=EXAMPLE

This command lists all percentage information for the specified log file and
writes it to the file EXAMPLE.LIS.

LMCP>

SHOW LOGFILE/CURRENT

Checkpoints started/ended 124/123
Stalls started/ended
1/1
Log status: checkpoint in progress, no stall in progress

This command shows status information about the currently active log file.

15-34

o
16

Monitor Utility (MONITOR)

The VMS Monitor Utility (MONITOR) is a system management tool that
you can use to obtain information about operating system performance.
This chapter describes the following enhancements to Version 5.4 of the
VMS Monitor Utility:

•

New MONITOR TRANSACTION command and TRANSACTION class
(for use within a DECdtm services environment)

•

New MONITOR VECTOR command and VECTOR class (for use within
a vector processing environment)

See the VMS Monitor Utility Manual for information about other classes
and commands.

16.1

MONITOR TRANSACTION Command
The MONITOR TRANSACTION command initiates monitoring of the
TRANSACTION class, which shows information about transactions
coordinated by the DECdtm services. (For a complete description of
DECdtm services, see Chapter 3.)

Use this command as follows:
1

Invoke the MONITOR Utility by entering the DCL command
MONITOR. The utility then displays the following prompt:
MONITOR>

FORMAT

At the MONITOR prompt, enter the MONITOR TRANSACTION
command. The format, description, and examples of how to use this
command follow.

MONITOR TRANSACTION
Qualifiers
Iqualifier[, ...]

One or more qualifiers, described as follows:
Class-name qualifiers

fAll
Specifies that a table of all available statistics (current, average, minimum,
and maximum) is to be included in the display and summary output. For
summary output, this qualifier is the default for all classes; otherwise,
it is the default for all classes except CLUSTER, MODES, PROCESSES,
STATES, SYSTEM, and VECTOR.

16-1

Monitor Utility (MONITOR)

16.1 MONITOR TRANSACTION Command

IAVERAGE
Selects average statistics to be displayed in a bar graph for display and
summary output.
ICURRENT
Selects current statistics to be displayed in a bar graph for display
.and summary output. The ICURRENT qualifier is the default for the
CLUSTER, MODES, STATES, SYSTEM, and VECTOR classes.
IMAXIMUM
Selects maximum statistics to be displayed in a bar graph for display and
summary output.
IMINIMUM
Selects minimum statistics to be displayed in a bar graph for display and
summary output.

DESCRIPTION

16-2

The TRANSACTION class consists of the following data items:
•

Start Rate-The rate at which transactions are started.

•

Prepare Rate-The rate at which transactions are placed in the
prepare state by DECdtm services.

•

One-Phase Commit Rate-The rate that one-phase commit
transactions complete using the one~phase commit operation. This
operation, which consumes significantly fewer system resources, is
used when there is only a single resource manager participating in the
transaction.

•

Total Commit Rate-The rate at which transactions are committed.
This value is the combined total of one~phase and two-phase commit
transactions.

•

Abort Rate-The rate at which transactions are aborted.

•

End Rate-The rate at which transactions are ended.

•

Remote Start Rate-The rate at which transactions are started by a
transaction manager on a remote node.

•

Remote Add Rate-The rate of remote add branch operations.

•

Completion Rate-The rate of completed transactions, indexed by their
duration time in seconds. Following is a list of the completion rate
categories:
Completion Rate 0-1

The number of transactions completed in 0-1
second (1 second or less)

Completion Rate 1-2

The number of transactions completed in 1-2
seconds

Completion Rate 2-3

The number of transactions completed in 2-3
seconds

Completion Rate 3-4

The number of transactions completed in 3-4
seconds

Monitor Utility (MONITOR)

16.1 MONITOR TRANSACTION Command

Completion Rate 4-5

The number of transactions completed in 4-5
seconds

Completion Rate 5+

The number of transactions that took more than 5
seconds to complete

A transaction completed in 0.5 second is included in the count
displayed for the Completion Rate 0-1 category, which indicates the
number of transactions completed in the last time interval that took
0-1 second to execute. See the example displays that follow.

Examples

MONITOR>

MONITOR TRANSACTION/ALL
VAX/VMS Monitor Utility
DISTRIBUTED TRANSACTION STATISTICS
on node SAMPLE
16-JAN-1990 14:52:34

o
c

CUR

AVE

MIN

MAX

Start Rate
Prepare Rate
One Phase Commit Rate
Total Commit Rate
Abort Rate
End Rate
Remote Start Rate
Remote Add Rate

34.76
33.77
0.00
35.09
0.00
35.09
31.12
31.45

34.76
33.77
0.00
35.09
0.00
35.09
31.12
31. 45

34.76
33.77
0.00
35.09
0.00
35.09
31.12
31.45

Completion Rate
by Duration
in Seconds

35.09
0.00
0.00
0.00
0.00
0.00

0-1
1-2
2-3
3-4
4-5
5+

This example shows the status of all transactions on node SAMPLE.

c
16-3

Monitor Utility (MONITOR)

16.1 MONITOR TRANSACTION Command

MONITOR>

MONITOR TRANSACTION/MAXIMUM
VAX/VMS Monitor Utility
DISTRIBUTED TRANSACTION STATISTICS
on node SAMPLE
16-JAN-1990 14:51:04

+-----+
1

MAX

+-----+

o
25
+ - - - - + - Start Rate
Prepare Rate
One Phase Commit Rate
Total Commit Rate
Abort Rate
End Rate
Remote Start Rate
Remote Add Rate

35 1**************
37 1**************

Completion Rate
by Duration
in Seconds

35 1**************

0-1
1-2
2-3
3-4
4-5
5+

+ -

100
-+

- - - + - - -

35 1**************
35 1**************
33 1*************
32 1************

+ - - - - + -

- - - + -

This example shows the maximum statistics of all transactions on node
SAMPLE.

o
16-4

Monitor Utility (MONITOR)

16.2 TRANSACTION Class Record

16.2

TRANSACTION Class Record
The TRANSACTION class record contains data describing the operations
of the DECdtm transaction manager. The TRANSACTION class has a
record type of 22 and a size of 69 bytes. Figure 16-1 illustrates the format
of a TRANSACTION class record; Table 16-1 describes the contents of
each of its fields.
Figure 16-1

TRANSACTION Class Record Format

Class Header
(14 Bytes)

Starts

MNR_TRA$L_STARTS

Prepares

MNR_TRA$L_PREPARES

One Phase Commits

MNR_TRA$~ONE_PHASE

Commits

MNR_TRA$L_COMMITS

Aborts

MNR_TRA$L_ABORTS

Ends

MNR_TRA$~ENDS

Branches
Adds

MNR_TRA$~BRANCHS
MNR_TRA$~ADDS

0-1 Transactions

MNR_TRA$L_BUCKETS1

1-2 Transactions

MNR_TRA$L_BUCKETS2

2-3 Transactions

MNR_TRA$L_BUCKETS3

3-4 Transactions

MNR_TRA$L_BUCKETS4

4-5 Transactions

MNR_TRA$L_BUCKETS5

5+ Transactions

MNR_TRA$L_BUCKETS6
ZK-2023A-GE

c
16-5

Monitor Utility (MONITOR)

16.2 TRANSACTION Class Record

Table 16-1

Descriptions of TRANSACTION Class Record Fields

Field

Symbolic Offset

Contents

Starts

Count of transaction operations started. The number
of times the system service $START_TRANS has
been successfully completed (Iongword, C).

Prepares

Count of transactions that have been prepared
(longword, C).

One Phase Commits

Count of one-phase commit events initiated
(Iongword, C).

Commits

Count of transactions committed. This is the
combined total of one-phase and two-phase commits
(Iongword, C).

Aborts

Count of transactions aborted. Combined total of
planned and unplanned aborts (Iongword, C).

Ends

Count of transactions ended. The number of times
the $END_TRANS has successfully completed
(Iongword, C).

Branches

Count of start remote (to a remote parent) branch
operations (Iongword, C).

Adds

Count of add remote (to a remote subordinate
parent) branch operations (longword, C).

0-1 Transactions

Count of transactions with a duration of less than
1 second (Iongword, C).

1-2 Transactions

Count of transactions with a duration of 1 to
2 (1.99) seconds (Iongword, C).

2-3 Transactions

Count of transactions with a duration of 2 to
3 seconds (Iongword, C).

3-4 Transactions

Count of transactions with a duration of 3 to
4 seconds (Iongword, C).

4-5 Transactions

Count of transactions with a duration of 4 to
5 seconds (longword, C).

5+ Transactions

Count of transactions with a duration greater than
5 seconds (Iongword, C).

o
16-6

Monitor Utility (MONITOR)
16.3 MONITOR VECTOR Command

c
16.3

MONITOR VECTOR Command
The MONITOR VECTOR command displays the number of IO-millisecond
clock ticks per second in which one or more vector consumers have been
scheduled on each currently-configured vector processor in the system.
Because the VMS operating system schedules vector consumers only on
those processors identified as "vector present," the VECTOR class output
never displays vector CPU time for those processors that are "vector
absent."
Note that, because vector consumers can use either or both the vector
CPU and scalar CPU components of a vector-present processor, the vector
CPU time in the VECTOR class display is not a strict measure of the
actual usage of the processor's vector CPU component. Rather, it indicates
the time during which a scheduled vector consumer has reserved both
vector CPU and scalar CPU components of the vector-present processor
for its own exclusive use. (For a more complete description of the vector
processing environment, see Chapter 2.)
Use this command as follows:
1

Invoke the MONITOR Utility by entering the DCL command
MONITOR. The utility then displays the following prompt:
MONITOR>

FORMAT

At the MONITOR prompt, enter the MONITOR VECTOR command.
The format, description, and an example of this command follow.

MONITOR VECTOR
Qualifiers

Iqualifier[, ...]

One or more qualifiers, described as follows:
Class-name qualifiers

IAll
Specifies that a table of all available statistics (current, average, minimum,
and maximum) is to be included in the display and summary output. For
summary output, this qualifier is the default for all classes; otherwise,
it is the default for all classes except CLUSTER, MODES, PROCESSES,
STATES, SYSTEM, and VECTOR.
IAVERAGE
Selects average statistics to be displayed in a bar graph for display and
summary output.

ICURRENT
Selects current statistics to be displayed in a bar graph for display
and summary output. The /CURRENT qualifier is the default for the
CLUSTER, MODES, STATES, SYSTEM, and VECTOR classes.

16-7

Monitor Utility (MONITOR)
16.3 MONITOR VECTOR Command

IMAXIMUM

Selects maximum statistics to be displayed in a bar graph for display and
summary output.
IMINIMUM

Selects minimum statistics to be displayed in a bar graph for display and
summary output.

DESCRIPTION

The VECTOR class consists of the data item Vector Scheduled Rate,
which is represented by a display of statistics that show the rates of 10millisecond clock ticks per second during which vector consumers have
been scheduled on each vector-present CPU.

Example
MONITOR>

MONITOR VECTOR
VAX/VMS Monitor Utility
VECTOR PROCESSOR STATISTICS
on node SAMPLE
12-JUN-1991 22:52:42

+-----+
1 CUR 1
+-----+
Vector Consumers Scheduled
Vector Present
Vector Absent
Vector Absent
Vector Present

CPU
CPU
CPU
CPU

ID
ID
ID
ID

a
1

2
4

25
a
50
+ - - - - + + 131*****
1
1
581**********************

75
+ -

100
- -+

+ - - - - + - - - - + - - - - + - - - - -+

This example shows the VECTOR class display for a multiprocessing
system containing two vector-present processors, CPU 0 and CPU 4.
Displayed statistics represent rates of 10-millisecond clock ticks per
second. For an average of 13 ticks per second over the last collection
interval, vector consumers have been scheduled on CPU O. For an average
of 58 ticks per second over the last collection interval, vector consumers
have been scheduled on CPU

\1
( .. J

o
16-8

Monitor Utility (MONITOR)
16.4 VECTOR Class Record

c
16.4

VECTOR Class Record
The VECTOR class record contains data describing the time during which
vector consumers have been scheduled on a vector-present processor. Its
record type number is 23. A VECTOR class record is of variable length
and depends on the number of active processors in the system. Assuming
all processors are active, MONITOR calculates its size by adding the size
of the class header and the data block, as follows:
13 + (5

( \
/

* MNR_SYI$B_VPCPUS)

Figure 16-2 illustrates the format of a VECTOR class record; Table 16-2
describes the contents of each of its fields.
Figure 16-2

VECTOR Class Record Format

Class Header
(13 Bytes)

Ticks

•
•
•

I
CPUID

1
L

MNR3EC$B_CPUID
MNR_VEC$L_TICKS

ZK-1942A-GE

o
16-9

Monitor Utility (MONITOR)
16.4 VECTOR Class Record

Table 16-2

Field

Descriptions of VECTOR Class Record Fields
Symbolic Offset

Contents

CPU 10

Identification of the processor from which the data has been
collected (1 byte).

Ticks

Number of 10-millisecond clock ticks in which a vector
consumer has been scheduled on this processor (1 longword).

To support the VECTOR class, MONITOR appends the records in
Table 16-3 to the system information record.
Table 16-3

Field

Descriptions of Additions to System Record Fields
Symbolic Offset

Contents

VPCPUs

Number of vector-present processors in the current system
(1 byte).

VP Conf

Bit mask identifying those processors in the configuration that
are vector-present processors (1 longword).

o
C)

o
16-10

o
17

Network Control Program Utility (NCP)

This chapter describes new NCP line and circuit name support for
VAXft 3000 systems and for two new Ethernet/820 controllers. See the
VMS Version 5.4 Release Notes for more information about these and other
hardware components that are new or enhanced for Version 5.4 of the
VMS operating system.

17.1

Line and Circuit Name Support for VAXft 3000 Systems
The VMS Network Control Program Utility (NCP) supports the following
new line and circuit name for VAXft 3000 systems (the controller number
can be 0 or a positive number):
KFE-<controller number>

When you enter NCP commands from a VAXft 3000 system connected to
your DECnet-VAX network, the KFE-n line and circuit name is displayed,
as follows:

( )

$ RUN SYS$SYSTEM:NCP
NCP> SHOW KNOW LINE

---/

Line Volatile Summary as of 31-AUG-1990 12:50:03
Line

State

KFE-O

$ RUN SYS$SYSTEM:NCP
NCP> SHOW KNOW LINE
Circuit Volatile Summary as of 31-AUG-1990 12:52:03

c
17.2

Circuit

State

KFE-O

Loopback
Name

Adjacent
Routing Node
8.999 (JUPE)

Line and Circuit Names for New Ethernet/820 Controllers
The VMS Network Control Program Utility (NCP) now supports new line
and circuit names for the following Ethernet/820 controllers. (See the VMS
Version 5.4 Release Notes for a complete description of each new controller.)
•

DEMNA controller-The NCP line and circuit name for the DEMNA
controller is as follows:
MNA-<controller number>

For example:
MNA-O (for EXAn)
MNA-1 (for EXBn)

17-1

Network Control Program Utility (NCP)
17.2 Line and Circuit Names for New Ethernet/820 Controllers

•

Second Generation Ethernet Controller (SGEC)-The NCP line and
circuit name for the SGEC is as follows:

ISA-<controller number>

For example:
ISA-O
ISA-l

(for EZAn)
(for EZBn)

(~~\

~ /)
....

o
C)

o
17-2

c
18 VMS Volume Shadowing Phase II

o
o

Volume shadowing is the process of maintaining multiple copies of the
same data on two or more disk volumes. This duplication of data provides
greater data availability and faster data accessibility. Volume shadowing
provides high availability by insuring against data loss resulting from
media deterioration or through controller or device failure. When data
is recorded on more than one disk volume, you have access to critical
data even when one volume is unavailable. Disk input/output operations
continue with the remaining members of the shadow set.
The system can also find data more quickly because it can search more
than one disk. Because a shadow set is made up of multiple disks
containing the same data, the shadow set can use the additional read
heads to respond to multiple read requests at the same time. In addition,
when normal media deterioration renders sections of a volume unreadable,
systems with volume shadowing can read the duplicate data and copy it to
the failing volume to repair data.
Before Version 5.4, the VMS operating system supported only phase I
volume shadowing (see the VAX Volume Shadowing Manual). This type
of shadowing provides centralized shadowing using HSC controllers with
compatible DSA disks. Phase I shadowing is limited to CI configurations
on a single system or a VAXcluster.
VMS Volume Shadowing phase II supports the following:
•

Volume shadowing phase II supports clusterwide shadowing of all
DSA devices. Phase II is not limited to HSC-controlled disks but
extends volume shadowing capabilities to all DSA disks including local
adapters, all DSSI (RF series) disk devices on any VAX computer, all
interfaces (including but not limited to the KFQSA interface), and
across MSCP servers.
•

Clusterwide shadowing of all MSCP-compliant DSA disks having the
same physical geometry (having the same number of logical blocks) on
a single system or located anywhere in a VAXcluster system.

Distributed, not centralized, shadowing
Volume shadowing phase II creates and maintains virtual units
in a distributed fashion on each node in the cluster. Phase II
supports shadowing on a single system or in a VAXcluster system
where interprocessor communication is carried out over a computer
interconnect (Cl), Digital small systems interconnect (DSSl), mixedinterconnect configuration, or the Ethernet. Thus, volume shadowing
provides fault tolerance resulting from disk media errors across the
full range of VAX processors and configurations.

•

Shadowing of the system disk and Files-lIOn-Disk Structure Level 2
(ODS2) data disks

•

Shadowing capabilities across different controllers.
18-1

VMS Volume Shadowing Phase II

c
Shadow set member units can be located on different controllers and
VMS MSCP servers.
•

Shadowing capabilities with mixed phases
It is possible to use both phase I and phase II shadowing on the
same node at the same time. You can also mix phase I and phase II
shadowing in a VAXcluster system.

See the new VMS Volume Shadowing Manual for complete information
about phase II volume shadowing.

(\,
\</J

o
o

o
18-2

c
Part 4: Programming Features
This part contains the following chapters:
Chapter 19, VMS Debugger
Chapter 20, Linker Utility (LINK)
Chapter 21, Utility Routines: MAIL
Chapter 22, System Services

Chapter 23, Run-Time Library Routines
Chapter 24, VMS Record Management Services
Chapter 25, 110 Driver Support
Chapter 26, System Dump Analyzer Utility (SDA)
Chapter 27, Device Support
Chapter 28, VAX Text Processing Utility (VAXTPU)
Chapter 29, VAX RMS Journaling: Support for DECdtm Services
Chapter 30, VMSINSTAL
Chapter 31, DECwindows and CDA Programming Features

c
19

VMS Debugger

This chapter describes enhancements to the VMS Debugger for Version
5.4 of the VMS operating system. These enhancements, which let you
debug vectorized programs (programs that use VAX vector instructions),
are described in more detail in the revised VMS Debugger Manual.

19.1

You can now perform the following debugging tasks using either the
debugger's command interface or the DECwindows interface:

0
C\

19.2

Debugging Vectorized Programs

•

Display information about the availability and use of the vector
processor on your system.

•

Control and monitor the execution of vector instructions with
breakpoints, watchpoints, and so on.

•

Specify built-in symbols for the vector registers (%VO through %V15)
and the vector control registers (%VCR, %VLR, and %VMR).

•

Examine the values contained in the vector registers and in the vector
control registers; deposit values into those registers.

•
•
•

Display vector instructions using a screen-mode instruction display.
Examine and deposit vector instructions and their operands.
Perform masked operations on vector registers to display only certain
register elements or override the masking associated with a vector
instruction.

•

U sing the EXAMINE command, specify composite address expressions
of a complex form, such as what might be appropriate for a vectorized
program. (Note that this feature is not restricted to vectorized
programs.)

•

Display the decoded results of vector floating-point exceptions.

•

Control synchronization between the scalar and vector processors.

•

Save and restore the current vector state when using the CALL
command to execute a routine that might affect the vector state.

•

Display vector register data using a screen-mode display.

Command Interface: New and Enhanced Commands and Qualifiers
The following list identifies new and enhanced commands and qualifiers
for the debugger's command interface:
•

CALL/[NO] SAVE_VECTOR_STATE

•

CANCEL BREAKIVECTOR_INSTRUCTION
19-1

VMS Debugger
19.2 Command Interface: New and Enhanced Commands and Qualifiers

•

CANCEL TRACENECTOR-INSTRUCTION

•

EXAMINEIFMASK, ITMASK, IOPERANDS

•

SET BREAKIVECTOR_INSTRUCTION,
IINSTRUCTION[=(opcode[, ... ])]

•

SET STEP VECTOR_INSTRUCTION, INSTRUCTION[=(opcode[, ...J)]

•

SET TRACENECTOR_INSTRUCTION,
IINSTRUCTION[ =(opcode[, ..J)]

•

SET VECTOR_MODE [NOJSYNCHRONIZED

•

SHOW PROCESS

•

SHOW VECTOR_MODE

•

STEPNECTOR_INSTRUCTION, IINSTRUCTION[ =(opcode[, ...J)]

•

SYNCHRONIZE VECTOR_MODE

See the VMS Debugger Manual for complete information about these
commands and qualifiers.

19.3

OECwindows Interface: Enhancements to Menus and Dialog Boxes
The following list identifies new features for the debugger's DECwindows
interface:
•

The Control menu has a new menu item labeled Synchronize Vector
Processor. This item is the DECwindows equivalent of the command
SYNCHRONIZE VECTOR_MODE.

•

In the Step dialog box, the target (upper right) option menu has a new
entry labeled the next vector instruction.

•

In the Break dialog box, the target (upper right) option ll?-enu has a
new entry labeled every vector instruction.

•

The Call dialog box has a new toggle button labeled Save vector State.

•

The Examine Variable dialog box has a new option menu labeled Mask.
This menu has three options labeled None, Tmask, and Fmask.

•

The Examine Code dialog box has a new option menu labeled With
Operand Values. This menu has 7 options labeled None, Brief, Full,
Brief with Tmask, Brief with Fmask, Full with Tmask, and Full with
Fmask.

•

The Examine Address or Register dialog box has a new option menu
labeled Mask. This menu has three options labeled None, Tmask, and
Fmask.

•

The Other Attributes dialog box has a new toggle button labeled
Scalar-Vector Synchronization. This button is equivalent to the
command SET VECTOR_MODE [NO]SYNCHRONIZED.

See the online help that is available from the debugger's DECwindows
interface for complete information about these features.

19-2

o
20 Linker Utility (LINK)
With Version 5.4 of the VMS operating system, you can now specify larger
page sizes by using the new /BPAGE qualifier with the LINK command.

/BPAGE affects the allocation of image sections. Because image sections
must be allocated on a page boundary, specifying a larger page size causes
the origin of image sections to be increased to the next multiple of that
size. /BPAGE affects only the construction of the image (shareable or
executable), not the linker itself or any page-size dependencies in the
linked program. An image linked to a larger page size generally runs
correctly on a current VMS system, but it might consume more virtual
address space. In addition, linking a shareable image to a larger page size
can cause the value of transfer vector offsets to change if they were not
allocated in page 0 of the image.
The format for using /BPAGE is as follows:
LINK [/BPAGE [=n]]

If you do not specify /BPAGE with the LINK command, the default 512byte page is used.

If you specify /BPAGE without a page size value (n is not specified), the
image is built using 8-kilobyte pages.
If you specify a page size value (n is specified), the image is built using
that value for the page size. Page size can be any size from 512 bytes to
65 kilobytes. The value is specified as the exponent of a power of 2. For
example, when n equals 9, the page size is 512 bytes; when n equals 13,
the page size is 8 kilobytes.

o
20-1

c
21

Utility Routines: MAIL

The callable interface to the VMS Mail Utility (MAIL) lets you create
applications that perform various Mail Utility functions, such as sending
mail messages to users on your system. In addition, your applications can
communicate with users on remote nodes connected to your system with
DECnet-VAX.

(

Table 21-1 summarizes these new Mail Utility routines. See the revised
VMS Utility Routines Manual for complete information.

Table 21-1

Mail Utility Routines

Routine

Description

Mail File Context

o
c

MAIL$MAILFILE_BEGIN

Initiates mail file processing

MAIL$MAILFILE_CLOSE

Closes a mail file

MAIL$MAILFILE_COMPRESS

Compresses a mail file

MAIL$MAILFILE_END

Terminates mail file processing

MAIL$MAILFILE_INFO_FILE

Obtains information about the mail file

MAIL$MAILFILE_MODIFY

Changes the wastebasket folder name

MAIL$MAILFILE_OPEN

Opens a mail file

MAIL$MAILFILE_PURGE_WASTE

Purges a mail file

Message Context
MAIL$MESSAGE_BEGIN

Initiates message processing

MAIL$MESSAGE_COPY

Copies messages

MAIL$MESSAGE_DELETE

Deletes messages

MAIL$MESSAGE_END

Terminates message processing

MAIL$MESSAGE_GET

Retrieves a message

MAIL$MESSAGE_INFO

Obtains information about a specified message

MAIL$MESSAGE_MODIFY

Identfies a message as replied, new, or
marked

MAIL$MESSAGE_SELECT

Selects a message or messages from the
currently open mail file
(continued on next page)

o
21-1

Utility Routines: MAIL

o
Table 21-1 (Cont.)

Mail Utility Routines

Routine

Description

Send Context
MAIL$SEND_ABORT

Aborts a send operation

MAl L$SEND _ADD _ADDRESS

Adds an addressee to the address list

MAl L$SEND_ADD_ATTRI BUTE

Constructs the message header

MAIL$SEND_ADD_BODYPART

Constructs the body of the message

MAl L$SEN 0 _BEG IN

Initiates send processing

MAIL$SEND_END

Terminates send processing

MAIL$SEND_MESSAGE

Sends a message

User Context
MAIL$USER_BEGIN

Initiates user profile context

MAIL$USER_DELETE_INFO

Deletes a user profile entry

MAIL$USER_END

Terminates user profile context

MAIL$USER_GET_INFO

Retrieves information about a user from the
user profile
Adds or modifies a user profile entry

o
21-2

c
22 System Services
The VMS Version 5.4 operating system includes new and modified system
services that support the following.

•
•
•
•

•

DECdtm services
Volume initialization
System security enhancements
Vector processing
VMS Volume shadowing

The information in this chapter is organized as follows:

o
Ci

22.1

•

Section 22.1 lists and briefly describes system services that are new for
Version 5.4 of the VMS operating system.

•

Section 22.2 describes how to use specific transaction management
services within the DECdtm environment.

•

Section 22.3 describes how to use the $INIT_VOL system service.

•

Section 22.4 includes the complete format and description of each new
system service.

•

Section 22.5 describes modifications to existing system services (for
example, the addition of new item codes and flags).

•

Section 22.6 contains new information about using system services to
create site-specific loadable images.

Summary of New System Services
Table 22-1 lists the system services that are new for the VMS Version 5.4
operating system.
Table 22-1

New VMS Version 5.4 System Services

System Service

Description

Function
DECdtm Services

$ABORT_ TRANSW

Abort Transaction

Aborts a transaction asynchronously;
can be called before the transaction is
committed

Abort Transaction and Wait

Synchronous equivalent of $ABORT_
TRANS
(continued on next page)

22-1

System Services
22.1 Summary of New System Services

Table 22-1 (Cant.)

New VMS Version 5.4 System Services

System Service

Description

Function
DECdtm Services

$END_TRANS

End Transaction

Commits a transaction asynchronously

$END_TRANSW

End Transaction and Wait

Synchronous equivalent of
$END_TRANS

$START_TRANS

Start Transaction

Starts a transaction (asynchronously) by
allocating a transaction identifier (TID)
and establishing the internal structures
that define a transaction

$START_ TRANSW

Start Transaction and Wait

Synchronous equivalent of
$START_TRANS

(-\
~ - - ./

Volume Initialization
$INIT_VOL

Initialize Volume

Formats a disk or magnetic tape volume
and writes a label on the volume

System Security
$FORMAT.-AUDIT

Format Security Audit Event
Message

Converts a security auditing event
message from binary format to ASCII
text and filters information considered
too sensitive to display

$HASH_PASSWORD

Hash Password

Applies a hash algorithm to an ASCII
password string and returns a quadword
hash value that represents the encrypted
password

i-\

Vector Processing

22.2

$RELEASE_VP

Release Vector Processor

Terminates the current process's status
as a vector consumer

$RESTORE_VP_EXCEPTION

Restore Vector Processor Exception
State

Restores the saved exception state of
the vector processor

$RESTORE_VP_STATE

Restore Vector State

Allows an AST routine or condition
handler to restore the vector state of the
mainline routine

$SAVE_VP_EXCEPTION

Save Vector Processor Exception
State

Saves the pending exception state of the
vector processor

Using Transaction Management System Services
Application programs can call the VMS transaction management system
services to delimit the set of operations comprising a distributed
transaction. These system services can then guarantee consistent
execution of the transaction.

22-2

System Services

22.2 Using Transaction Management System Services

Chapter 3 provides a complete description of DECdtm services and
discusses the concept of atomicity in distributed applications.
The transaction management system services provided by the DECdtm
services include the following:
•

Start Transaction ($START_TRANS)

•

Start Transaction and Wait ($START_TRANSW)

•

End Transaction ($END_TRANS)

•

End Transaction and Wait ($END_TRANSW)

•

Abort Transaction ($ABORT_TRANS)

•

Abort Transaction and Wait ($ABORT_TRANSW)

You must call these services in your application program according to the
syntax rules for the programming language that you are using. Refer to
the appropriate language reference manual for more information on using
system services.

22.2.1

Transaction Processing System Model
In Digital's model for transaction processing, several components work
together to execute atomic transactions.
At the end-user level, user-written application programs define the task
to be accomplished, such as query, update, and insertion. An application
program (AP) also specifies how transactions are to be executed. The
application programs initiate transaction execution using calls to VMS
system services.

At the system level, the execution of the transaction depends on the
interaction of resource managers (RMs) and transaction managers (TMs).
The interaction of these components is shown in Figure 22-1.
Figure 22-1

Transaction Processing Components

Node

Database
ZK-1869A-G E

The key function of the DECdtm services is to act as transaction
manager. A transaction manager supports the transaction management
system services that are issued from application programs to delimit
22-3

System Services
22.2 Using Transaction Management System Services

transactions. To complete or abort a transaction, the transaction
manager sends instructions to resource managers and other transaction
managers involved in the transaction. In this way, a transaction manager
coordinates the actions of a transaction.
Through calls to system services, application programs communicate
directly with the DECdtm services. Additionally, these programs can use
the services provided by a resource manager.
A resource manager is a software product that manages shared access
to a set of recoverable resources on behalf of applications programs. In
this context, recoverable means that all updates to the resources on
behalf of the transaction can be made permanent or can be undone.
Recoverable resources typically include files or databases. The resource
manager participates in the two-phase commit protocol to commit or abort
a transaction.

22.2.2

Transaction Management
The responsibilities of a transaction manager include the following:
•

Delimit transactions

•

Track participating transaction managers and resource managers

•

Ensure that transactions either commit or abort

•

Assist in recovery of resources after failures

For every transaction that it coordinates, the transaction manager in
the DECdtm services maintains a list of the transaction's participants.
Participants can include:
•

Resource managers on a local node, spanning one more or processes

•

Transaction managers on other nodes within a network, which might
also have associated resource manager and transaction manager
participants

The transaction manager uses this list of participants to execute the
two-phase commit protocol. During the execution of this protocol, each
participating transaction manager writes transaction information to a
log file. A log file contains a permanent record of transaction states.
By having access to a log file, a transaction manager can resume the
execution of the two-phase commit protocol after recovering from a system
failure. When executing the two-phase commit protocol, the transaction
manager tells the transaction's participants whether to commit or abort a
transaction.

22.2.3

Starting a Transaction
Transaction management services demarcate transactions. To indicate
the start of transaction operations, an application program calls
$START_TRANS or its synchronous equivalent, $START_TRANSW.

22-4

System Services
22.2 Using Transaction Management System Services

The application program should make a call to $START_TRANS prior to
the code making up the transaction operations and prior to any code that
accesses recoverable resources or remote nodes. In response to a call to
$START_TRANS, the transaction manager component of the DECdtm
services generates a unique transaction identifier (TID) for the transaction
so that ft can keep track of the transaction. The transaction manager
uses the TID to identify all actions performed by resource managers and
transaction managers on behalf of the transaction.

c
( "\
)

For each process on which they are used, the DECdtm services maintain
the concept of a current transaction. The transaction that is started using
$START_TRANS is considered the process default, or current, transaction.
Alternatively, the NONDEFAULT flag can be set when $START_TRANS is
called to establish a non default transaction.
Thus, when an application program that is using a resource manager
such as RMS Journaling makes a call to $ START_TRANS , the TID of
the current transaction is used by default. For RMS Journaling, unless a
specific TID is specified (using the XAB$_TID item code), RMS associates
the record stream with the default, current transaction.
The following FORTRAN code fragment demonstrates the use of
$START_TRANSW. The program first determines the accounts to be
credited and debited and the amount to be transferred. It then calls
$START_TRANSW to indicate to the transaction manager that it is
beginning the set of debit/credit operations that make up the distributed
transaction.
INTEGER*4 STATUS, TID (4)
INTEGER*2 IOSB (4)
INTEGER*4 SYS$START_TRANSW

GET_INPUT('Account to debit', DEBIT_ACCT)
GET_INPUT('Account to credit', CREDIT_ACCT)
GET_INPUT('Amount to transfer', TRANSFER_AMT)
STATUS=SYS$START_TRANSW (%VAL (0),
1
%VAL (0),
2
IOSB,
3
%VAL (0),
4
%VAL (0),
TID)
5
IF (STATUS) STATUS = IOSB (1)
IF (.NOT.STATUS) GOTO 100
STATUS = DEBIT_ACCOUNT (
1
DEBIT_ACCT, TRANSFER_AMT, %REF(O»
STATUS
1

CREDIT_ACCOUNT (
CREDIT_ACCT, TRANSFER_AMT, %REF(O»

o
22-5

System Services
22.2 Using Transaction Management System Services

22.2.4

Completing a Transaction
The processing of a transaction completes when a call is made to the
DECdtm system services to either commit or abort. The system services
that commit a transaction are $END_TRANS and its synchronous
equivalent, $END_TRANSW. The services that abort a transaction are
$ABORT_TRANS and its synchronous equivalent, $ABORT_TRANSW.
Upon receiving one of these calls, the DECdtm services inform all
participants to commit or abort.
The following FORTRAN code fragment demonstrates the use of
$END_TRANSW. After the final operation of the program is issued,
the program calls $END_TRANSW to commit the transaction.

STATUS
1

STATUS
1
2
3
4
5

CREDIT_ACCOUNT (
CREDIT_ACCT, TRANS FE R_AMT, %REF(O))
SYS$END_TRANSW (%VAL (0),
%VAL (0),
IOSB,
%VAL (0),
%VAL (0),
TID)

IF (STATUS)

STATUS

rOSB (1)

()

IF (.NOT.STATUS) GO TO 100

END

22.2.5

Calling a Planned Abort
$ABORT_TRANS enables applications to implement a planned abort. If
errors occur during the execution of the transaction processing, a call
can be made to $ABORT_TRANS to end the transaction so that previous
changes do not become permanent in the accessed database.
The following code fragment is from a COBOL application that calls
$ABORT_TRANSW as part of its error-handling:

DISPLAY "Calling subtransaction to FETCH record from database." LINE PLUS 1.
CALL "ERASE EAST" USING WS-EMP-KEY WS-EMP-RECORD WS-STATUS TID.
IF WS-STATUS IS NOT EQUAL TO "SUCCESS"
PERFORM ABORT-GLOBAL-TRANSACTION
GO TO END-MOVE-EAST-WEST.

ABORT-GLOBAL-TRANSACTION.

22-6

System Services
22.2 Using Transaction Management System Services

c
*
*

The employee name field contains information about the error
detected in the subprogram.
DISPLAY WS-EMP-NAME LINE PLUS 1.
DISPLAY "Aborting global transaction." LINE PLUS 1.

abort (rollback) global transaction
CALL "SYS$ABORT_TRANSW" USING
OMITTED
OMITTED
BY REFERENCE IOSB
OMITTED
OMITTED
BY REFERENCE TID
GIVING WS-SYS-STATUS.

() 22.2.6 Example of Using Transaction Management System Services
Example 22-1 is a BLISS program that uses the transaction management
services to create two simple transactions. The first transaction is
committed, using $END_TRANS. The second transaction is aborted,
using $ABORT_TRANS.
Example 22-1

Using Transaction Management Services

MODULE EXAMPLE (MAIN=EXAMPLE) =
BEGIN
LIBRARY'SYS$LIBRARY:STARLET' ;
ROUTINE EXAMPLE
BEGIN
LOCAL
STATUS,
IOSB
VECTOR [4, WORDJ,
TID
: $BBLOCK [DTI$S_TIDJ;

!+
! Start a nondefault process transaction
!-

STATUS = $START_TRANSW (EFN
FLAGS
IOSB
ASTADR
ASTPRM
TID
IF .STATUS AND

= 1,
(DDTM$M_NONDEFAULT OR
DDTM$M_SYNC) ,
IOSB,
0,
0,
TID) ;

(.STATUS NEQU SS$ SYNCH) THEN

STATUS = .IOSE [OJ;
IF NOT .STATUS THEN RETURN (.STATUS);
!+
! Commit the transaction
!-

(continued on next page)

22-7

System Services
22.2 Using Transaction Management System Services

Example 22-1 (Cont.)
STATUS

Using Transaction Management Services

= 1,
$END TRANSW (EFN
FLAGS
DDTM$M_SYNC,
IOSB
IOSB,
ASTADR = 0,
ASTPRM = 0,
TID
TID) ;

IF .STATUS AND
STATUS

(.STATUS NEQU SS$_SYNCH) THEN

.IOSB [0];

IF NOT .STATUS THEN RETURN (.STATUS);
!+
! Start another nondefault process transaction
!STATUS = $START_TRANSW (EFN
FLAGS
IOSB
ASTADR
ASTPRM
TID
IF .STATUS AND
STATUS

1,
(DDTM$M_NONDEFAULT OR
DDTM$M_SYNC),
IOSB,
0,
0,
TID) ;

(.STATUS NEQU SS$ SYNCH) THEN

.IOSB [0];

IF NOT .STATUS THEN RETURN (.STATUS);

!+
! Abort the transaction
!-

STATUS = $ABORT_TRANSW (EFN
FLAGS
IOSB
ASTADR
ASTPRM
TID
IF .STATUS AND

= 1,
DDTM$M_ SYNC,
IOSB,
0,
0,
TID) ;

(.STATUS NEQU SS$ SYNCH) THEN

STATUS = .IOSB [0];
RETURN (.STATUS);
END;
END
ELUDOM

o A call to $START_TRANS. The DECdtm transaction manager responds
to this call by creating a transaction identifier.
• To commit the transaction, the application calls $END_TRANS.
@) To start another transaction, the application makes another call to

$START_TRANS.

e To abort the transaction, the application calls $ABORT_TRANS.

22-8

System Services

22.3 Using the Initialize Volume ($INIT_ VOL) System Service

22.3

Using the Initialize Volume ($INIT_ VOL) System Service
Initializing a volume writes a label on the volume, sets protection and
ownership for the volume, formats the volume (depending on the device
type), and overwrites data already on the volume.
Normally, you initialize a volume from the DeL command stream by
using the INITIALIZE command. However, you can also use the Initialize
Volume ($INIT_VOL) system service to enable a process to initialize a
volume from within a program.
When you call the $INIT_VOL system service, you must specify a device
name and a new volume name. You can also use the itmlst argument
of $INIT_VOL to specify options for the initialization. For example, if
you want data compaction to be performed, you can specify the INIT$_
COMPACTION item code.
Before initializing the volume with $INIT_VOL, be sure you have placed
the volume on the device and started the device (by pressing the START or
LOAD button).

The default format for files on disk volumes is called Files-II Structure
Level 2. Files-I1 Structure Level 1 format is used by other Digital
operating systems, including RSX-1IM, RSX-IIM-PLUS, RSX-I1D
and lAS. For more information, see the Guide to VMS Files and Devices.
Examples
The following example illustrates a call to $INIT_VOL from VAX C. The
call is equivalent to the following DCL command:
INITIALIZE/DENSITY=6250 MUAO: USER01

#include <descrip.h>
#include <initdef.h>
struct item_descrip_3
{

unsigned short buffer_size;
unsigned short item_code;
void *buffer_address;
unsigned short *return_length;
};

main ()
{

unsigned long
density_code,
status;
$DESCRIPTOR(drive_dsc, "MUAO:");
$DESCRIPTOR(label_dsc, "USER01");
struct

struct item_descrip_3 density_item;
long terminator;
init_itmlst;
/*
** Initialize the input item list.
*/

22-9

System Services
22.3 Using the Initialize Volume ($INIT_ VOL) System Service

density_code = INIT$K_DENSITY_6250_BPI;
init_itmlst.density_item.buffer_size = 4;
init_itmlst.density_item.item_code = INIT$_DENSITY;
init itmlst.density item.buffer address
&density code;
init_itmlst.terminator = 0;
/*
** Initialize the volume.
*/
status

SYS$INIT VOL

(&drive dsc,

&label dsc,

&init_itmlst);

/*
** Report an error if one occurred.
*/
if «status & 1) != 1)
LIB$STOP (status);

The following example illustrates a call to $INIT_VOL from VAX BASIC.
The call is equivalent to the following DCL command:
INITIALIZE/DATA_CHECK=READ DJA21: USERVOLUME
~

OPTION TYPE

EXPLICIT

EXTERNAL LONG FUNCTION SYS$INIT_VOL

RECORD ITEM DESC
VARIANT
CASE
WORD BUFLEN
WORD ITMCOD
LONG BUFADR
LONG LENADR
CASE
LONG TERMINATOR
END VARIANT
END RECORD

c..-.\

INCLUDE '$INITDEF'

'~,FROM

'~LIBRARY

DECLARE LONG RET_STATUS, &
ITEM_DESC INIT ITMLST(2)
! Initialize the input item list.

INIT_ITMLST(O): :ITMCOD = INIT$_READCHECK
INIT_ITMLST(l): : TERMINATOR = 0
!

Initialize the volume.

RET_STATUS = SYS$INIT_VOL ("DJA21:" BY DESC,
INIT_ITMLST() BY REF)

22.4

"USERVOLUME" BY DESC,

Descriptions of New System Services
This section contains complete descriptions of the system services new for
Version 5.4 of the VMS operating system.

22-10

SYSTEM SERVICE DESCRIPTIONS

$ABORT_ TRANS

Abort Transaction
Aborts a transaction; it can be called before the transaction is committed.

FORMAT

SVS$ABORT_TRANS

RETURNS

VMS usage:
type:
access:
mechanism:

[efn] ,[flags] ,iosb ,[astadr]
,[astprm] ,[tid]

cond_value
longword (unsigned)
write only
by value

Longword condition value. All system services (except $EXIT) return by
immediate value a condition value in RO. Condition values returned by
this service are listed in the Condition Values Returned section.

ARGUMENTS

efn
VMS usage:
type:
access:
mechanism:

ef_number
longword (unsigned)
read only
by value

Number of the event flag to be set. The efn argument is a longword
containing this number; however, $ABORT_TRANS uses only the loworder byte. If you do not specify the efn, $ABORT_TRANS uses the
default value O.

flags
VMS usage:
type:
access:
mechanism:

mask_'ongword
longword (unsigned)
read only
by value

Flags specifying options for $ABORT_TRANS. The flags argument is a
longword bit mask that is the logical OR of each bit set, in which each bit
corresponds to an option. The $DDTMDEF macro defines a symbolic name
for each flag bit.
DDTM$M_SYNC, the only flag currently defined, is described in
Table 22-2.

o
22-11

SYSTEM SERVICE DESCRIPTIONS
$ABORT_TRANS

o
Table 22-2 $ABORT_TRANS Operation Flag
Flag

Description

DDTM$M_SYNC

Indicates successful synchronous completions by returning
SS$_SYNCH. When synchronous completion is successful,
the completion AST address is not called, the IOS8 is not
written, and the event flag is not set.

iosb
VMS usage: io_status_block
type:
quadword (unsigned)
access:
write only
mechanism: by reference
I/O status block (IOSB) to receive the final completion status of the
request. The iosh argument is the address of the quadword I/O status
block.

The following diagram shows the structure of the I/O status block:

Reserved by Digital

Condition Value

Reserved by Digital
ZK-1224A-GE

astadr
VMS usage: ast_procedure
type:
procedure entry mask
access:
call without stack unwinding
mechanism: by reference
AST service routine to be executed. The astadr argument is the address- '
of the entry mask of this routine. In the case of synchronous completion,
the call might not take place. Refer to the description of DDTM$M_SYNC
in Table 22-2.

If you specify astadr, the AST routine executes at the same access mode
as the caller of the $ABORT_TRANS service.

astprm
VMS usage: user_arg
type:
longword (unsigned)
access:
read only
mechanism: by value
AST parameter passed to the AST service routine specified by the astadr
argument. The astprm argument is a longword.

o
22-12

SYSTEM SERVICE DESCRIPTIONS

$ABORT_TRANS

tid
VMS usage:
type:
access:
mechanism:

transaction_id
octaword (unsigned)
read only
by reference

Pointer to the transaction identifier (TID) structure that designates the
transaction to be aborted. The default value for this parameter is the
current transaction.

DESCRIPTION

The Abort Transaction service aborts a specific transaction by invalidating
the transaction identifier (TID) and instructing all resource managers
involved to nullify all the actions of the transaction. This system service
can be called by an application program or by any resource manager or
transaction manager participating in the execution of the transaction.
For a single-node transaction, $ABORT_TRANS can be successfully called
any time before the transaction is committed. A transaction is considered
to be committed when the commit record is written to the transaction
log file. A committed transaction executes in its entirety. When a
transaction is aborted, the transaction manager orders all participants
in the transaction to roll back any changes made to database files. Thus,
none of the intended actions of the distributed transactions is made
permanent.

For distributed transactions, $ABORT_TRANS can be successfully called
from the coordinating (home) node any time before the transaction
is committed and from the participating (remote) node only until the
participant transaction manager is prepared.
Required Privileges

None.

Required Quota

ASTLM
Related Services

$END_TRANS, $START_TRANS

CONDITION
VALUES
RETURNED

SS$_NORMAL

The operation was successfully queued.

SS$_SYNCH

The synchronous operation completed successfully.

SS$_ACCVIO

The IOS8 or TID cannot be read by the caller, or the
IOS8 cannot be written by the caller.

SS$_8ADPARAM

The operations flags are invalid.

SS$_EXASTLM

The process has exceeded its AST limit quota.

SS$_ILLEFC

The efn argument specifies an illegal flag number.

22-13

SYSTEM SERVICE DESCRIPTIONS
$ABORT_TRANS

o
There is insufficient system dynamic memory for the
operation.

CONDITION
VALUES

SS$_NOCURTID

No default TID is defined.

SS$_NOSUCHTID

The designated TID is unknown.

SS$_WRONGSTATE

The transaction is in the wrong state for the attempted
operation.

Same as those returned in RO. A value of SS$_NORMAL returned in the
I/O status block indicates that the service completed successfully.

RETURNED IN
THE I/O STATUS
BLOCK

o
22-14

SYSTEM SERVICE DESCRIPTIONS

$ABORT_TRANSW

$ABORT_ TRANSW

Abort Transaction and Wait

Aborts a transaction; it can be called before the transaction is committed.
$ABORT_TRANSW completes synchronously; that is, it returns to the caller
after the request has completed.
For asynchronous completion, use the Abort Transaction ($ABORT_TRANS)
service, which aborts a transaction without waiting for the operation to
complete.
In all other respects, $ABORT_ TRANSW is identical to $ABORT_TRANS. For
all other information about the $ABORT_ TRANSW service, refer to the section
on $ABORT_TRANS.
For additional information about system service completion, refer to the
Synchronize ($SYNCH) service and to Introduction to VMS System Services.

FORMAT

SYS$ABORT_TRANSW

[efn] ,[flags] ,iosb ,[astadr]
,[astprm] ,[tid]

o
c'

o
22-15

SYSTEM SERVICE DESCRIPTIONS
$END_TRANS

$END_TRANS

End Transaction

Commits a transaction.

FORMAT

SYS$END_TRANS

RETURNS

VMS usage:
type:
access:
mechanism:

[efn] ,[flags] ,iosb ,[astadr]
,[astprm] ,[tid]

cond_value
longword (unsigned)
write only
by value

(
\.
\

"'-- j

ARGUMENTS

efn
VMS usage:
type:
access:
mechanism:

ef_number
longword (unsigned)
read only
by value

(-\
~.J

Number of the event flag to be set. The efn argument is a longword
containing this number; however, $END_TRANS uses only the low-order
byte. If you do not specify efn, $END_TRANS uses the default value O.

flags
VMS usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by value

(\
,_~

Flags specifying options for $END_TRANS. The flags argument is a
longword bit mask that is the logical OR of each bit set, in which each bit
corresponds to an option. The $DDTMDEF macro defines a symbolic name
for each flag bit.
DDTM$M_SYNC, the only flag currently defined, is described in
Table 22-3.

o
22-16

SYSTEM SERVICE DESCRIPTIONS

$END_TRANS

Table 22-3
Flag

$END_TRANS Operation Flag
Description

iosb

VMS usage:
type:
access:
mechanism:

io_status_block
quadword (unsigned)
write on Iy
by reference

I/O status block (lOSB) to receive the final completion status of the
request. The iosh argument is the address of the quadword I/O status
block.
The following diagram shows the structure of the I/O status block:

Reserved by Digital

Condition Value

Reserved by Digital
ZK-1224A-GE

astadr

VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

AST service routine to be executed. The astadr argument is the address
of the entry mask of this routine. In the case of synchronous completion,
the call might not take place. Refer to the description of DDTM$M_SYNC
in Table 22-3.
If you specify astadr, the AST routine executes at the same access mode
as the caller of the $END_TRANS service.

astprm
VMS usage:
type:
access:
mechanism:

user_arg
longword (unsigned)
read only
by value

AST parameter passed to the AST service routine specified by the astadr
argument. The astprm argument is a longword.

22-17

SYSTEM SERVICE DESCRIPTIONS
$END_TRANS

c
tid
VMS usage:
type:
access:
mechanism:

transaction_id
octaword (unsigned)
read only
by reference

Pointer to the transaction identifier (TID) structure that designates the
transaction to be committed. The default value for this parameter is the
curren t transaction.

DESCRIPTION

The End Transaction service instructs the DECdtm services to commit
a transaction. When $END_TRANS is called, the transaction manager
component of the DECdtm services implements the two-phase commit
protocol to inform all the transaction's participants (any resource managers
and transaction managers involved in the transaction) to commit.
The first phase of the two-phase commit protocol is termed the prepare
phase. In the prepare phase, the transaction manager sends a prepare
message to all participants. The prepare message requests each
participating resource manager to vote on its ability to complete the
transaction processing actions. The transaction manager waits to receive
the results of the prepare message.
The participants must notify the transaction manager whether they have
succeeded or failed in performing their transaction processing work. If a
participating resource manager is able to prepare, it sends a "yes" vote to
the transaction manager. If the resource manager is unable to prepare,
it casts a "no" vote. If the resource manager fails before replying, the
transaction manager assumes a "no" vote.

()

When all participants have responded to the prepare request, the
transaction manager proceeds to the second phase, the commit phase.
If all of the participants have successfully completed the prepare phase
and voted "yes," the transaction manager orders the participants to commit
the transaction. Each participating resource manager completes commit
processing for its transaction by writing a commit log record to its local
transaction log file. A distributed transaction is complete when all its
actions, such as changes to databases, are made permanent.
If an application calls $ABORT_TRANS or $ABORT_TRANSW or if any
of the participants have failed to prepare successfully, the transaction
is aborted. For example, a resource manager might fail to prepare
successfully due to a process failure, machine failure, or hardware
failure. In the abort phase, the transaction manager orders all remaining
participants to abort the transaction and roll back their transaction
processing work. Thus, none of the actions of the distributed transaction
is made permanent.
$END_TRANS returns a failure status (SS$_ABORT) if the prepare
phase does not complete successfully or if an error occurs that makes it
impossible to commit the transaction.
Required Privileges

None.

22-18

SYSTEM SERVICE DESCRIPTIONS

$END_TRANS

o
Required Quota
ASTLM
Related Services
$ABORT_TRANS, START_TRANS

CONDITION
VALUES
RETURNED

o
CONDITION
VALUES

SS$_NORMAL

The operation was successfully queued.

SS$_SYNCH

The synchronous operation completed successfully.

SS$_ABORT

The transaction aborted during processing.

SS$_ACCVIO

The 10SB or TID cannot be read by the caller, or the
10SB cannot be written by the caller.

SS$_BADPARAM

The operations flags are invalid.

SS$_EXASTLM

The process has exceeded its AST limit quota.

SS$_'LLEFC

The efn argument specifies an illegal flag number.

SS$_INSFMEM

There is insufficient system dynamic memory for the
operation.

SS$_NOCURTID

No default TID is defined.

SS$_NOSUCHTID

The designated TID is unknown.

SS$_WRONGSTATE

The transaction is in the wrong state for the attempted
operation.

Same as those returned in RO. A value of SS$_NORMAL returned in the
I/O status block indicates that the service completed successfully.

RETURNED IN
THE 1/0 STATUS
BLOCK

o
22-19

SYSTEM SERVICE DESCRIPTIONS
$END_TRANSW

$END_ TRANSW

End Transaction and Wait

Commits a given transaction. It returns a failure status (SS$_ABORT) if an
error occurs that makes it impossible the transaction to be committed.
$END_TRANSW completes synchronously; that is, it returns to the caller after
the request has actually completed.
For asynchronous completion, you use the End Transaction ($END_TRANS)
system service, which commits a transaction and allocates a transaction
identifier without waiting for the operation to complete.
In all other respects, $END_TRANSW is identical to $END_TRANS.
For all other information about $END_TRANSW, refer to the section on
$END TRANS.

(~,

~ __ ~

For additional information about system service completion, refer to the
Synchronize ($SYNCH) service and to Introduction to VMS System Services.

FORMAT

SYS$END_TRANSW

[efn] ,[flags] ,iosb ,[astadr]
,[astprm] ,[tid]

o
22-20

SYSTEM SERVICE DESCRIPTIONS

$FORMAT_AUDIT

Format Security Audit Event
Message

Converts a security auditing event message from binary format to ASCII text
and filters information the user considers too sensitive to display.

FORMAT

SVS$FORMAT_AUDIT
[fmttyp] ,audmsg ,[out/en] ,[outbuf] ,[width] ,[trmdsc]
,[routin] [,fmtt/g]

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

ARGUMENTS

fmttyp
VMS usage: longword_unsigned
type:
longword (unsigned)
access:
read only
mechanism: by value

Format for the message. The fmttyp argument is a value indicating
whether the security audit message should be in brief format, which is one
line of information, or full format. The default is full format. See the VMS
Audit Analysis Utility Manual for examples of formatted output.
Value

Meaning

NSA$C_FORMAT_STYLE_BRIEF

Use a brief format for the message.

NSA$C_FORMAT_STYLE_FULL

Use a full format for the message.

audmsg
VMS usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor

Security auditing message to format. The audmsg argument is the
address of a character descriptor pointing to a buffer containing the binary
message that requires formatting.

22-21

SYSTEM SERVICE DESCRIPTIONS

$FORMAT_AUDIT

out/en
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

Length of the formatted security audit message. The outlen argument is
the address of the word receiving the final length of the ASCII message.

outbuf
VMS usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor

Buffer holding the formatted message. The outbuf argument is the
address of a descriptor pointing to the buffer receiving the message.

width
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
read only
by reference

Maximum width of the formatted message. The width argument is the
address of a word containing the line width value. The default is
80 columns.

trmdsc
VMS usage:
type:
access:
mechanism:

char_string
character-coded text string
read only
by descriptor

Line termination characters used in a full format message. The trmdsc
argument is the address of a descriptor pointing to the line termination
characters to insert within a line segment whenever the width is reached.

routin
VMS usage:
type:
access:
mechanism:

longword_unsigned
procedure
read only
by reference

Routine that writes a formatted line to the output buffer. The routin
argument is the address of a routine called each time a line segment
is formatted. The argument passed to the routine is the address of a
character string descriptor for the line segment.
When an application wants event messages in the brief format,
$FORMAT_AUDIT calls the routine twice to format the first event
message. The first time it is called, the routine passes a string containing
the column titles for the message. The second and subsequent calls to
the routine pass the formatted event message. By using this routine
argument, a caller can gain control at various points in the processing of
an audit event message.

22-22

0
__

SYSTEM SERVICE DESCRIPTIONS

$FORMAT_AUDIT

fmtflg
VMS usage:
type:
access:
mechanism:

longword (unsigned)
mask_longword
read only
by value

Determines the formatting of certain kinds of audit messages. The fmtflg
argument is a mask specifying whether sensitive information, such as
passwords, should be displayed or column titles built for messages in brief
format. The following table describes the significant bits:
Bit

Value

Description

Do not format sensitive information, for example,
passwords.

Format sensitive information.
Build a column title for messages in brief format. (You
must specify a fmttyp of brief and a routin argument.)

DESCRIPTION

Do not build column titles.

The Format Audit service converts a security auditing event message
from binary format to ASCII text and can filter information-for example,
passwords. $FORMAT_AUDIT allows the caller to format a message in a
multiple line format or a single line format and tailor the information for
a display device of a specific width.
$FORMAT_AUDIT is intended for utilities that need to format the security
auditing event messages received from the audit server listener mailbox or
the system security audit log file.
Required Privileges

None.
Required Quota

$FORMAT_AUDIT can cause a process to exceed the paging file limit
(PGFLQUOTA) if it has to format a long auditing event message. The
caller of $FORMAT_AUDIT can also receive quota violations from services
that $FORMAT_AUDIT uses, such as $IDTOASC, $FAO, and $GETMSG.
Related Services

None.

CONDITION
VALUES
RETURNED

SS$_NORMAL

The service completed successfully.

SS$_MSGNOTFND

The service completed successfully; however, the
message code cannot be found and a default
message has been returned.

22-23

SYSTEM SERVICE DESCRIPTIONS

$FORMAT_AUDIT

The item list cannot be read by the caller, or the buffer
length or buffer cannot be written by the caller.
The item list contains an invalid identifier.
SS$_BUFFEROVF

The service completed successfully; however, the
formatted output string overflowed the output buffer
and has been truncated.
The process dynamic memory is insufficient for
opening the rights database.
The contents of the context longword are not valid.
The specified identifier is of invalid format.
The specified identifier name does not exist in the
rights database.

Because the rights database is an indexed file that you access with VMS
RMS, this service can also return RMS status codes associated with
operations on indexed files. For descriptions of these status codes, refer to
the VMS Record Management Services Manual.

o
o

o
22-24

SYSTEM SERVICE DESCRIPTIONS

$HASH_PASSWORD

Hash Password
Applies the hash algorithm you select to an ASCII password string and returns
a quadword hash value that represents the encrypted password.

FORMAT

SYS$HASH_PASSWORD
pwd ,alg ,[salt] ,usrnam ,hash

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

ARGUMENTS

pwd
VMS usage: char_string
type:
character-coded text string
access:
read only
mechanism: by descriptor-fixed-Iength string descriptor

ASCII password string to be encrypted. The pwd argument is the address
of a character string descriptor pointing to the ASCII password. The
password string can contain between 1 and 32 characters and use the
uppercase characters A through Z, the numbers 0 through 9, the dollar
sign ($), and the underscore (_).

alg
byte_unsigned
byte (unsigned)
read only
by value
Algorithm used to hash the ASCII password string. The alg argument
is an unsigned byte specifying the hash algorithm. The VMS operating
system recognizes the following algorithms:
VMS usage:
type:
access:
mechanism:

Symbolic Name

Description
Uses a eRe algorithm and returns a longword hash
value. This algorithm was used in releases prior to
VMS Version 2.0.

Uses a Purdy algorithm over salted input. It expects
a blank-padded user name and returns a quadword
hash value. This algorithm was used during VMS
Version 2.0 field test.

22-25

SYSTEM SERVICE DESCRIPTIONS

$HASH_PASSWORD

Symbolic Name

Description
Uses the Purdy algorithm over salted input. It
expects a variable length user name and returns a
quadword hash value. This algorithm was used in
releases prior to VMS Version 5.4.
Uses the Purdy algorithm over salted input. It
expects a variable length user name and returns
a quadword hash value. This algorithm is used to
hash all new passwords in VMS Version 5.4 and
later.

UAI$C PREFERED
ALGORITHM 1
-

Represents the latest encryption algorithm that
the VMS system uses to encrypt new passwords.
Currently, it equates to UAI$C_PURDY_So Digital
recommends that you use this symbol in source
modules because it always equates with the most
recent VMS algorithm.

1 The value of this symbol might be changed in future releases if an additional algorithm is

introduced.

Values ranging from 128 to 255 are reserved for customer use; the constant
UAI$K_CUST_ALGORITHM defines the start of this range.
You can use the UAI$_ENCRYPT and UAI$_ENCRYPT2 item codes
with the $GETUAI system service to retrieve the primary and secondary
password hash algorithms for a user.

O~~. ~
~~~

salt
VMS usage: word_unsigned
type:
word (unsigned)
access:
read only
mechanism: by value

Value used to increase the effectiveness of the hash. The salt argument
is an unsigned word containing 16 bits of data that is used by the hash
algorithms when encrypting a password for the associated user name. The
$GETUAI item code UAI$_SALT is used to retrieve the SALT value for a
given user. If you do not specify a SALT value, $HASH_PASSWORD uses
the value of O.

~--\

~ ~.

usrnam
char_string
character-coded text string
read only
by descriptor-fixed-Iength string descriptor
N arne of the user associated with the password. The usrnam argument is
the address of a descriptor pointing to a character text string containing
the user name. The current VMS password encryption algorithm (UAI$K_
PURDY_S) folds the user name into the ASCII password string to ensure
that different users with the same password produce different hash values.
This argument must be supplied for all calls to $HASH_PASSWORD but
is ignored when using the CRC algorithm ( U A I $ K _ A D _ I I ) . '
VMS usage:
type:
access:
mechanism:

22-26

~. \

SYSTEM SERVICE DESCRIPTIONS

$HASH_PASSWORD

hash
quadword_unsigned
quadword (unsigned)
write only
by reference
Output hash value representing the encrypted password. The hash
argument is the address of an unsigned quadword to which $HASH_
PASSWORD writes the output of the hash. If you use the UAI$C_AD_II
algorithm, the second longword of the hash is always set to zero.
VMS usage:
type:
access:
mechanism:

DESCRIPTION

Applies the hash algorithm you select to an ASCII password string and
returns a quadword hash value that represents the encrypted password.
Required Privileges
None.
Required Quota
None.
Related Services

$GETUAI and $SETUAI. Use $GETUAI to get the values for the salt and
alg arguments. Use $SETUAI to store the resulting hash using the item
codes UAI$_PWD and UAI$_PWD2.

CONDITION
VALUES
RETURNED

SS$_NORMAL

The service completed successfully.

SS$_ACCVIO

The input or output buffer descriptors cannot be read
or written to by the caller.

SS$_BADPARAM

The specified hash algorithm is unknown or invalid.

o
22-27

SYSTEM SERVICE DESCRIPTIONS

$INIT_VOL

Initialize Volume
Formats a disk or magnetic tape volume and writes a label on the volume. At
the end of initialization, the disk is empty except for the system files containing
the structure information. All former contents of the volume are lost.

FORMAT

SYS$INIT_ VOL

RETURNS

VMS usage:
type:
access:
mechanism:

devnam, vo/nam [,itm/st]

cond_value
longword (unsigned)
write only
by value

ARGUMENTS

devnam
VMS usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Name of the device on which the volume is physically mounted. The
descriptor must point to the device name, a character string of 1 to 64
characters. The device name can be a physical device name or a logical
name; if it is a logical name, it must translate to a physical name.

0.
.

The device does not have to be currently allocated; however, allocating the
device before initializing it is recommended.

volnam
char_string
character string
read only
by descriptor
Identification to be encoded on the volume. The descriptor must point
to the volume name, a character string of 1 to 12 characters. For a disk
volume name, you can specify a maximum of 12 alphanumeric characters;
for a magnetic tape volume name, you can specify a maximum of 6 ANSI
"a" characters. Any valid ANSI "a" characters can be used; these include
numbers, uppercase letters, and anyone of the following nonalphanumeric
characters:
VMS usage:
type:
access:
mechanism:

! "%'()*+,-. /: ;<=>

N onalphanumeric characters are not allowed in the volume name on disk.

22-28

SYSTEM SERVICE DESCRIPTIONS

$INIT_VOl

ilm/sl
VMS usage:
type:
access:
mechanism:

item_Iist_3
longword (unsigned)
read only
by reference

Item list specifying options that can be used when initializing the volume.
The itmlst argument is the address of a list of item descriptors, each of
which describes one option. The list of item descriptors is terminated by a
longword of O.
The following diagram depicts the format of a single item descriptor:
31

Item Code

Buffer Length

Buffer Address
Return Length Address
ZK-1705-GE

$INIT_ VOL Item Descriptor Fields
buffer length

A word specifying the length, in bytes, of the buffer that supplies the
information $INIT_VOL needs to process the specified item code. The
length of the buffer needed depends upon the item code specified in the
item descriptor.
item code

A word containing an option for the initialize operation. These codes are
defined by the $INITDEF macro.
There are three types of item codes:
•

Boolean item code. Boolean item codes specify a true or false
value. The form INIT$_code specifies a true value and the form
INIT$_NO_code specifies a false value. For Boolean item codes, the
buffer length and buffer address fields of the item descriptor must
be zero.

•

Symbolic value item code. Symbolic value item codes specify one of
a specified range of possible choices. The buffer length and buffer
address fields of the item descriptor must be zero.

•

Input value item code. Input value item codes specify a value to be
used by $INIT_VOL. The buffer length and buffer address fields of
the item descriptor must be nonzero.

Each item code is described after the argument descriptions.

buffer address

A longword containing the address of the buffer that supplies information
to $INIT_VOL.

22-29

SYSTEM SERVICE DESCRIPTIONS

$INIT_VOL

return length address

This field is not used.

item codes
INIT$_ACCESSED

An input item code that specifies the number of directories allowed in
system space on the volume.
You must specify an integer between 0 and 255 in the input buffer. The
default value is 3.
The INIT$_ACCESSED item code applies only to Files-II Structure Level
1 disks.
INIT$_BADBLOCKS_LBN

An input item code that enables $INIT_VOL to mark bad blocks on the
volume; no data is written to those faulty areas. INIT$_BADBLOCKS_
LBN specifies faulty areas on the volume by logical block number and
block count.
The buffer from which $INIT_VOL reads the option information contains
an array of quadwords containing information in the following format:

Logical Block Number
Count

ZK-1590A-GE

The following table describes the information to be specified for INIT$_
BADBLOCKS_LBN:
Field

Symbol Name

Logical block
number
Count

Description

Specifies the logical block number
of the first block to be marked as
allocated
INIT$L_BADBLOCKS_
COUNT

Specifies the number of blocks to
be allocated. This range begins
with the first block, as specified in
INIT$L_BADBLOCKS_LBN

For example, if the input buffer contains the values 5 and 3, INIT_VOL
starts at logical block number 5 and allocates 3 blocks.
The number of entries in the buffer is determined by the buffer length
field in the item descriptor.
All media supplied by Digital and supported on the VMS operating system,
except floppy disks and TU58 cartridges, are factory formatted and contain
bad block data. The Bad Block Locator Utility (BAD) or the diagnostic
formatter EVRAC can be used to refresh the bad block data or to construct
it for the floppy disks and TU58 cartridges.

22-30

0
I

•.

SYSTEM SERVICE DESCRIPTIONS

$INIT_VOL

The INIT$_BADBLOCKS_LBN item code is necessary only to enter bad
blocks that are not identified in the volume's bad block data. For more
information, see the VMS Bad Block Locator Utility Manual.
The INIT$_BADBLOCKS_LBN item code applies only to disks.
INIT$_BADBLOCKS_SEC

An input item code that specifies faulty areas on the volume by sector,
track, cylinder, and block count. $INIT_VOL marks the bad blocks as
allocated; no data is written to them.
The input buffer must contain an array of octawords containing
information in the following format:

31
Sector
Count
Track
Cylinder

ZK-1591A-GE

o
0

The following table describes the information to be specified for INIT$_
BADBLOCKS_LBN:
Field

Symbol Name

Description

Sector

INIT$L_BADBLOCKS_
SECTOR

Specifies the sector number of the
first block to be marked as allocated

Count

INIT$L_BADBLOCKS_
COUNT

Specifies the number of blocks to
be allocated

Track

INIT$L_BADBLOCKS_
TRACK

Specifies the track number of the
first block to be marked as allocated

Cylinder

INIT$L_BADBLOCKS_
CYLINDER

Specifies the cylinder number of the
first block to be marked as allocated

For example, if the input buffer contains the values 12, 3, 1 and 2, INIT_
VOL starts at sector 12, track 1, cylinder 2 and allocates 3 blocks.
The number of entries in the buffer is determined by the buffer length
field in the item descriptor.

All media supplied by Digital and supported on the VMS operating system,
except floppy disks and TU58 cartridges, are factory formatted and contain
bad block data. The Bad Block Locator Utility (BAD) or the diagnostic
formatter EVRAC can be used to refresh the bad block data or to construct
it for the floppy disks and TU58 cartridges. The INIT$_BADBLOCKS_
SEC item code is necessary only to enter bad blocks that are not identified
in the volume's bad block data. For more information, see the VMS Bad
Block Locator Utility Manual.
The INIT$_BADBLOCKS_SEC item code applies only to disks.

22-31

SYSTEM SERVICE DESCRIPTIONS

$INIT_VOL

INIT$_CLUSTERSIZE

An input item code that specifies the minimum allocation unit in blocks.
The input buffer must contain a longword value. The maximum size that
can be specified for a volume is one-hundredth the size of the volume; the
minimum size is calculated with the following formula:
volume size in blocks
255 * 4096

The INIT$_CLUSTERSIZE item code applies only to Files-II Structure
Level 2 disks (for Files-II Structure Level 1 disks, the cluster size is 1).
For Files-II Structure Level 2 disks, the cluster size default depends on
the disk capacity.
•

Disks that are 50,000 blocks or larger have a default cluster size of 3.

•

Disks smaller than 50,000 blocks have a default value of 1.

INIT$_COMPACTION
INIT$_NO_COMPACTION-Default

A Boolean item code that specifies whether data compaction should be
performed when writing the volume.
The INIT$_COMPACTION item code applies only to TA90 drives.
INIT$_DENSITY

A symbolic item code that specifies the density value for magnetic tapes
and diskettes.
For magnetic tape volumes, the INIT$_DENSITY item code specifies the
density in bytes per inch (bpi) at which the magnetic tape is written.
Possible symbolic values for tapes are as follows:
•

INIT$K_DENSITY_800_BPI

•

INIT$K_DENSITY_1600_BPI

•

INIT$K_DENSITY_6250_BPI

The specified density value must be supported by the drive. If you do not
specify a density item code for a blank magnetic tape, the system uses a
default density of the highest value allowed by the tape drive. If the drive
allows 6250, 1600, and 800 bpi operation, the default density is 6250. If
the drive allows only 1600 and 800 bpi operation, the default density is
1600. If you do not specify a density item code for a magnetic tape that
has been previously written, the· system uses the previously set volume
density.
For diskettes, the INIT$_DENSITY item code specifies how the diskette is
to be formatted. Possible symbolic values for diskettes are as follows:

22-32

•

INIT$K_DENSITY_SINGLE_DISK

•

INIT$K_DENSITY_DOUBLE_DISK

•

INIT$K_DENSITY_DD_DISK

•

INIT$K_DENSITY_HD _DISK

SYSTEM SERVICE DESCRIPTIONS

$INIT_VOL

For floppy disk volumes that are to be initialized on RX02, RX23 or RX33
diskette drives, the following values specify how the floppy disk is to be
formatted:
•

INIT$K_DENSITY_SINGLE_DISK

•

INIT$K_DENSITY_DOUBLE_DISK

•

INIT$K_DENSITY_DD_DISK

•

INIT$K_DENSITY_HD _DISK

Diskettes are initialized as follows:
•

RX23 diskettes-DD or HD density.

•

RX33 diskettes-double density only.

•

RX02 dual-density diskette drives-single or double density.

If you do not specify a density item code for a floppy disk, the system
leaves the volume at the density at which it was last formatted. RX02
floppy disks purchased from Digital are formatted in single density.

Note: Floppy disks formatted in double density cannot be read or
written by the console block storage device (an RXOI drive) of
a VAX-111780 processor until they have been reformatted in single
density.
INIT$_DIRECTORIES

An input item code that specifies the number of entries to preallocate for
user directories. The input buffer must contain a longword value in the
range of 16 to 16000. The default value is 16.
The INIT$_DIRECTORIES item code applies only to disks.

INIT$_ERASE
INIT$_NO_ERASE-Default

A Boolean item code that specifies whether deleted data should be
physically destroyed by performing the data security erase (DSE) operation
on the volume before initializing it. The INIT$_ERASE item code applies
to the following devices:
•

ODS-2 disk volumes

•

ANSI magnetic tape volumes on magnetic tape devices that support
the hardware erase function, for example, TU78 and MSCP magnetic
tapes.

For disk devices, this item code sets the ERASE volume attribute, causing
each file on the volume to be erased when it is deleted.
INIT$_EXTENSION

An input item code that specifies, by the number of blocks, the default
extension size for all files on the volume. The extension default is used
when a file increases to a size greater than its initial default allocation
during an update. For Files-11 Structure Level 2 disks, the buffer must
contain a longword value in the range 0 to 65535. For Files-11 Structure
Level 1 disks, the input buffer must contain a longword value in the range

22-33

SYSTEM SERVICE DESCRIPTIONS

0,',

$INIT_VOL

of 0 to 255. The default value is 5 for both Structure Levell and Structure
Level 2 disks.
The default extension set by this item code is used only if the following
conditions are in effect:
•

No default extension for the file has been set

•

No default extension for the process has been set using the SET RMS
command.

INIT$_FPROT

An input item code that specifies the default protection that is applied
to all files on the volume. The input buffer must contain a longword
protection mask that contains four 4-bit fields. Each field grants or denies
read, write, execute, and delete access to a category of users. Cleared
bits grant access; set bits deny access. The following diagram depicts the
structure of the protection mask:

(~\
~_

World

ZK-1S92A-G E

The INIT$_FPROT item code applies only to Files-II Structure Levell
disks and is ignored if it is used on a VMS system. VMS systems use
the default file extension set by the DCL command SET PROTECTION
/DEFAULT.

INIT$_HEADERS

An input item code that specifies the number of file headers to be allocated
for the index file. The input buffer must contain a longword value within
the range of 16 to the value set by the INIT$_MAXFILES item code. The
default value is 16.
The INIT$_HEADERS item code applies only to disks.

INIT$_HIGHWATER-Default
INIT$_NO_HIGHWATER

A Boolean item code that sets the file highwater mark (FHM) volume
attribute, which guarantees that a user cannot read data that he or she
has not written.
INIT$_NO_HIGHWATER disables FHM for a volume.
The INIT$_HIGHWATER and INIT$_NO_HIGHWATER item codes apply
only to Files-II Structure Level 2 disks.
INIT$_INDEX_BEGINNING

A symbolic item code that places the index file for the volume's directory
structure at the beginning of the volume. By default, the index is placed
in the middle of the volume.
This item code applies only to disks.

22-34

SYSTEM SERVICE DESCRIPTIONS
$INIT_VOL

INIT$_INDEX_BLOCK

An input item code that specifies the location of the index file for the
volume's directory structure by logical block number. The input buffer
must contain a longword value specifying the logical block number of the
first block of the index file. By default, the index is placed in the middle of
the volume.
The INIT$_INDEX_BLOCK item code applies only to disks.
INIT$_INDEX_END

A symbolic item code that places the index file for the volume's directory
structure at the end of the volume. The default is to place the index in the
middle of the volume.

This item code applies only to disks.
INIT$_INDEX_MIDDLE

A symbolic item code that places the index file for the volume's directory
structure in the middle of the volume. This is the default location for the
index.
This item code applies only to disks.
INIT$_LABEL_ACCESS

An input item code that specifies the character to be written in the volume
accessibility field of the VMS ANSI volume label VOL1 on an ANSI
magnetic tape. Any valid ANSI "a" characters can be used; these include
numbers, uppercase letters, and anyone of the following non alphanumeric
characters:
! "%'()*+,-. /: ;<=>
By default, the VMS operating system provides a routine SYS$MTACCESS
that checks this field in the following manner:

•

If the magnetic tape was created on a version of the VMS operating
system that conforms to Version 3 of ANSI, this item code is used to
override any character except an ASCII space.

•

If the magnetic tape conforms to an ANSI standard that is later than
Version 3, this item code is used to override any character except an
ASCII 1 character.

INIT$_LABEL_VOLO

An input item code that specifies the text that is written in the owner
identifier field of the VMS ANSI volume label VOL1 on an ANSI magnetic
tape. The owner identifier field can contain up to 14 valid ANSI "a"
characters.
INIT$_MAXFILES

An input item code that restricts the maximum number of files that the
volume can contain. The input buffer must contain a longword value
between 0 and a value determined by the following calculation:

volume size in blocks
cluster factor + 1

22-35

SYSTEM SERVICE DESCRIPTIONS
$INIT_VOL

o
Once initialized, the maximum number of files can be increased only by
reinitializing the volume.
The default maximum number of files is calculated as follows:
volume size in blocks
(cluster factor + 1) * 2

The INIT$_MAXFILES item code applies only to disks.
INIT$_OVR_ACCESS
INIT$_NO_OVR_ACCESS-Default

A Boolean item code that specifies whether to override any character in
the accessibility field of the VMS ANSI volume label VOLl on an ANSI
magnetic tape. For more information, see the Guide to VMS Files and
Devices.

(\
~ __ /

To specify INIT$_OVR_ACCESS, the caller must either own the volume or
have VOLPRO privilege.
INIT$_OVR_EXP
INIT$_NO_OVR_EXP-Default

A Boolean item code that specifies whether the caller writes to a magnetic
tape that has not yet reached its expiration date. This item code only
applies to the magnetic tapes that were created before VMS Version 4.0
and that use the D% format in the volume owner identifier field.

C)
. .. - .

To specify INIT$_OVR_EXP, the caller must either own the volume or have
VOLPRO privilege.
INIT$_OVR_VOLO
INIT$_NO_OVR_VOLO-Default

A Boolean item code that allows the caller to override processing of the
owner identifier field of the VMS ANSI volume label VOLl on an ANSI
magnetic tape.
To specify INIT$_OVR_VOLO, the caller must either own the volume or
have VOLPRO privilege.
INIT$_OWNER

An input item code that specifies the VIC that will own the volume. The
input buffer must contain a longword value, which is the VIC. The default
is the VIC of the caller.
For magnetic tapes, no VIC is written unless protection on the magnetic
tape is specified. If the INIT$_VPROT item code is specified but the
INIT$_OWNER item code is not specified, the VIC of the caller is assigned
ownership of the volume.
INIT$_READCHECK
INIT$_NO_READCHECK-Default

A Boolean item code that specifies whether data checking should be
performed for all read operations on the volume. For more information
about data checking, see the VMS I/O User's Reference Manual: Part I.
The INIT$_READCHECK item code applies only to disks.

22-36

SYSTEM SERVICE DESCRIPTIONS

$INIT_VOL

INIT$_SIZE

An input item code that specifies the number of blocks allocated for a RAM
disk with a device type of DT$_RAM_DISK. The input buffer must contain
a longword value.
INIT$_STRUCTURE_LEVEL_1
INIT$_STRUCTURE_LEVEL_2-Default

Symbolic item codes that specify whether the volume should be formatted
in Files-II Structure Levell or Structure Level 2. Structure Level 1 is
incompatible with the following item codes:

•

INIT$_READCHECK

•

INIT$_WRITECHECK

•

INIT$_CLUSTERSIZE

The default protection for a Structure Level 1 disk is full access to system,
owner, and group users, and read access to all other users.
The INIT$_STRUCTURE_LEVEL_l item code applies only to disks.
INIT$_USER_NAME

An input item code that specifies the user name that is associated with
the volume. The input buffer must contain a character string from 1 to 12
alphanumeric characters, which is the user name. The default is the user
name of the caller.
INIT$_VERIFIED
INIT$_NO_VERIFIED

A Boolean item code that indicates whether the disk contains bad block
data. INIT$_NO_VERIFIED indicates that any bad block data on the
disk should be ignored. For disks with 4096 blocks or more, the default is
INIT$_VERIFIED.

INIT$_NO_VERIFIED is the default for the following:
•

Disks with less than 4096 blocks

•

Digital Storage Architecture (DSA) devices

•

Disks which are not last-track devices

The INIT$_VERIFIED item codes apply only to disks.
INIT$_VPROT

An input item code that specifies the protection that is assigned to the
volume. The input buffer must contain a longword protection mask that
contains four 4-bit fields. Each field grants or denies read, write, execute,
and delete access to a category of users. Cleared bits grant access; set bits
deny access.

c
22-37

SYSTEM SERVICE DESCRIPTIONS
$INIT_VOL

o
The following diagram depicts the structure of the protection mask:
World

Group

Owner

System

ZK-1S92A-G E

The default is the default protection of the caller.
For magnetic tape, the protection code is written to a VMS-specific volume
label. The system only applies read and write access restrictions; execute
and delete access are ignored. Moreover, the system and the owner are
always given read and write access to magnetic tapes, regardless of the
protection mask specified.
When you specify a protection mask for a disk volume, access type E
(execute) indicates Create Access.
INIT$_WINDOW
The INIT$_WINDOW item code specifies the number of mapping pointers
to be allocated for file windows. The input buffer must contain a longword
value in the range 7 to 80. The default is 7.

When a file is opened, the file system uses the mapping pointers to access
the data in the file.

/<'--~

The INIT$_WINDOW item code applies only to disks.
INIT$_WRITECHECK
INIT$_NO_ WRITECHECK-Default

DESCRIPTION

The Initialize Volume system service formats a disk or magnetic tape
volume and writes a label on the volume. At the end of initialization,
the disk is empty except for the system files containing the structure
information. All former contents of the volume are lost.
A blank magnetic tape can sometimes cause unrecoverable errors when
it is read. $INIT_VOL attempts to read the volume unless the following
three conditions are in effect:
•

INIT$_OVR_ACCESS Boolean item code is specified.

•

INIT$_OVR_EXP Boolean item code is specified.

•

Caller has VOLPRO privilege.
If the caller has VOLPRO privilege, $INIT_VOL initializes a disk
without reading the ownership information. Otherwise, the ownership
of the volume is checked.

22-38

O·\
..-.

SYSTEM SERVICE DESCRIPTIONS

$INIT_VOL

A blank floppy disk or a diskette with an incorrect format can sometimes
cause a fatal drive error. Such a diskette can be initialized successfully by
specifying the INIT$_DENSITY item code to format the diskette.
Required Privileges

To initialize a particular volume, the caller must either have volume
protection (VOLPRO) privilege or the volume must be one of the following:

•

Blank disk or magnetic tape; that is, a volume that has never been
written

•

Disk that is owned by the caller's VIC or by the VIC [0,0]

•

Magnetic tape that allows write access to the caller's VIC or that was
not protected when it was initialized

Required Quota

None.

CONDITION
VALUES
RETURNED

SS$_NORMAL

The service completed successfully.

SS$_ACCVIO

The item list or an address specified in the item list
cannot be accessed.

SS$_BADPARAM

A buffer length of zero was specified with a nonzero
item code or an illegal item code was specified.
A concurrent call to SYS$INIT_VOL is already active
for the process.
The caller does not have sufficient privilege to initialize
the volume.

SS$_NOSUCHDEV

The specified device does not exist on the host
system.

The $INIT_VOL service can also return the following condition values, which are
specific to the Initialize Volume Utility. The symbolic definition macro $INITDEF defines
these condition values.
INIT$_ALLOCFAIL

Index file allocation failure.

INIT$_BADACCESSED

Value for INIT$_ACCESSED item code out of range.

INIT$_BADBLOCKS

Invalid syntax in bad block list.

INIT$_BADCLUSTER

Value for INIT$_CLUSTER_SIZE item code out of
range.

INIT$_BADDENS

Invalid value for INIT$_DENSITY item code.

INIT$_BADDIRECTORIES

Value for INIT$_DIRECTORIES item code out of
range.

INIT$_BADEXTENSION

Value for INIT$_EXTENSION item code out of range.

INIT$_BADHEADERS

Value for INIT$_HEADERS item code out of range.

IN IT$_BADMAXFI LES

Value for INIT$_MAXFILES item code out of range.

22-39

SYSTEM SERVICE DESCRIPTIONS
$INIT_VOL

c
INIT$_BADOWNID

Invalid value for owner 10.

INIT$_BADRANGE

Bad block address not on volume.

INIT$_BADVOL 1

Bad VOL 1 ANSI label.

INIT$_BADVOLACC

Invalid value for INIT$_LABEL_ACCESS item code.

INIT$_BADVOLLBL

Invalid value for ANSI tape volume label.

INIT$_BADWINDOWS

Value for INIT$_WINDOWS item code out of range.

INIT$_BLKZERO

Block zero is bad-volume not boatable.

INIT$_CLUSTER

Unsuitable cluster factor.

INIT$_CONFQUAL

Conflicting options were specified.

INIT$_DIAGPACK

Disk is a diagnostic pack.

INIT$_ERASEFAIL

Volume not completely erased.

INIT$_FACTBAD

Cannot read factory bad block data.

INIT$_ILLOPT

Item codes not appropriate for the device were
specified.

INIT$_INDEX

Invalid index file position.

INIT$_LARGECNT

Disk too large to be supported.

INIT$_MAXBAD

Bad block table overflow.

INIT$_MTLBLLONG

Magnetic tape label specified is longer than
6 characters.

INIT$_MTLBLNONA

Magnetic tape label specified contains non-ANSI "a"
characters.

INIT$_NOBADDATA

Bad block data not found on volume.

INIT$_NONLOCAL

Device is not a local device.

INIT$_NOTRAN

Logical name cannot be translated.

INIT$_NOTSTRUC1

Option(s) not available with Files-11
Structure Level 1.
Unknown device type.

o
CJ

o
22-40

SYSTEM SERVICE DESCRIPTIONS

$RELEASE_VP

Release Vector Processor
Terminates the current process's status as a vector consumer.

FORMAT

SYS$RELEASE_VP

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

()

ARGUMENTS

None.

DESCRIPTION

The Release Vector Processor service terminates the current process's
status as a vector consumer. $RELEASE_VP waits for all pending vector
instructions and vector memory operations to complete. It then declares
that the process no longer needs a vector-present processor. As a result,
the process relinquishes its use of the processor's vector registers and can
be scheduled on another processor in the system.
In systems that do not have vector-present processors but do have the
VAX vector instruction emulation facility (VVIEF) in use, this service
relinquishes the process's use of VVIEF. The VVIEF remains mapped in
the process's address space.

Required Privileges

None.
Required Quota

None.
Related Services

$RESTORE_VP_EXCEPTION,$RESTORE_VP_STATE,$SAVE_VP_
EXCEPTION

CONDITION
VALUES
RETURNED

The service completed successfully.

22-41

SYSTEM SERVICE DESCRIPTIONS
$RESTORE_VP_EXCEPTION

$RESTORE_VP_EXCEPTION Restore Vector
Processor Exception State
Restores the saved exception state of the vector processor.

FORMAT

SYS$RESTORE_VP_EXCEPTION

RETURNS

VMS usage:
type:
access:
mechanism:

excid

cond_value
longword (unsigned)
write only
by value

Longword condition value. All system services (except $EXIT) return by
immediate value a condition value in RO. Condition values returned by
this service returns are listed in the Condition Values Returned section.

ARGUMENTS

excid
VMS usage:
type:
access:
mechanism:

context
longword (unsigned)
read only
by reference

c-\

""~_)

Internal ID of the exception state saved by $SAVE_VP_EXCEPTION. The
excid argument is the address of a longword containing this ID.

DESCRIPTION

The Restore Vector Exception State service restores from memory the
vector exception state saved by a prior call to $SAVE_VP _EXCEPTION.
After a routine invokes this service, the next vector instruction issued
within the process causes the restored vector exception to be reported.

By default, when an AST or condition handler interrupts the execution of a
mainline routine, VMS saves the mainline routine's vector state, including
its vector exception state. Any other routine that executes synchronously
with, or asynchronously to, currently executing vectorized code and that
performs vector operations itself must preserve the preempted routine's
vector exception state across its own execution. It does so by using the
$SAVE_VP_EXCEPTION and $RESTORE_VP_EXCEPTION services.
U sed together, these services ensure that vector exceptions occurring as a
result of activity in the original routine are serviced by existing condition
handlers within that routine.
In systems that do not have vector-present processors but do have the VAX
vector instruction emulation facility (VVIEF) in use, VVIEF emulates the
function of this service.
Required Privileges

None.

22-42

SYSTEM SERVICE DESCRIPTIONS
$RESTORE_VP_EXCEPTION

Required Quota

BYTLM
Related Services

$RELEASE_VP, $RESTORE_VP_STATE, $SAVE_VP_EXCEPTION

CONDITION
VALUES
RETURNED

C·.\
/

The service completed successfully. The service also
returns this status when executed in a system that
does not have vector-present processors and that
does not have the VAX vector instruction emulation
facility (VVIEF) loaded.
SS$_ACCVIO

The caller cannot read the exception ID longword.

SS$_NOSAVPEXC

No saved vector exception state exists for this
exception ID.

o
22-43

SYSTEM SERVICE DESCRIPTIONS

$RESTORE_VP_STATE

o
Restore Vector State

Allows an AST routine or condition handler to restore the vector state of the
mainline routine.

FORMAT
RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

ARGUMENTS

None.

DESCRIPTION

The Restore Vector State service allows an AST routine or a condition
handler to restore the vector state of the process's mainline routine.
By default, when an asynchronous routine (AST routine or condition
handler) interrupts the execution of a mainline routine, VMS creates a
new vector state when the routine issues its first vector instruction. At
this point, the vector state of the mainline routine is inaccessible to the
asynchronous routine. If the asynchronous routine must manipulate the
vector state of the mainline routine, it first calls $RESTORE_VP_STATE
to restore the mainline's vector state.

o
0

In systems that do not have vector-present processors but do have the VAX
vector instruction emulation facility (VVIEF) in use, VVIEF emulates the
functions of this service.
This service can be called only from a routine running in user mode.
Required Privileges

None.
Required Quota

None.
Related Services

$RELEASE_VP, $RESTORE_VP_EXCEPTION, $SAVE_VP_EXCEPTION

22-44

SYSTEM SERVICE DESCRIPTIONS

$RESTORE_VP_STATE

CONDITION
VALUES
RETURNED

The service completed successfully. Vector state of
the mainline has been restored. The service also
returns this status when executed in a system that
does not have vector-present processors and that
does not have the VAX vector instruction emulation
facility (VVIEF) loaded.
88$_BAD8TACK

Bad user stack encountered.

88$_BADCONTEXT

The mainline vector state is corrupt.

88$_WRONGACMODE

The system service was called from an access mode
other than user mode.

o
o

o
22-45

SYSTEM SERVICE DESCRIPTIONS
$SAVE_VP_EXCEPTION

o
Save Vector Processor
Exception State

Saves the pending exception state of the vector processor.

FORMAT

SYS$SAVE_VP_EXCEPTION

RETURNS

VMS usage:
type:
access:
mechanism:

excid

cond_value
longword (unsigned)
write only
by value

ARGUMENTS

excid
context
longword (unsigned)
read only
by reference
Internal ID of the exception state saved by $SAVE_VP_EXCEPTION. The
excid argument is the address of a longword containing this ID.

VMS usage:
type:
access:
mechanism:

DESCRIPTION

The Save Vector Exception State service saves in memory any pending
vector exception state and clears the vector processor's current exception
state.
By default, when an AST or condition handler interrupts the execution of a
mainline routine, VMS saves the mainline routine's vector state, including
its vector exception state. Any other routine that executes synchronously
with, or asynchronously to, currently executing vectorized code and that
performs vector operations itself must preserve the preempted routine's
vector exception state across its own execution. It does so by using the
$SAVE_VP_EXCEPTION and $RESTORE_VP_EXCEPTION services.
U sed together, these services ensure that vector exceptions occurring as a
result of activity in the original routine are serviced by existing condition
handlers within that routine.

o
o

In systems that do not have vector-present processors but do have the VAX
vector instruction emulation facility (VVIEF) in use, VVIEF emulates the
functions of this service.
Required Privileges
None.

22-46

SYSTEM SERVICE DESCRIPTIONS

$SAVE_VP_EXCEPTION

Required Quota

None.
Related Services

$RELEASE_VP, $RESTORE_VP_EXCEPTION, $RESTORE_VP_STATE

CONDITION
VALUES
RETURNED

The service completed successfully. There were no
pending vector exceptions. The service also returns
this status when executed in a system that does not
have vector-present processors and that does not
have the VAX vector instruction emulation facility
(VVIEF) loaded.
SS$_ACCVIO

The caller cannot write the exception 10 longword.

SS$_INSFMEM

Insufficient system dynamic memory exists for
completing the service.
The service completed successfully. Pending vector
exception state has been saved.

o
c

o
22-47

SYSTEM SERVICE DESCRIPTIONS
$START_TRANS

o
Start Transaction
Starts a transaction by allocating a transaction identifier (TID) and establishing
the internal structures that define a transaction.

FORMAT

SYS$START_ TRANS

RETURNS

VMS usage:
type:
access:
mechanism:

[efn] ,[flags] ,iosb ,[astadr]
,[astprmJ,tid

cond_value
longword (unsigned)
write only
by value

ARGUMENTS

efn
VMS usage:
type:
access:
mechanism:

ef_number
longword (unsigned)
read only
by value

Number of the event flag to be set. The efn argument is a longword
containing this number; however, $START_TRANS uses only the low-order
byte. If you do not specify efn, $START_TRANS uses the default value O.

flags
VMS usage:
type:
access:
mechanism:

mask_longword
longword (unsigned)
read only
by value

O.\

Flags specifying options for $START_TRANS. The flags argument is a
longword bit mask that is the logical OR of each bit set, in which each bit
corresponds to an option.
The $DDTMDEF macro defines a symbolic name for each flag bit.
Table 22-4 describes each flag.

o
22-48

SYSTEM SERVICE DESCRIPTIONS

$START_TRANS

Table 22-4 $START_TRANS Operation Flags
Flag

Description

DDTM$M_NONDEFAULT

Indicates that this transaction is not the process default
(current) transaction.
Indicates successful synchronous completions by
returning SS$_SYNCH. When synchronous completion
is successful, the completion AST address is not called,
the IOS8 is not written, and the event flag is not set.
Indicates that the transaction might survive image
rundown. Caller must be in supervisor, executive, or
kernel mode.

iosb
io_status_block
quadword (unsigned)
write only
by reference
I/O status block (IOSB) to receive the final completion status of the
request. The iosb argument is the address of the quadword I/O status
block.

VMS usage:
type:
access:
mechanism:

The following diagram shows the structure of the I/O status block:

Reserved by Digital

Condition Value

Reserved by Digital

ZK-1224A-GE

astadr
ast_procedure
pr'ocedure entry mask
call without stack unwinding
by reference
AST service routine to be executed. The astadr argument is the address
of the entry mask of this routine.
VMS usage:
type:
access:
mechanism:

If you specify astadr, the AST routine executes at the same access mode
as the caller of the $START_TRANS service.
Note that the completion AST is not called if SS$_SYNCH is returned in
RO.

astprm

VMS usage:
type:
access:
mechanism:

user_arg
longword (unsigned)
read only
by value

22-49

SYSTEM SERVICE DESCRIPTIONS
$START_TRANS

o
AST parameter passed to the AST service routine specified by the astadr
argument. The astprm argument is a longword.

tid
VMS usage:
type:
access:
mechanism:

transaction_id
octaword (unsigned)
write only
by reference

Pointer to the transaction identifier (TID).

DESCRIPTION

The Start Transaction service starts a transaction and allocates a unique
TID for it.
The DECdtm services maintain the concept of a current transaction for
each process. When a transaction is started using $START_TRANS, that
transaction is considered the process default or current transaction. The
TID assigned by $START_TRANS identifies the current transaction.
There cannot be a current transaction already active for a process
when you start a new transaction, or an error is returned. The current
transaction becomes undefined when the current transaction is ended
by $END_TRANS or $ABORT_TRANS. However, it is possible to start
a nondefault transaction while the current transaction is in progress
by specifying the NONDEFAULT flag. A nondefault transaction is not
considered a current transaction.

O---~--.

Required Privileges

None.
Required Quota

$START_TRANS uses the job's buffered byte count quota limit (BYTLM)
and AST quota limit (ASTLM).
(\

Related Services

$AB ORT_TRANS, $END_TRANS

CONDITION
VALUES
RETURNED

22-50

SS$_NORMAL

The operation was successfully queued.

SS$_SYNCH

The synchronous operation completed successfully.

SS$_A80RT

The transaction aborted during processing.

SS$_ACCVIO

The IOS8 or TID cannot be read by the caller, or the
TID or IOS8 cannot be written by the caller.

SS$_ALRCURTIO

An attempt was made to start a default (current)
transaction when there was already one started.

SS$_8AOPARAM

The operations flags are invalid.

SS$_EXASTLM

The process has exceeded its AST limit quota.

SS$_EXQUOTA

The process quota was exceeded.

SYSTEM SERVICE DESCRIPTIONS

$START_TRANS

CONDITION
VALUES

SS$_ILLEFC

The efn argument specifies an illegal flag number.

SS$_INSFMEM

There is insufficient system dynamic memory for the
operation.

SS$_WRONGACMODE

The wrong access mode was specified; a process flag
was specified from user mode.

Same as those returned in RO. A value of SS$_NORMAL returned in the
1/0 status block indicates that the service completed successfully.

RETURNED IN
THE 1/0 STATUS
BLOCK

c
c

o
22-51

SYSTEM SERVICE DESCRIPTIONS
$START_ TRANSW

$START_ TRANSW

Start Transaction and Wait

Starts a transaction. It allocates a transaction identifier and establishes the
internal structures that define a transaction.
$START_ TRANSW completes synchronously; that is, it returns to the caller
after the request has actually completed. For asynchronous completion, you
use the Start Transaction ($START_TRANS) service; $START_TRANS starts
a transaction and allocates a transaction identifier without waiting for the
operation to complete.
In all other respects, $START_TRANSW is identical to $START_TRANS. For
all other information about the $START_ TRANSW service, refer to the section
on $START_ TRANS.
For additional information about system service completion, refer to the
Synchronize ($SYNCH) service and to the Introduction to VMS System
Services.

FORMAT

SYS$START_TRANSW

[efn] ,[flags] ,iosb ,[astadr]
,[astprm] ,tid

o
22-52

System Services

22.5 Modified System Services

22.5

Modified System Services
This section describes system services that have been modified in the VMS
Version 5.4 operating system.

22.5.1

$CHANGE_ACL
Modifications to $CHANGE_ACL include a new object type to support
vector processing and new item codes to support enhancements to system
security, described in the following sections.
22.5.1.1

Vector Processing: New Object Type
To control use of a system's vector processors, $CHANGE_ACL supports a
new CAPABILITY object type, which describes a restricted resource. With
the VMS Version 5.4 operating system, if the object type is CAPABILITY,
use the reserved name VECTOR. The only capability currently defined by
the VMS operating system is the VECTOR capability, governing the ability
of a subject to access a vector processor in the system. The symbolic name
is ACL$C_CAPABILITY.

22.5.1.2

System Security: New Item Codes
In Version 5.4 of the VMS operating system, $CHANGE_ACL accepts the
following item codes:

o
c

ACL$C_DELETE_ALL
When you specify ACL$C_DELETE_ALL, $CHANGE_ACL deletes the
entire Access Control List (ACL), including protected entries.
ACL$C_GRANT_ACE
When you specify ACL$C_GRANT_ACE, $CHANGE_ACL reads the next
ACE that matches the process's identifiers into the buffer pointed to by
bufadr. The returned ACE might grant or deny access to the object.
Since an ACL can have more than one matching ACE, you should proceed
as follows:

1
2

Specify an initial value of zero (0) for contxt.
Call $CHANGE_ACL repeatedly, without changing the value of

contxt, and test for the return status SS$_NOMOREACE, which
means that the ACL has no more matching entries.
ACL$C_NEXT_ACE
When you specify ACL$C_NEXT_ACE, $CHANGE_ACL advances through
an ACL, one ACE at a time. The contxt argument defines the initial and
final positions. The value of contxt itself is derived from the previous
ACL$C_FNDACETYP, ACL$C_FNDACLENT, or ACL$C_GRANT_ACE
operation.

The $CHANGE_ACL service returns the following new status codes:

You do not have privileges for the requested action.

22-53

System Services
22.5 Modified System Services

G
SS$_INCONOLCK

22.5.2

VMS encountered an irrecoverable error. Please submit
a Software Performance Report (SPR) that describes
conditions leading to the error.

$CHECK_ACCESS: Vector Processing and System Security Support
Like $CHANGE_ACL, $CHECK_ACCESS supports the new CAPABILITY
object type. Also note that $CHECK_ACCESS requires privilege to access
the UAF, for example, SYSPRV.
The $CHECK_ACCESS service returns the following new status codes:
Identifiers granted to the user exceed the number
allowed.
SS$_NOCALLPRIV

22.5.3

Caller lacks privilege for attempted operation.

SS$_NOSUCHSEC

The specified global section does not exist.

SS$_UNSUPPORTED

Operations on remote object are not supported.

$ENQ: Enhanced Lock Manager Support
The addition of the following new flags to $ENQ enables you to expedite
lock requests and force queueing of conversions.
LCK$M_EXPEDITE

This flag is valid only for new lock requests. Specifying this flag allows
a request to be granted immediately, provided the requested mode, when
granted, would not block any currently queued requests in the resource
conversion and wait queues. Currently, this flag is valid only for NLMODE
requests. If this flag is specified for any other lock mode, the request fails
and an error of SS$_UNSUPPORTED returned.
LCK$M_QUECVT

This flag is valid only for conversion operations. A conversion request with
the LCK$M_QUECVT flag set will be forced to wait behind any already
queued conversions.

o
(j

The conversion request is granted immediately, if there are no already
queued conversions.
The QUECVT behavior is valid only for a subset of all possible conversions.
Table 22-5 defines the legal set of conversion requests for LCK$M_
QUECVT. Illegal conversion requests fail, with SS$_BADPARAM
returned.

o
22-54

System Services

\
C

22.5 Modified System Services

Table 22-5

Legal QUECVT Conversions

Lock Mode
at Which
Lock Is Held

Lock Mode to Which Lock Is Converted
NL

Yes

Key to Lock Modes
NL-Nuillock
CR-Concurrent read
CW-Concurrent write
PR-Protected read
PW-Protected write
EX-Exclusive lock

22.5.4

$GETDVI: New Device Classes
In Version 5.4 of the VMS operating system, $GETDVI accepts the three
new device classes listed in Table 22-6.
Table 22-6

0
22.5.5

Values Returned by the DEVCLASS Item

Device Class

Value

Symbolic Name

Workstation

DC$_WORKSTATION

DECvoice

DC$_DECVOICE

Remote console storage

170

DC$_REMCSL_STORAGE

$GETJPI
The following sections describe new items codes that support vector
processing and enhancements to system security.
22.5.5.1

Vector Processi ng: New Item Codes

In Version 5.4 of the VMS operating system, $GETJPI accepts the
following item codes and returns information regarding a process's use
of system vector processing resources.

JPI$_FAST_ VP_SWITCH
When you specify JPI$_FAST_VP_SWITCH, $GETJPI returns an unsigned
longword containing the number of times this process has issued a vector
instruction that resulted in an inactive vector processor being enabled
without the expense of a vector context switch. In other words, this count
reflects those instances where the process has reenabled a vector processor
on which the process's vector context has remained intact.
22-55

System Services

22.5 Modified System Services

JPI$_SLOW_VP_SWITCH

When you specify JPI$_SLOW_VP_SWITCH, $GETJPI returns an
unsigned longword containing the number of times this process has
issued a vector instruction that resulted in an inactive vector processor
being enabled with a full vector context switch. This vector context switch
involves the saving of the vector context of the process that last used the
vector processor and the restoration of the vector context of the current
process.
JPI$_VP_CONSUMER

When you specify JPI$_VP_CONSUMER, $GETJPI returns a byte, the
low-order bit of which, when set, indicates that the process is a vector
consumer.
JPI$_VP_CPUTIM

When you specify JPI$_VP_CPUTIM, $GETJPI returns an unsigned
longword that contains the total amount of time the process has
accumulated as a vector consumer.
22.5.5.2

System Security: New Item Codes
In Version 5.4 of the VMS operating system, $GETJPI accepts the
following new item codes and returns information about process security
characteristics.
JPI$_RIGHTS_SIZE

When you specify JPI$_RIGHTS_SIZE, $GETJPI returns the number
of bytes required to buffer the rights list. The rights list includes both
the system rights list and the process rights list. Because the space
requirements for the rights list can change between the time you request
the size of the rights list and the time you fetch the rights list with JPI$_
RIGHTSLIST, you might want to allocate a buffer that is 10% larger.

,,_)

JPI$_PROCESS_RIGHTS

When you specify JPI$_PROCESS_RIGHTS, $GETJPI returns the binary
content of the process rights list as an array of quadword identifiers.
Each entry consists of a longword identifier value and longword identifier
attributes, shown in Table 22-7. Allocate a buffer that is sufficient to hold
the process rights list because $GETJPI only returns as much of the list
as will fit in the buffer.

0\",'.

Table 22-7 Attributes of an Identifier
Symbolic Name

Description

KGB$M_RESOURCE
KGB$M_DYNAMIC

Resources can be charged to the identifier.
Identifier can be enabled or disabled.

JPI$_SVSTEM_RIGHTS

When you specify JPI$_SYSTEM_RIGHTS, $GETJPI returns the system
rights list as an array of quadword identifiers. Each entry consists of a
longword identifier value and longword identifier attributes, shown in
Tablbe 22-7. $AGllocTaJtpeIa bUffer that is sufficl' ent tO holld the sylsltfiem. righhts
list ecause
E
onIy returns as much 0 f t h e ist as wi
t In t e
buffer.

22-56

0'"

System Services

22.5 Modified System Services

JPI$_RIGHTSLIST

When you specify JPI$_RIGHTSLIST, $GETJPI returns, as an array
of quadword identifiers, all identifiers applicable to the process. This
includes the process rights list (JPI$_PROCESS_RIGHTS) and the system
rights list (JPI$_SYSTEM_RIGHTS). Each entry consists of a longword
identifier value and longword identifier attributes, shown in Table 22-7.
Allocate a buffer that is sufficient to hold the rights list because $GETJPI
only returns as much of the list as will fit in the buffer.
JPI$_LAST_LOG'N_'

When you specify JPI$_LAST_LOGIN_I, $GETJPI returns, as a quadword
absolute time value, the date of the last successful interactive login prior
to the current session. It returns a quadword of 0 when processes have
not executed the LOGINOUT image.
JPI$_LAST_LOGIN_N

When you specify JPI$_LAST_LOGIN_N, $GETJPI returns, as
a quadword absolute time value, the date of the last successful
noninteractive login prior to the current session. It returns a quadword of
o when processes have not executed the LOGINOUT image.
JPI$_LOGIN_FAILURES

When you specify JPI$_LOGIN_FAILURES, $GETJPI returns the number
of login failures that occurred prior to the current session. It returns a
longword of 0 when processes have not executed the LOGINOUT image.
JPI$_LOGIN_FLAGS

When you specify JPI$_LOGIN_FLAGS, $GETJPI returns a longword
bitmask containing information related to the login sequence. It returns
a longword of 0 when processes have not executed the LOGIN OUT image.
The following bits are defined:
Symbolic Name

Description
User had new mail messages waiting at
login.

JPI$M_PASSWORD_CHANGED

User changed the primary password during
login.
User's primary password expired during
login.
System gave the user a warning at login
that the account's primary password would
expire within 5 days.
Account's secondary password was
changed during login.
Account's secondary password expired
during login.

System gave the user a warning at login
that the account's secondary password
would expire within 5 days.

22-57

System Services
22.5 Modified System Services

22.5.6

$GETSVI
The following sections describe new items codes that support vector
processing and enhancements to system security.
22.5.6.1

Vector Processing: New Item Codes

In Version 5.4 of the VMS operating system, $GETSYI accepts the
following item codes and returns information regarding the system's
vector processing configuration.
SVI$_VP_MASK

When you specify SYI$_VP_MASK, $GETSYI returns a longword mask,
the bits of which, when set, indicate which processors in the system have
vector coprocessors.
SVI$_VP_NUMBER

When you specify SYI$_VP _NUMBER, $GETSYI returns an unsigned
longword containing the number of vector processors in the system.
SVI$_VECTOR_EMULATOR

When you specify SYI$_VECTOR_EMULATOR, $GETSYI returns a byte,
the low-order bit of which, when set, indicates the presence of the VAX
vector instruction emulator facility (VVIEF) in the system.
22.5.6.2

System Security: New Item Code

In Version 5.4 of the VMS operating system, $GETSYI accepts the
following item code and returns information about system security.
SVI$_SVSTEM_RIGHTS

When you specify SYI$_SYSTEM_RIGHTS, $GETSYI returns the system
rights list as an array of quadword identifiers. Each entry consists of a
longword identifier value and the following longword identifier attributes:
Symbolic Name

Description

KGB$M_RESOURCE
KGB$M_DYNAMIC

Identifier can be enabled or disabled.

Resources can be charged to the identifier.

Allocate a buffer that is sufficient to hold the system rights list because
$GETSYI only returns as much of the list as will fit in the buffer.

22.5.7

$GETUAI: New Item Codes for Enhanced Password Screening
With Version 5.4 of the VMS operating system, passwords selected by
users can be screened for acceptability. The VMS system automatically
compares new passwords against a system dictionary to ensure that a
password is not a native language word. It also maintains a history list of
a user's passwords and compares each new password against this list to
guarantee that an old password is not reused.
In addition, a site with contractual obligations to use special algorithms
for encrypting passwords will be able to use them.

22-58

System Services
22.5 Modified System Services

To support these enhancements, $GETUAI accepts the following item
codes and returns information about passwords and logins:
UAI$_ENCRVPT

When you specify UAI$_ENCRYPT, $GETUAI returns one of the values
shown in the following table, identifying the encryption algorithm for the
primary password.
Because the encryption algorithm is a byte in length, the buffer length
field in the item descriptor should specify 1 byte.
Symbolic Name

Description

Uses a CRC algorithm and returns a longword hash
value. It was used in VMS releases prior to
Version 2.0.

Uses a Purdy algorithm over salted input. It expects
a blank-padded user name and returns a quadword
hash value. This algorithm was used during VMS
Version 2.0 field test.
Uses the Purdy algorithm over salted input. It expects
a variable length user name and returns a quadword
hash value. This algorithm was used in VMS releases
prior to Version 5.4.

Uses the Purdy algorithm over salted input. It expects
a variable length user name and returns a quadword
hash value. This is the current algorithm that VMS
uses for all new password changes.

UAI$_ENCRVPT2

When you specify UAI$_ENCRYPT2, $GETUAI returns one of the
following values identifying the encryption algorithm for the secondary
password. Refer to the UAI$_ENCRYPT item code for a description of the
algorithms.
UAI$C_AD_II
UAI$ C_PURDY
UAI$C_PURDY_V
UAI$C_PURDY_S
Because the encryption algorithm is a byte in length, the buffer length
field in the item descriptor should specify 1 byte.
UAI$_FLAGS

This item code has the following new symbolic names:

Symbolic Name

Description

UAI$V_DISPWDDIC

Automatic checking of user-selected passwords against
the system dictionary is disabled.

UAI$V_DISPWDHIS

Automatic checking of user-selected passwords against
previously used passwords is disabled.

22-59

System Services
22.5 Modified System Services

22.5.8

$MOD_IDENT: New Status Code
In Version 5.4 of the VMS operating system, $MOD_IDENT may return
the following status code:
SS$_DUPIDENT

22.5.9

The specified identifier value already exists.

$MOUNT: Volume Shadowing Flags
In Version 5.4 of the VMS operating system, $MOUNT accepts the
following new flags:
MNT$V_INCLUDE

Applicable only if you have the VMS Volume
Shadowing option.
Applicable only if you have the VMS Volume
Shadowing option.
Applicable only if you have the VMS Volume
Shadowing option.

For more information about volume shadowing, see Chapter 18 (summary
of phase II support) and the VMS Volume Shadowing Manual (detailed
information).

22.5.10 $SETUAI: New Item Codes for Enhanced Password Screening
With Version 5.4 of the VMS operating system, passwords selected by
users can be screened for acceptability. The VMS system automatically
compares new passwords against a system dictionary to ensure that a
password is not a native language word. It also maintains a history list of
a user's passwords and compares each new password against this list to
guarantee that an old password is not reused.
In addition, a site with contractual obligations to use special algorithms
for encrypting passwords will be able to use them.

C\.

To support these enhancements, $SETUAI accepts the following item codes
and returns information about encryption algorithms for passwords:
UAI$_ENCRYPT

When you specify UAI$_ENCRYPT, $SETUAI sets one of the values shown
in the following table to identify the encryption algorithm for the primary
password.
Symbolic Name

Description
Uses a CRC algorithm and returns a longword hash
value. It was used in VMS releases prior to
Version 2.0.
Uses a Purdy algorithm over salted input. It expects
a blank-padded user name and returns a quadword
hash value. This algorithm was used during VMS
Version 2.0 field test.

22-60

System Services

22.5 Modified System Services

Symbolic Name

Description
Uses the Purdy algorithm over salted input. It
expects a variable length user name and returns a
quadword hash value. This algorithm was used in
VMS releases prior to Version 5.4.
Uses the Purdy algorithm over salted input. It
expects a variable length user name and returns a
quadword hash value. This is the current algorithm
that VMS uses for all new password changes.

UAI$C PREFERED
ALGORITHM 1
-

Represents the latest encryption algorithm that
the VMS system uses to encrypt new passwords.
Currently, it equates to UAI$C_PURDY_So Digital
recommends that you use this symbol in source
modules.

1 The value of this symbol may be changed in future releases if an additional algorithm is
introduced.

Because the encryption algorithm is a byte in length, the buffer length
field in the item descriptor should specify 1 byte.

UAI$_ENCRVPT2

When you specify UAI$_ENCRYPT2, $SETUAI sets one of the following
values, indicating the encryption algorithm for the secondary password.
Refer to the UAI$_ENCRYPT item code for a description of the algorithms.
UAI$C_AD_II
UAI$C_PURDY
UAI$C_PURDY_V

UAI$C_PURDY_S
UAI$C_PREFERED_ALGORITHM
Because the encryption algorithm is a byte in length, the buffer length
field in the item descriptor should specify 1 byte.
UAI$_FLAGS

This item code has two new symbolic names:

Symbolic Name

Description

UAI$V_DISPWDDIC

Automatic checking of user-selected passwords against
the system dictionary is disabled.

UAI$V_DISPWDHIS

Automatic checking of user-selected passwords against
previously used passwords is disabled.

UAI$_SALT

When you specify UAI$_SALT, $SETUAI sets the salt field of the user's
record to the value you provide. The salt value is used in the VMS hash
algorithm to generate passwords. $SETUAI does not generate a new salt
value for you.

22-61

System Services
22.5 Modified System Services

Because this decimal number is a word in length, the buffer length field in
the item descriptor should specify 2 bytes.
By copying the item codes UAI$_SALT, UAI$_ENCRYPT, UAI$_PWD,
UAI$_PWD_DATE, and UAI$_FLAGS, a site-security administrator can
construct a utility that propagates password changes throughout the
network. Note, however, that Digital does not recommend using the same
password on more than one node in a network.

22.6

Implementing Site-Specific Security Policies
Occasionally, you may need to write routines that implement sitespecific policies or special algorithms. The routines that you write can
either replace or augment built-in VMS policies. This section contains
instructions for replacing key operating system security routines with
routines that are specific to your site. Two types of routines are discussed:
loadable system services and shareable images.

22.6.1

Creating Loadable Security Services
This section describes how to create a system service image and
how to update the file SYS$LOADABLE_IMAGES:VMS$SYSTEM_
IMAGES.DATA, which controls site-specific loading of system images.
These procedures update the loading of system images for all nodes of a
cluster.

()

Currently, you can replace three system services with services specific to
your site:
•

$ERAPAT-Generates. a security erase pattern

•

$MTACCESS-Controls magnetic tape access

•

$HASH_PASSWORD-Applies a hash algorithm to an ASCII password

When creating the system service, you code the source module and define
the vector offsets, the entry point, and the program sections for the system
service. At this point, you can assemble and link the module to create a
loadable image.

Once you have created the loadable image, you install it. First, you copy
the image into the SYS$LOADABLE_IMAGES directory and add an entry
for it in the VMS system images file using the SYSMAN Utility. Next, you
invoke the system images command procedure to generate a new system
image data file. Finally, you reboot the system to load in your service.
The following sections describe how to create and load the $ERAPAT
system service. An example of the $ERAPAT system service can be found
in SYS$EXAMPLES:DOD_ERAPAT.MAR on the VMS operating system.
What is described here also applies to the system services $HASH_
PASSWORD and $MTACCESS. An example of how to prepare and load
the $HASH_PASSWORD service can be found in SYS$EXAMPLES:HASH_
PASSWORD.MAR.

22-62

System Services
22.6 Implementing Site-Specific Security Policies

c
22.6.1.1

Preparing and Loading a System Service

Use the following procedure to prepare and load a system service, in this
case $ERAPAT:
1

Create the source module.
a. Include the following macro to define system service vector offsets:
$SYSVECTORDEF ; Define system service vector offsets

b. Use line following macro to define the system service entry point:
SYSTEM SERVICE ERAPAT, <R4>, MODE=KERNEL,NARG=3

Entry point name
Register to save
; Mode of system service
; Number of arguments

(The code immediately following this macro is the first instruction
of the $ERAPAT system service.)

c. Use the following macros to declare the desired program sections
(PSECT):

DECLARE PSECT EXEC$PAGED_CODE

Pageable code PSCET

DECLARE PSECT EXEC$PAGED_DATA

Pageable data PSECT

DECLARE PSECT EXEC$NONPAGED_DATA

Nonpageable data PSECT

DECLARE PSECT EXEC$NONPAGED_CODE

Nonpageable code PSCET

Assemble the source module by using the following command:
$

Link the module to create a SYS$ERAPAT.EXE executive loaded
image. You can link the module using the command procedure
DOD_ERAPAT_LNK.COM in SYS$EXAMPLES. (A command
procedure is also available to link the $HASH_PASSWORD example.)
To link the $ERAPAT module, enter the following command:
$

MACRO DOD_ERAPAT+SYS$LIBRARY:LIB.MLB/LIB

@SYS$EXAMPLES:DOD_ERAPAT_LNK.COM

Prepare the operating system image to be loaded.

a. Copy the SYS$ERAPAT.EXE image produced by the link command
into the directory SYS$COMMON:[SYS$LDR]. Note that privilege
is required to put files into this directory.
b. Add an entry for the SYS$ERAPAT.EXE image in the
SYS$UPDATE:VMS$SYSTEM_IMAGES.IDX data file.
You add an entry by using the SYSMAN command SYS_
LOADABLE ADD. (See the VMS SYSMAN Utility Manual for
a description.) For example, the following commands add an entry
in VMS$SYSTEM_IMAGES.IDX for SYS$ERAPAT.EXE:

$ RUN SYS$SYSTEM:SYSMAN
SYSMAN> SYS_LOADABLE ADD _LOCAL SYS$ERAPATSYSMAN> /LOAD_STEP = SYSINIT SYSMAN> /SEVERITY = WARNING SYSMAN> /MESSAGE = "failure to load SYS$ERAPAT.EXE"

22-63

System Services
22.6 Implementing Site-Specific Security Policies

This entry specifies that the SYS$ERAPAT.EXE image is to be
loaded by the SYSINIT process during the bootstrap. If there is an
error loading the image, the following messages are printed on the
console terminal:
%SYSINIT-E-failure to load SYS$ERAPAT.EXE
-SYSINIT-E-error loading <SYS$LDR>SYS$ERAPAT.EXE, status

"status"

c. Invoke the SYS$UPDATE:VMS$SYSTEM_IMAGES.COM
command procedure to generate a new system image data file. The
system bootstrap uses this image data file to load the appropriate
images into the system.
d. Reboot the system, which loads the original SYS$ERAPAT.EXE

image into the system. Subsequent calls to the $ERAPAT system
service use the normal VMS routine.
As the default, the system bootstrap loads all images described
in the system image data file (VMS$SYSTEM_IMAGES.DATA).
You can disable this functionality by setting the special SYSGEN
parameter LOAD_SYS_IMAGES to O.
22.6.1.2

(--\

~,/

Removing an Executive Loaded Image

V se the following procedure to remove an executive loaded image, in this
case, SYS$ERAPAT.EXE:
1

Enter the following SYSMAN command:
SYSMAN>

SYS_LOADABLE REMOVE _LOCAL

SYS$ERAPAT

Invoke the SYS$UPDATE:VMS$SYSTEM_IMAGES.COM command
procedure to generate a new system image data file. The system
bootstrap uses this image data file to load the appropriate images into
the system.

Reboot the system, which loads the installation-specific
SYS$ERAPAT.EXE image into the system. Subsequent calls to the
$ERAPAT system service use the installation-specific r o u t i n e . , ;'

(;1

As the default, the system bootstrap loads all images described in
the system image data file (VMS$SYSTEM_IMAGES.DATA). You can
disable this functionality by setting the special SYSGEN parameter
LOAD_SYS_IMAGES to O.

22.6.2

Installing Site-Specific Password Policy Filters
A site security administrator can screen new passwords to make sure they
comply with a site-specific password policy. (See Chapter 14.) This section
describes how a security administrator would encode the policy, create a
shareable image and install it in SYS$LIBRARY, and enable the policy by
setting a SYSGEN parameter.
Installing and enabling a site-specific password policy image requires both
SYSPRV and CMKRNL privileges. In addition, if INSTALL and SYSPRV
file access auditing are enabled, multiple security alarms are generated
when the shareable image is installed and the change to the SYSGEN
parameter is noted on the operator console.
22-64

System Services

22.6 Implementing Site-Specific Security Policies

The shareable image contains two global routines, which are called by the
VMS Set Password Utility whenever a user changes a password.

Warning: The two global routines let a security administrator obtain both
the proposed plaintext password and its equivalent quad word
hash value. All security administrators should be aware of
this feature, as its subversion by a malicious privileged user
will compromise your system's security. See the following
recommended procedures.
Digital recommends that you use the following commands to place security
alarm ACEs on the shareable image and its parent directory:
$ SET ACL/ACL=(ALARM=SECURITY,ACCESS=WRITE+CONTROL+DELETE+SUCCESS+FAILURE) _$ SYS$LIBRARY:VMS$PASSWORD_POLICY.EXE
$ SET ACL/ACL=(ALARM=SECURITY,ACCESS=WRITE+CONTROL+SUCCESS+FAlLURE) $ SYS$COMMON: [000000] SYSLIB. DIR

You must also enable ACL alarms using the following command:
$

SET AUDIT/ALARM/ENABLE=ACL

Once in place, these alarms will catch all attempts to replace or to modify
the VMS$PASSWORD_POLICY image.

22.6.2.1

Creating a Shareable Image
To compile and link a shareable image that filters passwords for words
that are sensitive to your site, perform the following steps:
1

Create the source module VMS$PASSWORD_POLICY.*. BLISS
and Ada examples of the policy module's interface, called
VMS$PASSWORD_POLICY.*, are located in SYS$EXAMPLES.
Define two routine names in the source module: POLICY_PLAINTEXT
and POLICY_HASH. These routines must be global; (see your
language reference for directions on defining a global routine). The
Set Password Utility looks for these routine names and displays the
message SYMNOTFOU if the names are missing or if the routines are
not defined as global.

c
2

22.6.2.2

Link the source file using the command procedure VMS$PASSWORD_
POLICY_LNK.COM, located in SYS$EXAMPLES.

Installing a Shareable Image
To install a shareable image, perform the following steps:
1

Copy the resulting file to SYS$LIBRARY and install it using the
following commands:

$ COpy VMS$PASSWORD_POLICY.EXE SYS$COMMON: [SYSLIB]/PROTECTION=(W:RE)
$ INSTALL ADD SYS$LIBRARY:VMS$PASSWORD_POLICY/OPEN/HEAD/SHARE

Set the SYSGEN parameter LOAD_PWD_POLICY to 1.
$
RUN SYS$SYSTEM: SYSGEN
SYSGEN>
USE ACTIVE
SYSGEN>
SET LOAD PWD POLICY 1
SYSGEN>
WRITE ACTIVE
WRITE CURRENT
SYSGEN>

22-65

System Services
22.6 Implementing Site-Specific Security Policies

To make the changes permanent, add the INSTALL command from
step 1 to the file SYS$SYSTEM:SYSTARTUP_V5.COM and modify the
system parameter file, MODPARAMS.DAT, so the parameter LOAD_
PWD_POLICY is set to 1.

Run AUTOGEN to ensure that the SYSGEN parameters are set
correctly on subsequent system startups.
$

@SYS$UPDATE:AUTOGEN SAVPARAMS SETPARAMS

i--\

~~--)

o
22-66

C)
23 Run-Time Library Routines
This chapter describes new features of the Run-Time Library (RTL)
Parallel Processing (PPL$) and Mathematics (MTH$) facilities.

23.1

Parallel Processing (PPL$)
The VMS Version 5.4 RTL Parallel Processing (PPL$) facility contains 19
new routines that complement the basic suite of functionality originally
provided for VMS Version 5.0. New features of the PPL$ facility include
the following:
•

A routine, PPL$CREATE_APPLICATION, that informs the PPL$
facility that the caller is forming or joining a parallel application. This
routine replaces PPL$INITIALIZE, which is obsolete beginning with
Version 5.4 of the VMS operating system,

•

Routines that implement work queues. Work queues allow one or
more processes to serve as dispatchers of work items to be performed
by other processes. Work queues also provide process synchronization.

o
o

Routines that implement work queue synchronization are as follows:
PPL$CREATE_WORK_QUEUE
PPL$DELETE_WORK_QUEUE
PPL$READ_WORK_QUEUE
PPL$DELETE_WORK_ITEM
PPL$INSERT_WORK_ITEM
PPL$REMOVE_WORK_ITEM
A new example program written in VAX C shows how to use the work
queue routines and PPL$CREATE_APPLICATION.

•

Routines that delete a PPL$ application or object. These routines are
as follows:
PPL$DELETE_APPLICATION
PPL$DELETE_BARRIER
PPL$DELETE_EVENT
PPL$DELETE_SEMAPHORE
PPL$DELETE_SPIN_LOCK
PPL$DELETE_VM_ZONE

• Routines that set and adjust a semaphore maximum (analogous
to setting and adjusting a barrier quorum). These routines are as
follows:

PPL$ADJUST_SEMAPHORE_MAXIMUM
PPL$SET_SEMAPHORE_MAXIMUM

23-1

Run-Time Library Routines
23.1 Parallel Processing (PPL$)

•

Routines that disable event notification and reset an event state
("untrigger" an event). These routines are as follows:
PPL$DISABLE_EVENT
PPL$RESET_EVENT

•

Routines that read a spin lock state and find a synchronization
element or shared memory zone's identifier, as follows:
PPL$READ _SPIN_LOCK
PPL$FIND_OBJECT_ID
PPL$FIND_OBJECT_ID replaces PPL$FIND_SYNCH_ELEMENT_ID,
which is beginning with Version 5.4 of the VMS operating system.

For a detailed description of the new PPL$ routines, refer to the VMS RTL
Parallel Processing (PPL$) Manual.

23.2

Mathematics (MTH$)
The RTL MTH$ facility provides the following new and modified sets of
routines to support vector processing:
•

Basic Linear Algebra Subroutines (BLAS) Levell

•

First Order Linear Recurrence (FOLR)

•

Routines that have been vectorized to support Digital vectorizing
compilers such as the VAX FORTRAN High Performance Option
(HPO)

See Section 2.3.1 for more information about using RTL MTH$ routines
in a vector processing environment. See VMS RTL Mathematics (MTH$)
Manual for complete descriptions of all new, modified, and existing RTL
MTH$ routines.

o
23-2

c
24 VMS Record Management Services
This chapter describes the following enhancements to VMS Record
Management Services for Version 5.4 of the VMS operating system:

o
24.1

Asynchronous support for process-permanent files

•

Increase in local buffer limit

•

Access-mode protection

•

Expired-date suppression

VMS RMS Asynchronous Support for Process-Permanent Files
Prior to Version 5.4 of the VMS operating system, VMS RMS ignored the
asynchronous option for process-permanent files. VMS RMS now supports
this option, which affects the performance options within the following two
RMS control blocks:

c
24.2

•

RMS Control Block

Field

Performance Option

File Access Block (FAB)

FAB$L_FOP

FAB$V_ASY

Record Access Block (RAB)

RAB$L_ROP

RAB$V_AST

Local Buffer Maximum Increased
With Version 5.4 of the VMS operating system, the maximum number of
local buffers is increased to 32,767. Prior to Version 5.4, you were limited
to specifying no more than 127 local buffers for a record stream from
the VMS RMS interface using the RAB multibuffer count field CRAB$B_
MBF). You obtain the additional local buffering capability by using the
multibuffer count XABITM. The multibuffer count XABITM is used as
an input to the Connect service only. It is not used as an output by any
service.
The maximum number of local buffers established by the DCL command
SET RMS_DEFAULT for a process has also increased from 127 to 255.
However, the maximum number of local buffers established by the DCL
command SET RMS_DEFAULT for the system remains 127.

The XAB$_MULTIBUFFER_COUNT XABITM requires a 4-byte buffer
to store the value that specifies the number of local buffers. To specify
the number of local buffers, set up the XAB$_MULTIBUFFER_COUNT
XABITM with the number of local buffers desired. Then, link the XABITM
into the XAB chain for the record stream prior to invoking the Connect
service. When you use the multibuffer count XABITM, the value specified
overrides any value that resides in the RAB$_MBF for the related record

24-1

VMS Record Management Services

24.2 Local Buffer Maximum Increased

stream. See Chapter 11 of the VMS Record Management Services Manual
for details about using an XABITM.
Before you increase the size of the local buffer pool, you should consider
current memory management parameters because excessively large buffer
pools introduce additional paging that can reduce I/O performance.

24.3

Access-Mode Protection for VMS RMS
VMS RMS now provides access-mode protection for its services and
associated memory. This feature is analogous to the protection provided by
the system services $ASSIGN and $SETPRT.
No code changes are required for RMS calls involving a single access mode.
A code change might be required for RMS calls that initiate operations
from an inner access mode and allow subsequent RMS operations from an
outer access mode.
If an inner-mode caller initiates an RMS operation without overriding the
access mode, subsequent outer-mode calls fail with an RMS$_PRV error.
The arguments in the following code example are used to override the
caller's access mode. These arguments, together with related topics, are
described in the section on access modes in Introduction to VMS System
Services.
FAB$V_CHAN_MODE = PSL$C_<USER,SUPER,EXEC,KERNEL>

! Select one

VMS uses the maximized value of the caller's access-mode and the FAB$V_
CHAN_MODE argument (RMS access-mode argument) to establish the
access mode.

24.3.1

Access-Mode Protected Services
The following services initiate operations on files. These services establish
the access mode that VMS RMS uses to validate the access modes of
subsequent accessing services.
$CREATE

$OPEN

$PARSE

$SEARCH

The following services access open files to perform various VMS RMS
operations. The access modes for each service trying to access an open file
must be validated before RMS operations are allowed.
$CLOSE

$CONNECT

$DELETE

$DISCONNECT

$DISPLAY

$EXTEND

$FIND

$FREE

$FLUSH

$GET

$NXTVOL

$PUT

$READ

$RELEASE

$REWIND

$SPACE

$TRUNCATE

$UPDATE

$WAIT

$WRITE

VMS RMS does not validate the access mode for the following services
because access-mode comparison is not relevant to them.
$ENTER

24-2

$ERASE

$REMOVE

$RENAME

VMS Record Management Services

24.3 Access-Mode Protection for VMS RMS

24.3.2

Access-Mode Protected Memory
VMS RMS now protects the following data structures and their associated
I/O buffers at EW (executive read/write). Previously, the data structures
were protected at DREW (user read, executive write).
•

RMS-controlled data structures

•

Process-permanent data structures

•

Image-activated data structures

The following memory protection exceptions apply to user-mode accessors
of RMS and are protected at DREW:

24.4

Internal RMS I/O buffers-to facilitate RAB$V_LOC mode

•

RMS buffers containing collated tables used for indexed files

Expired-Date Suppression
The file system, in conjunction with parameters established using the DCL
interface (see the Set Volume command in VMS DeL Dictionary), gives
users a facility for determining whether a data file has expired and is
eligible to be transferred to another storage medium. Expiration of a file is
determined by the Expiration Date and Time, which should not be updated
for maintenance functions or for any function where the data is not really
being modified.

o
c

•

Prior to VMS Version 5.4, the ability to suppress the expiration update
was available only to applications that interface directly with the file
system through the $QIO system service. (See ACP Functions in VMS I/O
User's Reference Manual: Part I.) Now the ability to selectively suppress
the update of the Expiration Date and Time is available to all applications
through the RMS interface.

24.4.1

The Role of XAB$_NORECORD XABITM
The XAB$_NORECORD XABITM suppresses the update of the Expiration
Date and Time on the $CLOSE service. The Expiration Date and Time
is used by VMS to determine if the data in a disk file has been accessed
recently. Normally, when data has been read or written to a disk file, the
$CLOSE service updates the Expiration Date and Time to the current date
and time. This moves back the date and time when the file is considered
expired. Specifying the XAB$_NORECORD XABITM suppresses the
update of the Expiration Date and Time.

The XAB$_NORECORD XABITM uses a 4-byte buffer to set the
NORECORD flag to logic 1 using the symbol XAB$_ENABLE. Any other
value in this XABITM buffer returns an RMS$_XAB error. An application
cannot disable this option because the ODS-II ACP does not support
disabling this function once it has been selected on a $OPEN or $CREATE.

24-3

VMS Record Management Services
24.4 Expired-Date Suppression

24.4.2

Applications for XAB$_NORECORD XABITM
Typically, the XAB$_NORECORD XABITM is used by directory or
maintenance routines that do not manipulate the data and, therefore,
does not change the expiration status of a disk file. For example, the DCL
command DIRECTORY/FULL uses the XAB$_NORECORD XABITM as it
opens files to access prolog data containing key information. In this case,
DIRECTORY displays prolog information but does not display or modify
user data in the disk file and should not modify the Expiration Date and
Time. Maintenance utilities should consider using this XABITM. For
example, a disk defragmentation utility should not modify the expiration
status of a disk file.
Digital recommends using the XAB$_NORECORD XABITM on the $OPEN
service instead of on the $CLOSE service-because the suppression of the
Expiration Date and Time update is guaranteed should the file deaccess or
should a close occur because of process deletion or RMS rundown.
XAB$_NORECORD can be enabled on input to the $CLOSE, $OPEN
and $CREATE services. If the $CREATE service opens an existing file
through the Create-if option and the Expiration Date and Time are not to
be modified, the XAB$_NORECORD XABITM can be specified. When the
XAB$_NORECORD XABITM is used on a $CREATE that creates a file,
it disables the update on the subsequent $CLOSE but does not prevent
initialization of the Expiration Date and Time on the file creation in the
ACP.

The XAB$_NORECORD XABITM can be sensed on output from RMS for
the $OPEN, $CREATE, $DISPLAY, and $CLOSE services. An application
typically senses the XAB$_NORECORD XABITM to determine if the
XABITM was specified on a previous $OPEN or $CREATE option or if it is
specified by the current RMS operation.

o
24-4

o
25 1/0 Driver Support
This chapter describes new VMS Version 5.4 I/O driver support in the
following areas:

•

Pseudoterminal driver

•

Shadow Set Virtual Unit Driver (SHDRIVER)

•

TRM$_MODIFIERS item code

•

I temlist read function I/O status block

•

ACP-QIO function attributes

See the revised VMS I/O User's Reference Manual: Part I for complete
information.

25.1

Pseudoterminal Driver
The Pseudoterminal Driver (FTDRIVER) is now part of the VMS operating
system. This driver, along with several control connection (PTD$) routines,
enables you to create, use, and manipulate pseudoterminals with the VMS
operating system. The VMS I/O User's Reference Manual: Part I describes
pseudoterminal driver functions and capabilities, and lists the VAX calling
standards for the control connection routines.

25.2

Shadow Set Virtual Unit Driver
The Shadow Set Virtual Unit Driver (SHDRlVER) is now part of the VMS
operating system. This driver supports VMS Volume Shadowing
phase II, which provides the same capabilities as VAX Volume Shadowing
phase I but includes support for all DSA disks. The VMS I/O User's
Reference Manual: Part I describes shadow set virtual unit driver
functions and capabilities.

o
25.3

New Modifier Bits for TRM$_MODIFIERS Item Code
Six new modifier bits have been added for the TRM$_MODIFIERS item
code for itemlist terminal driver read verify operations:

•

TRM$M_TM_ARROWS-The terminal interprets the left and right
arrow keys.

•

TRM$M_TM_NOCLEAR-Fill characters are not replaced with clear
characters after a non-fill character occurs.

•

TRM$M_TM_OTHERWAY-Enables left-justify insert mode and rightjustify overstrike mode.

•

TRM$M_TM_TERM_ARROW-The read operation is terminated when
a left or right arrow key is entered at the corresponding margin.

25-1

I/O Driver Support
25.3 New Modifier Bits for TRM$_MODIFIERS Item Code

•

TRM$M_TM_TERM_DEL-The read operation is terminated when a
DELETE key is entered at the left margin.

•

TRM$M_TM_TOGGLE-Enables Ctlr/A to function as a toggle key
between insert mode and overstrike mode.

Table 8-8 in the VMS I/O User's Reference Manual: Part I describes the
TRM$_MODIFIERS item code and its associated modifier bits.

25.4

Itemlist Read Function I/O Status Block
In the I/O status block (IOSB) for the itemlist read function, the byte at
IOSB+5, which formerly returned -1, now returns status information.
Table 8-15 in the VMS I/O User's Reference Manual: Part I lists this
status information.

25.5

New ACP-QIO Function Attributes
There are three new attributes for ACP-QIO functions:
•

ATR$C_DELETE_ALL-Deletes the entire access control list (ACL)

•

ATR$C_GRANT_ACE-Returns an access control list entry (ACE) that
grants or denies access

•

ATR$C_NEXT_ACE-Points to the next ACE in the ACL

Table 1-7 in the VMS I/O User's Reference Manual: Part I describes
ACP-QIO function attributes.

o
25-2

o
26 System Dump Analyzer Utility (SDA)
This chapter describes two new qualifiers to the SHOW PROCESS
command now available with Version 5.4 of the VMS System Dump
Analyzer Utility (SDA).

26.1

New SHOW PROCESS Qualifier: IIMAGES

The !IMAGES qualifier to the SDA command SHOW PROCESS displays
the address of the Image Control Block, the starting and end addresses
of the image, the activation code, the protected and shareable flags, the
image name, and the major and minor ID of the image.

The following is an example of output displayed by the SHOW PROCESS
IIMAGES command:
Process activated images

ICB

Start

End

Type

Image Name

7FF83878
7FF84100
7FF84400
7FF84470
7FF84560
7FF845DO
7FF835F8
7FF84800
7FF84720

00000200
0003ACOO
00036200
0002E400
00021AOO
OOOOOEOO
00008AOO
00060COO
00076800

OOOOODFF
0003FBFF
0003ABFF
000361FF
0002E3FF
000089FF
000219FF
000767FF
000A03FF

MAIN
GLOBAL PRT SHR
GLOBAL
GLOBAL
GLOBAL
GLOBAL
GLOBAL
SHR
MERGED
SHR
GLOBAL
SHR

SHOW_PROC_IMAGES 0,0
DECW$TRANSPORT_COMMON
CONVSHR 1,0
FDLSHR 1,0
SORTSHR 2,28
LIBRTL2 1,12
LIBRTL 1,14
ADARTL 0,0
MTHRTL 129,32781

Total images = 9

Major ID,Minor ID
12,12

Pages allocated = 10J7

The following are possible values for the activation code:
•

MAIN-Image is the object of a RUN command

•

MERGED-Image is an additional mapped image

•

GLOBAL-Image is a global image section

The protected flag (PRT) indicates that the image is installed protected.
The shareable flag (SHR) indicates that the image is installed shareable.
For more information on the SDA command SHOW PROCESS, see the
VMS System Dump Analyzer Utility Manual.

o
26-1

System Dump Analyzer Utility (SDA)
26.2 New SHOW PROCESS Qualifier: /VECTOR_REGISTERS

26.2

New SHOW PROCESS Qualifier: /VECTOR_REGISTERS
The System Dump Analyzer lets you examine vector instructions and
vector context from a system dump file or in a running system. One
way to accomplish this is by specifying the new NECTaR_REGISTERS
qualifier to the SHOW PROCESS command, which obtains the values of
the registers from the process's vector context area. See Section 2.3.5.2 for
a complete description of SDA support for vector processing.

(\\
'\".)

o
o

o
26-2

c
27 Device Support
The VMS Version 5.4 operating system provides device support for writing
and debugging'driver software for VAX 9000 and VAX 6000 systems. This
chapter describes this support for programmers who write and debug
driver software for non-Digital-supplied devices attached to a
VAX 9000 system. For more detailed information about device support
driver programming, see the revised VMS Device Support Manual.

27.1

The VAX 9000 bus architecture illustrated in Figure 27-1 features
multiple XMI buses for large systems. A system control unit (SCD)
and I/O control unit translate each address and connect a VAX 9000
CPD or memory bus to a target XMI and device or bus adapter. The
SCD and I/O control unit connect to each XMI through an XJA adapter.
Then, various bus adapters on the XMI provide connection to VAXBI,
Ethernet, and Computer Interconnect (Cl) buses, which are the second
level of the bus architecture. A KDM70 adapter on the XMI bus provides
a direct connection to disk or tape devices. Device support is provided for
non-Digital-supplied devices connected to second level I/O buses and below.
Generic XMI support is not provided.

o
27.2

VAX 9000 Hardware Considerations

VAX 9000 System Address Space
A VAX 9000 system supports 30-bit addressing on each XMI bus and
provides 1 gigabyte of physical address space. The total address space is
divided in equal halves by memory and I/O address space, as shown in
Figure 27-2.
All memory locations on a VAX 9000 XMI bus are addressed using physical
addresses in XMI memory space (from 0000 0000 16 through
1FFF FFFF 16 ). An XMI device that accesses memory directly (or indirectly
through a system-interconnect adapter) or its driver must perform virtualto-physical translation before transmitting a memory address on the
bus.
VAX 9000 XMI I/O address space (physical addresses 2000 000016
through 3FFF FFFF 16) is partitioned as illustrated in Figure 27-3.
Macro $I09AQDEF contained in SYS$LIBRARY:LIB.MLB defines symbols
describing the layout of I/O address space.

c
27-1

Device Support

27.2 VAX 9000 System Address Space

Figure 27-1

VAX 9000 System Architecture

VAX 9000
CPU

CPU

Memory

System Control Unit

I/O Control Unit

Console

: XJA I
--~-.

,/ ",.....
.t.,
I
I
I

Disk

I
I

Tapes

I
I
I

:X
:M

X
M
I
2

: I

:3
I
I
I

I
J
I
I
J
J
J
I
J
J

I
I
I
I
I

I
I
J
I

I
I

I
I
I
I
I
I
I
I
I
I
I

J
I
I
I
I

I
I
I
I
I
I
I

I
I

I
,.J

IL,

',V'/

,'V/

,.J

ZK-1599A-GE

27-2

Device Support

27.2 VAX 9000 System Address Space

Figure 27-2

VAX 9000 XMI Address Space

Hex Address
00000000
Memory Space
512Mb

20000000

I/O Space
512Mb

3FFF FFFF
ZK-5541-GE

c
o

The assignment of I/O addresses, shown in Figure 27-3, for any VAX 9000
system supports two levels of bus structure: the XMI and the VAXBI. A
VAX 9000 system uses the XMI as the primary I/O bus and can have up
to 4 XMls, depending on the model. Each XMI can have up to 12 nodes or
devices numbered 1 through D hexadecimal. Note that the XJA adapter
occupies node 0 on an XMI.
Each XMI-to-VAXBI adapter (DWMBAlA) provides connection to the
second level I/O subsystem. At the second level, device support is provided
for non-Digital-supplied devices connected to the VAXBI bus. See the VMS
Device Support Manual for more specific information about these generic
VAXBI devices.
Each XBI (14 maximum) is physically mapped into its own XBI window
space (XBlx) in the I/O block The four XMI buses are assigned the first
region of the I/O block, XMIO through XM13, that spans the node space
region. The window spaces for each VAXBI are next, contiguously assigned
XBIO through XBID 16 , spanning the XBI window space region. This allows
CPDs to address the individual XMI device CSRs as well as the individual
BI device CSRs.
In XMI I/O space, a given XBI's window space is determined by the XBI's
XMI node number. There is a limit of 8 XBls on a given XMI bus and a
limit of 14 XBIs across all XMI buses. In the assignment of XBI window
spaces, the XBI with the lowest node number on XMIO is assigned to XBIO
window space. The XBI with the second lowest node number in XMIO is
assigned to XBI1 window space, and so on through all XBls on XMIO, then
to XMI1, XMI2, and until XMI3 is exhausted or the 14th XBI is found.
A 40-bit bus (bits 39 to 0) in the SCD is transparent to devices and nodes
on the XMI and VAXBI buses. As shown in Figure 27-4, I/O space on the
40-bit bus starts at address 80 0000 000016 and is entered when bit 39
is set to a 1. Beginning at 80 0180 0000 is the array of 16 x 512Kb XMI
27-3

Device Support

27.2 VAX 9000 System Address Space

Figure 27-3

SCU/XMI Systems 1/0 Address Space
Hex Address
XMIO Node Space
XMI1 Node Space
XMI2 Node Space
XMI3 Node Space
XBIO Window Space
XBI1 Window Space
XBI2 Window Space
XBI3 Window Space
XBI4 Window Space
XBI5 Window Space
XBI6 Window Space
XBI7 Window Space
XBI8 Window Space
XBI9 Window Space
XBIA Window Space
XBIB Window Space
XBIC Window Space
XBID Window Space
XJAO Private Space
XJA 1 Private Space
XJA2 Private Space
XJA3 Private Space
SCU Register Space

2000 0000
2080 0000
2100 0000
2180 0000
2200 0000
2400 0000
2600 0000
2800 0000
2AOO 0000
2COO 0000
2EOO 0000
3000 0000
3200 0000
3400 0000
3600 0000
3800 0000

3AOO 0000
3COO 0000
3EOO 0000
3E08 0000
3E10 0000
3E18 0000

3E20 0000
3FFF FFFF
ZK-1938A-GE

node space allocations. This provides a 512Kb node space for each possible
XMI node. The System Control Unit, I/O control unit, and XJA adapter of
the SCU use this map to translate and select one of the eight XBI window
spaces from an address presented by a CPU.
An XJA of the SCUIXMI bus architecture is an adapter that connects the
seu ports to the XMI bus. The XJAs have a private space region in the
I/O block that allows CPUs to address the XJA CSRs. Since there are up
to four XMIs, there can be four XJAs. In the XJA private space region,
XJAs are mapped XJAO through XJA3.

27-4

0_'

Device Support

27.2 VAX 9000 System Address Space

Figure 27-4

SCU Bus Address Allocation

XMI Private Space
XMI Node Space
XB11 Window Space
XB12 Window Space
XB 13 Window Space
XB14 Window Space

Reserved
XB15 Window Space
XB16 Window Space
XB17 Window Space
XB 18 Window Space

80 0000 0000
80 0180 0000
80 0200 0000
80 0400 0000
80 0600 0000
80 0800 0000
80 OAOO 0000
80 1600 0000
80 1800 0000
80 1AOO 0000
80 1COO 0000
80 1EOO 0000
ZK-2004A-GE

Figure 27-5 describes the contents of each XJA private space. CSRs XBI
ID A and XBI ID B of this region are used by the XJA in translating a XBI
window-space address into its appropriate XMI XBI window-space address.
The last region is the SCU register space that allows CPU s to address the
CSRs of the System Control Unit and Console.

Figure 27-6 shows the bit structure and occurrences of a 30-bit I/O-space
address. The address bits are numbered 0 through 29, right-to-Ieft. Bits 0
through 22 translate the same for all buses. The occurrence of a 1 in bit 29
indicates an I/O bound address. With bit 29 set, bits 25 through 28 specify
an XBI Window space address. When bit 29 is set and bits 25 through 28
are 0, an XBI Window address is indicated, or if bits 25 through 29 are 1,
a SCU bound address is present.

o
27-5

Device Support
27.2 VAX 9000 System Address Space

Figure 27-5

XJA Private Space Address Allocation

31
XJA Error Summary
XJA Force Command
XJA IPINTR Source
XJA Diagnostic Control
XJA DMA Failing Address
XJA DMA Failing Command
XJA Error Interrupt Cntrl
XJA Configuration
XBIIDA
XBIIDB
XJA Error SCB Offset
ReseNed
XJA SCB Offset IPL 14
XJA 8CB Offset IPL 15
XJA SCB Offset IPL 16
XJA SCB Offset IPL 17

bb + 00
bb + 04

bb = 3EOO 0000 +
(XJA# * 80000)

bb + 08
bb + OC
bb + 10
bb + 14
bb + 18
(~---"\,

bb + 1C

~,-_/

bb + 20

bb + 24
bb + 28
bb + 2C
bb + 40

bb + 44
bb + 48
bb + 4C
bb + 50
ZK-2003A-GE

o
27-6

Device Support
27.2 VAX 9000 System Address Space

Figure 27-6

SCU/XMI Systems Address Bit Structure

~ I/OSpace
28

1
28

1 Specifies the bus or XBI Window Space
25

__---'-1_o_o_o_0_____1_ _......1Specifies XMI Node Space
28

1...-.....&.1_1_1_1_1_1_---'1 SCU Space
22

Specific Address
(same on all buses)

ZK-2002A-GE

27.3

Driver Debugging with Pool Checking
The Pool Check mechanism provided with VMS has been enhanced to
facilitate the debugging of a device driver in the context of driver memory
allocation and deallocation techniques. A new bit (bit 5) in the flags byte
of the POOLCHECK system parameter has been added which, when set,
validates the look-aside list de allocation operation (when freeing an SRP,
IRP, or LRP). For more information, see the VMS Device Support Manual.
The Poolcheck bugcheck has also been enhanced to distinguish between
several types of crashes, in addition to a corrupted packet condition. When
a crash occurs, the top-of-stack longword now contains a cause value, as
described further in VMS Device Support Manual.

o
27-7

c
28 VAX Text Processing Utility (VAXTPU)
This chapter describes VAXTPU Version 2.6 new features and
enhancements included in Version 5.4 of the VMS operating system.
See the revised VAX Text Processing Utility Manual for more detailed
information.

28.1

New Qualifier: IINTERFACE
The !INTERFACE qualifier, which you use to specify either character-cell
or DECwindows interface, has been added for compatibility with other
DECwindows applications. It is virtually the same as the IDISPLAY
qualifier.

28.2

New and Enhanced Built-In Procedures
The following built-in procedures are new or enhanced for the Version 5.4
VMS operating system:
•

GET_INFO
New GET_INFO built-in procedures enable you to determine the
following:
Widget input focus
Keystroke journal recovery
Work file name

Key name
Cursor position after vertical motion operations
Scroll setting
Automatic pop-up menu positioning
•

MARK
An enhancement to the MARK built-in procedure lets you create
markers at arbitrary positions within a buffer. Previously, markers
could be created only at the current editing point.

•

SET (KEYSTROKE_RECOVERY)
This new built-in procedure turns keystroke journal recovery on or off,
regardless of whether such recovery was specified when the VAXTPU
session was started.

•

SET (MENU_POSITION)
This new built-in procedure lets you set automatic pop-up menu
positioning for one or more pop-up widgets.

28-1

VAX Text Processing Utility (VAXTPU)
28.2 New and Enhanced Built-In Procedures

This new built-in procedure allows an application to restore the column
context value for a buffer.
•

SET (SCROLLING)
An enhancement to the SET (SCROLLING) built-in procedure enables
you to specify jump scrolling or smooth scrolling.

28.3

Work File Support
You can significantly increase the size of the files you edit with VAXTPU
by creating work files. Work files make it possible for VAXTPU to handle
files that are larger than the available virtual memory space.

o
28-2

c
29 VAX RMS Journaling: Support for DECdtm Services
This chapter describes VAX RMS Journaling enhancements that support
DECdtm services for Version 5.4 of the VMS operating system. (See
Chapter 3 for a complete description of DECdtm services.) VAX RMS
J ournaling continues to support existing applications developed on
previous versions of VAX RMS Journaling.

29.1

Support for DECdtm Transactions
The DECdtm transaction has superseded the Recovery Unit Facility
(RUF) recovery unit. In VAX RMS Journaling Version 5.4, an RMS
recovery unit is the recoverable work performed by a single process within
a DECdtm transaction.
The RUF recovery unit services have been superseded by corresponding
DECdtm transaction services, as follows:

RUF Recovery Unit Service

DECdtm Transaction Service

$START_RU

$START_TRANS(W)

$END_RU

$END_TRANS(W)
$ABORT_ TRANS(W)

In addition, a single DECdtm transaction service, $END_TRANS(W), has
replaced two other RUF services, $PREPARE_RU and $COMMIT_RU,
which together were equivalent to the $END_RU service.
For more information about the DECdtm transaction services, see
Chapter 22.

29.2

RUF Services Emulated
Recovery Unit Facility (RUF) services are still supported. They are
emulated transparently using DECdtm transaction services.
You do not have to recompile or relink your applications to run them under
VAX. RMS Journaling Version 5.4.
You can convert an application that uses only one active transaction at a
time to use the DECdtm services by replacing calls to RUF services with
calls to the corresponding DECdtm transaction services.

However, combining DECdtm transaction services and RUF recovery
unit services in a single image requires care. You should avoid having
transactions that were started using the DECdtm services active at the
same time as transactions that were started using the RUF services.

29-1

VAX RMS Journaling: Support for DECdtm Services
29.3 Network Support

29.3

Network Support
Remote RMS files marked for recovery unit journaling can be modified
within a transaction. They will be included in the atomic unit of work
defined by the transaction. A remote file is a file accessed by a client
RMS process through the DAPIFAL protocol to a "server" system.
The following conditions apply to remote files:
•

Remote files can be marked for any combination of RU (recovery unit),
AI (after-image), or BI (before-image) journaling.

•

All journaling takes place locally with respect to each file.

•

All recovery takes place locally with respect to each file.

•

Both client and server nodes must support DECdtm (that is, must be
running VMS Version 5.4 or later).

•

The server node must be licensed for RMS Journaling.

•

The DIRECTORY/FULL and ANALYZEIRMS commands have been
enhanced to display the type of journaling enabled but not the names
of any AI or BI journals.

•

The SET FILE/AI_JOURNALIBI_JOURNALIRU_JOURNAL command
can only be applied to a locally accessed file.

The following examples compare transactions using local or remote access:
Local Access

Remote Access

$OPEN filel
$CONNECT streaml to filel
$OPEN file2
$CONNECT stream2 to file2

$OPEN filel
$CONNECT streaml to filel
$OPEN n2: :file2
$CONNECT stream2 to file2

$START_TRANSW

$GET from streaml
$UPDATE to streaml
$PUT to stream2

o
o

$END_TRANSW

The only difference between the two code examples is that, in the remote
example, the second file specification includes a node name. As a result,
RMS transparently manages two recovery units within the transaction.
The following table summarizes the differences between using recovery
unit journaling locally and remotely:

29-2

Local Access

Remote Access

One transaction

One recovery unit

Two recovery units

One RU journal

Two RU journals

VAX RMS Journaling: Support for DECdtm Services

29.4 Record Stream Association

29.4

Record Stream Association
In applications that use the DECdtm transaction services, an RMS
record stream is associated with a transaction as a result of an RMS
record operation. The application can use either the DECdtm default
transaction or the new XABITM item list entry XAB$_TID to determine
which transaction the record stream should join.

29.4.1

How Streams Become Associated with a Transaction
Under RMS Journaling Version 5.4, record streams are associated with
transactions as follows:

c
o
29.4.2

•

If the DECdtm services are being used, then eligible streams associate
with a transaction at the time of a record operation, not when the
transaction is started or the stream is established (as was the case
using RUF services).

•

A record operation can cause stream association if its action is
recoverable. The $PUT, $UPDATE, $DELETE, $FIND, $FREE, $GET,
$RELEASE, and $REWIND services might cause an eligible stream to
associate with a transaction.

•

A record operation must result in stream association if it affects record
data in the file. The $PUT, $UPDATE, and $DELETE services must
cause an eligible stream to be associated with a transaction.

Stream Association Using RUF and OECdtm Services
The following example compares the way streams are associated with
transactions under DECdtm and RUF:

Using DECdtm

Using RUF

$START_TRANSW
$GET from stream1
$UPDATE to stream1

$START_RU
$GET from stream1
$UPDATE to stream1

•

Using Version 5.4 of RMS Journaling (DECdtm services), the stream
associates on the $GET service.

•

Using RUF services with versions of RMS Journaling prior to 5.4 and
emulation on Version 5.4, the stream associates on the $START_RU.

•

In most cases, this difference does not matter and a RUF application
can be converted to the direct use of DECdtm services by simple
substitution.

•

In the cases where it does matter, the association at record operation
time is more flexible than association at transaction start (using RUF).

29-3

VAX RMS Journaling: Support for DECdtm Services
29.5 Detached Recovery

29.5

Detached Recovery
The following sections describe modifications that have been made in
the operation of detached recovery-specifically to the performance of
synchronous, asynchronous, and partial recoveries.

29.5.1

Synchronous and Asynchronous Recovery
The RMS Detached Recovery server (new image
SYS$SYSTEM:RMSREC$SERVER.EXE) can perform both synchronous
and asynchronous recovery. Asynchronous recovery is the default mode; it
proceeds as follows:
1

Detached recovery "adopts" orphaned transactions by acquiring the
record locks for all records modified within a recovery unit. The
detached recovery server is multithreaded and performs asynchronous
system service calls (including RMS operations).

The detached recovery server indicates completion as soon as the
record locks have been reacquired. Thus, access to records and files is
reenabled sooner.

Actual recovery proceeds asynchronously with respect to the original
request. This is in contrast to the synchronous recovery that was
performed in versions of VAX RMS Journaling prior to Version 5.4.

Synchronous recovery is used in the following circumstances:

29.5.2

•

Partial recovery-One or more secondary files are unavailable, so
detached recovery cannot acquire all the record locks from an orphaned
transaction. See Section 29.5.2 for a detailed description of partial
recovery.

•

Limited resources-The detached recovery server does not have enough
resources to acquire all the record locks on the file to be recovered (for
example, a very large database with many active transactions).

•

Exclusive access-The process that initiates detached recovery has
tried to access the file such that it either has exclusive access to the
file or it is the only process that can modify the file. (It mayor may
not allow shared read access.) In this case, the accessor will not look
for record locks from other processes, and the locks owned by detached
recovery can create difficulties for the accessor.

Partial Recovery
When detached recovery receives a request to recover a file, it tries to
recover all the effects of all orphaned transactions that involve the file.
The specific file for which RMS requests recovery is called the primary
file. In addition to the changes made to the primary file, each of the
orphaned transactions can also include changes to a number of other files.
These additional files are called secondary files.

29-4

VAX RMS Journaling: Support for DECdtm Services

29.5 Detached Recovery

Recovery of secondary files is not required to allow access to the primary
file. If detached recovery cannot access a secondary file referenced in a
recovery unit journal for one of the orphaned transactions, then detached
recovery cannot adopt that transaction. In such a case, detached recovery
recovers that particular recovery unit journal in synchronous mode and
omits all operations that involve the inaccessible secondary file. Omitting
a secondary file is permissible, since it is necessary only to recover the
primary file to satisfy the client's request. All the information necessary to
recover the secondary file is left in the recovery unit journal for eventual
use in recovering that file.

29.6

Placement of Recovery Unit Journals
In RMS Journaling Version 5.4, the location of a recovery unit journal is
determined as follows:

o
c

•

The first local stream that associates with the transaction selects the
location for the RUJ file.

•

By default, the recovery unit journal is on the same volume as the file.

•

The SET FILEIRU_JOURNAL=(LABEL=volnam) command can specify
a different volume for all accessors of the file.

•

Each accessor can redirect the recovery unit journal by defining a
different equivalence name for the logical DISK$volnam.

•

The XAB$_RUJVOLNAM item list entry on a XABITM block
connected to the RAB can be used to override all the preceding factors.

•

Recovery unit journals can be reused. When the transaction is
completed, the recovery unit journal becomes idle.

•

If the process does not have an idle recovery unit journal on the
selected volume, then a new one is created.

The following example compares the placement of a recovery unit journal
under DECdtm and RUF:
Using DECdtm

Using RUF

$START_TRANSW
$GET from parameter (streaml)
$UPDATE to parameter (streaml)

$START_RU
$GET from parameter (streaml)
$UPDATE to parameter(streaml)

•

Using VAX RMS Journaling Version 5.4 (DECdtm services), the
recovery unit journal is created when the $GET service is called.

•

Using a version of VAX RMS Journaling prior to Version 5.4 (that is,
RUF services), the recovery unit journal is created when the $UPDATE
service is called.

•

Using RUF emulation on Version 5.4, the recovery unit journal is
created when the $START_RU service is called.

•

With the VMS Version 5.4 operating system, even read-only
transactions require a recovery unit journal, but it will not be written
to.

29-5

VAX RMS Journaling: Support for DECdtm Services
29.7 Multiple Long-Term Journals Allowed

29.7

Multiple Long-Term Journals Allowed
The files involved in a single transaction are no longer restricted to a
single after-image journal and a single before-image journal.

29.8

Mixed-Version Clusters
Nodes using versions of VAX RMS Journaling prior to Version 5.4 of the
VMS operating system can run together in a VAXcluster with nodes using
Version 5.4. Shared access to files marked for journaling is supported
in such a mixed-version cluster with one exception: you cannot use a
node running an earlier version to recover a file that participated in a
transaction that required a two-phase commit. VAX RMS Journaling
Version 5.4 includes certain records ("prepare" records) in the journal that
earlier versions do not understand.

(~'\
~._//

The following examples show responses to three ways of trying to access
the file [FINANCE]PAYROLL.DAT, which has a prepare record in its
recovery unit journal, using a version of VAX RMS Journaling prior to
Version 5.4:
•

If your application tries to access the file directly, RMS returns the
following error messages to your application:

$ TYPE PAYROLL.DAT
%TYPE-W-OPENIN, error opening WORK1: [FINANCE] PAYROLL.DAT; 1 as input
-RMS-E-RRF, recovery unit recovery failed
-RMSREC-F-INVJNLFIL, invalid journal file

In addition, detached recovery sends the following messages to
OPCOM:
%%%%%%%%%%% OPCOM 30-MAY-1990 09:16:20.84 %%%%%%%%%%%
Message from user BEETHOVEN on EROICA
%RMSREC-F-OPRHDRDET, error occurred during detached recovery unit recovery; init
iated by process ID (PID) 4A2004AO
%%%%%%%%%%% OPCOM 30-MAY-1990 09:16:20.91
Message from user BEETHOVEN on EROICA
%RMSREC-F-INVJNLFIL, invalid journal file

%%%%%%%%%%%

%%%%%%%%%%% OPCOM 30-MAY-1990 09:16:20.92 %%%%%%%%%%%
Message from user BEETHOVEN on EROICA
-RMSREC-F-JNLFILE, journal file DISK$WORK1: [SYSJNL]RMS$OOOOOOlE.RMS$JOURNAL;24
%%%%%%%%%%% OPCOM 30-MAY-1990 09:16:20.93 %%%%%%%%%%%
Message from user BEETHOVEN on EROICA
-RMSREC-F-INVJNLIDX, invalid journal index number

•

If you try to use the Recover Utility (RECOVER) on the file, RECOVER
responds with the following messages:

%RMSREC-F-NOTCOMREC, file was not completely recovered as requested
%RMSREC-F-LSTVALTIM, time of last valid record: 28-MAY-1990 13:18:06.27
%RMSREC-F-INVJNLFIL, invalid journal file
-RMSREC-F-JNLFILE, journal file DISK$WORK1: [FINANCE]PAYROLL.AIJ1;1
-RMSREC-F-CURNOTSUPP, journal entry: 12 currently not supported

29-6

VAX RMS Journaling: Support for DECdtm Services

29.8 Mixed-Version Clusters

•

If the file is being accessed by a process on a node running a version of
the VMS operating system prior to Version 5.4 and by a process on a
Version 5.4 node and the Version 5.4 node fails, the surviving accessor
on the other node attempts to perform detached recovery. Detached
recovery fails, deletes the surviving process, and sends the following
messages to OPCOM:

%%%%%%%%%%% OPCOM 30-MAY-1990 09:16:20.84 %%%%%%%%%%%
Message from user BEETHOVEN on EROICA
%RMSREC-F-OPRHDRDET, error occurred during detached recovery unit recovery; init
iated by process ID (PID) 4A2004AO

%%%%%%%%%%% OPCOM 30-MAY-1990 09:16:20.91
Message from user BEETHOVEN on EROICA
%RMSREC-F-INVJNLFIL, invalid journal file

%%%%%%%%%%%

To recover the file, you must perform recovery on, or access the file from, a
node running VAX RMS Journaling Version 5.4, or you must upgrade the
remaining nodes in your VAXcluster to Version 5.4 of the VMS operating
system.

o
29-7

c
30

VMSINSTAL

This chapter describes enhancements to the VMSINSTAL procedure for
Version 5.4 of the VMS operating system. See the revised VMS Developer's
Guide to VMSINSTAL for complete information.

30.1

The Software Product Kit Building Command Procedure
(SPKITBLD.COM) now has an additional parameter, the data-file
parameter CP4). You use this parameter to specify the name of a data file;
SPKITBLD.COM uses the data file to obtain information that it needs to
perform a product kit build. For more information on the SPKITBLD.COM
data-file parameter, see the VMS Developer's Guide to VMSINSTAL.

30.2

c
c

New Parameter for the VMSINSTAL SPKITBLD.COM Procedure

New and Enhanced VMSINSTAL Callbacks
The following callbacks are new or enhanced:
•

CHECK_VMS_VERSION
The VMS INSTAL callback CHECK_VMS_VERSION has a new valid
value for the option parameter CP4), the value S. When you specify
S for the option parameter, messages are not output to the screen
or saved during product installation. For more information on the
CHECK_VMS_VERSION callback, see the VMS Developer's Guide to
VMSINSTAL.

•

SET
The VMSINSTAL callback SET has a new option, SET SHUTDOWN.
The SET SHUTDOWN option specifies that a reboot is necessary in
order to complete the product installation. For a description of the SET
SHUTDOWN option, see the VMS Developer's Guide to VMSINSTAL.

•

GET_PASSWORD
A new VMSINSTAL callback, GET_PASSWORD, obtains a systemgenerated or installer-specified password. For more information about
the GET_PASSWORD callback, see the VMS Developer's Guide to
VMSINSTAL.

o
30-1

c
31

DECwindows and CDA Programming Features

This chapter describes DECwindows and CDA programming components
that have been enhanced for Version 5.4 of the VMS operating system, as
follows:

•

New DECwindows programming examples (Section 31.1)

•

Enhancements to the XUI Toolkit color mixing widget (Section 31.2)

•

Display PostScript@ support (Section 31.3)

•

PostScript@ support for the CDA VIEW command, CDA Viewer
support of Adobe font metrics and DECmath fonts, and the availability
of new CDA documentation (Section 31.4)

See the Overview of VMS Documentation for more information about the
new and revised books referenced in this chapter.

o
c

31.1

New Programming Examples in DECW$EXAMPLES Directory
This section describes the following new programming examples that have
been added to the DECW$EXAMPLES directory:

31.1.1

•

BTrap (Section 31.1.1)

•

TestVHist (Section 31.1.2)

•

TestVList (Section 31.1.3)

•

VDragExample (Section 31.1.4)

BTrap (Broadcast Message Trapper)
BTrap (Broadcast Message Trapper) is a program that traps broadcast
messages and displays them in a scrollable output window. The example
program shows how to do the following:
•

Use XtAddInput to make AST completion routines compatible with the
DECwindows toolkit

•

Implement pop-up menus

•

Implement a custom widget (the TList widget)

•

Save current geometry settings in a resource file, under program
control

The BTrap package consists of the following files:

•

BTrap.c- Main module for the sample program

® Display PostScript is a registered trademark of Adobe Systems Incorporated.
® PostScript is a registered trademark of Adobe Systems Incorporated.

31-1

OECwindows and COA Programming Features
31.1 New Programming Examples in DECW$EXAMPLES Directory

31.1.2

•

BTrap. uil-UIL file for the sample program

•

TList.c-TList widget sources

•

TList.h-TList widget include file

•

TList.note-TList widget documentation

•

TList.uil-TList widget UIL include file

TestVHist (Histogram Widget Exerciser)
The TestVHist (Histogram Widget Exerciser) program exercises the VHist
widget, a dynamically updatable bar histogram widget. It shows how to
include a VHist widget in an application program.
The TestVHist package consists of the following files:

31.1.3

•

TestVHist.c- Main module for the sample program

•

TestVHist.uil-UIL file for the sample program

•

VHist.c-VHist widget sources

•

VHist.h-VHist widget include file

•

VHist.note-VHist widget documentation

•

VHist.uil-VHist widget UIL include file

TestVList (VList Widget Exerciser)
The TestVList (VList widget exerciser) program exercises the VList widget,
a dynamic, customizable list box widget. It shows how to include a VList
widget in an application program.
The TestVList package consists of the following files:

31-2

•

TestVList.c-Main module for the sample program

•

TestVList.uil-UIL file for the sample program

•

VList.c-VList widget sources

•

VList.h-VList widget include file

•

VList.note-VList widget documentation

•

VList.uil-VList widget UIL include file

•

VFrame.c-VFrame widget sources

•

VFrame.h-VFrame widget include file

•

VFrame.uil-VFrame widget UIL include file

•

VHeader.c-VHeader widget sources

•

VHeader.h-VHeader widget include file

•

VHeader. uil-VHeader widget UIL include file

DECwindows and CDA Programming Features

31.1 New Programming Examples in DECW$EXAMPLES Directory

31.1.4

VDragExample (VDrag Exerciser)
The VDragExample (VDrag Exerciser) program exercises the VDrag
routine, which allows the user to drag widgets about within a window. It
shows how to intercept button and motion events to move a widget while
tracking the pointer.
The VDragExample package consists of these files:

c
o

31.2

•

VDragExample.c-Main module for the sample program

•

VDrag.c-VDrag routine sources

•

VDrag.note-VDrag routine documentation

XUI Toolkit: Enhancements to Color Mixing Widget
The XUI Toolkit color mixing widget, created by the COLOR MIX CREATE
routine, now supports both the hue lightness saturation (HLS) color
model as well as the red, green, blue (RGB) model. The HLS color model
allows users to choose the hue (color), lightness of the color, and the color
saturation, which determines how solidly the color appears. The RGB
color model provides three scales, each representing a percentage of red,
green, and blue.
The same Xll RGB callback information is returned regardless of which
color model is used. An option menu presents the HLS and RGB color
model choices and allows users to switch between models as often as they
wish.
The COLOR MIX CREATE routine includes eleven new attributes that
support the HLS model:

•

color_model-The color model currently being used

• hue_label-The label of the hue scale widget
• light_label-The label of the lightness scale widget

•
•

sat_label-The label of the saturation scale widget
black_label-The label for the zero end of lightness scale widget

• white_label-The label for the 100% end of lightness scale widget
• gray_label-The label for the zero end of saturation scale widget

•
•
•

full_label-The label for the 100% end of the saturation scale widget
optioD_label-The label for the color model option menu
hIs_label-The label for the color model option menu HLS option

• rgb_Iabel-The label for the color model option menu RGB option

See the VMS DECwindows Toolkit Routines Reference Manual for a
complete description of the COLOR MIX CREATE routine.

31-3

OECwindows and COA Programming Features
31.3 VMS DECwindows Display PostScript System

31.3

VMS OECwindows Display PostScript System
VMS Version 5.4 includes the Display PostScript® system, which provides
text and image display capability for bitmapped workstations. The
DECwindows implementation of the Display PostScript system allows
programmers to write applications in a general purpose language like C,
yet describe the images and text using the device-independent PostScript®
software. Programmers can mix X and PostScript routines, even within a
single window, using a single network connection to an X server.
The Display PostScript system provides additional imaging capabilities to
the X programming routines, as follows:
•

Coordinate system that can be moved, rotated, and scaled

•

Bezier curves to make it easy to display any curve, no matter how
complex

•

Device-independent color model

•

Text that can be scaled and rotated

•

Image operators for scanned images (scaling, rotating,
transformations, gray-scale manipulation)

The Display PostScript system is a device-independent graphics
architecture that can be implemented on a variety of windowing systems.
The Display PostScript server consists mainly of a PostScript interpreter,
which executes PostScript language code to display images on a user's
screen. The Display PostScript client consists mainly of a Client Library
through which an application communicates with the server.
DEC windows implements the Display PostScript system as an extension
to the X Window System, on which DECwindows is based. The Display
PostScript server is an extension to the X server; the Client Library is an
extension to Xlib. The Display PostScript extensions allow an application
written in any VAX language to handle Display PostScript programming
tasks on an X-based system.

o
C)

Table 31-1 provides a summary, by topic, of the documentation available
for the Display PostScript system and programming in the VMS
DECwindows environment.

o
® Display PostScript is a registered trademark of Adobe Systems Incorporated.

® PostScript is a registered trademark of Adobe Systems Incorporated.

31-4

DECwindows and CDA Programming Features

31.3 VMS DECwindows Display PostScript System

Table 31-1

Display PostScript Documentation

Topic

Type of
Information

Programming in the VMS
DECwindows environment

Overview and
guidelines

XUI Style Guide
VMS DEC windows Guide to Application Programming
VMS DECwindows Xlib Programming Volume

Programming using the
PostScript language

Tutorial

PostScript Language Tutorial and Cookbook by Adobe Systems,
available in most bookstores

Reference

PostScript Language Reference Manual by Adobe Systems
(available in most bookstores)

Oeviceindependent
overview

Display PostScript System Perspective for Software Developers

Oeviceindependent
reference

Display PostScript System Client Library Reference Manual
Display PostScript System pswrap Reference Manual
PostScript Language Extensions for the Display PostScript
System
PostScript Language Color Extensions
PostScript Document Structuring Conventions Specification
Version 2.1

Oevicespecific
overview and
reference

VMS DECwindows Display PostScript System Programming
Supplement

Programming using the
Display PostScript system

o
o
31.4

Document

Compound Document Architecture (CDA)
The following sections describe CDA new features, which include
PostScript support for the VIEW command, CDA Viewer support of
Adobe font metrics and DECmath fonts, and the availability of new CDA
documentation.

c
31.4.1

PostScript Support for CDA VIEW Command
The VMS VIEW command invokes the CDA Viewer, which lets you view
a compound document file on a character cell terminal or DECwindows
display. With the Version 5.4 of the VMS operating system, PS is now a
supported input format (.PS file extension).
Note that PostScript file viewing is supported only in the DECwindows
CDA Viewer and only when running to displays with servers that contain
the Display PostScript Extension. To view a PostScript file, you must
specify the IINTERFACE=DECWINDOWS qualifier. PostScript file
viewing does not support processing options.

For more information about the VIEW command, see the CDA Reference
Manual.
For new information about using the DECwindows CDA Viewer to view
PostScript files, see Section 7.2, CDA Viewer.

31-5

DECwindows and CDA Programming Features
31.4 Compound Document Architecture (CDA)

31.4.2

CDA Viewer Support of Adobe Font Metrics and DECmath Fonts
The CDA Viewer now uses the Adobe font metrics in processing a DDIF
file for viewing. The font name in a DDIF file follows the X-II font naming
convention. When processing a file from a creating application that uses
font metrics other than Adobe font metrics, the CDA Viewer defaults to
the Adobe Courier font.
When processing a file for viewing, the DECwindows CDA Viewer queries
the X server for a list of available fonts. Although the CDA Viewer does
not use these fonts in its calculations, it tries to match the font from the
file with an XII font on the server. If there is not an exact match, the
CDA Viewer uses the font from the list that is the closest lower point size
for that font name. If there is no match at all, the DECwindows CDA
Viewer display type defaults to 12-point Adobe Courier.
The character cell CDA Viewer displays all files in a 12-point Courier font.
The contents of each file are spaced and displayed correctly, based on the
font that is stored in the file.
The Adobe font metrics are stored in SYS$PS_FONT_METRICS:.AFM on
VMS systems and in lusrllib/font/metricsl on ULTRIX systems.
The CDA Viewer also supports the DECmath fonts used by DECwrite for
equation editing.
For more information, see the CDA Reference Manual.

31.4.3

New CDA Documentation
The following separately orderable manuals are now available:
•

The Introduction to the CDA Services provides an overview of
compound document processing terminology and the various
components of CDA, which include the CDA Toolkit, the CDA converter
architecture, DDIF, and DTIF.

•

The Guide to Creating Compound Documents with the CDA Toolkit is
a tutorial manual that describes how to use the CDA Toolkit to create
CDA-conforming compound document applications on VMS and on
ULTRIX systems.

•

The CDA Reference Manual provides reference material that
supplements the CDA user guides. It describes the DDIF and DTIF
aggregates, the CDA Toolkit routines, the front and back end converter
routines, the callable DECwindows and character-cell viewer routines,
and the VMS and ULTRIX system commands used to convert and to
view compound document files.

. ~~)

See the Overview of VMS Documentation for more information about these
manuals.

o
31-6

c
A

VMS Version 5.3 Features

This appendix describes features that were new to Version 5.3 of the VMS
operating system but are not yet documented in other printed manuals.

A.1

VMS Version 5.3 System Management Features
This section describes enhancements to the following components of the
VMS operating system:

o
A.1.1

•

Lock Manager

•

NCP Executor Commands

Extension of Lock Manager Limit
The Lock ID space for the Lock Manager is now extended from 65,535 to
262,144 locks. The SYSGEN parameters listed in the following table are
increased to the values indicated:

A.1.2

SYSGEN Parameter

New Maximum Value

LOCKIDTBL

262,144

LOCKIDTBL_MAX

262,144

SRPCOUNT

270,336

SRPCOUNTV

270,336

IRPCOUNT

135,168

IRPCOUNTV

135,168

NCP Executor Command Changes
The NCP executor commands now include the following:

A.1.3

•

A new parameter to SETIDEFINE EXECUTOR command

•

New display characteristics for SHOW EXECUTOR
CHARACTERISTICS command

Parameter for SET/DEFINE EXECUTOR
The network control ancillary program (NETACP) manages an index into
a properly synchronized table in nonpaged-pool memory. System managers
can modify the size of the table using the NCP command SETIDEFINE
EXECUTOR with the new parameter MAXIMUM DECLARED OBJECTS.

A-1

VMS Version 5.3 Features
A.1 VMS Version 5.3 System Management Features

A.1.4

Parameter

Description

MAXIMUM DECLARED OBJECTS

Specifies the number of objects that processes can declare. To
determine the current number of declared objects on your system, use
the NCP SHOW KNOWN OBJECTS command. Each of the objects
with a PID listed is one declared object. A single process can declare
more than one object. Failure to provide a sufficient number of objects
can result in the failure of network servers to be initialized. The default
of 31 objects is sufficient for most configurations. The valid range is 8
to 16383. Note that dynamically setting the number lower has no effect.

SHOW EXECUTOR CHARACTERISTICS Command
The SHOW EXECUTOR CHARACTERISTICS command now displays
information as shown in the following example. Note that a new entry
Maximum Declared Objects is displayed and the Pipeline quota now shows
10000.
NCP>

SHOW EXECUTOR CHARACTERISTICS

Node Volatile Characteristics as of 16-JUN-1990 10:48:27
Executor node

2.11

(BOSTON)

Identification
Management version
Incoming timer
Outgoing timer
Incoming Proxy
Outgoing Proxy
NSP version
Maximum links
Delay factor
Delay weight
Inactivity timer
Retransmit factor
Routing version
Type
Routing timer
Broadcast routing timer
Maximum address
Maximum circuits
Maximum cost
Maximum hops
Maximum visits
Maximum area
Max broadcast nonrouters
Max broadcast routers
Maximum path splits
Area maximum cost
Area maximum hops
Maximum buffers
Buffer size
Default access
Pipeline quota
Alias incoming
Alias maximum links
Alias node
Path split policy
Maximum Declared Objects

A-2

DECnet-VAX V5.3, VMS V5.3
V4.0.0
45
45
Enabled
Enabled
V4.1. 0
128
80
5
60
10
V2.0.0
routing IV
600
40
1023
16
1022
15
63
63
64
32
1
1022
30
100
576
incoming and outgoing
10000
Enabled
32
2.10 (CLDSTR)
Normal
31

o
0

VMS Version 5.3 Features

A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

A.2

VMS Version 5.3 Support for the VMS Distributed Name Service
The Distributed Name Service (DNS) is a facility for storing the names
of resources in your network such as files, disks, nodes, queues, and
mailboxes. The Distributed Name Service clerk is the VMS programming
interface to DNS that allows an application to register a resource in the
name service and then access the resource from any point in the network
by a single name. DNS is a layered product and must be installed in your
network before you can start the DNS clerk or utilize the name service.
Applications that need the Distributed Name Service must use the $DNS
clerk system service and the DNS run-time routines to register, modify,
and locate information in the DNS database. A DNS clerk, which is
resident on every VMS Version 5.3 system and later, receives application
requests through the $DNS system service. The clerk locates a DNS
server that can process the request. Once the request is satisfied, the clerk
returns the requested information to the client application.

The information in this section is intended for VMS programmers who are
writing applications that call the Distributed Name Service. It includes
the following:

•

Conceptual information on DNS

•

DNS clerk system services, $DNS and $DNSW

•

DNS run-time routines

•

Startup information for the DNS clerk

•

DECnet event messages from the DNS clerk

See the VMS System Messages and Recovery Procedures Reference Manual
for information about system error messages generated by the DNS clerk.

A.2.1

Introduction to the Distributed Name Service
The VAX Distributed Name Service (DNS) provides a means of assigning
unique names to network resources so that a network application or
network user can find resources within the network. (Resources are such
things as disks, systems, applications, and so on.) Once an application has
named a resource using DNS, the name is available for all users of the
application. Multiple users located throughout a network can refer to a
common resource by the same iIame. Resources can be moved within the
network. No additional preparation is required, and it is not necessary to
learn a new naming convention.
You should consider using DNS applications that need to access such
remote resources as printers, files, disks, and nodes. In addition,
application databases or servers are good candidates for naming. All
of these resources would be commonly named and their locations identified
within DNS. With DNS, the resource could be moved without users being
aware of the change.

A-3

VMS Version 5.3 Features
A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

Although it is desirable to name application databases, you should
ordinarily use DNS to store only the location of the database, not the
database itself. (Most database applications require higher levels of
consistency than DNS provides.) If the database is relocated, then only
the DNS information has to be modified.

A.2.2

The DNS Namespace
The collection of names in the Distributed Name Service database is called
a namespace. A namespace is located on VMS nodes where the DNS
server software is installed. The collection of databases stored on each
server makes up the namespace itself.
DNS refers to the named resources in a namespace as objects. Each
object name refers to a specific entity. The object .name is important
because applications use the object name in all DNS operations.
Associated with every object is a set of attributes describing properties of
an object. An application reads object attributes for information such as
an address, class, or version.
Most applications use the address attribute of an object, which allows you
to find the node on which a resource resides. When a network resource is
relocated, an application has DNS update the object's address attribute.
All requests for the object receive the new address. Since the object
has the same DNS name, the application user can be unaware that the
resource has moved.
A.2.2.1

Planning Namespace Objects
When writing applications that use DNS, it is important to determine
ahead of time what resources an application needs and how an application
will use each resource. Then you can determine what objects an
application needs to create and the kind of information each object
needs to store. Once the object is designed, you can decide which object
attributes to assign and what their values will be.

A.2.2.2

Restrictions
Because of the high cost of keeping copies of DNS names synchronized,
you should use DNS applications that store information that does not
change frequently. Frequent updates add traffic to the network, which
can degrade overall network performance. Because resources such as files,
disks, nodes, queues, and mailboxes remain on one node for a long time, a
good example of information to store with DNS is a network address.

Not only should the information stored in DNS be relatively static, it
should also be verifiable. When DNS updates its database, it attempts to
send the update to all copies of the name within 24 hours. This means
that your application can request data from a copy of a name that has
not been updated. An application must be able to recognize when data is
invalid. For this reason, a network address is a good example of data that
can be validated. If you use an address and the resource is not there, the
data is obviously outdated.

A-4

VMS Version 5.3 Features

A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

A.2.2.3

A.2.2.4

•

Object creation-An application needs to create an object to represent
each network resource it requires.

•

Object modification-Once an object is created to represent a resource,
an application modifies the object to contain the attributes and values
the application requires.

•

Object deletion-When a resource is no longer useful, an application
should delete the object.

•

Information retrieval-The most common operation an application
performs is requesting the DNS clerk to obtain the values of an
attribute so that, for example, the application can locate the resource
in the network.

Object Names
The name DNS assigns to an object is one that the user supplies. The
client application translates the name it receives through the user
interface from string format into opaque format before passing it to the
DNS clerk. DNS works only with opaque format because it is guaranteed
to be unique, whereas string format often contains logical names that
easily change.

The $DNS system service supplies functions for conversion between string
and opaque format. If an application maintains its own databases, then
the application must store DNS names in opaque format.
A.2.2.S

Using the Namespace
An application choosing to use the namespace performs four basic
operations:

Object Attributes
Client applications store information about a resource as object attributes.
When creating an object, an application needs to assign a class name and
a version to a new object. The class name reflects the purpose of the object
within an application. The purpose can be specific to an application or it
can be shared among a group of applications. For example, a group of user
names might be shared. An application uses the class name to search for
its objects or list its objects. The class version helps to pair a version of an
object with a software version.

To store additional information with an object, an application must modify
the object.

DNS always assigns certain attributes to an object during creation. It
assigns a unique identifier (UID) and an update time-stamping (UTS)
indicating when an object was last edited. DNS also assigns a third
attribute that specifies access control for the new object. Initially, the
owner of the object has read, write, delete, control, and test access.
The namespace administrator can modify this access according to site
requirements.
An attribute name is limited to 31 characters and its value cannot exceed
4000 bytes. The name service assigns a prefix of DNS$ to the name of
each attribute it assigns. An application creates a prefix to assign to
attributes it creates. For example, DECnet uses the prefix DNA$ and
A-S

VMS Version 5.3 Features
A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

the Distributed File Service uses the prefix DFS$. Names assigned by
Digital all contain the dollar sign ($). User-supplied names should use
an underscore (_). To ensure uniqueness, you should register your facility
name through Digital's product registration program.

A.2.3

Structure of a Namespace
A DNS namespace is a hierarchical set of directories, as depicted in
Figure A-I. At the top of the hierarchy is the root directory, which
is symbolized by a period (.). Below the root directory are levels of
subdirectories. The namespace administrator establishes the directory
structure of the namespace and, in some cases, assigns names to
directories. While the organization of the namespace directories is similar
to the VMS directory structure, names pace directories are completely
separate from the VMS directory structure.
Figure A-1

A DNS Namespace

Root

I
SALES

ATLANTA

RESEARCH

I
COMMUNICATIONS

ENGINEERING

MARKETING

I
DEVELOPMENT
dey disk
tools_disk
node_client

J}
=J

Objects

ZK-0959A-GE

Directories in a namespace can contain three types of entries:
•

Objects

•

Directory pointers

•

Soft links

An object represents a network resource. It consists of a name that is
unique within the namespace and its associated attributes.

Directory pointers are used internally by DNS to link one level of
directories to the next. DNS refers to the hierarchical relationship of
directories in terms of child directories and parent directories.
A soft link provides an alternate name for an object, directory, or soft link.
For examhple , da nam~spac~ shtructured with b oth an orhganizhationlal alnd a
geograp lcal imenslOn mIg t access a singl e 0 bdect t roug mu tip e so f t
links. A soft link can also be useful in renaming an object. The soft link
would point to the original object name so that users could successfully use

A-6

0
.

VMS Version 5.3 Features

A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

an outdated name. This kind of soft link would be deleted after sufficient
time has passed for applications and users to become aware of the new
object name. You create and delete links through the DNS management
program.
Although an application requests the creation of an object in order to
register a resource, it does not position the object in the namespace. The
system administrator determines which directory DNS stores the object in.
The structure of a namespace differs for each network, so you should not
hard-code names into applications.
A.2.3.1

Naming Syntax
The DNS name of an object, directory, or soft link in the namespace
is a complete path specification from the root directory to the
entity in the directory of interest. For example, the DNS name
.ENGINEERING.DEVELOPMENT.TOOLS_DISK identifies an
object named TOOLS_DISK in the namespace directory called
.ENGINEERING.DEVELOPMENT. The ENGINEERING directory is
in the root directory, and DEVELOPMENT is a child directory of the
ENGINEERING directory.

While the full name is a complete path name from the root directory, each
element in a full name is called a simple name. The last simple name
in a full name designates an object, a child directory, or a soft link. In
the previous example, TOOLS_DISK is a simple name assigned to a disk
object. The maximum length of a simple name is 255 bytes.
You can represent a full name in three ways:
namespacename:.simplename.simplename

or
.simplename.simplename

or
simplename.simplename

If the full name does not start with a namespace name or a period,
DNS attempts to translate the first simple name as a logical name. Any
equivalence name found is added to the name string in place of the
matched simple name. This process is repeated until the first term does
not match a logical name or the clerk encounters either a namespace name
or a leading period. (A namespace name, assigned during DNS server
installation, defaults to node-name_NS.)

The following example shows what happens with the name
RESEARCH.PROJECT_DISK:
1

Look up RESEARCH as a logical name.
RESEARCH translates to ENG.RESEARCH, so the name string
expands to ENG.RESEARCH.PROJECT_DISK.

Look up ENG as a logical name.
ENG translates to .ENGINEERING, so the name string becomes
.ENGINEERING.RESEARCH.PROJECT_DISK. Because the new
name has a leading period, translation stops.

A-7

VMS Version 5.3 Features
A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

A.2.3.2

The namespace name, INMAX_NS, is added to the front of
.ENGINEERING because it is not explicitly specified. (A namespace
administrator establishes the namespace name during installation.)
The name becomes INMAX_NS:.ENGINEERING
.RESEARCH.PROJECT_DISK.

Logical Names
When the DNS clerk is started on a VMS operating system (see
Section A.2.10), the VMS system creates a unique logical name table
for DNS to use in translating full names. This logical name table, called
DNS$SYSTEM, prevents unintended interaction with other system logical
names. The DNS use of logical names in parsing full names is described
in Section A.2.S.1.

To define systemwide logical names for DNS objects, use the
DCL command DEFINE. For example, to create the logical
RESEARCH.PROJECT_DISK shown in the previous section, you would
enter the following DCL command:
$

To define process or job logical names for $DNS, you must create a process
or job table and redefine DNS$LOGICAL as a search list, as in the
following example (note that elevated privileges are required to create
a job table):
$
$

~\I

~-./

DEFINE/TABLE=DNS$SYSTEM RESEARCH "ENG. RESEARCH"

When parsing a name, the $DNS service specifies the logical name
DNS$LOGICAL as the table it uses to translate a simple name into a
full name. This name ordinarily translates to DNS$SYSTEM in order to
access the systemwide DNS logical name table.

CREATE /NAME TABLE DNS PROCESS TABLE
DEFINE /TABLE=LNM$PROCESS DIRECTORY DNS$LOGICAL $ DNS_PROCESS_TABLE,DNS$SYSTEM

Once you have created the process or job table and redefined
DNS$LOGICAL, you can create job-specific logical names for DNS using
the DCL command DEFINE, as follows:
$

(\
,-)

DEFINE /TABLE=DNS PROCESS TABLE RESEARCH "ENG.RESEARCH.MYGROUP"

For information about logical names, see Introduction to VMS System
Services.
A.2.3.3

Valid Characters for DNS Names
DNS namespace names, full names, or simple names can contain letters,
numbers, and certain punctuation marks from the ISO Latin 1 character
set, as shown in Figure A-2. Additional characters and punctuation
marks can appear as long as the name is enclosed in quotation marks, for
example, "project%". See Figure A-S.

o
A-8

VMS Version 5.3 Features

A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

Figure A-2

Valid Character Codes for DNS Simple Names

Code Range
(Decimal}

Character

036
045
048-057
065-077
078-090
095
097-109
110-122
192-207
208-214
216-223
224-239
240-246
248-255

0123456789
ABCDEFGHIJKLM
NOPQRSTUVWXYZ
abcdefghijklm
n opq r s t uvwxyz

A AAAAA,iEQEEEE
[) No6666
0UUOOVpB

j f

a aaaaaa3~eeeelfi'i

n06665

" uuOOypy
ZK-0961 A-GE

Note: All simple names containing the dollar sign ($) are reserved for
use by Digital.

Figure A-3

Code Range
(Decimal)

032-033
035
037-044
046-047
058-064
091-094
096
123-126
160-167
168-174
175-187
188-191
215
247

Additional Character Codes Allowed in Quoted Simple
Names

Character

{space} !
#
% &
()
+
/
< = > ?
[ \ ] "

{ I }
{ no-break space} i
.. © ~
...,
«

1f.I
X

£
®

I
I

§
1

ZK-0962A-GE

DNS maintains the case of an entity when it registers an object, but it is
case insensitive in lookups. For example, the name eng. research would
match the name ENG.RESEARCH.

DNS also supports binary simple names. A binary name consists of the
leading character pair %x or %X, followed by pairs of hexadecimal digits.
A binary simple name does not match any regular or quoted simple name,
even if a given name has the same binary value.

A-9

VMS Version 5.3 Features
A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

DNS makes use of wildcards for identifying groups of objects during search
operations. Wildcards consist of the following:

A.2.4

Symbol

Name

Meaning

Question mark

Match one character.

Asterisk

Match any number of characters.

Creating Objects
Each application that uses DNS must register its resources in the
namespace using either the $DNS or the $DNSW system service.
Registration involves creating an object in the namespace to represent
the resource. You create an object to represent each resource in the
network that your application needs to find. At the same time, you should
define attributes the object needs and assign their values.

(\.
~/

A DNS object consists of a name and its associated attributes. You create
the object first, along with some key attributes. Later, you can modify the
object to hold additional attributes that are relevant to the application.
To create an object with $DNS:
1

Prompt for a name from the user interface.
The name that an application assigns to an object should come from
a user interface, a configuration file, a system logical, or some other
source. The application never assigns an object's name because the
namespace structure is uncertain. The name the application receives
from the user interface is in string format.

Use the $DNS parse function to convert the full name string into the
opaque format of DNS.

Optionally, reserve an event flag so you can check for completion of the
service.

o
o

o
A-10

VMS Version 5.3 Features

A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

Build an item list containing the following elements:
•

The opaque name for the object (resulting from the translation in
step 2)

•

The class name given by the application, which should contain the
facility code

•

The class version assigned by the application

•

An optional timeout value, specifying when the call expires

Optionally, provide the address of the DNS status block to receive
status information from the name service.

Optionally, provide the address of the asynchronous system trap (AST)
service routine. AST routines allow a program to continue execution
while waiting for parts of the program to complete.

Optionally, supply a parameter to pass to the AST routine.

Call the create object function, providing all the parameters supplied
in steps 1 through 7.

If a clerk call is not complete when timeout occurs, then the call completes
with an error. The error is returned in the DNS status block.

An application should check errors returned; it is not enough to check the
return of the $DNS call itself. You need to check the DNS status block to
be sure there are no errors at the DNS server.
The following C routine shows how to create an object in the namespace
with the synchronous service $DNSW. The routine demonstrates how to
construct an item list.

#include <dnsdef.h>
#include <dnsmsg.h>
/*
* Parameters:
class name
address of the opaque simple name of the class
*
to assign to the object
*
class len
length (in bytes) of the class opaque simple name
*
*
object - name= address of opaque full name of the object
*
to create in the namespace.
object len
length (in bytes) of the opaque full name of the
*
*
object to create
*/
create object(class_name, class len, object_name, object len)
unsigned char *class name;
unsigned short class len;
unsigned char *object_name;
unsigned short object len;
{

struct $dnsitmdef createitem[4]; /* Item list used by system service */
struct $dnscversdef version;
/* Version assigned to the object */
struct $dnsb iosb;
/* Used to determine DNS server status */
int status;
/* Status return from system service */

A-11

VMS Version 5.3 Features
A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

/*
* Construct the item list that creates the object:

*/
createitem[O] .dns$w_itm_size = class_len;
..
createitem[O] .dns$w_itm_code = dns$_class;
createitem[O] .dns$a_itm_address = class_name;
createitem[l] .dns$w_itm_size = object_len;
~
createitem[l] .dns$w_itm_code = dns$_objectname;
createitem[l] .dns$a_itm_address
object_name;
version.dns$b c major = 1;
version.dns$b=c=minor = 0;

createitem[2] .dns$w_itm_size = sizeof(struct $dnscversdef);
createitem[2] .dns$w_itm_code = dns$_version;
createitem[2] .dns$a_itm_address = &version;
* ((int *)&createitem[3]) = 0;
status

sys$dnsw(O, dns$_create_object, &createitem, &iosb, 0, 0); ~

if(status == SS$_NORMAL)
{

status

iosb.dns$l_dnsb_status;

return(status);

o The first entry in the item list is the address of the opaque simple
name representing the class of the object.
•

The second entry in the item list is the address of the opaque full
name for the object.

@) The next step is to build a version structure, which will indicate the

version of the object. In this case, the object is version 1.0.

e The third entry in the item list is the address of the version structure
that was just built.
~

Zero terminates an item list.

(3 Call the system service to create the object.

•

A.2.5

Check to see that both the system service and DNS were able to
perform the operation without error.

Modifying Objects
Mter applications use DNS to create objects that identify resources, they
add attributes to the newly created objects that describe properties of the
object.
You modify an object whenever you need to add an attribute, change an
attribute value, or delete an attribute. You can add as many attributes
as you like. If you add the same attribute to an object twice, the timestamping on the attribute is updated.

A-12

VMS Version 5.3 Features

A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

DNS attributes can have a single value or they can have a set of values.
For example, an attribute holding the class version number of a resource
would have a single value, while an attribute holding the location of a
service in the network could have a set of values. The set would hold the
addresses of all nodes in the network that offer the service. Depending on
the attribute type, DNS performs a slightly different action. DNS adds or
deletes a value when there is only one. When there is a set of values, DNS
adds or deletes a value from an existing group of values.
To modify an object with $DNS:
1

Build an item list containing the following elements:
•

The opaque name of the object you are modifying

•

The type of entry, as described in Section A.2.3

•

The operation to perform

•

The type of attribute you are adding-a single value or a set of
values

•

The attribute name

•

The value being added to the attribute

Supply any of the optional parameters described in Section A.2.4.

Call the modify attribute function, supplying the parameters
established in steps 1 and 2.

The following C example shows how to add an attribute and its value to
an object:

#include <dnsdef.h>
#include <dnsmsg.h>
/*
* Parameters:
*
obj_name
address of opaque full name of object
*
obj len
length of opaque full name of object
address of opaque simple name of attribute to create
*
att - name
length of opaque simple name of attribute
*
att len
*
att value= value to associate with the attribute
val len
length of added value (in bytes)
*
*/
add attribute (obj_name, obj len, att_name, att len, att_value, val len)
unsigned char *obj_name;
unsigned short obj len;
unsigned char *att_name;
unsigned short att len;
unsigned char *att_value;
unsigned short val len;
{

struct $dnsitmdef moditem[7];
/* Item list for $DNSW */
unsigned char objtype = dns$k object;
/* Using object entries */
unsigned char opertype = dns$k_present; /* Adding an object */
unsigned char attype
dns$k_set;
/* Attribute will be type set */
struct $dnsb iosb;
/* Used to determine DNS status */
int status;
/* Status of system service */

A-13

VMS Version 5.3 Features
A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

* Construct the item list to add an attribute to an object.
*/
moditem[O] .dns$w_itm_size = obj len;
moditem[O] .dns$w_itm_code = dns$_entry;
moditem[O] .dns$a_itm_address = obj name;
t)
moditem[l] .dns$w_itm_size = sizeof(char);
moditem[l] .dns$w itm code = dns$ lookingfor;
moditem[l] .dns$a=itm=address = &objtype;
~
moditem[2] .dns$w itm size = sizeof(char);
moditem[2] .dns$w-itm-code = dns$ modoperation;
moditem[2] .dns$a-itm=address = &~pertype;
~
moditem[3] .dns$w_itm_size = sizeof(char);
moditem[3] .dns$w itm code = dns$ attributetype;
moditem[3] .dns$a-itm=address = &attype;
~

(\\.
\~

/,.

moditem[4] .dns$w_itm_size = att_Ien;
moditem[4] .dns$w itm code = dns$ attributename;
moditem[4] .dns$a-itm=address = att name;
~
moditem[5] .dns$w_itm_size = val_len;
moditem[5] .dns$w_itm_code = dns$_modvalue;
moditem[5] .dns$a_itm_address = att value;
*( (int *)&moditem[6])

* Call $DNSW to add the attribute to the object.
*/
status

sys$dnsw(O, dns$_modify attribute, &moditem, &iosb,

0, 0);

if(status == SS$_NORMAL)
{

status

iosb.dns$l ctnsb_status;

return (status) ;

t) The first entry in the item list is the address of the opaque full name

of the object.
•

The second entry in the item list shows that the entry is an object-not
a soft link or directory pointer.

The third entry in the item list is the operation to perform. The
program adds an attribute with its value to the object.

The fourth entry in the item list is the attribute type. The attribute
has a set of values rather than a single value.

The fifth entry in the item list is the opaque simple name of the
attribute being added.

(3 The sixth entry in the item list is the value associated with the
attribute.

tt Check to see that both the system service and DNS performed the
operation without error.

A-14

VMS Version 5.3 Features

A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

A.2.6

Distributing the Namespace
A VMS node running DNS server software can contain the entire
namespace. However, performance and reliability are enhanced when
several VMS nodes act as DNS servers.
DNS supports the partitioning of the namespace across several DNS
servers. In this situation, no DNS server contains the entire namespace,
but each contains a portion of the namespace, usually the directories
frequently accessed by local client applications. Directory pointers connect
parts of the the database that are distributed among two or more servers.
Figure A-4 depicts a namespace with three DNS servers. The DESIGN
node contains most of the namespace-the root directory plus the research
and development directories. The applications directory resides on the
APPLY node, while the hardware directory resides on the SHOP node.

DNS refers to a collection of directories on a server as a clearinghouse.
Figure A-4

A Partitioned Namespace

SHOP Node

DESIGN Node

r---------------

Root

1
1
1

RESEARCH

HARDWARE

DEVELOPMENT

SYSTEMS

APPLICATIONS
__________________ J

1______ - - - - - - - - - - - - - - - - - - - - - - - - - -

ZK-0960A-GE

A.2.6.1

APPLY Node
~------------------~
1
1
1
1
1
1
1
1

Replicating Directories
In large networks, many applications rely on DNS and names must be
available for the application to work. To ensure availability, DNS allows
the duplication of data and provides a mechanism to keep all copies of
names synchronized. Then, if one server becomes disabled, applications
can still access the namespace through another server. Whenever data is
duplicated, DNS copies one or more directories with all their contents.

The namespace administrator determines how many copies of each
directory should exist and where they should be located. For example,
Figure A-5 shows the same namespace as Figure A-4. However, in
Figure A-5 the root directory is duplicated so that it exists on all three
DNS servers.

A-15

VMS Version 5.3 Features
A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

A.2.6.2

Types of Directories
Once you duplicate parts of a namespace, you generate different types of
directories. Some are writable, while others are read-only. In a replicated
namespace, there are three types of directories:

•

Master

•

Secondary

•

Read-only

For example, in Figure A-5 there are three copies of the root directory.
The master copy resides on node DESIGN. Read-only copies reside on the
other two nodes.
Figure A-5

A Namespace with Replicated Directories

SHOP Node

DESIGN Node

APPLY Node

Root

RESEARCH

DEVELOPMENT

Root *

Root *
1
1

HARDWARE

SYSTEMS

1_________________________________
* Read-Only Directories

APPLICATIONS

1
1
1~

__________________

ZK-0958A-GE

In a master directory an application can create or modify all types of
entries: objects, directory pointers, and soft links. In a secondary directory
an application can create or modify objects and soft links but not directory
pointers. An application can retrieve namespace data from any type of
directory.

When an application attempts to create a new object or update an existing
one, the DNS clerk sends the request to a DNS server that has a secondary
or master directory. The request to create an object succeeds as long as
no other entry with the same name exists; the request to modify an object
succeeds as long as the object is found in the directory.
A.2.6.3

A-16

Setting Confidence
An application can use the confidence argument in a $DNS call to stipulate
the type of directory that the DNS clerk should use to service the call. For
example, when an application wants to create an object, it can force the
DNS clerk to create the object in the master directory by stipulating a high
confidence level. Otherwise, DNS creates the object either in the master
or in a secondary directory.

VMS Version 5.3 Features

A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

In a create or modify call, confidence has the following meaning:
•

High confidence-Use the master directory.

•

Medium confidence-Use the master or a secondary directory. There
can be multiple copies of secondary directories.

An application's expression of confidence has a slightly different meaning
in a request to find data. In this operation, there are three levels of
confidence:

A.2.6.4

•

High confidence-Use the master directory.

•

Medium confidence-Use cached information to find the location of a
DNS server but get the information from a DNS server.

•

Low confidence-Use cached information.

Maintaining Consistency in Data

Whenever a directory is modified, the name service attempts to send the
updated information to all directory replicas as long as the convergence
attribute of the directory is set to high. Sometimes it is impossible to
deliver the updates to all directory replicas, however, because a network
link may be down or a node may be unreachable.
DNS does have a method of ensuring data consistency-it is called a
skulk. In a skulk, DNS checks to see if data is consistent. If not, it
gathers all updates made to a directory since the last skulk and propagates
the updates to all replicas of the directory. If there is any discrepancy
between information in a master and a secondary directory during a skulk,
then the entry with the most recent time-stamping is used. Once the
skulk is completed, DNS informs all directories of the time-stamping of
the latest universal update.

When the convergence attribute is high, DNS skulks the namespace every
12 hours. When the convergence is low, the skulk occurs every 24 hours.

Directory replicas can lose their consistency between skulks. Two objects
of the same name could be created simultaneously in different directory
replicas or updates to the namespace might not be seen by all copies
immediately. When DNS detects a conflict in replicas, it preserves the
object with the most recent update time-stamping and deletes the older
object. There is a chance that an application may get information from the
namespace that DNS has not synchronized. In this case, an application
has to have a mechanism to deal with the inconsistency.

A.2.7

Requesting Information from DNS
Once an application adds its objects to the namespace and modifies the
objects to contain any necessary attributes, the application is ready to
use the namespace. An application can request that the DNS clerk read
information stored with an object or list all the application's objects that
are stored in a particular directory. An application might also need to
resolve all soft links in a name in order to identify a target entry.

A-17

VMS Version 5.3 Features
A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

For example, the VAX Distributed File Service (DFS) is a layered
product that provides VMS users with the ability to use remote VMS
disks as if they were attached to their local VMS system. The DFS
application registers VMS directory structures (a directory and all of its
subdirectories) with DNS. Each DFS object registered in the namespace
names a particular file access point. DFS creates each object with a class
attribute of DFS$ACCESSPOINT and modifies the address attribute
(DNS$ADDRESS) of each object to hold the DECnet node address where
the directory structures reside. As a final step in registering its resources,
DFS creates a database to map DNS names to the appropriate VMS
directory structures.
Whenever the DFS application receives the following mount request, DFS
sends a request for information to the DNS clerk:
MOUNT ACCESS_POINT dns-name vms-logical-name

To read the address attribute of the access point object, the DFS
application performs the following procedures:
1

Translates the DNS name that is supplied through the user interface
to opaque format using the $DNS parse function

Reads the class attribute of the object with the $DNS read attribute
function, indicating that there will be a second call to read other
attributes of the object

Makes a second call to the $DNS service to read the address attribute
of the object

Sends the DNS name to the DFS server, which looks up the disk where
the access point is located

Verifies that the DNS name is valid on the DFS server

Then the DFS client and DFS server communicate to complete the mount
function.
A.2.7.1

Reading Objects
When requesting information from DNS, an application always takes an
object name from the user interface, translates the name into opaque
format, and passes it in an item list to the DNS clerk.

o
o

The following C program shows how an application reads an object
attribute. The $DNSW service uses an item list to return a set of objects.
Then, the application calls a run-time routine to read each value in the
set.
#include <dnsdef.h>
#include <dnsmsg.h>
/*
* Parameters:
*
opaque objname

*
*
*

*
*

A-18

obj_len
opaque attname
attname len

address of opaque full name for the object
containing the attribute to be read
length of opaque full name of the object
address of the opaque simple name of the
attribute to be read
length of opaque simple name of attribute

VMS Version 5.3 Features
A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

read_attribute (opaque_objname, obj len, opaque attname, attname len)
unsigned char *opaque_objname;
unsigned short obj_len;
unsigned char *opaque_attname;
unsigned short attname len;
{

struct $dnsb iosb;
char objtype = dns$k_object;

/* Used to determine DNS status */
/* Using object entries
*/

struct $dnsitmdef readitem[6]; /* Item list for system service */
struct dsc$descriptor set_dsc, value_dsc, newset_dsc, uid_dsc;
unsigned char attvalbuf[dns$k_maxattribute]; /* To hold the attribute */
/* values returned from extraction routine. */
unsigned char attsetbuf[dns$k_maxattribute]; /* To hold the set of
*/
/* attribute values after the return from $DNSW. */
unsigned char uidbuf[20];
/* Needed for context of multiple reads */
int read status;
int set status;
int xx;

/* Status of read attribute routine */

/* Status of remove value routine */
/* General variable used by print routine */

unsigned short setlen;
/* Contains current length of set structure */
unsigned short val len; /* Contains length of value extracted from set */
unsigned short uid_len;
/* Contains length of UID extracted from set */

/* Construct an item list to read values of the attribute. */
readitem[O] .dns$w_itm_code = dns$_entry;
readitem[O] .dns$w_itm_size = obj_len;
readitem[O] .dns$a_itm_address = opaque objname;

readitem[l] .dns$w_itm_code = dns$_lookingfor;
readitem[l] .dns$w_itm_size = sizeof(char);
readitem[l] .dns$a_itm_address = &objtype;
readitem[2] .dns$w_itm_code = dns$_attributename;
readitem[2] .dns$a_itm_address = opaque_attname;
readitem[2] .dns$w_itm_size = attname len;

readitem[3] .dns$w_itm_code = dns$_outvalset;
readitem[3] .dns$a_itm_ret length = &setlen;
readitem[3] .dns$w_itm_size = dns$k_maxattribute;
readitem[3] .dns$a itm_address = attsetbuf;
*( (int *)&readitem[4]) = 0;

do
{

read status = sys$dnsw(O, dns$ read_attribute,

&readitem, &iosb, 0, 0);

if(read_status == SS$_NORMAL)
{

read status
if ( (read_status

iosb.dns$l dnsb status;
SS$_NORMAL)

I I (read_status

DNS$_MOREDATA) )

{

set dsc.dsc$w_length = setlen;
set dsc.dsc$a_pointer = &attsetbuf[O]; /* Address of set */

value dsc.dsc$w length = dns$k simplenamemax;
value=dsc.dsc$a=pointer = attvalbuf;
/* Buffer to hold */
/* attribute value */
uid_dsc.dsc$w_length = 20;
uid_dsc.dsc$a_pointer = uidbuf; /* Buffer to hold value's UID*/

A-19

VMS Version 5.3 Features
A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

newset dsc.dsc$w length = dns$k maxattribute;
newset-dsc.dsc$a-pointer = &attsetbuf[O]; 1* Same buffer for *1
1* each call
*1
set status

dns$remove first set value(&set dsc, &value_dsc,
~al len, &;id_dsc,
&uid_len, &newset_dsc,
&setlen) ;

if(set status
{

== SS$ NORMAL)
-

readitem[4J .dns$w_itm_code = dns$_contextvartime;
readitem[4] .dns$w_itm_size = uid_len;
readitem[4] .dns$a_itm_address = uidbuf;

*((int *)&readitem[5])

printf("\tValue: ");
•
for (xx = 0; xx < val_len; xx++)
printf("%x ", attvalbuf[xx]);
printf("\n");
else if (set status != 0)
{

printf("Error %d returned when removing value from set\n",
set_status) ;
exit(set status);

while(set status
else
{

printf("Error reading attribute
exit (read_status) ;
while (read_status

%d\n",

read_status);

== DNS$_MOREDATA)i

o The item list contains five entries:

•

The opaque full name of the object with the attribute the program
wants to read

•

The type of namespace entry to access

•

The opaque simple name of the attribute to read

•

The address of the buffer containing the set of values returned by
the read operation

•

A zero to terminate the item list

The loop repeatedly calls the $DNSW service to read the values of
the attribute because the first call might not return all the values.
The loop executes until $DNSW returns something other than DNS$_
MOREDATA.

6) This loop extracts all values from the set returned by $DNSW, one
value at a time. This routine sets up descriptors for buffers that are
used by the DNS$REMOVE_FIRST_SET_VALUE routine to extract
values from the set. The loop executes until all values are extracted
from the set or it encounters an error.

A-20

(~\

VMS Version 5.3 Features

A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

e The DNS$REMOVE_FIRST_SET_VALUE routine extracts a value
from the set.

o This attribute name might be the context the routine uses to read
additional attributes. The attribute's DID, not its value, provides the
context.

o Finally, display the value in hexadecimal format. (You could also
take the attribute name and convert it to a printable format before
displaying the result.)
A.2.7.2

Listing Information
The list functions of $DNS allow applications to list the objects,
subdirectories, or soft links in a specific directory. Either the asterisk
(*) or question mark (?) wildcard, described in Section A.2.3.3, allows an
application to screen on the basis of its facility name.

The values DNS returns from read or enumerate functions are in different
structures. For example, an enumeration of objects returns different
structures than an enumeration of directories.

The following C program shows how an application can read the objects
in a directory with the $DNS system service. It demonstrates how you
parse any set that the enumerate objects function returns with a run-time
routine in order to remove the first entry from the set. The example also
demonstrates how the program takes each value from the set.
#include <dnsdef.h>
#include <dnsmsg.h>

* Parameters:
*

fname_p
fname len

opaque full name of the directory to enumerate
length of full name of the directory

struct $dnsitmdef enumitem[4];
/* Item list for enumeration */
unsigned char setbuf[lOO];
/* Values from enumeration */
/* DNS status information */
struct $dnsb enum_iosb;
int synch_event;
/* Used for synchronous AST threads */
unsigned short setlen;
/* Length of output in setbuf */
enumerate_objects (fname_p,
unsigned char *fname_p;
unsigned short fname len;

fname_len)

{

int enumerate_objects_ast();
int status;
int enum_status;

/* General routine status */
/* Status of enumeration routine */

/* Set up item list */
enumitem[O] .dns$w_itm_code = dns$_directory;
enumitem[O] .dns$w_itm_size = fname_len;
enumitem[O] .dns$a_itm_address = fname_p;

enumitem[l] .dns$w_itm_code = dns$_outobjects;
enumitem[l] .dns$a_itm_ret_length = &setlen;
enumitem[l] .dns$w_itm_size = 100;
enumitem[l] .dns$a_itm_address = setbuf;
*((int *)&enumitem[2])

/* Opaque directory name */

/* output buffer */

= 0; /* Zero terminate item list */

A-21

VMS Version 5.3 Features
A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

status

lib$get ef(&synch_event);

t»

if(status != SS$_NORMAL)
{

printf("Could not get event flag to synch AST threads\n");
exit (status) ;
enum status = sys$dns(O, dns$_enumerate objects, &enumitem,
~
&enum_iosb, enumerate_objects ast, setbuf);
if(enum_status != SS$_NORMAL)

{

printf("Error enumerating objects
exit(enum_status);
status

%d\n", enum_status);

sys$synch(synch_event, &enum_iosb);

if(status != SS$_NORMAL)
{

printf("S ync hronization with AST threads failed\n");
exit(status);

/* AST routine parameter:
*/
/*
outbuf : address of buffer that contains enumerated names. */

unsigned char objnamebuf[dns$k simplenamemax]; /* Opaque object name */
enumerate_objects_ast(outbuf)
unsigned char *outbuf;
{

struct $dnsitmdef cvtitem[3];
/* Item list for class name */
struct $dnsb iosb;
/* Used for name service status information */
struct dsc$descriptor set dsc, value dsc, newset dsc;
unsigned char simplebuf[dns$k simplestrmax];
int enum_status;
int status;
int set status;

/* Object name string */

/* The status of the enumeration itself */
/* Used for checking immediate status returns */
/* Status of remove value routine */

unsigned short val len;
unsigned short sname len;

/* Length of set value */
/* Length of object name */

enum_status = enum_iosb.dns$l_dnsb_status;
/* Check status */
if((enum_status != SS$_NORMAL) && (enum_status != DNS$_MOREDATA))
{

printf("Error enumerating objects
sys$setef(synch_event) ;
exit(enum_status);

%d\n", enum_status);

do
{

/*
* Extract object names from output buffer one
* value at a time.
Set up descriptors for the extraction.
*/
set_dsc.dsc$w_length = setlen;
/* Contains address of */
set dsc.dsc$a_pointer = setbuf;
/* the set whose values */
/* are to be extracted */

A-22

VMS Version 5.3 Features

A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

value dsc.dsc$w length = dns$k simplenamemax;
value-dsc.dsc$a-pointer = objn~mebuf; /* To contain the */
/* name of an object */
/* after the extraction */
newset_dsc.dsc$w_Iength = 100;
newset_dsc.dsc$a_pointer = setbuf;

/* To contain a new */
/* set structure after */
/* the extraction. */

/* Call RTL routine to extract the value from the set */
set status = dns$remove first set_value (&set_dsc, &value_dsc, &val_Ien,
0, 0, &newset dsc, &setlen);
if(set status

SS$_NORMAL)

{

cvtitem[O] .dns$w_itm_code
dns$ fromsimplename;
cvtitem[O] .dns$w_itm_size
val_len;
cvtitem[O] .dns$a itm_address = objnamebuf;
cvtitem[l] .dns$w_itm_code = dns$_tostringname;
cvtitem[l] .dns$w_itm_size = dns$k_simplestrmax;
cvtitem[l] .dns$a_itm_address = simplebuf;
cvtitem[l] .dns$a_itm_ret length
&sname len;
*«int *)&cvtitem[2]) = 0;
status = sys$dnsw(O, dns$ simple opaque to string, &cvtitem,
&iosb, 0, 0);

if(status == SS$_NORMAL)
status = iosb.dns$l_dnsb_status;
if(status != SS$_NORMAL)

/* Check for errors */

/* If error, terminate processing */

{

printf("Converting object name to string returned %d\n",
status) ;
exit(status);
else
simplebuf[sname_len] = 0;
printf ("%s\n", simplebuf);

/* Null terminate for printing */

enumitem[2] .dns$w_itm_code = dns$ contextvarname;
enumitem[2] .dns$w_itm_size = val_len;
enumitem[2] .dns$a_it~address = objnamebuf;
*( (int *)&enumitem[3])

else if (set status != 0)
{

printf("Error %d returned when removing value from set\n",
set_status);
exit(set status);
while(set status
if(enum_status

== SS$_NORMAL);

== DNS$_MOREDATA)

CD
enum status

sys$dns(O, dns$ enumerate objects, &enumitem,
&enum_iosb, enumerate objects ast, setbuf);

A-23

VMS Version 5.3 Features
A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

if(enum_status != SS$_NORMAL)

/* Check status of $DNS */

{

printf("Error enumerating objects
sys$setef(synch_event);

= %d\n", enum_status);

else
sys$setef(synch_event);

o Get an event flag to synchronize the execution of AST threads.
8 Use the system service to enumerate the object names.
@) Check the status of system service itself before waiting for threads.

e Use the $SYNCH call to make sure the DNS clerk has completed and
that all threads have finished executing.
•

After enumerating objects, $DNS calls an AST routine. The routine
shows how DNS$REMOVE_FIRST_SET_VALUE extracts object names
from the set returned by the DNS$_ENUMERATE_OBJECTS function.

o Use an item list to convert the opaque simple name to a string name
so you can display it to the user. The item list contains the following
entries:

•

The address of the opaque simple name to be converted

•

The address of the buffer that will hold the string name

•

A zero to terminate the item list

This object name could provide the context for continuing the
enumeration. Append the context variable to the item list so the
enumeration can continue from this name if there is more data.

(i) Use the system service to enumerate the object names as long as there

is more data.
•
A.2. 7.3

C___\I

Set the event flag to indicate that all AST threads have completed and
the program can terminate.

How the Clerk Locates Data
When the DNS clerk receives an application's call for service, it tries to
find a DNS server that can process the request.

Often, the DNS clerk does not know which DNS server holds the object
information. To find an unknown server, the clerk looks in its own
cache first. The clerk cache holds namespace information gathered from
servicing earlier application requests. If the clerk cache does not list the
needed server, then the DNS clerk requests information from a local DNS
server in its cache. (A clerk always knows about at least one DNS server
because this information is loaded at system startup.)
The clerk's last recourse is to trace directory pointers through the
namespace. Any DNS server is capable of telling the clerk about another
DNS server holding other directories in the namespace hierarchy. The
clerk follows directory pointers until it finds a DNS server holding the
A-24

VMS Version 5.3 Features

A.2 VMS Version 5.3 Support for the VMS Distributed Name Service

specified directory. If the clerk cannot find the specified directory, then it
follows directory pointers up to the root directory. Once the root directory
is found, the clerk traces directory pointers away from the root, until it
finds a DNS server that has the directory holding the requested object.
Once the clerk finds a directory that holds the required information, it
delivers the request to the DNS server. As soon as the clerk receives a
response, it transmits the result to the application.

A.2.B

DNS System Services
The Distributed Name Service Clerk system services are the programming
interface to the VAX Distributed Name Service facility. The DNS Clerk
system services allow an application to register a resource in a distributed
database and then access the resource from any point in the network by
a single name. There are two system service calls to the clerk that are
described in this section.

•

$DNS (Distributed Name Service Clerk)

•

$DNSW (Distributed Name Service Clerk and Wait)

The $DNS system service is the asynchronous client interface for
applications using the Distributed Name Service. The $DNSW system
service is the synchronous client interface.

c
A-25

DNS Clerk System Service Calls

$DNS

Distributed Name Service Clerk
The Distributed Name Service Clerk service registers a resource in a
distributed database. The SONS service completes asynchronously; that
is, it returns to the client immediately after making a name service call. The
status returned to the client call indicates whether a request was successfully
queued to the name service.
Note that the Distributed Name Service Clerk and Wait ($ONSW) call is the
synchronous equivalent of SONS. $DNSW is identical to SONS in every way
except that $DNSW returns to the caller after the operation completes.

FORMAT

SVS$DNS

RETURNS

VMS usage:
type:
access:
mechanism:

[etnj ,tunc ,itm/st ,[dnsbj ,[astadrj ,[astprmj

cond_value
longword (unsigned)
write only
by value

Longword condition value. All system services return by immediate value
a condition value in RO. Condition values returned by this call are listed
in the section Condition Values Returned. Errors returned here are from
the DNS clerk. Refer to the dnsb argument for errors returned by the
name service.

ARGUMENTS

0-\,.'

etn
VMS usage:
type:
access:
mechanism:

ef_number
longword (unsigned)
read only
by value

Number of the event flag to be set when $DNS completes. The efn
argument is a longword containing this number. The efn argument is
optional; if not specified, event flag 0 is set.
When $DNS begins execution, it clears the event flag. Even if the service
encounters an error and completes without queuing a name service
request, the specified event flag is set.

tunc
VMS usage:
type:
access:
mechanism:

function_code
longword (unsigned)
read only
by value

Function code specifying the action that $DNS is to perform. The fune
argument is a longword containing this function code.

A-26

0'
.-

DNS Clerk System Service Calls

$DNS

A single call to $DNS can specify one function code. Most function codes
require or allow for additional information to be passed in the call with the
itmlst argument.

$DNS Function Codes
DNS$_CREATE_OBJECT
This request creates an object in the namespace. Initially, the entry
has the attributes of DNS$UID, DNS$UTS, DNS$CLASS, DNS$ACS,
and DNS$CLASSVERSION. The name service creates the DNS$UID,
DNS$UTS, and DNS$ACS attributes. The client application supplies
the DNS$CLASS and DNS$CLASSVERSION attributes. You can add
additional attributes using the DNS$_MODIFY_ATTRIBUTE function.

The DNS clerk cannot guarantee that an object has been created. Another
DNS$_CREATE_OBJECT request could supersede the object created by
your call. To verify an object creation, wait until the directory is skulked
and then check to see if the requested object entry is present. If the value
of the directory's DNS$ALLUPTO attribute is greater than the UID of the
object entry, your object entry has been successfully created.
Creating an object in the namespace requires write access to the directory
in which the object will reside.

If specified, DNS$_OUTUID holds the UID of the created object.
You must specify the following item codes:
DNS$_CLASS (Class_Name)
DNS$_OBJECTNAME (Opaque_Full_Name)
DNS$_VERSION (Class_Version)
You can specify the following input item codes:
DNS$_CONF
DNS$_WAIT

You can specify the following output item code:
DNS$OUTUID (UID)
$DNS returns the following:
SS$_NORMAL
DNS$_ENTRYEXISTS
DNS$_INVALID_OBJECTNAME
DNS$_INVALID_CLASSNAME
Any condition listed in the section Condition Values Returned.
$DNS returns the following qualifying status:
DNS$V_DNSB_OUTLINKED

DNS$_DELETE_OBJECT

This request removes the specified object from the namespace. The
function requires delete access to the object in question.
You must specify the following input item code:
DNS$_OBJECTNAME (Opaque_Full_Narne)

A-27

DNS Clerk System Service Calls

$DNS

You can specify the following input item codes:
DNS$_CONF
DNS$_WAIT
$DNS returns the following:
SS$_NORMAL
DNS$_INVALID_OBJECTNAME
Any condition listed in the section Condition Values Returned.
$DNS returns the following qualifying status:
DNS$V_DNSB_OUTLINKED
DNS$_ENUMERATE_ATTRIBUTES

This request returns a set of attributes in DNS$_OUTATTRIBUTESET
that is associated with the entry. The entry type is specified in the DNS$_
LOOKINGFOR entry.
To manipulate the values returned by this call, use the DNS$REMOVE_
FIRST_SET_VALUE run-time routine. The values returned are the
Enum_Att_Name structure, which is described in Table A-l.
You must have read access to the entry to enumerate its attributes.
The DNS clerk enumerates attributes in alphabetical order. A return
status of DNS$_MOREDATA implies that not all attributes have
been enumerated. You should make further calls, setting DNS$_
CONTEXTVARNAME to the last attribute in the set returned, until
the procedure returns SS$_NORMAL.

. ~-

You must specify the following input item codes:
DNS$_ENTRY (Opaque_Full_Name)
DNS$_LOOKINGFOR (Entry_Type)
You must specify the following output item code:
DNS$_OUTATTRIBUTESET (set of Enum_Att_Name)

( . J\

You can specify any of the following input item codes:
DNS$_CONF
DNS$_CONTEXTVARNAME (Opaque_Simple_Name)
DNS$_WAIT
$DNS can return the following:
SS$_NORMAL
DNS$_MOREDATA
DNS$_INVALID_ENTRYNAME
DNS$_INVALID_CONTEXTNAME
Any condition listed in the section Condition Values Returned.
$DNS returns the following qualifying status:
DNS$V_DNSB_OUTLINKED

A-28

DNS Clerk System Service Calls

$DNS

DNS$_ENUMERATE_CHILDREN

This request takes as input a directory name with an optional simple
name that uses a wildcard. The DNS clerk matches the input against
child directory entries in the specified directory.
The DNS clerk returns a set of simple names of child directories in the
target directory that match the name with the wildcard. A null set is
returned when there is no match or when the directory has no children.
To manipulate the values returned by this call, use the DNS$REMOVE_
FIRST_SET_VALUE run-time routine. The value returned is a simple
name.
The function requires read access to the parent directory.

The child directories are enumerated in alphabetical order. If the call
returns DNS$_MOREDATA, not all children have been enumerated and
the client should make further calls, setting DNS$_CONTEXTVARNAME
to the last child directory in the set returned, until the procedure returns
SS$_NORMAL. Subsequent calls return the child directories, starting with
the directory specified in DNS$_CONTEXTVARNAME and continuing in
alphabetical order.
You must specify the following input item code:

DNS$_DIRECTORY (Opaque_Full_Name)
You must specify the following output item code:
DNS$_OUTCHILDREN (set of Opaque_Simple_Name)
You can specify the following input item codes:
DNS$_CONF
DNS$_CONTEXTVARNAME (Opaque_Simple_Name)
DNS$_WAIT
DNS$_WILDCARD (Opaque_Simple_Name)

$DNS returns the following:
SS$_NORMAL
DNS$_MOREDATA
DNS$_INVALID_DIRECTORYNAME
DNS$_INVALID_CONTEXTNAME
DNS$_INVALID_WILDCARDNAME
You might receive the following qualifying status:
DNS$V_DNSB_OUTLINKED
DNS$_ENUMERATE_OBJECTS

This request takes as input the directory name, a simple name that uses a
wildcard, and a class name that uses a wildcard. The DNS clerk matches
these against objects in the directory. If a wildcard and class filter are not
specified, then all objects in the directory are returned.
The function returns (in DNS$_OUTOBJECTS) a set of simple names
of objects in the directory that match the name with the wildcard. If no
objects match the wildcard or the directory contains no objects, a null
set is returned. The DNS clerk returns DNS$V_DNSB_OUTLINKED
A-29

DNS Clerk System Service Calls

$DNS

qualifying status if it encounters one or more soft links in resolving the
names of object entries to be enumerated.
To manipulate the values returned by this call, use the DNS$REMOVE_
FIRST_SET_VALUE run-time routine. The value returned is a simple
name structure.
This function requires read access to the parent directory.
The objects are enumerated in alphabetical order. If the call returns
DNS$_MOREDATA, not all objects have been enumerated and the client
should make further calls, setting DNS$_CONTEXTVARNAME to the last
object in the set returned, until the procedure returns SS$_NORMAL. If
the class filter is specified, only those objects of the specified classes are
returned.
You must specify the following input item code:
DNS$_DIRECTORY (Opaque_Full_Name)
You must specify the following output item code:
DNS$_OUTOBJECTS (set of Opaque_Simple_Names)
You can specify any of the following input item codes:
DNS$_WILDCARD (Opaque_Simple_Name)
DNS$_CLASSFILTER (Opaque_Simple_Name)
DNS$_CONTEXTVARNAME (Opaque_Simple_Name)
DNS$_CONF
DNS$_WAIT

$DNS returns the following:
SS$_NORMAL
DNS$_MOREDATA
DNS$_INVALID_DIRECTORYNAME
DNS$_INVALID_CONTEXTNAME
DNS$_INVALID_WILD CARD NAME
DNS$_INVALID_CLASSNAME

You might receive the following qualifying status:
DNS$V_DNSB_OUTLINKED
DNS$_ENUMERATE_SOFTLINKS

This request takes as input the name of a directory and a wildcarded
simple name. The DNS clerk matches these against soft links in the
directory. It returns (in DNS$_OUTSOFTLINKS) a set consisting of
simple names of soft links in the directory that match the wildcarded
name. If no soft link entries match the wildcard or the directory contains
no soft links, a null set is returned.
If no wildcard is specified, then all soft links in the directory are returned.

To manipulate the values returned by this call, use the DNS$REMOVE_
FIRST_SET_VALUE run-time routine. The value returned is a simple
name.
This function requires read access to the parent directory.

A-30

DNS Clerk System Service Calls
SONS

The soft links are enumerated in alphabetical order. If the call returns
DNS$_MOREDATA, not all matching soft links have been enumerated and
the client should make further calls, setting DNS$_CONTEXTVARNAME
to the last soft link in the set returned, until the procedure returns SS$_
NORMAL.
You must specify the following input item code:
DNS$_DIRECTORY (Opaque_Full_N arne)
You must specify the following output item code:
DNS$_OUTSOFTLINKS (set of Opaque_Simple_Name)

You can specify the following input item codes:
DNS$_WILDCARD (Opaque_Simple_Name)
DNS$_CONTEXTVARNAME (Opaque_Simple_Name)
DNS$_CONF
DNS$_WAIT
$DNS returns the following:

SS$_NORMAL
DNS$_INVALID_DIRECTORYNAME
DNS$_INVALID_CONTEXTNAME
DNS$_INVALID_WILDCARD NAME
You might receive the following qualifying status:
DNS$V_DNSB_OUTLINKED
DNS$_FULL_OPAQUE_TO_STRING

This request converts a full name in opaque format to its equivalent in
string format, as described in Section A.2.2.4. Setting the byte referred to
by DNS$_SUPPRESS_NSNAME to 1 prevents the namespace name from
being included in the string name.
You must specify the following item codes:
DNS$_FROMFULLNAME (Opaque_FuILName)
DNS$_TOSTRINGNAME (FuILN ame_Str)
You can specify the following input item code:
DNS$_SUPPRESS_NSNAME (byte)
$DNS returns the following:
SS$_NORMAL
DNS$_INVALIDNAME
You do not receive qualifying status.

DNS$_MODIFY_ATTRIBUTE

This request applies one update to the specified entry in the namespace.
You can add or remove an attribute; you can add or remove a value from
either a single-value attribute or a set-valued attribute.

A-31

DNS Clerk System Service Calls
$DNS

c
This operation requires write or delete access to the entry whose attribute
is being modified, depending on whether the operation adds or removes
the attribute.
When adding a value to a single-value attribute, include a value in DNS$_
MODVALUE or you will receive the error DNS$_INVALIDUPDATE. The
item code DNS$_MODVALUE is not required when writing to an attribute
set because the name service creates the attribute if no value is provided.
In a delete operation, include the DNS$_MODVALUE item code to remove
a certain value from an attribute set. Unless you specify the item code,
the name service removes the attribute and all its values from the entry.
You must specify the following item codes:
DNS$_ENTRY (Opaque_Full_Name)
DNS$_LOOKINGFOR (Entry_Type)
DNS$_MODOPERATION (DNS$K_PRESENT or DNS$K_ABSENT)
DNS$_ATTRIBUTETYPE (DNS$K_SET or DNS$K_SINGLE)
DNS$_ATTRIBUTENAME (Opaque_Simple_Name)

~\
~;;//

You can specify the following input item codes:
DNS$_CONF
DNS$_MODVALUE
DNS$_WAIT
$DNS returns the following:
SS$_NORMAL
DNS$_WRONGATTRIBUTETYPE
DNS$_INVALIDUPDATE
DNS$_INVALID_ENTRYNAME
DNS$_INVALID_ATTRIBUTENAME

You might receive the following qualifying status:
DNS$V_DNSB_OUTLINKED
DNS$_PARSE_FULLNAME_STRING

This request takes a full name in string format and converts it to
its equivalent in opaque format. If DNS$_NEXTCHAR_PTR is used,
the longword referenced by this entry contains the address of the
character immediately following the DNS name given in DNS$_
FROMSTRINGNAME.
You must specify the following item codes:
DNS$_FROMSTRINGNAME (Full_Name_Str)
DNS$_TOFULLNAME (Opaque_Full_Name)
You can specify the following input item code:
DNS$_NEXTCHAR_PTR
$DNS can return the following:
SS$_NORMAL
DNS$_INVALIDNAME
You do not receive qualifying status.
A-32

DNS Clerk System Service Calls

$DNS

DNS$_PARSE_SIMPLENAME_STRING

This request takes a simple name in string format and converts it
to its equivalent in opaque format. If DNS$_NEXTCHAR_PTR is
used, the longword referenced by this entry contains the address of
the character immediately following the DNS name given in DNS$_
FROMSTRINGNAME.
You must specify the following item codes:
DNS$_FROMSTRINGNAME (Simple_Name_Str)
DNS$_TOFULLNAME (Opaque_Simple_Name)
You can specify the following input item code:

DNS$_NEXTCHAR_PTR
$DNS can return the following:
SS$_NORMAL
DNS$_INVALIDNAME
You do not receive qualifying status.
DNS$_READ_ATTRIBUTE

This request returns (in DNS$_OUTVALSET) a set whose members
are the values of the specified attribute. When the request completes
successfully, the qualifying status indicates whether soft links were
followed in resolving the name.
This function requires read access to the object whose attribute is to be
read.

To manipulate the values returned by this call, use the DNS$REMOVE_
FIRST_SET_VALUE run-time routine. The contents of DNS$_
OUTVALSET are passed to DNS$REMOVE_FIRST_SET_VALUE, and
the routine returns the value of the attribute.
The attribute values are returned in the order they were received.
If the call returns DNS$_MOREDATA, not all values have been
returned. The client application can make further calls, setting DNS$_
CONTEXTVARTIME to the time-stamping of the last attribute in the set
returned, until the procedure returns SS$_NORMAL. If the client sets
the DNS$_MAYBEMORE argument to 1, the name service attempts to
make subsequent DNS$_READ_ATTRIBUTE calls for the same entry
more efficient. The client may set this argument to true on any call, but
performance improves only if the client accesses no other entry before
making a read attribute call for the previous entry.
You must include the following input item codes:
DNS$_ENTRY (Opaque_Full_Narne)
DNS$_LOOKINGFOR (Entry_Type)
DNS$_ATTRIBUTENAME COpaque_Simple_Name)

You must include the following output item code:
DNS$_OUTVALSET (set of values)
You can include the following input item codes:
DNS$_MAYBEMORE (Boolean)

A-33

DNS Clerk System Service Calls

$DNS

DNS$_CONTEXTVARTIME (DID)
DNS$_CONF
DNS$_WAIT
$DNS returns the following:
SS$_NORMAL
DNS$_MOREDATA
DNS$_INVALID_ENTRYNAME
DNS$_INVALID_ATTRIBUTENAME
You might receive the following qualifying status:
DNS$V_DNSB_OUTLINKED
DNS$_RESOLVE_NAME

This request follows a chain of soft links to its destination, returning the
full name of that entry so that future calls by the client application can
use the entry name without incurring the overhead of following the link.
This function requires read access to each of the soft links in the chain.
Applications that maintain their own databases of opaque DNS names
should use DNS$_RESOLVE_NAME any time they receive the qualifying
status DNS$V_DNSB_OUTLINKED. This status indicates a need to
update the current name, using the soft link facility of DNS. Use the
original name with DNS$_RESOLVE_NAME and store the result in the
application database.

0 .~
'..

If the application provides a name that does not contain any soft links,
DNS$_NOTLINKED status is returned. If the target of any of the chain
of soft links followed does not exist, the DNS$_DANGLINGLINK status is
returned. To obtain the target of any particular soft link, use the DNS$_
READ_ATTRIBUTE function with DNS$_LOOKINGFOR set to DNS$K_
SOFTLINK and request the attribute DNS$LINKTARGET. This can be
useful in discovering which link in a chain is "broken." If the DNS clerk
detects a loop, it returns DNS$_POSSIBLECYCLE status.

You must specify the following input item code:

DNS$_LINKNAME (Opaque_Full_Narne)
You must specify the following output item code:
DNS$_OUTNAME (Opaque_Full_Name)
You can specify the following input item codes:
DNS$_CONF
DNS$_WAIT
$DNS returns the following:
SS$_NORMAL
DNS$_INVALID_LINKNAME
DNS$_NOTLINKED
You might receive the following qualifying status:
DNS$V_DNSB_OUTLINKED

A-34

DNS Clerk System Service Calls

$DNS

DNS$_SIMPLE_OPAQUE_TO_STRING

This request takes a simple name in opaque format and converts it to its
equivalent in string format, as described in Section A.2.2.4.
You must specify the following item codes:
DNS$_FROMSIMPLENAME (Opaque_Simple_Name)
DNS$_TOSTRINGNAME (Simple_N ame_Str)
$DNS returns the following:
SS$_NORMAL
DNS$_INVALIDNAME

You do not receive qualifying status.
DNS$_TEST_ATTRIBUTE

This request returns DNS$_TRUE if the specified attribute has one of the
following characteristics:
•

It is a single-value attribute and its value matches the client-specified

value.
•

It is a set-valued attribute and the attribute contains the client-

specified value as one of its members.
On successful completion of the function, DNS$V_DNSB_OUTLINKED
indicates whether soft links were followed in resolving the name.
This function requires test or read access to the entry whose attribute is to
be tested.
If the attribute is not present in the entry or if the requested attribute

does not exist, the function returns
DNS$_FALSE.

You must specify the following item codes:
DNS$_ENTRY (Opaque_FulLName)
DNS$_LOOKINGFOR (Entry_Type)
DNS$~TTRIBUTENAME (Opaque_Simple_Name)
DNS$_VALUE (value)
You can specify the following input item codes:
DNS$_CONF
DNS$_WAIT
$DNS returns the following when the call is successful:
DNS$_TRUE
DNS$_FALSE
$DNS returns the following when the call is unsuccessful:

DNS$_INVALID_ENTRYNAME
DNS$_INVALID_ATTRIBUTENAME
You might receive the following qualifying status:
DNS$V_DNSB_OUTLINKED

A-35

DNS Clerk System Service Calls

$DNS

DNS$_TEST_GROUP
This request tests for group membership. It returns DNS$_TRUE if
the specified member is a member of the specified group (or a subgroup
thereof), and DNS$_FALSE otherwise. If a recursive search is required
and one or more of the subgroups is unavailable, the status encountered in
trying to access that group is returned.

The DNS$_INOUTDIRECT argument, on input, controls the scope of the
search. If set to true, the only group considered is the top level group
specified by the group argument. If set to false, recursive evaluation is
performed. On output, the DNS$_INOUTDIRECT argument is set to 1 if
the member was found in the top level group; otherwise it is set t() O.
You must specify the following item codes:
DNS$_GROUP (Opaque_Full_Name)
DNS$_MEMBER (Opaque_FuII_Name)
You can specify the following input item codes:
DNS$_CONF
DNS$_INOUTDIRECT (Boolean)
DNS$_WAIT
$DNS returns the following:
SS$_NORMAL
DNS$_NOTAGROUP
DNS$_INVALID_GROUPNAME
DNS$_INVALID_MEMBERNAME

You might receive the following qualifying status:
DNS$V_DNSB_INOUTDIRECT

itm/st
VMS usage:
type:
access:
mechanism:

item_list_3
longword (unsigned)
read only
by reference

Item list supplying information to be used in performing the function
specified by the fune argument. The itmlst argument is the address
of the item list. The item list consists of one or more item descriptors,
each of which is three longwords. The descriptors can be in any order
in the item list. Each item descriptor specifies an item code. Each Item
code either describes the specific information to be returned by $DNS or
otherwise affects the action designated by the function code. The item list
is terminated by a longword of zero.

o
A-36

DNS Clerk System Service Calls

$DNS

The item list is a standard VMS format item list. The following figure
depicts the general structure of an item descriptor:

Item Code

Buffer Length

Buffer Address
Return Length Address
ZK-1705-GE

$DNS Item Descriptor Fields
item code

A word containing a symbolic code describing the nature of the information
currently in the buffer or to be returned in the buffer. The location of the
buffer is pointed to by the buffer address field. Each item code has a
symbolic name; these symbolic names are defined by the $DNS macro and
have the format DNS$_code.

buffer length

A word specifying the length of the buffer; the buffer either supplies
information to be used by $DNS or receives information from $DNS. The
required length of the buffer varies depending on the item code specified;
each item code description specifies the required length.
buffer address

A longword containing the address of the buffer that specifies or receives
the information.

return length address

A longword containing the address of a word specifying the actual length
in bytes of the information returned by $DNS. The information resides in
a buffer identified by the buffer address field. The field applies to output
item list entries only and must be zero for input entries. If the return
length address is 0, it is ignored.
$DNS Item Codes
DNS$_ATTRIBUTETVPE

The DNS$_ATTRIBUTETYPE item code specifies whether an attribute
is set valued (DNS$K_SET) with a value of 3 or single valued (DNS$K_
SINGLE) with a value of 2.
DNS$_ATTRIBUTENAME

The DNS$_ATTRIBUTENAME item code specifies the opaque simple
name of an attribute. An attribute name cannot be longer than
31 characters.
DNS$_CLASS

The DNS$_CLASS item code specifies the class of an object for the $DNS
function DNS$_CREATE_OBJECT. DNS$_CLASS is an opaque simple
name.

A-37

DNS Clerk System Service Calls

$DNS

DNS$_CLASSFILTER

DNS$_CLASSFILTERis used by the $DNS function DNS$_
ENUMERATE_OBJECTS to limit the scope of the enumeration to those
objects belonging to a certain class (or, if a wildcard name is used, a group
of classes). DNS$_CLASSFILTER is an opaque simple name, which can
use a wildcard.
DNS$_CLASSFILTER is optional. A wildc:ard simple name of * is used by
default, meaning that objects of all classes will be enumerated.
DNS$_CONF

DNS$_CONF specifies for $DNS the level of importance in returning upto-date information. DNS$_CONF is 1 byte long and can take one of the
following values:
Confidence Level

Value

Description

Service the DNS clerk request at the lowest
cost, usually from cached information.
2

Bypass any cached information and obtain the
data directly from a name server.

Service the request from a master directory.

The entry is optional; if it is not specified, the DNS clerk assumes a value
of DNS$K_LOW.

C'
--"J
'

DNS$_CONTEXTVARNAME

DNS$_CONTEXTVARNAME is used by the enumeration functions of
$DNS to specify a context from which the enumeration is to begin. The
item is an opaque simple name.
DNS$_CONTEXTVARNAME is optional. If not given, the enumeration
begins with the first element.
DNS$_DIRECTORY

DNS$_DIRECTORY is used by most of the enumeration functions of
$DNS to specify the namespace directory in which the elements of the
enumeration are to be found. DNS$_DIRECTORY is an opaque full name.

DNS$_ENTRY

DNS$_ENTRY specifies for $DNS the opaque full name of a namespace
entry (object, soft link, directory, clearinghouse).
DNS$_FROMFULLNAME

DNS$_FROMFULLNAME specifies for the DNS$_FULL_OPAQUE_TO_
STRING function the opaque full name that is to be converted into string
format.
DNS$_FROMSIMPLENAME

DNS$_FROMSIMPLENAME specifies for the DNS$_SIMPLE_OPAQUE_
TO_STRING function the opaque simple name that is to be converted into
string f o r m a t . . '

A-3S

DNS Clerk System Service Calls

SONS
DNS$_FROMSTRINGNAME

DNS$_FROMSTRINGNAME specifies a name in string format for the
parse functions DNS$_PARSE_FULLNAME_STRING and DNS$_PARSE_
SIMPLENAME_STRING that is to be converted to opaque format.
DNS$_GROUP

DNS$_GROUP specifies for the DNS$_TEST_GROUP function the opaque
full name of the group that is to be tested. DNS$_GROUP must be the
name of a group object.
DNS$_INOUTDIRECT

DNS$_INOUTDIRECT is a Boolean value that serves two different
purposes for the DNS$_TEST_GROUP function. On input, DNS$_
INOUTDIRECT controls the scope of the search for the test, as follows:
Value

Definition

The only group to be tested is the top level group specified by the DNS$_
GROUP item.

All subgroups of the group named in DNS$_GROUP are tested for inclusion.
A subgroup is any member that is a group in itself.

On output, DNS$_INOUTDIRECT is set to indicate whether the members
were found in the top level group or were found as members of one of the
subgroups, as follows:
Value

Definition

The member was found in the top level group.

The member was found in one of the subgroups of the top level group.

DNS$_INOUTDIRECT is a single-byte value.
DNS$_LlNKNAME

DNS$_LINKNAME specifies the opaque full name of a soft link.
DNS$_LOOKINGFOR

DNS$_LOOKINGFOR specifies the type of entry on which the call is to
operate. DNS$_LOOKINGFOR, which is encoded as a byte, can take one
of the following values:
Type of Entry

Value

DNS$K_DIRECTORY

DNS$K_OBJECT

DNS$K_CHILDDIRECTORY

DNS$K_SOFTLINK

DNS$K_CLEARINGHOUSE

A-39

DNS Clerk System Service Calls
$DNS

n
V
DNS$_MAYBEMORE

DNS$_MAYBEMORE is used with the DNS$_READ _ATTRIBUTE function
to indicate that the results of the read operation are to be cached. This is
a single-byte item.
When this item is set to 1, the name service returns as much information
about the attributes for the entry as it is able to fit in the return buffer.
All of this information is cached to make later lookups of attribute
information for the entry quicker and more efficient.
If this item is not supplied, then only the requested information for the
entry is returned.
DNS$_MEMBER

DNS$_MEMBER specifies for the DNS$_TEST_GROUP function of $DNS
the opaque full name of a member that is to be tested for inclusion within
a given group.
DNS$_MODOPERATION

DNS$_MODOPERATION specifies for the DNS$_MODIFY_ATTRIBUTE
function the type of operation that is to take place. There are two types of
modifications: adding an attribute (DNS$K_PRESENT), which has a value
of 1, or deleting an attribute (DNS$K_ABSENT), which has a value of O.
The name service adds an attribute in the following way:
•

For an existing attribute where an attribute value is given, the value
is added to a set-valued attribute and all other values for the set are
unaffected. The value replaces any previous value in a single-value
attribute.

•

For an existing attribute where an attribute value is not given, all
previous values for the attribute are unaffected.

•

For a new attribute
Where an attribute is given, the attribute is created and given
the attribute type of DNS$K_SET or DNS$K_SINGLE as supplied
with the DNS$K_ATTRIBUTETYPE item. The value is assigned
to the attribute.

"_,

\.)
~-

Where an attribute value is not given, a set-valued attribute is
created without a value assignment, but a single-value attribute is
not created.
The name service deletes an attribute in the following way:
•

If the attribute exists and an attribute value is given, the attribute
value is removed from a set-valued attribute. All other values are
unaffected. For a single-value attribute, the attribute (along with its
value) is removed from the entry.

•

If an attribute value is not given, then the attribute and all values of
the attribute are removed. This is true for both set-valued attributes
and single-value attributes.

DNS$_MODVALUE

DNS$_MODVALUE specifies for the DNS$_MODIFY_ATTRIBUTE
function the value that is to be added to or deleted from an attribute.
The structure of this value is dependent on the application.

A-40

DNS Clerk System Service Calls

$DNS

DNS$_MODVALUE is an optional argument that affects the overall
operation of the DNS$_MODIFY_ATTRIBUTE function. (See the DNS$_
MODOPERATION item code description for more information.)
DNS$_NEXTCHAR_PTR

DNS$_NEXTCHAR_PTR is an optional item code that can be used with
the parse functions DNS$_PARSE_FULLNAME_STRING and DNS$_
PARSE_SIMPLENAME_STRING to return the address of the character
that immediately follows a valid DNS name. This option is most useful
when applications are parsing command line strings.
Without this item code, the parse functions return an error if any portion
of the name string is invalid.
DNS$_OBJECTNAME

DNS$_OBJECTNAME specifies the opaque full name of an object.
DNS$_OUTATTRIBUTESET

DNS$_OUTATTRIBUTESET specifies to the DNS$_ENUMERATE_
ATTRIBUTES function the address of a buffer that is to contain the
set of enumerated attribute names.

The names returned in this set can be extracted from the buffer with
the DNS$REMOVE_FIRST_SET_VALUE routine. The resulting values
are contained in the $DNSATTRSPECDEF structure, a byte indicating
whether an attribute is set-value or single-value followed by an opaque
simple name.
DNS$_OUTNAME

DNS$_OUTNAME specifies for the DNS$_RESOLVE_NAME function
the address of a buffer that is to contain the opaque full name of the
namespace entry that is pointed to by a soft link.
ONS$_OUTOBJECTS

DNS$_OUTOBJECTS specifies for the DNS$_ENUMERATE_OBJECTS
function the address of a buffer that is to contain the set of opaque simple
names returned by the enumeration.
The values resulting from the enumeration can be extracted using the
DNS$REMOVE_FIRST_SET_VALUE routine. The resulting values are
the opaque simple names of the objects found in the directory.
DNS$_OUTCHILDREN

DNS$_OUTCHILDREN specifies for the DNS$_ENUMERATE_
CHILDREN function the address of a buffer that is to contain the set
of opaque simple names returned by the enumeration.
The values resulting from the enumeration can be extracted using the
DNS$REMOVE_FIRST_SET_VALUE routine. These values are the
opaque simple names of the child directories found in the parent directory.
DNS$_OUTSOFTLINKS

DNS$_OUTSOFTLINKS specifies for the DNS$_ENUMERATE_
SOFTLINKS function the address of a buffer that is to contain the set
of opaque simple names returned by the enumeration.

A-41

DNS Clerk System Service Calls
$DNS

The values resulting from the enumeration can be extracted using the
DNS$REMOVE_FIRST_SET_VALUE routine. The resulting values are
the opaque simple names of the soft links found in the directory.

oNS$_OUTVALSET
DNS$_OUTVALSET specifies for the DNS$_READ_ATTRIBUTE function
the address of a buffer that is to contain the set of values for the given
attribute.
The values of the set placed in this buffer can be extracted using the
DNS$REMOVE_FIRST_SET_VALUE routine. The extracted values are
the values of the attribute.
DNS$_OUTUID

DNS$_ OUTUID is an optional item code that contains the address of a
buffer used by the create functions of $DNS to return the unique identifier
(UID). The UID is the time-stamping the entry received at creation.

0.
~.~

DNS$_SUPPRESS_NSNAME

DNS$_SUPPRESS_NSNAME is an optional item for the DNS$_FULL_
OPAQUE_TO_STRING function that is used to indicate that the leading
namespace name should not be returned in the converted full name string.
This is a single-byte value.
A value of 1 suppresses the leading namespace name in the resulting full
name string.
DNS$_TOFULLNAME

DNS$_TOFULLNAME specifies for the DNS$_PARSE_FULLNAME_
STRING function the address of a buffer that will contain the resulting
opaque full name.

DNS$_TOSIMPLENAME

DNS$_TOSIMPLENAME specifies for the DNS$_PARSE_SIMPLENAME_
STRING function the address of a buffer that will contain the resulting
opaque simple name.
DNS$_TOSTRINGNAME

DNS$_TOSTRINGNAME specifies the address of a buffer that is to
contain the string name resulting from one of the conversion functions:
DNS$_FULL_OPAQUE_TO_STRING or DNS$_SIMPLE_OPAQUE_TO_
STRING.
DNS$_VALUE

DNS$_VALUE specifies for the DNS$_TEST~TTRIBUTE function the
value that is to be tested. This item contains the address of a buffer
holding the value.
DNS$_VERSION

DNS$_VERSION specifies for the DNS$_CREATE_OBJECT function
the version associated with an object. This item contains the address of a
$DNSCVERSDEF (CLASSVERSION) structure. This is a 2-byte structure:
the first byte contains the major version number; the second contains the
minor version number.

A-42

DNS Clerk System Service Calls

SONS
DNS$_WAIT
DNS$_WAIT enables the client to specify a timeout value to wait for a
call to complete. If the timeout expires, the call returns either DNS$K_
TIMEOUTNOTDONE or DNS$K_TIMEOUTMAYBEDONE, depending on
whether the name space was updated by the incomplete operation.

The $BINTIM service converts an ASCII string time value to the
quadword time value required by $DNS.
The parameter is optional; if it is not specified, a system-defined default
timeout value of 10 minutes is assumed.

DNS$_WILDCARD
DNS$_WILDCARD is an optional item code that specifies to the
enumeration functions of $DNS the opaque simple name used to limit
the scope of the enumeration. (The simple name does not have to use a
wildcard.) Only those simple names that match the wildcard are returned
by the enumeration.
Item Code Identifiers

The identifiers shown in Table A-I are data structures that are used in
item code arguments. Each data structure defines the encoding of an item
list element.

Table A-1

DNS Item Code Arguments

Item Code Identifier

Description

Attribute_Name

The structure of an opaque simple name, limited to
31 ISO Latin 1 characters.
An attribute name string with the structure of a
simple name string but limited to 31 ISO Latin 1
characters.

Boolean

A 1-byte field with the value 0 if false and 1 if true.

Class_Name

An opaque simple name, limited to 31 ISO Latin 1
characters.
A simple name string, limited to 31 ISO Latin 1
characters.

Class_Version

A 2-byte field specifying major and minor version
numbers associated with the object class.

Confidence

A 1-byte field with the value: DNS$K_LOW,
DNS$K_MEDIUM, or DNS$K_HIGH.

Entry_Type

A 1-byte field with the value DNS$K_OBJECT,
DNS$K_SOFTLlNK, DNS$K_DIRECTORY, or
DNS$K_CLEARINGHOUSE.
A structure consisting of a single byte, indicating
whether the attribute is a set (DNSK$_SET) or a
single value (DNS$K_SINGLE), followed by an
opaque simple name.

(continued on next page)

A-43

DNS Clerk System Service Calls
$DNS

o
Table A-1 (Cont.)
Item Code Identifier

DNS Item Code Arguments
Description

A full name string with the following structure:
[NS_name:J [.J Namestring [.NamestringJ
NS_name:, if present, is a local system
representation of the NSUID, the unique identifier
of the name server. The DNS clerk supplies a
namespace name (node-name_NS) if the value is
omitted.
Namestring represents a simple name component.
Multiple simple names are separated by periods.
You can include the asterisk wildcard (*) and
simple name strings within quotation marks.
A structure consisting of a single byte, indicating
whether the entry is a principal (DNS$K_
GRPMEM_NOT_GROUP) or another group
(DNS$K_GRPMEM_IS_GROUP), followed by the
opaque full name 01 the member.
The internal format of the complete name
identifier for an object. The maximum output
of DNS$PARSE_FULLNAME_STRING is 402
bytes.
A simple name specifies the internal format
of one component of an Opaque_Full_Narne.
The Opaque_Simple_Name is the output of the
DNS$PARSE_SIMPLENAME_STRING routine. It
can be no longer than 257 bytes.

One term consisting of a string of ASCII characters
with its length stored separately in an item list.

dnsb
VMS usage:
type:
access:
mechanism:

dns_status_block
quadword (unsigned)
write only
by reference

Status block to receive the final completion status of the $DNS operation.
The dnsb argument is the address of the quadword $DNS status block.

o
A-44

DNS Clerk System Service Calls

$DNS

The following figure depicts the structure of a $DNS status block:

return status
reserved

I outlinked I inoutdirect
I

v
qualifying status

ZK-1080A-GE

Status Block Fields
return status

Set on completion of a DNS clerk request to indicate the success or
failure of the operation. Check the qualifying status word for additional
information about a request marked as successful. Wherever possible,
each function code description includes return status values.
qualifying status

This field consists of a set of flags that provide additional information
about a successful name service operation. Wherever possible, each
function code description includes qualifying status values.
The qualifying status values are defined as follows:
•

DNS$V_DNSB_INOUTDIRECT-If true, indicates only the top level
group was seached for a member.

•

DNS$V_DNSB_OUTLINKED-If set, indicates that one or more soft
links were encountered while resolving the object of the call.

astadr

VMS usage:
type:
access:
mechanism:

ast_procedure
procedure entry mask
call without stack unwinding
by reference

Asynchronous system trap (AST) routine to be executed when I/O
completes. The astadr argument, which is the address of a longword
value, is the entry mask to the AST routine.
The AST routine executes in the access mode of the caller of $DNS.

astprm
VMS usage:
type:
access:
mechanism:

user_arg
longword (unsigned)
re~d only
by value

Asynchronous system trap (AST) parameter passed to the AST service
routine. The astprm argument is a longword value containing the AST
parameter.

A-45

DNS Clerk System Service Calls
$DNS

DESCRIPTION

c
The VMS Distributed Name Service Clerk system service provides a lowlevel interface between an application (client) and the VAX Distributed
Name Service. The DNS clerk interface is used to create, delete, modify,
and retrieve objects or soft links in a namespace.
A single system service call supports the DNS clerk. It has two main
parameters:
•

A function code identifying the particular service to perform

•

An item list specifying all the parameters for the required function

The use of this item list is similar to that of other system services that use
a single item list for both input and output operations.
Item list entries must be specified in opaque format. You can convert
anyone of the name strings to opaque format with a conversion function.
If applications need to store names, they must store them in opaque
format. The opaque format guarantees the uniqueness of a name over
time, whereas a string format does not.
Many of the functions return results as a set. In some cases, the specified
output buffer might not be large enough to contain the complete set.
In this case, the return status indicates this condition with the success
status $DNS_MOREDATA. To obtain the remaining data from the set, the
client should make repeated calls, each time specifying the last attribute
received in the context variable item until the call returns SS$_NORMAL.

~_)

The context variable item can take one of two forms depending on the
function:
•

DNS$CONTEXTVARNAME-If the returned data is a set bf names,
then the item is a simple name.

•

DNS$CONTEXTVARTIME-If the returned data is a set of values,
then the item is a time-stamping.

If the context variable item is not specified or is null, then the results are
returned from the beginning of the set.

-\
1_)
C

All functions return the SS$_NORMAL status for success except DNS$_
TEST_ATTRIBUTE, which returns DNS$_TRUE or DNS$_FALSE. The
functions return linked information in the $DNS status block. The
DNS$V_DNSB_OUTLINKED bit in the status block indicates whether
any soft links are encountered in an information search.

CONDITION
VALUES
RETURNED

A-46

SS$_BADPARAM

Bad parameter value.

SS$_NORMAL

Normal completion of the request.

DNS$_ACCESSDENIED

Caller does not have required access to
the entry in question. This error is returned
only if the client has some access to the
entry. Otherwise, the unknown entry status
is returned.

DNS Clerk System Service Calls
$DNS

o
o

DNS$_BADCLOCK

The clock at the name server has a value
outside the permissible range.

DNS$_BADEPOCH

Copies of directories are not synchronized.

DNS$_BADITEMBUFFER

Invalid output item buffer detected. (This
normally indicates that the buffer has been
modified during the call.)

DNS$_CACHELOCKED

Global client cache locked.

DNS$_CLEARINGHOUSEDOWN

Clearinghouse is not available.

DNS$_CLERKBUG

Internal clerk error detected.

DNS$_CONFLICTINGARGUMENTS

Two or more optional arguments conflict;
they cannot be specified in the same
function call.

DNS$_DANGLlNGLINK

Soft link points to nonexistent entry.

DNS$_DATACORRUPTION

An error occurred in accessing the
data stored at a clearinghouse. The
clearinghouse may be corrupted.

DNS$_ENTRYEXISTS

An entry with the same full name already
exists in the namespace.

DNS$_FALSE

Unsuccessful test operation.

DNS$_INVALIDARGUMENT

A syntactically incorrect, out of range, or
otherwise inappropriate argument was
specified in the call.

DNS$_INVALlD_ATTRIBUTENAME

The name given for function is not a valid
DNS attribute name.

DNS$_INVALI 0_CLASSNAME

The name given for function is not a valid
DNS class name.

DNS$_INVALlD_
CLEARINGHOUSENAME

The name given for function is not a valid
DNS clearinghouse name.

DNS$_INVALlD_CONTEXTNAME

The name given for function is not a valid
DNS name.

DNS$_INVALlD_DIRECTORYNAME

The name given for function is not a valid
DNS directory name.

DNS$_INVALlD_ENTRYNAME

The name given for function is not a valid
DNS entry name.

DNS$_INVALIDFUNCTION

Invalid function specified.

DNS$_INVALlD_GROUPNAME

The name given for function is not a valid
DNS group name.

DNS$_INVALIDITEM

Invalid item list entry specified.

DNS$_INVALlD_LlNKNAME

The name given for function is not a valid
DNS link name.

DNS$_INVALlD_MEMBERNAME

The name given for function is not a valid
DNS name.

DNS$_INVALIDNAME

A badly formed name was supplied to the
call.
Namespace name given in name string is
not a valid DNS name.

A-47

DNS Clerk System Service Calls
$DNS

o
DNS$_INVALlD_OBJECTNAME

The name given for function is not a valid
DNS object name.
The name given for function is not a valid
DNS name.

DNS$_INVALIDUPDATE

An update was attempted to an attribute
that cannot be directly modified by the
client.

DNS$_INVALlD_WILDCARDNAME

The name given for function is not a valid
DNS name.
Error translating logical name in given
string.

DNS$_MISSINGITEM

Required item list entry is missing.

DNS$_MOREDATA

More output data to be returned.

DNS$_NAMESERVERBUG

A name server encountered an
implementation bug. Please submit an
SPR.

DNS$_NOCACHE

Client cache file not initialized.

DNS$_NOCOMMUNICATION

No communication was possible with any
name server capable of processing the
request. Check NCP event 353.5 for the
DECnet error.

DNS$_NONSRESOURCES

The call could not be performed due to lack
of memory or communication resources at
the local node to process the request.

DNS$_NONSNAME

Unknown namespace name specified.

DNS$_NOTAGROUP

The full name given is not the name of a
group.

DNS$_NOTIMPLEMENTED

This function is defined by the architecture
as optional and is not available in this
implementation.

DNS$_NOTLINKED

A link is not containeq in the name.

DNS$_NOTNAMESERVER

The node contacted by the clerk does
not have a DNS server running. This can
happen when the application supplies the
clerk with inaccurate replica information.

DNS$_NOTSUPPORTED

This version of the architecture does not
support the requested function.

DNS$_POSSIBLECYCLE

Loop detected in link or group entry.

DNS$_RESOURCEERROR

Failure to obtain system resource.

DNS$_TIMEOUTNOTDONE

The operation did not complete in the
time allotted. No modifications have been
performed even if the operation requested
them.

DNS$_TIMEOUTMAYBEDONE

The operation did not complete in the time
allotted. Modifications mayor may not have
been made to the namespace.
Successful test operation.

A-48

o
"------\

DNS Clerk System Service Calls
$DNS

c
DNS$_UNKNOWNCLEARINGHOUSE

The clearinghouse does not exist.

DNS$_UNKNOWNENTRY

Either the requested entry does not exist
or the client does not have access to the
entry.

DNS$_UNTRUSTEDCH

A DNS server is not included in the object's
access control set.

DNS$_WRONGATTRIBUTETYPE

The caller specified an attribute type
that did not match the actual type of the
attribute.

o
c

o
A-49

DNS Clerk System Service Calls
$DNSW

$DNSW

o
Distributed Name Service Clerk and Wait
The Distributed Name Service Clerk and Wait service registers a resource
in a distributed database; same as $DNS. However, the $DNSW service
completes synchronously; that is, it returns to the caller after the operation
completes.
For asynchronous completion, use the $DNS service, which returns to the
caller immediately after making a name service call. The return status to the
client call indicates whether a request was successfully queued to the name
service.
In all other respects, $DNSW is identical to $DNS. Refer to the $DNS
description for complete information about the $DNSW service.

/-~

(

FORMAT

SYS$DNSW

[etn] ,tunc ,itm/st ,[dnsb] ,[astadr] ,[astprm]

o
A-50

VMS Version 5.3 Features

$DNSW

A.2.9

DNS Run-Time Routines
All applications designed to take advantage of the Distributed Name
Service (DNS) use the DNS clerk system services and the DNS run-time
routines to register a resource in the DNS namespace and to modify
and find information within the namespace. This section describes the
run-time routines.

C'·'
/

o
A-51

DNS$ Run-Time Routines
DNS$APPEND_ SIMPLENAME_TO_RIGHT

DNS$APPEND_SIMPLENAME_TO_RIGHT Append a
Simple Name to the End of a Full
Name
The Append a Simple Name to the End of a Full Name routine adds an
opaque simple name to the end of an opaque full name to create a new full
name.

FORMAT

DNS$APPEND_ SIMPLENAME_TO_RIGHT

fullname ,simplename ,resulting-fullname
,resulting-length
RETURNS

ARGUMENTS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

ful/name
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The opaque full name gaining a new simple name. The fullname
argument is the address of a descriptor pointing to the opaque full name
that is to be extended.

simplename
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The opaque simple name that is appended. The simplename argument is
the address of a descriptor pointing to an opaque simple name that is to
be appended to the full name, thus creating a new full name.

resulting-ful/name
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

The new full name. The resulting-fullname argument is the address
of a descriptor that points to the buffer that receives the new full name.

A-52

DNS$ Run-Time Routines

DNS$APPEND_SIMPLENAME_TO_RIG HT

This buffer can be the same as the buffer referred to by the fullname
argument; however, the descriptors must be separate.

resulting-length
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The length of the. new full name. The resulting-length argument is the
address of a word that receives the length of the new full name found in
resulting-fullname.

c
c

DESCRIPTION

CONDITION
VALUES
RETURNED

DNS$APPEND_SIMPLENAME_TO_RIGHT adds an opaque simple name
to the end of an opaque full name to create a new full name.

SS$_NORMAL

Normal successful completion.

DNS$_INVALIDNAME

The name to be converted is not a valid DNS name.

Error appending name.

o
A-53

DNS$ Run-Time Routines

DNS$COMPARE_FULLNAME

Compare Full Names

The Compare Full Names routine compares two opaque full names and
returns the result.

FORMAT

DNS$COMPARE_FULLNAME

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

fullname1,fullname2

cond_value
longword (unsigned)
write only
by value

fullname1
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

One opaque full name. The fullnamel argument is the address of a
descriptor pointing to an opaque full name.

fullname2
VMS usage:
type:
access:
mechanism:

DESCRIPTION

CONDITION
VALUES
RETURNED

A-54

char_string
character string
read only
by descriptor

DNS$COMPARE_FULLNAME compares two opaque full names and
returns the result. First, the procedure checks the namespace UIDs of the
full names as numbers. If they are unequal, the routine returns the result.
If they are equal, it compares each simple name in the full name until it
finds an inequality or determines that both names are the same.

-1

fullname1 is less than fullname2.

fullname1 equals fullname2.
fullname1 is greater than fullname2.

DNS$ Run-Time Routines

DNS$COMPARE_SIMPLENAME

DNS$COMPARE_SIMPLENAME
Simple Names

Compare Two

The Compare Two Simple Names routine compares two simple names,
without considering case.

FORMAT

DNS$COMPARE_SIMPLENAME

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

simplename1
,simplename2

cond_value
longword (unsigned)
write only
by value

simplename1
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

An opaque simple name. The simplenamel argument is the address of a
descriptor pointing to the first simple name.

simplename2
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

An opaque simple name. The simplename2 argument is the address of a
descriptor pointing to the second simple name.

DESCRIPTION

CONDITION
VALUES
RETURNED

DNS$COMPARE_SIMPLENAME compares two simple names, without
considering case. The routine determines the relationship between two
opaque simple names to see if they are equal.

SS$_NORMAL

Normal successful completion.

-1

simplename1 is less than simplename2.

simplename1 equals simplename2.
simplename1 is greater than simplename2.

A-55

DNS$ Run-Time Routines

DNS$CONCATENATE_NAME

DNS$CONCATENATE_NAME Join Two Names
The Join Two Names routine jOins two opaque full names to form a new full
name.

FORMAT

DNS$CONCATENATE_NAME
fullname 1 ,fullname2 ,resulting-fullname
,resulting-length

RETURNS

VMS usage:
type:
access:
mechanism:

(~I

,,-j

ARGUMENTS

cond_value
longword (unsigned)
write only
by value

fullname1
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The opaque full name to be joined. The fullnamel argument is the
address of a descriptor pointing to the opaque full name.

fullname2
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The opaque full name appended to fullnamel. The fullname2 argument
is the address of a descriptor pointing to the full name to be appended.

resulting-fullname
VMS usage:
type:
access:
mechanism:

char_string
character stri ng
write only
by descriptor

The buffer where the new full name will be written. The resultingfullname argument is the address of a descriptor pointing to the buffer.
This buffer can be the same as the buffer referred to by the fullname 1
argument; however, the descriptors must be separate.

A-56

DNS$ Run-Time Routines

DNS$CONCATENATE_NAME

c
resulting-length
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The length of the new full name. The resulting-length argument is the
address of a word that receives the length of the new full name found in
resulting-fullname.

DESCRIPTION

CONDITION
VALUES
RETURNED

DNS$CONCATENATE_NAME joins two opaque full names to form a new
opaque full name, which is placed in the buffer named by the resultingfullname argument. The new full name receives the names pace name
of the first opaque full name. For example, appending the full name
TEST:.POP.DIRI (fullname2) to DEC:.ENG.NAC (fullnamel) results in a
full name of DEC:.ENG.NAC.POP.DIRl.

SS$_NORMAL

Normal successful completion.

DNS$_INVALIDNAME

The name to be converted is not a valid DNS name.

Error performing concatenation.

o
A-57

DNS$ Run-Time Routines
DNS$COUNT_ SIMPLENAMES

DNS$COUNT_SIMPLENAMES Count the Simple
Names in a Full Name
The Count the Simple Names in a Full Name routine counts the number of
simple names contained in an opaque full name.

FORMAT

DNS$COUNT_SIMPLENAMES

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

fullname ,count

cond_value
longword (unsigned)
write only
by value

luI/name
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The full name to be counted. The fullname argument is the address of a
descriptor pointing to the full name that is to be examined for the simple
names it contains.

count
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write on Iy
by reference

The number of simple names found in the full name. The count argument
is the address of a word that receives the number of simple names.

DESCRIPTION

CONDITION
VALUES
RETURNED

A-58

DNS$COUNT_SIMPLENAMES counts the number of simple names-but
not the namespace name-found in an opaque full name. The number of
simple names counted is returned in the word referenced by the count
argument. The routine is meant to be used with DNS$REMOVE_RIGHT_
SIMPLENAME and DNS$REMOVE_LEFT_SIMPLENAME.

SS$_NORMAL

Normal successful completion.

DNS$_INVALIDNAME

The name to be converted is not a valid DNS name.

DNS$ Run-Time Routines

DNS$CVT_DNSADDRESS_TO_BINARY

DNS$CVT_DNSADDRESS_TO_BINARV Convert
a DNS Address to a Phase IV Binary
Address
The Convert a DNS Address to a Phase IV Binary Address routine takes a
DNS address and returns the DECnet Phase IV node address.

FORMAT

DNS$CVT_DNSADDRESS_TO_BINARY

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

dnsaddress
,binary

cond_value
longword (unsigned)
write only
by value

dnsaddress
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The DNS address. The dnsaddress argument is the address of a
descriptor pointing to the DNS address.

binary

VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The DECnet Phase IV address found in the DNS address structure. The
binary argument is the address of a word containing the 16-bit Phase IV
address of the node.

DESCRIPTION

DNS$CVT_DNSADDRESS_TO_BINARY takes a DNS address and returns
the DECnet Phase IV node address. The Phase IV address is returned in a
word. If no Phase IV address is found in the DNS address, then the value
o is returned as an error.

o
A-59

DNS$ Run-Time Routines

DNS$CVT_DNSADDRESS_TO_BINARY

CONDITION
VALUES
RETURNED

Normal successful completion.
No DECnet Phase IV address found.

(

\,,-- _:/'

()

o
A-60

DNS$ Run-Time Routines

DNS$CVT_DNSADDRESS_TO_NODENAME

DNS$CVT_DNSADDRESS_TO_NODENAME Convert
a DNS Address to a Node Name
The Convert a DNS Address to a Node Name routine takes a DNS address
and returns a DECnet Phase IV node name.

FORMAT

o
o

DNS$CVT_DNSADDRESS_TO_NODENAME
dnsaddress ,nodename ,resulting-length

RETURNS

ARGUMENTS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

dnsaddress
VMS usage:
type:
access:
mechanism:

char_string
character stri ng
read only
by descriptor

The DNS address. The dnsaddress argument is the address of a
descriptor pointing to the DNS address.

nodename

VMS usage:
type:
access:
mechanism:

char_string
character stri ng
write only
by descriptor

The DECnet Phase IV node name. The nodename argument is the
address of a descriptor pointing to the Phase IV node name. The memory
buffer referenced by the DSC$A_POINTER portion of this descriptor must
be large enough to contain the entire Phase IV node name string, which
can be up to six bytes long.

resulting-length
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The length of the node name (in bytes) after conversion. The resultinglength argument is a word containing the length of the node name (in
bytes) after conversion.

A-61

DNS$ Run-Time Routines

DNS$CVT_DNSADDRESS_TO_NODENAME

DESCRIPTION

DNS$CVT_DNSADDRESS_TO_NODENAME takes a DNS address and
returns a DECnet Phase IV node name. If no Phase IV address is found,
then the value 0 is returned.
Because DNS$CVT_DNSADDRESS_TO_NODENAME calls both $ASSIGN
and $QIOW, it can return condition values from either of these system
services. The routine also returns errors detected through NETACP.

CONDITION
VALUES
RETURNED

Normal successful completion.
No DECnet Phase IV address found.

o
o

c
A-62

DNS$ Run-Time Routines
DNS$CVT_NODENAME_TO_DNSADDRESS

DNS$CVT_NODENAME_TO_DNSADDRESS
a Node Name to an Address

Convert

The Convert a Node Name to a DNS Address routine takes a DECnet Phase
IV node name and returns a DNS address.

FORMAT

DNS$CVT_NODENAME_TO_DNSADDRESS
nodename ,dnsaddress ,resulting-length

RETURNS

ARGUMENTS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

nodename
VMS usage:
type:
access:
mechanism:

char_string
character stri ng
read on Iy
by descriptor

The DECnet Phase IV node name. The nodename argument is the
address of a descriptor pointing to the node name. This routine creates
a DNS address containing the node address of the given Phase IV node
name.

dnsaddress
VMS usage:
type:
access:
mechanism:

char_string
character stri ng
write only
by descriptor

The address of a buffer containing the DNS address. The dnsaddress
argument is the address of a descriptor pointing to the buffer address.

resulting-length
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The length of the DNS address after conversion. The resulting-length
argument is a word containing the length of the address.

A-63

DNS$ Run-Time Routines

DNS$CVT_NODENAME_TO_DNSADDRESS

DESCRIPTION

DNS$CVT_NODENAME_TO_DNSADDRESS takes a DECnet Phase IV
node name and returns a DNS address. The routine creates the DNS
address for a given Phase IV node name.
DNS$CVT_NODENAME_TO_DNSADDRESS calls $ASSIGN and $QIOW
so it can return condition values from either of these system services. The
routine also returns errors detected through NETACP.

CONDITION
VALUES
RETURNED

Normal successful completion.

I~\

o
o

o
A-54

DNS$ Run-Time Routines
DNS$CVT_ TO_ USERNAME_STRING

DNS$CVT_TO_USERNAME_STRING Convert
an Opaque User Name to a String
The Convert an Opaque User Name to a String routine converts an opaque
DECnet Phase IV user name into a username string.

FORMAT

DNS$CVT_ TO_ USERNAME_STRING
fullname ,username ,resulting-length

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

cond_value
longword (unsigned)
write only
by value

ful/name
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The opaque full name for the DECnet Phase IV user name. The fullname
argument is the address of a descriptor pointing to the name.

username

VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

The name converted to DECnet Phase IV format (node::user). The
username argument is the address of a descriptor pointing to a buffer
containing the converted name.

resulting-length
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The length of the converted user name. The resulting-length argument
is the address of a word containing the length.

o
A-65

DNS$ Run-Time Routines
DNS$CVT_ TO_ USERNAME_STRING

DESCRIPTION

DNS$CVT_TO_USERNAME_STRING converts a DNS representation of a
Phase IV user name into a Phase IV username string.
If any full name other than a DNS representation of a Phase IV user name
is given, the routine returns a DNS$_INVALIDNAME error.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Procedure successfully completed.

DNS$_ACCESSVIOLATION

Memory or other resource access violation.

DNS$_CACHELOCKED

Global client cache locked by another process.

DNS$_INVALIDARGUMENT

One of the arguments was incorrect, out of range, or
otherwise inappropriate.

DNS$_INVALIDNAME

The name to be converted is not a valid DNS name.

DNS$_NOCACHE

Client cache file not initialized.

DNS$_RESOURCEERROR

Insufficient resources on local system to process
request.

(~\
I

o
C)

o
A-66

DNS$ Run-Time Routines

DNS$PARSE_USERNAME_STRING

DNS$PARSE_USERNAME_STRING Convert a
User Name from String to Opaque
The Convert a User Name from String to Opaque routine converts a DECnet
Phase IV user name to an opaque full name.

FORMAT

DNS$PARSE_USERNAME_STRING
user-string ,phase4-name ,resulting-length
[, next-character-pointer]

RETURNS

VMS usage:
type:
access:
mechanism:

c!
o

ARGUMENTS

cond_value
longword (unsigned)
write only
by value

user-string
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The name string to convert. The user-string argument is the address of a
descriptor pointing to the DEC net Phase IV username string, which is in
the format node::user.

phase4-name
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

The opaque full name resulting from conversion. The phase4-name
argument is the address of a descriptor pointing to the buffer that is to
contain an opaque full name representing a user name on a Phase IV
node.

resulting-length

VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The length of the opaque full name. The resulting-length argument
is the address of a word holding the length of the name returned in
phase4-name.

A-67

DNS$ Run-Time Routines
DNS$PARSE_USERNAME_STRING

next-character-pointer
VMS usage: address

type:

address

access:
write only·
mechanism: by reference

The character following the DNS name extracted from user-string.
The next-character-pointer argument is the address of the character
following the DNS name. When you use this argument, DNS$PARSE_
USERNAME_STRING returns DNS$_INVALIDNAME when it encounters
an invalid name. In such a case, next-character-pointer points to the
first character in the name that is invalid.

DESCRIPTION

DNS$PARSE_USERNAME_STRING converts a DECnet Phase IV user
name to an opaque full name that represents the user name.
The next-character-pointer argument affects how the routine parses the
string:
•

When next-character-pointer is zero or absent, the full name string
given in user-string must contain valid DNS characters with DNS
naming syntax. If any part of the string violates this rule, the routine
returns DNS$_INVALIDNAME and the output should not be used.

•

When the next-character-pointer argument has a nonzero value, the
parsing begins at the first character referenced by user-string and
parsing continues until one of the following occurs:

An invalid DNS character is found.
An exception to DNS syntax rules occurs.
All characters have been parsed.
Then the address given by next-character-pointer is set to the
address of the character or group of characters that is invalid. It
returns DNS$_INV...I\LIDNAME if the colons (::) separating the node
name from the user name of the Phase IV name are missing.

C)
/'

If any part of the node portion of the DECnet Phase IV username string
is not a proper DNS name, the routine returns DNS$_INVALIDNAME
regardless of the value and whether or not the next-character-pointer
argument is supplied.
Error conditions can result from the parse routine. You can test for error
conditions in any of the following ways:

A-68

•

When all parts of the name are invalid, test whether next-characterpointer contains the same address as user-string. Alternatively, test
whether the resulting length is zero.

•

When user-string contains a valid DNS name, test whether nextcharacter-pointer contains the address immediately following
the given buffer. Alternatively, test whether the address in nextcharacter-pointer minus the address of user-string is equal to or
larger than the size of the given buffer.

DNS$ Run-Time Routines

DNS$PARSE_USERNAME_STRING

•

CONDITION
VALUES
RETURNED

When parsing a user name that has been extracted from a command
line, test whether the character given at the address of nextcharacter-pointer is a valid separator for the command line, for
example, a space. If you find an invalid character, then part of the
DNS name is invalid.

SS$_NORMAL

Normal successful completion.

DNS$_ACCESSVIOLATION

Memory or other resource access violation.

DNS$_CACHELOCKED

Global client cache locked by another process.

DNS$_INVALIDARGUMENT

One of the arguments was incorrect, out of range, or
otherwise inappropriate.

DNS$_INVALIDNAME

The name to be converted is not a valid DNS name.

DNS$_NOCACHE

Client cache file not initialized.

DNS$_RESOURCEERROR

Insufficient resources on local system to process
request.

Error creating opaque name.

o
o

o
A-69

DNS$ Run-Time Routines
DNS$REMOVE_FIRST_SET_VALUE

DNS$REMOVE_FIRST_SET_VALUE

o
Remove a

Value from a Set
The Remove a Value from a Set routine extracts the first value from a set and
returns the value with its creation time-stamping UID.

FORMAT

DNS$REMOVE_FIRST_SET_VALUE
set [, value] [, value-length] [,uid] [,uid-Iength] [,newset]
[,newset-Iength]

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

cond_value
longword (unsigned)
write only
by value

set
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

()

The set from which the value is extracted. The set argument is the
address of a descriptor pointing to the set.

value
VMS usage:
type:
access:
mechanism:

char_string
character stri ng
write only
by descriptor

The value extracted from the set. The value argument is the address of a
descriptor pointing to a buffer containing the value.

value-length
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The length of the value. The value-length argument is the address of a
word holding the length of the value placed in value.

o
A-70

DNS$ Run-Time Routines
DNS$REMOVE_FIRST_SET_VALUE

C:
uid
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

The buffer holding the creation time-stamping UID of the extracted value.
The uid argument is the address of a descriptor pointing to the buffer.

uid-Iength
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The length of the UID placed in uid. The uid-Iength argument is the
address of a word holding the length.

newset
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

The opaque set without the first value. The newset argument is the
address of a descriptor pointing to a buffer containing that set. The buffer
can be the same as the one given in the set argument.

newset-Iength
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The length of the new set copied to the newset buffer. The newsetlength argument is the address of a word that receives the length.

DESCRIPTION

DNS$REMOVE_FIRST_SET_VALUE extracts a value from a set and
returns the value with its creation time-stamping UID. Use the routine to
extract values from the sets returned by $DNS and $DNSW.
A set can contain any number of values that are relevant to a given call.
The routine extracts values one at a time from the opaque set for use by
a program. In order to extract all values from the set, you must use an
execution loop.

o
A-71

DNS$ Run-Time Routines
DNS$REMOVE_FIRST_SET_VALUE

CONDITION
VALUES
RETURNED

SS$_NORMAL

Normal successful completion.

DNS$_INVALIDARGUMENT

The set argument was incorrect, out of range, or
otherwise inappropriate.

Set buffer is empty.

-1

Length of value, uid, or newset buffers too small.

(~\

o
A-72

DNS$ Run-Time Routines

DNS$REMOVE_LEFT_SIMPLENAME

DNS$REMOVE_LEFT~SIMPLENAME

Strip the
Simple Name on the Left from the Full
Name

The Remove the Simple Name on the Left from the Full Name routine
removes the leftmost simple name from an opaque full name. It returns
both the simple name stripped and the new full name that results from the
operation.

FORMAT

DNS$REMOVE_LEFT_SIMPLENAME
fullname [,resulting-fullnamej
[,resulting-fullname-Iengthj [,resulting-simplenamej
[, resulting-simplename-Iengthj

RETURNS

VMS usage:
type:
access:
mechanism:

0
ARGUMENTS

cond_value
longword (unsigned)
write only
by value

lullname
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The opaque full name to strip. The fullname argument is the address
of a descriptor pointing to the opaque full name to strip. If the full name
does not contain any simple names, the routine returns a value of 0 in
cond_value.

resulting-fullname
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

The opaque full name resulting from the operation. The resultingfullname argument is the address of a descriptor pointing to the buffer
containing the resulting opaque full name. This buffer can be the same as
the buffer referred to by the fullname argument; however, the descriptors
must be separate.

A-73

DNS$ Run-Time Routines

DNS$REMOVE_LEFT_SIMPLENAME

resulting-fullname-Iength
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The length of the full name that is returned. The resulting-fullnamelength argument is the address of a word receiving the length of the full
name returned in resulting-fullname.

resulting-simplename
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

The simple name stripped from fullname. The resulting-simplename
argument is the address of a descriptor pointing to the buffer containing
the opaque simple name that was stripped.

resulting-simplename-Iength
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The length of the simple name. The resulting-simplename-Iength
argument is the address of a word that receives the length of the simple
name returned in resulting-simplename.

DESCRIPTION

CONDITION
VALUES
RETURNED

DNS$REMOVE_LEFT_SIMPLENAME removes the leftmost simple name
from an opaque full name. When resulting-fullname is nonzero, the full
name resulting from the removal of the leftmost simple name is returned
in that buffer. When resulting-simplename is nonzero, the simple
name that was stripped from fullname is returned in that buffer. The
namespace name is not stripped from the full name; only simple names
are affected.

SS$_NORMAL

Normal successful completion.

DNS$_INVALIDNAME

The name to be converted is not a valid DNS name.

-1

Error stripping name.

No simple name.

(. .~
'\

o
A-74

DNS$ Run-Time Routines

DNS$REMOVE_RIG HT_ SIMPLENAME

DNS$REMOVE_RIGHT_SIMPLENAME Strip the
Simple Name on the Right from the
Full Name
The Remove the Simple Name on the Right from the Full Name routine
removes the rightmost simple name from an opaque full name. It returns
both the simple name stripped and the new full name that results from the
operation.

FORMAT

DNS$REMOVE_RIGHT_ SIMPLENAME
fullname [,resulting-fullnamej
[,resulting-fullname-Iengthj [,resulting-simplenamej
[, resu Iting-simplename-Iengthj

RETURNS

VMS usage:
type:
access:
mechanism:

ARGUMENTS

cond_value
longword (unsigned)
write only
by value

ful/name
VMS usage:
type:
access:
mechanism:

char_string
character string
read only
by descriptor

The opaque full name to strip. The fullname argument is the address of a
descriptor pointing to the opaque full name to strip. When the opaque full
name does not contain any simple names, the routine returns a value of 0
in cond_value.

resulting-fullname
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

The opaque full name resulting from the operation. The resultingfullname argument is the address of a descriptor pointing to a buffer
containing the resulting opaque full name. This buffer can be the same as
the buffer referred to by the fullname argument; however, the descriptors
must be separate.

A-75

DNS$ Run-Time Routines

DNS$REMOVE_RIGHT_ SIMPLENAME

res ulting-fullname-Ieng th
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The length of the full name returned in resulting-fullname. The
resulting-fullname-Iength argument is the address of a word that
receives the length of the full name returned in resulting-fullname.

resulting-simplename
VMS usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

A buffer containing the opaque simple name stripped from fullname. The
resulting-simplename argument is the address of a descriptor pointing
to the buffer.

resulting-simplename-Iength
VMS usage:
type:
access:
mechanism:

word_unsigned
word (unsigned)
write only
by reference

The length of the simple name. The resulting-simplename-length
argument is the address of a word receiving the length of the simple name
returned in resulting-simplename.

DESCRIPTION

CONDITION
VALUES
RETURNED

DNS$REMOVE_RIGHT_SIMPLENAME removes the rightmost simple
name from an opaque full name. When resulting-fullname is nonzero,
the full name resulting from the removal of the rightmost simple name
is returned in that buffer. When resulting-simplename is nonzero, the
simple name that was stripped from fullname is returned in that buffer.
The namespace name is not stripped from the full name; only simple
names are affected.

SS$_NORMAL

Normal successful completion.

DNS$_INVALIDNAME

The name to be converted is not a valid DNS name.

-1

Error stripping name.

o
A-76

VMS Version 5.3 Features

DNS$REMOVE_RIGHT_ SIMPLENAME

A.2.10 Starting the DNS Clerk
The VAX Distributed Name Service (DNS) is a product consisting of two
modules: a clerk and a server. The DNS clerk is an integral part of the
VMS operating system. The server is a layered product. As long as a DNS
server is installed in your network, you can start the DNS clerk on your
local VMS system. Then, applications can take advantage of the DNS
name service.
You start the DNS clerk once DECnet is running. The DNS startup
procedure defines the default DNS server, installs necessary libraries, and
creates an advertiser process. Startup involves two steps:
1

Obtain the name of the default DNS server from your network
administrator.

Execute the command procedure DNS$CHANGE_DEF_FILE. It runs
the command procedure DNS$CLERK_STARTUP, which installs the
shareable libraries and creates the advertiser process DNS$ADVER.
To run the command procedure, enter the following command:
$

@SYS$STARTUP:DNS$CHANGE_DEF_FILE.COM

When executed, SYS$STARTUP:DNS$CHANGE_DEF_FILE.COM
prompts for the name of the node where the DNS server is located.

Name of DNS server node?

Enter a node name, identifying the node that has the DNS server
installed.
Once you have run DNS$CHANGE_DEF_FILE.COM, you do not need
to run it again unless you want to change the default DNS server
or the default namespace. DNS$CHANGE_DEF_FILE. COM copies
a configuration file to SYS$SYSTEM that is called DNS$DEFAULT_
FILE.DAT. It lists the name of the namespace currently being used as a
default.
You must add the following line to SYS$MANAGER:SYSTARTUP.COM
after the line that starts DECNET: @SYS$STARTUP:DNS$CLERK_
STARTUP. COM. When the system boots, this line installs the DNS clerk
images and starts the advertiser.

A.2.11

DECnet Event Messages
The following are DECnet event messages sent by the Distributed Name
Service clerk. For a complete list of DECnet event messages, see the VMS
Network Control Program Manual.

o
A-77

VMS Version 5.3 Features
DNS$REMOVE_RIG HT_ SIMPLE NAME

353.5 DNS Clerk Unable to Communicate with Server

The DNS clerk was unable to communicate with a DNS server. This
message displays the name of the clearinghouse where the communication
failed, the node on which the DNS server servicing the clearinghouse
exists, and the reason why the communication failed, which might be any
of the following:
•

Unknown clearinghouse
The requested clearinghouse is not serviced by the DNS server that
was contacted. This can happen when the cache maintained by the
local DNS clerk contains outdated information for a directory.

•

Clearinghouse down
A DNS server is unable to service a request because the clearinghouse
is not operational (stopped state).

•

Wrong state
A DNS server is unable to service a request because the clearinghouse
is currently starting up or shutting down.

•

Data corruption
A DNS server is unable to service the request because the
clearinghouse file has been corrupted.

•

No communication

A network error occurred on the local system or on the system
containing the DNS server. The local VMS error is displayed as a
part of this message.
353.20 Local DNS Advertiser Error

This event communicates errors that are local to the DNS Advertiser
(DNS$ADVER). All these errors have the prefix ADV and are generated
when the DNS Advertiser has encounters an error that prevents proper
operation of the process. Exact errors are listed in the VMS System
Messages and Recovery Procedures Reference Manual.

o
A-78

()

VMS Version 5.2 Features

This appendix describes features that were new to Version 5.2 of the VMS
operating system but are not yet documented in other printed manuals.

8.1

VMS Version 5.2 System Management Features
The following sections describe enhancements to these components of the
VMS operating system:

o
8.1.1

System Generation Utility (SYSGEN)

•

NETCONFIG.COM

•

Backup Utility (BACKUP)

System Generation Utility (SYSGEN)
The VMS Version 5.2 System Generation Utility (SYSGEN) contains the
following new command and parameter:

o
8.1.1.1

•

DEINSTALL command

•

ERLBUFFERPAGES parameter

DEINSTAll Command Description
DEINSTALL removes or "deinstalls" system page files and system swap
files. Any file that is installed with the INSTALL command can be
removed with the DEINSTALL command.

Use of the DE INSTALL command requires the CMKRNL privilege.
Format
DEINSTAll

filespec

Parameter
filespec
Specifies the name of the page or swap file. The default file type is SYS.
Qualifiers
fAll
Deinstalls all page and swap files currently installed on the system. This
command is most useful during an orderly system shutdown procedure
where all disk volumes are being dismounted.

fINDEX=n
Deinstalls a page or swap file specified by the page file index. The page
file index is presented in the SHOW MEMORYIFILESIFULL display as
"Paging File Number."
B-1

VMS Version 5.2 Features
8.1 VMS Version 5.2 System Management Features

/PAGEFILE

Specifies that the file to be deinstalled is a page file.
/SWAPFILE

Specifies that the file to be deinstalled is a swap file.
Example
SYSGEN>

DEINSTALL SYS$SYSTEM:PAGEFILE.SYS/PAGEFILE

The command in this example deinstalls the system page file.
B.1.1.2

ERLBUFFERPAGES Parameter

The ERLBUFFERPAGES parameter specifies the number of pages of
memory to allocate for each buffer requested by the ERRORLOGBUFFERS
parameter. The ERLBUFFERPAGES parameter has a default value of 2
pages and a maximum value of 32 pages. The default value of 2 pages
consists of one page for each buffer greater than the previous buffer size.

8.1.2

(--_'\
\",- j '

NETCONFIG.COM Security Enhancements
In VMS Version 5.2, the DEC net network configuration command
procedure NETCONFIG.COM has been enhanced to provide several
options for restricting default access. A new command procedure for
eSxis~ingBneltw3°hrkedbsystems, NdEfiTCOhNFIG_UPDATE.COM, described in
ectlOn .. , as een create or t e same purpose.

0--__

You can plan the appropriate level of default access for your system
and implement that plan by responding to a few questions posed by
NETCONFIG.COM. NETCONFIG.COM then automatically records
your choices in the UAF (user authorization file) and in the network
configuration database.
Previously, NETCONFIG.COM created one default account named
DECNET. That account provided default access to all network objects
and applications that were not restricted by other forms of access control
(for example, proxy accounts and access control lists). If you chose to limit
default access, it was necessary to manually enter all the appropriate
commands in the UAF, using the Authorize Utility, and in the network
configuration database, using NCP commands.
B.1.2.1

Default Access Options

NETCONFIG.COM provides two different ways to limit default access.
The most restrictive form is to not create the default DECnet account but
to grant default access for certain system objects by creating a default
account for each one that you want to use. Using NETCONFIG.COM, you
can create an account for one or more of the following network objects:

B-2

•

MAIL

•

File access listener (FAL)

•

PHONE

•

Network management listener (NML)

•

Loopback mirror (MIRROR)

VMS Version 5.2 Features
B.1 VMS Version 5.2 System Management Features

• VMS Performance Monitor (VPM)
The second, less restrictive form of default access is to create a default
DECnet account but to disable default access to user-written programs
and procedures (also known as TASK objects). Default access for system
objects is still enabled.
You can still create an unrestricted default DECnet account that includes
default access to TASK objects. This type of access is suitable for systems
with low security requirements. To do so, you must override the defaults
provided by NETCONFIG.COM.

o
o

Note: If you do not create the default DECnet account, you must create
a default account for MAIL and VPM, if you want to use them. The
same is true for the MIRROR object if you want to use the User
Environment Test Package (UETP) to test the network connection.
FAL, if enabled by the default DECnet account or a separate default
account, makes a system vulnerable to unauthorized access. Digital
advises against creating a default account for FAL. Note, however, that
when you do not use FAL with a default account, remote file requests must
include explicit file access control information, or the local system manager
must set up proxy access for remote users. Consider an example with a
local node ETHQKE, and a remote node MISHA with no default account.
Entering the command $DIR MISHA:: from node ETHQKE produces the
following messages:
%DIRECT-E-OPENIN, error opening MISRA: :*.*;* as input
-RMS-E-FND, ACP file or directory lookup failed
-SYSTEM-F-INVLOGIN, login information invalid at remote node

However, you can access node MISHA by entering the command $DIR
MISHA"Username Password":: from node ETHQKE.
The system manager could also, by using AUTHORIZE, enable proxy
access for node ETHQKE by adding REMOTE_USER_FOO, as shown in
the following example:
$ SET DEF SYS$SYSTEM
$ RUN AUTHORI ZE
UAF> ADD/PROXY/DEFAULT ETHQKE: :REMCTE_USER_FOO LOCAL_USER
UAF> EXIT

Entering the command $ DIR MISHA:: from node ETHQKE would then
give user ETHQKE::REMOTE_USER_FOO access to remote node MISHA
by proxy; MISHA then associates this account with the account LOCAL_
USER on node MISHA.
The MIRROR object is used for loopback testing. To test your network
connection with VAX UETP you must create a default account for the
MIRROR object, if you did not create the default DECnet account.

The VPM object is used by the Monitor Utility in VAXcluster
configurations to obtain performance information about VAXc1uster
members. If your system is a member of a VAXcluster and the cluster
manager wants to use the Monitor Utility to collect such information, you
must create a default account for the VPM object, if you did not create the
default DECnet account.
8-3

VMS Version 5.2 Features

B.1 VMS Version 5.2 System Management Features

B.1.2.2

Security Benefits
The DECnet account provides default access for all incoming links
(unless this access is overridden by other forms of access control).
However, default accounts for any of the system objects named in the
NETCONFIG.COM procedure limit access to these objects. Default
accounts for selected objects, when used with other system security
facilities, enable a system or network manager to monitor these accounts
and to detect unauthorized access.

For each default account that you create, NETCONFIG.COM generates a
password and registers it in your network configuration database. Such
system-generated passwords are more secure than the passwords that
users typically create.
8.1.2.3

Questions Posed by NETCONFIG.COM
NETCONFIG.COM poses the following questions (the responses in
brackets are the default values):
Do you want a default DECnet account?

[NO] :

(The following question is asked only if you said YES to a default DECnet
account.)
Do you want default access to the TASK object disabled? [YES]:

(The following questions are asked regardless of whether you said YES or
NO to a default DECnet account.)
Do you want a default account for the MAIL object?

[YES] :

Do you want a default account for the FAL object?

[NO] :

Do you want a default account for the PHONE object?

[YES] :

Do you want a default account for the NML object?

[YES] :

(The following questions are asked only if you said NO to a default DEC net
account.)

8.1.3

Do you want a default account for the MIRROR object?

[YES] :

Do you want a default account for the VPM object?

[YES] :

New NETCONFIG_UPDATE.COM for Existing Networks
NETCONFIG_UPDATE.COM is a new command procedure for existing
networks that provides the same security enhancements for default access
that are provided by NETCONFIG.COM (see Section B.1.2). It also
provides a secondary procedure for modifying members of a VAXcluster.
Both procedures are described in the following sections.

o
B-4

VMS Version 5.2 Features

B.1 VMS Version 5.2 System Management Features

B.1.3.1

Benefits of NETCONFIG_UPDATE.COM
NETCONFIG_UPDATE.COM, unlike NETCONFIG.COM, configures
default access only. It performs no other network configuration. Therefore,
when you use NETCONFIG_UPDATE.COM to specify changes to default
access, everything else in the configuration database remains unchanged.

NETCONFIG_UPDATE.COM, like NETCONFIG.COM, generates
passwords for each account that you create for default access and for
any existing default accounts that you decide to keep in your configuration
database. For example, if you currently have a default account for MAIL
and decide to keep it, NETCONFIG.COM_UPDATE generates a new
password for it and replaces the existing password with the new one.

8.1.3.2

Using NETCONFIG_UPDATE.COM in a VAXcluster
NETCONFIG_UPDATE.COM provides a secondary procedure that
updates the default access of VAXcluster members. After you run
NETCONFIG_UPDATE.COM on one member of a VAXcluster, the
procedure detects that it is a VAXcluster member and instructs you to
run SYS$COMMON:[SYSMGRJUPDATE_CLUSTER_MEMBERS.COM on
the other VAXcluster members. This secondary procedure will modify the
default access of each VAXcluster member exactly as you modified that of
the first member.

With the SYSMAN Utility (see the VMS SYSMAN Utility Manual), you
can use the SET ENVIRONMENT/CLUSTER command to execute this
secondary procedure only once. The default access of all the remaining
VAXcluster members will be updated automatically.

8.1.4

Backup Utility (BACKUP)
This section describes the following new Backup Utility (BACKUP)
features:

8.1.4.1

•

Performance enhancements that cause BACKUP save and copy
operations to complete more quickly on systems that are configured
correctly

•

Faster cyclic redundancy checking (CRC) emulation for processors
that emulate CRC in software, resulting in a significant performance
enhancement for BACKUP on these processors

•

Support for the control character CtrllT, which returns information
about the online or standalone BACKUP operation in progress

Performance Enhancements
Version 5.2 of the Backup Utility includes a new method of scanning files
on the input disk. This new file-scanning method results in faster save
and copy operations on systems that are configured correctly. (It does not
improve BACKUP's performance during restore, compare, verify, or list
operations, however.) Prior to Version 5.2, disk head movement on the
input disk constrained the speed at which BACKUP could save or copy
files.

8-5

VMS Version 5.2 Features
B.1 VMS Version 5.2 System Management Features

To take full advantage of the new BACKUP file-scanning method, you
must change the values of certain user authorization file (UAF) and
System Generation Utility (SYSGEN) parameters. Sections B.1.4.2 and
B.1.4.3 specify which parameters you need to change.
B.1.4.2

Setting Up the BACKUP Account
BACKUP's new file-scanning method depends on the values of some user
authorization file (UAF) parameters of the account from which you perform
BACKUP operations. For example, if you perform BACKUP operations
from the SYSTEM account, the UAF parameters for the SYSTEM account
affect the way BACKUP performs. These UAF parameters define process
quotas, which are the amounts of system resources available to a process
created by the account. Digital recommends that you change the values
of these U AF parameters for the account you use to perform BACKUP
operations. See the VMS Authorize Utility Manual for more information
about modifying the values of UAF parameters.

(~\
~../

Table B-1 describes the UAF parameters that should be modified and
supplies values that provide the maximum amount of resources to
BACKUP. These values may not provide the best performance in all
cases, however. They are intended to be general guidelines.
Note: BACKUP bases its memory consumption on the WSQUOTA value,
not WSEXTENT.
Table B-1

UAF Process Quotas for the BACKUP Account

UAF Parameter

Meaning

Recommended Value

WSQUOTA

The number of pages of memory the working set of
the process can consume.

Equal to SYSGEN parameter
WSMAX

WSEXTENT

The absolute limit of physical memory allowed to the
process.

Equal to WSQUOTA

PGFLQUO

The number of pages of memory your process is
allowed in the page file.

Greater than or equal to
WSEXTENT

FILLM

The number of files that can be open simultaneously.
BACKUP scans this number of files at one time.

Equal to the SYSGEN parameter
CHANNELCNT

DIOLM

The number of direct I/O operations (usually disk
operations) that can be outstanding simultaneously.

Maximum of either (3 x FILLM) or
4096

ASTLM

The number of asynchronous system traps that can be
queued to the process simultaneously.

Maximum of either (3 x FILLM) or
4096

BIOLM

The maximum number of buffered I/O operations that
can be outstanding simultaneously.

Less than or equal to FILLM

BYTLM

The total number of bytes of memory that can be
outstanding for buffered I/O operations.

Greater than or equal to the
following value: (256 x FILLM) +
(6 x DIOLM)

ENQLM

The maximum number of locks that can be queued
simultaneously.

Greater than FILLM

Table B-2 lists a set of UAF parameter values that may be useful for your
configuration. You can choose to set the values for WSQUOTA and FILLM
lower than these values under the following circumstances:

B-6

c)
C)

VMS Version 5.2 Features

B.1 VMS Version 5.2 System Management Features

•

If your disks are highly fragmented, lower values prevent BACKUP
from becoming highly CPU-intensive.

•

If you use BACKUP during periods of heavy system use, lower values
prevent BACKUP from consuming too many system resources.

Note: If you decrease the values of UAF parameters other than
WSQUOTA and FILLM, use the ratios in Table B-1 to determine
appropriate values.
Alternatively, you can choose to set the values higher than these suggested
values if files are stored contiguously on your disks and if you perform
BACKUP operations during periods of light system use.

Table B-2

Suggested Values for UAF Process Quotas

UAF Parameter

Value

WSOUOTA

16,384

WSEXTENT

Greater than or equal to WSOUOTA

PGFLOUO

32,768

FILLM

128

DIOLM

4096

ASTLM

4096

BIOLM

128

BYTLM

65,536

ENOLM

256

After changing UAF parameters, log out of the BACKUP account and log
back in, allowing the new values of the UAF parameters to be used.

B.1.4.3

Setting System Generation Utility (SYSGEN) Parameters
For the new BACKUP file-scanning method to work efficiently, the System
Generation Utility (SYSGEN) parameters CHANNELCNT and WSMAX
must be set to appropriate values. If the account you use to perform
BACKUP operations has a FILLM value greater than the value of the
SYSGEN parameter CHANNELCNT, CHANNELCNT constrains the
number of files that can be opened at anyone time. If the WSQUOTA
value of the account is greater than the value of the SYSGEN parameter
WSMAX, WSMAX constrains the number of pages of memory that the
working set of the process can consume. See the VMS System Generation
Utility Manual for more information about changing the values of
SYSGEN parameters.

After changing SYSGEN parameters, shut down and reboot the system,
allowing the new values of the parameters to be used.

o
B-7

VMS Version 5.2 Features
B.1 VMS Version 5.2 System Management Features

B.1.4.4

Understanding Why the Output Device Seems Idle
Because BACKUP can scan many files at a time, it is possible that no data
will be sent to the output device for up to several minutes after the save or
copy operation begins. This does not indicate that BACKUP is performing
slowly or that your output device is not working correctly. Depending
on the values of the UAF parameters and the SYSGEN parameters,
BACKUP's new file-scanning method requires a certain amount of time
to become established. When the file-scanning is completed, BACKUP
sends the data to the output device more efficiently than it did before VMS
Version 5.2.

B.1.4.5

IBUFFER_COUNT Command Qualifier Is Now Obsolete
The new file-scanning method used by BACKUP makes the command
qualifier IBUFFER_COUNT obsolete. Previously, this command qualifier
specified the number of buffers used in a save, compare, or restore
operation to or from a tape. BACKUP now determines how many buffers
to use, depending on the amount of memory available to the account
performing the BACKUP operation and the number of files that account
can open simultaneously.

You can still specify the IBUFFER_COUNT qualifier, however, although
it has no effect. This ensures that command procedures written before
VMS Version 5.2 will still operate correctly. Digital recommends that you
remove the /BUFFER_COUNT qualifier from command procedures.
B.1.4.6

B.1.4.7

B-8

Cyclic Redundancy Checking Emulation Improvements
The method for performing cyclic redundancy checking (CRC) emulation is
now approximately 40% faster than the method used before VMS
Version 5.2. This is not a BACKUP-specific improvement, but it does
improve BACKUP performance on processors that emulate CRC in
software. BACKUP operations that use cyclic redundancy checking (CRC
is applied by default) now require significantly less time to complete on
the following processors, all of which emulate CRC in software:

•
•

MicroVAX IINAXstation II

•

MicroVAX 3200NAXstation 3200

•
•
•

MicroVAX 3500NAXstation 3500

MicroVAX 2000NAXstation 2000

MicroVAX 3600
VAX 6200

Pressing Ctri/T to Obtain Information About BACKUP Operations
Version 5.2 of the VMS operating system supplies an additional two lines
of information when you press Ctrlfr during an online or standalone
BACKUP operation. Ctrltr interrupts execution of the BACKUP
command, and displays three lines of information. The first line displays
information about the current process (node name, process name, system
time, currently running image, elapsed CPU time, page faults, direct
and buffered I/O operations, and pages in physical memory). The second
line displays information about BACKUP input. The third line displays
information about BACKUP output. For example, if you press Ctrl/T

VMS Version 5.2 Features

B.1 VMS Version 5.2 System Management Features

during a save operation, the second line displays the name of the last
file scanned by BACKUP and the third line displays the save-set volume
number, save-set block number, and the number of bytes in a block.
In order to use CtrllT, the command SET CONTROL=T must appear either
in the system login command procedure or in your personal login command
procedure. You can also enable CtrllT interactively by entering the DCL
command SET CONTROL=T.
The following example shows what happens when you press CtrllT during
a BACKUP save operation:
$ BACKUP/LOG DUAO: [M1SHA]*.COM;* MUAO:COMPROCS.BCK/REW1ND/LABEL=COMP
BACKUP-S-COPIED, copied DUAO: [M1SHA]A.COM;32
BACKUP-S-COP1ED, copied DUAO: [M1SHA]B.COM;30
BACKUP-S-COPIED, copied DUAO: [MISHA]C.COM;16

o
o

ICtrliTI

SQUASH::M1SHA 14:02:12 BACKUP
CPU=OO:OO.18.44 PF=2101 10=827 MEM=534
Last file scanned: DUAO: [NATASHA]D.DAT
Saveset volume: 1, saveset block: 35, (32256 byte blocks)
BACKUP-S-COPIED, copied DUAO: [M1SHA]D.COM;2
BACKUP-S-COPIED, copied DUAO: [M1SHA]E.COM;22

B.2

VMS Version 5.2 System Services Features
The VMS Version 5.2 operating system includes the following new system
services:
New Service

Function

$DEVICE_SCAN
$PROCESS_SCAN

Scan across the system for devices
Scan across the system or cluster for processes

The Device Scan system service, described in Section B.2.30, lets you
find the names of all devices that match a specified set of search criteria.
$DEVICE_SCAN can be used to produce a list of all disks, printers, or
terminals on the local node. After $DEVICE_SCAN has located device
information, you can use $GETDVI to further select the information, for
instance, to find the names of all mounted disks or all terminals running
at the same baud rate.

The Process Scan system service, described in Section B.2.30, lets you
scan for processes across the cluster. With the VMS Version 5.2 operating
system, any VMS process can now be seen or modified from any node in a
VAXcluster environment. Any system service that examines or modifies a
process is now capable of examining or controlling a process located on a
different node in the VAXcluster environment.

8-9

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

For Version 5.2 of the VMS operating system, processes are visible
clusterwide. As a result, significant changes have been made to the
following system services:
•

$CANWAK

•

$DELPRC

•

$FORCEX

•

$GETJPI

•

$RESUME

•

$SCHDWK

•

$SETPRI

•

$SUSPEND

•

$WAKE

Changes have also been made to the $GETUAI, $SETUAI, $MOUNT,
$DISMOUNT, and $MOD_IDENT system services. The following sections
describe the new and changed system services in more detail.

8.2.1

Modifications to $SETUAI and $GETUAI
VMS Version 5.2 includes the following changes to the $SETUAI and
$GETUAI system services:
•

New $SETUAI item codes
UAI$_PASSWORD
UAI$_PASSWORD2
UAI$_USER_DATA

•

New $SETUAI authorization flags
UAI$V_DISIMAGE
UAI$V_RESTRICTED

•

New $GETUAI item code
UAI$_USER_DATA

•

New $GETUAI authorization flags
UAI$V_DISIMAGE
UAI$V_RESTRICTED

o
8-10

VMS Version 5.2 Features

B.2 VMS Version 5.2 System Services Features

8.2.2

New Item Codes for $SETUAI and $GETUAI
The following new item codes have been added for the $SETUAI system
service:
New Item Code

Description

When you specify UAI$_PASSWORD, $SETUAI sets
the specified plaintext string as the primary password
of the user and updates the password change date.
When you specify UAI$_PASSWORD2, $SETUAI
sets the specified plaintext string as the secondary
password of the user and updates the password
change date.
When you specify UAI$_USER_DATA, $SETUAI sets
up to 255 bytes of information in the user data area of
the system user authorization file (SYSUAF).
This is the supported method for modifying the user
data area of the SYSUAF. Digital no longer supports
direct user modification of the SYSUAF.

To clear all information in the user data area of the
SYSUAF, specify $SETUAI with a buffer length of
zero.

The SYSPRV privilege is required to set any passwords (including the
password of the calling process) or to modify the user data with $SETUAI.
The UAI$_PASSWORD and UAI$_PASSWORD2 item codes provide the
building blocks for designing a site-specific SET PASSWORD utility. If
you create such a utility, you should set the LOCKPWD bit in the user
authorization file (UAF) to prevent users from using the SET PASSWORD
command and to prevent the LOGINOUT process from forcing password
changes. If you create a site-specific SET PASSWORD utility, install the
utility with SYSPRV privilege.
When specifying a password with UAI$_PASSWORD or UAI$_
PASSWORD2, adhere to the following guidelines:
•

The password must meet the minimum password length defined on the
system.

•

The password cannot exceed 32 characters in length.

•

The password must be different from the previous password.

To clear the primary or secondary password, specify UAI$_PASSWORD or
UAI$_PASSWORD2 with a buffer length of zero.
VMS Version 5.2 includes a new item code-UAI$_USER_DATA-for the
$GETUAI system service.

o
8-11

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

New Item Code

Description

When you specify UAI$_USER_DATA, $GETUAI
reads up to 255 bytes of information from the
user data area of the system user authorization
file (SYSUAF). You can read information written to
the user data area from previous versions of the VMS
operating system as long as the information adheres
to the guidelines described in the Guide to VMS
System Security.

8.2.3

New Authorization Flags for $SETUAI and $GETUAI
Two new authorization flags, UAI$V_DISIMAGE and UAI$V_
RESTRICTED, are used in the creation of captive and restricted user
accounts. (See the Guide to VMS System Security for a complete
description of these flags.) Use the $SETUAI system service to set the
flags for the specified user. Use the $GETUAI system service to determine
whether the specified flag is set. The new flags are represented as bits in
the UAI$_FLAGS item code with the following symbolic names:

8.2.4

New Authorization Flags

Description

UAI$V_DISIMAGE

When you specify UAI$V_DISIMAGE, the user cannot
issue the RUN or MCR commands or use the foreign
command mechanism in DCL.

UAI$V_RESTRICTED

Set the RESTRICTED flag (UAI$V_RESTRICTED) to
return the account to the level of security previously
specified by the CAPTIVE authorization flag in earlier
versions of the VMS operating system. (Under
VMS Version 5.2, the security of accounts with the
CAPTIVE flag set (UAI$_V_CAPTIVE) has been
increased by disallowing any access to the DCl
command level and disallowing use of the INQUIRE
verb in captive command procedures.)

o
o

Modifications to $MOUNT
The following flags have been added to the $MOUNT system service:

8-12

New Flag

Description

MNT$M_NOlABEl

The volume is to be mounted as a foreign volume;
a foreign volume is not Files-11 structured. If you
specify MNT$M_NOlABEl, the following item codes
can each appear in the item list only once: MNT$_
DEVNAM, MNT$_VOlNAM, and MNT$_lOGNAM. To
specify MNT$M_NOlABEl, the caller must either own
the volume or have VOlPRO privilege.

VMS Version 5.2 Features

c
c

B.2 VMS Version 5.2 System Services Features

8.2.5

New Flag

Description

MNT$M_NOREBUILD

The volume to be mounted should be returned to
active use immediately, without performing a rebuild
operation. If a disk volume is improperly dismounted
(such as during a system failure), you must rebuild
it to recover any caching limits that were enabled on
the volume at the time of the dismount. By default,
MOUNT attempts the rebuild. For a successful rebuild
operation that includes reclaiming all the available
free space, you must mount all of the volume set
members. Since the rebuild operation can take
a significant amount of time, specifying MNT$M_
NOREBUILD is recommended. The volume should
be rebuilt at a convenient time using the DeL SET
VOLUME/REBUILD command to recover the free
space.

MNT$M_NOUNLOAD

The volume to be mounted is not to be unloaded
when it is dismounted. Specifying MNT$M_
NOUNLOAD causes the volume to remain loaded
when it is dismounted unless the dismount explicitly
requests that the volume be unloaded.

Modifications to $DISMOUNT
VMS Version 5.2 includes the following changes to the $DISMOUNT
system service:
New Flag

Description

DMT$M_NOUNLOAD

Specifies that the volume is not to be physically
unloaded after the dismount. If both the DMT$M_
UNLOAD and DMT$M_NOUNLOAD flags are
specified, the DMT$M_NOUNLOAD flag is ignored.
If neither flag is specified, the volume is physically
unloaded, unless the DMT$M_NOUNLOAD flag was
specified on the $MOUNT system service or the
/NOUNLOAD qualifier was specified on the MOUNT
command when the volume was mounted.
Specifies that the volume should be dismounted
without checking for open files, spooled devices,
installed images, or installed swap and page files.

o
8-13

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

New Flag

Description
The specified device, rather than the entire volume
set, is dismounted.
Specifies that the volume is to be physically unloaded
after the dismount. If both the DMT$M_UNLOAD
and DMT$M_NOUNLOAD flags are specified, the
DMT$M_NOUNLOAD flag is ignored. If neither flag is
specified, the volume is physically unloaded, unless
the DMT$M_NOUNLOAD flag was specified on the
$MOUNT system service or the /NOUNLOAD qualifier
was specified on the MOUNT command when the
volume was mounted.

8.2.6

Modification to $MOD_IDENT
For Version 5.2 of the VMS operating system, the following status value
has been added to the list of Condition Values Returned:
The specified identifier name already exists in the rights
database.

8.2.7

Modifications to Existing System Services for Clusterwide Process
Accessibi lity

The following system services have been modified because a VMS process
is now visible clusterwide:
Modified Service

Function

$CANWAK

Cancel Wakeup

$DELPRC

Delete Process

$FORCEX

Force Image Exit

$GETJPI

Get Job/Process Information

$RESUME

Resume Process

$SCHDWK

Schedule Wakeup for Process

$SETPRI

Set Priority

$SUSPEND

Suspend Process

$WAKE

Wake Process

The descriptions of the pidadr and prcnam arguments have been
changed for these system services. The pidadr argument can now refer to
a process running on another node in the cluster. The process name can
now specify a node name as well as the process name. This full process
name can contain up to 23 characters.

8-14

C~i

VMS Version 5.2 Features

",\
C

B.2 VMS Version 5.2 System Services Features

)

In addition, these services now return the following status codes:
Status

Explanation
The remote node is running a version of VMS prior to
Version 5.2 and is unable to handle the request.

SS$_NOSUCHNODE

The specified node is not currently a member of the
cluster.
The remote node has insufficient resources to
respond to the request. (Bring this error to the
attention of your system manager.)

SS$_UNREACHABLE

c
8.2.8

Process Information Services
The VMS process information services enable you to gather information
about processes. You can obtain information about one process or a group
of processes on the local system or on remote nodes in a VAXcluster
system. DCL commands such as SHOW SYSTEM and SHOW PROCESS
use the process information services to display information about
processes. You can use these services within your programs.

c
o

The remote node is a member of the cluster but is not
accepting requests. (This is normal for a brief period
early in the system boot process.)

The following are process information system services:
•

Get JoblProcess Information ($GETJPl)

•

Process Scan ($PROCESS_SCAN)

For detailed information about $GETJPI, see the VMS System Services
Reference Manual. For detailed information about $PROCESS_SCAN, see
Section B.2.30.

8.2.9

Overview of $GETJPI and $GETJPI with $PROCESS_SCAN
$GETJPI was previously included with the process control system services.
However, because $GETJPI is used to obtain information about processes
rather than control processes, $GETJPI is now included with the process
information services.

$GETJPI returns information about processes. $GETJPI uses the PID
or the process name to obtain information about one process and the
-1 wildcard to obtain information about all processes. $GETJPI cannot
perform a selective search-it can only search for one process in the
cluster or for all processes on the local system. If you want to perform a
selective search for information or get information about processes across
the cluster, use $GETJPI with $PROCESS_SCAN.
$PROCESS_SCAN provides a process context that is used by $GETJPI
to return information about processes on the local system or across the
cluster. $PROCESS_SCAN can be used only with $GETJPI; it cannot
be used alone. The process context generated by $PROCESS_SCAN is

8-15

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

used by $GETJPI like the -1 wildcard, except that it is initialized by
calling the $PROCESS_SCAN service instead of by a simple assignment
statement. However, the $PROCESS_SCAN context is more powerful and
more flexible than the -1 wildcard. $PROCESS_SCAN uses an item list to
specify selection criteria to be used in a search for processes and produces
a context longword that describes a selective search for $GETJPI.
Vsing $GETJPI with $PROCESS_SCAN to perform a selective search is a
more efficient way to locate information because information is returned
only about the processes you have selected. For example, you can specify a
search for processes owned by one user name, and $GETJPI returns only
the processes that match the specified user name. You can specify a search
for all batch processes and $GETJPI returns information only about
processes running as batch jobs. You can specify a search for all batch
processes owned by one user name and $GETJPI returns information only
about processes owned by that user name that are running as batch jobs.

8.2.10 Using the Process 10 to Obtain Information
$GETJPI returns information about processes by using the process
identification (PID) or the process name. The PID is a 32-bit number
that is unique for each process in the cluster. Specify the PID by using the
pidadr argument. All the significant digits of a PID must be specified;
only leading zeros can be omitted.

()

It might be preferable to use the pidadr argument instead of the prcnam
argument when specifying a process to $GETJPI, for the following reasons:

•

The pidadr argument can be used to identify any process in the
system, whereas the prcnam argument can be used only to identify
processes that have the same VIC group number as the caller of
$GETJPI.

•

$GETJPI executes faster when you use pidadr rather than prcnam.
When you specify prcnam, $GETJPI must search a table of process
names and VICs for an entry that contains the specified process
name and the VIC group number of the calling process; this search is
unnecessary when you use pidadr.

C '\,
~~ ~

Table B-3 shows how $GETJPI operates given various values for the
prcnam and pidadr arguments.

c
8-16

VMS Version 5.2 Features

B.2 VMS Version 5.2 System Services Features

Table 8-3

Process Identification

Process
Name
Specified?

Process 10
Address
Specified?

Contents of
Process 10

Yes

The process identification of
the calling process is used and
returned.

Yes

Process 10

The process identification is used
and returned.

Yes

The process name is used and
the process identification is
returned.

Yes

Process 10

The process identification is used
and returned. The process name
is ignored.

The process identification of the
calling process is used, but is not
returned.

The process name is used.
The process identification is not
returned.

o
8.2.11

Resultant
Action
by Services

Using the Process Name to Obtain Information
To obtain information about a process using the process name, specify
the prcnam argument. Although a PID is unique for each process in
the cluster, a process name is unique (within a VIC group) only for each
process on a node. To locate information about processes on the local node,
specify a process name string of 1- to 15-characters. To locate information
about a process on a particular node, specify the full process name, which
can be up to 23 characters long. The full process name is configured in the
following way:
•

1 to 6 characters for the node name

•

2 characters for the colons (::) that follow the node name

•

1 to 15 characters for the local process name

Note that a local process name can look like a remote process name.
Therefore, if you specify ATHENS::SMITH, the system checks for a process
named ATHENS::SMITH on the local node before checking node ATHENS
for a process named SMITH.

See the VMS System Services Reference Manual for more information
about $GETJPI. See the Introduction to VMS System Services for more
information about process identification.

8-17

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

8.2.12 Modifications to $GETJPI
You can still use $GETJPI as you did before VMS Version 5.2. However,
the $GETJPI system service has been modified to work with $PROCESS_
SCAN. If you use $PROCESS_SCAN with $GETJPI, the process context
(pidctx) is used by $GETJPI as the pidadr.
$GETJPI has also been modified to include new status codes and new item
codes. The new status codes are described in Section B.2.7. The new item
codes are described in the following table:
Item Code

Function
10 of the CPU on which the process is running or on
which it last ran, returned as -1 if the system is not a
multiprocessor.

JPI$_GETJPLCONTROL_
FLAGS

Flags for options that control what actions $GETJPI
takes to retrieve the information (described in detail in
the Introduction to VMS System Services).

JPI$_NOOENAME

Name of the VAXcluster node on which the process is
running.
Cluster 10 of the VAXcluster node on which the
process is running.
VMS version number of the VAXcluster node on which
the process is running.

JPI$_STS2

Second longword of process status flags.

JPI$_TERMINAL

Now returns up to eight bytes of information, including
the colon (:) after the device name.
Access port name for the terminal associated with
the process. (The terminal name is returned by JPI$_
TERMINAL.) If the terminal is on a terminal server,
this item returns the terminal server name and the
name of the line port on the server. If the terminal is a
OECnet remote terminal, this item returns the source
system node name and the user name on the source
system. Otherwise, it returns a null string.

o
o

Physical device name of the terminal associated
with the process. This name is the same as JPI$_
TERMINAL unless virtual terminals are enabled, in
which case JPI$_TERMINAL returns the name of the
virtual terminal and JPI$_TT_PHYOEVNAM returns
the name of the physical terminal. If JPI$_TERMINAL
is null, or if the virtual terminal is disconnected from
the physical terminal, JPI$_TT_PHYDEVNAM returns
a null string.

8.2.13

Using $GETJPI Alone
Using $GETJPI without $PROCESS_SCAN limits you to obtaining
information about one process at a time or information about all processes
on the local system. To obtain information about one process (either a
local or a remote process), specify the PID or the process name. To obtain
8-18

. ...

VMS Version 5.2 Features

B.2 VMS Version 5.2 System Services Features

information about all processes on the local system, use the -1 wildcard
as the pidadr. If no PID or process name is specified, $GETJPI returns
information about the calling process.

8.2.14 Requesting Information About a Single Process
Example B-1 is a FORTRAN program that displays the process name and
the PID of the calling program.
Example 8-1

Using $GETJPI to Obtain Information About the Calling Process

No process name or PID is specified; $GETJPI returns data on the
calling process.
PROGRAM CALLING PROCESS
Implicit none

IMPLICIT NONE

INCLUDE ' ($ jpidef)

/nolist'

Definitions for $GETJPI

INCLUDE' ($ssdef)

/nolist'

System status codes

STRUCTURE /JPIITMLST/
UNION
MAP
INTEGER*2 BUFLEN,
2
CODE
INTEGER*4 BUFADR,
RETLENADR
2
END MAP
MAP
INTEGER*4 END LIST
END MAP
END UNION
END STRUCTURE
RECORD /JPIITMLST/
2
JPILIST(3)

Declare the item list for
$GETJPI

INTEGER*4 SYS$GETJPIW

System service entry points

INTEGER*4 STATUS,
2
PID

Status variable
PID from $GETJPI

INTEGER*2 IOSB(4)

I/O status block for $GETJPI

CHARACTER*16
2
PRCNAM
INTEGER*2 PRCNAM LEN
! Initialize $GETJPI item list

Process name from $GETJPI
Process name length

JPILIST(l) .BUFLEN
JPILIST(l) .CODE
JPILIST(l) . BUFADR
JPILIST(l) .RETLENADR
JPILIST(2) . BUFLEN
JPILIST(2) .CODE
JPILIST(2) .BUFADR
JPILIST(2) .RETLENADR
JPILIST(3) . END_LIST

Structure declaration for
$GETJPI item lists

A longword of 0 terminates
an item list

JPI$ _PID
%LOC(PID)

LEN (PRCNAM)
JPI$_PRCNAM
%LOC(PRCNAM)
%LOC(PRCNAM_LEN)

(continued on next page)

8-19

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

Example 8-1 (Cont.)

Using $GETJPI to Obtain Information About the Calling Process

! Call $GETJPI to get data for this process
STATUS

SYS$GETJPIW

%VAL (1) ,

Event flag 1
No PID
No process name
2
JPILIST,
Item list
2
Always use rOSB with $GETJPI!
2
IOSB,
No AST
2
2
No AST arg
Check the status in both STATUS and the IOSB, if
STATUS is OK then copy IOSB(I) to STATUS
2

IF (STATUS) STATUS

IOSB(l)

! If $GETJPI worked, display the process, if done then
! prepare to exit, otherwise signal an error

1010

IF (STATUS) THEN
TYPE 1010, PID, PRCNAM(l:PRCNAM_LEN)
FORMAT (' ',Z8.8,'
',A)
ELSE
CALL LIB$SIGNAL(%VAL(STATUS))
END IF
END

Example B-2 demonstrates (in FORTRAN) how to use the process name
to obtain information about a process.
Example 8-2

Using $GETJPI and the Process Name to Obtain Information About a Process

To find information for a particular process by name,
substitute this code, which includes a process name,
to call $GETJPI in Example B-1
Call $GETJPI to get data for a named process
STATUS

C-'"
I ...

SYS$GETJPIW

2
2
2
2
2
2
2

8.2.15

%VAL(l),
'SMITH_I',
JPILIST,
IOSB,

)

Event flag 1
No PID
Process name
Item list
Always use IOSB with $GETJPI!
No AST
No AST arg

Requesting Information About All Processes on the Local System
You can use $GETJPI to perform a wildcard search on all processes on
the local system. When the pidadr argument is specified as -1, $GETJPI
returns requested information for each process that the program has
privilege to access. The requested information is returned for one process
for each call to $GETJPI.

8-20

VMS Version 5.2 Features

B.2 VMS Version 5.2 System Services Features

To perform a wildcard search, call $GETJPI in a loop, testing the return
status.
When performing wildcard searches, $GETJPI returns an error status for
processes that are inaccessible. When a program that uses a -1 wildcard
checks the status value returned by $GETJPI, it should test for the
following status codes:

Status

Explanation

SS$_NOMOREPROC

All processes have been returned.

SS$_NOPRIV

The caller lacks sufficient privilege to examine a
process.

SS$_SUSPENDED

The target process is being deleted or is suspended
and cannot return the information.

Example B-3 is a MACRO program that demonstrates how to use the
$GETJPI -1 wildcard to search for all processes on the local system.
Example 8-3

Using $GETJPI to Request Information About All Processes on the Local System

.TITLE

o
o

WILDJPI - Wildcard $GETJPI example program

$JPIDEF

; Define $GETJPI item codes

.PSECT

DATA

RD,WRT,NOEXE

IOSB:
PID:

. QUAD
. LONG

-1

Completion status
Wildcard PID initialized to -1

ITEMS:

. WORD
. WORD
.ADDRESS
.ADDRESS
.LONG

32
JPI$ USERNAME
UNAME
UNAMESIZ
0

Size of user name buffer
User name item code
Address of user name buffer
Address to return user name size
End of list

UNAMEDSC:
UNAMESIZ:

.LONG
0
.ADDRESS UNAME

Length and address form a string
descriptor for LIB$PUT_OUTPUT
Buffer for size of user name
Address of user name buffer

UNAME:

.BLKB

User name buffer

.PSECT

CODE

. ENTRY

START, "'M<>

EXE,NOWRT

(continued on next page)

o
8-21

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

Example 8-3 (Cont.)

Using $GETJPI to Request Information About All Processes on the Local
System

LOOP:

$GETJPIW_S EFN=#l, PIDADR=PID, ITMLST=ITEMS, IOSB=IOSB
BLBC
RO,10$
MOVZWL
IOSB,RO

10$:

BLBS

RO,DISPLAY

CMPW
BEQL
CMPW
BEQL
CMPW
BEQL
BRB

RO,#SS$_NOPRIV
LOOP
RO,#SS$ SUSPENDED
LOOP
RO,#SS$_NOMOREPROC
DONE
ERROR

Get information and wait
- use event flag 1
- use wildcard pid
- address of item list
- always use IOSB for status check
If failure in RO, check that status
If success in RO, then move status
from IOSB to RO for checks
If success in both RO and IOSB,
then display this user name
No privilege for this process?
If no privilege, try next process
Process suspended?
If yes, try next process
No more processes?
If yes, finished
Otherwise, exit with error code in RO

DISPLAY:

PUSHAL
CALLS
BRB

UNAMEDSC
#l,G"LIB$PUT- OUTPUT
LOOP

Pass address of the user name descriptor
Display name on SYS$OUTPUT
Get the next process

DONE:
ERROR:

MOVL
$EXIT_S

#SS$_NORMAL,RO
RO

Put success status into RO
Exit with status in RO

.END

START

8.2.16 Using $GETJPI with $PROCESS_SCAN
Using the $PROCESS_SCAN system service greatly enhances the power
of $GETJPI. With this combination, you can search for selected groups of
processes as well as processes on remote nodes. When you use $GETJPI
alone, you specify the pidadr or the prcnam to locate information about
one process. When you use $GETJPI with $PROCESS_SCAN, the pidctx
generated by $PROCESS_SCAN is used as the pidadr argument to
$GETJPI. This process context allows $GETJPI to use the selection
criteria set up in the call to $PROCESS_SCAN.

8.2.17

Using the $PROCESS_SCAN Item List and Item-Specific Flags
$PROCESS_SCAN uses an item list to specify the selection criteria for the
$GETJPI search.
Each entry in the $PROCESS_SCAN item list contains the following:

8-22

•

The attribute of the process to be examined

•

The value of the attribute or a pointer to the value

•

Item-specific flags to control how to interpret the value

VMS Version 5.2 Features

B.2 VMS Version 5.2 System Services Features

Item-specific flags enable you to control selection information. For
example, you can use flags to select only those processes that have
attribute values that compare to the value in the item list in the following
ways:

Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL
PSCAN$M_NEQ
PSCAN$M_GEQ
PSCAN$M_GTR
PSCAN$M_LEQ
PSCAN$M_LSS
PSCAN$M_CASE_BLIND
PSCAN$M_PREFIX_MATCH
PSCAN$M_WILDCARD

Match this value or the next value
Match value exactly (the default)
Match if value is not equal
Match if value is greater than or equal to
Match if value is greater than
Match if value is less than or equal to
Match if value is less than
Match without regard to case of letters
Match on the leading substring
Match string is a wildcard pattern

The PSCAN$M_OR flag is used to connect identical item codes in an item
list. For example, in a program that searches for processes owned by
several specified users, each user name must be specified in a separate
item list entry. The item list entries are connected with the PSCAN$M_
OR flag as in the following FORTRAN example:
PSCANLIST(l) .BUFLEN
LEN('SMITH')
PSCANLIST(l) . CODE
PSCAN$_USERNAME
PSCANLIST(l) .BUFADR
%LOC('SMITH')
PSCANLIST(l) .ITMFLAGS = PSCAN$M_OR
PSCANLIST(2) .BUFLEN
= LEN('JONES')
PSCANLIST(2) .CODE
= PSCAN$_USERNAME
PSCANLIST(2) .BUFADR
= %LOC('JONES')
PSCANLIST(2) .ITMFLAGS = PSCAN$M_OR
PSCANLIST(3) .BUFLEN
= LEN('JOHNSON')
PSCANLIST(3) .CODE
= PSCAN$_USERNAME
PSCANLIST(3) . BUFADR
%LOC('JOHNSON')
PSCANLIST(3) .ITMFLAGS = 0
PSCANLIST(4) . END_LIST = 0

Use the PSCAN$M_WILDCARD flag to specify that a character string
is to be treated as a wildcard. For example, if you want to search for
all process names that begin with the letter A and end with the string
ER, use the string A *ER with the PSCAN$M_WILDCARD flag. If the
PSCAN$M_WILDCARD flag is not specified, the search looks for the
4-character process name A *ER.

The PSCAN$M_PREFIX_MATCH defines a wildcard search to match the
initial characters of a string. For example, to find all process names that
start with the letters AB, use the string AB with the PSCAN$M_PREFIX_
MATCH flag. If you do not specify the PSCAN$M_PREFIX_MATCH flag,
the search looks for a process with the 2-character process name AB.

8-23

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

The PSCAN$M_PREFIX_MATCH flag also allows either the PSCAN$M_
EQL or the PSCAN$M_NEQ flag to be specified. If you specify PSCAN$M_
NEQ, the service matches those names that do not begin with the specified
character string.

8.2.18

Requesting Information About Processes That Match One Criterion
You can use $GETJPI with $PROCESS_SCAN to search for processes
that match an item list with one criterion. For example, if you specify a
search for processes owned by one user name, $GETJPI returns only those
processes that match the specified user name.
Example B-4 demonstrates (in FORTRAN) how to perform a $PROCESS_
SCAN search on the local node to select all processes that are owned by
user SMITH.
Example 8-4

Using $GETJPI and $PROCESS_SCAN to Select Process Information by User
Name

PROGRAM PROCESS SCAN
IMPLICIT NONE

Implicit none

INCLUDE' ($jpidef)
/nolist'
INCLUDE '($pscandef) /nolist'
INCLUDE' ($ssdef)
/nolist'

Definitions for $GETJPI
Definitions for $PROCESS_SCAN
Definitions for SS$_NAMES

STRUCTURE /JPIITMLST/
UNION
MAP
INTEGER*2 BUFLEN,
CODE
2
INTEGER*4 BUFADR,
RETLENADR
2
END MAP
MAP
INTEGER*4 END LIST
END MAP
END UNION
END STRUCTURE
STRUCTURE /PSCANITMLST/
UNION
MAP
INTEGER*2 BUFLEN,
CODE
2
INTEGER*4 BUFADR,
2
ITMFLAGS
END MAP
MAP
INTEGER*4 END LIST
END MAP
END UNION
END STRUCTURE

Structure declaration for
$GETJPI item lists

A longword of 0 terminates
an item list

Structure declaration for
$PROCESS SCAN item lists

A longword of 0 terminates
an item list

(continued on next page)

8-24

VMS Version 5.2 Features

B.2 VMS Version 5.2 System Services Features

Example 8-4 (Cont.)

()

Using $GETJPI and $PROCESS_SCAN to Select Process Information by
User Name

RECORD /PSCANITMLST/
2
PSCANLIST(12)

Declare the item list for
$PROCESS SCAN

RECORD /JPIITMLST/
2
JPILIST(3)

Declare the item list for
$GETJPI

INTEGER*4 SYS$GETJPIW,
2
SYS$PROCESS SCAN

System service entry points

INTEGER*4 STATUS,
2
CONTEXT,
2
PID

Status variable
Context from $PROCESS SCAN
PID from $GETJPI

INTEGER*2 IOSB(4)

I/O status block for $GETJPI

CHARACTER*16
2
PRCNAM
INTEGER*2 PRCNAM LEN

Process name from $GETJPI
Process name length

LOGICAL*4 DONE

Done with data loop

!********************************************
!* Initialize item list for $PROCESS_SCAN *
!********************************************
! Look for processes owned by user SMITH

LEN (' SMITH' )
PSCANLIST(l) .BUFLEN
PSCANLIST(l) .CODE
PSCAN$ USERNAME
PSCANLIST(l) . BUFADR
%LOC (' SMITH' )
PSCANLIST(l) .ITMFLAGS
o
PSCANLIST(2) .END LIST
o
!********************************************
End of item list initialization
!*
*
!********************************************
STATUS

2
2

SYS$PROCESS SCAN (
CONTEXT,
PSCANLIST)

Set up the scan context

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

! Loop calling $GETJPI with the context
DONE = .FALSE.
DO WHILE (.NOT. DONE)
Initialize $GETJPI item list
JPILIST(l) . BUFLEN
JPILIST(l) .CODE
JPILIST(l) . BUFADR
JPILIST(l) .RETLENADR
JPILIST(2) .BUFLEN
JPILIST(2) .CODE
JPILIST(2) . BUFADR
JPILIST(2) .RETLENADR
JPILIST(3) . END_LIST

JPI$ PID
%LOC(PID)

LEN (PRCNAM)
JPI$_PRCNAM
%LOC(PRCNAM)
%LOC(PRCNAM_LEN)

o
(continued on next page)

8-25

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

Example 8-4 (Cont.)

Using $GETJPI and $PROCESS_SCAN to Select Process Information by
User Name

Call $GETJPI to get the next SMITH process
STATUS
2

2
2

2
2
2
2

SYS$GETJPIW (
%VAL(l),
CONTEXT,

Event flag 1
Process context
No process name
JPILIST,
Item list
IOSB,
Always use IOSB with $GETJPI!
No AST
No AST arg
Check the status in both STATUS and the IOSB, if
STATUS is OK then copy IOSB(l) to STATUS
IF (STATUS) STATUS

IOSB(l)

If $GETJPI worked, display the process, if done then
prepare to exit, otherwise signal an error
IF (STATUS) THEN
TYPE 1010, PID, PRCNAM(l:PRCNAM_LEN)
FORMAT (' ',Z8.8,'
',A)
ELSE IF (STATUS .EQ. SS$_NOMOREPROC) THEN
DONE = .TRUE.
ELSE
CALL LIB$SIGNAL(%VAL(STATUS))
END IF

1010

END DO
END

8.2.19 Requesting Information About Processes That Match Multiple Values
for One Criterion
$PROCESS_SCAN can also search for processes that match one of a
number of values for a single criterion, for example, processes owned by
several specified users.

C-)~\

Each value must be specified in a separate item list entry, and the item
list entries must be connected with the PSCAN$M_OR item-specific flag.
$GETJPI selects each process that matches any of the item values.
For example, to look for processes with user names SMITH, JONES,
or JOHNSON, substitute FORTRAN code such as that shown in
Example B-5 to initialize the item list in Example B-4.

o
8-26

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

c
Example 8-5

Using $GETJPI and $PROCESS_SCAN with Multiple
Values for One Criterion

!********************************************
!* Initialize item list for $PROCESS_SCAN *
!********************************************
! Look for users SMITH, JONES and JOHNSON

PSCANLIST(l) .BUFLEN
PSCANLIST(l) .CODE
PSCANLIST(l) .BUFADR
PSCANLIST(l) .ITMFLAGS
PSCANLIST(2) .BUFLEN
PSCANLIST(2) .CODE
PSCANLIST(2) .BUFADR
PSCANLIST(2) .ITMFLAGS
PSCANLIST(3) .BUFLEN
PSCANLIST(3) .CODE
PSCANLIST(3) .BUFADR
PSCANLIST(3) .ITMFLAGS
PSCANLIST(4) .END_LIST

LEN (' SMITH' )
PSCAN$_USERNAME
%LOC (' SMITH' )
PSCAN$M_OR
LEN (' JONES' )
PSCAN$_USERNAME
%LOC (' JONES' )
PSCAN$M_OR
LEN (' JOHNSON' )
PSCAN$_USERNAME
%LOC (' JOHNSON' )

o
o

!********************************************
End of item list initialization
!*
*
!********************************************

8.2.20 Requesting Information About Processes That Match Multiple Criteria
$PROCESS_SCAN can be used to search for processes that match values
for more than one criterion. When multiple criteria are used, a process
must match at least one value for each specified criterion.
Example B-6 demonstrates (in FORTRAN) how to find any batch process
owned by either SMITH or JONES. The program uses syntax similar to
the following logical expression to initialize the item list:
«username

= "SMITH") OR (username = "JONES"))
AND
(MODE

JPI$K_BATCH)

c
8-27

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

Example 8-6

Selecting Processes That Match Multiple Criteria

!********************************************
!* Initialize item list for $PROCESS SCAN *
!********************************************
! Look for BATCH jobs owned by users SMITH and JONES

PSCANLIST(l) . BUFLEN
PSCANLIST(l) .CODE
PSCANLIST(l) .BUFADR
PSCANLIST(l) .ITMFLAGS
PSCANLIST(2) .BUFLEN
PSCANLIST(2) .CODE
PSCANLIST(2) .BUFADR
PSCANLIST(2) .ITMFLAGS
PSCANLIST(3) . BUFLEN
PSCANLIST(3) .CODE
PSCANLIST(3) . BUFADR
PSCANLIST(3) .ITMFLAGS
PSCANLIST(4) .END LIST

LEN (' SMITH' )
PSCAN$ USERNAME
%LOC (' SMITH' )
PSCAN$M_OR
LEN (' JONES' )
PSCAN$_USERNAME
%LOC (' JONES' )

o
o
PSCAN$ MODE
JPI$K_BATCH

o
o

!********************************************
End of item list initialization
!*
*
!********************************************

See Section B.2.30 for more information about $PROCESS_SCAN item
codes and flags.

8.2.21

Specifying a Node as Selection Criterion
Several $PROCESS_SCAN item codes do not refer to attributes of a
process, but to the VAXcluster node on which the target process resides.
When $PROCESS_SCAN encounters an item code that refers to a node
attribute, it creates an alphabetized list of node names. $PROCESS_SCAN
then directs $GETJPI to compare the selection criteria against processes
on these nodes.
$PROCESS_SCAN ignores a node specification if it is running on a node
that is not part of a VAXcluster system. For example, if you request
that $PROCESS_SCAN select all nodes with the hardware model name
"VAX 6360," this search returns information about local processes on a
nonclustered system, even if that system is a MicroVAX.
A remote $GETJPI operation currently requires the system to send a
message to the CLUSTER_SERVER process on the remote node. The
CLUSTER_SERVER process then collects the information and returns
it to the requesting node. This has several implications for clusterwide
searches:
•

8-28

All remote $GETJPI operations are asynchronous and must be
properly synchronized. Many applications that are not correctly
synchronized might seem to work on a single node because some
$GETJPI operations are actually synchronous; however, these
applications fail if they attempt to examine processes on remote nodes.
For more information on how to synchronize $GETJPI operations,

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

see the section on synchronizing system service completion in the
Introduction to VMS System Services.
•

The CLUSTER_SERVER process is always a current process because
it is executing on behalf of $GETJPI.

•

Attempts by $GETJPI to examine a node do not succeed during a brief
period between the time a node joins the cluster and the time that the
CLUSTER_SERVER process is started. Searches that occur during
this period skip such a node. Searches that specify only such a booting
node fail with a $GETJPI status of SS$_UNREACHABLE.

•

SS$_NOMOREPROC is returned after all processes on all specified
nodes have been scanned.

8.2.22 Scanning All Nodes on the Cluster for Processes
$PROCESS_SCAN can scan the entire cluster for processes. For example,
to scan the cluster for all processes owned by SMITH, use FORTRAN code
like that in Example B-7 to initialize the item list to find all processes
with a nonzero cluster system identifier (CSID) and a user name of
SMITH.

Example 8-7 Searching the Cluster for Process Information
!********************************************
!* Initialize item list for $PROCESS SCAN *
!********************************************
! Search the cluster for jobs owned by SMITH

PSCANLIST(l) . BUFLEN
PSCANLIST(l) .CODE
PSCANLIST(l) .BUFADR
PSCANLIST(l) .ITMFLAGS
PSCANLIST(2) . BUFLEN
PSCANLIST(2) .CODE
PSCANLIST(2) .BUFADR
PSCANLIST(2) .ITMFLAGS
PSCANLlST(3) .END_LIST

o
PSCAN$_NODE CSID

o
PSCAN$M_NEQ
LEN (' SMITH' )
PSCAN$_USERNAME
%LOC (' SMITH' )

!********************************************
End of item list initialization
!*
*
!********************************************

8.2.23 Scanning Specific Nodes on the Cluster for Processes
You can specify a list of nodes as well. Example B-8 demonstrates (in
FORTRAN) how to design an item list to search for batch processes on the
nodes TIGNES, VALTHO, or 2ALPES.

o
8-29

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

Example 8-8

Searching for Process Information on Specific Nodes in the Cluster

!********************************************
!*

Initialize item list for $PROCESS_SCAN

!********************************************

! Search for BATCH jobs on nodes TIGNES, VALTHO and 2ALPES

PSCANLIST(l) .BUFLEN
PSCANLIST(l) .CODE
PSCANLIST(l) .BUFADR
PSCANLIST(l) .ITMFLAGS
PSCANLIST(2) . BUFLEN
PSCANLIST(2) .CODE
PSCANLIST(2) . BUFADR
PSCANLIST(2) .ITMFLAGS
PSCANLIST(3) . BUFLEN
PSCANLIST(3) .CODE
PSCANLIST(3) .BUFADR
PSCANLIST(3) .ITMFLAGS
PSCANLIST(4) . BUFLEN
PSCANLIST(4) .CODE
PSCANLIST(4) . BUFADR
PSCANLIST(4) .ITMFLAGS
PSCANLIST(5) .END LIST

LEN (' TIGNES' )
PSCAN$_NODENAME
%LOC (' TIGNES' )
PSCAN$M_OR
LEN (' VALTHO' )
PSCAN$_NODENAME
%LOC (' VALTHO' )
PSCAN$M_OR
LEN ( , 2ALPES' )
PSCAN$_NODENAME
%LOC (' 2ALPES')

o
o
PSCAN$_MODE
JPI$K_BATCH

o
o

!********************************************
End of item list initialization
!*
*
!********************************************

8.2.24 Conducting Multiple Simultaneous Searches with $PROCESS_SCAN
Only one asynchronous remote $GETJPI request per $PROCESS_SCAN
context is permitted at a time. If you issue a second $GETJPI request
using a context before a previous remote request using the same context
has completed, your process stalls in a resource wait until the previous
remote $GETJPI request completes. This stall in the RWAST state
prevents your process from executing in user mode or receiving user-mode
ASTs.

If you want to run remote searches in parallel, create multiple contexts
by calling $PROCESS_SCAN once for each context. For example, you can
design program that calls $GETSYI in a loop to find the nodes in the
VAXcluster system and creates a separate $PROCESS_SCAN context for
each remote node. Each of these separate contexts can run in parallel.
The bc~ command SHOW USERS uses this technique to obtain user
information more quickly~

Only requests to remote nodes must wait until the previous search using
the same context has completed: If the $PROCESS_SCAN context specifies
the local node, any number of $GETJPI requests using that context can
be executed in parallel (within the limits implied by the process quotas for
ASTLM and BYTLM).

Note: When you use $GETJPI to reference remote processes, you
must properly synchronize all $GETJPI calls. See the section
on asynchronous service completion in the Introduction to VMS

8-30

VMS Version 5.2 Features

B.2 VMS Version 5.2 System Services Features

System Services. Before VMS Version 5.2, if you did not follow
these synchronization rules, your programs might have appeared
to run correctly. However, if you attempt to run such improperly
synchronized programs using $GETJPI with $PROCESS_SCAN
with a remote process, your program might attempt to use the
dat,a before $GE'fJPI has returned it.
To perform a synchronous search in which the program waits until
all requested information is available, use $GETJPIW with an IOSB
argument.

Programming Considerations for GETJPI$

The following sections describe some important considerations for
programming with $GETJPI.

8.2.26 Using Item Lists Correctly

o
c

When, $GETJPI collects data, it makes multiple passes through the item
list. If the item list is self-modifying (that is, if the addresses for the
output buffers in the item list point back at the item list), $GETJPI
replaces the item list information with the returned data. Therefore,
incorrect data might be read or unexpected errors might occur when
$GETJPI reads the item list again.
The number of passes needed by $GETJPI depends on which item codes
are referenced and the state of the target process. A program that appears
to work normally might fail when a system has processes that are swapped
out of memory or when a process is on a remote node.
The results from $GETJPI are unpredictable when an item list has buffer
pointers that point back at the item list itself. To prevent confusing errors,
Digital recommends that you do not use self-modifying item lists.

8.2.27 Improvin~ Performance by Using Buffered $GETJPI Operations
To request information about a process located on a remote node, $GETJPI
must send a message to the remote node, wait for the response, and then
extract the data from the message received. When you perform a search
on a remote system, the program must repeat this sequence for each
process that $GETJPI locates.
To reduce the overhead of such a remote search, use $PROCESS_SCAN
with the PSCAN$_GETJPI_BUFFER_SIZE item code to specify a buffer
size for $GETJPI. When the buffer size is specified by'$PROCESS_SCAN,
$GETJPI packs informatIon for several processes into one buffer and
transmits them in a single message. This reduction in the number of
messages improves performance.

For example, if the $GETJPI item list requests 100 bytes of information,
you might specify a PSCAN$_GETJPI_BUFFER_SIZE of 1000 bytes
so that the service can place information for at least 10 processes in
each message. ($GETJPI does not send fill data in the message buffer;

8-31

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

therefore, it is possible that information for more than 10 processes can be
packed into the buffer.)

The $GETJPI buffer must be large enough to hold the data for at least
one process. If the buffer is too small, the error code SS$_IVBUFLEN is
returned from the $GETJPI call.
You do not have to allocate space for the $GETJPI buffer; buffer space
is allocated by $PROCESS_SCAN as part of the search context that it
creates. Because $GETJPI buffering is transparent to the program that
calls $GETJPI, you do not have to modify the loop that calls $GETJPI.
If you use PSCAN$_GETJPI_BUFFER_SIZE with $PROCESS_SCAN,
all calls to $GETJPI using that context must request the same item code
information. Because $GETJPI collects information for more than one
process at a time within its buffers, you cannot change the item codes
or the lengths of the buffers in the $GETJPI item list between calls.
$GETJPI returns the error SS$_BADPARAM if any item code or buffer
length changes between $GETJPI calls. However, you can change the
buffer addresses in the $GETJPI item list from call to call.
The $GETJPI buffered operation is not used for searching the local node.
When a search specifies both multiple nodes and $GETJPI buffering,
the buffering is used on remote nodes but is ignored on the local node.
Example B-9 demonstrates (in FORTRAN) how to use a $GETJPI buffer
to improve performance.
Example 8-9

Using a $GETJPI Buffer to Improve Performance

!********************************************
!* Initialize item list for $PROCESS SCAN *
!********************************************
! Search for jobs owned by users SMITH and JONES
! across the cluster with $GETJPI buffering

PSCANLIST(l) . BUFLEN
PSCANLIST(l) .CODE
PSCANLIST(l) .BUFADR
PSCANLIST(l) .ITMFLAGS
PSCANLIST(2) .BUFLEN
PSCANLIST(2) .CODE
PSCANLIST(2) .BUFADR
PSCANLIST(2) .ITMFLAGS
PSCANLIST(3) .BUFLEN
PSCANLIST(3) .CODE
PSCANLIST(3) .BUFADR
PSCANLIST(3) .ITMFLAGS
PSCANLIST(4) . BUFLEN
PSCANLIST(4) .CODE
PSCANLIST(4) . BUFADR
PSCANLIST(4) .ITMFLAGS
PSCANLIST(5) . END_LIST

o
PSCAN$_NODE_CSID

o
PSCAN$M_NEQ
LEN (' SMITH' )
PSCAN$_USERNAME
%LOC (' SMITH' )
PSCAN$M_OR
LEN (' JONES' )
PSCAN$_USERNAME
%LOC (' JONES' )

o
o
PSCAN$ GETJPI BUFFER SIZE
1000

o
o

!********************************************
End of item list initialization
!*
*
!********************************************

B-32

VMS Version 5.2 Features

B.2 VMS Version 5.2 System Services Features

8.2.28 Meeting Remote $GETJPI Quota Requirements
A remote $GETJPI request uses system dynamic memory for messages.
System dynamic memory uses the process quota BYTLM. To determine the
number of bytes required by a $GETJPI request:
1

Add:
•

The size of the $PROCESS_SCAN item list

• The total size of all reference buffers for $PROCESS_SCAN (the
sum of all buffer length fields in the item list)

C\
./

•

The size of the $GETJPI item list

•
•
•

The size of the $GETJPI buffer
The size of the calling process RIGHTSLIST
Approximately 300 bytes for message overhead

Double this total.

The total is doubled because the messages consume system dynamic
memory on both the sending node and the receiving node.

This formula for BYTLM quota applies to both buffered and nonbuffered
$GETJPI requests. For buffered requests, use the value specified in the
$PROCESS_SCAN item, PSCAN$_GETJPI_BUFFER_SIZE, as the size
of the buffer. For nonbuffered requests, use the total length of all data
buffers specified in the $GETJPI item list as the size of the buffer.
If the BYTLM quota is insufficient, $GETJPI (not $PROCESS_SCAN)
returns the error SS$_EXBYTLM.

8.2.29 Using $GETJPI Control Flags
The JPI$_GETJPI_CONTROL_FLAGS item code, which is specified in the
$GETJPI item list, provides additional control over $GETJPI. Therefore,
$GETJPI might be unable to retrieve all the data requested in an item
list because JPI$_GETJPI_CONTROL_FLAGS requests that $GETJPI
not perform certain actions that may be necessary to collect the data. For
example, a $GETJPI control flag might instruct the calling program not to
retrieve a process that has been swapped out of the balance set.
If $GETJPI is unable to retrieve any data item because of the restrictions
imposed by the control flags, it returns the data length as zero. To verify
that $GETJPI received a data item, examine the data length to be sure
that it is not zero. To make this verification possible, be sure to specify
the return length for each item in the $GETJPI item list when any of the
JPI$_GETJPI_CONTROL_FLAGS flags is used.

Unlike other $GETJPI item codes, the JPI$_GETJPI_CONTROL_FLAGS
item is an input item. The item list entry should specify a longword buffer.
The desired control flags should be set in this buffer.

8-33

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

Because the JPI$_GETJPI_CONTROL_FLAGS item code tells $GETJPI
how to interpret the item list, it must be the first entry in the $GETJPI
item list. The error code SS$_BADPARAM is returned if it is not the first
item in the list.
The following are the $GETJPI control flags:
JPI$M_NO_TARGET_I NSWAP

When JPI$M_NO_TARGET_INSWAP is specified, $GETJPI does not
retrieve a process that has been swapped out of the balance set. JPI$M_
NO_TARGET_INSWAP is used to avoid adding the additional load of
swapping processes into a system. For example, this flag is used with
SHOW SYSTEM to avoid bringing processes into memory to display their
accumulated CPU time.
If you specify·JPI$M_NO_TARGET_INSWAP and request information
from a process that has been swapped out, the following consequences
occur:

•

Any data stored in the virtual address space of the process is not
accessible.

•

Any data stored in the process header (PHD) may not be accessible.

•

Any data stored in resident data structures, such as the process control
block (PCB) or the job information bloc~ (JIB), is accessible.

, ....

You must examine the return length of an item to verify that the item was
retrieved. The information might be located in a different data structure
in another release of VMS.
JPI$M_NO_TARGET_AST

When JPI$M_NO_TARGET_AST is specified, $GETJPI does not deliver a
kernel-mode AST to the target process. JPI$M_NO_TARGET_AST is used
to avoid executing a target process in orcler to retrieve information.
If you specify JPI$M_NO_TARGET_AST and cannot deliver an AST to a
target process, the following consequences occur:
•

Any data stored in the virtual address space of the process is not
accessible.

•

Data stored in system data structures, such as the process header
(PHD), the process control block (PCB), or the job information block
(JIB), is accessible.

You must examine the return length of an item to v~rify that the item was
retrieved. The information might be located in a different data structure
in another release of VMS.
The use of the flag JPI$M_NO_TARGET_AST also implies that $GETJPI
does not swap in a process, because $GETJPI would bring a process into
memory only to deliver an AST to that process.

8-34

VMS Version 5.2 Features

B.2 VMS Version 5.2 System Services Features

JPI$M_IGNORE_TARGET_STATUS

When JPI$M_IGNORE_TARGET_STATUS is specified, $GETJPI attempts
to retrieve as much information as possible, even if the process is
suspended or being deleted. JPI$M_IGNORE_TARGET_STATUS is used
to retrieve all possible information from a process. For example, this flag
is used with SHOW SYSTEM to display processes that are suspended, are
being deleted, or are in miscellaneous wait states.
Example B-10 demonstrates (in FORTRAN) how to use $GETJPI control
flags to avoid swapping processes during a $GETJPI call.
Example 8-10

c
c

Using $GETJPI Control Flags to Avoid Swapping a Process into the Balance Set

PROGRAM CONTROL FLAGS
IMPLICIT NONE

Implicit none

INCLUDE' ($jpidef)
/nolist'
INCLUDE '($pscandef) /nolist'
INCLUDE' ($ssdef)
/nolist'

Definitions for $GETJPI
Definitions for $PROCESS SCAN
Definitions for SS$ names

STRUCTURE /JPIITMLST/
UNION
MAP
INTEGER*2 BUFLEN,
2
CODE
INTEGER*4 BUFADR,
RETLENADR
2
END MAP
MAP
INTEGER*4 END LIST
END MAP
END UNION
END STRUCTURE
STRUCTURE /PSCANITMLST/
UNION
MAP
INTEGER*2 BUFLEN,
2
CODE
INTEGER*4 BUFADR,
2
ITMFLAGS
END MAP
MAP
INTEGER*4 END LIST
END MAP
END UNION
END STRUCTURE

Structure declaration for
$GETJPI item lists

A longword of 0 terminates
an item list

Structure declaration for
$PROCESS_SCAN item lists

A longword of 0 terminates
an item list

(continued on next page)

o
8-35

VMS Version 5.2 Features

B.2 VMS Version 5.2 System Services Features

Example 8-10 (Cont.)

Using $GETJPI Control Flags to Avoid Swapping a Process into the
8alance Set

RECORD /PSCANITMLST/
2
PSCANLIST(5)

Declare the item list for
$PROCESS_SCAN

RECORD /JPIITMLST/
2
JPILIST(6)

Declare the item list for
$GETJPI

INTEGER*4 SYS$GETJPIW,
2
SYS$PROCESS SCAN

System service entry points

INTEGER*4
2
2
2

Status variable
Context from $PROCESS SCAN
PID from $GETJPI
Flags for $GETJPI

STATUS,
CONTEXT,
PID,
JPIFLAGS

INTEGER*2 IOSB(4)

I/O status block for $GETJPI

CHARACTER*16
2
PRCNAM,
2
NODENAME
INTEGER*2 PRCNAM_LEN,
2
NODENAME LEN

Process name from $GETJPI
Node name from $GETJPI
Process name length
Node name length

CHARACTER*80
IMAGNAME
2
INTEGER*2 IMAGNAME LEN

Image name from $GETJPI
Image name length

LOGICAL*4 DONE

Done with data loop

0.- ·-

!********************************************
!* Initialize item list for $PROCESS SCAN *
!********************************************

! Look for interactive and batch jobs across
! the cluster with $GETJPI buffering
PSCANLIST(l) . BUFLEN
PSCANLIST(l) .CODE
PSCANLIST(l) .BUFADR
PSCANLIST(l) .ITMFLAGS
PSCANLIST(2) .BUFLEN
PSCANLIST(2) .CODE
PSCANLIST(2) . BUFADR
PSCANLIST(2) .ITMFLAGS
PSCANLIST(3) . BUFLEN
PSCANLIST(3) .CODE
PSCANLIST(3) .BUFADR
PSCANLIST(3) .ITMFLAGS
PSCANLIST(4) .BUFLEN
PSCANLIST(4) .CODE
PSCANLIST(4) .BUFADR
PSCANLIST(4) .ITMFLAGS
PSCANLIST(5) .END_LIST

o
PSCAN$_NODE_CSID

PSCAN$M_NEQ

o
PSCAN$_MODE
JPI$K_INTERACTIVE
PSCAN$M_OR

o
PSCAN$ MODE
JPI$Kj3ATCH

o
o

PSCAN$ GETJPI BUFFER SIZE
1000

o
(continued on next page)

o
8-36

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

Example 8-10 (Cont.)

Using $GETJPI Control Flags to Avoid Swapping a Process into the
8alance Set

!********************************************
End of item list initialization
!*
*
!********************************************
STATUS
2
2

SYS$PROCESS SCAN (
CONTEXT,
PSCANLIST)

Set up the scan context

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
! Initialize $GETJPI item list

c
c
o

JPILIST(l) .BUFLEN
JPILIST(l) .CODE
JPILIST(l) .BUFADR
JPILIST(l) .RETLENADR
JPILIST(2) .BUFLEN
JPILIST(2) .CODE
JPILIST(2) .BUFADR
JPILIST(2) .RETLENADR
JPILIST(3) .BUFLEN
JPILIST(3) .CODE
JPILIST(3) .BUFADR
JPILIST(3) .RETLENADR
JPILIST(4) .BUFLEN
JPILIST(4) .CODE
JPILIST(4) . BUFADR
JPILIST(4) .RETLENADR
JPILIST(5) .BUFLEN
JPILIST(5) .CODE
JPILIST(5) .BUFADR
JPILIST(5) .RETLENADR
JPILIST(6) .END_LIST
! Loop calling $GETJPI

lAND ('FFFF'X, JPI$ GETJPI_CONTROL_FLAGS)
%LOC(JPIFLAGS)

o
4

JPI$ PID
%LOC(PID)

o
LEN (PRCNAM)
JPI$_PRCNAM
%LOC(PRCNAM)
%LOC(PRCNAM_LEN)
LEN (IMAGNAME)
JPI$_IMAGNAME
%LOC (IMAGNAME)
%LOC(IMAGNAME_LEN)
LEN (NODENAME)
JPI$_NODENAME
%LOC(NODENAME)
%LOC(NODENAME_LEN)

o
with the context

DONE = .FALSE.
JPIFLAGS = lOR (JPI$M_NO_TARGET_INSWAP, JPI$M_IGNORE_TARGET_STATUS)
DO WHILE (.NOT. DONE)
! Call $GETJPI to get the next process
STATUS
2
2
2
2
2
2
2

= SYS$GETJPIW (
%VAL(1) ,
CONTEXT,
JPILIST,
IOSB,

Event flag 1
Process context
No process name
Itemlist
Always use IOSB with $GETJPI!
No AST
No AST arg
(continued on next page)

o
8-37

VMS Version 5.2 Features
B.2 VMS Version 5.2 System Services Features

Example 8-10 (Cant.)

Using $GETJPI Control Flags to Avoid Swapping a Process into the
Balance Set

Check the status in both STATUS and the IOSB, if
STATUS is OK then copy IOSB(l) to STATUS
IF (STATUS) STATUS

= IOSB(l)

! If $GETJPI worked, display the process, if done then
! prepare to exit, otherwise signal an error

IF (STATUS) THEN
IF (IMAGNAME_LEN .EQ. 0) THEN
TYPE 1010, PID, NODENAME, PRCNAM
ELSE
TYPE 1020, PID, NODENAME, PRCNAM,
IMAGNAME(l:IMAGNAME_LEN)
END IF
ELSE IF (STATUS .EQ. SS$_NOMOREPROC) THEN
DONE
.TRUE.
ELSE
CALL LIB$SIGNAL(%VAL(STATUS»
END IF

END DO
1010
1020

FORMAT (' ',Z8.8,'
FORMAT (' ',Z8.8,'

',A6,':: ',A,' (no image)')
',A6,':: ',A,' ',A)

END

8.2.30 Descriptions of New VMS Version 5.2 System Services
This section contains reference information for two system services,
$DEVICE_SCAN, an input/output system service, and $PROCESS_SCAN,
a process information system service.

o
B-38

VMS Version 5.2 Feature$
$DEVICE_SCAN

Scan for Devices
The Device Scan system service returns the names of all devices that match
a specified set of search criteria. The names returned by $DEVICE_SCAN
can then be passed to another service, for example, $GETDVI or $MOUNT.

FORMAT

SVS$DEVICE_SCAN

RETURNS

VMS usage:
type:
access:
mechanism:

return devnam ,ret/en
,[search_devnam] ,[itm/st]
,[con txt]

cond_value
longword (unsigned)
write only
by value

Longword condition value. All system services (except $EXIT) return by
immediate value a condition value in RO. Condition values returned by
this service are listed under Condition Values Returned.

ARGUMENTS

return_devnam
char_string
character-coded text string
write only
by descriptor-fixed length string descriptor
Buffer to receive the device name. The return_devnam argument is the
address of a character string descriptor pointing to a buffer into which
$DEVICE_SCAN writes the name of the first or next device that matches
the specified search criteria. The maximum size of any device name is
64 bytes.
VMS usage:
type:
access:
mechanism:

ret/en
word_unsigned
word (unsigned)
write only
by reference
Length of the device name string returned by $DEVICE_SCAN. The
retlen argument is the address of a word into which $DEVICE_SCAN
writes the length of the device name string.

VMS usage:
type:
access:
mechanism:

search_devnam

VMS usage: device_name
type:
character-coded text string
access:
read only
mechanism: by descriptor-fixed length string descriptor

Name of the device for which $DEVICE_SCAN is to search. The search_
devnatn argument accepts the standard wildcard characters, the asterisk
(*), which matches any sequence of characters, and the percent sign (%),
which matches anyone character. For example, to match all unit 0 DU

8-39

VMS Version 5.2 Features
$DEVICE_SCAN

o
devices on any controller, specify *DU%O. This string is compared to the
most complete device name (DVI$-.ALLDEVNAM).

ifm/sf
VMS usage:
type:
access:
mechanism:

item_list_3
longword_unsigned
read only
by reference

Item list specifying search criteria used to identify the device names for
return by $DEVICE_SCAN. The itmlst argument is the address of a list
of item descriptors, each of which describes one search criterion. The list
of item descriptors is terminated by a longword of O.
The following figure depicts the format of a single item descriptor:

Item Code

Buffer Length

Buffer Address
Return Length Address
ZK-1705-GE

$DEVICE_SCAN Item Descriptor Fields

buffer length

A word containing a user-supplied integer specifying the length (in bytes)
of the buffer from which $DEVICE_SCAN is to read the information. The
length of the buffer needed depends upon the item code specified in the
item code field of the item descriptor.
item code

A word containing a user-supplied symbolic code specifying the item of
information that $DEVICE_SCAN is to return. The $DVSDEF macro
defines these codes. Each item code is described following this list of item
descriptor fields.

buffer address

A longword containing the user-supplied address of the buffer from which
$DEVICE_SCAN is to read the information.
return length address

This field is not currently used.
$DEVICE_SCAN Item Codes
DVS$_DEVCLASS

An input value item code that specifies, as an unsigned longword, the
device class being searched. The $DCDEF macro defines these classes.
The DVS$_DEVCLASS argument is a longword containing this number;
however, DVS$_DEVCLASS uses only the low-order byte of the longword.

8-40

VMS Version 5.2 Features
$DEVICE_SCAN

DVS$_DEVTVPE
An input value item code that specifies, as an unsigned longword, the
device type for which $DEVICE_SCAN is going to search. The $DCDEF
macro defines these types.
The DVS$_DEVTYPE argument is a longword containing this number;
however, DVS$_DEVTYPE uses only the low-order byte of the longword.
DVS$_DEVTYPE should be used with $DVS_DEVCLASS to specify the
device type being searched for.

con txt
VMS usage:
type:
access:
mechanism:

quadword_unsigned
quadword (unsigned)
modify
by reference

Value used to indicate the current position of a $DEVICE_SCAN search.
The contxt argument is the address of the quadword that receives this
information. On the initial call, the quadword should contain O.

DESCRIPTION

The Device Scan service returns all device names that match a specified
set of search criteria. The device names are returned for one process per
call. A context value is used to continue multiple calls to $DEVICE_SCAN.
$DEVICE_SCAN allows wildcard searches based on device names, device
classes, and device types. It also provides the ability to perform a wildcard
search on other device-related services.
$DEVICE_SCAN makes it possible to combine search criteria. For
example, to find only RA82 devices use the following selection criteria:
DVS$_DEVCLASS

DC$_DISK and DVS$_DEVTYPE

DT$_RA82

To find all mailboxes with MB as part of the device name (excluding
mailboxes such as NLAO), use the following selection criteria:

DVS$_DEVCLASS

CONDITION
VALUES
RETURNED

DC$_MAILBOX and DEVNAM = *MB*

SS$_NORMAL

The service completed successfully.

SS$_ACCVIO

The search_devnam, itmlst, or contxt argument
cannot be read by the caller, or the retlen, return_
devnam, or contxt argument cannot be written by the
caller.
The contxt argument contains an invalid value or the
item list contains an invalid item code.

SS$_NOSUCHDEV

The specified. device does not exist on the host
system.

SS$_NOMOREDEV

No more devices match the specified search criteria.

o
8-41

VMS Version 5.2 Features
$PROCESS_SCAN

'--~--'
(
'
/

Process Scan
The Process Scan system service creates and initializes a process context
that is used by $GETJPI to scan processes on the local system or across the
nodes in a VAXcluster system. An item list is used to specify selection criteria
to obtain information about specific processes, for example, all processes
owned by one user or all batch processes.

FORMAT

SYS$PRQCESS_SCAN pidctx [, itm/stJ

RETURNS

VMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

Longword condition value. All system services (except $EXIT) return by
immediate value a condition value in RO. Condition values returned by
this service are listed under Condition Values Returned.

ARGUMENTS

pidctx

process_id
longword (unsigned)
modify
by reference
Context value supplied by $PROCESS_SCAN to be used as the pidadr
argument of $GETJPI. The pidctx argument is the address of a longword
that is to receive -the process context longword. This longword normally
contains zero ot a previous context. If it contains a previous context, the
old context is deleted. If it contains a value other than zero or a previous
context~ the old value is ignored.

VMS usage:
type:
access:
mechanism:

itm/st
item_list_3
longword (unsigned,)
read only
by reference
Item list spec'ifying selection criteria to be used by the scan or to control
the scan.

VMS usage:
type:
access:
mechanism:

The itmlst argument is the address of a list of item descriptors, each
of which describes one selection criterion or contrpl option. Within each
selection criterion you can include several item entries. The list of item
descriptors is terminated by a longword of zero.
The information in the item list is passed to the item descriptor in one
of two ways. If the item descriptor can always hold the actual value of
the selection criterion, the value is placed in the second longword of the
item descriptor and the buffer length is specified as zero. If the item
descriptor points to the actual value of the selection criterion, the address
of the value is placed in the second longword of the item descriptor and

8-42

0
-

VMS Version 5.2 Features

$PROCESS_SCAN

you must specify the buffer length for the selection criterion. Each item
code description specifies whether the information is passed by value or by
reference.
The following figure depicts the format of an item descriptor that passes
the selection criterion as a value:
31

Item Code

Item Value
Item-Specific Flags
ZK-0949A-GE

The following figure depicts the format of an item descriptor that passes
the selection criterion by reference:
31

Item Code

Buffer Length

Buffer Address
Item-Specific Flags
ZK-0948A-GE

$PROCESS_SCAN Item Descriptor Fields

buffer address

A longword containing the user-supplied address of the buffer from which
$PROCESS_SCAN retrieves information needed by the scan. When you
specify an item code that is passed by reference, $PROCESS_SCAN uses
the address as a pointer to the actual value. See the description of the
item value field for information about item codes that are passed by
value.
buffer length

Buffer length is specified in a different way for the two types of item
descriptors:
•

Character string or reference descriptors
A· word containing a user-supplied integer specifying the length (in
bytes) of the buffer from which $PROCESS_SCAN retrieves a selection
criterion. The length of the buffer needed depends upon the item code
specified in the item descriptor.

•

Immediate value descriptors
The length of the buffer is always specified as zero.

·8-43

VMS Version 5.2 Features

$PROCESS_SCAN

item code

A word containing the selection criterion. These codes are defined by
the $PSCANDEF macro. Each item code is described after this list of
descriptor fields.
item value

A longword containing the actual value of the selection criterion. When
you specify an item code that is passed by value, $PROCESS_SCAN
searches for the actual value contained in the item list. See the description
of the buffer address field for information about item codes that are
passed by reference.
item-specific flags

A longword that contains flags to help control selection information. Itemspecific flags, for example EQL or NEQ, are used to specify how the value
specified in the item descriptor is compared to the process value.

(~\

I~,

These flags are defined by the $PSCANDEF macro. Some flags are
common to multiple item codes; other flags are specific to an individual
item code. See the description of each item code to determine which flags
are used.
For item codes that describe bit masks or character strings, these flags
control how the bit mask or character string is compared with that in the
process. By default, they are compared for equality.
For item codes that describe integers, these flags specify an arithmetic
comparison of an integer item with the process attribute. For example,
a PSCAN$M_GTR selection specifying the value 4 for the item code
PSCAN$_PRIB finds only the processes with a base priority above 4.
Without one of these flags, the comparison is for equality.

$PROCESS_SCAN Item Codes
PSCAN$_ACCOUNT

When you specify PSCAN$_ACCOUNT, $GETJPI returns information
about processes that match the account field.

(-._ . ._~\';
~

If the string supplied in the item descriptor is shorter than the account
field, the string is padded with blanks for the comparison unless the
item-specific flag PSCAN$M_PREFIX_MATCH is present.
Because the information is a character string, the selection value is passed
by reference. The length of the buffer is placed in the first word of the item
descriptor and the address of the buffer is placed in the second longword.
Although the current length of the account field is eight bytes, the
PSCAN$_ACCOUNT buffer can be up to 64 bytes in length. If the buffer
length is zero or greater than 64, the SS$_IVBUFLEN error is returned.
The following flags can be used with this item code:

8-44

Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL

Match this value or the next value
Match value exactly (the default)

VMS Version 5.2 Features
$PROCESS_SCAN

o
Item-Specific Flag

Description

PSCAN$M_NEQ
PSCAN$M_CASE_BLlND
PSCAN$M_PREFIX_MATCH
PSCAN$M_WILDCARD

Match if value is not equal
Match without regard to case of letters
Match on the leading substring
Match string is a wildcard pattern

PSCAN$_AUTHPRI

When you specify PSCAN$_AUTHPRI, $GETJPI returns information
about processes that match the authorized base priority field.

(

""\
/

This integer item code is passed by value; the value is placed in the second
longword of the item descriptor. The buffer length must be specified as
zero.
The following flags can be used with this item code:
Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL
PSCAN$M_NEQ
PSCAN$M_GEQ
PSCAN$M_GTR
PSCAN$M_LEQ
PSCAN$M_LSS

PSCAN$_CURPRIV

When you specify PSCAN$_CURPRIV, $GETJPI returns information
about processes that match the current privilege field. Privilege bits are
defined by the $PRVDEF macro.
Because the bit mask information is too long to be passed by value, the
information is passed by reference. The privilege buffer must be exactly
eight bytes; otherwise, the SS$_IVBUFLEN error is returned.
The following flags can be used with this item code:

Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQ
PSCAN$M_NEQ
PSCAN$M_BIT_ALL
PSCAN$M_BIT_ANY

Match this value or the next value
Match value exactly (the default)
Match if value is not equal
A" bits set in pattern set in target
Any bit set in pattern set in target

PSCAN$_GETJPI_8UFFER_SIZE

When you specify PSCAN$_GETJPI_BUFFER_SIZE, you determine the
size of a buffer to be used by $GETJPI to process multiple requests in a
single message. Using this item code can greatly improve the performance

8-45

VMS Version 5.2 Features
$PROCESS_SCAN

(j
of scans on remote nodes because fewer messages are needed. This item
code is ignored during scans on the local node.
This integer item code is passed by value; the value is placed in the second
longword of the item descriptor. The buffer length must be specified as
zero. The buffer is allocated by $PROCESS_SCAN; you do not have to
allocate a buffer.
If you use PSCAN$_GETJPI_BUFFER_SIZE with $PROCESS_SCAN,
all calls to $GETJPI usingthe context established by $PROCESS_
SCAN must request the same item code information. Because $GETJPI
locates information for more than one process at a time, it is not
possible to change the item codes or the length of the buffers used in
the $GETJPI item list. $GETJPI checks each call and returns the error
SS$_BADPARAM if an attempt is made to change the item list during
a buffered process scan. However, the buffer addresses can be changed
between $GETJPI calls.

Because the locating and buffering of information by $GETJPI is
transparent to a calling program, you are not required to change the
way $GETJPI is called when you use this item code.
The $GETJPI buffer uses the process quota BYTLM. If the buffer is too
large for the process quota, $GETJPI (not $PROCESS_SCAN) returns the
error SS$_EXBYTLM. If the buffer specified is not large enough to contain
the data for at least one process, $GETJPI returns the error
SS$_BADPARAM.
No item-specific flags are used with PSCAN$_GETJPI_BUFFER_SIZE.

PSCAN$_GRP

When you specify PSCAN$_GRP, $GETJPI returns information about
processes that match the UIC group number.
This integer item code is passed by value; the value is placed in the second
longword of the item descriptor. Because the value of the group number
is a word, the high-order word of the value is ignored. The buffer length
must be specified as zero.
The following flags can be used with this item code:
Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL
PSCAN$M_NEQ
PSCAN$M_GEQ
PSCAN$M_GTR
PSCAN$M_LEQ
PSCAN$M_LSS

PSCAN$_HW_MODEL

When you specify PSCAN$_HW_MODEL, $GETJPI returns information
about processes that match the specified CPU hardware model number.
The hardware model number is an integer, such as VAX$K_V8840. The
VAX$ symbols are defined by the $VAXDEF macro.

8-46

VMS Version 5.2 Features
$PROCESS_SCAN

This iriteger item code is passed by value; the value is placed in the second
longword of the item descriptor. The buffer length must be specified as
zero.
The following flags can be used with this item code:

Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL
PSCAN$M_NEQ

Match this value or the next value
Match value exactly (the default)
Match if value is not equal

PSCAN$_HW_NAME
When you specify PSCAN$_HW_NAME, $GETJPI returns information
about processes that match the specified CPU hardware name, such as
VAX 111780, VAX 8800, or VAXstation II/GPX.
Because the information is a character string, the selection value is passed
by reference. The length of the selection value is placed in the first word
of the item descriptor and the address of the buffer is placed in the second
longword.

The PSCAN$_HW_NAME buffer can be up to 128 bytes in length. If the
buffer length is zero or greater than 128, the SS$_IVBUFLEN error is
returned.
The following flags can be used with this item code:
Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL
PSCAN$M_NEQ
PSCAN$M_CASE_BLlND
PSCAN$M_PREFIX_MATCH
PSCAN$M_WILDCARD

Match this value or the next value
Match value exactly (the default)
Match if value is not equal
Match without regard to case of letters
Match on the I~ading substring
Match a wildcard pattern

PSCAN$_JOBPRCCNT
When you specify PSCAN$_JOBPRCCNT, $GETJPI returns information
about processes that match the subprocess count for the job (the count of
all subprocesses in the job tree).
This integer item code is passed by value; the value is placed in the second
longword of the item descriptor. The buffer length must be specified as
zero.
The following flags can be used with this item code:

Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL

Match this value or the next value
Match value exactly (the default)

B-47

VMS Version 5.2 Features
$PROCESS_SCAN

o
Item-Specific Flag

Description

PSCAN$M_NEQ

Match if value is not equal

PSCAN$M_GEQ

Match if value is greater than or equal to

PSCAN$M_GTR

Match if value is greater than

PSCAN$M_LEQ

Match if value is less than or equal to

PSCAN$M_LSS

Match if value is less than

PSCAN$_JOBTVPE

When you specify PSCAN$_JOBTYPE, $GETJPI returns information
about processes that match the job type. The job type values include the
following:
Value

Description

JPI$K_LOCAL

Local interactive process

JPI$K_DIALUP

Interactive process accessed by a modem line

JPI$K_REMOTE

Interactive process accessed by using SET
HOST

JPI$K_BATCH

Batch process

JPI$K_NETWORK

Noninteractive network process

JPI$K_DETACHED

Detached process

These values are defined by the $JPIDEF macro. Note that job type values
are similar to mode values. See PSCAN$_MODE.

Description

PSCAN$M_OR

Match this value or the next value

PSCAN$M_EQL

Match value exactly (the default)

PSCAN$M_NEQ

Match if value is not equal

PSCAN$_MASTER_PID

When you specify PSCAN$_MASTER_PID, $GETJPI returns information
about processes that are descendants of the specified parent process. The
master process is the first process created in the job tree. The PSCAN$_
OWNER item is similar, but the owner process is the process that created
the target process (the owner process might itself be a subprocess).
Although all jobs in a job tree must have the same master, they can
have different owners.
This integer item code is passed by value; the value is placed in the second
longword of the item descriptor. The buffer length must be specified as
zero.

B-48

VMS Version 5.2 Features
$PROCESS_SCAN

c
The following flags can be used with this item code:
Item-Specific Flag

Descri ption

PSCAN$M_OR
PSCAN$M_EOL
PSCAN$M_NEO

Match value exactly (the default)

Match this value or the next value
Match if value is not equal

PSCAN$_MEM

When you specify PSCAN$_MEM, $GETJPI returns information about
processes that match the VIC member number.

This integer item code is passed by value; the value is placed in the second
longword of the item descriptor. Because the value of the member number
is a word, the high-order word of the value is ignored. The buffer length
must be specified as zero.
The following flags can be used with this item code:

Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EOL
PSCAN$M_NEO
PSCAN$M_GEO
PSCAN$M_GTR
PSCAN$M_LEO
PSCAN$M_LSS

PSCAN$_MODE

When you specify PSCAN$_MODE, $GETJPI returns information about
processes that match the specified mode. Mode values include the
following:
Value

Description

JPI$K_INTERACTIVE
JPI$K_BATCH
JPI$K_NETWORK
JPI$K_OTHER

Interactive process
Batch job
Noninteractive network job
Detached and other process

These values are defined by the $JPIDEF macro. Note that values checked
by PSCAN$_MODE are similar to PSCAN$_JOBTYPE values.

This integer item code is passed by value; the value is placed in the second
longword of the item descriptor. The buffer length must be specified as
zero.

8-49

VMS Version 5.2 Features
$PROCESS_SCAN

The following flags can be used with this item code:
Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL
PSCAN$M_NEQ

Match this value or the next value
Match value exactly (the default)
Match if value is not equal

PSCAN$_NODE_CSID

When you specify PSCAN$_NODE_CSID, $GETJPI returns information
about processes on the specified nodes. To scan all nodes in a VAXcluster
system, you specify a CSID of zero and the item-specific flag PSCAN$M_
NEQ.
This integer item code is passed by value; the value is placed in the second
longword of the item descriptor. The buffer length must be specified as
zero.
The following flags can be used with this item code:
Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL
PSCAN$M_NEQ

Match this value or the next value
Match value exactly (the default)
Match if value is not equal

PSCAN$_NODENAME

When you specify PSCAN$_NODENAME, $GETJPI returns information
about processes that match the specified node names. To scan all of the
nodes in a VAXcluster system, specify the node name using an asterisk
wildcard ( * ) and the PSCAN$M_WILDCARD item-specific flag.
Because the information is a character string, the selection value is passed
by reference. The length of the selection value is placed in the first word
of the item descriptor and the address of the buffer is placed in the second
longword.

..... .

Although the current length of the node name is 6 bytes, the PSCAN$_
NODENAME buffer can be up to 64 bytes in length. If the buffer length is
zero or greater than 64, the SS$_IVBUFLEN error is returned.
The following flags can be used with this item code:

B-50

Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL
PSCAN$M_NEQ
PSCAN$M_CASE_BLlND
PSCAN$M_PREFIX_MATCH
PSCAN$M_WILDCARD

Match this value or the next value
Match value exactly (the default)
Match if value is not equal
Match without regard to case of letters
Match on leading substring
Match a wildcard pattern

VMS Version 5.2 Features

$PROCESS_SCAN

PSCAN$_OWNER

When you specify PSCAN$_OWNER, $GETJPI returns information about
processes that are immediate descendants of the specified process. The
PSCAN$_MASTER_PID item is similar, but the owner process is the
process that created the target process (the owner process might itself be
a subprocess). Although all jobs in a job tree must have the same master,
they can have different owners.
This integer item code is passed by value; the value is placed in the second
longword of the item descriptor. The buffer length must be specified as
zero.
The following flags can be used with this item code:
Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL
PSCAN$M_NEQ

Match this value or the next value
Match value exactly (the default)
Match if value is not equal

PSCAN$_PRCCNT

When you specify PSCAN$_PRCCNT, $GETJPI returns information about
processes that match the subprocess count (the count of all immediate
descendants of a given process). The PSCAN$_JOBPRCCNT item code is
similar, except that JOBPRCCNT is the count of all subprocesses in a job.
This integer item code is passed by value; the value is placed in the second
longword of the item descriptor. The buffer length must be specified as
zero.
The following flags can be used with this item code:
Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL
PSCAN$M_NEQ
PSCAN$M_GEQ
PSCAN$M_GTR
PSCAN$M_LEQ
PSCAN$M_LSS

PSCAN$_PRCNAM

When you specify PSCAN$_PRCNAM, $GETJPI returns information about
processes that match the specified process names.
The process name string is padded with blanks for the comparison unless
the item-specific flag PSCAN$M_PREFIX_MATCH is present.

8-51

VMS Version 5.2 Features

$PROCESS_SCAN

Although the current length of the process name field is 15 bytes, the
PSCAN$_PRCNAM buffer can be up to 64 bytes in length. If the buffer
length is zero or greater than 64, the SS$_IVBUFLEN error is returned.
The following flags can be used with this item code:
Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EOL
PSCAN$M_NEO
PSCAN$M_CASE_BLlND
PSCAN$M_PREFIX_MATCH
PSCAN$M_WI LDCARD

Match this value or the next value
Match value exactly (the default)
Match if value is not equal
Match without regard to case of letters
Match on leading substring
Match a wildcard pattern

PSCAN$_PRI

When you specify PSCAN$_PRI, $GETJPI returns information about
processes that match current priority. Note that the current priority of a
process can be temporarily increased as a result of system events such as
the completion of I/O.
This integer item code is passed by value; the value is placed in the second
longword of the item descriptor. The buffer length must be specified as
zero.
The following flags can be used with this item code:
Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EOL
PSCAN$M_NEO
PSCAN$M_GEO
PSCAN$M_GTR
PSCAN$M_LEO
PSCAN$M_LSS

Match this value or the next value

()

Match value exactly (the default)
Match if value is not equal
Match if value is greater than or equal to
Match if value is greater than
Match if value is less than or equal to
Match if value is less than

PSCAN$_PRI8

When you specify PSCAN$_PRIB, $GETJPI returns information about
processes that match base priority.
This integer item code is passed by value; the value is placed in the second
longword of the item descriptor. The buffer length must be specified as
zero.
The following flags can be used with this item code:
Item-Specific Flag

Description

Match this value or the next value

8-52

VMS Version 5.2 Features

$PROCESS_SCAN

Item-Specific Flag

PSCAN$M_EOL
PSCAN$M_NEQ
PSCAN$M_GEO
PSCAN$M_GTR
PSCAN$M_LEQ
PSCAN$M_LSS

Description

PSCAN$_STATE

When you specify PSCAN$_STATE, $GETJPI returns information about
processes that match the specified process state. State values, for example
SCH$C_COM and SCH$C_PFW, are defined by the $STATEDEF macro.
This integer item code is passed by value; the value is placed in the second
longword of the item descriptor. The buffer length must be specified as
zero.
The following flags can be used with this item code:

Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EOL
PSCAN$M_NEQ

Match this value or the next value
Match value exactly (the default)
Match if value is not equal

PSCAN$_STS

When you specify PSCAN$_STS, $GETJPI returns information that
matches the current status mask. Without any item-specific flags, the
match is for a process mask that is equal to the pattern. Status bits,
for example PCB$V_ASTPEN or PCB$V_PSWAPM, are defined by the
$PCBDEF macro.
This bit mask item code uses an immediate value descriptor; the selection
value is placed in the second longword of the item descriptor. The buffer
length must be specified as zero.
The following flags can be used with this item code:

Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL
PSCAN$M_NEO
PSCAN$M_BIT_ALL
PSCAN$M_BIT_ANY

Match this value or the next value
Match value exactly (the default)
Match if value is not equal
All bits set in pattern set in target
Any bit set in pattern set in target

PSCAN$_TERMINAL

When you specify PSCAN$_TERMINAL, $GETJPI returns information
that matches the specified terminal names. The terminal name string
is padded with blanks for the comparison unless the item-specific flag
PSCAN$M_PREFIX_MATCH is present.

8-53

VMS Version 5.2 Features

$PROCESS_SCAN

Because the information is a character string, the selection value is passed
by reference. The length of the selection value is placed in the first word
of the item descriptor and the address of the buffer is placed in the second
longword.
Although the current length of the terminal name field is 8 bytes, the
PSCAN$_TERMINAL buffer can be up to 64 bytes in length. If the buffer
length is zero or greater than 64, the SS$_IVBUFLEN error is returned.
The following flags can be used with this item code:
Item-Specific Flag

Description

PSCAN$M_OR
PSCAN$M_EQL
PSCAN$M_NEQ
PSCAN$M_CASE_BLlND
PSCAN$M_PREFix_MATCH
PSCAN$M_WILDCARD

Match this value or the next value
Match value exactly (the default)
Match if value is not equal
Match without regard to case of letters
Match on leading substring
Match a wildcard pattern

PSCAN$_UIC

When you specify PSCAN$_UIC, $GETJPI returns information about
processes that match the UIC identifier. To convert an alphanumeric
identifier name to the internal identifier, use the $ASCTOID system
service before calling $PROCESS_SCAN.

O
_. .
_.

Description

PSCAN$M_OR
PSCAN$M_EQL
PSCAN$M_NEQ

Match this value or the next value
Match value exactly (the default)

Match if value is not equal

PSCAN$_USERNAME

When you specify PSCAN$_USERNAME, $GETJPI returns information
about processes that match the specified user name.
The user name string is padded with blanks for the comparison unless the
item-specific flag PSCAN$M_PREFIX_MATCH is present.
Because the information is a character string, the selection value is passed
by reference. The length of the selection value is placed in the first word
of the item descriptor and the address of the buffer is placed in the second
longword.
Although the current length of the username field is 12 bytes, the
PSCAN$_USERNAME buffer can be up to 64 bytes in length. If the
buffer length is zero or greater than 64, the SS$_IVBUFLEN error is
returned .

. 8-54

, , ' .\

VMS Version 5.2 Features

$PROCESS_SCAN

The following flags can be used with this item code:
Item-Specific Flag

Description

PSCAN$M..,..OR
PSCAN$M_EQL
PSCAN$M_NEQ
PSCAN$M_CASE_BLlND
PSCAN$M_PREFIX_MATCH
PSCAN$M_WILDCARD

Match this value or the next value
Match value exactly (the default)
Match if value is not equal
Match without regard to case of letters
Match on leading substring
Match a wildcard pattern

The following flags can be furnished in the item-specific flag field of the
item descriptor.
$PROCESS_SCAN Item-Specific Flags
PSCAN$M_BIT_ALL

If the PSCAN$M_BIT_ALL flag is used, all bits set in the pattern mask
specified by the item descriptor must also be set in the process mask.
Other bits in the process mask may also be set.

For item <;:odes that describe bit masks, such as privilege masks and status
words, this flag controls how the pattern bit mask specified by the item
d,escriptor is compared with that in the process. By default, the bit masks
are compared for equality.
The PSCAN$M_BIT_ALL flag is used only with bit masks.
PSCAN$M_BIT_ANY

If tpe PSCAN$M_BIT_ANY flag is used, a match occurs if any bit in the
pattern mask is also set in the process mask.
For item codes that describe bit masks, such as privilege masks and status
words, this flag controls how the pattern bit mask specified by the item
descriptor is compared with that in the process. By default, the bit masks
are compared for equality.
The PSC1\N$M_BIT_ANY flag is used only with bit masks.
PSCAN$M_CASE_BLlND

When you specify PSCAN$M_CASE_BLIND to compare the character
string specified by the item descriptor with the character string value from
the process, $PROCESS_SCAN does not distinguish between uppercase
and lowercase letters.
The PSCAN$M_CASE_BLIND flag is used only with character-string item
codes. The PSCAN$M_CASE_BLIND flag can be specified with either the
PSCA,N$M_PREFIX_MATCH flag or the PSCAN$M_WILDCARD flag.
PSCAN$M_EQL

when you specify PSCAN$M_EQL, $PROCESS_SCAN compares the value
specified by the item descriptor with the value from the process to see if
there is an exact match.

B-55

VMS Version 5.2 Features

$PROCESS_SCAN

PSCAN$M_EQL and PSCAN$M_NEQ are used with bit masks, character
strings, and integers to control how the item is interpreted. Only one of
the flags can be specified; if more than one of these flags is used the
SS$_IVSSRQ error is returned. If you want to specify that bits not set in
the pattern mask must not be set in the process mask, use
PSCAN$M_EQL.

PSCAN$M_GEQ
When you specify PSCAN$M_GEQ, $PROCESS_SCAN selects a process if
the value from the process is greater than or equal to the value specified
by the item descriptor.
PSCAN$M_GEQ,PSCAN$M_GTR,PSCAN$M_LEQ,andPSCAN$M_LSS
are used with integer item codes only. Only one of these four flags can be
specified; if more than one of these flags is used the SS$_IVSSRQ error is
returned.

PSCAN$M_GTR
When you specify PSCAN$M_GTR, $PROCESS_SCAN selects a process if
the value from the process is greater than the value specified by the item
descriptor.
PSCAN$M_GEQ, PSCAN$M_GTR, PSCAN$M_LEQ, and PSCAN$M_LSS
are used with integer item codes only. Only one of these four flags can be
specified; if more than one of these flags is used the SS$_IVSSRQ error is
returned.

PSCAN$M_LEQ

When you specify PSCAN$M_LEQ, $PROCESS_SCAN selects a process if
the value from the process is less than or equal to the value specified by
the item descriptor.
PSCAN$M_GEQ, PSCAN$M_GTR, PSCAN$M_LEQ, and PSCAN$M_LSS
are used with integer item codes only. Only one of these four flags can be
specified; if more than one of these flags is used the SS$_IVSSRQ error is
returned.

PSCAN$M_LSS

0,
~,c=)

When you specify PSCAN$M_LSS, $PROCESS_SCAN selects a process
if the value from the process is less than the value specified by the item
descriptor.
PSCAN$M_GEQ,PSCAN$M_GTR,PSCAN$M_LEQ,andPSCAN$M_LSS
are used with integer item codes only. Only one of these four flags can be
specified; if more than one of these flags is used the SS$_IVSSRQ error is
returned.

PSCAN$M_NEQ
When you specify PSCAN$M_NEQ, $PROCESS_SCAN selects a process if
the value from the process is not equal to the value specified by the item
descriptor.
PSCAN$M_EQL and PSCAN$M_NEQ are used with bit masks, character
strings, and integers to control how the item is interpreted. Only one
of the flags can be specified; if more than one of these flags is used the
SS$_IVSSRQ error is returned.

8-56

VMS Version 5.2 Features

$PROCESS_SCAN

PSCAN$M_OR

When you specify PSCAN$M_OR, $PROCESS_SCAN selects processes
whose values match the current item descriptor or the next item
descriptor. The next item descriptor must have the same item code as the
item descriptor with the PSCAN$M_OR flag. Multiple items are chained
together; all except the last item descriptor must have the PSCAN$M_OR
flag.
The PSCAN$M_OR flag can be specified with any other flag and can be
used with bit masks, character strings, and integers. If the PSCAN$M_
OR flag is used between different item codes or if it is missing between
identical item codes, the SS$_IVSSRQ error is returned.
PSCAN$M_PREFIX_MATCH

When you specify PSCAN$M_PREFIX_MATCH, $PROCESS_SCAN
compares the character string specified in the item descriptor to the
leading characters of the requested process value.
For example, to find all process names that start with the letters AB,
use the string AB with the PSCAN$M_PREFIX_MATCH flag. If you do
not specify the PSCAN$M_PREFIX_MATCH flag, the search looks for a
process with the 2-character process name AB.
The PSCAN$M_PREFIX_MATCH flag also allows either the PSCAN$M_
EQL or the PSCAN$M_NEQ flag to be specified. If you specify PSCAN$M_
NEQ, the service matches those names that do not begin with the specified
character string.

The PSCAN$M_PREFIX_MATCH is used only with character-string item
codes. The PSCAN$M_PREFIX_MATCH flag cannot be specified with the
PSCAN$M_WILDCARD flag; if both of these flags are used the
SS$_IVSSRQ error is returned.
PSCAN$M_WILDCARD

When you specify PSCAN$M_WILDCARD, the character string specified
by the item descriptor is assumed to be a wildcard pattern. Acceptable
wildcard characters are the asterisk ( *), which allows the match to
substitute any number of characters in place of the asterisk and the
percent sign (%), which allows the match to substitute anyone character
in place of the percent sign. For example, if you want to search for
all process names that begin with the letter A and end with the string
ER, use the string A*ER with the PSCAN$M_WILDCARD flag. If the
PSCAN$M_WILDCARD flag is not specified, the search looks for the
4-character process name A*ER.

The PSCAN$M_WILDCARD is used only with character-string item codes.
The PSCAN$M_WILDCARD flag cannot be specified with the PSCAN$M_
PREFIX_MATCH flag; if both of these flags are used the
SS$_IVSSRQ error is returned. The PSCAN$M_NEQ flag can be used
with PSCANM$_WILDCARD to exclude values during a wildcard search.

DESCRIPTION

The Process Scan system service creates and initializes a process context
that is used by $GETJPI to scan processes on the local system or across
the nodes in a VAXcluster system. An item list is used to specify selection
criteria to obtain information about specific processes, for example, all
processes owned by one user or all batch processes.

8-57

VMS Version 5.2 Features
$PROCESS_SCAN

o
The output of the $PROCESS_SCAN service is a process context longword
named pidctx. This process context is then proVided to $GETJPI as the
pidadr argument. The process context provided by $PROCESS_SCAN
enables $GETJPI to search for processes across the nodes in a VAXcluster
system and to select processes that match certain selection criteria.
The process context consumes process dynamic memory. This memory is
deallocated when the end of the context is reached. For example, when the
$GETJPI service returns SS$_NOMOREPROC or when $PROCESS_SCAN
is called again with the same pidctx longword, the dynamic memory is
deallocated. If you anticipate that a scan might be interrupted before it
runs out of processes, $PROCESS_SCAN should be called a second time
(without an itmlst argument) to release the me;fllory~ Dynamic memory is
automatically released when the current image termin&tes.
$PROCESS_SCAN copies the item list and user buffers to the allocated
dynamic memory. This means that the item lists and user buffers can be
deallocated or reused immediately; they are not referenced during the calls
to $GETJPI.
..
The item codes referenced by $PROCESS_SCAN,' are found in data
structures that are always resident in the system, primarily the process
control block (PCB) and the job information blobl,t (JIB). A scan of
processes never forces a process th&t is swapped\:out of memory to be
brought into memory to read nonresident information.

CONDITION
VALUES
RETURNED

SS$_NORMAL

The service completed "stcd~ssfully.
t.

SS$_ACCVIO

. •

,:..,";",

j., ,(.,

-.:.

The pidctx argLJment cannot be written by the caller,
the item list cannot be teao by' the caller, or a buffer
for a reference descriptor cannot be read.
The item list contains an invalid item identifier or an
invalid combinatioll of item-specific flags is present.
The buffer length field is invalid. For immediate value
d~scriptors, the blJffer le.ngtb Il1U~t be zero. For
r~ference descriptors, the buffer length cannot be
zero or longer than the'maximum for the specified
item code. This error is also returned if the total
length of the item list phis tlie I~ngthof all of tHe
buffer fields is too large: to process.
The pidctx argument was not supplied, or the
(for example, multiple
item list is improperly
occurrences of a given jt~m code were interspersed
with other item Godes).

formed
A

•

o
8-58

Version 5.1 Features

c
C

VMS Version 5.1 Features

This appendix describes features that were new to Version 5.1 of the VMS
operating system but are not yet documented in other printed manuals.

C.1

c
o

VMS V~rsion 5.1 Support for Compound Documents
The term comppund documents refers to files that can contain a number
of integrated components including text, graphics, and scanned images.
This appendix specifically describes VMS support for using the text from
DECwindows compound documents that are structured according to the
DIGITAL Document Interchange Format (DDIF) specification. Refer to
the Introduction to the CDA Services and CDA Reference Manual for more
information about compound documents.
VMS commands and utilities, as well as existing application programs that
accept text input, ~an now use the text content of DECwindows compound
documents.
To support the use of DDIF text, VMS RMS has implemented a new RMS
file attr~bute, stored semantics, and a DDIF -to-text RMS extension.
The value of the stored semantics attribute is called the file tag and
it specifies how file data is to be interpreted. When file data is to be
interpreted in accordance with the DDIF specification, the appropriate file
tag is DDIF. The use of file tags is limited to disk files on VMS Version 5.1
and later systems.
The DDIF-to-text RMS extension transparently extracts text from DDIF
files as variable-length text records that can be accessed through the VMS
RMS interface.
The enhancements made to support the reading of text from DDIF files are
transparent to· the user and to the application programmer. This support
requires that all DDIF files in a VMS Version 5.1 environment be tagged
with the DDIF file tag. DDIF files created by VMS and VMS layered
products are tagged appropriat~ly.
Section C.l.1 describes various VMS_file management commands and
utilities that display, create, and preserve file tags where appropriate.
Section C.l.1 also describes the way various VMS commands and utilities
respond to DDIF file input. Section C.l.2 describes VMS support for DDIF
files in heterogeneous computing environments. Section C.l.3 describes
the changes made to the VMS RMS program interface to support the
stored semantics attribute and to control access to the content of DDIF
files.

o
C-1

Version 5.1 Features
C.1 VMS Version 5.1 Support for Compound Documents

C.1.1

VMS Commands and Utilities
This section describes the VMS commands and utilities that support tag
maintenance by displaying, creating, and preserving the RMS file tags
used with DDIF files. It also provides additional information that is
relevant to the way selected VMS commands and utilities respond to DDIF
file input.
The following table lists the VMS commands and utilities that support tag
maintenance:
Command/Uti lity

Tag Maintenance Function

DIRECTORY/FULL

Displays file tag

ANALYZE/RMS_FILE

Displays file tag

SET FILE/SEMANTICS

Creates file tag

VMS MAIL

Preserves file tagt

COpy

Preserves file tagt

BACKUP

Preserves file tag

tSee text for exceptions.

Tags are made up of binary values that can be up to 64 bytes long and
can be expressed using hexadecimal notation. The hexadecimal value
of the DDIF tag, for example, is 2BOC8773010301. VMS permits you
to assign mnemonics to tag values so that DCL commands, such as
DIRECTORY/FULL, and VMS utilities, such as FDL and ANALYZEIRMS_
FILE, display a mnemonic for the DDIF tag instead of the hexadecimal
value. The following DCL commands have been included in the system
startup command file to assign the mnemonic DDIF to the hexadecimal
value for a DDIF tag:
$
$

DEFINE/TABLE=RMS$SEMANTIC TAGS DDIF 2BOC8773010301
DEFINE/TABLE=RMS$SEMANTIC=OBJECTS 2BOC8773010301 DDIF

U sing the appropriate DEFINE commands, you can assign mnemonics for
other tags, including tags used with international program applications.

C-2

C.1.1.1

Displaying RMS File Tags
The DIRECTORY/FULL command and the AnalyzelRMS_File Utility now
display the RMS file tag for DDIF files.

C.1.1.1.1

DIRECTORY/FULL
Where applicable, the DIRECTORY/FULL command now provides the
value of the stored semantics tag as part of the file information returned
to the user. This is the recommended method for quickly determining
whether or not a file is tagged. The following display illustrates how the
DIRECTORY/FULL command returns the RMS attributes for a DDIF file
named X.DDIF:

Version 5.1 Features
C.1 VMS Version 5.1 Support for Compound Documents

X.DDIF;l

File ID:

RMS attributes:

C.1.1.1.2

(767,20658,0)

Stored semantics: DDIF

ANALYZE/RMS_FILE

When you use the ANALYZEIRMS_FILE command to analyze a DDIF file,
the utility returns the file tag as an RMS file attribute.
FILE HEADER
File Spec: USERD$: [TEST]X.DDIF;l

Stored semantics: DDIF

One ANALYZEIRMS_FILE command option is to create an output FDL
file that reflects the results of the analysis, using the following format:

ANALYZE/RMS_FILE/FDL filespec

When you use this option for analyzing a tagged file, the output FDL
file includes the file tag as a secondary attribute to the FILE primary
attribute. This is illlustrated in the following FDL file excerpt:
IDENT

9-JUN-1989 13:27:30

VAX/VMS ANALYZE/RMS_FILE Utility"

SYSTEM

c
C.1.1.2

SOURCE

VMS

ALLOCATION

STORED SEMANTICS

%X'2BOC8773010301'

FILE

DDIF

Creating RMS File Tags
The CDA$CREATE_FILE routine in the Compound Document
Architecture toolkit creates and tags DDIF files. However, you might
encounter a DDIF file that was created without a file tag or a DDIF file
whose file tag was not preserved during file processing.

The DCL command SET FILE provides a qualifier, I[NO]SEMANTICS,
that permits you to tag a DDIF file through the DCL interface for VMS
Version 5.1 or later systems. You can also use the qualifier to change a tag
or to remove a tag from a file.

C-3

Version 5.1 Features
C.1 VMS Version 5.1 Support for Compound Documents

The following command line tags the file X.DDIF as a DDIF file by
assigning the appropriate value to the /SEMANTICS qualifier:
$

SET FILE X.DDIF/SEMANTICS=DDIF

See Section C.l.1 for information about how to use logical name tables to
assign a mnemonic to a tag.
A subsequent DIRECTORYIFULL command displays the following line as
part of the file header:

RMS attributes:

Stored semantics: DDIF

The next example illustrates how to use the SET FILE command to delete
an RMS file tag:
$

C.1.1.3

SET FILE X.DDIF/NOSEIVlANTICS

Preserving RMS File Tags and OOIF Semantics
The COpy command and the VMS Mail Utility preserve RMS file tags and
DDIF semantics when you copy or mail a DDIF file on a VMS Version 5.1
or later system, except for conditions described in Sections C.l.2.2, C.l.2.3,
and C.l.2.4.

O~~
~ ~

The Backup Utility always preserves file tags and semantics when you
back up a DDIF file to magnetic tape.
C.1.1.3.1

COpy Command
This section describes the results of using the COpy command with DDIF
files for various operations.

When you use the COpy command to copy a DDIF file to a disk on a VMS
Version 5.1 or later system, VMS RMS preserves the DDIF tag and the
DDIF semantics of the input file in the output file.

~~)

When you use the COpy command to copy a DDIF file to a nondisk
device on a VMS Version 5.1 or later system, VMS RMS does not preserve
the DDIF tag or the DDIF semantics of the input file in the output file.
Instead, VMS RMS writes the text from the input file to the output file as
variable-length records.
When you copy two or more DDIF and text files in any combination to a
single output file, the output file takes the characteristics of the first input
file, as shown in the following examples:
1

In this example, the first input file is a text file, so the output file
(FOO.TXT) contains variable-length text records from X.TXT, Y.DDIF,
and Z.TXT but does not include the DDIF tag from Y.DDIF.
$

C-4

COpy X.TXT,Y.DDIF,Z.TXT FOO.TXT

Version 5.1 Features
C.1 VMS Version 5.1 Support for Compound Documents

o
2

In this example, the first input file (A.DDIF) is a DDIF file, so the
output file (FOO.DDIF) includes the DDIF tag as well as the DDIF
semantics from A.DDIF. The attempt to copy the text input file (Z.TXT)
fails because there is no text-to-DDIF RMS extension, but the contents
of B.DDIF and C.DDIF are copied to the output file. However, the
output file has no practical use because, as a result of the way DDIF
files are· structured, only the data from the first input file (A.DDIF) is
accessible in the output file.
$

In this example, the first input file (A.DDIF) is a DDIF file, so the
output file (FOO.DDIF) includes the DDIF tag as well as the contents
of A.DDIF. FOO.DDIF also includes the contents of B.DDIF and
C.DDIF. Again, however, the output file has no practical use because,
as a result of the way DDIF files are structured, only the data from
the first input file (A.DDIF) is accessible in the output file.
$

C.1.1.3.2

COPY A.DDlF,B.DDlF,C.DDlF FOO.DDlF

VMS Mail Utility

The VMS Mail Utility preserves the DDIF file tag when DDIF files are
mailed between VMS Version 5.1 or later systems. The VMS Mail Utility
also preserves the DDIF file tag when you create an output file on a VMS
Version 5.1 or later system using the EXTRACT command.

c
c

COpy A.DDlF,B.DDlF,Z.TXT,C.DDlF FOO.DDlF

When you read a mail message that is a DDIF file, the VMS Mail Utility
outputs only the text portion of the file. Similarly, if you edit a DDIF mail
file, you can access only the file text; the output file is a text file that can
no longer be used as a DDIF file. However, if you forward a message that
consists of a DDIF file, the VMS Mail Utility sends the entire DDIF file,
including DDIF semantics and the DDIF tag, to the addressee.
C.1.1.4

APPEND Command

This section describes what happens when you attempt to use the
APPEND command with DDIF and text files.
In the first example, the APPEND command appends a DDIF file to a text
file:
$

APPEND X.DDlF Y.TXT

The output file, Y.TXT, contains its original text records as well as text
from the input file, X.DDIF, reformatted as variable-length text records.
In the next example, the APPEND command appends a DDIF file to
another DDIF file:
$

APPEND X.DDlF Y.DDlF

The output file, Y.DDIF, contains the DDIF tag, the original contents
of Y.DDIF, and the contents of X.DDIF. However, the portion of the file
that contains X.DDIF is not accessible because of the way DDIF files are
structured.
In the final example, the APPEND command attempts to append a text
file to a DDIF file:
$

APPEND X.TXT Y.DDlF

C-5

Version 5.1 Features
C.1 VMS Version 5.1 Support for Compound Documents

This append operation fails because there is no text-to-DDIF RMS
extension.

C.1.2

DDIF Support in a Heterogeneous Environment
This section describes the implementation of DDIF support in two
heterogeneous environments. The first heterogeneous environment
includes VMS Version 5.1 or later systems and non-VMS systems. The
second heterogeneous environment includes VMS Version 5.1 or earlier
systems.
C.1.2.1

EXCHANGE/NETWORK Command

A new DCL command, EXCHANGEINETWORK, has been created
to support the transfer of files between VMS systems and non-VMS
systems that do not support VMS file types. The EXCHANGEINETWORK
command transfers files in either record mode or block mode but can be
used only when both systems support DECnet file transfers.

(-~\

(~/

To interactively tag a DDIF file and transfer the file between a non-VMS
operating system and a VMS Version 5.1 or later system, do the following:
1

Create the following file, assigning it the name DDIF.FDL:
FILE
ORGANIZATION
STORED SEMANTICS

sequential
DDIF

CARRIAGE CONTROL
FORMAT
SIZE

none
fixed
512

RECORD

To transfer the desired file, enter the EXCHANGEINETWORK
command, using the following format:
EXCHANGE/NETWORK/FDL=DDIF.FDL input_filespec output_filespec

See Section C.2 for more information about the EXCHANGEINETWORK
command.
C.1.2.2

COpy Command

If you use the COpy command to copy tagged DDIF files to systems other
than VMS Version 5.1 systems from a VMS Version 5.1 system, the results
will vary depending on the target system:
•

If the target system is a non-VMS system, the file is copied, but the
DDIF tag is not preserved.

•

If the target system is a VMS Version 5.1 or earlier system, the copy
operation fails with the VMS RMS error message RMS$_SUPPORT,
network operation not supported, and a secondary error message of
RMS$_SEMANTICS, inconsistent usage of RMS Semantics. Error
messages similiar to the following will appear:
%COPY-E-OPENOUT, error opening PWEDGE:: []TRY.DDIF;l as output
-RMS-F-SUPPORT, network operation not supported
-RMS-E-SEMANTICS, inconsistent usage of RMS Semantics
%COPY-W-NOTCOPIED, ABCD4: [DAVIDS]TRY.DDIF;l not copied

C-6

0.. \

Version 5.1 Features

C.1 VMS Version 5.1 Support for Compound Documents

•

If the target system is a cluster alias for a mixed version cluster
containing Version 5.1 or earlier systems, the result of the copy
operation depends on whether the cluster node that actually handles
the request is a Version 5.1 or earlier system.

•

If you use the COpy command to copy tagged DDIF files from Version

5.1 or later systems to earlier systems while on an earlier system, the
copy operation will fail with the error message RMS$_NET, network
operation failed at remote node, and with a DAP status code of 16F,
inconsistent usage of RMS Semantics. Error messages similiar to the
following will appear:
%COPY-E-OPENIN, error opening ARC"davids password": :ABCD4: [DAVIDS]TRY.DDIF;l as
input
-RMS-F-NET, network operation failed at remote node; DAP code = OlF7516F
%COPY-W-NOTCOPIED, ARC"davids password": :ABCD4: [DAVIDS]TRY.DDIF;l not copied
PWEDGE$

C.1.2.3

VMS Mail Utility
If you try to send mail messages containing DDIF files to non-VMS

systems that do not support tagged files, the VMS Mail Utility returns the
NOACCEPTMSG error message, indicating that the remote node cannot
accept the message format.

Similarly, the VMS Mail Utility does not support the mailing of DDIF
files to systems earlier than Version 5.1. As with non-VMS systems, the
VMS Mail Utility returns the NOACCEPTMSG error message for systems
earlier than Version 5.1, indicating that the remote node cannot accept the
message format.
C.1.2.4

DOfF File Access Within a Mixed Version Cluster

In a cluster that contains both Version 5.1 or earlier systems, operations
on DDIF files from systems earlier than Version 5.1 will cause inconsistent
behavior. Records read from DDIF files on systems earlier than Version
5.1 will be fixed-length 512-byte records, which contain DDIF control
information in addition to the text context. Thus, typing a DDIF file on a
system earlier than Version 5.1 does not produce readable text.

Copying a DDIF file using a system earlier than Version 5.1 will not
preserve the DDIF tag on the output file, which will cause problems in
later access to the new file from a Version 5.1 or later system.
However, using the Backup Utility from systems earlier than Version 5.1
will create a correct backup of DDIF files, and will properly restore DDIF
files from BACKUP save sets.

C.1.3

VMS RMS Interface Changes
This section provides details about the changes made to the VMS RMS
interface that support access to text in VMS DECwindows DDIF files. It
includes information related to tagging files and accessing tagged files
through the VMS RMS interface. The section also describes how tags are
preserved at the VMS RMS interface.

C-7

Version 5.1 Features
C.1 VMS Version 5.1 Support for Compound Documents

C.1.3.1

()

Programming Interface for File Tagging
This section focuses on the use of the DDIF tag for supporting VMS
DECwindows files, although VMS RMS also supports file tagging for other
compound document data formats.

You can tag a file from the VMS RMS interface by using the $CREATE
service in conjunction with a new extended attribute block (XAB) called
the item XAB ($XABITM). The $XABITM macro is a general-purpose
macro that was added to the RMS interface to support several Version 5.0
features. Tagged file support involves the use of the two item codes shown
in Table C-l.
Table C-1

Tag Support Item Codes

Item

Buffer Size

Function

XAB$_STORED_SEMANTICS

64 bytes
maximum

Defines the file semantics
established when the file is
created

XAB$_ACCESS_SEMANTICS

64 bytes
maximum

Defines the file semantics
desired by the accessing
program

The entries XAB$_STORED_SEMANTICS and XAB$_ACCESS_
SEMANTICS in the item list can represent either a control (set) function
or a monitor (sense) function that can be passed to VMS RMS from the
application program by way of the RMS interface.

"_ _'

The symbolic value XAB$K_SEMANTICS_MAX_LEN represents the tag
length. This value can be used to allocate buffer space for sensing and
setting stored semantics for the DDIF file.
Within anyone $XABlTM, you can activate either the set function or
the sense function for the XAB$_STORED_SEMANTICS and XAB$_
ACCESS_SEMANTICS items, because a common field (XAB$B_MODE)
determines which function is active. If you want to activate both the set
function and the sense function for either or both items, you mq.st use two
$XABITM control blocks, one for setting the functions and one for sensing
the functions.

C~\

Each entry in the item list addressed by the $XABITM is made up of three
longwords and a longword of zero terminates the list. You can locate the
item list anywhere within the readable address space for a process, but
any buffers required by the related function must be located in read/write
memory. If the item list is invalid, RMS returns a status of RMS$_XAB in
the RAB$L_STS field and the address of theXAB in RAJ3$L_STV.
The format and arguments of the $XABITM macro are as follows. Note
that the block length field and the type code field are statically initIalized
by the $XABITM macro or may be explicitly initialized using a high-level
language.

C-8

Version 5 . 1 Features

$XABITM

ITEMLIST=item-list-address,
MODE= { sensemode },
setmode
NXT=next-xab-address

FORMAT

$XABITM

ARGUMENTS

The ITEMLIST argument defaults to zero, but a valid pointer must be
specified when you use a XABITM. MODE defaults to sensemode. The
symbolic offset, size, and a brief description of each XABITM field are
described in the following list:
•

The block length field (XAB$B_BLN) is a I-byte static field that
defines the length of the XABITM, in bytes. This field is initialized to
the value XAB$C_ITMLEN.

•

The type code (XAB$B_COD) field is a I-byte static field that identifies
this control block as a XABITM. This field is initialized to the value
XAB$C_ITM.

•

The XAB$L_ITEMLIST field is a longword field that contains the
symbolic address of the item list.

•

The XAB$B_MODE field is a I-byte field that specifies whether the
items can be set by the program. It contains either the symbolic value
XA13$K_SETMODE or the symbolic value XAB$K_SENSEMODE
(default).

•

The XAB$L_NXT field is a longword field that contains the symbolic
address of the next XAB in the XAB chain. A value of zero (the
default) indicates that the current XAB is the last (or only) XAB in the
chain.

o
C-9

Version 5.1 Features

Support for Compound Documents

Example C-l illustrates a BLISS-32 program that tags a file through
the RMS interface. The tag value shown is a 6-byte hexadecimal number
representing the code for the DDIF tag. The VMS RMS program interface
accepts only hexadecimal tag values.
To write to a tagged file without using an RMS extension, the application
program must specify access semantics that match the file's stored
semantics. As shown in the example, $CREATE tags the file and
$CONNECT specifies the appropriate access semantics.
Example C-1

Tagging a File

MODULE TYPE$MAIN (
I DENT = 'X -1' ,
MAIN = MAIN,
ADDRESSING MODE (EXTERNAL=GENERAL)

(

~
\

) =
BEGIN
FORWARD ROUTINE
MAIN : NOVALUE;

Main routine

INCLUDE FILES:
LIBRARY 'SYS$LIBRARY:LIB';
OWN
NAM
: $NAM(),
RETLEN,
: BLOCK[ 7, BYTE]
DDIF TAG
INITIAL ( BYTE(%X'2B' ,%X'OC' ,%X'87' ,%X'73' ,%X'Ol' ,%X'03' ,%X'Ol')),
FAB XABITM
$xabitm
( itemlist=
$ITMLST_UPLIT

(

)

(ITMCOD=XAB$_STORED_SEMANTICS,
BUFADR=DDIF_TAG,
BUFSIZ=%ALLOCATION(DDIF_TAG))

mode = SETMODE),
RAB XABITM
$xabitm
( itemlist=
$ITMLST UPLIT
(

)

FAB

REC
STATUS,
RAB

(ITMCOD=XAB$_ACCESS_SEMANTICS,
BUFADR=DDIF_TAG,
BUFSIZ=%ALLOCATION(DDIF_TAG))

mode = SETMODE),
$FAB( fnm = 'TAGGED-FILE. TEST' ,
nam = NAM,
mrs
512,
rfm = FIX,
fac = <GET,PUT,UPD>,
xab = FAB_XABITM),
BLOCK[512,BYTE] ,

$RAB( xab = RAB_XABITM,
(continued on next page)

C-10

Version 5.1 Features

Support for Compound Documents

Example C-1 (Cont.) Tagging a File
fab
FAB,
rsz
512,
rbf
REC,
usz
512,
ubf
REC),
BLOCK[8,BYTE] INITIAL(D);

o
c
o

DESC
ROUTINE MAIN
NOVALUE =
BEGIN
STATUS = $CREATE( FAB = FAB );
IF NOT .STATUS
THEN
SIGNAL (.STATUS);
STATUS = $CONNECT( RAB
RAB);
IF NOT .STATUS
THEN
SIGNAL (.STATUS);
STATUS = $CLOSE( FAB ~ FAB );
IF NOT .STATUS
THEN
SIGNAL (.STATUS);
END;
END
ELUDOM

C.1.3.2

Accessing a Tagged File
This section provides details of how VMS RMS handles access to tagged
files at the program level. When a program accesses a tagged file, VMS
RMS must determine whether and when to associate an RMS extension
with the access. This is important to the programmer because an RMS
extension can change the attributes of the accessed file.

For example, a DDIF file is stored as a sequentially organized file having
512-byte, fixed-length records. If the DDIF-to-text RMS extension is used
to extract text from a DDIF file, the accessed file appears as a sequentially
organized file having variable-length records with a maximum record size
of 2048 bytes and an implicit carriage return.
One consideration in determining whether an access requires the RMS
extension is the type of access CFAB$B_FAC). When an application
program opens a file through the VMS RMS program interface, it must
specify if it will be doing record I/O (default), block I/O (BIO), or mixed
I/O (BRO), where the program has the option of using either block I/O
or record I/O for each access. For example, if block I/O operations are
specified, VMS RMS does not associate the RMS extension with the file
access.

Another consideration is whether the program senses the tag when it
opens a file. If the program does not sense the tag when it opens a DDIF
file for record access, VMS RMS associates the RMS extension during the
$OPEN and returns the file attributes that have been modified by the
extension.

C-11

Version 5.1 Features
Support for Compound Documents

The final consideration is the access semantics the program specifies
and the file's stored semantics (tag). If the program specifies block I/O
(FAB$V_BIO) operations, RMS does not associate the RMS extension and
the $OPEN service returns the file's stored attributes to the accessing
program regardless of whether the program senses tags.
C.1.3.2.1

File Accesses That Do Not Sense Tags

This section describes what happens when a program does not use the
XAIHTM to sense a tag when it opens a file.
When a program opens a DDIF file for record operations and does not
sense the tag, VMS RMS assumes that the program wants to access text
in the file. In this case, VMS RMS associates the RMS extension, which
provides file attributes that correspond to record-mode access.
When a program opens a DDIF file with the FAB$V_BRO option and does
not sense the tag, any subsequent attempt to use block I/O fails. If the
program specifies block I/O (FAB$V_BIO) when it invokes the $CONNECT
service, the operation fails because the file attributes returned at $OPEN
permit record access only. Similarly, if the program specifies the FAB$V_
BRO option when it opens the file, and then specifies mixed mode (block
/record) operations by not specifying RAB$V_BIO at $CONNECT time,
block operations such as READ and WRITE are disallowed.
C.1.3.2.2

File Accesses That Sense Tags

VMS RMS does not associate the RMS extension as part of the $OPEN
service if a program opens aDDIF file and senses the stored semantics.
This allows the program to specify access semantics with the $CONNECT
service. VMS RMS returns the file attributes, including the stored
semantics attribute (tag value), to the program as part of the $OPEN
service.
When the program subsequently invokes the $CONNECT service, VMS
RMS uses the specified operations mode to determine its response. If the
program specified FAB$V_BRO with the $OPEN service and then specifies
block I/O (RAB$V_BIO) when it invokes the $CONNECT service, VMS
RMS does not associate the RMS extension.

(

~~
\

.....

... .

But if the program specifies record access or FAB$V_BRO when it opens
the file and then decides to use record I/O when it invokes the $CONNECT
service, VMS RMS compares the access semantics with the file's stored
semantics to determine whether t() associate the RMS extension. If the
access semantics match the stored semantics, VMS RMS does not associate
the RMS extension. If the access semantics do not match the stored
semantics, VMS RMS associates the access with the RMS extension. In
this case, the program mtist use the $DISPLAY service to obtain the
modified file attributes. If VMS RMS cannot find the appropriate RMS
extension, the operation fails and the $CONNECT service returns the
EXTNOTFOU error message.

If the application program senses the file's stored semantics, VMS RMS
allows mixed-mode operations. In this case, mixed block and record
operations are permitted because the application gets record mode f i l e - ·
attributes and data from the RMS extension and block mode file attributes
and data from the file.
C-12

Version 5.1 Features

Support for Compound Documents

Example C-2 illustrates a BLISS-32 program that accesses a tagged file
from an application program that does not use an RMS extension.
Example C-2

Accessi n9 a Tagged File

MODULE TYPE$MAIN (
IDENT == 'X-1',
MAIN == MAIN,
ADDRESSING MODE (EXTERNAL==GENERAL)
)

BEGIN
FORWARD ROUTINE
MAIN : NOVALUE;

Main routine

INCLUDE FILES:

o
c

LIBRARY 'SYS$LIBRARY:STARLET';
OWN
NAM
: $NAM () ,
BLOCK [ XAB$K_SEMANTICS_MAX_LEN,BYTE ],
ITEM BUFF
RETLEN,
FAB XABITM
$xabitm
( itemlist==
$ITMLST_UPLIT
((ITMCOD==XAB$ STORED SEMANTICS,
BUFADR==ITEM_BUFF,
BUFSIZ==XAB$K_SEMANTICS_MAX_LEN,
RETLEN=RETLEN)),
mode == SENSEMODE),
RAB ITEMLIST
BLOCK [ ITM$S_ITEM + 4, BYTE ],
RAB XABITM
$XABITM
itemlist==RAB_ITEMLIST,
mode=SETMODE ),
FAB
$FAB( fnm
'TAGGED-FILE.TEST',
nam
NAM,
fac
<GET,PUT,UPD>,
xab
FAB_XABITM),
REC
BLOCK[512,BYTE],
STATUS,
RAB
$RAB( xab
RAB_XABITM,
fab
FAB,
rsz
512,
rbf
REC,
usz
512,
ubf
REC),
DESC
BLOCK[8,BYTE] INITIAL(O);
ROUTINE MAIN
NOVALUE =
BEGIN
STATUS == $OPEN( FAB == FAB );
IF NOT .STATUS
THEN
SIGNAL (.STATUS);
RAB_ITEMLIST[ ITM$W_BUFSIZ
.RETLEN;
RAB_ITEMLIST[ ITM$L_BUFADR
ITEM BUFF;
RAB_ITEMLIST[ ITM$W_ITMCOD
XAB$=ACCESS_SEMANTICS;
STATUS == $CONNECT( RAB = RAB );
IF NOT .STATUS
THEN
(continued on next page)

C-13

Version 5.1 Features
Support for Compound Documents

Example C-2 (Cont.) Accessing a Tagged File
SIGNAL (.STATUS);
STATUS = $CLOSE( FAB = FAB );
IF NOT .STATUS
THEN
SIGNAL (.STATUS);
END;
END
ELUDOM

C.1.3.3

Preserving Tags
To preserve the integrity of a tagged file that is being copied or
transmitted, the tag must be preserved in the destination (output) file.
The most efficient way to use the RMS interface for propagating tags is to
open the source file (input) and sense the tag using a $XABITM with the
item code XAB$_STORED_SEMANTICS:

ITEMLIST[
ITEMLIST[
ITEMLIST[
ITEMLIST[

ITM$W_BUFSIZ
ITM$L_BUFADR
ITM$L_RETLEN
ITM$W_ITMCOD

RETLEN;
XAB$ STORED_SEMANTICS;

XABITM[ XAB$B_MODE ] = XAB$K_SENSEMODE;
STATUS = $OPEN( FAB = FAB );

Then create the destination (output) file and set the tag using a $XABITM
with the item code XAB$_STORED_SEMANTICS:

IF .RETLEN GTR 0
THEN
BEGIN
ITEMLIST[ ITM$W_ITMCOD ] = XAB$_STORED_SEMANTICS;
ITEMLIST[ ITM$L_SIZE
] = .RETLEN;
XABITM[ XAB$B_MODE ] = XAB$K_SETMODE;
END;
STATUS

$CREATE( FAB = FAB );

END;
END
ELUDOM

o
C-14

Version 5.1 Features

Support for Compound Documents

C.1.4

Distributed File System Support for OOIF Tagged Files
Version 1.1 of the Distributed File System (DFS) includes limited support
for DDIF tagged files. You can create and read DDIF files on a DFS device
when the DFS client node is running VMS Version 5.1 or later versions.
You can also use the DIRECTORYIFULL command to determine whether
a DDIF file on a DFS device is tagged.
You cannot use the SET FILE/[NO]SEMANTICS command to either
tag DDIF files or remove the tags from DDIF files on a DFS device.
Furthermore, the Backup Utility does not preserve the DDIF tag or the
DDIF stored semantics for data files on a DFS device.

C.1.5

VMS RMS Errors
Four VMS RMS error messages signal the user when the corresponding
error condition exists:

•

RMS$_EXTNOTFOU

• RMS$_SEMANTICS
• RMS$_EXT_ERR
• RMS$_OPNOTSUP
The RMS$_EXTNOTFOU error message indicates that VMS RMS has not
found the specified RMS extension. Verify that the file is correctly tagged,
using the DIRECTORYIFULL command, and that the application program
is specifying the appropriate access semantics.
VMS RMS returns the RMS$_SEMANTICS error message when you try to
create a tagged file on a remote system earlier than VMS Version 5.1 from
a Version 5.1 or later system.
VMS RMS returns the RMS$_EXT_ERR error when the DDIF RMS
extension detects an inconsistency.
VMS RMS returns the RMS$_OPNOTSUP error when the RMS DDIF
extension is invoked by an RMS operation. For example, if the extension
does not support write access to a DDIF file, verify that the application
program is not performing record operations that modify the file.

o
C-15

VMS Version 5.1 Features
C.2 EXCHANGE/NETWORK Command

C.2

EXCHANGE/NETWORK Command
The EXCHANGE/NETWORK command allows the VMS operating system
to transfer files to or from operating systems that do not support VMS file
organizations. The transfer occurs over a DECnet network communications
link that connects VMS and non-VMS operating system nodes.
Using DECnet services, the EXCHANGE/NETWORK command can perform
the following operations:
Transfer files between a VMS node and a non-VMS system node
Transfer a group of input files to a group of output files
Transfer files between two non-VMS nodes, provided those nodes share
DECnet connections with the VMS node that issues the EXCHANGE
/NETWORK command
The EXCHANGE/NETWORK command imposes the following restrictions:
Transfers of files can occur only between disk devices. (If a disk device is
not the desired permanent residence for the file, you must either move the
file to a disk before issuing the command or retrieve the file from a disk
after the command completes.)
The remote system must have a block size of 512 bytes, where a byte is
8 bits long.
The nodes transferring files must support the DECnet Data Access
Protocol (DAP).
The VMS Record Management Services (RMS) facility provides VMS access
to records in VMS RMS files. To trahsfer VMS RMS files between two nodes
where both nodes are VMS nodes, use one of the other DCl commands
(such as COPY, APPEND, or CONVERT), as appropriate. These commands
recognize RMS file organizations and are designed to ensure that RMS record
structures are preserved as your files are moved.

(-~'i
'~-,-j

Use the EXCHANGE/NETWORK command to transfer files between VMS
nodes and noh-VMS nodes when the differences in the file organizations
would otherwise prevent the transfer or could lead to undesirable results.
While COpy ensures that both the contents and the attributes of a replicated
file are preserved, EXCHANGE/NETWORK is more flexible. EXCHANGE
/NETWORK offers you explicit control of your record attributes during file
transfers, with the opportunity to make a file usable on several different
operating systems.

o
C-16

VMS Version 5.1 Features

C.2 EXCHANGE/NETWORK Command

FORMAT

EXCHANGE/NETWORK

input-file-spec[, ... ]
output-file-spec

PARAMETERS
input-file-spec[, ...]

Specifies the name of an existing file to be transferred. Wildcard
characters are allowed. Use a comma (,) to indicate multiple file
specifications.
output-file-spec

Specifies the name of the output file into which the input is transferred.

You must specify at least one field in the output file specification. If you
omit the device or directory, your current default device and directory are
used. The EXCHANGEINETWORK command replaces any other missing
fields (file name, file type, version number) with the corresponding field of
the input file specification.
EXCHANGEINETWORK creates a new output file for every input file that
you specify.
You can use the asterisk wildcard character in place of the following:
file name, file type, or version number. The EXCHANGEINETWORK
command uses the corresponding field in the related input file to name
the output file. You can also use the wildcard character in the output file
specification to direct EXCHANGE/NETWORK to create more than one
output file. For example:

EXCHANGE/NETWORK A.A,B.B

MYPC: :*.C

This EXCHANGEINETWORK command creates the files A.C and B.C at
the non -VMS target node MYPC.
A more complete explanation of wildcard characters and version numbers
follows in the "description" section.

o
DESCRIPTION

The EXCHANGEINETWORK command transfers files between VMS
nodes and non-VMS nodes connected to the same DECnet network. If the
non-VMS system does not support VMS file organizations, EXCHANGE
/NETWORK can modify or discard file and record attributes during the
transfer. However, if the target system is a VMS node, you have the option
of applying new file and record attributes to the output file by supplying
a File Definition Language (FDL) file, as described later in this section.
EXCHANGE/NETWORK provides a number of defaults to handle the
majority of transfers properly. However, in some situations, you need to
know your file or record format requirements at both nodes.
VMS File and Record Attributes

All RMS files in the VMS environment include stored information,
known as the file and record attributes, to describe the file and record
characteristics. File attributes consist of items such as file organization,
file protection, and file allocation information. Record attributes consist
of items such as the record format, record size, key definitions for indexed
C-17

VMS Version 5.1 Features
C.2 EXCHANGE/NETWORK Command

files, and carriage control information. These attributes define the data
format and access methods for the VMS RMS facility.
Non-VMS operating systems that do not support VMS file organizations
have no means of storing file and record attributes with their files.
Transferring a VMS file to a non-VMS system that is unable to store
and handle file and record attributes can result in most of this information
being discarded. Removing these attributes from a file can render it
useless if it must be returned to the VMS system.
Transferring Files to VMS Nodes

When you transfer files to a VMS system from a non-VMS system, the
files typically assume default file and record attributes. However, you can
specify the attributes that you want the file to acquire in a File Definition
Language (FDL) file. If you specify an FDL file with the IFDL qualifier,
the FDL file determines the characteristics of the output file. This feature
is useful in establishing compatible file and record attributes when you
transfer a file from a non-VMS system to a VMS system. However, when
you use an FDL file, you also assume responsibility for determining the
required characteristics.
See the VMS File Definition Language Facility Manual for mure
information about FDL files.
Transferring Files to Non-VMS Nodes

EXCHANGEINETWORK discards file and record attributes associated
with a VMS file during a transfer to a non-VMS system that does not
support VMS file organizations. Be aware that the loss of file and record
attributes in the transfer can render the output file useless for many
applications.

Selecting Transfer Modes

The EXCHANGEINETWORK command has four transfer mode options:
AUTOMATIC, BLOCK, RECORD, and CONVERT. For most file transfers,
AUTOMATIC is sufficient. The AUTOMATIC transfer mode option allows
EXCHANGEINETWORK to transfer files using either block or record I/O.
The selection is based on the input file organization and the operating
systems involved.

0--"---\
~

Selecting the BLOCK transfer mode option forces EXCHANGEINETWORK
to open both the input and output files for block 110 access. The input file
is then transferred to the output file block by block. Use this transfer
mode when you transfer executable images. It is also useful when you
must preserve a file's content exactly, which is a common requirement
when you store files temporarily on another system or when cooperating
applications exist on the systems.
Selecting the RECORD transfer mode option forces EXCHANGE
INETWORK to open both the input file and output file for record I/O
accesds. The input £file is dthen transferIred to the output file record by
recor . This trans er mo e is primari y used for transferring text files.

C-18

Oli'.

VMS Version 5.1 Features

C.2 EXCHANGE/NETWORK Command

Selecting the CONVERT transfer mode option forces EXCHANGE
/NETWORK to open the input file for RECORD access and the output
file for BLOCK access. Records are then read in from the input file,
packed into blocks, and written to the output file. This transfer mode is
primarily used for transferring files with no implied carriage control. For
example, to transfer a file created with DIGITAL Standard Runoff (DSR)
to a DECNET-DOS system, you must use the CONVERT transfer mode
option. To transfer the resultant output file back to a VMS node, use the
AUTOMATIC transfer mode option.
Wildcard Characters
Wildcard characters are permitted in the file specifications and follow the
behavior typical of other VMS commands with respect to the VMS node.
When more than one input file is specified but wildcards are not specified
in the output file specification, the first input file is copied to the output
file, and each subsequent input file is transferred and given a higher
version number of the same output file name. Note that the files are not
concatenated into a single output file. Also note that when you transfer
files to foreign systems that do not support version numbers, only one
output file results, and it is the last input file.

To create multiple output files, specify multiple input files and use at least
one of the following:
•

An asterisk wildcard character in the output file name, file type, or
version number field

•

Only a node name, a device name, or a directory specification as the
output file specification

When you create multiple output files, EXCHANGE/NETWORK uses the
corresponding field from each input file in the output file name.

Use the fLOG qualifier when you specify multiple input and output files to
verify that the files were copied as you intended.
Version Numbers
The following guidelines apply when the target node file formats accept
version numbers.
If no version numbers are specified for input and output files, the
EXCHANGEINETWORK command (by default) assigns a version number
to the output files that is either of the following:

•

The version number of the input file

•

A version number one greater than the highest version number of an
existing file with the same file name and file type

When the output file version number is specified by an asterisk wildcard
character, the EXCHANGE/NETWORK command uses the version
numbers of the associated input files as the version numbers of the output
files.

C-19

VMS Version 5.1 Features
C.2 EXCHANGE/NETWORK Command

If the output file specification has an explicit version number, the
EXCHANGEINETWORK command normally uses that number for the
output file specification. However, if an equal or higher version of the
output file already exists, no warning message is issued, the file is copied,
and the version number is set to a value one greater than the highest
version number already existing.
File Protection and Creation/Revision Dates

The EXCHANGEINETWORK command treats an output file as a new file
when any portion of the output file name is explicitly specified. When the
output node is a VMS system, the creation date for a new file is set to the
current time and date. However, if the output file specification consists
only of wildcard characters, the output file no longer qualifies as a new file,
and, therefore, the creation date of the input file is used. That is, if the
output file specification is one of the following, the creation date becomes
that of the input file: *, *.*, or *.*;*.

(\
I",

The revision date of the output file is always set to the current time and
date; the backup date is set to zero. The output file is assigned a new
expiration date. (Expiration dates are set by the file system if retention is
enabled; otherwise, they are set to zero.)
When the target node is a VMS node, the protection and access control list
(ACL) of the output file is determined by the following parameters, in the
following order:
1

Protection of previously existing versions of the output file

Default protection and ACL of the output directory

Process default file protection

For an introduction to access control lists, see the VMS DCL Concepts
Manual.
On VMS systems, the owner of the output file usually is the same as the
creator of the output file. However, if a user with extended privileges
creates the output file, the owner is either the owner of the parent
directory or the owner of a previous version of the output file, if one
exists.
Extended privileges include any of the following:

C-20

•

SYSPRV or BYPASS

•

System VIC

•

GRPPRV if the owner of the parent directory (or previous version of
the output file) is in the same group as the creator of the new output
file

•

An identifier (with the resource attribute) representing the owner of
the parent directory (or previous version of the output file)

VMS Version 5.1 Features

C.2 EXCHANGE/NETWORK Command

QUALIFIERS
IBACKUP

Modifies the time value specified with the !BEFORE or ISINCE qualifier.
!BACKUP selects files according to the dates of their most recent backup.
This time qualifier is incompatible with the other time qualifiers that
also allow you to select files according to time attributes: ICREATED,
IEXPIRED, and IMODIFIED. If you do not specify any of these four time
qualifiers, the default is ICREATED.
IBEFORE[=time]

Selects only those files dated prior to the specified time. You can specify
time as an absolute time, as a combination of absolute and delta times,
or as one of the following keywords: TODAY (default), TOMORROW, or
YESTERDAY. Specify one of the following time qualifiers with IBEFORE to
indicate the time attribute to be used as the basis for selection: !BACKUP,
ICREATED (default), /EXPIRED, or !MODIFIED.
See the VMS DCL Concepts Manual for complete information about
specifying time values.
IBY_OWNER[=uic]

Selects only those files whose owner user identification code (UIC) matches
the specified owner UIC. The default UIC is that of the current process.
Specify the UIC using standard UIC format as described in the VMS DCL
Concepts Manual.
ICONFIRM
INOCONFIRM (default)

Controls whether a request is issued before each file transfer operation to
confirm that the operation should be performed on that file. The following
responses are valid:

YES
TRUE

QUIT

FALSE

Ctrl/Z

ALL

Return

You can use any combination of uppercase and lowercase letters for word
responses. Word responses can be abbreviated to one or more letters
(for example, T, TR, or TRU for TRUE), but these abbreviations must be
unique. Affirmative answers are YES, TRUE, and 1. Negative answers
are NO, FALSE, 0, and the Return key. QUIT or Ctrl/Z indicates that you
want to stop processing the command at that point. When you respond
with ALL, the command continues to process, but no further prompts are
given. If you type a response other than one of those in the list, DCL
displays an error message and redisplays the prompt.
ICREATED (default)

Modifies the time value specified with the !BEFORE or ISINCE qualifier.
The ICREATED qualifier selects files based on their date of creation. This
time qualifier is incompatible with the other time qualifiers that also allow
you to select files according to time attributes: !BACKUP, /EXPIRED, and
IMODIFIED. If you do not specify any of these four time qualifiers, the
default is ICREATED.

C-21

VMS Version 5.1 Features
C.2 EXCHANGE/NETWORK Command

IEXCLUDE=(file-spec[, ...])
Excludes the specified files from the file transfer operation. You can
include a directory but not a device in the file specification. Wildcard
characters are allowed in the file specification. However, you cannot use
relative version numbers to exclude a specific version. If you provide only
one file specification, you can omit the parentheses.
IEXPIRED
Modifies the time value specified with the IBEFORE or ISINCE qualifiers.
IEXPIRED selects files according to their expiration date. (The expiration
date is set with the SET FILE!EXPIRATION_DATE command.) This time
qualifier is incompatible with the other time qualifiers that also allow you
to select files according to time attributes: /BACKUP, ICREATED, and
!MODIFIED. If you do not specify any of these four time qualifiers, the
default is ICREATED.
IFD l=fd I-file-spec
Specifies that the output file characteristics are described in the File
Definition Language (FDL) file. Use this qualifier when you require
special output file characteristics. See the VMS File Definition Language
Facility Manual for more information about FDL files.

Use of the IFDL qualifier implies that the transfer mode is block by block.
However, the transfer mode you specify with the ITRANSFER_MODE
qualifier prevails.
IlOG
INOlOG (default)
Controls whether the EXCHANGEINETWORK command displays the file
specifications of each file copied.

(-~\

When you use the /LOG qualifier, the EXCHANGEINETWORK command
displays the following for each copy operation: (1) the file specifications of
the input and output files, and (2) the number of blocks or the number of
records copied (depending on whether the file is copied on a block-by-block
or record-by-record basis).
IMODIFIED
Modifies the time value specified with the !BEFORE or ISINCE qualifier.
The /MODIFIED qualifier selects files according to the date on which they
were last modified. This time qualifier is incompatible with the other time
qualifiers that also allow you to select files according to time attributes:
IBACKUP, ICREATED, and /EXPIRED. If you do not specify any of these
four time qualifiers, the default is ICREATED.
ISINCE[=time]
Selects only those files dated after the specified time. You can specify time
as an absolute time, a combination of absolute and delta times, or as one of
the following keywords: TODAY (default), TOMORROW, or YESTERDAY.
Specify one of the following time qualifiers with ISINCE to indicate the
time attribute to be used as the basis for selection: /BACKUP, ICREATED
(default), !EXPIRED, or /MODIFIED.

See the VMS DCL Concepts Manual for complete information about
specifying time values.

C-22

VMS Version 5.1 Features

C.2 EXCHANGE/NETWORK Command

ITRANSFER_MODE=option

Specifies the I/O method to be used in the transfer. This qualifier is useful
for all file formats. You can specify anyone of the following options:

Option

Function

AUTOMATIC

Allows EXCHANGE/NETWORK to determine the
appropriate transfer mode.

BLOCK

Transfers block by block.

CONVERT[=option[, ... ]]

Reads records from the input file, packs them
into blocks, and writes to the output file in block
mode. The options determine what additional
information is inserted during the transfer.

RECORD

Transfers record by record.

The AUTOMATIC transfer mode option allows EXCHANGE/NETWORK to
determine the appropriate transfer mode. The default is the AUTOMATIC
transfer mode.
If you explicitly select the BLOCK transfer mode option, EXCHANGE
/NETWORK opens both the input and output files for block I/O.
EXCHANGE /NETWORK then transfers the files block by block.

If you explicitly select the RECORD transfer mode option, EXCHANGE
/NETWORK opens both the input and output files for record lIO. The
target system must support record operations, and the input file must be
record oriented.
If you select the CONVERT transfer mode option, EXCHANGE
/NETWORK reads records in from the input file, packs them into blocks,
and writes them to the output file in block mode. There are four options
available with the CONVERT transfer mode to control the insertion of
special characters in the records, as explained in the following paragraphs:

•

CARRIAGE_CONTROL

•

COUNTED

•

FIXED_CONTROL

•

RECORD_SEPARATOR=separator

If you specify CARRIAGE_CONTROL, any carriage control information in
the input file is interpreted, expanded into actual characters, and included
with each record.
If you specify COUNTED, the length of each record in bytes is included at
the beginning of each record. The length includes all FIXED_CONTROL,
CARRIAGE_CONTROL, and RECORD_SEPARATOR information in each
record.

If you specify FIXED_CONTROL, all variable length with fixed control
record (VFC) information is written to the output file as part of the data.
This information follows the record length information if the COUNTED
option was specified.

C-23

VMS Version 5.1 Features
C.2 EXCHANGE/NETWORK Command

If you specify RECORD_SEPARATOR, a 1- or 2-byte record separator is
inserted between each record. Record separator characters are the last
characters in the record. The three choices for separator characters are
CR for carriage return only, LF for line feed only, or CRLF for carriage
return and line feed.
EXAMPLES

EXCHANGE/NETWORK VMS FILE.DAT FOO: :FOREIGN SYS.DAT

In this example, the EXCHANGEINETWORK command transfers the
file VMS_FILE.DAT located in the current default device and directory
to the file FOREIGN_SYS.DAT on the non-VMS node FOO. Because the
ITRANSFER_MODE qualifier was not explicitly specified, EXCHANGE
INETWORK automatically determines whether the transfer method
should be block or record I/O.
~

$
$

EXCHANGE/NETWORK/TRANSFER_MODE=BLOCKFOO: :FOREIGN_SYS.DAT VMS_FILE.DAT

In this example, the EXCHANGEINETWORK command transfers the file
FOREIGN_SYS.DAT from the non-VMS node FOO to the file VMS_
FILE.DAT in the current default device and directory. Block 1/0 is
specified for the transfer mode.
$
$

EXCHANGE/NETWORK/FDL=VMS_FILE_DEFINITION.FDLFOO: :REMOTE_FILE.TXT VMS_FILE.DAT

In this example, the EXCHANGEINETWORK command transfers the file
REMOTE_FILE.TXT on node FOO to the file VMS_FILE.DAT. The file
attributes for the output file VMS_FILE.DAT are obtained from the File
Definition Language (FDL) source file VMS_FILE_DEFINITION.FDL. For
more information about creating FDL files, see the VMS File Definition
Language Facility Manual. Because the qualifier IFDL is specified and the
ITRANSFER_MODE qualifier is omitted, the transfer mode uses block 1/0,
by default.

o
(-\"',,
~-_/

EXCHANGE/NETWORK$ /TRANSFER_MODE=CONVERT=(CARRIAGE_CONTROL,COUNTED, $ RECORD_SEPARATOR=CRLF,FIXED_CONTROL) $ PRINT _F ILE . TXT FOO:: *

In this example, the EXCHANGEINETWORK command transfers the file
PRINT_FILE.TXT from the current default device and directory to the file
PRINT_FILE.TXT on the non-VMS node FOO. The use of the CONVERT
option with the ITRANSFER_MODE qualifier forces the input file to be
read in record by record, modified as specified by the convert options
described below, and written to the output file block by block. As many
records as will fit are packed into the output blocks.
The CONVERT option CARRIAGE_CONTROL specifies that carriage
control information be converted to ASCII characters and inserted before
the data or appended to the record, depending on whether prefix control
or postfix control, or both, are used. The CONVERT option FIXED_
CONTROL specifies that any fixed control information be translated
to ASCII characters and inserted at the beginning of the record. The
CONVERT option RECORD_SEPARATOR=CRLF appends the two

C-24

O..

VMS Version 5.1 Features

C.2 EXCHANGE/NETWORK Command

specified characters, carriage return and line feed, to the end of the
record. The CONVERT option COUNTED specifies that the total length
of the record must be counted (once the impact of all the previous convert
options have been added), and the result is to be inserted at the beginning
of the record, in the first two bytes.

c
o
o

o
C-25

o
o

c
Index
Attribute for DNS (Cont.)

Aborting a transaction· 3-4, 3-7, 22-4, 22-11,
22-13,22-15
ABORT subcommand
with LMCP REPAIR command • 15-26
Access control list
See ACL
Accounting Utility (ACCOUNTING)
vector processing support • 2-14
ACL (access control list)
on vector capability object • 2-11 to 2-12
ACP-QIO function attributes • 25-2
Adapter
bus· 12-4, 12-5, 12-6
showing information· 12-4, 12-5, 12-6
ADAPTER keyword
Error Log Utility (ERROR LOG)· 13-1
Address
converting to node address • A-59
converting to node name • A--:61
Adobe font metrics • 31-6
AGEN$MAIL.COM • 8-7
AGEN$P1 logical name· 8-4
AGEN$P2 logical name· 8-4
AGEN$P3 logical name· 8-4
AGEN$PARAMS.REPORT· 8-1
using MAIL to Send· 8-7
Arithmetic exception
debugging vector· 2-17,2-27
AST (asynchronous system trap)
in target process • B-33
vector processing synchronization issues • 2-24
Asymmetric vector processing configuration • 2-2
Asynchronous option
VMS RMS support • 24-1
@ command
in SYSMAN Utility· 10-1
Atomic transaction
defined • 3-2
ATTACH command
in SYSMAN Utility· 10-1
Attribute for DNS
assigning • A-5
enumerating • A-28
modifying· A-31

reading • A-33
returning value· A-70
testing for one • A-35
types of· A-13
Attribute_Name identifier· A-43
Attribute_Name_Str identifier· A-43
AUTOGEN
AGEN$PARAMS.REPORT· 8-1
command procedure for automating • 8-4
controlling size of page and swap files • 8-3
including files in MODPARAMS.DAT • 8-2
LNMSHASHTBL parameter • 8-4
logical names defined by • 8-4
LRPCOUNT parameter • 8-4
new feedback parameters • 8-4
using MAIL to send reports· 8-7
validation of parameter names • 8-1
Availability of data
with volume shadowing • 18-1

B
BACKUP command
/MEDIA_FORMAT qualifier· 4-1
IBACKUP qualifier
with EXCHANGE/NETWORK command • C-21
with SET ACL command • 4-1
Backup Utility (BACKUP) • B-5 to B-9
/BUFFER_COUNT command qualifier • B-8
cyclic redundancy checking· B-8
performance enhancements • B-5
pressing Ctrl/T during BACKUp· B-8
setting SYSGEN parameters to enhance
performance of· B-7
setting up BACKUP account • B-6
summary of VMS Version 5.2 new features • B-5
UAF parameters for BACKUP account· B-6
/BEFORE qualifier
EXCHANGE/NETWORK command • C-21
BLAS (Basic Linear Algebra Subroutines)· 2-4,
2-19, 2-21
Boolean identifier· A-43
/BPAGE qualifier
in Linker Utility· 20-1
Buffer

Index-1

Index

c
Buffer (Cont.)
using $GETJPI for multiple requests for
information • B-45
BYTLM quota
using with $GETJPI buffers· B-45
/BY OWNER qualifier
EXCHANGE/NETWORK command • C-21

c
CACHE keyword
Error Log Utility (ERROR LOG) ·13-1
Calculator
hexadecimal mode • 7-5
octal mode • 7-5
Capability
See also Vector capability
defined • 2-5
CAPABILITY object type
for SET ACL command • 4-1
for SHOW ACL command • 4-2
CDA Viewer
in DECwindows· 7-2
new processing options
orientation radio box • 7-3
Scale Factor· 7-3
Use Bitmap Widths toggle button· 7-4
Use Comments toggle button· 7-3
Use Fake Trays toggle button • 7-4
Watch Progress toggle button • 7-4
PostScript file support· 7-2
support of Adobe font metrics· 31-6
support of DECmath fonts· 31-6
CHECK_VMS_VERSION (VMSINSTAL callback) •
30-1
Child directory
DNS ·A-7
CI (computer interconnect)
using multiple CI interfaces· 11-1
using multiple STAR couplers • 11-1
Circuit
devices
controllers • 17-1
DEMNA controller· 17-1
Second Generation Ethernet Controller
(SGEC) • 17-2
Class_Name identifer· A-43
Class_Name_Str identifier· A-43
Class_Version identifer· A-43
Clearinghouse • A-15

Index-2

CLEAR subcommand
with SET HOSTIDTE command • 4-2
Client Library
Display PostScript system· 31-4
Clock
menu bar· 7-5
Cluster identification number
F$CSID lexical function· 4-3
COLOR MIX CREATE routine
HLS support· 31-3
COMMIT subcommand
with LMCP REPAIR command· 15-27
Committing a transaction· 3-4, 3-7, 22-4, 22-16,
22-18, 22-20
Compiling fonts
for DECwindows server· 4-1
Compound document
See also DDIF
defined • C-1
Condition value • A-46 to A-49
Confidence identifier • A-43
Confidence level • A-16
Configuration
for volume shadowing· 18-1
CONFIGURATION keyword
Error Log Utility (ERROR LOG)· 13-1
ICON FI RM qualifier
EXCHANGE/NETWORK command • C-21
CONVERT command
LMCP Utility· 15-14
Converting audit event message • 22-21
CONVERT TABS command
EVE editor· 5-2
CREATE command
LMCP Utility • 15-16
ICREATED qualifier
EXCHANGE/NETWORK command • C-21
Creating a transaction log file • 15-4
Cyclic redundancy checking • B-8

D
Data
availability with volume shadowing· 18-1
ensuring against loss • 18-1
Data structure
DECdtm programming routines· 3-8
DCL commands
~ summary of new and enhanced· 4-1

Index

DCl command verification
in SYSMAN Utility· 10-1
DDIF (DIGITAL Document Interchange Format)
VMS RMS support of· C-1
DOIF-to-text RMS extension • C-1
Debugger
debugging vectorized programs· 19-1
enhancements to command interface· 19-1
enhancements to DECwindows interface • 19-2
support for vectorized programs • 2-25
DECdtm programming routines
data type • 3-8
DECdtm services· 3-1 to 3-8
See also log Manager Control Program Utility
aborting a transaction· 3-4,3-7,22-4,22-13
Abort Transaction and Wait system service· 22-15
Abort Transaction system service • 22-11
atomic transaction • 3-2
committing a transaction· 3-4, 3-7, 22-4, 22-16,
22-20
customizing • 3-1, 15-4
data type • 3-8
disabling • 3-1, 15-4
End Transaction and Wait system service • 22-20
End Transaction system service • 22-16
log manager· 3-5, 15-1
log Manager Control Program Utility (lMCP) •
3-7, 15-1
exiting • 15-12
invoking • 15-12
Monitor Utility (MONITOR) support· 3-7, 16-1 to
16-6
participant in a transaction • 3-4, 3-6, 15-10,
22-4
resource manager. 3-3, 22-4
RMS Journaling support· 29-1 to 29-7
starting a transaction • 22-4
Start Transaction and Wait system service • 22-52
Start Transaction system service· 22-48
system services • 3-6, 22-2
SYS$A80RT_TRANS· 22-11
SYS$A80RT_ TRANSW • 22-15
SYS$END_TRANS· 22-16
SYS$END_TRANSW· 22-20
SYS$START_ TRANS • 22-4, 22-48
SYS$START_ TRANSW • 22-4, 22-52
transaction identifier (TID) • 3-6, 15-10
transaction log file· 3-5, 15-1
creating • 15-4
determining location • 15-2
estimating file size • 15-4
format • 15-9

OECdtm services
transaction log file (Cont.)
placing in alternate location • 15-8
resizing • 15-7
sample display • 15-9
transaction manager· 3-4, 22-4
transaction processing • 3-1
transaction states • 3-6, 15-10, 22-4
TRANSACTION_ID data type • 3-8
two-phase commit protocol • 3-2, 3-7, 22-6
DECnet account
limiting default access· 8-3
DECnet event messages· A-77
Decompressing the system messages help library •
6-2
DECwindows
Calculator
hexadecimal mode· 7-5
octal mode • 7-5
Clock
menu bar· 7-5
Mail
displaying PostScript files • 7-5
DECwindows CDA Viewer
See CDA Viewer
OECwindows screen
multiscreen support· 7-1
IDEC_CRT qualifier
with SET TERMINAL command • 4-2
DEFINE command
in SYSMAN Utility ·10-1
Defining keys in SYSMAN Utility
See DEFINE command
OEINSTALl command • 8-1
DeltalXDelta Utility (DElTA/XDElTA)
support for vectorized programs • 2-26
DEMNA controller
circuit name· 17-1
line name ·17-1
Device driver
programming· 27-1
Device names
for VAXft 3000 system • 12-3
Devices
F$DEVICE lexical function • 4-3
scanning of across the cluster· 8-39
Device support
for VAX 9000· 27-1
DIGITAL Document Interchange Format
See DDIF
DIGITAL Extended Math Library

Index-3

Index

o
DIGITAL Extended Math Library (Cont.)

DNS clerk (Cont.)

See DXML
Directory
DNS types • A-6, A-16
enumerating in DNS· A-29
.DISABLE directive· 2-20
Disabling the TP _SERVER process· 3-1, 15-4
Disk
initializing from within a program • 22-9, 22-28
examples • 22-9 to 22-10
repairing faulty • 18-1
shadowing • 18-1
Disk space
amount needed to decompress help library· 6-2
Display PostScript system
imaging capabilities· 31-4
list of available documentation· 31-4
overview • 31-4
programming facilities· 31-4
Distributed Name Service
See DNS
DNS$APPEND_SIMPLENAME_TO_RIGHT routine·
A-52
DNS$COMPARE_FULLNAME routine • A-54
DNS$COMPARE_SIMPLENAME routine • A-55
DNS$CONCATENATE_NAME routine· A-56
DNS$CONTEXTVARNAME item • A-46
DNS$CONTEXTVARTIME item • A-46
DNS$COUNT_SIMPLENAMES routine • A-58
DNS$CVT_DNSADDRESS_TO_BINARY routine·
A-59
DNS$CVT_DNSADDRESS_TO_NODENAME routine
·A-61
DNS$CVT_NODENAME_TO_DNSADDRESS routine
·A-63
DNS$CVT_TO_USERNAME_STRING routine· A-65
DNS$PARSE_USERNAME_STRING routine· A-67
DNS$REMOVE_FIRST_SET_VALUE routine • A-70
DNS$REMOVE_LEFT_SIMPLENAME routine· A-73
DNS$REMOVE_RIGHT_SIMPLENAME routine·
A-75
DNS (Distributed Name Service)· A-3
clearinghouse • A-15
event messages· A-77
restrictions • A-4
root directory • A-6
system error messages • A-3
wildcards· A-9, A-21
DNS call
timeout in • A-11
DNS clerk
locating data in namespace • A-24

starting • A-77
$DNS function code • A-27 to A-36
converting from opaque • A-31
converting opaque name • A-35
converting string name • A-32, A-33
creating an object· A-27
deleting an object • A-27
enumerating attributes • A-28
enumerating child directories • A-29
enumerating objects • A-29
enumerating soft links • A-30
modifying attribute· A-31
reading attribute • A-33
resolving soft link • A-34
testing a group • A-36
testing for attribute • A-35
$DNS item code • A-37 to A-43
arguments· A-43 to A-44
attribute address • A-41
attribute name • A-37
attribute type • A-37
attribute value address • A-42
Boolean values • A-39
caching results· A-40
confidence level • A-38
converting names· A-38, A-39, A-40, A-42
entry type· A-38, A-39
enumerating directories • A-38
enumerating functions • A-38
enumerating objects • A-38
member name • A-40
modifying attributes • A-40
object class • A-37
object name • A-41
simple name address • A-41
soft link name • A-39
specifying groups • A-39
suppressing namespace name • A-42
target name address • A-41
testing attribute value • A-42
timeout value • A-43
UID address • A-42
version of object • A-42
wildcard • A-43
DNS name
case sensitivity • A-9
comparing • A-55
converting· A-31 , A-32 , A-33 , A-35
converting full name· A-31
defining logicals • A-8
format of • A-5

Index-4

Index

c
c
o

DNS name (Cont.)

Enumerate call (Cont.)

source of • A-5
DNS naming conventions
binary names· A-9
format· A-5
logical names • A-8
quoted names· A-9
syntax· A-7
valid characters • A-8
wildcards • A-9
DNS object· A-7
creating • A-10 to A-12, A-27
deleting· A-27
enumerating • A-29
modifying • A-12 to A-14
reading attributes of • A-18
DNS string name
converting to opaque • A-33
format· A-5
$DNS system service - A-26
arguments· A-26 to A-45
building item list· A-36
description • A-46
format· A-26, A-46
function codes • A-26
item code identifiers • A-43
qualifying status • A-45
returns • A-26
status block • A-26
$DNSW system service· A-50
Driver debugging
with Pool Check· 27-7
DSA disk
specifying preferred path • 11-2
DUMP command
LMCP Utility· 15-18
DXML (DIGITAL Extended Math Library)· 2-5,2-19

soft links· A-30
Enum_AtCName identifier· A-43
ERLBUFFERPAGES parameter
description • B-2
Error Log Utility (ERROR LOG)
qualifiers
IEXCLUDE
device class keywords • 13-1
entry type keywords • 13-1
IINCLUDE
device class keywords • 13-1
entry type keywords • 13-1
INODE ·13-2
supported device types for VAXft 3000 systems •
13-1
vector processing support • 2-14
Ethernet/820 controllers
circuit name • 17-1
line name ·17-1
EVE editor • 5-1 to 5-2
box editing • 5-1
CONVERT TABS command· 5-2
IINTERFACE qualifier· 5-2
IWORK qualifier • 5-2
Event flag
$DNS system service· A-26
Event messages
DNS ·A-77
Exception
servicing vector· 2-27 to 2-31
EXCHANGE/NETWORK command • C-16 to C-25
creating files • C-20
protecting files • C-20
qualifiers - C-20
selecting transfer modes • C-18
transferring files • C-1 8
wildcard characters - C-19
IEXCLUDE qualifier
Error Log Utility (ERROR LOG)
device class keywords • 13-1
entry type keywords - 13-1
EXCHANGE/NETWORK command • C-22
Executing a SYSMAN command procedure - 10-1
Exiting
LMCP ·15-12
LMCP REPAIR command mode· 15-28
EXIT subcommand
with LMCP REPAIR command -15-28
with SET HOST/DTE command - 4-2
Expired-Date Suppression • 24-3

EDIT/TPU command
qualifiers
IINTERFACE • 5-2
IWORK·5-2
.ENABLE directive· 2-20
Entry_Type identifier· A-43
Enumerate call
attributes • A-28
directories • A-29
objects • A-29

Index-5

Index

o
/EXPIRED qualifier
EXCHANGE/NETWORK command • C-22
with SET ACL command • 4-1
Extensions
to DECwindows for supporting Display PostScript •
31-4

F
F$CSID lexical function· 4-3
F$DEVICE lexical function • 4-3
F$ENVIRONMENT lexical function
new item codes • 4-3
symbol scoping • 4-3
F$GETDVI lexical function
new item codes • 4-3
volume shadowing • 4-3
F$GETJPllexical function· 2-13
new item codes • 4-3
vector processing support· 4-3
F$GETSYI lexical function· 2-13
new item codes • 4-3
parameter
cluster-id • 4-3
F$PID lexical function· 4-3
F$TYPE lexical function
return values • 4-3
FAB$V_ASY
documentation change • 24-1
Failover
using shadowed disks • 18-1
FAL (file access listener)
creating a default account • B-3
default access - B-3
Fault tolerance
through volume shadowing • 18-1
/FDL qualifier
EXCHANGE/NETWORK command· C-22
File
copying • C-16
creating • C-16
transferring • C-16, C-18
File access listener
See FAL
File Expiration Date and Time
evaluation criteria· 24-3
usage· 24-3
File protection
with EXCHANGE/NETWORK command • C-20

Index-6

File tag
creating • C-1
DDIF· C-1
disposition by COpy command • C-4
requirement for • C-1
stored semantics file attribute • C-1
using· C-1
First-Order Linear Recurrence subroutines
See FOLR subroutines
FOLR (First-Order Linear Recurrence) subroutines •
2-4,2-19,2-21
FONT command • 4-1
FORGET subcommand
with LMCP REPAIR command -15-29
FTDRIVER· 25-1
Full name
converting to opaque • A-32
converting to string • A-31
FUII_Name_String identifer· A-44

G
GET_PASSWORD (VMSINSTAL callback) • 30-1
Group_Member identifier • A-44

H
Hashing passwords· 22-25
Help
setting up and decompressing • 6-2
HELP command
in LMCP Utility· 15-22
HELP subcommand
with LMCP REPAIR command • 15-30
HLP$L1BRARY logical name· 6-2

I
I/O address space
of SCU/XMI bus • 27-1
1/0 symbolic addresses· 27-1
Image
loading site-specific - 22-62
/INCLUDE qualifier
Error Log Utility (ERROR LOG)
device class keywords • 13-1

Index

c
/INCLUDE qualifier
Error Log Utility (ERROR LOG) (Cont.)
entry type keywords • 13-1
INFORMATIONAL keyword
Error Log Utility (ERROR LOG)· 13-1
Initialization file
in SYSMAN Utility· 10-1
INITIALIZE command
/MEDIA_FORMAT qualifier· 4-1
Initializing a volume
from within a program· 22-9, 22-28
examples • 22-9 to 22-10
10$_SETPRFPTH function
specifying preferred path for DSA disks • 11-2
Itemlist Read Function
I/O Status Block· 25-2

Lexical functions
summary of new and enhanced • 4-2
vector processing support· 2-13
Librarian Utility (LIBRARIAN)
using to set up online help • 6-2
Line
devices
controllers • 17-1
DEMNA controller· 17-1
Second Generation Ethernet Controller
(SGEC) • 17-2
Linker Utility (LINK)
/BPAGE qualifier· 20-1
LMCP
See Log Manager Control Program Utility
LNMSHASHTBL parameter
use with AUTOGEN feedback· 8-4
Loadable image commands
in SYSMAN Utility· 10-1
Load balanCing • 11-1
using SYSGEN parameters ·11-1
LOAD_PWD_POLICY system parameter· 12-2
LOAD_PWS_POLICY parameter
in System Generation Utility (SYSGEN) • 12-2
LOAD_SYS_IMAGES parameter
in System Generation Utility (SYSGEN)· 12-2
LOAD_SYS_IMAGES system parameter· 12-2
Local buffer pool
affect on I/O performance • 24-2
Local buffers
increase in limit· 24-1

Local buffers (Cont.)
specifying number with multibuffer count XABITM·
24-1
Lock manager limit· A-1
Log file
See Transaction log file
Logical name • A-8
process logical names defined by AUTOGEN • 8-4
Log manager· 3-5, 15-1
Log Manager Control Program Utility (LMCP) • 3-7,
15-1
command descriptions • 15-13 to 15-34
CONVERT command ·15-14
CREATE command ·15-16
DUMP command ·15-18
exiting • 15-12
HELP command • 15-22
invoking • 15-12
privileges • 15-12
REPAIR command· 15-23
subcommands • 15-25 to 15-33
SHOW command • 15-33
LOGOUT command
vector processing support • 2-13
/LOG qualifier
EXCHANGE/NETWORK command • C-22
Loopback mirror
See MIRROR
LRPCOUNT parameter
use with AUTOGEN feedback· 8-4

M
MagnetiC tape
initializing from within a program· 22-9, 22-28
examples • 22-9 to 22-10
MAIL
default access • B-3
Mail (DECwindows)
displaying PostScript files • 7-5
Mail Utility (MAIL)
callable routines· 21-1
Mapping I/O space· 27-1
Marginal vector consumer • 2-6
detection of· 2-11
Mathematics • 23-2
/MEDIA_FORMAT qualifier
with BACKUP command • 4-1
with INITIALIZE command· 4-1
with MOUNT command· 4-1

Index-7

Index

o
/MEDIA_FORMAT qualifier (Cont.)
with SET MAGTAPE command· 4-2
Messages
converting security message from binary to ASCII
• 22-21
facilities with new and modified messages • 6-1
filtering sensitive information • 22-21
online help for • 6-2
reported in a vector processing system • 2-15 to
2-19
MIRROR
default access for loopback testing • 8-3
Modes
of transferring files • C-18
/MODIFIED qualifier
EXCHANGE/NETWORK command • C-22
with SET ACL command • 4-1
$MOD_IDENT system service· 8-14
Monitor Utility (MONITOR) • 16-1
cluster performance • 8-3
DECdtm services support· 16-1 to 16-6
MONITOR TRANSACTION command • 16-1
MONITOR VECTOR command • 16-7
support for DECdtm services· 3-7
TRANSACTION class • 16-1
TRANSACTION class record • 16-5
VECTOR class • 16-7
VECTOR class record • 16-9
vector processing support • 2-14
MONITOR VECTOR command ·16-7
MOUNT command
/MEDIA_FORMAT qualifier· 4-1
MSCP server
load balancing • 11-1
MSCP _LOAD parameter
using to control load balancing • 11-1
MSCP_SERVE_ALL parameter
using to control load balancing ·11-1
MTH$· 23-2
Multibuffer count XA81TM
for increased local buffering • 24-1
precedence over RA8$8_M8F field· 24-1
Multiprocessing
SHOW CPU command· 4-2
START/CPU command • 4-2
STOP/CPU command • 4-2
Multiscreen support· 7-1

N
Name
DNS
See DNS name
Name service
See DNS (Distributed Name Service)
Namespace • A-4
changing default· A-77
clearinghouses in • A-15
distributing • A-15
listing information • A-21 to A-24
name of· A-7, A-44
structure of • A-6
ways of using • A-5
NCP executor· A-1
SET/DEFINE EXECUTOR command • A-1
SHOW EXECUTOR CHARACTERISTICS
command· A-2
NETCONFIG.COM command procedure
security enhancements • 8-2
NETCONFIG_UPDATE.COM • 8-4
Network Control Program (NCP)
line and circuit support for new Ethernet/820
controllers ·17-1
line and circuit support for VAXft 3000 • 17-1
Network default access
controlling access to your system • 8-2
for existing systems • 8-4
for VAXcluster members • 8-5
NEXT subcommand
with LMCP REPAIR command • 15-32
/NOCONFIRM qualifier
EXCHANGE/NETWORK command • C-21
Node name
converting to address • A-63
/NODE qualifier
Error Log Utility (ERROR LOG) • 13-2
/NOLOG qualifier
EXCHANGE/NETWORK command • C-22

o
Object
See DNS object
ODS-II ACP • 24-3
Online help
for system messages • 6-2

Index-8

Index

c
Opaque name
concatenating· A-52, A-56
converting to string· A-31 , A-35 , A-65
converting user name • A-67
counting components· A-58
format of • A-5
returning simple name· A-73, A-75
Orientation radio box processing option • 7-3

Page file
controlling size in AUTOGEN • 8-3
deinstalling • B-1
Parallel processing • 23-1
Participant· 22-13, 22-18
Participant in a transaction • 3-4, 3-6, 15-10, 22-4
Password
return hash value· 22-25
screening • 14-1
password history list· 14-2
site-specific filter • 14-2
specifying an encryption algorithm • 14-3
Patch Utility (PATCH)
support for vectorized programs • 2-27
PHONE
default access • B-3
PIO (process identification) number
defined· B-15, B-16
using to reference remote process· B-15, B-16
Pool checking· 27-7
Poolchecking driver
bugcheck crashes· 27-7
sensitivity • 27-7
PostScript files
COA Viewer support· 7-2, 31-5
VIEW command support· 7-3, 31-5
PPL$· 23-1
Privileges
for LMCP commands· 15-12
Process
See also Remote process
See also SYS$GETJPI system service

See also SYS$PROCESS_SCAN system service
locating a subset of • B-42
obtaining information about· B-15
example • B-19
synchronously • B-30

Process (Cont.)
obtaining information about one process • B-18,
B-19
obtaining information about processes on specific
nodes • B-28, B-29
obtaining information about the calling process •
B-19
obtaining information about using PIO· B-15
obtaining information about using process name •
B-15, B-16, B-17
scanning across the clusters • B-42
using $PROCESS_SCAN item list to specify
selection criteria about • B-22, 8-24
example • B-26, B-27
using $PROCESS_SCAN item list with remote
procedures • B-31
using $PROCESS_SCAN search for· B-22
using wildcard search for • B-20
Process context
using with $GETJPI· B-15
Processing options
COA Viewer
orientation radio box • 7-3
Scale Factor· 7-3
Use Bitmap Widths toggle button· 7-4
Use Comments toggle button· 7-3
Use Fake Trays toggle button· 7-4
Watch Progress toggle button • 7-4
Process name
length of for remote processes • B-16, B-17
specifying for local process· B-16, B-17
specifying for remote processes • B-16, B-17
specifying processes by • B-51
specifying processes with node name • B-50
using to obtain information about remote
processes· B-15, B-16, B-17, B-27
example • B-20
Process-permanent files
VMS RMS asynchronous support· 24-1
Process search· 8-42
obtaining information about one process • B-18,
8-19
obtaining information about the calling process •
B-19
searching on all nodes • B-29
searching on specific nodes • B-28, B-29
using $PROCESS_SCAN item list to specify
selection criteria about processes· B-22,
B-24
example· B-26 , B-27
using item list with remote procedures· B-31
using item-specific flags to control selection
information • B-22

Index-9

Index

o
Process search (Cont.)
using wildcard on local system • B-20
$PROCESS_SCAN system service
controlling selection information for $GETJPI •
B-44
item descriptor
buffer length • B-42
format • B-42
using item-specific flags • B-44
Pseudoterminal Driver· 25-1
PSWRAP command • 4-1

Q
au IT subcommand
with SET HOST/DTE command • 4-2

R
RAB$B_MBF field
limitation • 24-1
Remote process
See Process
Remote process search
See Process search
REPAIR command
in LMCP Utility' 15-23
ABORT subcommand • 15-26
COMMIT subcommand ·15-27
EXIT subcommand • 15-28
FORGET subcommand • 15-29
HELP subcommand • 15-30
NEXT subcommand • 15-32
Resource manager· 3-3, 22-4
RMS$_XAB error • 24-3
RMS Journaling
support for DECdtm services· 29-1 to 29-7
RMS services
using XAB$_NORECORD XABITM • 24-4
RRD40
UETP support· 9-1
RTL (Run-Time Library)
DNS$ routines· A-51 to A-77
mathematics (MTH$) • 23-2
MTH$ routines· 2-4,2-19, 2-21
parallel processing (PPL$) • 23-1
vectorized MTH$ routines· 2-4,2-19,2-21

Index-10

s
SAVE subcommand
with SET HOST/DTE command • 4-2
Scalar
defined • 2-1
processor synchronization • 2-32
Scalar consumer • 2-5
Scale Factor processing option· 7-3
Screen
supporting more than one· 7-1
SCSI disk class driver
disabling the loading of· 12-1
SCSI tape class driver
disabling the loading of· 12-1
SCSI_NOAUTO system parameter· 12-1
SCU/XMI bus
I/O address space • 27-1
SCU/XMI bus architecture • 27-1
SDA (System Dump Analyzer)
support for vectorized programs • 2-25
vector processing support· 26-2
Second Generation Ethernet Controller (SGEC)
circuit name· 17-2
line name • 17-2
Security
converting message from binary to ASCII· 22-21
enhancements to NETCONFIG.COM
for existing systems • B-4
for new systems • B-2
filtering sensitive message information • 22-21
hashing passwords • 22-25
screening new passwords • 14-1
password history list· 14-2
site-specific filter • 14-2
site-defined password policy • 14-1 to 14-4
specifying an encryption algorithm • 14-3
SEND BREAK subcommand
with SET HOST/DTE command • 4-2
Server
Display PostScript system· 31-4
Session language
new languages • 7-1
setting another· 7-1
SET (VMSINSTAL callback) • 30-1
SET ACL command • 2-12
/BACKUP qualifier· 4-1
CAPABILITY object type· 4-1
/EXPIRED qualifier· 4-1
IMODIFIED qualifier· 4-1

Index

c
o

SET/DEFINE EXECUTOR command· A-1
SET DTE subcommand
with SET HOST/DTE command • 4-2
SET HOST/DTE command· 4-1
subcommands
CLEAR· 4-2
EXIT ·4-2
QUIT· 4-2
SAVE· 4-2
SEND BREAK· 4-2
SET DTE ·4-2
SHOW DTE • 4-2
SPAWN ·4-2
SET MAGTAPE command
/MEDIA_FORMAT qualifier· 4-2
SET PROFILE/VERIFY command
in SYSMAN Utility· 10-1
SET SHUTDOWN (VMSINSTAL callback option) •
30-1
SET SYMBOL command
new qualifiers • 4-2
symbol scoping • 4-2
SET TERMINAL command
/DEC_CRT qualifier· 4-2
Shadowing
See Volume shadowing
Shadow Set Virtual Unit Driver· 25-1
SHDRIVER • 25-1
SHOW ACL command • 2-12
CAPABILITY object type· 4-2
SHOW/BI=Blindex command
in System Generation Utility (SYSGEN) • 12-4
SHOW/BUS=busld command
in System Generation Utility (SYSGEN)· 12-5
SHOW command
LMCP Utility· 15-33
SHOW CPU command • 4-2
vector processing support· 2-13
SHOW DTE subcommand
with SET HOST/DTE command· 4-2
SHOW EXECUTOR CHARACTERISTICS command •
A-2
SHOW PROCESS command
vector processing support • 2-13
SHOW PROCESS/IMAGES
SDA (System Dump Analyzer) • 26-1
SHOW PROCESSIVECTOR_REGISTERS
SDA (System Dump Analyzer) • 26-2
SHOW/XMI=Blindex command
in System Generation Utility (SYSGEN) • 12-6
SHOW ZONE command· 4-2

Simple name
converting to opaque • A-33
Simple_Name_Str identifier· A-44
/SINCE qualifier
EXCHANGE/NETWORK command • C-22
Skulk· A-17
SMP_CPUS parameter· 2-9
Soft link
DNS·A-7
enumerating • A-30
locating target entry • A-34
SPAWN command
in SYSMAN Utility· 10-1
SPAWN subcommand
with SET HOST/DTE command • 4-2
SPKITBLD.COM· 30-1
SS$_ACCVIO· 2-27,2-29
SS$_BADCONTEXT· 2-31
SS$_CPUNOTACT· 2-31
SS$_EXQUOTA· 2-31
SS$_ILLVECOP • 2-29
SS$_INSFMEM • 2-31
SS$_INSFWSL· 2-31
SS$_MCHECK· 2-31
SS$_NOPRIV • 2-31
SS$_VARITH· 2-28,2-30
SS$_VASFUL· 2-31
SS$_VECALIGN • 2-27, 2-30
SS$_VECDIS • 2-30
START/CPU command • 2-9, 4-2
Starting a transaction· 22-48, 22-50, 22-52
START/ZONE command • 4-2
STOP/CPU command • 2-9, 4-2
STOP/ZONE command· 4-2
Stored semantics file attribute
See File tag
Swap file
controlling size in AUTOGEN • 8-3
deinstalling • B-1
Sychronization
exception • 2-32
memory • 2-32
Symbol scoping
F$ENVIRONMENT lexical function • 4-3
SET SYMBOL command • 4-2
Symmetric vector processing configuration • 2-2
SYNDROME keyword
Error Log Utility (ERROR LOG)· 13-2
SYS$ABORT_TRANS • 22-6, 22-11
SYS$ABORT_ TRANSW • 22-15
SYS$CANWAK system service • B-14

Index-11

Index

o
SYS$CHANGE_ACL· 22-53
SYS$CHECK_ACCESS· 22-54
SYS$DECDTM_INHI8IT logical name· 3-1,15-4
SYS$DELPRC system service· 8-14
SYS$DEVICE_SCAN system service· 8-9, 8-38,
8-39
SYS$DISMOUNT system service· 8-13
SYS$DNS system service
See $DNS system service
SYS$END_TRANS· 22-6,22-16
SYS$END_TRANSW· 22-20
SYS$ENQ • 22-54
SYS$FORCEX system service· 8-14
SYS$FORMAT_AUDIT· 22-21
SYS$GETDVI • 22-55
SYS$GETJPI· 2-22 to 2-23,22-55
SYS$GETJPI system service· 8-14, 8-15
See also SYS$PROCESS_SCAN system service
AST in target process • 8-33
buffer • 8-31, 8-33
control flags • 8-33
defined • 8-15
item codes • 8-18
item list· 8-22, 8-31
item-specific flags • 8-22
obtaining information about all processes on the
local system • 8-18, 8-20
obtaining information about one process • 8-18
obtaining information with $PROCESS_SCAN
context • 8-1 8
obtaining information with PID· 8-18
obtaining information with wildcard search
example • 8-21
packing information in buffers· 8-31, 8-33
searching for processes on all nodes· 8-29
searching for processes on specific nodes • 8-28,
8-29
searching for selected processes· 8-22
specifying buffer size • 8-31, 8-33
specifying criteria to select processes
example • 8-27
swapping processes· 8-33
synchronizing calls· 8-28, 8-29, 8-30
using $PROCESS_SCAN item list to specify
selection criteria about processes • 8-22,
8-24, 8-26, 8-27
using $PROCESS_SCAN item-specific flags to
control selection information • 8-22
using $PROCESS_SCAN search· 8-22
using item list to specify selection criteria about
processes

Index-12

SYS$GETJPI system service
using item list to specify selection criteria about
processes (Cont.)
example • 8-26
using item list with remote procedures· 8-31
using multiple $PROCESS_SCAN contexts· 8-30
using synchronous calls • 8-30
using wildcard
example· 8-21
using wildcard as pidadr· 8-18, 8-20
using wildcard search· 8-20
SYS$GETSYI· 2-22 to 2-23,22-58
SYS$GETUAI • 22-58
SYS$GETUAI system service· 8-10
authorization flags • 8-12
new item codes • 8-11
SYS$HASH_PASSWORD • 22-25
SYS$INIT_VOL· 22-9,22-28
examples • 22-9 to 22-1 0
SYS$JOU RNAL logical name· 15-1, 15-8
defining as a search list· 15-2
SYS$MOD_IDENT· 22-60
SYS$MOUNT· 22-60
SYS$MOUNT system service· 8-12
SYS$PROCESS_SCAN system service· 8-9, 8-15,
8-38, 8-42
See also SYS$GETJPI system service
defined • 8-15
obtaining information about processes on all
nodes· 8-29
obtaining information about processes on specific
nodes· 8-28,8-29
searching on all nodes· 8-29
searching on specific nodes • 8-28, 8-29
setting up multiple contexts • 8-30
specifying selection criteria about processes
example • 8-26
using $PROCESS_SCAN item list to specify one
selection criterion about processes
example • 8-24
using item list to control selection information
example • 8-26
using item list to specify selection criteria about
processes • 8-22, 8-24
example • 8-26, 8-27
using item list with remote procedures • 8-31
using item-specific flags to control selection
information • 8-22
example • 8-24
SYS$RELEASE_VP • 2-23, 22-41
SYS$RESTORE_VP_EXCEPTION • 2-24, 22-42
SYS$RESTORE_VP_STATE • 2-24, 22-44

o
o

Index

o
SYS$RESUME system service· 8-14
SYS$SAVE_VP_EXCEPTION - 2-24, 22-46
SYS$SCHDWK system service· 8-14
SYS$SETPRI system service· 8-14
SYS$SETUAI • 22-60
SYS$SETUAI system service· 8-1
authorization flags • 8-12
new item codes • 8-11
SYS$START_TRANS • 22-4, 22-48
SYS$START_ TRANSW • 22-4, 22-52
SYS$SUSPEND system service - 8-14
SYS$WAKE system service· 8-14
SYSGEN parameters· A-1
using to control load balancing - 11-1
SYSMAN Utility • 10-1
commands
ATTACH· 10-1
@ command· 10-1
DEFINE ·10-1
SET PROFILE· 10-1
SPAWN -10-1
System disk
shadowing the • 18-1
System Generation Utility (SYSGEN) - 2-8, 2-9,
2-11, 8-1 to 8-2
commands
SHOW/81=8lindex • 12-4
SHOW/8US=busld • 12-5
SHOW/XMI=8Iindex - 12-6
DEINSTALL command· 8-1
ERL8UFFERPAGES parameter· 8-2
parameters
LOAD_PWD_POLICY - 12-2
LOAD_SYS_IMAGES - 12-2
using parameters to control load balancing -11-1
System management
pool check parameter· 27-7
System messages
accessing with online help • 6-2
facilities with new and modified messages • 6-1
System object
default access for· 8-2
System parameters
description - 8-2
displaying
bus adapter· 12-4, 12-5, 12-6
pool check • 27-7
System service·A-25, 8-9, 8-10, 8-11, 8-12, 8-14
Abort Transaction • 22-11
Abort Transaction and Wait· 22-15
End Transaction • 22-16

o
o

System service (Cont.)
End Transaction and Wait • 22-20
Format Security Audit Event Message • 22-21
Hash Password· 22-25
Initialize Volume • 22-9, 22-28
list of new services • 22-1
loading site-specific • 22-62
obtaining information about processes • 8-15
Release Vector Processor· 22-41
Restore Vector Processor Exception State • 22-42
Restore Vector State • 22-44
Save Vector Processor Exception State· 22-46
Start Transaction • 22-48
Start Transaction and Wait • 22-52
transaction management services • 3-6
System Tuning
automated technique for running AUTOGEN • 8-4
SYS_LOADA8LE command
in SYSMAN Utility· 10-1

T
TA90E tape drive
controlling data compaction • 4-1, 4-2
Tape
initializing from within a program • 22-9, 22-28
examples • 22-9 to 22-1
TASK object
restricting default access • 8-3
TP_SERVER process
disabling • 3-1, 15-4
Transaction
aborting • 3-4, 3-7, 22-4, 22-11, 22-13, 22-15
atomic· 3-2
committing-3-4, 3-7, 22-4, 22-16, 22-18, 22-20
examples • 3-1
forgetting • 15-29
monitoring • 16-1, 16-7
participants· 3-4, 3-6, 15-10, 22-4, 22-13,
22-18
starting· 22-48, 22-50, 22-52
states· 3-6, 15-10,22-4
Transaction identifier (TID)· 3-6, 15-10, 22-4,
22-13,22-18,22-48,22-50,22-52
Transaction log file • 3-5, 15-1
creating • 15-4, 15-14, 15-16
determining location • 15-2
dumping • 15-18
estimating file size • 15-4
format

Index-13

Index

c
Transaction log file
format (Cont.)
description • 15-9
sample display • 15-9
placing in alternate location • 15-8
repairing· 15-23
resizing • 15-7
showing· 15-33
Transaction management· 22-2
Transaction manager· 3-4, 22-4
Transaction processing • 3-1
Transaction states • 15-24
Transfer modes
EXCHANGE/NETWORK command • C-18
/TRANSFER_MODE qualifier
EXCHANGE/NETWORK command • C-23
TRM$_MODIFIERS itemlist item code· 25-1
Two-phase commit protocol· 3-2, 3-7, 22-6

u
UETP (User Environment Test Package)
support for RRD40 • 9-1
testing the DECnet connection • B-3
testing thE:! VAX Vector Instruction Emulation
Facility (VVIEF) • 9-1
testing vector processors • 9-1
Use Bitmap Widths toggle button • 7-4
Use Comments toggle button • 7-3
Use Fake Trays Toggle button· 7-4
User Environment Test Package
See UETP
User-written programs and procedures
default access for· B-3

v
VAX 9000
bus architecture • 27-1
device support· 27-1
hardware • 27-1
I/O address space· 27-1
VAX 9000 bus
address • 27-1
VAXcluster
MSCP server load balancing • 11-1
using multiple CI interfaces ·11-1
using multiple STAR couplers ·11-1

Index-14

VAXcluster (Cont.)
volume shadowing in • 18-1
VAXcluster failover· 15-1, 15-3
VAXft 3000
adding a zone to a running system • 4-2
device names • 12-3
device types supported by Error Log Utility· 13-1
displaying current state of system • 4-2
line and circuit support within NCP • 17-1
removing a zone from a running system • 4-2
SHOW ZONE command • 4-2
STOP/ZONE command • 4-2
VAX Procedure Calling Standard
requirements for vectorized programs· 2-31 to
2-33
VAX Text Processing Utility
See VAXTPU
VAXTPU· 28-1 to 28-2
VAX Vector Instruction Emulation Facility
See VVIEF
Vector
defined • 2-1
Vector arithmetic exception
debugging· 2-17, 2-27
Vector capability· 2-5
determining availability within a system • 2-13
placing an ACL on • 2-11 to 2-12
Vector-capable system· 2-2
Vector consumer • 2-6
determining the identity of· 2-13, 2-22
managing • 2-9 to 2-12
marginal· 2-6, 2-11
obtaining information about • 2-12 to 2-15, 2-22
to 2-23
Vector context • 2-5
preserving· 2-23, 2-32
Vector context switch
fast· 2-7
obtaining information about· 2-13,2-22
slow· 2-7
Vector count register • 2-2
Vector CPU time
definition • 2-14
obtaining information
about image • 2-14
about process· 2-13,2-14,2-22
about processor • 2-14
about system • 2-14
obtaining information regarding processor· 16-9
obtaining information regarding system • 16-9
Vector exception

Index

c
Vector exception (Cont.)

o
o

arithmetic • 2-17, 2-27
memory management • 2-27
servicing • 2-27 to 2-31
Vector exception state
preserving across procedure boundaries· 2-23 to
2-25, 2-32
Vectorized program
debugging • 2-25 to 2-31, 19-1
definition • 2-3 to 2-5
requirements when written in VAX MACRO • 2-20
writing • 2-4, 2-19 to 2-33
Vectorizing compiler· 2-4, 2-19
VECTOR keyword
Error Log Utility • 2-14
Error Log Utility (ERROR LOG) ·13-1
Vector length register· 2-2
Vector mask register· 2-2
Vector-present processor· 2-2
adding to system • 2-8 to 2-9
identifying • 2-13, 2-23
removing from system • 2-8 to 2-9
when unavailable • 2-9
Vector processing • 2-1 to 2-34
benefits of • 2-3
establishing batch queues for • 2-10
F$GETJPI lexical function • 4-3
integrated model· 2-2
management considerations • 2-8 to 2-19
resource requirements • 2-10
SET ACL command • 4-1
SHOW ACL command • 4-2
support within Monitor Utility • 16-7 to 16-10
system descriptions • 2-2 to 2-3
system messages • 2-15 to 2-19
testing with the User Environment Test Package
(UETP)· 9-1
Vector processing support code
loading • 2-5, 2-8
Vector processing system
configuring • 2-8 to 2-9
obtaining information about • 2-12 to 2-15, 2-22
to 2-23
obtaining number of vector processors in • 2-13,
2-23
performance • 2-1
tuning • 2-10 to 2-11
Vector processor
releasing • 2-23, 22-41
restoring the exception state of • 22-42
saving the exception state of • 22-46
Vector register • 2-2

Vector state
definition • 2-24
restoring • 22-44
VECTOR_MARGIN parameter· 2-11
VECTOR_PROC parameter • 2-8
Version number
assigning • C-19
VIEW command
PostScript file support· 7-3
PS input format • 4-2
viewing PostScript files • 4-2
VMSINSTAL callback
CHECK_VMS_VERSION· 30-1
GET_PASSWORD· 30-1
SET ·30-1
VMS Performance Monitor
See VPM
VMS Volume Shadowing
See Volume shadowing • 18-1
Volume
initializing from within a program· 22-9, 22-28
examples • 22-9 to 22-10
Volume shadowing
configurations· 18-1
disk repair and recovery • 18-1
F$GETDVI lexical function • 4-3
fault tolerance • 18-1
in a VAXcluster· 18-1
mixing phase I and phase 1/ • 18-2
overview· 18-1
phase II support· 18-1
the system disk· 18-1
types· 18-1
VPM (VMS Performance Monitor) • 8-3
default access for • 8-3
VT 400 terminal
SET TERMINAL command· 4-2
setting characteristics for • 4-2
VVIEF$DINSTAL.COM • 2-15
VVIEF$INSTAL.COM • 2-15
VVIEF (VAX Vector Instruction Emulation Facility)
determining presence of·2-13, 2-15, 2-23
loading • 2-15
overview • 2-7 to 2-8
testing with the User Environment Test Package
(UETP)· 9-1
unloading • 2-15

Index-15

Index

o
w
Watch Progress toggle button • 7-4
Wildcard character
DNS • A-9, A-21
EXCHANGE/NETWORK command· C-19
Wildcard search
obtaining information about processes • B-42
example • B-21
using $GETJPI • B-20

x
XAB$_ENABLE symbol· 24-3
XAB$_MULTIBUFFER_COUNT XABITM
implementation of • 24-1
supporting data structure requirement • 24-1
XAB$_NORECORD XABITM • 24-3
buffer requirement • 24-3
typical usage· 24-4
XMI bus
memory space· 27-1

(

/-"
\

I~j

o
Index-16

)
·
C
\

How to Order Additional Documentation

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

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

Telephone and Direct Mail Orders

c
o

Your Location

Call

Contact

Continental USA,
Alaska, or Hawaii

BOO-DIGITAL

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

Puerto Rico

B09-754-7575

Local Digital subsidiary

Canada

BOO-267 -6215

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

International

Local Digital subsidiary or
approved distributor

Internal l

USASSB Order Processing - WMOlE15
or
U.S. Area Software Supply Business
Digital Equipment Corporation
Westminster, Massachusetts 01473

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

(

\
,

c
o

Reader's Comments

VMS Version 5.4 New
Features Manual

AA-LA97C-TE

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

I rate this manual's:

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

Excellent

Good

Fair

Poor

D
D
D
D
D
D
D
D

I would like to see morelless

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page

Descri ption

Additional comments or suggestions to improve this manual:

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

Name/Title

Dept.

Company

Date

Mailing Address
Phone

- - - Do Not Tear - Fold Here and Tape ------------------~lllr--------------

,CI

No Postage

~D.D".DTM
~

I
I
I
I

~ece~sary

W IIW

If Mailed
in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADRESSEE

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

111 ••••• 11.1111 •• 11 •••• 1.11.1111.1 •• 1•• 1.1 ••• 1.11 •• 1
- - - Do Not Tear - Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

o
Q,.l