Beruflich Dokumente
Kultur Dokumente
Stratus Technologies
R089-03
Notice
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.
Preface xvii
Contents iii
Contents
Contents v
Contents
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
(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
Contents xi
Contents
Glossary Glossary-1
Index Index-1
Figures xiii
Tables
Tables xv
Tables
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.
Preface xvii
Preface
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 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.
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:
Notation Conventions
This manual uses the following notation conventions.
• 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
• 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 *.*
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
Preface xxi
Preface
IBM PC or
V103 V103 Compatible V105 V105
VOS Function ASCII EPC PC PC/+ 106 ANSI
† Numeric-keypad key
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
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
Notation Meaning
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.
Notation Meaning
argument_1... Required argument for which you can specify multiple values.
[argument_1]... Optional argument for which you can specify multiple values.
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.
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.
(Privileged) Only a privileged process can specify a value for this argument.
Preface xxv
Preface
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.
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.”
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.
• 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.
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.
• ‘‘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:
You can specify that the new process can run on any module to which you have
access.
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).
• 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.
• 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:
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:
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.
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.
To reattach the port to its previous attachment (the terminal), use the
detach_default_output command.
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.
See Chapter 7 for information about command macros, and Appendix D for a
description of the &attach_input and &detach_input statements.
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.
• 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:
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.
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.
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.
• 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.
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:
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”
• ‘‘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.
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).
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.”
• ‘‘Display Form”
• ‘‘Command-Line Form”
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.
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.
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:
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:
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.
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.
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.
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.
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.
For example, suppose the current directory contains the following files:
report.cobol
compress.cobol
fast_sort.pl1
fast_sort.obj
fast_sort.pm
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.
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.
• 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:
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.
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.
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.
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.
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.
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.
You need to make only one message_file.dd file for your per-command message
files.
* 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.
/ =num -4
=name e$format_error
=text 'Incorrect record format.'
=category
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.
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.
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.
• 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:
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
(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 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
Object not
found
tx045a
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
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:
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.pm in
command_library?
file.cm in
tools_library?
file.pm in
tools_library?
Object not
found tx046
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.
• 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.
The commands that change the list of library paths for your own processes are:
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
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:
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:
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.
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.
• ‘‘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.
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.
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.
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:
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.
• first
• subsequent
• all
• symbol
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.
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:
(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.
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.
all HD by (home_dir)
The string HD is the input to the directive; the value of (home_dir) is the output.
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
* 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.
Using Abbreviations 5-5
Types of Replacement Directives
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.
• 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.
&n&
&fn&
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:
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:
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:
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:
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.
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:
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:
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.
• 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.
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.
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
• 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
Brief Descriptions
The following table shows the symbols used in this section and the meaning of each
symbol.
Symbol Meaning
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
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.
(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.
(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.
(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.
(rank C)
Returns the integer rank in the ASCII collating sequence of the character specified
by C.
(unique_string)
Returns a unique character string.
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.
(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.
(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.
(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
expressed as a binary, octal, decimal, or hexadecimal integer.
(max N1 N2)
Returns the larger of the two values specified in the arguments N1 and N2.
(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.
(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.
(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.
This chapter contains information on using the VOS command macros and contains
the following sections:
The command macro statements are discussed in this chapter, but not described fully.
See Appendix D for complete information about them.
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.
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.
• 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.
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:
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
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:
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
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.
• 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.
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:
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:
Apostrophes
There are two circumstances that require apostrophes in macros:
• 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:
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.
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.
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
!detach_default_output
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:
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:
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.
In each of these circumstances, the value of the expression is evaluated by the (calc)
command function.
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:
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.
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.
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.
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&
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:
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:
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.)
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]
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
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.
&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:
• 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:
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.
parameter_data_type [suffix]
option(option_keyword),parameter_data_type [suffix]
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)]
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.
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.
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.
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]
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.
.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:
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
Display Form
----------------------------------- compile ------------------------------------
input_file:
output_file:
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.
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.
&begin_parameters
pn file_name:pathname,required
ma character_string:option(match),string,=''
&end_parameters
option(match),string
It has the following elements:
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:
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
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:
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:
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.
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
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 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.
switch(line_numbers)
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:
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.
The description of each data type includes a list of the qualifiers allowed with that data
type.
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.
&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
&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)
The following qualifiers are valid for a parameter of this data type:
allow
disable_input
hidden
length
no_abbrev
noform
required
req_for_form
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)
The following qualifiers are valid for a parameter of this data type:
allow
disable_input
hidden
length
no_abbrev
noform
required
req_for_form
The following example shows a parameter descriptor specifying that the expected
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.
The following qualifiers are valid for a parameter of this data type:
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.
The following example shows a parameter descriptor specifying that the expected
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.
The following qualifiers are valid for a parameter of this data type:
allow
byte
disable_input
hidden
longword
max
min
noform
required
req_for_form
word
pathname
Defines a parameter that takes a path name or a star name as an input value. The
following are values pathname accepts:
The following qualifiers are valid for a parameter of this data type:
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
enclosed in apostrophes.
&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.
The following qualifiers are valid for a parameter of this data type:
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
enclosed in apostrophes.
&begin_parameters
file_a input_files:starname,required
file_b output_file:pathname,required
&end_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.
The following qualifiers are valid for a parameter of this data type:
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.
&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
-no_verbose
upward insert &$abbrev&
write
quit
&detach_input
!sort (home_dir)>abbreviations
!use_abbreviations (home_dir)>abbreviations
&return
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)
The following qualifiers are valid for a parameter of this data type:
allow
disable_input
hidden
length
no_abbrev
noform
required
req_for_form
&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.
The following qualifiers are valid for a parameter of this data type:
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.
&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.
&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)
The following qualifiers are valid for a parameter of this data type:
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:
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.
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
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.
For example, suppose the file start_up.cm in your home directory contains the
following instructions:
When you log in, this startup macro performs the following steps:
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
!attach_default_output (home_dir)>backup.out
!walk_dir %s1#d02>Sales>Smith -down_command 'delete_file
*.backup -no_ask'
!detach_default_output
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.
&begin_parameters
file filename:pathname,required
&end_parameters
&
!attach_default_output out_sink.out -append
!display &file& -no_header
!detach_default_output
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
!append_file weekly_1
!append_file weekly_2
!append_file weekly_3
!append_file weekly_4
!append_file weekly_5
!append_file weekly_6
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.
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.
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).
• 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:
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.
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.
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:
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.
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.
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.
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
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:
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
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
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:
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
enclosed in apostrophes.
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.
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.
File-Related
Tasks Examples of Commands Access Requirements
Directory-Related
Tasks Examples of Commands Access Requirements
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.
• 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.
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.
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.)
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.
• In any directory you have modify access to, you can add, change, or remove
entries from the access control lists associated with its subdirectories. (See
‘‘Commands for Managing Access” later in this chapter.)
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.
• In any directory you have modify access to, you can add, change, or remove
entries from the default access control list associated with it. (See ‘‘Commands for
Managing Access” later in this chapter.)
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
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.
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:
The output of two of these commands uses one-letter codes, called access codes to
represent access rights.
Examples
The following command displays the file access control list of the file named report
in the current directory:
display_access_list report
%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:
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:
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.
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
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:
status %s1#d01>Sales>Smith>monthly_meetings
read %s1#d01>Sales>Smith>report
null %s1#d01>Sales>Smith>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:
%s1#d01>Sales>Smith>report
w Smith.Sales (D)
r Jones.* (D)
r *.Sales
r *.Accounting (D)
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:
%s1#d01>Sales>Smith>monthly_meetings
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.
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:
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:
Now, if you give the command display_access_list report, the output looks
like this:
%s1#d01>Sales>Smith>report
r *.Sales
w *.Temp
The output of the command display_access report -all now looks like this:
%s1#d01>Sales>Smith>report
w Smith.Sales (D)
r Jones.* (D)
r *.Sales
w *.Temp
r *.Accounting (D)
%s1#d01>Sales>Smith>monthly_meetings
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:
%s1#d01>Sales>Smith>monthly_meetings
m Smith.Sales
s Jones.*
s *.Sales
n *.Accounting
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:
Now, if you give the command display_access_list report, the output looks
like this:
%s1#d01>Sales>Smith>report
r *.Sales
The output of the command display_access report -all now looks like this:
%s1#d01>Sales>Smith>report
w Smith.Sales (D)
r Jones.* (D)
r *.Sales
r *.Accounting (D)
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:
%s1#d01>Sales>Smith
w Smith.Sales
r Jones.*
r *.Accounting
n *.*
Also, the command display_access report -all now produces this output:
%s1#d01>Sales>Smith>report
w Smith.Sales (D)
r Jones.* (D)
r *.Sales
r *.Accounting (D)
n *.* (D)
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:
%s1#d01>Sales>Smith
w Smith.Sales
r Jones.*
n *.*
Also, the command display_access report -all now produces this output:
%s1#d01>Sales>Smith>report
w Smith.Sales (D)
r Jones.* (D)
r *.Sales
n *.* (D)
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:
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
%s1#d01>Smith>Sales>monthly_meetings
m Smith.Sales
s Jones.*
s *.Sales
n *.Accounting
%s1#d01>Smith>Sales>monthly_meetings
w Smith.Sales
r Jones.*
n *.*
• 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
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.
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.
NOTE
You may want to run this command periodically on
directories that contain objects that the POSIX
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:
%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 (?).
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.
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.
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
Displays a report for a directory or directory hierarchy that summarizes the
POSIX.1 access modes for each object.
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.
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.
remove_default_access
Removes entries from the default access control lists of a directory or set of
directories.
set_expiration_date
Sets an expiration date on a file to protect it against premature deletion.
set_owner_access
Sets the owner access bits on an executable file.
set_safety_switch
Turns a safety switch on or off for a file or files, preventing premature deletion or
truncation of the file.
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 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.
remove_default_access
Removes entries from the default access control lists of a directory or set of
directories.
verify_system_access
Checks that you can use the resources of a system to access files and to start
processes in that system.
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.
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.
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.
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.
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.
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
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_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
Lists the path names of a set of devices connected to a set of modules.
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.
login
Starts an interactive process or subprocess.
logout
Ends a login process or login subprocess.
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
Lists the path names of a set of devices connected to a set of modules.
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.
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.
delete_dir
Deletes directories and all their contents.
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.
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.
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.
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.
detach_default_output
Detaches your default_output port and reattaches it to its previous attachment,
which is normally your terminal. Use this command in conjunction with the
attach_default_output command.
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
Displays a report for a directory or directory hierarchy that summarizes the
POSIX.1 access modes for each object.
Printing
Getting Information about Printers
display_device_info
Displays information about a device defined on the current module.
display_print_status
Displays the status of the printer or printers connected to one or more modules.
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.
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;
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
Sets the owner access bits on an executable file.
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
Displays information about a device defined on the current module.
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
Lists the path names of a set of devices connected to a set of modules.
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.
set_terminal_parameters
Sets the terminal parameters for your terminal.
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.
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:
• stop or s
• continue or c
• keep or k
• re-enter or r
You can issue this command only when your process is at break level.
You can issue this command only when your process is at break level.
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.
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.
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)
(Page 2 of 2)
The following table shows the meaning of symbols used in this appendix to show the
syntax of command functions.
Symbol Meaning
I an integer
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:
(abs N)
Returns the absolute value of N.
Example
(abs -2) 2
The possible codes the (access) command function returns and their corresponding
meanings for files and directories are as follows:
Directories Files
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
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
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
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.
(before S1 S2)
Returns the initial substring of S1 that precedes the substring S2.
Example
(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
(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.
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.
Level 1 ** exponentiation Y N N
- negative (prefix) Y N N
^ not N Y N
Level 3 * multiplication Y N N
/ division 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
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:
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:
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).
12 / 3 * 4 left to right 16
12 / 3 * 4 right to left 1
• 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:
&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
&if (command_status) ^= 0
&then &return
(concat S1 ...Sn)
Returns the strings S1 through Sn combined into one string with all spaces between
the components removed.
Example
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:
(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
(current_dir)
Returns the full path name of your current directory.
Examples
(current_dir) %s1#d01>Sales>Smith
&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:
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_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.
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_time) command function assume that the current date
and time are Monday, May 28, 2001, at two o’clock in the afternoon.
(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
(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
(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.
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.
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.
(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.
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
If the object specified by path_name does not exist, the returned value is 0.
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
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
(hexadecimal I)
Returns the value of I expressed as a hexadecimal integer. The integer I can be
expressed as a binary, octal, decimal, or hexadecimal integer.
Examples
(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:
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 (iso_date) command function assume that the current date
is Monday, June 18, 2001.
(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.
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
(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
(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
(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
(max N1 N2)
Returns the larger of the two values specified in the arguments N1 and N2.
Example
(max 33 36) 36
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 1434 Smith Sales m2) Smith not registered for group
Sales on module m2.
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.
(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.
cpu_family The value representing the processor family for the current
module. The possible return values are mc68k, i860 or
hppa.
(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
Example
(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:
%s1#m2
#m2
m2
Example
(online #m5) 1
Example
(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.
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.
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.
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..
(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
(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.
If the arguments contain apostrophes, the command processor removes one level of
apostrophes before passing the arguments to the command function.
Examples
(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).
Example
(referencing_dir) %s2>#d01>Sales>Smith>reports
(reverse S)
Returns the reversed character pattern of the string S.
Example
(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
(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
(software_purchased software_purchased_bit)
Returns 1 if the product denoted by software_purchased_bit has been
purchased. Returns 0 otherwise.
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.
Examples
(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
(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.
tabs The column positions where tabs are set for the terminal.
(terminal_name)
Returns the full path name of the login terminal. (This function works only in a login
process.)
(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.
[coming][absolute_time][time_zone][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 (time) command function assume that the current time is one
o’clock in the afternoon, Eastern Standard Time.
(time) 13: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 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.
Example
(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
(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
Examples
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
• 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;
detach_default_output
&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.
&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.
Example
The following example is a command macro that calls the line editor to replace one
character string in a file with another:
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 0-
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 0-
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 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 0-
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 0-
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.
Related Information
See the description of the &attach_input statement in this appendix.
&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
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_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
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:
&do 0-
Form
&do
command,_statement,_or_input_1
command,_statement,_or_input_2
.
.
.
&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.
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:
Releated Information
See the description of the &end statement in this appendix.
&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.
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.
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.
&end 0-
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 0-
Form
&end_parameters[end_qualifier] [,end_qualifier]...
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.
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.
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 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 0-
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:
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&
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 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&
The label name in a &label statement, however, must be a constant; it cannot contain
any macro parameters or variables.
Related Information
See the description of the &label statement in this appendix.
&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.
In the case of nested &if-&then-&else statements, a line can contain only one &if
statement.
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
command processor replaces parameters and variables with their values before
evaluating command functions in the expression.
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:
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:
Related Information
See the description of the (calc) command function in Appendix C for the definition
of an expression.
&label 0-
Form
&label label_name
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 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.
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 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]
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 0-
The &set statement evaluates an expression and assigns the value to a variable.
Form
&set variable_name expression
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.)
The first &set statement could declare sum, or it could have been declared earlier. The
second statement is equivalent to:
&set_string 0-
Form
&set_string variable_name S1 ...Sn
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.
Example
The following example illustrates use of this macro statement:
The output of the last line in the preceding example displays the line 001BYE.
&while 0-
Form
&while expression
command,_statement,_or_input_1
command,_statement,_or_input_2
.
.
.
&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.
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.
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.
• ‘‘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.
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.
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.
On Off Default
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.
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.
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.
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.
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.
Some requests always change the current line, some requests never change it, and
others may change it.
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.
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
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.
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.
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.
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.
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 after the present current line.
-n Sets the current line to the nth line before the present current line.
bottom or b Sets the current line to the last line in the buffer.
join Joins the current line with the line before or after.
quit or q Quits.
Request Purpose
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 .
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
the upward qualifier with this request.
=
Prints the number of the current line. The current line does not change. You cannot use
the upward qualifier with this request.
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.
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
Using the Line Editor E-11
Line Editor Requests
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.
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).)
n1 n2+m n3 n4+m
n1 = 11
n2 = 21
m = 5
n3 = 45
n4 = 51
Using the preceding values, consider this form of the tab request:
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.
Every process has five predefined ports. Table F-1 shows their names and identifiers.
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.
The following are conventions that govern the system uses of process 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.
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.
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.
F-8 no no macro no
default_input none
command_input none
default_input none
command_input none
default_input none
default_input none
This appendix describes how to specify date/time string arguments in the following
command functions:
(date)
(date_time)
(iso_date)
(iso_time)
(time)
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.
The following are examples of complete date string values for absolute_date;
each value specifies the first day of August 2001:
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.
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.
• 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.
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.
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.
0 twelve midnight
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.
at Azores
bt Baghdad
jt Java
nt Nome
ut Universal
z Zulu (Universal)
NOTES
1. Beginning in VOS Release 14.0.0, the bdt (Bering
Daylight Time) time-zone code is no longer
supported.
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
If you use the specified time of 00:00 + 2 hours, is in the following example:
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.
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.
• 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.
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.
TOPICS Description
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.
• 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:
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.
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.
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.
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.
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.
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.
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 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.
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 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.
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 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.
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.
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 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.
Glossary-7
Glossary
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.
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 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
A type of replacement directive in an abbreviations file that tells the operating
system to replace an input string with an output string when the specified input
string occurs first in a command string.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.)
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.
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:
Some names with asterisks function differently; see module star name and user
star name.
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:
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
A type of replacement directive in an abbreviations file that tells the operating
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
A type of replacement directive in an abbreviations file that tells the operating
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.
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.
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.
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
Index-3
Index
Index-5
Index
Index-7
Index
Index-9
Index
Index-11
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