Hitachi Cross-OS FIle Exchange Code Converter User's Guide

Transcription

1 Hitachi Cross-OS File Exchange Code Converter User s Guide Hitachi Virtual Storage Platform Hitachi Universal Storage Platform V/VM Hitachi TagmaStore Universal Storage Platform Hitachi TagmaStore Network Storage Controller Hitachi Lightning 9900 V Series FASTFIND LINKS Document Organization Product Version Getting Help Contents MK-94RD253-03

2 Copyright 2010 Hitachi, Ltd. All rights reserved. No part of this publication may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, or stored in a database or retrieval system for any purpose without the express written permission of Hitachi, Ltd. (hereinafter referred to as Hitachi ) and Hitachi Data Systems Corporation (hereinafter referred to as Hitachi Data Systems ). Hitachi and Hitachi Data Systems reserve the right to make changes to this document at any time without notice and assume no responsibility for its use. This document contains the most current information available at the time of publication. When new and/or revised information becomes available, this entire document will be updated and distributed to all registered users. Some of the features described in this document may not be currently available. Refer to the most recent product announcement or contact your local Hitachi Data Systems sales office for information about feature and product availability. Notice: Hitachi Data Systems products and services can be ordered only under the terms and conditions of the applicable Hitachi Data Systems agreement(s). The use of Hitachi Data Systems products is governed by the terms of your agreement(s) with Hitachi Data Systems. Hitachi is a registered trademark of Hitachi, Ltd. in the United States and other countries. Hitachi Data Systems is a registered trademark and service mark of Hitachi, Ltd. in the United States and other countries. ShadowImage and TrueCopy are registered trademarks of Hitachi Data Systems. AIX,, MVS/ESA, MVS/XA, and VSE/ESA are registered trademarks or trademarks of International Business Machines Corporation. All other trademarks, service marks, and company names are properties of their respective owners. Microsoft product screen shot(s) reprinted with permission from Microsoft Corporation. ii

3 Contents Preface...vii Intended Audience... viii Product Version... viii Document Revision Level... viii Changes in this Revision... viii Document Organization...ix Referenced Documents...x Document Conventions...xi Convention for Storage Capacity Values... xii Accessing Product Documentation... xii Getting Help... xiii Comments... xiii Overview of Code Converter Overview of Code Converter Code Converter Process Code Converter Functions Alphanumeric Character Conversion Function Double-Byte Character Conversion Function Non-Conversion Function (Simple Transmission) Output Suppression Function Numeric Conversion Function Code Conversion Functions Undefined Character Code Processing (Single-byte) Undefined Character Code Processing (Double-byte) Shift Code Deletion Processing (Double-Byte and Single-Byte Combination) Shift Code Insertion Processing (Double-Byte and Single-Byte Combination) Shift Code Insertion Suppression Processing (Double-Byte and Single-Byte Combination) Contents iii

4 Short Output Field Processing System Requirements and Installation System Requirements Overview of Code Converter Installation Installation Media for UNIX-based Systems Installation Media for Windows-based Systems Installation and Uninstallation for UNIX Systems Installing for UNIX Systems Uninstalling for UNIX Systems Upgrading or Downgrading Installation and Uninstallation for Windows Systems Installing for Windows Systems Uninstalling for Windows Systems Upgrading and Downgrading License Key Input License Key for UNIX Systems License Key for Windows Systems Using FX Code Converter FX Code Converter User Process Flow Database Data File Record Format Code Conversion Using Fixed-Length Records Code Conversion Using Variable-Length Records Creating a Field Definition File Using the Parameter Definition File to Associate Field Definition Files Edit Option File Mainframe-to-Open System Character Code Conversion Overview of Character Code Conversion Alphanumeric Field conversion (CHAR:OPK4) Double-byte Character Field Conversion (KANJI:OPK1) Double Byte Character Field Conversion (KANJI:OPK2) Customizing the Code Conversion Table Open-to-Mainframe Character Code Conversion Overview Alphanumeric Field Conversion (CHAR:OPK9) Double Byte Character Field Conversion (KANJI:OPK6) Double Byte Character Field Conversion (KANJI:OPK7) iv Contents

5 Numeric Conversion MTO Numeric Value Conversion Overview Packed Decimal Conversion (NUM:OPA1) Sign Zero Suppression Decimal Point All-space Fields Zoned Decimal Conversion (NUM:OPA2) Sign Zero Suppression Decimal Point All-space Fields only Fields Customizing the Code Conversion Table Operation Overview Utility Features Definition Statement Syntax Definition Statement Syntax Rules Definition Statement Details Command Syntax for UNIX Systems Command Syntax for Windows Systems Examples of the ccnv Utility Customizing Character Conversion Converting Private Characters Outputting Code Conversion Table Information Outputting to a File Troubleshooting Troubleshooting Error Codes ccnv Messages FX Code Converter Error Codes and Basic Troubleshooting Guidelines Calling the Support Center Edit Option File... A-1 Edit Option File... A-1 Contents v

6 HOST... B-1 EBCDIC-ASCII Code Conversion... C-1 Acronyms and Abbreviations vi Contents

7 Preface This document describes and provides instructions for installing and using Hitachi Cross-OS File Exchange (FX) Code Converter for the Hitachi RAID storage systems. The Hitachi RAID storage systems include the following models: Hitachi Virtual Storage Platform (VSP) Hitachi Universal Storage Platform V/VM Hitachi TagmaStore Universal Storage Platform (USP) Hitachi TagmaStore Network Storage Controller (NSC) Hitachi Lightning 9900V Please read this document carefully to understand how to use this product, and maintain a copy for reference purposes. This preface includes the following information: Intended Audience Product Version Document Revision Level Changes in this Revision Document Organization Referenced Documents Document Conventions Convention for Storage Capacity Values Accessing Product Documentation Getting Help Comments Preface vii

8 Intended Audience This document is intended for system administrators, Hitachi Data Systems representatives, and Authorized Service Providers who are involved in installing, configuring, and operating the Hitachi Raid storage systems. Readers of this document should meet the following requirements: You should have a background in data processing and understand RAID storage systems and their basic functions. You should be familiar with the Hitachi RAID storage system(s), and you should have read the User and Reference Guide for the storage system. You should be familiar with the Storage Navigator software for the Hitachi RAID storage system(s), and you should have read the Storage Navigator User s Guide. You should be familiar with the applicable open-system operating system(s) and application software. Product Version This document revision applies to FX version 01-XX-66/2x or later. Document Revision Level Revision Date Description MK-94RD253-P February 2007 Preliminary Release MK-94RD April 2007 Initial Release, supersedes and replaces MK-94RD253-P MK-94RD May 2007 Revision 1, supersedes and replaces MK-94RD MK-94RD September 2007 Revision 2, supersedes and replaces MK-94RD MK-94RD October 2010 Revision 3, supersedes and replaces MK-94RD Changes in this Revision Added the Hitachi Virtual Storage Platform. viii Preface

9 Document Organization The following table provides an overview of the contents and organization of this document. Click the chapter title in the left column to go to that chapter. The first page of each chapter provides links to the sections in that chapter. Chapter Overview of Code Converter Code Converter Functions System Requirements and Installation Using Code Converter Mainframe-to-Open Systems Character Code Conversion Open Systems-to-Mainframe Character Code Conversion Numeric Conversion Customizing the Code Conversion Table Troubleshooting Appendix A: Edit Option File Appendix B: HOST Appendix C: EBCDIC-ASCII Code Conversion Description Provides an overview of how Code Converter operates and the interactions it has with other Hitachi software. Describes Code Converter functions and operations and when they are used by an operator. Describes the system and installation requirements for Code Converter, and provides instructions for installing Code Converter. Describes the operational sequence, how users perform operations and use the functions of Code Converter. Describes the mainframe-to-open (mto) character code conversion process. Describes the open-to-mainframe (otm) character code conversion process. Describes the considerations involved in performing numeric value conversions. Describes the procedures for customizing the code conversion table for use with your specific conversion requirements. Provides troubleshooting information, error codes, and customer support contact information. Describes the error codes and messages in the Code Converter Edit Options file. Provides an example of a Code Conversion table and a table of EBCDIC-to-ASCII conversion values. Lists the EBCDIC-ASCII code conversions performed by the default code conversion table that is provided with FX. Preface ix

10 Referenced Documents Hitachi Virtual Storage Platform: Hitachi Cross-OS File Exchange User s Guide, MK-96RD647 Storage Navigator User Guide, MK-90RD7027 User and Reference Guide, MK-90RD7042 Hitachi Universal Storage Platform V/VM: Storage Navigator User s Guide, MK-96RD621 User and Reference Guide, MK-96RD635 Hitachi TagmaStore USP/NSC: Storage Navigator User s Guide, MK-94RD206 Universal Storage Platform User and Reference Guide, MK-94RD231 Network Storage Controller User and Reference Guide, MK-95RD279 x Preface

11 Document Conventions The terms Virtual Storage Platform and VSP refer to all models of the Hitachi Virtual Storage Platform storage system, unless otherwise noted. The terms Universal Storage Platform V/VM and USP V/VM refer to all models of the Hitachi Universal Storage Platform V/VM unless otherwise noted. This document uses the following typographic conventions: Convention Bold Italic screen/code Description Indicates text on a window, other than the window title, including menus, menu options, buttons, fields, and labels. Example: Click OK. Indicates a variable, which is a placeholder for actual text provided by the user or system. Example: copy source-file target-file Note: Angled brackets (< >) are also used to indicate variables. Indicates text that is displayed on screen or entered by the user. Example: # pairdisplay -g oradb < > angled brackets Indicates a variable, which is a placeholder for actual text provided by the user or system. Example: # pairdisplay -g <group> Note: Italic font is also used to indicate variables. [ ] square brackets Indicates optional values. Example: [ a b ] indicates that you can choose a, b, or nothing. { } braces Indicates required or expected values. Example: { a b } indicates that you must choose either a or b. vertical bar Indicates that you have a choice between two or more options or arguments. Examples: [ a b ] indicates that you can choose a, b, or nothing. { a b } indicates that you must choose either a or b. This document uses the following icons to draw attention to information: Icon Meaning Description Note Tip Caution WARNING Calls attention to important and/or additional information. Provides helpful information, guidelines, or suggestions for performing tasks more effectively. Warns the user of adverse conditions and/or consequences (e.g., disruptive operations). Warns the user of severe conditions and/or consequences (e.g., destructive operations). Preface xi

12 Convention for Storage Capacity Values Physical storage capacity values (e.g., disk drive capacity) are calculated based on the following values: Physical capacity unit Value 1 KB 1,000 (10 3 ) bytes 1 MB 1,000 KB or 1,000 2 bytes 1 GB 1,000 MB or 1,000 3 bytes 1 TB 1,000 GB or 1,000 4 bytes 1 PB 1,000 TB or 1,000 5 bytes 1 EB 1,000 PB or 1,000 6 bytes Logical storage capacity values (e.g., logical device capacity) are calculated based on the following values: Logical capacity unit Value 1 block 512 bytes 1 KB 1,024 (2 10 ) bytes 1 MB 1,024 KB or 1,024 2 bytes 1 GB 1,024 MB or 1,024 3 bytes 1 TB 1,024 GB or 1,024 4 bytes 1 PB 1,024 TB or 1,024 5 bytes 1 EB 1,024 PB or 1,024 6 bytes Accessing Product Documentation The user documentation for the Hitachi RAID storage systems is available on the Hitachi Data Systems Portal: Check this site for the most current documentation, including important updates that may have been made after the release of the product. xii Preface

13 Getting Help Comments The Hitachi Data Systems customer support staff is available 24 hours a day, seven days a week. If you need technical support, log on to the Hitachi Data Systems Portal for contact information: Please send us your comments on this document: doc.comments@hds.com. Include the document title, number, and revision, and refer to specific section(s) and paragraph(s) whenever possible. Thank you! (All comments become the property of Hitachi Data Systems.) Preface xiii

14 xiv Preface

15 1 Overview of Code Converter This chapter provides and overview of how Code Converter operates and the interactions it has with other Hitachi software. Overview of Code Converter Code Converter Process Overview of FX Code Converter 1-1

16 Overview of Code Converter The Code Converter, running on the Hitachi RAID storage systems using Hitachi Cross-OS File Exchange (FX), moves data between mainframe systems and open-systems servers. It enables the modification of data, including code conversion of various double-byte characters. It incorporates functions such as standard double-byte code conversion. The purpose of implementing the Code Converter is to build a mainframe/server data exchange system without having to develop a converter, as with double-byte code conversion. Note: The Hitachi Cross-OS File Exchange software consists of the File Access Library (FAL) and the File Conversion Utility (FCU) (FAL/FCU). 1-2 Overview of FX Code Converter

17 Code Converter Process The Code Converter is a user s own coding (UOC) function that is called from FX File Conversion Utility. Figure 1-1 shows the positioning of the Code Converter and an outline of mainframe-to-open (mto) conversion operations, and Figure 1-2 shows open-to-mainframe (otm) conversion. Cross-OS File Exchange (FCU) FAL Fibre Hitachi RAID storage system Figure 1-1 Mainframe-to-Open (mto) Conversion Overview of FX Code Converter 1-3

18 Cross-OS File Exchange (FCU) FAL Fibre Hitachi RAID storage system Figure 1-2 Open-to-Mainframe (otm) Conversion Note 1: JP1 and OJE (open job entry) are Hitachi-provided package products. They are required for communication between the mainframe and the opensystems servers to handle data transfer. Note 2: A field represents a part of a record or can be the whole record, and is the basic processing unit of the FX Code Converter. Basic flow of FX (mto) and Code Converter operations (refer to the circled numbers in Figure 1-1 and Figure 1-2): 1. The FX software reads the data of a mainframe FXmto volume. 2. If use of mto edit interface is declared with reference to the Parameter Definition file (which the user creates in advance), FX extracts the data for one record and passes the record data to Code Converter. 3. Code Converter extracts the data for one field and then determines the type of conversion specified referring to the Field Definition file (which the user creates in advance). 4. Perform conversion of double-byte characters etc. referring to the Field Definition file and the Edit Option file (standard file provided). 5. Repeat extraction processing and conversion processing of steps 3 and 4 for all fields in the record. 1-4 Overview of FX Code Converter

19 6. Code Converter returns the data after conversion to FX, after ending conversion processing of all fields for one record. This process repeats iteratively from step 1 through step FX outputs the data for the record to the server file (UNIX, etc.). Overview of FX Code Converter 1-5

20 1-6 Overview of FX Code Converter

21 2 Code Converter Functions This chapter describes Code Converter s available functions, their concept of operations and when they are used by an operator. Alphanumeric Character Conversion Function Double-Byte Character Conversion Function Non-Conversion Function (Simple Transmission) Output Suppression Function Numeric Conversion Function Code Conversion Functions Code Converter Functions 2-1

22 Table 2-1 lists the Code Converter function specifications. The edit functions performed in connection with the alphanumeric and double-byte code conversions are covered in detail in Code Conversion Functions. Table 2-1 Code Converter Functions Function Specification Remarks Alphanumeric Character Conversion Function Double-Byte Character Conversion Function Non-Conversion Function (Simple Transmission) Output Suppression Function Numeric Conversion Function Code conversion is performed only on singlebyte field data characters. Mainframe EBCDIC Open system ASCII Note: Single-byte character codes are changed. Code conversion is performed on field data characters in which double-byte characters alone, or double-byte characters and singlebyte characters are intermingled. Mainframe Traditional Chinese Open system Big5 Note: double-byte character codes are changed. The data in the input field is not changed and is output. The data in the input field is not output. Code conversion is performed to the field data which consists only of numeric characters. Mainframe packed decimal, zoned decimal Open system numeric character A numeric character code is changed. None None Input data is not limited to characters. The output field is shortened by the length of the non-conversion field that is not output. None 2-2 Code Converter Functions

23 Alphanumeric Character Conversion Function Code conversion is performed on a single-byte character data field. Figure 2-1 illustrates the process flow. The target coding system is as follows: Mainframe code set EBCDIC Open-system code set ASCII Figure 2-1 Alphanumeric Character Conversion Flow Data is read from an input file per 1 record, the portion of the single-byte character field to convert is extracted, and the appointed alphanumeric character conversion is performed. Conversion is performed for every field, and the result is edited per 1 record and written to an output file. The position from which single-byte character fields in a record are extracted and the output field length are determined by referring to the value specified in the Field Definition file created by the user (refer to Creating a Field Definition File for more information). Detail specification (the type of conversion table to use etc.) of the alphanumeric character conversion method is controlled by the default specification parameter in the standard Edit Option file provided (refer to Edit Option File more information). Code Converter Functions 2-3

24 Double-Byte Character Conversion Function Code conversion is performed on a data field which consists of the double-byte characters, or double-byte and single-byte characters that are intermingled. Figure 2-2 illustrates the process flow. The target coding system is as follows: Mainframe Traditional Chinese: In this case, EBCDIC single-byte characters are intermingled with double-byte characters Open system Big5: In this case, ASCII single-byte characters are intermingled with double-byte characters. Figure 2-2 Double-byte Character Conversion Flow Data is read from an input file per 1 record, the portion of the double-byte character field (single-byte character can be included in the field) to convert is extracted, and appointed double-byte character conversion is performed. The conversion is as same as alphanumeric character conversion explained in Alphanumeric Character Conversion Function. 2-4 Code Converter Functions

25 Non-Conversion Function (Simple Transmission) Data in input field is output without any processing. Input data is not limited to character codes. Figure 2-3 illustrates the process flow. Figure 2-3 Non-conversion Process Flow Data is read from an input file per 1 record, the portion of the non-conversion field (unprocessed) is extracted, and simple transmission is performed. The position from which the non-conversion field in a record is extracted is determined by referring to the specified value in the Field Definition file created by the user (for details, see Creating a Field Definition File). Note 1: For non-conversion fields, make sure that the output field length is the same as the input field length. If the description of output field length is omitted in the Field Definition file, the default will be the same length as the input field. Note 2: Since this processing method carries out only simple transmissions for non-conversion fields, the standard Edit Option file that is usually provided is not referred to here. Code Converter Functions 2-5

26 Output Suppression Function Input field data is not output. The output record length is shortened and is not output. Figure 2-4 illustrates the process flow. Figure 2-4 Output Suppression Function Flow Data is read from an input file per 1 record; the portion of the output suppression field is extracted, and after reading, the data is discarded. The output field length of an output suppression field is always 0. The position from which the output suppression field in a record is extracted is recognized by referring to the value specified in the Field Definition file created by the user (for details, see Creating a Field Definition File). Note: Do not specify an output field length for the output suppression function. Since an output is suppressed, the standard Edit Option file provided is not referred to here. 2-6 Code Converter Functions

27 Numeric Conversion Function Code conversion is performed only on the numeric character data fields. Figure 2-5 illustrates the process flow. The target coding system is as follows. Mainframe packed decimal or zoned decimal Open system Numeric character Figure 2-5 Numeric Conversion Function Process Flow Data is read from an input file per 1 record, the portion of the numeric character field to convert is extracted, and the numeric character conversion is performed. Conversion is performed for every field, and the result is edited per 1 record, and written to an output file. The position from which the numeric character field in a record is extracted and the output field length is determined by referring to the value specified in the Field Definition file created by the user (for details, see Creating a Field Definition File). Specification of the details (sign position, the number of decimal digits, etc.) of the numeric character conversion method is controlled by the default specification parameter in the standard Edit Option file provided (for details, see Edit Option File). Code Converter Functions 2-7

28 Code Conversion Functions Undefined Character Code Processing (Single-byte) Figure 2-6 Illustrates the Single-byte undefined character code process. Figure 2-6 Undefined Character Code Processing (Single-byte) In this situation, an undefined character (a valid character which is not defined in the conversion table) in an alphanumeric character conversion is replaced by a replacement code for undefined characters (single-byte space). 2-8 Code Converter Functions

29 Undefined Character Code Processing (Double-byte) Figure 2-7 illustrates the undefined character code process. Figure 2-7 Undefined Character Code Processing (double-byte) In this situation, an undefined character (a valid character which is not defined in the conversion table) in a double-byte character conversion is replaced by a replacement code for undefined characters (double-byte space). When single-byte characters are intermingled with double-byte characters, either a single-byte space or a double-byte space is used as the replacement code according to the position in the field. Code Converter Functions 2-9

30 Shift Code Deletion Processing (Double-Byte and Single-Byte Combination) Figure 2-8 illustrates the shift code deletion process. Figure 2-8 Shift Code Deletion Processing When carrying out double-byte code conversion (double-byte and single-byte in the same field) from a coding system with a shift code to a coding system without a shift code, the shift codes are deleted. A shift code is a special code which shows the boundary of double-byte/single-byte characters. Data is leftaligned in the output field. Extra space in the output field is padded with the field padding code (double-byte or single-byte space) Code Converter Functions

31 Shift Code Insertion Processing (Double-Byte and Single-Byte Combination) Figure 2-3 illustrates the shift code insertion process. Figure 2-9 Shift Code Insertion Process When carrying out double-byte code conversion (double-byte and single-byte in the same field) from a coding system without a shift code to a coding system with a shift code, a shift code can be inserted where necessary. A shift code is a special code which shows the boundary of double-byte/single-byte characters. If extra space still remains in the output field, it is filled up with a field padding code (double-byte/single-byte space). Note: the end of input data is discarded when an output field area runs short as a result of inserting shift codes. Code Converter Functions 2-11

32 Shift Code Insertion Suppression Processing (Double-Byte and Single-Byte Combination) Figure 2-10 illustrates the shift code insertion process. Figure 2-10 Shift Code Insertion Suppression Process When double-byte code conversion (double-byte and single-byte in the same field) is carried out from a coding system without a shift code to a coding system with a shift code, the user can choose not to insert a shift code to the output field. A shift code is a special code which shows the boundary of double-byte/single-byte characters. Note: It is necessary to additionally specify TRAN_SHIFT_NO for code conversion mode in the Edit Option file. Normally, a shift code should be inserted Code Converter Functions

33 Short Output Field Processing Figure 2-11 illustrates the short output field process. Figure 2-11 Short Output Field Processing Note: the end of input data is discarded when the output field length specified in the Field Definition file is too short, or when the output field becomes short as a result of inserting shift codes. Code Converter Functions 2-13

34 2-14 Code Converter Functions

35 3 System Requirements and Installation This chapter describes the system and installation requirements for Code Converter. It also details how to install Code Converter on you system. System Requirements Overview of the FX Code Converter Installation Installation Media for UNIX-based Systems Installation Media for Windows-based Systems Installing and Uninstalling for UNIX Systems Installation and Uninstallation for Windows Systems License Key Input System Requirements and Installation 3-1

36 System Requirements The system requirements for the FX Code Converter are: FAL/FCU CD for the applicable open-system platform(s). See the Hitachi Cross-OS File Exchange User s Guide for details regarding the FAL/FCU software. Note: FAL/FCU currently supports files larger than 2 GB. Hitachi RAID storage system: FX Code Converter mto: the Hitachi RAID storage system must be configured with -B and/or -A FX volumes. FX Code Converter otm: the Hitachi RAID storage system must be configured with -C and/or -A FX volumes. Note: A license key is required for FX Code Converter operations. If you execute mto before inputting the license key code, a 0 byte file will be created. If this occurs, execute mto again after you have input the license key code. Use Storage Navigator to enter the license key. For instructions, see the Storage Navigator User s Guide for the storage system. Mainframe operating systems: MVS/ESA, MVS/XA For the latest information on supported mainframe systems, contact your Hitachi Data Systems representative. UNIX operating systems: HP-UX, AIX, Solaris, Red Hat Linux, SUSE Linux For the latest information on supported UNIX OS versions, contact your Hitachi Data Systems representative. PC server operating system: Microsoft Windows For the latest information on supported Windows OS versions, contact your Hitachi Data Systems representative. 3-2 System Requirements and Installation

37 Overview of Code Converter Installation Figure 3-1 shows an overview of the Code Converter installation process. In order to use Code Converter, you must first install the Cross-OS File Exchange software (File Conversion Utility, FCU), and then install Code Converter. For details on installing FCU, see the Hitachi Cross-OS File Exchange User s Guide. Figure 3-1 Installation Overview System Requirements and Installation 3-3

38 Installation Media for UNIX-based Systems Table 3-1 lists and describes the FX Code Converter Installation Utility files for use with UNIX systems. FX Code Converter provides these files in tar (tape archive) format. For information about supported operating systems, please contact your Hitachi Data Systems representative. Table 3-1 Code Conversion Utility Files for UNIX Systems File Name Contents Installation Location libuoc.* (Note 1) codetran.ini HOST.tbl UOC double-byte conversion function s object (replace with a dummy object provided by FAL/FCU) ini file used by the double-byte code conversion routine Traditional Chinese Big5 conversion table standard table for mto conversion /usr/lib FAL/FCU boot directory HOST.tbl EditOpFile Big5 Traditional Chinese conversion table Edit Option file standard table for otm conversion ccnv (Note 2) Executable file for the ccnv command used to customize code conversion tables for all files contained in this table. ppkeyset Executable file for inputting a license key code. /usr/bin libuoc.ver (Note 5) Version information file /usr/lib uoc.c (Note 3) uocerror.h (Note 3) Standard source provided Standard header file provided Files for creating user-defined UOC function that is used when not using Code Converter FAL/FCU boot directory libuoc.mak (Note 3) Makefile uoc.exp (Notes 3, 4) Module definition file Notes: 1. This file extension is used in place of.* depending on the platform as shown in Table Use ccnv listed here when customizing code conversion tables, such as adding user-defined characters or characters not in conversion table. 3. These files are not necessary when you use Code Converter. 4. uoc.exp is provided only in the AIX version. 5. Place libuoc.ver in /usr/lib/. 3-4 System Requirements and Installation

39 Table 3-2 File Extensions for UNIX-based Operating Systems Type Manufacturer Operating System File Extension UNIX server HP HP - UX 11.0 or later.sl HP-UX 11iV2 (IA-64) or late.so AIX 5.2 or later.a SUN Solaris 8 or later.so.1 Linux Red Hat Linux AS2.1 or later.so.1 SUSE Linux ES9 or later.so.1 System Requirements and Installation 3-5

40 Installation Media for Windows-based Systems Table 3-3 lists and describes the FX Code Converter Installation Utility files for use with Windows systems. FX Code Converter provides these files in Windows install format (InstallShield). For information about supported operating system versions, please contact your Hitachi Data Systems representative. Table 3-3 Code Conversion Utility Files for Windows Systems File Name Contents Installation Location uoc.dll codetran.ini UOC double-byte conversion function s object (Replace with a dummy object provided by FAL/FCU) ini file used by the double-byte code conversion routine FAL/FCU boot folder(c:\fcu) HOST.tbl HOST.tbl EditOpFile Traditional Chinese Big5 conversion table Big5 Traditional conversion table Edit Option file standard table for mto conversion standard table for otm conversion ccnv.exe (Note 1) ppkeyset.exe libuoc.ver (Note 3) Executable file for the ccnv command used to customize code conversion tables for all files contained in this table. Executable file for inputting a license key code. Version information file (Stored in the Windows system directory) C:\WINDOWS uoc.c (Note 2) uocerror.h (Note 2) Standard source provided Standard header file provided File for creating user-defined UOC function that is used when not using Code Converter FAL/FCU folder \UOC(C:\FCU\UOC) uoc.mak (Note 2) Makefile uoc.dsp (Note 2) Project file uoc.def (Note 2) def file Notes: 1. Use ccnv files listed here when customizing code conversion tables, such as adding user-defined characters or characters not in the conversion table. 2. These files are not necessary when you use Code Converter. These files are stored in the subdirectory Uoc that is created under the working directory of the installation directory. 3. This file is stored in a Windows system directory (e.g., c:\windows). 3-6 System Requirements and Installation

41 Installation and Uninstallation for UNIX Systems This section discusses installation, uninstallation, and upgrade or downgrade of the FX Code Converter program using UNIX Systems. Installing for UNIX Systems To install Code Converter: 1. Log in to the open-systems server (UNIX server) as root. 2. To mount Code Converter, insert the CD into the drive. 3. Go to the working directory of the installation server, and then use the following tar command to copy all files in the installation media to the working directory. The Code Converter files listed in Table 3-1 are stored in the working directory of open systems. Enter the following, specifying the CD device file name as shown in Table 3-4. #tar xvf xxxxxx/libuoc.tar Table 3-4 OS CD Device File Names Installation Media Device File Name HP-UX or later CD (Mount point)/program/convert/main/hp_ux/ Tru64 UNIX V5.1 or later CD (Mount point)/program/convert/main/digital/ AIX or later CD (Mount point)/program/convert/main/aix/ Solaris 2.6 or later CD (Mount point)/program/convert/main/solaris/ Note: When you mount the CD, file names/directory names may not be displayed in all caps as shown in Table 3-4. You may also find a semicolon (;) plus one character, e.g., ';l', at the end of the file name. In these cases, you need to place single quotes around the file name. Check on the file name using the ls command. 4. Remove the CD for Code Converter from the drive. 5. Save libuoc.* in /user/lib under another file name. Note: Specify the file extension for your model according to Table Move the shared library to /usr/lib/: # mv -f libuoc.* /usr/lib Note: Specify the file extension for your model according to Table Move the version information file to /usr/lib/: # mv -f libuoc.ver /usr/lib Important: The FCU cannot operate unless this is done. 8. Move the inputting file for the license key to /usr/bin/: # mv -f ppkeyset /usr/bin 9. Log out, and then log in again. Code Converter is now installed. System Requirements and Installation 3-7

42 Uninstalling for UNIX Systems Note: Before uninstalling the FAL/FCU products, you must uninstall the Code Converter products. To uninstall Code Converter: 1. Log in to the open-systems server (UNIX server) as root. 2. Delete all files described in Table 3-1 by using the rm command. 3. Delete the libuoc executable files and the version information files which have been installed on the /usr/lib directory. Note: Specify the file extension for your model according to Table 3-2. # cd /usr/lib # rm libouc.* libuoc. ver 4. Rename the file that was saved under another file name at the installation procedure in Installing for UNIX Systems (step 5) to libuoc.*. The FCU cannot operate unless this is done. Specify the file extension for your model according to Table 3-2. Upgrading or Downgrading To upgrade or downgrade Code Converter: 1. Log in to the open-systems server (UNIX server) as root. 2. Copy the files within the related files that are provided by Code Converter, if a user has changed, into a working directory. 3. Edit the option file (EditOpFile). 4. Install Code Converter from CD. 5. Restore the files from step Log out, and then log in again. Code Converter is now upgraded/downgraded. 3-8 System Requirements and Installation

43 Installation and Uninstallation for Windows Systems This section discusses installation, uninstallation, and upgrade or downgrade of the FX Code Converter program on Windows systems. Installing for Windows Systems To install Code Converter: 1. Start the computer. 2. Log in as administrator. 3. Insert the CD for Code Converter into the drive. 4. Double-click setup.exe on Explorer to run the Code Converter setup file: setup.exe is in the following directory: (CD drive)\program\convert\main\win\disk1. 5. Follow the instructions displayed and enter /select user information, installation folder, program folder, etc. Specify the same FCU directory as the destination directory. 6. When the InstallShield Wizard Complete window appears, click the [Finish] button to complete the Code Converter installation. Uninstalling for Windows Systems Note: Before uninstalling the FAL/FCU products, you must uninstall the Code Converter products. To uninstall Code Converter: 1. Start the computer. 2. Log in as administrator. 3. Select [Start]-[Settings]-[Control Panel]. 4. Double-click [Add/Remove Programs]. 5. Select [Code Converter] from the list under [Removes the Change or Remove Programs], and click the [Change/Remove] button to start uninstallation. Follow the instructions displayed. 6. When the Maintenance Complete window appears, click the [Finish] button to complete the uninstallation process. System Requirements and Installation 3-9

44 Upgrading and Downgrading To upgrade or downgrade Code Converter: 1. Start the computer. 2. Log in as administrator. 3. Copy files within the related files that are provided by Code Converter, if a user has changed, in a working directory. 4. Edit the option file (EditOpFile). 5. Install Code Converter from CD. 6. Restore files from step 3 above System Requirements and Installation

45 License Key Input A license key is required for using the FX Code Converter. License Key for UNIX Systems Input the license key using the ppkeyset command. Note: When you use the AIX operating system, and you run the Code Converter program before inputting a license key, an error may occur during the ppkeyset command execution. Enter the slibclean command, and input the license key using the ppkeyset command. Input the following commands from the command line, appropriate to each operating system and platform: HP-UX: ppkeyset <License key> /usr/lib/libuoc.sl Solaris: ppkeyset <License key> /usr/lib/libuoc.so.1 AIX: ppkeyset <License key> /usr/lib/libuoc.a Tru64 UNIX: ppkeyset <License key> /usr/lib/libuoc.so License Key for Windows Systems 1. Double click the ppkeyset.exe of install directory. The following message will appear in MS-DOS window: Please enter <License key> [Installed Directory or File]... or <quit> for exit 2. Enter <license key> < Installed Directory> 3. Enter the following, if < Installed Directory> is a directory name with space : <license key> fal.dll falmt.dll The following message will appear: Please enter <License key> [Installed Directory or File]... or <quit> for exit 4. Enter quit. System Requirements and Installation 3-11

46 3-12 System Requirements and Installation

47 4 Using FX Code Converter This chapter describes the operational sequence, how users perform operations and use the functions of Code Converter. FX Code Converter User Process Flow Database Data File Record Format Using FX Code Converter 4-1

48 FX Code Converter User Process Flow Figure 4-1 illustrates the process flow for the FX Code Converter. Figure 4-1 FX Code Converter User Process Flow Code Converter process flow: 1. Confirm the record formats of the database data file to be converted. Note: When using Code Converter to perform double-byte conversions, the database data file must be a sequential access method file (SAM) with fixed-length or variable-length records. Additionally, the field positions within the records must be fixed and consistent. Confirm the record formats of the mainframe file and open-systems file. 2. Create a Field Definition file. Specify the field configuration details of the input/output record and the details of the conversion: The position of the fields to be converted, the type of conversion to be performed on those fields, how the result should be edited and output to the output record, and the length of the output field are specified. A Field Definition file is created for each record format (field configuration) found in the database data file to be converted. For each field in the input record, position, length, type of code conversion to be performed, and output length are specified in the prescribed format. 3. Use the Parameter Definition file to associate the Field Definition file. 4-2 Using FX Code Converter

49 Parameter Definition files are used to associate Field Definition files with the database data file to be converted. The Parameter Definition file is used by the File Conversion Utility to specify the database data files for mto conversion or otm conversion (a pair of mainframe SAM file and open-systems UNIX/PC file). Describe the Parameter Definition file in text file form. 4. Execute/run the File Conversion Utility. Using FX Code Converter 4-3

50 Database Data File Record Format When using Code Converter to perform conversions such as double-byte conversions, the database data file must be a sequential access method file (SAM) with fixed-length or variable-length records. In addition, the field positions within the records must be fixed and consistent. You must confirm the record formats of the mainframe file and the open-systems file. Code Converter retrieves input data from a fixed position for each record. The field position within the record and the field length must be the same for all records, as shown in Figure 4-2 and Figure 4-3 (e.g., SAM file output by the DB2 REORG utility). Figure 4-2 Field Position and Field Length Example 1 Figure 4-3 Field Position and Field Length Example 2 Figure 4-4 illustrates the record formats supported and conversion modes provided by the FX Code Converter. Figure 4-4 Record Form and Code Conversion Form Conversion 4-4 Using FX Code Converter

51 Code Conversion Using Fixed-Length Records Figure 4-5 shows the mto (mainframe-to-open) and otm (open-to-mainframe) code conversion when mainframe records and open-systems records both have fixed-length formats. Figure 4-5 Code Conversion Outline for Fixed-length Records Code Conversion Using Variable-Length Records The following actions must be performed when converting variable-length records: 1. Specify all delimiters. 2. Ensure that the total of field lengths specified in the Field Definition file equals the maximum record length of the mainframe record length (minus) Ensure that the fields specified in the Field Definition file end within the mainframe record. Note: When the last field has a variable length ( end is specified for input field length), numeric conversion cannot be performed on the field. Numeric codes (packed decimal/zoned decimal) are treated as being in fixed-length fields. Using FX Code Converter 4-5

52 Converting Variable Length Mainframe Records to Variable Length UNIX/PC Records (mto) Code conversion is performed on each field in the variable-length mainframe record, and the result is output as a variable-length UNIX/PC record. Note: Make sure to specify a delimiter in the end statement of the Field Definition file. Fixed field length: Figure 4-6 shows how mto code conversion is performed when the fields specified in the field definition statement have a fixed length (when end is not specified for the input field length). The record length of variable-length mainframe records must be short as the maximum record length (minus) 4. Figure 4-6 Code Conversion in Variable Length Records ( end not specified for field length) Record 1: Code conversion is performed on Field 1 only. Fields 2 and 3 are not processed. Record 2: Code conversion is performed on Fields 1 through 3. Record 3: Code conversion is performed on Fields 1 and 2. Field 3 is not processed. Last field = variable length: Figure 4-7 shows how otm (open-systemsto-mainframe) code conversion is performed, when the last field specified in the field definition statement has a variable length (when end is specified for the input field length). The record length of variable-length mainframe records must be short as the maximum record length Using FX Code Converter

53 Figure 4-7 Code Conversion in Variable Length Records (with end specified for field length) You can specify end in the field definition statement only when the field is the last field of the record. When end is specified, code conversion for the last field starts at the beginning of the field and ends at the end of the record. In Figure 4-7 end is specified for Field 2, indicated by the grey areas. Converting Variable-Length UNIX/PC Records to Variable-Length Mainframe Records (otm) After removing the delimiters in the variable-length UNIX/PC records, code conversion is performed on each field, and the result is output to the mainframe in variable-length record format. The output record length after conversion must equal to (the maximum record length defined for the mainframe record - 4). Fixed field length: Figure 4-8 shows how otm code conversion is performed when the fields specified in the Field Definition file have a fixed length (when end is not specified for the input field length). Delimiters are not output to the mainframe records. The record length of variablelength mainframe records must be as short as the maximum record length - 4. Using FX Code Converter 4-7

54 Figure 4-8 Overview of Code Conversion in Variable Length Records ( end not specified for field length) Record 1: Code conversion is performed on Field 1 only. Fields 2 and 3 are not processed. Record 2: Code conversion is performed on Fields 1 through 3. Record 3: Code conversion is performed on Fields 1 and 2. Field 3 is not processed. Last field = variable length: Figure 4-9 shows how otm (open-systemsto-mainframe) code conversion is performed, when the last field specified in the Field Definition file has a variable length (when end is specified for the input field length). Figure 4-9 Overview of Code Conversion in Variable Length Records (with end specified for field length) 4-8 Using FX Code Converter

55 You can specify end in the Field Definition file only when the field is the last field of the record. When end is specified, code conversion for the last field starts at the beginning of the field and ends at the end of the record. In Figure 4-9, end is specified for Field 2, indicated by the grey areas. Converting Variable Length UNIX/PC Records to Fixed Length Mainframe Records (otm) After removing the delimiters in the variable-length UNIX/PC records, code conversion is performed on each field, and the result is output to the mainframe in fixed-length record format. Padding and delimiter must be specified in the end statement of the Field Definition file. After code conversion, the extra space in the mainframe record is padded with padding code specified. The extra space in each field is filled with the field padding code specified in the Edit Option file. The total length of output fields defined in the field definition must be less than the fixed length of the mainframe record. Note: Mainframe records with padding cannot be reconverted to UNIX/PC records using mto conversion. Fixed field length: Figure 4-10 shows how otm code conversion is performed when the fields specified in the field definition statement have a fixed length (when end is not specified for the input field length). Delimiters are not output to the mainframe records. Figure 4-10 Overview of Code Conversion in Variable Length Records ( end not specified for field length) Record 1: Code conversion is performed on Field 1 only. The rest of the mainframe record is padded with a padding code. Fields 2 and 3 are not processed. Using FX Code Converter 4-9

56 Record 2: Code conversion is performed on Fields 1 through 3. Record 3: Code conversion is performed on Fields 1 and 2. The rest of the mainframe record is padded with a padding code. Field 3 is not processed. Last field = variable length: Figure 4-11 shows how otm (open-systemsto-mainframe) code conversion is performed, when the last field specified in the Field Definition file has a variable length (when end is specified for the input field length). Figure 4-11 Overview of Code Conversion in Variable Length Records (with end specified for field length) Record 1: Code conversion is performed on Field 1 only. The rest of the mainframe record is padded with a padding code. Field 2 is not processed. Record 2: Code conversion is performed on Fields 1 and 2. Record 3: Code conversion is performed on Fields 1 and 2. The rest of the mainframe record is padded with a padding code Using FX Code Converter

57 Creating a Field Definition File Create a Field Definition file to specify the position of the fields to be converted, the type of conversion to be performed on those fields, how the result should be edited and output to the output record, and the length of the output field. A Field Definition file is created for each record format (field configuration) found in the database data file to be converted. For each field in the input record, specify its position, length, type of code conversion to be performed, and output length, in the format described below. Use editors such as vi to create the Field Definition file as a text file. The maximum file size is 1,000 lines, including comments. To use the file, store it in the current directory of the open systems (UNIX/PC server). The Field Definition file consists of field definition statements, an end statement, and comments. Field Definition Statement Specify a line of field definition statement for each field in the input record in the order they appear, starting from the first field of the record (Figure 4-12). Figure 4-12 Field Definition Statement fld: Keyword (reserved word) to indicate a field definition statement. relative_byte_position: Specify a relative byte position within the record to indicate where the field begins, using a decimal value starting from 0. input_field_length: Specify the byte length of the input (source) field using a decimal value. field_attribute: Specify the type of code conversion to be performed on the field as follows: Suppress output : SKIP No code conversion: NOP Alphanumeric character conversion: CHAR:OPnn (for OPnn, see Figure 4-4). Double-byte character conversion: KANJI:OPnn (for OPnn, see Figure 4-4). Numeric conversion: NUM:OPnn (for OPnn, see Table 4-5) Using FX Code Converter 4-11

58 output_field_length: Specify the byte length of the field's output (target) area, using a decimal value. This parameter can be omitted if the length is the same as the byte length of the input field. Note: This parameter must be omitted for fields with no code conversion and fields that suppress output. If the field is the last field in the record, and if the rest of the record is included in this last input field, the byte length of the input field can be specified with end as shown below. Since you do not need to specify a specific value, this allows you to create a field definition statement/field Definition file for multiple datasets/records that is the same except the length of the last field (see Figure 4-13). Figure 4-13 Last Field In The Record End Statement end: the rest of the record from where this field begins is defined as an input field. The field length depends on the record format, as follows: Fixed-length record: (byte length of input field) = (input record length) - (relative byte position within the record) Variable-length record: (byte length of input field) = (the length after code conversion) Note: You cannot perform numeric conversion on a variable-length record field with end specified. Numeric conversion can only be performed on fixedlength records. A line of end statement is written at the end, after field definition statements are specified for all fields in the input record (Figure 4-14). Figure 4-14 End Statement end: Keyword (reserved word) to indicate that all Field definition statements have been written. Delimiter=delimiter_code: Specify a delimiter code as follows, if a delimiter is added to the end of the open-systems records: 4-12 Using FX Code Converter

59 Comments To add CR=(0D) - Delimiter=CR To add LF=(0A) - Delimiter=LF To add CRLF=(0D0A) - Delimiter=CRLF (only for Windows) Padding=padding_code: When converting variable-length open-systems records to fixed-length mainframe records, specify a padding code with a 2-digit hexadecimal character, to fill the space between the last field to convert and the end of the mainframe record. Note: When adding a delimiter, the output record length increases/decreases accordingly. Take this into consideration when specifying the output length. Note that when the input record contains binary data in addition to single-byte and/or doublebyte characters, the binary data may have data that matches the delimiter specified. This may prevent correct recognition of delimiters to isolate records. Comments can be included as necessary, within a field definition statement (at the end of the statement), or separately as a comment statement (Figure 4-15). Table 4-1 indicates the tables that show the conversion mode parameters for each field attribute. When including a comment within a field definition statement, add the comment after the required items of the statement (5 parameters). When the byte length of the output field is omitted, # can be specified in its place to indicate that subsequent data is a comment. When # is specified at the beginning of a line, the entire line is becomes a comment. Blank lines are also treated as comments. Figure 4-15 Including Comments in a Field Definition File Using FX Code Converter 4-13

60 Table 4-1 Conversion Mode Parameters by Type of Conversion and Field Attribute Type of conversion Field attribute OPnn table Suppress output SKIP - No code conversion NOP - Alphanumeric character conversion CHAR:OPnn Table 4-2 Double-byte character conversion KANJI:OPnn Numeric conversion NUM:OPnn Table 4-3 Suppress output SKIP - Conversion Modes For Open Systems Using Big5 Table 4-2 lists the attribute options for use with the Traditional Chinese Code System. Table 4-2 Field Attribute Options for the Traditional Chinese Code System Indication Parameter Of Conversion Mode When Field Is Value Table 4-3 lists the field attribute options for the numeric-based coding scheme. Table 4-3 List of Field Attribute Options for Numeric-based Coding Scheme 4-14 Using FX Code Converter

61 Figure 4-16 Example of a Field Definition File In the example in Figure 4-16 the input record length is = 1,236 bytes and the output record length is , = 2,456 plus 1 byte for delimiter, thus 2,457 bytes. The first field contains the first 294 bytes of data. Single-byte alphanumeric character conversion is performed before output. Conversion is performed according to conversion mode information for [CHAR:OP45] specified in the Edit Option file. The output field length is 588 bytes. The second field is the 16 bytes of data that follow the first field. No code conversion is performed, and data is output without any change. The output field length is 16 bytes. The third field is the 756 bytes of data that follow the second field. Singlebyte alphanumeric character conversion is performed before output. Conversion is performed according to conversion mode information for [CHAR:OP45] specified in the Edit Option file. The output field length is 1512 bytes. The fourth field is the 40 bytes of data that follow the third field. Only double-byte code conversion is performed before output. Conversion is performed according to conversion mode information for [KANJI:OP41] specified in the Edit Option file. The output field length is 80 bytes. The fifth field is the 130 bytes of data that follow the fourth field. Singlebyte alphanumeric character conversion is performed before output. Conversion is performed according to conversion mode information for [CHAR:OP45] specified in the Edit Option file. The output field length is 260 bytes. Using FX Code Converter 4-15

62 Using the Parameter Definition File to Associate Field Definition Files Parameter Definition files are used to associate Field Definition files with the database data file to be converted. The Parameter Definition file is used by the File Conversion Utility to specify the database data files for mto conversion or otm conversion (a pair of mainframe SAM file and open-systems UNIX/PC file). Add a declaration to perform user editing operations (Code Converter operations), as well as Code Converter parameters such as the Field Definition file, to the Parameter Definition file. The Parameter Definition file is also created by the user as a text file, following a prescribed format. Adding Parameters to the Parameter Definition File Add two parameters as follows: USER-EDIT: This is a reserved keyword declaring that user editing operations (Code Converter operations) are to be performed. At the end of the existing Parameter Definition file, enter one or more single-byte spaces, and then specify this keyword exactly as shown. Field Definition file name and Edit Option file name: These are the Code Converter parameters. Add./ to the name of the Field Definition file created as described in section and to the name of the Edit Option file (EditOpFile), join the two names with a, (comma), then add this after USER-EDIT in following one or more single-byte spaces. Do not enter any spaces between the Field definition file name and the Edit Option file name. Figure 4-17 shows the parameter definition file being used to associate the field definition file. Figure 4-17 Using the Parameter Definition File to Associate the Field Definition File 4-16 Using FX Code Converter

63 Edit Option File The Edit Option File defines the details for all the code conversion modes supported by Code Converter (Table 4-2, Table 4-3). It is located on the current directory of the open-systems environment (UNIX/PC server). Users may want to customize this file, such as changing the space code used for replacing the undefined character code to a special code. For this reason, a brief explanation of what is defined in the Edit Option file is presented in Figure Figure 4-18 Specifying Conversion Mode in the Edit Option File For each line in the Edit Option file, the part of the line after the necessary item (1 parameter), as well as any data following #, are treated as comments. Blank lines are also treated as comments. Using FX Code Converter 4-17

64 Figure 4-19 Including Comments in the Edit Option File Conversion Mode Format Details The Edit Option file includes conversion mode information such as those for alphanumeric character conversions and double-byte code conversions. Information appears in no particular order for every conversion mode (OPnn) used in the Field Definition file. Information for each conversion mode starts with a definition label header specified in the format [CHAR:OPnn], [KANJI:OPnn], or [NUM:OPnn], and continues until the next definition label header [xxxx:opnn] appears. The end of information is indicated with the end indicator (two characters [] ). Conversion mode parameters are specified one parameter per line, for the prescribed number of parameters as shown in Table 4-4 through Table 4-6. Parameters are specified in the order of the line number shown in these tables. Note these line numbers only count lines with effective information, and do not include lines that only contain comments. The last line contains the end indicator ( [] ), which indicates the end of the Edit Option file Using FX Code Converter

65 Table 4-4, Table 4-5, and Table 4-6 list the conversion mode parameters used by the FX Code Converter. Table 4-4 Conversion Mode Parameters for Alphanumeric Character Conversion [CHAR:OPnn] (number of parameters: 6) Conversion Mode Parameter Parameter value Description Type of code conversion mto EBCto Convert EBCDIC to ASCII otm toebc Convert ASCII to EBCDIC Tables directory Alphanumeric string Specifies where the code conversion tables are located. Conversion table name Alphanumeric string Specifies the code conversion table to use for this field. Replace code for undefined characters 2-digit hexadecimal character Specifies the code to replace undefined characters. Field padding code 2-digit hexadecimal character Specifies the code to fill the extra space in output field. Code conversion option Code conversion option Allows 0-byte length records for datasets with variable-length records in mto conversion. Allows 0-byte length records in otm conversion. This line can be omitted when not specifying TRAN_NOREC. Using FX Code Converter 4-19

66 Table 4-5 Conversion Mode Parameters for Double-Byte Code Conversion [KANJI:OPnn] (number of parameters: 9) Conversion Mode Parameter Parameter Value Description Type of code conversion mto HOSTto Convert double-byte characters from Traditional Chinese character to Big5 otm tohost Convert double-byte characters from Big5 to Traditional Chinese character Tables directory Alphanumeric string Specifies where the code conversion tables are located. Conversion table name Alphanumeric string Specifies the code conversion table to use for this field. Code conversion option Replace code for undefined single-byte characters Replace code for undefined single-byte characters Specifies the code to replace undefined double-byte characters. Double-byte field padding code TRAN_EBCDIC TRAN_SGLSPACE TRAN_DBLSPACE TRAN_START_SINGLE TRAN_START_DOUBLE TRAN_SHIFT_NO TRAN_SHIFT_SPACE TRAN_SHIFT_DBLCHAR TRAN_NOREC TRAN_NOPAD Replace code for undefined single-byte characters 4-digit hexadecimal character 2-digit hexadecimal character 4-digit hexadecimal character Single-byte code in the record Convert spaces to single-byte space code Convert spaces to double-byte space code This record starts with a single-byte character* This record starts with a double-byte character* Do not insert shift code In otm conversion, add shift code to single-byte spaces within double-byte character strings In otm conversion, add shift code to double-byte character strings.(specifies double-byte and single-byte mixture) Allows 0-byte length records for datasets with variable-length records in mto conversion. Allows 0-byte length records in otm conversion. Do not fill in field padding code for deleted SO/SI codes Replace code for undefined single-byte characters Specifies the code to replace undefined double-byte characters. Specifies the code to fill the extra space in output field when both single-byte and double-byte codes exist. Specifies the code to fill the extra space in output field when only double-byte codes exist. Single-byte/double-byte TRAN_DOUBLE This field contains double-byte codes only. TRAN_MIX This field contains both single and double-byte codes Using FX Code Converter

67 Table 4-6 Conversion Mode Parameters for Numeric Conversion [NUM:OPnn] (number of parameters: 7) Conversion Mode Parameter Parameter value Description Type of code conversion mto PACKtoCHAR ZONEtoCHAR Convert packed decimals to characters Convert zoned decimals to characters otm CHARtoPACK Convert characters to packed decimals CHARtoZONE Convert characters to zoned decimals Sign position TRAN_SIGN_F Leading sign TRAN_SIGN_E Trailing sign TRAN_SIGN_V Insert sign before effective digits(only applicable to zero suppressed fields) TRAN_SIGN_NON Unsigned Decimal digits 1-digit decimal character Specifies the number of decimal digits between0 and 9 Zero suppression Type of plus sign* Type of minus sign* All-space fields TRAN_NON_SUPPRESS TRAN_ZERO_SUPPRESS TRAN_SIGN_PLUS_C TRAN_SIGN_PLUS_A TRAN_SIGN_PLUS_E TRAN_SIGN_PLUS_F TRAN_SIGN_MINUS_D TRAN_SIGN_MINUS_B TRAN_ALLSPACE_NORMAL TRAN_ALLSPACE_ZERO Does not perform zero suppression Performs zero suppression Indicated with C (otm conversion only) Indicated with A (otm conversion only) Indicated with E (otm conversion only) Indicated with F (otm conversion only) Indicated with D (otm conversion only) Indicated with B (otm conversion only) In otm conversion, a field that only contains spaces generates an error. In mto conversion, fields that only contains 0 outputs a 0 In otm conversion, fields that only contains spaces outputs a 0 * Parameter applicable to otm conversion. In mto conversion, signs are determined automatically. Using FX Code Converter 4-21

68

69 5 Mainframe-to-Open System Character Code Conversion This chapter describes the mto character code conversion process. Overview of Character Code Conversion Alphanumeric Field conversion (CHAR:OPK4) Double-byte Character Field Conversion (KANJI:OPK1) Double Byte Character Field Conversion (KANJI:OPK2) Customizing the Code Conversion Table Mainframe-to-Open Character Code Conversion 5-1

70 Overview of Character Code Conversion The single-byte code conversion process changes code from EBCDIC to ASCII. The double-byte code conversion process is from Traditional Chinese to Big5. Code Converter provides the following types of character code conversion for each field data type, as shown in Table 5-1. Table 5-1 Code Conversion Data Types and Field Types Input field data type Character code conversion Field type and conversion mode EBCDIC EBCDIC to ASCII CHAR:OPK4 Traditional Chinese Traditional Chinese to Big5 KANJI:OPK1 EBCDIC and Traditional Chinese EBCDIC and Traditional Chinese mixture data to ASCII and Big5 code conversion KANJI:OPK2 All code conversion uses the above code conversion tables. Traditional Chinese code is converted to Big5 code type. Figure 5-1 Converting Traditional Chinese Code to Code 5-2 Mainframe-to-Open Character Code Conversion

71 Alphanumeric Field conversion (CHAR:OPK4) All specified field data convert assume single-byte code. Code conversion follows the code conversion table shown in Appendix C. The following are exceptions: Undefined character: An undefined character (valid character is not defined in the conversion table) will be replaced by X FF. Undefined characters can be replaced by a single-byte character if it is so specified in the Edit Option file. Shift code: Shift code (X 0E : double-byte code start, X 0F : single-byte start) is treated the same way as an undefined character. Mainframe-to-Open Character Code Conversion 5-3

72 Double-byte Character Field Conversion (KANJI:OPK1) All data conversion operations assume double-byte code. The following are exceptions: Undefined character: An undefined character (valid character is not defined in the conversion table) conversion will be replaced by X. An undefined character can be replaced by a double-byte character if it is so specified in the Edit Option file. Unjustified character: An unjustified character (first byte : X 41 through X 49, X 4C through X 91, X C2 through X E2 second byte : X 40 through X FD ) is treated same way as an undefined character. The space character (X 40 ) is excluded. Shift code: The shift character (X 0E : double-byte code start, X 0F : single-byte code start) is treated as a double-byte code. When performing code conversion with double-byte data following a shift code and another shift code, the data is treated as an unjustified character code. Space character: An even-numbered character (X 40 ) is converted to a Big5 double-byte space character (X A140 ). A one byte space character (X 40 ) is changed to an ASCII single-byte space character (X 20 ). When specifying TRAN_SGLSPACE in the Edit Option file, all X 40 characters are changed to single-byte space characters (X 20 ). 5-4 Mainframe-to-Open Character Code Conversion

73 Double Byte Character Field Conversion (KANJI:OPK2) Shift code is used for converting single-byte code double-byte code n. Singlebyte code conversion is same as alphanumeric field conversion (OPK4). Double-byte conversion is same as double-byte character field conversion (OPK1). The following are exceptions. Shift code: The Big5 code set does not have a shift character. The shift code character is used for converting single-byte code and double-byte code. the shift code itself is not converted. When the shift code character is input, output data length becomes shorter than the original input data length, and X FF is added for shift code characters in the output data. When specifying field padding code in the Edit Option file, padding code can be replaced with specified single-byte code. Assumption of shift code: When the first byte of a field is not a shift code, data conversion is in single-byte format. When the first character of the field is double-byte, double-byte conversion will be assumed by specifying TRAN_START_DOUBLE in the Edit Option file. Mainframe-to-Open Character Code Conversion 5-5

74 Customizing the Code Conversion Table When converting from Traditional Chinese to Big5, the FX Code Converter uses standard code conversion table shown in Table 5-2. When using userdefined characters or using anything other than standard Big5 characters, you will need to customize the Code Conversion table. Table 5-2 Big5 Code Conversion File Name Table Contents HOST Include conversion information of EBCDIC and Traditional Chinese to Big5 5-6 Mainframe-to-Open Character Code Conversion

75 6 Open-to-Mainframe Character Code Conversion This chapter describes open-system-to-mainframe (otm) character code conversion. Overview Alphanumeric Field Conversion (CHAR:OPK9) Double Byte Character Field Conversion (KANJI:OPK7) Customizing the Code Conversion Table Open-to-Mainframe Character Code Conversion 6-1

76 Overview Single-byte code conversion involves changing code from ASCII to EBCDIC. Double-byte code conversion is from Big5 to Traditional Chinese. The FX Code Converter provides the following types of character code conversion for each field data type, as shown in Table 6-1. Table 6-1 otm Code Conversion Input Field Data Type Character Code Conversion Field Type and Conversion Mode ASCII ASCII to EBCDIC CHAR:OPK9 Big5 Big5 to Traditional Chinese KANJI:OPK6 ASCII and Big5 ASCII and Big5 mixture data to EBCDIC and Traditional Chinese code conversion KANJI:OPK7 All code conversion uses specified code conversion tables. Big5 code is converted to Traditional Chinese. Figure 6-1 Converting from Code to Traditional Chinese Code 6-2 Open-to-Mainframe Character Code Conversion

77 Alphanumeric Field Conversion (CHAR:OPK9) All specified field data conversion assumes single-byte code. Code conversion follows the code conversion table shown in Table 6-2. Undefined characters are exceptions. An undefined character (a valid character is not defined in the conversion table) is a conversion is replaced by X FF. An undefined character can replace single-byte code by specifying single-byte in the Edit Option file. Open-to-Mainframe Character Code Conversion 6-3

78 Double Byte Character Field Conversion (KANJI:OPK6) All data conversion assumes double-byte code. The following are exceptions. Undefined character: Undefined characters (valid characters not defined in the conversion table) are replaced by X. Undefined characters can replace double-byte code by specifying double-byte in the Edit Option file. Unjustified character: An unjustified character (first byte: X 81 through X FE, second byte: X 40 through X 7E, X A1 through X FE ) is same as an undefined character. The space character (X 20 ) is excluded. 6-4 Open-to-Mainframe Character Code Conversion

79 Double Byte Character Field Conversion (KANJI:OPK7) Single-byte conversion is the same as alphanumeric field conversion (OPK9). Double-byte conversion is same as double-byte character field conversion (OPK6). The following is an exception. Shift code: Traditional Chinese code uses Shift code (X 0E : doublebyte code start, X 0F : single-byte code start) to convert single-byte code and double-byte code. The converted code will be no longer than the previous unconverted code because shift code is padded. When converted code is longer than the allowable record length, an error is generated. Note: when you specify TRAN_NOSHIFT in the Edit Option file, shift code is not padded. Customizing the Code Conversion Table When converting code from Big5 to Traditional Chinese, the FX Code Converter uses the standard code conversion table shown in Table 6-2. When using user-defined characters or using anything other than the standard Big5 characters, you will need to customize the code conversion table. For further information on customizing the Code Conversion table, refer to Customizing the Code Conversion Table. Table 6-2 File Name HOST Standard Code Conversion Table Table Contents Include conversion information of ASCII and Big5 to Traditional Chinese. Open-to-Mainframe Character Code Conversion 6-5

80 6-6 Open-to-Mainframe Character Code Conversion

81 7 Numeric Conversion This chapter describes the considerations involved in performing numeric value conversions. MTO Numeric Value Conversion Overview Packed Decimal Conversion (NUM:OPA1) Zoned Decimal Conversion (NUM:OPA2) Numeric Conversion 7-1

82 MTO Numeric Value Conversion Overview Numeric values are stored in mainframe systems as packed decimal or zoned decimal. The FX Code Converter provides the following types of numeric value conversion for each field data type, as shown in Table 7-1. Table 7-1 Types of Numeric Value Conversion Input Field Data Type Numeric Value Conversion Field Type and Conversion Mode Packed decimal Zoned decimal Packed decimal data converted to character data Zoned decimal data converted to character data NUM:OPA1 NUM:OPA2 Numeric value conversion output is right-aligned. If an output field is not large enough for the converted value (the effective length of the converted field is longer than the output field length), an error is generated (error code: 757). Conversely, if there is extra space in the output field (the effective length of the converted value is shorter than the output field length), the extra space preceding the effective field data is padded with 0 or a blank space(s). 7-2 Numeric Conversion

83 Packed Decimal Conversion (NUM:OPA1) Packed decimal conversion divides 1 byte of numeric (packed decimal) data in the specified field into top 4 bits and bottom 4 bits, then converts each group into 1 byte of character data, resulting in total of 2 bytes of character data. If the 1 byte of packed decimal data is out of range (top/bottom 4 bits: X A to X F ), a wrong data error is generated (error code: 760). Packed decimal conversion is performed according to the options specified in the Edit Option file. Numeric Conversion 7-3

84 Sign The bottom 4 bits in the last byte of packed decimal data contain the sign bits. Sign bits are recognized as follows: Sign bits indicating A, C, E, or F: plus Sign bits indicating B or D: minus Sign bits indicating a value other than above (0 through 9): wrong data (error code: 760) The sign is inserted into the sign position specified in the Edit Option file. Note: When the sign position is specified as unsigned, no minus sign is inserted for negative values (whose sign bits indicate B or D). Leading sign: Figure 7-1 Conversion When Leading sign is Specified Trailing sign: Figure 7-2 Conversion When Trailing Sign is Specified Insert sign before effective digits: Figure 7-3 Conversion When Insert Sign Before Effective Digits Is Specified Unsigned: Figure 7-4 Conversion When Unsigned is Specified 7-4 Numeric Conversion

85 Zero Suppression Zero suppression replaces leading zeroes preceding the effective digits in the output field with spaces. Zero suppression is performed according to the option specified in the Edit Option file. Zeroes are suppressed in relation to sign position, as shown in the following examples. No zero suppression, Leading Sign: Figure 7-5 Conversion When No zero suppression, Leading sign is Specified Zero suppression, Trailing sign: Packed decimal conversion Character data D (SP) (SP) Zero suppression Effective field length Figure 7-6 Conversion When Zero suppression, Trailing sign is Specified Decimal Point A decimal point is inserted according to the number of decimal point specified in the Edit Option file. When 0 is specified, there will be no decimal point, and no decimal point is inserted. Decimal point: 3, Zero suppression, Insert sign before effective digits: Figure 7-7 Conversion for Decimal Point = 3, Zero suppression and Trailing sign Specified Numeric Conversion 7-5

86 Decimal point: 0, No zero suppression, Unsigned: Figure 7-8 Conversion for Decimal Point = 0, No zero suppression and Unsigned Specified All-space Fields All-space fields contain only spaces (all data is X 40 ) unconditionally generate a data error (error code: 760). 0-only fields: Fields that contain only 0 are converted according to the Allspace field option in the Edit Option file. When the option to convert 0 in 0- only fields to 0 (TRAN_ALLSPACE_NORMAL) is specified, 0 is converted to 0 as in normal numeric value conversions. When the option to convert 0 in 0-only fields to spaces (TRAN_ALLSPACE_ZERO) is specified, all 0's are converted to spaces (X 20 ), as shown in Figure 7-9. The sign position, zero suppression, and the number of decimal point specified in the Edit Option file, as well as the sign of the input data, are ignored. Figure 7-9 Conversion of 0 in a 0-only Field to Spaces 7-6 Numeric Conversion

87 Zoned Decimal Conversion (NUM:OPA2) Sign Zoned decimal conversion takes 1 byte of numeric (zoned decimal) data in the specified field and converts the bottom 4 bits into 1 byte of character data. If the 1 byte of zoned decimal data is out of range (bottom 4 bits: X'A to X'F), a data error is generated (error code: 760). Zoned decimal conversion is performed according to the options specified in the Edit Option file. The bottom 4 bits in the last byte of zoned decimal data contain the sign bits. Sign bits are recognized as follows: Sign bits indicating A, C, E, or F: plus Sign bits indicating B or D: minus Sign bits indicating a value other than above (0 through 9): wrong data (error code: 760) The sign is inserted into the sign position specified in the Edit Option file. Note: when the sign position is specified as unsigned, no minus sign is inserted for negative values (whose sign bits indicate B or D). Leading Sign: Figure 7-10 Conversion When Leading sign is Specified Trailing sign: Figure 7-11 Conversion When Trailing sign is Specified Insert sign before effective digits: Figure 7-12 Conversion When Insert sign before effective digits is Specified Numeric Conversion 7-7

88 Unsigned: Figure 7-13 Conversion When Unsigned is Specified Zero Suppression Zero suppression replaces leading zeroes preceding the effective digits in the output field to spaces. Zero suppression is performed according to the option specified in the Edit Option file. Zeroes are suppressed in relation to sign position, as shown in the examples that follow. No zero suppression, Leading Sign: Figure 7-14 Conversion When No zero suppression, Leading sign is Specified Zero suppression, Trailing sign: Figure 7-15 Conversion When Zero suppression, Trailing sign is Specified 7-8 Numeric Conversion

89 Decimal Point A decimal point is inserted according to the number of decimal point specified in the Edit Option file. When 0 is specified, there will be no decimal point, and no decimal point is inserted. Decimal point: 3, Zero suppression, Insert sign before effective digits: Figure 7-16 Conversion for Decimal Point = 3, Zero suppression and Insert before effective digits Specified Decimal point: 0, No zero suppression, Unsigned: Figure 7-17 Conversion for Decimal Point = 0, No zero suppression and Unsigned Specified All-space Fields 0-only Fields Fields that only contain spaces (all data is X 40 ) unconditionally generates a data error (error code: 760). Fields that contain only 0 are converted according to the All-space field option in the Edit Option file. When the option to convert 0 in 0-only fields to 0 (TRAN_ALLSPACE_NORMAL) is specified, 0 is converted to 0 as in normal numeric value conversions. When the option to convert 0 in 0-only fields to spaces (TRAN_ALLSPACE_ZERO) is specified, all 0's are converted to spaces (X 20 ), as shown in Figure The sign position, zero suppression, and the number of decimal digits specified in the Edit Option file, as well as the sign of the input data, is ignored. Numeric Conversion 7-9

90 Figure 7-18 Conversion of 0 in a 0-only Field to Spaces 7-10 Numeric Conversion

91 8 Customizing the Code Conversion Table This chapter describes the procedures for customizing the code conversion table for use with your specific conversion requirements. Operation Overview Utility Features Definition Statement Syntax Command Syntax for UNIX Systems Command Syntax for Windows Systems Examples of the ccnv Utility Customizing the Code Conversion Table 8-1

92 Operation Overview Figure 8-1 illustrates the code conversion table customization process. Figure 8-1 Overview of the ccnv Utility 8-2 Customizing the Code Conversion Table

93 Utility Features The ccnv utility provides features necessary to customize code conversion tables. These are described below: Table customization: Customizes the specified code conversion table according to the user's customization information (definition statements) specified by the user. The standard code conversion table cannot be modified. This feature is also used for conversion of user-defined characters. See the example in section 10.5 for details. Table information output: Outputs information on the code conversion table such as the type of conversion, creation date, and date last modified. Table dump output: Outputs code conversion table dump results to a file. The contents of this dump output only concerns the codes, and do not include internal information such as header information contained in the code conversion table. The resulting file name is the code conversion table name with.dmp appended to the end as the file extension. Standard table generation: Re-generates the standard code conversion table provided. Use this feature when the standard code conversion table is modified or deleted unintentionally or by hard disk failures. Customizing the Code Conversion Table 8-3

94 Definition Statement Syntax This section describes the syntax of the definition statement used by the ccnv utility command to customize the code conversion table. Definition Statement Syntax Rules Use single-byte alphanumeric characters to specify the definition statement (except comments). Types of definition statements (Table 8-1): Table 8-1 Definition Statements Definition Statement NAME statement TYPE statement CODE statement Code customization statement Comments Description Specifies name of the code conversion table to customize. Specifies the type of conversion to customize. Specifies the character code to customize. Specifies how the character code is converted. Enter comments. Start position of the definition statement: Although there are no rules regarding the start position, it is recommended to keep the statement on one line, within 120 columns. Order of definition statements: The definition statements must be specified in the order shown in Figure 8-2. Figure 8-2 Order of Definition Statements 8-4 Customizing the Code Conversion Table

95 Definition Statement Details NAME statement Syntax: NAME=code_conversion_table_name_to_generate Parameters: Specify the code conversion table name to generate in alphanumeric characters. The maximum length is 255 characters, and the name must begin with an alphabet. When modifying an existing code conversion table and not creating a new one, specify *. TYPE statement Syntax: TYPE=type_of_conversion Parameters: Specify the type of code conversion to customize. Table 8-2 shows the options that can be specified. Table 8-2 Syntax Options Option HOSTto tohost Description Customize the code conversion table to convert Traditional Chinese to Big5 Customize the code conversion table to convert Big5 to Traditional Chinese CODE statement Syntax: CODE=type_of_code Parameters: Specify the type of code to customize. When none is specified, it is assumed from the type of conversion in the code conversion table passed by the -t option of the ccnv utility command. Table 8-3 shows the options that can be specified in the CODE statement. Table 8-3 CODE Statement Options Type of Conversion Option Description HOSTto T_HOST Customize table for Traditional Chinese code EBCDIC Customize table for EBCDIC code tohost Customize table for Big5 code ASCII Customize table for ASCII code Customizing the Code Conversion Table 8-5

96 Code customization statement Syntax: Code_to_convert:Converted_code When specifying more than one code, separate them with a comma (,). There are no rules regarding the columns to define the parameters, but each pair must be separated with a comma (,) or a line break. Parameters: Specify code_to_convert from the code conversion table with hexadecimal. Specify the desired code after conversion in converted_code, also using hexadecimal. Table 8-4 shows the range of values that can be specified. Note that specifying any value outside this range generates an error. Table 8-4 Range of Values Code Valid values EBCDIC 0x00 0xFF ASCII 0x00 0xFF T_HOST First byte: 0x41 0x49, 0x4C 0x91, 0xC2 0xE2 Second byte: 0x41 0x7F, 0x81 0xFD0x4180 First byte: 0x81 0xFE Second byte: 0x40 0x7E, 0xA1 0xFE 8-6 Remarks Shift code raises an error Value outside the valid range is an error Value outside the valid is raises an error Comments: Enter comments. Syntax: #Comments Parameters: Anything entered between # and line break is treated as a comment. Customizing the Code Conversion Table

97 Command Syntax for UNIX Systems Use the ccnv command to customize code conversion tables. The syntax rules for the ccnv command are described below. ccnv command: Syntax: ccnv [option] definition_statement_file_name ( indicates a single-byte space) Parameters: Specify the name of the definition statement file that defines the customization of the code conversion table. The file name must include the file extension.txt. When there is no file extension, an error message indicating that definition statements cannot be found is displayed. Command options: D -d dir: Specify the output directory for the code conversion table in dir. Note: This option can be used with other options for file output. L -l: Definition statements specified are additionally output to the result list. When this option is specified, lines with errors are output directly above the error message, and making corrections becomes easier. P -p: The generated code conversion table is dumped as a character based file. The table is output to the current directory where the command is executed, with a file name that includes the Code Conversion name and the file extension changed to.dmp. Use this file to review the customized table. T -t: Specifies the code conversion table name to customize. This option can be omitted when executing customization. It defaults to the standard table for the type of conversion specified in the definition statement. -I -I: Outputs code conversion table information such as the creation date and date last modified to standard output. Customizing the Code Conversion Table 8-7

98 Command Syntax for Windows Systems Use the ccnv.exe utility to customize code conversion tables. This section describes the use of this utility (Figure 8-3). Figure 8-3 Using the ccnv Utility with Windows Systems 1. Execute customizing: Select the [Customize] button after selecting the conversion table file and the definition statement file. 2. Output table information: Select the [Table Information] button; the generated date and history will be displayed. 3. Output table dump: Select the [Table Dump] button, and then execute WordPad; a dump of the conversion table will be displayed. 4. Create Standard Table: Select the [Create Standard Table] button, then select Create standard conversion table. 8-8 Customizing the Code Conversion Table