PIPES(U1)

Name
PIPES - Connects one or more programs together.

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

Description
Pipes is a powerful program that 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 programs 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
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. The idea of pipes comes from *NIX, and is a standard feature in all versions. In the *NIX 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 following any options attempts to read from the keyboard (*KI), pipes will provide a <SPACE> (ASCII 0x20) character to the program instead. 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 let it continue. The LS-DOS command dir does this by default.

-n  Same as -s, except a <NULL> (ASCII 0x00) is supplied to the program.

-r  Same as -s, except a <RETURN> (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 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.

| next command group
    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.

; 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.

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 a 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 the program tries to read data from the keyboard, it is actually read from FILEA. Anything that the program 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 the program tries to read a character from the keyboard, it will always get a <SPACE> character. Any output from the program is stored in FILEA. pipes date ; time 12:34:56 > filea ; lib The programs DATE, TIME and LIB are executed in that order. The output of DATE and LIB goes to the display. The output of TIME is stored in FILEA. The parameter to the TIME program is passed just as it is typed. pipes date > filea ; time >> filea The programs DATE and TIME are executed in that order. The output of DATE is stored in the file FILEA, and the output of TIME 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 that was stored. Since wc is the end of the pipe, its output is sent to the display. 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 reads the data that wc(U1) 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 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 created. If the -r (or one of the other options) was not used, dir 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 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 dir :1 display to advance from one page to the next. Note that no matter how many programs are connected together with pipes, any redirection is specified after the last program, and 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 un-releasable 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, the error 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 can be reading data from standard input (either redirected or from a pipe), and still prompt you to display the next page. When you specify -n, -s, -r or -e in pipes, these 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.

Files
Pipes creates PIPES0 and PIPES1 on logical drive 0 unless you specify otherwise. These files are intentionally left after pipes finishes executing. Because the space is already allocated, pipes will run faster the next time it is invoked. Also, if a lengthy pipe aborts without displaying anything, the files can be examined for error messages that can 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 *NIX systems. If you need more information on pipes(U1), please write to M.A.D. Software, P.O. Box 331323, Ft. Worth Texas, 76163. Please include a Self-Addressed-Stamped-Envelope when requesting information.
------
307171