SimoREC1
COBOL Copy File Analysis
  Table of Contents  v-14.03.28 - simorec1.htm 
  Introduction
  Program Objectives
  Program Input and Output
  Example, a Simple COBOL Copy File
  Example, a Challenging COBOL Copy File
  Requirements & Installation
  Quick Start
  How to Create HTML Documents for Record Structures
  How to Create a Callable Conversion Routine
  How to Create File I/O Programs
  I/O Program, Ordered or Sequential Load
  I/O Program, Random Add or Update
  Installation Verification Procedure
  Generate HTML in IBM Format, Simple Example
  Generate HTML in Micro Focus Format, Various Numeric Formats
  Generate HTML in IBM Format, Typical Copy File for a Record Structure
  Generate EBCDIC to ASCII Callable Convert Routine
  Generate EBCDIC to ASCII Convert Routine & File I/O Program
  Generate EBCDIC to ASCII Convert Routine, File I/O Program & HTML
  Technical Details
  Create an ASCII/Text File
  Create HTML Documents, System Description
  Create a Callable Data Convert Routine
  A COBOL Copy File used to Create a Callable Convert Routine
  A Generated Callable COBOL Data Convert Routine (Source Code)
  Create a File Convert Package
  The Control/Configuration File
  Integrating with Micro Focus Desktop
  Considerations and Limitations
  Numeric Fields
  Signed-Zoned-Decimal, Numeric Fields
  Packed Numeric Fields
  Functional Limitations
  Frequently Asked Questions
  System Overview
  Summary
  Software Agreement and Disclaimer
  Downloads and Links
  Current Server or Internet Access
  Internet Access Required
  Glossary of Terms
  Comments or Feedback
  Company Overview
The SimoTime Home Page

Table of Contents Previous Section Next Section Introduction

SimoREC1 (a COBOL Record Layout and Content Conversion Utility Program) is currently available as a Controlled Release Option (CRO) and is an add-on to the SimoZAPS Utility program. 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 analyzing 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.


We have made a significant effort to ensure the documents and software technologies are correct and accurate. We reserve the right to make changes without notice at any time. The function delivered in this version is based upon the enhancement requests from a specific group of users. The intent is to provide changes as the need arises and in a timeframe that is dependent upon the availability of resources.

Copyright © 1987-2014
SimoTime Enterprises
All Rights Reserved

Table of Contents Previous Section Next Section Program Objectives

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

1 Show an example of Scanning a COBOL copy file and determining the actual Data Structure.
1.1Show an example of scanning a COBOL copy file and determining the Record Length.
1.2Calculate Field Sizes (based on number of possible digits) and position with a record.
1.3Show the logical size and physical size of packed and binary fields..
1.4For BINARY fields provide a run time option to calculate the physical size based on IBM or Micro Focus.
1.5Generate field sizes for Group items..
1.6Show the REDEFINES field definitions.
2 Create HTML documentation from the COBOL copy file information.
3 Create a COBOL callable routine that converts between EBCDIC and ASCII at the field level.
4 Integrate the COBOL Copy File Analysis Function into Micro Focus Mainframe Express or Net Express as a tool bar item.
  Program Objectives for SimoREC1

Table of Contents Previous Section Next Section Program Input and Output

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

Table of Contents Previous Section Next Section Example, a Simple COBOL Copy File

The following (VKSDREC1.cpy) 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 has a logical field length of nine (9) bytes. However, the use of the COMP-3 will make it a packed field and the physical length will be five (5) bytes. The following HTML document quickly provides this information.

      *****************************************************************
      *               VKSDREC1.CPY - a COBOL Copy File                *
      *  Copy File for the VSAM Data Set used for the Demo programs.  *
      *         Copyright (C) 1987-2014 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(6).
           05  FILLER              PIC X.
           05  VSAM-LAST-NAME      PIC X(15).
           05  VSAM-FIRST-NAME     PIC X(10).
           05  VSAM-STREET-ADDRESS PIC X(24).
           05  VSAM-CITY           PIC X(15).
           05  VSAM-STATE          PIC X(3).
           05  VSAM-POSTAL-CODE    PIC X(6).
      *
      ***  VKSDREC1 - End-of-Copy File - - - - - - - - - - - VKSDREC1 *
      *****************************************************************
      *

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

The physical length for the BINARY or COMP fields is calculated based on the format for an IBM Mainframe

Level Field/Redefines Name
Directive for Binary is IBMCOMP
Field Type Relative
Position
Whole
Numbers
Decimal
Positions
Logical
Size
Physical
Size
Table
Cell Size
Table
Minimum
Table
Maximum
Redefine
Depth
01 VKSD-RECORD Group Item 1 0 0 0 512 0 0 0 0
05 VKSD-KEY Alphameric 1 0 0 12 12 0 0 0 0
05 VKSD-NAME Group Item 13 0 0 0 46 0 0 0 0
10 VKSD-LAST-NAME Alphameric 13 0 0 28 28 0 0 0 0
10 VKSD-FIRST-NAME Alphameric 41 0 0 18 18 0 0 0 0
05 VKSD-ADDRESS-1 Alphameric 59 0 0 48 48 0 0 0 0
05 VKSD-ADDRESS-2 Alphameric 107 0 0 48 48 0 0 0 0
05 VKSD-CITY Alphameric 155 0 0 18 18 0 0 0 0
05 VKSD-STATE Alphameric 173 0 0 18 18 0 0 0 0
05 VKSD-POSTAL-CODE Alphameric 191 0 0 12 12 0 0 0 0
05 VKSD-CREDIT-LIMIT Numeric/Signed
PACKED
203 7 2 9 5 0 0 0 0
05 VKSD-FILLER Alphameric 208 0 0 305 305 0 0 0 0
Level Field/Redefines Name
Directive for Binary is IBMCOMP
Field Type Relative
Position
Whole
Numbers
Decimal
Positions
Logical
Size
Physical
Size
Table
Cell Size
Table
Minimum
Table
Maximum
Redefine
Depth

Table of Contents Previous Section Next Section Example, a Challenging COBOL Copy File

The following (TEST0002.cpy) 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 numeric fields and redefines.    *
      *****************************************************************
      *         Copyright (C) 1987-2014 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       *
      *****************************************************************
      *
      *    *----------------------------------------------------------*
      *    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 simple table.
      *    2. What is the size of a table element or cell?
      *    3. What is the size of the table?
           05  TABLE-A-PIX-X5-O    pic X(5)    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-P-09S-10E.
               10  TABLE-P-09S-O   pic S9(9)       COMP-3
                                   OCCURS 10 TIMES.

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

      *    *----------------------------------------------------------*
      *    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 group item.
      *    2. Create two binary, numeric fields within the group item.
      *    3. What is the length of the group item on the mainframe?
      *    3. What is the length of the group item on the PC?
           05  B-NUMERIC.
               10  B-09-UNSIGN     pic  9(5)   COMP.
               10  B-09-SIGNED     pic  9(5)   BINARY.

      *    *----------------------------------------------------------*
      *    1. Create a filler, alphameric field.
           05  FILLER              pic X(55).
      **   End-of-Copy File -------------------------------- TEST0002 *
      *****************************************************************
      *

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

The physical length for the BINARY or COMP fields is calculated based on the format for an IBM Mainframe

Level Field/Redefines Name
Directive for Binary is IBMCOMP
Field Type Relative
Position
Whole
Numbers
Decimal
Positions
Logical
Size
Physical
Size
Table
Cell Size
Table
Minimum
Table
Maximum
Redefine
Depth
01 KSE00256-REC Group Item 1 0 0 0 512 0 0 0 0
05 KSE00256-KEY-01 Numeric/Unsign 1 6 0 6 6 0 0 0 0
05 X-ALHPAMERIC-FIELDS Group Item 7 0 0 0 40 0 0 0 0
10 X-FIELD-08 Alphameric 7 0 0 8 8 0 0 0 0
10 X-FIELD-32 Alphameric 15 0 0 32 32 0 0 0 0
05 VARIOUS-FORMATS Group Item 47 0 0 0 39 0 0 0 0
10 PIC-XXX Alphameric 47 0 0 3 3 0 0 0 0
10 PIC-999 Numeric/Unsign 50 3 0 3 3 0 0 0 0
10 PIC-99V999 Numeric/Unsign 53 2 3 5 5 0 0 0 0
10 PIC-99V9P3P Numeric/Unsign 58 2 3 5 5 0 0 0 0
10 PIC-9P2PV999 Numeric/Unsign 63 2 3 5 5 0 0 0 0
10 PIC-S999 Numeric/Signed 68 3 0 3 3 0 0 0 0
10 PIC-S99V999 Numeric/Signed 71 2 3 5 5 0 0 0 0
10 PIC-S99V9P3P Numeric/Signed 76 2 3 5 5 0 0 0 0
10 PIC-S9P2PV999 Numeric/Signed 81 2 3 5 5 0 0 0 0
05 N-NUMERIC Group Item 86 0 0 0 18 0 0 0 0
10 N-07-UNSIGN Numeric/Unsign 86 7 2 9 9 0 0 0 0
10 N-07-SIGNED Numeric/Signed 95 7 2 9 9 0 0 0 0
05 P-NUMERIC Group Item 104 0 0 0 10 0 0 0 0
10 P-09-UNSIGN Numeric/Unsign
PACKED
104 7 2 9 5 0 0 0 0
10 P-09-SIGNED Numeric/Signed
PACKED
109 7 2 9 5 0 0 0 0
05 B-NUMERIC Group Item 114 0 0 0 8 0 0 0 0
10 B-09-UNSIGN Numeric/Unsign
BINARY
114 7 2 9 4 0 0 0 0
10 B-09-SIGNED Numeric/Signed
BINARY
118 7 2 9 4 0 0 0 0
05 LN-SIGNED Group Item 122 0 0 0 19 0 0 0 0
10 LN-09-SIGNED Numeric/Signed
SIGN/LEADING
122 7 2 9 9 0 0 0 0
10 LN-09-SIGNED-S Numeric/Signed
SIGN/LEADING
SEPARATE
131 7 2 10 10 0 0 0 0
05 TN-SIGNED Group Item 141 0 0 0 19 0 0 0 0
10 TN-09-SIGNED Numeric/Signed
SIGN/TRAILING
141 7 2 9 9 0 0 0 0
10 TN-09-SIGNED-S Numeric/Signed
SIGN/TRAILING
SEPARATE
150 7 2 10 10 0 0 0 0
05 TABLE-A-PIX-X5-O TABLE
Alphameric
160 0 0 5 50 5 10 0 0
05 TABLE-P-09S-10E Group Item 210 0 0 0 50 0 0 0 0
10 TABLE-P-09S-O TABLE
Numeric/Signed
PACKED
210 9 0 9 50 5 10 0 0
05 TABLE-X-PIC-NO-O TABLE/Element
Group Item
260 0 0 0 81 5 15 0 0
10 TABLE-X-PIC-XX TABLE
Alphameric
260 0 0 2 30 2 15 0 0
10 TABLE-X-PIC-3 TABLE
Alphameric
262 0 0 3 45 3 15 0 0
10 TABLE-X-PIC-3-O TABLE
Alphameric
265 0 0 3 6 3 2 0 0
05 RED-01-PRIME Alphameric 422 0 0 4 4 0 0 0 0
05 RED-01-AGAIN
RED-01-PRIME
Group Item
REDEFINES
422 0 0 0 4 0 0 0 1
10 RED-01-BYTE-01 Alphameric 422 0 0 1 1 0 0 0 1
10 RED-01-BYTE-02 Alphameric 423 0 0 1 1 0 0 0 1
10 RED-01-BYTE-03 Alphameric 424 0 0 1 1 0 0 0 1
10 RED-01-BYTE-04 Alphameric 425 0 0 1 1 0 0 0 1
05 BLUE-01-PRIME Alphameric 426 0 0 4 4 0 0 0 0
05 BLUE-01-SHORT
BLUE-01-PRIME
Group Item
REDEFINES
Size Variation
426 0 0 0 2 0 0 0 1
10 BLUE-01-BYTE-01 Alphameric 426 0 0 1 1 0 0 0 1
10 BLUE-01-BYTE-02 Alphameric 427 0 0 1 1 0 0 0 1
05 FOUR-BYTES-PRIME Alphameric 430 0 0 4 4 0 0 0 0
05 FOUR-BYTES-VALUE
FOUR-BYTES-PRIME
Numeric/Unsign
REDEFINES
430 4 0 4 4 0 0 0 1
05 SIX-BYTES-PRIME Alphameric 434 0 0 6 6 0 0 0 0
05 SIX-BYTES-SHORT
SIX-BYTES-PRIME
Numeric/Unsign
REDEFINES
Size Variation
434 4 0 4 4 0 0 0 1
05 NINE-PRIME Alphameric 440 0 0 9 9 0 0 0 0
05 NINE-AGAIN
NINE-PRIME
Group Item
REDEFINES
Size Variation
440 0 0 0 3 0 0 0 1
10 NINE-AGAIN-05 Numeric/Unsign
PACKED
440 5 0 5 3 0 0 0 1
10 NINE-AGAIN-05-R
NINE-AGAIN-05
Alphameric
REDEFINES
440 0 0 3 3 0 0 0 2
05 ONE-BYTE Alphameric 440 0 0 1 1 0 0 0 1
05 B-NUMERIC Group Item 449 0 0 0 8 0 0 0 0
10 B-09-UNSIGN Numeric/Unsign
BINARY
449 5 0 5 4 0 0 0 0
10 B-09-SIGNED Numeric/Unsign
BINARY
453 5 0 5 4 0 0 0 0
05 FILLER Alphameric 458 0 0 55 55 0 0 0 0
Level Field/Redefines Name
Directive for Binary is IBMCOMP
Field Type Relative
Position
Whole
Numbers
Decimal
Positions
Logical
Size
Physical
Size
Table
Cell Size
Table
Minimum
Table
Maximum
Redefine
Depth

Table of Contents Previous Section Next Section Requirements & Installation

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.

1 Executes on Windows/NT, Windows/XP and Windows/7 using Micro Focus Net Express and the CMD files provided.
2 This example will also run with Micro Focus Mainframe Express
3 The Copy File Analysis Function that creates HTML documentation may be integrated into Net Express or Mainframe Express as a tool bar item using the REC1MFO1.CMD file. Refer to the Integrating with Micro Focus COBOL Desktop Environments section of this document for more information.
4 The Copy File Analysis Function that creates HTML documentation may be executed from a Windows command line using the REC1HTML.CMD file. Refer to the Create HTML Documentation section of this document for more information.
5 The Copy File Analysis Function that creates a callable COBOL source member for conversion between EBCDIC and ASCII may be executed from a Windows command line using the REC1CALL.CMD file. Refer to the Create a Callable COBOL Conversion Routine section of this document for more information.
  Requirements and Installation, SimoREC1 Record Layout and Content Conversion Program

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.

Table of Contents Previous Section Next Section Quick Start

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" information for the following four items.

1 Read the COBOL copy file that defines the record layout and create an HTML document.
2 Create the COBOL source code for a callable routine that will do the conversion between EBCDIC and ESCII based in the record layout information provided in the COBOL copy file.
3 Create the COBOL source code for a program that will do file I/O to read a file and write a new file based on the specifications provided in a control file. This I/O program will call the routine to convert the record contents between EBCDIC and ESCII.
The I/O program will read and write the files sequentially. If the output file is a keyed indexed file the input file must be in sequence by the key field.
4 Create the COBOL source code for a program that will do file I/O to read a file and write a new file based on the specifications provided in a control file. This I/O program will call the routine to convert the record contents between EBCDIC and ESCII.
The I/O program will read the input file sequentially and write or rewrite to the output file randomly. If the output file is a keyed indexed file the sequence of the records within the input file do not need to be in sequence by the key field. This approach is slower than the process described in item 3 but will add new records to the output file without dependencies on the sequencing. If a record is read from the input file that has the same key as an existing record in the output file the record in the output file will be updated with the new information.
  Getting Started Quickly

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

Table of Contents Previous Section Next Section How to Create HTML Documents for Record Structures

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

C:\> REC1HTML copyfilename.CPY HTMLname.HTM IBM or MF

Parameter Description
1st - copyfilename The 1st parameter copyfilename must be the name of a COBOL copy file.
2nd - HTMLNAME The 2nd parameter HTMLname must be the name of the HTML document to be created.
3rd - IBM or MF The 3rd parameter IBM or MF must be "IBM" or "MF".
Note 1: 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).
Note 2: 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).
  Create HTML Documentation for Record Structures using COBOL Copy Files

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

Table of Contents Previous Section Next Section How to Create a Callable Conversion Routine

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

C:\> REC1CALL copyfilename.CPY routinename.CBL

Parameter Description
1st - copyfilename The 1st parameter copyfilename must be the name of a COBOL copy file.
2nd - routineNAME The 2nd parameter routinename must be the name of the callable COBOL routine to be created.
  Create a Callable Conversion Routine using COBOL Copy Files

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

Table of Contents Previous Section Next Section How to Create File I/O Programs

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

Table of Contents Previous Section Next Section I/O Program, Ordered or Sequential Load

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.

C:\> ZAPSREC1 controlfilename.TXT programname.CBL

Parameter Description
1st - controlfilename The 1st parameter controlfilename must be the name of a control file with a minimum amount of file definition specifications.
2nd - programname The 2nd parameter programname must be the name of the callable COBOL program to be created.
  Create a File I/O program using Sequential Processing (Ordered Load)

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

Table of Contents Previous Section Next Section I/O Program, Random Add or Update

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.

C:\> ZAPSREC2 controlfilename.TXT programname.CBL

Parameter Description
1st - controlfilename The 1st parameter controlfilename must be the name of a control file with a minimum amount of file definition specifications.
2nd - programname The 2nd parameter programname must be the name of the callable COBOL program to be created.
  Create a File I/O program using Sequential Processing (Ordered Load)

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

/Dialect   C2
/progid    ITKEKAC2
/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

Table of Contents Previous Section Next Section Installation Verification Procedure

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

Table of Contents Previous Section Next Section Generate HTML in IBM Format, Simple Example

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 format 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 *           IVPREC11.cmd - a Windows Command File          *
echo *     This program is provided by SimoTime Enterprises     *
echo *       (C) Copyright 1987-2014 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" will use IBM rules for BINARY fields sizes.
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

Table of Contents Previous Section Next Section Generate HTML in Micro Focus Format, Various Numeric Formats

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 format 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 *           IVPREC12.CMD - a Windows Command File          *
echo *     This program is provided by SimoTime Enterprises     *
echo *       (C) Copyright 1987-2014 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 fully qualified name for the HTML file to be created
rem  * 3. The literal "MF" will use Micro Focus rules for BINARY
rem  *    fields sizes.
rem  *
     call Rec1HTML %SimoLIBR%\test0002.cpy %SimoLIBR%\HTML\test0002.htm MF
     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\test0002.htm"
     call :PostNote "Finished JobName %IvpName% - Job Status is %JobStatus%"
     endlocal
:End
     pause

Table of Contents Previous Section Next Section Generate HTML in IBM Format, Typical Copy File for a Record Structure

This IVP (IVPREC13.cmd) shows the generation of a single HTML document using a typically structure COBOL copy file for a record layout. This command will call Rec1HTML.CMD and pass it three (3) parameters. The HTML document will be created based on the IBM format 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=IvpRec13
     call :PostNote "************************************************************%IvpName%"
     call :PostNote "Starting JobName %IvpName%"
echo ************************************************************
echo *           IVPREC13.CMD - a Windows Command File          *
echo *     This program is provided by SimoTime Enterprises     *
echo *       (C) Copyright 1987-2013 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 *          Show logical and physical field lengths and
echo *          the field position within the record layout.
echo * Author:  SimoTime Enterprises
echo * Version: 07.11.01
call :PostNote "Annotate Shows a typical copy file."
call :PostNote "Annotate This is an easy HTML Generation."
rem  *
rem  ****************************************************************
rem  * Do the Scan, create the TEXT, DAT/IDX and HTML files...
rem  * Use the IBM Format (i.e. 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" will use IBM rules for BINARY fields sizes.
rem  *
     call Rec1HTML %SimoLIBR%\test0003.cpy %SimoLIBR%\HTML\test0003.htm IBM
     if   ERRORLEVEL = 1 set JobStatus=0020
     if not "%JobStatus%" == "0000" goto :EojNok
     echo IvpRec13 Notice the different record lengths.
     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\test0003.htm"
     call :PostNote "Finished JobName %IvpName% - Job Status is %JobStatus%"
     endlocal
:End
     pause

Table of Contents Previous Section Next Section Generate EBCDIC to ASCII Callable Convert Routine

This IVP (IVPREC14.cmd) shows the generation of the COBOL source code for a callable program that will do an EBCDIC to ASCII conversion at the field level based on a COBOL copy file that defines the record layout. This command will call Rec1CALL.CMD and pass it three (3) parameters. The third parameter determines the type of conversion.

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=IvpRec14
     call :PostNote "************************************************************%IvpName%"
     call :PostNote "Starting JobName %IvpName%"
echo ************************************************************
echo *           IVPREC14.CMD - a Windows Command File          *
echo *     This program is provided by SimoTime Enterprises     *
echo *       (C) Copyright 1987-2014 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 COBOL Source code,
echo *          EBCDIC to ASCII conversion example.
echo * Author:  SimoTime Enterprises
echo * Version: 07.11.01
echo *
call :PostNote "Annotate Show field level data conversion,"
call :PostNote "Annotate EBCDIC to ASCII encoding"
call :PostNote "Annotate This is an easy Generation of COBOL code."
rem  *
rem  ****************************************************************
rem  * Do the Scan, create the TEXT, DAT/IDX and HTML files...
rem  *
rem  * The following call to Rec1CALL requires three parameters.
rem  * 1. The fully qualified name for the COBOL copy file that
rem  *    defines the record layout.
rem  * 2. The fully qualified name for the callable COBOL conversion program
rem  *    to be created.
rem  * 3. The literal "E2A" will generate code for EBCDIC to ASCII.
rem  *
     call REC1CALL %SimoLIBR%\ITEMCB01.CPY %SimoLIBR%\DataWrk1\ITME2AR1.CBL E2A
     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%"
     pause
     goto :End
rem  *
:EojAOK
     call :PostNote "Finished JobName %IvpName% - Job Status is %JobStatus%"
     pause
:End
     endlocal

Table of Contents Previous Section Next Section Generate EBCDIC to ASCII Convert Routine & File I/O Program

This IVP (IVPREC15.cmd) is a two step job that does the following.

Step Description
Step-01 Call Rec1CALL.CMD to create the COBOL source code for a callable COBOL conversion program. Three parameters are required.
1. The fully qualified name for the COBOL copy file that defines the record layout.
2. The fully qualified name for the callable COBOL conversion program to be created.
3. The literal "E2A" determines the type of conversion (EBCDIC to ASCII).
Step-02 Call ZapsREC1.CMD to create the COBOL source code for the mainline program that does the file I/IO. Two parameters are required.
1. The fully qualified name for the specifications file for input.
2. The fully qualified name for the COBOL I/O program to be created.
  Generate EBCDIC to ASCII Conversion Routine and File I/O Program

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

@echo OFF
     setlocal
     if "%SimoLIBR%" == "" set SimoLIBR=c:\SimoLIBR
     set PostNote=c:\SimoLIBR\LOGS\SimoTime.LOG
     set JobStatus=0000
     set ShowCode=SHOW
rem  *
     set IvpName=IvpRec15genr
     set SYSOUT=%SimoLIBR%\LOGS\SYSOUT_IvpRec15genr.txt
     call :PostNote "************************************************************%IvpName%"
     call :PostNote "Starting JobName %IvpName%"
echo ************************************************************
echo *        IVPREC15GENR.CMD - a Windows Command File         *
echo *     This program is provided by SimoTime Enterprises     *
echo *       (C) Copyright 1987-2013 All Rights Reserved        *
echo *         Web Site URL:   http://www.simotime.com          *
echo *               e-mail:   helpdesk@simotime.com            *
echo ************************************************************
echo * Text:   Scan a Copy file,
echo *         Step01, Create a callable COBOL conversion routine
echo *         Step02, Create a COBOL File I/O program.
echo * Author: SimoTime Enterprises
echo *
rem  *
:Step01
     call :PostNote "************************************************************"
     call :PostNote "* This procedure requires that SimoREC1 and SimoZAPS be    *"
     call :PostNote "* installed. The following step will create the callable   *"
     call :PostNote "* COBOL routine that does the data conversion.             *"
rem  *
rem  * The following call to Rec1CALL requires three parameters.
rem  * 1. The fully qualified name for the COBOL copy file that
rem  *    defines the record layout.
rem  * 2. The fully qualified name for the callable COBOL conversion program
rem  *    to be created.
rem  * 3. The literal "E2A" will generate code for EBCDIC to ASCII.
rem  *
     call Rec1CALL %SimoLIBR%\ITEMCB01.CPY %SimoLIBR%\DataWrk1\ITME2AR1.CBL E2A
     if ERRORLEVEL = 1 goto :EojNOK
rem  *
:Step02
     call :PostNote "************************************************************"
     call :PostNote "* This step will create the COBOL program that will read   *"
     call :PostNote "* an EBCDIC encoded,Keyed-Sequential-Data-Set and write an *"
     call :PostNote "* ASCII encoded Keyed-Sequential-Data-Set.                 *"
rem  *
rem  * The following call to ZapsREC1 requires two parameters.
rem  * 1. The fully qualified name for the specifications file for input
rem  * 2. The fully qualified name for the COBOL I/O program to be created
rem  *
     call ZapsREC1 %SimoLIBR%\IvpRec15spec.txt %SimoLIBR%\DataWrk1\ItKeKaC1.CBL
     if ERRORLEVEL = 1 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 %~1
     goto :EOF
rem  * The preceding :EOF causes a return to caller within this CMD.
rem  *
rem  *********************************************************************
:EojNOK
     call :PostNote "ABENDING JobName %IvpName%, User is %USERNAME%"
     pause
rem  *
rem  *********************************************************************
:EojAOK
     call :PostNote "Finished JobName %IvpName%, User is %USERNAME%"
     echo * Thank you for using the GENERATE function by SimoTime Enterprises
     pause
rem  *
:End

Table of Contents Previous Section Next Section Generate EBCDIC to ASCII Convert Routine, File I/O Program & HTML

This IVP (IVPREC16.cmd) is a three step job that does the following.

Step Description
Step-01 Call Rec1CALL.CMD to create the COBOL source code for a callable COBOL conversion program. Three parameters are required.
1. The fully qualified name for the COBOL copy file that defines the record layout.
2. The fully qualified name for the callable COBOL conversion program to be created.
3. The literal "E2A" determines the type of conversion (EBCDIC to ASCII).
Step-02 Call ZapsREC1.CMD to create the COBOL source code for the mainline program that does the file I/IO. Two parameters are required.
1. The fully qualified name for the specifications file for input.
2. The fully qualified name for the COBOL I/O program to be created.
Step-03 Call Rec1HTML.CMD to create the HTML document for the Record layout. Three parameters are required.
1. The fully qualified name for the COBOL copy file that defines the record layout.
2. The fully qualified name for the HTML file to be created.
3. The literal "IBM" will use IBM Mainframe rules for BINARY fields sizes.
  Generate EBCDIC to ASCII Conversion Routine and File I/O Program

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

@echo OFF
     setlocal
     if "%SimoLIBR%" == "" set SimoLIBR=c:\SimoLIBR
     set PostNote=%SimoLIBR%\LOGS\SimoTime.LOG
     set JobStatus=0000
     set ShowCode=SHOW
rem  *
     set IvpName=IvpRec16genr
     set SYSOUT=%SimoLIBR%\LOGS\SYSOUT_IvpRec16genr.txt
     call :PostNote "************************************************************%IvpName%"
     call :PostNote "Starting JobName %IvpName%"
echo ************************************************************
echo *        IVPREC16GENR.CMD - a Windows Command File         *
echo *     This program is provided by SimoTime Enterprises     *
echo *       (C) Copyright 1987-2014 All Rights Reserved        *
echo *         Web Site URL:   http://www.simotime.com          *
echo *               e-mail:   helpdesk@simotime.com            *
echo ************************************************************
echo * Text: Scan a Copy file,
echo *       Step01, Create the COBOL source code for a
echo *               callable COBOL conversion program.
echo *       Step02, Create the COBOL source code for a
echo *               program that does the File I/O processing.
echo *       Step03, Create the HTML document for the Record
echo *               layout.
echo *
:Step01
     call :PostNote "************************************************************"
     call :PostNote "* This procedure requires that SimoREC1 and SimoZAPS be    *"
     call :PostNote "* installed. The following step will create the callable   *"
     call :PostNote "* COBOL routine that does the data conversion.             *"
rem  *
rem  * The following call to Rec1CALL requires three parameters.
rem  * 1. The fully qualified name for the COBOL copy file that
rem  *    defines the record layout.
rem  * 2. The fully qualified name for the callable COBOL conversion program
rem  *    to be created.
rem  * 3. The literal "E2A" will generate code for EBCDIC to ASCII.
rem  *
     call Rec1CALL %SimoLIBR%\CUSTCB01.CPY %SimoLIBR%\DataWrk1\CUSE2AR1.CBL E2A
     if   ERRORLEVEL = 1 set JobStatus=0010
     if not "%JobStatus%" == "0000" goto :EojNok
rem  *
:Step02
     call :PostNote "************************************************************"
     call :PostNote "* This step will create the COBOL program that will read   *"
     call :PostNote "* an EBCDIC encoded,Keyed-Sequential-Data-Set and write an *"
     call :PostNote "* ASCII encoded Keyed-Sequential-Data-Set.                 *"
rem  *
rem  * The following call to ZapsREC1 requires two parameters.
rem  * 1. The fully qualified name for the specifications file for input
rem  * 2. The fully qualified name for the COBOL I/O program to be created
rem  *
     call ZapsREC1 %SimoLIBR%\IvpRec16spec.txt %SimoLIBR%\DataWrk1\CuKeKaC1.CBL
     if   ERRORLEVEL = 1 set JobStatus=0020
     if not "%JobStatus%" == "0000" goto :EojNok
rem  *
:Step03
     call :PostNote "************************************************************"
     call :PostNote "* Do the Scan, create the TEXT, DAT/IDX and HTML files...  *"
     call :PostNote "* Use the IBM Format (i.e. 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" will use IBM rules for BINARY fields sizes.
rem  *
     call Rec1HTML %SimoLIBR%\CUSTCB01.cpy %SimoLIBR%\HTML\CUSTCB01.htm IBM
     if   ERRORLEVEL = 1 set JobStatus=0030
     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 %~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%"
     call :PostNote "ABENDING JobName %IvpName%, User is %USERNAME%"
     pause
rem  *
rem  *********************************************************************
:EojAOK
     call :PostNote "Finished JobName %IvpName%, User is %USERNAME%"
     echo * Thank you for using the GENERATE function by SimoTime Enterprises
     pause
rem  *
:End

Table of Contents Previous Section Next Section Technical Details

This section provides a technical description of the details of the functions provided by the SimoREC1 utility program.

Table of Contents Previous Section Next Section Create an ASCII/Text File

The first step in the copy file analysis is to scan and parse the copy file and create an ASCII.TXT file with a column-oriented format with fixed field and fixed record length. The subsequent steps will use the ASCII.TXT file to create the various outputs. The ASCII.TXT file is used as a temporary work file and is usually name REC1TXT1.TXT. This file may be saved by mapping to another name, renaming or copying with another name. Processing the ASCII.TXT file may be much easier to process than trying to parse a COBOL copy file outside the scope of the SimoREC1 Record Layout and Content Conversion Utility Program. A COBOL copyfile is provided to define the structure of this ASCII.TXT file.

Table of Contents Previous Section Next Section Create HTML Documents, System Description

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

  C:\> REC1HTML copyfilename.CPY HTMLname.HTM IBM or MF 

The following is the source code for the command file (Rec1HTML.CMD) that will run the SimoTime Record Layout Utility Program to read a copy file and create an HTML document.

@echo OFF
     set JobStatus=0000
     set UtlName=Rec1HTML
     if "%SimoLIBR%" == "" set SimoLIBR=c:\SimoLIBR
     if "%SimoNOTE%" == "" set SimoNOTE=%SimoLIBR%\LOGS\SimoTIME.LOG
rem  * *******************************************************************
rem  *               REC1HTML.CMD - a Windows Command File               *
rem  *         This program is provided by SimoTime Enterprises          *
rem  *           (C) Copyright 1987-2013 All Rights Reserved             *
rem  *             Web Site URL:   http://www.simotime.com               *
rem  *                   e-mail:   helpdesk@simotime.com                 *
rem  * *******************************************************************
     echo * Text:    Scan a Copy file, Create a TEXT and HTML file
     echo *          Show logical and physical field lengths and
     echo *          the field position within the record layout.
     echo * Author:  SimoTime Enterprises
     echo * Version: 05.06.07
     call SimoNote "Starting JobName %UtlName%, v08.04.13, User is %USERNAME%"
rem  *
     echo * Parameter-1, Name of the Copy File
     echo * Parameter-2, Name of the HTML File to be created.
     echo * Parameter-3, IBM or MF format for BINARY numbers
     if "%1" == "" set JobStatus=0001
     if not "%JobStatus%" == "0000" goto :EojNok
     if "%2" == "" set JobStatus=0002
     if not "%JobStatus%" == "0000" goto :EojNok
     if "%3" == "" set JobStatus=0003
     if not "%JobStatus%" == "0000" goto :EojNok
     set REC1COPY=%1
     set Rec1HTML=%2
     set REC1TXT1=%SimoLIBR%\DataWrk1\REC1Txt1.txt
     set REC1IDX1=%SimoLIBR%\DataWrk1\REC1Idx1.dat
     set HTMHDRD1=%SimoLIBR%\rec1hdr1.htm
     set HTMFTRD1=%SimoLIBR%\rec1ftr1.htm
     call SimoNOTE "1, Copy File is %REC1COPY%"
     call SimoNOTE "2, HTML File is %Rec1HTML%"
     call SimoNOTE "3, %3 format for BINARY numbers"
rem  *
rem  ****************************************************************
rem  * Do the Scan, create the TEXT, DAT/IDX and HTML files...
rem  *
     run SIMOREC1 %3 HTML
     if   ERRORLEVEL = 1 set JobStatus=0010
     if not "%JobStatus%" == "0000" goto :EojNok
     if "%SimoGENS%" == "BATCH" goto :End
     echo Rec1Htm1 HTML document displayed in separate window using Internet Explorer.
     START "c:\Program Files\Internet Explorer\iexplore.exe" %Rec1HTML%
     goto :End
rem  *
rem  ****************************************************************
:EojNok
     if  %JobStatus% == 0001 call SimoNOTE "ABENDING JobName Rec1Htm1 - Parm-1 must be name of COBOL copyfile"
     if  %JobStatus% == 0002 call SimoNOTE "ABENDING JobName Rec1Htm1 - Parm-2 must be name of HTML member for output"
     if  %JobStatus% == 0003 call SimoNOTE "ABENDING JobName Rec1Htm1 - Parm-3 must be IBM or MF"
     call SimoNOTE "ABENDING JobName %UtlName% - Job Status is %JobStatus%"
rem  *
:End
     call SimoNOTE "Finished JobName %UtlName% - Job Status is %JobStatus%"
     exit /B %JobStatus%

Table of Contents Previous Section Next Section Create a Callable Data Convert Routine

SimoREC1 does not actually do data conversion. SimoREC1 generates a callable COBOL program (or routine) that will do the data conversion at the field level between ASCII and EBCDIC. This provides the advantages of using a utility to do the conversion without the considerations or limits of a utility program. The SimoREC1 utility itself runs on a windows platform but the generated COBOL conversion code may be compiled and will run on an IBM mainframe (MVS, z/OS or VSE), a Windows platform or the various UNIX platforms supported by Micro Focus COBOL. Also, if special or unique conversion processing is required it may be added to the generated COBOL source code.

SimoREC1 generates the callable COBOL program by analyzing the COBOL copy file that defines the record layout. The copy file is required to have one 01 level group definition with a valid field name. If an 01 level does not exist then one will be created with the predefined field name of SIMOREC1-FORCE-01.

If multiple record types are defined with multiple 01 group levels then the copy file will need to be split apart by each 01 group level. A callable COBOL program should then be generated for each of the 01 group levels or multiple record types.

When used in conjunction with the SimoZAPS utility program a complete suite of conversion programs may be generated. The SimoZAPS program has the capability of generating the COBOL source code to read one file format, make a call to a conversion routine and create a file of another format.

The following command may be used to generate the callable conversion routine.

  C:\> REC1CALL copyfilename.CPY routinename.CBL parameters 

When using REC1CALL (SimoZAPS in conjunction with SimoREC1) the usual SimoZAPS parameters are not used since SimoZAPS only creates the I/O program that will call the conversion routine. The following parameters are used with the REC1CALL procedure.

PARAMETER Description
E2A or A2E Defines the direction of conversion. E2A defines an EBCDIC to ASCII conversion. A2E defines an ASCII to EBCDIC conversion.
IBM or MF Used to define what to do with BINARY or COMPUTATIONAL numbers. IBM will handle binary fields as 2, 4 or 8 byte fields. MF will handle binary fields using actual lengths based on the picture clause.
NOREDEFINES Reserved for future use.
CPYNFILE CPYNFILE(filename) where filename is an eight (8) byte name of the copy file that defines the table to be used for converting signed, zoned, decimal numbers.
CPYXFILE CPYXFILE(filename) where filename is an eight (8) byte name of the copy file that defines the table to be used for converting text fields.
  Parameters for the REC1CALL Command

The following two sections describe the Installation Verification Procedure or IVP (IVPREC14.CMD) that uses the Rec1CALL.CMD process.

Table of Contents Previous Section Next Section A COBOL Copy File used to Create a Callable Convert Routine

The following is an example of a copy file that is used by the Installation Verification Procedure (IVPREC14.CMD) to create a callable COBOL routine that will do EBCDIC to ASCII conversion at the field level.

      *****************************************************************
      *               ITEMCB01.CPY - a COBOL Copy File                *
      *        An Item Master File used by the Demo programs.         *
      * This is a VSAM Keyed-Sequential-Data-Set or Key-Indexed File. *
      *         Copyright (C) 1987-2014 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  ITEM-RECORD.
           05  ITEM-NUMBER              PIC 9(12).                      COL-A
           05  ITEM-DATA.
               10  ITEM-DESCRIPTION     PIC X(48).                      COL-B
               10  ITEM-QTY-ONHAND      PIC 9(7)            COMP.       COL-C
               10  ITEM-QTY-ALLOCATED   PIC 9(7)            COMP.       COL-D
               10  ITEM-UNIT-OF-MEASURE PIC X(16).                      COL-E
               10  ITEM-COST            PIC S9(7)V9(2)      COMP-3.     COL-F
               10  ITEM-PRICE           PIC S9(7)V9(2)      COMP-3.     COL-G
               10  ITEM-LADATE          PIC X(8).                       COL-H
               10  ITEM-LATIME          PIC X(8).                       COL-I
               10  ITEM-TOKEN           PIC X(3).
               10  ITEM-DISCOUNT        OCCURS 3 TIMES.
                   15  ITEM-D-CODE      PIC X.
                   15  ITEM-D-PERCENT   PIC S9(3)V9(4).
               10  FILLER               PIC X(375).
      *
      ***  ITEMCB01 - End-of-Copy File - - - - - - - - - - - ITEMCB01 *
      *****************************************************************
      *

Table of Contents Previous Section Next Section A Generated Callable COBOL Data Convert Routine (Source Code)

The following is the COBOL source code for the callable routine that is created as a result of running the Installation Verification Procedure (IVPREC14.CMD).

       IDENTIFICATION DIVISION.
       PROGRAM-ID.    ITME2AR1.
       AUTHOR.        SIMOTIME ENTERPRISES.
      *****************************************************************
      *           This routine was generated by SimoREC1              *
      *             A product of SimoTime Enterprises                 *
      *        Our e-mail address is: helpdesk@simotime.com           *
      *     Also, visit our Web Site at http://www.simotime.com       *
      *  Generation Date: 2007/07/27  Generation Time: 09:41:28:37    *
      *****************************************************************
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  IX-1  PIC 9(5) VALUE 0.
       01  RM-1  PIC 9(5) VALUE 0.
       01  RO-1  PIC 9(5) VALUE 0.
       01  IX-2  PIC 9(5) VALUE 0.
       01  RM-2  PIC 9(5) VALUE 0.
       01  RO-2  PIC 9(5) VALUE 0.

       COPY ASCEBCB1.
       COPY ASCEBCB2.

      *****************************************************************
       LINKAGE SECTION.
       COPY ITEMCB01.

      *****************************************************************
       PROCEDURE DIVISION using ITEM-RECORD.
           inspect ITEM-NUMBER              converting E-INFO to A-INFO
           inspect ITEM-DESCRIPTION         converting E-INFO to A-INFO
      *    Binary  ITEM-QTY-ONHAND
      *    Binary  ITEM-QTY-ALLOCATED
           inspect ITEM-UNIT-OF-MEASURE     converting E-INFO to A-INFO
      *    Packed  ITEM-COST
      *    Packed  ITEM-PRICE
           inspect ITEM-LADATE              converting E-INFO to A-INFO
           inspect ITEM-LATIME              converting E-INFO to A-INFO
           inspect ITEM-TOKEN               converting E-INFO to A-INFO
      *    Group10 ITEM-DISCOUNT                     occurs 00003 times
      *    Group  00008
      *    Table   ITEM-D-CODE
           perform varying IX-1 from 1 by 1 until IX-1 > 00003
             inspect ITEM-D-CODE(IX-1)      converting E-INFO to A-INFO
           end-perform
      *    Table   ITEM-D-PERCENT
           add 0000115 to ZERO giving RM-1
           add 0000008 to ZERO giving RO-1
           perform 00003 times
             inspect ITEM-RECORD(RM-1:00007)
                                            converting E-NUMB to A-NUMB
             add RO-1 to RM-1
           end-perform
      *    Group10                                          End-Group10
      *    Filler  A Non-Unique Reference to a Data Item
           inspect ITEM-RECORD(138:375)     converting E-INFO to A-INFO
           GOBACK.

Table of Contents Previous Section Next Section Create a File Convert Package

To create a complete conversion package requires the use of two SimoTime utility programs. The SimoREC1 utility will create the COBOL source code for a callable routine that does the actual data conversion. The SimoZAPS utility will generate the COBOL source code that does the file I/O to read an input file, call the callable routine to do the conversion and write the converted records to an output file.

The Installation Verification Procedure (IVPREC15.CMD) will create the two COBOL source members required to convert an EBCDIC encoded Keyed-Indexed file to an ASCII encoded Keyed-Indexed file. The following description of the IVP assumes the SimoZAPS and SimoREC1 utility programs have been installed in the C:\SimoLIBR directory.

The following flowchart is a quick overview of the process for generating the COBOL source code to do the file I/O with possible file format and record content conversion.

                 
IVPREC15
CMD
   
   
The command for running the program to generate COBOL source code.
   
   
   
 
 
 
 
   
   
   
   
Rec1CALL
CMD
The command to generate the COBOL callable conversion routine.
   
   
   
   
   
Rec1COPY
TXT
 
 
SimoREC1
UTL
   
   
ITME2AR1
CBL
   
   
   
   
   
   
   
REC1Txt1
TXT
   
   
   
   
   
   
   
REC1Idx1
DAT
   
   
   
 
 
 
 
   
   
   
ZAPSREC1
CMD
The command to generate the COBOL program for File I/O.
   
   
   
ITKEKAT1
TXT
   
   
SimoZAPS
UTL
 
 
ITKEKAC1
CBL
   
   
   
SYSMASK3
TXT
   
   
End-of-Job
EOJ
This is End-of-Job
 
Generating COBOL source code for the file I/O with possible file format and record content conversion

The command file (IVPREC15.CMD) is provided as part of the Installation Verification Process (IVP). This IVP command file creates the two COBOL source members that will do the File I/O and data conversion between EBCDIC and ASCII. The IVP command file will call Rec1CALL.CMD to create the callable COBOL routine that will do the data conversion.

After creating the callable conversion routine the IVP command file will call ZAPSREC1.CMD to generate the COBOL file I/O source member that will call the conversion routine.

Table of Contents Previous Section Next Section The Control/Configuration File

The Control/Configuration file (SIMOCFG1.TXT) contains records with keywords and text strings that are used to control the behavior of the SimoREC1 programs. The following statement (or record) in the Control file would cause the SimoREC1 program to generate code that would test a packed numeric field for all SPACE values and convert the SPACE values to a SPACE value of the specified encoding scheme. For example if the conversion is from EBCDIC to ASCII then all x'40' values will be converted to all x'20' values.

/PACKEDFLD SPACECONVERT

The following would initialize a packed field that contained SPACE values to all ZEROES. For example, a five digit packed field would be changed to a three byte x'00000F' value.

/PACKEDFLD SPACEZERO

The default Control file used by the REC1CALL.CMD is c:\SimoLIBR\SIMOCFG1.TXT. This may be overridden by setting an environment variable prior to calling REC1CALL.CMD. The following is an example.

SET SIMOCFG1=C:\MyDir\MyCfg.TXT

Note: It is not a good practice to have non-numeric values in a numeric field. The reason the packed field contains spaces should be corrected.

Refer to the Considerations and Limitations, Packed Numeric Fields section of this document for more information.

Table of Contents Previous Section Next Section Integrating with Micro Focus Desktop

From the MFE toolbar select "Options", then select "Customize IDE" from the drop-down list of items. When the "Customize IDE" window is displayed select the "Tools" tab and then click on the "New Tool" button. The following would pass the arguments as parameters to the command file (Rec1Mfo1.CMD).

  Current user-modifiable tools:  
 
Record Layout!IBM Format
-- end --
 
     
 
Command: c:\SimoLIBR\Rec1Mfo1.cmd
Arguments: $(FileSel) $Base(FileSel) HTML IBM nopause
Start in: c:\SimoLIBR
 
     

Once the preceding information is entered the "Record Layout" function may then be selected from the Micro Focus Desktop "Tools" item.

Note: The information about the user tools is stored in the Windows registry. To copy this information to another machine requires the use of REGEDIT to do an EXPORT and IMPORT. The information is stored in the Windows registry at the following location

[HKEY_CURRENT_USER\Software\Micro Focus\Mainframe Express\3.0\MFIDE\Tools]

From a DOS command line enter the following.

c:\>regedit

When the "Registry Editor" window is displayed select the "HKEY_CURRENT_USER" then select "Software" then select "Mainframe Express" then select "3.0" then select "MFIDE" then select "Tools".

With the "Tools" item highlighted select "Registry" from the toolbar at the top of the "Registry Editor" window and from the drop-down list select "Export Registry File". At this point follow the prompts to select a directory and file name to save the exported registry entry information for the user defined tools to be used with MFE.

The following command file (Rec1Mfo1.CMD) will run the SimoTime Record Layout Utility Program (SimoREC1). SimoREC1 will run the copy file analysis and calculate the logical and physical size of the fields based on the IBM Mainframe format. An HTML document will also be created and displayed using the browser.

@echo OFF
rem  * *******************************************************************
rem  *               REC1MFO1.CMD - a Windows Command File               *
rem  *         This program is provided by SimoTime Enterprises          *
rem  *           (C) Copyright 1987-2013 All Rights Reserved             *
rem  *             Web Site URL:   http://www.simotime.com               *
rem  *                   e-mail:   helpdesk@simotime.com                 *
rem  * *******************************************************************
rem  *
rem  * Text    - Record Layout Utility Program
rem  * Author  - SimoTime Enterprises
rem  *
rem  * The SimoTime Record Layout Utility Program will read a COBOL
rem  * copy file and create an ASCII/Text file and an HTML document
rem  * that contains the logical length (i.e. number of digits) and
rem  * the physical length (i.e. packed and binary fields) of each field
rem  * within a record. The position of the field within a record is
rem  * calculated along with the length of the record.
rem  *********************************************************************
rem  *
     setlocal
     if "%SimoLIBR%" == "" set SimoLIBR=c:\SimoLIBR
     if "%PostNote%" == "" set PostNote=%SimoLIBR%\LOGS\SimoTIME.LOG
     set JobStatus=0000
rem  *
     call :PostNote "************************************************************Rec1Mfo1"
     call :PostNote "Starting JobName Rec1Mfo1, v07.10.14, User is %USERNAME%"
     set REC1COPY=%1
     set REC1HTML=%SimoLIBR%\HTML\%2.htm
     set HTMHDRD1=%SimoLIBR%\htmhdrh1.htm
     set HTMFTRD1=%SimoLIBR%\htmftrh1.htm
     set REC1TXT1=%SimoLIBR%\DataWrk1\Rec1Txt1.txt
     set REC1IDX1=%SimoLIBR%\DataWrk1\Rec1Idx1.dat
     call :PostNote "Annotate Copy File is %1"
rem  *
rem  *********************************************************************
rem  * The use of the PARM=IBM will cause the program to calculate the
rem  * physical length of the BINARY fields based upon the IBM mainframe
rem  * format. A PARM=MF would calculate the lengths based on the Micro
rem  * Focus format without the IBMCOMP and NOTRUNC directives.
rem  * This is the default for Net Express.
rem  *
     call :PostNote "Identify JobStep 0001, Scan the COBOL Copy File, Create HTM file."
     run SimoRec1 %4 HTML
     if ERRORLEVEL 1 set JobStatus=0001
     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 %~1
     goto :EOF
rem  * The preceding :EOF causes a return to caller within this CMD.
rem  *
rem  *********************************************************************
:EojAOK
     call :PostNote "Finished JobName Rec1Mfo1"
echo * Rec1Mfo1 Execute Internet Explorer.EXE, this window will
echo *          close when the IE Window is closed...
     START "c:\Program Files\Internet Explorer\iexplore.exe" %REC1HTML%
     goto :End
:EojNOK
     call :PostNote "ABENDING JobName Rec1Mfo1"
     call :PostNote "ABENDING Message JobStatus %JobStatus%"
     pause
     goto :End
:End
     if not "%5" == "nopause" pause

Table of Contents Previous Section Next Section Considerations and Limitations

This section describes situations that may occur during the migration of data from an IBM Mainframe to a Windows platform. The SimoTime Conversion Utility Programs that run on a Windows Platform with Micro Focus do not actually do the data file conversion. The utility programs generate COBOL programs (source code that is ANSI/85 compliant) that may be compiled and executed in a Micro Focus environment or an IBM Mainframe environment. This approach offers two advantages.

Item Description
1 The data file conversion may be done on a Micro Focus platform (Linux, UNIX or Windows) or an IBM Mainframe (ZOS or VSE) by simply compiling the generated COBOL programs on the targeted platform.
2 If special requirements are needed a user may make modifications to the generated COBOL source code.
  Advantages of using Generated Programs for Data File Conversion

Table of Contents Previous Section Next Section Numeric Fields

I think we all would agree that numeric fields should never contain non-numeric values. The situation that causes a non-numeric value in a numeric field should be corrected. The following table shows the rules used by SimoREC1 for conversion of numeric fields.

Field Type Description
Zoned-Decimal For numeric fields with USAGE IS DISPLAY the conversion code generated by SimoTime uses a table that will convert DIGITS, PLUS-SIGN, MINUS-SIGN, DECIMAL-POINT and SPACES between EBCDIC and ASCII.
Packed For numeric fields with USAGE IS COMP-3 (i.e. PACKED FIELDS) the conversion code generated by SimoTime should not and does not do any conversion. This is the default behavior.
However, we have seen a few instances where a packed field may contain SPACES and we have addressed this situation with a configuration option.
Note: A SPACE character (hex 40 for EBCDIC or a hex 20 for ASCII) could be a valid entry in a packed field in all the positions of the field except the units position. It would be reasonable to assume that if the units position of a packed field is a SPACE character and all other positions are SPACE characters then the packed field SPACE values should be converted.
Binary For numeric fields with USAGE IS COMP (i.e. BINARY FIELDS) the conversion code generated by SimoTime should not and does not do any conversion.
  Special Considerations for Numeric Fields

Table of Contents Previous Section Next Section Signed-Zoned-Decimal, Numeric Fields

Numeric fields that are signed, zoned-decimal format require additional consideration. The two options for maintaining the numeric format as zoned-decimal are as follows.

1. Maintain zoned-decimal in ASCII or EBCDIC and abide by the strict definition of zoned-decimal format. The sign position (trailing or leading) will have the high-order four bits (or left-most nibble) represent the sign and low order four bits (or right-most nibble) is the binary value for the digit. The EBCDIC format for positive numbers in all positions except the sign position will be x'Fn' or b'1111nnnn . The sign position will be 'Cn' or b'1100nnnn'. The ASCII format for positive numbers in all positions except the sign position will be x'3n' or b'0011nnnn'. The sign position will be x'7n' or b'0111nnnn'.

2. Use a modified-zoned-decimal format where the sign position (trailing or leading) will be translated based on the character display value. The sign position (trailing or leading) will have the high-order four bits (or left-most nibble) represent the sign and low order four bits (or right-most nibble) represent the digit. The EBCDIC format for positive numbers in all positions except the sign position will be x'Fn' or b'1111nnnn . The sign position will be 'Cn' or b'1100nnnn'.

The ASCII format for positive numbers in all positions except the sign position will be x'3n' or b'0011nnnn'. The sign position will no longer abide by the strict definition of zoned-decimal. The signed, positive digits of 1-9 in EBCDIC are represented by x'C1' through x'C9' which is also the representation for the letters "A" through "I". These will convert to the ASCII letters "A" through "I" or x'41' through x'49' and this would maintain the right-most nibble as the binary digit value and this is in accordance with the definition of zoned-decimal.

The departure from the strict definition of zoned-decimal happens with the positive zero and negative zero through nine. A zero with a positive or negative sign in EBCDIC is x'C0' and x'D0' which is also the representation for special characters "{" and "}". Using the modified-zoned-decimal these translate to the ASCII values for "{" and "}" which are x'7B' and x'7D' and the right-most nibble is no longer the binary value of the digit. The same is true for the negative digits 1 through 9. The EBCDIC is x'D1' through x'D9' which are the same as the letters "J" through "R". These are translated to the ASCII values of "J" through "R" which are x'4A' through x''52' and the right-most nibble is no longer the binary value of the digit. This is a departure from the definition of zoned-decimal.

Micro Focus supports both the zoned-decimal and the modified-zoned-decimal. Refer to the SIGN(EBCDIC) directive for supporting the modified-zoned-decimal format. For Mainframe Express (MFE) the SIGN(EBCDIC) is the default setting. For Net Express (NXE) the SIGN(ASCII) is the default and this will abide by the strict definition of zone-decimal.

Some applications may contain code that is dependent on the sign position being "A" through "I", "J" through "R", "{" or "}" to edit a field and properly display or print the content as a numeric, signed value. If this is true then the programs would need to be changed or the SIGN(EBCDIC) directive will need to be used with Net Express (NXE).

The modified-zoned-decimal format using the Micro Focus SIGN(EBCDIC) compiler directive may have an advantage when FTP'ing information between systems. If the FTP mode is ASCII then the sign position will conform to the modified-zone-decimal format when the data is converted during the file transfer process.

Abiding by the strict definition of zone-decimal will require the use of the BINARY mode when using FTP and the file may not be converted during the FTP or transfer process. It must be converted between ASCII and EBCDIC on the source machine prior to sending or on the target machine after receiving.

Table of Contents Previous Section Next Section Packed Numeric Fields

For numeric fields with USAGE IS COMP-3 (i.e. PACKED FIELDS) the conversion code generated by SimoTime does not do any conversion. This is the default behavior.

However, we have seen a few instances where a packed field may contain SPACES and we have addressed this situation with a configurable option. Refer to the Technical Details, Control/Configuration File section of this document for more information.

A SPACE character (hex 40 for EBCDIC or a hex 20 for ASCII) could be a valid entry in a packed field in all the positions of the field except the units position. It would be reasonable to assume that if the units position of a packed field is a SPACE character and all other positions are SPACE characters then the packed field SPACE values should be converted.

The following is sample code that will test a packed field for SPACE values and then convert the EBCDIC SPACE values to ASCII SPACE values.

      *    Packed  CUST-CREDIT-LIMIT
      *    The /PACKEDFLD option is set to SPACECONVERT
           if CUST-RECORD(300:4) = all x'40'
              inspect CUST-RECORD(300:4)   replacing all x'40' by x'20'
           end-if

The following is sample code that will test a packed field for SPACE values and then initialize the packed field to ZERO values.

      *    Packed  CUST-CREDIT-LIMIT
      *    The /PACKEDFLD option is set to SPACEZERO
           if CUST-RECORD(300:4) = all x'40'
              inspect CUST-RECORD(300:4)   replacing all x'40' by x'00'
              move x'0F' to CUST-RECORD(303:1)
           end-if

Table of Contents Previous Section Next Section Functional Limitations

The following is a list of known limitations or restrictions.

1 Multi-Dimensional Table support in a COBOL copy file.
2 Support for the occurs-depending-on or ODO usage within a COBOL copy file.
  Functional Limitations of SimoREC1

The preceding will require the user to use a modified version of the COBOL copy file or to modify the generated COBOL source code.

Table of Contents Previous Section Next Section Frequently Asked Questions

The following is a list of frequently asked questions about the SimoREC1 Utility Conversion program.

Item Question and Answer
1 We would like to have the option of running the data file conversion process on the mainframe, the PC with Windows or a Unix platform. How can this be accomplished?
SimoREC1 generates COBOL source code that will be used to do the actual conversion of the data files. SimoREC1 only requires Windows for the generation of the COBOL source code. The generated COBOL code is COBOL/2 compliant and will compile and execute on an IBM Mainframe or any platform supported by Micro Focus COBOL.
2 Is it possible to do the data conversion during the transfer process between the mainframe and the PC?
Yes, this is possible. However, this is usually limited to data strings that contain all text (i.e. no COMP or COMP-3 fields). For example, converting during the transfer process works quite well for source members. Also, signed, numeric fields cannot be treated as simple text fields even if they are zoned decimal.
3 Can SimoREC1 provide documentation of the record layout with information such as field positions and actual field lengths along with the total length of the record?
Yes, this is provided in an HTML format. This process may also be integrated as a Toolbar item with Micro Focus Mainframe Express or Net Express.
4 How are NUMERIC fields processed? For example, if the callable COBOL conversion routine is executed on the mainframe how does it avoid getting a S0C7 error when attempting to place an ASCII value into an EBCDIC numeric field?
During the copy file analysis step the NUMERIC fields are identified along with their position and offset within the record . When generating a callable COBOL routine SimoREC1 uses the group definition for the record (this is a character data structure by definition) and the Reference Modification function of COBOL along with the position and length values to process NUMERIC fields.
5 A VSAM Keyed-Sequential-Data-Set (KSDS), the JCL and an update program are downloaded from an IBM Mainframe to a Windows platform. The program is then compiled using Micro Focus Mainframe Express and everything works as expected. The program is then ported to Micro Focus Net Express and the file open fails with a file status code of 39. Why does this happen?
The file status code of 39 indicates the actual file attributes do not match the program defined attributes. In this case what is happening is the BINARY (or COMP) fields are being calculated with different length. For example, on the IBM mainframe a PIC 9(7) COMP field will have an actual 4-byte length. On the PC this will default to a 3-byte length, this will result in different record lengths being calculated and a subsequent file status code of 39. For Micro Focus Net Express the COBOL compiler directives IBMCOMP and NOTRUNC must be used in order to access the data set.
6 SimoREC1 does the record content conversion between ASCII and ECBDIC at the field level. Would it be possible to use a single INSPECT statement for the contiguous fields for improved performance?
It is possible to use a single statement for contiguous fields. However, be very careful. For example, do not mix contiguous alphameric and contiguous numeric fields into a single statement. Also, initial timings have not shown any significant performance improvements when combining the contiguous statements. It may not be worth the risk of manually combining the contiguous fields and introducing errors in the conversion process.
7 How does SimoREC1 handle REDEFINES?
The REDEFINES are identified during the copy file analysis step. The HTML document produced will show the redefines and further identify short redefines. When generating a callable COBOL routine SimoREC1 uses the primary definition.
8 How does SimoREC1 handle FILLER items?
The FILLER items are identified during the copy file analysis step. The HTML document produced will show the FILLER items with their position within the record and their length. When generating a callable COBOL routine SimoREC1 uses the Reference Modification function of COBOL along with the position and length values to process FILLER items.
9 What if the copy file contains table definitions (i.e. OCCURS items)?
The SimoREC1 Utility will generate the code to convert each table element. This is done using PERFORM logic that loops until each element within the table has been converted.
10 How are PACKED and BINARY (i.e. COMP-3 or COMP) fields processed during an EBCDIC to ASCII conversion?
The PACKED and BINARY fields are identified during the copy file analysis step. During the generation of the callable COBOL routine a comment statement is inserted into the source code to identify the PACKED or BINARY field. The mainframe numeric encoding is maintained for the PACKED and BINARY fields.
11 How does SimoREC1 process multiple record types within the same file?
This requires some manual work. First, if the copy file contains multiple 01 levels for the different record types then a new copy file should be created for each of the different 01 levels (or record types). Next, create a callable COBOL conversion routine for each of the new copy files. As the final step use the SimoZAPS utility to create a COBOL program that does the file I/O and manually add the logic to call the various conversion routines based on the content of the record.
12 What needs to be done with Alternate Indexes?
This may require some manual work. The alternate indexes will need to be recreated on the target platform. SimoREC1 has additional capability for generating a data conversion program with alternate index statements.
13 Will the differences in the EBCDIC and ASCII collating sequence cause problems?
In an EBCDIC encoding scheme the numbers come after the letters and lower case precedes upper case. In an ASCII encoding scheme the numbers come before the letters and upper case precedes lower case. This is normally an arrangement or list sequencing issue that needs explaining to the business users prior to implementation and is usually accepted as a necessary change.
However, this may cause some problems if certain coding techniques were used. For example the following logic is correct in an EBCDIC environment but will fail in an ASCII environment, "If BYTE-01-CONTENT < SPACE or > 9 then non-printable character". This coding would need to be changed. Also, see the next items in this list for another exposure.
14 What is the effort/impact of converting indexed files with Alpha-meric keys and the EBCDIC vs. ASCII collating sequence?
This requires some additional work. If sequential file processing is used (i.e. ACCESS MODE IS SEQUENTIAL on the SELECT statement) and the key for the index actually contains a mixture of alphabetic and numeric characters (and/or special characters) the odds are very high that a sequencing error will be encountered while attempting to write to the target file. This requires an unordered load that reads the input file sequentially and randomly adds records to the output file, this will perform slower than an ordered or sequential load of the file.
SimoREC1 will generate the code for an ordered load (sequential add using SYSMASK3.TXT) or an unordered load (random add or update using SYSMASK4.TXT).
Another alternative would be to reproduce the Indexed file as a sequential file. The sequential file could then be converted, sorted and used to create a new indexed file
15 What are the limitations when processing a copy file? For example, we have copy files that do not have an 01 level defined. We also have copy files that have multiple 01 levels for different record types.
SimoREC1 does process most copy files without any problems. However, there are some considerations. To answer the first question an 01 level definition is not required. If the first field definition is not an 01 level then SimoREC1 will create a virtual 01 level called SIMOREC1-FORCE-01.
The second part of the question poses a different problem that will require some additional work. If the copy file contains multiple 01 levels for the different record types then a new copy file will need to be created for each of the different 01 levels (or record types).
  Frequently Asked Questions

Table of Contents Previous Section Next Section System Overview

The following is a flowchart of the job steps for executing the program to scan a COBOL copy file and create the various outputs for documentation and/or data file conversion.

                 
SIMOREC1
UTL
   
   
Get Command Line, execute program.
   
   
   
 
 
 
 
   
   
   
   
Rec1COPY
copy
 
 
SIMREC2
UTL
   
   
REC1TXT1
lseq
Read the copy member, create the TEXT and INDEXED files.
   
   
   
   
   
   
   
REC1IDX1
indx
   
   
   
 
 
 
 
   
   
   
   
REC1TXT1
crlf
SIMREC3
UTL
 
 
SIMRECD4
copy
Read the TEXT file and create a new COPY file.
   
   
   
 
 
 
 
   
   
   
   
REC1TXT1
crlf
SIMREC4
UTL
 
 
REC1HTML
html
Read the TEXT file and create the HTML file.
   
   
   
 
 
 
 
   
   
   
   
REC1TXT1
crlf
 
 
SIMREC5
UTL
   
   
REC1ZAP1
cmd
Create CMD file.
   
   
   
   
   
   
   
REC1ZAP2
txt
Create Specs file for SimoZAPS.
   
   
   
 
 
 
 
   
   
   
COPYFILE
cpy
 
 
SIMREC6
UTL
   
   
REC1ZAP1
txt
Read copy file, create callable conversion routine
   
   
   
   
   
ROUTINE
cbl
COBOL source code for data conversion
End-of-Job
EOJ
This is End-of-Job
 
Scan a COBOL copy file and create the various outputs for documentation and/or data file conversion

Table of Contents Previous Section Next Section Summary

The purpose of this document is to assist as a tutorial for new programmers or as a quick reference for experienced programmers. In the world of programming there are many ways to solve a problem. This suite of programs is provided as a COBOL programming example of one of the possible solutions to the problem of converting the EBCDIC encoded fields within a record to ASCII encoded fields within a record using a COBOL Copy File as input. This example will also maintain the integrity of the mainframe numeric encoded fields for PACKED and BINARY data.

Table of Contents Previous Section Next Section Software Agreement and Disclaimer

Permission to use, copy, modify and distribute this software, documentation or training material for any purpose requires a fee to be paid to SimoTime Enterprises. Once the fee is received by SimoTime the latest version of the software, documentation or training material will be delivered and a license will be granted for use within an enterprise, provided the SimoTime copyright notice appear on all copies of the software. The SimoTime name or Logo may not be used in any advertising or publicity pertaining to the use of the software without the written permission of SimoTime Enterprises.

SimoTime Enterprises makes no warranty or representations about the suitability of the software, documentation or learning material for any purpose. It is provided "AS IS" without any expressed or implied warranty, including the implied warranties of merchantability, fitness for a particular purpose and non-infringement. SimoTime Enterprises shall not be liable for any direct, indirect, special or consequential damages resulting from the loss of use, data or projects, whether in an action of contract or tort, arising out of or in connection with the use or performance of this software, documentation or training material.

Table of Contents Previous Section Next Section Downloads and Links

This section includes links to documents with additional information that are beyond the scope and purpose of this document. The first group of documents may be available from a local system or via an internet connection, the second group of documents will require an internet connection.

Note:  A SimoTime License is required for the items to be made available on a local system or server.

Table of Contents Previous Section Next Section Current Server or Internet Access

The following links may be to the current server or to the Internet.

Note: The latest versions of the SimoTime Documents and Program Suites are available on the Internet and may be accessed using the Link to Internet icon. If a user has a SimoTime Enterprise License the Documents and Program Suites may be available on a local server and accessed using the Link to Server icon.

Link to Internet   Link to Server   Explore the cycle of converting and transferring non-relational data files between an IBM Mainframe System and a Windows, Linux or UNIX System. This discussion will leverage the non-relational file support provided by Micro Focus for the distributed systems.

Link to Internet   Link to Server   Explore how to create multiple HTML documents for record structures based on the definitions provided from the COBOL copy files. This includes record layouts for non-relational files and/or VSAM Data Sets.

Link to Internet   Link to Server   Explore How to Read an EBCDIC-ecoded Sequential file and Create an ASCII-encoded Sequential file. This is an example of how a COBOL program can read a sequential file with EBCDIC content that is downloaded from a mainframe in binary format using FTP (File Transfer Protocol). The example then describes how to translate the EBCDIC content to ASCII and write an ASCII file.

Link to Internet   Link to Server   Explore an Extended List of Software Technologies that are available for review and evaluation. The software technologies (or Z-Packs) provide individual programming examples, documentation and test data files in a single package. The Z-Packs are usually in zip format to reduce the amount of time to download.

Link to Internet   Link to Server   Explore The ASCII and EBCDIC Translation Tables. These tables are provided for individuals that need to better understand the bit structures and differences of the encoding formats.

Link to Internet   Link to Server   Explore The File Status Return Codes to interpret the results of accessing VSAM data sets and/or QSAM files.

Table of Contents Previous Section Next Section Internet Access Required

The following links will require an internet connect.

The SimoREC1 program, this documentation, the Installation Verification Procedures (IVP's) and examples are provided electronically or on machine-readable media with a predefined SETUP procedure. Additional information about acquiring SimoREC1 may be obtained by contacting the helpdesk@simotime.com or refer to the  Product Availability and Pricing  document.

A good place to start is The SimoTime Home Page via Internet Connect for access to white papers, program examples and product information.

Explore The Micro Focus Web Site via Internet Connect for more information about products and services available from Micro Focus.

Table of Contents Previous Section Next Section Glossary of Terms

Link to Internet   Link to Server   Explore the Glossary of Terms for a list of terms and definitions used in this suite of documents and white papers.

Table of Contents Previous Section Next Section Comments or Feedback

This document was created and is copyrighted and maintained by SimoTime Enterprises.

If you have any questions, suggestions, comments or feedback please call or send an e-mail to: helpdesk@simotime.com

We appreciate hearing from you.

Table of Contents Previous Section Next Section Company Overview

Founded in 1987, SimoTime Enterprises is a privately owned company. We specialize in the creation and deployment of business applications using new or existing technologies and services. We have a team of individuals that understand the broad range of technologies being used in today's environments. This includes the smallest thin client using the Internet and the very large mainframe systems. There is more to making the Internet work for your company's business than just having a nice looking WEB site. It is about combining the latest technologies and existing technologies with practical business experience. It's about the business of doing business and looking good in the process. Quite often, to reach larger markets or provide a higher level of service to existing customers it requires the newer Internet technologies to work in a complementary manner with existing corporate mainframe systems.

Whether you want to use the Internet to expand into new market segments or as a delivery vehicle for existing business functions simply give us a call or check the web site at http://www.simotime.com


Return-to-Top
COBOL Data Structures and Record Layouts for Data File Conversion
Copyright © 1987-2014
SimoTime Enterprises
All Rights Reserved
When technology complements business
http://www.simotime.com