COBOL Copybook Formatter
In this article
Overview
You can use the COBOL Copybook Formatter Snap to format a JSON file into a flat file based on the specified COBOL structures. COBOL programs can then format the input data to process the output.
Snap Type
The Copybook Formatter Snap is a Format-type Snap that formats a flat file based on the specified COBOL structures.
Prerequisites
None.
Support for Ultra Pipelines
Does not support Ultra pipelines.
Limitations
The input document structure is very rigid and must map to the format of the provided COBOL structures.
Known Issues
None.
Snap Views
Type | Format | Number of Views | Examples of Upstream and Downstream Snaps | Description |
---|---|---|---|---|
Input | Document |
|
| Structured JSON documents that match the structure of the COBOL structures. |
Output | Binary
|
|
| A flat binary file containing the data mapped from the input document to the COBOL structures provided as part of the configuration. |
Error | Error handling is a generic way to handle errors without losing data or failing the Snap execution. You can handle the errors that the Snap might encounter when running the pipeline by choosing one of the following options from the When errors occur list under the Views tab:
Learn more about Error handling in pipelines. |
Snap Settings
Asterisk ( * ): Indicates a mandatory field.
Suggestion icon (): Indicates a list that is dynamically populated based on the configuration.
Expression icon ( ): Indicates the value is an expression (if enabled) or a static value (if disabled). Learn more about Using Expressions in SnapLogic.
Add icon ( ): Indicates that you can add fields in the field set.
Remove icon ( ): Indicates that you can remove fields from the field set.
Upload icon ( ): Indicates that you can upload files.
Field Name | Field Type | Description | |
---|---|---|---|
Label*
Default Value: Cobol Copybook Formatter | String | Specify the name for the Snap. You can modify the default name to be more specific and meaningful, especially if you have more than one of the same Snaps in your pipeline.
| |
Copybooks* | Use this field set to define the Copybooks to use. | ||
Copybook File*
Default Value: N/A | String/Expression | Specify the Copybook file that describes the data. Alternatively, click the upload icon to browse and upload the required copybook file. | |
Copybook Split*
Default Value: SPLIT_NONE | String/Expression/Suggestion | Select the option to split the Copybook for processing. The available options are:
| |
Organization*
Default Value: IO_DEFAULT | String/Expression/Suggestion | Specify the type of file organization for the data payload. Alternatively click the Suggestion icon to fetch a list of file organisation types and select the desired organization.
Learn more about Organization types. | |
Dialect*
Default Value: FMT_MAINFRAME | String/Expression/Suggestion | Specify the COBOL dialect. The available options are:
The selected dialect determines how the parser deals with binary information in the input file. | |
Encoding*
Default Value: UTF8 | String/Expression/Suggestion | Specify the format for encoding the input data. Any supported Java encoding is available for use. Some common code pages to be used:
| |
Configure error processing | Configure the action the Snap must take if an error occurs. | ||
Set maximum acceptable number of errors | Integer | Set the maximum number of acceptable errors that can occur before the Snap terminates. Zero (0) indicates no limit on errors that can be issued. | |
Configure field error processing | Use this field set to configure the Snap's action when an error occurs for each field. | ||
Field Name | String/Expression/Suggestion | Specify or select the full name (this must include structure for uniqueness) of the COBOL field being configured. | |
Error processing configuration* | Expression/Dropdown list | Select or set the action the Snap must take when an error occurs when processing:
| |
Default value for field | String/Expression | Specify the default value that will be output for a field. | |
Debugging configuration | Configure the debugging properties. | ||
Name of only structure to output | String/Expression/Suggestion | Specify or select the name of the only structure for which data is to be sent to the output. Data for any other structure is ignored and is not sent to the output. | |
Ranges of records to be output | Specify one or more ranges of records to be output. | ||
Low record for range | String | Specify the first record in the range to be passed to the output.
| |
High record for range | String | Specify the last record in the range to be output. | |
Set character to initialize each record | Integer | Specify the number (optional) to set each record to the output. The field is specified as a numeric value from 0 to 255 inclusive and represents the decimal value of the character to be used. For example:
| |
Snap Execution
Default Value: Validate & Execute | Dropdown list | Select one of the three modes in which the Snap executes:
|
Additional configuration requirements
The output from this Snap will be a flat binary file containing the data that reflects the COBOL structure(s) provided as part of the configuration. This file will consist of data that has records with the following formats. For the records to be written correctly, you must configure the correct record type processing for the records to be processed accurately. For more information about the Organization types, refer to the Organization field in the Snap Settings table:
Fixed Length records (IO_FIXED_LENGTH): Records that have a consistent fixed length that is the total length of the COBOL structure or structures configured for the Snap.
Records delimited by a carriage return/line feed (CR/LF) or just a LF (IO_STANDARD_TEXT_FILE): Records separated by CR/LF characters within the data. The length of the data between these CR/LFs may be fixed or variable and must correctly be represented by the length of the COBOL structure or structures configured for the Snap.
Variable blocked records (IO_VB): Variable length records that are created on IBM z/OS environments with an RDW prior to each record. This RDW includes the record length, including the length of the following data followed by the Record-data.
Alternate variable blocked records (IO_VLI): Records consist of a byte swapper Record-Length excluding the length of the following data followed by the Record-Data.
To ensure accurate processing of the data, you must configure the following types of data correctly:
Character data: This data must have a code page you must correctly specify in your configuration.
Binary data: These are binary numeric values that have a specific endianness (the order in which the bits are transmitted over a communication channel) depending on the platform from which they have originated.
Big Endian generally comes from older mainframe platforms (z Series, i Series, Solaris, and so on) and is where the high-order byte of the binary value is the most significant byte.
Little Endian generally comes from newer platforms (x86, x86-64, and so on) and is where the low-order byte of the binary value is the most significant byte.
Troubleshooting
Error | Reason | Resolution |
---|---|---|
Account validation failed. | The pipeline ended before the batch could complete execution because of a connection error. | Verify that the Refresh token field is configured to handle the inputs properly. If you are not sure when the input data is available, configure this field as zero to keep the connection always open. |
Examples
Process a Single JSON-formatted Record
This example demonstrates how to use a single COBOL Structure defined with a JSON format being processed from JSON to COBOL formatted output for postprocessing by a downstream Snap.
Configure the File Reader Snap to accept the data for processing. Provide the filename and leave the other settings with default values.
Next, provide the JSON Parser Snap to output the contents as a document downstream. Lave all values defaulted for this step.
Next, provide the COBOL Formatter Snap to handle the incoming data and output a document downstream. Provide a valid matching Copybook to handle the incoming data and modify the additional settings based on the requirements for that Copybook.
The pipeline is now ready to process the file and produce the formatted document. Following pipeline validation, you can preview the output:
Process multiple JSON-formatted records
This example demonstrates how to use a multi-record COBOL structure defined with a JSON format processed from JSON to COBOL format output using the JSON Parser and Copybook Formatter Snaps.
Configure the File Reader Snap to read the data for processing. Provide the filename and leave the other settings with the default values.
Configure the JSON Parser Snap to output the contents as a document. Leave the other settings with default values.
Configure the COBOL Formatter Snap to handle the incoming data to output a document downstream. You must provide a valid matching Copybook to handle the incoming data and modify the additional settings based on the requirements for that Copybook.
On validation, the pipeline processes the file and produces the formatted document.
Process JSON-formatted records with header and trailer details
This example demonstrates how to process the COBOL structure containing header and trailer definitions defined in a JSON format.
Configure the File Reader Snap to read the data for processing.
Next, connect the JSON Parser Snap to output the contents as a document downstream.
Configure the COBOL Formatter Snap with a valid matching Copybook to handle the incoming data and modify the additional settings based on the requirements for that Copybook.
The COBOL Copybook Formatter has the ability to accept multiple types of records in the input stream when multiple COBOL Structures are provided. In this case, the Structure name of the COBOL structure to be used must be the top level in the JSON input.
On validation, the pipeline processes the file and produces the formatted document.
Downloads