[Indigo]<AltoSource>ALTOUSERSHANDBOOK.DM!2>DDS.bravo

Page Numbers: Yes X: 530 Y: 10.5" First Page: 103 Not-on-first-page
Margins: Top: 1.3" Bottom: 1" Binding: -8
Odd Heading: Not-on-first-page

DDS REFERENCE MANUAL

Even Heading:

DDS REFERENCE MANUAL

DDS Reference Manual

Table of Contents

0.The mouse and cursor104

1.The display104

1.1The viewspec area104

1.2The filter area106

1.3The data area107

1.4Marking files107

2.Commands109

2.1Internal commands109

2.2External commands110

2.3Error messages111

3.User profile112

4.The command line114

The Descriptive Directory System (DDS) is a front end for the Alto file system that provides substantially greater flexibility than the TAB and "?" features in the Executive. In addition to file names, DDS can display file lengths, creation-read-write dates, and contents. This reference manual describes release 1.12 of DDS.

0. The mouse and cursor

1.1 The viewspec area

The three buttons on the mouse are called RED (left or top button), YELLOW (middle button), and BLUE (right or bottom button). Most mouse-controlled actions in DDS happen as soon as you depress the mouse button: these are described below using phrases like "RED does xxx", meaning "As soon as you depress RED, xxx happens." Some actions require depressing a button and then releasing it: phrases like "clicking RED does xxx" mean "If you depress RED and then release it, xxx will happen." Careful reading, or a little experimenting, will familiarize you quickly with the distinction.

The cursor changes shape according to its location on the display and according to how DDS is interpreting the buttons. Generally speaking, when the cursor is circular, RED selects what you are pointing at in some way, and BLUE deselects it. When the cursor assumes the shape of an hourglass, DDS is busy doing something and is not listening to the mouse buttons.

1. The display

Like Bravo, DDS divides the display into a command area at the top, and one or more windows below. Currently DDS just supports a single window. A heavy black bar separates the command area from the window. Section 2 (below) describes the command area.

The window has three parts, separated by lighter horizontal bars:

1) The top part is the view specification area, or viewspec area for short. It contains a set of keywords that describe what information is to be displayed for the files being examined in this window, and a set of keywords that describe how the displayed files are sorted.

2) The second part is the filter specification area, or filter area for short. It contains a pair of expressions which together determine what set of files is being examined in the window. View and filter specification are completely independent: each can be changed without affecting the other.

3) The main part of the window is the data area, which actually displays a set of files. The names are always displayed: other information is controlled by the viewspecs.

1.1 The viewspec area

There are 9 keywords in the viewspec area that control what is displayed:

createdthe date when the file was created

writtenthe date when the file was last altered

readthe date when the file was last read

referencedthe date when the file was last referenced (i.e. the most recent of "created", "written", and "read")

sizethe size of the file in disk pages

lengththe length of the file in bytes (characters)

addressthe hardware address, in the form directory-pointer: (SN1,SN2)!VN @ virtual-leader-address

contentsthe contents of the file (in octal, if a binary file)

pagemapthe disk addresses of all pages of the file, with a "*" before each address which is not adjacent to the preceding one

If the keyword is displayed white-on-black, the corresponding information is displayed in the data area, otherwise not.

There are 6 keywords that control other aspects of how the data are displayed:

(marked)if turned on, DDS only displays marked files (see sec. 1.4 below)

(small)if turned on, DDS uses a smaller font for the data, which allows more data to appear on the screen (see sec. 3 below for how to tell DDS the name of the font)

(packed)if turned on, DDS displays several files per line if possible (not implemented yet)

(times)in conjunction with "created", "written", "read", or "referenced", shows the time of day as well as the date

(browse)if turned on, then when "contents" is turned on, DDS only displays the first 5 lines of text files and the message "*** binary file ***" for binary files, instead of the complete contents of the file.

(chart)if turned on, changes the data display to be a chart made up of boxes in which the height of the box is proportional to the file length. (Try it -- you’ll like it.)

When the cursor is positioned over a keyword name, RED turns the keyword on; BLUE turns the keyword off. When the cursor is over the word "Show:" at the upper left of the keywords, BLUE turns all keywords off.

There are currently 8 keywords that control sorting of the data:

namealphabetic order by name (upper and lower case letters are equivalent)

extensionalphabetic order by extension

createdthe corresponding date and time

written

read

referencedthe date last referenced

lengththe file length

serialthe file’s serial number (not of general interest)

The keywords which are displayed white-on-black are those actually used to sort the data area. They are displayed in the order most- to least-significant criterion, e.g. "extension↑" followed by "name↑" means sort by extension first, then sort files with the same extension by name. Following each keyword, whether active or not, is an arrow which indicates whether the sort is to be in ascending (upward arrow) or descending (downward arrow).

When the cursor is positioned over a sorting keyword name, clicking RED turns the keyword on and adds it to the list of white-on-black keywords actually used for sorting; clicking BLUE turns the keyword off and removes it from the list; clicking YELLOW inverts the direction of the arrow, regardless of whether the keyword is in the list. When the cursor is over the words "Sort by:" at the left of the sorting keywords, BLUE turns off all sorting criteria.

Since sorting may take a long time and it is easy to request sorting by accident, you can abort sorting at any time by typing any character. Be sure the cursor is not in the data area when you do this: if it is, DDS may start the sort over again!

Whenever the cursor moves into the data area, regardless of whether any mouse buttons are down, DDS repaints the display to be as specified by the viewspecs if the viewspecs have changed since the last time the display was repainted.

1.2 The filter area

The filter area contains two expressions which defines what subset of the directory will actually be displayed in the data area. These expressions are built up from name patterns which are similar to those recognized by the Alto Executive. More precisely, a name pattern is a sequence of characters which may contain "*"s and "#"s: "*" matches any sequence of characters in a name (including no characters at all), "#" matches any single character. Upper and lower case letters are not distinguished. Note that DDS deletes the final "." from file names. Here are some examples of name patterns and what they match:

*.BCAll files with extension BC (or bc, bC, or Bc).

*.BAll files with extension B.

*.B*All files whose names contain the string .B -- this includes all files with extension Bsomething, but also includes files like THIS.BINARY.THAT.

*.B#All files whose extensions consist of B and one more character.

*All the files in the directory.

You can build up more complex expressions using the words "and", "or", and "not", and parentheses. Here are some examples of such expressions and what they select:

LPD* and not *.tempAll files beginning with LPD, except those with extension temp.

*.memo or *.memo$All files with extension memo or memo$.

(*.BT or *.BS) and not X*All files with extension BT or BS, except those beginning with X.

The upper expression in the filter area is called the selspec; the lower one is called the context. (The two together are simply called the filters.) Only files which satisfy both expressions will be displayed. The idea is that if you are going to be working on memos, for example, you can set the context to "*.memo" and use the selspec to further select within this set. As another example, if there is some set of files you want not to see (like "*$"), you can set the context to "not *$".

To change the selspec or the context, point at it, or at the word "Selspec:" or "Context:", and click RED or YELLOW. This will cause it to change to white-on-black. As soon as you start typing, the old text will vanish and what you type will appear white-on-black in its place. Eventually you must type one of the following three things before you can point anywhere else or select any commands (see sec. 2 below):

CRconfirms the change, and repaints the display to reflect it.

ESCis equivalent to *CR, i.e. it adds a * to what you have typed and then confirms the change.

DELaborts the typein and restores the old selspec or context expression.

See section 3 below for how to get the selspec and/or context initialized automatically to something other than "*" when you first enter DDS.

The third line of the filter area is a message of the form "nnn files are selected, of which mmm are marked" where nnn is the count of files selected by the current filter and mmm is the count of those which are marked (see 1.4 below). If there are marked files not selected by the filter (again, see 1.4), the message "there are kkk files marked but not selected" also appears. While DDS is sorting data, the message Sorting ... appears in this area in place of the file counts.

1.3 The data area

As mentioned above, whenever the cursor moves into the data area, DDS regenerates the display if necessary to conform to the current viewspecs.

The left edge of the data area is a scrolling bar which works the same way as in Bravo: clicking RED scrolls up, clicking BLUE scrolls down, and clicking YELLOW jumps proportionately to the vertical location in the window. A hollow arrow in the left margin shows where in the list you are positioned: if the arrow is at the top, you are at the beginning of the list; if the arrow is at the bottom, you are at the end. The idea is that if you were to move the cursor to this arrow and click YELLOW, the list would stay positioned just as it is.

If you are positioned at the beginning of the list of selected files, DDS displays the message

"~~~~~ BEGIN ~~~~~"

at the head of the list; if not, DDS displays

"~~~~~ nnn files not shown ~~~~~"

indicating the position within the list of the first file actually shown on the screen (e.g. "2 files not shown" means the first file on the screen is actually the third in the list). Similarly, if the last file shown on the screen is actually the last file in the list, DDS displays

"~~~~~ END ~~~~~"

below it.

A vertical strip at the right edge of the data area will be used in the future to control the formatting of the screen into windows. Currently the cursor changes shape when it is in this area, but the buttons have no effect. Another vertical strip just to the left of this one is used for mass marking and unmarking of files: see the following section.

1.4 Marking files

DDS provides a facility for marking any set of files for later processing by commands such as <Delete>, <Send to Maxc>, etc. Marked files are displayed with a small dark arrow in the left margin, and a count of how many marked files are in the current selected set is maintained in the filter area. When the cursor is in the data area of a window, other than the right or left edge areas, the mouse buttons control marking and unmarking of individual files: RED marks the file on whose line the cursor resides; BLUE unmarks the file. When the cursor is in the vertical strip about 1" in from the right edge of the screen, the cursor changes to the word ALL, and the buttons mark and unmark files en masse: clicking RED marks all the files selected by the filter; clicking BLUE unmarks all the files.

Note that files may be marked even though they are not selected by the current filter, i.e. marking is associated with the file rather than the display. (If this proves confusing it will be changed.) The count of "files marked but not selected" in the filter area lets you know when there are marked files not selected by the current selspecs.

Since marking or unmarking individual files occurs as soon as the button is depressed, you can hold down RED or BLUE and slide the mouse (slowly) in the vertical direction to mark or unmark a group of adjacent files.

The marked file counts in the filter area are adjusted as soon as a file is marked or unmarked, but if the "marked" viewspec is on and you unmark a file, you must scroll the data to get the unmarked file(s) deleted from the display.

2. Commands

The command area at the top of the screen consists of four parts:

1)A header with the DDS version number, time of day, and count of free disk pages;

2)A type-in area, where typed characters appear;

3)An error message line;

4)A menu of commands, each command being enclosed in angle brackets <>.

When the mouse is in the command menu area, RED selects a command for subsequent execution: the selected command is displayed white-on-black, and any previously selected command is deselected. BLUE deselects the currently selected command and selects the default command <Quit>. Typing ESC or CR finally initiates the command: you can freely select or deselect commands, type and edit your type-in, change viewspecs, etc. up to that moment. For commands which do not require type-in, you may also initiate the command by clicking YELLOW with the mouse in the command menu area. The cursor takes the shape of a circle with a cross when this is allowed, and a circle with a dot when it is not.

Some commands require or allow type-in before the final ESC or CR. You may type at any time. All typed characters are accumulated in the type-in area just below the header until the ESC or CR. CTRL-A (or BS), CTRL-W, CTRL-Q, and DEL are available for editing as in Bravo. DDS displays a vertical bar when it is waiting for your typing, and of course you can "type ahead" while DDS is processing a command. However, as for selspec and context changes (sec. 1.2), once you have started to type, you must either confirm the command with ESC or CR, or abort with DEL, before you can select another command or another place to type (selspec or context).

When you have selected a command with RED, then when you release the button, DDS may display something in the type-in area which is a default for that command. If you want to execute the command with that default type-in, you can just confirm it (with ESC, CR, or YELLOW); otherwise, the default disappears as soon as you start typing, just like the old selspec or context.

In the description of commands below, "something" following the command name means that DDS expects you to have typed something before the final ESC or CR that initiates the command; "optional-something" means you may type something or not. To help you remember, all the commands that require type-in end with "...", and those which allow but do not require type-in end with "[...]".

Many commands operate on a set of files: they use precisely those files which, at the time you type the final ESC or CR, are both selected (i.e. match the selspec) and marked. "Filename-1 ... filename-n" in the descriptions below refer to these files, which are also called the "designated" files.

DDS presently has two classes of commands: those which leave you in DDS after execution (internal commands), and those which send you back to the Alto Executive (external commands). For external commands, DDS saves away a command line so that if something goes wrong, you can execute the command again by typing @Dds.cm@CR to the Executive.

2.1 Internal commands (those which leave you in DDS)

<Put on file ...> "filename" writes on the file named "filename" (in text form) the contents of the window. DDS also writes a header with your name, the disk name, and the date and time. The default for "filename" is "Dir.Lst", an arbitrary name which DDS supplies so you don’t have to make one up.

<List on file ...> "filename" writes on the file named "filename" (in text form) the names of the designated files, separated by blanks. This makes it easy for you to make up an @-file for the Executive by adding a command name to the front of this file. The default for "filename" is "Dir.Cm", an arbitrary name which DDS supplies so you don’t have to make one up.

<Delete> deletes the designated files. There is presently no way to un-delete files, so be careful: the count of marked files in the filter window is a good clue as to whether you are deleting more than you want. You can stop a <Delete> at any time by typing any character: of course, some files may already have been deleted. DDS changes the "free pages" count at the top of the screen as it deletes each file.

<Rename as ...> "filename" requires that there be exactly one designated file, and changes its name to "filename". If there is already a file named "filename", <Rename> gives an error message and does nothing else.

2.2 External commands (those which leave you in the Executive)

<Quit> leaves DDS gracefully. SHIFT-SWAT is also safe whenever DDS is awaiting input (i.e. not in the midst of sorting, deleting, etc.).

<Bravo/[...]> "optional-switches" gives control to Bravo in the following way:

If there are no designated files, DDS effectively executes "Bravo/switches".

If there is more than one designated file, DDS gives an error message and does nothing else.

If there is a single designated file and you did not type anything, DDS effectively executes "Bravo/N filename", i.e. instructs Bravo to read in the file.

If there is a single designated file and you did type in switches, DDS executes "Bravo/switches filename".

<Gears/[...]> "optional-switches" executes "Gears/switches filename-1 ... filename-n", i.e. prints the designated files.

<Send to Maxc directory <...>> "directory-name" sends the designated files to the directory named "directory-name" on Maxc, using FTP. The default for directory-name is the user name on your Alto disk. If you accept the default, DDS assumes you have already done a Login in the Executive to supply the password; if you supply some other directory-name XYZ which requires a password, FTP will prompt you with a message asking you to type in the password for XYZ at that time.

<Send to ...> "name" sends the designated files to the Alto whose name is "name", using FTP. "Name" may be anything acceptable to FTP, i.e. an Alto name, an Alto number, etc. The default for "name" is Maxc, which is not really very useful.

<Execute ...> "command" constructs a command line formed from "command" and the names of the designated files, and then executes the command line thus formed by either jumping directly to the subsystem or returning to the Alto Executive. (If there are no designated files, DDS produces an error message "No files are marked" and does nothing else.) The command line is formed in the following way:

If "command" does not contain any "*" characters, the command line is just "command" followed by the names of the designated files. For example, if files Alpha and Beta are designated, <Execute ...> "Bldr/L" would execute the command line "Bldr/L Alpha Beta". "String" may contain blanks, so for example <Execute> "Bldr Foo/S" would execute "Bldr Foo/S Alpha Beta".

If "command" does contain a "*", DDS divides "command" into 3 parts "s1 s2*s3", where s2 is the part of "command" extending backwards from the "*" to the first preceding blank (or the beginning of "command"). Then the command line is "s1 s2f1s3 s2f2s3 ..." where f1, f2, etc. are the names of the files. For example, if Alpha and Beta are designated, <Execute ...> "Bldr @*@" would execute the command line "Bldr @Alpha@ @Beta@". (If this seems confusing or useless, don’t worry about it too much -- some future version of DDS may find a better way to provide this facility.)

2.3 Error messages

Non-fatal error messages appear in bold characters just below the type-in line. Such messages always abort the current command and reset the command to <Quit>, but they do not change the state of DDS in any other way. The message disappears as soon as you type any character.

Fatal errors cause DDS to call Swat. When this happens, the screen changes completely and a heading like "Swat.21 (August 28, 1976)" appears at the top; the error message itself appears at the bottom of the screen just above a "#". Fatal errors are never supposed to happen, but if one ever does, summon a DDS expert. If none is available, write down the message and what you were doing at the time, and then type CTRL-K. This will throw you out of DDS and back to the Executive.

3. User profile

DDS examines the user profile (User.Cm) during initialization to obtain the names of the fonts which will be used to display various things, and other rarely-changed information. Just as Bravo’s section of User.Cm begins with [BRAVO] and then follows the format of OPTION:STRING, DDS looks for [DDS] and follows the same format for its entries.

The entries which DDS recognizes in User.Cm fall into two classes. "Initialization-only" entries are those which DDS only consults when you ask it to do a full initialization (by using the FULLINIT: Yes entry in User.Cm, or the /I switch in the command line, both described below). "Ordinary" entries are those which DDS looks at every time.

The names of the "ordinary" entries are:

FONT: fontname - specifies the name of the normal font (used for the command window, the file count line, and the data area).

BOLDFONT: fontname - specifies the name of the bold font (used for error messages, the viewspec and selspec display, and the headings on the data area).

SMALLFONT: fontname - specifies the name of the small font (used for displaying data when the "(small)" viewspec is turned on).

SMALLBOLDFONT: fontname - specifies the name of the small bold font.

USERTYPE: type - lets DDS know what kind of user you are. If type is NON-PROGRAMMER, DDS doesn’t provide the "pagemap" and "address" viewspecs. If type is WIZARD, DDS provides some extra features for debugging which are not described in this document.

WINDOWS: Yes - enables you to use some experimental facilities for splitting the screen into multiple windows in a Bravo-like manner. These facilities are not documented, not fully debugged, and not recommended.

RAMOK: Yes - tells DDS to use the RAM on your Alto. If your Alto is a standard one, this will make DDS run about 30% faster; if not, DDS may not run faster, and may not run at all. Try it once (or use the /R switch in the command line as described below) and see what happens.

FULLINIT: Yes - tells DDS to scan the whole Alto file directory each time it starts up, and reinitialize the selspec, context, etc. from the "initialization-only" entries in User.Cm (possibly overridden by the command line: see sec. 4). FULLINIT: No - tells DDS to update its knowledge of the world from Sys.Log (an incremental record of file activity since you last ran DDS), and restore the selspec, context, etc. to what they were when you last left DDS. The default is FULLINIT: No which leads to much faster startup.

The names of the "initialization-only" entries are:

SELSPEC: expression - specifies the initial value of the selspec when you enter DDS. If there is something illegal about the expression, DDS just uses "*" for the initial selspec, as though there were no SELSPEC entry in User.Cm.

CONTEXT: expression - specifies the initial value of the context when you enter DDS.

SHOW: list of viewspecs - allows you to initialize the viewspecs. Use commas between viewspecs if there is more than one.

SORT BY: list of sorting keywords - allows you to initialize the sorting order. Each keyword may be followed by "↑" for ascending order or "←" for descending order (neither means ascending order). Use commas between keywords if there is more than one.

A word about fonts: if FONT is not specified in User.Cm, DDS uses the standard system font SysFont.Al. If BOLDFONT is not specified, DDS fabricates a boldface version of the normal font, whatever it may be. If SMALLFONT is not specified, the "(small)" viewspec has no effect. If you specify a font name and there is no file by that name, DDS just ignores that entry in User.Cm.

4. The command line

Just typing Dds to the Alto Executive will activate DDS in its normal way, in which various aspects of its behavior are controlled by entries in User.Cm if present. However, you can override User.Cm by typing switches following the name DDS to the Executive. Here are the switches currently implemented:

Dds/Iequivalent to FULLINIT: Yes in User.Cm.

Dds/-Ioverrides (cancels) FULLINIT: Yes in User.Cm.

Dds/Requivalent to RAMOK: Yes in User.Cm.

Dds/-Roverrides (cancels) RAMOK: Yes in User.Cm.

Dds/Wequivalent to WINDOWS: Yes in User.Cm.

Dds/-Woverrides (cancels) WINDOWS: Yes in User.Cm.

Dds/Scauses DDS to write some statistics in a file Dds.stats. Not currently of general interest.

Dds/Pcauses DDS to write some data regarding disk activity in Dds.stats. Not of general interest.

These switches can be combined, e.g. Dds/I/R causes both full initialization and use of the RAM. Switches may be either upper or lower case.

If DDS is doing a full initialization (either because FULLINIT: Yes appears in User.Cm or because you said Dds/I), you may also supply initial selspec and context strings in the command line, and these will take precedence over those in User.Cm, if any. Unfortunately, the Alto Executive makes it a little inconvenient to include *’s in these strings, and you can’t have blanks in them at all. To include a *, you must type ’*, e.g. to start up DDS and specify alpha* as the selspec, you must type
Dds/I alpha’*
to the Executive. To specify beta* as the selspec and *.cm as the context, you must type
Dds/I beta’* ’*.cm