SPECS stage v1.2

Pipelines v2.0

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

Home

Syntax

 _STOP_ALLeof______ <__________________
>>__SPECs__|__________________|__ _| Group |________|__________________________________><
 |_STOP_ _ANYeof__ _| |_READ_____________|
 |_streams_| |_READSTOP_________|
 |_WRITE____________|
 |_SELECT_streamnum_|
 |_PAD_char_________|
 
Group:
 
|__| Input |__| Conversion |__| Output |__| Alignment |_________________________________|
 
Input:
 
|__ _inputrange______________________________ __________________________________________|
 |_string__________________________________|
 | _FROM__1_______ _BY__1_____ |
 |_RECNO_|_______________|__|___________|__|
 | |_FROM__fromnum_| |_BY__bynum_| |
 |_TIME____________________________________|
 |_DATE____________________________________|
 
Conversion:
 
|__ _______ __ _________ __ _______ __ _____ ___________________________________________|
 |_STRIP_| |_REVerse_| |_UPper_| |_C2B_|
 |_LOWer_| |_C2X_|
 |_B2C_|
  |_X2C_|
Output:
 
|__ _Next_ _____________ ____________ __________________________________________________|
 | | (1) | |
 | |_____.length_| |
 |__ _NEXTWord_ __ _____________ __|
 | |_NWord____| | (1) | |
 | |_____.length_| |
 |_columnrange_____________________|
 
Alignment:
 
|__ ________ ___________________________________________________________________________|
 |_Left___|
 |_Centre_|
 |_Right__|
 
Notes: 
(1) Spaces are not allowed here.
(2) columnrange is unsigned.

Purpose

Use the SPECS stage to rearrange the contents of records. SPECS reads records from its primary input stream, by default, or from the one or more input streams specified by the operands. SPECS writes records to its primary output stream.

SPECS constructs one or more output records on a field-by-field basis. The output fields can come from input record fields (from one or more input records), literal values, the record number, or the system time or date. The data may be converted into a different format before it is placed in the output record. The output data can be left-aligned, centred, or right-aligned in the output field.

The basic format of the SPECS stage is:

 <_________________________________________________
>>__SPECS_____input__ ____________ ___output___ ___________ __|________________________><
 | conversion | | alignment |

(input )

is the literal data or the location of data in the input record you specify. For example, you can specify the string ABC or columns 1 through 5 of the input record.

(conversion )

is the type of conversion you can specify to change the format of the input data. For example, ASCII characters can be converted to their eight digit binary equivalent.

(output )

is the location where the data will be placed. For example, the data can begin in column 3 of the output record.

(alignment )

is the type of alignment you can specify for the data written to the primary output stream. You can specify the output data to be left-aligned, centred, or right-aligned.

Other operands allow you to:

●	Specify more than one input stream
●	Specify a character to be used for padding
●	Write pieces of multiple input records to a single output record
●	Write multiple output records from a single input record

Operands

Note. The definitions of most of the operands begin with a notation that describes if the operand can be used to define; (input ), (conversion ), (output ) or (alignment ). The operands that do not begin with this notation do not fall into one of those categories.

●

STOP

stop processing records when the specified number of input streams are at end-of-file.

●	ALLeof specifies that SPECS stops processing records when it determines that all input streams being used are at end-of-file. STOP ALLEOF is the default.
●	ANYeof specifies that SPECS stops processing records when it encounters the first input stream at end-of-file.
●	streams is an unsigned integer which specifies that SPECS stops processing records when streams number of input streams are at end-of-file, or when all streams used are at end-of-file.

●

inputrange

(input ) is an integer column, word or field range on which to operate.

●

string

(input ) is a delimited character string, hexadecimal string or binary string to insert into the output record at the specified position.

●

RECNO

(input ) specifies that the record number of each record (where, by default, the first record number is 1, incrementing by 1 for each subsequent record) is the input data. The record number is written to each output record. The record number is a 10-character field, right-aligned with leading spaces. For example, the two records generated by the following PIPE command contain the record number:

**** Top of file ****
01 Address Rxpipe
02
03 ‘pipe literal /ABC/ | literal /XYZ/ | specs recno 1 1-* 12 | console’
04
05 Exit 0
**** End of file ****
 
Output:
 1 XYZ
 2 ABC
 

●

FROM fromnum is an unsigned integer which specifies a record number for the first record. The default and minimum value is FROM 1. For example: ... | specs recno from 10 by 1 1-* 12 | ... the first record is record number 10, the second record number is 11, and so on.

●

BY bynum is an unsigned integer which specifies the increment for the record numbers. The default and minimum value is BY 1. For example: ... | specs recno from 10 by 2 1 1-* 12 | ... the first record is record number 10, the second record number is 12, the third is 14, and so on. You must specify a positive bynum. If incrementing the record number would exceed the value _MAX_INT_ as defined by Pipelines; the next record number in the range is (_MAX_INT_ – fromnum).

●

TIME

(input ) specifies that each input record written to the output stream has the current system time placed at the column position specified. The format is:

hh:mm:ss

●

DATE

(input ) specifies that each input record written to the output stream has the current system date placed at the column position specified. The format is:

yyyy/mm/dd

●

STRIP
(conversion ) specifies that the input data is stripped of leading and trailing whitespace (both space (X’20) and tab (X’09) characters are considered to be whitespace) before being converted and placed in the output field. For example:

... | specs 6.8 strip c2x 1 | ...
 

removes leading and trailing whitespace from the input data and then converts it to hexadecimal.

●

REVerse

(conversion ) specifies that the input data is reversed, before being placed in the output field. For example:

... | specs w3 rev 1 ...

selects word three, reverses the contents and places the result in the first column of the output field.

●

UPper

(conversion ) specifies that the input data is converted to uppercase, before being placed in the output field. For example:

... | specs 1-10 strip up 1.5 ...

selects columns 1 through 10, converts the contents to uppercase and places the result in the first column of the output field. The output field will be 5 characters in length.

●

LOWer

(conversion ) specifies that the input data is converted to lowercase, before being placed in the output field. For example:

... | specs 1-* low 15 ...

selects the entire record, converts the contents to lowercase and places the result in the fifteenth column of the output field.

●

C2B

(conversion ) converts input data from bytes (characters) to their binary representation. Each byte is converted to its 8-character binary equivalent. For example:

Input	C2B	Output
A	Converts to	01000001
13	Converts to	0011000100110011

●

C2X

(conversion ) converts input data from bytes (characters) to their hexadecimal representation. The output data contains 2 characters (the hexadecimal equivalent) for each byte. For example:

Input	C2X	Output
AB	Converts to	4142
23	Converts to	3233

●

B2C

(conversion ) converts input data from their binary representation to bytes (character). For example:

Input	B2C	Output
0100100001101001	Converts to	Hi
001100010011000001011000	Converts to	10X

●

X2C

(conversion ) converts input data from their hexadecimal representation to bytes (characters). For example:

Input	X2C	Output
4142	Converts to	AB
313538	Converts to	158

Note. When converting data with the X2C operand; the input data must contain an even number of hexadecimal characters. The output data consists of 1 character for every 2 characters in the input data.

●

Next

(output ) specifies that the output field begins in the next column position in the output record.

Specify .length immediately after the NEXT operand to indicate a length (number of columns to be used) for the output data. There cannot be any spaces between NEXT and .length.

In the following PIPE command, SPECS writes abc in column one of the output record, and then takes the whole input record starting at column one and places it in the next position in the output record:

**** Top of file ****
01 Address Rxpipe
02
03 ‘pipe “literal /pipeline/ | specs /abc/ 1 1-* next | console’
04
05 Exit 0
**** End of file ****
 
Output:
abcpipeline

●

length is an unsigned integer which specifies the output data length (where .length is the number of columns) after the operands NEXT, NEXTWORD or NWORD. There cannot be any spaces between NEXT, NEXTWORD or NWORD and .length. For example: **** Top of file **** 01 Address Rxpipe 02 03 ‘pipe literal /pipelines are/ | specs 1-* 1 /easy to learn/ next.4 | console’ 04 05 Exit 0 **** End of file **** Output: pipelines areeasy

●

NEXTWord

NWord

(output ) specifies that the output field is to begin in the column that is one after the next available column. A space is placed in the next available column.

Specify .length immediately after the NEXTWORD or NWORD operand to indicate a length for the output data; the length you specify does not include the space character that separates the output data. There cannot be any spaces between the NEXTWORD or NWORD and .length.

The SPECS stage in the following PIPE command writes its input data, Princeton, beginning in the first column of the output record and then writes the character string University one space after the next available column in the output record.

**** Top of file ****
01 Address Rxpipe
02
03 ‘pipe literal /Princeton/ | specs 1-* 1 /University/ nextword | console’
04
05 Exit 0
**** End of file ****
 
Output:
Princeton University
 

Specifying NEXTWORD.1 as shown in the following PIPE command, writes the first character, U, one space after the next available column in the output record:

**** Top of file ****
01 Address Rxpipe
02
03 ‘pipe literal /Princeton/ | specs 1-* 1 /University/ nextword.1 | console’
04
05 Exit 0
**** End of file ****
 
Output:
Princeton U
 

●

columnrange

(output ) is an unsigned integer column range which defines the position and length of the data in the output record.

●

Left

(alignment ) specifies that the data is left-aligned within the output field. When there is no conversion of the input data, leading whitespace (both space (X’20) and tab (X’09) characters are considered to be whitespace) are stripped before alignment.

If the data is too large for the specified output field, the right-most data is truncated to fit the output field.

●

Centre

(alignment ) specifies that the output data is centred within the output field. When there is no conversion of the input data, leading and trailing whitespace (both space (X’20) and tab (X’09) characters are considered to be whitespace) are stripped before centring.

If the data is too large for the specified output field, data is truncated evenly (when possible) on the left and right to fit the output field.

●

Right

(alignment ) specifies that the output data is right-aligned within the output field. When there is no conversion of the input data, trailing whitespace (both space (X’20) and tab (X’09) characters are considered to be whitespace) are stripped before alignment.

If the data is too large for the specified output field, the left-most data is truncated to fit the output field.

●

READ

consumes the current input record and reads without consuming the next record on the currently selected input stream (which is initially the primary input stream). READ can put data from consecutive input records into a single output record. If the end-of-file is encountered when reading without consuming an input stream record, input fields referring to any part of that record are considered to be null.

The following example shows a SPECS stage that specifies the READ operand:

**** Top of file ****
01 Address Rxpipe
02 
03 ‘pipe literal /ABCD/ | literal /123/ | specs 1-* 1 read 1-3 4 | console’
04
05 Exit 0
**** End of file ****
 
Output:
123ABC
 

The SPECS stage reads the first record in its input stream and places the data 123 in the output record beginning in column 1. The READ operand signals that it is done with that input record. SPECS then reads the next input record and places the first three columns of the data ABCD in the same output record beginning in column 4.

You can use READ if you want to process the output records from the LOOKUP stage to combine a master record and detail record into one output record.

●

READSTOP

consumes the current input record and reads without consuming the next record on the currently selected input stream (which is initially the primary input stream). READSTOP can put data from consecutive input records into a single output record. If end-of-file is encountered when reading the file, SPECS writes the record built so far and does not process the remainder of the operands specified after READSTOP.

In the following example, when SPECS processes the last of three records, READSTOP writes the record built so far and does not go on to add the asterisks to the final output record.

**** Top of file ****
01 Address Rxpipe
02
03 ‘pipe literal /a/ | dup 2 | specs 1-* 1 readstop 1-* nw /**/ nw | console’
04
05 Exit 0
**** End of file ****
 
Output:
a a **
a
 

If you use READ in place of READSTOP, as in the following example, READ continues processing the remainder of the stage which adds the asterisks:

**** Top of file ****
01 Address Rxpipe
02
03 ‘pipe literal /a/ | dup 2 | specs 1-* 1 read 1-* nw /**/ nw | console’
04
05 Exit 0
**** End of file ****
 
Output:
a a **
a **

●

WRITE

writes the output record built so far to the primary output stream. A new, empty output record is initialised. WRITE can put data from a single input record into multiple output records. The following example shows a SPECS stage that specifies the WRITE operand:

**** Top of file ****

01 Address Rxpipe

02

03 ‘pipe “literal /ABC123/ | specs 1-3 1 write 4-6 4 | console’

04

05 Exit 0

**** End of file ****

Output:

ABC
 123
 

The SPECS stage reads the first 3 columns of the input record and places the data ABC into the output record beginning in column 1. WRITE writes the record to the primary output stream. SPECS then reads the data in columns 4 through 6 of the same input record and places the data 123 into the next output record beginning in column 4.

You can use WRITE if you want to write a record for each word in the input record (provided you know that there are a fixed number of words).

●

SELECT

sets the currently selected input stream. When SELECT is not specified, the primary input stream is the currently selected one.

SPECS reads one record from all input streams specified by the SELECT operands for each output record that is built. SPECS stops when all input streams reach end-of-file.

●

streamnum is an unsigned integer which specifies the input stream number to be used as the source for the subsequent input data specification, where 0 is the primary input stream, 1 is the secondary input stream, and so on. One record is read from each of the selected input streams for each output record that is built. Input streams that are connected, but not referenced, are not read when SELECT is used. The SPECS stage stops only when all input streams have reached end-of-file. Until then, an input stream at end-of-file is considered to hold null records.

●

PAD

specifies that a pad character is used to pad the output positions that do not contain data after the input data is written to the output location.

●

char is the pad character. For example:, PAD fills positions in front of the output data if you specify the data to begin in a column other than the first column or the next available column: **** Top of file **** 01 Address Rxpipe 02 03 ‘pipe literal /3.14159/ | specs pad 0 1-* 5 | console’ 04 05 Exit 0 **** End of file **** Output: 00003.14159 PAD fills positions at the end of the output data if the output data does not extend to the last column you specify. For example: **** Top of file **** 01 Address Rxpipe 02 03 ‘pipe literal /Why/ | specs pad ? 1-* 1-10 | console’ 04 05 Exit 0 **** End of file **** Output: Why??????? If PAD is specified; it remains in effect until the next PAD specification is encountered.

Streams used

The following streams are used by the SPECS stage:

Stream	Action
Input streams	By default, SPECS reads records from its primary input stream. If specified by the operands, SPECS reads records from other specified input streams.
Primary output stream	After rearranging the contents of the input records as specified by the operands, SPECS writes the resulting records to its primary output stream.

Usage notes

1)	SPECS does not delay the records unless the READ or READSTOP operand is specified. SPECS with the READ or READSTOP operand delays one record for each read.
2)	If the SPECS stage discovers that its primary output stream is not connected, the SPECS stage ends.
3)	SPECS is not required to use any part of an input record. For example, SPECS does not use the data contained in its input stream (the literal string XYZ) in the following PIPE command: **** Top of file **** 01 Address Rxpipe 02 03 ‘pipe “literal /XYZ/ | specs /Bob is a tennis player./ 1 | console’ 04 05 Exit 0 **** End of file **** Output: Bob is a tennis player.
4)	Depending on the length of a record, the input data may be present in full, partially, or not at all. If input data is not present in a record, the field is null (the length is 0). For example, if you specify an input range that is larger than the input data itself, SPECS writes the data up to the end of the literal data or record and does not issue an error message. The following pipeline shows an example of this: **** Top of file **** 01 Address Rxpipe 02 03 ‘pipe literal /record1 record2/ | specs words1-5 1 | console’ 04 05 Exit 0 **** End of file **** Output: record1 record2
5)	If alignment is not specified, the data written to the output field is left-aligned. The output field may have leading space characters, may be truncated, or a pad character may fill the field on the right to the size of the output specification.
6)	The output record is at least long enough to contain all literal fields and all output fields defined with a range. It is longer if there is an input data field beyond the last literal field, and the input record does contain at least part of the input field.
7)	Output data whose position is specified by NEXT or NEXTWORD can be overlaid by a subsequent specification indicating a specific output column.
8)	SPECS with the SELECT operand can cause a set of pipelines to stall when a record is not available on all connected input streams. When the SELECT operand is specified, there must be a record available on all input streams before any input record is consumed.
9)	For each conversion operand there is another operand that performs the opposite function. For example; C2B is the opposite of B2C.
10)	If SPECS finds an error in the operands or a format error in its input records, the SPECS stage ends.
11)	SPECS verifies that its secondary output stream is not connected and then begins execution.

Examples

Arranging text in columns (vertical)

See also

Reference the following links for additional information:

DROP, JOIN, SPLIT, STRIP, TRANSLATE

History of change

Version	Action	Description
1.1	Changed	The operands: STRIP, alignment LEFT, CENTRE and RIGHT only remove spaces (x’20’) and tabs (x’09’) before positioning the data in the output record.
	Added	The REVERSE, UPPER and LOWER operands.
1.2	Changed	The NEXTWORD operand will no longer insert a SPACE into the output record, before appending data; if that data is null.