SimoREC1 When technology complements business   COBOL Copy File Analysis

Copyright © 1987-2008  SimoTime Enterprises, LLC  All Rights Reserved http://www.simotime.com

Introduction
(Next) (Previous) (Table-of-Contents)

SimoREC1 (a COBOL Record Layout and Content Conversion Utility Program) is currently available as a Controlled Release Option (CRO). CRO's provide a process for SimoTime to deliver technology that is used by our consultants in the field but has not been productized. A CRO has been field tested through actual use for a minimum of six months and is subjected to a suite of regression tests prior to release. SimoTime's intent is to productize this CRO and make it generally available with appropriate documentation. SimoTime reserves the right to change a CRO during the productizing process. This may require a user to make changes pertaining to the CRO usage and interfaces.

The SimoTime Record Layout and Content Conversion Utility Program (SimoREC1) reads a COBOL Copy FIle and produces various outputs for reference material, documentation and data file conversion. For reference or documentation purposes SimoREC1 creates an ASCII/Text file and an HTML document from a COBOL copy file. The utility provides the length of a field and the position of the start of the field within a record. Also, the actual physical length for group items, packed fields, binary fields and tables will be calculated. This information is provided by the SimoTime Record Layout utility program within a text file and an HTML document.

Once this information has been calculated SimoREC1 has the capability of creating the source code for a callable COBOL program that will do the conversion between EBCDIC and ASCII at the field level. The SimoREC1 utility used in conjunction with the SimoZAPS utility has the capability of generating a set of programs that will read a file containing EBCDIC encoding and write a new file containing ASCII encoding. The numeric encoding used by the IBM Mainframe or Micro Focus is maintained.

Some of the information about a record structure may be found by compiling a program that references the copy file and then analysing the listing. For example, with Micro Focus COBOL using the DATAMAP option will produce a listing file with useful information about the fields in working storage.

For more information about this program or if you have any questions, suggestions or comments please call or send an e-mail to: helpdesk@simotime.com.

Program Objectives
(Next) (Previous) (Table-of-Contents)

SimoREC1 will scan a COBOL copy file and produce the following information.

Program Input and Output
(Next) (Previous) (Table-of-Contents)

The following shows a couple of examples of using COBOL copy files as input and producing HTML documents as output.

COBOL Copy File, A Simple Example
(Next) (Previous) (Table-of-Contents)

The following is a simple example of a COBOL copy file. Without a utility program the length of VKSD-NAME must be manually calculated. The VKSD-CREDIT-LIMIT field is nine (9) digits and appears to be nine (9) bytes in length. However, the use of the COMP-3 will make it a packed field and the length will be five (5) bytes. The following HTML document quickly provides this information.

      *****************************************************************
      *  Copy File for the VSAM Data Set used for the Demo programs.  *
      *****************************************************************
      *         Copyright (C) 1987-2003 SimoTime Enterprises          *
      *                     All Rights Reserved                       *
      *****************************************************************
      *              Provided by SimoTime Enterprises                 *
      *        Our e-mail address is: helpdesk@simotime.com           *
      *     Also, visit our Web Site at http://www.simotime.com       *
      *****************************************************************
       01  VKSD-RECORD.
           05  VKSD-KEY            PIC X(12).
           05  VKSD-NAME.
               10  VKSD-LAST-NAME  PIC X(28).
               10  VKSD-FIRST-NAME PIC X(18).
           05  VKSD-ADDRESS-1      PIC X(48).
           05  VKSD-ADDRESS-2      PIC X(48).
           05  VKSD-CITY           PIC X(18).
           05  VKSD-STATE          PIC X(18).
           05  VKSD-POSTAL-CODE    PIC X(12).
           05  VKSD-CREDIT-LIMIT   PIC S9(7)V9(2)  COMP-3.
           05  VKSD-FILLER         PIC X(305).
      *!   KSDCPYB2 - End-of-Copy File...

The following is a simple example of the HTML documentation created from the preceding COBOL copy file.

COBOL Copy File, A Challenging Example
(Next) (Previous) (Table-of-Contents)

The following is a challenging example of a COBOL copy file. The length of KSE00256-REC must be manually calculated and this can be a bit more challenging than the previous example. The length of P-TABLE-09S-10E appears to be nine (9) bytes. However, the use of the COMP-3 will make it a packed field and the length will be five (5) bytes. Furthermore, the OCCURS clause makes it a table of ten (10) elements so the length is of P-TABLE-09S-10E is actually fifty (50) bytes. Also, note the use of REDEFINES and REDEFINES with the redefinition being shorter than the primary field. This is a legitimate coding technique but the length of the primary field must be used when calculating the total length of the record. The following HTML document quickly provides this information.

      *****************************************************************
      *    Record layout for testing SimoREC1                         *
      *****************************************************************

      *    *----------------------------------------------------------*
      *    1. Create a group item
      *    2. What is the Length?
       01  KSE00256-REC.

      *    *----------------------------------------------------------*
      *    1. Create a simple numeric field.
      *    2. What is the relative position within the record layout?
           05  KSE00256-KEY-01     pic 9(6).

      *    *----------------------------------------------------------*
      *    1. Create a group item.
      *    2. Create two alphameric fields within the group item.
      *    3. What is the length of the group item?
           05  X-ALHPAMERIC-FIELDS.
               10  X-FIELD-08      pic X(8).
               10  X-FIELD-32      pic X(32).

      *    *----------------------------------------------------------*
      *    1. Create a group item.
      *    2. Create various fields within the group item.
      *    3. What is the length of the group item?
           05  VARIOUS-FORMATS.
               10  PIC-XXX         pic XXX.
               10  PIC-999         pic 999.
               10  PIC-99V999      pic 99V999.
               10  PIC-99V9P3P     pic 99V9(3).
               10  PIC-9P2PV999    pic 9(2)V999.
               10  PIC-S999        pic S999.
               10  PIC-S99V999     pic S99V999.
               10  PIC-S99V9P3P    pic S99V9(3).
               10  PIC-S9P2PV999   pic S9(2)V999.

      *    *----------------------------------------------------------*
      *    1. Create a group item.
      *    2. Create two numeric fields within the group item.
      *    3. What is the length of the group item?
           05  N-NUMERIC.
               10  N-07-UNSIGN     pic  9(7)V9(2).
               10  N-07-SIGNED     pic S9(7)V9(2).

      *    *----------------------------------------------------------*
      *    1. Create a group item.
      *    2. Create two packed, numeric fields within the group item.
      *    3. What is the length of the group item?
           05  P-NUMERIC.
               10  P-09-UNSIGN     pic  9(7)V9(2)   COMP-3.
               10  P-09-SIGNED     pic S9(7)V9(2)   COMP-3.

      *    *----------------------------------------------------------*
      *    1. Create a group item.
      *    2. Create two binary, numeric fields within the group item.
      *    3. What is the length of the group item?
           05  B-NUMERIC.
               10  B-09-UNSIGN     pic  9(7)V9(2)   COMP.
               10  B-09-SIGNED     pic S9(7)V9(2)   BINARY.

      *    *----------------------------------------------------------*
      *    1. Create a group item.
      *    2. Create two leading, signed fields within the group item.
      *    3. What is the length of the group item?
           05  LN-SIGNED.
               10  LN-09-SIGNED    pic S9(7)V9(2)   SIGN LEADING.
               10  LN-09-SIGNED-S  pic S9(7)V9(2)
                                   SIGN LEADING SEPARATE.

      *    *----------------------------------------------------------*
      *    1. Create a group item.
      *    2. Create two trailing, signed fields within the group item.
      *    3. What is the length of the group item?
           05  TN-SIGNED.
               10  TN-09-SIGNED    pic S9(7)V9(2)   SIGN TRAILING.
               10  TN-09-SIGNED-S  pic S9(7)V9(2)
                                   SIGN TRAILING SEPARATE.

      *    *----------------------------------------------------------*
      *    1. Create a group item.
      *    2. Create a table or array within the group item.
      *    3. What is the length of the group item?
           05  P-TABLE-09S-10E.
               10  PT-09S-CELL     pic S9(9)       COMP-3
                                   OCCURS 10 TIMES.

      *    *----------------------------------------------------------*
      *    1. Create a group item.
      *    2. Create a table or array within the group item.
      *    3. What is the length of the group item?
           05  TABLE-NO-PIC        OCCURS 15 TIMES.
               10  TABLE-NO-PIC-XX pic XX.
               10  TABLE-NO-PIC-3  pic X(3).

      *    *----------------------------------------------------------*
      *    1. Create a four-byte alphameric field.
      *    2. Create a redefined group item.
      *    3. Create four fields within the redefined group item.
           05  RED-01-PRIME        pic X(4).
           05  RED-01-AGAIN        REDEFINES RED-01-PRIME.
               10  RED-01-BYTE-01  pic X.
               10  RED-01-BYTE-02  pic X.
               10  RED-01-BYTE-03  pic X.
               10  RED-01-BYTE-04  pic X.

      *    *----------------------------------------------------------*
      *    1. Create a four-byte alphameric field.
      *    2. Create a redefined group item.
      *    3. Create two fields within the redefined group item.
      *    4. What is the length of the redefined group item?
           05  BLUE-01-PRIME       pic X(4).
           05  BLUE-01-SHORT       REDEFINES BLUE-01-PRIME.
               10  BLUE-01-BYTE-01 pic X.
               10  BLUE-01-BYTE-02 pic X.

      *    *----------------------------------------------------------*
      *    1. Create a four-byte alphameric field.
      *    2. Create a redefined four-byte, numeric field.
           05  FOUR-BYTES-PRIME    pic X(4).
           05  FOUR-BYTES-VALUE    REDEFINES FOUR-BYTES-PRIME
                                   pic 9(4).
      *    *----------------------------------------------------------*
      *    1. Create a six-byte alphameric field.
      *    2. Create a short-redefine as a four-byte, numeric field.
           05  SIX-BYTES-PRIME     pic X(6).
           05  SIX-BYTES-SHORT     REDEFINES SIX-BYTES-PRIME
                                   pic 9(4).

      *    *----------------------------------------------------------*
      *    1. Create a nine-byte, alphameric field.
      *    2. Create a short-redefine as a packed, five-digit,
      *       three-byte field.
      *    3. Create a nested redefine as a three-byte, alphameric
      *       field.
           05  NINE-PRIME          pic X(9).
           05  NINE-AGAIN          REDEFINES NINE-PRIME.
               10  NINE-AGAIN-05   pic 9(5)    COMP-3.
               10  NINE-AGAIN-05-R REDEFINES NINE-AGAIN-05
                                   pic X(3).
      *    *----------------------------------------------------------*
      *    1. Create a one-byte, alphameric field.
           05  ONE-BYTE            pic X   value '*'.

      *    *----------------------------------------------------------*
      *    1. Create a two-hundred-byte, alphameric field.
           05  FILLER              pic X(200).

The following is a challenging example of the HTML documentation created from the preceding COBOL copy file.

System Requirements and Installation
(Next) (Previous) (Table-of-Contents)

The SimoREC1 Record Layout and Content Conversion Utility Program requires about 1 meg of disk space to install. SimoREC1 requires very little resources to execute. The Micro Focus COBOL suite of products will usually determine the minimum hardware configuration. A typical configuration to run the SimoTime technologies, the Micro Focus COBOL oriented technologies and application components are 20 megabytes of disk and 256 meg of memory. SimoREC1 will run in the following environments.

To install the SimoREC1 Record Layout and Content Conversion Utility Program run the SETUP.EXE from the Compact Disk. This utility program will install into the C:\SimoLIBR directory by default. We recommend this not be changed because the samples and the IVP's (Installation Verification Procedures) expect this configuration.

Note: If the target install directory for SimoLIBR is changed it will be necessary to modify the ZAPSREC1.CMD, ZAPSREC2.CMD and the IVP.CMD's to access the new directory structure. Also, the modified SimoLIBR directory should be added to the path statement.

Quick Start
(Next) (Previous) (Table-of-Contents)

This section provides information on how to quickly start the process of creating the data file conversion programs using SimoREC1 once the Installation is complete. This section will provide "quick start" informaion for the following four items.

The following descriptions assume that SimoZAPS and SimoREC1 are installed in the C:\SimoLIBR directory and this directory is on the Windows PATH.

Quick Start, How to Create HTML Documention for Record Structures
(Next) (Previous) (Table-of-Contents)

The following command (REC1HTML.CMD) may be used to generate HTML documentation from a COBOL copy file.

The 1st parameter copyfilename must be the name of a COBOL copy file.

The 2nd parameter HTMLname must be the name of the HTML document to be created.

The 3rd parameter IBM or MF must be "IBM" or "MF".

The "IBM" keyword will cause the record structure (position and length of fields) to be calculated based on the size of COMP or BINARY fields used on the mainframe (i.e. binary fields are 2, 4 or 8 bytes only).

The "MF" keyword will cause the record structure (position and length of fields) to be calculated based on the size of COMP or BINARY fields used on the Wintel or UNIX platforms (i.e. binary fields are based on the number of digit in the picture clause and may be 1, 2, 3, 4 , 5, 6, 7 or 8 bytes).

For a more detailed description of creating HTML documentation refer to the Create HTML Documentation, System Description section of this document.

Quick Start, How to Create a Callable Conversion Routine
(Next) (Previous) (Table-of-Contents)

The following command (REC1CALL.CMD) may be used to generate the COBOL source code for a callable conversion routine from a COBOL copy file.

The 1st parameter copyfilename must be the name of a COBOL copy file.

The 2nd parameter routinename must be the name of the callable COBOL routine to be created.

For a more detailed description of creating a callable conversion routine refer to the Create a Callable Data Conversion Routine section of this document.

Quick Start, How to Create File I/O Programs
(Next) (Previous) (Table-of-Contents)

The section will describe how to read a file, convert the content of the individual records and write a new file. Two approaches are discussed. The first approach will read the input file sequentially and write the output file sequentially. This appraoch is the fastest and will work for most situations. A problem arises when doing content conversion between ASCII and EBCDIC and if the output file has a VSAM, Keyed Sequential Data Set (KSDS) or Micro Focus Keyed-Indexed file with an alpha-numeric key. Since the collating sequences are differnt for ASCII and EBCDIC (for example, the numbers come before the letters in ASCII and the number come after the letters in EBCDIC) this could result in trying to add a record out of sequence. Therefore, a second approach is provided that does a random update or add to the output file.

The File I/O program is actually created using the SimoZAPS utility. For a more detailed description refer to the documentation for SimoZAPS in the "Generate Function, The Control File" section on the SimoTime Web Site.

Quick Start, File I/O Program with Ordered or Sequential Load
(Next) (Previous) (Table-of-Contents)

The following command (ZapsRec1.CMD) may be used to generate the COBOL source code for a file I/O program. This requires a minimum amount of specifications to be defined in a control file. This command will generate the COBOL source code to read and write files by processing in a sequential order.

The 1st parameter controlfilename must be the name of a control file with a minimum amount of file definition specifications.

The 2nd parameter programname must be the name of the callable COBOL program to be created.

The following shows the contents of a control file for sequential processing.

/Dialect   C2
/progid    ITKEKAC1
/sysut1    name=ITMGETDE org=Indexed recfm=variable rlen=512 klen=12 kpos=1
/sysut2    name=ITMPUTDA org=Indexed recfm=variable rlen=512 klen=12 kpos=1
*
/transmode E2A
/transcall ITME2AR1
*
/END

Quick Start, File I/O Program with Random Add or Update
(Next) (Previous) (Table-of-Contents)

The following command (ZapsRec2.CMD) may be used to generate HTML documentation from a COBOL copy file.

The following command (ZapsRec2.CMD) may be used to generate the COBOL source code for a file I/O program. This requires a minimum amount of specifications to be defined in a control file. This command will generate the COBOL source code to read the records from the input file in sequential order and write or rewrite the records to the output file in a random order.

The 1st parameter controlfilename must be the name of a control file with a minimum amount of file definition specifications.

The 2nd parameter programname must be the name of the callable COBOL program to be created.

The following shows the contents of a control file for random processing.

/Dialect   C2
/progid    ITKEKAC1
/VSAMLOAD  RANDOM
/sysut1    name=ITMGETDE org=Indexed recfm=variable rlen=512 klen=12 kpos=1
/sysut2    name=ITMPUTDA org=Indexed recfm=variable rlen=512 klen=12 kpos=1
*
/transmode E2A
/transcall ITME2AR1
*
/END

Installation Verification Procedures (IVP) & Examples
(Next) (Previous) (Table-of-Contents)

This section describes the Installation Verification Procedures (IVP's) provided in the Z-Pack for SimoREC1. The IVP's are a suite of Windows Command Files and sample copy files that validate the correct installation and system configuration while demonstrating some of the capabilites of SimoREC1. The IVP,s may also serve as examples or models and may be copied and then modified to generate conversion programs or documentation based on user-defined copy files.

The following section will refer to the IBM or MF (i.e. Micro Focus) format. On an IBM mainframe numeric fields that are BINARY (or COMP) are always 2, 4 or multiple of 8 bytes. In the Micro Focus environment it is possible to have a 1, 3, 5,6 or 7 byte BINARY field. Depending on the copy file this could generate a different record length and different offsets of fields within the record. SimoREC1 is capable of generating HTML documentation and conversion programs based on either format.

IVP, Generate HTML in IBM Format, Simple Example
(Next) (Previous) (Table-of-Contents)

The first IVP (IvpRec11.CMD) shows the generation of a single HTML document using a very simple COBOL copy file. This command will call Rec1HTML.CMD and pass it three (3) parameters. The HTML document will be created based on the IBM fomat for BINARY, numeric fields.

Refer to the comments (or remarks) in the following command file for additional information.

@echo OFF
     set JobStatus=0000
     setlocal
     if "%SimoLIBR%" == "" set SimoLIBR=c:\SimoLIBR
     set PostNote=%SimoLIBR%\LOGS\SimoTIME.LOG
     set IvpName=IvpRec11
     call :PostNote "************************************************************%IvpName%"
     call :PostNote "Starting JobName %IvpName%"
echo ************************************************************
echo *               This program is provided by:               *
echo *                SimoTime Enterprises, LLC                 *
echo *       (C) Copyright 1987-2008 All Rights Reserved        *
echo *         Web Site URL:   http://www.simotime.com          *
echo *               e-mail:   helpdesk@simotime.com            *
echo ************************************************************
echo * Text:    Scan a Copy file, Create a TEXT and HTML file.
echo * Author:  SimoTime Enterprises
echo * Version: 07.11.01
echo *
call :PostNote "Annotate Show logical and physical field lengths."
call :PostNote "Annotate Show the field positions within the record."
call :PostNote "Annotate This is a very simple HTML Generation."
rem  *
rem  ****************************************************************
rem  * Do the Scan, create the TEXT, DAT/IDX and HTML files...
rem  * Use the IBM format for BINARY or COMP Fields.
rem  *
rem  * The following call to Rec1HTML requires three parameters.
rem  * 1. The fully qualified name for the COBOL copy file for input
rem  * 2. The fully qualified name for the HTML file to be created
rem  * 3. The literal "IBM" or "MF" to determne the size of BINARY
rem  *    fields.
rem  *
     call Rec1HTML %SimoLIBR%\test0001.cpy %SimoLIBR%\HTML\test0001.htm IBM
     if   ERRORLEVEL = 1 set JobStatus=0010
     if not "%JobStatus%" == "0000" goto :EojNok
     goto :EojAok
rem  *
rem  ****************************************************************
rem  * Display the message and write to the log file using ECHO.
rem  * The ~ causes the leading/trailing double-quotes to be removed.
rem  *
:PostNote
     @echo OFF
     echo %date% %time% %~1 >> %PostNote%
     echo * %IvpName% %~1
     goto :EOF
rem  * The preceding :EOF causes a return to caller within this CMD.
rem  *
rem  ****************************************************************
:EojNok
     call :PostNote "ABENDING JobName %IvpName% - Job Status is %JobStatus%"
     goto :End
rem  *
:EojAok
     call :PostNote "Produced %SimoLIBR%\HTML\test0001.htm"
     call :PostNote "Finished JobName %IvpName% - Job Status is %JobStatus%"
     endlocal
:End
     pause

IVP, Generate HTML in Micro Focus Format, Various Numeric Formats
(Next) (Previous) (Table-of-Contents)

This IVP (IvpRec12.CMD) shows the generation of a single HTML document using a COBOL copy file with various numeric formats. This command will call Rec1HTML.CMD and pass it three (3) parameters. The HTML document will be created based on the Micro Focus fomat for BINARY, numeric fields.

Refer to the comments (or remarks) in the following command file for additional information.

@echo OFF
     set JobStatus=0000
     setlocal
     if "%SimoLIBR%" == "" set SimoLIBR=c:\SimoLIBR
     set PostNote=%SimoLIBR%\LOGS\SimoTIME.LOG
     set IvpName=IvpRec12
     call :PostNote "************************************************************%IvpName%"
     call :PostNote "Starting JobName %IvpName%"
echo ************************************************************
echo *               This program is provided by:               *
echo *                SimoTime Enterprises, LLC                 *
echo *       (C) Copyright 1987-2008 All Rights Reserved        *
echo *         Web Site URL:   http://www.simotime.com          *
echo *               e-mail:   helpdesk@simotime.com            *
echo ************************************************************
echo * Text:    Scan a Copy file, Create a TEXT and HTML file
echo *
echo * Version: 07.11.01
call :PostNote "Annotate Shows various numeric formats."
call :PostNote "Annotate This is a moderate HTML Generation."
rem  *
rem  ****************************************************************
rem  * Do the Scan, create the TEXT, DAT/IDX and HTML files...
rem  * Use the Micro Focus (or MF) format for BINARY Fields
rem  *
rem  * The following call to Rec1HTML requires three parameters.
rem  * 1. The fully qualified name for the COBOL copy file for input
rem  * 2. The