TOPS-20 Commands Reference Manual

Chapter 1 Introduction

Commands and arguments

A complete TOPS-20 command consists of the command name and usually one or more arguments. In the most general sense, arguments are any combinations of letters, numerals, punctuation marks and other characters that you type after the command name itself to complete the meaning of the command. These arguments can be file specifications, switches, subcommands, and values for switches and subcommands, as well as words and numbers (the arguments to the SET and TERMINAL commands, for example). The following pages contain general information about each variety of argument.

File Specifications

Information and programs for TOPS-20 are usually stored in uniquely labeled files. Therefore, file specifications or "filespecs" are the most common variety of argument to a command. A complete file specification is of the form:

        dev:<dir>name.typ.gen;att;...;att

where:

dev
is a device (usually a file structure)
<dir>
is a directory name (enclosed in angle < > or square [ ] brackets)
name
is a filename
.typ
is a file type
.gen
is a generation number
;att
is a file attribute

You need file attributes in only a few situations and can usually let dev:, <dir>, and .gen take default values (that is, values defined by the state of your job - see the Special Features section below), so you can give most file specifications in the shortened form, name.typ, without being unclear. In a few cases, an entire file specification is assumed if you do not supply one when you give the command (for the CREATE and EDIT commands, for example, and for LOAD-class commands - COMPILE, LOAD, EXECUTE, and DEBUG).

Whenever you omit the dev: field of the filespec, the system assumes you mean your connected structure (DSK:). This is the public structure (usually named PS:), which all users must log in to, unless you connect to a directory on another structure by using the CONNECT command. Give the INFORMATION STRUCTURE command if you are unsure of the name for your connected structure.

Whenever you omit the <dir> field of the filespec, the system assumes you mean your connected directory. Unless you have given a CONNECT command, this is your "log-in" directory, the directory on the public structure that you must log in to and which usually has a name composed of your surname, or surname and initials, enclosed in angle or square brackets. You can change your connected directory by giving a CONNECT command. Use the DIRECTORY command to see the name of your connected directory.

When you omit the .gen field of the filespec the system usually assumes you mean the highest generation (largest generation number) of the file. (A few commands, for example, DELETE, RENAME, and DIRECTORY, act on all generations of a file unless you specify a particular generation.) When you create and edit text files, compile and debug programs, or do anything else to produce another generation of a file, the system automatically works with the highest existing generation and labels the changed file with the next higher generation number. Therefore when you omit the generation number in a filespec given as argument to a TOPS-20 command, you are assured of using the most recent version of the file. Although you can override this default action by specifying particular generations of input and output files, it is simplest and most straightforward to allow the defaults to prevail.

Specification of file attributes is optional. You can assign attributes in order to have a file automatically marked for deletion when you log out; to associate a file with a valid account; and so forth. Appendix C lists the available file attributes.

Pressing the ESC key instead of typing a filespec field will usually cause any default for the remaining fields to be printed on your terminal.

There are two characters (called "wildcard" characters) that you can include in any field of a filespec to include all files matching the rest of the filespec. An asterisk (*) fills in for zero or more characters of a field, while a percent sign (%) fills in for a single character only. (However, only the complete field "DSK*:" is allowed as wildcard for the device field, and only the complete field "*" is allowed as wildcard for the generation field.) Therefore you could give the command DIRECTORY *.CBL to find out what source files written in COBOL are in your connected directory, or the command DELETE *.Q* to remove the EDIT program's backup files from your directory.

Switches

Switches are arguments used with LOAD-class (COMPILE, LOAD, EXECUTE, and DEBUG) and EDIT-class (CREATE and EDIT) commands, as well as with Queue-class commands - that is, those affecting entries in processing queues (CANCEL, DISMOUNT, MODIFY, MOUNT, PLOT, PRINT, PUNCH, and SUBMIT).

Switches can also be used with the following program-control commands: DDT, GET, MERGE, R, and RUN. The REWIND command also accepts a switch.

Switches allow you to quickly give many options chosen from a large list, and let you specify to which files they apply when you give more than one filespec in a single command.

Give switches on the same line as the command, typing a slash (/) before each switch. If your command requires more than one line, simply keep typing without giving a carriage return. The system will begin a new line automatically and will read your command as if you had typed it on a single line. Or you can end your command line at any point with a hyphen (-) and carriage return, and continue the command on the next line; the hyphen will not be considered part of your input.

Keep in mind the way each class of command considers switches. EDIT-class commands operate on only one file at a time, and the switches must be given before the input filespec - this is the simplest case.

Queue-class and LOAD-class commands treat switches according to their position in the command line. If you give them before any filespecs, they act as default switches for all filespecs in the command (they will be in effect unless you override them with later switches applying to individual files only). If you give them after the first filespec, they apply only to the preceding file. In addition, there are a few switches of a different sort for the PLOT, PRINT, and PUNCH commands - these apply to all files no matter where they appear in the command line. These are called job switches (because they affect the entire printing job) and are presented in a separate list in those command descriptions.

A switch is a default if the system assumes it in the absence of others. For example, for LOAD-class commands, /FORTRAN is the default for all switches that specify which compiler to use (like /MACRO, /COBOL, and /PASCAL). The /NOCOMPILE switch is the default for /COMPILE, /NOCOMPILE, and /RELOCATABLE. Most defaults for these commands apply to only a pair of switches; however, the /BINARY, /NOSEARCH, and /NOOPTIMIZE switches are assumed, for example, unless you specify /NOBINARY, /SEARCH, and /OPTIMIZE.

Default switches for the other classes of command operate similarly. Some are in effect unless you specify their opposite; others are in effect with a default argument unless you specify another argument; still others must be specified to be in effect, but are supplied with a default argument. The list of switches presented with each command description distinguishes these cases. When you give two or more switches of the same kind (for example, /BINARY and /NOBINARY), the last switch given usually prevails.

Subcommands

Subcommands are a variety of arguments used chiefly with DIRECTORY-class (DIRECTORY, FDIRECTORY, TDIRECTORY, and VDIRECTORY) commands and with the BUILD command. If you want to give subcommands to any of the DIRECTORY-class commands, type a comma at the end of the command line just before pressing the carriage return. After the system prompts you with a double at sign (@@) you can give subcommands, one on each line. If you give no subcommands to the DIRECTORY command, the ALPHABETICAL and HEADING subcommands will be in effect, giving an alphabetical listing of files. For a few subcommands, default arguments will be in effect if you give the subcommands without supplying any. You can give subcommands in any order, requesting or declining special categories of information and specifying the format of its presentation. If you give mutually exclusive subcommands (ALPHABETICAL and CHRONOLOGICAL, for example) the last-given subcommand prevails. Note that the FDIRECTORY, TDIRECTORY, and VDIRECTORY commands are equivalent to the DIRECTORY command with certain subcommands automatically included, and can be further modified with other subcommands from DIRECTORY's list. To cancel a DIRECTORY-class command while giving subcommands, type a CTRL/C.

The BUILD command operates differently from DIRECTORY-class commands in putting you automatically into subcommand mode without your typing a final comma on the command line, and in offering a special subcommand to cancel the command while you are typing subcommands.

See the individual command descriptions for more detailed information about subcommands.

Other Arguments

Some command arguments are not introduced by special characters such as slashes or double at signs, but still are particular words, or "keywords," having a special meaning to the system. Give these on the same line as the command itself, leaving at least one space before and between arguments. Certain of these (for example, the LOGICAL-NAMES argument to the INFORMATION command) are actually composed of more than one word, joined by hyphens so that the system will not interpret them as more than one argument. If the complete command will not all fit onto one line, simply keep typing: the system automatically begins a new line when necessary, but interprets the typing as if it had all appeared on one line. Or you can end a command line at any point with a hyphen (-) and a carriage return, and continue the command on the next line; the hyphen will not be considered part of your input.

A few command arguments must be accompanied by special symbols to be interpreted correctly. Enclose directory names in angle brackets when using them with the CONNECT or names (for DEFINE), device names (used with ASSIGN), and structures and tape sets (used with MOUNT or DISMOUNT) all require a colon at the end. (But note that when supplying what look like structure and tape set names to the related CANCEL command, you are supplying jobnames, and must not include the colon.) If you punctuate a command argument incorrectly, the system will usually print a message reminding you of this.

Special features

Defaults

The concept of "defaults," or command arguments assumed when you do not specify a choice, is important for understanding TOPS-20. To speed processing of commands and to help inexperienced users, the system uses defaults when necessary for completing commands that you give. By taking advantage of this defaulting action, you can make the system work faster and more efficiently for you. This manual displays prominently the available choices of command arguments and the established defaults for these.

There are different kinds of default. When you give file specifications as arguments to, say, the PRINT command, the system assumes that you are referring to the highest (most recent) generation of these files in your connected structure and connected directory. By specifying a different structure, directory, or generation you can override this default, but only if you already have the right (established by user membership in a group, perhaps, or by a prior ACCESS command) to do so.

When you give the INFORMATION BATCH-REQUESTS command without further arguments, you are presented with a listing of all requests in the batch input queue. The /USER switch allows you to limit this display to the jobs of the user named. If you give the switch without supplying a user name, your own user name is used as default. (But the /USER switch to the related SUBMIT command has meaning for privileged users only, who can use it to run batch jobs under other user names; for non-privileged users this switch effectively defaults to your own user name.) Only a few command arguments behave like the /USER switch. The /TIME switch to the SUBMIT command is worth noting: by not giving the switch, you set a time limit of 5 minutes; by giving the switch without specifying a time limit, you are setting a 1-hour limit; and you can set any other time limit by supplying it as argument to the switch.

Note that none of the three switches to INFORMATION BATCH-REQUESTS and INFORMATION OUTPUT-REQUESTS (/ALL, /FAST, and /USER) is used as a default: each calls for a listing that differs in some respects from that yielded by the unmodified command. However, the INFORMATION LOGICAL-NAMES command, which allows keywords ALL, JOB, and SYSTEM, has JOB as default for these. The list of arguments associated with each command makes these choices clear.

To discover what default argument (if any) is established for a switch, subcommand, or other argument, press the ESC key instead of giving the argument: the default will be printed on your terminal.

"Recognition" input is another feature of the TOPS-20 operating system that speeds up your input, by finishing the typing of a command or command argument for you when you have given only part of it and then prompting your next response.

As soon as you have typed enough of a command or argument to distinguish it from others, press the ESC key: the system will finish the word, if possible, and prompt your next input with guidewords enclosed in parentheses. (Note that this manual does not show guidewords except in the Format section of each command description.) By pressing the ESC key without beginning an argument you make the system print the default argument, if there is one. If the system cannot help you, either because you have not typed enough characters to make your intentions clear or because there is no default, your terminal makes a warning noise - either a ringing bell or high-pitched beep.

Because the ESC key does not produce a printed character, you may be unable to remember exactly where you pressed it when later examining the output from a hard-copy terminal. If you want to avoid this possibility, use the TERMINAL NO RAISE command to make your terminal produce lowercase input, to distinguish it from the uppercase printing of the system.

For TOPS-20 Version 7, recognition has been expanded so that presssing the ESC key also shows as much of a command keyword or file specification as possible. For file specifications, recognition is in effect only for the file name, extension, and version.

You cannot use recognition for device names or directory names (including file structures), jobnames (for example, with the MODIFY or CANCEL command) or logical names.

Abbreviation

By abbreviating commands and command arguments, you can further increase the speed with which you give instructions to TOPS-20. The smallest unique abbreviation for a command or argument will stand for the entire word; if there is a default choice for further arguments, the system will assume you want this too. (You can determine sufficient abbreviations by using the ESC key: any correctly recognized abbreviation will stand for the word.) For example, the abbreviated command FD stands for the FDIRECTORY command; I L stands for INFORMATION LOGICAL-NAMES JOB.

There are a few cases where non-unique abbreviations stand for a frequently used command. For example, DIS is the abbreviation for DISABLE even though two other commands begin with the letters DIS - DISCARD and DISMOUNT.

Special AbbreviationCommand
CCONTINUE
DDEPOSIT
DISDISABLE
EEXAMINE
EXEXECUTE
INFORMATION FINFORMATION FILE-STATUS
LOG (When not logged in)LOGIN
LOG (When logged in)LOGOUT

You cannot use abbreviation (or recognition) in a few cases. The names of devices (including file structures), and jobnames (given, for example, as arguments to the MODIFY or CANCEL command) must be typed in full; and of course passwords cannot be abbreviated or recognized.

Question Marks

Whenever you type a question mark (?) instead of (or even in the middle of) a TOPS-20 command or command argument, the system responds with instructions or a list of possible completions. By using question marks and recognition when you are unsure of the proper command or argument, you can have the system help you during your terminal session.

These features, together with the HELP command, which provides information on various system programs, are valuable supplements to the written documentation for TOPS-20.

For TOPS-20 Version 7, new functionality has been added to make the question mark feature more useful. More possible completions and choices are now listed. In addition to possible command names listed in response to a question mark, the system also displays possible filenames from the system (SYS:) directory. For example:

@L ? Command, one of the following
   LOAD    LOGOUT
    or system program name
   LOGIN
   LOGOUT

Where the LOGIN and LOGOUT that appear after "or system program name" are files from the system directory that start with L.

The functionality of the question mark feature has been expanded for file specifications also. Question mark lists possible file names, extenstions (including nulls), and file version numbers. For example:

@DIRECTORY E? FILE NAME EXTRA EXTUSR EMACS @DIRECTORY EMACS.? FILE NAME INIT VARS @DIRECTORY EMACS.INIT.? FILE NAME 1 2

Date-Time arguments

You can specify date and time arguments to many of the TOPS-20 commands. The following sections describe the formats for these arguments.

Date

The examples below show the various formats that are acceptable for the date argument:

Jun 30 198130 Jun 1981
May 1, 821/May/1982
January 000005 750005-January-000075
F/13-835/17/83

If the month and day are both numeric, the first number of the two, if less than 13, is considered to be the month. Otherwise, the second number is considered to be the month. For example:

2/15/83is February 15th
15/2/83is February 15th

You can abbreviate the month to as few characters as possible without causing it to be confused with another month. Thus,

O
Jun
Jul
Ja

are acceptable abbreviations for October, June, July, and January.

Many commands allow you to give the day of the week or "today" for the date.

If you specify the time along with the date, you must separate the two arguments by at least one space and/or no more than one tab.

For the time argument you can specify:

Examples

6:00PM-EDTis 5:00PM EST
6:00PM-PSTis 9:00PM EST
6:00PM-GMTis 1:00PM EST

Note that a hyphen (-) is required before the zone.

The basic time format is:

     hh:mm:ss

where:

hhis hours, must be less than 24, and is optional
mmis minutes, must be less than 60, and is required
ssis seconds, must be less than 60, and is optional

The colon between hours and minutes is optional.

Examples (based on a 24-hour clock):

3is 00:03:00AM
125is 1:25AM
14:30is 2:30PM
25:33is 00:25:33AM

Relative Date-Time Arguments

Many commands accept relative dates and times. You can specify that an event is to occur at a certain amount of time from the current time, from today, or from a certain day of the week. Likewise, you can specify relative times in the past.

Examples

@SET ALERT +30      sets an alert for 30 minutes from now

@DIRECTORY,         produces a listing of files that
@@BEFORE TODAY      were created before today's date

Exec messages

The TOPS-20 Command Processor, or EXEC, displays messages in response to errors or other conditions that arise when using the TOPS-20 Command Language. There are three kinds of EXEC messages: error, warning, and information.

Error messages begin with a question mark (?). An error message indicates that a failure has occurred and execution of the command or program has stopped. If, for example, you type the wrong password in a LOGIN or CONNECT command, you receive the message ?Incorrect password, and the command is not executed.

Warning messages begin with percent sign (%). A warning message also indicates that a failure has occurred, but execution of the command or program usually continues. For example, suppose you type the command DIRECTORY *.PAS, *.REL to list all the files with the extensions .PAS and .REL, and, your connected directory does not contain any .REL files. The EXEC lists all the files with the .PAS extensions and then prints the warning message, %No such file type *.REL.

The third type of message you can get from the EXEC (and sometimes from the system) is an information message. Information messages are enclosed in square brackets [ ] and inform you about the status of the system or the result of an EXEC command. For example, the message [DECSYSTEM-20 continued] indicates that a temporary pause in service has ended. The message [n pages freed] indicates that your EXPUNGE command freed n disk pages. Usually information messages require no response from you.

When you need more information than is provided by an EXEC message, see the EXEC Message Manual. This manual contains detailed descriptions of all EXEC messages, plus actions to take for correcting errors.

New and changed features

The TOPS-20 EXEC has been enhanced considerably for TOPS-20 Version 7. The following is a list of new commands, and new arguments, subcommands and switches to previously existing commands. Changes affecting the command are shown as bulleted items.

Changes to Commands and New Arguments, Subcommands, and Switches