CopybookViewGenerator User Guide


Version 4.2.424.0

1. Introduction to CopybookViewGenerator

The raw binary data is stored in the database when using the IMSql for SQL Server or file drivers for SQL Server or Cosmos DB.

The individual fields are known to the COBOL or PL/I program through the definition of the record data structure, typically stored in a copybook, but are otherwise not known to the database.

The CopybookViewGenerator tool takes a COBOL copybook, or PL/I structure, as input and generates the corresponding view to manipulate the database data in a structured way corresponding to said structure definition.

When targeting an SQL server, the CopybookViewGenerator tool generates an SQL script to create a view containing one column for each copybook’s variable with a picture clause and, optionally, columns of the original table to read the data.

The script also contains the creation of triggers so that the view can be used to update, insert and delete data and adjust the underlying raw data representation accordingly. Before executing the SQL creation script, conversion functions should be created.

To do so, execute the scripts Functions.sql and EbcdicFuncs.sql available at the location C:\Program Files\Raincode\Compilers\net6.0\bin\sql.

When targeting Cosmos DB, the CopybookViewGenerator tool generates a C# class that defines a data structure corresponding to the copybook definitions and a method to decode binary data. This C# class can then be used by the CosmosDBChangedFeedProcessor, which updates the view container whenever the data container is modified. This view is read-only, i.e. changes in the view container are not reported back to the data container.

For example, the ORDERS segment is declared in the following IMS DBD:

SEGM  NAME=ORDERS,BYTES=240,PARENT=CATALOG
      FIELD NAME=(ORDNBR,SEQ,U),BYTES=20,START=21,TYPE=C
      FIELD NAME=DETAILS,BYTES=200,START=41,TYPE=C

And a copybook refining the structure of ORDERS as such:

01 CPY-ORDERS.
      05 CPY-PRE                  PIC X(20).
      05 CPY-ORDNBR               PIC X(20).
      05 CPY-DETAILS.
         10 CPY-DESCR             PIC X(176).
         10 CPY-DATE-9            PIC 9(8).
         10 CPY-TOTAL             PIC 9(5)V9(2) COMP-3.
         10 CPY-VAT               PIC 9(7)V9(2) COMP.
         10 FILLER                PIC X(8).

With the option -type=sql, it will produce the following SQL view:

Create or alter View [dbo].[DEALERDB_ORDERS_V]
as select
-- the columns of the original table
  [DEALERDB_ORDERS].[RID]
  ,[DEALERDB_ORDERS].[HID]
  ,[DEALERDB_ORDERS].[PID]
  ,[DEALERDB_ORDERS].[Data]
  ,[DEALERDB_ORDERS].[SEGDATA1]
  ,[DEALERDB_ORDERS].[ORDNBR]
  ,[DEALERDB_ORDERS].[DETAILS]
-- the columns representing the copybook variables
  , ... as [CPY_PRE]
  , ... as [CPY_ORDNBR]
  , ... as [CPY_DESCR]
  , ... as [CPY_DATE_9]
  , ... as [CPY_TOTAL]
  , ... as [CPY_VAT]
  , ... as [FILLER_1]
  from [dbo].[DEALERDB_ORDERS];

and with the option -type=cosmos, the following C# class:

namespace RainCodeLegacyFileDriver.Azure
{
    public class OrdersViewFields : ViewFields
    {
        public string CPY_PRE { get; set; }
        public string CPY_ORDNBR { get; set; }
        public string CPY_DESCR { get; set; }
        public int CPY_DATE_9 { get; set; }
        public decimal CPY_TOTAL { get; set; }
        public decimal CPY_VAT { get; set; }
        public string FILLER_1 { get; set; }

        public OrdersViewFields(byte[] data)
        {
            this.CPY_PRE = Conversion.EBCDIC_TO_string(data, 0, 20);
            this.CPY_ORDNBR = Conversion.EBCDIC_TO_string(data, 20, 20);
            this.CPY_DESCR = Conversion.EBCDIC_TO_string(data, 40, 176);
            this.CPY_DATE_9 = Conversion.DISPLAY_UNSIGNED_TO_int(data, 216, 8);
            this.CPY_TOTAL = Conversion.COMP3_TO_decimal(data, 224, 4,2);
            this.CPY_VAT = Conversion.COMP_UNSIGNED_TO_decimal(data, 228, 4,2);
            this.FILLER_1 = Conversion.EBCDIC_TO_string(data, 232, 8);
        }
}

2. Views generation

The view generation is done in two steps:

  • Transformation of the COBOL or PL/I declaration in XML

  • Generation of the view and triggers creation scripts

2.1. COBOL Copybook to XML

The COBOL compiler (cobrc) is used to parse the copybook and transform it into an XML file. The step of parsing the copybook and transforming it into XML is performed automatically by the CopybookViewGenerator tool when using the option -cpy.

The compiler is invoked with :DeclDescriptors to give the path to the output file and the copybook:

cobrc :DeclDescriptors=path_to_xml.xml path_to_cpy.cpy

The XML file contains the description of all the variables defined in the copybook.

2.2. COBOL or PL/I program to XML

The COBOL compiler (cobrc) or the PL/I compiler (plirc) are used to parse a source file and transform all the variables declaration into an XML file.

The compiler is invoked with :DeclDescriptors to give the path to the output file and the source file:

cobrc :DeclDescriptors=path_to_xml.xml path_to_source.cbl
plirc :DeclDescriptors=path_to_xml.xml path_to_source.pli

2.3. XML to SQL

The CopybookViewGenerator tool reads the XML file produced in the previous step and generates the view. If the XML file contains more than one variable declaration, the option :struct is used to specify the name of the variable for which the view needs to be generated.

CopybookViewGenerator :xml=path_to_xml.xml :struct="my-var" :table="my_table" :output=path_to_sql_scrip.sql

By default, the view contains all the columns of the original table. If the table columns are not necessary in the view, the option :OnlyTech can be added.

3. Parameters

It uses the following parameters:

Table 1. Parameters of CopybookViewGenerator

Command-line option

Default value

Description

type

SQL

Specifies the output type. Supported types are -type=sql for SQL Server (SQL code) and -type=cosmos for Cosmos DB (C# code).

cpy

Specifies the copybook to use when creating the view. An XML file is generated by the Raincode COBOL compiler as if it were provided through the -xml option.

XML

Specifies the XML form of the copybook to use when creating the view, as generated by the Raincode COBOL and PL/I compilers.

DB

Specifies the database name to be referred to explicitly in generated SQL source files.

schema

Specifies the schema name to be referred to explicitly in generated SQL source files.

table

Specifies the table for which the SQL view must be generated.

output

Specifies the file in which the view must be generated.

struct

Specifies the name of the structure to use when generating the view. If no such structure is specified, the first structure in the copybook is used.

conn

Specifies the connection string for the data source to query the table structure. Available only for the SQL Server.

rawcolumns

False

Matches the raw slices of the record in the form of unconverted binary values. Available only for the SQL Server.

debugmode

False

Generates debugging assertion in the SQL view. Available only for the SQL Server.

readonly

False

When set, it generates only the read-only view, not the triggers that allow this view to be used as a read/write table. Available only for the SQL Server.

schemabinding

False

When set, it ensures that all the generated artefacts are bound to the schema for better performance and allow the generated views to be indexed. Available only for the SQL Server.

compileroptions

Additional options to pass to the compiler when generating the XML form of the copybook with the -cpy option.

OnlyTech

False

Generates a view containing only the technical columns (RID, PID, HID) of the table. Available only for the SQL Server.