r089 03

VOS Commands User’s Guide
Stratus Technologies
R089-03
Notice
The information contained in this document is subject to change without notice.
UNLESS EXPRESSLY SET FORTH IN A WRITTEN AGREEMENT SIGNED BY AN AUTHORIZED

REPRESENTATIVE OF STRATUS TECHNOLOGIES, STRATUS MAKES NO WARRANTY OR REPRESENTATION
OF ANY KIND WITH RESPECT TO THE INFORMATION CONTAINED HEREIN, INCLUDING WARRANTY OF
MERCHANTABILITY AND FITNESS FOR A PURPOSE. Stratus Technologies assumes no responsibility or obligation
of any kind for any errors contained herein or in connection with the furnishing, performance, or use of this document.
Software described in Stratus documents (a) is the property of Stratus Technologies International, S.à r.l. or the third
party, (b) is furnished only under license, and (c) may be copied or used only as expressly permitted under the terms
of the license.
Stratus documentation describes all supported features of the user interfaces and the application programming
interfaces (API) developed by Stratus. Any undocumented features of these interfaces are intended solely for use by
Stratus personnel and are subject to change without warning.
This document is protected by copyright. All rights are reserved. No part of this document may be copied, reproduced,
or translated, either mechanically or electronically, without the prior written consent of Stratus Technologies.
Stratus, the Stratus logo, Continuum, Continuous Processing, StrataLINK, and StrataNET are registered trademarks of
Stratus Technologies International, S.à r.l.
The Stratus Technologies logo, ftServer, ftServer with design, Stratus 24 x 7 with design, The World’s Most Reliable
Servers, The World’s Most Reliable Server Technologies, ftMemory, ftMessaging, ftStorage, Selectable Availability,
XA/R, SQL/2000, and The Availability Company are trademarks of Stratus Technologies International, S.à r.l.
RSN is a trademark of Lucent Technologies, Inc.

All other trademarks are the property of their respective owners.
Manual Name: VOS Commands User’s Guide
Part Number: R089

Revision Number: 03
VOS Release Number: 14.4.0
Printing Date: April 2002
Stratus Technologies, Inc.

111 Powdermill Road
Maynard, Massachusetts 01754-3409
© 2002 Stratus Technologies International, S.à r.l. All rights reserved.

Contents
Preface xvii
1. User Processes and Passwords 1-1

Your User Process 1-1
Subprocesses 1-1
Status of Your Process 1-2
Priority Levels 1-2
Privileged Processes 1-3
System-Generated Files 1-3
Ports 1-4
The default_output Port 1-4
The default_input Port 1-4
Ports That You Create 1-5
Password Format and Usage 1-6
Entering Your Password 1-6
Limits on Login Failures 1-6
Changing Your Password 1-7
2. Understanding the Command Language 2-1

Arguments 2-1
Default Values 2-2
Predefined Values 2-2
Required and Optional Arguments 2-2
Numerical Arguments 2-3
Labels and Keywords 2-3
Display Form and Command-Line Form 2-3
Display Form 2-3
Command-Line Form 2-4
Retrieving a Command Line 2-4
Giving Argument Values 2-5
Positional Arguments (Command-Line Form Only) 2-5
Arguments with One Predefined Value 2-6
Switches 2-6
Contents iii
Contents
Arguments with Several Predefined Values 2-6

Other Keyword Arguments 2-7
Entering Character-String Values 2-7
Entering Star Name Pair Values 2-7
Where to Find More Information 2-8
3. National Language Support 3-1

Configuring Languages Supported on the Module 3-2
Process Language 3-2
Default Character Set 3-3
System Error Messages 3-4
Defining Per-Command Message Files 3-4
The message_file.dd File 3-5
Example of a command_name.tin Entry 3-6
Creating a Per-Command Message File 3-6
Message Library 3-7
4. How the System Processes Commands 4-1

Command Processing Loop 4-1
How the System Locates Commands to Execute 4-2
Determining the Components of a Command 4-2
Libraries 4-3
Library Paths 4-4
Command Search Rules 4-5
Changing the Search Rules for a Module 4-7
Changing the Search Rules for Your Process 4-10
5. Using Abbreviations 5-1

Abbreviations Facility 5-1
Abbreviations File 5-2
Sample Abbreviations File 5-2
The use_abbreviations Command 5-3
Types of Replacement Directives 5-3
First Directives 5-4
Subsequent Directives 5-4
All Directives 5-4
Symbol Directives 5-5
Abbreviation Parameters 5-6
Controlling Abbreviations 5-8
Steps in Replacing Abbreviations 5-9
iv VOS Commands User’s Guide (R089)

Contents
6. Introduction to Command Functions 6-1

Basic Information 6-1
Brief Descriptions 6-2
Information 6-3
Calculations 6-5
String Manipulations 6-6
Numeric 6-8
Files and Directories 6-9
7. Using Command Macros 7-1

Introduction to Command Macros 7-2
Definition and Example 7-2
Invoking a Command Macro 7-3
The Macro Processor 7-3
Elements of a Command Macro 7-3
Command Lines 7-3
Macro Lines 7-4
Command Macro Statements 7-4
Comment Lines 7-4
Parameter Declarations 7-4
Input Lines 7-5
Spaces 7-5
Punctuation 7-5
Separators 7-6
Operators 7-6
Line Continuation Characters 7-6
Ampersands 7-6
Apostrophes 7-7
Exclamation Points 7-7
Dollar Signs 7-8
Command Functions in Macros 7-8
Abbreviations in Macros 7-9
Expressions in Macros 7-9
Macro Variables 7-10
Parameters 7-13
Parameter Declarations 7-13
Parameter Descriptors 7-14
General Form 7-14
Labels 7-15
Specifiers 7-15
Qualifiers 7-16
Defaults 7-17
Contents v
Contents
Parameter Types 7-18

Positional Parameters 7-18
Optional Parameters 7-21
Switch Parameters 7-24
Parameter Data Types 7-26
End Qualifiers 7-37
How a Command Macro Is Processed 7-37
Avoiding Macro Recursion Loops 7-38
Startup Command Macros 7-38
Examples of Command Macros 7-41
The append_file.cm Macro 7-41
The append_list.cm Macro 7-42
The compile_and_go.cm Macro 7-42
8. Executing Noninteractive Processes 8-1

Batch Processes 8-1
Priorities 8-2
Queue Priority 8-2
Process Priority 8-3
Batch Control File 8-3
Batch Control Directives 8-4
Commands Related to Batch Processing 8-6
Started Processes 8-6
9. Understanding Access Control 9-1

Types of Access Rights 9-1
File Access Rights 9-3
Directory Access Rights 9-4
Access Control List Entries 9-4
User Names 9-5
How Access Control List Entries Are Sorted 9-5
Types of Access Control Lists 9-6
File Access Control Lists 9-6
Directory Access Control Lists 9-6
Default Access Control Lists 9-6
How the System Determines Access 9-7
Commands for Displaying Access 9-8
The display_access_list Command 9-9
The display_default_access_list Command 9-10
The display_access Command 9-10
Commands for Managing Access 9-12
The give_access Command 9-13
vi VOS Commands User’s Guide (R089)

Contents
The remove_access Command 9-15

The give_default_access Command 9-15
The remove_default_access Command 9-16
The propagate_access Command 9-17
The set_owner_access Command 9-18
The verify_posix_access Command 9-19
Appendix A. Commands Grouped by Task A-1

Batch Processing A-1
Break/Interrupt A-2
Controlling Access to Data A-2
Access Control A-2
Displaying Access A-3
Controlling File Access A-4
Controlling Directory Access A-4
Controlling System Access A-5
Customizing Your Environment A-5
Creating Synonyms A-5
Setting Up Program Libraries A-5
Setting Up Your Process Environment A-6
Setting Up Your Terminal A-6
Editing A-6
Getting Started A-7
Communicating with Other Users A-7
Getting Information about Devices A-7
Getting Information about the System A-7
Getting On and Off the System A-8
Getting Status Information A-9
Managing Files and Directories A-10
Backing Up and Restoring Files A-10
Changing Directories A-10
Converting Files A-10
Creating and Deleting Directories A-10
Creating and Deleting Files A-10
Copying, Renaming, and Moving Directories A-11
Copying, Renaming, and Moving Files A-11
Getting Information about Files A-11
Getting Information about Directories A-11
Comparing Directories A-12
Comparing Files A-12
Displaying Files A-12
Locating Files A-12
Locating Directories A-12
Sorting Files A-12
Contents vii
Contents
Ports A-13
POSIX A-13
Printing A-14
Getting Information about Printers A-14
Getting Information about Print Requests A-14
Printing Files A-14
Programming A-14
Analyzing Programs A-14
Compiling and Binding Programs A-14
Debugging Programs A-16
Executing Programs A-18
Writing Programs A-19
Administering Systems A-19
Tape Processing A-20
Terminal Management A-22
Appendix B. Halting Program Execution B-1

Break Level B-1
Break-Level Command Descriptions B-2
The stop Command B-2
The continue Command B-2
The keep Command B-3
The re-enter Command B-3
Appendix C. Command Function Reference C-1

(abs N) C-3
(access path_name [user_name]) C-3
(after S1 S2) C-4
(ask [prompt [response_qualifier]]
[-no_echo]) C-4
(before S1 S2) C-6
(break S C) C-6
(byte I) C-6
(calc expression) C-6
(ceil N) C-10
(command_status) C-10
(concat S1 ...Sn) C-10
(contents path_name [line_number]
[open_status]) C-11
(copy S I) C-11
(count S C) C-11
(current_dir) C-12
viii VOS Commands User’s Guide (R089)

Contents
(current_module) C-12
(date [date_string][-long][-standard]) C-12
(date_time [date_time_string][-long]
[-standard]) C-13
(decimal I) C-15
(directory_name path_name) C-15
(end_of_file path_name) C-15
(exists path_name [object_type]
[chase_code]) C-15
(file_info path_name key) C-16
(floor N) C-17
(given parameter) C-17
(group_name) C-17
(has_access path_name access_code
[user_name]) C-17
(hexadecimal I) C-18
(home_dir) C-19
(index S1 S2) C-19
(iso_date [date_string][-long][-standard]) C-19
(iso_date_time [date_time_string][-long]
[-standard]) C-20
(language_name) C-21
(length [S]) C-21
(lock_type path_name) C-22
(locked path_name) C-22
(ltrim S [C]) C-22
(master_disk [module_name]) C-23
(max N1 N2) C-23
(message status_code [S1[S2[S3]]][-number]) C-23
(min N1 N2) C-24
(mod N1 N2) C-25
(module_info key) C-25
(module_name module_name) C-25
(object_name path_name [suffix]) C-26
(online [module_name]) C-26
(path_name path_name [suffix]) C-26
(person_name) C-27
(process_dir) C-27
(process_info key) C-27
(process_type) C-28
(quote S1 ...Sn) C-29
(rank C) C-29
(referencing_dir) C-29
(reverse S) C-30
(rtrim S [C]) C-30
Contents ix
Contents
(search S C) C-30
(software_purchased software_purchased_bit) C-31
(string S1... Sn) C-31
(substitute S1 S2 S3 [-ignore_quotes]) C-31
(substr S I1 [I2]) C-32
(system_name) C-32
(terminal_info key) C-32
(terminal_name) C-33
(time[time_string][-long][-standard]) C-33
(translate S1 [S2[S3]]) C-34
(trunc N) C-35
(unique_string) C-35
(unquote S) C-35
(user_name) C-36
(verify S C) C-36
(where_path path_name [type]) C-36
Appendix D. Macro Statement Reference D-1

&attach_input D-3
&begin_parameters D-5
&break D-6
&continue D-7
&control D-8
&detach_input D-9
&display_line D-10
&display_line_partial D-12
&do D-13
&echo D-15
&end D-17
&end_parameters D-18
&eof D-20
&eval D-21
&goto D-23
&if D-25
&label D-28
&mode D-29
&return D-31
&set D-32
&set_string D-34
&while D-36
x VOS Commands User’s Guide (R089)

Contents
Appendix E. Using the Line Editor E-1

Basic Concepts E-1
Text Buffer E-1
Saved Path Name E-2
Line Editor Modes and Switches E-2
Line Editor States and Requests E-3
The Current Line E-4
The Current Search String E-4
Forms of Requests E-4
Using the Line Editor in Command Macros E-6
The upward Qualifier E-6
Repeated Requests E-7
The <CTRL> <BREAK> Request E-7
Line Editor Requests E-8
Conventions Used in Request Descriptions E-9
Request Descriptions E-10
Carriage Return (CR) E-10
n E-10
t+[n] E-10
-[n] E-10
= E-10
append/text/ E-10
bottom E-11
change[n]/[text1]/[text2]/[m] E-11
copy n[:m] E-11
delete[n] E-11
find /[text]/ E-12
goto[n] E-12
insert [/text/] E-12
join E-13
locate /[text]/ E-13
mode E-13
move n[:m] E-13
overlay[n]/[text1]/[text2]/[m] E-13
path E-14
print[n] E-14
quit E-14
read path_name E-14
skip[n] E-15
tab[tab_specifier] E-15
write [path_name[n]] E-16
Contents xi
Contents
Appendix F. Predefined Ports F-1

How the System Uses the Predefined Ports F-1
Attachments of Predefined Ports F-3
Appendix G. Specifying Dates and Times G-1
Appendix H. Using the Online Help Facility H-1

Requesting Help Information H-2
Using the Help Menu Subsystem H-2
Tasks H-3
Commands H-3
Command Functions H-4
Help H-4
Getting Information about Individual Commands H-4
Getting Information about a Command’s Arguments H-5
Writing Help Messages H-6
Glossary Glossary-1
Index Index-1
xii VOS Commands User’s Guide (R089)

Figures
Figure 4-1. Library Directories in the system Directory 4-4

Figure 4-2. The Operating System’s Command Search Rules 4-6
Figure 4-3. Sample Search Path for a Command 4-9
Figure H-1. Main Menu of the Help Subsystem H-3
Figures xiii
Tables
Table 5-1. Special Replacement Characters in Symbol Directives 5-5

Table 9-1. Access Rights Required for File-Related Tasks 9-2
Table 9-2. Access Rights Required for Directory-Related Tasks 9-3
Table C-1. Arithmetic, Logical, and String Expression Operators C-7
Table C-2. Information Returned by the (file_info) Command
Function C-16
Table C-3. Information Returned by the (module_info) Command
Function C-25
Table C-4. Information Returned by the (process_info)
Command Function C-27
Table C-5. Information Returned by (terminal_info) Command
Function C-32
Table E-1. Line Editor Mode Settings E-2
Table E-2. The Line Editor Requests E-8
Table F-1. Predefined Ports and Port Identifiers F-1
Table F-2. Factors That Determine Port Attachments F-3
Table F-3. Attachments When an Interactive Process Executes a
Command F-4
Table F-4. Attachments When a Noninteractive Process Executes a
Command F-4
Table F-5. Attachments When an interactive Process Executes a
Command after executing attach_default_output F-4
Command after executing attach_default_output F-5
Command Macro F-5
Command Macro F-5
Command Macro Containing the Command
attach_default_output F-6
attach_default_output F-6
Table F-11. Attachments When an interactive Process Executes a
Command Macro Containing the Macro Statement
&attach_input F-6
xiv VOS Commands User’s Guide (R089)

Tables

Command Macro Containing the Macro Statement
&attach_input F-7
attach_default_output and the
Macro Statement &attach_input F-7
attach_default_output and the
Macro Statement &attach_input F-7
Table G-1. Valid Time Zone Input Strings G-3
Tables xv
Tables
xvi VOS Commands User’s Guide (R089)

Preface
The VOS Commands User’s Guide (R089) documents the VOS command
environment and its facilities available with VOS Release 14.4.0.
This manual is intended for those who use or administer Stratus VOS modules. This
manual is also useful to those who need to work with the VOS command environment.
Before working with the VOS Commands User’s Guide (R089), you should be familiar
with the manual Introduction to VOS (R001).
Manual Version
This manual is a revision. Change bars, which appear in the margin, note the specific
changes to text since the previous publication of this manual. Note, however, that
change bars are not used in new chapters or appendixes.
This revision incorporates the following changes.
• New format and complete manual reorganization.

• Documentation for National Language Support in Chapter 3.
• Documentation for using the verify_posix_access command in Chapter 9.
• Addition of the following POSIX commands in Appendix A:
check_posix
handle_sig_dfl
kill
set
verify_posix_access
• Documentation of the following command functions in Appendix C:

(iso_date)
(iso_time)
(software_purchased)
Preface xvii
Preface
• Documentation of the following command macro statements in Appendix D:

&break
&continue
&do
&end
&while
• Support for nested &if-&then-&else statements and stricter syntax-checking

for &if statements. The &if statement is described in Appendix D.
• Restrictions on the command-macro commands used within the &eval command
are described in Appendix D.
• Restrictions on the evaluation of command-macro variables are described in
Appendix D.
• Additional values allowed for time_zone argument of the(date)command are
documented in Appendix G.
Manual Organization
Chapter 1, ‘‘User Processes and Passwords,” discusses priority levels, privileged
processes, and process status information. It includes how to create a subprocess and
how to manipulate ports, and provides information about how and when to change your
password (if you need one on your system).
Chapter 2, ‘‘Understanding the Command Language,” explains how to specify

commands and different types of command arguments using two forms (display form
and command-line form). It also shows you how to get information about commands
and their arguments.
Chapter 3, ‘‘National Language Support,” explains the effects of National Language

Support (NLS) on the user interface. NLS allows you to direct the operating system to
present messages on your display in the national language defined for your process
and the character set appropriate for it.
Chapter 4, ‘‘How the System Processes Commands,” describes how the systems
processes commands and how it locates commands to execute. This chapter also
discusses how you can control the order in which VOS searches through directories for
commands you specify.
Chapter 5, ‘‘Using Abbreviations,” explains how to use the abbreviations facility to

define alternate names for commands or other objects. Using this facility, you can
choose names that are shorter, easier to remember, or otherwise more convenient for
you.
xviii VOS Commands User’s Guide (R089)

Preface
Chapter 6, ‘‘Introduction to Command Functions,” introduces the command functions

and describes how you can use them to return values for arguments in command lines.
Command functions allow you the convenience of specifying an argument once, even
though its value may vary depending on factors such as time of day or the contents of
a file at a given time.
Chapter 7, ‘‘Using Command Macros,” describes how to create command macros so

you can define your own commands, name them according to your preferences, and
stores them where they are most accessible for your purposes.
Chapter 8, ‘‘Executing Noninteractive Processes,” describes how to do non interactive

processing so you can accomplish certain tasks at more convenient times or on more
convenient modules. This frees your interactive process from delays associated with
complicated and time-consuming program execution.
Chapter 9, ‘‘Understanding Access Control,” describes access control. Using the

access control commands, you can make your work more secure; only those users you
authorize can look at or modify the contents of your files and directories. This chapter
also explains how you can determine your own access rights and the access rights of
others to objects in the system.
Appendix A, ‘‘Commands Grouped by Task,” contains a list of VOS commands

categorized by task.
Appendix B, ‘‘Halting Program Execution,” describes how to halt program execution

and the commands that are available once the interruption occurs.
Appendix C, ‘‘Command Function Reference,” provides detailed descriptions of the

VOS command functions. This information is arranged alphabetically.
Appendix D, ‘‘Macro Statement Reference,” provides detailed descriptions of the VOS

command macro statements. This information is arranged alphabetically.
Appendix E, ‘‘Using the Line Editor,” describes the line editor and all available line
editor requests.
Appendix F, ‘‘Predefined Ports,” describes the predefined ports associated with your
process and what their attachments are during program execution.
Appendix G, ‘‘Specifying Dates and Times,” describes how to specify input date/time
strings as arguments to command functions.
Appendix H, ‘‘Using the Online Help Facility,” describes the purpose of the online help
system and explains how to use it.
Preface xix
Preface
Related Manuals
Refer to the following Stratus manuals for related documentation:
• Introduction to VOS (R001)

• VOS Reference Manual (R002)
• VOS Commands Reference Manual (R098)
• VOS POSIX.1: Support Guide (R502)
• VOS Subroutines manuals
VOS PL/I Subroutines Manual (R005)
VOS BASIC Subroutines Manual (R018)
VOS FORTRAN Subroutines Manual (R020)
VOS Pascal Subroutines Manual (R021)
VOS C Subroutines Manual (R068)
Notation Conventions
This manual uses the following notation conventions.
• Italics introduces or defines new terms. For example:

The master disk is the name of the member disk from which the module was
booted.
• Boldface emphasizes words in text. For example:

Every module must have a copy of the module_start_up.cm file.
• Monospace represents text that would appear on your terminal’s screen (such as
commands, subroutines, code fragments, and names of files and directories).
For example:
change_current_dir (master_disk)>system>doc
• Monospace italic represents terms that are to be replaced by literal values. In the
following example, the user must replace the monospace-italic term with a literal
value:
list_users -module module_name
xx VOS Commands User’s Guide (R089)

Preface
• Monospace bold represents user input in examples and figures that contain both
user input and system output (which appears in monospace). For example:
display_access_list system_default
%dev#m1>system>acl>system_default
w *.*
Key Mappings for VOS Functions

VOS provides several command-line and display-form functions. Each function is
mapped to a particular key or combination of keys on the terminal keyboard. To
perform a function, you press the appropriate key(s) from the command-line or display
form. For an explanation of the command-line and display-form functions, see the
manual Introduction to VOS (R001).
The keys that perform specific VOS functions vary depending on the terminal. For
example, on a V103 ASCII terminal, you press the <Shift> and <F20> keys simultaneously
to perform the INTERRUPT function; on a V105 PC/+ 106 terminal, you press the <1> key
on the numeric keypad to perform the INTERRUPT function.
NOTE
Certain applications may define these keys differently.
Refer to the documentation for the application for the
specific key mappings.
The following table lists several VOS functions and the keys to which they are mapped
on commonly used Stratus terminals and on an IBM PC® or compatible PC that is
running the Stratus PC/Connect-2 software. (If your PC is running another type of
software to connect to a Stratus host computer, the key mappings may be different.)
For information about the key mappings for a terminal that is not listed in this table, refer
to the documentation for that terminal.
IBM PC or
V103 V103 Compatible V105 V105
VOS Function ASCII EPC PC PC/+ 106 ANSI
CANCEL <F18> *† *† <5> † or * † <F18>
<F17> <F12> <Alt>-<C> <4> †

CYCLE <F17>
CYCLE BACK <Shift>-<F17> <Shift>-<F12> <Alt>-<B> <7> † <Shift>-<F17>
DISPLAY FORM <F19> -† -† <6> † or - † <F19> or

<Shift>-<Help>
Preface xxi
Preface
IBM PC or
V103 V103 Compatible V105 V105
VOS Function ASCII EPC PC PC/+ 106 ANSI
HELP <Shift>-<F8> <Shift>-<F2> <Shift>-<F2> <Shift>-<F8> <Help>
INSERT DEFAULT <Shift>-<F11> <Shift>-<F10> <Shift>-<F10> <Shift>-<F11> <F11>
INSERT SAVED <F11> <F10> <F10> <F11> <Insert Here>
INTERRUPT <Shift>-<F20> <Shift>-<Delete> <Alt>-<I> <1> † <Shift>-<F20>
NO PAUSE <Shift>-<F18> <Shift>- * † <Alt>-<P> <8> † <Shift>-<F18>
† Numeric-keypad key
Format for Commands and Requests

Stratus manuals use the following format conventions for documenting commands and
requests. (A request is typically a command used within a subsystem, such as
analyze_system). Note that the command and request descriptions do not
necessarily include each of the following sections.
xxii VOS Commands User’s Guide (R089)

Preface
A B
add_disk Privileged
C Purpose
The add_disk command tells the operating system on the current
module to recognize the specified logical volume for the duration of
the current bootload.
D Display Form
-------------------------- add_disk -------------------------
disk_name:
module_name: current_module
E Command Line Form

add_disk disk_name
[ module_name ] G
F Arguments
disk_name Required
The name of the logical volume to be recognized for the current
bootload.
.
H .
.
A name
The name of the command or request is at the top of the first page of the
description.
B Privileged
This notation appears after the name of a command or request that can be issued
only from a privileged process. (See the online glossary, which is located in the file
>system>doc>glossary.doc, for the definition of privileged process.)
C Purpose
Explains briefly what the command or request does.
D Display Form
Shows the form that is displayed when you type the command or request name
followed by -form or when you press the key that performs the DISPLAY FORM
function. Each field in the form represents a command or request argument. If an
argument has a default value, that value is displayed in the form. (See the online
glossary for the definition of default value.)
Preface xxiii
Preface
The following table explains the notation used in display forms.
The Notation Used in Display Forms
Notation Meaning
Required field with no default value.
The cursor, which indicates the current position on the

screen. For example, the cursor may be positioned on the
first character of a value, as in a ll.
current_user The default value is the current user, module, system, or

current_module disk. The actual name is displayed in the display form of the
current_system command or request.
current_disk
E Command-Line Form
Shows the syntax of the command or request with its arguments. You can display
an online version of the command-line form of a command or request by typing the
command or request name followed by -usage.
The following table explains the notation used in command-line forms. In the table,
the term multiple values refers to explicitly stated separate values, such as two or
more object names. Specifying multiple values is not the same as specifying a star
name. (See the online glossary for the definition of star name.) When you specify
multiple values, you must separate each value with a space.
xxiv VOS Commands User’s Guide (R089)

Preface
The Notation Used in Command-Line Forms
Notation Meaning
argument_1 Required argument.
argument_1... Required argument for which you can specify multiple values.
Set of arguments that are mutually exclusive; you must specify

Ç È
argument_1
one of these arguments.
argument_2
[argument_1] Optional argument.
[argument_1]... Optional argument for which you can specify multiple values.
Set of optional arguments that are mutually exclusive; you can

¢ argument_2 £
argument_1
specify only one of these arguments.
Note: Dots, brackets, and braces are not literal characters; you should not type them.
Any list or set of arguments can contain more than two elements. Brackets and braces
are sometimes nested.
F Arguments
Describes the command or request arguments. The following table explains the
notation used in argument descriptions.
G The Notation Used in Argument Descriptions
Notation Meaning
<CYCLE> There are predefined values for this argument. In the display
form, you display these values in sequence by pressing the key
that performs the CYCLE function.
Required You cannot issue the command or request without specifying a

value for this argument.
If an argument is required but has a default value, it is not labeled

Required since you do not need to specify it in the command-line
form. However, in the display form, a required field must have a
value—either the displayed default value or a value that you
specify.
(Privileged) Only a privileged process can specify a value for this argument.
Preface xxv
Preface
H The following additional headings may appear in the command or request

description: Explanation, Error Messages, Examples, and Related Information.
Explanation
Explains how to use the command or request and provides supplementary
information.
Error Messages
Lists common error messages with a short explanation.
Examples
Illustrates uses of the command or request.
Related Information
Refers you to related information (in this manual or other manuals), including
descriptions of commands, subroutines, and requests that you can use with or in
place of this command or request.
Online Documentation
Stratus provides the following types of online documentation.
• The directory >system>doc provides supplemental online documentation,

including updates and corrections to Stratus manuals and a glossary of terms.
• The VOS StrataDOC Web site is an online-documentation service provided by
Stratus. It enables Stratus customers to view, search, download, print, and
comment on VOS technical manuals via a common Web browser. It also provides
the latest updates and corrections available on the VOS document set.
If you are a Stratus customer with a current support contract, you can access the
VOS StrataDOC Web site, at no charge, at http://stratadoc.stratus.com.
You can also order the VOS StrataDOC CD-ROM from Stratus.
This manual is available on the VOS StrataDOC Web site.
For information about accessing the VOS StrataDOC Web site, contact the Stratus
Customer Assistance Center (CAC). For information about ordering the VOS
StrataDOC CD-ROM, see the next section, “Ordering Manuals.”
xxvi VOS Commands User’s Guide (R089)

Preface
Ordering Manuals
You can order manuals in the following ways.
• If your system is connected to the Remote Service Network (RSN™), issue the
maint_request command at the system prompt. Complete the on-screen form
with all of the information necessary to process your manual order.
• Customers in North America can call the Stratus Customer Assistance Center
(CAC) at (800) 221-6588 or (800) 828-8513, 24 hours a day, 7 days a week. All
other customers can contact their nearest Stratus sales office, CAC office, or
distributor; see the file cac_phones.doc in the directory >system>doc for CAC
phone numbers outside the U.S.
Manual orders will be forwarded to Order Administration.
Commenting on This Manual

You can comment on this manual by using the command comment_on_manual or by
completing the customer survey that appears at the end of this manual. To use the
comment_on_manual command, your system must be connected to the RSN. If your
system is not connected to the RSN, you must use the customer survey to comment
on this manual.
The comment_on_manual command is documented in the manual VOS System

Administration: Administering and Customizing a System (R281) and the VOS
Commands Reference Manual (R098). There are two ways you can use this command
to send your comments.
• If your comments are brief, type comment_on_manual, press <Enter> or <Return>, and
complete the data-entry form that appears on your screen. When you have
completed the form, press <Enter>.
• If your comments are lengthy, save them in a file before you issue the command.
Type comment_on_manual followed by -form, then press <Enter> or <Return>. Enter
this manual’s part number, R089, then enter the name of your comments file in the
-comments_path field. Press the key that performs the CYCLE function to change
the value of -use_form to no and then press <Enter>.
NOTE
If comment_on_manual does not accept the part number
of this manual (which may occur if the manual is not yet
registered in the manual_info.table file), you can use
the mail request of the maint_request command to
send your comments.
Preface xxvii
Preface
Your comments (along with your name) are sent to Stratus over the RSN.
Stratus welcomes any corrections and suggestions for improving this manual.
xxviii VOS Commands User’s Guide (R089)

Chapter 1
User Processes and
Passwords 1-
This chapter has two sections. The first section, ‘‘Your User Process,” discusses the
sequence of states of the system as it works on your programs. The second section,
‘‘Password Format and Usage,” explains the rules for selecting, changing, and using a
VOS password.
Your User Process

The sequence of states of the system as it works on your programs is called your user
process. Your interactive process begins when you log in to the system from a prelogin
state, and ends when you log out and return to a prelogin state. This section has the
following topics:
• ‘‘Subprocesses”
• ‘‘Status of Your Process”
• ‘‘Priority Levels”
• ‘‘Privileged Processes”
• ‘‘System-Generated Files”
• ‘‘Ports”
Subprocesses
A subprocess is an additional user process. When you start a subprocess, the process
from which you started it is suspended but not terminated. You create a subprocess
when you do one of the following:
• from command level or break level, issue the login command

• from within a display form, press the <INTERRUPT> key
• from within an editing session, give the request to start a subprocess
You can specify that the new process can run on any module to which you have
access.
User Processes and Passwords 1-1

Your User Process
When the operating system creates a subprocess, it executes your startup command
macro file if you have one. The subprocess inherits several attributes of its parent
process, such as priority and access privileges, and it executes in the current directory
of the parent process.
To exit from the subprocess, give the logout command. Each successive process
that you start is a subprocess of the preceding process. Therefore, you must log out of
each new subprocess to return to your original process.
See Chapter 7 for information about startup command macro files. See the description
of the login and logout commands in the VOS Commands Reference
Manual (R098).
Status of Your Process

You can get information about the status of your process by pressing the <STATUS> key.
The operating system displays the following information on the status line, which
generally is the last line of your terminal screen:
• the time
• whether or not your process is privileged (see “Privileged Processes” in this
chapter)
• your person name
• the amount of CPU time your process has used since the last update of the
displayed status information
• the accumulated amount of CPU time your process has used since it started
• the number of page faults your process has taken since the last update of the
displayed status information (see “page” and “paging” in the Glossary).
VOS updates the status information every minute. To stop displaying the status
information, press the <Shift> key and the <STATUS> key at the same time.
Note that when you log in from a terminal connected to another module, the status line
displays the date only.
Priority Levels
Every process has a priority level associated with it. A priority level is a number ranging
from 0 (the lowest) to 9 (the highest) that determines the precedence of a process
relative to other processes for the allocation of CPU time. When you are registered to
use the system, the following priorities are assigned to your processes.
• A default priority level. This is the priority that will be assigned to your initial
interactive process unless you specify a different priority.
1-2 VOS Commands User’s Guide (R089)

Your User Process
• A maximum priority level. This is the highest priority level that you can assign to
any of your processes.
You specify a priority with either the -priority argument of the login command or
the -process_priority argument of the batch command or the start_process
command.
If you start a process (either interactive or batch) without specifying a priority, VOS
assigns to the new process the priority of the calling process.
Privileged Processes
Privilege is an attribute of a user allowing him or her to use certain system administrator
commands or subroutines. When you are registered to use the system, the following
information is entered regarding privilege:
• whether your processes are privileged or nonprivileged by default

• if your processes are nonprivileged by default, whether you are allowed to create
privileged processes.
To create a privileged process, use the -privileged argument to the login, batch,
or start_process command.
System-Generated Files
In certain circumstances, the operating system creates files. The types of files that
might appear include the following:
• keystrokes files, which have names such as _edit.t1.32.2

• backup files, which have names with the suffix .backup
• shorthand files, which have the name shorthand_definitions
For descriptions of these files, see the edit command and the emacs command in the
VOS Commands Reference Manual (R098).
The operating system also occasionally creates files with names that look like this:
_mWe$jaRsVZKaaFZN
These files help the operating system manage certain errors and other conditions, such
as simultaneous attempts by two users to edit the same file. The files store data (for
example, a copy of a file) or provide you with other useful information.
Finally, other operating system software can generate files and put them in your home
directory. Refer to the documentation for specific products for descriptions of these
files.

Your User Process
You can handle system-generated files as you do any other files: rename them, delete
them, copy them, move them, and so forth.
Ports
A port is a named logical object that is associated with a file or device in order to provide
I/O access to that file or device. When a port is associated with a file or device, it is said
to be attached to that file or device.
Every interactive process has five predefined ports initially associated with its terminal.
Of the five, you can manipulate two. These are described in this section. See
Appendix F for information about the other three ports.
In addition to the five predefined ports, VOS creates an error port in your process with
a unique name generated by the system. This port gives your process access to a text
file containing error messages, so that actual error messages instead of code numbers
can be displayed on your terminal screen.
You can also create ports for use in programs or for the use of certain commands, as
described under “Ports That You Create” later in this section.
The default_output Port

The default_output port is a predefined port to which VOS writes most output data
from commands. It is usually attached to your terminal if your process is an interactive
process, such as a login process. If your process is not interactive (such as a batch
process), the default_output port is attached to an output file.
You can attach the default_output port to a file using the

attach_default_output command. This causes VOS to write the data going out
of your process to a file. This is useful for saving in a file output that would normally
appear on your terminal.
To reattach the port to its previous attachment (the terminal), use the
detach_default_output command.
The default_input Port

The default_input port is a predefined port through which VOS expects to receive
the input data that commands require. When you log in at a terminal and run a program
interactively, the default_input port is attached to the terminal itself.
You can attach the default_input port to a macro file with the command macro
statement &attach_input. This allows the input data required by a command
contained in a macro to come from the macro itself (instead of from the terminal).
To reattach the port to its previous attachment (the terminal), use the command macro
statement &detach_input.

Your User Process
See Chapter 7 for information about command macros, and Appendix D for a
description of the &attach_input and &detach_input statements.
Ports That You Create

There are two purposes for creating additional ports in your process:
• to provide flexibility within programs

• to provide device attachments for certain commands.
To create a port in your process, use the attach_port command. When you issue
this command, you supply a name for the port and the name of a file or a device. VOS
then does the following:
• creates a logical connection between the port and the file or device (this is referred
to as associating the port with the file or device)
• generates a number called the port identifier
You can then use the port identifier in a program to refer to the associated file or device.
To remove the association between a port name and an object, you detach the port with
the detach_port command. When a port created with the attach_port command
is detached, it no longer exists.
Within a program’s code, you can reference a port identifier instead of a specific file
name or device name. When you execute your program, the program has access to
the named file or device by means of the port identifier, which is determined using
service subroutines. You can then use the same program with many different files or
devices by repeatedly detaching the port and attaching it again to associate the same
port with different files or devices.
Some commands require the use of ports to provide connections to devices. For
example, the commands save_object and restore_object require as the first
argument the port name attached to a magnetic tape drive or disk file. Similarly, most
of the commands used for tape processing require port attachments.
A port you create remains attached until you detach it with the detach_port
command or until your process stops.
A user process can have up to 4096 ports in use at one time. To display a list of the
ports currently attached to your process, use the list_port_attachments
command.

Password Format and Usage

If your registration entry requires you to have a password, you must supply the
password when you give an initial login command. You are not required to give your
password when you give the login command to create a subprocess. This section
includes the following topics:
• ‘‘Entering Your Password”

• ‘‘Limits on Login Failures”
• ‘‘Changing Your Password”
Entering Your Password

You can supply the password in any of the following ways:
• Using the command-line form, give the password following the -password
keyword. The characters are displayed as you type.
• Using the display form, give the password in the -password field. The characters
are not displayed as you type.
• Using either form, give the command without a password, then supply the
password in response to the prompt. The characters are not displayed as you type.
If you mistype your user identification or password, the operating system displays the
following message on the screen:
login: Access denied.
The operating system then redisplays the login banner, and you can attempt to log in
again.
If you realize you have mistyped your password before you enter it, you can use the
<CANCEL> key to delete the incorrect password.
Limits on Login Failures

In some systems, there are limits on the number of successive login failures allowed
per terminal and per user account. Your system administrator can tell you what limits,
if any, are in effect on your system.
If there is a limit imposed on the number of successive login failures allowed for one
terminal, the terminal will be disconnected briefly when the limit is exceeded. If there is
a failure limit imposed on user accounts, the user’s account will be terminated when he
or she exceeds the limit. To have the account reinstated, the user must contact the
system administrator. A user can exceed the single-account limit whether the login
attempts are on one terminal or several terminals.

Changing Your Password

Unless your registration entry imposes restrictions, there is no limit to how often you
can change your password. To do so, use the -change_password option of the
login command. See the description of the login command in the VOS Commands
Reference Manual (R098) for details.
In some systems, passwords are valid for only a specified period of time. One week
before the end of that time period, the operating system issues a warning of the
pending expiration and prompts you for a new password. If you choose not to change
your password at that time, press the <RETURN> key. You must then change your
password in a subsequent login by using the -change_password option of the login
command.
If you do not change your password before the expiration date, your user account is
terminated unless your system allows a grace period. If so, the first time you log in
during the grace period, you receive an expiration warning and a prompt for a new
password. If you disregard the prompt by pressing the <RETURN> key, your user account
is terminated.
When you change passwords, you must select your new password according to the
following rules.
• The new password cannot be the same as your current password.

• If your system administrator has set a minimum password length, the new
password must be no shorter than specified.
• If your system administrator has set the password format for your system to
two_words, the new password must contain a punctuation mark. In this context,
“punctuation mark” means any one of these characters:
! " # $ % ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ‘ { | } ~
A punctuation mark cannot be the first or last character of the password.
• If the new password contains certain punctuation marks that VOS recognizes as
delimiters (!, (, ', ;, or &), you may not be able to log back in and give the
password using the command-line form. However, the password will be accepted
if you wait for the prompt.


Chapter 2
Understanding the Command
Language 2-
This chapter describes VOS command environment and contains the following
sections:
• ‘‘Arguments”
• ‘‘Display Form and Command-Line Form”
• ‘‘Giving Argument Values”
• ‘‘Where to Find More Information”
In working with VOS commands, you should understand two terms that are used
throughout this manual:
• A command line is a set of one or more command strings, separated by

semicolons.
• A command string is a command name and any of the command’s arguments you
select. The elements of a command string are separated either by spaces or by
tabulation characters (entered with the <TAB> key only).
This chapter primarily describes the types of arguments for commands that are built in
to the operating system (the internal commands). See Chapter 6, ‘‘Introduction to
Command Functions for a description of the three types of commands: internal
commands, command macros, and program modules.
Arguments
Most commands take arguments. An argument is a value given with a command that
provides additional information to the command. For example, the file_names
argument of the print command tells VOS which files to print. This section describes
the following arguments:
• ‘‘Default Values”
• ‘‘Predefined Values”
• ‘‘Required and Optional Arguments”
Understanding the Command Language 2-1

Arguments
• ‘‘Numerical Arguments”
• ‘‘Labels and Keywords”
Default Values
Some arguments have default values. A default value is the value predefined by VOS
that is in effect when you do not specify a value. For example, in the print command,
1 is the default value for the -copies argument.
Predefined Values
A predefined value is a value that VOS makes available for an argument.
If an argument has only one predefined value, that value is the default. You can change
the default by specifying a different value.
Some arguments have two or more predefined values. For these arguments, you can
specify one of the predefined values only; any other value is invalid. In most cases, one
of the predefined values is the default. For example, see the -format argument of the
set_ready command. In a few cases, an argument has predefined values but does
not have a default value. For example, see the access argument of the give_access
command.
A switch is an argument that has two predefined values, “yes” and “no.” For example,
see the -line_numbers argument of the print command.
When an argument has two or more predefined values, they are referred to as cycle
values because you display them in the display form using the <CYCLE> and <CYCLE_BACK>
keys. You can also use the <¬> and <®> keys to display these values.
See the section ‘‘Giving Argument Values” later in this chapter for information about
working with predefined values.
Required and Optional Arguments

Arguments that do not have default values are either required or optional. A required
argument is an argument for which you must specify a value; for example, the
file_names argument of the print command is required. An optional argument is
an argument for which VOS does not need a value to execute the command; for
example, the -title argument of the print command is optional.

Display Form and Command-Line Form
Numerical Arguments
Numerical arguments may be signed integers of type decimal, binary, octal, or
hexadecimal. A letter following the input value indicates the base type: b or B for binary,
o or O for octal, d or D for decimal, and x or X for hexadecimal. If no such letter is given,
decimal is assumed.
For example, the number “10” in decimal could also be entered as its equivalent values;
“A” in hexadecimal (Ax), “1010” in binary (1010b), and “12” in octal (12o).
Labels and Keywords

The name of an argument is called a label. A label that begins with a hyphen is called
a keyword. For example, in the print command, file_names and -queue are
labels. Of these, -queue is a keyword.
In the command-line form of a command, an argument that does not have a keyword
is called a positional argument. This term is defined and explained later in this chapter
under the heading ‘‘Command-Line Form.”

This section describes the two ways to give a VOS command:
• ‘‘Display Form”
• ‘‘Command-Line Form”
It then explains how to redisplay command lines you have entered.
Display Form
To give a command in the display form, you type the name of the command and press
the <DISPLAY_FORM> key. The resulting video form displays a label and a field for each
argument. The values initially displayed in argument fields of the display form of a
command are default values.
You can type any of a command’s arguments after the command name and before you
press <DISPLAY_FORM>. The values you give for the arguments will be shown in the initial
display of the display form. You can also type values and choose among predefined
values after the form is displayed.
To request help information about any argument of the command, move to the field for
that argument and press <HELP>. To move from one field to another, use the <RETURN>,
<TAB>, <−>, and <¯> keys. If the form has two columns of arguments, you can also use the
<¬> and <®> keys. When the values displayed in all the fields are the values that you
want, you must press the <ENTER> key to issue the command.

If an argument value requires more space than the field available for it in the display
form, issue the command in command-line form. For example, using the command-line
form of the batch command lets you enter a longer command line than if you type in
the command_line field of the display form.
Note that another way to display the display form, less convenient than pressing
<DISPLAY_FORM>, is to type the keyword -form after the command name, then press
<RETURN> or <ENTER>.
Command-Line Form
To give a command in the command-line form, type the name of the command followed
by any arguments you select, then press either the <RETURN> key or the <ENTER> key.
In the context of the command-line form, an argument that does not have a keyword is
called a positional argument. See the next section for information about entering
positional arguments.
Retrieving a Command Line

VOS has two storage areas where it saves the last command line you entered. You can
retrieve command lines from these storage areas, and thus avoid retyping them. Once
a command line has been retrieved, you can edit it before entering it again.
The storage areas are:
• the insert saved buffer

• the insert default buffer
Pressing <RETURN> or <DISPLAY_FORM> replaces text in both buffers. Pressing <ENTER>

replaces text in the insert saved buffer only.
To retrieve text stored in the insert saved buffer since the last time you pressed
<RETURN>, <DISPLAY_FORM>, or <ENTER>, press the <INSERT_SAVED> key. To retrieve text stored
in the insert default buffer since the last time you pressed <RETURN> or <DISPLAY_FORM>,
press the <INSERT_DEFAULT> key.
Note that when you enter a break level command (such as typing s for stop) or when
you answer a prompt during the execution of a program (such as answering y to the
prompt Verify deletions of star_name. file_name?), pressing <RETURN>
stores the text in the insert saved buffer only. In either case, when your process returns
to command level, you can use the <INSERT_DEFAULT> key to retrieve the command line
you entered the last time your process was at command level.
See Chapter 6 for more information about command level, and see Appendix B for
information about break level.

Giving Argument Values

This section describes how to enter values for each type of argument.
Positional Arguments (Command-Line Form Only)

If a command has only one positional argument (for example, the file_names
argument of the print command), you can give the value at any point after the
command name (with one exception, described below). The position of the value is not
significant, since the command processor can unambiguously identify all other
arguments by their keywords.
If a command has two positional arguments, you must give one before the other in a
specified order. For example, the copy_file command has the positional arguments
source_file and destination. The source_file value must always precede a
value supplied for destination, even if there are intervening keyword arguments.
Thus, the following is a valid format for a copy_file command line:
copy_file -pack source_file -delete destination
In general, you can specify positional arguments in any order with relation to keyword
arguments. However, if a command has a keyword argument that takes more than one
value, you must specify all positional arguments before that keyword argument. For
example, the bind command contains both the positional argument
object_modules and the keyword argument -search, which takes one or more
directory names as values. In the following command line, the command processor
cannot determine whether the second directory_name value is intended as the
value for object_modules or as a second value for the -search argument:
bind -search directory_name directory_name

To determine the correct order for positional arguments, see the command
documentation or give the command name with the -usage option (as described later
in this chapter).
You do not need to enter a positional argument that has a default value unless you want
to change the value or you want to specify a positional argument that follows.

Arguments with One Predefined Value

In the display form, move the cursor to the field and type a new value.
In the command-line form, if the argument is a keyword argument, specify the keyword
plus the new value on the command line. If it is a positional argument, specify only the
new value.
For example, the default value of the display command’s -first_line argument
is 1, but you can give any line number to specify at what line in the file you want to begin
the display.
Switches
In the display form, use the <CYCLE>, <CYCLE_BACK>, <¬>, and <®> keys to display one value
or another. For example, to change the default value of the -line_numbers argument
of the print command, cycle to yes.
In the command-line form, most switches consist of only a keyword. When the switch
is off by default, the keyword that you give to turn it on has a positive format. For
example, to turn on the -line_numbers switch in the print command, you simply
give the keyword -line_numbers. However, when a switch is on by default, the
keyword that turns it off has a negative format. For example, the -page_breaks
argument to the print command is on by default. To print a file without page breaks,
the keyword is -no_page_breaks.
Arguments with Several Predefined Values

In the display form, use the <CYCLE>, <CYCLE_BACK>, <¬>, and <®> keys to display one value
at a time, stopping when the value you want is displayed.
In the command-line form, give both the keyword and the appropriate predefined value.
For example, the -sort argument of the list command has the following predefined
values: name, size, date_created, date_modified, date_used, date_saved.
In the display form, you can cycle to the value you want; in the command-line form, you
must specify the keyword -sort followed by the desired value.
Note that there are a few arguments having several predefined values that are
positional arguments. For example, see the access argument to the give_access
command and the give_default_access command.

Other Keyword Arguments

If an argument is not a positional argument and does not have predefined values, you
enter a value for it as follows:
• In the display form, type the value in the field.

• In the command-line form, type the keyword followed by the value.
The -header argument of the print command is an example of this type of

argument.
Entering Character-String Values

Some arguments, such as the text argument of the send_message command,
accept character strings as values.
In the command-line form, you must enclose a character string in apostrophes (') if it
contains a space, or tab, a semicolon, or parentheses that are not part of a command
function. If one of the two apostrophes needed to balance the string (one at the
beginning, one at the end) is missing, VOS sends the message A quoted string
is not closed.
If you need an apostrophe within a character-string value in the command-line form,

type two apostrophes (''), which VOS interprets as a single apostrophe. For example,
to send a message to Susan Smith that contains an apostrophe, John Brown could
enter the following command-line form of the send_message command:
send_message Susan_Smith 'I can''t meet at 2; how about 3?'

The output of the command looks like this:
John_Brown: I can't meet at 2; how about 3?

Note that the quotation mark (”) is not equivalent to the apostrophe or to double
apostrophes. The quotation mark has no more significance than any other character in
a character-string value.
Entering Star Name Pair Values

Some commands have two successive arguments that accept path name values, both
of which can be star names. These commands are said to accept a star name pair. For
example, see the descriptions of the rename, compare_files, copy_file, and
move_file commands in the VOS Commands Reference Manual (R098).
A command that accepts a star name pair first selects a list of files by matching names
in the specified directory with the first star name. Then, to determine a second star
name for each name on the list, the command replaces each asterisk in the second star
name by the characters matching the corresponding asterisk in the first name.

Where to Find More Information
For example, suppose the current directory contains the following files:
report.cobol
compress.cobol
fast_sort.pl1
fast_sort.obj
fast_sort.pm
The following command changes the file name report.cobol to

report.old.cobol and the file name compress.cobol to
compress.old.cobol:
rename *.cobol *.old.cobol

To move the files fast_sort.pl1, fast_sort.obj, and fast_sort.pm to the
subdirectory save_dir and change their names to slow_sort.pl1,
slow_sort.obj, and slow_sort.pm, respectively, use this command:
move_file fast_sort.* save_dir>slow_sort.*

The command rename *.incl.* *.save renames all files in the current directory
having the infix .incl. as follows:
• preserves any part of a file name preceding .incl.

• changes .incl., and any part of a file name following it, to .save.
Where to Find More Information

See the Introduction to VOS (R001) manual for details about getting help from the
system before and after logging in. Also see the tables in that manual that list and
explain special keys and function keys on your keyboard for entering, editing, and
canceling commands.
See Appendix H for information about the online help facility.
See Appendix B for information about how to halt the execution of a command after
pressing <ENTER> or <RETURN>.
See the VOS Commands Reference Manual (R098) for complete details about
commands and their arguments.

Chapter 3
National Language Support 3-
National Language Support (NLS) is the ability of the operating system to support
languages other than English. If you wish to display or print text in another language,
you have a variety of options that allow messages, text files, and character data
manipulated by programs to be represented in the character set appropriate to the
language.
NLS includes the following specific areas:
• Support for the Japanese kanji and katakana character sets, as well as support for
ASCII, Latin #1, hangul, simplified Chinese, Chinese1, Chinese2, and user_dbcs
character sets.
• Support for per-command message files to enable messages to be translated into
different languages for different user populations.
• Emacs support for all the character sets listed above.
• VOS terminal type facility support for all the character sets listed above.
• Asynchronous device I/O support for all the character sets listed above.
• Asynchronous Forms Management System support for all the character sets listed
above.
• C, COBOL, and PL/I compiler support for all the character sets listed above.
This chapter provides the information you need to work with National Language
Support. It has the following sections:
• “Configuring Languages Supported on the Module” describes the system

languages table.
• “The Process Language” describes how a process language is defined for a
process.
• “The Default Character Set” describes how a file can have a specific attribute
defining the character set used to represent the text it contains.
• “System Error Messages” describes how programs find system error messages.
• “Defining Per-Command Message Files” describes how message files specific to
a command can be created and how they are located.
National Language Support 3-1

Configuring Languages Supported on the Module
Configuring Languages Supported on the Module

The system administrator configures the languages supported on a module. The
system languages table contains an entry that defines each language configured on
the module. The function of the languages table is to allow the system administrator to
tailor certain features of the environment to match the expectations of the user
community on a module. In particular, the language definitions in the languages table
supply date and time terms. Further, when a user’s process selects a language defined
in a configured languages table, system messages can be displayed in the language
specified. See the section ‘‘System Error Messages” later in this chapter for information
about how system messages can be tailored for different users.
Each language definition in the languages.table file includes the date and time
formats and terms used in that language. Definition of date and time information in the
language table provides for automatic translation of date and time information into
terms and formats that match a user’s process language, and allows the operating
system to recognize date and time terms the user types at the terminal. The languages
table also makes it possible to further tailor the environment using system messages,
including error messages and prompts from commands, represented in the user’s
process language. See the section ‘‘Process Language” later in this chapter for
information about how a process language is determined.
In addition to creating and configuring a languages table, the system administrator may
define one of the languages in the table as the module default language. The module
default language is the language in which system messages and date/time information
are represented for a process unless otherwise specified or unless the language
specified for a process is not defined on the module. The operating system displays or
prints text data (including messages) in the default language, and expects input data
in the default language. If there is no explicitly specified default language in the
languages table, the module default language is U.S. English but the system
administrator can designate any language configured on the module as the default.
The details of how to create and configure the system language table are in the VOS
System Administrator’s Guide (R012).
Process Language
The process language is the language a process uses for the display, storage, and
printing of text.
The system administrator sets the process language by defining it in the user
registration table. If your entry in the registration table does not name a process
language, your default process language is the same as the module default language.
The reason to assign a default process language in the user registration table is that
the module default language is not the same as the user’s national language.

Default Character Set
The process language must be one of the languages recognized on your module. As
explained above in the section ‘‘Configuring Languages Supported on the Module,” the
languages recognized on a module are those defined in the system language table.
You can change your process language from the module default language, or from the
language named in your entry in the registration file, by placing a set_language
command in your start_up.cm or by issuing the set_language command at
command level, which defines your process language and that of any subprocesses
you create.
A subprocess you create with the login command has the same process language as
that of your initial login process. If no process language is explicitly defined in your user
registration entry, your process language is the module default language. The same is
true of started processes and batch processes. However, you can explicitly assign a
process language to a started process or a batch process by using the set_language
command before giving a command to start a noninteractive process.
Default Character Set

A text file can have a default character set, independent of any process language. The
default character set is the file attribute that determines how the operating system
interprets the internal representations of characters in a text file. Possible default
character sets are: none, ASCII, Latin #1, Japanese kanji, katakana, hangul, simplified
Chinese, Chinese1, Chinese2, and user_dbcs. Only fixed, relative, and sequential
files are allowed to have a default character set.
A text file can also contain text in several different character sets. Some characters in
a file may be explicitly assigned to a character set different from the default through the
use of single or locking shifts. The function of shift characters is analogous to the
function of the shift key on a keyboard. There are two kinds of shifts: single shifts, which
operate on a character at a time, and locking shifts, which operate on all ensuing
characters until another shift character unlocks the shift. The file can have only one
default character set attribute, which if set must be the character set used to store the
records of the file when no explicit indication of a different character set is imbedded
with the characters. But a file can contain text in more than one character set. To
change from one character set to another, it is necessary to embed shift characters in
the file.
You give a file a default character set attribute by using the create_file command
and selecting one of the character set values. You can also create a file with a default
character set attribute using a text editor. The edit editor supports ASCII and Latin
Alphabet #1. The Emacs editor supports those character sets and, in addition,
katakana and Japanese kanji, hangul, simplified Chinese, Chinese1, Chinese2, and
user_dbcs.

System Error Messages
The default character set attribute for a file created with the create_file command
is none if you do not specify a default character set. A file whose default character set
attribute is none has no default character set and cannot be a text file. It is a binary file.
The set_text_file command sets the default character set and shift mode of a file
that already exists. Use the -force option of the set_text_file command to
change the shift mode and default character set of a nonempty file.
The convert_text_file command is used to change the shift mode and default
character set of a file already having a shift mode and default character set.
Files printed on a printer or displayed on a terminal will show shifted characters,

assuming the device supports that character set.
System Error Messages

Error messages for your process can be displayed in your process language if a
translated message file exists in that language, or in English if no translated message
file exists. If no language is explicitly defined for your process, system error messages
are in the module default language (U.S. English in the absence of an explicitly defined
module default language).
The system error message file is supplied in English, and must be translated, in its
entirety, into your process language before you can obtain error messages in your
process language. The name of the system error message file is
error_codes.text. It is stored in the directory >system>error.
The translated system error message table is stored in the same directory that contains
the standard system error messages. Its name is error_codes.lang.text, with
.lang being the language name suffix for your process language. The translated error
messages file is stored in the directory >system>error.
Error codes for both the standard error message table and the translated error
message table are positive integers in the range of 1 to 32,767.
Defining Per-Command Message Files

A per-command message file is a file containing user-written messages (usually error
messages) for a user-written command. The messages can be in any language
configured on the module.
A per-command message file must have a name in the form command_name.text. It

is stored either in the directory that contains the program module or in a subdirectory
of the directory containing the program module. If it is a subdirectory, it has the name
of the language in which the error messages are written, which may be any of the
languages configured on the module.

Messages in the per-command message file use codes in the range -1 to -32,768.
When a program handles an error code in this numeric range, the operating system
looks for a per-command message file in the directory that contains the program
module.
To create per-command message files, you need a data description (.dd) file and a
table input (.tin) file. These files are used as input to the create_table command,
described in the VOS System Administrator’s Guide (R012). The remainder of this
section describes the .dd file, gives an example of a .tin file, and outlines the steps
in the creation of the per-command message file.
The message_file.dd File

The message_file.dd file defines the format of the data to be input into the
per-command message file. To create a .dd file for a per-command message file, you
must make a copy of the error_codes.dd file, which is in the directory
>system>error. The command to use is:
copy_file >system>error>error_codes.dd message_file.dd
You need to make only one message_file.dd file for your per-command message
files.
The message_file.dd file looks like this:
fields: num binary (15),

name char (32),
text char (128) varying,
category char (18),
category2 char (18);
end;
This file defines the record format for command_name.tin.
The command_name.tin file specifies the contents of the records in the

command_name.table file. Each record description follows the format of the
message_file.dd file, except that the category fields are not meaningful for
per-command message files.
The command_name.text file is a file similar to the error_codes.table file,

containing the text of the error messages for the command.
The fields in the command_name.tin file are:
* num
The error code itself, which must be a number in the range -1 to -32,768.

* name
The name of the error code.
* text
A string giving the message that the error code displays. The string must be
enclosed in apostrophes.
* category, category 2
The type of the error code.
Example of a command_name.tin Entry

The following is an example of an entry in a command_name.tin file:
/ =num -4
=name e$format_error
=text 'Incorrect record format.'
=category
Creating a Per-Command Message File

Follow these steps to create a per-command message file:
Step 1: Use a text editor to create a file named command_name.tin. Note that the
first part of the name need not be the name of the command, but it is
recommended that you use some kind of convenient naming scheme to keep
the message file associated with the command. Also, note that one message
file might serve several commands, for example if an application is made out
of several commands.
Step 2: Copy the file error_codes.dd to one of the directories in your message
library paths, using a file name that will identify it to you, such as
message_file.dd. Make a backup copy named
message_file.dd.backup. It is recommended that you use one
message_file.dd file for all per-command message files.
Step 3: Issue the create_table command with the path names of the files
command_name.tin and message_file.dd as arguments. The output of
the create_table command is a file named command_name.table.
Step 4: Issue the command make_message_file with the file
command_name.table as an argument. The output of this command is a file
named command_name.text. The make_message_file command is
described in the VOS System Administrator’s Guide (R012).
Step 5: It is recommended that you store the file command_name.text either in the
directory containing the program module command_name.pm or in a
subdirectory of that directory with the name of your process language. You can
place per-command message files anywhere in the file system, but the

directory you use must be in the message library search rules (described in the
next section) or in the call to s$use_cmd_message_file in the user-written
command. (You must give a full path name in a call to
s$use_cmd_message_file.)
Message Library
There is a message library with a sequence of search paths. The directories in the
message library, in sequence, are:
(referencing_dir)>(language_name)
(referencing_dir)
>system>message_library>(language_name)
>system>message_library>us_english
The value of the (referencing_dir) command function is the path name of the
directory that contains the program module being executed. The value of the
(language_name) command function is the primary name of the process language.
See ‘‘Library Paths’’ in Chapter 4 for more information about search rules in general.


Chapter 4
How the System Processes
Commands 4-
This chapter has two sections, each describing an aspect of the command language
interface to the operating system.
The first section, ‘‘Command Processing Loop,” describes the steps in the processing
of a command. The second section, ‘‘How the System Locates Commands to Execute,”
explains the rules VOS follows to locate the object you are specifying in a command,
and describes how to change the search rules both for a module and for a process.
Command Processing Loop

The part of the operating system software that accepts and executes commands is
called the command processor. In an interactive process, the command processor
cycles through a series of steps called the command processing loop. The steps are
as follows:
1. Displays a prompting message and waits for a command.

This waiting state is called command level.
You have some choice in the form of the prompting message displayed. For
example, you can have no message at all, a symbol, a character string of up to
eight characters, or a ready prompt in one of three forms. See the descriptions of
the set_ready and the set_terminal_parameters commands in the VOS
Commands Reference Manual (R098) for information about changing the form of
the prompting message.
2. Reads from your terminal the command you enter.

3. Expands abbreviations and processes command functions.
Abbreviations are described in Chapter 5; command functions are described in
Chapter 6.
4. Executes the command line.

5. Returns to command level.
How the System Processes Commands 4-1

How the System Locates Commands to Execute

When you enter a command, you are specifying an object for the command processor
to locate and then execute. VOS must determine exactly which object you mean. You
may be referring to a user-written program or to a program supplied by VOS. Since
VOS has no reserved command names, you could specify a program with the same
name as a VOS command. However, to ensure against ambiguity, when you log in
there is a set of search rules in effect that determine the order in which objects are
located and subsequently executed.
This section contains the following topics:
• ‘‘Determining the Components of a Command”

• ‘‘Libraries”
• ‘‘Library Paths”
• ‘‘Changing the Search Rules for a Module”
• ‘‘Changing the Search Rules for Your Process”
Determining the Components of a Command

When you enter a command, the command processor reads from your terminal one or
more words, separated by spaces. It assumes that the first word is the name of a
command. There are three types of commands:
• Internal commands, which are built into the operating system. The command
processor does not search for internal commands in the directory hierarchy.
• Command macros, which are files containing one or more commands and/or
command macro statements. A command macro name must have the suffix .cm.
See Chapter 9 for information about command macros.
• Program modules, which are files containing the executable forms of programs. A
program module name must have the suffix .pm.
In determining which object you are referring to when you give a command, VOS
makes the following decisions:
1. Decides whether or not the first word is a path name. VOS does this by looking for
the symbols %, #, >, and <.
2. Determines whether the first word has the suffix .cm or the suffix .pm.
Once these decisions are made, VOS can begin the search for the object. The next
section describes where the search occurs.

Note that if you give one of your programs the name of a system-supplied internal
command, the command processor will load the internal command unless you supply
a path name for your program.
Libraries
A library is one or more directories in which the operating system looks for objects of a
particular type. There are four kinds of system libraries:
• include libraries, in which the compilers search for include files

• object libraries, in which the binder searches for object modules (objects with the
suffix .obj)
• command libraries, in which the command processor searches for command
macros (objects with the suffix .cm) and program modules (objects with the suffix
.pm)
• message libraries, in which error handling routines search for files containing the
text of error messages, and where the help system finds help files.
One of each of these libraries is available in the >system directory of each module
for all processes running on the module. The system directory is one level below
the master disk in the directory hierarchy. These libraries are named
include_library, object_library, command_library, and
message_library. Figure 4-1 shows the position of these directories in the
hierarchy. In addition, you can use the commands add_library_path,
delete_library_path, or set_library_paths to place other directories in
any of those libraries and to define the search sequence to suit your needs. See
the section ‘‘Changing the Search Rules for Your Process,” later in this chapter.

master_disk
system
object_library message_library
include_library
command_library
Figure 4-1. Library Directories in the system Directory
(For information about the other files and directories in the system directory, see the
VOS System Administrator’s Guide (R012).)
The libraries can include any number of directories, which can be located anywhere in
the directory hierarchy.
The remainder of this chapter discusses mainly command libraries. However, the
principles described apply also to the other libraries; the only difference is in the names
of target objects.
Library Paths
When a directory is included in a library, the directory’s path name is known as a library
path. The library paths for each library are organized into a list that the operating
system uses to search for an object. The operating system begins searching in the first
directory on the appropriate list. If the object is not in that directory, it searches in the
second directory, and so on, until it locates the object.
The remainder of this chapter is concerned with library paths. Specifically, it describes
the following:
• the search rules VOS follows to locate a command to execute

• how your system administrator can change the list of library paths for the entire
module
• how you can change the list of library paths for your process

Command Search Rules

Figure 4-2 shows the search rules the command processor follows when it tries to
locate a command. The top of the figure shows the order of the first two determinations
VOS makes, namely, whether the object is a path name and if it has a suffix of either
.cm (for a command macro) or .pm (for a program module).
The figure depicts, from top to bottom, the order in which VOS conducts the search.
The search ends when the object is located. If VOS fails to locate the object (because
it doesn’t exist according to the current search rules), you receive the message
Object not found.
The rules depicted assume the existence of only one library path
(system>command_library) in the command library. Later in this chapter,
Figure 4-3 shows a more complicated example with more libraries in the search path.

command
Path Name?
Yes No
Suffix? Suffix?
Yes No Yes No
file.suffix file.cm file.suffix in internal

in specified in specified command_library? command?
directory? directory?
Object not file.pm Object not file.cm in

found in specified found command_library?
directory?
Object not file.pm in

found command_library?
Object not
found
tx045a
Figure 4-2. The Operating System’s Command Search Rules
Note that when you omit a suffix, the order of precedence is first .cm, then .pm. Also
note that when provided with the least amount of information (an object name with no
path name or suffix), VOS relies entirely on the search rules as shown in Figure 4-2,
under the last column.

The order of precedence in searching for a command when you omit a path name and
a suffix is:
1. an internal command
2. a command macro in command_library
3. a program module in command_library
Changing the Search Rules for a Module

Frequently, users on the same system require shared access to commands and
programs contained in directories that are not on the operating system’s default search
list. Rather than allocating many copies of the same object to multiple users, it is more
efficient to add library paths to the command library pointing to directories that contain
site-specific tools and applications to which all users have access.
Using the set_default_library_paths command, system administrators can

change the list of directories that VOS will search through for a specified library. The
changes are effective for all new processes in a module. For example, suppose the
directory %s1#d01>Accounting>tools_library contains programs and macros
used throughout the Accounting Department. The system administrator could add this
directory to the module’s list of command library directories.
The command function (current_dir) is typically defined with the

set_default_library_paths command as the first path name in a given library for
a module. When VOS encounters (current_dir) as a library path, it expands the
command function relative to the current process each time it searches for an object.
You can display the list of library paths defined for your module with the command
list_default_library_paths. If the system administrator added to the list both
the (current_dir) command function and the directory
Accounting>tools_library, the output might look similar to this:
include library directories:

(current_dir)
%s1#d01>system>include_library
object library directories:

(current_dir)
%s1#d01>system>object_library
command library directories:

(current_dir)
%s1#d01>system>command_library
%s1#d01>Accounting>tools_library

message library directories:

(referencing_dir)
For information about the commands set_default_library_paths and

list_default_library_paths, see the VOS System Administrator’s
Guide (R012).
Note that (current_dir) is at the top of the list for each library except the message
library. The current directory is the first place the operating system looks for an include
file, an object module, or a command (after it determines that the command is not an
internal command). See Chapter 8 and Appendix C for information about command
functions.
Figure 4-3 depicts the operating system’s search rules when the command library
contains the library paths shown in the previous example.

command
Path Name?
Yes No
Suffix? Suffix?
Yes No Yes No
file.suffix file.cm file.suffix in Internal

in specified in specified (current_dir)? command?
directory? directory?
Object not file.pm file.suffix in file.cm in

found in specified command_library? (current_dir)?
directory?
Object not file.suffix in file.pm in

found tools_library? (current_dir)?
Object not file.cm in

found command_library?
file.pm in
command_library?
file.cm in
tools_library?
file.pm in
tools_library?
Object not
found tx046
Figure 4-3. Sample Search Path for a Command

For example, assume that the search rules depicted in Figure 4-3 are in effect and you
have a macro called cleanup.cm in your current directory. To execute the macro, you
could type cleanup with no path name or suffix. Since the name cleanup does not
match the name of an internal command, VOS looks next in your current directory for
an object with the suffix .cm. The search stops when cleanup.cm is located in your
current directory and the macro is executed.
Note the following:
• To execute a command macro in your current directory, you must specify a path
name unless (current_dir) is specified first as a command library directory.
• To execute a command macro or program module in your current directory that has
the same name as an internal command (for example, a macro called list.cm),
you must specify the object’s suffix.
• To execute a program module in your current directory if a command macro with
the same name exists, you must specify the object’s suffix.
Changing the Search Rules for Your Process

Several VOS commands allow you to create and maintain a list of library paths for your
own processes. VOS will use the order you specify in this list to search for a command
before it uses the order specified in the default library path list defined for the module.
The commands that change the list of library paths for your own processes are:
• add_library_path—This command adds a directory to your list of library paths

for the current login process.
• delete_library_path—This command deletes a directory from your list of
library paths for the current login process.
• set_library_paths—This command defines a new list of library paths for the
specified library for the current login process.
To list the library paths for your process, use the list_library_paths command.
Suppose you create a collection of macros and programs that you use frequently and
you want the ability to execute them regardless of your current directory. Further,
suppose some of the files have the same name as files in another command library
directory. You could store the files in any directory to which you have modify access.
(See Chapter 9 for information about directory access.) Then you could add that
directory’s name to your list of library paths so that VOS will search there according to
the order you have specified.
For example, if user Smith gives the following command, it will add the path name of
the directory macros to the list of library paths in the command library for Smith’s

process. It places the macros directory before the command_library directory in

system:
add_library_path command (home_dir)>macros -before

+ >system>command_library
To make more extensive changes to your list of library paths than simply adding or
deleting a single directory, use the set_library_paths command. For example, if
Smith gives the following command, it defines the directories listed in the command as
the new list of library paths for Smith’s current login process:
set_library_paths command (home_dir)>macros '(current_dir)'

+ >system>command_library
If Smith omits the name of a currently-defined library path from the library_names
argument of this command, the omitted directory will be deleted from Smith’s list of
library paths. For instance, in the preceding example, the directory
Accounting>tools_library was omitted from the list of path names in the
command library. The list_library_paths command would, therefore, produce
this output:
include library directories:

(current_dir)
%s1#d01>system>include_library
object library directories:

(current_dir)
%s1#d01>system>object_library
command library directories:

%s1#d01>Sales>Smith>macros
(current_dir)
%s1#d01>system>command_library
message library directories:

(referencing_dir)
These commands change the list of library paths only for your process and only for the
duration of the current process. If, after giving one of these commands, you want to
restore the list of library paths that was in effect when you logged in, you can log out
and log back in again. Conversely, if you want to have a library-path command be in
effect each time you log in, include the command in a startup macro file (startup macros
are described in Chapter 7).

As shown in some of the previous examples in this section, the command functions
(home_dir), (current_dir), (referencing_dir), and (language_name)
can be specified as library paths. Specifying (home_dir) is the same as specifying
the full path name of your home directory, but shorter.
When you use the (current_dir) command function or the (referencing_dir)

command with a library path command, normally you should enclose it in apostrophes
('). This prevents the command processor from evaluating the (current_dir)or
(referencing_dir) at the time you give a library-path command. Instead, it is
evaluated when the command processor searches for a command according to the
most recently-defined library paths. This gives you greater flexibility in enabling VOS to
locate a command, since the value of (current_dir) or (referencing_dir)
changes each time you change directories.
If you do not include the apostrophes, you must specify a path name and suffix each
time you execute a macro or program module stored in your current directory if it differs
from the directory that was current when you gave the library-path command. Only
when you want the present value of (current_dir) or (referencing_dir) to be
used as an argument to a library-path command should you omit the apostrophes.
Note that the value of (home_dir) always remains the same for your processes.
Therefore, using apostrophes when you include it as an argument to a library-path
command makes no significant difference.

Chapter 5
Using Abbreviations 5-
This chapter on using abbreviations has the following sections:
• ‘‘Abbreviations Facility”
• ‘‘Abbreviations File”
• ‘‘Types of Replacement Directives”
• ‘‘Controlling Abbreviations”
• ‘‘Steps in Replacing Abbreviations”
Abbreviations Facility
The VOS abbreviations facility lets you define different names for commands or other
parts of command lines. You can type a character string of your choice as a substitute
for another string that VOS recognizes. For example, you could define the abbreviation
ccd as a substitute for the command change_current_directory.
An abbreviation is a character string in a command that VOS replaces before executing

the command. Abbreviations are typically short forms of command names that you use
frequently. However, you can define abbreviations for other objects as well. Any
component of a command line can be abbreviated. Specifically, you can abbreviate
command names, arguments, macro names, path names, components of path names,
suffixes, command functions, combinations of any of these, and even entire command
lines.
Using Abbreviations 5-1

Abbreviations File
Abbreviations File
An abbreviations file is a text file containing one or more replacement directives. A
replacement directive is a line of text in an abbreviations file that contains a string to be
replaced (called the input string) and the string that VOS is to replace it with (called the
output string). For example, in the sample abbreviations file below, each line is a
replacement directive. In the first line, CD is the input string (the abbreviation) and
current_dir is the output string.
You create an abbreviations file with a text editor, using the formats for replacement
directives described later in this chapter under ‘‘Types of Replacement Directives.”
VOS does not allow abbreviation input strings to be used in the output strings of other
replacement directives; that is, abbreviations may not be used recursively (nested).
Also, note that the system administrator usually provides an initial abbreviations file in
each user’s home directory.
Sample Abbreviations File

The following is a sample abbreviations file:
all CD by current_dir
all HD by home_dir
first cbr by cancel_batch_requests
first ccd by change_current_dir
first copy by copy_file
first cpr by cancel_print_requests
first d by display
first dal by display_access_list
first dcd by display_current_dir
first dfs by display_file_status
first del by delete_file
first dtp by display_terminal_parameters
first lo by logout
first lpr by list_print_requests -all
first l by list
first move by move_file
first p by print -notify
first stp by set_terminal_parameters
first ua by use_abbreviations
subsequent -m by -module
subsequent == by -match
Note that the extra spaces between the columns of text in the sample abbreviations file
are included only to improve readability.

Types of Replacement Directives
The use_abbreviations Command

The use_abbreviations command compiles the directives in an abbreviations file
into a table that VOS uses to replace abbreviations. The command is effective only for
the duration of a login session. However, use_abbreviations is usually included in
your startup command macro (described in Chapter 7), so that it is automatically
invoked each time you log in.
Whenever you change the contents of your abbreviations file, you must give the
use_abbreviations command for the changes to take effect. Note that if you are in
a subprocess when you give the use_abbreviations command, the command is
not effective for any superior processes of the subprocess.
When you give the use_abbreviations command with no file name, by default the
operating system looks in your home directory for a file named abbreviations. If you
have more than one abbreviations file, you can specify any path name as an
abbreviations file by using the abbreviations_file_name argument of the
use_abbreviations command.
Note that if your abbreviations file is very large and you give the use_abbreviations
command you may receive the following message:
No room in process-data-region heap for allocation.
In this case, give the use_abbreviations command with the keyword -off first;
then give the use_abbreviations command again. The -off argument causes the
operating system to discard a previously compiled abbreviations table so that sufficient
resources are available for compiling the abbreviations a second time.

There are four types of replacement directives:
• first
• subsequent
• all
• symbol
This section describes each type of replacement directive. Then it explains

abbreviation parameters, which can be specified as part of first directives.
The general form of a replacement directive is as follows:
replacement_type input_string by output_string

First Directives
A first directive tells VOS to replace an input string with an output string when the
specified input string occurs first in a command string. First directives are useful for
abbreviating long command strings.
For example, the command name display_current_dir is abbreviated to dcd with

the following first directive:
first dcd by display_current_dir
The string dcd is the input to the directive; display_current_dir is the output.
In a command line, the input string of a first directive must always precede one of the
following:
• a space, or another symbol that separates the components of a command string

• a semicolon (;), or another symbol that separates commands in a command line.
(See ‘‘Symbol Directives” later in this section for information about how to define
abbreviations that replace one symbol with another in a command line.)
The output string of a first directive can contain abbreviation parameters, which are
replaced by words in the command line. Abbreviation parameters are explained later
in this chapter.
Subsequent Directives
A subsequent directive tells VOS to replace an input string with an output string when
the specified input string occurs at any point in the command string after the first word.
Subsequent abbreviations are useful for abbreviating command arguments.
For example, the keyword argument -terminal_type is abbreviated to -ttp with

the following subsequent directive:
subsequent -ttp by -terminal_type
The string -ttp is the input to the directive; -terminal_type is the output.
All Directives
An all directive tells VOS to replace an input string with an output string wherever the
specified input string occurs in the command. All directives are useful for including the
same abbreviation in either the first or subsequent positions in a command line.

For example, the command function (home_dir) is abbreviated to HD with the

following all directive:
all HD by (home_dir)
The string HD is the input to the directive; the value of (home_dir) is the output.
See Chapter 6 and Appendix C for information about command functions.
Symbol Directives
A symbol directive tells VOS to replace one character by another. The input character
(the one that is replaced) can be any character except a space, a numeral, an
uppercase letter, a lowercase letter, or an underline (_). The output character (the
replacement) must be one of the characters with special meaning for VOS, as shown
in Table 5-1.
Table 5-1. Special Replacement Characters in Symbol Directives
Character Name Meaning
space word separator
! exclamation point abbreviations suppressor
# number sign disk directory and device
% percent sign system name prefix
’ apostrophe character-string delimiter
( opening parenthesis command function delimiter
) closing parenthesis command function delimiter
. period suffix delimiter
; semicolon command string delimiter
< less-than sign path name delimiter
> greater-than sign path name delimiter
& ampersand ampersand
* asterisk asterisk
- hyphen hyphen
Symbol directives let you enter characters in a command line that are more convenient
for any reason. For example, suppose you are accustomed to working with a system
that uses colons (:) instead of greater-than signs (>) to delimit parts of a path name.
You could have the following symbol abbreviation, which causes every colon in a
command to be replaced by a greater-than sign:
symbol : by >
In this way, you can continue using the naming conventions you are most comfortable
with.
Note that symbolic directive character replacement occurs even when the command
line begins with the abbreviation suppressor character “!”.
Abbreviation Parameters
An abbreviation parameter is a variable in the output string of a first directive. When
you use an abbreviation that contains a parameter, you can substitute one or more
input arguments or argument values for the parameter.
Abbreviation parameters are useful for:
• shortening commands that you usually give with the same set of arguments, in
which only a subset may vary
• passing a value from one command string to another in the same command line
• forcing a parameter to a specific position in the command string.
The formats for abbreviation parameters are:
&n&
&fn&
Examples in this section show how to use both formats.
When the parameter is of the form &n&, the command processor substitutes the word
in the nth position after the first word in the command for the parameter &n& in the
output string.
When the parameter is of the form &fn&, the command processor substitutes the word
in the nth position and all remaining words after the nth word in the command for the
parameter &fn& in the output string.
For example, suppose you regularly compile different VOS COBOL source files, create
program listings, and then print the listings. You could include the following first
directive in the abbreviations file:
first compile by cobol &1& -list; print &1&.list

When you enter compile make_report, the word make_report substitutes for the
parameter &1& in both command strings and the command line expands to the
following:
cobol make_report -list; print make_report.list
If you sometimes use the options -xref and -statistics to obtain a list of
cross-references and the compilation statistics, you could have this abbreviation:
first compile by cobol &1& -list &f2&; print &1&.list
Then, when you enter compile make_report -xref -statistics, the

expanded command looks like this:
cobol make_report -list -xref -statistics; print

make_report.list
In this example, if you omit the options -xref and -statistics, the parameter &f2&
is replaced by an empty string and is therefore ignored.
As another example, suppose you update the same report each week and, because it
is lengthy, you defer printing it until after peak working hours. You might use the
following command:
print rept -copies 15 -defer_until '01-06-15 18:00' -header

'Weekly Report'
This command prints fifteen copies of a file in the current directory named rept, each
having the title “Weekly Report,” and defers printing until June 15, 2001 at 6:00 pm.
Since this command is relatively long, an abbreviation would be particularly convenient.

You could therefore include the following first directive in your abbreviations file:
first prpt by print rept -copies 15 -header 'Weekly Report'
Using this example you must specify the -defer_until argument with a different
value each week. However, you could include in the first directive the keyword label
-defer_until with an abbreviation parameter. The abbreviation would then look like
this:
first prpt by print rept -copies 15 -defer_until &1& -header

'Weekly Report'

Controlling Abbreviations
With this first directive in your abbreviations file you could enter the command each
week, giving only the abbreviation followed by the date and time. For example:
prpt '01-6-22 18:00'
Since the date/time string (enclosed in apostrophes) is the first word on the line after
the input string to the abbreviation (prpt), VOS replaces the parameter &1& with the
actual date/time value. When it is expanded, this command prints the weekly report
with the specified options at the specified date and time.
To increase the generality of the sample prpt abbreviation, you could add the
parameter &f2& at the end of the output string in the abbreviations file. This allows you
to give additional arguments to the print command (such as -indentation or
-notify) when you issue the prpt abbreviation. Otherwise, if you omit &f2& in the
replacement directive, the operating system discards any additional arguments you
specify with the input string.
Controlling Abbreviations
When you give a command, VOS searches the command line for any abbreviations
listed in the abbreviations table. Those found are replaced with the corresponding
output string. This replacement is called expanding an abbreviation.
You can prevent VOS from expanding any abbreviations with the -off argument to the
use_abbreviations command, as described in the section “The
use_abbreviations Command.”
To prevent VOS from expanding part of a command line, you can do either of the
following:
• Enclose in apostrophes (') the part you do not want expanded. VOS removes the
apostrophes and does not expand abbreviations within the apostrophes. (See
Chapter 2, ‘‘Understanding the Command Language” for more information about
using apostrophes in a command line.)
• Type a single exclamation point (!) before the part you do not want expanded. VOS
removes the exclamation point and does not expand any abbreviations in the
command line after the exclamation point.
NOTE
Neither the exclamation point (!) nor the apostrophes (')
prevent replacement of symbol directive characters.

Steps in Replacing Abbreviations
If you want to include an exclamation point in a command while allowing VOS to

continue expanding abbreviations, do either of the following:
• Enter two consecutive exclamation points (!!). VOS removes the first exclamation
point and continues to expand abbreviations in the remainder of the command line.
• Enclose the exclamation point in single apostrophes ('!'). VOS removes the
apostrophes and leaves the exclamation point intact in the command line.

In step 2 of the command processing loop (described in Chapter 4), the command
processor reads a command from your terminal. In step 3, VOS expands abbreviations
and processes command functions. This section explains the steps that VOS follows
in expanding abbreviations:
1. VOS replaces symbols according to all symbol directives. Since the output of
symbol directives are characters that delimit words and identify path names in a
command line, this step allows VOS to separate the string into its individual
components.
See Table 5-1 for a list of the symbols that VOS looks at in this step. All of the
symbols in that table except &, *, and - are used to delimit the components of a
command line.
2. If a word appears in your abbreviations file as input to an all or a subsequent

directive, and if its position in the command is the same as the position specified in
the directive, VOS replaces the word in the command with the directive’s output
string.
3. VOS evaluates all command functions and substitutes the values they return into
the command. (See Chapter 6 for an explanation of command functions.)
4. VOS now expands first directives. The first word in the command begins with the
first non-blank character in the command string and ends at the first space or
semicolon (;). Any character preceding the first space or semicolon is included in
the first word. If the first word matches the input string of a first directive, and if it is
not part of the output of an all directive or a command function, then the command
processor replaces the word with the first directive’s output string.
5. Next, VOS evaluates abbreviation parameters. If a parameter is of the form &n&,
VOS replaces the parameter with the word in position n after the first word in the
command. If the parameter is of the form &fn&, VOS replaces the parameter with
the word in position n and with all remaining words in the command string.
If there are more abbreviation parameters than words in the command string, VOS
substitutes an empty string for each of the extra parameters. This has no effect on
how the command executes.

6. Finally, VOS evaluates command functions again. During the expansion of

abbreviations, one or more new command functions may be introduced in the
command; these functions are now evaluated.

Chapter 6
Introduction to Command
Functions 6-
This chapter has two sections that provide an overview of the command functions. The
first section, ‘‘Basic Information,” defines and describes the purpose of command
functions. The second section, ‘‘Brief Descriptions,” organizes command functions into
five categories and briefly describes each function within its category. The categories
are:
• ‘‘Information”
• ‘‘Calculations”
• ‘‘String Manipulations”
• ‘‘Numeric”
• ‘‘Files and Directories”
For complete information about the command functions, see Appendix C. In the
appendix, the command functions are documented in alphabetical order and their
arguments are described in detail.
Basic Information
A command function is a self-contained function that you can use as an argument in a
command line. Before executing the rest of the command line in which a command
function appears, the command processor evaluates the command function and
replaces it with a value. The value returned becomes part of the command line. For
example, to display the current time, you could enter the following command line with
the command function (time):
display_line (time)
The output for the preceding example could be 13:10:59, which specifies the current
hour (13, in 24-hour format), minutes (10), and seconds (59).
The most common use for command functions is in command macros. However, a few
of the functions are also frequently used in commands. For a list of those command
functions and information about how they can be used in commands, see the VOS
Commands Reference Manual (R098).
Introduction to Command Functions 6-1
Brief Descriptions
When you use command functions, note the following:
• Parentheses are part of every command function; you must include them whenever
you type a command function.
• The command processor expands abbreviations before it evaluates command
functions. You can, therefore, create abbreviations for command functions. See
Chapter 5 for imformation on using abbreviations.
You can use command functions to return values of the following data types:
• path names
• user names
• module, system, or device names
• numeric values
• date-time values
• character-string values
The value returned by a command function has a limit of 256 characters.
Brief Descriptions
The following table shows the symbols used in this section and the meaning of each
symbol.
Symbol Meaning
S, S1, S2, ..., Sn, R a character string

C a character or set of characters
I an integer
N, N1, N2, ..., Nn a number
A character string is an ordered set of characters. Positions in a character string are

counted starting with the left most character (the beginning). A substring is a string of
any length that occurs within a longer string. An initial substring is a substring whose
first character is also the first character in the containing string. Similarly, a
final substring is a substring whose last character is also the last character in the
containing string. For example, if S is the character string abcdef, then a and abcd
are two initial substrings of S; likewise, def and ef are two final substrings of S.
You must enclose character string arguments in apostrophes if the string contains one
or more spaces, semicolons, or parentheses (as used with any command argument).
If you need an apostrophe character within a character string, type two apostrophes

Brief Descriptions
(''). See ‘‘Entering Character-String Values’’ in Chapter 2 for additional information on

character strings.
Information
The command functions listed here return informational values:
(command_status)
Returns the VOS status code passed by the most recently executed command to
the VOS service subroutine s$error or s$stop_program.
(current_dir)
Returns the full path name of your current directory.
(current_module)
Returns the full path name of your current module.
(date [date_string][-long][-standard])
Returns a date in the form yy-mm-dd. With -long, the date is in the form
month day, year. With -standard, the date is in the form defined for your
default process language.
(date_time [date_string][-long][-standard])
Returns a date and time in the form yy-mm-dd hh:mm:ss. With -long, the date
and time are in the form weekday, month day, year hh:mm:ss am/pm
time_zone. With -standard, the date and time are in the form defined for your
default process language.
(group_name)
Returns the name of your current group.
(home_dir)
Returns the full path name of your home directory.
(iso_date [-long][-standard])
Returns a date in the form of yyyy-mm-dd.
(iso_date_time [-long][-standard])
Returns a date and time in the form yyyy-mm-dd hh:mm:ss.
(language_name)
Returns the name of the default process language defined for your process.
(master_disk [module_name])
Returns the full path name of the master disk directory on the module specified by
module_name. If you omit a value for module_name, returns the full path name
of the current module.

Brief Descriptions
(message I [S1[S2[S3]]])
Returns the text of the message identified by VOS status code I, with the optional
parameters S1, S2, and S3.
(module_info key)
Returns various kinds of module-specific information, depending on the value of
key.
(module_name module_name)
Returns the full path name of the module specified by module_name.
(online [module_name])
Returns the value 1 if the module specified by module_name is currently on line
through the network. Returns 0 if module_name is not on line or if no such module
exists.
(person_name)
Returns the person name of the user logged in on the current process.
(process_dir)
Returns the full path name of the process directory of the current process.
(process_info key)
Returns various kinds of process-specific information, depending on the value of
key.
(process_type)
Returns the type of the current process. The possible returned values are
interactive, sub_process, and batch.
(referencing_dir)
Returns the full path name of the directory that contains the program module or
command macro that is currently executing. The purpose of this command function
is to be placed in the library paths list of path names; it cannot be used interactively.
(software_purchased software_purchase_bit)
Returns 1 if the product denoted by software_purchase_bit has been
purchased. Returns 0 otherwise.
(system_name)
Returns the name of the current system.
(terminal_info key)
Returns various kinds of terminal-specific information, depending on the value of
key.

Brief Descriptions
(terminal_name)
Returns the full path name of the current login terminal.
(time [time_string][-long][-standard])
Returns a time in the form hh:mm:ss, in 24-hour format. With -long, the time is
in 12-hour format and is of the form hh:mm, followed by either am or pm. With
-standard, the time is in the form defined for your default process language.
(user_name)
Returns the user name of the user logged in on the current process.
Calculations
The command functions listed here return calculated values. The command processor
evaluates the input you specify, performs the calculation, and returns the value. Some
of the returned values are numeric and some are character strings:
(ask [prompt[response_qualifier]][-no_echo])
Writes to the terminal_output port and displays on the display screen the string
specified by prompt and any string specified by response_qualifier. Then,
with no trailing new line displayed, a user-supplied response is read from the
terminal port and displayed on the display screen. The value the command
function returns is the response. If you specify response_qualifier, the type
of response that must be entered depends on its value. If you specify -no_echo,
the display of your response is suppressed.
(byte I)
Returns the ASCII character that corresponds in the ASCII collating sequence to
the integer I.
(calc expression)
Returns the value resulting from the command processor’s evaluation of the
specified expression.
(directory_name path_name)
Returns the full path name of the directory containing the object specified by
path_name.
(exists path_name [type][-no_chase])

Returns the value 1 if the object specified by path_name exists and you have
status access to its containing directory, or non-null access to the object itself,
and 0 otherwise.
(given parameter)
Returns the value 1 if the specified command macro parameter was supplied a
value when the current command macro was invoked, and 0 otherwise. Note that
this command function can only be used in command macros.

Brief Descriptions
(object_name path_name [suffix])

Returns the name of the object specified by path_name, with the specified suffix,
if any, appended.
(path_name path_name [suffix])

Returns the full path name of the object specified by path_name, with the specified
suffix, if any, appended.
(rank C)
Returns the integer rank in the ASCII collating sequence of the character specified
by C.
(unique_string)
Returns a unique character string.
(where_path path_name [type])

Returns the full path name, full module name, or object type of path_name,
depending on the value of type.
String Manipulations
The command functions listed here return values based on manipulated character
strings. The command processor evaluates the strings you supply as input and
manipulates them according to the method specified by the name of the function. Some
returned values are character strings and some are numeric.
Note that the following command functions return an error code if used with the
National Language Support character strings that contain shift characters:
(after) (reverse)
(before) (search)
(break) (substitute)
(count) (substr)
(index) (translate)
(length) (verify)
(after S1 S2)
Returns the final substring of S1 that follows the substring S2.
(before S1 S2)
Returns the initial substring of S1 that precedes the substring S2.

Brief Descriptions
(break S C)
Returns the length of the initial substring of S that precedes the first instance in S
of any character in the set C.
(concat S1 ...Sn)
Returns the strings S1 through Sn combined into one string with all spaces
between the components removed.
(copy S I)
Returns the string S, copied I times.
(count S C)
Returns the length of the longest initial substring of S consisting entirely of
characters in the set C.
(index S1 S2)
Returns the position in the string S1 of the first character in the substring S2. If S2
is not a substring of S1, the returned value is 0.
(length [S])
Returns the length of the string S.
(ltrim S [C])
Returns the longest final substring of S whose first character is not in the set C. If
you omit C, VOS trims leading spaces from S.
(quote S1 ... Sn)

Returns the strings S1 through Sn combined into one string, with each component
separated from the next by one space and apostrophes added at the beginning and
the end.
(reverse S)
Returns the reversed character pattern of the string S.
(rtrim S [C])
Returns the longest initial substring of S whose last character is not in the set C. If
you omit C, VOS trims trailing spaces from S.
(search S C)
Returns the left most position in the string S that contains a character in the set C.
If no member of C is in S, then the returned value is 0.
(string S1 ... Sn)

separated from the next by one space.

Brief Descriptions
(substitute S1 S2 S3 [-ignore_quotes])
Returns the string that results from locating each occurrence of S2 within S1, then
replacing each occurrence with S3.
(substr S I1 [I2])
Returns the substring of the string S that begins in position I1 and extends either
for I2 characters or, if you omit I2, to the end of S.
(translate S1 [S2[S3]])
Returns the character string S1 translated according to the character strings S2
and S3. Each occurrence of an element of S3 in the string S1 is replaced by the
element of S2 corresponding to the same position in S3.
(unquote S)
Returns the string S with any leading and trailing apostrophes removed and with
any doubled apostrophes within the string reduced to single apostrophes.
(verify S C)
Returns the left most position of the character in the string S that is not in the set
C. If all the characters in S are in C, then the returned value is 0.
Numeric
The command functions listed here return numeric values. The command processor
evaluates the number or integer you supply as input and returns a numeric value
according to the method specified by the name of the function.
(abs N)
Returns the absolute value of N.
(ceil N)
Returns the smallest integer greater than or equal to N.
(decimal I)
Returns the value of I expressed as a decimal integer. The integer I can be
expressed as a binary, octal, decimal, or hexadecimal integer.
(floor N)
Returns the largest integer less than or equal to N.
(hexadecimal I)
Returns the value of I expressed as a hexadecimal integer. The integer I can be
(max N1 N2)
Returns the larger of the two values specified in the arguments N1 and N2.

Brief Descriptions
(min N1 N2)
Returns the smaller of the two values specified in the arguments N1 and N2.
(mod N1 N2)
Returns the remainder of the division of N1 by N2.
(trunc N)
Returns the integer part of N.
Files and Directories

The command functions listed here return values based on operations performed on
an existing file or directory with a path name you specify.
(access path_name [user_name])

Returns the access rights of the user specified by user_name to the object
specified by path_name.
(contents path_name [line_number][open_status])

Returns the records of the file specified by path_name, with each record
separated from the next by a space. If line_number is specified, returns the
record of the file specified by line_number. Note that open_status can be used
only in command macros.
(end_of_file path_name)
Returns the value 1 if the last execution of (contents) on a file held open in a
macro returned e$end_of_file; otherwise, the returned value is 0. Note that this
command function can be used only in command macros.
(file_info path_name key)

Returns various kinds information about the file specified by path_name,
depending on the value of key.
(has_access path_name access_code [user_name])

Returns the value 1 if the user specified by user_name has at least the access
rights specified by access_code to the object specified by path_name.
Otherwise, returns the value 0.
(lock_type path_name)
Returns the type of lock on the file specified by path_name.
(locked path_name)
Returns the value 1 if the file specified by path_name is locked, and 0 if it is not
locked.

Brief Descriptions

Chapter 7
Using Command Macros 7-
This chapter contains information on using the VOS command macros and contains
the following sections:
• ‘‘Introduction to Command Macros” explains what a command macro is and

provides basic information about invoking a macro and about the macro processor.
• ‘‘Elements of a Command Macro” explains each of the major elements that can be
in a macro, provides information about spaces in macros, and explains how
punctuation symbols are used.
• ‘‘Command Functions in Macros” explains why command functions are often
useful in macros.
• ‘‘Abbreviations in Macros” explains why abbreviations should be avoided and how
to suppress their expansion.
• ‘‘Expressions in Macros” provides information about the use of expressions in
macros.
• ‘‘Macro Variables” provides complete information about macro variables.
• ‘‘Parameters” provides complete information about macro parameters. This
section first describes parameter declarations. Then it explains parameter
descriptors, describing each part separately. Then it describes the three types of
parameters and explains how to declare each type. Finally it provides complete
information about the data types used to declare parameters.
• ‘‘End Qualifiers” explains briefly what end qualifiers do. (For complete information,
see Appendix D.)
• ‘‘How a Command Macro Is Processed” outlines what the command processor and
the macro processor do when a macro is invoked.
• ‘‘Avoiding Macro Recursion Loops” shows by example how to avoid a problem that
can occur when a macro calls itself.
• ‘‘Startup Command Macros” defines and shows examples of macros that perform
certain operations immediately after the user logs in.
• ‘‘Examples of Command Macros” show three complete examples.
The command macro statements are discussed in this chapter, but not described fully.
See Appendix D for complete information about them.
Using Command Macros 7-1

Introduction to Command Macros
Introduction to Command Macros

This section defines command macros and shows an example. Then it explains how to
invoke a macro. Finally, it defines the role of the macro processor.
Definition and Example

A command macro is a text file that contains one or more commands and/or command
macro statements and that has a name ending with the suffix .cm. A macro is actually
one kind of user-written command (an ordinary program module is the other). As with
any command, you invoke a macro by entering its name. The operating system then
sequentially executes the command lines and macro statements in the file.
A command macro usually replaces one of the following:
• a long command string that you issue frequently

• a group of internal commands, command macros, and/or program modules that
together perform an operation you regularly require
• a sequence of internal commands, command macros, and/or program modules
that you execute in a certain way depending on external factors, such as the time
of day.
This example shows the command macro lst.cm, which contains a sequence of
internal commands. A simple macro like this is a convenient way to store a command
sequence for reuse:
!attach_default_output temp
!list -all
!detach_default_output
!print temp -delete
The first command creates a file named temp and attaches your default_output
port to it. The second lists the contents of your current directory; the list is written to the
file temp. The third reattaches default_output to its previous attachment. The
fourth prints temp and then deletes it.
NOTE
Exclamation points are used in command macros to
suppress the expansion of abbreviations. This is
explained in detail later in this chapter.

Elements of a Command Macro
Invoking a Command Macro

A command macro has both a command-line form and a display form. To use the
command-line form, enter the name of the macro with any parameters you choose,
then press either the <RETURN> key or the <ENTER> key. To use the display form, enter the
name of the macro and press the <DISPLAY_FORM> key. Insert or edit values as necessary
and press the <ENTER> key.
When you enter a macro’s name, you can omit the .cm suffix if the operating system
will be able to locate the macro without it. In most cases, you can omit the suffix if the
macro is in your current directory because the current directory is the first one the
operating system searches in attempting to locate commands. See Chapter 4 for an
explanation of the rules the operating system follows to locate a command.
The Macro Processor

The macro processor is that part of the operating system software that reads macro
files and processes macro statements (defined later in this chapter). The macro
processor does not process command lines and input lines (defined later) that it
encounters in macros; instead, it returns these lines to the command processor. The
operating system starts up the macro processor when a command macro is issued.

A line of a command macro can be any of the following:
• a command line
• a macro line
• an input line
This section first describes each of these three major elements. Then it explains the
use of spaces in macros. Finally, it describes the punctuation used in macros.
Command Lines
A command line is a set of one or more command strings, separated by semicolons. A
command string is a command name and any of the command’s arguments you select.
As described in Chapter 6, there are three types of commands: internal commands,

command macros, and program modules. The command in a command string can be
any one of these.
See “Avoiding Macro Recursion Loops” later in this chapter for an example of a
problem that can occur when a macro contains a call to itself.

Macro Lines
A macro line can be one of the following:
• a command macro statement

• a comment line
• a parameter declaration
Command Macro Statements

A command macro statement is a statement in the form &keyword that can be
included in a command macro to perform a predefined function. See Appendix D for
complete information about the command macro statements.
Command macro statements are often referred to simply as macro statements.
You cannot put more than one macro statement on a line. For example, the following
line would produce an error message:
&begin_parameters; &end_parameters
You cannot use abbreviations in macro statements.
Comment Lines
A comment line is either a line that begins with an ampersand (&) followed by a space
or a line that consists only of an ampersand. The characters that follow the ampersand
on the line, if any, are taken to be the comment. The command processor ignores all
comment lines.
Comment lines can be used to explain the purpose of the macro or to describe how it
works. Comment lines containing only an ampersand can be used to improve the
readability of a macro by clarifying its organization.
For example, the first two lines of the following macro are comment lines:
& This command macro is named set_cursor.cm.

&
!set_terminal_parameters -cursor_format blinking_underline
Parameter Declarations
For a description of parameter declarations, see ‘‘Parameters” later in this chapter.

Input Lines
You can use a command macro to call a program such as line_edit or
analyze_system that places the calling process into a request loop. You then use
subsequent lines of the macro to provide input to the program and to exit from the
program.
To supply input to a program in a macro, you must include the following elements in the
macro in the order shown:
• the &attach_input macro statement, which allows the program to accept input
directly from the macro file
• the command to invoke the program
• input to the program (probably including a request such as quit to exit from the
program)
• the &detach_input macro statement, which prevents any further program input
from coming from the macro
See Appendix D for information about the &attach_input and &detach_input

macro statements. In particular, see the example given for &attach_input. The
example is a macro that calls the line editor and executes line edit requests.
For complete descriptions of the line editor and the line edit requests, see Appendix E.
For information about the system-analysis subsystem, see the VOS System Analysis
Manual (R073).
Spaces
Extra spaces in a macro do not affect how the macro executes, but serve to improve
readability by allowing for similar indentation and spacing of similar items.
In a macro, the following are recognized as spaces:
• space characters
• horizontal tab characters
• vertical tab characters
• form feed characters
Punctuation
This section first lists the symbols that are used as separators and the symbols that are
used as operators. Then it describes how to use the symbols &+ as line continuation
characters. Finally, it explains how ampersands, apostrophes, exclamation points, and
dollar signs are used in macros.

Separators
The following characters are used as separators in macros:
( ) , . : ;
Operators
The following characters are used as operators in macros:
** (exponentiation)
+ (positive), - (negative), ^ (not)
* (multiplication), / (division)
+ (addition), - (subtraction)
|| (concatenation)
<, <=, =, ^=, >=, > (relations)
& (and)
| (or)
See the description of the (calc) command function in Appendix C for more
information about operators and their use in expressions.
Line Continuation Characters

You can continue a line in a macro onto a second or subsequent line by adding the
characters &+ before you press <RETURN> to continue the line. To include a line in a
macro that exceeds the maximum line length for a file, you must use line continuation
characters. In addition, by presenting a long line as separate lines in this way, you can
make the long line easier to read and understand.
The macro processor treats lines joined by line continuation characters as if they were
one line. Any leading blanks on the second or subsequent lines are ignored.
Ampersands
In some circumstances, the ampersand character (&) requires special treatment. A
single ampersand can be interpreted by the macro processor as any of the following:
• a macro statement indicator

• a comment line indicator
• a parameter delimiter (parameters are described later in this chapter)
• the “and” logical operator
If you want to include an ampersand in a macro but you do not want the command
processor to interpret it as an indicator, a delimiter, or a logical operator, you must use
two ampersands where you want the single ampersand to appear.

For example, suppose the current value of the macro variable &source& is
make_reports.cobol. (Macro variables are described later in this section.) Now
consider this command macro line:
&display_line The variable &source& is about to be used.
This line is displayed:
The variable make_reports.cobol is about to be used.
In contrast, consider the following command macro line:
&display_line The variable &&source&& is about to be used.
In this case, the following line is displayed:
The variable &source& is about to be used.
Apostrophes
There are two circumstances that require apostrophes in macros:
• To include an apostrophe in a character string within a macro, enclose the entire

string in apostrophes, and use two apostrophes where you want the single
apostrophe to appear within the string. For example:
!display_line 'Enter your employer''s address.'
• Normally, a command function inside a quoted string is not evaluated and replaced.
If you want such a command function to be evaluated and replaced, enclose the
command function (including its parentheses) in apostrophes. For example:
!display_line 'Your current directory is '(current_dir)'.'
Exclamation Points
An exclamation point (!) in a macro tells the operating system not to expand any
abbreviations that occur between the exclamation point and the end of the line. It is a
good practice to use exclamation points preceding every command and command line
in a macro.
For a full explanation of the use of exclamation points and of the need to suppress
abbreviations, see the section ‘‘Abbreviations in Macros” later in this chapter.

Command Functions in Macros
Dollar Signs
The dollar sign ($) can be used with macro variables in command macros. (Macro
variables are described later in this section.)
To enclose the value of a variable in apostrophes when it is replaced, you can use a
dollar sign as a prefix to the variable name. Using this prefix with a variable is similar
to specifying the variable as the argument of the (quote) command function (see
Appendix C), except that the dollar sign allows unbalanced quotation marks in the
string, but (quote) does not.
For example, if the current value of the parameter &source& is

make_reports.cobol, the macro statement &display_line &$source&
displays the output 'make_reports.cobol'
Command Functions in Macros

Command functions can be used in command macros. They are evaluated when the
macro is executed.
A command function included in a macro increases the generality of the macro. For
example, suppose a command macro contains these commands:
!attach_default_output (home_dir)>list_files.(date)
!list -files
This macro creates a file in the home directory of the current user, attaches the user’s
default_output port to the new file, and writes to this file the names of all files in the
user’s current directory. It then reattaches the default_output port to its previous
attachment. The first command function, (home_dir), allows any user to issue the
macro to create a file in his or her home directory. The second command function,
(date), ensures that whenever the macro is issued the file it creates will be named
with the current date.
When a command function is inside a quoted string, the command function will not be
evaluated and replaced unless you enclose it in apostrophes. For example:
!display_line 'Your current directory is '(current_dir)'.'
See Chapter 6 and Appendix C for information about command functions.

Abbreviations in Macros
Abbreviations in Macros
Command macros can contain abbreviations in command strings, but not in macro
statements. However, even in command strings you should avoid using abbreviations
in macros, for the following reasons.
• Not all users have the same abbreviations defined. The use of a macro that
contains abbreviations is limited to users who have defined those abbreviations.
• Using unabbreviated names in a macro makes the macro easier to read and
understand.
An exclamation point (!) in a macro tells the operating system not to expand any
abbreviations that occur between the exclamation point and the end of the line.
When you write a macro, it is a good practice to precede every command or command
line in the macro with an exclamation point. This ensures that other users will be able
to execute your macro even if it contains terms that they have defined as abbreviations.
For example, the following command string includes a file name, dirs. The
exclamation point preceding the command ensures that if a user issuing the macro has
the word dirs as an abbreviation, the abbreviation will not be expanded:
!line_edit dirs -no_backup -mapcase -no_verbose
Note that none of the sample command macros in this chapter uses abbreviations, and
that all use exclamation points to suppress expansion of abbreviations.
Expressions in Macros
An expression is a series of one or more operands and zero or more operators that can
be evaluated by the command processor to return a value. For example, the following
are expressions:
3 * 5
& code& = 0
(current_dir) ^= (home_dir)
aa || bb
In these expressions, the operators are *, =, ^=, and ||. The remaining elements of
the expressions are operands. The first of these expressions (3 * 5) is arithmetic, the
next two are logical, and the last is a string expression.
For full information about expressions, see the description of the (calc) command
function in Appendix C.

Macro Variables
Expressions are used in command macros in the following circumstances:
• on the right-hand side of an &if statement

• on the right-hand side of a &set statement
• in an explicit use of the (calc) command function in a &set_string statement.
In each of these circumstances, the value of the expression is evaluated by the (calc)
command function.
In a command macro, an expression can contain command functions, macro variables,

and macro parameters. (Macro variables and parameters are discussed later in this
chapter.) For example, the three logical expressions in the following lines contain the
command functions (current_dir) and (home_dir) and the macro variable dir:
&if (length &dir&) = 0 & (current_dir) ^= (home_dir)

&then !change_current_directory
&else !change_current_directory &dir&
The three expressions are:
(length &dir&) = 0 & (current_dir) ^= (home_dir)

(length &dir&) = 0
(current_dir) ^= (home_dir)
Note that the first expression contains the second and third expressions.
Macro Variables
A macro variable is a variable that is declared and given its initial value in one of the
macro assignment statements, &set or &set_string. These statements, which are
documented fully in Appendix D, have the following forms:
&set variable_name expression

&set_string variable_name S1...Sn
Each statement sets the value of variable_name to the value specified by

expression or S1...Sn. The value of variable_name can be either numeric or a
character string, but it must begin with an alphabetical character.
The &set statement assigns a numeric value to a variable by calling the (calc)
command function to evaluate the specified expression. (See the description of this
command function in Appendix C.) For arithmetic expressions and argument values
that require a numeric data type, use variables whose values are assigned with &set
statements.

Macro Variables
The &set_string statement assigns a character string value to a variable by calling

the (string) command function to evaluate the specified character string. (See the
description of this command function in Appendix C.) For argument values that require
a character string data type, use variables whose values are assigned with
&set_string statements.
NOTE
Semicolons, or strings containing semicolons, that appear
in the &set_string statement, must always be
enclosed within apostrophes.
You can specify an assignment statement anywhere in a command macro, but you
cannot use a variable in a macro until it has been defined. After a macro variable has
been defined, you can assign new values to it in subsequent assignment statements.
A macro variable can be used in an expression to calculate another value; it can be

passed to a command as an argument; and it can be assigned a value in another
assignment statement.
NOTE
The command-macro processor does not evaluate
&label statements for macro variable substitutions;
therefore, you should not use macro variables within
&label statements. The command-macro processor
evaluates &goto statements for macro variable
substitutions; therefore, you can use macro variables
within &goto statements.
The macro processor stores macro variables as character strings. When the value of a
variable is converted, it is treated as numeric if it can be converted to a number;
otherwise the value is treated as a string.
Once the variable is declared, you refer to the value of the variable by enclosing the
variable name in ampersands (&). For example, if the current value of the variable
named count is 0, then &count& is a reference to the value 0. If you omit the
ampersand delimiters, then count refers to the name count.

Macro Variables
The following command macro shows how the statements &set and &set_string
assign different values to a variable after evaluating the same right-hand component:
&set a +00500.00
&set_string b +00500.00
&
!display_line a = &a&
!display_line b = &b&
When issued, the preceding macro produces the following output:
a = 500
b = +00500.00
In the following example, assume that the expression specified by count can be
evaluated and reduced to a single numerical value. The &set statement defines the
variable num and assigns to it the current value of count:
&set num &count&
In the next two examples of assignment statements, the values of the variables var1
and var2 are equivalent. In the first example, the expression &count& + 1 is
evaluated with the implicit use of the (calc) command function; in the second
example, (calc) is specified explicitly, although it is not required:
&set var1 &count& + 1
&set var2 (calc &count& + 1)
In the next example, the variable this_dir is assigned a character string value that
equals the path name of the directory containing the object specified by the variable
source. (See the description of the (directory_name) command function in
Appendix C.)
&set_string this_dir (directory_name &source&)
If you want the value of a variable to be enclosed in apostrophes when it is replaced,

use a dollar sign as a prefix for the variable’s name. For an example, see the
information about dollar signs earlier in this chapter.

Parameters
Parameters
A parameter in a command macro is a named variable that is declared within the
parameter declaration section (defined below) of a command macro. A parameter
receives its initial value in one of the following ways:
• from an argument specified in the command string that calls the macro
• from a default value specified within the macro.
A macro variable, by comparison, is declared and receives its initial value in a macro
assignment statement.
The macro processor stores parameters as character strings. When the value of a
parameter is converted, it is treated as numeric if it can be converted to a number;
otherwise the value is treated as a string.
Parameter Declarations
A parameter declaration is a line in a command macro that appears between the macro
statements &begin_parameters and &end_parameters. (See Appendix D for
descriptions of these statements.) It must contain the name of a parameter and it can
contain a parameter descriptor (described later in this chapter). The form of a
parameter declaration is:
parameter_name [parameter_descriptor]
That portion of a macro from the &begin_parameters statement to the

&end_parameters statement is called the parameter declaration section. The
parameter declaration section must begin on the first line of the macro that is not a
comment line.
For example, the following parameter declaration section declares two parameters,
source_module and output_file. Note that neither of these declarations has a
parameter descriptor:
&begin_parameters
source_module
output_file
&end_parameters
If a command macro has one or more parameters defined in a parameter declaration

section, the macro accepts arguments from the command line. When you give a
command macro with one or more argument values, each value is assigned to the
parameter whose description it matches; the input value becomes the initial value of
the corresponding parameter.

Parameters
You can use a macro parameter in expressions to calculate other values, you can pass
it to a command as an argument, and you can assign a value to it in an assignment
statement. Once you assign a value to a parameter, however, the value supplied on
input is lost.
If a command macro does not accept parameters, it is good practice to include an

empty parameter declaration section, as follows:
&begin_parameters
&end_parameters
You can omit a parameter declaration section to achieve the same results. However,
including an empty declaration section explicitly states to a person reading the macro
that the command macro accepts no parameters.
Parameter Descriptors
A parameter descriptor is that part of a parameter declaration that specifies certain
characteristics of the parameter. For example, some of the characteristics you can
specify are:
• whether the user is required to supply a value for the parameter

• the type of the parameter (positional, optional, or switch)
• the data type of the value
• the default value, if any
If a parameter declaration contains no descriptor, the parameter has the following

characteristics by default:
• It is not required.
• It is a positional parameter.
• Its data type is a character string of up to 256 characters.
General Form
The following shows the general form of a parameter descriptor:
[label] specifier[qualifier] ...[default]
The only required element of a parameter descriptor is specifier.

Parameters
Labels
A label is an optional element of a parameter descriptor. Its purpose is to provide a
descriptive term that will be useful to the user of a macro. It has the following form:
label:
The label, if specified, must be the first component of the parameter descriptor. The
colon following label must be the only colon in the descriptor.
Depending on the type of the parameter, the label will appear in the display form, the
command-line form, both of these, or neither of these. As the next section explains,
there are three types of macro parameters: positional, optional, and switch. The
information provided by label is used differently depending on the type of the
parameter, as follows:
• For a positional parameter, a label is used to label the parameter’s field in the
display form. It also provides a label in the command-line form when you give the
command macro with the -usage option.
• For an optional parameter, a label is used to label the parameter’s field in the
command-line form only.
• For a switch parameter, there is no purpose for specifying a label, since it is used
in neither the display form nor the command-line form.
• All qualifiers except allow will allow a null string.
For examples of how labels are used, see the sections that describe positional and
optional parameter descriptors.
Specifiers
A specifier is an element of a parameter descriptor that defines the type of the
parameter. It is the principal element of the descriptor; a parameter descriptor is invalid
if it does not contain a specifier.
There are three types of parameters, and each type uses a different form for
specifier, as follows.
For a positional parameter, the form is:
parameter_data_type [suffix]
For an optional parameter, the form is:
option(option_keyword),parameter_data_type [suffix]

Parameters
For a switch parameter, the form is:
switch(switch_keyword)
For detailed descriptions of each of the forms, see the sections under “Parameter
Types.”
Qualifiers
A qualifier is an optional element of a parameter descriptor that specifies an attribute
of the parameter. Its form is:
,qualifier [(value)]
Note that a comma must precede qualifier.
The values you can specify for qualifier vary for different parameters, as follows:
• For switch parameters, you can use only the qualifiers hidden and noform.
• For positional and optional parameters, the allowed qualifiers vary according to the
parameter’s data type. See the section “Parameter Data Types” for lists of the
qualifiers allowed for each data type.
The remainder of this section describes the qualifiers.
allow (value1, (value2, (arg1,arg2)),[(valueN)]))

Specifies the allowed input values for the parameter. In the display form, you can
display the allowed values sequentially with the <CYCLE> key.
byte
Tells the macro processor to convert the input value to a one-byte integer. The
range of values allowed for a parameter qualified by byte is 0 to 255.
disable_input
Tells the macro processor that the parameter’s value must be specified either in the
command line or by default and cannot be changed in the form.
hidden
Specifies that the input value is not to be displayed on the screen when it is entered
in the display form. This qualifier is useful for passwords.
length (integer)
Specifies the maximum length of the input value.
longword
Tells the macro processor to convert the input value to a four-byte integer. The
range of values allowed for a parameter qualified by longword is
from -2,147,483,648 to 2,147,483,647.

Parameters
max (integer)
Specifies the maximum permissible value of the numeric variable.
min (integer)
Specifies the minimum permissible value of the numeric variable.
no_abbrev
Tells the macro processor that abbreviations are not to be expanded if the
parameter’s value is entered in the display form. This qualifier is useful for
parameter values that are command strings, since abbreviations can be expanded
again when the command string is used; it avoids double evaluation.
noform
Tells the command processor to omit this parameter in the display form of the
macro.
output_path (label)
Specifies the path name of the output file. If a parameter with an output_path
qualifier is not given an input value, the value of label is used. The value of label
must be the name of a label specified for a parameter in the current declaration
section.
required or req
Specifies that a value for this parameter cannot be omitted. If a parameter with a
required qualifier is not given an input value, the macro cannot be executed.
In the display form, the operating system highlights the field of a parameter that has
the required qualifier.
req_for_form
Specifies that a display form cannot exist if a parameter with a req_for_form
qualifier has no input value. The macro processor prompts for the value if you do
not specify it on the command line when you issue the macro.
word
Tells the macro processor to convert the input value to a two-byte integer. The
range of values allowed for a parameter qualified by word is from -32768 to
32767.
Defaults
A default is an optional element of a parameter descriptor that specifies a value for the
macro processor to use for the parameter if no input value is supplied.

Parameters
There are three forms of the default element. The first of these forms can be used with
a descriptor for any parameter type. It is:
,=default_value
Note that a comma followed by an equals sign must precede the value given for
default_value.
For positional and optional parameters, the value you can specify as a default depends
on the data type of the parameter. For switch parameters, the default value must be
either 1 or 0. When no default component is supplied for a switch, the default value is 0.
The other forms of the default element are valid only for optional parameters. These
forms are:
,==default_value_2
,=default_value_1,==default_value_2
These forms are described in detail under the heading “Optional Parameters.”
Parameter Types
This section describes each of the three types of parameters. The types are:
• positional
• optional
• switch
For each type, the section describes in detail the specifier component of the parameter
descriptor and explains how the label component functions. It also describes the two
forms of the default element that are allowed only with optional parameters.
Positional Parameters
A positional parameter is a parameter that the macro processor identifies in a
command line by the position of its value (rather than by a keyword).
The specifier component of a descriptor for a positional parameter has the following
form:
parameter_data_type [suffix]

Parameters
The value of parameter_data_type must be one of the following:
date_time
device_name
module_name
name
number
pathname
starname
string
system_name
unclaimed
user_name
See “Parameter Data Types” later in this section for descriptions of these data types.
You can specify a value for suffix only when the value of parameter_data_type
is pathname or starname. If the descriptor contains a suffix and you do not supply a
suffix as part of the parameter’s input value, the suffix specified in the descriptor is
appended to the value.
Some examples of suffixes are:
.pm
.cobol
.bind
.out
.cm
.text
When there is no descriptor defined for a positional parameter, the label for the field in
the display form is derived from the parameter’s name. For example, suppose the file
compile.cm in your current directory contains the following declaration section:
&begin_parameters
source_module
output_file
&end_parameters
The parameters defined in this example are both positional, since a parameter is
positional by default when it has no descriptor.
The following command-line form is displayed when you issue compile with the
-usage option:
Usage: compile [source_module] [output_file]

Parameters
The display form looks like this:
Display Form
----------------------------------- compile ------------------------------------
source_module:
output_file:
Now suppose that the parameter declaration section in the file compile.cm contains
descriptors for the two parameters defining their data types as path names:
&begin_parameters
source_module pathname
output_file pathname
&end_parameters
When the descriptor for a positional parameter does not contain a label, the label for
the field in the display form is derived from the specifier. Therefore, invoking this macro
in the display form produces the following:
Display Form
----------------------------------- compile ------------------------------------
path_name:
path_name:
You can more clearly describe a positional parameter by specifying a value for label
in the parameter descriptor. For example, suppose you add labels to the descriptors in
the compile.cm macro, as shown here:
&begin_parameters
source_module input_file:pathname
output_file output_file:pathname
&end_parameters
The macro’s display form now looks like this:
Display Form
----------------------------------- compile ------------------------------------
input_file:
output_file:

Parameters
Positional parameters are often given the required qualifier. For example, if the
source_file parameter in the macro compile.cm contains the descriptor
input_file:pathname,required, the display form looks like this:
Display Form
----------------------------------- compile -------------------------------------
input_file:
output_file:
Optional Parameters
An optional parameter is a parameter that the macro processor identifies in a command
line by a keyword that begins with a hyphen and is followed by a value.
The specifier component of a descriptor for an optional parameter has the following
form:
option(option_keyword),parameter_data_type[suffix]
You may include or omit a hyphen preceding the value for option_keyword. If you
omit the hyphen, the macro processor will add it to the beginning of the keyword when
it displays the macro’s display form or command-line forms.
The value of parameter_data_type must be one of the following:
date_time
device_name
module_name
name
number
pathname
starname
string
system_name
unclaimed
user_name
See “Parameter Data Types” later in this chapter for descriptions of these data types.
You can specify a value for suffix only when the value of parameter_data_type
is pathname or starname. If the descriptor contains a suffix and you do not supply a
suffix as part of the parameter’s input value, the suffix specified in the descriptor is
appended to the value.

Parameters
Suppose the following declaration section appears in a command macro named

search.cm:
&begin_parameters
pn file_name:pathname,required
ma character_string:option(match),string,=''
&end_parameters
The parameter named ma is an optional parameter. It has the label

character_string, whose uses are described below.
The specifier portion of the descriptor is:
option(match),string
It has the following elements:
• option, which identifies the parameter as optional

• match, which is the option_keyword element of the specifier
• string, which is the parameter_data_type element (specifying that the
parameter’s value must be a character string).
The value ,='' is the default element of the descriptor. It specifies that the default
value for this parameter is the null string.
The display form for the command macro search.cm looks like this:
Display Form
------------------------------------ search ------------------------------------
file_name:
-match: ''
In the display form for an optional parameter, the value for label (if any) specified in
the descriptor is ignored. Instead, the parameter’s label is derived from
option_keyword.
When you issue the search.cm macro with the -usage option, the following
command-line form is displayed:
Usage: search file_name [-match character_string]
In the command-line form for an optional parameter, the value for label (if one is
specified in the descriptor) is shown following the option_keyword value. If the
descriptor does not contain a label value, the value of parameter_data_type is

Parameters
shown following the keyword. For example, this is the declaration section for the
search.cm macro without labels in the parameter descriptors.
&begin_parameters
pn pathname,required
ma option(match),string,=''
&end_parameters
When you give the search.cm macro with the -usage option, the following
command-line form is displayed:
Usage: search pathname [-match string]
The default element of the descriptor for an optional parameter can be in any of the
following forms:
,=default_value
,==default_value_2
,=default_value_1,==default_value_2
The first of these forms is valid for all parameter types. It is described earlier in this
chapter under “Defaults.”
With the second and third forms, you can invoke the macro on the command line using
the parameter’s keyword (that is, the value of option_keyword) without giving a
value for the parameter. If you do this, default_value_2 is used as the default.
The second form has only one default value. It is used as the default only when you
invoke the macro with option_keyword and no value.
The third form allows you to specify two default values for a parameter. The command
processor recognizes one or the other as the default depending on how the macro is
called, as follows:
• The value of the parameter is default_value_1 when the macro is invoked

without the value of option_keyword specified on the command line.
• The value of the parameter is default_value_2 when the macro is invoked with
the value of option_keyword specified on the command line.
Therefore, depending on how you call the macro, the value displayed in the
parameter’s field in the display form is either default_value_1 or
default_value_2.
With either the second or the third form for the default element, the value that follows
option_keyword is enclosed in square brackets ([]) in the command-line form.

Parameters
For example, this is the declaration section for the macro print_report.cm:
&begin_parameters
fn file_name:pathname,required
hd header:option(header),string,==DRAFT
ft footer:option(footer),string,=Weekly,==Monthly
&end_parameters
If you call the macro without specifying -header, there is no value shown for the hd
parameter in the display form. If you do specify -header, the value in the -header
field is DRAFT.
If you call the macro without specifying -footer, the value shown for the ft
parameter in the display form is Weekly. If you do specify -footer, the value in the
-footer field is Monthly.
The following examples show command lines that call the display form of the
print_report.cm macro with and without the option keywords, and they show the
display forms that result in each case:
print_report.cm <DISPLAY_FORM>
Display Form
--------------------------------- print_report ---------------------------------
file_name:
-header:
-footer: Weekly
print_report.cm -header -footer <DISPLAY_FORM>
Display Form
--------------------------------- print_report ---------------------------------
file_name:
-header: DRAFT
-footer: Monthly
Switch Parameters
A switch parameter is a parameter that has only two possible values and that the macro
processor identifies as follows:
• in the command-line form, by a keyword beginning with a hyphen, in either

affirmative or negative format (for example, -ask or -no_ask)

Parameters
• in the display form, by a keyword beginning with a hyphen followed by the value
yes or no.
The value of the parameter is 1 when the keyword is in affirmative format or followed
by yes. The value is 0 when the keyword is in negative format or followed by no.
Switch parameters are used in macros primarily in conditional &if statements. (See
the description of the &if statement in Appendix D.)
The specifier component of a descriptor for a switch parameter has the following
form:
switch(switch_keyword)
You may include or omit a hyphen preceding the value for switch_keyword. If you
omit the hyphen, the macro processor will add it to the beginning of the keyword when
it displays the macro’s display form or command-line form.
Note that this specifier differs from the specifiers for positional and optional parameters
because it does not include the element parameter_data_type. Data type
specification is unnecessary for a switch, since the parameter’s value is limited to yes
(1) or no (0).
Switch parameters accept only the qualifiers noform and hidden, which are
described in the “Qualifiers” section.
The value of the default component (if any) in the descriptor for a switch parameter
must be either 1 or 0.
The following example adds to the search.cm macro a line describing the switch
parameter ln:
&begin_parameters
pn file_name:pathname,required
ma character_string:option(match),string,=''
ln switch(line_numbers),=1
&end_parameters
The descriptor for ln has no label, since a label for a switch parameter is ignored by
the command processor.
The specifier portion of the descriptor is:
switch(line_numbers)

Parameters
It has the following elements:
• switch which identifies the parameter as a switch

• line_numbers, which is the switch_keyword element of the specifier.
The value ,=1 is the default element of the descriptor. It specifies that the default
value for this parameter is 1.
The following display form is displayed when you issue the macro search.cm with the
<DISPLAY_FORM> key.
Display Form
------------------------------------ search -------------------------------------
file_name:
-match: ''
-line_numbers: yes
Note that the label for the switch parameter is -line_numbers, the value of
switch_keyword.
The following command-line form is displayed when you issue search with the
-usage option:
Usage: search file_name [-match character_string]

[-no_line_numbers]
As in the display form, the label for the switch parameter in the command-line form is
derived from the switch_keyword value. However, when the default value of the
parameter is affirmative (1), as it is for the ln parameter, the command processor
displays the label in its negative form (in this case, -no_line_numbers). This is
because a user calling the search.cm macro would never have to give the value
-line_numbers, since this value is supplied by default.
Parameter Data Types

This section describes the values available for the parameter_data_type element
of the specifier for a positional or optional parameter. (You do not specify data types for
switch parameters.)
The description of each data type includes a list of the qualifiers allowed with that data
type.

Parameters
date_time
Specifies a parameter that takes as an input value a date/time string. Some
examples of values date_time accepts are:
1june2001
1 june, 2001
6/1/01
01-june-01
8:00
13:00:00
10 am
06:00
(date)
(time + 1 hour)
(date_time coming friday 5:00 pm)
You can specify a date or time only, or a combination of both. In the command-line
form, you must enclose the input value in apostrophes if it contains spaces. For
more information about allowable date/time string values, see Appendix G.
The following qualifiers are valid for a parameter of this data type:
disable_input
hidden
noform
required
req_for_form
The default value, if any, must be a date and/or time string and it must be enclosed
by apostrophes.
When you use the date_time data type, spaces in the returned value are
converted to underlines (_). This occurs both when you specify a value and when
you use a default.

Parameters
The following example includes a descriptor for a positional parameter specifying

that one of the expected input values is a time string:
&begin_parameters
name user_name:user_name,required
text message:string,required,no_abbrev
time time:date_time
&end_parameters
&if (given time) & (time) <= &time&
&then !send_message &name& &$text& -system
&return
The following example includes a descriptor for an optional parameter specifying

that the expected input value is a date/time string:
&begin_parameters
dir directory_name:pathname,required
time option(-date_time),date_time
&end_parameters
device_name
Defines a parameter that takes as an input value the path name of a device. Some
examples of values device_name accepts are:
%s1#p1.0
#p1.0
p1.0
(terminal_name)
allow
disable_input
hidden
length
no_abbrev
noform
required
req_for_form
The default value, if any, must be a device name.

Parameters
The following example shows a parameter descriptor specifying that the expected
input value is the name of a device:
&begin_parameters
device option(-device),device_name,=%s1#p1.2
&end_parameters
module_name
Defines a parameter that takes as an input value the path name of a module. Some
examples of values module_name accepts are:
%s1#m2
#m2
m2
(current_module)
allow
disable_input
hidden
length
no_abbrev
noform
required
req_for_form
The default value, if any, must be a module name.
input value is the name of a module:
&begin_parameters
module option(-module),module_name,=%s1#m2
&end_parameters
name
Defines a parameter that accepts a name as an input value.
A name is an ASCII character string of not more than 32 characters, consisting

either of a single letter or a sequence of letters, digits, and the underline character;
the first character must be a letter.

Parameters
allow
disable_input
hidden
length
module_starname
no_abbrev
noform
required
req_for_form
The default value, if any, must be a name. If the default value contains a colon,
comma, equals sign, space, or left or right parenthesis, it must be enclosed in
apostrophes.
input value is the name of an object:
&begin_parameters
source source_module:name,required
&end_parameters
&if (exists -file &source&.out)
&then !truncate_file &source&.out
&else !create_file &source&.out
!set_implicit_locking &source&.out
!batch '(home_dir)>cms>runbind &source&' -output_path
&source&.out
&return
number
Defines a parameter that takes as an input value a character string consisting of
integers.

Parameters
allow
byte
disable_input
hidden
longword
max
min
noform
required
req_for_form
word
The default value, if any, must be a number.
pathname
Defines a parameter that takes a path name or a star name as an input value. The
following are values pathname accepts:
• a full path name

• a relative path name
• a star name
• a command function that returns a path name
disable_input
hidden
noform
output_path
required
req_for_form
The default value, if any, must be a path name or a star name. If the default value
contains a colon, comma, equals sign, space, or left or right parenthesis, it must be

Parameters
The following examples illustrate parameter descriptors specifying path names as

expected input values:
&begin_parameters
file_a first_file:pathname,required
file_b second_file:pathname,required
&end_parameters
&begin_parameters
command batch_command_macro:pathname.cm,required
&end_parameters
starname
Defines a parameter that takes a star name or a path name as an input value. The
following are values starname accepts:
• a star name
• a full path name
• a relative path name
• a command function that returns a path name.
disable_input
hidden
noform
output_path
required
req_for_form
The default value, if any, must be a star name or a path name. If the default value
contains a colon, comma, equals sign, space, or left or right parenthesis, it must be
The following example illustrates a parameter declaration specifying a star name

as an expected input value:
&begin_parameters
file_a input_files:starname,required
file_b output_file:pathname,required
&end_parameters

Parameters
string
Defines a parameter that accepts as an input value a character string value of up
to 300 characters, including spaces and numeric characters. Any character can
appear in a string.
allow
disable_input
hidden
length
no_abbrev
noform
required
req_for_form
The default value, if any, must be a character string. If the default value contains a
colon, comma, equals sign, space, or left or right parenthesis, it must be enclosed
in apostrophes.
The following example includes a parameter descriptor specifying that the

expected input value is a character string:
&begin_parameters
command
command:string,length(300),required,no_abbrev
output
option(-output_path),pathname,=file_command.text
&end_parameters
The descriptor for the command parameter allows the macro to accept a command
line as an input value. The parameter is defined as a string since a command line
can be up to 300 characters long.
The string parameter data type is also appropriate in the following command
macro, which edits an abbreviation:
&begin_parameters
abbrev abbreviation:string,required,no_abbrev
&end_parameters
&attach_input
!line_edit (home_dir)>abbreviations -no_keystrokes

Parameters
-no_verbose
upward insert &$abbrev&
write
quit
&detach_input
!sort (home_dir)>abbreviations
!use_abbreviations (home_dir)>abbreviations
&return
The value of the parameter &abbrev& is a character string representing the

abbreviations directive to be added to the abbreviations file. The string data type
is appropriate since the length of &abbrev& must be able to vary greatly. The
macro calls the line editor to insert the abbreviation string into the file.
Note that in the preceding example, the name of the parameter &abbrev& is
preceded by a dollar sign ($) when used as an argument to the line edit request
upward insert. This is so that the value of &abbrev& will be enclosed in
apostrophes when it is replaced. (The insert request requires a delimiting
character for the text it inserts.) See Appendix E for information about the
line_edit command.
system_name
Defines a parameter that takes as an input value the path name of a system. Some
examples of values system_name accepts are:
%s1
s1
(system_name)
allow
disable_input
hidden
length
no_abbrev
noform
required
req_for_form
The default value, if any, must be a system name.

Parameters
The following example illustrates a parameter descriptor specifying that the

expected input value is the name of a system:
&begin_parameters
system option(-system),system_name,=%s1
&end_parameters
unclaimed
Defines a parameter that accepts as input values any parameters not specifically
declared with a parameter descriptor.
allow
disable_input
hidden
length
no_abbrev
noform
required
req_for_form
The command processor forms a character string from all undeclared parameters
and inserts one space between each consecutive pair; the unclaimed parameter
has this string as its value. The length of the string must not exceed
256 characters.
The following example shows a parameter descriptor specifying an unclaimed

parameter data type:
&begin_parameters
file file_name:pathname,required
rest unclaimed
&end_parameters
&
!print &file& -copies 3 -module (current_module) -indent 5
&rest&
&return
Input values for declared parameters (such as the path name value in the
preceding example) are assigned to the corresponding parameters. Any remaining
input values specified for which parameter descriptors do not appear are stored in
the parameter rest (defined as unclaimed). Thus, you can use the unclaimed
parameter type to enter more parameters than are specifically declared.

Parameters
The following command macro, which contains an unclaimed parameter type,

adds an abbreviation to the user’s abbreviations file:
&begin_parameters
ab_line abbreviations:unclaimed,no_abbrev
&end_parameters
&attach_input
!line_edit (home_dir)>abbreviations -no_keystrokes
-no_verbose
upward insert &$ab_line&
write
quit
&detach_input
!sort (home_dir)>abbreviations
!use_abbreviations (home_dir)>abbreviations
&return
This example is almost identical to the sample command macro that appears in the
discussion of the string data type. The only difference is that the replacement
directive to be added to the user’s abbreviations file is stored in the unclaimed
parameter ab_line instead of the string parameter abbrev. The unclaimed
type also permits the length of ab_line to vary greatly, since a string parameter
is limited to 300 characters or less.
The next example might appear in a command macro to compile a source module.
It illustrates how to use an unclaimed parameter type to vary the compiler options
you specify when you call the macro in which it appears:
&begin_parameters
source source_module:pathname,required
compiler_options options:unclaimed
&end_parameters
user_name
Defines a parameter that takes as an input value the name of a user. Some
examples of values user_name accepts are:
Smith.Sales
Smith.*
*.Sales
*.*
Smith
(person_name)

End Qualifiers
allow
disable_input
hidden
length
no_abbrev
noform
required
req_for_form
The default value, if any, must be a name in the appropriate form. If the default
value contains a colon, a comma, an equals sign, a space, or a left or right
parenthesis, it must be enclosed in apostrophes.
End Qualifiers
An end qualifier is an element that can be included with an &end_parameters macro
statement to specify one of the following:
• that certain parameters are mutually exclusive

• that at least one of the named parameters must be given
• that the display form is always displayed
• that the macro will accept only the default values
• that the display form has a two-column format
• that the macro can be issued only by a privileged user.
The end qualifiers are described with the &end_parameters statement in

Appendix D.
How a Command Macro Is Processed

A macro is processed according to the following steps:
1. The command processor reads the command string from the terminal (when the
macro is called from command level) or from a command macro file (when the
macro is called from within another macro).
2. The command processor expands abbreviations in the command string, following
the same rules it uses when processing commands from a terminal. (See
Chapter 5 for information about abbreviations.)
3. The macro processor reads lines from the macro file until it reaches the end of the
file. It initializes the variables and processes the macro statements, and it conveys
commands and input lines to the command processor for execution.

Avoiding Macro Recursion Loops
Avoiding Macro Recursion Loops

A command macro can contain calls to itself. However, if you write a macro that calls
itself, you should observe precautions to avoid a recursion loop, which is the repetitive
execution of the same program.
For example, suppose you write a macro named cobol.cm that contains the following
command line:
!cobol &source&
This command line is intended to call the VOS COBOL compiler program module
cobol.pm to compile a source file specified by the parameter source. However,
suppose you have changed the command library path directories for your process so
that the command processor finds the macro cobol.cm before it finds cobol.pm.
(See Chapter 4 for information about the command search rules.) In this case,
cobol.cm executes itself recursively. The command processor performs the recursion
until it runs out of memory and aborts the macro.
You can avoid recursion in this macro by specifying the suffix .pm for the cobol
command. For example, the following macro calls the VOS COBOL compiler explicitly:
&begin_parameters
source source_file:pathname,required
rest unclaimed
&end_parameters
!cobol.pm &source& &rest&
&return
Startup Command Macros

Most users store a command macro in their home directories called the startup
command macro. Typically, a startup command macro contains commands and other
instructions that tailor the command environment to the requirements of a particular
user. The macro must have the name start_up.cm.
When you log in, the operating system searches your home directory for the file
start_up.cm. If it finds start_up.cm, it executes the macro before reading
commands from your terminal.
There may be a standard startup command macro on file for your system. If so, your
system administrator can provide you with a copy. You can then modify this standard
macro, if you wish, to suit your own needs. You can also delete the macro if you want
to; generally, you are not required to have a startup command macro, although your
system administrator can require you to use one.

Typically, a startup command macro performs the following activities:
• sets the characteristics of your terminal with the set_terminal_parameters

command
• compiles an abbreviations file with the use_abbreviations command (see
Chapter 5)
• adds directories to the system libraries on the current module with the
add_library_path command (see Chapter 4)
• displays system-wide notices with the display_notices command
• displays messages or files with the display_line and display commands.
For example, suppose the file start_up.cm in your home directory contains the
following instructions:
!set_terminal_parameters -cursor_format blinking_underline

!display_line 'Good morning, Joe'
!display memo_file.new
!change_current_dir (home_dir)>reports
When you log in, this startup macro performs the following steps:
1. It sets the format of the cursor on your screen to a blinking underline.

2. It displays on your screen the line Good morning, Joe.
3. It displays the contents of the file memo_file.new, which is stored in your home
directory.
4. It changes the current directory to the subdirectory reports.
In the next example, the user named Smith in the group Sales has a startup macro
that executes another macro named backdel.cm each time Smith logs in before
9 AM. The backdel.cm macro deletes all back-up files from Smith’s home directory
and all subdirectories in that hierarchy. Smith’s startup command macro looks like this:
!use_abbreviations
&if (process_type) = batch
&then &goto batch
!display_notices
&if (time) < 09:00:00
&then !start_process backdel
&label batch
!add_library_path command (home_dir)
&return

The macro file backdel.cm contains the following command lines:
!attach_default_output (home_dir)>backup.out
!walk_dir %s1#d02>Sales>Smith -down_command 'delete_file
*.backup -no_ask'
The backdel.cm command macro does the following:
1. It issues the attach_default_output command to attach the

default_output port to the output file called backup.out in Smith’s home
directory.
2. It issues the walk_dir command to execute the command delete_file
*.backup -no_ask in each directory of the hierarchy %s1#d02>Sales>Smith.
3. It issues the detach_default_output command to reattach the
default_output port to its previous attachment.
In the backdel.cm macro, note that the -append option is omitted from the
attach_default_output command in this example; it assumes that Smith requires
a list of only the most recently deleted back-up files. Including the -append option,
however, would result in the file backup.out maintaining a historical list of all deleted
back-up files unless Smith edits the file.
In the start_up.cm macro, note the following:
• If Smith’s process is a batch process, as determined by the (process_type)

command function, the macro backdel.cm is not executed.
• The macro backdel.cm is executed from a started process. Any error messages
resulting from its execution (for example, if delete_file finds no back-up files in
one of the directories) are recorded in the output file called backdel.out, which
is created by the start_process command. Thus, Smith obtains a record (in
backdel.out) of which files were not found, as well as a record (in backup.out)
of which files were deleted.
In contrast, if backdel.cm were issued interactively, VOS would display any error
messages on Smith’s screen instead of writing the messages (and other output) to
an output file.
• The command add_library_path command (home_dir) is included so that

Smith can issue backdel.cm regardless of the current directory.

Examples of Command Macros

This section first describes the macro append_file.cm. Then it describes the macro
append_list.cm, which calls append_file.cm. It also shows how
append_file.cm could be enhanced to perform the function of append_list.cm.
Finally, it provides a lengthy example using the macro compile_and_go.
The append_file.cm Macro

The following command macro, named append_file.cm, appends the contents of
one file to another file:
&begin_parameters
file filename:pathname,required
&end_parameters
&
!attach_default_output out_sink.out -append
!display &file& -no_header
This macro performs the following actions:
1. It passes a path name input value to the parameter named file.

2. It issues the attach_default_output command to attach the default output
port to the output file out_sink.out and to specify (with the -append option) that
the contents of the output file are appended instead of truncated.
3. It issues the display command with the -no_header option to write to the output
file the contents of the input file without a header.
4. It issues the detach_default_output command to reattach the
default_output port to its previous attachment.
This macro uses the attach_default_output and detach_default_output

commands to divert output from a terminal screen to a file and then to redirect it back
to a terminal. Note that you can use the commands start_logging and
stop_logging to perform the same functions.
Each time you issue the append_file.cm macro, it appends the contents of a new
input file to the accumulated contents of out_sink.out. To append the contents of a
file named weekly_1, you would enter the following command line:
append_file weekly_1

The append_list.cm Macro

To append several files to the file out_sink.out by issuing a single command, you
could create a command macro named append_list.cm that contains several calls
to the append_file macro, each with a different input path name. Such a command
macro might look like this:
!append_file weekly_1
When you issue the append_list.cm command macro, it appends the contents of
all six input files to out_sink.out in the sequence in which they appear in the macro.
Alternatively, you could change the append_file.cm macro as follows:
• define additional parameters in the parameter declaration section so the macro

accepts additional path name input values
• specify additional display commands with parameter names corresponding to
the additional parameter declarations as argument values.
This technique has the advantage of avoiding the need to change the input file names
for each append_file command line in the append_list.cm macro file whenever
you want to append the contents of new files to the file out_sink.out. Also, this
method permits the default_output port to be attached and detached only once
instead of successively as it is each time append_file.cm is issued in the
append_list.cm command macro.
The compile_and_go.cm Macro

The final example is a command macro named compile_and_go that compiles,
binds, and executes a VOS COBOL program. This macro illustrates the most
frequently used features of the command macro language:
& command macro compile_and_go

&
&begin_parameters
program_name source_module:pathname.cobol,required
args options:unclaimed
&end_parameters
&
(Continued on next page)

&if ^ (exists &program_name&)

&then &goto no_source
&
&set name (before (object_name &program_name&) .cobol)
!attach_default_output
!cobol &program_name& &args& -list
&if (command_status) ^= 0
&then &goto errors
&
!print &name&.list -delete
!bind &name&.obj
&then &goto bind_fails
&
&name&.pm
&goto cleanup
&
&label no_source
&display_line The source module &program_name& does not
exist.
&return
&
&label errors
!print &name&.error -delete
&goto cleanup
&
&label bind_fails
&display_line The object module &name&.obj cannot be bound.
&
&label cleanup
&set cs (command_status)
&return &cs&
This command macro does the following:
1. It accepts a file name as input and assigns it to the program_name parameter. Any
additional input values are assigned to the parameter args, which is specified as
unclaimed.
2. It determines whether the object specified by &program_name& exists. If not,
control transfers to the group of macro statements labeled no_source. These
statements display an appropriate message and terminate the command macro.
3. It assigns to the variable name the value returned by the (before) command
function (the value of program_name with the suffix .cobol omitted).

4. It attaches the default_output port to the file default_output.out with the

attach_default_output command.
5. It compiles the VOS COBOL source module and creates a compilation listing.
6. It determines whether the compilation terminated normally. If not, control transfers
to the group of macro statements labeled errors. These statements print and
then delete the error file (specified by &name&.error), and transfer control to the
label cleanup.
7. It prints and then deletes the compilation listing (specified by &name&.list), then
binds the resulting object module (specified by &name&.obj).
8. It determines whether the binding operation terminated normally. If not, control
transfers to the label bind_fails and an appropriate message is displayed.
9. It executes the resulting program module and transfers control to the label
cleanup.
10. It performs several clean-up operations, then terminates the macro.
Note the following in this command macro:
• Blank comment lines are used to improve readability by dividing the macro into
related groups of instructions.
• The command functions (exists) (in Step 2) and (command_status) (in
Steps 6 and 8) are used in several expression components of &if statements.
The value of the (exists) command function is 1 if a specified object exists,
and 0 otherwise. Similarly, the value of the (command_status) command
function is 0 if the preceding program terminated normally, and a different value
otherwise. This macro example illustrates how to use these command functions in
conditional &if and &then statements to control the order in which commands in
a macro are executed.
For information about a similar use in a source module of the system variable called
command_status (the value of which is returned by the (command_status)
command function), refer to the description of the VOS PL/I subroutines
s$stop_program and s$error in the VOS PL/I Subroutines Manual (R005).
Here is an example of how you might issue the command macro compile_and_go:
compile_and_go make_reports -no_optimize

Assuming that the source module make_reports exists in the current directory, and
that no errors occur during compilation and binding, issuing this command macro is
equivalent to interactively entering the following sequence of commands:
attach_default_output
cobol make_reports.cobol -no_optimize -list
print make_reports.list -delete
bind make_reports.obj
make_reports.pm
detach_default_output
The compilation listing, the object module, and the file default_output.out are
stored in the current directory, which is not necessarily the directory that contains the
source module.


Chapter 8
Executing Noninteractive
Processes 8-
When your current process is interactive, the operating system waits for the current
command to complete before it starts executing your next command. If a command is
time-consuming to execute, this can be inconvenient. Such a command can be
handled more efficiently by a noninteractive process.
This chapter has two sections that describe the ways to execute a noninteractive
process:
• ‘‘Batch Processes”
• ‘‘Started Processes”
Batch Processes
A batch process is a process that the operating system runs concurrently with the other
processes in the system when time and resources are available. It does not interfere
with an interactive session on your terminal. A batch process can execute any
command that does not require user interaction, but cannot execute one that does. For
example, a batch process cannot execute the emacs command.
To start a batch process, you issue the batch command, specifying in the
command_line argument one or more commands that you want executed in a batch
process. The commands are called a batch request.
In the command-line form of the batch command, enclose the command line in
apostrophes if it contains a space, a semicolon, or parentheses that are not part of a
command function.
When the operating system receives a batch request, it puts the request into a queue
known as the batch queue. The batch processor is the part of the operating system
software that creates batch processes and manages the batch queue. The batch
processor handles the requests in the batch queue sequentially, starting a batch
process for each request when the request preceding it in the queue has been
completed.
Executing Noninteractive Processes 8-1

Batch Processes
The batch processor also handles tasks such as restarting a batch process after a
system interruption, sending notification that a batch process has finished, stopping a
batch process that has been cancelled with the cancel_batch_requests
command, and displaying the status of batch requests. However, the batch processor
does not control a batch process after the process has been started.
Priorities
This section describes the two types of priority for a batch process:
• ‘‘Queue Priority”
• ‘‘Process Priority”
Queue Priority
Normally, batch requests are put in the batch queue in the order they are issued.
However, you can specify a queue priority with a batch request that will place the
request ahead of (or behind) others in the queue.
A queue priority is a number ranging from 0 (the lowest) to 9 (the highest) that
determines where in the queue a newly issued batch request will be inserted relative
to existing requests. Since requests in the batch queue are started according to their
order in the queue, the request with the highest queue priority will be at the head of the
queue and thus will be started first. If two or more requests have the same priority, the
oldest request is started.
You assign a queue priority using the the -queue_priority argument of the batch
command.
Use the following command to determine the priority of all requests currently in the
batch queue:
list_batch_requests -all -long
Next, issue your batch request with a higher (or lower) value for -queue_priority.
Your request will enter the queue ahead of any unstarted requests with lower priorities,
or behind any with higher priorities. Requests with the same priority will be placed in
the queue in the order of their arrival.
To change the position of your presently enqueued request, you can issue the
update_batch_requests command with the -queue_priority option. Specify a
value for -queue_priority that puts your request either ahead of or behind other
requests currently in the batch queue.
If you do not specify a queue priority for a batch request, the request enters the queue
with a priority value of 4.

Batch Processes
Process Priority
In addition to the queue priority, each batch request has a process priority associated
with it (as does any process, whether invoked interactively or through a batch process).
A process priority is a number ranging from 0 (the lowest) to 9 (the highest) that
determines the precedence of a process relative to other processes for the allocation
of CPU time. The process priority, which is discussed under ‘‘Priority Levels’’ in
Chapter 1, controls the execution of a process after the process has been started. Only
the queue priority of a batch request influences when the batch process starts relative
to other requests on the batch queue.
Use the -process_priority argument of the batch command to specify the

process priority of a batch process. If you do not specify a process priority, the batch
process will have the priority of the process that invoked it.
Note that queue priority and process priority are unrelated.
Batch Control File

If you choose the -control argument of the batch command, the batch processor
takes its instructions from the batch control file specified with the argument.
A batch control file is a text file containing directives that control the timing and order of
the execution of the batch request and that has a name ending with the suffix .batch.
Each directive must end with a semicolon, and the last directive must be end;.
Using a batch control file can shorten the command line when you issue the
command-line form of the batch command. You can specify in the batch control file all
the options to use and then issue the batch command, giving only the command_line
argument and the -control argument. Typical uses for a batch control file are:
• for running a batch job you frequently issue with the same options
• for running batch jobs that require the wait_on path_name and
wait_on_module module_name directives, since they are unavailable as
batch command arguments
Some of the directives you can specify in a control file are identical to the arguments
that you can give with a batch command. The batch processor disregards any
repetitions. However, options specified on the command line override any in the control
file if there is a discrepancy.

Batch Processes
Batch Control Directives

The following describes the directives you can include in a batch control file:
after process_name;
Specifies one or more process names, star names, or requests submitted by
(user_name).*. It does not refer to all requests in the queue. The newly issued
batch request is not executed until the processes identified by process_name
have finished executing. By default, the operating system executes the batch
request after executing requests that have a higher priority in the queue. In the
command line form of the command, command_line must precede -after.
cpu_limit elapsed_cpu_time;
Allots the amount of CPU time available to the batch process. The
elapsed_cpu_time value is measured in hours, minutes, and seconds; hours
and minutes are optional.
defer_until date_time;
Defers the batch process until the specified date and time. The value of
date_time can be a character string in the standard form:
yy-mm-dd hh:mm:ss
It can also be a character string in any form accepted by the (date_time)

command function. In this case, the string must be enclosed in apostrophes. See
Appendix G for information about date/time input strings.
end;
Designates the end of the control file. The end; directive must be the last directive
in a batch control file.
Example
A batch control file in the current directory named compile_all.batch could contain
the following directives:
process_name compile_all;
output_path compile_all.out;
wait_on >system>object_library;
wait_for_module %s1#m2;
end;
The command line to invoke this batch control file looks like this:
batch command_line -control compile_all.batch

Batch Processes
Note that you can optionally omit the suffix .batch in the control_file_name value
of the -control argument.
notify[user_name[module_star_name]];
Notifies the user specified by user_name when something needs to be mounted
and when a batch process terminates. If you omit a value for user_name, or if
user_name is a period (.), the batch processor uses your user name. If you omit
a value for module_star_name, the batch processor notifies all modules on the
current system.
output_path path_name;
The path name of the device or file to which the batch process is output.
process_name process_name;
The name of the batch process.
process_priority process_priority;
The process priority of the batch process.
yy-mm-dd hh:mm:ss
It can also be a character string in any form accepted by the (date_time)

command function. In this case, the string must be enclosed in apostrophes. See
Appendix G for information about date/time input strings.
wait_on_module module_name;
Indicates that the module specified by module_name must be available before a
batch process starts.
wait_on path_name;
Indicates that the resource (such as a tape drive) specified by path_name must
be available before the batch process starts. If the path name refers to a device,
then the batch processor reserves the device and the reservation is passed on to
the batch process; if the device referred to is a disk, the batch processor reserves
the disk until the batch process ends. Reserving a device prevents any other
process from accessing the device until the reservation is cancelled. Only a device
can be reserved. If the path name refers to a file or a directory, the process waits
until the object is unlocked before starting. This directive can be given more than
once.

Started Processes
Commands Related to Batch Processing

This section lists and briefly describes commands related to batch processing:
• The display_batch_status command displays information about batch

queues on a particular module.
• The list_batch_requests command displays information about batch
requests that you or other users have issued.
• The update_batch_requests command enables revision of many parameters
of a request that is in the batch queue but that has not started execution.
• The cancel_batch_requests command cancels a batch process.
• The reserve_device command reserves a device, such as a tape drive or
printer, for the execution of a batch process.
• The move_device_reservation command changes the device reserved for a
batch process.
• The cancel_device_reservation command cancels the reservation of a
device.
Started Processes
A started process is a process that runs independently of and concurrently with your
interactive process. You create a started process with the start_process command.
Like a batch process, a started process can execute any command that does not
require user interaction. For example, a batch process cannot execute Emacs. Unlike
a batch process, however, a started process begins running immediately after you
issue the start_process command.
You can start multiple concurrent processes. Also, you can start a process anywhere
in the system, so work can be done on a more convenient module. For example, you
may want to execute a command macro on the module on which it is stored.
In the following example, the command compiles the VOS COBOL source file
make_reports.cobol independently of your current interactive session:
start_process 'cobol make_reports.cobol'
Note that this example shows the start_process command in the command-line
form, and that the command line contains spaces. Therefore, the command line is
A started process terminates independently of the process that starts it.
To stop a process before it terminates, use the stop_process command.

Chapter 9
Understanding Access
Control 9-
This chapter describes the access control facility. It has six sections, as follows:
• ‘‘Types of Access Rights” describes some tasks you typically perform and the
access required for each task. Then it explains the types of access a user can have
to files and the types of access a user can have to directories.
• ‘‘Access Control List Entries” describes access control list entries, the user name
component of these entries, and how the entries are sorted.
• ‘‘Types of Access Control Lists” describes file access control lists, directory access
control lists, and default access control lists.
• ‘‘How the System Determines Access” explains how the operating system uses
access control lists to determine a user’s access rights when he or she attempts to
use a file or directory.
• ‘‘Commands for Displaying Access” describes the commands that let you display
your own access rights and those of other users.
• ‘‘Commands for Managing Access” describes the commands that let you define
who has access to your files and directories, and what kinds of access they have.
Types of Access Rights

There are minimum access requirements for every task you do on the computer. Your
system administrator defines the access rights you have to your home directory. You
determine the access rights that you and others have to all its subordinate directories
and to all files in those directories. The system administrator also defines the access
rights you have to other objects in the system and the access rights other users have
to your home directory.
Table 9-1 lists several categories of file-related tasks you are likely to perform on a
regular basis, some examples of commands you issue to perform them, and the access
rights you need. The next section describes these access rights.
Understanding Access Control 9-1

The table is based on these assumptions:
• dir1 is the current directory.

• file1 is a file in dir1.
• file2 does not exist.
• file.lang is a file with a program language name suffix.
• file.cm is a command macro in dir1.
• file.pm is a program module in dir1.
Table 9-1. Access Rights Required for File-Related Tasks
File-Related
Tasks Examples of Commands Access Requirements
Creating a file copy_file file1 file2 Read access to file1 and

modify access to dir1
create_file file2 Modify access to dir1
emacs file2 Modify access to dir1
Compiling a cobol file.cobol Read access to file.lang,

program fortran file.fortran default write access
pl1 file.pl1 on dir1, and modify
access to dir1
Updating a file edit file1 Write access to file1

emacs file1 Write access to file1
line_edit file1 Write access to file1
Reading a file copy_file file1 file2 Read access to file1 and

modify access to dir1
display file1 Read access to file1
Deleting a file delete_file file1 Modify access to dir1
Renaming a file rename file1 file2 Modify access to dir1
Executing a file file.cm Execute access to file.cm

file.pm Execute access to file.pm
Table 9-2 shows some directory-related task groups, an example of a command in

each category, and the access rights you need.

The table is based on these assumptions:

• dir2 is a subdirectory of dir1.
• dir3 does not exist.
Table 9-2. Access Rights Required for Directory-Related Tasks
Directory-Related
Tasks Examples of Commands Access Requirements
Creating a directory create_dir dir3 Modify access to dir1
Listing a directory list -all dir1>* Status access to dir1
Deleting a directory delete_dir dir2 Modify access to dir1
Renaming a directory rename dir2 dir3 Modify access to dir1
As the preceding tables illustrate, access can apply to two kinds of objects: files and
directories. There are different levels of access a user can have to each of these
objects. The next two sections describe these levels of access rights for files and
directories.
File Access Rights

There are four types of access rights a user can have to a file. They are described as
follows:
• Null access means a user has no access to the file.

• Execute access means a user can execute a program module or a command
macro, but cannot read or write the file.
• Read access means a user can read the file or execute it if it is executable, but
cannot write it.
• Write access means a user can execute, read, and write the file.

Access Control List Entries
Directory Access Rights

There are three types of access rights a user can have to a directory. They are
described as follows:
• Null access means a user has no access to the directory.

• Status access means a user can display information about the directory (using
commands such as list and display_file_status), but cannot modify the
directory by creating, deleting, or renaming objects.
• Modify access means a user has full access to the contents of the directory,
including the ability to create, delete, and rename objects.

Access to files and directories is defined by entries in system files called access control
lists. An entry in an access control list has two parts:
• an access right, which specifies what kind of access the set of users has to a file
or directory
• a user name, which specifies a set of one or more users having a specified type of
access right to a file or directory.
The following example represents the contents of an access control list specifying user
access to a directory:
m Smith.Sales
m Smith.*
s *.Sales
n *.*
The letter m represents modify access, s represents status access, and n represents
null access.
The following example represents an access control list specifying user access to a file:
w Smith.Sales
r Smith.*
e *.Sales
n *.*
The letter w represents write access, r represents read access, e represents execute
access, and n represents null access.
The next two sections describe user names in access control lists, and how they are
used to determine the order in which entries in an access list are sorted.

User Names
A user name has the following form:
person_name.group_name
A user name can represent an individual user. For example, Smith.Sales represents
the user with the person name Smith and the group name Sales. A user name that
can represent one or more users is called a user star name. In a user star name, either
component is an asterisk or both components are asterisks. There are three forms that
a user star name can have, as follows:
• person_name.* specifies the set of all users with the same person name,
regardless of group names. An example is Smith.*.
• *.group_name specifies the set of all users in the same group, regardless of
person names. An example is *.Sales.
• *.* specifies the set of all users, regardless of person names or group names.
An individual’s user name is said to match a user star name in the following
circumstances:
• When the user star name is in the form person_name.*, the individual’s user
name must have the same person name.
• When the user star name is in the form *.group_name, the individual’s user name
must have the same group name.
• When the user star name has two asterisks, all user names are matches for it.
• The following are matching user names:

Jones.Accounting matches Jones.*
Jones.Sales matches *.Sales
Smith.Accounting matches *.Accounting
Clark.Personnel matches *.*.
How Access Control List Entries Are Sorted

Entries in an access control list are sorted in order of increasingly inclusive user names.
As a result, the order of names in an access control list is as follows:
• Those with no asterisks are first (for example, Jones.Sales).

• Those in the form person_name.* follow next (for example, Jones.*).
• Those in the form *.group_name are next (for example, *.Sales).
• The name *.* is last.

Types of Access Control Lists
Types of Access Control Lists

There are three kinds of lists that define access control:
• file access control lists

• directory access control lists
• default access control lists
These lists are described in the next three sections. The fourth section describes how
the operating system uses these lists to determine a user’s access.
File Access Control Lists

A file access control list is associated with a file and contains an ordered set of entries
that defines the access rights of users to that file.
The operating system maintains a file access control list for every file in the system.
The entries in a file access control list are created in the following ways:
• When you create a file, the operating system gives it an empty access control list.
• In any directory you have modify access to, you can add, change, or remove
entries from the access control lists associated with its files. (See ‘‘Commands for
Managing Access” later in this chapter.)
Directory Access Control Lists

A directory access control list is associated with a directory and contains an ordered
set of entries that defines the access rights of users to that directory.
The operating system maintains a directory access control list for every directory in the
system. The entries in a directory access control list are created in the following ways:
• When you create a directory, the operating system gives the directory a copy of the
access control list of its containing directory.
entries from the access control lists associated with its subdirectories. (See
‘‘Commands for Managing Access” later in this chapter.)
Default Access Control Lists

A default access control list is associated with a directory and contains an ordered set
of entries that defines the access rights of users to files in that directory.

How the System Determines Access
The operating system maintains a default access control list for every directory in the
system. The entries in a default access control list are determined in the following ways:
• When you create a directory, the operating system gives it a copy of the default
access control list of its containing directory.
entries from the default access control list associated with it. (See ‘‘Commands for
Managing Access” later in this chapter.)
How the System Determines Access

When a user tries to use a file or directory, the operating system checks entries in the
appropriate access control list for a matching user name.
In an access control list, no user name can appear more than once. However, a user
name can match more than one user star name. Further, each user star name
matching an individual’s user name can be paired with a different access right.
Therefore, the operating system uses the following method to unambiguously
determine a user’s access:
• searches the appropriate access control list (starting at the top) for a user name
that matches the individual’s user name
• uses the access right paired with the first matching user name.
For a file, this means that the operating system does the following:
1. searches the file access control list for a user name that matches the individual
user’s name
2. uses the access right paired with the first matching user name
3. if no match is found in the file access control list, searches the default access
control list of the file’s containing directory.
4. uses the access right paired with the first matching user name in the containing
directory’s default access control list
5. if no match is found in either the file access control list or the containing directory’s
default access control list, the user has undefined access, which is effectively null
access

Commands for Displaying Access
For a directory, the operating system does the following:
1. searches the directory access control list for a user name that matches the
individual user’s name
2. uses the access right paired with the first matching user name
3. if no match is found in the directory access control list, the user has undefined
access, which is effectively null access.

This section describes the following commands:
• display_access_list—This command shows entries in file access control

lists and directory access control lists.
• display_default_access_list—This command shows entries in default
access control lists.
• display_access—This command shows user access to files and directories.
The following table shows the file and directory access rights required to issue the
commands in this section. The table is based on these assumptions:

• dir2 is a subdirectory of dir1
Command Minimum Access Requirements
display_access_list file1 Status access to dir1
display_access_list dir2 Status access to dir1
display_default_access_list dir2 Status access to dir2
display_access file1 Status access to dir1 or execute access

to file1
display_access dir2 Status access to dir1 or status access to

dir2
The output of two of these commands uses one-letter codes, called access codes to
represent access rights.

The display_access_list Command

The display_access_list command shows the access control lists of one or more
files and directories.
Examples
The following command displays the file access control list of the file named report
in the current directory:
display_access_list report
The output looks like this:
%s1#d01>Sales>Smith>report
r *.Sales
The single entry shown in this example specifies that the set of all users with the group
name Sales has read access to the file.
See ‘‘The display_access Command” later in this chapter for an example of how
user access information for a file is derived from the file access control list.
The following command displays the directory access control list of the directory
monthly_meetings:
display_access_list monthly_meetings
%s1#d01>Sales>Smith>monthly_meetings
m Smith.Sales
s Jones.*
s *.Sales
s *.Accounting
The entries shown in this example specify user access to the directory
monthly_meetings as follows:
• The user Smith.Sales has modify access.

• The set of users with the person name Jones has status access.
• The set of users with the group name Sales has status access.
• The set of users with the group name Accounting has status access.

The display_default_access_list Command

The display_default_access_list command displays the default access
control list of a directory, showing the access users have to files in the directory.
Example
The following command displays the default access control list for the current directory,
%s1#d01>Sales>Smith:
display_default_access_list (current_dir)
%s1#d01>Sales>Smith
w Smith.Sales
r Jones.*
r *.Accounting
The entries shown in this example specify user access to the files contained in the
directory %s1#d01>Smith>Sales as follows:
• The user Smith.Sales has write access.

• The set of users with the person name Jones has read access.
• The set of users with the group name Accounting has status access.
See the next section for an example of how user access information for a file is derived
from the containing directory’s default access control list. Recall, however, that the
access right paired with the first matching user name in a file access control list
overrides the access right paired with a matching user name in a default access control
list.
The display_access Command

The display_access command lets you display the following:
• your access to one or more files or directories

• the access of another user to one or more files or directories
• the access of all users to one or more files or directories.
To display the access to a file, the display_access command uses both the file
access control list and the default access control list of the file’s containing directory.
To display the access to a directory, the command uses only the directory access
control list.

Examples
The following command displays your access to the file named report:
display_access report
The output looks similar to this:
write %s1#d01>Sales>Smith>report
The following command displays the access of the user Jones.Accounting to all
files and directories in the current directory, %s1#d01>Sales>Smith:
display_access * -user Jones.Accounting
status %s1#d01>Sales>Smith>monthly_meetings
read %s1#d01>Sales>Smith>report
null %s1#d01>Sales>Smith>travel
The user named Jones.Accounting has status access to the directory

monthly_meetings, read access to the file report, and null access to the file or
directory travel.
Note that in the output of the preceding command, file and directory names are listed
alphabetically.
The following command displays the access of all users to the file named report in
the current directory. When the -all argument is given, the display_access
command displays a list that merges the file access control list and the containing
directory’s default access control list:
display_access report -all
w Smith.Sales (D)
r Jones.* (D)
r *.Sales
r *.Accounting (D)
Recall that the sample output of the display_access_list report command

shows that the only entry in the access control list for the object report is for the user
star name *.Sales. In this example, the letter D in parentheses indicates that the file

Commands for Managing Access
access information for the user names Smith.Sales, Jones.*, and *.Accounting
is derived from the default access control list for the directory
%s1#d01>Sales>Smith. The file access information for the user name *.Sales, on
the other hand, is derived from the access control list of the file report.
The following command shows the access of all users to the directory
monthly_meetings:
display_access monthly_meetings -all
m Smith.Sales
s Jones.*
s *.Sales
s *.Accounting
Note that the access information used for the output in this example is derived from the
directory access control list. Therefore, the output of this example is identical to the
output of the command display_access_list monthly_meetings.

This section describes the following commands:
• give_access—This command inserts entries in a file access control list or a

directory access control list.
• remove_access—This command deletes entries in a file access control list or a
directory access control list.
• give_default_access—This command inserts entries in a default access
control list.
• remove_default_access—This command deletes entries in a default access
control list.
• propagate_access—This command updates entries in the directory access
control lists and default access control lists of directories subordinate to a specified
directory.
• set_owner_access—This command sets the owner-access switches of a
program module.
• verify_posix_access—This command displays a report for a directory or
directory hierarchy that summarizes the POSIX.1 access modes for each object.

The following table shows the file and directory access rights required to issue the
commands described in this section. The table is based on the following assumptions:

• dir2 is a subdirectory of dir1.
• file3.pm is a program module in dir1.
Command Access Requirements
give_access access file1 Modify access to dir1
give_access access dir2 Modify access to dir1
remove_access file1 Modify access to dir1
remove_access dir2 Modify access to dir1
give_default_access access dir2 Modify access to dir2
remove_default_access access dir2 Modify access to dir2
propagate_access dir1 Modify access to dir1
set_owner_access file3.pm Modify access to dir1
The give_access Command

The give_access command inserts an entry into a file or directory access control list
in order to define the access of one or more users to the file or directory.
Examples
The following command adds to the file access control list of the file report an entry
specifying that the set of users matching the user star name *.Temp has write access
to the file:
give_access write report -user *.Temp

Now, if you give the command display_access_list report, the output looks
like this:
r *.Sales
w *.Temp
The output of the command display_access report -all now looks like this:
w Smith.Sales (D)
r Jones.* (D)
r *.Sales
w *.Temp
r *.Accounting (D)
Suppose the current directory is monthly_meetings. The command

display_access_list monthly_meetings displays the following output:
m Smith.Sales
s Jones.*
s *.Sales
s *.Accounting
The following command changes to null the access right of the user star name
*.Accounting for the directory monthly_meetings:
give_access null monthly_meetings -user *.Accounting
The command display_access_list monthly_meetings now displays the

following output:
m Smith.Sales
s Jones.*
s *.Sales
n *.Accounting
Note that the output of the command display_access monthly_meetings -all

is identical to the output in the preceding example, except for the access right paired
with the user star name *.Accounting.

The remove_access Command

The remove_access command removes entries from file access control lists and
directory access control lists.
Example
The following command removes from the file access control list of the file report an
entry specifying that the set of users matching the user star name *.Temp has no
access to the file:
remove_access report -user *.Temp
Now, if you give the command display_access_list report, the output looks
like this:
r *.Sales
The output of the command display_access report -all now looks like this:
w Smith.Sales (D)
r Jones.* (D)
r *.Sales
r *.Accounting (D)
The give_default_access Command

The give_default_access command specifies user access to files by inserting
entries into the default access control list of the directory containing the files.
Example
The following command adds to the default access control list of the current directory,
%s1#d01>Smith>Sales, an entry specifying that the set of users matching the user
star name *.* has null access to the files in that directory:
give_default_access null (current_dir) -user *.*

The command display_default_access_list (current_dir) now produces

the following output:
%s1#d01>Sales>Smith
w Smith.Sales
r Jones.*
r *.Accounting
n *.*
Also, the command display_access report -all now produces this output:
w Smith.Sales (D)
r Jones.* (D)
r *.Sales
r *.Accounting (D)
n *.* (D)
The remove_default_access Command

The remove_default_access command removes user access to files by deleting
entries from the default access control list of the directory containing the files.
Example
The following command deletes from the default access control list of the current
directory, %s1#d01>Smith>Sales, the entry with the user star name
*.Accounting:
remove_default_access (current_dir) -user *.Accounting
The command display_default_access_list (current_dir) now produces

the following output:
%s1#d01>Sales>Smith
w Smith.Sales
r Jones.*
n *.*

Also, the command display_access report -all now produces this output:
w Smith.Sales (D)
r Jones.* (D)
r *.Sales
n *.* (D)
The propagate_access Command

The propagate_access command replaces or inserts entries into the directory
access control lists and default access control lists of directories subordinate to the
specified directory.
When you create a directory, it inherits the directory access control list and default
access control list of its containing directory. But when you later change the directory
access control list or default access control list of the containing directory, the operating
system does not update the directory access control lists and default access control
lists of the subordinate directories. You can use the propagate_access command to
update these lists so they match the new lists on the superior directory.
Example
Assume that the following commands (shown earlier in this chapter) have been given:
give_access null %s1#d01>Smith>Sales>monthly_meetings -user

*.Accounting
give_default_access null %s1#d01>Smith>Sales -user *.*
remove_default_access %s1#d01>Smith>Sales -user *.Accounting
Recall that the object monthly_meetings is a directory.
The following command replaces the directory access control lists and the default
access control lists of all directories subordinate to the current directory,
%s1#d01>Smith>Sales:
propagate_access

The output of the command display_access_list monthly_meetings now

looks like this:
%s1#d01>Smith>Sales>monthly_meetings
m Smith.Sales
s Jones.*
s *.Sales
n *.Accounting
The output of the command display_default_access_list

monthly_meetings now looks like this:
%s1#d01>Smith>Sales>monthly_meetings
w Smith.Sales
r Jones.*
n *.*
The set_owner_access Command

The set_owner_access command sets the owner-access switches of a program
module. The two switches are the person switch and the group switch. Each switch can
be set to either true or false. Using this command lets you arrange for users of a
program to temporarily have the same access to files and directories as the program’s
owner. An owner is the author of a program module.
• When the person switch is true, the person name component is the same as the
author’s person name.
• When the group switch is true, the group name component is the same as the
author’s group name.
During program execution, the operating system uses this owner-access switch to
determine your process’s access rights, where necessary. When you are the owner of
a program, you can precisely tailor the access users have to objects such as
databases.
To set the owner-access switches of a program module, you need modify access to the
containing directory.
You can see the current values of the person and group switches of a program module
using the display_file_status command.

Example
Suppose that the owner of the file make_report.pm is Clark.Accounting, and

suppose that the user Smith.Sales runs the program.
The following table shows the temporary name of Smith’s process during the execution
of the program for all possible settings of the person and group switches of the program
module.
Temporary Name Person Switch Group Switch
Clark.Accounting true true
Clark.Sales true false
Smith.Accounting false true
Smith.Sales false false
As another example, suppose you have modify access to a directory containing a

database. In this database, many users need read access to some fields in a record,
but read access to all other fields must be restricted to all but a few users. To meet
these requirements, you can take the following steps:
1. Give read access to the database to the few individuals, including yourself, and
give null access to everyone else.
2. Write a program that displays only selected fields.
3. Set the owner access switches on the program so that all user processes running
the program temporarily have your person and group access rights.
Therefore, anyone using the program temporarily has your access to the database
(read access), and they can see data only in the fields you selected.
The verify_posix_access Command

The verify_posix_access command displays a report for a directory or directory
hierarchy that summarizes the POSIX access modes for each object.
Run the verify_posix_access command to check the contents of valid VOS

POSIX ACLs in order to identify the owner of an object. (This is necessary for POSIX
functions such as stat(), fstat(), chmod(), and chown() to function properly.)
NOTE
You may want to run this command periodically on
directories that contain objects that the POSIX

applications might access because files are frequently

added, modified, or deleted.
Since ACLs provide extended permissions, it is possible to create ACLs that do not
cleanly map to VOS POSIX basic permissions. This prevents VOS POSIX Support
from determining the owner ID and/or group ID of a file or directory. For more
information on POSIX Support, see VOS POSIX.1: Support Guide (R502).
Example
The following example specifies that only the current directory (in this example,
Manual>Stratus) should be analyzed:
verify_posix_access -depth 1 -long
Owner Group Other Obj Object

Access Access Access Type Name
------------- ---------------- -------- ---- ---------
%es#Manual>Stratus
w rwx Abcdef w rwx SysAdmin n --- *.* dacl default access list
w rwx Abcdef n --- Stratus n --- *.* file .bash_history
w rwx Abcdef r r-x Stratus r r-x *.* file .bashrc
w rwx Abcdef w rwx SysAdmin n --- *.* file .signature
w rwx Abcdef w rwx SysAdmin n --- *.* file .spam
w rwx Abcdef w rwx ???????????? n --- *.* file 14.4.2
Each line of the report is the status of a single object. The columns are Owner Access,
Group Access, Other Access, Object Type, and Object Name. Each of the
access columns is further subdivided into VOS access mode, POSIX access mode,
and a name. When a unique Owner or Group name cannot be determined, the
respective column is filled with a question mark (?).

Appendix A
Commands Grouped by Task A-
This appendix shows how commands are related according to the tasks they are used
to complete. For a complete description on how to use these commands see the VOS
Commands Reference Manual (R098).
Batch Processing
batch
Puts a request for a batch job into a batch queue. A batch request is a command
line that will be executed as a noninteractive process. The purpose of running a
batch job is to postpone the consumption of system resources by jobs that do not
require interaction.
cancel_batch_requests
Removes a batch request from the batch queue before the process starts, or stops
running a batch process or processes.
cancel_device_reservation
Cancels a reservation of a device.
display_batch_status
Displays the status of the batch queue on a specified module, including: the name
of the queue or queue, the state of the queue, the maximum number of users, and
the number of jobs.
list_batch_requests
Displays information about a set of batch requests.
move_device_reservation
Moves a device reservation from the current process to another process. Uses this
command in conjunction with the reserve_device command.
reserve_device
Reserves a device for use by your process. While you have a device reserved for
a process, no other process can use the device.
set_cpu_time_limit
Sets the upper bound on the amount of central processor time a process can
consume before it is stopped.
Commands Grouped by Task A-1
Commands Grouped by Task
set_priority
Sets the execution priority for one or more processes. The process name identifies
the process (among several processes running with a given user name) for which
priority is to be set.
sleep
Puts a process to sleep for a specified period, after which the operating system
reactivates the process. The sleeping process is the process that issues the
command.
start_process
Creates and starts a process.
stop_process
Stops a process.
update_batch_requests
Modifies a batch request in the batch queue before it is processed. Uses this
command to change the command line, the order of requests in the queue, and so
on.
Break/Interrupt
break_process
Sends an interrupt signal to a process.
debug
Calls the symbolic debugging aid.
kill
Sends a signal to the processes specified by each pid operand.
Controlling Access to Data

Access Control
display_access
Displays the access rights one user has to a set of files and directories. If you do
not give the name of a user, the command displays your access rights.
display_access_list
Displays the access control lists for a set of files and directories you specify.
display_default_access_list
Displays the default access control lists of directories you specify. A default access
control list, in conjunction with the access control list, sets the access on files and
links to files created in the directory.
A-2 VOS Commands User’s Guide (R089)

give_access
Adds entries to the access control lists of a file, directory, or set of such objects.
Uses this command to set explicit access rights for individuals or groups of users.
give_default_access
Adds entries to the default access control lists of a directory or set of directories.
The default access control list of a directory controls the access to any file in the
directory of users who are not covered by the access control list of the file.
propagate_access
Copies a directory’s access control lists to all of the directories subordinate to it in
the hierarchy.
remove_access
Removes entries from the access control lists of a file or directory, or set of such
objects.
remove_default_access
Removes entries from the default access control lists of a directory or set of
directories.
set_owner_access
Sets the owner access bits on an executable file.
verify_posix_acess
Displays a report for a directory or directory hierarchy that summarizes the
POSIX.1 access modes for each object.
Displaying Access
display_access
Displays the access rights one user has to a set of files and directories. If you do
not give the name of a user, the command displays your access rights.
display_access_list
Displays the access control lists for a set of files and directories you specify.
display_default_access_list
Displays the default access control lists of directories you specify. A default access
control list, in conjunction with the access control list, sets the access on files and
links to files created in the directory.
verify_posix_acess

Controlling File Access

give_access
Adds entries to the access control lists of a file, directory, or set of such objects.
Uses this command to set explicit access rights for individuals or groups of users.
give_default_access
directory of users who are not covered by the access control list.
propagate_access
Copies a directory’s access to all the directories subordinate to it in the hierarchy.
remove_access
Removes entries from the access control lists of a file or directory, or set of such
objects.
directories.
set_expiration_date
Sets an expiration date on a file to protect it against premature deletion.
set_owner_access
set_safety_switch
Turns a safety switch on or off for a file or files, preventing premature deletion or
truncation of the file.
Controlling Directory Access

give_access
Adds entries to the access control lists of a directory or set of directories. Uses this
command to set explicit access rights for individuals or groups of users.
give_default_access
directory of users who are not covered by an access control list.
propagate_access
Copies a directory’s access control list to all of the directories subordinate to it in
the hierarchy.
remove_access
Removes entries from the access control lists of a directory or set of directories.

directories.
Controlling System Access

login
Starts an interactive process or subprocess.
verify_system_access
Checks that you can use the resources of a system to access files and to start
processes in that system.
Customizing Your Environment

Creating Synonyms
link
Creates a link to a file, directory, or another link. A link is a synonym of the object
name of the file or directory, or a synonym for another link.
link_dirs
Creates in each directory of a set links to all objects in every other directory in the
set. Uses the link_dirs command to make two or more directories equivalent;
typically, to create links in top-level directories on systems configured with several
logical disks.
unlink
Deletes one or more links.
use_abbreviations
Activates the abbreviations file after you edit it or when you log in. The command
defines the abbreviations file that the command processor will subsequently use to
expand abbreviations in your command lines and debugging aid commands.
Setting Up Program Libraries

add_library_path
Adds a path name to the list of directories that the operating system searches to
find objects.
delete_library_path
Removes a path name from the list of directories that define a specified library.
list_library_paths
Displays a list of directories that define libraries for the current process.
set_library_paths
Sets the path names of the directories defined as libraries for the current process.

Setting Up Your Process Environment

set
Assigns, clears, or displays environment variables.
set_language
Sets the language the process is to use for National Language Support.
set_time_zone
Sets the time zone for your current process. The operating system changes the
time of day in your process to correspond to the new time zone.
use_abbreviations
Activates the abbreviations file after you edit it or when you log in. The command
defines the abbreviations file that the command processor will subsequently use to
expand abbreviations in your command lines and debugging aid commands.
Setting Up Your Terminal

set_ready
Sets the form of the prompting message the operating system displays on your
terminal when it returns your process to command level.
set_terminal_parameters
Sets the terminal parameters for your terminal. Each field of the form displays the
current value for your terminal, which the operating system uses as a default value
when you do not explicitly give a value.
Editing
Edit
Calls the screen editor. This command puts your process at editor request level.
edit_form
Calls the forms editor. This command puts your process at forms editor request
level.
emacs
Calls the emacs text editor. This command puts your process at editor request
level.
line_edit
Calls the line editor. This editor is useful for creating command macros that
manipulate text.

Getting Started
Communicating with Other Users
comment_on_manual
Sends user comments about Stratus manuals over the Remote Service Network
(RSN) to the Customer Assistance Center (CAC). You can use this command only
if the RSN is installed and enabled on your system.
send_message
Sends a message to one or more users’ terminals.
Getting Information about Devices

display_device_info
Displays information about a device defined on the current module.
display_disk_info
Displays information about the disks in a module.
display_disk_usage
Displays the number of disk blocks occupied by a directory and all its contents.
display_system_usage
Displays information about the current usage of a module or set of modules.
list_devices
Lists the path names of a set of devices connected to a set of modules.
Getting Information about the System

check_posix
Checks that POSIX support is installed and operational.
display_current_module
Displays the full name of the module running your process.
display_date_time
Displays the current date and time.
display_device_info
display_disk_info
Displays information about the disks in a module.
display_disk_usage
Displays the number of disk blocks occupied by a directory and all its contents.

display_notices
Displays system-wide notices on the terminal screen. In particular, the command
displays all files named (master_disk)>system>notices*.
display_system_usage
Displays information about the current usage of a module or set of modules.
help
Lists the names of commands and command functions.
list_devices
list_gateways
Lists network gateways in the system. A gateway provides a communications link
from the current system to one or more other systems. This link can connect
directly to another system or it can connect to a common network shared by
multiple systems.
list_modules
Lists one or all of the modules in a system.
list_systems
Lists the systems accessible from your module.
list_users
Displays information about selected processes.
set
Assigns, clears, or displays environment variables.
Getting On and Off the System

call_thru
Connects your login terminal to a remote host either as a login terminal or as a
slave terminal.
login
Starts an interactive process or subprocess.
logout
Ends a login process or login subprocess.

Getting Status Information

display_current_dir
Displays the full path name of your current directory on your terminal screen.
display_date_time
Displays the current date and time.
display_error
Displays the text of an error message identified by a particular error code.
display_line
Displays on your terminal the literal text of the argument that follows the command
name on the command line.
list_devices
list_modules
Lists one or all of the modules in a system.
list_systems
Lists the systems accessible from your module.
list_users
Displays information about selected processes.
verify_system_access
Checks that you can use the resources of a system to access files and to start
processes in that system.
where_command
Finds out the type of a given command and the full path name of a program module
or command macro. The command uses your process’s command library path
names to locate the command.

Managing Files and Directories

Backing Up and Restoring Files
restore_object
Restores directories, files, or links saved with the save or save_object
command.
save_object
Saves a directory, file, or link on magnetic tape or in a disk file.
verify_save
Verifies that an object or set of objects saved using the save_object or save
command is restorable.
Changing Directories
change_current_dir
Changes your current directory.
Converting Files
cvt_stream_to_fixed
Converts a stream file (either a program module, object module, or terminal type
object file) to a fixed file.
set_log_protected_file
Converts an ordinary file or files into a log protected file or files, or converts a log
protected file or files into an ordinary file or files.
Creating and Deleting Directories

create_dir
Creates one or more directories.
delete_dir
Deletes directories and all their contents.
Creating and Deleting Files

create_data_object
Creates an object module of a specified size, to be used by processes that share
virtual memory.
create_file
Creates an empty file.
delete_file
Deletes files from the directory hierarchy.
truncate_file
Truncates a file or files to zero length, and truncates all the file indexes.

Copying, Renaming, and Moving Directories

copy_dir
Copies a directory and its contents from one location to another.
move_dir
Moves a directory and its contents from one place in the file system to another.
rename
Gives a directory a new name.
translate_links
Changes the name of a disk, directory, or a system. The changes occur in the link
targets throughout a directory hierarchy.
Copying, Renaming, and Moving Files

convert_text_file
Converts the data of a text file to conform to a new default character set and shift
mode.
copy_file
Copies a file or set of files from one location to another in the file system.
move_file
Moves a file or set of files.
rename
Gives a file a new name.
set_text_file
Changes the text file attributes of an existing file.
Getting Information about Files

display_file_status
Displays information about a specified set of files.
Getting Information about Directories

display_current_dir
Displays the full path name of your current directory on your terminal screen.
display_dir_status
Displays information about a directory.
walk_dir
Executes a command or start a process in a specified directory and all directories
subordinate to it.

Comparing Directories
compare_dirs
Compares two directories and displays the differences.
Comparing Files
compare_files
Compares one or more files with another file and displays the differences if there
are any.
Displaying Files
display
Displays the contents of a file on the output device or file attached to your
default_output port (normally your terminal) or to the device or file you
specify in the command.
display_file
Displays the contents of a file on the output device or file attached to your
default_output port (normally your terminal), or to the device or file you
specify in the command.
dump_file
Dumps the contents of a file for debugging purposes, or dump the contents of an
index to a file. The command dumps the contents of the file in both hexadecimal
and ASCII, with the ASCII text in the rightmost column.
Locating Files
list
Lists the files in a directory.
locate_files
Lists all files in a directory subhierarchy whose names match one or more file
names.
Locating Directories
list
Lists the contents of a directory.
Sorting Files
sort
Sorts the records in one or more ASCII text files and merges the sorted files with a
set of presorted files, using collating sequences and sort keys you give either in the
command or in a sort control file.
text_data_merge
Sorts and merges records to create form letters.

Ports
attach_default_output
Attaches to a file or I/O device the output port that is normally attached to your
terminal. Command output is directed to that file or device until you give the
detach_default_output command.
attach_port
Creates and names an I/O port and attaches it to a specified file or I/O device.
Detaches your default_output port and reattaches it to its previous attachment,
which is normally your terminal. Use this command in conjunction with the
detach_port
Detaches an attached port from a file or I/O device.
list_port_attachments
Lists information about a set of ports in your process.
start_logging
Starts logging the I/O traffic through a port to a log file or I/O device.
stop_logging
Stops logging the I/O traffic through a port. Use this command in conjunction with
the start_logging command.
POSIX
The following set of POSIX.1 commands are shipped with VOS:
check_posix
Displays an error or warning message if the configuration of the current module
does not meet the constraints imposed by the VOS POSIX.1 implementation.
Otherwise, returns the message No errors were detected.
handle_sig_dfl
Changes the default action of certain POSIX.1 signals.
kill
Sends a signal to the processes specified by each pid operand.
verify_posix_access

Printing
Getting Information about Printers
display_device_info
display_print_status
Displays the status of the printer or printers connected to one or more modules.
Getting Information about Print Requests

display_print_defaults
Displays the default values for one or more specified print queues.
list_print_requests
Displays information about a set of print requests.
Printing Files
cancel_print_requests
Cancels one or more print requests. The command removes the request from the
print queue or stops the job from printing.
print
Prints one or more files.
Programming
Analyzing Programs
analyze_pc_samples
Analyzes the program counter (PC) raw data file created by the
harvest_pc_samples command, and generates a statistical report on the
execution of one or more specified program modules.
harvest_pc_samples
Collects process information and program counter (PC) samples from the module
for a specified length of time. The output is stored in a file that is analyzed with the
analyze_pc_samples command.
Compiling and Binding Programs

add_entry_names
Finds all the entry points defined in an object module (or object library) and creates
links to the object modules that contain those entry points.
add_library_path
Adds a path name to the list of directories that the operating system searches to
find objects.

add_profile
Adds profile information from two profile data files, accumulating the sum in the
second profile data file. This command is useful when multiple runs of the same
program are required to meter or test a program fully.
assemble
Translates an assembly language module into machine language.
bind
Creates an executable program module by binding one or more object modules.
c
Compiles a source program in the C language.
cc
Compiles a VOS Standard C source module.
ccp
Produces a fully expanded VOS Standard C source module.
c_preprocess
Expands a C program.
cobol
Compiles a source program in the COBOL language.
delete_library_path
Removes a path name from the list of directories that define a specified library.
display_object_module_info
Extracts information from an object module or module. You can select the
information to be extracted from among the following: source module path name,
compiler, operating system version, user name of the person who compiled the
object module, date and time created or compiled, system name, compiler options
chosen, the entry name, the number of arguments the entry takes, and whether the
entry is a subroutine or a function.
fortran
Compiles a source program in the Fortran language.
link
Creates a link for a file, directory, or another link.
link_dirs
Creates in each directory of a set links to all objects in every other directory in the
set. Use the link_dirs command to make two or more directories equivalent;

typically, to create links in top-level directories on systems with several logical

disks.
list_library_paths
Displays a list of directories that define libraries for the current process.
pascal
Compiles a source program in the Pascal language.
pl1
Compiles a source program in the PL/I language.
preprocess_file
Creates an output text file by copying input from an input text file into the output
text file, based on preprocessor statements specified in the input text file.
profile
Produces formatted performance information about the execution of a program
module so that it can be displayed.
set_library_paths
Sets the path names of the directories defined as libraries for the current process.
use_message_file
Sets the path name of the message file to be used for your current login session.
You most commonly use a new message file when binding and executing a
program that requires messages not in the standard system message file.
Debugging Programs
break_process
Signals a break to a process or set of processes, suspending execution.
debug
Calls the debugger, either from command level or from break level.
display_error
Displays the text of an error message identified by a particular error code.
display_line
Displays information about a set of files you specify.
display_program_module
Displays information about the authorship, history, size, and structure of a program
module.

dump_file
Dumps the contents of a file for debugging purposes, or dumps the contents of an
index to a file. The command dumps the contents of the file in both hexadecimal
and ASCII, with the ASCII text in the rightmost column.
dump_record
Dumps one or more records in a fixed, sequential, relative, or stream file.
dump_tape
Dumps files from a tape.
mp_debug
Calls the multiprocess debugger to debug one or more processes in the current
network.
set_alignment_fault_mode
Stops a user program when an alignment fault occurs.
start_logging
Starts logging the I/O traffic through a port to a log file or I/O device.
start_process
Creates and starts a process.
stop_logging
Stops logging the I/O traffic through a port. Use this command in conjunction with
the start_logging command.
stop_process
Stops a process or set of processes.
where_command
Finds out the type of a given command and the full path name of a program module
or command macro. The command uses your process’s command library path
names to locate the command.
where_path
Finds out the location of an object specified by a path name. When the path name
includes a link, the command displays the ultimate target of the path name,
whether the target exists, and the name of the module containing the target. When
the path name does not include a link, the command displays the full form of the
specified path name.
who_locked
Displays the names of the processes and their owners that currently have locked
a given file or device.

Executing Programs
create_data_object
Creates an object module of a specified size, to be used by processes that share
virtual memory.
create_deleted_record_index
Creates a list of reusable locations in a file.
create_index
Creates an index to a file.
create_record_index
Creates an index used to map records into a file and reuses space made available
by deletions. The command assigns a number to each record written to the file. The
numbers ascend sequentially, beginning with 1. Once the index is created, it is
updated for the life of the file.
delete_index
Deletes a set of indexes to a file.
enforce_region_locks
Turns mandatory region locking on or off for one or more stream files.
get_external_variable
Displays the value of an external static variable within a program module.
handle_sig_dfl
Changes the default action of certain POSIX.1 signals.
set_cpu_time_limit
Sets the upper bound on the amount of central processor time a process can
consume before it is stopped.
set_external_variable
Sets the external static variable within a program module to a specified value.
set_file_allocation
Sets the number of additional disk blocks that the operating system allocates for a
file each time the file needs more disk space.
set_implicit_locking
Turns implicit locking on or off for a file or files. When the state is on, the file system
overrides an attempt to open the file with a different locking specification.
set_index_flags
Turns automatic update of file indexes on or off.

set_owner_access
set_pipe_file
Turns on the pipe file attribute on a file. This attribute cannot be turned off.
set_priority
Sets the execution priority for one or more processes. The process name identifies
the process (among several processes running with a given user name) for which
priority is to be set.
sleep
Puts a process to sleep for a specified period, after which the operating system
reactivates the process. The sleeping process is the process that issues the
command.
sort
Sorts the records in one or more ASCII text files and merges the sorted files with a
set of presorted files, using collating sequences and sort keys you give either in the
command or in a sort control file.
Writing Programs
edit
Calls the screen editor. This command puts your process at editor request level.
emacs
Invokes the text editor. After you invoke the emacs command, your process is at
editor request level.
Administering Systems
list_process_cmd_limits
Lists the initial and maximum totals for the heap, stack, and space limits for
commands executed by an existing process.
update_process_cmd_limits
Changes the heap, stack, and space limits for an existing process or set of
processes.

Tape Processing
attach_port
Creates and names an I/O port and attaches it to a file or I/O device you specify.
cancel_device_reservation
Cancels a reservation of a device. (Devices are usually reserved for the execution
of a batch process).
create_tape_volumes
Initializes one or more tapes.
copy_tape
Makes a logical copy of all supported tape formats.
detach_port
Detaches an attached port from a file or I/O device.
dismount_tape
Dismounts a magnetic tape mounted on the tape drive connected to a specified
port. The command unloads the tape reel and sends a message to the operator.
display_device_info
display_tape_params
Displays the initial default values of the tape processing parameters that the tape
facility uses when you process a tape volume.
dump_tape
Dumps files from a tape.
list_devices
list_port_attachments
Lists information about a set of ports in your process.
list_save_tape
Lists the contents of a save tape.
list_tape
Lists the contents of a labeled tape volume.
mount_tape
Mounts a tape volume on the tape drive connected to a port. Uses the
attach_port command to attach an I/O port to the tape drive before you mount
the tape.

move_device_reservation
Moves a device reservation from the current process to another process. Uses this
command in conjunction with the reserve_device command.
position_tape
Positions the tape mounted on the tape drive connected to an I/O port.
read_tape
Reads magnetic tape files to disk files in your directory hierarchy.
reserve_device
Reserves a device for use by your process. While you have a device reserved for
a process, no other process can use the device.
set_second_tape
Designates a magnetic tape drive the tape facility is to use as a second tape drive
when processing multivolume tape files, such as during full system backups.
set_tape_defaults
Sets the default values of the tape processing parameters that the operating
system uses when you process a tape volume on the tape drive connected to a
given port.
set_tape_drive_params
Sets the tape drive parameters, overriding the defaults drive attributes of the tape
drive attached to a given port, for the duration of the port attachment.
set_tape_file_params
Sets the tape file parameters to override the default tape parameters while the tape
file is open.
set_tape_mount_params
Determines the tape mount parameters that override the default mount attributes
of the mount_tape command for the duration of the mount.
write_tape
Writes a file or files to the tape volume on the tape drive connected to a given port.

Terminal Management
display_terminal_parameters
Displays the current values of parameters for your terminal. The parameters
displayed are those set by the set_terminal_parameters command.
list_terminal_types
Lists the terminal types for which default parameter values are defined.
set_ready
Sets the form of the prompting message the operating system displays on your
terminal when it returns your process to command level.
Sets the terminal parameters for your terminal.

Appendix B
Halting Program Execution B-
This appendix describes how to halt the execution of a program (an internal command,
a command macro, or a user program), and the selection of responses you have
available once you do so.
Break Level
The operating system suspends the execution of your program when you issue a
<CTRL><BREAK> request by pressing the <CTRL> and <BREAK> keys simultaneously on your
terminal. After you issue the <CTRL><BREAK> request, your process is at break level. (Note
also that some program errors can put a process at break level.) The operating system
indicates that you are at break level by displaying the following message on your
screen:
BREAK
Request? (stop, continue, debug, keep, login, re-enter)
At break level, you can issue only six commands. They are briefly described as follows:
• The stop command tells the operating system to terminate the program
abnormally, discarding all current command macros, and to return your process to
command level.
• The continue command tells the operating system to resume processing as if the
interruption had not occurred.
• The debug command invokes the symbolic debugger, allowing you to examine
your program and set breakpoints. You can restart the program from the debugger
or terminate it.
• The keep command saves an interrupted executable image of the program in a file
that can be debugged later.
• The login command creates a new login process for you, as a subprocess of the
current process.
• The re-enter command returns control to the interrupted program at a
predetermined execution point.
Halting Program Execution B-1

Break-Level Command Descriptions
The four of these commands you use most commonly (stop, continue, keep, and
re-enter) are described in the next section. For descriptions of the debug and
login commands, see the VOS Commands Reference Manual (R098).
When the execution of a program terminates, normally or abnormally, all of the files it
opened are closed, all of the locks that it locked are unlocked, all of the events it
attached are detached, and all of the ports it attached are detached.
The circumstances in which issuing the <CTRL><BREAK> request does not put your process
at break level are:
• when your process is in the display form of a command

• when your process is in a program that has special break processing, such as
Emacs or Word Processing Editor
• when your process is at command level
• when the set_terminal_parameters command has been used to set your
terminal so that it ignores a <CTRL><BREAK> request. Note that when you log in, breaks
are disabled until your startup command macro completes execution, or until it
specifically enables breaks with the set_terminal_parameters command.

This section describes the four break-level commands you use most frequently:
• stop or s
• continue or c
• keep or k
• re-enter or r
The stop Command

The stop command abnormally ends execution of an interrupted program. The
operating system discards all current command macros and abnormally terminates the
program.
You can issue this command only when your process is at break level.
The continue Command

The continue command continues execution of an interrupted program as if it had not
been interrupted. The only exception is that if a nonrecoverable error caused the
interruption, the program cannot be continued. In this case, if you issue a continue
command, the operating system displays an error message and your process remains
at break level.
B-2 VOS Commands User’s Guide (R089)

You can issue this command only when your process is at break level.
The keep Command

The keep command stores the executable image of an interrupted program in a file in
the file system. The operating system creates a file in your current directory to contain
the executable image. The file has the same name as the interrupted program module
except that the suffix is changed from .pm to .kp.
You can issue this command only when your process is at break level. The command
is valid only after execution of a program has been suspended. You cannot later restart
the stored image, but you can examine the values of the program’s variables and trace
the stack using the symbolic debugger.
The re-enter Command

The re-enter command resumes execution at a predetermined point of an
interrupted program. The exceptions are that if a nonrecoverable error caused the
interruption, or if the program has not been prepared for re-entry, it cannot be
re-entered. If you issue a re-enter command in this case, the operating system
displays an error message and your process remains at break level.
A program enables the re-enter response by enabling an on-unit for the re-enter
condition.
You can issue this command only when your process is at break level. The command
is valid only after the operating system has suspended execution of a program.
Halting Program Execution B-3

B-4 VOS Commands User’s Guide (R089)

Appendix C
Command Function Reference C-
This appendix alphabetically lists and describes in detail all of the available command
functions. The command functions are shown in the following list.
(Page 1 of 2)
(abs) (end_of_file) (min)
(access) (exists) (mod)
(after) (file_info) (module_info)
(ask) (floor) (module_name)
(before) (given) (object_name)
(break) (group_name) (online)
(byte) (has_access) (path_name)
(calc) (hexadecimal) (person_name)
(ceil) (home_dir) (process_dir)
(command_status) (index) (process_info)
(concat) (iso_date) (process_type)
(contents) (iso_date_time) (quote)
(copy) (language_name) (rank)
(count) (length) (referencing_dir)
(current_dir) (lock_type) (reverse)
(current_module) (locked) (rtrim)
(date) (ltrim) (search)
(date_time) (master_disk) (software_purchased)
(decimal) (max) (string)
(directory_name) (message) (substitute)
Command Function Reference C-1

Command Function Reference
(Page 2 of 2)
(substr) (time) (unquote)
(system_name) (translate) (user_name)
(terminal_info) (trunc) (verify)
(terminal_name) (unique_string) (where_path)
The following table shows the meaning of symbols used in this appendix to show the
syntax of command functions.
Symbol Meaning
S, S1, S2, ..., Sn, R a character string
C a character or set of characters
I an integer
N, N1, N2, ..., Nn a number
A character string is an ordered set of characters. Positions in a character string are

counted starting with the leftmost character. A substring is a string of any length that
occurs within a longer string. An initial substring is a substring whose first character is
also the first character in the containing string. Similarly, a final substring is a substring
whose last character is also the last character in the containing string. For example, if
S is the character string abcdef, then a and abcd are two initial substrings of S;
likewise, def and ef are two final substrings of S.
You must enclose character string arguments within apostrophes if the string contains
one or more spaces, semicolons, or parentheses. If you need an apostrophe character
within a character string, type two apostrophes (''). See ‘‘Entering Character-String
Values’’ in Chapter 2 for additional information about character strings.
Note that many of the examples of command functions in this appendix make the
following assumptions:
• The current system is %s1.

• The current module is #m2 (path name %s1#m2).
• The current master disk is #d01 (path name %s1#d01).
• The current user is Smith in the group Sales (user name Smith.Sales).
• The current directory is %s1#d01>Sales>Smith (the current user’s home
directory).
C-2 VOS Commands User’s Guide (R089)

(abs N)
Returns the absolute value of N.
Example
Command Function Returned Value
(abs -2) 2
(access path_name [user_name])

Returns a code specifying the access rights of a user to the object specified by
path_name. If you specify a value for user_name, it must be of the form
person_name.group_name (for example, Smith.Sales). If you omit the user
name, the access rights returned are your own.
The possible codes the (access) command function returns and their corresponding
meanings for files and directories are as follows:
Directories Files
m for modify w for write

s for status r for read
n for null e for execute
n for null
If none of the access rights defined for the object specified by path_name apply to the
user specified by user_name, the (access) command function returns the code
u (for undefined), which is effectively null access.

If the object specified by path_name does not exist, the returned value is n. Also, if the
value for user_name does not specify a particular user by having the form
person_name.group_name, the returned value is n.
Example
(access %s#d01>Sales>Smith Smith.Sales) m
The user Smith.Sales has modify access rights to his or her home directory.
(after S1 S2)
Returns the final substring of S1 that follows the substring S2.
Example
(after aabbcc.ddeeff c.d) deeff
(ask [prompt [response_qualifier]][-no_echo])

Returns a user-supplied input string. Writes the string specified by prompt and any
string specified by response_qualifier to the terminal_output port (with no
trailing new line). Then, reads the user-supplied response string from the terminal
port and displays it on a new line.
For example, the command function (ask 'Do you want to delete x?') first
displays the prompt Do you want to delete x?. On the same line you could
respond by entering yes. The value of the function is therefore yes. Since no value for
response_qualifier is specified, you could respond I doubt it. The value of
the function would then be I doubt it.
If the string you specify for prompt contains spaces, semicolons, or parentheses that
are not part of a command function, the string must be enclosed in apostrophes ('). If
you omit a value for prompt, the null string is written to the terminal_output port.
You can specify a string value for response_qualifier to restrict the type of
response the command function will accept.

To specify that the response must be one of a particular set of responses, each element
of response_qualifier must have the form:
(S1[S2[S3] ...])=R
In this case, you must enclose the entire response_qualifier string in apostrophes
('), and separate each Sn from the next with a comma. If you specify any Sn value as
a response, the command function returns R. For example, to restrict the response
allowed to either yes or no, the value of response_qualifier might be:
'(yes,y)=yes (no,n)=no'
If the response is yes or y, the returned value is yes; if the response is no or n, the
returned value is no.
To specify that the response must have a particular data type, the value for
response_qualifier can be any of the following:
date_time
module_name
device_name
system_name
name
number
pathname [suffix]
user_name
In any of these cases, ask displays the string specified by prompt and a form of the
string specified by response_qualifier; the response entered must be of the type
specified, or an error message results.
If you select the -no_echo option, terminal input is not echoed to the display screen
and the response to the prompt is suppressed.
Example
Consider this form of the (ask) command function:
(ask 'Do you want to delete x?' '(yes,y)=yes (no,n)=no')
The prompt displayed is Do you want to delete x? (yes, no). If the response
is yes or y, the returned value is yes; if the response is no or n, the returned value is
no.
The value of (ask 'What is your name?' name) might be John.

(before S1 S2)
Returns the initial substring of S1 that precedes the substring S2.
Example
(before aabbcc.ddeeff c.d) aabbc
(break S C)
Returns the length of the initial substring of S that precedes the first instance in S of any
character in the set C.
Example
(break aabbcc.ddeeff ',.;:') 6
(byte I)
Returns the ASCII character that corresponds to the integer I in the ASCII collating
sequence. The (byte) command function is the inverse of the (rank) command
function.
Example
(byte 97) a
(calc expression)
Returns the value that results from the command processor’s evaluation of the
specified expression.
An expression is a series of one or more operands and zero or more operators that can
be evaluated. Operands are the terms, or elements, of the expression to which the
operators are applied. An operand can be a character string or a number (a number is
any string that can be converted to a number). Operators are symbols representing the
actions performed on the operands. An infix operator is written between two operands.
A prefix operator is written in front of an operand.

The expression can be an arithmetic, logical, or string expression. An arithmetic

expression contains an arithmetic operator and operands that can be evaluated and
reduced to a single numeric value. A logical expression contains a logical operator and
operands that can be evaluated and reduced to either 0 when the expression is false
or 1 when it is true. A string expression contains the string operator (||) and operands
that can be evaluated and reduced to a single character string value.
Table C-1 shows the operators that an expression can contain in order of decreasing
precedence. Precedence is the order in which the operators in an expression are
processed; operators with higher precedence are processed before operators with
lower precedence.
Table C-1 also shows which operators can be used in arithmetic, logical, and string
expressions. Note that the operators on level 6 are categorized only as logical
operators. These operators are used with arithmetic and logical operands, yet the
expressions are logical since the result is always either 0 or 1.
Table C-1. Arithmetic, Logical, and String Expression Operators (Page 1 of 2)
Precedence Symbol Meaning Arithmetic Logical String
Level 1 ** exponentiation Y N N
Level 2 + positive (prefix) Y N N
- negative (prefix) Y N N
^ not N Y N
Level 3 * multiplication Y N N
/ division Y N N
Level 4 + addition (infix) Y N N
- subtraction (infix) Y N N
Level 5 || concatenation N N Y
Level 6 = equal to N Y N
^= not equal to N Y N
> greater than N Y N
< less than N Y N
>= greater than or equal to Y N
<= less than or equal to N Y N
Level 7 & and N Y N

Table C-1. Arithmetic, Logical, and String Expression Operators (Page 2 of 2)
Precedence Symbol Meaning Arithmetic Logical String
Level 8 | or N Y N
Note that the solid vertical bars that represent the concatenation operator and the or
operator appear as broken vertical bars on some terminals and keyboards.
The arithmetic operations are performed with floating point arithmetic to a precision of
15 decimal digits. When two terms are compared, they are converted to numbers if
possible. If both terms cannot be converted to numbers, they are compared as
character strings.
All calculations and conversions are performed by PL/I operators. See the VOS PL/I
Language Manual (R009) for the evaluation and conversion rules.
NOTE
If you want(calc)to evaluate two operands and a string
operator as a string expression when(calc)would
otherwise evaluate them as an arithmetic or logical
expression, enclose the operands using the(quote)
command function. For example:
(calc (quote 1) || (quote 2))
Similarly, in a logical or string expression, if you want to use one or more characters in
an operand that (calc) would otherwise interpret as an operator, give the operand as
an argument to the (quote) command function. For example:
(calc (quote *) < (quote /))
Evaluation of operators is from left to right, except for exponentiation and prefix
operators, which are evaluated from right to left. For example, note that the value of the
following expression differs when it is evaluated from right to left instead of left to right
(division and multiplication have equal precedence).
Expression Order of Evaluation Value
12 / 3 * 4 left to right 16
12 / 3 * 4 right to left 1

When you write an expression, observe the following rules:
• You must put spaces before and after the infix operators so that the operating
system can distinguish between your use of the symbols as operators and your use
of them for other purposes.
• You can use parentheses to change the order in which operators are evaluated.
When using parentheses to associate terms, you must enclose each parenthesis
in apostrophes ('). Put a space before the beginning apostrophe and after the
ending apostrophe that enclose an opening or closing parenthesis.
Examples
In the following two examples of the(calc)command function, note how the result
differs when parentheses are used to alter the precedence of multiplication over
addition.
(calc 3 + 4 * 7) 31
(calc '(' 3 + 4 ')' * 7) 49
The following five examples illustrate the use of(calc)in an expression in a command
macro:
&set a (calc (length &file&) - 4)
&set a (calc '(' 2 + 2 ')' / '(' 3 + 2 ')')
&set a '(' 2 + 2 ')' / '(' 3 + 2 ')'
&set count &count& + 1

&if &count& > 5
&then &goto exit
&begin_parameters
file pathname:pathname,required
&end_parameters
&if (exists &file&)
&then !display_file &file&
Note that &set statements imply(calc); (calc)is used explicitly in some of the
preceding examples for clarity. For more information about the &set macro statement,
see Appendix D.

(ceil N)
Returns the smallest integer greater than or equal to N.
Examples
(ceil 1.5) 2
(ceil -1.5) -1
(command_status)
Returns the current value of the process variable called command_status. When a
command begins to execute, the operating system sets the value of the
command_status variable to 0. If the command executes normally without errors, the
value does not change; otherwise, it is set to the value of the system status code
passed by the most recently executed command to the system service subroutine
s$error or s$stop_program.
Example
The following illustrates the use of(command_status)in a command macro:
&then &return
(concat S1 ...Sn)
Returns the strings S1 through Sn combined into one string with all spaces between
the components removed.
Example
(concat aabbcc . ddeeff) aabbcc.ddeeff

(contents path_name [line_number][open_status])

Returns the records of the file specified by path_name, with each record separated
from the next by a space. The value of path_name can be a relative path name. The
maximum record length of the specified file cannot exceed 300 characters. The
argument line_number is an option to specify the number of the line you want to
display.
The value of open_status can be either -hold or -close. This argument can be
used only within a command macro. The -hold option keeps the file open until the
command macro terminates or until the macro processor encounters the -close
option.
Examples
These examples use the file >Sales>Smith>reminders, which contains these two
lines:
1. Write the sales report.

2. Hire a temporary co-op.
(contents >Sales>Smith>reminders) 1. Write the sales report.

2. Hire a temporary co-op.
(contents >Sales>Smith>reminders 2) 2. Hire a temporary co-op.
(copy S I)
Returns the string S, copied I times. The integer I can be expanded as a binary, octal,
decimal, or hexadecimal integer.
Example
(copy ba 4) babababa
(count S C)
Returns the length of the longest initial substring of S consisting entirely of characters
in the set C.

Example
(count aabbcc.ddeeff af) 2
(current_dir)
Returns the full path name of your current directory.
Examples
(current_dir) %s1#d01>Sales>Smith
The following example illustrates the use of (current_dir) in a command macro.
&begin_parameters
path_source:pathname,='(current_dir)'
&end_parameters
(current_module)
Returns the full module name of your current module.
Example
(current_module) %s1#m2
(date [date_string][-long][-standard])
Returns a date. The date is in the form yy-mm-dd, unless you give the -long
argument. With -long, the date is in the form month day, year. For example, if the
value of (date) is 01-06-09, the value of (date -long) would
be June~9,~2001.
With -standard, the (date) command function returns a date, and accepts a
date_string argument formed in accordance with the date and time values in the
language definition for the process language. The date_string argument represents
a date to be returned. Date strings are described in detail in Appendix G. If you give no

value for this argument, the value returned is the current date. The form of the
date_string argument is as follows:
[coming] [absolute_date] [relative_terms]
If you specify the -standard argument, you can specify coming in your process
language; for example, if your process language is Italian, the term might be
prossimo.
Examples
These examples of the (date) command function assume that the current date is
Monday, May 28, 2001.
(date sun) 01-05-27
(date coming sun) 01-06-03
(date sun +1 wk) 01-06-03
(date coming 6/1) 01-06-01
(date june 2) 01-06-02
(date fri) 01-06-01
(date fri +1 wk) 01-06-08
(date_time [date_time_string][-long][-standard])
Returns a date and time. The value is in the form yy-mm-dd hh:mm:ss. With -long,
the date-time value is in the form weekday, month day, year hh:mm:ss am/pm
time_zone. For example, if the value of (date_time) is 01-06-09 15:25:45, the
value of (date_time -long) would be Saturday, June 9, 2001 3:25 pm est.
With -standard, the (date_time) command function returns a date, and accepts a
date_time_string argument formed in accordance with the date and time values in
the language definition for the process language. Date/time strings are described in
detail in Appendix G. If you give no value for date_time_string, the returned value
is the current date and time.
The form of the date_time_string argument is as follows:
[coming] [absolute_date] [absolute_time]

[time_zone] [relative_terms]

prossimo.
Examples
These examples of the (date_time) command function assume that the current date
and time are Monday, May 28, 2001, at two o’clock in the afternoon.
(date_time) 01-05-28 14:00:00
(date_time -long) Monday, May 28, 2001 2:00 pm est
(date_time coming 6/1) 01-06-01 00:00:00
(date_time june 2 10am) 01-06-02 10:00:00
(date_time +5 days +1 wk) 01-06-09 00:00:00
(date_time thu 12pm) 01-05-31 12:00:00
(date_time 6/27 +1 yr -long) Thursday, June 27, 2001 12:00 am est
The following examples show the (date_time) command function used in a

command macro:
&set_string date (substr (date_time) 4 2)(substr (date_time) 7 2)
&set_string day_of_week (before (date_time -long) ',')

(decimal I)
Returns the value of I expressed as a decimal integer. The integer I can be expressed
as a binary, octal, decimal, or hexadecimal integer.
Examples
(decimal -1101b) -13
(decimal -15o) -13
(decimal -15O) -13
(decimal -13d) -13
(decimal -dx) -13
(directory_name path_name)
Returns the full path name of the directory containing the object specified by
path_name. The input path name can be a relative path name.
Example
(directory_name %s1#d01>Sales>Smith) %s1#d01>Sales
(end_of_file path_name)
Returns the value 1 if the last execution of (contents) on a file held open in a macro
returned e$end_of_file; otherwise, the returned value is 0. If the file specified as
path_name is not a held file, or if the function is invoked from outside a command
macro, an error occurs.
(exists path_name [object_type][chase_code])

Returns the value 1 if the object specified by path_name exists, and you have status
access to its containing directory, or non-null access to the object itself, and 0
otherwise. For example, the value of (exists %s1#d01>Sales) is 1 if the object
exists and you have appropriate access, and 0 if it does not.
You can meet either access requirement if you have non-null access to an object but
no access to any of its containing directories. Inquiries about any of the containing
directories would return 0, while inquires about the object would return 1.

The path_name argument can be a star name. The value for the object_type
argument can be -file, -device, -directory, or -link. If you omit a value for
object_type, the operating system looks for all non-device types.
The value for chase_code can be either -chase or -no_chase. This argument
controls whether the operating system chases a link to its ultimate target. If you omit
chase_code, the operating system uses -chase, unless you specify -link, in which
case -no_chase is used.
If you specify a star name as the value for path_name, you must specify -no_chase
for chase_code.
You cannot use both -link for object_type and -chase for chase_code in the
same command function, since the command function cannot look for a link and chase
it at the same time. Therefore, if you specify -link, you must specify -no_chase.
(file_info path_name key)

Returns various kinds of information about the file specified by path_name, depending
on the value of key. Table shows the allowed values for key and the information
returned by each value.
Table C-2. Information Returned by the (file_info) Command Function
Key Returned Value
author The name of the file’s author.
blocks_used The size of the file.
date_created The date the file was created.
date_modified The date the file was last modified.
date_used The date the file was last used. Returns the
null string if there is no last-used date.
date_saved The date the file was last saved. Returns the
null string if there is no last-saved date.
expiration_date The date the file expires. Returns the null

string if there is no expiration date.
last_record The last record number in a file with fixed or

relative file organization. Returns the null
string for all other file organizations.
organization The type of file organization.
record_size The maximum record size of the file. Returns the

null string if there is no maximum record size.

(floor N)
Returns the largest integer less than or equal to N.
Examples
(floor 1.5) 1
(floor -1.5) -2
(given parameter)
Returns the value 1 if the specified command macro parameter was supplied a value
when the current command macro was issued, and 0 otherwise.
This command function can be used only in command macros.
Example
The value of (given source) is 1 when an argument was supplied that corresponds
to the command macro parameter source, and 0 otherwise.
(group_name)
Returns the name of your current group.
Example
(group_name) Sales
(has_access path_name access_code [user_name])

Returns the value 1 if the user specified by user_name has at least the access rights
specified by access_code to the object specified by path_name. Otherwise, the
returned value is 0.
If the object specified by path_name does not exist, the returned value is 0.
If you specify a value for user_name, it must be of the form

person_name.group_name. If you omit the user name, the access rights returned
are your own.

The value you specify for access_code must be appropriate for the type of object you
specify for path_name. The valid codes you can specify for access_code and their
corresponding meanings for files and directories are as follows:
Directories Files
m for modify w for write

s for status r for read
e for execute
For both directories and files, the code n signifies null access rights. However, if you
specify n as the value for access_code, the value the command function returns is
always 1 since all users have at least null access to every object in the system.
Example
(has_access %s#d01>Sales>Smith s Smith.Sales) 1
(hexadecimal I)
Returns the value of I expressed as a hexadecimal integer. The integer I can be
Examples
(hexadecimal 1101b) 0Dx
(hexadecimal 15o) 0Dx
(hexadecimal 13d) 0Dx
(hexadecimal 13) 0Dx
(hexadecimal dx) 0Dx

(home_dir)
Returns the full path name of your home directory.
Example
(home_dir) %s1#d01>Sales>Smith
In a command macro, this function might be used in the following command line:
!line_edit (home_dir)>abbreviations
(index S1 S2)
Returns the position in the string S1 of the first character in the substring S2. If S2 is
not a substring of S1, the returned value is 0.
Example
(index aabbcc.ddeeff .) 7
(iso_date [date_string][-long][-standard])
Returns a year. The date is in the form yyyy-mm-dd, unless you give the -long
argument. With -long, the date is in the form month day, year. For example, if the
value of (iso_date) is 01-06-09, the value of (iso_date -long) would be
June 9, 2001.
With -standard, the (iso_date) command function returns a date, and accepts a
date_string argument formed in accordance with the date and time values in the
language definition for the process language. The date_string argument represents
a date to be returned. Date strings are described in detail in Appendix G. If you give no
value for this argument, the value returned is the current date. The form of the
date_string argument is as follows:
[coming] [absolute_date] [relative_terms]
prossimo.

Examples
These examples of the (iso_date) command function assume that the current date
is Monday, June 18, 2001.
(iso_date sun) 2001-06-17
(iso_date coming sun) 2001-06-24
(iso_date sun +1 wk) 2001-06-24
(iso_date coming 6/1) 2002-06-01
(iso_date june 2) 2001-06-02
(iso_date fri) 2001-06-22
(iso_date fri +1 wk) 2001-06-29
(iso_date_time [date_time_string][-long][-standard])
Returns a date and time. The value is in the form yyyy-mm-dd hh:mm:ss. With
-long, the date-time value is in the form weekday, month day, year hh:mm:ss
am/pm time_zone. For example, if the value of (iso_date_time) is 01-06-09
15:25:45, the value of (iso_date_time -long) would be Tuesday, June 9,
2001 3:25 pm est.
With -standard, the (iso_date_time) command function returns a date, and

accepts a date_time_string argument formed in accordance with the date and
time values in the language definition for the process language. Date/time strings are
described in detail in Appendix G. If you give no value for date_time_string, the
returned value is the current date and time.
The form of the date_time_string argument is as follows:
[coming] [absolute_date] [absolute_time]

[time_zone] [relative_terms]
prossimo.

Examples
These examples of the(iso_date_time) command function assume that the current

date and time are Monday, June 18, 2001, at two o’clock in the afternoon.
(iso_date_time) 2001-06-18 14:00:00
(iso_date_time -long) Monday, June 18, 2001 2:00 pm est
(iso_date_time coming 6/1) 2002-06-01 00:00:00
(iso_date_time june 2 10am) 2001-06-02 10:00:00
(iso_date_time +5 days +1 wk) 2001-06-30 00:00:00
(iso_date_time thu 12pm) 2001-06-14 12:00:00
(iso_date_time 6/27 +1 yr -long) Thursday, June 27, 2002 12:00 am est
The following examples show the (iso_date_time) command function used in a

command macro:
&set_string date (substr (iso_date_time) 4 2)(

substr (iso_date_time) 7 2)
&set_string day_of_week (before (iso_date_time -long) ',')
(language_name)
Returns the name of the default process language.
Example
(language_name) italiano
(length [S])
Returns the length of the string S. If S contains spaces, the (length) command
function treats S as a single string. If you omit S, the value of (length) is 0.

Examples
(length aabbcc.ddeeff) 13
(length abc def) 7
The following example illustrates the use of (length) in a command macro:
&if (length &message&) = 0

&then &return
(lock_type path_name)
Returns the type of lock on the file specified by path_name. The possible values
returned are as follows:
no_lock
read_lock
write_lock
implicit_lock
record_lock
transaction_file
dirty_readers
region_locking
(locked path_name)
Returns the value 1 if the file specified by path_name is locked, and 0 if it is not locked.
(ltrim S [C])
Returns the longest final substring of S whose first character is not in the set C. If you
omit C, the operating system trims leading spaces from S.
Example
(ltrim aabbcc.ddeeff af) bbcc.ddeeff

(master_disk [module_name])
Returns the full path name of the master disk directory on the module specified by
module_name. If you omit a value for module_name, the command function uses the
current module. The following are examples of valid input values for module_name:
%s1#m2
#m2
m2
Example
(master_disk m2) %s1#d01
(max N1 N2)
Returns the larger of the two values specified in the arguments N1 and N2.
Example
(max 33 36) 36
(message status_code [S1[S2[S3]]][-number])

Returns the text of the message corresponding to the value specified by
status_code.
The value of the status_code argument can be one of the following:
• an integer specifying a system status code

• the command function (command_status)
• the name of a system status message.
If you specify any of the optional string arguments (S1, S2, and S3), they replace any
parameters defined in the text of the returned message. If there are no parameters
defined in the text of the message, the string arguments are ignored.

Examples
(message e$object_not_found) Object not found.
(message 1434 Smith Sales m2) Smith not registered for group
Sales on module m2.
If you specify the(command_status)function for status_code, the(message)

command function returns the text of the message corresponding to the code returned
by(command_status). Since none of the messages corresponding to codes
returned by(command_status)have parameters, you do not need to specify the
optional string arguments.
(message (command_status)) Object not found.
You can determine the status code number of a message by giving the name
corresponding to a status message (which must begin with e$, m$, r$, or q$) for
status_code and by giving the -number argument. If you omit -number, the
command function returns the text of the message.
(message e$object_not_found -number) 1032
(min N1 N2)
Returns the smaller of the two values specified in the arguments N1 and N2.
Example
(min 30 43) 30

(mod N1 N2)
Returns the remainder of the division of N1 by N2.
Example
(mod 14 4) 2
(module_info key)
Returns information about the current module, depending on the value of key. The
value for the key argument can be system_release, os_release,
cpu_family, or cpu_type. Table C-3 shows the kind of information returned, based
on the value of key.
Table C-3. Information Returned by the (module_info) Command Function
Key Returned Value
cpu_family The value representing the processor family for the current
module. The possible return values are mc68k, i860 or
hppa.
cpu_type The value of the type of processor in the current module.
system_release or The currently installed release of the operating system.

os_release
(module_name module_name)
Returns the full path name of a module specified by module_name. The following are
examples of valid input values for module_name:
%s1#m2
#m2
m2
Example
(module_name #m2) %s1#m2

(object_name path_name [suffix])

Returns the name of the object specified by path_name, with the specified suffix, if
any, appended.
Example
(object_name make_reports .cobol) make_reports.cobol
(online [module_name])
Returns the value 1 if the module specified by module_name is currently online
through the network. Returns 0 if one of the following conditions exist:
• the specified module is not online

• the specified module does not exist
• the current user has no access to the specified module
The current module is always online.
The following are examples of valid input values for module_name:
%s1#m2
#m2
m2
Example
(online #m5) 1
(path_name path_name [suffix])

Returns the full path name of the object specified by path_name, with the specified
suffix, if any, appended.
Example
(path_name make_reports .cobol) %s1#d01>Sales>Smith>make_reports.cobol

(person_name)
Returns your person name.
Example
(person_name) Smith
(process_dir)
Returns the full path name of the process directory of the current process.
Example
(process_dir) %s1#d01>process_dir_dir>pd.20402829.Smith
(process_info key)
Returns various kinds of process-specific information, depending on the value of key.
Table C-4 shows the allowed values for key and the information returned by each
value.
Table C-4. Information Returned by the (process_info) Command Function (Page 1 of 2)
Key Returned Value
cpu_time The amount of time—excluding time for page faults—the

processor has spent running the process’s programs. The units
are 1/65536 seconds.
disk_reads The number of times the process has read data from the disk—
except for page faults—since the process was created.
disk_writes The number of times the process has written data to the disk
since the process was created.
language The name of the language of the current process.
large Returns a 0 for any process runing in an address space. As of

VOS Release 9.0, this value is always 0.
login_time The time that the process logged in.

Table C-4. Information Returned by the (process_info) Command Function (Page 2 of 2)
page_faults The number of page faults the process has taken since it was
created.
page_fault_time The accumulated time the CPU has spent in page faults for the
process. The units are 1/65536 seconds.
priority A number from 0 to 9 giving the priority of the process.
privileged 1 if the process is privileged; 0 otherwise.
process_name The name of the process.
program_name The file name of the currently loaded program module, internal
command, or command macro. In all cases where a command
macro runs a program or internal command,
(process_info) program_name will refer to the .pm or
internal command in preference to the command macro.
If no .pm, .cm, or internal command is executing, the null
string is returned..
sub_process_level The current subprocess level. For a login process (created

from pre-login), the subprocess level is 0; for a subprocess
created from a login process or another subprocess, the level
is the number of subprocesses created.
subsystem The subsystem your process was created under when it

logged in.
(process_type)
Returns the type of the current process. The possible returned values are
interactive, sub_process, and batch.
The value of (process_type) for your login process is interactive when the
process is created from pre-login, and sub_process when you log in a subprocess.
The process type of a started process is batch.
Example
The following example illustrates the use of (process_type) in a command macro:
&if (process_type) = batch

&then &goto batch

(quote S1 ...Sn)
separated from the next by one space, and apostrophes (') added at the beginning and
the end.
If the arguments contain apostrophes, the command processor removes one level of
apostrophes before passing the arguments to the command function.
Examples
quote aa bb) 'aa bb'
(quote ‘aa bb’) ‘aa bb’
(quote aa’’bb) ‘aabb’
(quote ‘aa’’bb’) ‘aa’’bb’
(rank C)
Returns the integer rank in the ASCII collating sequence of the character specified by
C. The command function (rank) is the inverse of the command function (byte).
Example
(rank a) 97
(referencing_dir)
Returns the directory path name of the currently loaded program module or command
macro. If an internal command is executing, the null string is returned.
If no .pm, .cm, or internal command is executing, the null string is returned, an error
message (No program is currently loaded.) is printed, and
command_status is set to e$no_program_loaded (1805).
In all cases where a command macro runs a program, (referencing_dir) refers to

the path name of the .pm.

Example
(referencing_dir) %s2>#d01>Sales>Smith>reports
(reverse S)
Returns the reversed character pattern of the string S.
Example
(reverse loot) tool
(rtrim S [C])
Returns the longest initial substring of S whose last character is not in the set C. If you
omit C, the operating system trims trailing spaces from S.
Example
(rtrim aabbcc.ddeeff af) aabbcc.ddee
(search S C)
Returns the leftmost position in the string S that contains a character in the set C. If no
member of C is in S, then the value of this function is 0.
Examples
(search aabbcc.ddeeff .) 7
(search decipher code) 1

(software_purchased software_purchased_bit)
Returns 1 if the product denoted by software_purchased_bit has been
purchased. Returns 0 otherwise.
(string S1... Sn)

separated from the next by one space. You can use this function to combine multiple
arguments into a single character-string argument that would otherwise require an
additional level of apostrophes.
Example
(string aa bb) aa bb
(substitute S1 S2 S3 [-ignore_quotes])
Returns the string that results from locating each occurrence of S2 within S1, then
replacing each occurrence with S3.
The command processor removes one level of apostrophes in the string S1 before
passing it to the substitute command function. In the resulting string, no occurrence
of S2 within a part of S1 enclosed in apostrophes is replaced.
The -ignore_quotes argument causes every occurrence of S2 within S1 to be

replaced regardless of any part of S1 enclosed in apostrophes.
Examples
(substitute 'aabbcc''aabbcc''' 'bb' 'BB') aaBBcc'aabbcc'
(substitute ‘aabbcc’’aabbcc’’’ ‘bb’ ‘BB’ -ignore_quotes) aaBBcc’aaBBcc’

(substr S I1 [I2])
Returns the substring of the string S that begins in position I1 and extends for I2
characters or, if you omit I2, to the end of S.
Example
(substr aabbcc.ddeeff 3 4) bbcc
(system_name)
Returns the name of the current system.
Example
(system_name) s1
(terminal_info key)
Returns various kinds of terminal-specific information, depending on the value of key.
Table C-5 shows the allowed values for key and the information returned by each
value.
Table C-5. Information Returned by (terminal_info) Command Function (Page 1 of 2)
Key Returned Value
baud_rate The speed at which data is transmitted to the terminal.
continue_chars The character(s) displayed to indicate a continued line.
cursor_format The format of the cursor. Possible values are blinking_block,

blinking_underline, steady_block,
steady_underline, and off.
device_type The name of the device driver for this terminal. Possible values are
terminal, window_term, or vterm.
escape_char The escape character.
flow_off_char The character used to stop a stream of output to the terminal.
flow_on_char The character used to resume a stream of output to the terminal.

Table C-5. Information Returned by (terminal_info) Command Function (Page 2 of 2)
line_length The number of characters in a line on the screen.
pause_chars The message displayed on the pause line.
pause_lines The number of lines displayed on the screen before a pause

message.
prompt_chars The message displayed to prompt for terminal input.
screen_size The number of lines displayed on the screen.
tabs The column positions where tabs are set for the terminal.
type The name of the terminal type. Use the list_terminal_types

command to list all possible values of terminal_type.
For more information, see the description the set_terminal_parameters

command in the VOS Commands Reference Manual (R098).
(terminal_name)
Returns the full path name of the login terminal. (This function works only in a login
process.)
For example, the value of (terminal_name) could be %s1#t1.4.
(time[time_string][-long][-standard])
Returns a time. The time is in 24-hour format and is of the form hh:mm:ss, unless you
give the -long argument. With -long, the time is in 12-hour format and is of the form
hh:mm, followed by either am or pm. For example, if the value of(time)is 15:25:45,
then the value of (time -long)would be 3:25 pm.
With -standard, the (time) command function returns a time, and accepts a
time_string argument formed in accordance with the date and time values in the
language definition for the process default language. The time_string argument is
a string that represents a time. Time strings are described in detail in Appendix G. If
you give no value for time_string, the returned value is the current time.
The form of the time_string argument is as follows:
[coming][absolute_time][time_zone][relative_terms]
prossimo.

Examples
These examples of the (time) command function assume that the current time is one
o’clock in the afternoon, Eastern Standard Time.
(time) 13:00:00
(time -long) 1:00 pm
(time +1 hr) 14:00:00
(time 10 pm) 22:00:00
(time coming 10:00 -long) 10:00 am
(time cst) 15:00:00
NOTE
When using the 12-hour time format, you must specify pm
to indicate that the hour is between noon and midnight.
Otherwise, the returned time value is am.
(translate S1 [S2[S3]])
Returns the character string S1 translated according to the character strings S2 and
S3. Each occurrence of an element of S3 in the string S1 is replaced by the element of
S2 corresponding to the same position in S3.
If S3 is longer than S2, spaces are added on the right of S2 until the length of S2 equals
that of S3.
If you omit S3, S3 is assumed to be the ASCII collating sequence.
If you omit both S2 and S3, S2 is assumed to be the list of characters with ranks of 96
through 126 in the ASCII character set, for example, the lower case letters, and S3 is
assumed to be the list of characters with ranks of 64 through 94 in the ASCII character
set, the upper case letters. In this case, the (translate) command function is used
to transpose lowercase to uppercase.
If S1 is the null string, the result is the null string.

Example
(translate aabbcc.ddeeff ABCDEF abcdef) AABBCC.DDEEFF
(trunc N)
Returns the integer part of N.
Examples
(trunc 1.5) 1
(trunc -1.5) -1
(unique_string)
Returns a unique character string.
Example
(unique_string) _aaaaabbbckooxxxx
(unquote S)
Returns the string S with any leading and trailing apostrophes removed and with any
doubled apostrophes within the string reduced to single apostrophes. The command
processor removes one level of apostrophes before passing the argument to the
command function.
Example
(unquote '''aa bb''') aa bb

(user_name)
Returns your current user name.
Example
(user_name) Smith.Sales
(verify S C)
Returns the leftmost position of the character in the string S that is not in the set C. If all
the characters in S are in C, the returned value is 0.
Example
(verify aabbcc.ddeeff af) 3
(where_path path_name [type])

Returns information concerning path_name: its full path name, its object type, or the
path name of the object containing it.
The value for the argument type can be -path_name, -object_type, or

-module_name. If you omit type, the value -path_name is used.
The value of (where_path) is determined as follows:
1. When path_name is a link, the information returned by (where_path) is related

to the ultimate target of the link, rather than to the link itself.
2. When type is -path_name, (where_path) returns the full path name of the
object specified by path_name.
3. When type is -object_type, (where_path) returns the object type of the
object specified by path_name. The object types that can be returned are device
for an I/O device, file for a file, directory for a directory, and link for a link.
4. When type is -module_name, (where_path) returns the name of the system
and module containing the object specified by path_name.

Examples
(where_path smith_memos) %s1#d01>Sales>Smith>smith_memos
(where_path smith_memos -object_type) file
(where_path smith_memos -module_name) %s1#d01


Appendix D
Macro Statement Reference D-
A command macro statement is a statement in the form &keyword that can be

included in a command macro to perform a predefined function. Command macro
statements are valid only in command macros.
NOTE
Command macro statements are often referred to simply
as macro statements.
This appendix alphabetically lists, describes, and provides examples of all command
macro statements, as follows:
&attach_input
&begin_parameters
&break
&continue
&control
&detach_input
&display_line
&display_line_partial
&do
&echo
&end
&end_parameters (including end qualifiers)
&eof
&eval
&goto
&if (including &then and &else)
&label
&mode
&return
&set
&set_string
&while
Macro Statement Reference D-1

Macro Statement Reference
When working with macro statements, note the following:
• You cannot include multiple macro statements on the same line, as you can with
commands. For example, this line can appear in a command macro:
!attach_default_output all_files -append; list;
However, the following line produces an error message:
&begin_parameters; &end_parameters
• Abbreviations that appear in macro statements are not expanded, whether they
appear in the statement itself or in a command function contained in the statement.
Command macros should contain no abbreviations for the following reasons:
– Not all users have the same abbreviations defined. The use of a macro that
contains abbreviations is limited to users who have defined those
abbreviations.
– Using unabbreviated names in a macro makes the macro easier to read and
understand.
D-2 VOS Commands User’s Guide (R089)

&attach_input
&attach_input 0-
The &attach_input statement detaches your default_input port from its current
attachment and attaches it to the current command macro. (It saves the old attachment
of the port.)
Form
&attach_input
Explanation
The &attach_input statement enables a command or program to read the input data
it requires from the command macro file itself. When you attach your default_input
port to the command macro file with the &attach_input statement, you must
anticipate the input needed by each command that follows this statement. Then,
specify the input in the proper sequence on the line or lines that follow.
If the command macro has already attached the default_input port to the macro
file, the operating system disregards another &attach_input command.
The default_input port is reattached to its previous attachment when the command
macro completes execution, or when a &detach_input statement in the macro is
executed.

&attach_input
Example
The following example is a command macro that calls the line editor to replace one
character string in a file with another:
& a command macro that replaces every occurrence of

& the character string passed in as &from& by the
& character string passed in as &to& in the file
& specified for &file&
&
&begin_parameters
file pathname,required
from string,required
to string,required
&end_parameters
&
&attach_input
&
!line_edit &file& -no_backup -mapcase -no_verbose
change * /&from&/&to&/ *
write
quit
&
&detach_input
&return
The command line_edit calls the line editor. The next three lines contain the line
editor requests change, write, and quit. After reading the quit request, the line
editor returns control to the command macro.
Related Information
See the description of the &detach_input statement in this appendix. See
Appendix E for a description of the line editor.

&begin_parameters
&begin_parameters 0-
The &begin_parameters statement begins a macro parameter declaration section.

The final statement in the section must be an &end_parameters statement.
Form
&begin_parameters
Explanation
The operating system interprets all lines in a command macro file between a
&begin_parameters statement and an &end_parameters statement as
parameter declarations. You can include only one &begin_parameters statement in
a command macro, and it must be the first line of the macro that is not a comment
(before any executable command).
Example
Two command macro parameters are declared in the following example:
&begin_parameters
source_module source:pathname,required
compiler_options options:unclaimed
&end_parameters
Related Information
See the description of the &end_parameters statement in this appendix, and
‘‘Parameter Declarations’’ in Chapter 7.

&break
&break 0-
The &break statement terminates execution within a &while loop.
Form
&break
Explanation
After the &break statement executes, the command-macro processor breaks out of
the &while loop and resumes execution at the statement immediately following the
&end command marking the end of that &while loop. If you specify a &break
command within nested &while loops, it applies to the innermost loop only. The
command-macro processor ignores any characters between the &break command
and the end of the line.
Example
The following example uses the &break statement to terminate execution of the
&while loop if count of 2 is encountered:
&set i 0
&while &i& < 4
display_line i = &i&
&if &i& = 2 &then &do
&display_line BREAK HERE
&break
&end
&set i &i& + 1
&end
Related Information
See the description of the &continue and &while statements in this appendix.

&continue
&continue 0-
The &continue statement skips the remaining portion of the current iteration of the
&while loop and transfers program control to the loop-continuation location, where the
controlling expression is evaluated.
Form
&continue
Explanation
After the &continue statement executes within a &while loop, the command-macro
processor jumps to the &while command at the top of the loop to re-evaluate the test
condition defined there. If you specify a &continue command within nested &while
loops, it applies to the innermost loop only. The command-macro processor ignores
any characters between the &continue command and the end of the line.
Example
The following example uses the &continue statement to skip displaying the current
value of &x& unless it is greater than or equal to 10:
&set x 1
&while &x& < 20
&set x &x& + 1
&if &x& < 10
&then &continue
&display_line &x& is between 10 and 20.
&end
Related Information
See the description of the &while statement in this appendix.

&control
&control 0-
The &control statement turns the macro processor on or off.
Form
&control switch
The value of switch can be on or off. Initially, control is on and the macro processor
interprets macro statements and variables in the usual way. When you turn control off,
the macro processor gives no special meaning to lines containing ampersands until
you turn control back on.
Explanation
Using the &control statement, you can execute a VOS Word Processing Editor
keystrokes file as a command macro to recover from errors resulting from accidental or
abnormal termination of an editing session. For a description of this procedure, see the
information about keystrokes files in the VOS Word Processing User’s Guide (R006).

&detach_input
&detach_input 0-
The &detach_input statement reattaches the default_input port to the

attachment it had prior to the most recent &attach_input statement in the current
command macro.
Form
&detach_input ¢ no_eof£
eof
Explanation
In the &detach_input statement, the default value of the option is eof. If you select
eof, either explicitly or by default, the command macro returns the status code 1025
(e$end_of_file) to the program or file from which the &detach_input statement
is detaching your default_input port. If you select no_eof, the command macro
returns a status code of 0 and the null string. Some programs to which you might attach
your default_input port do not recognize end-of-file markers; use the no_eof
option when detaching your default_input port from this type of program.
The operating system disregards a &detach_input statement if no &attach_input

statement has been executed in the current command macro.
Related Information
See the description of the &attach_input statement in this appendix.

&display_line
&display_line 0-
The &display_line statement writes the text given in the statement to the current
attachment of the default_output port. The port is normally attached to your
terminal.
Form
&display_line text
The value of text is the text to be displayed.
Explanation
In a &display_line statement, the text can contain command macro variables and
parameters. The operating system replaces any variables and parameters with their
current values before writing the text to the default_output port. Any part of the text
enclosed in apostrophes is displayed literally; if a parameter or variable name appears
in the text within apostrophes, the operating system does not replace the name with the
corresponding value.
The operating system does not replace abbreviations and evaluate command functions
within the specified text.
Examples
Assume that the current value of the parameter &source& is make_reports.cobol.
Consider the following examples of the macro statement &display_line and the
corresponding output:
&display_line &source& displays make_reports.cobol

&display_line ‘&source&’ displays ’&source&’
&display_line &$source& displays ’make_reports.cobol’

&display_line
In contrast, consider the following examples of the display_line command in a

macro and the corresponding output:
!display_line &source& displays make_reports.cobol

!display_line ‘&source&’ displays &source&
!display_line &$source& displays make_reports.cobol

&display_line_partial
&display_line_partial 0-
The &display_line_partial statement writes the text given in the statement to the
current attachment of the default_output port without a trailing carriage return. This
port is normally attached to your terminal.
Form
&display_line_partial text
The value of text is the text to be displayed.
Explanation
In a &display_line_partial statement, the text can contain command macro
variables and parameters. The operating system replaces any variables and
parameters with their current values before writing the text to the default_output
port. Any part of the text enclosed in apostrophes is displayed literally; if a parameter
or variable name appears in the text within apostrophes, the operating system does not
replace the name with the corresponding value.
The operating system does not replace abbreviations and evaluate command functions
in the specified text.
Since &display_line_partial does not write a carriage return at the end of the
output line, you can use this statement to concatenate output to the default_output
port. For example, you can use &display_line_partial to display as one output
line text that is broken up within the command macro.
Example
Suppose that &source_module& has the value make_reports, and that a
command macro contains these statements:
&display_line_partial The program &source_module&

&display_line cannot be found.
The statements produce this display on your terminal:
The program make_reports cannot be found.

&do
&do 0-
The &do statement defines the beginning of a sequence of command-macro processor

statements. The final statement in the sequence must be an &end statement.
Form
&do
command,_statement,_or_input_1
.
.
.
&end
Explanation
The command-macro processor executes the sequence statements inside the &do
group. When the execution of the do-sequence is complete, control is transferred to the
command following the sequence’s &end command. The command-macro processor
ignores any characters between the &do statement and the end of the line.
The maximum nesting depth of any combination of &if statements, &do groups, and
&while loops is 32.

&do
Example
In the following example, if the value of the variable &answer& is add, the macro sets
&a& to the sum of two numbers and displays the result. If the value of &answer& is not
add, it sets &a& to the difference of two numbers and displays the result:
&if &answer& = add

&then &do
&set a &b& + &c&
&display_line b + c = &a&
&end
&else &do
&set a &b& - &c&
&display_line b - c = &a&
&end
Releated Information
See the description of the &end statement in this appendix.

&echo
&echo 0-
The &echo statement controls whether command lines, input lines, and macro
statements contained in the macro are written to the default_output port, which is
normally attached to your terminal.
Form
&echo control_codes
...
The value of control_codes is any combination of one or more keywords from the
following list:
command_lines
no_command_lines
input_lines
no_input_lines
macro_lines
no_macro_lines
Explanation
At times, you may want to see some or all of the lines in a command macro as the
operating system reads and processes them. There are three kinds of lines:
• command lines
• macro lines
• input lines.
These are described in detail in Chapter 7.
At the start of the execution of a command macro, no lines in the macro are displayed
in interactive mode; in batch mode, command lines and input lines are displayed (for
outer level macros only). You can give the &echo statement with one or more control
codes to tell the operating system which lines to display while the macro executes. A
subsequent &echo statement can change the set of lines displayed.

&echo
To display a particular kind of line, use the appropriate control code: command_lines,
input_lines, or macro_lines. To stop displaying a type of line, use the negative
form: no_command_lines, no_input_lines, or no_macro_lines. Using a
combination of positive and negative forms of the control codes, you can define any
subset of the lines to be displayed.
Example
The following statement turns on the display of macro statements and turns off the
display of input lines so that only macro statements are displayed thereafter until the
next &echo statement.
&echo macro_lines no_input_lines

&end
&end 0-
The &end statement defines the end of a sequence of command-macro processor

statements. The beginning statement in the sequence must be a &do or &while
statement.
Form
&end
Explanation
The &end statement closes a &do group or a &while loop. Its action depends on
which of these it is closing. See the descriptions of the &do, &while, and &break
statements for an explanation of the behavior of the &end statement in each case.
Related Information
See the descriptions of the &break, &do, and &while statements in this appendix.

&end_parameters
&end_parameters 0-
The &end_parameters statement terminates a parameter declaration section in a

command macro.
Form
&end_parameters[end_qualifier] [,end_qualifier]...
The value of end_qualifier can be one or more of the following:
exclusive (parameter, parameter, ...)

inclusive (parameter, parameter, ...)
form
noarg
2col
privileged
Explanation
The end qualifiers are keywords that you can use to specify how the macro will accept
parameters and their values, how and when the macro’s display form will be displayed,
and whether execution of the macro will be restricted to privileged users. The following
lists and describes each end qualifier.
exclusive (parameter,parameter, ...)

Indicates that only one of the specified parameters can be given.
inclusive (parameter,parameter, ...)

Indicates that at least one of the specified parameters must be given.
form
Indicates that the display form is always displayed for this macro. Note that a
command macro that specifies form cannot be used in a batch process or a
started process.

&end_parameters
noarg
Tells the macro processor to disregard any input values given to the command
macro. This end qualifier is useful if you want to use only default values; it is also
useful with the display form.
2col
Indicates that the display form is displayed in two-column format.
privileged or priv
Tells the macro processor that only a privileged user can execute this command
macro.
Example
The following parameter declaration section declares three parameters named
source, exec, and test:
&begin_parameters
source source_module:pathname,required
exec switch(-execute),=0
test switch(-checkout),=0
&end_parameters exclusive(-execute,-checkout)
The two switch parameters are defined in the end qualifier as mutually exclusive, so
you cannot specify both -execute and -checkout when you issue the macro.
Related Information
See the description of the &begin_parameters statement in this appendix, and see
‘‘Parameters’’ in Chapter 7.

&eof
&eof 0-
The &eof statement passes an end-of-file status code to the program reading the file.
Form
&eof
Explanation
When a command macro contains an &eof statement and the default_input port
is not attached to the file, then &eof has the same effect as a &return statement.
When a command macro contains an &eof statement and the default_input port
is attached to the file, then the program reading its input from the file is given an
end-of-file status code.
Note that when you run an application that reads input from the terminal, you can type
&eof to signal the end of the input stream.

&eval
&eval 0-
The &eval statement forces evaluation and execution of a specified string.
Form
&eval string
The value of string is a character string that represents a command line or macro
statement.
Explanation
An &eval statement allows multiple variable substitution. For example:
&set_string comment1 This is a comment.

&set_string comment2 &&comment1&&
&eval &display_line &comment2&
With the &eval statement, the last line produces the following output:
This is a comment.
In contrast, without the &eval statement, the last line produces this output:
&comment1&

&eval
The following command-macro processor statements, which affect the flow of control
within a command macro, cannot be specified within the &eval command statement.
Note, however, that you can specify the &goto statement inside an &eval statement.
&begin_parameters
&break
&continue
&do
&else
&end
&end_parameters
&if
&label
&then
&while

&goto
&goto 0-
The &goto statement indicates which line of the command macro is to be executed
next.
Form
&goto label_name
The value of label_name is the name of a label in a &label statement in the current
command macro. You can include macro parameters in label_name so you can
modify the flow of control at the time you issue the macro.
Explanation
A &goto statement tells the operating system to ignore intervening lines in the macro
and execute the line following the given label. This line can be a macro statement or a
command line.
A &label statement defines a location in the macro that can be the target of a &goto
statement. For example:
&goto not_found
...
&label not_found
...
When the command processor reaches the &goto not_found statement, it transfers
control to the line immediately following the &label not_found statement.
A &goto statement can specify the name of a macro parameter or macro variable for
label_name. For example:
&goto &variable_name&
Here, &variable_name& is either the name of a parameter or the name of a variable

whose value is assigned by a &set or &set_string statement before the &goto
statement is executed. This &goto statement transfers control to the line in the macro
following the statement &label value_of_variable.

&goto
The label name in a &label statement, however, must be a constant; it cannot contain
any macro parameters or variables.
The command-macro processor evaluates &goto statements for macro variable

substitutions; therefore, you can use macro variables within &goto statements.
Related Information
See the description of the &label statement in this appendix.

&if
&if 0-
The &if statement controls the order in which the operating system executes
commands and statements in a command macro.
Form
&if expression
&then then_string
[&else else_string]
The expression is a logical expression that the operating system evaluates when it
executes the &if statement. The extent of the expression is defined by the end of the
line or by the keyword &then. When expression is evaluated using the (calc)
command function, the result must be 1 or 0; otherwise, the command macro ends in
an error.
The value of then_string is a command or statement that is executed when the

value of expression is 1. It can be any command that can be invoked when your
process is at command level, or any command macro statement except
&begin_parameters, &end_parameters, and &label. A white space (that is, one
or more spaces or tab characters, or a carriage return) is required before a &then
statement. The &then clause of the &if statement can appear on the same line as the
expression.
In the case of nested &if-&then-&else statements, a line can contain only one &if
statement.
The &else clause of an &if statement is optional. The value of else_string is a

command or statement that is executed when the value of expression is 0. It can be
any command or statement allowed as a then_string. The &else clause of the &if
statement must be on a line by itself.
Explanation
When the operating system executes an &if statement, it first evaluates expression
using the (calc) function. The expression must either be an instance of the (calc)
command function or be an expression that can be evaluated by (calc). The
expression can contain parameters, command functions, and macro variables. The

&if
command processor replaces parameters and variables with their values before
evaluating command functions in the expression.
If one of the operands in expression contains a character that can be used as an

operator (or a string of these characters), the operand must be given as an argument
to the (quote) command function.
The value of expression must be a character string convertible to either the

number 0 or the number 1. For example, 0, 0.0, and 0e0 can be converted to 0.
If the result is 1, the command processor executes then_string. If the result is 0,

then the command processor executes else_string if there is an &else clause;
otherwise, it executes the command or statement following the &then clause. If either
then_string or else_string is the &do or &while statement, then the command
processor executes the whole associated &do group or &while loop.
Ambiguous &if statements could have unpredictable results, and the

command-macro processor flags those ambiguous statements as errors. Errors are
also generated if the command macro ends prematurely (for example, if an &if
statement occurs at the end of the command-macro file without a corresponding &then
statement).
The maximum nesting depth of any combination of &if statements, &do loops and
&while groups, is 32.
Examples
The following statements cause the flow of control in the command macro in which they
appear to go to the statement with the label is_there when the value of
&switch_arg& is 1:
&if &switch_arg&
&then &goto is_there
...
&label is_there
...
The following part of a command macro transfers control to the statement labeled
batch_at_home when your current directory is your home directory and your process
is not interactive:
&if (current_dir) = (home_dir) & (process_type) = 'batch'

&then &goto batch_at_home
...
&label batch_at_home
...

&if
The next example enables (calc) to evaluate the asterisk character as an operand
(comparing its hexadecimal rank with that of the first character in &char&), instead of
as the multiplication operator:
&if (quote *) > &char&

&then &do
.
.
.
&end
Related Information
See the description of the (calc) command function in Appendix C for the definition
of an expression.

&label
&label 0-
The &label statement sets a target for a &goto statement. It is a nonexecutable

statement.
Form
&label label_name
The value of label_name must be a name containing no more than 32 characters.

The characters can be letters, digits, and underline characters. A label name must be
a constant; it cannot contain any macro parameters or variables.
Each label must be unique within a given command macro.
Restrictions
The command-macro processor does not evaluate &label statements for macro
variable substitutions; therefore, you can not use macro variables within &label
statements.
Related Information
See the description of the &goto statement in this appendix.

&mode
&mode 0-
The &mode statement is a switch that controls the behavior of a command macro in the
event of an error. Each mode can be turned on and off by using the appropriate switch
value.
Form
&mode mode_switch
The value of mode_switch is any combination of one or more keywords from the
following list:
abort
no_abort
execute
no_execute
requote
no_requote
Explanation
When the mode is abort, any attempt to run a nonexistent program or command
macro terminates processing of the command macro and returns control to command
level. When the mode is no_abort, control proceeds to the next line of the macro in
the event of an attempt to execute a nonexistent program or command macro. The
error is then diagnosed, and processing continues normally. The default mode is
abort. Note that other errors may still result in abnormal termination of the command
macro, for example, malformed macro statements or unbalanced &if, &then, or
&else statements.
When the mode is execute, the macro processor executes any command lines in the
command macro. When the mode is no_execute, commands are ignored. The
no_execute mode, used in conjunction with the &echo statement, checks command
macro statements for validity without testing or executing the commands. The default
mode is execute.

&mode
When the mode is requote, as the macro processor replaces a variable with its value
it encloses the value within apostrophes. Essentially, each variable is treated as though
it is referenced as &$variable_name&. When the mode is no_requote, the macro
processor does not enclose values within apostrophes. The default mode is
no_requote.

&return
&return 0-
The &return statement terminates the current command macro and returns control to
command level or to the prior (calling) command macro.
Form
&return[command_status]
The value of command_status must be an integer representing a system error status

code, the name of a system error status message, or the command function
(command_status).
Explanation
When the command processor reads a &return statement, it reattaches the
default_input port if the command macro contains an &attach_input statement
but does not contain a corresponding &detach_input statement. It also reattaches
your command_input port to its preceding attachment, and then reads the next
command from there.
If you supply the command_status argument, the command status of the current
process is updated when the macro terminates execution. You can use this option to
determine if a command or program terminated successfully or unsuccessfully.
Example
The following example illustrates use of the &return statement with the
command_status option:
&return e$file_not_found
The &return statement returns control to command level and sets the process’s
command_status variable to 1017. This is the error code number corresponding to
e$file_not_found.

&set
&set 0-
The &set statement evaluates an expression and assigns the value to a variable.
Form
&set variable_name expression
The value of variable_name is the name of a parameter or macro variable. A

parameter is declared in the parameter declaration section. (See the description of
&begin_parameters.) A macro variable is declared the first time it appears in a &set
or &set_string statement. It is an error to use a macro variable in an expression
before assigning a value to it in a &set or &set_string statement. The value of
variable_name can have neither an initial nor a final ampersand when it is defined.
It must not contain more than 32 characters and it must begin with a letter.
The value of expression is an expression that can be evaluated at the time the &set
statement is executed. The entire expression is evaluated by the (calc) command
function.
Explanation
A &set statement assigns a value to a command macro parameter or variable.
The operating system calls the (calc) command function to evaluate expression.
The resulting value is assigned to the parameter or macro variable specified by
variable_name.
Example
Suppose increment is a command macro parameter, defined in a parameter
declaration section. The first of the following &set statements declares and assigns a
value to the variable sum. The second adds the current value of increment to the
current value of sum. (Recall that the ampersand delimiters indicate the value, not the
name, of the parameter or macro variable.)
&set sum &initial_value&

&set sum &sum& + &increment&

&set
The first &set statement could declare sum, or it could have been declared earlier. The
second statement is equivalent to:
&set sum (calc &sum& + &increment&)

&set_string
&set_string 0-
The &set_string statement assigns a character-string value to a variable.
Form
&set_string variable_name S1 ...Sn
The value of variable_name is the name of a parameter or macro variable. A

parameter is declared in the parameter declaration section. (See the description of
&begin_parameters.) A macro variable is declared the first time it appears in a
&set_string or &set statement. It is an error to use a variable in an expression
before assigning a value to it in a &set_string or &set statement. The value of
variable_name can have neither an initial nor a final ampersand when it is defined.
It must not contain more than 32 characters and it must begin with a letter.
The value of S1...Sn is a set of one or more character strings that is evaluated to a
single character string value by the (string) command function at the time the
&set_string statement is executed.
NOTE
Any character that is special to the command processor
appearing in the &set_string statement, for example,
semicolons, must always be enclosed within apostrophes.
Explanation
A &set_string statement assigns a character-string value to a command macro
parameter or variable. This statement is particularly useful when it is necessary to treat
a series of numbers as a character string (that is, when you must avoid evaluating the
numbers arithmetically).
The operating system calls the (string) command function to evaluate the strings
S1 through Sn. The resulting value is assigned to the parameter or macro variable
variable_name.

&set_string
Example
The following example illustrates use of this macro statement:
&set_string license 001BYE

!display_line &license&
The output of the last line in the preceding example displays the line 001BYE.

&while
&while 0-
The &while statement evaluates a controlling expression, executes a loop if the

expression is true, and continues to execute the loop until the controlling expression is
false.
Form
&while expression
.
.
.
&end
Explanation
The &while statement evaluates expression. If expression is true (1), the
command processor executes the commands, statements, and input lines between the
&while statement and its corresponding &end statement; the &end statement
transfers control back to the &while statement, forming a loop. If expression is false
(0), control transfers to the statement following the corresponding &end statement.
The maximum nesting depth of any combination of &if statements, &do groups, and
&while loops is 32.

&while
Example
The following example uses the &while statement to count to 10:
&set counter 1
&while &counter& <= 10
&display_line &counter&
&set counter &counter& + 1
&end
&
&display_line DONE!
Related Information
See the description of the &end statement in this appendix.

&while

Appendix E
Using the Line Editor E-
The line editor is a text editor that lets you create, edit, and save files either interactively
or under the control of a command macro.
The line_edit command, issued interactively or within a command macro, calls and
sets up the line editor. After you issue this command, you can give editor requests,
described later in this appendix, to enter and modify text in a temporary work space and
to write out the edited text from the work space to a file in the directory hierarchy. The
quit request returns your process to command level or to the control of the command
macro that called the line editor.
This appendix has the following sections:
• ‘‘Basic Concepts”
• ‘‘Line Editor Requests”
NOTE
In this appendix, the term “print” refers to text written to the
current attachment of the default_output port (for
example, the default_output port could be attached to
a printing terminal, a display terminal, or an output file).
Basic Concepts
This section describes some basic concepts you need to understand in order to work
with the line editor.
Text Buffer
The text buffer is a temporary work space that contains the text you are editing. The
operating system does not display this buffer on your screen as it does with the Word
Processing Editor or Emacs, but you can insert text in the buffer and you can modify
existing text with line editor requests.
The buffer is organized as a sequence of text lines, with each line corresponding to a
record in a text file. The maximum line length is 300 characters. You can specify a line
Using the Line Editor E-1
Basic Concepts
in the buffer by its line number; the first line is line number 1, the second is line
number 2, and so on. When you insert a line in the middle of the buffer, the line
numbers of all lines following the new line increase by 1, and when you delete a line,
the line numbers decrease by 1.
Saved Path Name

You can give the path name of a file when you issue the line_edit command. If the
file does not exist, the editor creates it; if it does exist, the editor reads it into the text
buffer. In either case, the editor saves the path name. The editor then uses this saved
path name as a default name if you do not specify a path name when you give the
request to write out the text buffer. When you omit the path name from a line_edit
command, the buffer is initially empty and there is no saved path name.
You need read access to a file to read it into the editor buffer; you need write access to
an existing file to write out the contents of the text buffer to the same file. Also, to create
a file in a directory, you need modify access to that directory. See Chapter 9 for a
discussion of file and directory access.
Line Editor Modes and Switches

A line editor mode is a setting that determines how the line editor interprets and carries
out your requests.
There are three types of mode, each with an on setting and an off setting. Table E-1
shows the line editor mode switches and the default setting for each switch.
Table E-1. Line Editor Mode Settings
On Off Default
mapcase no mapcase no mapcase
numbers no numbers no numbers
verbose no verbose verbose
Each switch can be turned on or off either with an argument to the line_edit
command or with a line editor request. The command arguments that change the
default mode settings are -mapcase, -numbers, and -no_verbose (described in the
VOS Commands Reference Manual (R098)).
In mapcase mode, the editor disregards the case of alphabetical characters when
comparing text strings with the change, find, locate, and overlay requests.
E-2 VOS Commands User’s Guide (R089)

Basic Concepts
In numbers mode, the editor prints the number of a text line in the text buffer whenever
the editor prints the line on your terminal. The line number is printed in the leading four
columns.
In verbose mode, the editor prints every line that it modifies or selects with the append,
change, find, goto, locate, and overlay requests.
The requests that change mode settings are called mode requests. A mode request
begins with the keyword mode (or the short form m) followed by the name of the mode
in its appropriate form. You turn a mode switch on with the positive form of its name.
These are mapcase (or m), numbers (or n), and verbose (or v). To turn a mode
switch off, its name must be preceded by no_, no, or n.
If you specify the full name of the mode switch, you can omit the keyword mode.
For example, the following requests turn numbers mode off:
mode no_numbers
mode no_n
mode no numbers
mode no n
mode n numbers
mode n n
m no_numbers
m no_n
m no numbers
m no n
m n numbers
m n n
no_numbers
no numbers
n numbers
You can insert or delete spaces around the keywords, and you can use any
combination of uppercase and lowercase letters to spell the terms.
Line Editor States and Requests

The line editor is always in one of two states: the edit state or the input state.
In the edit state, the line editor interprets each line you enter as a request. An editor
request is an instruction you give for an action to be performed on the text buffer. For
example, there are requests to add text to the buffer, modify text already in the buffer,
relocate the current position in the buffer, and write text in the buffer to a file. The line
editor requests are described later in this appendix.

Basic Concepts
The req? prompt signifies that the line editor is in the edit state and is ready to accept
a request. You enter the request at the cursor following the prompt.
In the input state, the line editor interprets each line you enter as input to the text buffer.
When you press <RETURN>, the editor inserts the line into the buffer. You enter the input
state from the edit state by giving the insert request.
Line editor requests are not recognized in the input state. The only exception is a line
containing a single period; the editor interprets this as a request to return to the edit
state.
When the line editor is in the input state and in numbers mode, the editor prompts you
for each new input line with a line number in increments of 1. If the editor is not in
numbers mode, you are not prompted with a line number.
The Current Line

In both the edit and input states, the line editor maintains a current line. This is a line
in the buffer that the editor uses as a base location, or relative position, when carrying
out many of the requests. For example, the print request tells the editor to write a line
of text in the buffer to the default_output port. If you are using the line editor
interactively on a display terminal, typing print at the request prompt causes the
editor to display the current line.
Some requests always change the current line, some requests never change it, and
others may change it.
The Current Search String

The requests change, find, locate, and overlay tell the line editor to search in the
text buffer for a specified string called the search string. If you give one of these
requests without specifying a search string, the editor uses the current search string.
This is the string most recently specified in either a find request or a locate request
in the current editing session.
Forms of Requests
Most line editor requests can be given using only the first letter of the name. For
example, you can give the goto request by specifying only g. Thus, the following
requests have the same result:
goto 1
g 1
In each case, the line editor sets the current line to the first line in the buffer. Note,
however, that not every request can be given in this way. For example, you can give
the mode request with m, but to give the move request you must specify its full name.

Basic Concepts
Most requests can be qualified with arguments. For example, the goto request takes
a line number argument, as the preceding examples show. You can separate the first
argument from the request name with a space, but in most cases the space is not
necessary. The preceding examples are therefore equivalent to:
goto1
g1
However, you must enter a space before typing a path name as an argument to the
read or write request. Note also that the line editor disregards leading and trailing
spaces in a request.
You can give more than one request in a single line if you separate the requests with
a semicolon (;). For example, the following requests set the current line to the first line
in the buffer, print it, set the current line to the fifth line in the buffer, and then print the
new current line:
g 1; print;goto5 ;p
When you make several requests on one line, the line editor checks that all the
requests are syntactically valid before carrying out any of them.
You can mix uppercase and lowercase letters in request names, even when mapcase
mode is off. For example, the following requests are equivalent:
Goto 1
GOTO 1
goTO 1
gOtO 1

Basic Concepts
Using the Line Editor in Command Macros

You can put into a command macro file a series of line editor requests and input lines
for editing a file. You can then use the macro to perform the editing tasks on multiple
files. For example, to change every occurrence of one word to another word in a file,
you must call the line editor, perform a change request, and write out the modified text.
If you want to perform this operation on several files, you can save time by writing a
command macro that accepts a file name as an argument, calls the line editor using
the specified file name for the text_file_name argument, and performs the editor
requests. As an example, the following command macro changes every occurrence of
one character string to another in any file that you specify:
& a command macro that replaces every occurrence of

& the character string passed in as &from& to the
& character string passed in as &to& in the file
& specified for &file&
&
&begin_parameters
file pathname,required
from string,required
to string,required
&end_parameters
&
&attach_input
&
!line_edit &file& -no_backup -mapcase -no_verbose
change * /&from&/&to&/ *
write
quit
&
&detach_input
&return
Chapter 9 describes how to create and execute command macros; Appendix D

describes command macro statements (see the descriptions of the
&begin_parameters, &end_parameters, &attach_input, and
&detach_input statements).
The upward Qualifier

You can qualify many of the line editor’s requests with the upward (or u) keyword. This
keyword reverses the direction in which a request operates. It must precede the name
of the request to be qualified. For example, the copy request copies a set of lines to
the position immediately after the current line. But when preceded by the upward
qualifier, the copy request inserts the copied lines before the current line.

Basic Concepts
Repeated Requests
To repeat a list of requests a number of times, enclose the requests in parentheses
followed by a number stating how many repetitions to perform. You must type all the
requests on one line and separate them by semicolons.
Consider this compound request:
goto 100; (+10; upward append /new record:/) 20
The request sets the current line to the 100th line in the buffer and begins a repeated
request series. The series is executed 20 times. The first request in the series resets
the current line 10 lines ahead in the buffer. The second request puts the text string
“new record:” at the beginning of the current line. Thus the text is added to the lines
numbered 110, 120, ..., 300.
If a request in the repeated request series fails while the line editor is carrying out the
series, the editor stops executing the series and stops the repetition.
If you inadvertently start an infinite loop using this technique, you can stop the loop by
pressing the <CTRL><BREAK> keys, as described in the next section.
The <CTRL> <BREAK> Request

When you use the line editor interactively, you can give the <CTRL><BREAK> request to halt
the current operation and go to break level. At break level you can issue any of the
following commands:
• The stop command returns you to command level.

• The debug command invokes the debugger.
• The login commands logs you in to a subprocess.
• The continue command starts execution again as if there had been no break.
• The re-enter command interrupts the break request, returning you to
line_edit request level.
See the descriptions in Appendix B of the commands you use most commonly at break
level: stop, continue, keep, and re-enter. See the VOS Commands Reference
Manual (R098) for descriptions of the break-level commands debug and login.
If the line editor is in the input state when you type re-enter, then it displays the
following message and changes the state from input to edit:
***RE-ENTERED***
Any text that you entered on the line in which you pressed the <CTRL><BREAK> keys is
discarded.

Line Editor Requests
If the line editor is executing a request when you type re-enter, the
***RE-ENTERED*** message is displayed and the edit state is resumed without the
previously issued request being executed.

Table E-2 lists and briefly describes the requests you can make when the line editor is
in the edit state. Details of each request are provided later in this section.
Table E-2. The Line Editor Requests (Page 1 of 2)
Request Purpose
Carriage Return (CR) Sets the current line to the line following the present current line.
n Sets the current line to the nth line.
+n Sets the current line to the nth line after the present current line.
-n Sets the current line to the nth line before the present current line.
= Prints the current line number.
append or a Adds text to the beginning or end of a line.
bottom or b Sets the current line to the last line in the buffer.
change or c Changes one text string to another in a set of lines.
copy Copies lines to a point before or after the current line.
delete or d Deletes lines beginning or ending with the current line.
find or f Finds the nearest line beginning with a given string.
goto or g Sets the current line to a given line.
insert or i Inserts a line, or changes to the input state.
join Joins the current line with the line before or after.
locate or l Locates the nearest occurrence of a given string.
mode or m Sets the mode of the editor.
move Moves lines to a point before or after the current line.
overlay or o Overlays one text string with another.
path Prints the path name of the file in the buffer.
print or p Prints lines beginning or ending with the current line.
quit or q Quits.

Table E-2. The Line Editor Requests (Page 2 of 2)
Request Purpose
read or r Reads in a file to the buffer.
skip or s Skips to a specified number of lines to reset the current line.
tab or t Sets or display the tabulation stops.
write or w Writes out the buffer to a file.
Conventions Used in Request Descriptions

The notations m and n stand for unsigned integers or, in specified instances, for an
asterisk character (*).
The notations text, text1, and text2 stand for character strings that you want to
insert, locate, or replace in the text buffer.
Any character string used as an argument to a line edit request must be delimited
(enclosed) by two identical characters that are not part of the string specified by text.
In this appendix, the slant character (/) is used as the delimiter. You can use as a
delimiter any character except a space, a semicolon, or a character in a string
represented by text.
For example, the notation /text/ could stand for any of the following:
/declaration/
BabababababababababababB
. 1234567890 .
In the first example, the text delimiter is /; it could not be a, c, d, e, i, l, n, o, r, or t,

because these characters are in the text string. In the second example, the text
delimiter is B; in the third, the delimiter is a period (.).
Note that in a command macro, when you pass a variable or parameter as a character
string argument to a line edit request, you can use the dollar sign ($) when specifying
the parameter so that its value is appropriately delimited when it is replaced (for
example, &$source&). Otherwise, use the slant character to enclose the entire
variable (for example, /&source&/) when you specify it on the request line.

In the request descriptions, any parts of a request enclosed in brackets are optional.
For every optional argument, there is a default value that the editor uses when you omit
a value. For example, the goto request accepts an optional line number argument. If
you omit the line number, the editor uses the value 1. The form of the goto request is:
goto[n]
The brackets indicate that the line number n is optional.
Request Descriptions
Carriage Return (CR)
Sets the current line to the line following the present current line. If the request
succeeds, the editor always prints the new current line. The request fails if the present
current line is the last line in the buffer. You cannot use the upward qualifier with this
request.
n
Sets the current line to the nth line in the buffer. The argument specified by n must be
the number of a line in the buffer. If the request succeeds, the editor always prints the
new current line. If the request fails, the current line does not change. You cannot use
the upward qualifier with this request.
t+[n]
Sets the current line to the nth line after the present current line. If you omit a value for
n, the editor uses a value of 1. If the request succeeds, the editor always prints the new
current line. If the request fails, the current line does not change. You cannot use the
upward qualifier with this request.
-[n]
Sets the current line to the nth line before the present current line. If you omit a value
for n, the editor uses a value of 1. If the request succeeds, the editor always prints the
new current line. If the request fails, the current line does not change. You cannot use
=
Prints the number of the current line. The current line does not change. You cannot use
append/text/
Appends the character string specified by text to the end of the current line. If you use
the upward qualifier with the append request, the editor adds the string to the
beginning of the line. If the editor is in verbose mode, it prints the edited line.

bottom
Sets the current line to the last line in the buffer. If the editor is in verbose mode, it
prints the bottom line. You cannot use the upward qualifier with this request.
change[n]/[text1]/[text2]/[m]
Substitutes the string text2 for the first n occurrences of the string text1 in every line
in a set of m consecutive lines. If you use the upward qualifier, the set ends at the
current line; otherwise, it begins at the current line.
If you omit a value for n, the editor changes only the first occurrence in each line (the
default value of n is 1). If you specify an asterisk as the value of n, the editor replaces
every occurrence of text1 by text2.
If you omit a value for m, the editor replaces the strings in the current line only (the
default value of m is 1). If you specify an asterisk as the value of m, the editor changes
all occurrences of text1 from the current line through the end of the file, or, if you use
the upward qualifier, the editor changes all the occurrences from the beginning of the
file through the current line.
If the value of text1 is the null string, the editor uses the current search string. This
request does not change the current search string.
If the value of text2 is the null string, the editor changes the string specified by text1
to the null string. In effect, it deletes the string specified by text1.
If a line in the set does not contain the string specified by text1, the editor skips the
line but counts it as one of the lines in the set. If none of the lines in the set contains
the string, the editor prints a message saying so. If the editor is in verbose mode, it
prints every line that it changes.
This request does not reset the current line.
copy n[:m]
Copies the set of m consecutive lines starting with line n to a position immediately
before or after the current line. If you use the upward qualifier, the editor inserts the
copied lines before the current line; without the qualifier, the copies are inserted after
the current line.
If you omit a value for m, the editor copies only the line specified by n. If you specify an
asterisk as the value of m, the editor copies the lines beginning with n and ending with
the last line in the buffer.
delete[n]
Deletes a set of n consecutive lines from the buffer. If you omit a value for n, the editor
deletes the current line. If you use the upward qualifier, the editor deletes n
consecutive lines ending with the current line. If you omit the qualifier, the editor deletes
n consecutive lines beginning with the current line. If you specify an asterisk as the
value of n, and you use the upward qualifier, the editor deletes all the lines from the
beginning of the buffer through the current line; otherwise it deletes all the lines from
the current line through the end of the buffer.
The current line is reset to the line following the old current line when you use the
upward qualifier, or to the line before the old current line when you do not use the
qualifier.
If you delete all the lines from the buffer, the editor discards the saved path name.
find /[text]/
Searches the buffer for the closest line to the current line in the buffer that begins with
the character string specified by text. If you use the upward qualifier, the editor
searches for the nearest line before the current line; otherwise, it searches for the
nearest line after the current line. If the value of text is the empty string, the editor
uses the current search string as a value for text; otherwise, the editor resets the
current search string to text. If text begins with spaces, the editor searches for lines
that begin with any number of spaces (more, less, or equal to the number you give at
the beginning of text) followed by the remainder of the search string.
If the editor locates a line that begins with the search string, it resets the current line to
that line. Otherwise, the current line is not reset. If the editor is in verbose mode, it
prints the located line.
goto[n]
Resets the current line to the nth line in the buffer if there is an nth line. If you omit a
value for n, the editor resets the current line to the first line in the buffer. If you specify
an asterisk as the value of n, the editor resets the current line to the last line in the
buffer. If the editor is in verbose mode, it prints the new current line.
insert [/text/]
Inserts the string specified by text as a separate line in the buffer. If you use the
upward qualifier, the line is inserted before the current line; otherwise, text is inserted
after the current line. The current line does not change unless you use the upward
qualifier. In that case, the number of the current line increases by 1. The new line is not
printed, even when the editor is in verbose mode.
If you omit a value for text, the editor enters its input state. You enter text lines, which
the editor inserts after the current line (or before it if you use the upward qualifier), until
you type a single period on a line to return to the edit state. The current line does not
change while you are in the input state.

join
Concatenates the current line and the line following the current line into one line. If you
use the upward qualifier, the editor joins the line preceding the current line and the
current line. In both cases, the united line becomes the current line. If the editor is in
verbose mode, it prints the united line.
The order of the characters in the buffer is unchanged. However, the request trims all
existing spaces except one from the point where the two lines are joined.
locate /[text]/
Searches the buffer for the nearest line to the current line in the buffer that contains the
character string specified by text. If you use the upward qualifier, the editor searches
for the nearest line before the current line; otherwise, it searches after the current line.
If the value of text is the empty string, the editor uses the current search string as a
value for text; otherwise, the editor resets the current search string to text.
If the editor finds a line containing the search string, it resets the current line to that line.
Otherwise, the current line is not reset. If the editor is in verbose mode, it prints the
line it finds.
mode
Prints the current settings of the mode switches when you type this request with no
arguments. “Line Editor Modes and Switches” in this appendix describes how to use
the mode request to set the mode switches.
move n[:m]
Moves the set of m lines beginning with line n in the buffer to the position after the
current line. If you use the upward qualifier, the editor moves the lines to the position
before the current line.
If you omit a value for m, the editor moves only the line specified by n. If you specify an
asterisk as the value of m, the editor moves the set of lines beginning with line n and
ending with the last line in the buffer.
overlay[n]/[text1]/[text2]/[m]
Overlays the first n occurrences of the string text1 with the string text2 in every line
in a set of m consecutive lines. If you use the upward qualifier, the set ends at the
current line; otherwise, it begins at the current line.
If you omit a value for n, the editor overlays only the first occurrence of text1 (the
default value of n is 1). If you specify an asterisk as the value of n, the editor overlays
every occurrence of text1 with text2 within the specified set of lines.

If you omit a value for m, the editor overlays the strings in the current line only (the
default value of m is 1). If you specify an asterisk as the value of m, the editor overlays
all occurrences of text1 from the current line through the end of the file, or, if you use
the upward qualifier, the editor overlays all the occurrences from the beginning of the
file through the current line.
If the value of text1 is the null string, the editor uses the current search string. This
request does not change the current search string.
If the value of text2 is the null string, or if it has fewer characters than either text1
or the current search string (whichever you are using), then text2 is padded with
spaces on the right until it has the same length. If text2 is the longer string, however,
the editor overwrites the number of characters necessary to hold text2 following each
occurrence of text1, except in one case: if another occurrence of text1 would be
overwritten, the editor does not make the change and tells you the reason.
If a line in the set does not contain the string specified by text1, the editor skips the
line but counts it as one of the lines in the set. If none of the lines in the series contains
the string, however, the editor prints a message saying so. If the editor is in verbose
mode, it prints every line that it changes. This request does not reset the current line.
path
Prints the saved path name. If there is no saved path name, then the editor prints an
empty line. (If the saved path name is a link, the editor shows the path name that is the
ultimate target of the link and the saved path name.)
print[n]
Prints a series of n lines. If you omit a value for n, the editor prints the current line. If
you use the upward qualifier, the series of lines ends with, and includes, the current
line. If you do not use the qualifier, the series begins with, and includes, the current line.
If you specify an asterisk as the value for n, and you specify the upward qualifier, the
editor prints all the lines from the beginning of the buffer to the current line; otherwise,
when you omit the upward qualifier, it prints all the lines from the current line to the end
of the buffer.
This request does not change the current line.
quit
Returns your process to command level. If the contents of the buffer have not been
written to a file, the editor asks you whether to discard them.
read path_name
Reads in the contents of the file specified by path_name to the current text buffer. The
text is inserted before the current line if you use the upward qualifier; otherwise, it is
inserted after the current line.

If the buffer is empty when you issue this request, the current line is set to the first line
in the buffer after the contents of the file are read in. The editor also sets the saved path
name to path_name in this case.
If the buffer is not empty, the editor changes neither the current line nor the saved path
name.
skip[n]
Resets the current line to the nth line in the buffer after the current line if you omit the
upward qualifier. If you use the qualifier, the editor resets the current line to the nth line
before the current line. If you omit a value for n, the editor uses the value 1. If the editor
is in verbose mode, it prints the new current line.
tab[tab_specifier]
Sets the tab stops according to the value of tab_specifier or, if you omit the
specifier, it prints the current tab stops. If you do not set the stops with this request, the
editor uses the settings that were in effect for your terminal when you called the editor.
(See the description of the set_terminal_parameters command in the VOS
Commands Reference Manual (R098).)
A tab_specifier is a sequence of column numbers (n) and/or column numbers plus

increments (n+m). A specifier of the type n+m instructs the editor to set tab stops at
column n, column n+(m*1), column n+(m*2), column n+(m*3), and so forth until the
end of the line is reached or until another tab specifier supersedes the current one.
Consider the following form of tab_specifier:
n1 n2+m n3 n4+m
Substitute the elements of tab_specifier in the preceding example with the

following values:
n1 = 11
n2 = 21
m = 5
n3 = 45
n4 = 51
Using the preceding values, consider this form of the tab request:
tab 11 21+5 45 51+5

This request sets tab stops at the following column numbers (assuming a line length
of 80):
11 (n1)
21 (n2)
26 (n2+[m*1])
31 (n2+[m*2])
36 (n2+[m*3])
41 (n2+[m*4])
45 (n3)
51 (n4)
56 (n4+[m*1])
61 (n4+[m*2])
66 (n4+[m*3])
71 (n4+[m*4])
76 (n4+[m*5])
The specifiers must increase in value from left to right in the request.
When your process returns to command level, the tab stops in effect on your terminal
when you called the editor are restored.
write [path_name[n]]
Writes out some or all of the buffer contents to the file specified by path_name, or to
the file with the saved path name if you omit a value for path_name. If you specify
values for both path_name and n, the editor writes n lines starting with the current line
to the file path_name. If you use the upward qualifier, the editor writes the n lines
ending with the current line. If you specify an asterisk as the value for n, the editor
writes all the lines from the current line to the end of the buffer or, if you use the upward
qualifier, from the beginning of the buffer to the current line.
If the specified file does not exist, the editor creates it. If the file exists, the editor
replaces its old contents with the new contents. If you give path_name without giving
the n qualifier, and there is no saved path name, then the editor makes path_name
the saved path name.

Appendix F
Predefined Ports F-
Every process has five predefined ports. Table F-1 shows their names and identifiers.
Table F-1. Predefined Ports and Port Identifiers
Port Name Port Identifier
default_input 1
terminal_output 2
command_input 3
default_output 4
terminal 5
The attachments of these ports depend on the type of the process (interactive or
noninteractive) and what the process is doing (waiting at command level, executing a
system command, executing a command macro, executing an application program).
This appendix explains where these ports are attached in various circumstances.
How the System Uses the Predefined Ports

The operating system communicates continually with a user and the user’s process. It
sends and receives messages and data of several types. As the state of a process
changes, the attachments of the predefined process ports change to account for the
different sources and destinations of data, such as commands and error messages.
The following are conventions that govern the system uses of process ports:
• The default_input port is for data required by commands, subsystems, and

user programs.
The system expects to receive the input data that commands and subsystems
require through your process’s default_input port. When you log in at a
terminal and run a program interactively, the system attaches the
default_input port indirectly through the terminal port to the terminal.
However, when you are executing a command macro that contains the macro
statement &attach_input, the system attaches the port to the command macro
Predefined Ports F-1
How the System Uses the Predefined Ports
file so that the system can read data or subsystem requests from the macro file.
This allows you, for example, to use a macro to monitor system performance (with
the analyze_system command) or to edit files.
• The terminal_output port is for error messages from system commands and
programs.
The system writes to the terminal_output port errors detected by the system
or errors that you report using the error-handling subroutines in your application.
When you log in, the terminal_output port is attached to your terminal
indirectly through the terminal port. In a noninteractive process, the system
attaches the port to the output file.
• The command_input port is for commands from your process.

In an interactive process, the command processor receives commands (and
command arguments) through the command_input port. When your process is at
command level, the system attaches the command_input port to your terminal.
However, when your process is executing a command macro, the system attaches
your process’s command_input port to the command macro file so it can read
commands from the file. When the macro ends, the system reattaches the port to
its previous attachment.
• The default_output port is for data generated by your process.

The system writes most output data from commands to your default_output
port. In an interactive process, the system attaches the port to your terminal. In a
noninteractive process, it attaches the port to the output file. You can change the
attachment of the port with the attach_default_output and
detach_default_output commands.
• The terminal port is attached to the terminal in an interactive process and is

unattached in a noninteractive process.
The system attaches the other ports to the terminal port when the source or
destination of data passing through the port is the terminal.
Of these five ports, you can manipulate the attachments only of the default_input
and default_output ports, as explained in Chapter 1. The operating system
manages the attachments of the other ports for you.
F-2 VOS Commands User’s Guide (R089)

Attachments of Predefined Ports

The following tables show the attachments and directions of the flow of data in a
process in various circumstances. The conditions that vary among the illustrations are:
• whether the process is interactive or noninteractive.

• whether the default_output port has been reattached with the
• whether the process is executing a command or a command macro.
• if the process is executing a command macro, whether the macro contains the
macro statement &attach_input.
Table F-2 presents the twelve significant combinations of these factors and the number
of the table (F-3 through F-14) that shows the port attachments and connections for
each combination.
Table F-2. Factors That Determine Port Attachments
Table Interactive attach_default_output Command/Macro attach_input
F-3 yes no command does not apply
F-4 no no command does not apply
F-5 yes yes command does not apply
F-6 no yes command does not apply
F-7 yes no macro no
F-8 no no macro no
F-9 yes yes macro no
F-10 no yes macro no
F-11 yes no macro yes
F-12 no no macro yes
F-13 yes yes macro yes
F-14 no yes macro yes

Table F-3. Attachments When an Interactive Process Executes a Command
Predefined Port Attachment Direction of Data Flow
default_input terminal from terminal
terminal_output terminal to terminal
command_input terminal from terminal
default_output terminal to terminal
Table F-4. Attachments When a Noninteractive Process Executes a Command
default_input none
terminal_output output file-1 or device-1 to output file-1 or device-1
command_input none
default_output output file-1 or device-1 to output file-1 or device-1
Table F-5. Attachments When an interactive Process Executes a Command

after executing attach_default_output
command_input terminal from terminal


after executing attach_default_output
default_input none
command_input none
Table F-7. Attachments When an Interactive Process Executes a Command Macro
command_input macro file from macro file
Table F-8. Attachments When a Noninteractive Process Executes a Command Macro
default_input none
command_input macro file from macro


Macro Containing the Command attach_default_output

Macro Containing the Command attach_default_output
default_input none
Table F-11. Attachments When an interactive Process Executes a Command

Macro Containing the Macro Statement &attach_input
default_input macro file from macro file


Macro Containing the Macro Statement &attach_input

Macro Containing the Command attach_default_output and the
Macro Statement &attach_input

Macro Containing the Command attach_default_output and the
Macro Statement &attach_input


Appendix G
Specifying Dates and Times G-
This appendix describes how to specify date/time string arguments in the following
command functions:
(date)
(date_time)
(iso_date)
(iso_time)
(time)
See Appendix C for information about these command functions.
The general form of a date/time string is as follows:
[coming] [absolute_date] [absolute_time] [time_zone]

[relative_terms]
coming
A keyword specifying that the input date and/or time string is in the future. If
selected, coming must be the first term in the string.
If you specify the -standard argument, you can use the keyword defined for the
current process language in place of coming to specify that the input date and/or
time string is in the future. For example, in Italian the keyword might be defined as
prossimo. The non-English keyword is valid only if you specify the -standard
argument in the call to the command function.
absolute_date
A date string in one of the input formats shown in the examples below. The date
string can specify either a complete date or a partial date. A complete date explicitly
specifies the year, month, and day. A partial date gives less information but will be
interpreted unambiguously by VOS.
Specifying Dates and Times G-1

Specifying Dates and Times
The following are examples of complete date string values for absolute_date;
each value specifies the first day of August 2001:
8/1/01 august 1 2001 august 01, 01

01-08-01 1-august2001 1august2001
01/8/1 1 august, 2001 01 august 01
08 01 01 1aug01 01-august-01
010801 01 Agosto 01 1Ago01
The following are examples of partial date string values for absolute_date and
how the values are interpreted. Assume that the current date is
Wednesday, August 1, 2001.
Partial Date Meaning
01 the first day of 2001 (1/1/01)
august the first day of August in the current year (8/1/01)
8/1 the first day of August 2001 (8/1/01)
fri the Friday of the current week (8/3/01)
Values allowed for specifying the day of the week in a partial date string are: sun,
mon, tue, wed, thu, fri, and sat. A week is interpreted as beginning on Sunday
and ending on Saturday.
If you choose the -standard option, the days of the week can be specified in your
process language. For example, in Italian the days of the week in a partial date
string may be: Dom, Lun, Mar, Mer, Gio, Ven, and Sab.
Note the following:
• The number specifying the month must occur in the date string before the
number specifying the day of the month.
• The number specifying the year cannot separate the month and day.
• The day of the week cannot be specified together with a complete date in an
input date string.
Also note that absolute_date must precede absolute_time when both are
included in a date/time string.
G-2 VOS Commands User’s Guide (R089)

absolute_time
A time string in one of the input formats shown in the examples below. The time
string can specify either a complete time or a partial time. A complete time explicitly
specifies the hour, minute, and second. A partial time gives less information; you
can specify a partial time only if it is preceded by a date string that gives a complete
date. When this condition exists, a partial time is interpreted unambiguously by
VOS.
The following are examples of complete time string values for absolute_time.
8:00 10am 10 del mattino

08:00 10 am 1:00 del pomeriggio
08:00:00 10:00 am
The following are examples of partial time string values for absolute_time, and
how the values are interpreted. The examples assume that a preceding
absolute_date string is specified.
Partial Time Meaning
1 one o’clock in the morning
0 twelve midnight
21 nine o’clock in the evening
time_zone
A string that specifies the time zone. Table G-1 shows the values allowed for
time_zone and the meaning of each value.
Table G-1. Valid Time Zone Input Strings (Page 1 of 3)
Code Time Zone
adt Atlantic Daylight
ast Atlantic Standard
at Azores
bst British Summer
bt Baghdad
cad Central Australia Daylight
cas Central Australia Standard
cdt Central Daylight

Code Time Zone
cet Central European
chd China Daylight
cht China Time
cst Central Standard
ead East Australia Daylight
eas East Australia Standard
edt Eastern Daylight
eet Eastern Europe
est Eastern Standard
fst French Summer
fwt French Winter
gmt Greenwich Mean
gst Greenland Standard
hdt Hawaii-Aleutian Daylight
hfe Heure Francaise d’Ete
hfh Heure Francaise d’Hiver
hkt Hong Kong
hst Hawaii-Aleutian Standard
ist Indian Standard
jst Japan Standard
jt Java
kdt Alaska Daylight
kst Alaska Standard
mas Malaysia Standard
mdt Mountain Daylight
mes Middle Europe Summer
met Middle Europe

Code Time Zone
mew Middle Europe Winter
mst Mountain Standard
ndt Newfoundland Daylight
nst Newfoundland Standard
nt Nome
nzd New Zealand Daylight
nzs New Zealand Standard
pdt Pacific Daylight
phs Philippine Standard
pst Pacific Standard
sdt Samoa Daylight
sis Singapore Standard
sst Samoa Standard
tpe Taiwan Standard
tst Thailand Standard
ut Universal
wad West Australia Daylight
was West Australia Standard
wat West Africa
wib Indonesia Standard
ydt Yukon Daylight
yst Yukon Standard
z Zulu (Universal)
NOTES
1. Beginning in VOS Release 14.0.0, the bdt (Bering
Daylight Time) time-zone code is no longer
supported.

2. Beginning in VOS Release 14.0.0, the bst (Bering

Standard Time) time-zone code is now used for
British Summer time. The replacement time-zone
code for Bering Standard Time is nt (Nome).
3. Beginning in VOS Release 14.0.0, the hdt and hst
time-zone codes are now used for Hawaii-Aleutian
Daylight time and Hawaii-Aleutian Standard time,
respectively. They were previously used for Alaska
Daylight time and Alaska Standard time, but these
now have the kdt and kst time-zone codes,
respectively.
relative_terms
One or more strings of the form +I specifier or -I specifier, where I is an
integer and specifier is any of the terms in the list below. The value of I
specifies the number of units by which the output date and/or time is to be offset.
For example, the date string fri +1 wk is the date of the Friday after the Friday
of the current week.
When using relative units in the (date_time) function, date and time are acted
upon separately. Thus, the time offset is applied to the current time unless an
absolute time is specified.
For example, assume the time is 11:00 a.m. on February 28, 2001. If you enter
display_line (date_time feb_28 +2hours)
the output returns 01-02-28 13:00:00
If you use the specified time of 00:00 + 2 hours, is in the following example:
display_line (date_time feb_28_00:00 +2hours)
the output returns 01-02-28 02:00:00
The following values are valid for specifier:
yr, yrs, year, years

mo, mos, month, months,
wk, wks, week, weeks,
day, days,
hr, hrs, hour, hours,
min, mins, minute, minutes,
sec, secs, second, seconds

If your process language is not English, and your process language is one of the
languages configured on your module, these values can be replaced with their
equivalents in your process language.


Appendix H
Using the Online Help Facility H-
NOTE
Beginning with VOS Release 14.4.0, the VOS help facility
was superseded by the VOS StrataDOC online
documentation service. The help facility has not been
updated since then but remains available for those
customers who use it within their own applications.
The online help facility is the part of the operating system that provides information on
your display screen about commands and command functions. This appendix
describes the components of the online help facility.
The online help facility is designed to lead you to information you are likely to need as
a new user of the operating system, whether or not you have previous experience with
computing systems. Online help will continue to be useful as your experience with the
operating system grows. However, the help facility assumes no prior knowledge of the
names of system commands or of what they do.
Help information has two main purposes. First, it helps you decide on the command
you need to use to do a certain task; the help subsystem is provided for this purpose.
Second, after you have identified the command you need, help information tells you
how to choose specific values for arguments; help messages from the display form and
command-line form of commands are provided for this purpose.
This appendix has two sections:
• ‘‘Requesting Help Information,” which describes the online help facility.

• ‘‘Writing Help Messages,” which explains how to create your own help files.
Using the Online Help Facility H-1

Requesting Help Information

You invoke the help facility in the following ways:
• To enter the help subsystem, press the <HELP> key or type the help command with
no arguments on a command line.
• To display a brief description of the command, either type the command name and
press the <HELP> key or type the help command and give the name of the command
as the topic_name argument on the command line.
• To get help information about a command’s arguments, press the <DISPLAY_FORM>
key to invoke the command in the display form, then position the cursor to an
argument field and press the <HELP> key.
Using the Help Menu Subsystem

The help subsystem is the part of the online help facility that provides menus from
which you can choose topics you want information about.
Some help subsystem menus display lists of tasks from which you can choose those
that are closest to what you want to do. Other menus organize commands into groups
that form facilities, components of the command interface to the operating system.
When you are first orienting yourself to the operating system, you might choose to
explore the menu subsystem of the help facility to learn about some generic tasks you
could use the computer to complete. Or, if you prefer, you might choose to explore the
command menus to look up commands grouped by system facility. See Figure H-1 for
the mail menu of the Help subsystem. Additional subsystem menu items provide
descriptions of command functions and information about how to use the help system.
H-2 VOS Commands User’s Guide (R089)

Figure H-1. Main Menu of the Help Subsystem
HELP SYSTEM Main Menu
To select a topic, type a number from 1 to 4 and press RETURN.

Type the number zero (0) to exit from the help system.
TOPICS Description
1 Tasks Find out how to do tasks you want to do

--such as run a batch job or create,
compile, and load a program.
2 Commands List commands grouped according to

acility. Get general descriptions
of individual commands.
3 Command Functions List command functions grouped by

functional category. Get descriptions
of syntax and arguments.
4 Help Find out how to use the help system.
The items you can choose from the menu shown in Figure H-1 are described below:
Tasks
When you choose Tasks from the top-level menu of the menu subsystem, the help
facility displays a list of tasks any computer user is likely to want to know how to do.
Further menu screens under tasks describe subtasks, and the help screen the next
level down provides a context for using system commands.
The task menus are primarily intended for when you know in a general way what you
want to use the computer to do, such as run a batch job, write a program, or edit text,
but do not know the specific command or commands you need to perform the task.
Commands
When you choose Commands from the top-level menu, the help facility displays a menu
that lists functional groups, or facilities, into which the system commands are classified.
If you choose a group from this menu, the help facility displays a list of commands in
that group. Select a command from the list, and the help facility displays a brief
description of the command.

Command Functions
When you choose Command Functions from the top-level menu, the help facility
displays a menu that lists the functional groups into which command functions are
classified. If you choose a group from this menu, the help facility displays a list of
command functions in that group. Select a command function from the list, and the help
facility displays a brief description of the command function, giving its syntax and
explaining the options it accepts, if any.
Help
When you choose Help from the top-level menu, the help facility displays a series of
screens that describe features of the help subsystem.
Getting Information about Individual Commands

Help information describing individual commands is also available. You can do either
of the following at command level:
• Type the name of the command and press the <HELP> key.
• Type help and the name of a command as the topic_name argument.
To determine the correct form for keywords and the required order for positional
arguments of any command invoked in the command-line form, you can use the
-usage option. The -usage option displays a command’s arguments on a command
line.
To invoke the -usage option, type the command name and the keyword -usage on a
command line. The command name appears, followed by either a list of its arguments
or a message that no arguments are required. Suppose you invoke the following
command:
rename -usage
The following is displayed:
Usage: rename old_name new_name [-delete] [-files] [-dirs]

[-links] [-all]
You can also use the -usage option with the <DISPLAY_FORM> key to display a display
form, then return to command level without executing the command. For example, if
you enter rename -usage and press <DISPLAY_FORM>, the output looks like this:

Display Form
----------------------------------- rename ------------------------------------
old_name:
new_name:
-delete: no
-files: yes
-dirs: no
-links: no
ready hh:mm:ss
The -usage option can also be used in combination with the -form option to display
a command’s display form in an Emacs buffer. Give the Emacs execute_request
directive, then respond to the prompt by entering the command followed by -usage
-form. See the VOS Emacs User’s Guide (R093) for information about
execute_request.
Note that you can enter arguments into the command string preceding -usage
<DISPLAY_FORM> and -usage -form.
In the command-line form, if you try to issue a command without supplying values for
all required arguments, the operating system prompts you for the missing values.
Getting Information about a Command’s Arguments

Help information is available for each argument in the display form of a command. If
you know the name of the command you want to use, you can request information
about the arguments that you can give with the command.
When you invoke the command in display form, if you do not know the purpose of an
argument, or if you need more information in order to supply an argument value,
position the cursor to the field and press the <HELP> key. The help facility displays a
message describing the argument. The initial help message is brief, and in cases
where there is more help information available the help facility prompts you to press the
<HELP> key repeatedly until you have displayed all the information available. When you
press the <RETURN> key, the help facility redisplays the form, showing any argument
values you have selected.
When a command invoked in command-line form prompts for a required argument,

press the <HELP> key to display help information about the required argument.
In the display form, if you try to issue a command without supplying values for all
required arguments that have no defaults, you receive the message A required
field is missing.

Writing Help Messages
Writing Help Messages

You can create your own help files. All help files (in English) are standard ASCII text
files with names of the form topic_name.help. The topic_name portion of the help
file name can be the name of a command, but it need not be; it can also be a topic for
which you want help to be available online. The suffix .help tells the help facility that
the file is a help message file.
Control sequences determine how the help text is displayed on the screen. Each
control sequence is embedded in the help message file and is in the form &sequence:
(preceded by an ampersand (&) and ending with a colon (:)). The control sequence
must be on a line by itself with the text following on the next line. Each screen of help
information must not exceed 18 lines of text. Descriptions of the control sequences
follow:
&brief:
&brief displays a brief message at the beginning of a help file. The message is
terminated by the next control sequence (preceded by an ampersand) or by the
end of the file. The help facility displays the &brief message when you invoke
help at command level with the topic_name argument.
&arg:argument:
&arg displays help text for argument. The &arg control sequence precedes each
argument described in a help file.
&more:
&more allows you to display a sequence of connected help screens on a single
topic. After each 18 lines of text (or less if you wish), insert &more on a line by itself
in the file.
To clear the screen and display a descriptive banner line at the top of a help screen,
include a banner control string:
&more:
&iv:Topic Name subtopic name
If you create help files of your own, you can store them in any directory you include in
your message library search paths. The message library is described in Chapter 3.

Glossary Glossary-
abbreviation
A character string in a command that the operating system replaces before
executing the command. Each user defines his or her own abbreviations by editing
an abbreviations file located in the user’s home directory. The user then gives the
command use_abbreviations, which compiles the abbreviations file into an
abbreviations table. VOS uses the table to expand the abbreviations into their long
forms.
abbreviation parameter
A variable in the output string of a first directive that is replaced by one or more
input arguments or argument values on the command line.
abbreviations file
A text file containing replacement directives.
abbreviations table
A table created from an abbreviations file by the use_abbreviations command.
The operating system refers to a user’s abbreviations table to determine the
replacement for an abbreviation.
access
To read from or write to a file or device. (See access code and access right.)
access control
The mechanism by which the operating system determines the access rights of
users to files and directories.
access control list

A file that the operating system uses to determine the access rights of users to a
particular file or directory. An access control list is a list of entries, each of which
shows an access code and a user name. There are three kinds of access control
lists: file access control lists, directory access control lists, and default access
control lists.
Glossary-1
Glossary
access right
A designation that determines the operations a user is permitted to perform on a
file or directory. The types of access rights to a file are null, execute, read, and
write. The types of access rights to a directory are null, status, and modify.
alias
An alternate (usually shorter) form of a person name that can be used with the
login command.
all directive
A type of replacement directive in an abbreviations file that tells the operating
system to replace an input string with an output string wherever the specified input
string occurs in the command.
argument
A character string that specifies how a command, request, subroutine, or function
is to be executed.
ASCII (American Standard Code for Information Interchange)

A standard binary code that represents each character as a 7-bit number.
attach
To associate a port with a file or device, creating the port, if necessary, and
generating a port identifier. The port identifier can then be used to refer to the file
or device. (Compare with detach.)
back up
To copy onto disk or tape some or all of the data stored on a system’s disks. If data
are later damaged or accidentally deleted, they can be retrieved from the backup
copy in the state they were in at an earlier time. (See restore.)
batch control file

A text file containing directives that control the timing and order of the execution of
a batch request.
batch process
A noninteractive process that executes a command. When you request a batch
process, the operating system puts the batch request into a specified queue and
starts a batch process to execute the command whenever resources become
available. The batch process runs independently of the process that issued the
batch request.
Glossary-2 VOS Commands User’s Guide (R089)

Glossary
batch processor
The part of the operating system software that creates batch processes and
manages the batch queue. The batch processor handles the requests in the batch
queue sequentially, starting a batch process for each request when the request
preceding it in the queue has been completed.
batch queue
A queue where the operating system puts batch requests until they can be
handled.
batch request
One or more commands that are executed in a batch process.
bind
To combine a set of one or more independently compiled object modules into a
program module. Binding compacts the code and resolves symbolic references to
external programs and variables that are shared by object modules in the set and
in the object library. (See library.)
break
To send a signal that interrupts a program being executed and places the process
executing the program at break level.
break level
The state that results when a user gives a break signal and it is handled by the
default system software. When an interactive process is placed at break level, you
are prompted to enter one of the following commands: stop, continue, debug,
keep, login, or re-enter.
caller
See calling process.
calling process
The process that invoked the program currently being executed.
character
A character from one of the character sets supported by the operating system. A
character consists of one or more bytes, depending on the character set.
Glossary-3
Glossary
character string
An ordered set of characters. The length of a character string depends on the
number of bytes per character (which is not the same for all character sets) and the
number of characters in the string.
command
A program invoked from command level, either interactively or as a statement in a
command macro. There are three kinds of commands: internal commands,
command macros, and program modules.
command function
A self-contained function that you can use as an argument in a command line.
Before executing the rest of the command line in which a command function
appears, the command processor evaluates the command function and replaces it
with a value. The value returned becomes part of the command line. An example
of a command function is (time), which the operating system replaces with the
current time. A command function must always be enclosed in parentheses.
command level
The state at which commands can be issued to the command processor.
command library
The library in which the command processor searches for command macros
(objects with the suffix .cm) and program modules (objects with the suffix .pm).
command line
A set of one or more command strings, separated by semicolons.
command line storage areas

Two storage areas, called the insert saved buffer and the insert default buffer, that
save text you enter at command level, break level, and prompt level. The insert
saved buffer saves text you enter with the <RETURN>, <DISPLAY_FORM>, or <ENTER> key.
The insert default buffer saves text you enter with the <RETURN> or <DISPLAY_FORM>
keys. You retrieve text from the insert saved buffer by pressing <INSERT_SAVED>, and
from the insert default buffer by pressing <INSERT_DEFAULT>.
command macro
A text file that is a user-written program, invoked in the same way that you invoke
a command. The name of a command macro must end with the suffix .cm.

Glossary
command macro statement

A statement in the form &keyword that can be included in a command macro to
perform a predefined function. Command macro statements are valid only in
command macros.
command name
The name of a program or command macro that can be issued as a command.
command processor
The part of the operating system software that accepts and executes commands.
The command processor replaces abbreviations and evaluates command
functions in a command before loading the program specified in the command.
command string
A command name and any command arguments and/or macro parameters you
specify.
compiler
A program that translates a source module (source code) into an object module.
configuration table
One of the table files that the operating system uses to identify the elements of a
system. For example, the file devices.table contains information about each
device present in the system, and the file disks.table contains information
about each of the disks present in a system.
current directory
A directory currently associated with your process. VOS uses your current
directory as the default directory when you do not specifically name the directory
containing an object that you want VOS to find. For example, if you supply a relative
path name in a command, VOS uses the current directory as the reference point
from which to locate the object in the directory hierarchy.
When you log in, your current directory is set to your home directory. You can
change the directory that is your current directory with the change_current_dir
command or the s$change_current_dir subroutine.
current line
In the line editor, a line in the buffer that the editor maintains and uses as a base
location, or relative position, when carrying out many of the requests.
Glossary-5
Glossary
current module
The module associated with a process; the module on which the process is
executing. You cannot change the current module of a process.
current search string

In the line editor, the character string most recently specified in either a find
request or a locate request. The line editor searches for this string in a text buffer
when you give a change, find, locate, or overlay request without specifying
a new search string.
current system
The Stratus system associated with a process; the system containing the process’s
current module.
cycle values
Two or more predefined values that you display in the display form using the
<CYCLE>, <CYCLE_BACK>, <¬>, and <®> keys.
date-time, standard operating system

A 32-bit integer, representing a date, time, and zone. The operating system
interprets the value as the number of seconds since the beginning of
January 1, 1980, Greenwich Mean Time. A date time value of 0 is interpreted as
the beginning of January 1, 1980, Greenwich Mean Time.
default access control list

An access control list that is associated with a directory and contains an ordered
set of entries that defines the access rights of users to the files in that directory.
default priority level

The priority assigned to your initial interactive process unless you specify a
different priority.
default value
The value that the operating system uses if a specific value is not supplied.
detach
To disassociate a port from a file or device. (Compare with attach.)
device
Any piece of hardware that can be referenced and used by the system or users of
the system and that is defined in the device configuration table. Terminals, printers,
tape drives, and communications lines are devices.

Glossary
device configuration table

The file devices.table, which contains information about each device present
in a system. (See configuration table.)
device name
The name of a device. Device names are specified by the system administrator in
the device configuration table. The path name of a device has two components:
(1) the name of the system, prefixed by a percent sign, and (2) the name of the
device, prefixed by a number sign. For example: %s1# sales_printer.
At command level, you can abbreviate a device name by omitting the system
component.
Note that module names and disk names have the same form as device names.
directory
A catalogue of files, subdirectories, and links.
directory access control list

An access control list that is associated with a directory and contains an ordered
set of entries that defines the access rights of users to that directory.
directory hierarchy
The structure of the set of directories subordinate to a disk.
disk directory
The top directory on a disk. In a path name, the disk directory name is prefixed with
a number sign (#).
disk name
The name of a disk. Disk names are specified by the system administrator in the
disks configuration table. (See configuration table.) The path name of a disk has
two components: (1) the name of the system, prefixed by a percent sign, and
(2) the name of the disk, prefixed by a number sign. For example: %s1# d01.
Note that module names and device names have the same form as disk names.
default character set

An attribute of a file, defined by the create_file, set_text_file, or emacs
commands, that causes text in the file to be represented in a specified character
set. Character sets supported are ASCII, Latin #1, Japanese kanji, katakana,
hangul, simplified Chinese, Chinese1, Chinese2, and user_dbcs.
Glossary-7
Glossary
default process language

The language in which text is displayed and printed in a process, specifically the
text of date and time information, system error messages, and files containing text
in the character set appropriate to the process language.
display
To show on the screen of a display terminal.
edit state
A state of the line editor in which each line you enter is interpreted as a request.
editor
A program to create and modify text files. Stratus supports two screen editors and
one line editor. The screen editors are called by emacs or edit, and the line editor
is called by line_edit.
error code
A status code that is returned by a VOS service subroutine to indicate that an error
has occurred in the execution of the subroutine.
error message
A character string that is associated with an error code.
escape character
A user-defined ASCII character that signals the beginning of an escape sequence.
The default escape character is the grave accent.
event
A data structure, associated with a file or device, that is used by processes to
communicate with one another. When one process notices that some action has
occurred that is of potential interest to one or more other processes, the first
process notifies the event. This notification causes VOS to inform all processes
that have been waiting for the action. (These processes are said to be waiting on
the event.) Each time an event is notified, its event count is incremented.
executable image
The object created from a program module by the loader. The modifiable part of the
executable image does not reside in the file hierarchy, but rather in temporary
paging storage that is shared by many processes. Parts of an executable image
can be swapped in and out of main storage.

Glossary
execute access
A type of file access that means a user can execute a program module or a
command macro, but cannot read or write the file.
expression
A series of one or more operands and zero or more operators that can be
evaluated by the command processor to return a value.
file
A set of records or bytes stored on disk or tape as a unit. A disk file has a path name
that identifies it as a unique entity in the system’s directory hierarchy. Attributes of
a disk file, such as its size and when it was created, are maintained in the directory
containing the file.
file access control list

An access control list that is associated with a file and contains an ordered set of
entries that defines the access rights of users to that file.
file system
The part of the operating system that manages files in the directory hierarchy.
final substring
A substring whose last character is also the last character in the containing
character string.
first directive
system to replace an input string with an output string when the specified input
string occurs first in a command string.
full path name

For a file, directory, or link, a name that is composed of the name of the system,
the name of the disk, the names of the directories that contain the object, and finally
the name of the file, directory, or link.
For a device, a name that is composed of the name of the system and the name of
the device.
A full path name refers to only one object; an object has exactly one full path name.
(However, many links can refer to the same object.)
function
A procedure that takes zero or more input arguments and returns a single value.
Glossary-9
Glossary
group
A set of users whose directories are contained in the same group directory.
group directory
A set of user directories, collected together for the purposes of allocating system
resources and simplifying access control. A group directory is a directory
immediately subordinate to a disk. It has the same name as a group and contains
the user directories of the members of the group.
group name
The name that identifies the group directory to which a person registered to use the
system belongs. A group name is one of the two parts of a user name.
home directory
A directory that is your current directory when you log in and that the operating
system uses as the default directory in which to place certain per-user files.
A directory can be specified as your home directory in the registration databases.

If the databases do not specify a home directory, your default home directory is a
subdirectory of the group directory that you logged into, and is named with your
person name.
implicit locking
A VOS locking mode in which VOS does not lock the file or record for either reading
or writing when it opens the file, but rather locks it for the appropriate access type
each time a process performs an I/O operation on the file or record.
include file
A file that the compiler includes in the source module used by the compilation
process. The name of the include file must be specified in a language-specific
directive within the source module.
include library
The library in which the compilers search for include files.
initial substring
A substring whose first character is also the first character in the containing
character string.
input state
A state of the line editor in which each line you enter is interpreted as input to the
text buffer.

Glossary
insert default buffer

A command line storage area that saves text you input with the <RETURN> or the
<DISPLAY_FORM> key.
insert saved buffer

A command line storage area that saves text you input with the <RETURN>,
<DISPLAY_FORM>, or <ENTER> key.
interactive process
A process started with the login command. A user working with an interactive
process is engaged in a dialogue with the operating system, issuing commands
and receiving responses, normally from a display terminal.
internal command
A command program that is built into the operating system. Internal commands are
not stored in the directory hierarchy.
iso_date
A date in the form of yyyy-mm-dd. See also date-time, standard operating
system.
iso_date_time
A date and time in the form of yyy-mm-dd hh:mm:ss. See also date-time,
standard operating system.
keyword
An argument label that begins with a hyphen.
label
For an internal command, the name of a command argument. In a command
macro, an optional element of a parameter descriptor that can provide a descriptive
term that will be useful to users of the macro.
library
One or more directories in which VOS looks for objects of a particular type. There
are four kinds of libraries defined by VOS:
• include libraries, in which the compilers search for include files

• object libraries, in which the binder searches for object modules
• command libraries, in which the command processor searches for commands
• message libraries, in which the operating system searches for message files
associated with individual .pm files
Glossary-11
Glossary
One of each of these libraries is available in the >system directory of each module
for all processes running on the module. In addition, you can define your own
libraries.
library path
The path name of a directory included in a library.
line editor
A VOS text editor that lets you create, edit, and save files either interactively or
under the control of a command macro.
link
An object contained in a directory that directs all references to itself onward to a
file, a directory, or another link. Like many other objects, a link has a path name that
identifies it as a unique entity in the system directory hierarchy.
lock
A system data structure associated with a file, file record, or device that can be set
to restrict the use of the object to a particular mode until the lock is reset. Setting a
lock is called locking the lock; resetting it is called unlocking the lock.
locking shift
A user-transparent character in a key or record, indicating that the remaining
characters in the key or record are from a character set other than the default.
macro parameter
A named variable that is declared within the parameter declaration section of a
command macro.
macro processor
The part of the operating system software that reads macro files and processes
macro statements. The macro processor does not process command lines and
input lines that it encounters in macros; instead, it returns these lines to the
command processor. The operating system starts up the macro processor when a
command macro is issued.
macro variable
A named variable in a command macro that is declared and given its initial value
in one of the macro assignment statements, &set or &set_string.

Glossary
mapcase mode
In the line editor, a setting that causes the line editor to disregard the case of
alphabetical characters when comparing text strings with the change, find,
locate, and overlay requests.
master disk
The name of the member disk from which the module is booted. In the case of
automatic bootload, it is the lowest-numbered disk on the lowest numbered disk
controller in the chassis. If it is a manual boot, it is the disk selected manually during
the boot sequence.
The master disk is also known as the boot disk.
maximum priority level

The highest priority level that you can assign to any of your processes.
message
A line of text that the operating system displays to provide you with information.
Messages are one type of status information. Each message has an associated
code and an associated name that begins with the prefix m$.
mode
In the line editor, a setting that determines how the line editor interprets and carries
out line editor requests. There are three line editor modes, each with an on setting
and an off setting: mapcase, numbers, and verbose.
mode requests
In the line editor, requests that change mode settings.
modify access
A type of directory access that means a user has full access to the contents of the
directory, including the ability to create, delete, and rename objects.
module
A single Stratus computer. A module is the smallest hardware unit of a system
capable of executing a user’s process.
module name
The name of a module. Module names are specified by the system administrator
in the modules configuration table. (See configuration table.) The path name of
a module has two components: (1) the name of the system, prefixed by a percent
sign, and (2) the name of the module, prefixed by a number sign. For example:
%s1 # m5.
Glossary-13
Glossary
Note that device names and disk names have the same form as module names.
module star name

A name that contains one or more asterisks or consists solely of an asterisk, and
that is used to specify a set of modules in a system. An asterisk can be in any
position in the name, and each asterisk represents zero or more characters. A
module star name can be used alone or as part of a full module path name, but in
a full module path name there can be no asterisks in the system name. When a
module star name consists solely of an asterisk, it represents all modules in the
current system. See also star name.
National Language Support (NLS)

The ability of the operating system to represent text in languages other than
English. Languages suppoted include ASCII, Latin #1, Japanese kanji, katakana,
hangul, simplified Chinese, Chinese1, Chinese2, and user_dbcs.
newline character
A nonprinting character that you insert in a file by pressing the <RETURN> key.
null access
A type of file or directory access that means a user has no access to the file or
directory.
numbers mode
In the line editor, a setting that causes the line editor to print the number of a text
line in the text buffer whenever the editor prints the line on your terminal. The line
number is printed in the leading four columns.
object
Any data structure or device in the system that you can refer to by name or some
other identifier. For example, all of the following are objects: directories, files, links,
systems, modules, devices, groups, persons, ports, queues, locks, file indexes, file
records.
object library
The library in which the binder searches for object modules (objects with the suffix
.obj).
object module
A file produced by a compiler. An object module consists of nonexecutable
machine instructions and usually contains symbolic references to external
variables and programs. To execute the program, an object module must be bound
by the binder and loaded by the loader.

Glossary
object name
A character string identifying an object. The maximum length of an object name is
32 characters. Examples of objects that have object names are files, directories,
and links.
online help facility

The part of the operating system that provides help information online through the
<HELP> key or the help command.
operands
The terms, or elements, in an expression to which the operators are applied.
operator precedence
The order in which the operators in an expression are processed; operators with
higher precedence are processed before operators with lower precedence.
operators
Symbols representing the actions performed on the operands in an expression.
optional argument
An argument for which the operating system does not need a value to execute the
command.
owner
The author of a program module.
page
A unit of virtual storage containing 4096 bytes. A page is the smallest unit of
storage that VOS moves between main storage and secondary storage on a disk.
paging
Dividing a virtual address space into pages and managing pages (reading in from
the disk to main storage and writing out to disk, when necessary) when a process
refers to virtual addresses in the pages. Paging is invisible to users’ programs.
parameter
See macro parameter.
parameter declaration
A line in a command macro that appears between the macro statements
&begin_parameters and &end_parameters.
Glossary-15
Glossary
parameter descriptor
The part of a parameter declaration that specifies certain characteristics of the
parameter.
password
A sequence of characters that a user can be required to supply when logging in.
The characters in a password do not appear on the screen when they are typed in
response to a prompt for a password.
path
An attribute of an object. The object’s path is the sequence of objects (system, disk,
directory) that are superior to the object in the directory hierarchy.
path name
A unique name that identifies a device or locates an object in the directory
hierarchy. See full path name and relative path name.
per-command message file

A message file containing messages unique to one or more .pm (program module)
files. To find a particular per-command message file, the operating system uses the
library paths defined for the message library.
person
An individual who is registered to use a system. A person is specified by a person
name.
person name
The name that identifies a person to the system. When logging in, you must supply
either the person name or the alias by which the system can identify you.
A person name is one of the two parts of a user name.
port
A named logical object that is associated with a file or device in order to provide I/O
access to that file or device. A port is created when it is attached and destroyed
when it is detached.
port attachment
The creation of a port for the purpose of accessing a file or device.
port identifier
A system-generated number corresponding to a port.

Glossary
port name
The name of a port.
positional argument
In the command-line form of a command, an argument that does not have a
keyword.
POSIX
This term refers to the IEEE POSIX standard, which is the system application
program interface. POSIX enables applications written in the C programming
language that conform to part 1 of the IEEE POSIX standard to be ported to VOS
with minimal source code modifications.
predefined value
A value that the operating system makes available for a command argument. If an
argument has only one predefined value, that value is the default.
pre-login process
A process that the Overseer starts for a terminal for which log-in processes are
enabled. From a pre-login process, you can issue only a few commands (such as
login, help, and list_users).
priority level
A number ranging from 0 (the lowest) to 9 (the highest) that determines the
precedence of a process relative to other processes for the allocation of CPU time.
privilege
An attribute of a user allowing him or her to use certain commands, requests, and
subroutines. You can be privileged or not depending on your status as defined in
the registration databases and on how you logged in.
Most users must specify the -privileged argument to the login command in
order to be privileged. However, the system administrator can set the information
in the registration databases so that you are not permitted to give the
-privileged argument, or so that you are automatically logged in as privileged
unless you give the -no_privileged argument.
privileged process
A process of a user who is logged in as privileged.
process
The sequence of states of the hardware and software during the execution of a
user’s programs. When you log in, the operating system creates a process for you
Glossary-17
Glossary
to control the execution of your programs. Your process can create other
processes at your request. A process is always in one of three states: running,
waiting, or ready.
process directory
A directory associated with a process that contains temporary information needed
by the process. The process directories in each module are in the directory
process_dir_dir, which is a subdirectory of the (master_disk) directory.
process language
The national language associated with the current process. A user’s default
process language is defined in that user’s registration entry.
process state
One of the three states – running, waiting, or ready – that a process can be in.
program module
A file produced by the binder from object modules. A program module consists of
executable machine instructions that the loader can convert to an executable
image. A program module name must have the suffix .pm.
program termination
A program terminates when it calls s$stop_program or when it finishes normal
execution and returns to the command processor. Upon termination, the ports
(files) used by the program are closed (and detached, if appropriate) and any locks
locked by the process are unlocked.
queue
A mechanism to record jobs that are waiting to be processed. Jobs can be given
priorities within a queue.
queue priority
A number ranging from 0 (the lowest) to 9 (the highest) that determines where in
the queue a newly issued batch request will be inserted relative to existing
requests.
read access
A type of file access that means a user can read the file or execute it if it is
executable, but cannot write it.
record
The data structure the operating system uses to manage data in a file. For files
other than stream files, a record is the smallest unit of data that the operating

Glossary
system I/O routines can access when performing I/O operations on files or devices.
For stream files, a record consists of unstructured data.
recursion loop
The repetitive execution of the same program.
registration databases
The databases user_registration.sysdb and change_password_sysdb,
which together identify the users who are registered to use a system and the
system resources available to each user. A system administrator uses the
registration_admin command to add to, delete, or change information in
these databases, including person names, passwords, aliases, names of groups
individual users are registered in, and the privileged or non-privileged status of
individual users.
relative path name

A name that identifies a device or an object in the directory hierarchy without
specifying its full path name.
replacement directive
A line of text in an abbreviations file that contains a string to be replaced (called the
input string) and a string to replace it with (called the output string).
required argument
A command argument for which you must specify a value.
restore
To retrieve data from one or more back-up disks or tapes when current data on a
disk are damaged or accidentally deleted. The data are retrieved in the state they
were in at an earlier time. (See back up.)
saved path name

In the line editor, the path name of a file you gave as an argument to the
line_edit command. The editor uses this saved path name as a default name if
you do not specify a path name when you give the request to write out the text
buffer. When you omit the path name from a line_edit command, there is no
saved path name.
search string
In the line editor, the character string the line editor searches for in a text buffer
when you give the change, find, locate, or overlay request. You can specify
a new search string each time you give one of these requests, or you can use the
current search string.
Glossary-19
Glossary
shared programs
Programs that can be shared simultaneously by more than one process. All
programs can be shared, unless users have set up access control or locking
mechanisms to deny access to other users.
shift character
See single shift and locking shift.
shift mode
A text file attribute indicating the types of shift characters in a file. See single shift
and locking shift.
sign
An indication of whether a value is less than or greater than zero.
single shift
A user-transparent character in a key or record, indicating that the next character
is from a character set other than the default.
source module
A text file that can be compiled by a VOS compiler to produce an object module. A
source module is a program written in a computer language.
specific user name

The name of an individual user in a specified group.
star name
A name that contains one or more asterisks or consists solely of an asterisk. A star
name can be used to specify a set of objects. Star names function in the following
manner:
• An asterisk can be in any position in a star name.

• In a path name, a star name can be in the final object name position only.
• When the operating system matches non-star names to a star name, each
asterisk represents zero or more characters.
• No name can contain consecutive asterisks; there must always be an
intervening character.
Some names with asterisks function differently; see module star name and user
star name.

Glossary
star name pair

Two successive star name values for two successive command arguments.
start-up command macro

A command macro named start_up.cm that is usually located in a user’s home
directory. It contains commands and other instructions that tailor the command
environment to the requirements of a particular user. When the user logs in, VOS
runs the command macro before placing the user’s process at command level or
placing it in the subsystem that is specified in the user’s registration entry or named
in the login command’s -subsystem argument.
started process
A process that runs independently of and concurrently with your interactive
process.
status access
A type of directory access that means a user can display information about the
directory, but cannot modify the directory by creating, deleting, or renaming
objects.
status code
A code with an associated name and often an associated line of text. There are four
types of status code:
• error codes, whose names begin with the prefix e$

• message codes, whose names begin with the prefix m$
• query codes, whose names begin with the prefix q$
• request codes, whose names begin with the prefix r$
status line
The last line of your terminal screen. When you press the <STATUS> key, the
operating system displays information about your process on the status line.
string
See character string.
subprocess
An additional user process begun while the former process is suspended but not
terminated. The new subprocess “inherits” several attributes from the former
process, such as priority and access privileges, and the current directory. Each
successive process that you start is a subprocess of the preceding process.
Glossary-21
Glossary
Therefore, you must log out of each new subprocess to return to your original
process.
subroutine
A sequence of statements that can be invoked as a set at one or more points in a
program to execute a specific operation.
subsequent directive
system to replace an input string with an output string when the specified input
string occurs at any point in the command string after the first word.
substring
A character string of any length that occurs within a longer string.
suffix
A character string that begins with a period and is appended to an object name to
indicate the type of the object.
switch
A command argument or macro parameter that can have one of two values, “yes”
or “no.” A switch parameter has the value 1 if its value is “yes” and 0 if its value is
“no.”
symbol directive
system to replace one character in the command string by another.
system
Either a single module that is not connected to other modules, or a group of up to
32 modules located at the same site (the same building or neighboring buildings)
and connected in a local network by means of StrataLINK.
target of a link
The immediate target of a link is the file, directory, or link specified by the link’s path
name. The ultimate target of a link is the file or directory that is the target of the last
link in a chain.
text buffer
In the line editor, a temporary work space that contains the text you are editing. The
operating system does not display this buffer on your screen as it does with the
VOS Word Processing Editor or VOS Emacs, but you can insert text in the buffer
and you can modify existing text with line editor requests.

Glossary
text file
• A sequential, relative, or fixed file that has a character set and shift mode
defined. Characters from more than one character set are permitted in some
text files, with shifts in character set indicated by shift characters. A text file in
any character set supported by the operating system can be edited by Emacs,
but not all text editors support all the character sets. See single shift and
locking shift.
• In VOS Pascal, a file declared with the predefined type text.
unlock
See lock.
user
An individual who is registered to use a system. A user is specified by a user name,
which is made up of a person name and a group name.
user name
An identifier composed of a person name and a group name.
user process
See process.
user star name

A user name containing one or two asterisks that is used to specify a set of users.
When a user attempts to use a file or directory to which an access control list
applies, the operating system checks his or her access by matching user star
names on the list to actual users and groups.
Either component of a user star name (the person name or the group name) can
be an asterisk, or both components can be asterisks. An asterisk as the first
component matches all person names; an asterisk as the second component
matches all group names. In arguments that accept user star names, if you give
only a person name (or only a single asterisk), the operating system appends .*
to the name.
verbose mode
In the line editor, a setting that causes the line editor to print every line that it
modifies or selects with append, change, find, goto, locate, and overlay
requests.
VOS
The virtual operating system of the Stratus computer.
Glossary-23
Glossary
write access
A type of file access that means a user can execute, read, and write the file.

Index Index-
A display_access_list, 9-9
display_default_access_list,
abbreviating
9-10
command arguments, 5-4
give_access, 9-13
command functions, 6-2
give_default_access, 9-15
long command names, 5-4
propagate_access, 9-17
abbreviation parameters, 5-6
remove_access, 9-15
forms of, 5-6
remove_default_access, 9-16
uses for, 5-6
set_owner_access, 9-18
abbreviations, 5-1
verify_posix_access command, 9-19
all directive, 5-4
access control lists, 9-4
disabling, 5-3
deleting an entry, 9-15
expansion, 5-8
displaying entries, 9-9
first directive, 5-4
entries, 9-4
objects you can abbreviate, 5-1
for directories, 9-6
preventing any expansion, 5-8, 7-9
for files, 9-6
preventing partial expansion, 5-8
how they are searched, 9-7
reasons to avoid in macros, 7-9
how they are sorted, 9-5
replacement directives, 5-3
inserting an entry, 9-13
steps in expansion, 5-8
updating entries, 9-17, 9-18
subsequent directive, 5-4
access rights
symbol directive, 5-5
for directories, 9-4
abbreviations file, 5-2
for files, 9-3
compiling into abbreviations table, 5-3
add_library_path command, 4-10, 4-11,
exceeding compilation size limit, 5-3
7-39
more than one, 5-3
after batch directive, 8-4
sample, 5-2
after command function, 6-6, C-4
abs command function, 6-8, C-3
all replacement directives, 5-4
absolute values, C-3
allotting CPU time to batch process, 8-4
access
allow parameter descriptor qualifier, 7-16
displaying, 9-8
ampersands
how it is determined, 9-7
as variable name delimiters, 7-11
managing, 9-12
in macro statements, 7-4, D-1
access codes
special treatment in macros, 7-6
for directories, C-3
to specify macro comment lines, 7-4
for files, C-3
analyze_system command, F-2
access command function, 6-9, C-3
analyzing programs, A-14
access control, 9-1
apostrophes
access control commands, A-2
added by quote command function, C-29
access required to issue, 9-8, 9-13
enclosing a batch command line, 8-1
display_access, 9-10
enclosing a character string, 2-7, 8-5
Index-1
Index
enclosing a command function, 4-12, 7-7 wait_on_module, 8-5

enclosing a started process command batch processes, 8-1
line, 8-6 batch processing commands, A-1
enclosing abbreviations, 5-8 cancel_batch_requests, 8-6
enclosing the value of a macro cancel_device_reservation, 8-6
variable, 7-12 display_batch_status, 8-6
in a library path command argument, 4-12 list_batch_requests, 8-2, 8-6
in command macros, 7-7 move_device_reservation, 8-6
removed by unquote command reserve_device, 8-6
function, C-35 update_batch_requests, 8-6
within a character string, 2-7, 7-7 batch processor, 8-1
append line editor request, E-10 batch queue_priority, 8-2
arithmetic expressions, C-7 batch queues, 8-1
ASCII characters, C-6 batch requests, 8-1
ASCII collating sequence, C-6 listing, 8-2
ask command function, 6-5, C-4 process priority, 8-3
assignment statements, 7-10 queue_priority, 8-2
associating terms in an expression, C-9 before command function, 6-6, C-6
asterisks begin_parameters macro statement, D-5
in file names, 2-7 binary integers, C-11, C-14
to specify a user star name, 9-5 binding programs, A-14
attach input macro statement, 7-5 bottom line editor request, E-11
attach_default_output command, 1-4, break command function, 6-7, C-6
F-2 break level, 1-2, 2-4, B-1
attach_input macro statement, 1-4, D-3, break level commands, A-2, B-1
F-2 continue, B-2
attach_port command, 1-5 keep, B-3
avoiding double abbreviation evaluation, 7-17 re-enter, B-3
avoiding macro recursion loops, 7-38 stop, B-2
break macro statement, D-6
B byte command function, 6-5, C-6
byte parameter descriptor qualifier, 7-16
backing up files, A-10
batch command, 8-1
command_line argument, 8-3
C
control argument, 8-3 calc command function, 6-5, C-6
batch control files, 8-3 calculating an expression, C-6
directives, 8-4 cancel_batch_requests command, 8-2,
example, 8-4 8-6
batch directives cancel_device_reservation
after, 8-4 command, 8-6
cpu_limit, 8-4 ceil command function, 6-8, C-10
defer_until, 8-4 change line editor request, E-11
end, 8-4 changing directories, A-10
notify, 8-5 changing your password, 1-7
output_path, 8-5 character string values, 2-7
process_name, 8-5 in command-line forms, 2-7
process_priority, 8-5 in display forms, 2-7
wait_on, 8-5 including apostrophes in, 2-7, 7-7
Index-2 VOS Commands User’s Guide (R089)

Index
character strings, 6-2, C-2 has_access, 6-9, C-17

command arguments, 2-1 hexadecimal, 6-8, C-18
cycle values, 2-2 home_dir, 6-3, C-19
default values, 2-2 index, 6-7
displaying in comand-line forms, H-4 informational, 6-3
displaying in display forms, 2-4 iso_date, 6-3, C-19
entering character string values, 2-7 iso_date_time, 6-3, C-20
keywords, 2-3 language_name, 6-3, C-21
labels, 2-3 length, 6-7, C-21
numerical arguments, 2-3 lock type, C-22
optional, 2-2 lock_type, 6-9
positional, 2-4, 2-5 locked, 6-9, C-22
predefined values, 2-2, 2-6 ltrim, 6-7, C-22
required, 2-2 master_disk, 6-3, C-23
switches, 2-2, 2-6 max, 6-8, C-23
command functions, 6-1, C-1 message, 6-4, C-23
abs, 6-8, C-3 min, 6-9, C-24
access, 6-9, C-3 mod, 6-9, C-25
after, 6-6, C-4 module info, 6-4
ask, 6-5, C-4 module_info, C-25
before, 6-6, C-6 module_name, 6-4, C-25
break, 6-7, C-6 numeric values, 6-8
brief descriptions, 6-2 object_name, 6-6, C-26
byte, 6-5, C-6 online, 6-4, C-26
calc, 6-5, C-6 path_name, 6-6, C-26
calculations, 6-5 person_name, 6-4, C-27
categories of, 6-1 process_dir, 6-4, C-27
ceil, 6-8, C-10 process_info, 6-4, C-27
command_status, 6-3, C-10 process_type, 6-4, C-28
complete list, C-1 quote, 6-7, C-29
concat, 6-7, C-10 rank, 6-6, C-29
contents, 6-9, C-11 referencing_dir, 6-4, C-30
copy, 6-7, C-11 returning date time values, G-1
count, 6-7, C-11 reverse, 6-7, C-30
current dir, 6-3 rtrim, 6-7, C-30
current_dir, C-12 search, 6-7, C-30
current_module, 6-3, C-12 software_purchased, 6-4, C-31
data types of returned values, 6-2 string, 6-7, C-31
date, 6-3, C-12 string manipulations, 6-6
date_time, 6-3 substitute, 6-8, C-31
decimal, 6-8, C-14 substr, 6-8, C-32
directory_name, 6-5, C-15 system_name, 6-4, C-32
end_of_file, 6-9, C-15 terminal_info, 6-4, C-32
exists, 6-5, C-15 terminal_name, 6-5, C-33
file_info, 6-9, C-16 time, 6-5, C-33
files and directories, 6-9 translate, 6-8, C-34
floor, 6-8 trunc, 6-9, C-35
given, 6-5, C-17 unique_string, 6-6, C-35
group_name, 6-3, C-17 unquote, 6-8, C-35
Index-3
Index
user_name, 6-5, C-36 for communicating with other users, A-7

verify, 6-8, C-36 for compiling and binding programs, A-14
where_path, 6-6, C-36 for controlling access, A-2
command level, 4-1, F-2 for controlling directory access, A-4
command library, 4-3 for controlling file access, A-3
command lines, 2-1, 7-3 for controlling system access, A-5
command macros, 4-2 for converting files, A-10
assignment statements, 7-10 for creating synonyms, A-5
attachment of command_input port, F-2 for customizing your environment, A-5
attachment of default_input port, F-2 for debugging programs, A-16
command-line form, 7-3 for displaying access, A-3
comment lines, 7-4 for displaying files, A-12
display form, 7-3, 7-19 for executing programs, A-17
elements of, 7-3 for getting device information, A-7
examples, 7-2, 7-41 for getting directory information, A-11
halting execution, B-1 for getting file information, A-11
how they are processed, 7-37 for getting on and off the system, A-8
how to issue, 7-3 for getting print request information, A-14
line continuation characters, 7-6 for getting printer information, A-13
naming, 7-2 for getting started, A-6
parameter declarations, 7-13 for getting status information, A-8
parameter descriptors, 7-14 for getting system information, A-7
parameters, 7-12, 7-13 for halting execution, B-1
providing input to programs, 7-5 for locating directories, A-12
punctuation, 7-5 for locating files, A-12
separators, 7-6 for managing directories, A-9
start_up, 7-38 for managing files, A-9
use of space characters, 7-5 for managing ports, A-12
variables, 7-10 for managing POSIX, A-13
command name text file, 3-5 for printing files, A-14
command name tin file, 3-5 for processing tapes, A-19
command processing for programming, A-14
identifying an object, 4-2 for setting up program libraries, A-5
search rules, 4-4 for setting up your process
command processing loop, 4-1 environment, A-5
command status process variable, C-10 for setting up your terminal, A-6
command strings, 2-1, 7-3 for writing programs, A-19
command_input port, F-2 internal, 4-2
command_status command function, 6-3, program modules, 4-2
C-10 system administration, A-19
command-line form of commands, 2-4 types of, 4-2, 7-3
commands commas
available at break level, B-1 preceding a parameter descriptor default
command macros, 4-2 value, 7-18
for analyzing programs, A-14 preceding a parameter descriptor
for backing up and restoring files, A-10 qualifier, 7-16
for batch processing, A-1 comment lines in command macros, 7-4
for break and interrupt processing, A-2 communicating with other users, A-7
for changing directories, A-10 comparing directories, A-11

Index
comparing files, A-12 declaring macro parameters, 7-13

compiling an abbreviations file, 5-3 declaring macro variables, 7-10
compiling programs, A-14 default access control lists, 9-6
concat command function, 6-7, C-10 deleting an entry, 9-16
contents command function, 6-9, C-11 displaying entries, 9-10
continue command, B-1, B-2 how entries are created, 9-7
continue macro statement, D-7 inserting an entry, 9-15
control macro statement, D-8 searching, 9-7
controlling access, 9-1, A-2 updating entries, 9-17, 9-18
controlling directory access, A-4 default argument values, 2-2
controlling file access, A-3 default priority level, 1-2
controlling system access, A-5 default_input port, 1-4, F-1
converting files, A-10 default_output port, 1-4, D-12, F-2
copy command function, 6-7, C-11 defaults in a parameter descriptor, 7-17, 7-23
copy line editor request, E-11 defer_until batch directive, 8-4
copying directories, A-10 deferring a batch process, 8-4
copying files, A-11 delete line editor request, E-12
count command function, 6-7, C-11 delete_library_path command, 4-10
cpu_limit batch directive, 8-4 deleting directories, A-10
creating a batch control file, 8-4 deleting files, A-10
creating a port, 1-5 detach_default_output command, 1-4,
creating a privileged process, 1-3 F-2
creating a subprocess, 1-2 detach_input macro statement, 1-4, 7-5,
creating directories, A-10 D-9
creating files, A-10 detach_port command, 1-5
creating synonyms, A-5 device information commands, A-7
CTRL_BREAK request, B-1 device_name parameter data type, 7-28
current line, E-4 directory access control lists, 9-6
current search string, E-4 deleting an entry, 9-15
current_dir as a library path, 4-7 displaying entries, 9-9
current_dir command function, 6-3, C-12 how entries are created, 9-6
current_module command function, 6-3, inserting an entry, 9-13
C-12 searching, 9-8
customizing your environment, A-5 updating entries, 9-17
CYCLE key, 2-2 directory access rights
cycle values, 2-2 modify, 9-4
CYCLE_BACK key, 2-2 null, 9-4
status, 9-4
D directory_name command function, 6-5,
C-15
date command function, 6-3, C-12 disable_input parameter descriptor
date strings, G-1 qualifier, 7-16
date time strings, G-1 disabling abbreviations, 5-3
date_time command function, 6-3 display command, 7-39
date_time parameter data type, 7-27 display form of commands, 2-3
debug command, B-1 display_access command, 9-10
debugging programs, A-16 display_access_list command, 9-9
decimal command function, 6-8, C-14 display_batch_status command, 8-6
decimal integers, C-11, C-14
Index-5
Index
display_default_access_list conversions, C-8

command, 9-10 in command macros, 7-9
display_file_status command, 9-18 logical, C-7
DISPLAY_FORM key, 2-3, 2-4 operands, C-6
display_line command, 7-39 operators, C-6, C-7
display_line macro statement, D-10 precedence of operators, C-8
display_line_partial macro rules for writing, C-9
statement, D-12 strings, C-7
display_notices command, 7-39 use of apostrophes, C-9
displaying access, 9-8, A-3, C-3 use of parentheses, C-9
to files and directories, 9-9, 9-10 use of spaces, C-9
to files in a directory, 9-10
displaying files, A-12 F
do macro statement, D-13
dollar signs in command macros, 7-8 false expressions, C-7
double ampersands, 7-6 file access control lists, 9-6
double apostrophes, 2-7, 7-7, C-35 deleting an entry, 9-15
DOWN ARROW key, 2-3 displaying entries, 9-9
how entries are created, 9-6
inserting an entry, 9-13
E searching, 9-7
echo macro statement, D-15 file access rights
edit state, E-3 execute, 9-3
editing files in a macro, E-1 null, 9-3
editing text, A-6 read, 9-3
else clause, D-25 write, 9-3
end batch directive, 8-4 file_info command function, 6-9, C-16
end macro statement, D-17 final substrings, 6-2, C-2, C-4
end qualifiers, 7-37, D-18 find line editor request, E-12
end_of_file command function, 6-9, C-15 first replacement directives, 5-4
end_parameters macro statement, D-18 floating point arithmetic, C-8
ENTER key, 2-3, 2-4 floor command function, 6-8
eof macro statement, D-20 form feed characters, 7-5
error codes dd file, 3-5 form of a date time input string, G-1
error messages, 3-4 form of a macro statement, 7-4
error port, 1-4 form of a parameter declaration, 7-13
eval macro statement, D-21 form of a parameter descriptor, 7-14
exclamation points form option, 2-4
in command macros, 7-7
preceding abbreviations, 5-8 G
executable image of a program, B-3
execute access, 9-3, C-3 getting information
executing programs, A-17 about batch queues, 8-6
exists command function, 6-5, C-15 about batch requests, 8-6
expanding abbreviations, 5-8 about devices, A-7
expiration of passwords, 1-7 about directories, A-11
expressions, C-6 about files, A-11
arithmetic, C-7 about print requests, A-14
calculations, C-8 about printers, A-13

Index
about the system, A-7 insert default buffer, 2-4

about your process, 1-2 insert line editor request, E-12
getting on and off the system, A-8 insert saved buffer, 2-4
getting online help, H-2 INSERT_DEFAULT key, 2-4
getting status information, A-8 INSERT_SAVED key, 2-4
give_access command, 9-13 integers
give_default_access command, 9-15 allowed by copy, C-11
given command function, 6-5, C-17 binary, C-11, C-14
giving a password, 1-6 corresponding ascii characters, C-6
giving arguments with line editor requests, E-5 decimal, C-11, C-14
giving commands hexadecimal, C-11, C-14
in the command-line form, 2-4 octal, C-11, C-14
in the display form, 2-3 rank in ASCII sequence, C-29
goto line editor request, E-12 returned by decimal, C-14
goto macro statement, D-23 interactive processes, 1-1
group names, 9-5 attachment of predefined ports, F-1
group_name command function, 6-3, C-17 specifying priority, 1-3
internal commands, 4-2
H interrupting a process, A-2
iso_date command function, 6-3, C-19
halting a started process, 8-6 iso_date_time command function, 6-3,
halting command macro execution, B-1 C-20
halting program execution, B-1 issuing a command macro, 7-3
has_access command function, 6-9, C-17 issuing commands
help files in the command-line form, 2-4
writing, H-6 in the display form, 2-3
help information
for command functions, H-4
for commands, H-1, H-3
J
online, H-1 join line editor request, E-13
requesting, H-2
tasks, H-3 K
HELP key, H-2, H-4, H-5
help subsystem, H-2, H-3 keep command, B-1, B-3
hexadecimal command function, 6-8, C-18 keywords, 2-3
hexadecimal integers, C-11, C-14
hidden parameter descriptor qualifier, 7-16 L
home_dir as a library path, 4-12 label macro statement, D-28
home_dir command function, 6-3, C-19 labels, 2-3
horizontal tab characters, 7-5 labels in parameter descriptors, 7-14
language_name command function, 6-3,
I C-21
if macro statement, D-25 LEFT ARROW key, 2-2, 2-3
include library, 4-3 length command function, 6-7, C-21
index command function, 6-7 length parameter descriptor qualifier, 7-16
infix operators, C-6 libraries, 4-3
initial substrings, 6-2, C-2, C-6, C-11 library path commands
input lines in command macros, 7-5 add_library_path, 4-10, 4-11
input state, E-4 delete_library_path, 4-10
Index-7
Index
list_library_paths, 4-10 line_edit command, D-4, E-1

set_library_path, 4-10, 4-11 list_batch_requests command, 8-2, 8-6
library paths, 4-4 list_library_paths command, 4-10
adding a directory, 4-10, 4-11 list_port_attachments command, 1-5
changing the order of directories, 4-10, listing arguments of a command, H-4
4-11 listing batch requests, 8-2
defining new directories, 4-10, 4-11 listing library paths
deleting a directory, 4-10 for a module, 4-7
displaying the modules default list, 4-7 for your process, 4-10
listing the directories, 4-10 listing port attachments, 1-5
message library, 3-7 locate line editor request, E-13
line editor, E-1 locating directories, A-12
character string delimiter, E-9 locating files, A-12
current line, E-4 lock_type command function, 6-9, C-22
current search string, E-4 locked command function, 6-9, C-22
edit state, E-3 logical expressions, C-7
going to break level, E-7 login command, 1-2, B-1
halting an infinite loop, E-7 login failures, 1-6
input state, E-4 logout command, 1-2
line numbers, E-2 longword parameter descriptor qualifier, 7-16
mode requests, E-3 ltrim command function, 6-7, C-22
printing the current line, E-10
repeating requests, E-7 M
saved path name, E-2
setting the current line, E-10 macro parameters, 7-13
text buffer, E-1 declaring, 7-13
upward qualifier, E-6 default characteristics, 7-14
line editor modes, E-2 default_values, 7-17
line editor requests descriptors, 7-14
append, E-10 labels, 7-15
bottom, E-11 optional, 7-21
change, E-11 positional, 7-18
copy, E-11 qualifiers, 7-16
delete, E-12 specifiers, 7-15
find, E-12 switch, 7-24
goto, E-12 types, 7-18
insert, E-12 uses, 7-14
join, E-13 macro processor, 7-3
locate, E-13 macro punctuation, 7-5
mode, E-13 ampersand, 7-6
move, E-13 apostrophes, 7-7
overlay, E-13 dollar sign, 7-8
path, E-14 double ampersands, 7-6
print, E-14 exclamation point, 7-7
quit, E-14 line continuation characters, 7-6
read, E-14 macro recursion loops, 7-38
skip, E-15 macro statements, 7-4, D-1
tab, E-15 attach_input, D-3
write, E-16 begin parameters, D-5

Index
break, D-6 mode line editor request, E-13

continue, D-7 mode macro statement, D-29
control, D-8 modify access, 9-4, C-3
detach_input, D-9 module_info command function, 6-4, C-25
display line, D-10 module_name command function, 6-4, C-25
display_line_partial, D-12 module_name parameter data type, 7-29
do, D-13 move line editor request, E-13
echo, D-15 move_device_reservation command, 8-6
else, D-25 moving directories, A-10
end, D-17 moving files, A-11
end_parameters, D-18
eof, D-20 N
eval, D-21
goto, D-23 name parameter data type, 7-29
if, D-25 naming a batch process, 8-5
label, D-28 naming a command macro, 7-2
mode, D-29 naming a port, 1-5
return, D-31 national language support, 3-1
set, D-32 error messages, 3-4
set_string, D-34 languages configured, 3-2, 3-3
then, D-25 module default language, 3-2
while, D-36 process language, 3-2
macro variables, 7-10 text files, 3-3
character string data types, 7-11 no_abbrev parameter descriptor
declaring, 7-10 qualifier, 7-17
name delimiter, 7-11 noform parameter descriptor qualifier, 7-17
numeric data types, 7-10 noninteractive processes, 8-1
uses, 7-11 attachment of default_output port, F-2
managing access, 9-12 attachment of terminal_output
for processes executing your program port, F-2
modules, 9-18 batch processes, 8-1
to files in your directories, 9-15, 9-16, 9-17 detachment of terminal port, F-2
to your files and directories, 9-13, 9-15, started processes, 8-6
9-17 notify batch directive, 8-5
managing your terminal, A-21 null access, C-3
mapcase mode, E-2 to directories, 9-4
master_disk command function, 6-3, C-23 to files, 9-3
matching user names, 9-5 number parameter data type, 7-30
max command function, 6-8, C-23 numbers mode, E-3
max parameter descriptor qualifier, 7-17 numerical arguments, 2-3
maximum priority level, 1-3
message command function, 6-4, C-23 O
message library, 3-7, 4-3 object library, 4-3
messages object_name command function, 6-6, C-26
per-command, 3-4 octal integers, C-11, C-14
system, 3-4 online command function, 6-4, C-26
min command function, 6-9, C-24 online help, H-1
min parameter descriptor qualifier, 7-17 operands, C-6
mod command function, 6-9, C-25 operator precedence, C-7
Index-9
Index
operators, C-6 required, 7-17

infix, C-6 word, 7-17
order of evaluation, C-8 parameter descriptors, 7-14
prefix, C-6 default_values, 7-17
optional command arguments, 2-2 general form, 7-14
optional macro parameters, 7-21 labels, 7-15
data types, 7-21 qualifiers, 7-16
form of specifier, 7-15, 7-21 specifiers, 7-15
forms for default values, 7-18 parameters in abbreviations, 5-6
special default indicators, 7-23 parentheses
use of labels, 7-15 in a command function, 6-2
output_path batch directive, 8-5 in an expression, C-9
output_path parameter descriptor passwords, 1-6
qualifier, 7-17 changing, 1-7
overlay line editor request, E-13 expiration of, 1-7
owner access switches, 9-18 punctuation characters in, 1-7
path line editor request, E-14
P path_name command function, 6-6, C-26
pathname parameter data type, 7-31
parameter data types, 7-26 person names, 9-5
date_time, 7-27 person_name command function, 6-4, C-27
device_name, 7-28 PL/I operators, C-8
for optional parameters, 7-21 port identifiers, 1-5, F-1
for positional parameters, 7-19 port management commands, A-12
module_name, 7-29 ports, 1-4
name, 7-29 attaching, 1-5
number, 7-30 command_input, F-2
pathname, 7-31 default_input, 1-4, F-1
starname, 7-32 default_output, 1-4, F-2
string, 7-33 detaching, 1-5
system_name, 7-34 error, 1-4
unclaimed, 7-34 listing attachments, 1-5
user_name, 7-36 maximum allowed per process, 1-5
parameter declaration sections, 7-13 terminal, C-4, F-2
parameter declarations, 7-13 terminal_output, C-4, F-2
parameter descriptor qualifiers, 7-16 positional command arguments, 2-4
allow, 7-16 determining correct order, 2-5
byte, 7-16 how to specify, 2-5
disable_input, 7-16 with predefined values, 2-6
hidden, 7-16 positional macro parameters, 7-18
length, 7-16 data types, 7-19
longword, 7-16 form of default value, 7-18
max, 7-17 form of specifier, 7-15, 7-18
min, 7-17 use of labels, 7-15
no_abbrev, 7-17 POSIX commands, A-13
noform, 7-17 precedence
output_path, 7-17 for batch processes, 8-3
req_for_form, 7-17 for interactive processes, 1-2
for operators, C-7

Index
precision of floating point arithmetic, C-8 queue_priority, 8-2

predefined argument values, 2-2 quit line editor request, E-14
a single value, 2-6 quote command function, 6-7, C-29
default value, 2-2
how to select one, 2-6 R
several values, 2-6
predefined ports, 1-4 rank command function, 6-6, C-29
attachments of, F-3 read access, 9-3, C-3
command_input, F-2 read line editor request, E-14
conventions for system use, F-1 recursion loop in a command macro, 7-38
default_input, 1-4, F-1 re-enter command, B-1, B-3
default_output, 1-4, F-2 referencing_dir command function, 6-4,
port identifiers, F-1 C-30
terminal, F-2 remove_access command, 9-15
terminal_output, F-2 remove_default_access command, 9-16
prefix operators, C-6 renaming directories, A-10
print line editor request, E-14 renaming files, A-11
printing commands, A-13 repeating line editor requests, E-7
printing files, A-14 replacement directives
priority levels, 1-2 all, 5-4
of a batch process, 8-3 first, 5-4
of an enqueued batch request, 8-2 general form, 5-3
of an interactive process, 1-2 input string, 5-2
privileged processes, 1-3 output string, 5-2
process priority, 1-2, 8-3 parameters in first directive, 5-6
process_dir command function, 6-4, C-27 subsequent, 5-4
process_info command function, 6-4, C-27 symbol, 5-5
process_name batch directive, 8-5 types, 5-3
process_priority batch directive, 8-5 req_for_form parameter descriptor
process_type command function, 6-4, C-28 qualifier, 7-17
processes, 1-1 required command arguments, 2-2
started, 8-6 required parameter descriptor qualifier, 7-17
subprocess, 1-1 reserve_device command, 8-6
user, 1-1 reserving devices for batch processes, 8-5
processing of commands, 4-1 restoring files, A-10
program execution, A-17 retrieving a command line, 2-4
program input in command macros, 7-5 RETURN key, 2-3, 2-4
program module owner access switches, 9-18 return macro statement, D-31
program modules, 4-2 reverse command function, 6-7, C-30
programming, A-14 RIGHT ARROW key, 2-2, 2-3
prompting message, 4-1 rtrim command function, 6-7, C-30
propagate_access command, 9-17 rules for determining access, 9-7
punctuation in command macros, 7-5 for directories, 9-8
for files, 9-7
Q
qualifiers in parameter descriptors, 7-16
qualifying parameters in declaration
section, 7-37
Index-11
Index
S status access, 9-4, C-3

STATUS key, 1-2
saved path name, E-2
status line, 1-2
search command function, 6-7, C-30
steps in expanding abbreviations, 5-8
search rules, 4-4
steps in processing a command macro, 7-37
adding a library directory, 4-10, 4-11
steps in processing of commands, 4-1
changing for a module, 4-7
stop command, B-1, B-2
changing for your process, 4-10
stop_process command, 8-6
changing the order of library
string command function, 6-7, C-31
directories, 4-10, 4-11
string expressions, C-7
defining new library directories, 4-10, 4-11
string parameter data type, 7-33
deleting a library directory, 4-10
subprocesses, 1-1
listing the library paths, 4-10
subsequent replacement directives, 5-4
order of precedence, 4-6
substitute command function, 6-8, C-31
semicolons
substr command function, 6-8, C-32
ending batch control file directives, 8-3
substrings, 6-2, C-2, C-4, C-6
separating command strings, 2-1
final, C-2, C-4
separating line editor requests, E-5
initial, C-2, C-6
separators in command macros, 7-6
suffixes
set macro statement, 7-10, C-9, D-32
.cm, 4-2
set_default_library_paths
examples of, 7-19
command, 4-8
in optional parameter descriptors, 7-21
set_library_paths command, 4-10, 4-11
in positional parameter descriptors, 7-19
set_owner_access command, 9-18
.kp, B-3
set_string macro statement, 7-11, D-34
.obj, 4-3
.pm, 4-2, B-3
command, 7-39
suppressing abbreviations, 7-9
setting up program libraries, A-5
switch command arguments, 2-2
setting up your process environment, A-5
how to specify, 2-6
setting up your terminal, A-6
negative format, 2-6
skip line editor request, E-15
switch macro parameters, 7-24
software_purchased command
default values, 7-25
function, 6-4, C-31
form of default value, 7-18
sorting files, A-12, A-19
form of specifier, 7-16, 7-25
space characters, 7-5
negative format, 7-24
spaces in command macros, 7-5
use of labels, 7-15
spaces in command strings, 2-1
symbol replacement directives, 5-5
specific user names, 9-5
system administration commands, A-19
specifiers in parameter descriptors, 7-15
system administrator
specifying batch process_priority, 8-5
defining access, 9-1
specifying batch queue_priority, 8-2
defining password format, 1-7
specifying interactive process priority, 1-3
setting login limitations, 1-6
star name pairs, 2-7
system directory, 4-3
starname parameter data type, 7-32
system generated files, 1-3
start up command macros, 7-38
system information commands, A-7
examples, 7-39
system_name command function, 6-4, C-32
typical uses, 7-39
system_name parameter data type, 7-34
start_process command, 8-6
started processes, 8-6

Index
T V
TAB key, 2-3 verbose mode, E-3
tab line editor request, E-15 verify command function, 6-8, C-36
tape processing, A-19 verify_posix_access command, 9-19
tape processing commands, A-19 vertical tab characters, 7-5
terminal management commands, A-21
terminal port, F-2 W
terminal_info command function, 6-4,
C-32 wait_on batch directive, 8-5
terminal_name command function, 6-5, wait_on_module batch directive, 8-5
C-33 where_path command function, 6-6, C-36
terminal_output port, C-4, F-2 while macro statement, D-36
terminal_port, C-4 word parameter descriptor qualifier, 7-17
text buffer, E-1 write access, 9-3, C-3
text editing commands, A-6 write line editor request, E-16
then clause, D-25 writing programs, A-19
time command function, 6-5, C-33
time strings, G-1
complete input formats, G-3
partial input formats, G-3
time zones, G-3
translate command function, 6-8, C-34
true expressions, C-7
trun command function, C-35
trunc command function, 6-9
types of commands, 4-2, 7-3
U
unclaimed parameter data type, 7-34
undefined access, C-3
unique_string command function, 6-6,
C-35
unquote command function, 6-8, C-35
UP ARROW key, 2-3
update_batch_requests command, 8-2,
8-6
upward line editor qualifier, E-6
usage option, H-4
use_abbreviations command, 5-3, 7-39
error message, 5-3
off argument, 5-3
user names, 9-4
components, 9-5
order in an access control list, 9-5
user process priority, 1-2
user star names, 9-5
user_name command function, 6-5, C-36
user_name parameter data type, 7-36
Index-13
Index

r089 03

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

r089 03

Uploaded by

Copyright:

Available Formats

VOS Commands User’s Guide

The information contained in this document is subject to change without notice.

UNLESS EXPRESSLY SET FORTH IN A WRITTEN AGREEMENT SIGNED BY AN AUTHORIZED

RSN is a trademark of Lucent Technologies, Inc.

Manual Name: VOS Commands User’s Guide

Part Number: R089

Stratus Technologies, Inc.

© 2002 Stratus Technologies International, S.à r.l. All rights reserved.

1. User Processes and Passwords 1-1

2. Understanding the Command Language 2-1

Arguments with Several Predefined Values 2-6

3. National Language Support 3-1

4. How the System Processes Commands 4-1

5. Using Abbreviations 5-1

iv VOS Commands User’s Guide (R089)

6. Introduction to Command Functions 6-1

7. Using Command Macros 7-1

Parameter Types 7-18

8. Executing Noninteractive Processes 8-1

9. Understanding Access Control 9-1

vi VOS Commands User’s Guide (R089)

The remove_access Command 9-15

Appendix A. Commands Grouped by Task A-1

Appendix B. Halting Program Execution B-1

Appendix C. Command Function Reference C-1

viii VOS Commands User’s Guide (R089)

Appendix D. Macro Statement Reference D-1

x VOS Commands User’s Guide (R089)

Appendix E. Using the Line Editor E-1

Appendix F. Predefined Ports F-1

Appendix G. Specifying Dates and Times G-1

Appendix H. Using the Online Help Facility H-1

xii VOS Commands User’s Guide (R089)

Figure 4-1. Library Directories in the system Directory 4-4

Table 5-1. Special Replacement Characters in Symbol Directives 5-5

xiv VOS Commands User’s Guide (R089)

Table F-12. Attachments When a Noninteractive Process Executes a

xvi VOS Commands User’s Guide (R089)

This revision incorporates the following changes.

• New format and complete manual reorganization.

• Documentation of the following command functions in Appendix C:

• Documentation of the following command macro statements in Appendix D:

• Support for nested &if-&then-&else statements and stricter syntax-checking

Chapter 2, ‘‘Understanding the Command Language,” explains how to specify

Chapter 3, ‘‘National Language Support,” explains the effects of National Language

Chapter 5, ‘‘Using Abbreviations,” explains how to use the abbreviations facility to

xviii VOS Commands User’s Guide (R089)

Chapter 6, ‘‘Introduction to Command Functions,” introduces the command functions

Chapter 7, ‘‘Using Command Macros,” describes how to create command macros so

Chapter 8, ‘‘Executing Noninteractive Processes,” describes how to do non interactive

Chapter 9, ‘‘Understanding Access Control,” describes access control. Using the

Appendix A, ‘‘Commands Grouped by Task,” contains a list of VOS commands

Appendix B, ‘‘Halting Program Execution,” describes how to halt program execution

Appendix C, ‘‘Command Function Reference,” provides detailed descriptions of the

Appendix D, ‘‘Macro Statement Reference,” provides detailed descriptions of the VOS

• Introduction to VOS (R001)

• Italics introduces or defines new terms. For example:

• Boldface emphasizes words in text. For example:

xx VOS Commands User’s Guide (R089)

Key Mappings for VOS Functions

CANCEL <F18> *† *† <5> † or * † <F18>

<F17> <F12> <Alt>-<C> <4> †

CYCLE BACK <Shift>-<F17> <Shift>-<F12> <Alt>-<B> <7> † <Shift>-<F17>

CANCEL <F18> † † <5> † or * † <F18>