BEA WebLogic XML/Non-XML Translator

Transcription

1 BEA WebLogic XML/No-XML Traslator A Compoet of BEA WebLogic Itegratio User Guide BEA WebLogic XML/No-XML Traslator Release 2.0 Documet Editio 2.0 July 2001

2 Copyright Copyright 2001 BEA Systems, Ic. All Rights Reserved. Restricted Rights Leged This software ad documetatio is subject to ad made available oly pursuat to the terms of the BEA Systems Licese Agreemet ad may be used or copied oly i accordace with the terms of that agreemet. It is agaist the law to copy the software except as specifically allowed i the agreemet. This documet may ot, i whole or i part, be copied photocopied, reproduced, traslated, or reduced to ay electroic medium or machie readable form without prior coset, i writig, from BEA Systems, Ic. Use, duplicatio or disclosure by the U.S. Govermet is subject to restrictios set forth i the BEA Systems Licese Agreemet ad i subparagraph (c)(1) of the Commercial Computer Software-Restricted Rights Clause at FAR ; subparagraph (c)(1)(ii) of the Rights i Techical Data ad Computer Software clause at DFARS , subparagraph (d) of the Commercial Computer Software--Licesig clause at NASA FAR supplemet ; or their equivalet. Iformatio i this documet is subject to chage without otice ad does ot represet a commitmet o the part of BEA Systems. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. FURTHER, BEA Systems DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE, OR THE RESULTS OF THE USE, OF THE SOFTWARE OR WRITTEN MATERIAL IN TERMS OF CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE. Trademarks or Service Marks BEA, WebLogic, Tuxedo, ad Jolt are registered trademarks of BEA Systems, Ic. How Busiess Becomes E-Busiess, Operatig System for the Iteret, Liquid Data, BEA WebLogic E-Busiess Platform, BEA Builder, BEA Maager, BEA elik, BEA Campaig Maager for WebLogic, BEA WebLogic Commerce Server, BEA WebLogic Persoalizatio Server, BEA WebLogic Process Itegrator, BEA WebLogic Collaborate, BEA WebLogic Eterprise, BEA WebLogic Server, ad BEA WebLogic Itegratio are trademarks of BEA Systems, Ic. All other trademarks are the property of their respective compay. BEA WebLogic XML/No-XML Traslator User Guide Documet Editio Part Number Date Software Versio 2.0 July 2001 BEA WebLogic XML/No-XML Traslator 2.0

3 About This Documet This documet describes BEA WebLogic XML/No-XML Traslator, hereafter referred to as XML Traslator, ad provides istructios for usig it to traslate data from biary format to XML ad from XML to biary format. This documet covers the followig topics: BEA WebLogic XML/No-XML Traslator Overview Buildig Format Defiitios Testig Format Defiitios Usig the Ru-Time Compoet Supported Data Types Glossary What You Need to Kow This documet is iteded maily for applicatio programmers ad techical aalysts who perform data traslatios from biary to XML ad XML to biary. BEA WebLogic XML/No-XML Traslator User Guide iii

4 e-docs Web Site BEA product documetatio is available o the BEA corporate Web site. From the BEA Home page, click o Product Documetatio or go directly to the e-docs Product Documetatio page at How to Prit the Documet You ca prit a copy of this documet from a Web browser, oe file at a time, by usig the File Prit optio o your Web browser. A PDF versio of this documet is available o the BEA WebLogic XML/No-XML Traslator documetatio Home page o the e-docs Web site (ad also o the documetatio CD). You ca ope the PDF i Adobe Acrobat Reader ad prit the etire documet (or a portio of it) i book format. To access the PDFs, ope the BEA WebLogic XML/No-XML Traslator documetatio Home page, click the PDF files butto ad select the documet you wat to prit. If you do ot have the Adobe Acrobat Reader, you ca get it for free from the Adobe Web site at Related Iformatio The followig BEA publicatios are also available: BEA WebLogic XML/No-XML Traslator Istallatio Guide BEA WebLogic XML/No-XML Traslator Gettig Started Guide BEA Format Builder olie help system iv BEA WebLogic XML/No-XML Traslator User Guide

5 Cotact Us! Your feedback o the BEA WebLogic XML/No-XML Traslator documetatio is importat to us. Sed us at docsupport@bea.com if you have questios or commets. Your commets will be reviewed directly by the BEA professioals who create ad update the BEA WebLogic XML/No-XML Traslator documetatio. I your message, please idicate that you are usig the documetatio for the BEA WebLogic XML/No-XML Traslator 2.0 release. If you have ay questios about this versio of BEA WebLogic XML/No-XML Traslator, or if you have problems istallig ad ruig BEA WebLogic XML/No-XML Traslator, cotact BEA Customer Support through BEA WebSupport at You ca also cotact Customer Support by usig the cotact iformatio provided o the Customer Support Card, which is icluded i the product package. Whe cotactig Customer Support, be prepared to provide the followig iformatio: Your ame, address, phoe umber, ad fax umber Your compay ame ad compay address Your machie type ad authorizatio codes The ame ad versio of the product you are usig A descriptio of the problem ad the cotet of pertiet error messages Documetatio Covetios The followig documetatio covetios are used throughout this documet. Covetio boldface text Item Idicates terms defied i the glossary. BEA WebLogic XML/No-XML Traslator User Guide v

6 Covetio Ctrl+Tab italics moospace text moospace boldface text moospace italic text UPPERCASE TEXT Item Idicates that you must press two or more keys simultaeously. Idicates emphasis or book titles. Idicates code samples, commads ad their optios, data structures ad their members, data types, directories, ad file ames ad their extesios. Moospace text also idicates text that you must eter from the keyboard. Examples: #iclude <iostream.h> void mai ( ) the poiter psz chmod u+w * \tux\data\ap.doc tux.doc BITMAP float Idetifies sigificat words i code. Example: void commit ( ) Idetifies variables i code. Example: Strig expr Idicates device ames, eviromet variables, ad logical operators. Examples: LPT1 SIGNON OR { } Idicates a set of choices i a sytax lie. The braces themselves should ever be typed. [ ] Idicates optioal items i a sytax lie. The brackets themselves should ever be typed. Example: buildobjcliet [-v] [-o ame ] [-f file-list]... [-l file-list]... vi BEA WebLogic XML/No-XML Traslator User Guide

7 Covetio Item Separates mutually exclusive choices i a sytax lie. The symbol itself should ever be typed.... Idicates oe of the followig i a commad lie: That a argumet ca be repeated several times i a commad lie That the statemet omits additioal optioal argumets That you ca eter additioal parameters, values, or other iformatio The ellipsis itself should ever be typed. Example: buildobjcliet [-v] [-o ame ] [-f file-list]... [-l file-list] Idicates the omissio of items from a code example or from a sytax lie. The vertical ellipsis itself should ever be typed. BEA WebLogic XML/No-XML Traslator User Guide vii

8 viii BEA WebLogic XML/No-XML Traslator User Guide

9 Cotets About This Documet What You Need to Kow... iii e-docs Web Site... iv How to Prit the Documet... iv Related Iformatio... iv Cotact Us!...v Documetatio Covetios...v 1. BEA WebLogic XML/No-XML Traslator Overview Uderstadig XML Traslatio What is XML Traslator? The Desig-Time Compoet The Ru-Time Compoet Ru-Time Plug-I to WebLogic Process Itegrator Post Traslatio Optios ad Cosideratios Performig XML Trasformatio Workig with BEA WebLogic Process Itegrator Gettig Started with the BEA WebLogic XML/No-XML Traslator Buildig Format Defiitios Uderstadig the Data Formats Used with XML Traslator About Biary Data (No-XML Data) About XML Documets About MFL Documets Aalyzig the Data to be Traslated Usig the Format Builder Startig Format Builder BEA WebLogic XML/No-XML Traslator User Guide ix

10 Usig the Format Builder Mai Widow Creatig a Message Format Creatig a Group Creatig a Field Creatig a Commet Creatig Refereces Workig with Palettes Savig a Message Format to a File Opeig a Existig Message Format File Workig With the Repository Settig Format Builder Optios Format Builder Meus Testig Format Defiitios Startig Format Tester Usig the Format Tester Mai Widow Usig the Meu Bar Usig the Shortcut Meus Usig the Biary Widow Usig the XML Widow Usig the Debug Widow Usig the Resize Bars Testig Format Defiitios Debuggig Format Defiitios Searchig For Values Positioig to a Offset Usig the Debug Log Importig Meta Data Importig a COBOL Copybook COBOL Copybook Sample Files Importig C Structures C Struct Importer Sample Files Startig the C Struct Importer Uderstadig Hardware Profiles x BEA WebLogic XML/No-XML Traslator User Guide

11 Geeratig MFL Geeratig C Code Importig a FML Field Table Class FML Field Table Class Importer Prerequisites FML Field Table Class Sample Files Creatig XML with the FML Field Table Class Importer Retrievig ad Storig Repository Documets Accessig the Repository Repository Meu Retrievig Repository Documets Storig Repository Documets Importig Documets ito the Repository Ivokig the Batch Import Utility Usig the Repository Documet Chooser Usig the Ope Documet Dialog Box Usig the Store Documet Dialog Box Usig the Shortcut Meus Usig the Ru-Time Compoet Biary to XML Geeratig XML with a Referece to a DTD Passig i a Debug Writer XML to Biary Covertig a Documet object to Biary Passig i a debug writer XML to XML Trasformatio Iitializatio methods Java API Documetatio Ru-Time Plug-I to WebLogic Process Itegrator A. Supported Data Types MFL Data Types... A-1 COBOL Copybook Importer Data Types... A-7 C Structure Importer From Importig Meta Data... A-9 BEA WebLogic XML/No-XML Traslator User Guide xi

12 B. Creatig Custom Data Types User Defied Types Sample Files... B-2 Registerig User Defied Types i Format Builder... B-3 Creatig User Defied Types for the Stad-Aloe XML Traslator Egie... B-5 Cofiguratio of User Defied Types for the Process Itegrator XML Traslator Plug-I... B-6 Publishig User Defied Types to the Repository from Format Builder.. B-7 Publishig User Defied Types to the Repository Usig the Repository Import Utility... B-9 User Defied Type Codig Requiremets... B-9 Class com.bea.wlxt.bitype.bitype... B-9 Class com.bea.wlxt.bitype.bitypestrig... B-13 Class com.bea.wlxt.bitype.bitypedate... B-14 Class com.bea.wlxt.mfl.mflfield... B-16 C. Ruig the Purchase Order Sample What is Icluded i the Purchase Order Sample... C-2 Prerequisite Cosideratios... C-2 Uderstadig the Data Formats Used with XML Traslator... C-2 About Biary Data (No-XML Data)... C-3 About XML Documets... C-3 About MFL Documets... C-4 Performig Biary to XML Traslatio... C-6 Aalyzig the Data to be Traslated... C-6 Usig the Format Builder To Test the Traslatio... C-10 Performig XML to Biary Traslatio... C-18 Glossary Idex xii BEA WebLogic XML/No-XML Traslator User Guide

13 CHAPTER 1 BEA WebLogic XML/No-XML Traslator Overview Withi most eterprise applicatio itegratio (EAI) problem domais, data traslatio is a iheret part of a EAI solutio. XML is quickly becomig the stadard for exchagig iformatio betwee applicatios, ad is ivaluable i itegratig disparate applicatios. However, most data trasformatio egies do ot support traslatios betwee biary data formats ad XML. BEA WebLogic XML/No-XML Traslator (hereafter referred to as XML Traslator) provides for a exchage of iformatio betwee applicatios by supportig data traslatios betwee biary formats from legacy systems ad XML. This sectio provides iformatio about the followig topics: Uderstadig XML Traslatio What is XML Traslator? l The Desig-Time Compoet l The Ru-Time Compoet l Ru-Time Plug-I to WebLogic Process Itegrator Post Traslatio Optios ad Cosideratios l Performig XML Trasformatio l Workig with BEA WebLogic Process Itegrator Gettig Started with the BEA WebLogic XML/No-XML Traslator BEA WebLogic XML/No-XML Traslator User Guide 1-1

14 1 BEA WebLogic XML/No-XML Traslator Overview Uderstadig XML Traslatio Data that is set to, or received from, legacy applicatios is ofte platform-specific biary data that is i the ative machie represetatio. Biary data is ot self-describig, so i order to be uderstood by a applicatio, the layout of this data (metadata) must be embedded withi each applicatio that uses the biary data. XML is becomig the stadard for exchagig iformatio betwee applicatios because XML embeds a descriptio of the data withi the data stream, thus allowig applicatios to share data more easily. XML is easily parsed ad ca represet complex data structures. As a result, the couplig of applicatios o loger requires metadata to be embedded withi each applicatio. Whe you traslate biary to XML data, you covert structured biary data to a XML documet so that the data ca be accessed via stadard XML parsig methods. You must create the metadata used to perform the coversio. The traslatio process coverts each field of biary data to XML accordig to the metadata defied for each field of data. I the metadata you specify the ame of the field, the data type, the size, ad whether the field is always preset or optioal. It is this descriptio of the biary data that is used to traslate the biary data to XML. Figure 1-1 shows a sample of XML data traslatio. Figure 1-1 XML Data Traslatio of: Tom;Joes;1345;19; Applicatios developed o the WebLogic platform ofte use XML as the stadard data format. If you wat the data from your legacy system to be accessible to applicatios o the WebLogic platform, you may use XML Traslator to traslate it from biary to XML or from XML to biary. If you eed the XML i a particular XML dialect for ed use, you must trasform it usig a XML data mappig tool. 1-2 BEA WebLogic XML/No-XML Traslator User Guide

15 What is XML Traslator? What is XML Traslator? XML Traslator facilitates the itegratio of data from diverse eterprise applicatios by supportig data traslatios betwee biary formats from legacy systems ad XML. XML Traslator ormalizes legacy data ito XML so it may be directly cosumed by XML applicatios, trasformed ito a specific XML grammar, or used directly to start workflows i BEA WebLogic Process Itegrator. XML Traslator supports o-xml to XML traslatio ad vice versa ad is made up of three primary compoets: The Desig-Time Compoet The Ru-Time Compoet Ru-Time Plug-I to WebLogic Process Itegrator To perform a traslatio, you create a descriptio of your biary data usig the desig-time compoet (Format Builder). This ivolves aalyzig biary data so that its record layout is accurately reflected i the metadata you create i Format Builder. You the create a descriptio of the iput data i Format Builder ad save this metadata as a Message Format Laguage (MFL) documet. XML Traslator icludes importers that automatically create message format defiitios. You ca the use XML Traslator s ru-time compoet to traslate istaces of biary data to XML. Figure 1-2 shows the evet flow for o-xml to XML data traslatio. A Plug-I to Process Itegrator allows for easy access to cofigurig traslatios. BEA WebLogic XML/No-XML Traslator User Guide 1-3

16 1 BEA WebLogic XML/No-XML Traslator Overview Figure 1-2 Evet Flow for No-XML to XML Traslatio Usig XML Traslator The Desig-Time Compoet The desig-time compoet is a Java applicatio called Format Builder. Format Builder is used to create descriptios of biary data records. Format Builder allows you to describe the layout ad hierarchy of the biary data so that it ca be traslated to or from XML. With Format Builder, you ca describe sequeces of bytes as fields. Each field descriptio icludes the type of data (floatig poit, strig, etc.), the size of the data, ad the ame of the field. Format Builder allows you to further defie groupigs of fields (groups), repetitio of fields ad groups, ad aggregatio. The descriptio you create i Format Builder is saved i a XML grammar called Message Format Laguage (MFL). MFL documets are metadata used by the ru-time compoet of XML Traslator ad the plug-i to Process Itegrator to traslate a istace of a biary data record to a istace of a XML documet (or vice-versa). Format Builder will also create a DTD or XML Schema documet that describes the XML documet created from a traslatio. Figure 1-4 shows the process flow of biary ad XML data through Format Builder durig the desig-time phase. 1-4 BEA WebLogic XML/No-XML Traslator User Guide

17 What is XML Traslator? Figure 1-3 Desig Time Process Flow Through Format Builder Aalyze biary data to determie the layout ad biary types of each field of data Biary Data Based o your aalysis of the biary data, create metadata usig Format Builder Format Builder The metadata you create i Format Builder is saved as a MFL documet. It ad the biary data are ready to be processed by the ru-time compoet MFL Documet DTD Documet XML Schema Documet You ca also use Format Builder to retrieve, validate, ad edit stored MFL documets ad to test message format defiitios with your ow data. MFL documets may be stored usig the file system or archived i the Process Itegrator repository. The test feature allows you to select the optio of testig the traslatio of XML data to biary format, or biary data to XML format. You may save the trasformed data to a file for future testig. The Ru-Time Compoet The ru-time compoet of XML Traslator is a Java class with various methods used to traslate data betwee biary ad XML formats. This Java class ca be deployed i a EJB usig BEA WebLogic Server, ivoked from a workflow i BEA WebLogic Process Itegrator, or itegrated ito ay Java applicatio. Figure 1-4 shows the ru-time process flow for biary to XML traslatios ad XML to biary traslatio. BEA WebLogic XML/No-XML Traslator User Guide 1-5

18 1 BEA WebLogic XML/No-XML Traslator Overview Figure 1-4 Ru-Time Process Flow Biary to XML XML to Biary Biary to XML Traslatio Listig 1-1 is a code sample that shows the parsig of a file cotaiig biary data ito a XML documet object. The MFL file mymfl.mfl is used as the descriptio of the biary data cotaied i the file mybiaryfile. Listig 1-1 Sample Code for Biary to XML Traslatio import com.bea.wlxt.*; import org.w3.dom.documet; import java.io.fileiputstream; import java.et.url; try { 1-6 BEA WebLogic XML/No-XML Traslator User Guide

19 What is XML Traslator? WLXT wlxt = ew WLXT(); URL mfldocumetname = ew URL("file:mymfl.mfl"); FileIputStream i = ew FileIputStream("mybiaryfile"); Documet doc = wlxt.parse(mfldocumetname, i, ull); } catch (Exceptio e) { e.pritstacktrace(system.err); } XML to Biary Traslatio Listig 1-2 is a code sample that shows the traslatio of the XML data cotaied i the file myxml.xml to the biary format specified by the MFL documet mymfl.mfl. The biary data is writte to the file mybiaryfile. Listig 1-2 Sample Code for XML to Biary Traslatio import com.bea.wlxt.*; import java.io.fileiputstream; import java.io.fileoutputstream; import java.et.url; try { WLXT wlxt = ew WLXT(); URL mfldocumetname = ew URL("file:mymfl.mfl"); FileIputStream i = ew FileIputStream("myxml.xml"); FileOutputStream out = ew FileOutputStream("mybiaryfile"); wlxt.serialize(mfldocumetname, i, out, ull); } catch (Exceptio e) { e.pritstacktrace(system.err); } BEA WebLogic XML/No-XML Traslator User Guide 1-7

20 1 BEA WebLogic XML/No-XML Traslator Overview Ru-Time Plug-I to WebLogic Process Itegrator BEA XML Traslator Plug-I for WebLogic Process Itegrator provides for a exchage of iformatio betwee applicatios by supportig data traslatios betwee biary formats from legacy systems ad XML. The XML Traslator Plug-I provides Process Itegrator actios that allow you to access XML to Biary ad Biary to XML traslatios. I additio to this data traslatio capability, the XML Traslator Plug-I provides evet data processig i biary format, i-memory cachig of MFL documets ad traslatio object poolig to boost performace, a BiaryData variable type to edit ad display biary data, exportig of etirely self-cotaied workflow defiitio packages, ad executio withi a WebLogic Server clustered eviromet. The followig illustratio describes the relatioship betwee XML Traslator ad Process Itegrator. Figure 1-5 XML Traslator ad Process Itegrator Relatioship Start Workflow Task Cofigured with XML Traslator Actios Doe Iput Biary Data MFL Documet Name Traslated XML Documet BEA XML Traslator Plug-I to Process Itegrator BEA XML Traslator Java Classes MFL Documet XML Documet Repository MFL Documet Optioal: DTD XML Schema Format Builder 1-8 BEA WebLogic XML/No-XML Traslator User Guide

21 Post Traslatio Optios ad Cosideratios Post Traslatio Optios ad Cosideratios After you have successfully traslated your biary data to XML, or vice versa, you have umerous optios for additioal processig of the XML data. The XML data ca be trasformed to a specific XML dialect or to a display format. The XML data ca be set to other applicatios that cosume XML such as WebLogic Process Itegrator. Oce your biary data has bee put i a self-describig format such as XML, this data is available for use i other applicatios. Performig XML Trasformatio Oce you have traslated biary data ito XML, you may eed to trasform the XML data to a differet XML grammar, to a display format (HTML), or to aother biary format. The process of trasformig XML to aother XML grammar is referred to i this documet as XML trasformatio. XML trasformatio ca be accomplished via the XML module of WebLogic Server. WebLogic Process Itegrator provides a actio that allows you to access this module ad trasform XML documets usig XSL style sheets. You might wat to trasform XML for several reasos: Trasform the XML to a specific XML dialect (RosettaNet or ebxml) Trasform the XML to a display format (HTML) Trasform the XML so that it matches aother MFL documet ad ca be coverted to a differet biary format by XML Traslator XSL (extesible stylesheet laguage) is a XML laguage that describes a series of trasformatios that are to be performed o odes of a XML documet. A stylesheet is a XSL documet that ca be used to map a XML documet to aother XML dialect or to aother text format (such as HTML or PDF). A stylesheet ca also be used with the ru-time compoet of XML Traslator to trasform XML. Figure 1-6 demostrates oe XML grammar coverted to aother usig a XSLT egie. The trasformatio metadata i this case is a XSL style sheet that describes how oe XML grammar is mapped ito aother. BEA WebLogic XML/No-XML Traslator User Guide 1-9

22 1 BEA WebLogic XML/No-XML Traslator Overview Figure 1-6 XML Data Trasformatio of: Tom;Joes,1345;19 Workig with BEA WebLogic Process Itegrator BEA WebLogic Process Itegrator (Process Itegrator) is a powerful workflow egie that automates workflow, busiess-to-busiess processes, ad eterprise applicatio assembly. WebLogic Process Itegrator rus o BEA WebLogic Server ad is a robust J2EE stadards-based workflow ad process itegratio solutio. Usig a ituitive flowchart paradigm, busiess aalysts use the WebLogic Process Itegrator Studio to defie busiess processes that spa applicatios or to automate huma iteractio with applicatios. Developers ca use WebLogic Process Itegrator to assemble applicatio compoets quickly without programmig. The assembled applicatios are executed ad maaged by the WebLogic Process Itegrator egie. Process Itegrator has a extesible architecture that allows ew fuctioality to be plugged i. XML Traslator icludes a plug-i that provides XML to biary ad biary to XML traslatio that is accessible through a Process Itegrator actio. For detailed iformatio about usig the example workflow, see BEA WebLogic XML/No-XML Traslator Plug-I Guide BEA WebLogic XML/No-XML Traslator User Guide

23 Gettig Started with the BEA WebLogic XML/No-XML Traslator Gettig Started with the BEA WebLogic XML/No-XML Traslator The steps outlied i Table 1-1 provide you with a high-level guidelie to all of the tasks ad processes that you must perform to istall, cofigure, ad work with the XML Traslator. Thik of these steps as a road map to guide you through the process ad to poit you to the resources available to help you. Table 1-1 Steps for Workig with the XML Traslator Task 1. Read the BEA WebLogic XML/No-XML Traslator Release Notes. 2. Make sure that all of the platform/eviromet prerequisites listed i the Istallatio ad Cofiguratio Guide ad i the Release Notes have bee met. 3. Istall the BEA WebLogic XML/No-XML Traslator. 4. Defie the data format usig Format Builder ad geerate traslatio metadata. Resource BEA WebLogic XML/No-XML Traslator Release Notes. BEA WebLogic XML/No-XML Traslator Release Notes ad BEA WebLogic XML/No-XML Traslator Istallatio ad Cofiguratio Guide. BEA WebLogic XML/No-XML Traslator Istallatio ad Cofiguratio Guide. BEA WebLogic XML/No-XML Traslator User Guide. 5. Test the traslatio BEA WebLogic XML/No-XML Traslator User Guide. 6. Istall Process Itegrator ad verify correct operatio of the repository. 7. Save the format to the Process Itegrator Repository. BEA WebLogic Process Itegrator Istallatio Guide. BEA WebLogic XML/No-XML Traslator User Guide. BEA WebLogic XML/No-XML Traslator User Guide 1-11

24 1 BEA WebLogic XML/No-XML Traslator Overview Task 8. Deploy the XML Traslator plug-i usig the Process Itegrator plug-i maager. 9. Add a XML to Biary or Biary to XML traslatio actio to a task i a Process Itegrator workflow. Resource BEA WebLogic Process Itegrator Istallatio Guide. BEA WebLogic Process Itegrator Istallatio Guide BEA WebLogic XML/No-XML Traslator User Guide

25 CHAPTER 2 Buildig Format Defiitios The followig sectios provide iformatio o buildig format defiitios usig the Format Builder icluded with BEA WebLogic XML/No-XML Traslator (hereafter referred to as XML Traslator): Uderstadig the Data Formats Used with XML Traslator Aalyzig the Data to be Traslated Usig the Format Builder The Format Builder icluded with XML Traslator allows users to build format defiitios for biary data that will be traslated to or from XML. Format defiitios are the metadata used to parse or create biary data. Uderstadig the Data Formats Used with XML Traslator To uderstad how the Format Builder is used, it helps to uderstad the data formats used by XML Traslator: biary data, XML, MFL, DTD ad Schema. BEA WebLogic XML/No-XML Traslator User Guide 2-1

26 2 Buildig Format Defiitios About Biary Data (No-XML Data) Because computers are based o the biary umberig system, applicatios ofte use a biary format to represet data. A file stored i biary format is computer-readable but ot ecessarily huma-readable. Biary formats are used for executable programs ad umeric data, ad text formats are used for textual data. May files cotai a combiatio of biary ad text formats. Such files are usually cosidered to be biary files eve though they cotai some data i a text format. Ulike XML data, biary data is ot self-describig. I other words, biary data does ot provide a descriptio of how the data is grouped, divided ito fields, or arraged i a layout. Biary data is a sequece of bytes that ca be iterpreted as a iteger, a strig, or a picture, depedig o the itet of the applicatio that geerates the sequece of bytes. I order for biary data to be uderstood by a applicatio, the layout must be embedded withi each applicatio that uses this data. Biary data may also be embedded usig differet character sets. For example, character data o a IBM maiframe is usually ecoded usig the EBCDIC character set while data from a desktop computer is either ASCII or uicode. The Format Builder is used to create a Message Format Laguage (MFL) file that describes the layout of the biary data. MFL is a XML laguage that icludes elemets to describe each field of data, as well as groupigs of fields (groups), repetitio, ad aggregatio. The hierarchy of a biary record, the layout of fields, ad the groupig of fields ad groups are expressed i a MFL documet. This MFL documet is used by XML Traslator at ru-time to traslate the data to ad from a XML documet. Listig 2-1 Example of Biary Data 1234; ;SUP:21Sprockley s Sprockets01/15/ Mai St.; Austi;TX;75222;555 State St.;Austi;TX;75222;PO ;666123;150;Red Sprocket; 2-2 BEA WebLogic XML/No-XML Traslator User Guide

27 Uderstadig the Data Formats Used with XML Traslator About XML Documets Exteded Markup Laguage, or XML, is a text format for exchagig data betwee differet systems. It allows data to be described i a simple, stadard, text-oly format. I cotrast to biary data, XML data embeds a descriptio of the data withi the data stream. Applicatios ca share data more easily, sice they are ot depedet o the layout of the data beig embedded withi each applicatio. Sice the data is preseted i a stadard form, applicatios o disparate systems ca iterpret the data usig XML parsig tools, istead of havig to iterpret data i proprietary biary formats. Istaces of XML documets cotai character data ad markup. The character data is referred to as cotet, while the markup provides hierarchy for that cotet. Markup is distiguished from text by agle brackets. Iformatio i the space betwee the < ad the > is referred to as the tag that markup the cotet. Tags provide a idicatio of what the cotet is for, ad a mechaism to describe paret-child relatioships. Listig 2-2 shows a example of a XML documet. Listig 2-2 Example of XML Documet <?xml versio="2.0"?> <PurchaseRequest> <PR_Number>1234</PR_Number> <Supplier_ID> </Supplier_ID> <Supplier_Name>Sprockley&apos;s Sprockets</Supplier_Name> <Requested_Delivery_Date> T00:00:00:000</Requested_Delivery_Date> <Shippig_Address> <Address> <Street>123 Mai St.</Street> <City>Austi</City> <State>TX</State> <Zip>75222</Zip> </Address> </Shippig_Address> </PurchaseRequest> A XML documet ca coform to a cotet model. A cotet model allows Metadata about XML documets to be commuicated to a XML parser. XML documets are said to be valid if they coform to a cotet model. A cotet model describes the data that ca exist i a istace of a XML documet. A cotet model also describes a top-level etity, which is a sequece of subordiate etities. These subordiate etities BEA WebLogic XML/No-XML Traslator User Guide 2-3

28 2 Buildig Format Defiitios are further described by their tag ames ad data cotet. The two stadard formats for XML cotet models are XML Documet Type Defiitio (DTD) ad XML Schema. A Schema is a XML documet that defies what ca be i a XML documet. A DTD also defies what cotet ca exist i a XML documet, but the Schema defiitio is more specific tha the DTD, ad provides much fier-graied cotrol over the cotet that ca exist i a XML documet. Listig 2-3 shows a example of a Documet Type Defiitio. Listig 2-3 Example DTD <!ELEMENT PurchaseRequest (PR_Number,Supplier_ID,Supplier_Name?,Requested_Delivery_Date,Shippig_Address, Billig_Address,Paymet_Terms,Purchase_Items)> <!ELEMENT PR_Number (#PCDATA) > <!ATTLIST PR_Number type CDATA #FIXED "onegativeiteger"> <!ELEMENT Supplier_ID (#PCDATA) > <!ATTLIST Supplier_ID type CDATA #FIXED "onegativeiteger"> <!ELEMENT Supplier_Name (#PCDATA) > <!ATTLIST Supplier_Name type CDATA #FIXED "strig"> <!ELEMENT Requested_Delivery_Date (#PCDATA) > <!ATTLIST Requested_Delivery_Date type CDATA #FIXED "timeistat"> <!ELEMENT Shippig_Address (Address)> <!ELEMENT Address (Street,City,State,Zip)> <!ELEMENT Street (#PCDATA) > <!ATTLIST Street type CDATA #FIXED "strig"> <!ELEMENT City (#PCDATA) > <!ATTLIST City type CDATA #FIXED "strig"> <!ELEMENT State (#PCDATA) > <!ATTLIST State type CDATA #FIXED "strig"> <!ELEMENT Zip (#PCDATA) > <!ATTLIST Zip type CDATA #FIXED "onegativeiteger"> Listig 2-4 shows a example of a XML Schema. Listig 2-4 Example XML Schema <?xml versio="1.0" ecodig="utf-8"?> <xsd:schema xmls:xsd=" <xsd:aotatio> <xsd:documetatio> 2-4 BEA WebLogic XML/No-XML Traslator User Guide

29 Uderstadig the Data Formats Used with XML Traslator This schema created for MFL MessageFormat PurchaseRequest. </xsd:documetatio> </xsd:aotatio> <xsd:elemet ame="purchaserequest"> <xsd:complextype cotet="elemetoly"> <xsd:sequece> <xsd:elemet ref="pr_number" mioccurs="1" maxoccurs="1"/> <xsd:elemet ref="supplier_id" mioccurs="1" maxoccurs="1"/> <xsd:elemet ref="supplier_name" mioccurs="0" maxoccurs="1"/> <xsd:elemet ref="requested_delivery_date" mioccurs="1" maxoccurs="1"/> <xsd:elemet ref="shippig_address" mioccurs="1" maxoccurs="1"/> </xsd:sequece> </xsd:complextype> </xsd:elemet> <xsd:elemet ame="pr_number" type="xsd:onegativeiteger"/> <xsd:elemet ame="supplier_id" type="xsd:onegativeiteger"/> <xsd:elemet ame="supplier_name" type="xsd:strig"/> <xsd:elemet ame="requested_delivery_date" type="xsd:timeistat"/> <xsd:elemet ame="shippig_address"> <xsd:complextype cotet="elemetoly"> <xsd:sequece> <xsd:elemet ref="address" mioccurs="1" maxoccurs="1"/> </xsd:sequece> </xsd:complextype> </xsd:elemet> </xsd:schema> About MFL Documets Message Format Laguage (MFL) is a XML laguage that describes the layout of biary data. This laguage icludes elemets to describe each field of data, as well as groupigs of fields (groups), repetitio, ad aggregatio. The hierarchy of a biary record, the layout of fields, ad the groupig of fields ad groups is expressed i a MFL documet. MFL documets are created usig Format Builder. These MFL documets are the used to perform ru-time traslatio. MFL documets are created for you whe you defie ad save defiitios from withi Format Builder. BEA WebLogic XML/No-XML Traslator User Guide 2-5

30 2 Buildig Format Defiitios The MFL documets you create usig Format Builder ca cotai the followig elemets: Message Format - The top level elemet. Defies the message ame ad MFL versio. Field - Sequece of bytes that have some meaig to a applicatio. (For example, the field EMPNAME cotais a employee ame.) Defies the formattig for the field. The formattig parameters you ca defie iclude: l l l l l Tagged - Idicates that a literal precedes the data field, deotig the begiig of the field. Legth - Idicates that a legth value precedes the data field, deotig the legth of this field. Occurrece - Repeatig fields appear more tha oce i the message format. You ca set a specific umber of times the field is to repeat, or defie a delimiter to idicate the ed of the repeatig field. Optioal - The field may or may ot be preset i the amed message format. Code Page - The character ecodig of the field data. Groups - Collectios of fields, commets, ad other groups or refereces that are related i some way (for example, the fields PAYDATE, HOURS, ad RATE could be part of the PAYINFO group). The parameters you ca defie iclude: l l l l Tagged - Beig tagged meas that a literal precedes the other cotet of the group, which could be other groups or fields. Occurrece - Repeatig groups appear more tha oce i the message format: You ca set a specific umber of times the group is to repeat, or defie a delimiter to idicate the ed of the repeatig group. Choice of Childre - Defiig a group as Choice of Childre meas that oly oe item i the group will appear i the message format. Optioal - The group of data withi this structure may or may ot be preset i the amed message format. Refereces - Idicate that aother istace of the field or group format exists i the data. Referece fields or groups have the same format as the origial field or group, but you ca chage the optioal settig ad the occurrece settig for the referece field or group. For example, if you have a bill to address ad a ship 2-6 BEA WebLogic XML/No-XML Traslator User Guide

31 Aalyzig the Data to be Traslated to address i your data, you oly eed to defie the address format oce. You ca create the bill to address defiitio ad create a referece for the ship to address. Commets - Notes or additioal iformatio about the message format. Aalyzig the Data to be Traslated Before a message format ca be created, the layout of the biary data must be uderstood. Legacy purchase order sample data ad correspodig MFL ad XML documets for a purchase order record are icluded o the XML Traslator CD-ROM. The sample purchase order illustrates how XML Traslator traslates data from oe format to aother. For more iformatio o this sample data, refer to Appedix C, Ruig the Purchase Order Sample. The key to traslatig biary data to ad from XML is to create a accurate descriptio of the biary data. For biary data (data that is ot self-describig), you must idetify the followig elemets: Hierarchical groups Group attributes, such as ame, optioal, repeatig, delimited Data fields Data field attributes, such as ame, data type, legth/termiatio, optioal, repeatig The Format Builder (the desig-time portio of XML Traslator) is used to build the format defiitios that are used for data traslatios. For details o the steps you eed to perform to thoroughly aalyze your data, refer to the BEA WebLogic XML/No-XML Traslator Samples Guide. BEA WebLogic XML/No-XML Traslator User Guide 2-7

32 2 Buildig Format Defiitios Usig the Format Builder Format Builder assists you i creatig format descriptios for biary data. You use Format Builder to create hierarchical ad detail iformatio derived from structural ad detailed aalysis of your data. These format descriptios are stored i a MFL documet. You ca also use Format Builder to test your format descriptios before you apply them to your actual data. Startig Format Builder To start Format Builder, choose Start Programs BEA WebLogic E-Busiess Platform WebLogic Itegratio 2.0 xmltraslator Format Builder. The Format Builder mai widow displays. If you did ot use the istallatio directory defaults, your path may be differet. Usig the Format Builder Mai Widow The mai widow of Format Builder is split ito two paes. The left pae (the Tree Pae) shows the structural iformatio for the data format. The right pae (the Properties Pae) shows the detail for the item selected i the tree pae. Details of the file you are editig display i the Title Bar of the Format Builder mai widow. 2-8 BEA WebLogic XML/No-XML Traslator User Guide

33 Usig the Format Builder Figure 2-1 Format Builder Mai Widow The structure of the biary data is defied i the tree pae usig a combiatio of fields ad groups that match the target data. The followig topics discuss the parts of the mai widow ad provide istructios for avigatig ad executig commads from the mai widow of Format Builder: Usig the Tree Pae Usig the Meu Bar Usig the Toolbar Usig Drag ad Drop Usig the Shortcut Meus BEA WebLogic XML/No-XML Traslator User Guide 2-9

34 2 Buildig Format Defiitios Usig the Tree Pae The Tree Pae represets hierarchical/structural iformatio about the format of the biary data i a tree. The root ode of the tree will correspod to the MFL documet beig created or edited. The root ode is referred to as the Message ode. Child odes are labeled with group or field ames. Fields are represeted by leaf odes i the tree. Groups cotai fields or other groups ad are represeted by o-leaf odes i the tree. The ico for each ode ecapsulates iformatio about the ode. The ico idicates whether the ode represets a message, a group, a field, a commet, or a referece. The ico also idicates whether a group or field is repeatig, whether a group is a Choice of Childre, ad whether a group or field is optioal or madatory. You also have the ability to add, delete, move, copy, or reame odes i the tree. This is doe through the meus or the toolbar (see Usig the Meu Bar ad Usig the Toolbar). The icos that appear i the Tree Pae are described i the followig table. Table 2-1 Tree Ico Descriptios Tree Ico Ico Name Descriptio Message Format The top level elemet. Group Optioal Group Collectios of fields, commets, ad other groups or refereces that are related i some way (for example, the fields PAYDATE, HOURS, ad RATE could be part of the PAYINFO group). Defies the formattig for all items cotaied i the group. A group that may or may ot be icluded i the message format. Repeatig Group A group that has oe or more occurrece. Optioal Repeatig Group A group that may or may ot be icluded, but if icluded, may occur more tha oce BEA WebLogic XML/No-XML Traslator User Guide

35 Usig the Format Builder Table 2-1 Tree Ico Descriptios Tree Ico Ico Name Descriptio Group Referece Group Choice Field Optioal Field Idicates that aother istace of the group exists i the data. Referece groups have the same format as the origial group, but you ca chage the optioal settig ad the occurrece settig for the referece group. Idicates that oly oe of the items i the group will be icluded i the message format. Sequece of bytes that have some meaig to a applicatio. (For example, the field EMPNAME cotais a employee ame.) Defies the formattig for the field. A field that may or may ot be icluded i the message format. Repeatig Field A field that has oe or more occurreces. Optioal Repeatig Field Field Referece Commet A field that may or may ot be icluded, but, if icluded, may occur more tha oce i the message format. Idicates that aother istace of the field exists i the data. Referece fields have the same format as the origial field, but you ca chage the optioal settig ad the occurrece settig for the referece field. Cotais otes about the message format or the data traslated by the message format. BEA WebLogic XML/No-XML Traslator User Guide 2-11

36 2 Buildig Format Defiitios Table 2-1 Tree Ico Descriptios Tree Ico Ico Name Descriptio Collapse A mius sig ext to a object idicates that it ca be collapsed. Expad A plus sig ext a object idicates that it ca be expaded to show more objects. Usig the Meu Bar The Meu bar displays the meu headigs. The meu items that are available deped o what is selected i the tree pae ad the state of the tree. Click a meu headig to ope the meu ad choose a commad. Figure 2-2 Format Builder Meu Bar All Format Builder meus are expadable from your keyboard by pressig Alt + memoic keys. Some meu commads are also executable usig Ctrl + letter accelerator keys. Note: Meu items that appear i gray are uavailable for the curret selectio. Usig the Toolbar For a complete descriptio of the meu commads, see Format Builder Meus. The toolbar provides buttos that access some of the frequetly used commads i the meus. To activate a commad, click its toolbar butto. If a commad is uavailable, its butto appears grayed-out. Figure 2-3 Format Builder Toolbar 2-12 BEA WebLogic XML/No-XML Traslator User Guide

37 Usig the Format Builder The toolbar buttos provided with Format Builder are described below: Toolbar Butto Name Descriptio New Creates a ew Message Format. Ope Opes a existig Message Format. Save Saves the curret Message Format. Cut Removes the item curretly selected i the left-had pae, ad it s child objects, from the tree. The item ca be pasted elsewhere i the tree. Note: This actio is ot available if the Message Format (root) item is selected. Copy Makes a copy of the item curretly selected i the left-had pae for isertio elsewhere i the tree. Note: This actio is ot available if the Message Format (root) item is selected. Paste as Siblig Iserts the cut or copied item as a siblig object of the selected item. Paste as Referece Iserts a referece to the cut or copied item as a siblig object of the selected item. Udo Reverses the previous actio. The tool tip chages to idicate the actio that ca be udoe. For example, chagig the ame of a field to Address ad clickig Apply causes the tool tip to read Udo Apply Field Address. Format Builder supports multi-level udoig ad redoig. BEA WebLogic XML/No-XML Traslator User Guide 2-13

38 2 Buildig Format Defiitios Toolbar Butto Name Descriptio Redo Isert Field Reverses the effects of a Udo commad. The tool tip chages to idicate the actio that ca be redoe. For example, chagig the ame of a field to Address ad the udoig that actio causes the tool tip to read Redo Apply Field Address. Format Builder support multi-level udoig ad redoig. Iserts a field as a siblig of the item selected i the tree pae. Isert Group Iserts a group as a siblig of the item selected i the tree pae. Isert Commet Iserts a commet as a siblig of the item selected i the tree pae. Move Up Moves the selected item up oe positio uder its paret. Move Dow Moves the selected item dow oe positio uder its paret. Promote item Demote item Expad All Promotes the selected item to the ext highest level i the tree. For example, Field1 is the child object of Group1. Selectig Field1 ad clickig the Promote tool makes it a siblig of Group1. Demotes the selected item to the ext lower level i the tree. For example, Group1 is the siblig of Field1. Field1 immediately follows Group1 i the tree. Selectig Field1 ad clickig the Demote tool makes it a child of Group1. Expads all items i the tree pae to show child items BEA WebLogic XML/No-XML Traslator User Guide

39 Usig the Format Builder Toolbar Butto Name Descriptio Collapse All Collapses the tree pae to show first level items oly. Format Tester Opes the Format Tester widow. Usig the Shortcut Meus Istead of usig the stadard meus to fid the commad you eed, use the right mouse butto to click a item i the tree pae. The meu that appears shows the most frequetly used commads for that item. The followig commads are available from the Shortcut Meus. Note: Some commads may be uavailable, depedig o the item you have selected i the tree, or the state of the tree at the time. Table 2-2 Shortcut Meus Meu Commad Cut Copy Paste Isert Group Isert Field Descriptio Removes the item curretly selected i the left-had pae, ad it s child objects, from the tree. Makes a copy of the item curretly selected i the left-had pae for isertio elsewhere i the tree. Iserts the cut or copied item. A additioal meu displays whe you select Paste. You ca choose to paste the item as a child or siblig of the selected item. I additio, you ca choose to paste a referece to the cut or copied item as a siblig of the selected item. Iserts a ew group. You select whether to isert the group as a child or siblig of the selected item. Iserts a ew field. You select whether to isert the field as a child or siblig of the selected item. BEA WebLogic XML/No-XML Traslator User Guide 2-15

40 2 Buildig Format Defiitios Meu Commad Isert Commet Duplicate Delete Descriptio Iserts a commet. You select whether to isert the commet as a child or siblig of the selected item. Makes a copy of the curretly selected item. The duplicate item cotais the same values as the origial item. The ame of the duplicate item is the same as the origial item ame, with the word New iserted before the origial ame. For example, duplicatig a group called Group1 results i a group with the ame NewGroup1. Whe you duplicate a item with a umeric value i its ame, the ew item ame cotais the ext sequetial umber. For example, duplicatig NewGroup1 results i a group amed NewGroup2. Deletes the selected item. Usig Drag ad Drop You ca use the drag ad drop feature of XML Traslator to copy ad/or move the items i the tree pae. Note: The ode beig copied or moved is always iserted as a siblig of the selected ode durig the drag ad drop process. If you drag ad drop the ode oto the message format ode, it is iserted as the last child. To use drag ad drop to move a item: 1. Select the item you wat to move. 2. Press ad hold the left mouse butto while you drag the item to the desired ode. 3. Whe the item is i the desired locatio, release the left mouse butto. The item is moved to the ew locatio. To use drag ad drop to copy a item: 1. Select the item you wat to copy. 2. Press ad hold the CTRL key. 3. Keepig the CTRL key depressed, press ad hold the left mouse butto while you drag the item to the desired ode BEA WebLogic XML/No-XML Traslator User Guide

41 Usig the Format Builder 4. With the siblig object selected, release the left mouse butto. A copy of the item is placed at the ew locatio. Creatig a Message Format The first step i creatig a Message Format Defiitio file is to create a message format (the root ode of a message format file). To create a message format: 1. Choose File New. The Message Format Pae displays i the detail widow. Figure 2-4 Message Format Properties 2. Eter data i the fields as described i the followig table. Note: The examples that follow are based o MFL versio 2.01 documets. Table 2-3 Message Format Properties Field Descriptio Message Format Properties Name MFL Versio The ame of the message format. This value will be used as the root elemet i the traslated XML documet. This ame must comply with XML elemet amig covetios. The versio of MFL you are usig. Versio 2.0 of Format Builder adds ew features ad its default versio is If you ope a MFL documet created usig a earlier versio of Format Builder, you must chage this value from 2.0 to 2.01 to use all of the ew Format Builder features. BEA WebLogic XML/No-XML Traslator User Guide 2-17

42 2 Buildig Format Defiitios Field Apply Reset Help Descriptio Saves your chages to the message format documet. Discards your chages to the detail widow ad resets all fields to the last saved values. Displays olie help iformatio for this detail widow. Valid Names Message Formats, Fields, ad Groups are idetified by a Name. The ame that is specified is used as the XML tag whe biary data is traslated to XML by XML Traslator. Thus the ame must coform to the XML rules for a ame. The rules for ames are as follows: Must start with a letter or uderscore Ca cotai letters, digits, the period character, the hyphe character, or the uderscore character. The followig are valid ame examples: MyField MyField1 MyField_agai MyField-agai The followig are ivalid ame examples: 1MyField - may ot start with a digit My>Field - the greater-tha sig (>) is a illegal character My Field - a space is ot permitted Creatig a Group Groups are collectios of fields, commets, refereces ad other groups that are related i some way (for example, the fields PAYDATE, HOURS, ad RATE could be part of the PAYINFO group). You ca create a group as a child of the message format item, as a child of aother group, or as a siblig of a group or field BEA WebLogic XML/No-XML Traslator User Guide

43 Usig the Format Builder To create a group: 1. Select a item i the tree pae. 2. Choose Isert Group As Child if you wat to create the group as the child of the message format or aother group. Choose Isert Group As Siblig if you wat to create the group as the siblig of aother group or a field. The Group Details display i the detail widow. Figure 2-5 Group Details 3. Eter data i the fields as described i the followig table. Note: The followig example applies to MFL versio 2.1. Table 2-4 Group Detail Properties Field Descriptio Group Descriptio Name Optioal The ame of the group. This ame must comply with XML elemet amig covetios. Choose Optioal if this is a optioal group. BEA WebLogic XML/No-XML Traslator User Guide 2-19

44 2 Buildig Format Defiitios Field Choice of Childre Descriptio Choose Choice of Childre if oly oe of the items i the group will be icluded i the message format. Group Occurrece Occurrece Choose oe of the followig to idicate how ofte this group appears i the message format: Oce - Idicates the group appears oly oce. Repeat Delimiter - Idicates the group will repeat util the specified delimiter is ecoutered. Repeat Field - Idicates the group will repeat the umber of times specified i the repeat field. Repeat Number - Idicates the group will repeat the specified umber of times. Ulimited - Idicates the group will repeat a ulimited umber of times. Note: Uless a group is defied as Optioal, all groups occur at least oce. Group Attributes Group is Tagged Select this optio if this is a tagged group. Beig tagged meas that a literal precedes the other cotet of the group, which could be other groups or fields. Group Delimiter Noe Delimited Select this optio if the group has o delimiter. Groups ca have their termiatio poit specified by a delimiter. A delimiter is a strig of characters that marks the ed of the group of fields. The group cotiues util the delimiter characters are ecoutered. Select this optio if the ed of the group is marked with a delimiter. Value - Eter the delimiter that marks the ed of the group of fields. Note: Normally, groups are ot delimited. They are usually parsed by cotet (the group eds whe all child objects have bee parsed) BEA WebLogic XML/No-XML Traslator User Guide

45 Usig the Format Builder Field Delimiter Field Delimiter is Shared Descriptio Groups ca have their termiatio poit specified by a field that cotais a delimiter character strig. A delimiter is a strig of characters that mark the ed of the group. The group cotiues util the delimiter character strig cotaied i the specified field is ecoutered. Field - Select the field that cotais the delimiter character strig. A list of valid fields will be preseted i a drop-dow list. Default - Eter the default delimiter character that will be used if the above field is ot preset i the data. This value is required. Idicates that the delimiter marks both the ed of the group of data, ad the ed of the last field of the group. The delimiter is shared amog the group, ad the last field of the group, to delimit the ed of the data. Group Update Buttos Apply Duplicate Reset Help Saves your chages to the message format documet. Makes a copy of the group curretly displayed. The duplicate group cotais the same values as the origial group. The ame of the duplicate group is the same as the origial group ame, with the word New iserted before the origial ame. For example, duplicatig a group called Group1 results i a group with the ame NewGroup1. Whe you duplicate a item with a umeric value i its ame, the ew item ame cotais the ext sequetial umber. For example, duplicatig NewGroup1 results i a group amed NewGroup2. Discards your chages to the detail widow ad resets all fields to the last saved values. Displays olie help iformatio for this detail widow. 4. Click Apply to save your chages to the message format file, or click Reset to discard your chages to the detail widow ad reset all fields to the last saved value. BEA WebLogic XML/No-XML Traslator User Guide 2-21

46 2 Buildig Format Defiitios Note: The Apply ad Reset buttos are oly eabled oce chages are made to the detail pael s compoets. Creatig a Field Fields are a sequece of bytes that have some meaig to a applicatio. (For example, the field EMPNAME cotais a employee ame.) You ca create a field as a child of the message format item, as a child of a group, or as a siblig of a group or aother field. The field ame is used as the elemet ame i the XML documet ad must comply with XML amig covetios. To create a field: 1. Select a item i the tree pae. 2. Choose Isert Field As Child if you wat to create the field as the child of the message format or group. Choose Isert Field As Siblig if you wat to create the field as the siblig of aother field or a group. The Field Details display i the detail widow BEA WebLogic XML/No-XML Traslator User Guide

47 Usig the Format Builder Figure 2-6 Field Details 3. Eter data i the fields as described i the followig table. Note: The followig example applies to MFL versio Table 2-5 Field Detail Properties Field Descriptio Field Descriptio Name Optioal The ame of the field. This ame must comply with XML elemet amig covetios. Select this optio if this is a optioal field. Optioal meas that the data for the field may or may ot be preset. BEA WebLogic XML/No-XML Traslator User Guide 2-23

48 2 Buildig Format Defiitios Field Type Descriptio Select the data type of the field from the drop-dow list. The default is Strig. Note: The Field Type you select dictates the Field Data Optios that appear o the dialog. Refer to Appedix A, Supported Data Types, for a list of data types supported by XML Traslator. Field Occurrece Occurrece Choose oe of the followig to idicate how ofte this field appears i the message format: Oce - Idicates the field appears oly oce. Repeat Delimiter - Idicates the field will repeat util the specified delimiter is ecoutered. Repeat Field - Idicates the field will repeat the umber of times specified i the field deoted as the repeat field. Repeat Number - Idicates the field will repeat the specified umber of times. Ulimited - Idicates the field will repeat a ulimited umber of times. Note: Uless a field is defied as optioal, the field will occur at least oe time. Note: The fields that display i the followig sectios of the detail widow deped o the Field Type selected. Field Attributes Field is Tagged Select this optio if this is a tagged field. Beig tagged meas that a literal proceeds the data, idicatig that the data is preset. You must also choose the data type of the tag field from the drop-dow list box. For example: SUP:ACME INC, SUP: is a tag. ACME INC is the field data. If you selected the Field is Tagged optio, eter the tag i the text box to the right of the checkbox BEA WebLogic XML/No-XML Traslator User Guide

49 Usig the Format Builder Field Field Default Value Descriptio Select this optio to specify a value for the data of the field that will be iserted ito the biary data if the field is ot preset i the XML. Note: If the field does ot occur i the biary data ad it is ot optioal, the the biary data will fail to parse eve if there is a default value give. Data Base Type Year Cutoff Code Page Value If the field is a date or time field, the base type idicates what type of characters (ASCII, EBCDIC, or Numeric) make up the data. If the field is a date field that has a 2-digit year, the year cutoff allows the 2-digit year to be coverted to a 4-digit year. If the 2-digit year is greater tha or equal to the year cutoff value, a 19 prefix will be added to the year value. Otherwise a 20 prefix will be used. The character ecodig of the field data. The value that appears i a literal field. Field Termiatio Legth Imbedded Legth Variable-sized data types ca have their legth set to a fixed value. Legth - Eter the umber of bytes i the field. Trim Leadig/Trailig - Removes the specified data from the leadig or trailig edge of the data. Pad - If the XML data is shorter tha the specified legth, eter the ecessary value to the data to correct its legth. Variable-sized data types ca have their termiatio poit specified by a imbedded legth. A imbedded legth precedes the data field ad idicates how may bytes the data cotais. Type - Specifies the data type ad Legth or Delimiter for termiatio if eeded. Tag/Legth Order - Specifies the order of tag ad legth fields whe both are preset. Default is tag before legth. Trim Leadig/Trailig - Removes the specified data from the leadig or trailig edge of the data. BEA WebLogic XML/No-XML Traslator User Guide 2-25

50 2 Buildig Format Defiitios Field Delimiter Delimiter Field Decimal Positio Descriptio Variable-sized data types ca have their termiatio poit specified by a delimiter. A delimiter is a value that marks the ed of the field. The field data cotiues util the delimiter is ecoutered. Value - Eter the delimiter that marks the ed of the field data. Trim Leadig/Trailig - Removes the specified data from the leadig or trailig edge of the data. Variable-sized data types ca have their termiatio poit specified by a field that cotais a delimiter value. A delimiter is a value that marks the ed of the field. The field data cotiues util the field cotaiig the delimiter is ecoutered. Field - Select the field that cotais the delimiter. Default - Eter the default delimiter. You must supply a default value. The default is used whe the delimiter field is ot preset. Trim Leadig/Trailig - Removes the specified data from the leadig or trailig edge of the data. Specifies the umber of digits (0-16) to the left of the decimal poit. Field Update Buttos Apply Duplicate Reset Help Saves your chages to the message format file. Makes a copy of the field curretly displayed. The duplicate field cotais the same values as the origial field. The ame of the duplicate field is the same as the origial field ame, with the word New iserted before the origial ame. For example, duplicatig a field called Field1 results i a field with the ame NewField1. Whe you duplicate a item with a umeric value i its ame, the ew item ame cotais the ext sequetial umber. For example, duplicatig NewField1 results i a group amed NewField2. Discards your chages to the detail widow ad resets all fields to the last saved values. Displays olie help iformatio for this detail widow. 4. Click Apply to save your chages to the message format file, or click Reset to discard your chages to the detail widow ad reset all fields to the last saved value BEA WebLogic XML/No-XML Traslator User Guide

51 Usig the Format Builder Note: The Apply ad Reset buttos are oly eabled oce chages are made to the detail pael s compoets. Creatig a Commet Commets cotai otes about the message format or the data traslated by the message format. Commets are icluded i the message format defiitio for documetatio ad iformatioal purposes oly. You ca create a commet as a child or siblig of ay message format, group, or field. Commets are uumbered i the MFL documet ad are ot trasformed to the XML or Biary data. Note: Covetioally, the commet usually precedes the ode it iteds to documet. To create a commet: 1. Select a item i the tree pae. 2. Choose Isert Commet As Child if you wat to create the commet as the child of the selected item. Choose Isert Commet As Siblig if you wat to create the commet as the siblig of the selected item. The Commet Details display i the detail widow. 3. Eter data i the fields as described i the followig table. Figure 2-7 Commet Details BEA WebLogic XML/No-XML Traslator User Guide 2-27

52 2 Buildig Format Defiitios Table 2-6 Commet Detail Properties Field Commet Details Apply Reset Help Descriptio Eter the commet text. Saves your chages to the message format documet. Discards your chages to the detail widow ad resets the field to the last saved value. Displays olie help iformatio for this detail widow. 4. Click Apply to save your chages to the message format file, or click Reset to discard your chages to the Commet Details widow ad reset the field to the last saved value. Note: The Apply ad Reset buttos are oly eabled oce chages are made to the detail pael s compoets. Creatig Refereces Refereces idicate that the descriptio of the field or group format has bee previously defied ad you wat to reuse this descriptio without re-eterig the data. Referece fields or groups have the same format as the origial field or group, but you ca chage oly the optioal settig ad the occurrece settig for the referece field or group. For example, if you have a bill to address ad a ship to address i your data ad the format for the address is the same, you oly eed to defie the address format oce. You ca create the bill to address defiitio ad create a referece for the ship to address. Note: Refereces are amed exactly the same as the origial item. For example, the bill to address defiitio ad the ship to address defiitio would be amed the same. If you wat to reuse a group defiitio, create a geeric group ad embed it withi a specific group. For example, i the previous example, you ca create a address group withi a bill_to group ad referece address withi a ship_to group. To create a referece: 1. Select a field or group i the tree pae BEA WebLogic XML/No-XML Traslator User Guide

53 Usig the Format Builder 2. Choose Edit Copy. 3. Choose the proper siblig i the tree. 4. Choose Edit Paste As Referece. Figure 2-8 Referece Details 5. Eter data i the fields as described i the followig table. Table 2-7 Referece Detail Properties Field Descriptio Referece Descriptio Name Optioal Displays the ame of the origial field or group for which you created this referece. This value caot be chaged. Select this optio if the referece field or group is optioal. Occurrece BEA WebLogic XML/No-XML Traslator User Guide 2-29

54 2 Buildig Format Defiitios Field Occurrece Descriptio Choose oe of the followig to idicate how ofte this referece field or group appears i the message format: Oce - Idicates the referece appears oly oce. Repeat Delimiter - Idicates the referece will repeat util the specified delimiter is ecoutered. Repeat Field - Idicates the referece will repeat the umber of times specified i the field deoted as the repeat field. Repeat Number - Idicates the referece will repeat the specified umber of times. Ulimited - Idicates the referece will repeat a ulimited umber of times. Field Update Buttos Apply Edit Referece Reset Help Saves your chages to the message format documet. Displays the detail widow for the origial item so you ca edit the details of the refereced field or group. Discards your chages to the detail widow ad resets all fields to the last saved values. Displays olie help iformatio for this detail widow. 6. Click Apply to save your chages to the message format file, or click Reset to discard your chages to the detail widow ad reset all fields to the last saved value. Note: The Apply ad Reset buttos are oly eabled oce chages are made to the detail pael s compoets. Workig with Palettes The palette allows you to store commoly used message format items ad isert them ito your message format defiitios. These items are stored i a MFL documet, ad you ca use the drag ad drop feature (see Usig Drag ad Drop) to copy items from the palette ito your message format defiitio. You ca also ope ay MFL documet i the palette ad reuse ay message format items BEA WebLogic XML/No-XML Traslator User Guide

55 Usig the Format Builder Opeig the Palette To ope the palette: 1. Start Format Builder by clickig Start Programs BEA WebLogic E-Busiess Platform WebLogic Itegratio 2.0 xmltraslator Format Builder. The Format Builder mai widow displays. 2. Choose View Show Palette. The palette widow displays. You may reorder or chage the hierarchy withi the palettes by usig drag ad drop or the Cotext meu. The cotets of the palette are automatically saved whe you exit Format Builder. Note: You ca oly copy items from the tree pae to the palette ad vice versa. You caot move items betwee the widows. Usig the File Meu The XML Traslator palette cotais some commo date formats, literals, ad strigs. You ca use these items i the message formats you create, as well as addig your ow items to the palette. The followig commads are available from the palette s File meu. BEA WebLogic XML/No-XML Traslator User Guide 2-31

56 2 Buildig Format Defiitios Table 2-8 File Meu Commads Meu Commad Ope Save Hide Palette Descriptio Opes a existig message Format. Saves ay message format items you have added to the palette, or ay existig items you have modified. The default palette is amed palette.xml ad is stored i the Format Builder istallatio directory. Closes the Palette widow. Usig the Shortcut Meu The followig commads are available from the palette s shortcut meu. You ca access the shortcut meu by right-clickig withi the palette widow. Note: Some commads may be uavailable, depedig o the time you have selected i the tree. Table 2-9 Shortcut Meu Commads Meu Commad Isert Reame Delete Move Up Move Dow Promote Descriptio Iserts a ew group i the palette. Whe you select this commad, a widow displays askig you to supply the ame of the ew group. Displays a widow askig you to supply the ew ame of the group. Deletes the selected item. Moves the selected item up oe positio uder its paret. Moves the selected item dow oe positio uder its paret. Promotes the selected item to the ext highest level i the tree. For example, Field1 is the child object of Group1. Selectig Field1 ad clickig the Promote tool makes it a siblig of Group BEA WebLogic XML/No-XML Traslator User Guide

57 Usig the Format Builder Meu Commad Demote Descriptio Demotes the selected item to the ext lower level i the tree. For example, group1 is the siblig of Field1. Field1 immediately follows Group1 i the tree. Selectig Field1 ad clickig the Demote tool makes it a child of Group1. Addig Items to the Palette To add items to the palette: 1. Choose View Show Palette to display the palette. Note: If the Palette widow is already displayed, skip this step. 2. From the tree pae of the XML Traslator widow, choose the item you wat to add to the palette. 3. Click ad hold the left mouse butto ad drag the item ito the palette widow. 4. Whe the item is placed i the positio you wat it (as siblig of the selected item), release the mouse butto. The item is copied from the XML Traslator widow to the palette widow. Notes: You caot add ay ode that depeds o the existece of aother ode to the palette. For example, you caot add Field or Group Refereces, ad you caot add items that have a Repeat Field specified. Deletig Items From the Palette Addig commets is possible, but ot recommeded sice commets do ot have uique ames ad therefore are idistiguishable o the palette. To delete items from the palette: 1. Select the item i the palette to be deleted ad click the right mouse butto. The Shortcut Meu displays. 2. Choose Delete. A message displays askig you to cofirm the deletio. 3. Click OK to delete the item. BEA WebLogic XML/No-XML Traslator User Guide 2-33

58 2 Buildig Format Defiitios Addig Palette Items to a Message Format To copy items from the palette to a message format: 1. Choose View Show Palette to display the palette. Note: If the Palette widow is already displayed, skip this step. 2. From the palette widow, choose the item you wat to add to your message format. 3. Click ad hold the left mouse butto ad drag the item ito the tree pae of the Format Builder widow. 4. Whe the item is placed i the positio you wat it (as the siblig of the desired item), release the mouse butto. The item is copied from the palette to the message format. Savig a Message Format to a File To save a message format file for the first time: 1. Choose File Save As. The Save As dialog displays. Figure 2-9 Save As Dialog 2. Navigate to the directory where you wat to save the file. 3. I the File Name text box, type the ame you wat to assig to the file BEA WebLogic XML/No-XML Traslator User Guide

59 Usig the Format Builder 4. Format Builder automatically assigs the.mfl extesio to message format files by default if o extesio is give. 5. Click Save As to save the file i the specified locatio with the specified ame ad extesio. To save a message format file usig the same ame, choose File Save. The file is saved i the same locatio with the same ame ad extesio. To save a message format file usig a differet ame, choose File Save As ad follow steps 1 through 5 above. Opeig a Existig Message Format File To ope a existig message format file: 1. Choose File Ope. The Ope dialog displays. Figure 2-10 Ope Dialog 2. Navigate to the directory cotaiig the desired file ad select the file ame. 3. Click Ope. The file is loaded ito Format Builder. Workig With the Repository The XML Traslator repository provides a cetralized documet storage mechaism that supports the followig four documet types: BEA WebLogic XML/No-XML Traslator User Guide 2-35

60 2 Buildig Format Defiitios Message Format Laguage documet XML Documet Type Defiitio documet XML Schema documet XSLT Stylesheet The repository allows the supported documets to be shared betwee the compoets of WebLogic Itegratio. The repository provides access to these documet types ad provides maipulatio of repository documets icludig access to the documet text, descriptio, otes, ad removal of the documet. The repository allows the supported documets to be shared betwee XML Traslator, WebLogic Process Itegrator (Process Itegrator), WebLogic Server (WLS), ad WebLogic Collaborate (WLC). The repository also icludes a batch import utility that allows previously costructed MFL, DTD, XML Schema, ad XSLT documets residig o a differet file system to be easily migrated ito the repository. For more iformatio o usig the repository, refer to the Retrievig ad Storig Repository Documets sectio. Retrievig Repository Documets Perform the followig steps to retrieve a MFL documet from the repository: 1. Start Format Builder. 2. Choose Repository Log I. The Repository Log I dialog box opes. Eter your user ame, password, ad the server where the repository resides. 3. Choose Repository Retrieve. The Select-documet-to-retrieve dialog box opes. 4. Select the documet you wat to retrieve from the documet list. 5. Click Retrieve. The Select-documet-to-retrieve dialog box is dismissed ad you are retured to the Format Builder mai widow with your selected documet listed i the Tree Pae. Oce you have retrieved the specified documet, you ca edit it as you would ay MFL documet withi Format Builder, store the documet back ito the repository, store the documet back ito the repository with a differet ame, or save as a local file BEA WebLogic XML/No-XML Traslator User Guide

61 Usig the Format Builder Aytime you ope a documet that is stored i the repository, a read-oly Documet Repository Properties box displays i the Message Format detail pael whe the message format ode is selected. This properties box provides you with a documet descriptio ad ay otes that were attached to the documet. Storig Repository Documets Perform the followig steps to store a MFL documet i the repository: 1. Start Format Builder. 2. Ope the MFL documet you wat to store i the repository. 3. Log i to the repository. 4. Choose Repository Store As. The Store As dialog box opes. 5. Eter the ame you wat to associate with this repository documet i the Name field. 6. Eter a descriptio of the repository documet i the Descriptio field. 7. Eter ay otes you would like attached to the documet i the Notes field. 8. Click Store. The Store As dialog box is dismissed ad your MFL documet displays i the Format Builder Tree Pae. A Documet Repository Properties box with documet Descriptio ad Notes iformatio displays i the Detail pael of the Format Builder Message Format Detail Pael. If your Format Builder optios specify geeratio of a DTD/XML Schema, these documets will also be stored i the repository usig the supplied ame. Settig Format Builder Optios You ca set several optios to cotrol the overall operatio of Format Builder. To set Format Builder optios: 1. Choose Tools Optios. The Optios dialog displays. BEA WebLogic XML/No-XML Traslator User Guide 2-37

62 2 Buildig Format Defiitios Figure 2-11 Format Builder Optios Dialog 2. Eter data i the fields as described i the followig table. Table 2-10 Format Builder Optios Properties Field Default Message Format Versio Defiitio Select the MFL versio used whe creatig ew documets. Note: Message formats cotai their ow format versio specified o the Message Format pae. XML Formattig Optios Iitial Idet New Lie Idet Eter the umber of spaces to idet the first lie of the XML documet created by XML Traslator. Eter the umber of spaces to idet a ew child lie of the XML documet created by XML Traslator. XML Cotet Model Optios Auto-geerate DTD Geerates a DTD documet whe you save or store the MFL documet. This documet will be placed i the same directory as the message format whe savig to a file ad i the repository whe storig BEA WebLogic XML/No-XML Traslator User Guide

63 Usig the Format Builder Field Auto-geerate Schema Defiitio Geerates a Schema file whe you save the MFL documet. This documet will be placed i the same directory as the message format whe savig to a file ad i the repository whe storig. Actio Buttos OK Cacel Saves your chages ad closes this detail widow. Discards your chages ad closes this detail widow. Format Builder Meus File Meu The followig meus are available i Format Builder. The followig commads are available from the File Meu. Note: Some commads may be uavailable, depedig o the actios you have take. Table 2-11 File Meu Commads Meu Commad New Ope Close Save Save As Exit Descriptio Creates a ew Message Format documet. Opes a existig Message Format documet. Closes the curret Message Format documet. Saves the curret Message Format documet. Saves the curret Message Format uder a differet ame documet. Exits the Format Builder program. BEA WebLogic XML/No-XML Traslator User Guide 2-39

64 2 Buildig Format Defiitios Edit Meu The followig commads are available from the Edit Meu. Note: Some commads may be uavailable, depedig o the actios you have take ad the state of the tree pae ad its items. Table 2-12 Edit Meu Commads Meu Commad Udo Redo Cut Descriptio Reverses the previous actio. The Udo commad i the Edit Meu chages to idicate the actio that ca be udoe. For example, chagig the ame of a field to Field1 ad clickig Apply causes the Edit Meu to read Udo Apply Field Field1. Reverses the effects of a Udo commad. The Redo commad i the Edit Meu chages to idicate the actio that ca be redoe. For example, chagig the ame of a field to Field1 ad the udoig that actio causes the Edit Meu to read Redo Apply Field Field1. Removes the item curretly selected i the left-had pae, ad it s child objects, from the tree. This item is placed o the clipboard for pastig ito aother locatio. Note: This actio is ot available if the Message Format (root) item is selected. Copy Makes a copy of the item curretly selected i the left-had pae for isertio elsewhere i the tree. Note: This actio is ot available if the Message Format (root) item is selected. Paste Iserts the cut or copied item. A additioal meu displays whe you select Paste. You ca choose to paste the item as a child or siblig of the selected item. I additio, you ca choose to paste a referece as a siblig of the selected item BEA WebLogic XML/No-XML Traslator User Guide

65 Usig the Format Builder Meu Commad Duplicate Delete Move Up Move Dow Promote Demote Descriptio Makes a copy of the item selected i the tree. The duplicate item cotais the same values as the origial item. The ame of the duplicate item is the same as the origial item ame, but the word New is iserted before the origial ame. For example, duplicatig a item called Field1 results i a item with the ame NewField1. Whe you duplicate a item with a umeric value i its ame, the ew item ame cotais the ext sequetial umber. For example, duplicatig NewGroup1 results i a group amed NewGroup2. Deletes the item selected i the tree, as well as all child objects of that item. Moves the selected item up oe positio uder its paret. Moves the selected item dow oe positio uder its paret. Promotes the selected item to the ext highest level i the tree. For example, Field1 is the child object of Group1. Selectig Field1 ad clickig the Promote tool makes it a siblig of Group1. Demotes the selected item to the ext lower level i the tree. For example, Group1 is the siblig of Field1. Field1 immediately follows Group1 i the tree. Selectig Field1 ad clickig the Demote tool makes it a child of Group1. Isert Meu The followig commads are available from the Isert Meu. Table 2-13 Isert Meu Commads Meu Commad Field Group Descriptio Iserts a ew field. You ca choose whether to isert the field as a child or siblig of the item selected i the tree. Iserts a ew group. You ca choose whether to isert the group as a child or siblig of the item selected i the tree. BEA WebLogic XML/No-XML Traslator User Guide 2-41

66 2 Buildig Format Defiitios Meu Commad Commet Descriptio Iserts a commet. You ca choose whether to isert the commet as a child or siblig of the item selected i the tree. View Meu The followig commads are available from the View Meu. Table 2-14 View meu Commads Meu Commad Show Palette Expad All Collapse All Descriptio Displays the palette widow. For more iformatio o the palette, see Workig with Palettes. Expads the etire tree pae to show the child objects of all items i the tree. Collapses the etire tree pae to show oly the root message format. Repository Meu The followig commads are available from the Repository Meu. Table 2-15 Repository Meu Commads Meu Commad Log I Log Out Retrieve Store Store As Descriptio Displays the Process Itegrator Repository Logi dialog, allowig you to coect to the repository. Discoects from the repository. Retrieves a documet from the repository. Stores the curret documet i the repository. Stores the curret documet i the repository uder a differet ame BEA WebLogic XML/No-XML Traslator User Guide

67 Usig the Format Builder Tools Meu The followig commads are available from the Tools Meu. Table 2-16 Tools Meu Commads Meu Commad Import Test User Defied Types Optios Descriptio Displays a list of the istalled importers. Choose the importer from which you wat to import a message. Opes the Format Tester. Opes the Add/Remove User Defied Types dialog box. Displays the Format Builder Optios dialog. Help Meu The followig commads are available from the Help Meu. Table 2-17 Help Meu Commads Meu Commad Help Topics How Do I About Descriptio Displays the mai Help scree. Provides step-by-step istructios for performig the basic tasks i Format Builder. Displays versio ad copyright iformatio about Format Builder ad the JDK you are ruig. BEA WebLogic XML/No-XML Traslator User Guide 2-43

68 2 Buildig Format Defiitios 2-44 BEA WebLogic XML/No-XML Traslator User Guide

69 CHAPTER 3 Testig Format Defiitios Oce you have built a format defiitio, you ca test it usig the Format Tester feature of Format Builder. The Format Tester parses ad reformats data as a validatio test ad geerates sample biary or XML data. This sample data ca be edited, searched, ad debugged to produce the expected results. The Format Tester uses the XML Traslator rutime egie to perform the test traslatio. This sectio discusses the followig topics: Startig Format Tester Usig the Format Tester Mai Widow Testig Format Defiitios Debuggig Format Defiitios Startig Format Tester To start the tester: 1. Start Format Builder by clickig Start Programs BEA WebLogic E-Busiess Platform WebLogic Itegratio 2.0 xmltraslator Format Builder. The Format Builder mai widow displays. Note: To ru Format Tester, you must have a message format documet ope i Format Builder. BEA WebLogic XML/No-XML Traslator User Guide 3-1

70 3 Testig Format Defiitios 2. Choose Tools Test. The Format Tester dialog displays. Note: The Tester works with the curretly loaded message defiitio documet. Figure 3-1 Format Tester Dialog Usig the Format Tester Mai Widow The followig topics discuss the elemets of the Format Tester mai widow ad provide istructios for avigatig ad executig commads from the Format Tester mai widow. Usig the Meu Bar Usig the Shortcut Meus Usig the Biary Widow To use the Text feature, select the Text tab from withi the Biary widow to view all pritable characters. For example, carriage returs are show as lie breaks. If you have o-pritable characters, the Text widow displays them as small squares. 3-2 BEA WebLogic XML/No-XML Traslator User Guide

71 Usig the Format Tester Mai Widow Usig the Debug Widow Usig the Resize Bars The followig topics explai how to use each of these features to help you accomplish your task. Usig the Meu Bar The followig meus are available i Format Tester. All Format Tester meus are expadable from your keyboard by pressig Alt + muemoic key. Some meu commads are also executable usig Ctrl + letter accelerator keys. Figure 3-2 Meu Bar File Meu The followig commads are available from the File meu. Table 3-1 File Meu Commads Meu Commad Ope Biary Descriptio Allows you to select a file to be displayed i the biary widow. Note: The default file extesio for biary files is.data. Ope XML Allows you to select a file to be displayed i the XML sectio of the Format tester widow. Note: The default file extesio for XML files is XML. Save Biary Save XML Debug Log Allows you to save the cotets of the biary widow. Allows you to save the cotets of the XML widow. Allows the debug iformatio to be saved i a text file. BEA WebLogic XML/No-XML Traslator User Guide 3-3

72 3 Testig Format Defiitios Meu Commad Close Descriptio Closes the Format Tester widow. Edit Meu The followig commads are available from the Edit meu Table 3-2 Edit Meu Commads Meu Commad Cut Copy Paste Fid Fid Next Go To Descriptio Removes the curretly selected text ad places it o the clipboard for pastig ito aother locatio. Copies the curretly selected text ad places it o the clipboard for pastig ito aother locatio. Iserts the cut or copied text at the cursor locatio. Allows you to search for a hex or text value i the biary data. Cotiues your search to the ext istace of the specified value. Allows you to move the cursor i the biary editor to a specified byte offset. Display Meu The followig commads are available from the Display meu Table 3-3 Display Meu Commads Meu Commad XML Debug Clear Biary Descriptio Allows the XML data pael to be hidde or show. If hidde, the biary widow expads to fill the width of the tester. The To XML butto remais, but the splitter disappears. Allows the Debug output widow to be hidde or show. Resets the cotets of the biary widow to be empty. 3-4 BEA WebLogic XML/No-XML Traslator User Guide

73 Usig the Format Tester Mai Widow Meu Commad Clear XML Clear Debug Hex Offsets as Hexadecimal Hex Offsets as Decimal Text Values i ASCII Text Values i EBCDIC Descriptio Resets the cotets of the XML widow to be empty. Resets the cotets of the debug widow to be empty. Displays the offset values as hexadecimal. Selectig this optio turs off the Offsets as Decimal display. Displays the offset values as decimal. Mutually exclusive with the Offset as Hexadecimal selectio. Chages the character set used whe displayig the text portio of the hex editor display to ASCII. Mutually exclusive with the Values i EBCDIC meu selectio. Chages the character set used whe displayig the text portio of the hex editor display to EBCDIC. Mutually exclusive with the Values i ASCII meu selectios. Geerate Meu The followig commads are available from the Geerate meu. Table 3-4 Geerate meu Commads Meu Commad Biary XML Prompt while geeratig data Descriptio Geerates biary data to match the curret format specificatio. Geerates XML data to match the curret format specificatio. If selected, you are prompted durig the geeratio process to determie if optioal fields or groups should be geerated, determie which choice of childre should be geerated, ad determie how may times a repeatig group should repeat. BEA WebLogic XML/No-XML Traslator User Guide 3-5

74 3 Testig Format Defiitios Traslate Meu The followig commads are available from the Traslate meu. Table 3-5 Traslate Meu Commads Meu Commad Biary to XML XML to Biary Descriptio Coverts the cotets of the biary widow to XML. Coverts the cotets of the XML widow to biary. Usig the Shortcut Meus Istead of usig the stadard meus to fid the commad you eed, use the right mouse butto to click a item i the pop-up shortcut meu. The followig commads are available from the Shortcut meus. Note: Some commads may be uavailable, depedig o which display pael the mouse poiter is curretly i. Table 3-6 Shortcut Meu Commads Meu Commad Cut Copy Paste Clear Geerate To XML Descriptio Removes the curretly selected text ad places it o the clipboard for pastig ito aother locatio. Copies the curretly selected text ad places it i the clipboard for pastig ito aother locatio. Iserts the cut or copied text at the cursor locatio. Resets the cotets of the biary, XML, or Debug widow to be empty. Geerates biary or XML data to match the curret format specificatio. Coverts the cotets of the biary widow to XML. 3-6 BEA WebLogic XML/No-XML Traslator User Guide

75 Usig the Format Tester Mai Widow Meu Commad To Biary Text i ASCII Text i EBCDIC Descriptio Coverts the cotets of the XML widow to biary. Chages the character set to ASCII whe displayig text with the hex editor. Chages the character set to EBCDIC whe displayig text with the hex editor. Usig the Biary Widow The biary data display pael acts as hexadecimal editor, displayig data offsets, the hex value of idividual bytes, ad the correspodig text, which ca be optioally displayed as ASCII/EBCDIC characters. The Biary widow cosists of the followig three tabs used to select which mode to display the data: Hex Editor Escaped Text Text The editor allows for editig of the hex byte or the text value. If a hex data value is modified, the correspodig text value is updated, ad vice versa. Usig the Data Offset Feature The data offset feature of the hexadecimal editor allows you to display your data offsets as Hexadecimal or Decimal. To chage your data offsets: 1. Choose Display Hex. The followig two data offset optios display. l Offsets as Hexadecimal l Offsets as Decimal 2. Click the display optio that best suits your eeds. The data offset pael of the Biary widow dyamically chages to reflect your choice. BEA WebLogic XML/No-XML Traslator User Guide 3-7

76 3 Testig Format Defiitios Usig the Escaped Text Feature Usig the Text Feature To use the Escaped Text feature, select the Escaped Text tab from withi the Biary widow to view o-pritable characters as escape sequeces. The Escaped Text widow displays o-pritable characters as hex values. For example, the Escaped Text widow does ot show lie breaks, but escapes the carriage returs. To use the Text feature, select the Text tab from withi the Biary widow to view all pritable characters. For example, carriage returs are show as lie breaks. If you have o-pritable characters, the Text widow displays them as small squares. Usig the XML Widow The XML data pael displays XML data that has bee coverted or traslated from the cotets of the Biary pael, or XML that is to be coverted to Biary. The cotets of the XML pael ca be cleared or edited to suit your eeds. Whe XML is geerated, the XML Formattig Optios specified i the Format Builder optios dialog box are used. Refer to Settig Format Builder Optios for more iformatio. Usig the Debug Widow The Debug widow displays the actios that take place durig the traslatio operatio, ay errors that are ecoutered, ad field ad group values alog with delimiters. To determie the locatio of the error, determie the last field that parsed successfully ad examie the specificatio of the ext field o the Tree Pae of Format Builder. Whe you ope the Format Tester, oly the Biary ad XML widows are visible. To ope the Debug widow, choose Display Debug to toggle the Debug widow o ad off. The Debug widow opes below the Biary ad XML widows. Debug output is restricted to the most recet 64 KB of messages. This restrictio prevets large debug output from causig a JVM out of memory evet. 3-8 BEA WebLogic XML/No-XML Traslator User Guide

77 Testig Format Defiitios The debug feature allows for full debug iformatio to be captured to a file. See the Usig the Debug Log topic for more iformatio. Note: Usig the Debug widow or Log File icreases the time required to traslate from XML to Biary. Usig the Resize Bars Resize bars are located betwee the Biary, XML, ad Debug widows ad eable each widow to be resized to suit your eeds. Each resize bar ca selected ad dragged up ad dow, or left or right, as appropriate, to elarge oe of the widows ad reduce the other. Each resize bar also cotais two directioal buttos that ca be clicked to elarge or dimiish ay of the three widows. Testig Format Defiitios Perform the followig steps to test a message format defiitio. 1. Start Format Builder. 2. Ope a Message Format file. 3. Start Format Tester. 4. Click File Ope Biary, or File Ope XML to load the file you wat to traslate ad view, or eter your ow data i oe of the two data widows. 5. Select Display Debug if you wat to view the actios that take place durig the traslatio operatio. This step is optioal, but you must ope the Debug widow prior to the traslatio operatio i order to view ay debug iformatio later. 6. Select Traslate Biary to XML, or Traslate XML to Biary to traslate your data to the appropriate format. The traslated data displays i the Biary or XML widow. BEA WebLogic XML/No-XML Traslator User Guide 3-9

78 3 Testig Format Defiitios Figure 3-3 Format Tester Debug messages geerated durig traslatio process 7. Correct the errors, if preset, ad test the traslatio agai. 8. Cotiue this process util the traslatio is successful. Note: You ca leave Format Tester ope while you modify the Message Format from withi Format Builder. Ay chages to the message defiitio are automatically detected by Format Tester. Debuggig Format Defiitios The followig topics discuss the various Format Tester features you ca use to debug ad correct your data. Searchig For Values 3-10 BEA WebLogic XML/No-XML Traslator User Guide

79 Debuggig Format Defiitios Positioig to a Offset Usig the Debug Log Searchig For Values The Format Tester Fid feature allows you to search for hex or text values i the biary data. Perform the followig steps to perform a hex or text value search. 1. From withi Format Tester, choose File Ope Biary to ope the biary data file you wat to search. 2. Choose Edit Fid. The Fid dialog box opes. Figure 3-4 Fid Dialog Box 3. Eter the value you wat to fid. 4. Select Text or Hex to specify what type of value you are searchig. 5. Specify the directio you wat to search. 6. Specify the positio i the file from which you wat your search to begi. 7. Click OK. The Fid dialog box disappears ad your cursor displays ext to the value for which you are searchig. 8. Choose Edit Fid Next to search to the ext istace of the specified value. BEA WebLogic XML/No-XML Traslator User Guide 3-11

80 3 Testig Format Defiitios Positioig to a Offset The Format Tester GoTo feature allows you to move the cursor i the biary editor to a byte offset you specify. To move to a specified offset: 1. From withi Format Tester, choose Edit Go To. The Go To dialog box displays. Figure 3-5 Goto Dialog Box 2. Eter the offset value you wat to go to. 3. Select either Dec or Hex to specify the type of offset you wat to go to. 4. Select either Forwards or Backwards to specify the directio you wat your search to proceed withi the file. 5. Select either Begiig of File, Curret Positio, or Ed of File to specify the startig positio of your search withi the file. 6. Click OK to have your cursor placed ext to the offset you are lookig for. The Go To dialog box disappears after you click the OK butto. Usig the Debug Log The Format Tester debug log feature allows you to save your debug iformatio i a text file. To use the Format Tester debug log, choose File Debug Log. You will be preseted with a stadard Save As dialog box from which you ca select the destiatio directory ad ame for this log file. If you select a existig file, the ew debug iformatio will be appeded oto the ed of the existig file BEA WebLogic XML/No-XML Traslator User Guide

81 Debuggig Format Defiitios Format Tester saves debug logs to the curretly selected directory or the last directory selected. BEA WebLogic XML/No-XML Traslator User Guide 3-13

82 3 Testig Format Defiitios 3-14 BEA WebLogic XML/No-XML Traslator User Guide

83 CHAPTER 4 Importig Meta Data XML Traslator provides three utilities that allow you to import COBOL copybooks, covert C structure defiitios ito MFL Message Defiitio, ad import FML Field Table classes. The followig topics provide iformatio o how to perform these types of imports. Importig a COBOL Copybook Importig C Structures Importig a FML Field Table Class Importig a COBOL Copybook XML Traslator icludes a feature that allows you to import a COBOL copybook ito Format Builder creatig a message defiitio to traslate the COBOL data. Whe importig a copybook, commets are used to documet the imported copybook ad the Groups ad Fields it cotais. To import a COBOL copybook: 1. Choose Tools Import COBOL Copybook Importer. The COBOL Copybook Importer dialog displays. BEA WebLogic XML/No-XML Traslator User Guide 4-1

84 4 Importig Meta Data Figure 4-1 COBOL Copybook Importer 2. Eter data i the fields as described i the followig table: Table 4-1 COBOL Copybook Importer Field Descriptios Field File Name Browse Descriptio Type the path ad ame of the file you wat to import. Click to avigate to the locatio of the file you wat to import. Byte Order Big Edia Select this optio to set the byte order to Big Edia. Note: This optio is used for IBM 370, Motorola, ad most RISC desigs (IBM maiframes ad most Uix platforms). Little Edia Select this optio to set the byte order to Little Edia. Note: This optio is used for Itel, VAX, ad Uisys processors (Widows, VMS, Digital, Uix, ad Uisys). Character Set EBCDIC Select this optio to set the character set to EBCDIC. Note: These values are attributes of the origiatig host machie. 4-2 BEA WebLogic XML/No-XML Traslator User Guide

85 Importig a COBOL Copybook Field ASCII Descriptio Select this optio to set the character set to ASCII. Note: These values are attributes of the origiatig host machie. Other The character ecodig of the field data is selected usig a list of code pages. Actio Buttos OK Cacel About Imports the COBOL Copybook usig the settigs you defied. Closes the dialog ad returs to Format Builder without importig. Displays iformatio about the COBOL Copybook importer icludig versio ad supported copybook features. Oce you have imported a copybook, you may work with it as you would ay message format defiitio. If a error or usupported data type is ecoutered i the copybook, a message is displayed iformig you of the error. You ca choose to display the error or save the error to a log file for future referece. COBOL Copybook Sample Files The followig table provides a listig ad descriptio of the sample files istalled for the COBOL Copybook Importer. All directory ames are relative to the XML Traslator istallatio directories. Table 4-2 COBOL Copybook Sample Files Directory File Descriptio samples\cobol emprec5.cpy Sample Copybook file. samples\cobol emprec5.data Test data correspodig to emprec5.cpy. BEA WebLogic XML/No-XML Traslator User Guide 4-3

86 4 Importig Meta Data Importig C Structures XML Traslator icludes a C Struct importer utility that coverts a C struct defiitio ito a MFL Message Defiitio by geeratig the followig two types of output data: MFL documet C Code Both the MFL documet ad C code output methods require a.c or.h iput file to be specified, parsed, ad the desired structure selected before choosig whether to geerate MFL (default) or C code. I additio to the requiremet that all iput to the parser cosist of valid C code, all outside refereces, such as #iclude(s), #defie(s), ad typedef(s) must be resolved prior to use. This may require had editig or use of the compiler s pre-processor. There are platform cosideratios that affect the descriptio of data for C code. For example, the legth of a log o a platform will affect the biary data that coforms to a particular structure defiitio. There are two methods for dealig with these platform depedecies depedig o whether or ot MFL is geerated directly ito Format Builder. If you wat to geerate MFL ad have that MFL displayed immediately i Format Builder, you must supply the platform depedet parameters i a cofiguratio file. Alterately, by choosig to geerate C code source, you may compile the C code o the desired machie. The compiler o that machie accouts for the ecessary platform depedet iformatio. This will produce a executable file that whe ru will produce a MFL documet ad biary data that coforms to that MFL i separate files. The MFL documet ca be opeed i Format Builder ad the biary data file ca be opeed i Format Tester. Geeratig MFL directly ito Format Builder requires platform cofiguratio parameters foud i a existig cofiguratio file or a ewly geerated cofiguratio file created with the hardware profile editor. The hardware profile editor allows you to specify a existig profile that ca be loaded, updated, ad saved. The source code for a utility that geerates hardware profiles accordig to your eeds is provided i the samples\cgf subdirectory. 4-4 BEA WebLogic XML/No-XML Traslator User Guide

87 Importig C Structures C Struct Importer Sample Files The followig table provides a listig ad descriptio of the sample files istalled for the C Struct Importer. All directory ames are relative to the XML Traslator istallatio directory. Table 4-3 C Struct Importer Sample Files Directory File Descriptio samples\c emprec5.h A C versio of the emprec5.cpy sample Copybook file, with some typedefs. samples\c emprec5.h A variat of the emprec5.h file usig a ested struct defiitio, but o typedefs. samples\c emprec5s.h A simple versio of the emprec5.h file. samples\c tfsez.h A small sample extracted from the tfs.h file. Desiged to test recursive typedefs. samples\cfg cprofile.c The source code for the cprofile.c utility. This utility is desiged to geerate profiles o various platforms. The followig.cfg files were all geerated by the cprofile program o various platforms. Each.cfg file cotais the DESCRIPTION. samples\cfg dec8cc.cfg DEC Alpha 1091, Digital Uix 4.0e, cc compiler. samples\cfg hp5cc.cfg HP-UX B.11.00, cc compiler. samples\cfg t4bcc5.cfg Widows NT 4.0, Borlad 5.x compiler, default switches. samples\cfg t4vc6.cfg Widows NT 4.0, Visual C++ 6.x compiler, default switches. samples\cfg su7cc.cfg SuOS 5.8, cc compiler. samples\cfg w95bcc5.cfg Widows 95, Borlad 5.x compiler, default aligmet. samples\cfg w95vc5.cfg Widows 95, Visual C++ 5.x compiler, default aligmet. BEA WebLogic XML/No-XML Traslator User Guide 4-5

88 4 Importig Meta Data Startig the C Struct Importer To start the C Struct Importer: 1. Start Format Builder by clickig Start Programs BEA WebLogic E-Busiess Platform WebLogic Itegratio 2.0 xmltraslator Format Builder. The Format Builder mai widow displays. 2. Choose Tools Import C Struct Importer. The C Struct Importer dialog box displays. Figure 4-2 C Struct Importer Dialog Box The C Struct Importer dialog box opes with MFL specified as the default output ad cotais the followig fields. Table 4-4 C Struct Importer Field Descriptios Field Descriptio Iput Iput File Eter the path ad ame of the file you wat to import. 4-6 BEA WebLogic XML/No-XML Traslator User Guide

89 Importig C Structures Field Browse Structure Parse Descriptio Click Browse to avigate to the directory cotaiig the file you wat to use. This list box is populated with the list of structures foud i the iput file after it has bee successfully parsed. Click Parse to parse the iput file. If successful, the Structure list box is populated with the list of structures foud i the iput file. Output MFL C Code If you select this optio butto, you ca geerates MFL from a structure defiitio ad a hardware cofiguratio file. You will see the Hardware Profile group box. If you select this optio butto, you ca geerate C source code to compile o the target machie ad execute to produce MFL. You will see the C Code File Names group box. Hardware Profile Name Browse Save Save As Edit New Specify a existig profile either by eterig the file ame or usig the Browse butto. The prebuilt hardware profiles may be foud i the samples\cfg directory. Click Browse to avigate to the directory cotaiig the file you wat to use. Saves the curret hardware profile. Saves the curret hardware profile uder aother ame. Click Edit to edit the curret hardware profile listed i the Hardware Profile Name field. Click New to create a ew hardware profile. BEA WebLogic XML/No-XML Traslator User Guide 4-7

90 4 Importig Meta Data Figure 4-3 C Struct Importer Dialog Box Field Descriptio C Code File Names MFL Ge Browse Data Ge Browse Specifies the C source code file ame that must be compiled o the target machie to geerate MFL. Click Browse to avigate to the directory where you wat the file to reside. Specifies the C source code file ame that must be compiled o the target machie for geeratig test data. Click Browse to avigate to the directory where you wat the file to reside. Actio Buttos OK Cacel About Click OK to save your hardware profile chages. Click Cacel to dismiss your hardware profile chages. Click About to view C Struct Importer versio ad date iformatio. 4-8 BEA WebLogic XML/No-XML Traslator User Guide

91 Importig C Structures Uderstadig Hardware Profiles The hardware profiles used by the C Struct Importer cotai data size ad aligmet iformatio for specific hardware ad compiler combiatios ad are used to geerate MFL for C structures. They are stored i cofiguratio files that ca be created, loaded, updated, ad saved. The cprofile.c source file located i the samples\cfg directory is used to geerate these profiles for ay platform. This code is desiged to be compiled ad executed o the target platform with the complier ormally used ad should compile ad execute o ay platform with a ANSI stadard C compiler i order to geerate a profile cofiguratio file that ca be imported ito the C Struct Importer. Buildig the Hardware Profile Utility To produce acceptable parser iput, execute the followig commads for each of the platforms listed. O Widows NT, use the VC++ pre-processor: cl /P cprofile.c (output i cprofile.i)- VC++ Compiler gcc -P -E cprofile.c>cprofile.i - GNU Compiler O Uix: cc -P cprofile.c (output i cprofile.i) Ruig the Hardware Profile Utility At a commad prompt, eter the followig text to execute the cprofile program ad specify a hardware profile ame: cprofile cofigfileame [DESCRIPTION] The optioal descriptio is placed i the cofiguratio file as the DESCRIPTION value. If the descriptio cotais embedded blaks, eclose it i quotes. BEA WebLogic XML/No-XML Traslator User Guide 4-9

92 4 Importig Meta Data Geeratig MFL Perform the followig steps to geerate MFL. 1. Eter a file ame i the Iput File field, or click Browse to select a file. 2. Click Parse to parse the file. Upo completio, the Structure list box is populated with the list of structures foud i the iput file. Note: If your file does ot parse correctly, it is recommeded that you proceed i oe of two ways: Ru your.h or.c source code through the compilers preprocessor ad ru that output through the parser. Commet out the character creatig the parse failure ad attempt to parse agai. Please ote that the parser fails at the first failure it ecouters. 3. Select the desired structure from the Structure drop-dow list box. At this poit, you must provide some profile cofiguratio data to geerate the MFL directly. You ca do this by creatig a ew hardware profile, or specifyig a existig profile. 4. Specify a existig profile or create a ew oe by performig oe of the followig procedures. l Note: l Specify a existig profile either by eterig the file ame i the Hardware Profile Name field, or click Browse to select a file. Click Edit to ope the hardware profile editor if you eed to view or edit the profile parameters. hardware profiles for commo cofiguratios are prebuilt ad may be foud i the samples\c\cfg directory. Click New to create a ew hardware profile. This opes the Hardware Profile editor loaded with the default parameters. Specify a Profile Name, a descriptio, ad modify the primitive data types ad byte order to suit you eeds BEA WebLogic XML/No-XML Traslator User Guide

93 Importig C Structures Figure 4-4 C Struct Importer Hardware Profile Dialog Box 5. Click OK to save your hardware profile chages ad retur to the C Struct Importer dialog box. 6. Click OK to geerate your MFL. If the geeratio is successful, you are retured to Format Builder with a MFL object listed i the Tree Pae. The MFL object reflects the same ame as the iput file used i the parse operatio. If errors are detected durig the geeratio process, the MFL Geeratio Errors dialog box displays providig you the opportuity to view or file the error log. BEA WebLogic XML/No-XML Traslator User Guide 4-11

94 4 Importig Meta Data Figure 4-5 MFL Geeratio Errors Dialog Box 7. Click Display Error Log to view ay errors ecoutered, click Save Error Log to save the error log to the locatio of your choice, or click Cacel to dismiss the MFL Geeratio Errors dialog box. Oce you have determied what errors were geerated, you ca retur to the C Struct Importer ad repeat the prior steps. Geeratig C Code Perform the followig steps to geerate C code. 1. Eter a file ame i the Iput File field, or click Browse to select a file. 2. Click Parse to parse the file. Upo completio, the Structure list box is populated with the list of structures foud i the iput file. Note: If your file does ot parse correctly, it is recommeded that you proceed i oe of two ways: Ru your.h or.c source code through the compilers preprocessor ad ru that output through the parser. Commet out the character creatig the parse failure ad attempt to parse agai. Please ote that the parser fails at the first failure it ecouters. 3. Select the desired structure from the Structure drop-dow list box. 4. Select the C Code optio butto. 5. Eter a file ame i either the MFL Ge or Data Ge fields, or click Browse to select a file BEA WebLogic XML/No-XML Traslator User Guide

95 Importig a FML Field Table Class 6. Click OK. You will be wared about overwritig existig files ad otified about the success or failure of the code geeratio. 7. Copy the geerated source code to the target platform ad compile ad execute it. Note: You must copy the iput file cotaiig the struct declaratios as well. Both programs, whe compiled, take a argumet of the output file ame. 8. Copy the geerated MFL or data back to the platform ruig Format Builder. Importig a FML Field Table Class The FML Field Table Class Importer facilitates the itegratio of WebLogic Tuxedo Coector ad WebLogic Process Itegrator (Process Itegrator). Tuxedo applicatio buffers are traslated to/from XML by the FML to XML Traslator that is a feature of WebLogic Tuxedo Coector. The itegratio of Weblogic Process Itegrator with Process Itegrator requires the creatio of the XML that is passed betwee the WebLogic Tuxedo Coector traslator ad Process Itegrator. To this ed, you ca use the FML Field Table Class Importer ad the XML geeratio feature of Format Tester to facilitate the creatio of the ecessary XML. FML Field Table Class Importer Prerequisites Perform the followig steps prior to startig Format Builder. 1. Move the field tables associated with the FML buffer from the Tuxedo system to the WebLogic Server/WebLogic Tuxedo Coector eviromet. 2. Use the weblogic/wtc/jatmi/mkfldclass utility to build java source code represetig the field tables. 3. Compile the source code. The resultig class files are called fldtbl classes because they implemet the FldTbl iterface. These fldtbl classes must be moved to a locatio specified i the Format Builder CLASSPATH. BEA WebLogic XML/No-XML Traslator User Guide 4-13

96 4 Importig Meta Data The samples/fml directory cotais several fldtbl class fields that you ca use as samples. These samples allow you to work through the followig steps without havig completed the previous three steps. Note: These steps are ormally doe whe cofigurig WTC, so these class files may already exist. FML Field Table Class Sample Files The followig table provides a listig ad descriptio of the sample files istalled for the FML Field Table Class Importer. All directory ames are relative to the XML Traslator istallatio directory. Table 4-5 FML Field Table Class Sample Files Directory File Descriptio samples\fml bakflds.class A compiled source file that serves as iput to the FML Field Table Class Importer. samples\fml bakflds.java A fldtbl source file geerated by the mkfldclass utility. samples\fml crdtflds.class A compiled source file that serves as iput to the FML Field Table Class Importer. samples\fml crdtflds.java A fldtbl source file geerated by the mkfldclass utility. samples\fml tbtest1flds32.class A compiled source file that serves as iput to the FML Field Table Class Importer. samples\fml tbtest1flds32.java A fldtbl source file geerated by the mkfldclass utility. Creatig XML with the FML Field Table Class Importer Perform the followig steps to create a XML documet with the FML Field Table Class Importer BEA WebLogic XML/No-XML Traslator User Guide

97 Importig a FML Field Table Class 1. Start Format Builder by clickig Start Programs BEA WebLogic E-Busiess Platform WebLogic Itegratio 2.0 xmltraslator Format Builder. The Format Builder mai widow displays. 2. Choose Tools Import FML Field Table Class Importer. The FML Field Table Class Importer dialog displays. 3. Eter the ame of the fldtbl class file that is to be processed ito the Class Names field. Because a sigle FML buffer may cotai fields from several field tables, you ca eter oe or more fldtbl class ame files i the Class Names field. The list should be comma separated ad each ame does ot have to iclude the.class extesio. Note: If ay of the listed classes are ot fldtbl classes created by the weblogic/wtc/jatmi/mkfldclass utility, or are ot i Format Builder s CLASSPATH, the a error dialog box is displayed. However, the valid fldtbl classes i the list will still be processed. 4. Click Load. The ames of the fields from the field tables appear i the Available Fields list. The Available Fields list does ot allow for duplicate ames. If the ame of a field appears i differet field tables, it will oly appear oce o the list. BEA WebLogic XML/No-XML Traslator User Guide 4-15

98 4 Importig Meta Data 5. Select the desired fields from the Available Fields list ad click Add. The selected fields will appear i the Selected Fields list. To remove a field from the Selected Fields list, select the desired field ad click Remove. 6. Click OK after you have successfully selected all the ecessary field ames. The FML Field Table Class Importer dialog will closes ad the geerated MFL will appear i the Format Builder tree pae. The selected fields will be listed i the order they appear i the selected Fields list. 7. Edit the created MFL documet to specify the order ad occurreces of the fields that will be i the XML documet which is passed to the WTC FML/XML Traslator from Process Itegrator. 8. Choose Tools Test to ope Format Tester. 9. From the Format Tester meu bar, choose Geerate XML. 10. Format Tester ow creates a XML documet that coforms to the MFL documet i Format Builder. Edit the data cotet of the fields as desired. 11. Choose File Save XML to save the XML documet to the ame ad locatio of your choice. The created XML may be imported ito Process Itegrator by usig the XML istace editor. Refer to the WebLogic Process Itegrator documetatio for iformatio o importig XML BEA WebLogic XML/No-XML Traslator User Guide

99 CHAPTER 5 Retrievig ad Storig Repository Documets The XML Traslator repository feature provides a cetralized documet storage mechaism that supports the followig four documet types: Message Format Laguage documet XML Documet Type Defiitio documet XML Schema documet XSLT Stylesheet The repository allows the supported documets to be shared betwee the compoets of WebLogic Itegratio. The repository provides access to these documet types ad provides maipulatio of repository documets icludig access to the documet text, descriptio, otes, ad removal of the documet. The repository allows the supported documets to be shared betwee XML Traslator, WebLogic Process Itegrator (Process Itegrator), WebLogic Server (WLS), ad WebLogic Collaborate (WLC). The repository also icludes a batch import utility that allows previously costructed MFL, DTD, XML Schema, ad XSLT documets residig o a differet file system to be easily migrated ito the repository. This sectio discusses the followig topics: Accessig the Repository Retrievig Repository Documets Storig Repository Documets Importig Documets ito the Repository BEA WebLogic XML/No-XML Traslator User Guide 5-1

100 5 Retrievig ad Storig Repository Documets Usig the Repository Documet Chooser Accessig the Repository To access the Repository: 1. Start Format Builder by clickig Start Programs BEA WebLogic E-Busiess Platform WebLogic Itegratio 2.0 xmltraslator Format Builder. The Format Builder mai widow displays. 2. Choose Repository Log I. The Process Itegrator Repository Logi widow opes. Figure 5-1 Process Itegrator Repository Logi Dialog Box 3. Eter the Process Itegrator userid specified for the coectio i the User Name field. 4. Eter the Process Itegrator password specified for the coectio i the Password field. 5. Eter the server ame ad Port umber i the Server[:port] field. Note: The Process Itegrator Repository Logi widow allows up to three usuccessful logi attempts, after which, a logi failure message is displayed. If you experiece three logi failures, choose Repository Log I to repeat the logi procedure. 5-2 BEA WebLogic XML/No-XML Traslator User Guide

101 Retrievig Repository Documets 6. Click Coect. If your logi is successful, the Logi widow disappears ad the Format Builder Title bar displays the server ame ad port umber etered o the Process Itegrator Repository Logi widow. You may ow choose ay of the active repository meu items to access. Repository Meu The followig commads are available from the Repository Meu. Table 5-1 Repository Meu Commads Meu Commad Log I Log Out Retrieve Store Store As Descriptio Displays the Process Itegrator Repository Logi dialog, allowig you to coect to the repository. Discoects from the repository. Retrieves a documet from the repository. Stores the curret documet i the repository. Stores the curret documet i the repository uder a differet ame. Retrievig Repository Documets Perform the followig steps to retrieve repository documets: 1. Start Format Builder. 2. Log i to the Repository. 3. Choose Repository Retrieve. The Select-documet-to-retrieve dialog box opes. BEA WebLogic XML/No-XML Traslator User Guide 5-3

102 5 Retrievig ad Storig Repository Documets 4. Select the documet you wat to retrieve from the documet list. 5. Click Retrieve. The Select-documet-to-retrieve dialog box is dismissed ad you are retured to the Format Builder mai widow with your selected documet listed i the Tree Pae. Oce you have retrieved the specified documet, you ca edit it as you would ay MFL documet withi Format Builder, store the documet back ito the repository, store the documet back ito the repository with a differet ame, or save as a local file. Aytime you ope a documet that is stored i the repository, a read-oly Documet Repository Properties box displays i the Message Format detail pael whe the message format ode is selected. This properties box provides you with a documet descriptio ad ay otes that were attached to the documet. Storig Repository Documets Perform the followig steps to store a MFL documet i the repository: 1. Start Format Builder. 2. Ope the MFL documet you wat to store i the repository. 3. Log i to the repository. 4. Choose Repository Store As. The Store As dialog box opes. 5. Eter the ame you wat to associate with this repository documet i the Name field. 6. Eter a descriptio of the repository documet i the Descriptio field. 7. Eter ay otes you would like attached to the documet i the Notes field. 8. Click Store. The Store As dialog box is dismissed ad your MFL documet displays i the Format Builder Tree Pae. A Documet Repository Properties box with documet Descriptio ad Notes iformatio displays i the Detail pael of the Format Builder Message Format Detail Pael. If your Format Builder optios specify geeratio of a DTD/XML Schema, these documets will also be stored i the repository usig the supplied ame. 5-4 BEA WebLogic XML/No-XML Traslator User Guide

103 Importig Documets ito the Repository Importig Documets ito the Repository The XML Traslator Repository Batch Import Utility provides a commad lie iterface to the Repository. It provides a mechaism for easily importig previously built MFL documets ito the Repository. The Batch Importer is capable of importig MFL, DTD, class,.xslt, ad XML schema documets i ay combiatio. The Batch Importer also works with ay plug-i repository. Use of the repository importer with the Process Itegrator Repository requires the placemet of a wlxt-repository.properties file to be placed i a CLASSPATH directory. The cotets of this file idetify the WebLogic Server hostig the Process Itegrator repository. For example: wlxt.repository.url=t3://localhost:7001 Ivokig the Batch Import Utility At the cosole commad prompt, ivoke the Batch Import Utility usig the followig commad. java com.bea.wlxt.repository.import [-v] [-] [-t type] [-f folder] files... The followig iformatio describes the commads ad their optios. -v - -f specifies that verbose mode is o. This switch may appear aywhere withi the commad lie ad affects all operatios that follow. Verbose mode is disabled by default. specifies that verbose mode is off. This switch may appear aywhere withi the commad lie ad affects all operatios that follow. Verbose mode is disabled by default. Optioal switch specifyig the paret folder of all the followig files. Multiple -f switches may be specified to chage folders durig a import executio. By default, documets are imported ito the root folder of the BEA WebLogic XML/No-XML Traslator User Guide 5-5

104 5 Retrievig ad Storig Repository Documets repository. A special -f switch argumet may be used to specify the root folder. Folder ames specified i the -f switch are always absolute pathames from the repository root folder. Folder ames withi a path should be separated by a forward slash. -t files Optioal switch specifyig the default type of all the followig files. The default type is assiged to documets whe the documet type caot be determied by the file extesio. Valid values are.mfl,.dtd,.class,.xsl, ad.xsd. specifies oe or more fileames to be imported. Wildcards may be used based o the curret commad lie shell. All switches take effect at the poit i the commad lie where the are ecoutered ad remai i effect util overridde by aother switch. For example, the followig commad lie imports all.dtd,.class, ad.mfl files i the curret directory, but oly eables verbose mode while class files are imported. java com.bea.wlxt.repository.import *.dtd -v *.class - *.mfl The documet type of imported documets is derived from the file extesio as follows: Table 5-2 Supported Documet Types ad Extesios File Extesio.dtd.xsd.mfl.class.xsl aythig else Documet Type Assiged DTD XML Schema MFL Java Class Extesible Stylesheet Laguage Default type (defaults to MFL) 5-6 BEA WebLogic XML/No-XML Traslator User Guide

105 Usig the Repository Documet Chooser Usig the Repository Documet Chooser The Repository Documet Chooser provides a user iterface exposig the cotets of the repository. The user iterface cosists of six differet dialog ad message boxes that allow you to store, retrieve, ad modify repository documets. Usig the Ope Documet Dialog Box The followig is a image of the Ope Documet dialog box used for retrievig repository documets. Figure 5-2 Select Documet To Retrieve Dialog Box The followig referece umbers refer to those listed i the previous figure. 1 The Curret Folder field specifies the ame of the curret repository folder. BEA WebLogic XML/No-XML Traslator User Guide 5-7

106 5 Retrievig ad Storig Repository Documets The Up Folder ico is used to move up to the paret of the curret folder if the curret folder is ot the root folder of the repository. The Root Folder ico is used to make the root the curret folder if the curret folder is ot the root folder of the repository. The New Folder ico is used to create a ew child folder i the curret folder. This ico is disabled if the repository does ot support folders. The list field cotais all the MFL documets i the curret folder. Each etry i the list is prefixed by a ico idicatig the type of object: Folder or MFL. Selectig a etry i the list causes its iformatio to be displayed. Double-clickig a etry i the list causes it to be retrieved or become the curret folder. The Retrieve butto opes the selected documet. If a folder is curretly selected, pressig this butto causes it to become the curret folder. The Cacel butto causes the dialog box to be dismissed. The Name field specifies the ame of the curretly selected documet folder. The Descriptio field provides the descriptio of the curretly selected documet folder. The Notes field provides the otes attached to the curretly selected documet folder. Usig the Store Documet Dialog Box The followig is a image of the Store Documet dialog box used for storig repository documets. 5-8 BEA WebLogic XML/No-XML Traslator User Guide

107 Usig the Repository Documet Chooser Figure 5-3 Store Documet Dialog Box The Store Documet dialog box differs from the Ope Documet dialog box oly i its ability to eter a ew documet ame, descriptio, or otes. Usig the Shortcut Meus Both the Ope Documet ad Store Documet dialog boxes provide the capability to update repository objects, reame existig objects, ad remove objects. These update features are accessed by right-clickig o a repository object. The followig is a image of the shortcut meus. Figure 5-4 Store Documet Dialog Box Selectig Delete wars you that a object is about to be permaetly removed from the repository. BEA WebLogic XML/No-XML Traslator User Guide 5-9

108 5 Retrievig ad Storig Repository Documets Figure 5-5 Cofirm Delete Dialog Box Selectig Reame allows the folder or documet to be reamed i the repository. The followig dialog box displays requestig the ew object ame. Pressig Cacel aborts the reame operatio. Figure 5-6 Reame Folder NewFolder Dialog Box Selectig Properties allows the descriptio ad otes of the selected object to be updated. Figure 5-7 Modify Documets - Documet Geerate Dialog Box 5-10 BEA WebLogic XML/No-XML Traslator User Guide

109 Biary to XML 6 Usig the Ru-Time Compoet The ru-time compoet of XML Traslator cosists of a Java class amed WLXT. This class has various methods used to traslate data betwee biary ad XML formats. This Java class ca be deployed i a EJB usig BEA WebLogic Server, ivoked from a workflow i BEA WebLogic Process Itegrator, or itegrated ito ay Java applicatio. The XML Traslator class provides several parse() methods that traslate biary data ito XML. XML Traslator also provides several serialize() methods that traslate XML data to a biary format. Biary data formats are described via MFL documets. XML Traslator uses MFL documets to read ad write biary data to or from XML. MFL documets are specified by a URL i a parse() or serialize() method. The code samples below illustrate how to use XML Traslator to parse biary data ito XML, ad serialize XML ito biary. Biary to XML The followig code listig uses the parse() method of XML Traslator to parse a file cotaiig biary data ito XML. Listig 6-1 Sample Biary to XML Parse() Method 1 import com.bea.wlxt.*; 2 import org.w3c.dom.documet; BEA WebLogic XML/No-XML Traslator User Guide 6-1

110 6 Usig the Ru-Time Compoet 3 import java.io.fileiputstream; 4 import java.et.url; 5 6 public class Example 7 { 8 public static void mai(strig[] args) 9 { 10 try 11 { 12 WLXT wlxt = ew WLXT(); 13 URL mfldocumetname = ew URL( file:mymfl.mfl ); 14 FileIputStream i = ew FileIputStream( mybiaryfile ); Documet doc = wlxt.parse(mfldocumetname, i, ull); 17 Strig xml = wlxt.getxmltext(doc, 0, 2); 18 System.out.pritl(xml); 19 } 20 catch (Exceptio e) 21 { 22 e.pritstacktrace(system.err); 23 } 24 } 25} I the prior listig, a ew istace of the XML Traslator class is istatiated at lie 12. A Uiform Resource Locator (URL) is created for a MFL file that was previously created with Format Builder. A FileIputStream is created for some biary data that exists i the file mybiaryfile. The URL for the MFL documet, ad the stream of biary data, are the passed ito the parse method of XML Traslator at lie 16. The parse method coverts the biary data ito a istace of a W3C Documet object. This object ca be coverted to XML text via XML Traslator getxmltext() method (as show o lie 17), or maipulated directly via the W3C DOM API. Geeratig XML with a Referece to a DTD WXLT also icludes parse() methods that allow a referece to a Documet Type Defiitio (DTD) or a XML Schema to be output i the resultig XML documet. The followig listig illustrates this geeratio. 6-2 BEA WebLogic XML/No-XML Traslator User Guide

111 Biary to XML Listig 6-2 Sample XML Geeratio with a DTD Referece Code Example 1 import com.bea.wlxt.*; 2 import org.w3c.dom.documet 3 import java.io.fileiputstream; 4 import java.et.url; 5 6 public class Example2 7 { 8 public static void mai(strig[] args) 9 { 10 try 11 { 12 WLXT wlxt = ew WLXT(); 13 URL mfldocumetname = ew URL( file:mymfl.mfl ); 14 FileIputStream i = ew FileIputStream( mybiaryfile ); Documetdoc=wlxt.parse(mflDocumetName,i, mydtd.dtd, 17 ull);strig xml = wlxt.getxmltext(doc, 0, 2); 18 System.out.pritl(xml); 19 } 20 catch (Exceptio e) 21 { 22 e.pritstacktrace(system.err); 23 } 24 } 25 } The oly differece betwee Listig 4-2 ad Listig 4-1 occurs i lie 16. O lie 16, a differet parse method is ivoked that allows a DTD file to be specified (mydtd.dtd), so that it is refereced i the resultig XML documet. Thus, the resultig XML has a DOCTYPE statemet that refers to the DTD mydtd.dtd (see the followig example). <?xml versio= 1.0?> <!DOCTYPE somerootnode SYSTEM mydtd.dtd > A similar parse method allows the resultig XML to refer to a XML Schema. BEA WebLogic XML/No-XML Traslator User Guide 6-3

112 6 Usig the Ru-Time Compoet Passig i a Debug Writer All of the parse() methods of XML Traslator allow a PritWriter to be passed i as the last parameter of the parse() method. If this parameter is ot ull, XML Traslator will prit debug messages to this PritWriter. This allows you to debug the traslatio if the MFL documet ad the biary data do ot agree. If debug messages are ot desired, pass i ull for this parameter as show i the previous listigs. Listig 6-3 Passig i a Debug Writer Sample 1 import com.bea.wlxt.*; 2 import org.w3c.dom.documet 3 import java.io.fileiputstream; 4 import java.io.pritwriter; 5 import java.et.url; 6 7 public class Example3 8 { 9 public static void mai(strig[] args) 10 { 11 try 12 { 13 WLXT wlxt = ew WLXT(); 14 URL mfldocumetname = ew URL( file:mymfl.mfl ); 15 FileIputStream i = ew FileIputStream 16 ( mybiaryfile ); 17 Documet doc=wlxt.parse(mfldocumetname,i,ew PritWriter(System.out,true)); 18 Strig xml = wlxt.getxmltext(doc, 0, 2); 19 System.out.pritl(xml); 20 } 21 catch (Exceptio e) 22 { 23 e.pritstacktrace(system.err); 24 } 25 } 26 } 6-4 BEA WebLogic XML/No-XML Traslator User Guide

113 XML to Biary At lie 17, as a last parameter to the parse() method, a PritWriter object is created from the System.out PritStream. This will cause debug messages such as the oes show below to be writte to the cosole. Listig 6-4 Debug Output Parsig FieldFormat NAME at offset 0 Field NAME Foud delimiter [;] Field NAME type Strig offset 0 value=[joh Doe] Doe FieldFormat NAME Group PAYINFO repeat util delim=[*] Parsig 1st istace of StructFormat PAYINFO at offset 18 Parsig FieldFormat PAYDATE at offset XML to Biary The followig code listig illustrates usig XML Traslator to covert XML text to biary format. Listig 6-5 Sample XML to Biary Coversio 1 import com.bea.wlxt.*; 2 import java.io.fileiputstream; 3 import java.io.fileoutputstream; 4 import java.et.url; 5 6 public class Example4 7 { 8 public static void mai(strig[] args) 9 { 10 try 11 { 12 WLXT wlxt = ew WLXT(); 13 URL mfldocumetname = ew URL( file:mymfl.mfl ); BEA WebLogic XML/No-XML Traslator User Guide 6-5

114 6 Usig the Ru-Time Compoet 14 FileIputStream i = ew FileIputStream( myxml.xml ); 15 FileOutputStream out = ew FileOutputStream( mybiaryfile ); wlxt.serialize(mfldocumetname, i, out, ull); 18 out.close(); 19 } 20 catch (Exceptio e) 21 { 22 e.pritstacktrace(system.err); 23 } 24 } 25 } I the code example above, a ew istace of XML Traslator class is created at lie 12. The a URL is created for a MFL file, ad a FileIputStream is created for a file cotaiig XML text. A FileOutputStream is also istatiated to store the biary data that will result from the XML to biary traslatio. O lie 17, the serialize() method of XML Traslator is ivoked, to traslate the XML data cotaied i the FileIputStream i (myxml.xml), to the biary format described i mymfl.mfl. This biary data is writte to the FileOutputStream out (which is the file mybiaryfile ). Covertig a Documet object to Biary The listig below illustrates covertig a W3C Documet object to a biary format. Listig 6-6 Covertig a Documet Object to Biary 1 import com.bea.wlxt.*; 2 import java.io.fileoutputstream; 3 import java.et.url; 4 5 import org.w3c.dom.documet; 6 7 import org.apache.xerces.parsers.domparser; 8 9 public class Example5 10 { 11 public static void mai(strig[] args) 6-6 BEA WebLogic XML/No-XML Traslator User Guide

115 XML to Biary 12 { 13 // Parse XML ito a Documet object 14 Documet doc = ull; 15 try 16 { 17 DOMParser parser = ew DOMParser(); 18 parser.parse("myxml.xml"); 19 doc = parser.getdocumet(); 20 } 21 catch (Exceptio e) 22 { 23 e.pritstacktrace(system.err); 24 System.exit(1); 25 } try 28 { 29 WLXT wlxt = ew WLXT(); 30 URL mfldocumetname = ew URL("file:mymfl.mfl"); 31 FileOutputStream out = ew FileOutputStream("mybiaryfile"); wlxt.serialize(mfldocumetname, doc, out, ull); 34 out.close(); 35 } 36 catch (Exceptio e) 37 { 38 e.pritstacktrace(system.err); 39 } 40 } 41 } This example illustrates passig i a Documet object to the serialize() method of the XML Traslator class. This is useful whe your applicatio already has XML i the form of a Documet object, or has created a Documet object usig the DOM API. Lies 14 through 25 covert the XML text i the file myxml.xml to a Documet object usig a XML parser. This Documet object is passed to XML Traslator o lie 33, to covert it to the biary format specified by the MFL file mymfl.mfl. BEA WebLogic XML/No-XML Traslator User Guide 6-7

116 6 Usig the Ru-Time Compoet Passig i a debug writer Debug Output The serialize methods also support passig i a PritWriter parameter for the loggig of debug messages. A example ivocatio of the serialize method with a PritWriter object is give below. wlxt.serialize(mfldocumetname, i, out, ew PritWriter(System.out, true)); This will cause debug messages such as the oes show below to be writte to the cosole. The followig code represets debug output. Listig 6-7 Debug Output Processig xml ad mfl odes tcp1 Processig xml ode NAME Checkig MFL ode NAME Foud matchig MFL ode NAME Writig field NAME value Joh Doe Processig xml ode PAYINFO Checkig MFL ode PAYINFO XML to XML Trasformatio XML Traslator also provides methods to trasform XML via XSLT. XSLT is a laguage for trasformig XML documets. A XSLT stylesheet is a XML documet that describes trasformatios that are to be performed o the odes of a XML documet. The XML Traslator class provides trasform() methods that apply a XSLT stylesheet to a XML documet. Usig a stylesheet, a XML documet ca be trasformed ito HTML, PDF, or aother XML dialect. 6-8 BEA WebLogic XML/No-XML Traslator User Guide

117 XML to XML Trasformatio The listig below illustrates trasformig a XML documet usig oe of the trasform methods provided by the XML Traslator class. Listig 6-8 XML to XML Trasformatio 1 import com.bea.wlxt.*; 2 import java.io.fileiputstream; 3 import java.io.fileoutputstream; 4 import java.et.url; 5 6 import org.xml.sax.iputsource; 7 8 public class Example7 9 { 10 public static void mai(strig[] args) 11 { try 14 { 15 WLXT wlxt = ew WLXT(); 16 URL stylesheet = ew URL("file:mystylesheet.xsl"); 17 FileIputStream i = ew FileIputStream("myxml.xml"); 18 FileOuputStream out = ew FileOutputStream 19 ( myoutputfile ) wlxt.trasform(ew IputSource(i), out, stylesheet); out.close(); 24 } 25 catch (Exceptio e) 26 { 27 e.pritstacktrace(system.err); 28 } 29 } 30 } O lie 15, a istace of XML Traslator is created. O the followig lie a URL is created for a previously created XSLT stylesheet. A FileIputStream is the created for a file cotaiig XML text. A FileOutputStream is also created for the text that results from the XSLT trasformatio. O lie 21, a trasform() method of the XML Traslator class is ivoked to trasform the XML i the file myxml.xml, accordig to the XSLT stylesheet mystylesheet.xsl. The output of the trasformatio is writte to the file myoutputfile. BEA WebLogic XML/No-XML Traslator User Guide 6-9

118 6 Usig the Ru-Time Compoet Iitializatio methods iit() method The XML Traslator class provides several methods to preprocess MFL documets ad XSLT stylesheets. Oce these documets are preprocessed, they are cached iterally, ad reused whe refereced i a parse(), serialize(), or trasform() method. This greatly improves the performace of these methods, sice the MFL documet or XSLT stylesheet has already bee processed ad cached. This is particularly useful whe XML Traslator is used i a EJB or servlet, where the same MFL documets or XSLT stylesheets are used repeatedly. The XML Traslator class provides two iit() methods that take either a java.util.properties object or the file ame of a Properties file as a parameter. This iit() method will retrieve the WLXT.stylesheets ad WLXT.MFLDocumets properties from the Properties object. Each property is expected to cotai a comma-delimited list of documets that are to be preprocessed ad cached. Whe these documets are later refereced i a parse(), serialize(), or trasform() method, the preprocessed versio will be retrieved from the cache. The listig below demostrates usig a iit() method to iitialize a istace of the XML Traslator class. Listig 6-9 Properties file mycofig.cfg: WLXT.MFLDocumets=file:mymfl.mfl WLXT.stylesheets=file:mystylesheet.xsl Listig 6-10 Source code example of iit() method usig file mycofig.cfg 1 import com.bea.wlxt.*; 2 import java.io.fileiputstream; 3 import java.io.fileoutputstream; 4 import java.et.url; 5 6 import org.xml.sax.iputsource; 7 import org.w3c.dom.documet; 8 9 public class Example BEA WebLogic XML/No-XML Traslator User Guide

119 XML to XML Trasformatio 10 { 11 public static void mai(strig[] args) 12 { WLXT wlxt = ull; // Iitialize WLXT with a properties file 17 try 18 { 19 wlxt = ew WLXT(); 20 wlxt.iit("mycofig.cfg"); 21 } 22 catch (Exceptio e) 23 { 24 e.pritstacktrace(system.err); 25 } // Parse biary data ito XML 28 Documet doc = ull; 29 try 30 { 31 URL mfldocumetname = ew URL("file:mymfl.mfl"); 32 FileIputStream i = ew FileIputStream("mybiaryfile"); doc = wlxt.parse(mfldocumetname, i, ull); 35 } 36 catch (Exceptio e) 37 { 38 e.pritstacktrace(system.err); 39 } try 42 { 43 URL stylesheet = ew URL("file:mystylesheet.xsl"); 44 FileOutputStream out = ew FileOutputStream 45 ( myoutputfile ) wlxt.trasform(doc, out, stylesheet); out.close(); 50 } 51 catch (Exceptio e) 52 { 53 e.pritstacktrace(system.err); 54 } 55 } 56 } BEA WebLogic XML/No-XML Traslator User Guide 6-11

120 6 Usig the Ru-Time Compoet The iit() method o lie 20 of the listig above, causes the XML Traslator object to preprocess the documets listed i the file mycofig.cfg. Whe a MFL documet is specified i the parse() method of lie 34, this MFL documet has already bee processed a cached iside the XML Traslator object. The same is true of the stylesheet that is refereced i the ivocatio of the trasform() method o lie 46. Java API Documetatio For the complete referece to usig the XML Traslator class, see the Java API Documetatio located i the apidoc subdirectory of your XML Traslator istallatio. Ru-Time Plug-I to WebLogic Process Itegrator BEA XML Traslator Plug-I for WebLogic Process Itegrator provides for a exchage of iformatio betwee applicatios by supportig data traslatios betwee biary formats from legacy systems ad XML. The XML Traslator Plug-I provides Process Itegrator actios that allow you to access XML to Biary ad Biary to XML traslatios. I additio to this data traslatio capability, the XML Traslator Plug-I provides evet data processig i biary format, i-memory cachig of MFL documets ad traslatio object poolig to boost performace, a BiaryData variable type to edit ad display biary data, exportig of etirely self-cotaied workflow defiitio packages, ad executio withi a WebLogic Server clustered eviromet. The followig illustratio describes the relatioship betwee XML Traslator ad Process Itegrator BEA WebLogic XML/No-XML Traslator User Guide

121 XML to XML Trasformatio Figure 6-1 Ru-Time Plug-I to Process Itegrator Start Workflow Task Cofigured with XML Traslator Actios Doe Iput Biary Data MFL Documet Name Traslated XML Documet BEA XML Traslator Plug-I to Process Itegrator BEA XML Traslator Java Classes MFL Documet XML Documet Repository MFL Documet Optioal: DTD XML Schema Format Builder For more iformatio about the XML Traslator ru-time plug-i for WebLogic Process Itegrator, refer to the BEA WebLogic XML/No-XML Traslator Plug-I Guide. BEA WebLogic XML/No-XML Traslator User Guide 6-13

122 6 Usig the Ru-Time Compoet 6-14 BEA WebLogic XML/No-XML Traslator User Guide

123 APPENDIX A Supported Data Types This sectio lists the followig data types supported by XML Traslator. MFL Data Types COBOL Copybook Importer Data Types C Structure Importer From Importig Meta Data MFL Data Types Table A-1 lists the MFL data types that XML Traslator supports. These types are specified i the type attribute of a FieldFormat elemet. Table A-1 Supported MFL Data Types Data Type Biary (Base64 ecodig) Biary (Hex ecodig) DateTime: MM/DD/YY hh:mm Descriptio Ay character value accepted. Requires a legth, legth field, delimiter, or a delimiter field. Resultig XML data for this field is ecoded usig base-64. Ay character value accepted. Requires a legth, legth field, delimiter, or a delimiter field. Resultig XML data for this field is ecoded usig base-16. A strig defiig a date ad time, i.e. 01/22/00 12:24. BEA WebLogic XML/No-XML Traslator User Guide A-1

124 A Supported Data Types Data Type DateTime: MM/DD/YY hh:mi AM DateTime: MM/DD/YY hh:mm:ss DateTime: MM/DD/YY hh:mm:ss AM DateTime: DD/MM/YY hh:mm DateTime: DD/MM/YY hh:mm AM DateTime: DD/MM/YY hh:mm:ss DateTime: DD/MM/YY hh:mm:ss AM DateTime: MMDDYYhhmm DateTime: YYYYMMDDhhmmss DateTime: MMDDYYhhmmss Date: DDMMMYY Date: DDMMMYYYY Descriptio A strig defiig a date ad time, i.e. 01/22/00 12:24 AM. A strig defiig a date ad time, i.e. 01/22/00 12:24:00. A strig defiig a date ad time, i.e. 01/22/00 12:24:00 AM. A strig defiig a date ad time, i.e. 22/01/00 12:24. A strig defiig a date ad time, i.e. 22/01/00 12:24 AM. A strig defiig a date ad time, i.e. 22/01/00 12:24:00. A strig defiig a date ad time, i.e. 22/01/00 12:24:00 AM. A strig of umeric digits defiig a date ad time, i.e A fourtee byte umeric strig of the format YYYYMMDDHHMISS. A Base data type may be specified. A strig of umeric digits defiig a date ad time, i.e A strig defiig a date, i.e. 22JAN00. A strig defiig a date, i.e. 22JAN2000. Date: DD/MM/YY A strig defiig a date, i.e. 22/01/00. Date: DD/MM/YYYY A strig defiig a date, i.e. 22/01/2000. Date: DD-MMM-YY Date: DD-MMM-YYYY A strig defiig a date, i.e. 22-JAN-00. A strig defiig a date, i.e. 22-JAN Date: MMDDYY A six digit umeric strig defiig a date, i.e Date: MMDDYYYY A eight digit umeric strig defiig a date, i.e A-2 BEA WebLogic XML/No-XML Traslator User Guide

125 MFL Data Types Data Type Descriptio Date: MM/DD/YY A strig defiig a date, i.e. 01/22/00. Date: MM/DD/YYYY A strig defiig a date, i.e. 01/22/2000. Date: MMM-YY Date: MMM-YYYY Date: MMMYY Date: MMMYYYY Date: MMMDDYYYY Date: YYYYMMDD Date: Wed Nov 15 10:55:37 CST 2000 EBCDIC Filler FloatigPoit: 4 bytes, Big-Edia FloatigPoit, 4 bytes, Little-Edia FloatigPoit: 8 bytes, Big-Edia FloatigPoit: 8 bytes, Little-Edia A strig defiig a date, i.e. JAN-00. A strig defiig a date, i.e. JAN A strig defiig a date, i.e. JAN00. A strig defiig a date, i.e. JAN2000. A strig defiig a date, i.e. JAN A eight byte umeric strig of the format YYYYMMDD. A base data of Strig or EBCDIC may be specified to idicate the character ecodig. The default date format of the Java platform, i.e. WED NOV 15 10:55:37 CST 2000 A strig of characters i IBM Exteded Biary Coded Decimal Iterchage Code. Requires a legth, legth field, delimiter, or a delimiter field. A sequece of bytes that is ot traslated to XML. This field of data is skipped over whe traslatig biary data to XML. Whe traslatig XML to biary data, this field is writte to the biary output stream as a sequece of spaces. A four byte big edia floatig poit umber that coforms to the IEEE Stadard 754. A four byte little edia floatig poit umber that coforms to the IEEE Stadard 754. A eight byte big edia floatig poit umber that coforms to the IEEE Stadard 754. A eight byte little edia floatig poit umber that coforms to the IEEE Stadard 754. BEA WebLogic XML/No-XML Traslator User Guide A-3

126 A Supported Data Types Data Type Floatig Poit IBM 4 byte IBM 8 byte Descriptio IBM Maiframe floatig poit. Iteger: Siged, 1 byte A oe byte siged iteger, i.e. 56 is 0x38. Iteger: Usiged, 1 byte A oe byte usiged iteger, i.e. 128 is 0x80. Iteger: Siged, 2 byte, Big-Edia Iteger: Siged, 4 byte, Big-Edia Iteger: Siged, 8 bytes, Big-Edia Iteger: Usiged, 2 byte, Big-Edia Iteger: Usiged, 4 byte, Big-Edia Iteger: Usiged, 8 bytes, Big-Edia Iteger: Siged, 2 bytes, Little-Edia Iteger: Siged, 4 bytes, Little-Edia Iteger: Siged, 8 bytes, Little-Edia Iteger: Usiged, 2 bytes, Little-Edia Iteger: Usiged, 4 bytes, Little-Edia Iteger: Usiged, 8 bytes, Little-Edia A siged two-byte iteger i big edia format, i.e is 0x1234. A siged four-byte iteger i big edia format, i.e is 0x A siged eight-byte iteger i big edia format, i.e is 0x A usiged two-byte iteger i big edia format, i.e is 0xFDE8. A usiged four-byte iteger i big edia format, i.e is 0x0000FDE8. A usiged eight-byte iteger i big edia format, i.e is 0x FDE8. A siged two-byte iteger i little edia format, i.e is 0x3412. A siged four-byte iteger i little edia format, i.e is 0x A siged eight-byte iteger i little edia format, i.e is 0x A usiged two-byte iteger i little edia format, i.e is 0xE8FD. A usiged four-byte iteger i little edia format, i.e is 0xE8FD0000. A usiged eight-byte iteger i little edia format, i.e is 0xE8FD A-4 BEA WebLogic XML/No-XML Traslator User Guide

127 MFL Data Types Data Type Literal Descriptio A literal value determied by the cotets of the value attribute. Whe biary data is traslated to XML, the presece of the specified literal i the biary data is verified by WLXT. The literal is read, but is ot traslated to the XML data. Whe XML data is traslated to a biary format, ad a literal is defied as part of the biary format, WLXT writes the literal i the resultig biary byte stream. Numeric A strig of characters cotaiig oly digits, i.e. 0 through 9. Requires a legth, legth field, delimiter, or a delimiter field. Packed Decimal: Siged Packed Decimal: Usiged Strig Strig: NUL termiated IBM siged packed format. Requires a legth, legth field, delimiter, or a delimiter field to be specified. The legth or legth field should specify the size of this field i bytes. IBM usiged packed format. Requires a legth, legth field, delimiter, or a delimiter field to be specified. The legth or legth field should specify the size of this field i bytes. A strig of characters. Requires a legth, a legth field, a delimiter, or a delimiter field. If o legth, legth field, or delimiter is defied for a data type Strig, a delimiter of "\x00" (a NUL character) will be assumed. A strig of characters, optioally NUL (\x00) termiated, residig withi a fixed legth field. This field type requires a legth attribute or legth field which determies the amout of data read for the field. This data is the examied for a NUL delimiter. If a delimiter is foud, data followig the delimiter is discarded. If a NUL delimiter does ot exist, the fixed legth data is used as the value of the field. Time: hhmmss A strig defiig a time, i.e Time: hh:mm AM A strig defiig a time, i.e. 12:24 AM. Time: hh:mm A strig defiig a time, i.e. 12:24. Time: hh:mm:ss AM A strig defiig a time, i.e. 12:24:00 AM. Time: hh:mm:ss A strig defiig a time, i.e. 12:24:00. BEA WebLogic XML/No-XML Traslator User Guide A-5

128 A Supported Data Types Data Type Zoed Decimal: Leadig sig Zoed Decimal: Leadig separate sig Zoed Decimal: Siged Zoed Decimal: Trailig separate sig Zoed Decimal: Usiged Descriptio IBM siged zoed decimal format where the sig idicator is i the first ibble. Requires a legth, legth field, delimiter, or a delimiter field to be specified. The legth or legth field should specify the size of this field i bytes. IBM siged zoed decimal format where the sig idicator is i the first byte. The first byte oly cotais the sig idicator ad is separated from the umeric value. Requires a legth, legth field, delimiter, or a delimiter field to be specified. The legth or legth field should specify the size of this field i bytes. IBM siged zoed decimal format. Requires a legth, legth field, delimiter, or a delimiter field to be specified. The legth or legth field should specify the size of this field i bytes. IBM siged zoed decimal format where the sig idicator is i the last byte. The last byte oly cotais the sig idicator ad is separated from the umeric value. Requires a legth, legth field, delimiter, or a delimiter field to be specified. The legth or legth field should specify the size of this field i bytes. IBM usiged zoed decimal format. Requires a legth, legth field, delimiter, or a delimiter field to be specified. The legth or legth field should specify the size of this field i bytes. A-6 BEA WebLogic XML/No-XML Traslator User Guide

129 COBOL Copybook Importer Data Types COBOL Copybook Importer Data Types Table 4-1 lists the COBOL data types ad the support provided by the Importer. Table 6-1 COBOL Data Types COBOL Type BLANK WHEN ZERO (zoed) COMP-1, COMP-2 (float) COMP-3, PACKED-DECIMAL COMP, COMP-4, BINARY (iteger) COMP, COMP-4, BINARY (fixed) COMP-5, COMP-X DISPLAY (alphaumeric) DISPLAY umeric (zoed) edited alphaumeric edited float umeric edited umeric group record INDEX JUSTIFIED RIGHT OCCURS (fixed array) OCCURS DEPENDING (variable-legth) OCCURS INDEXED BY OCCURS KEY IS Support supported supported supported supported supported supported supported supported supported supported supported supported supported igored supported supported igored igored BEA WebLogic XML/No-XML Traslator User Guide A-7

130 A Supported Data Types COBOL Type POINTER PROCEDURE-POINTER REDEFINES SIGN IS LEADING SEPARATE (zoed) SIGN IS TRAILING (zoed) SIGN IS TRAILING SEPARATE (zoed) SIGN IS LEADING (zoed) SYNCHRONIZED Support supported supported supported supported supported supported supported igored 66 RENAMES igored 66 RENAMES THRU igored 77 level supported 88 level (coditio) igored Support for these data types is limited. The followig formats: 05 pic 9(5) comp-5 05 pic 9(5) comp-x will be coverted to a usiged 4 byte iteger type, while the followig will geerate errors: 05 pic X(5) comp-5 05 pic X(5) comp-x I these samples, pic9(5) could be substituted for pic x(5). The followig values are defied as follows: Supported - the data type will be correctly parsed by the importer ad coverted to a message format field or group. Usupported - this data type is ot supported ad the importer reports a error whe the copybook is imported. A-8 BEA WebLogic XML/No-XML Traslator User Guide

131 C Structure Importer From Importig Meta Data Igored - the data type is parsed ad a commet is added to the message format. No correspodig field or group is created. Some vedor-specific extesios are ot recogized by the importer, however, ay copybook statemet that coforms to ANSI stadard COBOL will be parsed correctly by the Importer. The Importer s default data model, which is based o the IBM maiframe model, ca be chaged i Format Builder to compesate for character set ad data ediaess. Whe importig copybooks, the importer may idetify fields geerically that, upo visual ispectio, could easily be idetified by a more specific data type. For this reaso, the copybook importer creates commets for each field foud i the copybook. This iformatio is useful i assistig you i editig the MFL data to better represet the origial Copybook. For example: origial copybook etry: 05 birth-date picxx/xx/xx results i: A field of type EBCDIC with a legth of 8 Closer ispectio idicates that this is iteded to be a date format ad could be defied as A field of type Date: MM/DD/YY or A field of type Data: DD/MM/YY C Structure Importer From Importig Meta Data The C Struct importer does ot parse files cotaiig aoymous uios, bit fields, or i-lie assembler code. The followig samples of usupported structures came from the pre-processor output of a hello.c file that cotaied a #iclude <widows.h>. Aoymous Uios BEA WebLogic XML/No-XML Traslator User Guide A-9

132 A Supported Data Types #lie 353 e:\\program files\\microsoft visual studio\\vc98\\iclude\\wit.h typedef uio_large_integer{ struct { DWORD LowPart; LONG HighPart; }; struct { DWORD LowPart; LONG HighPart; } u; #lie 363 e:\\program files\\microsoft visual studio\\vc98\\iclude\\wit.h LONGLONG QuadPart; } LARGE_INTEGER Bit Fields typedef struct_ldt_entry { WORD LimitLow; WORD BaseLow; uio { struct { BYTE BaseMid; BYTE Flags1; BYTE Flags2; BYTE BaseHi; } Bytes; struct DWORD BaseMid : 8; DWORD Type : 5; DWORD Dpl : 2; DWORD Pres : 1; DWORD LimitHi : 4; DWORD Sys : 1; DWORD Reserved_0 : 1; DWORD Default_Big : 1; DWORD Graularity : 1; DWORD BaseHi : 8; } Bits; } HighWord; } LDT_ENTRY, *PLDT_ENTRY; I-Lie Assembler Code _ilie ULONGLONG _stdcall It64ShrlMod32( ULONGLONG Value, DWORD ShiftCout A-10 BEA WebLogic XML/No-XML Traslator User Guide

133 C Structure Importer From Importig Meta Data { } ) _asm { mov ecx, ShiftCout mov eax, dword ptr [Value] mov edx, dword ptr [Value+4] shrd eax, edx, cl shr edx, cl } BEA WebLogic XML/No-XML Traslator User Guide A-11

134 A Supported Data Types A-12 BEA WebLogic XML/No-XML Traslator User Guide

135 APPENDIX B Creatig Custom Data Types XML Traslator uses a metadata laguage called Message Format Laguage (MFL), based o XML, to describe biary data structure. Format Builder creates ad maitais this metadata as a data file, or a MFL documet i the Process Itegrator repository. MFL uses the followig metadata iformatio to describe a biary field: Data type Legth/Delimiter Optioal/Madatory Default value Code Page ecodig Of this iformatio, the data type is the most critical. The selected data type dictates which metadata attributes are valid ad how they are iterpreted. XML Traslator icludes a User Defied Type feature that allows you to create custom data types specific to your uique data type requiremets. The User Defied Type feature allows these custom data types to be plugged i to the XML Traslator rutime egie. Oce a user defied data type is plugged-i, it is idistiguishable from a built-i data type i both features ad fuctio. BEA WebLogic XML/No-XML Traslator User Guide B-1

136 B Creatig Custom Data Types Istructios o how to use the XML Traslator User Defied Type feature are cotaied i the followig topics: User Defied Types Sample Files Registerig User Defied Types i Format Builder Creatig User Defied Types for the Stad-Aloe XML Traslator Egie Cofiguratio of User Defied Types for the Process Itegrator XML Traslator Plug-I User Defied Type Codig Requiremets Class com.bea.wlxt.mfl.mflfield User Defied Types Sample Files The followig table provides a listig ad descriptio of the sample files istalled for use with user defied types. All directory ames are relative to the XML Traslator istallatio directory. Table 6-2 User Defied Types Sample Files Directory File Descriptio samples/userdef CapStrig.java Source for a user data type that coverts strigs to upper case. samples/userdef Dddmmyy.java Source for a user defied type that supports a Europea date format. samples/userdef Makefile Make file for buildig the sample source. samples/userdef ParseUserDef.java Source that shows istallig the sample user defied type ad usig them with the rutime egie. samples/userdef readme.txt Explais how to compile ad ru the sample. B-2 BEA WebLogic XML/No-XML Traslator User Guide

137 Registerig User Defied Types i Format Builder samples/userdef sample.data Data for the ParseUserData sample. samples/userdef sample.mfl The Message Format Laguage (MFL) file for the ParseUserData sample. Registerig User Defied Types i Format Builder Perform the followig steps to register a ew user defied type: 1. Start Format Builder by clickig Start Programs BEA WebLogic E-Busiess Platform WebLogic Itegratio 2.0 xmltraslator Format Builder. The Format Builder mai widow displays. 2. Choose Tools User Defied Types. The Add/Remove User Defied Types dialog box displays. Figure 6-2 Add/Remove User Defied Types Dialog Box 3. Eter the class ame implemetig the type i the Class Name field. BEA WebLogic XML/No-XML Traslator User Guide B-3