Literal

LITERAL stage v1.3

Pipelines v2.1

Purpose, Operands, Streams, Usage, Examples, Related

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

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

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 1 Address Rxpipe 2 3 'pipe literal /or not to be/', 4 '\| literal /To be/', 5 '\| console' 6 7 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

The following pipeline writes the string 12345 to the console.

'pipe literal x3132333435 | console'

output:

The following pipeline writes the string ABCDEFGHIJK to the console.

'pipe literal A-K | console'

output:

ABCDEFGHIJK

In the following example, LITERAL writes a record that contains a description of the terminal output that the CP QUERY VIRTUAL STORAGE command generates:

pipe cp query virtual storage | literal My virtual storage: | console

My virtual storage:

STORAGE = 07168K

Ready;

Note that the LITERAL stage writes the specified record to the output stream ahead of the records it receives from the CP stage.

Related

SPECS

History

Version	Date	Action	Description	Pipelines
1.3	26.12.2021	changed	Application-wide rewrite.	2.1
1.2	23.05.2011	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.	1.9
1.1	30.06.2009	added	Addition of the PREFACE and APPEND operands.	1.6
1.0	06.09.2007	created	First version.	1.0