Purpose, Argument, Streams, Usage, Examples, Related

                          ┌─.REX─┐
>>──┬─CALLpipe─┬──program─┴──────┴──┬──────────┬─────────────────────────────────────>< 
    └─SUBpipe──┘         (1)        └─argument─┘

Notes:
(1) You must not specify any spaces between the program name and the .REX
    extension.

Use the CALLPIPE stage command to connect to the specified target ooRexx program.

CALLPIPE loads the target program and begins servicing its read and write record requests; effectively using the program as a subroutine. CALLPIPE simultaneously reads records from its primary input stream and writes them to the target program whilst reading records from the target and writing them to a specified output stream, if it is connected. Depending on the program configuration; CALLPIPE may start reading records from the target before it begins writing records to the target or vice-versa; however, the relative order of the records flowing through the caller and the target can be predicted if both the caller and the target only comprise pipelines with stages that do not delay the records.

CALLPIPE is designed to be used in conjunction with the IN and OUT stage commands. The first stage of the target program connects to CALLPIPE through the IN stage command and the target program connects back to CALLPIPE through the OUT stage command.

Consider the following two ooRexx programs:

mypipe.rex

**** Top of file ****
Address Rxpipe

'pipe (name mypipe)',
    '< myfile.txt',                    /* Read our input file myfile.txt.    */
    '| callpipe format.rex upper 50',  /* Call our subroutine with optiions. */
    '| console'                        /* Display the records on console.    */
 
Exit 0
**** End of file ****

format.rex


**** Top of file ****
Address Rxpipe
Parse Arg type ncol .

'pipe (name format)',
    'in',                      /* Read records from our caller (mypipe.rex). */
    '| strip trailing',        /* Strip trailing whitespace.                 */
    '| locate',                /* Discard empty records.                     */
    '| chop' ncol,             /* Truncate records after column 'ncol'       */
    '| xlate' type,            /* Translate records to upper/lower?          */
    '| out 0'                  /* Write records to our caller (mypipe.rex).  */
 
Exit 0
**** End of file ****

• program
  is the name of the target ooRexx program. If the program is not in the current working directory, you must specify a fully qualified path. If you do not specify the .REX extension, CALLPIPE will append it.
  
  
  • argument
    is the argument which will be passed to the target program.

1. CALLPIPE does not delay the records.
   
   
2. If the CALLPIPE stage discovers that its primary input stream and all of its output streams are not connected, then the CALLPIPE stage ends.
   
   
3. The target program inherits the thread priority of the calling pipeline.
   
   
4. The target program inherits the stall detection monitor setting of the calling pipeline; only if the caller explicitly specifies the MONITOR pipeline option or the caller inherited the MONITOR setting from its caller, and so on.
   
   
5. The target program inherits the TRACE setting of the calling pipeline. However, the target pipeline can override this inherited setting by specifying its own TRACE option setting.
   
   
6. If the target program exits with an error code; CALLPIPE causes its pipeline or set of pipelines to quiesce, returning that exit code to its caller, and so on.
   
   
7. If the target program name or its argument contains spaces, you must enclose them in quotation marks. For example:
   
   

   callpipe "my subroutine.rex" argument1 "argument 2"
   

   
   
8. CALLPIPE verifies that its secondary input stream is not connected and then begins execution.

See: Purpose.

IN, OUT, RUNPIPE