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.
(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.
-a -b -c or -abc or -a -bc or -ab -cThe 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.|
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.
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.|
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 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.|
LS -U -ZOptions 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 -1When 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.
pipes dir :0 (n) | moreIn 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 -cThe 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
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.|
pipes program1 < filea > filebPROGRAM1 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 > fileaPROGRAM1 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 ; libThe 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 >> fileaThe 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 | wcThe 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 ; dateThe 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 :1The 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.
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.
Copyright 1988, 1992, 1996, 1998, 2000, 2001, 2002, 2004, M. A. D. Software, All Rights Reserved.
MADSOFT is a trademark of M. A. D. Software.