REDIR VER 3.1 USERS GUIDE ------------------------- Copyright 1987 James Apolis SCOPE: REDIR is a console I/O redirection program. It's a flexable tool that allows the user to have complete control over console I/O operations. It also has batch processing capabilities making it possible to perform a multitude of complexed tasks automatically. This program was written using Z80 assembly language for compactness and speed. It has been tested and is known to work well with CP/M 2.2 and MP/M-II. INTRODUCTION: REDIR has three principal functions. The first is the redirect output function. This function allows all of the console output performed by a transient program to be redirected to one or more of the devices which are capable of accepting characters to output. e.g. console, printer, punch, null, file. The second function is redirect input. This function allows all of the console input performed by a transient program to be redirected from any one of the possible devices which are capable of providing characters. e.g. console, reader, file. The third function is echo input. This function allows all of the console input performed by a transient program to be echoed to one or more of the devices which are capable of accepting characters to output. e.g. console, printer, punch, file. In addition to its redirection control, it also has the capability to execute command lines from a file. This gives the program submit like capabilities. This kind of batch processing coupled with flexible console I/O control gives the program a great deal of control and flexibility. Page 1 COMMAND SYNTAX: REDIR ? for help REDIR {[BEP]} {>or>>(1)} {/or//(2)} {<(3)} du:command cmd_tail REDIR {[BEP-B-E-P]} =du:filename.typ {variable1 variable2...} Fields (1),(2) and (3) can be one or more of the devices described in the table below under the "DEVICES" column. When multiple devices are specified they must be seperated by a comma. See the description of these fields for a more detailed definition. --------- F I E L D -------- (1) (2) (3) DEVICES DESCRIPTION DIRECTION RED OUT ECHO IN RED IN ------- -------------- --------- ------- ------- ------ CON: Console device In/Out Yes Yes Yes RDR: Reader device In No No Yes PUN: Punch device Out Yes Yes No LST: List device Out Yes Yes No NUL: Null device Out Yes No No FILE File device In/Out Yes Yes Yes Page 2 REDIRECTING CONSOLE OUTPUT -------------------------- > Redirect console output command. This command will cause all console output to be redirected to a file and/or one or more of the specified devices which are capable of accepting output data. This would include any characters output from the transient program that would normally be displayed at the console. If a file name is specified then any existing file by that name is overwritten. The CON: (console) device is the default device if this command is not specified. >> Redirect console output and append to file command. Same as ">" command exept data is appended to the output file. (1) This field specifies where to redirect all console output to. The possible output devices are: du:filename.typ, CON: for console, PUN: for punch, LST: for list, and/or NUL: for null. The PUN: device is allowed only on CP/M systems. Valid drives for the file are A thru P, S for the system drive, and T for the temporary drive. For CP/M the system and temporary drives are set to drive A, and the system and temporary user numbers are set to 0 unless the program is patched otherwise. Valid user numbers are 0 thru 15. If no file type is specified then it will default to ".OUT". If a drive and/or user is specified then only that drive/user area will be searched for the file. If no drive or user is specified then the default area will be searched first then the system drive and user. One or more devices can be specified. Multiple devices must be seperated by a comma. A single device or file name can't be specified more than once. If a file name is specified, it can't be the same as the file name specified for field (2) or (3). EXAMPLE: >CON:,B1:OUTFILE,LST: This example will redirect console output to a file on drive B user 1 called "OUTFILE.OUT". It will also send console output to the console and list devices. Page 3 ECHOING CONSOLE INPUT --------------------- / Echo console input command. This command will cause all console input to be echoed to a file and/or one or more of the specified devices which are capable of accepting output data. This would include any characters that are input by the transient program that would normally be typed at the console. If a file name is specified then any existing file by that name is overwritten. The NUL: device is the default device if this command is not specified. // Echo output and append to file command. Same as "/" command exept data is appended to the output file. (2) This Field specifies where to echo all console input to. The possible output devices are: du:filename.typ, CON: for console, PUN: for punch, and LST: for list. The PUN: device is allowed only on CP/M systems. Valid drives for the file are A thru P, S for the system drive, and T for the temporary drive. For CP/M the system and temporary drives are set to drive A, and the system and temporary user numbers are set to 0 unless the program is patched otherwise. Valid user numbers are 0 thru 15. If no file type is specified then it will default to ".IN". If a drive and/or user is specified then only that drive/user area will be searched for the file. If no drive or user is specified then the default area will be searched first then the system drive and user. One or more devices can be specified. Multiple devices must be seperated by a comma. A single device or file name can't be specified more than once. If a file name is specified, it can't be the same as the file name specified for field (1). EXAMPLE: /B1:ECHOFILE This example will echo console input to a file on drive B user 1 called "ECHOFILE.IN". This is the method used to create input files for the redirect console input command. Page 4 REDIRECTING CONSOLE INPUT ------------------------- < REDIRECT console input command. This command will cause all console input to be redirected from a file or a device which is capable of providing input data. This would include any characters that are input by the transient program that would normally be typed at the console. The CON: device is the default device if this command is not specified. (3) This field specifies where to get console input from. The possible input devices are: du:filename.typ, CON: for console, RDR: for reader. The RDR: device is allowed only on CP/M systems. Valid drives for the file are A thru P, S for the system drive, and T for the temporary drive. For CP/M the system and temporary drives are set to drive A, and the system and temporary user numbers are set to 0 unless the program is patched otherwise. Valid user numbers are 0 thru 15. If no file type is specified then it will default to ".IN". If a drive and/or user is specified then only that drive/user area will be searched for the file. If no drive or user is specified then the default area will be searched first then the system drive user 0. Only one input device and one alternate input device can be specified. If the end of the file is encountered REDIR will terminate unless an alternate device had been specified in which case it will switch to the alternate. Multiple devices must be seperated by a comma. A single device or file name can't be specified more than once. If a file name is specified, it can't be the same as the file name specified for field (1). EXAMPLE: OUTFILE,CON: /INFILE A0:ASM $1 EXAMPLE: ;This line will be displayed but not executed. EXAMPLE: ;;This line will not be displayed or executed. Page 7 TARGET COMMAND -------------- command This is the target command to execute when redirecting console I/O. This must be a transient command (A command file which is present on the disk). Built in CP/M commands like TYPE, DIR, ect. can't be redirected Since they are not loaded from the disk when executed. cmd_tail This is the command tail of the target command. This should be entered exactly as you would normally for the program you are executing. OPTIONS ------- [B] Background mode. This option performs three functions. (1) Under MP/M this option causes the program to detach automatically after it is executed and return to the system prompt. (2) Under CP/M or MP/M this option also causes REDIR to inhibit polling for special characters entered at the console when the program is receiving input from a file (eg. ^C ^D ^S ^\). (3) Under CP/M when using the PUN: device, this option causes console status calls to return with status indicating that a character is never ready, otherwise characters are always ready. This is necessary since there is no BDOS or BIOS call to check the status of the reader port as there is for the console. [E] Inhibit trapping of BDOS errors. You should use this option when executing REDIR under other memory resident type programs (eg. programs that remain in memory). REDIR does not remain in memory after ending but it is resident during its execution. This will help the two programs not to collide with each other causing the system to crash. This option is only allowed on CP/M systems. [P] Execute .PRL file. This option may be used under CP/M or MP/M to force execution of an MP/M .PRL file. .PRL files will run under CP/M only if the program doesn't make any MP/M specific BDOS calls. If this option is not specified REDIR will searches for a .COM then a .PRL file under MP/M or will search for a .COM under CP/M. - Reset option. This character can preceed any option character to reset the option that it preceeds. Since options normally default to the reset condition, it is only useful when processing in batch mode to reset that option for all of the commands in the batch file. Page 8 REAL-TIME REDIRECTION CONTROL ----------------------------- Redir can't make decisions when inputting data for a program from a file. It can only follow the path which you have set for it. This means that if anything unexpected happens while you are executing a program, redir will simply keep entering data as if the program was executing as expected. Also, it may be desirable to toggle devices while running for many various reasons. For instance you can create an initialization sequence for programs by switching on and off the echo to file function. Or you may wish to toggle on or off any of the other devices such as the list device. This is where real-time control over the I/O redirection comes in. Console I/O can be controlled after entering the program with the use of special redirection control sequences. These sequences consist of an attention character, a redirection command, and a device specification. If any character is typed that is not a valid control sequence character, the program will resume with no changes to the redirection. The attention character "^\" indicates that the characters that follow are intended as a command for redir and is not a character meant for the target program. If you wish to enter a "^\" as an input to the program, you simply enter two of them "^\^\". Once the attention character is typed the program will display a command prompt, "Command [<,>,/,^\]?" and suspend awaiting an entry. The first character of the sequence indicates what kind of redirection you wish to control. This can be ">" to toggle an output device, "/" to toggle an echo device, "<" to set the input device or "^\" to enter cntl-\ to the program. When a command is entered a list of valid devices will be displayed, "(F)ile (C)on: (L)st: (P)un:?" or "(F)ile (C)on: (R)dr:?" and suspend waiting for an entry. The next character entered specifies the device. This character is the first character of the device name. eg. C=CON: L=LST: P=PUN: R=RDR: F=file The file redirection can't be toggled unless it was previously activated by entering a file name in the redir command tail. Other control characters that can be entered are ^C to abort the program or ^S to suspend the program. Under MP/M ^D will cause the program to detach from the console and receive a system prompt. Doing this will suspend the program until the console is reattach to the program. *** Control character summary *** ^C Abort program. ^S Suspend program. ^D Detach program from console. (MP/M only) ^\ Attention character. >d Toggle redirection to output device. OUTPUT.LOG,CON: A:TYPE TEXT.FIL This will allow you to execute a program (TYPE) while saving all console output to a file. For example this can be useful to use the type program as a filter to convert all tabs in the file that is typed to spaces (assuming that type performs this conversion). REDIR /B1:CONSOLE A0:DDT This will allow you to create an input file, on drive B: user 1, for use with redir to duplicate the commands that you will enter while in DDT. REDIR LST:,CON: A:DIR *.COM This will cause all console output to go to the console and the printer. REDIR >NUL: [B] ASM SOURCE.AAA This is more useful under MP/M. It will cause ASM to compile the program SOURCE.ASM in background mode and return to the system prompt while ASM is still running. REDIR >CON:0,CON:1,CON:2 TYPE HELP.DOC This will only work under MP/M. This will cause the file HELP.DOC to be displayed at console 0, 1, and 2. REDIR =COMPILE JUNK This will execute a batch file that was written to compile source files. The source file being compiled is JUNK. Page 10 MESSAGES DISPLAYED BY REDIR --------------------------- File read error: There was a BDOS error reading from the file shown. File write error: There was a BDOS error writing to the file shown. File not found: The file shown could not be found. BDOS error: Bad Sector There is a bad sector on the disk. BDOS error: Select The disk could not be selected. BDOS error: Disk R/O The disk is read only. BDOS error: File R/O The file is read only. ^--Input Error! The command tail entered was invalid. The "^" points to the character in question. Not enough memory When processing the included batch files, there was not enough memory to get the job done. This is not very likely to occurr unless you have an incredinot enough memory to get the job done. This is not very likely to occurr unless you have an incredibly small TPA. To many nested includes You have attempted to exceed the limit of 255 for nested includes. One nest level is when a batch file that includes another batch file. This is most likely to happen when you have two batch files that include each other, causing a never ending loop. End of input file The end of the file specified as the input has been detected. This error only occurrs if a secondary input device is not specified and the target program attempts to perform a console input when the end of the input file has been reached. Page 11 Batch line longer than 127 characters When processing the batch file command line, after adding in the variables the command line exceeded 127 characters which is the maximum allowed characters per line. Bank switch attempted The target program attempted to switch from the user memory bank to another bank. Command [>,<,/,^\]? Redir command prompt. See section on real time redirection control. (F)ile (C)on: (R)dr: File, console, or reader input device prompt. (F)ile (C)on: (L)st: (P)un: File, console, list, or punch output device prompt. REDIR aborting REDIR is exiting. (E)xit (A)bort (R)etry (I)gnore? When a BDOS error occurrs you have four possible choices. (E) Attempt to exit REDIR normally, closing all files. (A) Abort REDIR without closing its files. This should only be used as a last resort since the output file data will be lost. (R) Retry the BDOS function. (I) Ignore the error and continue the program. Page 12 SYNOPSIS OF REDIR ----------------- The capability of controlling console I/O can be very useful in a variety of ways. First of all lets examine the possibilities with output redirection. The first and most obvious advantage is that you can save the output of a program to a file. This will most likely be an advantage with programs like type facilities, directory programs, and so forth. But consider the more obscure posibilities. It can be used to generate example files for instructions on how to patch a file with a debugger. It can be used to create tutotials that follow the every move of the program you are trying to present as if you were acually running the program. It might also be used to keep track of events that occurred when you executed a program. I'm sure there are many more possibilities but I'll leave that open to you. Lets consider the other possible output destinations. Have you ever wanted to execute a program and not have to look at its output? This is where the null device comes in handy. This is a fictional device that doesn't really exist exept in our imagination. It allows you to redirect console output to nowhere. In other words you can inhibit a program from outputting at all. This can be advantageous when it is desirable for the console to be detached while the program runs. This could mean a physical disconnecting of the terminal or a logical detachment as can be the case for MP/M. This operating system offers the capability to multi task by logically detaching the console from the program that you are executing. This works great until you run up against one of the inherant problems with MP/M. As soon as the program does any kind of input or output it will be suspended in the BDOS until it can complete the I/O, however if you are using REDIR then the I/O can complete and return thereby allowing the program to run. Another output device is the list device. I think the possibilities for this are pretty obvious. It allows all console output is sent to the printer. This works great but watch out with programs that do cursor addressing and other fancy things with your terminal since this can have unpredictable results on the printer output. The last output device is the punch. This is kind of a general purpose port avaliable on CP/M systems. Console output can be sent to this device if for instance you wanted to monitor the activity on the console from another terminal or if you wish to communicate directly with a peripheral device such as a modem or PROM programmer. Page 13 Now we will look at some possibilities for the second major function, echoing console input. This is similar to the redirect output command in that data is sent to an output device. The difference is that the source of the data is not the programs outputs but rather its inputs. This is an important feature since this is the only way that you can create a file for use with the redirect input command. If a filename is specified all data that is typed along with console status check information is stored in a file. If input is echoed to anyplace other than a file, the console status information is excluded. Console status information needed in a file because it is necessary for the proper operation of the transient program when using it as an input file for the redirect input command. Programs do console status checks for many various reasons and these must be handled properly for the particular circumstances. Console input can also be echoed to the console, list or punch devices. The third major function is the redirect input command. This allows you to receive input from the console, reader, or a file. The input from file function can be very handy since you can do things automatically that would normally would have to be done manually. It can for instance be used to automatically edit a file or to do things when batching or submitting that would not normally be possible. If the end of the input file is encountered then REDIR will terminate automatically unless an alternate device such as the console or reader is specified. In the latter case console input will be switched to the specified secondary device upon encountering the end of the input file. Console status checks can be a problem when using the reader device (RDR:). This is because there are no provisions in CP/M to check the status of the RDR: port. This is handled by always returning with status indicating that a character is ready. This way when the program attempts to get the character it will simply suspend until a character is received. This will cause a problem however with programs that poll the console and interrupt or abort the program when a character has been typed. This problem can be remedied by using the [B] option. This is the background option for MP/M but also for both CP/M and MP/M it will change the console status check to indicate that data is never ready at the console instead of the default condition which indicares that data is always ready. You should be aware of this problem if you plan to use the reader device to perform console input, otherwise there is no problem. By utilizing the batch processing capabilities of REDIR, you can execute multiple programs to perform a complicated task. The combination of console I/O redirection control and batch mode command processing can be a powerful combination. Most submit type files should have no trouble executing unless they contain CP/M memory resident commands. These are commands that are not present on the disk but rather in memory. They are DIR, TYPE, ERA, REN, SAVE, and USER. Page 14 REDIR APPLICATION NOTES ----------------------- 1) When creating an input file if the last character that is placed in the file is a control-Z it will not be recognised when using that file for input. This is because a control-Z is the CP/M end of file character. This character will be recognised if any character or console status check follows the control-Z. 2) A possible problem can occurr if you run REDIR under a program that resides in upper TPA. (CP/M shells and the like). This is beacuse REDIR modifies the BDOS error vector table in the BDOS. If a program is where the BDOS is expected to be this will cause the programs code to be corrupted. This is not a problem with REDIR, but is a problem with the other resident program that is running. This can be corrected by using the [E] option which inhibits REDIR from modifying the error vector table. If you use this option and a BDOS error occurs, aborting REDIR, you shoud reset the system since REDIR could not restore the addresses for the jump instructions at address 0 and 5 because it was aborted by CP/M. REDIR will support other programs that modify the BDOS error vector table. 3) When redirecting input from the punch device and the program makes a console status check, REDIR will always indicate that a character is ready. This is because there are no provisions under CP/M to check the status of the reader device. This is not preferable in some cases since some programs look for a character to be typed to abort. This can be remedied by using the [B] option. This option will cause REDIR to always return status indicating that a character is NOT ready. This problem only occurrs with the reader device. 4) MP/M COMPATIBILITY ATTRIBUTES: Since the program that is being executed under REDIR is being executed indirectly, the attribute of the program being executed has no affect on its operation. Certain compatibility attributes are necessary to make some programs work properly under MP/M therefore it may be necessary to set certain compatibility attributes on the REDIR.COM file. These attributes will NOT affect CP/M. f1 - Default open. Processes running with this attribute have all files opened in locked mode marked as read only in the system lock list. This allows all processes with this attribute set to read and write to common files with no restrictions. There is however no record locking provided. In addition this attribute also allows a process to write to a file opened by another process in read only mode. To be safe, all static files such as programs and help files should be made read only when this compatibility attribute is used. Page 15 f2 - Partial close default. Processes with this attribute set have thier default close mode changed from permanent close to partial close. This is for programs that close a file to update the directory, but continue to use the file. A side affect of this attribute is that files opened by a process are not released until REDIR terminates. Since the program is read into memory and executed by REDIR, the f2 attribute of the program being executed has no affect. It is not recommended to set this bit on REDIR since this may cause errors during a batch operation if a file is set to R/W and is accessed by more than one program during the batch operation. f3 - Ignore close checksum errors. This attribute affects the close checksum error handling. When this attribute is set and a checksum error is detected during a close operation and a lock list item for the file exists, the file is closed. Otherwise an unsuccessful close error code is returned to the calling process. Some programs modify the file control block (FCB) of an open file or change the default user number before closing the file. These conditions will cause an FCB checksum error under MP/M. This error condition can be inhibited by setting the file attribute f3, which is the third character of the file name in the directory, to a 1. f4 - Disable FCB checksum errors for read and write operations. Setting this attribute also sets the f2 and f3 attributes. This attribute should be used carefully because it effectively disables MP/M IIs file security. It is not recommended to set this bit on REDIR since this may cause errors during a batch operation if the file is accessed by more than one program during the batch operation. Page 16