Preface: This is an HTML approximation of the type-set documentation provided for some of the utilities in the Utility Disk #1. Subsequently, the printed documentation will be formatted differently than what is presented here.

Excerpts from Utility Disk #1 Documentation

LS-DOS 6 - Utilities 1

(derived from LS troff documentation - Version 1(5) 18-Jun-1993 Copyright 1993 M. A. D. Software, All Rights Reserved. HTML Version Copyright 1998 M. A. D. Software, All Rights Reserved. Duplication or other use is prohibited without prior written permission.

Name

LS - Displays directory contents

Syntax

ls: [ -1abdlmptuxz/.!?h ] [ wildspec ][ :drivespec ]... [>[>] file | device ] [ ; next command ]

Description

Ls lists the files on the specified drives. If a wildspec is specified, all files that match the wildspec will be displayed. If a drivespec is specified, only files on that particular drive or drives will be displayed. If the drivespec is omitted, all directories on all active drives are displayed. By default, the files are displayed in columns and are sorted alphabetically. Specifying options can cause additional information to be displayed, alter the sorting order, or change the format of the display. Ls accepts several options. Options are specified by single characters, and they may be entered in upper or lowercase. Options are always preceded by a hyphen (a "-"). If you are specifying multiple options, you can specify the options in any of these formats:

-a -b -c or -abc or -a -bc or -ab -c

The options are:

-1	Only one file is listed on each line. This is useful for building lists of files that will be used by other programs.
-a	"All Files". Files that are marked "invisible" will be displayed along with the rest of the files.
-b	Sorts the files in reverse (Backwards) order. By default the file named "A" (or the file with the most recent date) would be displayed first.
-d	The logical drive number is appended to each filename displayed.
-l	Each file is displayed in a long format, showing the size, date and permissions. This option provides information similar to that found in the system DIR (A) command. In the long format, a list of attributes are displayed for each file. These are represented by the characters dsifocun. If the file has a particular attribute, the letter is displayed. If the file doesn't have that attribute, a "-" is displayed instead. d The file is a PDS (Partition Data Set) or a DiskDisk subdirectory. s The file is a system file, usually part of the operating system. i The file is marked invisible and is displayed only if the -a option is specified. f The file has a fixed size. o The file is marked "open". If the OS is running in networked mode, files are marked this way so that only one application can have write access at a time. c The file is copy-protected. u The file has an user-password (only on pre-LS-DOS 6.3 and pre-LDOS 5.3 versions). n The file has been modified since the last time backup(L) made a copy of this file. The protection attribute for each file is also listed. Normally it is Full, but if the file has an Owner Password, it can be any of the following: Full The file has no restrictions on access. Remove The file attributes cannot be changed but all other access is allowed. Rename The file cannot removed, but all other access is allowed. Write The file can be read or written but not removed or renamed. Update The file can be read and updated, but cannot be removed, renamed or change size. Read The file can be read or executed, but no other access is allowed. Execute The file can be executed, but cannot be read or modified. None Without the Owner Password, the file cannot be accessed. If a file is accessed with the Owner Password, full access is always allowed. On older TRSDOS and LDOS versions, if the file has a User Password and an Owner Password, no access is allowed at all unless one of the two passwords are known.
-m	Files are displayed in the stream format, separated by commas. (Ignored if -l or -x is specified.)
-p	Output of ls is routed through the more(U1) utility. The screen will pause once 23 lines of text have been displayed. The more(U1) prompt ("--More--") allows you to advance or search through the remainder of the output. See the more(U1) command for additional information on the options that more(U1) provides. The -p option is ignored if the output is redirected.
-t	Files are sorted by time and date instead of by name.
-u	Filenames are displayed in uppercase. By default they are displayed in lowercase.
-x	Files are displayed in columns and are sorted horizontally instead of vertically (the default). (This option is ignored if -l is specified.)
-z	In the -l format, the file times are displayed in military hours instead of the AM/PM format.
-/ or -.	Forces the filenames to be displayed with "/" or "." as the extension character.
-!	Causes ls to ignore any default settings that are specified in the DEFAULTS/MAD file. Ls will also ignore any options that are specified to the left of the -! option. Note that the DEFAULTS/MAD file is accessed even if the -! option is specified.
-? or -h	Displays the help message.
wildspec	A wildspec specifies none or more files that are to be displayed in alphabetical order. A wildspec may contain none or more of the following wildcard characters: * The * matches zero or more characters in the specified position. For example, the wildspec AZ will match any of the following filenames: AZ ABZ ABCDEFGZ ABC/XYZ Note that unlike a LS-DOS/TRSDOS 6 partspec(L), the filename and extension are treated as a single unit. A single will match files with and without extensions. % The % matches exactly one character. So A%C matches: ABC AXC The file AC will not match the A%C pattern. [ ] Ranges specify multiple characters that may appear in a given position in the filenames being tested. There are two formats that can be combined: [abc] These specific characters are acceptable in this position in the filename. So A[BC5]D would match: ABD ACD A5D [b-e] The characters in this ASCII range are acceptable in this position in the filename. A[E-J]X matches: AEX AFX AGX AHX AIX AJX Numbers can also be included in ranges, but the first value of the range must always have a lower ASCII value than the second value. [!...] The ! excludes all files that match characters in this position. So A[!DKP]D will match all filenames that start with an "A", end with a "D", and the second character is any character except "D", "K", or "P". Combinations of ranges are also allowed. A[1-3ABD]X would allow these filenames: A1X A2X A3X AAX ABX ADX Any lowercase characters in the wildspec are converted to uppercase before the comparison is performed.
:drivespec	The drivespec specifies one or more logical drives that should be scanned for files that match the file wildspec. The % and * will examine all enabled drives. A range can also be used. For example, :[2-47] will search for files on drives 2, 3, 4 and 7. If the drivespec is not specified and a wildspec is, all drives are searched for files that match the file wildspec and all files that match will be displayed. So if the command ls sample/txt is used and the file SAMPLE/TXT exists on four different logical drives, all four files will be displayed.
[>] file \| device	By specifying a file or device, the output is sent to the specified file or device instead of the display. This is known as redirected output. For example, the command *ls a:5 > adir:0 places a list of files from logical drive 5 with names that start with the letter 'a' in the file ADIR:0*. If >> is used, ls will append the output of ls to the existing contents of the specified file or device. Filespecs* for redirection may not specify a password.
; next command	After ls completes, the remainder of the command line is executed as a second command. The command ls;date will display directory information, and then the date will be displayed.
<SHIFT>@	When pressed during output to the display, the output will pause. Pressing any other key resumes output. Pressing this key is ignored when output is redirected.

Files

Ls reads the DEFAULTS/MAD file and uses any default options that are specified there. For example, if you wanted ls to always display filenames in uppercase and the times in military hours, the following entry in the DEFAULTS/MAD file would do this:

LS -U -Z

Options in the DEFAULTS/MAD file are ignored if the -! option is specified on the command line. You may make copies of ls with different names. When examining the DEFAULTS/MAD file, the name used to invoke the program will be used to locate the default entries. For example, if you made copies of LS/CMD and named them NDIR/CMD and CAT/CMD, you could add the following lines to the DEFAULTS/MAD file:

LS -1
NDIR -LP/U
NCAT -X/U

When ndir is run, the output will be similar to what is produced by the system dir(L) command, ncat would display files in the same order as the system cat(L) command, and ls(U1) will display files one per line.

(derived from PIPES troff documentation - Version 1(1) 17-Jul-1993 Copyright 1993 M. A. D. Software, All Rights Reserved. HTML Version Copyright 1998 M. A. D. Software, All Rights Reserved. Duplication or other use is prohibited without prior written permission.

Name

PIPES - Connects two or more programs together.

Syntax

pipes [ -snre?h ] [ -d n ] program #1 [ | program #2 ] ... [ | program #n] [< file | device ] [>[>] file | device ]
[ ; next command group ]

Description

Pipes executes one or more commands from a single command line. Each command is separated by a semicolon (';') or a pipe ('|'). Separating commands with semicolons allows you to specify several LS-DOS commands or program names using a single command line. When the pipe operator ('|') is used instead of a semicolon, the text from one program that would normally be displayed is stored on disk and is provided as input to the next program that is specified. The output of the second program can then be "piped" to a third program, and so on. For example, if you would like to search through a directory display using the standard LS-DOS dir(L) command, you can use a command like:

pipes dir :0 (n) | more

In this example, the output of the LS-DOS library command dir(L) is intercepted and written to a file instead of the display as originally programmed. Then the second program, the more(U1) program, is run and when it reads from what it thinks is the keyboard, it is actually reading the data from dir(L) that has been stored in a file. Because more(U1) is the last program is this "pipeline", its output goes to the display.

Pipes are a powerful technique that allows compound programs to be created. This is done by connecting smaller programs together. These programs are unaware of the programs they are passing data to and from, and this means that existing programs and commands can be used without having to modify them.

The idea for pipes comes from the UNIX operating system, and is a standard feature in all versions. In the UNIX implementation, each program specified on the command line is run simultaneously, so as soon as the first program produces data, the second program can read it. Since LS-DOS is not a multi-tasking operating system, each program must run entirely before the next program can be started and allowed to see the data from the first program. This creates a few restrictions in how pipes can be used, but these are minor.

Pipes accepts several options. Options are usually specified by single characters, and they may be entered in upper or lowercase. Options are always preceded by a hyphen (a "-"). If you are specifying multiple options, you can specify the options in any of these formats:

-a -b -c or -abc or -a -bc or -ab -c

The options are:

-d drivenumber	Specifies what logical drive pipes should use for the temporary files it creates.
-s	When the first program attempts to read from the keyboard (KI), pipes* will provide a <SPACE> (ASCII 0x20) character to the program instead of actually reading the keyboard. No matter how many times the program reads the keyboard, it will always receive a <SPACE> character. This is useful if the program being executed pauses the display and is simply looking for a character to allow it continue. By default, the LS-DOS command dir(L) does this.
-n	Same as -s, except a [NULL] (ASCII 0x00) is supplied to the program.
-r	Same as -s, except a [ENTER] (ASCII 0x0D) is supplied to the program.
-e	Similar to -s, except that when the program tries to read the keyboard, it will always receive an end-of-file error (ASCII 0x1C). Some programs will exit when they see an EOF, and this may be desirable.
-? or -h	Displays the help message.
< file \| device	If a file or device is specified, when the first program specified reads data from the keyboard, pipes will read the data from the file or device until the end-of-file is detected or an error occurs. This is known as redirected input. Filespecs for redirection may not specify a password.
>[>] file \| device	By specifying a file or device, the output of the last program before the end of the line or before a semicolon (';') is sent to the specified file or device instead of the display. This is known as redirected output. For example, the command pipes lib > libtext:0 places the text from the lib(L) command in the file LIBTEXT:0. If >> is used, the output will be appended to any existing contents of the file. Filespecs for redirection may not specify a password.
\| program	The pipe symbol ('\|') indicates the end of one program specification, and the start of the next. Unlike the semicolon symbol (';'), the pipe symbol ('\|') instructs pipes to store all of the output of the program on the left of the pipe symbol, and provide that data to the program on the right of the pipe symbol. On the Model 4, 4D or 4P keyboard, the pipe symbol is produced by holding down the <CLEAR> key, then hold down the <SHIFT> key, then press the </> key.
; next command group	When pipes encounters a semicolon (';'), all options and redirection resets. Then the remaining command line is examined for new options, program names, pipes, and any new redirection specifications. A single command line for pipes can have as many semicolon-separated commands as desired.

Notes

Pipes works by loading a driver into high memory that intercepts I/O to the *DO, *SI, and in certain cases, the *KI devices. Pipes also intercepts the @EXIT and @ABORT supervisor calls. When pipes is invoked, it examines the command line up to the first semicolon it finds, looking for any redirection specifications. Then it goes back to the start of the command line looking for any options. When a program specification is found, that program is executed with the input and output routed as specified. Here are some examples of how pipes interprets different command lines:

pipes program1 < filea > fileb

PROGRAM1 is executed. If PROGRAM1 tries to read data from the keyboard, the data is actually read from FILEA. Anything that PROGRAM1 wants to display is stored in FILEB. Note that the < and > specifications, plus any other parameters that pipes are not passed to the programs being executed.

pipes -s program1 > filea

PROGRAM1 is executed. If PROGRAM1 tries to read a character from the keyboard, it will always get a <SPACE> character. Any output from PROGRAM1 is stored in FILEA.

pipes date ; time 12:34:56 > filea ; lib

The programs date(L), time(L) and lib(L) are executed in that order. The output of date(L) and lib(L) goes to the display since they are not redirected. The output of time(L) is stored in FILEA. The parameter to the time(L) program is passed just as it was present on a normal LS-DOS command line.

pipes date > filea ; time >> filea

The programs date(L) and time(L) are executed in that order. The output of date(L) is stored in the file FILEA, and the output of time(L) is appended to the contents of FILEA.

pipes lib | wc

The library command lib(L) is executed and the display output is stored on disk. Then the program wc(U1) is executed and reads the data from lib(L) that was stored. Since wc is the end of the pipeline, its output is sent to the display.

Note that the spaces around the | and ; in these examples are optional. The command pipes lib|wc is accepted.

pipes time ; wc | more +/1024 < filea > fileb ; date

The library command time(L) is executed and its output is sent to the display. Then the program wc(U1) is executed and it reads data from FILEA. The output of wc(U1) is stored on disk. Then the program more(U1) is executed and it reads the data from wc(U1) that was stored on disk. The output of more(U1) is stored in FILEB. Finally, the date(L) command is executed and its output is displayed.

pipes -r dir :0 | more ; dir :1

The library command dir(L) will be executed and it will produce a list of files on drive 0. This data will be stored on disk. Because the -r option is specified, each time dir(L) pauses the display, it will immediately think the [ENTER] key has been pressed and will display the next page of files. Once dir(L) is finished, more(U1) will be executed and it will display the list of files that dir(L) created. If the -r (or one of the other options) was not used, dir(L) would pause and wait for a key to be pressed, but since nothing is being displayed, you would not know when or how many times a key needed to be pressed. Finally, the dir(L) command is executed a second time and will produce a list of files on drive 1. Because options reset when a semicolon (';') is encountered, the -r option from earlier no longer applies and the user must press a key to cause the display from the dir :1 command to advance from one page to the next.

Note that no matter how many programs are connected together with pipes, any redirection must be specified after the last program. The redirected input only affects the program at the start of the pipeline, and the redirected output only affects the last program on the pipeline.

When the entire command line has been processed, or if an error occurs, pipes resets all the devices to their normal states, and then will attempt to remove itself from high memory. If another high memory module (driver, filter, etc) is loaded from within pipes, the memory that pipes was using cannot be released. Pipes will reuse the unreleasable memory in later invocations.

To keep the size of pipes to a minimum, it only has a limited number of error messages. When pipes encounters an error, it aborts immediately, and will display a message containing the phrase "broken pipe". Normally, the actual cause of the error will be displayed by the operating system or the program that aborted. However, if the output of that program was being sent to a pipe, the message will not be displayed. Instead it was stored on disk. In these cases, any specific error message has been stored in one of the PIPE files.

Pipes will abort if logical drive 0 (or the specified drive) runs out of disk space, or is write protected. In these cases, the error message will indicate which file pipes is having trouble with.

Pipes cannot be invoked from within pipes.

Ideally, all applications would read data from *SI and write to *SO, which are normally routed to *KI and *DO, respectively. But unfortunately, hardly any programs do this, making it difficult for a program to accept data from a pipe and prompt the user at the keyboard. Programs that need to do this must read data that might be redirected from *SI, and read the responses to any user prompts from *KI. All the programs in the Utilities Disk 1 do this. This is how more(U1) can be reading data from standard input (either redirected or from a pipe), and still prompt the user to find out what it should do next.

When you specify -n, -s, -r or -e in pipes, the generated characters (or errors) are provided to the first program on the command line (or after a semicolon) if it tries to read from *KI. Unless redirected by a < specification or a pipe, reading from *SI is the same as reading from *KI. When redirection does occur, programs that read from *SI will be reading data from the specified file, device or pipe.

To install pipes as the Immediate Execution Program (IEP), in LS-DOS, use the command:

COPY PIPES/CMD SYS13/SYS:0 (C=N)

Once done, pipes can be invoked by typing an asterisk ('*') instead of the word pipes.

Files

Pipes creates PIPES0 and PIPES1 on logical drive 0 unless you specify another drive. These files are intentionally left after pipes finishes executing. Because the space is already allocated, pipes can run faster the next time it is invoked. Also, if a lengthy pipeline aborts without displaying anything, the files can be examined for error messages that may help you determine which program had problems.

Credit

Pipes for LS-DOS is based on the program MCM written by Frank Durda IV, which appeared in The Misosys Quarterly (Vol IV, No IV), and is used with permission. The syntax of pipes and redirection is based on the Berkeley CSH ("C" shell, a command interpreter) for UNIX systems.

To order the complete Utility Disk #1, specify:

Model 4/4D/4P Utility Disk #1, Part Number 4G6UT01 $15.00

How to place an order with M. A. D. Software.

To return to the Utility Disk #1 description, click here.