Using the handles 3 to 9 in REXX programs

OS/2 defines 10 general file handles for batch files (and therefor also 
for REXX programs): 

+---------------+---------------------------------------------+
|Handle         |Default assignment                           |
+---------------+---------------------------------------------+
|0              |Standard Input (STDIN)                       |
+---------------+---------------------------------------------+
|1              |Standard Output (STDOUT)                     |
+---------------+---------------------------------------------+
|2              |Standard Error (STDERR)                      |
+---------------+---------------------------------------------+
|3              |no default assignment                        |
+---------------+---------------------------------------------+
|4              |no default assignment                        |
+---------------+---------------------------------------------+
|5              |no default assignment                        |
+---------------+---------------------------------------------+
|6              |no default assignment                        |
+---------------+---------------------------------------------+
|7              |no default assignment                        |
+---------------+---------------------------------------------+
|8              |no default assignment                        |
+---------------+---------------------------------------------+
|9              |no default assignment                        |
+---------------+---------------------------------------------+

To use the handles 0 to 2 in REXX programs, use the filenames STDIN, 
STDOUT, or STDERR. Note that these are the default values and therefor you 
do not have to explicitly code them. 
The handles 0 to 2 always exist and point either to the keyboard (handle 
0), the screen (handles 1 and 2), or to a file if redirected via <, >, or 
|. 

It's also possible to use the handles 3 to 9 in REXX programs. To do that, 
you must call the program with a redirection for the handle and inside the 
REXX program you can access them only via OS/2 commands, like for example 
the <ECHO command. 

Examples: 

Example for using ony the handle 3: 

 
/* testHandle3.cmd                                                    */
/*                                                                    */
/* REXX sample on using handle 3 in a REXX program                    */
/* call this cmd with                                                 */
/*                                                                    */
/*   testHandle3.cmd 3>handle3.out                                    */
/*                                                                    */

  testString = "This text goes to the file referenced by handle 3"
  "echo. " testString ">>&3"
exit 0

Example for using the handles 3 to 9: 

 
/* testHandles3to9.cmd                                                */
/*                                                                    */
/* REXX sample on using the handles 3 to 9 in a REXX program          */
/* call this cmd with                                                 */
/*                                                                    */
/*   testHandles3to9.cmd 3>ha3 4>ha4 5>ha5 6>ha6 7>ha7 8>ha8 9>ha9    */
/*                                                                    */

  testString = "This text goes to the file referenced by handle "
  do i=3 to 9
    "echo. " testString || i ">>&" || i
  end /* for */
exit 0

You can also redirect more then one file handle into a file. Example: 

 
  testhandles3to9.cmd 3>test3x.out 4>>&3 5>>&3 6>>&3 7>>&3 8>>&3 9>>&3

In this example every echo command writes to the file test3x.out. 

 
  testhandles3to9.cmd 3>test3x.out 4>>&3 5>>&3 6>>&3 7>>&3 8>>&3 9>>&3 3>test3y.out

In this example every echo command except the echo command for handle 3 
writes to the file test3x.out. The echo command for handle 3 writes to 
test3y.out 

Please be aware that the output goes to STDOUT or you will get an error 
message if you try to use an unassigned file handle - for example if you 
call the first example testHandle3.cmd above without the redirection of 
the handle 3: 

 
    testHandle3.cmd

Also be aware that files you open inside your REXX program will get the 
next free file handle. Therefor the first file you open in a REXX program 
normally gets the handle 3. But if you redirect the handle 3 into a file 
via redirection on the command line the first file you open inside your 
REXX program will get the handle 4. Try the example below to see the 
difference. 

 
/* testHandle3a.cmd                                                   */
/*                                                                    */
/* REXX sample                                                        */
/*                                                                    */
  call stream 'TESTSTREAM', 'c', 'OPEN WRITE'

  testString = "This text goes to the file referenced by handle 3"
  "echo. " testString ">>&3"

  call stream 'TESTSTREAM', 'c', 'CLOSE'
exit 0

If you call this program with 

 
    testHandle3a.cmd 3>handle3.out

the output goes to the file HANDLE3.OUT. if you call this example with 

 
    testHandle3a.cmd

the output goes to the file TESTSTREAM. 

To check if one or more of the handles 3 to 9 are redirected to a file, 
you can check which handle you'll get if you create a new file: 

 
/* This code works in Object-Oriented REXX only!                      */
  DATAFILE = 'NUL'
  if stream( DATAFILE, 'c', 'OPEN READ' ) = "READY:" then
  do
    DATAFILE_handle = stream( DATAFILE, 'c', 'QUERY HANDLE' )
    say "DATAFILE handle is" DATAFILE_handle
    call stream DATAFILE, 'c', 'CLOSE'
  end /* if */
  else
    say "Error opening " || DATAFILE || " for reading!"

Normally, if the handles between 3 and 9 are not redirected, the handle 
for the new file is 3. If one or more of the handles 3 to 9 is redirected 
to a file the handle you get is 5 (if only handle 3 is redirected), 6 (if 
handle 3 and 4 are redirected), and so on. 

BUT 

The handle is also 5 or above if STDIN, STDOUT, or STDERR is redirected to 
another device, file or pipe. So, to be sure, check this also (How to 
check if STDIN, STDOUT or STDERR are redirected to a file) a 

see Using redirection for a simple process controller, General input line 
enhancer for other samples 
see Output & Input control, Reserved names for files in REXX for additional 
information