TOPS-20 User's Guide
Chapter 4 File specifications
This chapter describes:
- TOPS-20 File System Organization
- Complete form of a file specification
- Using wildcards to specify files
- Specifying special characters - CTRL/V
- Typing file specifications
- Using logical names
When you enter a program, data or text into the computer,
it is stored in a file. A computer file system has an
organization similar to that of an office file cabinet
system. You create and label a file then store the file in
your drawer of the file cabinet. Your drawer of the file
cabinet is called your directory on TOPS-20.
The "label" on a file is called a file specification. A
file's specification tells the system where to locate and
identify the file. The complete form of a file
specification is:
A device name designates the location of the file on a
particular device or file structure. (Refer to Section 6.1 for a
description of file structures.)
A device name consists of alphabetic characters that
indicate the type of device, a number specifying a
particular device (when more than one of a particular device
is available), and a colon terminating the name of the
device. Table 4-1 lists some common DECSYSTEM-20 devices
and their device names.
A colon terminates the device name. With some TOPS-20
commands, the colon following the device name is optional.
Refer to the TOPS-20 Command Reference Manual.
Examples of device names are:
If you omit a device name from a file specification, the
system uses, as a default, the device or file structure you
are presently using.
One area of disk storage allocated for your use is your
log-in directory. You reference your log-in directory by
using a directory name, which is your user name, enclosed in
angle brackets <> or square brackets []. Therefore,
if your user name is KIRSCHEN, you have a directory named
<KIRSCHEN>. You can use other directories in addition
to your log-in directory.
If you have access to the directory of another user and
you want to use a file from that directory, insert the
directory name enclosed by angle brackets, immediately
before the filename. The illustration below shows how to
access the file LIZARD.DAT from the directory of user
HODGES.
A directory name consists of up to 39 alphanumeric
characters, including the special characters dollar sign,
period, hyphen, and underline. You can use the * and %
wildcard characters to specify a group of directories,
though it is not actually part of a directory name. (Refer
to Section 4.3 for more information on
using wildcard characters.) Directory names are always
enclosed in brackets and are used only when the device is a
disk. Examples of directory names are:
Most programs and commands allow you to type a directory
name, but a few require a similar designator called a
project-programmer number. Table 4-2 lists the TOPS-20
system programs that require you to type a
project-programmer number instead of a directory name when
you reference files in directories. Your installation may
also have other system programs with this requirement.
A project-programmer number consists of two numbers
separated by a comma and enclosed in square brackets. To
find the project-programmer number corresponding to a
particular directory name, give the TRANSLATE command. The
following example shows how to find the project-programmer
number associated with the directory <KIRSCHEN>:
The FILCOM program, for example, requires a
project-programmer number. If you want to compare your
version of the file PLEASE.MAC with the version of the same
file in user KIRSCHEN's directory, give the following
commands:
Refer to the TOPS-20 User Utilities Guide for a complete
description of the FILCOM program.
Each file in your directory is identified by a filename
consisting of up to 39 alphanumeric characters, including
hyphen, dollar sign, and underline. You choose the
filename. A filename that reflects the contents of the file
will help you remember what is in the file. Examples of
filenames are:
Although most programs and commands allow filenames up to
39 characters long, some programs do not support this
extended length. If you are using any of the programs
listed in Table 4-2, the maximum length of a filename is six
characters; $, -, and _ characters are invalid in a
filename; and the wildcard characters * and % are used for
specifying a group of filenames where permitted by the
program.
To help identify the contents of a file or give the same
filename to more than one file, specify a file type
consisting of a period followed by up to 39 alphanumeric
characters, including $, - and _. The wildcard characters
can be used to specify a group of files with the same file
type, but is not actually part of the file type. Examples
of some standard file types that contain programs are:
Other file types include:
Refer to Appendix B for a list of standard file types.
In addition to the standard file types, you may use your
own file types.
Although most programs and commands allow file types up
to 39 characters in length, some software programs do not
recognize this extended length. If you are using any of the
programs listed in Table 4-2, the maximum length of a file
type is three characters; the $, -, and _ characters are
invalid in a file type; and the wildcard characters are used
for specifying a group of file types where permitted by the
program.
The generation number identifies modified or additional
versions of the same file. The operating system increases
the generation number by one when you change the file. You
can create a new file and assign a generation number to it.
When you type a file specification, you can include a
generation number. At times you may have more than one
generation of a file, especially if you previously gave the
SET FILE GENERATION-RETENTION COUNT command. The system
always assumes that the most recent file is the one with the
highest generation number. If you create a new file with a
generation number lower than an existing file with the same
filename and type, you may have trouble saving and restoring
it on tape using DUMPER or using it with the LOAD-class
commands (unless you delete the version with the higher
generation number). Refer to the TOPS-20 User Utilities
Guide for a description of the DUMPER program, and to Section 9.3 of this manual
for information on the LOAD-class commands.
When you do not specify a generation number, the system
selects one according to the way you use the file:
When you do specify a particular generation number, the
system uses the file with that generation number. You can
give a generation number as a positive number or as a
symbol. There are four symbolic generation numbers. Refer
to Table 4-3 for a list and description of the four symbolic
generation numbers.
For example, if you have three generations (.1,.2,.3) of
the file BACKUP.DAT, .0 is the symbolic generation number
for BACKUP.DAT.3, .-2 is the symbolic generation number for
BACKUP.DAT.1, and .-1 is the symbolic generation for
BACKUP.DAT.4. Refer to Section 6.5 for an example
of how the system uses symbolic generation numbers.
Some installations limit the number of generations of any
one file you can keep. Therefore, if the limit is 3 and you
create a fourth generation of the file, the system deletes
the file with the lowest generation number. If you have the
files BRKING.CBL.3,4,5, and you create BRKING.CBL.6, the
system deletes the oldest file (BRKING.CBL.3). The system
always assumes that the oldest file is the one with the
lowest generation number, and the most recent file is the
one with the highest generation number.
If you are using a file with any of the programs listed
in Table 4-2, you cannot include a generation number in the
file specification. These programs always use the highest
existing generation number for files if you are reading or
the generation number 1 if you are creating a file.
File attributes specify distinctive characteristics for a
file specification. More than one attribute may appear in a
file specification. The three most common attributes are:
;A for account, ;P for protection, and ;T for temporary.
The account descriptor takes the form:
The descriptor is an account consisting of up to 39
alphanumeric characters. All charges for file storage are
billed to this account. If you do not specify an account
for your file specification, the system uses the account you
specified in your LOGIN command or your last SET ACCOUNT
command.
The file protection code takes the form:
Protection is a TOPS-20 protection code. (Refer to Section 6.2, Protecting
Directories and Files.)
A temporary file specification contains the file
descriptor ;T and a generation number of 100000 plus the
number of the job that created the file. (Refer to Section 6.11 for more
information on temporary files.) Temporary files are deleted
from your login and connected directories when you log off
the system.
You can display a list of files with the same attribute
by using the DIRECTORY command. This command prints a list
of all files with an account of 17:
You can specify other file attributes when working in a
DECnet or magnetic tape environment. Refer to Appendix C of
the TOPS-20 Commands Reference Manual for the complete list
of attributes. The DECnet-20 User's Guide further describes
the DECnet-related file attributes.
You can use a wildcard character in a file specification
to specify files that have part or all of a directory name,
filename, file type or generation number that is the same in
each file specification. The characters are valid wildcard
characters.
The * wildcard matches any number of characters in a
field of a file specification that uniquely identifies the
file. The following example illustrates using the wildcard
character * to list all files in the directory <SMITH>
with the file type .TXT:
If you give the command DIRECTORY L*, the system lists
all the filenames beginning with the letter L.
If you give the command DIRECTORY *T, the system lists
all the filenames ending with the letter T.
The % wildcard matches a single character in a field of a
file specification that uniquely identifies the file. You
cannot use % in a generation number. The following example
illustrates using % to list all files in the directory
<SMITH> containing four letters, and beginning with
the letter L and ending with the letters ST:
If you are using a file with any of the programs listed
in Table 4-2, you must use a different convention for
specifying groups of files. The * wildcard designates a
group of filenames or file types, but must either entirely
replace the filename or file type, or occur at the end of
the filename or file type. Therefore, the construction
TEST* is valid but the construction *TEST is not.
Not all programs in Table 4-2 accept wildcard characters
in a file specification. Also, the commands, COMPILE,
DEBUG, EXECUTE, and LOAD do not accept wildcard characters
in file specifications.
If you need to include a special character, that is, any
character other than an alphanumeric, $, - or _ in a file
specification, type CTRL/V directly before the special
character.
If you are using a file with any one of the programs
listed in Table 4-2, do not use the CTRL/V feature.
There are two methods of typing a file specification in a
command: full input and recognition input. For full input,
you type the complete file specification. If you are using
any of the programs listed in Table 4-2, you must always use
full input; recognition is not available.
When you are unsure of a file specification, type a
question mark to obtain a list of possible file names,
extensions (including nulls), and file versions. For
example:
Recognition input makes it easier for you to type file
specifications. You can make the system recognize file
specifications by using either CTRL/F or ESC. For file
specifications, CTRL/F recognizes only the current field of
the specification, for example it completes a directory
name, filename, file type, generation number. The ESC key
recognizes as many subsequent fields as possible, including
any defaults. Many commands set up defaults so that you can
press the ESC key at the beginning of a file specification,
causing the system to print the full default file
specification on your terminal.
The following example illustrates a way to use CTRL/F to
recognize a portion of a default file specification. If you
want to change the file type of the file PROG1.OAS, give the
RENAME command followed by the file name PROG1 and press the
ESC key; the system prints .OAS.* (TO BE). Now type CTRL/F;
the system prints PROG1. Type the new file type, .PAS.
The system considers generation numbers in specific ways.
When you are using an existing file, the system selects the
highest generation number; when you are creating a file and
a file with that same name and type already exists, the
system assigns a generation number one higher than the
highest existing generation number.
The following examples illustrate the way the system
considers generation numbers. If you have two files in your
directory, TEST.TXT.2 and TEST.TXT.3, and you give the TYPE
command to print the TEST.TXT file, the system selects the
file with the highest generation number. Give the TYPE
command, followed by the filename TEST.TXT and press ESC.
The system prints .3 (the highest generation number).
If you want to copy the file NEW.FIL.1 to the destination
file TEST.TXT.3, give the COPY command, followed by the
filename NEW.FIL and press ESC; the system prints .1 and
(TO). Type the filename TEST.TXT and press ESC; the system
assigns a generation number one higher than the existing
generation number. In this case, the destination file
becomes TEST.TXT.4.
You can use recognition on any part of the file
specification except the device name field. When you use a
device name, you must always type this name in full. If you
do not type a device name, the system uses DSK: (your
connected file structure), but does not print it on your
terminal.
When you type more than one file specification, you can
incorporate recognition input when typing each file
specification. You can also incorporate wildcards with
recognition input when you type a group of files.
When you type more than one file specification on a line,
separate each file specification with a comma. The
following example illustrates using commas to separate file
specifications in a PRINT command.
A logical name is a descriptive word used to establish a
search route for locating files in other directories or on
other structures. When you define a logical name, you tell
the system where, and in which order, to search for a file.
A logical name comprises up to 39 alphanumeric
characters, including -, $, and _. followed by a colon.
However, you can use an abbreviated word for the logical
name when you define the search list.
For example, you are a member of a team working on a
project. Your team has a directory called <TEAM> on
the structure PS: where the members store all the completed
programs for the project. When you are looking for a
project file and you are not sure where it is, you must look
through your own directory, and then through the team's
directory to find it. Instead of giving two separate
DIRECTORY commands for each directory, you can give one
DIRECTORY command using a logical name that will
automatically search through both directories until it finds
the file. The example below illustrates defining a logical
name to search your directory, (here your user name is
KONEN), and then the team's directory. Include the
structure name with the directory names.
You now have the logical name ALL: defined as
PS:<KONEN> and PS:<TEAM>. If you want to search
for the file TEST.FOR in either directory, give the
following command:
The system searches first in the directory <KONEN>
where it does not find the file, and then in the directory
<TEAM> where it does find the file. If the file
TEST.FOR exists in <KONEN> and in <TEAM>, the
system searches only until it finds the first file. In this
case, finding the file in <KONEN>, it does not
continue the search in the directory <TEAM>. When you
give the DIRECTORY command, the system always prints the
name of the directory and the structure in which it finds
the file.
The logical name you define applies only to your current
job. It remains in effect until you either remove it, or
end your job by logging out. If you want the same defined
logical name every time you log in, you can put the
definition in your LOGIN.CMD file. (Refer to Section 1.7 for
information on LOGIN.CMD files.)
To find out what logical name you are using, you can give
the INFORMATION LOGICAL-NAMES JOB command.
There are also systemwide logical names that all users
can give without having to define them for each job. A
systemwide logical name, like SYS:, is usually defined by
each installation and includes the directories that contain
standard system software. To print a list of systemwide
logical names, give the INFORMATION LOGICAL-NAMES SYSTEM
command.
When you define a logical name, you can include an
existing systemwide logical name in your definition. Each
directory name, device name, or other logical name you use
in defining the logical name must be separated by a comma.
For example, you can set up a search route to look for a
file in the system directories, SYS:, then in <TEAM>
and <KONEN>.
By defining the logical name TEST:, the system searches
SYS: first, because that was the first area you specified,
and if it does not find the file there, continues its search
through <TEAM> next, and finally through
<KONEN>.
If you copy a file to a logical name, the system places
the file in the first area defined in the logical name. For
example, if you copy the file CHECK.TST to the logical name
ALL:, the system places the file in the directory
<KONEN>, because that directory was the first area
defined in ALL:.
If you are defining a logical name for a program listed
in Table 4-2, you cannot include the characters - $ or _ in
the logical name. Also the logical name cannot exceed six
characters, excluding the colon.
To remove a logical name you have defined, give the
DEFINE command, but do not type any definition. After the
DEFINE command, type only the logical name. The following
example shows how to remove the logical name TEST::
You can also use the logical name as an abbreviation for
all or part of a file specification. Using a logical name
saves you typing if your file specification is lengthy.
The following example shows defining a logical name for a
directory name, and then giving the DIRECTORY command using
the logical name:
The following example shows defining a logical name for a
filename, and then giving the EDIT command followed by the
logical name to get the file.
Logical names can be used to define physical device
names. For example, suppose you have a program that uses
one tape drive to input data and another to receive output.
These tape drives, physically named MTA0: and MTA1:, can be
given the logical names IN: and OUT:. By placing logical
names for devices in your programs and defining them at
runtime, you can eliminate the need to modify the program to
refer to the devices that are currently available.
4.1 TOPS-20 file system organization
4.2 Complete form of a file specification
dev:<dir>name.typ.gen;attribute
where:
4.2.1 Device Names - dev:
Table 4-1: System Device Names
____________________________________________________________________
Device Device Name
____________________________________________________________________
Your Connected Structure and Directory DSK:
Your Terminal TTY:
The structure that receives POBOX:
your mail messages
A Particular Terminal TTYn:
A Particular Magnetic Tape MTAn:
Any Line Printer LPT:
A Particular Line Printer LPTn:
Any Card Reader CDR:
A Particular Card Reader CDRn:
Receptacle for unwanted program output NUL:
or supplier* of null input
The number n indicates a particular unit when the device has
multiple units.
* For example, COPY (FROM) NUL: (TO) TEST.FIL erases the contents
of the file TEST.FIL.
____________________________________________________________________
TTY20: the terminal connected to line 20
MTA0: the magnetic tape unit numbered 0
LPT: a line printer
ADMIN: a file structure
4.2.2 Directory Names - <DIR>
<HODGES>LIZARD.DAT.3
<PORADA>
<MCELMOYLE>
<MORRILL>
<NEXT-RELEASE>
4.2.3 Project-Programmer Numbers - [PPN]
Table 4-2: Special System Programs
___________________________________
ALGOL LIBARY
CREF LINK
FILCOM MAKLIB
ISAM
___________________________________
@TRANSLATE (DIRECTORY) <KIRSCHEN>
PS:<KIRSCHEN> (IS) PS:[4,516]
@FILCOM
*TTY:=PLEASE.MAC[4,516],PLEASE.MAC/A
4.2.4 Filenames - name
TEST
COMPUT
ACCTS
DATA-ITEM
10-MEM
4.2.5 File Types - .typ
________________________________
File Type Program Language
________________________________
.ALG ALGOL
.BAS BASIC
.CBL COBOL
.FOR FORTRAN
.MAC MACRO
________________________________
4.2.6 Generation Numbers - .gen
Table 4-3: Symbolic Generation Numbers
____________________________________________________________________
Generation Number Represents
____________________________________________________________________
.0 the highest existing generation number.
.-1 one greater than the highest existing
generation number.
.-2 the lowest existing generation number.
.-3 or * all existing generations.
____________________________________________________________________
4.2.7 File Attributes - ;A, ;P, ;T
;Adescriptor
;Pprotection
@DIRECTORY (OF FILES) *.*;A17
4.3 Using wildcards to specify files
@DIRECTORY (OF FILES) *.TXT
PS:<SMITH>
DATA.TXT.7
MAIL.TXT.5
TEST.TXT.1
Total of 3 files
@DIRECTORY (OF FILES) L*
PS:<SMITH>
LAST.TXT.10
LEVEL.DAT.1
LOOP.TXT.6
LOST.DAT.4
Total of 4 files
@DIRECTORY (OF FILES) *T
PS:<SMITH>
ACCTST.FOR.1
CKACCT.FOR.1
NEWACT.FOR.1
TEST.FIL.1
Total of 4 files
@DIRECTORY (OF FILES) L%ST
PS:<SMITH>
LAST.TXT.10
LIST.FOR.3
LOST.DAT.4
Total of 3 files
4.4 Specifying special characters - CTRL/V
4.5 Typing file specifications
@DIRECTORY E? FILE NAME
EXTRA
EXTUSR
EMACS
@DIRECTORY EMACS.? FILE NAME
INIT
VARS
@DIRECTORY EMACS.INIT.? FILE NAME
1
2
<ESC> <CTRL/F>
| |
@RENAME (FILE) PROG1.OAS.* (TO BE) PROG1.PAS
<ESC>
|
@TYPE (FILE) TEST.TXT.3
<ESC> <ESC>
| |
@COPY (FROM) NEW.FIL.1 (TO) TEST.TXT.4 !New generation!
@PRINT (FILES) ATEST.LOG, BTEST.LOG, CTEST.LOG
[Printer job ATEST queued, request #18, limit 9, 3 files]
4.6 Using logical names
@DEFINE (LOGICAL NAME) ALL: (AS) PS:<KONEN>,PS:<TEAM>
@DIRECTORY (OF FILES) ALL:TEST.FOR
PS:<TEAM>
TEST.FOR.5
@INFORMATION (ABOUT) LOGICAL-NAMES (OF) JOB
ALL: => PS:<KONEN>,PS:<TEAM>
@INFORMATION (ABOUT) LOGICAL-NAMES (OF) SYSTEM
ACCOUNT: => GIDNEY:<ACCOUNTS>
DEFAULT-EXEC: => SYSTEM:EXEC.EXE
.
.
.
SYS: => PS:<SUBSYS>,PS:<NEW>
TOOLS: => SNARK:<TOOLS>
@DEFINE (LOGICAL-NAME) TEST: SYS:,PS:<TEAM>,PS:<KONEN>
@COPY (FILE) CHECK.TST.1 (TO) ALL:CHECK.TST.1 !New file!
CHECK.TST.1 => <KONEN>CHECK.TST.1 [OK]
@DEFINE (LOGICAL-NAME) TEST:
@DEFINE (LOGICAL NAME) TS: (AS) PS:<TEST-SPECS>
@DIRECTORY (OF FILES) TS:
@DEFINE (LOGICAL NAME) PP:(AS) R4-PROJECT-PLAN.RNO
@EDIT PP: