WIXLIB

Chapter 2Installing the Cobol Copybook ConverterThis chapter describes how to install the Cobol Copybook Converter.What’s in This Chapter Supported Operating Systems on page 10 System Requirements on page 10 Installing the Product Files on page 11 After You Install on page 112.1Supported Operating SystemsThe Cobol Copybook Converter supports Japanese data and is available for thefollowing operating systems: Windows 2000 Windows XP Windows 2000 Japanese Windows XP Japanese2.2System RequirementsThe system requirements for the Cobol Copybook Converter are the same as for eGateIntegrator. For information, refer to the eGate Integrator Installation Guide. Additionalsystem requirements include: The system where the Cobol Cobybook Converter is installed needs approximately20 MB of free disk space for the application and its configuration, library, and scriptfiles. Cobol Copybook Converter 5.0.4 requires a 5.0.4 or higher version of the logicalhost.Cobol Copybook Converter User’s Guide10SeeBeyond Proprietary and Confidential

Chapter 2Installing the Cobol Copybook Converter2.3Section 2.3Installing the Product FilesInstalling the Product FilesDuring the eGate Integrator installation process, the Enterprise Manager, a web-basedapplication, is used to select and upload products as .sar files from the eGateinstallation CD-ROM to the Repository.The installation process includes installing the following components: Installing the Repository Uploading products to the Repository Downloading components (such as Enterprise Designer and Logical Host) Viewing product information home pagesFollow the instructions for installing the eGate Integrator in the SeeBeyond ICAN SuiteInstallation Guide, and include the following steps:1 After uploading the eGate.sar file (using Enterprise Manager) select and upload thefollowing files as described in the SeeBeyond ICAN Suite Installation Guide: CobolCopyBook.sar (to install the Cobol Copybook Converter) FileeWay.sar (to install the File eWay, used in the sample Projects) CobolCopyBookDocs.sar (to install the user’s guide and the sample Projects)2 In the Enterprise Manager, click the DOCUMENTATION tab.3 Click Cobol Copybook Converter.4 In the right-hand pane, click Download Sample, and select a location for the .zipfile to be saved.For information about importing and using the sample, refer to Locating,Importing, and Using the Sample Projects on page 26.2.4After You InstallUpon successful completion of the required files and documentation installation, openthe readme file included with the Cobol Copybook Converter documentation SAR file.This file contains information about patches or ESRs that may be required to run theCobol Copybook Converter or to run project sample files that use the Cobol CopybookConverter.After ensuring you have all the required Cobol Copybook Converter patches or ESRs,you must then incorporate the Cobol Copybook Converter into an eGate Project andEnvironment in Enterprise Designer. The next chapters describe how to incorporate theCobol Copybook Converter into an eGate Project and an eGate Environment, as well asconfiguring it and building the necessary OTDs.Cobol Copybook Converter User’s Guide11SeeBeyond Proprietary and Confidential

Chapter 3Using the OTD WizardThis chapter describes how to build the business logic for Cobol Copybook ConverterProjects. Project business logic is contained in Business Processes for eInsight, and inCollaborations for eGate Integrator used without eInsight.To build Cobol Copybook Project business logic, you use the Cobol Copybook wizardto create the Cobol Copybook Converter OTD. You then create the Business Processesor Collaborations, and the Connectivity Maps.What’s in This Chapter About the Cobol Copybook Wizard on page 12 Creating Cobol Copybook OTDs on page 12 Cobol Copybook OTD on page 15 Cobol Copybook OTD Methods on page 163.1About the Cobol Copybook WizardYou use the Cobol Copybook wizard to create copybook converter OTDs. These OTDscan then later be used in Collaboration Definitions to create the business logic behindthe Collaborations.3.2Creating Cobol Copybook OTDsYou create Cobol Copybook Converter OTDs with the Cobol Copybook wizard in theEnterprise Designer.To create Cobol Copybook OTDs1 In the Explorer tab of the Enterprise Designer, right-click %Project Name% New Object Type Definition. The New Object Type Definition Wizard dialog boxappears.2 Click Cobol Copybook and click Next. The Select Cobol Copybook Files pageappears.Cobol Copybook Converter User’s Guide12SeeBeyond Proprietary and Confidential

Chapter 3Using the OTD WizardSection 3.2Creating Cobol Copybook OTDsFigure 2 Cobol Copybook Wizard—Cobol Copybook Selection3 Browse for the desired Cobol Copybook file and highlight it.4 Click the Add button to include a copybook file in a project.5 Repeat Steps 3 and 4 for each file to include in the project.6 To remove a copybook file from the project, highlight the file name in the SelectFiles container and click Remove.7 Click Next. The Declare Copybook Encodings page appears only if the ExtendedLanguage Option, in the Options menu, has been selected.Cobol Copybook Converter User’s Guide13SeeBeyond Proprietary and Confidential

Chapter 3Using the OTD WizardSection 3.2Creating Cobol Copybook OTDsFigure 3 Cobol Copybook Wizard—Declare Copybook Encodings8 Select the charset encoding, from the drop-down list, to be used by each input(copybook) file.9 Click Next. The Configure Converter Options page appears.Figure 4 Cobol Copybook Wizard—Configure Converter OptionsCobol Copybook Converter User’s Guide14SeeBeyond Proprietary and Confidential

Chapter 3Using the OTD WizardSection 3.3Cobol Copybook OTD10 Optionally, add/remove checks from boxes to enable/disable options: Ignore copybook content beyond column 72 -- The converter expectscopybooks to be width-compliant with IBM’s Cobol reference format. Uncheckthis box to process books with content (excluding comments/line numbers)beyond column 72. Default: enabled (box is checked). Check Item names against reserved words -- The converter disallows data itemnames that match reserved words. Uncheck this box to process copy books thatuse reserve words for item names. When name checking is disabled, theconverter cannot process copy books with unnamed items (i.e., implicit‘FILLER’ items). Default: enabled (box is checked).11 Click Finish. The OTD Editor window appears, displaying the OTD.The section below describes the cobol copybook methods (operations) that are availablefor you to use in the source code for the Collaborations or Business Activities.3.3Cobol Copybook OTDWhen an OTD is built from a copybook file (as is the Sample copybook file) it creates anOTD which contains methods that may be used with the converted contents of thecopybook business object.Figure 5 Sample Copybook OTDThe figure above shows the copybook converter OTD. The OTD has a node for each ofthe business processes that may be performed on the converted copybook. Theunmarshal method allows business processes to flow data into the copybook OTDs andaccess contents field-by-field.Cobol Copybook Converter User’s Guide15SeeBeyond Proprietary and Confidential

Chapter 3Using the OTD Wizard3.4Section 3.4Cobol Copybook OTD MethodsCobol Copybook OTD MethodsThe Object Type Definitions (OTDs) created by the Cobol Copybook Converter providethe method that you can use to extract or insert content into OTDs. “OTD Method Guidelines” on page 16 “Root-level Methods” on page 17 “Non-Root Methods” on page 243.4.1OTD Method GuidelinesThis section addresses the concerns of global behavior, effects, and assumptionsinherent to most methods.Encoding Behavior for RedefinitionsThe unmarshal and marshal methods of a Cobol Copybook OTD (with the exception ofthe marshalToString and unmarshalFromString) have been reimplemented to heed theOTD structure's data type information. When data flows into or out of the OTD,character set encoding is applied only to the portions of the data that fall on or drawfrom OTD fields corresponding to items in the Copybook specification that storecharacter data (i.e., usage display items, whether implicitly or explicitly specified). Datafor other types of OTD fields are not subject to charset encoding, since these fields arecapable of containing binary (non-character) data.An ambiguity arises when an OTD field, corresponding to a usage display item, is alsothe object of redefinition(s) in the Copybook. Redefined items may have alternate,multiple storage types, and to deal with such an item, the OTD must decide which oneof the multiple definition is in effect at the time of unmarshaling or marshaling, inrelation to the available data. The current implementation of Cobol Copybook OTDsresolve this ambiguity by ignoring redefinitions. The decision whether or not to applyencoding to a field is based solely on the item's original storage specification in theCopybook.DBCS ItemsCobol Copybook OTDs do not support any particular DBCS encoding. When insertedinto DBCS nodes, it will not perform inspections of data to determine what specificDBCS encoding is used by character codes or byte sequences (e.g., discerning between adouble-byte and a multi-byte encoding). As a consequence: DBCS items are represented in the OTD by Java byte array nodes, and their contentwill be treated as binary "blobs" with the following rules: If content is set directly to a DBCS node, it is stored as-is. If the content is retrieved directly from the DBCS node, the content that wasoriginally set is also returned as-is. If content is unmarshaled via the OTD root, the portion corresponding to theDBCS node is stored as-is. It should be noted however, that correctness of theCobol Copybook Converter User’s Guide16SeeBeyond Proprietary and Confidential

Chapter 3Using the OTD WizardSection 3.4Cobol Copybook OTD Methodsaggregate input is the responsibility of the root-level unmarshal call (e.g., do notuse unmarshalFromString if the OTD contains DBCS items). If the OTD's content is marshaled, the portion corresponding to the DBCS nodeis yielded as-is, and is excluded from any character set transcoding thatcharacter data nodes of the OTD may be subjected to. Copybook OTDs will not auto-truncate DBCS data. Since the OTD cannot know thespecific DBCS encoding of the data, it cannot correctly truncate it at the correctcharacter boundaries. If the content which is set directly to a DBCS node exceedsthe item's width, the OTD will raise an exception.3.4.2.Root-level MethodsThe following methods are the root-level methods provided: “enableUnmarshalValidation(boolean enable)” “marshal()” “marshal(String charset)” “marshal(OtdOutputStream out)” “marshal(OtdOutputStream out, String charset)” “marshalToString()” “reset()” “resetHigh()” “resetLow()” “retrieveEncoding()” “unmarshal(byte[] in)” “unmarshal(OtdInputStream in)” “unmarshal(OtdInputStream in, String charset)” “unmarshal(byte[] in, String charset)” “unmarshalFromString(String in)” “useEncoding(String enc)”enableUnmarshalValidation(boolean enable)Causes the OTD to validate data flow during an unmarshal call.Syntaxvoid enableUnmarshalValidation(boolean enable)Throwsnone.Cobol Copybook Converter User’s Guide17SeeBeyond Proprietary and Confidential

Chapter 3Using the OTD WizardSection 3.4Cobol Copybook OTD MethodsExamples// enable validation during unmarshal// call to unmarshal may raise an exception if content is not compatiblebyte[] content .OTD 1.enableUnmarshalValidation(true);OTD 1.unmarshal(content);// disable validation during unmarshal// call to unmarshal will not raise data-related exceptions// instead, data-related exceptions may/will occur when// accessing specific nodes with invalid data.byte[] content .OTD 1.enableUnmarshalValidation(false);OTD 1.unmarshal(content);marshal()Serializes the OTD’s content as an array of bytes. The content is encoded with theOTD's current encoding, which is the encoding specified when data was lastunmarshaled (see setEncoding() and unmarshal() for additional details). If no data wasunmarshaled prior to a marshal call, then the OTD defaults to EBCDIC CP037encoding. If the OTD content is incompatible with the current encoding (this canhappen when data was unmarshaled with a different encoding that the current one), acom.stc.otd.runtime.MarshalException occurs.Syntaxbyte [] marshal()ThrowsMarshalException, IOException, UnsupportedEncodingExceptionExamples// populate OTD and marshal entire content in EBCDICOTD 1.setField1(.OTD 1.setField2(.byte[] output OTD 1.marshal();// write ASCII data to OTD// edit some fieldsCobol Copybook Converter User’s Guide18SeeBeyond Proprietary and Confidential

Chapter 3Using the OTD WizardSection 3.4Cobol Copybook OTD Methods// marshal OTD data (still ASCII)byte[] content .OTD 1.unmarshal(content, "US-ASCII");OTD 1.setField9(.OTD 1.setField10(.byte[] output OTD 1.marshal();// write ASCII data to OTD// edit some fields// marshal OTD data using different encoding (may fail depending on data)byte[] content .OTD 1.unmarshal(content, "US-ASCII");OTD 1.setField9(.OTD 1.setField10(.OTD 1.useEncoding("CP277");byte[] output OTD 1.marshal();marshal(String charset)This method serializes the content of the OTD as an array of bytes. The content isencoded using the user-specified character set. The encoding specified in this call actsas a temporary override to the OTD's current encoding, but does not become thecurrent encoding (see setEncoding and unmarshal documentation for information). Ifthe OTD content is not compatible with the current encoding (this can happen if datawas unmarshaled using an encoding different from the current one),com.stc.otd.MarshalException occurs. If the specified charset value does not name asupported character set, a java.io.UnsupportedEncodingException is generated.Syntaxbyte[] marshal(String charset)ThrowsMarshalException, IOException, UnsupportedEncodingExceptionExamplesbyte[] content cocoOtd.marshal("cp037"); // retrieve OTD content as EBCDIC databyte[] content cocoOtd.marshal("US-ASCII"); // retrieve OTD content as ASCII datamarshal(OtdOutputStream out)This method serializes the content of the OTD and writes it to the supplied outputstream object. The output is encoded using the same user-specified encoding usedwhen the data was last unmarshaled (see setEncoding and unmarshal documentationCobol Copybook Converter User’s Guide19SeeBeyond Proprietary and Confidential

Chapter 3Using the OTD WizardSection 3.4Cobol Copybook OTD Methodsfor additional details). If no data was unmarshaled prior to the call to marshal, thenEBCDIC CP037 encoding is used. If the OTD content is not compatible with the currentencoding (this can happen if the data was unmarshaled using an encoding differentfrom the current one), com.stc.otd.MarshalException occurs. A java.io.IOException isgenerated if an output error occurs in attempting to write data to the stream object.Syntaxvoid marshal(OtdOutputStream out)ThrowsMarshalException, IOException, m out, String charset)This method flows data out from the OTD to the supplied stream object, using thespecified charset encoding. The given encoding acts as a temporary override to theOTD's current encoding, it does not become the current encoding (see setEncoding andunmarshal documentation for information).If the specified charset is not compatible with the OTD content (this can happen whenthe data was unmarshaled to the OTD using a different encoding),com.stc.otd.runtime.MarshalException occurs. If the encoding is not supported orrecognized, java.io.UnsupportedEncodingException is generated.Syntaxvoid marshal(OtdOutputStream stream, String charset)ThrowsMarshalException, IOException, UnsupportedEncodingExceptionmarshalToString()This method serializes the content of the OTD to a String object. The String is created bydecoding the byte data with the OTD's current encoding, which is the encodingspecified when data was last unmarshaled (see setEncoding and unmarshaldocumentation for additional details). If no data was unmarshaled prior to a marshalcall, then the OTD defaults to EBCDIC CP037 encoding. Only use this method withcopybook OTDs built from copybooks comprised solely of usage display entries. Usingthis method on OTDs designed to hold binary data (e.g., packed decimal, internaldecimal) may invalidate the data, because portions of the binary content may not havea suitable mapping to UTF-8. A java.io.UnsupportedEncodingException may occur ifthe current encoding (i.e., the encoding used by the last unmarshal call) is not capableof encoding the data. This is possible because certain charset encodings in Java are nottwo-way encodings (encodings that can decode or encode, but not both).SyntaxString marshalToString()ThrowsMarshalException, IOException, UnsupportedEncodingExceptionCobol Copybook Converter User’s Guide20SeeBeyond Proprietary and Confidential

Chapter 3Using the OTD WizardSection 3.4Cobol Copybook OTD Methodsreset()Initializes the storage space of the OTD as follows: alphanumeric fields (PIC X) - blank spaces (EBCDIC value 0x40) numeric fields (PIC 9) - binary zero packed decimal fields - signed-trailing packed binary zeroSyntaxvoid reset()ThrowsnoneresetHigh()Initializes the entire storage space of the OTD to high bit values; each byte is initializedto 0xFF.Syntaxvoid resetHigh()ThrowsnoneresetLow()Initializes the OTD storage space to low bit values; each byte is initialized to 0x0.Syntaxvoid resetLow()ThrowsnoneretrieveEncoding()Returns the canonical name of the current OTD encoding. The default current OTDencoding is "CP037" until it is changed by a successful useEncoding call, or by a call toone of the encoding-specifiable unmarshal methods. The canonical name may differfrom the one used previously to set the current encoding. See the Java 2 APIdocumentation for java.nio.charset. Charset for more information.SyntaxString retrieveEncoding()ThrowsnoneCobol Copybook Converter User’s Guide21SeeBeyond Proprietary and Confidential

Chapter 3Using the OTD WizardSection 3.4Cobol Copybook OTD Methodsunmarshal(byte[] in)Deserializes the given input into an internal data tree. Data flowed to the OTD usingthis method must use EBCDIC CP037 encoding. This method sets the OTD's currentencoding to EBCDIC CP037, which is used when data is subsequently

Note: The Cobol Copybook Converter must have valid COBOL syntax to complete an accurate conversion. The Cobol Copybook Converter performs limited syntax validation on an input copybook. To ensure a functional OTD conversion, verify that the copybook supplied to the converter is well-formed and valid. 1.2.1 Unsupported Features