Parse Copybook Data Activity

The Parse Copybook Data activity parses binary COBOL data and returns JSON data. This activity parses incoming data according to the selected Copybook connection. After parsing, the output data conforms to the schema generated by the Copybook connection. Also, other activities can access the data.

Configuration

On the Settings tab, you can select the Copybook connection and configure the parsing process.

Field	Description
Copybook	The Copybook connection that contains a copybook.
Big Endian	The byte order of the incoming data. Select true to specify the byte order as Big Endian, for example, for IBM mainframes and certain UNIX platforms. Select false if the byte order is Little Endian. Examples: For Microsoft Windows and certain UNIX platforms
Character Set	The character-set encoding for the string values in the incoming data except for items with USAGE DISPLAY-1. This also affects the parsing of zoned decimal values. For more information, see Handling of Zoned Decimal Items. Some of the available character sets are multi-byte, for example UTF-8. If you select a multi-byte character set, it is used to convert binary content to strings. However the binary length of item is based on its PICTURE assuming one byte per character. Character Set selection does not alter the binary offsets and lengths of items in the copybook.
Character Set for DISPLAY-1 Items	The character-set encoding for items with USAGE DISPLAY-1. Binary length of such items is based on their PICTURE clause (assuming two byte per character). However, you can choose a single-byte or a variable character set, which is then used to convert text. Character Set selection does not alter the binary offsets and lengths of items in the copybook.
Multiple Records	This option determines whether to repeat the copybook parsing until the end of the input data is reached and whether to generate multiple output elements. If Multiple Records is selected, the schema of the Output property data becomes an array. Otherwise the schema is an object that contains a single instance of the copybook data.
Record Delimiter Length	The field that specifies the length of a delimiter between records in the input data in case of a true selected in Multiple Records field.
Trim Whitespaces from text items	Removes leading and trailing whitespace characters as well as additional characters from string values. The additional characters are as follows: U+0000 U+FEFF U+FFFD
Return Empty Nodes	Determines whether to exclude empty strings, objects or arrays from the output.
Return Remaining Bytes	Enable returning of the remainder of the input binary data. If selected, the output of the activity displays the remainingBytes field. This field contains the tailing portion of the input binary that has not been processed by this activity. For more information, see Connecting Multiple Parse Activities.
Allow Incomplete Records	This field determines whether the input must contain all the input data for the entire copybook layout (record) or whether incomplete layouts are tolerated. For more information, see Parsing Incomplete Records.
Allow Incomplete Text Items	If enabled, the last text item is allowed to have less bytes that the copybook implies. For more information, see Parsing Incomplete Records.
Ignore Invalid Items	This field turns off errors resulting from invalid content in the binary data in an elementary item. For more information, see Validation of Elementary Items.

Input

The Input tab has the following fields:

Field	Description
bytes	A byte sequence that contains COBOL data. It is encoded as Base64.
forceCharacterSet	A runtime override for the Character Set setting. For details about Character Set, see the description of the field Character Set in the section Parse Copybook Data-Configuration.
forceCharacterSetDisp1	A runtime override for the Character Set setting for DISPLAY-1 Items setting. For details about Character Set setting for DISPLAY-1 Items, see the description of the field Character Set for DISPLAY-1 Items setting in the section Parse Copybook Data - Configuration.
recordDelimiterLen	Runtime override for Record Delimiter Length. For details about Record Delimiter Length, see the description of the field Record Delimiter Length in the section Parse Copybook Data - Configuration.

Output Settings

The Output Settings tab displays the output schema of the activity as a tree structure. The output is read-only. The information in the schema varies based on the fields selected on the Configuration tab. The properties that are displayed in the schema correspond to the output of this activity and can be used as input by subsequent activities in the flow.

Output

The Output tab has the following fields:

Field	Description
noOfRecords	This is the number of records the activity has read.
remainingBytes	If you select the Return Remaining Bytes in Settings, the output of the activity contains the remainingBytes field. This field contains the tailing portion of the input base64Binary that has not been processed by this activity. For more information, see Connecting Multiple Parse Activities.
data	JSON data read from the input byte sequence. If Multiple Records is selected, it contains an array of records or a single record. The schema for a record is generated by the selected Copybook connection to reflect the copybook.

Connecting Multiple Parse Activities

A binary buffer often consists of data whose layouts could be described in multiple copybooks. Sometimes the decision of which copybook to use next is made based on the data present. Control fields in REDEFINE groups offer a form of control but do not cover all patterns. The most typical pattern is as follows:

• Two or more copybooks of different byte size are packed into an envelope message.
• Each copybook is preceded with an indicator field that determines which copybook layout follows.
• Layouts are different sizes, which makes it impossible to pack copybooks into a super-copybook with a REFEDINES clause.

To address this scenario, the Parse Copybook Data activity offers an option to return the remainder of the byte data, making it available to the next Parse activity. For example:

In this example, ParseCopybookData parses a small copybook

01 INDICATOR PIC X

The transitions are conditional on the data returned from the activity. The conditions are as follows:

$activity[ParseCopybookData].data.INDICATOR=='C'

and

$activity[ParseCopybookData].data.INDICATOR=='O'

ParseCopybookData1 is configured to use the copybook connection CUSTOMER and ParseCopybookData2 uses the copybook connection ORDER.

ParseCopybookData has the Return Remaining Bytes option enabled, the data is forwarded to the ParseCopybookData1 or ParseCopybookData2 activity.

The Return Remaining Bytes option is not selected by default. It must be enabled using the check box on the General tab. Selecting the Return Remaining Bytes check box results in the addition of the remainingBytes property to the parse activity's output.

Return Remaining Bytes is not applicable to activities with Multiple Records selected. If this option is selected, then Parse reads the copybook multiple times till the end of data is reached.

When the end of data is reached, the returned remainingBytes is empty.