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 structure(s). COBOL programs can then format the input data to process the output.
Provide one or more COBOL copybooks to the Snap to process the data.
Configure the Snap to indicate how the COBOL structures should be interpreted. A single or multiple copybooks can contain one or more structures that are used to create the output data. The Snap must understand the level at which these structures should start in the COBOL copybook. If there is a single structure, no splitting of the copybook is required. If there are multiple structures in the copybooks, normally this will be at the 01 level; however, there are also options to split based on other levels.
Configure the format of the records to be written to the output file.
Configure the code page in which the output character fields are encoded.
Configure the endianness of the output binary fields.
Configure the default value to which each flat file record should be set initially if required.
Provide input documents that comply with the structures below.
On running the pipeline, the Snap produces a binary output representing the input documents formatted based on the specified COBOL structure.
Input Document Structure
The input document structure must exactly map to the COBOL structure or structures as follows:
If the COBOL copybook is a list of fields without any structures, the input document will consist of a list of fields with the same name as the COBOL field, with a value to be set into the correct location in the flat file record. A sample COBOL copybook and input data are provided below:
If the COBOL copybook has a high level 01 Structure and individual fields below this, the input document must have fields in the format <StructureName> as the first level and then each <fieldname> in an object below that. A sample COBOL copybook and input data are provided below:
If the COBOL copybook contains multiple different COBOL structures, the input must be an input document with each document element starting with the name of one of the COBOL structures provided. The rest of the structure should follow the same rules as above. A sample COBOL copybook and input data are provided below:
Note that often, there is a requirement to supply data as a hexadecimal value. This can be achieved by providing the value of a field in the format of x’012345’, but please note:
The value must be an even number of digits to be a valid hexadecimal value.
The value is set exactly as is in the location of the field in the output flat file. Therefore the exact length of that field must be provided.
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 |
|
| The input to this snap must be structured JSON documents that match the structure of the COBOL structures. |
Output | Binary |
|
| The output from this Snap is a flat binary file containing the data that has been mapped from the input document to the COBOL structure(s) 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 fieldset.Remove icon (
): Indicates that you can remove fields from the fieldset.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 which describes the data. Alternatively, click the upload | |
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 organisation for the data payload. Alternatively click the Suggestion
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 when 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 ocucurs 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 will be 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:
This has performance implications so we recommend you to use only if required. | |
Snap Execution
Default Value: Validate & Execute | Dropdown list | Select one of the three modes in which the Snap executes:
| |
Additional Information
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 that are 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 should have a code page that you must correctly specify in your configuration.
Binary data: These are binary numeric values that will have a specific endianness (the order in which the bits are transmitted over a communication channel) depending on the platform from which they have come.
Big Endian generally comes from older mainframe platforms (z Series, i Series, Solaris etc.) 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 due to 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:
Downloads
Download and import the Pipeline into SnapLogic.
Configure Snap accounts, as applicable.
Provide Pipeline parameters, as applicable.