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.

You can process documents using the following steps:

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.

When the pipeline is run, Snap produces a binary output representing the input documents formatted according to 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

Min: 1
Max: 1

JSON Splitter

The input to this snap must be structured JSON documents that match the structure of the COBOL structures.

Output

Binary

Min: 1
Max: 1

File writer
Zip File Writer

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:

Stop Pipeline Execution: Stops the current pipeline execution if the Snap encounters an error.
Discard Error Data and Continue: Ignores the error, discards that record, and continues with the remaining records.
Route Error Data to Error View: Routes the error data to an error view without stopping the Snap execution.

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 Example: Process The 038 Copybook		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.
Copybooks*	Copybook File* Default Value: N/A Example: PipeRecFileOfPS.jso	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 Example: SPLIT_01_LEVEL		String/Expression/Suggestion	Select the option to split the Copybook for processing. The available options are: SPLIT_NONE: No split. SPLIT_01_LEVEL: Splits on all 01 levels. SPLIT_TOP_LEVEL: Splits on the top-level structures defined by a level that is is greater than level 01. SPLIT_REDEFINE: Splits on the highest level of COBOL REDEFINE structures. If the Copybook contains multiple ‘01 entries’, it must be split for processing. If the Copybook contains multiple structures below the 01 level, that must be used. If the Copybook contains multiple ‘01 entries’, it must be split for processing. If the Copybook contains multiple structures below the 01 level, that must be used.
Organization* Default Value: IO_DEFAULT Example: IO_UNICODE_TEXT		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. IO_DEFAULT: Attempt to automatically detect the file organization. IO_STANDARD_TEXT_FILE: Standard file using CRLF or LF as newline delimiter. IO_UNICODE_TEXT: Unicode/double byte file using CRLF or LF as newline delimiter. IO_FIXED_LENGTH: Every record (or line) is a standard fixed length based on the maximum record length (determined from copybook). IO_CONTINOUS_NO_LINE_MARKER: Files where there are no End-of-Line markers. Records are based on Record-Lengths. IO_VB: Mainframe VB (Variable Record length file). Records consist of a Record-Length including the length of the following data followed by the Record-Data. IO_VLI: Mainframe like VB (Variable Record length file). Records consist of a byte swapper Record-Length excluding the length of the following data followed by the Record-Data. Learn more about Organization types.
Dialect* Default Value: FMT_MAINFRAME Example: FMT_INTEL		String/Expression/Suggestion	Specify the COBOL dialect. The available options are: FMT_MAINFRAME: Mainframe COBOL (Big Endian). FMT_INTEL: Intel COBOL (Little Endian). FMT_FUJITSU: Fujitsu Cobol 3 compiler. FMT_OPEN_COBOL: GnuCobol (formerly Open Cobol) on a Little-Endian machine. FMT_OC_MICRO_FOCUS_B: GnuCOBOL running in Microfocus compatibility mode on a Big-Endian machine. FMT_BIG_ENDIAN: Generic Big Endian. The selected dialect determines how the parser deals with binary information in the input file.
Encoding* Default Value: UTF8 Example: CP1252		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: CP1141: Standard mainframe EBCDIC code page. ASCII: Standard ASCII files. Windows-1252: Standard code page used on Windows platforms.
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 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: Fail: The pipeline processing fails immediately an error is encountered on this field. This is the default behavior of the Snap. IgnoreField: The field is ignored and is not included in the output record. IgnoreRecord: The entire record is ignored and not included in the output. DefaultValue: The default value provided will be output for the field in the output record.
	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. The numbers here are relative to 1, so 1 is the first record, 2 is the second record. If the ranges include records that don’t exist in the input data, these will be ignored. If ranges overlap, this will cause a configuration error.
	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: 0 – x’00’ (low values) 32 – Ascii blank 64 – EBCDIC Blank 255 – x’FF’(high values) This has performance implications so we recommend you to use only if required.
Snap Execution Default Value: Validate & Execute Example: Execute only		Dropdown list	Select one of the three modes in which the Snap executes: Validate & Execute: Performs limited execution of the Snap, and generates a data preview during Pipeline validation. Subsequently, performs full execution of the Snap (unlimited records) during Pipeline runtime. Execute only: Performs full execution of the Snap during Pipeline execution without generating preview data. Disabled: Disables the Snap and all Snaps that are downstream from it.

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 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 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.