Windows File Redirection Extensions in TCC

TCC supports the input / output redirection operators in CMD, and extends them to include new Windows redirection types and UTF-8 and UTF-16 redirection.

Redirection can be used to reassign the standard input (stdin), standard output (stdout), and standard error (stderr) devices from their default settings (the keyboard and screen) to another device such as NUL or a serial port, to a file, or to the Windows clipboard or the TCC pseudo-devices CLIPn: and TMPn:. Redirection always applies to a specific command, and lasts only for the duration of that command. When the command is finished, the assignments for standard input, standard output, and standard error revert to their previous values.

TCC's output is normally in ANSI. If you want to redirect output in Unicode (UTF-8 or UTF-16), you can use the /U startup option in TCC, or the Unicode Output option in TCMD.INI, or the >:8 or >:u redirection syntax.

In the descriptions below, filename means either the name of a file or of an appropriate device (CON for the keyboard and screen; CLIP: (or CLIP0: - CLIP9:) for the clipboard; NUL for the "null" device, etc.).

Here are the standard input / output redirection options supported by TCC (see below for additional redirection options using numeric file handles):

Input redirection

To get input from a file or device instead of from the keyboard:

< filename

Output redirection

Overwrite STDOUT:

> filename

Append STDOUT:

>> filename

overwrite STDERR:

>&> filename

append STDERR:

>>&> filename

merge overwrite standard output and standard error:

filename merge append standard output and standard error:

>>& filename

To use redirection, place the redirection symbol and filename at the end of the command line, after the command name and any parameters. For example, to redirect the output of the DIR command to a file called DIRLIST, you could use a command line like this:

dir /b *.dat > dirlist

You can use any combination of input and output redirection for the same command, as appropriate for your purpose. For example, this command sends input to the external program SORT from the file DIRLIST, and sends output from SORT to the file DIRLIST.SRT:

sort < dirlist > dirlist.srt

You can redirect text to or from the Windows clipboard by using the TCC pseudo-device name CLIP: (the colon is required). Redirection to the clipboard is always done using UTF16 Unicode. If you redirect the output of a single internal command like DIR, the redirection ends automatically when that command is done. If you start a batch file with redirection, all of the batch file's output is redirected, and redirection ends when the batch file is done. Similarly, if you use redirection after the closing parenthesis of a command group (e.g., ...) > report), all of the output from the command group is redirected, and redirection ends when the command group is done.

You can change the format of the redirected output. These options will override the UnicodeOutput and UTF8Output directives in TCMD.INI. Note: these options only work for redirecting output from TCC internal commands and batch files.

>:a Redirected output (STDOUT and/or STDERR) is ANSI (8 bit characters)

>:u Redirected output is UTF16 Unicode

>:8 or >:u8 Redirected output is UTF8

>>:a Appended redirected output (STDOUT and/or STDERR) is ANSI (8 bit characters)

>>:u Appended redirected output is UTF16 Unicode

>>:8 or >>:u8 Appended redirected output is UTF8

NoClobber

When output is directed to a file with >, >&, or >&>, and that file already exists, it will be overwritten. You can protect existing files by using the SETDOS /N1 command, the Protect redirected output files setting on the Startup tab of the configuration dialogs, or the Protect redirected output file option.

When output is appended to a file with >>, >>&, or >>&>, the file will be created if it doesn't already exist. However, if the NoClobber mode is set as described above, append redirection will not create a new file; instead, if the output file does not exist a "File not found" or similar error will be displayed.

You can temporarily override the current setting of NoClobber by using an exclamation mark [!] after the redirection symbol. For example, to redirect the output of DIR to the file DIROUT, and allow overwriting of any existing file despite the NoClobber setting:

dir >! dirout

Multiple redirections

Redirection is fully nestable. For example, you can invoke a batch file and redirect all of its output to a file or device. Output redirection on a command within the batch file will take effect for that command only; when the command is completed, output will revert to the redirected output file or device in use for the batch file as a whole.

Creating an empty file

You can use redirection to create an empty (zero-byte) file. To do so, enter >filename as a command, with no actual command before the > character. If you have enabled Protect redirected output file, use >!filename.

Redirection by handle

In addition to the redirection options above, TCC also supports the CMD syntax:

n>file Redirect handle n to the named file

n>&m Redirect handle n to the same place as handle m

Warning: You may not put any spaces between the n and the >, or between the >, &, and m in the second form. The values of n and m must be single decimal digits, and represent file handles. Windows defines 0, 1, and 2 as.

0 - standatd input

1 - standard output

2 - standard error

The n>file syntax redirects output from handle n to file. You can use this form to redirect two handles to different places. For example:

dir > outfile 2> errfile

sends normal output to a file called OUTFILE and any error messages to a file called ERRFILE.

The n>&m syntax redirects handle n to the same destination as the previously assigned handle m. For example, to send standard error to the same file as standard output, you could use this command:

dir > outfile 2>&1

Notice that you can perform the same operations by using standard redirection features. The two examples above could be written as:

dir > outfile >&> errfile

and

dir >& outfile

"Here-document" redirection

Wherever input redirection is supported, you can use a Linux-like "here-document" approach. The syntax is:

program << word

The current batch file is read up to the next occurrence of word, and the resulting text becomes standard input to program. For example:

c:\test\program.exe << endinput

input 1

input 2

input 3

endinput

echo This is the next line after "program.exe"

Special features of "here document":

If the << is followed by a hyphen (-), the leading white space on the following lines will be removed before passing them to program (i.e. they will be effectively left-justified).

The parser will perform variable expansion on each line, unless the word following << is enclosed in double quotes.

"Here-string" redirection

The "here-string" lets you send string text directly to a program's input. The syntax is:

program <<< string

This is similar to using KEYSTACK, but easier to enter for text input. (If you need to send special keys or insert waits, you'll need to use KEYSTACK.) For example, to send a string to the standard input of program:

c:\test\program.exe <<< This is some input text.

Windows Pipes Extensions in TCC

Piping is a special form of redirection, using an additional instance of TCC for each instance of the piping specified in the command line. TCC supports the pipe operators in CMD, and extends them to include new pipe operators and UTF-8 and UTF-16 piping.

You can create a pipe to send the standard output of a command (command1) to the standard input of another command (command2), and optionally also send the standard error as well:

what is sent to pipe	command format
standard output only	command1 \| command2
merge standard output & standard error	command1 \|& command2
standard error only	command1 \|&\| command2

For example, to take the output of the ALIAS command (which displays a list of your aliases and their values) and pipe it to the external SORT utility to generate a sorted list, you would use the command:

alias | sort

To do the same thing and then pipe the sorted list to the internal VIEW command for viewing:

alias | sort | view /s

The TEE and Y commands are "pipe fittings" which add more flexibility to Windows pipes.

TCC's output is normally in ANSI. If you want to redirect output in Unicode, you need to either use the /U startup option in TCC, or the Unicode Output option in TCMD.INI.

Like redirection, pipes are fully nestable. For example, you can invoke a batch file and send all of its output to another command with a pipe. A pipe on a command within the batch file will take effect for that command only; when the command is completed, output will revert to the pipe in use for the batch file as a whole. You may also have 2 or more pipes operating simultaneously if, for example, you have the pipes running in different windows or processes.

Processing each line received from a pipe

To process each line of text sent by the left side of a pipe in TCC, you can use this syntax:

dir | for %file in (@CON:) command %file

This example shows how to pass each line of piped data to a command.

WARNINGS: TCC implements pipes by starting a new process for the receiving program. This process goes through the standard shell start-up procedure, including execution of the TCSTART file, for EACH receiving program. All of the sending and receiving programs run concurrently; the sending program writes to the pipe and the receiving program reads from the pipe. When the receiving program finds an End of File signal, it finishes reading and processing the piped data, and terminates. When you use pipes with TCC, make sure you consider the possible consequences from using a separate process to run the receiving program, especially that it cannot create/modify/delete environment variables of the sending program, and inclusion of a command to change directories in the TCSTART file may cause the new process to execute in a different directory. When you use more than one pipe in a single command, e.g. the second example above with LIST, each pipe adds another instance of TCC. If you need to execute the pipe in the same context, use in-process pipes (see below).

Viewing Pipe Activity

The TCC PIPEVIEW command will read from STDIN, and display the pipe activity in realtime in a VIEW window while also forwarding it on to STDOUT to be read by the next app.

Additional Pipe-related Commands

TCC has several additional "pipe-fitting" commands:

TEE is normally used to "split" the output of a program so that you can see it on the display and also save it in a file. It can also be used to capture intermediate output before the data is altered by another program or command.
Y copies standard input to standard output. Once the input ends, the named files are appended to standard output.
PEE is similar to TEE, but instead of redirecting STDOUT to multiple files, it redirects it to multiple secondary commands via pipes. You must enclose each command (and any arguments) in double quotes.

In-Process Pipes

In-process pipes work like the old-style DOS pipes, by creating a temporary output file, redirecting STDOUT to that file, and then redirecting the temp file to STDIN of the following command. The syntax is:

command1 |! command2

This the same as doing:

command1 > temp.dat & command2 < temp.dat

but is easier to type & to read.

The advantage of in-process pipes is that command2 will be run in the same context as command1, so you can do things like modify environment variables without having them discarded when command2 exits. There are also some disadvantages to using this type of "pseudo-pipe" -- it will usually be slower than a true pipe; it will use some disk space for its temp file; and command2 will not be started until command1 has exited.

Piping ANSI, Unicode, and UTF-8 Output

You can change the format of output sent to a pipe. These options will override the UnicodeOutput and UTF8Output directives in TCMD.INI. The piped output options also work with in-process pipes (i.e., |!:u). Note: these options only work for redirecting output from TCC internal commands and batch files.

|:a   Piped output is ANSI
|:u   Piped output is UTF16 Unicode
|:8 or |:u8   Piped output is UTF8