|
CALLPIPE stage v1.3
|
Pipelines v2.0
|
_.REX_
>>__CALLpipe__pipeline_|______|__ __________ __________________________________________><
(1) |_argument_|
Notes:
(1) You must not specify any spaces between the pipeline operand and the .REX extension.
Use the CALLPIPE
stage command to connect to the specified target pipeline.
CALLPIPE loads
the target pipeline and begins servicing its read and write record requests; effectively
using the pipeline as a subroutine. CALLPIPE simultaneously reads records from
its primary input stream and writes them to the pipeline, whilst reading
records from the pipeline and writing them to the output stream specified by
the OUT stage of the called pipeline, if it is connected. Depending on the
configuration of the pipeline; CALLPIPE may start reading records from the
target pipeline before it begins writing records to the target pipeline, or
vice-versa; however, the relative order of the records flowing through the
caller and the target pipeline can be predicted if both pipelines only comprise
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 pipeline connects to CALLPIPE through the IN stage
command and the target pipeline connects back to CALLPIPE through the OUT stage
command. Consider the following two pipelines:
mypipe.rex
**** Top of file****
01 Address Rxpipe
02
03 ‘pipe (name mypipe)’,
04 ‘< myfile.txt’, /* Read myfile.txt. */
05 ‘| xlate upper’, /* Translate records to uppercase. */
06 ‘| callpipe format.rex’, /* Call format pipeline. */
07 ‘| console’ /* Display records on the console. */
08
09 Exit 0
**** End of file ****
format.rex
**** Top of file ****
01 Address Rxpipe
02
03 ‘pipe (name format)’,
04 ‘in’, /* Read records from caller (mypipe.rex/callpipe). */
05 ‘| strip trailing’, /* Strip trailing whitespace. */
06 ‘| locate’, /* Discard empty records. */
07 ‘| chop 50’, /* Truncate records after column 50. */
08 ‘| out’ /* Write records back to caller (mypipe.rex/callpipe). */
09
10 Exit 0
**** End of file ****
mypipe reads records
from myfile.txt; translates them to
uppercase and through the CALLPIPE stage command, writes the records to the format pipeline. The records enter format through the IN stage, pass
through the; STRIP, LOCATE and CHOP stages and exit the format pipeline through the OUT stage; flowing back into CALLPIPE
and finally through the CONSOLE stage which displays the records on the
console.
The target
pipeline must specify the IN stage command in order to read output records
written by CALLPIPE and it must specify the OUT stage command in order to write
records to CALLPIPE. However, you do not have to specify either the IN or OUT
stage command in the target pipeline. You may call a pipeline which only reads
records from its caller or only writes records to its caller.
|
●
|
pipeline
is the name of
the target pipeline file. If the pipeline file is not in the current
working directory, you must specify a fully qualified path and filename. If
you do not specify the .REX extension operand, CALLPIPE will append it.
|
|
|
|
●
|
argument
is the argument which will be
passed to the target pipeline.
|
|
The following streams are used by the
CALLPIPE stage:
|
Stream
|
Action
|
|
|
|
|
Primary input
stream
|
CALLPIPE reads records from its primary
input stream.
|
|
Output streams
|
CALLPIPE writes records to the output stream
specified by the called pipelines’ OUT stage. If the stream is not connected;
the records are discarded.
|
|
1)
|
CALLPIPE does not delay the records.
|
|
2)
|
If the CALLPIPE stage discovers that its
primary input and primary and secondary output streams are not connected, the
CALLPIPE stage ends.
|
|
3)
|
The target pipeline inherits the thread priority of the calling
pipeline.
|
|
4)
|
The target
pipeline 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
pipeline 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 pipeline exits with an error
code; CALLPIPE causes its pipeline or set of pipelines to quiesce, returning
that exit code to its calling pipeline, and so on.
|
|
7)
|
If the target pipeline or its argument
contains spaces, you must enclose them in quotation marks. For example:
callpipe “my pipeline.rex” “argument 1” argument2
|
|
8)
|
CALLPIPE verifies
that its secondary input stream is not connected and then begins execution.
|
See: Purpose
Reference the
following links for additional information:
IN, OUT, RUNPIPE