LITERAL stage v1.2

Pipelines v2.0

Purpose, Operands, Streams used, Usage notes, Examples, See also

Home

Syntax

 _PREFace___
>>__LITeral__|___________|__ ___________ ______________________________________________><
 |_APPend____| |_string____|
 |_charrange_|

Purpose

Use the LITERAL stage to write the specified literal string as a record to its primary output stream. If the primary input stream for the LITERAL stage contains any records, LITERAL copies the records from its primary input stream to its primary output stream.

Operands

●	PREFace specifies that LITERAL writes the string or charrange to its primary output stream first, followed by the records from its primary input stream. This is the default.
●	APPend Specifies that LITERAL writes the records from its primary input stream to its primary output stream first, followed by the string or charrange.
●	string is a string of characters that make up a record. If you do not specify the string or charrange argument, LITERAL creates and writes a null record.
●	charrange is a character range that makes up a record. For example, specifying A-K for charrange; expands to the literal string ABCDEFGHIJK.

Streams used

The following streams are used by the LITERAL stage:

Stream	Action
Primary input stream	LITERAL reads records from its primary input stream.
Primary output stream	After writing the literal string to its primary output stream, LITERAL copies any records read from its primary input stream to its primary output stream.

Usage notes

1)	LITERAL does not delay the records.
2)	If the LITERAL stage discovers that its primary output stream is not connected, the LITERAL stage ends.
3)	Because LITERAL writes its argument as the first record to its output stream before copying its input stream, records from multiple LITERAL stages are written to the output in reverse order compared to the order of the stages in the pipeline. For example: **** Top of file **** 01 Address Rxpipe 02 03 ‘pipe literal /or not to be/’, 04 ‘| literal /To be/’, 05 ‘| console’ 06 07 Exit 0 **** End of file **** Output: To be or not to be
4)	You cannot define a charrange which can also be interpreted as a string, for example. literal a-a The argument a-a will always be interpreted as a literal string with the value - (DASH); the string representation takes precedence. LITERAL always tries to interpret its argument; firstly as a string and then as a charrange. If the argument does not represent a valid string or charrange definition; LITERAL issues an error message in respect of a charrange definition error, not a string definition error.
5)	LITERAL verifies that its secondary input and output streams are not connected and then begins execution.

Examples

1)	The following pipeline writes the string 12345 to the console. **** Top of file **** 01 Address Rxpipe 02 03 ‘pipe literal x3132333435 | console’ 04 05 Exit 0 **** End of file **** Output: 12345
2)	The following pipeline writes the string ABCDEFGHIJK to the console. **** Top of file **** 01 Address Rxpipe 02 03 ‘pipe literal A-K | console’ 04 05 Exit 0 **** End of file **** Output: ABCDEFGHIJK

See also

Reference the following link for additional information:

SPECS

History of change

Version	Action	Description
1.1	Added	Addition of the PREFACE and APPEND operands.
1.2	Changed	LITERAL was not issuing the correct error message when a termination delimiter was missing from the stage command argument. Canned stage message #22 will be issued when the argument does not comprise a closing delimiter.