Flat File

Title PageDeveloper Version 7.1 Flat File Schema Developer’s Guide Copyright &  Docu‐ ment ID Cerebra, Glue, Infravio X‐Broker, Infravio X‐Registry, Infravio, My webMethods Server, My webMethods, webMethods Access, webMethods Administrator,  webMethods Broker, webMethods Central Configuration, webMethods Dashboard, webMethods Designer, webMethods Developer, webMethods Fabric,  webMethods Glue, webMethods Infrastructure Data Collector, webMethods Infravio X‐Broker, webMethods Infravio X‐Registry, webMethods Installer,  webMethods Integration Server, webMethods logo, webMethods Mainframe, webMethods Manager, webMethods Modeler, webMethods Monitor,  webMethods Optimize for Infrastructure, webMethods Optimize for Process, webMethods Optimize, webMethods Portal, webMethods Process Engine,  webMethods Servicenet, webMethods Task Engine, webMethods Trading Networks, webMethods Workflow, and webMethods are either registered  trademarks or trademarks of webMethods, Inc. Acrobat, Acrobat, and Reader are registered trademarks of Adobe Systems Incorporated.  Amdocs and ClarifyCRM are registered trademarks of Amdocs.   Ariba is a registered trademark of Ariba, Inc.  BEA, BEA WebLogic Server, Jolt, and Tuxedo are registered trademarks, and BEA WebLogic Platform is a  trademark of BEA Systems, Inc.  Action Request System, BMC Software, PATROL, and Remedy are registered trademarks of BMC Software, Inc.  BroadVision  is a registered trademark of BroadVision, Inc.  Chem eStandards and CIDX are trademarks of CIDX, The Chemical Industry Data Exchange.  SiteMinder and  Unicenter are registered trademarks of CA, Inc.  PopChart is a registered trademark of CORDA Technologies, Inc.  Kenan and Arbor are registered trademarks  of Alcatel‐Lucent.  Data Connection and SNAP‐IX are registered trademarks of Data Connection Corporation.  D&B and D‐U‐N‐S are registered trademarks of  Dun & Bradstreet Corporation.  Eclipse is a trademark of Eclipse Foundation, Inc.  Entrust is a registered trademark of Entrust, Inc.  papiNet is a registered  trademark of the European Union and the United States.  Financial Information eXchange, F.I.X, and F.I.X Protocol are trademarks of FIX Protocol Ltd.   UCCnet and eBusinessReady are registered trademarks, and 1SYNC and Transora are trademarks of GS1 US.  Hewlett‐Packard, HP, HP‐UX, OpenView, PA‐ RISC, and SNAplus2 are trademarks of Hewlett‐Packard Company.  i2 is a registered trademark of i2 Technologies, Inc.  AIX, AS/400, CICS, ClearCase, DB2,  Domino, IBM, Informix, Infoprint, Lotus, Lotus Notes, MQSeries, OS/390, OS/400, RACF, RS/6000, SQL/400, S/390, System/390, VTAM, and WebSphere, and  z/OS are registered trademarks; and Communications System for Windows NT, DB2 Universal Database, IMS, MVS, and SQL/DS are trademarks of IBM  Corporation.   InnoDB is a trademark of Innobase Oy.  Itanium is a registered trademark of Intel Corporation.  Linux is a registered trademark of Linus  Torvalds.  W3C is a registered trademark, and X Window System is a trademark of the Massachusetts Institute of Technology.  MetaSolv is a registered  trademark of Metasolv Software, Inc.  ActiveX, Microsoft, Outlook, Visual Basic, Visual SourceSafe, Windows, Windows NT, and Windows Server are  registered trademarks of Microsoft Corporation.   Six Sigma is a registered trademark of Motorola, Inc.  Firefox and Mozilla are registered trademarks of the  Mozilla Foundation.  MySQL is a registered trademark of MySQL AB.  nCipher is a trademark of nCipher Corporation Ltd.   Eclipse is a trademark of Eclipse  Foundation, Inc.  Entrust is a registered trademark of Entrust, Inc.  papiNet is a registered trademark of the European Union and the United States.  Financial  Information eXchange, F.I.X, and F.I.X Protocol are trademarks of FIX Protocol Ltd.  UCCnet and eBusinessReady are registered trademarks, and 1SYNC and  Transora are trademarks of GS1 US.  Hewlett‐Packard, HP, HP‐UX, OpenView, PA‐RISC, and SNAplus2 are trademarks of Hewlett‐Packard Company.  i2 is a  registered trademark of i2 Technologies, Inc.  AIX, AS/400, CICS, ClearCase, DB2, Domino, IBM, Informix, Infoprint, Lotus, Lotus Notes, MQSeries, OS/390,  OS/400, RACF, RS/6000, SQL/400, S/390, System/390, VTAM, and WebSphere, and z/OS are registered trademarks; and Communications System for Windows  NT, DB2 Universal Database, IMS, MVS, and SQL/DS are trademarks of IBM Corporation.  InnoDB is a trademark of Innobase Oy.  Itanium is a registered  trademark of Intel Corporation.   Teradata is a registered trademark of NCR Corporation. Netscape is a registered trademark of Netscape Communications  Corporation.  ServletExec is a registered trademark, and New Atlanta is a trademark of New Atlanta Communications, LLC.  SUSE is a registered trademark  of Novell, Inc.  Appia is a registered trademark and Javelin Technologies is a trademark of NYFIX, Inc.  CORBA is a registered trademark of Object  Management Group, Inc.  JD Edwards, OneWorld, Oracle, PeopleSoft, Siebel, and Vantive are registered trademarks; and Infranet, PeopleSoft Pure Internet  Architecture, Portal, and WorldSoftware are trademarks of Oracle Corporation.  Perforce is a trademark of Perforce Software.  JBoss and Red Hat are  registered trademarks of Red Hat, Inc.  PIP and RosettaNet are trademarks of RosettaNet, a non‐profit organization.   SAP and R/3 are registered trademarks  of SAP AG.  PVCS is a registered trademark of Serena Software, Inc.  SWIFT and SWIFTNet are registered trademarks of Society for Worldwide Interbank  Financial Telecommunication SCRL.  SPARC and SPARCStation are registered trademarks of SPARC International, Inc.  BAAN and SSA are registered  trademarks; and SSA Global is a trademark of SSA Global Technologies, Inc.  EJB, Enterprise JavaBeans, Java, JavaServer, JDBC, JSP, J2EE, Solaris, Sun, and  Sun Microsystems are registered trademarks; and Java Naming and Directory Interface, JavaServer Pages, SOAP with Attachments API for Java, and SunSoft  are trademarks of Sun Microsystems, Inc.  Sybase is a registered trademark of Sybase, Inc.  VERITAS is a registered trademark, and VERITAS Cluster Server is  a trademark of Symantec Corporation.  UNIX is a registered trademark of The Open Group.  Unicode is a trademark of Unicode, Inc.  VeriSign is a registered  trademark of Verisign, Inc.  Software AG and all Software AG product names are either trademarks or registered trademarks of Software AG.  Other product and company names mentioned herein may be the trademarks of their respective owners. Copyright © 2007 webMethods, Inc. All rights reserved. Copyright © 2007 Software AG and/or its suppliers, Uhlandstrasse 12, 64297 Darmstadt, Germany. All rights reserved. Document ID: DEV-FFS-DG-71-20070831 Contents Contents About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 7 8 Chapter 1. Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Flat File? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Types of Flat Files Does webMethods Support? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Flat File Schema? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Type of Flat File Constraints Can You Define? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Is a Flat File Schema Used to Parse Records? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Record Parsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Record Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Extractors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Undefined Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a Flat File Dictionary? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . When Should I Create a Flat File Dictionary? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is the Flat File Schema Editor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flat File Structure Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 10 10 11 12 12 14 14 15 16 16 18 18 19 19 21 Chapter 2. Processing Flat Files Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Formatting Inbound and Outbound Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processing Inbound Flat Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 1: Create Appropriate Flat File Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 2: Receive the Flat File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 3: Parse, Convert, and Validate Flat File Data to an IS Document . . . . . . . . . . . . . . . . . . . Step 4: Process the IS Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping Flat File Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handling Large Flat Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processing Outbound Flat Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 1: Create Appropriate Flat File Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 2: Convert the IS Document to a Flat File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 3: Send/Process the Flat File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 24 25 25 26 26 27 27 27 30 31 31 31 32 33 Flat File Schema Developer’s Guide Version 7.1 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 2: Specify Flat File Properties . . . . . . . . . . . . . . . Step 1: Add and Configure the Flat File Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building a Client that Posts a Flat File to a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Flat File Schema . . . . . . . . . . . . . . . . . . . Extractors . . . . Byte Count Validator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Flat File Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Length Validator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing a Flat File Schema or Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Format Services . . . Floating Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying Element Descriptions and Alternate Names in the Flow Editor . . . . . . . . . . . . . . . . . . . . Step 4: Test the Flat File Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 36 36 41 43 44 47 48 57 61 62 62 64 64 64 65 66 66 66 66 67 67 68 69 72 72 73 74 Chapter 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Code List Validator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FTPing a File From a webMethods Integration Server . . . . . . . . . . . . . . . . . . Setting Access Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting a Flat File to Integration Server via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing Flat File Dictionary Dependencies . .Contents Chapter 3. . . . . . . . . . . . . . . . Working with Format Error Messages . . . . . . . . . . . . . . . . . . . . . . Getting Results from an FTP’d Document . . . . . . . . . . . . . . . . . . . . . . . . . Conditional Validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flat File Content Handler and Content Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting a Flat File to Integration Server via FTP . . . . . . . . . . . . . . . . . . . . . Sending and Receiving Flat Files . . . . . . . . . . . Choosing the Service to Receive the Flat File from the Content Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Field Validators . . . . . . . . . . . Submitting a Flat File to Integration Server in a String Variable . . . . . Creating and Editing Flat File Schemas and Dictionaries . . . . . . . . . . . . . . . . . . Flat File Schema Property Descriptions . . . . . . . . . . . Step 3: Define the Structure of the Flat File Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disabling Format Services . . . . . . . . . . . . . . . . . . . . . . . . .1 4 . . . . Managing Dictionary Dependencies on Format Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples: Parsing Inbound Floating Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples: Parsing Outbound Floating Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing the Flat File Configuration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 78 78 79 79 80 80 81 82 83 Flat File Schema Developer’s Guide Version 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pub. . . . . . . . . . . . . . . . . . . . . . . . . . . pub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flat File Generation IS Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pub. . .generate:saveXMLASFFSchema . . . . .generate:deleteFFSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .flatFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .flatFile. . . . .generate:getFFSchemaAsXML . . . . . . . . . . . General Error Entries in the errors Array . . . . . . . . . . . . . . . . . . . . . . . . . . .flatFile. . . . . . . . . . .flatFile. . . WmFlatFile Built–in Services Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .flatFile. . . . . . . . . . . . . . . . . . . . . . . pub. . . . . . . . . . pub. . . . . . . . . . . . . . . . . . . . . . . .flatFile:FormatService .flatFile. . . . . . . . . . . . . . . . . .generate:deleteFFDictionaryEntry .flatFile. . . . . . . . . . . . . . . . . . . . . . . . . . .flatFile. . . . . . . . . . . . . . . . . . . . . . . . . pub. . . . . . .generate:saveXMLAsFFDictionary . . . . pub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Error Codes . . . . . . . . . . . . . . . . . . . . .generate:listFFDictionaryEntries . . . . . . Flat File Generation Sample Services . . . . . . . . . . . Flat File Conversion Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flat File Generation Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .flatFile. . . . . .flatFile. .flatFile. . . . . . . . . . . . . 84 84 84 85 Chapter 5. pub. . . . . . . . . . . . . . . . . . . . . . pub. . . . . .generate:createDocumentType . . . . . . . . . . .flatFile. . . . . . . . . . . . . . . . . . . . . . . pub. .generate:updateFFDictionaryEntryFromXML .Contents Submitting a Flat File to Integration Server via File Polling . . . . . . . . . . . . . . . . . . . . .generate:FFSchema . . . . . . . . . . . . . . . . . . . . .flatFile. . . . . . . . . . . . . . . . . .generate:findDependants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .generate:findReferences . . . . . . . . . . . . . . . .flatFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .generateFFSchema:fixedLength . . . . . . . . . . . . . . . 115 Validation Error Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sample. . pub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .generate:getFFDictionaryAsXML . . . . . . . . . . . . . . . . . . . .flatFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Results from an Emailed Document . . .flatFile:getSupportedEncodings . . . Entries for Conditional Validator Errors in errorDetails Array . . . . . . . . . . . . . . Submitting a Flat File to Integration Server via an E–mail Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Requirements for Submitting a Flat File Document via an E-mail Message . . . . . . . . . . .flatFile. . . . . . . . . . . . .flatFile. . . . . . . . . . . . . . . . . . . . . .generate:FFDictionary . . . . . . . . .flatFile:convertToString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .flatFile. . . . . . pub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .generate:getFFDictionaryEntryAsXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pub. . . . . .1 5 . . .flatFile:convertToValues . . . . . . . . . . . . . . . . . . . 87 88 88 90 93 98 98 98 99 99 100 100 101 101 101 102 102 103 103 104 106 107 107 109 111 111 113 Appendix A. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sample. . . . . . . . . . . . . . . . . . . . . . . . . . Validation Errors . . . . . pub. . . . . . . . . . . . . . . .generateFFSchema:delimited . . . . 116 117 117 120 Flat File Schema Developer’s Guide Version 7. . . . pub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pub. . . . . . . . . . . . . . pub. . . . . . . . . .generate:createFFDictionary . . . . . . . . . . . . . pub. pub. . . . . . . . . . . . . . . .generate:deleteFFDictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Flat File Dictionary Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving Namespace Data to Write to an XML File . . . . .Contents Appendix B. . . . . . . . . . . . . . . . . . . . . . . . Modifying an Existing Flat File Dictionary Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 130 131 132 133 133 134 134 138 140 140 140 141 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Overview . . . . . . . . . . . . . . . . . and Schemas . . . . . . . . . . . 123 Overview . . . . . . . . . . . . . Creating a Flat File Schema . . . . . . . . . . . Writing Partial Character Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . and Schemas . . . . . . . . . . . . . . . . . . . . Dictionaries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dictionaries. . . . . . . . . . Modifying Flat File Dictionary Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flat File Byte Count Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying an Existing Flat File Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an Entire Flat File Dictionary with Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dictionaries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Programmatically Creating Flat File Schemas and Dictionaries . . . . 124 124 125 126 127 127 Appendix C. . . . . . . . . . . . . . . . . . Deleting Flat File Dictionary Entries. . . . . . . . .1 6 . . . . . . . . . . . . Stateful Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reading Partial Characters . . Sample Flow Services for Working with XML Files . 143 Flat File Schema Developer’s Guide Version 7. . . . . . . . Creating an Empty Flat File Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . and Schemas . . . . . . . . . . . . . Handling Partial Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Flat File Dictionary Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing Stateful Encodings . . . . . . . . . . . . . . . . . . Creating a Service that Retrieves the XML File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  This guide is for users who want  to use webMethods Developer to create flat file schemas and dictionaries to parse and  validate inbound flat files and produce outbound flat files. Identifies storage locations for services on the webMethods  Integration Server using the convention folder.About This Guide About This Guide The webMethods Integration Server provides the WmFlatFile package to enable you to  exchange and process flat files using its built–in services. Identifies characters and values that you must type exactly or  messages that the system displays on the console.1 7 . Identifies terms the  first time they are defined in text. Do not type the [ ]  symbols in your own code. Identifies variable information that you must supply or change  based on your specific situation or environment. Identifies keyboard keys. Directory paths use the “\” directory delimiter unless the subject is  UNIX‐specific. Document Conventions Convention Bold Italic Description Identifies elements on a screen. Keys that you must press simultaneously  are joined with the “+” symbol. you should be familiar the basic concepts described in the  webMethods Integration Server Administrator’s Guide and the webMethods Developer User’s  Guide. Optional keywords or values are enclosed in [ ]. To use this guide effectively.subfolder:service. Narrow font Typewriter font UPPERCASE \ [ ] Flat File Schema Developer’s Guide Version 7. Also identifies service input and  output variables.  you can find documentation for all webMethods products on the  webMethods Bookshelf.webmethods.” located by default under webMethods installation directory.About This Guide Additional Information The webMethods Advantage Web site at http://advantage. Starting with 7. Additional Documentation.0. To provide feedback on webMethods documentation. Flat File Schema Developer’s Guide Version 7. In  addition.  go to  the Documentation Feedback Form on the webMethods Bookshelf. The webMethods Knowledge Base provides  troubleshooting information for many webMethods products.1 8 .  Documentation Feedback.com provides you  with important sources of information about webMethods products: Troubleshooting Information. you have the option of downloading the  documentation during product installation to a single directory called  “_documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Concepts Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 What Type of Flat File Constraints Can You Define? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 How Is a Flat File Schema Used to Parse Records? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 What Is a Flat File Dictionary? . . 19 What Is the Flat File Schema Editor? . . . . . . . . . . . . . . . . . . . . . . . . 10 What Is a Flat File Schema? . 10 What Is a Flat File? . . . . . . . . . . . . . . . . . . . . . . . . . . .1 9 . . . . . . 19 Flat File Schema Developer’s Guide Version 7. . .Chapter 1. . . . . . . . . . . . . . . . . . . . . . . . . . 18 When Should I Create a Flat File Dictionary? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  To set up the translation. Field Rec1*C1Field1+C1Field2*FieldA*C2Field1+C2Field2! Composite Record Composite record delimiter = ! field delimiter = * subfield delimiter = + To communicate using flat files. A single logical record of application data is externalized as a set of records  without any structural information. ID and ID qualifier. users must create a flat file schema that contains a  particular flat file’s structural information. the application receiving the flat file must  have knowledge of the structure of the flat file.  The fields within a composite are referred to as subfields. except that composites are not  allowed inside composites. Therefore. In other  words. and fields) within a flat file can be identified. the following flat file data and its list of delimiters enables you to see how  elements (records. What Is a Flat File? When different applications attempt to communicate with one another. composites. By nesting records in the flat file schema (adding a record to a record) you  can represent the hierarchical structure of the data in the flat file schema.  All flat files consist of a list of records containing fields and composites: Fields are atomic pieces of data (for example. Flat files present complex hierarchical data in a record–based storage format. which  unlike XML does not embed structural information (metadata) within the data. This enables receivers of flat file documents to parse and validate  Flat File Schema Developer’s Guide Version 7. This structural information identifies the parent–child relationships between different  records in the flat file. they may not  speak the same “language. through the flat file schema. Concepts Overview The webMethods Flat File package (WmFlatFile) is a set of services that enables you to  translate documents into and from flat file formats.” Flat files enable you to send data to any application in a  mutually agreed upon format so that the data in the files can be read and processed. to read the flat  file. Date and time). the metadata of a flat file is separated from the data and contained in a flat file  schema. postal code).1. For example.  Composites contain multiple fields (for example. The actual data has been “flattened” by removing this hierarchical  relationship. A composite definition  contains the same information as a record definition. you use a flat  file schema to define how to identify individual records within a flat file and what data is  contained in each of those records.  Records (also known as segments) are sequences of fields and/or composites.1 10 . including how to identify records and separate  those records into fields.  and the Nth delimited field is  identified in the record. Each record is preceded by two bytes that indicate the length of the  record.  Variable length.  What Types of Flat Files Does webMethods Support? The WmFlatFile package can exchange all types of flat files but can process only certain  types of flat files. To parse a flat file that does not conform to these restrictions. Fixed length. This can be used regardless of whether a field delimiter  has been specified. mainframe  punch or print records). Each field is separated by a delimiter. Records in the flat file can have different lengths. you can create a custom  service using webMethods Developer. Each distinct record structure has a record identifier. the record identifiers must be located in the  same location in all records in the file. If the flat file contains record identifiers. The WmFlatFile package then can identify fields in these records based on either: Delimiters. For more information. This can be used only when a field delimiter (and. Each record is a fixed number of bytes (for example.  Byte position. Flat File Schema Developer’s Guide Version 7.1 11 .  subfield delimiter) has been specified. see “Default Records” on page 18. the record must be parsed using a default record definition. if necessary. or if no record identifier is  present. The WmFlatFile package can process flat files in which: The records in the flat file are defined using one of the following methods: Delimiters.1. see the webMethods Developer  User’s Guide. For more  information about default records. Each field is defined by 1) the number of bytes from the beginning of the  record and 2) the field length. Each record in the flat file is separated by a delimiter. Concepts inbound flat files for use by their back–end systems. and senders of documents to convert  outbound documents to flat file format for delivery to another back–end system.  “Validation Errors” in this guide. and field levels of flat  files. A flat file schema also acts as the model against which you can  validate an inbound flat file. A flat file schema consists of hierarchical elements that represent each record. and fields in a flat  file. For more information about data validation. including delimiters. and either a definition or  reference. What Type of Flat File Constraints Can You Define? Flat file schemas contain information about the document. You  define structural constraints for each parent element in the flat file schema. These types of constraints are  referred to as validators. the validation engine in the WmFlatFile package compares the  records. see Chapter 3. Each element is a record. Concepts What Is a Flat File Schema? A flat file schema is the blueprint that contains the instructions for parsing or creating a  flat file and is created as a namespace element in the webMethods Integration Server. and  subfield in a flat file. For more information  about setting flat file schema constraints. Conditional constraints describe the valid combinations of fields and subfields allowed  in records and composites. followed by a City field. the State field might have a content constraint  specifying that its value must be exactly two digits.1. Content type constraints describe the possible values or minimum/maximum values for  elements in a flat file. record. “Creating and Editing Flat File  Schemas and Dictionaries” in this guide. composites. and  repeated record structures.1 12 . records. composite. in this guide. or field. you can use the Required (R) conditional  validator to require that at least one of the specified fields be present. “Creating and Editing Flat File  Schemas and Dictionaries”. see  Appendix A. You then configure each element with the necessary constraints. During data validation. you can define validators only for  parent records. a flat file schema might describe an address record that consists of a  Street Address field. and ZIP Code field. For instructions to create a flat file schema. For example. An inbound flat file is considered valid when it  complies with the constraints outlined in its related flat file schema. For example. see Chapter 3. For example. In flat file dictionaries. This  blueprint details the structure of the document. State field. composites. field.  Flat File Schema Developer’s Guide Version 7. and fields in a flat file with the constraints described for those  records and fields in the flat file schema. A flat file schema can define three types of constraints:  Structural constraints describe the sequence of records.   Fields within a character–delimited composite are separated by  a subfield delimiter. Level Document  Constraint How the records are parsed What records can appear in the document Whether the records are record definitions or record references The order in which the records can appear Whether a record is mandatory or optional Whether a record can repeat. and field levels. Concepts The following table identifies the types of flat file schema constraints you can set for the  document. how many times Record/  Composite How fields and composites are extracted from a record Delimited field. not character lengths and positions.1 13 .1. Whether a field or composite is mandatory or optional How to conditionally validate each field Field Minimum and maximum field lengths List of valid values Range of valid values Partition of valid values Important! All lengths and positions specified in a flat file schema refer to byte lengths and  positions. record. This can be used regardless  of whether a field delimiter has been specified. Flat File Schema Developer’s Guide Version 7. and if so. Positional field.  This can be used only when a field delimiter has been specified. Each field is defined by an offset from the  beginning of the record and length. This is important to note because the byte  count can differ from the character count for encodings that have multi–byte characters. Extracts the Nth delimited field from the record.  0X09) Octal value (for example. Flat File Schema Developer’s Guide Version 7. The field values then are  pulled from the record using the extractors defined in the flat file schema.1 14 . !) or character representation (for example. Finally. you  can choose from one of its four record parsers: Delimited Record Parser. the parsed record is placed in the output data based on the structure defined in  the flat file schema. Record Parsers A record parser breaks a flat file into individual records. This process is repeated until all records in the flat file have been  parsed. If the record cannot be identified and you have not selected a default record. This is done  using the record identifier. as  defined in the flat file schema using the Flat File Schema Editor. which uses a flat  file schema to parse flat files inbound to the Integration Server. \r\n for  carriage return) Hexidecimal value (for example. After each record in a flat file has been parsed. each record must be identified. Concepts How Is a Flat File Schema Used to Parse Records? The WmFlatFile package provides the pub. 009) Unicode characters (for example. For information about how to  specify field format services.1. see “Format Services” on page 66. This parser expects a specific delimiter to indicate the end of a  record. you can specify: A character (for example. \uXXXX. where XXXX represents the unicode  value of the character) The occurrence of the record delimiter signals the end of one record and the  beginning of the next record. In the WmFlatFile package. For a record delimiter.flatFile:convertToValues service. Identifying the record provides the definition of that record. Fixed Length. You also can format flat file data to meet the  requirements of your back–end system or application using the Format Service property on  the Flat File Structure tab of the Flat File Schema Editor. the  field values are not extracted from the record. the field values are extracted from the record using the definition of the default  record. If the record cannot be identified (known as undefined data) and you have selected a default  record. The convertToValues service  uses a record parser (Delimited. or Variable Length) to parse the records in a  flat file.  This parser splits a file into records of the same  pre‐specified length.1.4 or later. The  WmFlatFile package uses that identifier to connect the record definition in a flat file  schema with a particular record in the flat file.  The parser supports both single‐byte and multi‐byte encodings. the third field is  used as the record identifier. You  must enter carefully the exact Unicode character values you want to search for in an  instance of the flat file you are describing. not the  WmFlatFile package. Another example is the use of Unicode  Flat File Schema Developer’s Guide Version 7. In this case. For example. Concepts Fixed Length Record Parser. see Appendix B. (The behavior of delimited fields and  records remain the same. you can  choose from one of two methods of record identification: Starts at position record identifiers compare the value that occurs in the record.” some instances of “Rec1” may be  identified as “Rec. there is no functional difference between specifying bytes or  characters. if 2 is specified. “Flat File Byte Count Parser”. This change does not affect users who currently  parse/compose flat files using single‐byte encodings because one byte equals one  character. The name of the record definition must  match the value obtained by the record identifier. Documents using  this record parser should be created using the webMethods EDI Module. Note that the  Starts at position identifier cannot distinguish between all types of record names. Service Pack 2.” Nth Field record identifiers use the value of the specified field as the record identifier.5.  These identifiers count from zero (0). Note: This parser measures the lengths and positions of records in terms of bytes.) For details. at the  specified offset. Each record may be a different length. EDI Document Type Record Parser. see the webMethods EDI Module User’s  Guide. The WmFlatFile package does not perform any kind of normalization on input provided  in the flat file schema or when comparing or processing values retrieved from a file. to all the record names defined in the flat file schema. This parser is used only for EDI flat files and provides  additional functionality needed to properly parse EDI documents. Prior to 6. the parser measured lengths and  positions in terms of characters. you should differentiate wide  (sometimes called multi–byte or zenkaku) characters from their narrow (or single–byte)  equivalents when processing Asian characters. Record Identifiers A record identifier looks at a record and extracts an identifier out of the data. This parser expects each record to be preceded by two  bytes that indicate the length of the record.  rather than characters. Variable Length Record Parser. Multi‐byte encoded  files must run on JVM version 1.” because “Rec1” begins with “Rec. For more information.1 15 . For  example. if you name records “Rec1” and “Rec. In the WmFlatFile package. For example.  If extractors are not defined in the flat file schema.1 16 . Undefined Data In some cases. not  the start of the record.flatFile:convertToValues service. For example.flatFile:convertToValues service might contain  records that were not recognized. the data resulting from the pub. When the convertToValues service processes an unrecognized record. the Shift–JIS and MS932  encodings commonly used with Japanese language text are very similar. If a value is a composite. and so on. known as undefined data. it puts a  Flat File Schema Developer’s Guide Version 7. In all cases.1. or of the lack of detail in the flat file schema (such as no record  identifier). they can have field delimiters.  Instead of a field delimiter. This could be a result of the  complexity of the flat file. fields are matched using a strict  binary comparison of Unicode character values in the separate fields. From the first field delimiter to the second field delimiter is the second field in  the record. Remember that all positions used in  extracting fields from a composite are referenced from the beginning of the composite. a subfield delimiter is used to separate a composite into fields. The user specifies  the start of the field by specifying the number of bytes from the beginning of the record to  the start of the field and specifying the number of bytes from the beginning of the record  to the end of the field. Extractors Extractors take data out of a parsed record and place it in the output of the  pub. Note: Although fixed length and variable length record parsers do not use record  delimiters. You also should exercise care when selecting the encoding of the file being processed. From the beginning of the record to the first field delimiter is the first field in  the record.  Fields are extracted from a composite based on either the position of the subfield delimiter  in the composite or on a substring of the composite. This can result in the WmFlatFile package not finding a match  where you otherwise would expect one to exist. Everything from the last field delimiter to the record delimiter (the  end of the record) is considered part of the final field. Fields and composites are extracted from a record based on the position of the field  delimiter.  Some encodings are very similar to one another. the  parser returns a series of records that contain no fields or composites. Concepts combining and pre–composed sequences. it is simply a field that can be further parsed into more fields. but they map  some characters differently. Fields also can be extracted from a record based on a substring of the original record  starting at a particular byte count and ending at a particular byte count. 1. but with fixed field and record delimiters.  unrecognized records will be placed into the output IS document with the undefined data  tag. and if you use a fixed length or  variable length parser.1 17 . Working with undefined data involves three steps: 1 2 3 Configuring the flat file schema and record–level Allow Undefined Data settings. Writing logic to handle the parsed data. In still other cases.  By selecting a default record. no errors  will be generated if the record contains undefined data. errors will be generated if the record contains undefined data. Note: If your flat file does not contain record identifiers. which it is not the  default. Flat File Schema Developer’s Guide Version 7. which might produce errors. Any record that cannot be  recognized will be parsed using this default record. You do so using a combination of two fields:  The Allow Undefined Data check box on the Settings tab The Allow Undefined Data check box for each record in the flat file schema on the Flat File Structure tab When the Allow Undefined Data check box on the Settings tab is selected. undefined  data is expected and should not generate validation errors. and the Allow Undefined Data check box for a particular record is selected. OR parsing the undefined data in each record based on the  document structure. such as logic to map the parsed data to  another service or perform error handling. Note: If the file is encoded using a multi‐byte encoding. you must select a default record. as described in  “Default Records” on page 18. If a default record is not selected. all  unidentified records should be parsed using a default record definition. a CSV (comma separated values) file can be parsed as a  special case of record with no record identifier. undefined data should not be allowed in the document and  if encountered should generate validation errors in the output. In other cases. You can select a default record when creating a flat file schema. For some types of documents. Ignoring undefined data. the service puts two placeholders into the pipeline: unDefData and  unDefBytes. If either the Allow Undefined Data check box on the Settings tab or the Allow Undefined Data check box for a particular record is  cleared.  You can choose whether you want errors to be generated for a flat file schema when  undefined data is encountered. Concepts placeholder named unDefData in the resulting IS document (IData object) and stores the  record as a string in the pipeline.  see “Customizing the Flat File  Configuration Settings” on page 74. When creating an element definition in a flat file dictionary. and fields. By default. the record  does not have a record identifier). If a default record has not been specified. if you have a CSV (comma separated values) flat file that simply lists the  name. This allows you  to create record definitions in a dictionary that can be used across multiple flat file  schemas. if your flat file schema does not contain any record identifiers. You then specify the remaining properties in the instance of the element  definition in a particular flat file schema. 321 Oak Dr Memphis TN. 888–555–1111. Concepts Default Records If the pub. each recordWithNoID record appears as a child of the record  above it. A flat file dictionary is  simply a repository for elements that you reference from flat file schemas. To modify this default behavior.  Flat file dictionaries are created as namespace elements in the Integration Server and  contain definitions of records. the record will be treated as undefined data unless you  specify a default record definition to be used to parse all unrecognized records of a  particular type. in an array. address. Reusing record definitions reduces the amount of memory consumed by a flat  file schema. If you specified a default record definition to parse this particular type of record. the record will be treated as undefined data. 123 Main St Washington DC. the element definition is  updated automatically in all of the flat file schemas.1 18 . A default record can only be defined in a flat file dictionary. Flat File Schema Developer’s Guide Version 7.1. you  must specify a default record. the file  can be properly parsed and converted to an IS document (IData object) of the name  recordWithNoID. 800–555–2222. and phone number of a group of customers. none of the records would  have a record identifier: John Doe. as  described in “Undefined Data” on page 16. For example. When you change a definition in a  flat file dictionary that is referenced in multiple flat file schemas. you specify only certain  properties. Note: You can reference a flat file dictionary definition in any flat file schema regardless of  whether the dictionary and schema are located in the same package. composites.flatFile:convertToValues service cannot recognize a record (for example. What Is a Flat File Dictionary? A flat file schema can contain either record definitions or references to record definitions  that are stored elsewhere in the namespace in a flat file dictionary. In fact. Jane Smith.  An example of this is EDI ANSI X12 and UN/EDIFACT  documents. This allows for the entire document to be edited in a single view. In this way. EDI ANSI X12 also has different versions of these documents (for example.1 19 . Reusing definitions reduces the amount of memory  consumed by the webMethods Integration Server. A more complex scenario would involve multiple families of documents and multiple  versions of those families. without  referencing a flat file dictionary. The  definitions then can be reused at a later time. or composite between versions are maintained. Defining these records. 4010). All flat file schemas in one version of the same family should use the same  dictionary. field. the best approach is to create  the definitions in the flat file dictionary and reference them in a flat file schema. Developer displays the contents of the flat file schema or  dictionary in the Flat File Schema Editor. Each  version of the document set should have its own dictionary. and  composites in a dictionary allows for them to be reused throughout the entire set of EDI  ANSI X12 document flat file schemas. In a scenario in which you intend to parse only one flat file. One dictionary should be created for each version of EDI ANSI X12  documents and one dictionary should be created for each version of EDI UN/EDIFACT  documents. composite. and composite definitions many times.  What Is the Flat File Schema Editor? When you select a flat file schema or dictionary from the Navigation Panel of  webMethods Developer.1. or flat files that do not share  record.  If a clear choice does not exist between these two scenarios. A separate dictionary would not be required for each flat file schema in the  same version. you can define these elements directly in the flat  file schema. you can be certain  that changes to a record. field. fields. Concepts When Should I Create a Flat File Dictionary? The decision to define records in a flat file dictionary versus in a flat file schema depends  on the type of flat files that you intend to parse.  Flat File Schema Developer’s Guide Version 7. The Electronic Document Interchange  (EDI) ANSI X12 standard defines a large set of document structures that reuse the same  record. or field definitions. 1. content type.1 20 . Identifies a flat file schema in the Navigation Panel. Note: A green check mark next to a flat file schema or dictionary (  ) indicates that the  flat file schema or dictionary is locked and available to be edited. the schema or dictionary is unlocked and cannot be edited.  Flat File Dictionary. For detailed information. see “Flat File  Structure Tab” below. When the check mark is  absent. Flat File Structure tab. Symbol Description Flat File Schema. The Flat File Schema Editor is divided into the following sections:  Flat File Definition tab. This tab enables you to specify the structural. This tab enables you to specify what type of flat file you are  parsing or creating. and  conditional constraints of your flat file schema. Concepts Identifying Flat File Schemas and Dictionaries Name of Flat File Schema Navigation Panel Flat File Schema Editor The following table identifies the symbols for flat file schemas and dictionaries in the  Navigation Panel of webMethods Developer. Flat File Schema Developer’s Guide Version 7. Identifies a flat file dictionary in the Navigation Panel.  composite. your reference is  broken. Identifies a composite reference in a flat file schema. either delete the reference or re–create  the definition in the appropriate dictionary. Flat file schemas that contain broken references will not parse  correctly. Identifies a field reference in a flat file schema. Composite Definition.  Composite Reference. Field Reference. If you  create a composite and then select that composite. Flat File Schema Developer’s Guide Version 7. you can add only a field reference or  field definition. For example. See Record Reference in this table for information about “Reference not found. A  composite definition contains the same information as a record definition.  except that composites are not allowed inside of a composite. Identifies a record reference in a flat file schema. when you have a record selected. If “Reference not found” appears after the reference name.  The Flat File Schema Editor uses unique symbols to represent the components of flat file  schemas and dictionaries. A broken reference indicates that the referenced element no longer  exists. composites and fields.  See Record Reference in this table for information about “Reference not  found.  you can add record.1. when you add a new element it  will be added as a child of the selected element. Record Reference. An  element reference refers to an element definition in a flat file dictionary. To fix a broken reference. allow undefined  data. Flat File Structure Tab When creating your flat file schema.1 21 . Identifies a field definition in the flat file. This panel enables you to configure a default record.” Field Definition. or field references or definitions to this record. you will create new records. The appropriate new element selections  will be displayed for that element level.  Symbol Description Record Definition. and set up the ACL (access control lists) permissions for your flat file  schema or dictionary.” An element definition is an element that is contained in a flat file schema or dictionary. add areas. For the element  name you have selected in the Flat File Schema Editor. Concepts Properties panel. The following table identifies the symbols for each component  that can appear in a flat file schema. Identifies a record definition in a flat file schema. Identifies a composite definition in a flat file schema.  and then click to move the element up or  down in the flat file schema structure. “Processing Flat Files Overview” of this guide. Concepts You use the buttons at the top of this tab to edit the structure of your schema. The  following table provides a description of each of these buttons. For more information. and then click to move the element left or  right in the flat file schema structure.1 22 . and then click to delete the selected  element. The IS document  type is used to map the output of the convertToValues service to another  format. see “Mapping Flat File Data” on  page 27 of Chapter 2.1. Select the desired element. Select the desired element. Button Description Select the desired element. Creates an IS document type for this flat file schema. Flat File Schema Developer’s Guide Version 7. Chapter 2. Processing Flat Files Overview Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Processing Inbound Flat Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Processing Outbound Flat Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Flat File Schema Developer’s Guide Version 7.1 23 2. Processing Flat Files Overview Overview As discussed in Chapter 1, “Concepts” in this guide, the webMethods WmFlatFile  package enables you to exchange all types of flat files and process certain types of flat  files. You create flat file schemas to convert and validate inbound flat files and to create  outbound flat files. The following diagram summarizes the services that the WmFlatFile package provides to  process flat files: pub.flatFile:convertToValues and pub.flatFile:convertToString. For descriptions, see  the table that follows the diagram below. Note: If you also are using Trading Networks, see the sections about flat file TN document  types in the webMethods Trading Networks Concepts Guide and webMethods Trading Networks  Administrator’s Guide for information about how Trading Networks processes flat files. Processing Flat Files webMethods Integration Server Flat File Package Conversion/Validation Services Flat File (ffData) Inbound Receive flat file convertToValues (optional validation) Process IS Document Flat File Schema Process IS Document convertToString Flat File (ffData) Send/Process Flat File IS Doc (ffValues) IS Doc (ffValues) Outbound Item Flat File (ffData) Description Flat file input with type of String, InputStream, or ByteArray  (received by the Integration Server via File Polling, HTTP, FTP, etc.  For more information, see Chapter 4, “Sending and Receiving Flat  Files” in this guide.)  Flat File Schema Developer’s Guide Version 7.1 24 2. Processing Flat Files Overview Item Conversion/ Validation Services Description WmFlatFile package provides services (pub.flatFile:convertToValues and pub.flatFile:convertToString) that parse, validate, and convert  inbound flat files to IS documents (IData objects), and construct  outbound documents from IS documents. For more information  about these services, see Chapter 5, “WmFlatFile Built–in Services  Reference” in this guide. Flat File schema containing the structure of the flat file.  An IS document (IData object) represents the structure and values  of your flat file for eventual mapping or other processing. All  inbound documents must be converted to IS documents before  being processed further. Flat File Schema IS Doc (ffValues) Formatting Inbound and Outbound Data You can format flat file data to meet the requirements of your back–end system or  application. The Format Service property in the Flat File Schema Editor enables you to  specify the service you want to invoke for a particular field when convertToValues or  convertToString is called. For example, when using the convertToValues service to convert a  date field in a flat file into an IS document, you can specify that a particular format service  be invoked for that field during parsing. To alter the format of the date field, you might  invoke a service that changes the format of the field from YYYYMMDD to MMDDYYYY.  For information about how to specify field format services, see “Format Services” on  page 66. Processing Inbound Flat Files The WmFlatFile package provides the pub.flatFile:convertToValues service, which uses a flat  file schema to parse flat files inbound to a webMethods Integration Server. The input of  this service is a flat file and the name of a flat file schema, and the output of this service is  an IS document (IData object). The output IS document is created based on the structure  defined in the flat file schema. You can also specify to validate the flat file against the flat  file schema, which generates errors as output based on the constraints placed on the  records and fields in the flat file schema. Note: Validation is turned off by default. To enable validation, you must set the validate  variable of the convertToValues service to true.  You should use this service as part of customized flow services. You then can use  webMethods Developer services to process the resulting data as necessary, (for example,  map data from one format to another). For more information about creating flow services,  Flat File Schema Developer’s Guide Version 7.1 25  For more information. Processing Flat Files Overview see the webMethods Developer User’s Guide. the flat file parser ignores any data that appears before the first  valid record in the file. “Creating and Editing Flat File Schemas and  Dictionaries” in this guide. Flat File Schema Developer’s Guide Version 7. and validate inbound flat files. Use the webMethods Developer to  create the flat file schemas used to parse.2. The general process for inbound flat files is as follows: Inbound Flat File Process Conversion/Validation Flat File (ffData) convertToValues (optional validation) IS Doc (IData) Process IS Document Flat File Schema Is Valid errors The flat file schema provides the convertToValues service with the information necessary to  detect the boundaries between records and fields. convert. “Sending and Receiving Flat Files” in this  guide. For more information about mapping data. Note: When parsing a file. the  service matches the record in the flat file with a record defined in the flat file schema using  the record identifier. see  “Mapping Flat File Data” on page 27. Step 1: Create Appropriate Flat File Schema Before you start working with an inbound flat file. see Chapter 4. Step 2: Receive the Flat File The webMethods Integration Server provides a number of ways to send and receive flat  files. After a record boundary is detected. you must create a flat file schema to be  used for conversion and validation of the document. see Chapter 3.1 26 . For steps  to create flat file schemas.  you must set the  validate variable of the convertToValues service to true.  For more information about the convertToValues service.  During flat file parsing.2. To set or  change the constraints for a particular flat file schema.1 27 . record.  Step 4: Process the IS Document webMethods Developer provides tools for processing IS documents (IData objects). and Validate Flat File Data to an IS Document To parse a flat file using a flat file schema. These steps enable you to map data into other formats. see Chapter 5. Mapping Flat File Data In many cases it is necessary to map the output of the convertToValues service to another  format. or user– defined format. which returns errors describing how  the given ffData violates the constraints described in the flat file schema. see Chapter 3. Creating an IS document type from your flat file schema enables you to reference  and view the document structure in a flow service.  and/or field constraints you defined in a flat file schema. see “What Type of Flat File Constraints Can You Define?” on page 12. and to convert the data into IS documents  (IData objects). Processing Flat Files Overview Step 3: Parse. “Creating and  Editing Flat File Schemas and Dictionaries” in this guide. “Validation Errors” in this guide. To validate a flat file against the flat file schema used to parse the file. it is an option to validate the flat file against the document. such as your back–end. For a list of the constraints you  can set. Flat File Schema Developer’s Guide Version 7. “WmFlatFile Built– in Services Reference” in this guide. Convert.  including mapping data into other formats. For a list of  validation error codes and messages. you call the convertToValues service. see Appendix A. For the flow service you are creating or editing. as shown in the figure above. Processing Flat Files Overview To map flat file data 1 In the Developer Navigation Panel.1 28 . if your flat file schema name is  “PurchaseOrder. with “DT”  appended. This creates an IS document type in the same folder as  This IS document type is named the same as the flat file schema. and then click  the schema. select the saved flat file schema. For example.flatFile:convertToValues flow operation.2.  . Flat File Schema Developer’s Guide Version 7. on the Flow Editor of the Developer  select the INVOKE pub.” the related IS document type name is “PurchaseOrderDT. click the Flat File Structure tab.” 2 3 Click   to save the IS document type. 2. Select Document 5 In the Select dialog box. “Test:PurchaseOrder”). Flat File Schema Developer’s Guide Version 7. Perform the following to add a Document Reference to the IS document type that is  based on the flat file schema. . in the ffSchema variable specify the location and  name of the flat file schema (for example. The name appears in the Name  box. then click  Reference to add a new document reference variable. Processing Flat Files Overview 4 On the Pipeline tab under Service In. “PurchaseOrderDT”). navigate to the IS document type created in step 1 of this  procedure (for example. a b On the Pipeline tab click under Pipeline Out.1 29 . Click OK. Specify other inputs  as necessary.  the WmFlatFile package receives a flat file and keeps the  file content in memory during processing.  out–of–memory errors might occur. Flat File Schema Developer’s Guide Version 7. the WmFlatFile package processes all flat files in the same manner. the  WmFlatFile package can encounter problems when working with these files because the  system does not have enough memory to hold the entire parsed file. map the value of the ffValues variable to the  document reference variable created in this procedure. this  object becomes null.1 30 . 7 Click   to save the service. The service generates an output object (ffIterator variable) that encapsulates and keeps  track of the input records during processing.2. That is. you can set the iterator variable in the  pub. the convertToValues service returns and the iterator moves to the top level of the  next record in the schema. you should exit from the repeat  step to discontinue processing.  If some or all of the files that you process using the WmFlatFile package encounter  problems because of memory constraints. until all records are parsed. If the results were kept in the pipeline. if you receive large files. the results are mapped and  dropped from the pipeline to conserve memory.wmflatFile:convertToValues service to true to process top level records (children of the  document root) in the schema one at a time. When the ffIterator variable is null. However. Handling Large Flat Files As installed. After all child records of the top level record  are parsed. This parsing should be done in a  repeat step where each time the convertToValues service returns. Processing Flat Files Overview 6 On the Pipeline tab under Service Out. When all input data has been parsed.  regardless of their size.  If you specified only certain parts  of the flat file to translate to the IS document (via the flat file schema). and subfield  separators as well as optionally specify an outputFileName so that the output also will be  written to a file. Processing Flat Files Overview Processing Outbound Flat Files The WmFlatFile package provides the pub. The general process for outbound documents is as follows: Outbound Flat File Process Conversion IS Doc (IData) convertToString Send/Process Flat File Flat File (ffData) Flat File Schema Step 1: Create Appropriate Flat File Schema Before you start working with an IS document (IData object). only those  parts will be translated back to the flat file.1 31 . which uses a flat file  schema to create a flat file outbound from a webMethods Integration Server. “Creating and Editing Flat File Schemas and Dictionaries” of this guide. you must create a flat file  schema to be used for conversion of the object.flatFile:convertToString service. Flat File Schema Developer’s Guide Version 7. You use webMethods Developer to create  the flat file schemas used to create outbound flat files. Step 2: Convert the IS Document to a Flat File The WmFlatFile package provides the convertToString service to convert flat file IS  documents (IData objects) to outbound flat files using the flat file schema you created.  Note: The flat file resulting from convertToString will be only as complete as the information  translated from the original flat file to the IS document.2. and the output of this  service is a flat file. field.  This service enables you to specify delimiters to be used as record. of course.  see Chapter 3. The input of  this service is an IS document (IData object) and a flat file schema. For steps to create flat file schemas.  on the Flow Editor of the Developer  select the INVOKE pub. in the ffSchema variable specify the location and  name of the flat file schema (for example. This creates an IS document type in the same folder  This IS document type is named the same as the flat file schema. select the saved flat file schema. Flat File Schema Developer’s Guide Version 7. Specify other inputs  as necessary.flatFile:convertToString flow operation. as shown in the figure above.” 2 3 4 Click   to save the IS document type.2. To convert an IS document to flat file data 1 In the Developer Navigation Panel.1 32 . For the flow service you are creating or editing. click the Flat File Structure tab. The following steps provide an example of how you might convert an IS document to a  flat file. On the Pipeline tab under Service In. if your flat file schema name is  “PurchaseOrder. “Test:PurchaseOrder”). .” the related IS document type name is “PurchaseOrderDT. For example. and then click  as the schema. with “DT”  appended. Creating an IS document type from your flat file schema enables you to reference  and view the document structure in a flow service. Processing Flat Files Overview Example In many cases it is necessary to map the output of the convertToString service to another  format.  including via HTTP.  see Chapter 4. navigate to the IS document type created in step 1 of this  procedure (for example. For more information. . and FTP. Select Document Reference  On the Select dialog box. Click OK. The name appears in the Name  box.1 33 . click under Pipeline In.2. a b On the Pipeline tab. Processing Flat Files Overview 5 Perform the following to add a Document Reference to the IS document type that is  based on the flat file schema. “Sending and Receiving Flat Files” in this guide. Step 3: Send/Process the Flat File After the flat file is created. 7 Click   to save the service. SMTP. Flat File Schema Developer’s Guide Version 7. you can send or process the file as necessary. then click  to add a new document reference variable. “Test:PurchaseOrder”). map the document reference variable created in this procedure to  the value of the ffValues variable under Service Out. You can send a  flat file using many methods. 6 On the Pipeline tab. 1 34 .2. Processing Flat Files Overview Flat File Schema Developer’s Guide Version 7. . . . . . . . . . . . . . . . . . . . . . 72 Managing Flat File Dictionary Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Setting Access Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Step 4: Test the Flat File Schema . . . . . .1 35 . . . . . . . . . . . . . . . . . . . 73 Customizing the Flat File Configuration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Step 2: Specify Flat File Properties . . . . . . . . . . . . . . . . . . . . . . . . . 74 Flat File Schema Developer’s Guide Version 7. . . . 41 Step 3: Define the Structure of the Flat File Schema . . . . . . . . . . . 36 Step 1: Add and Configure the Flat File Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and Editing Flat File Schemas and Dictionaries Creating a Flat File Schema . . . . . . . . . . . . .Chapter 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Creating a Flat File Dictionary . . . . . . . . . 69 Editing a Flat File Schema or Dictionary .  and then click Next. select the type of parser for this flat  file schema:  Delimiter.  7 On the Flat File Definition tab under Record Parser. see the webMethods  Developer User’s Guide. Type the name of the new flat file schema. create a flat file  dictionary. Variable Length. and the Flat File Schema  Editor displays in the right pane. Flat File Schema Developer’s Guide Version 7. select its location (the folder you created in  the WmFlatFile–dependent package). The first two bytes of the input data stream contains the length of  each record.1 36 . or composite  definitions should use a common dictionary. see “Creating a Flat File Dictionary” on page 69. To simplify the steps needed to  create a flat file schema. 2 3 4 5 6 In the New dialog box. The flat file schema you created is automatically selected. and then click Finish. click File   New in the menu bar. If you want to reuse element definitions in other flat file schemas.3. fields.) For more information about creating  and using a flat file dictionary. mainframe punch or  print records).  Create a new folder within the new package.  In webMethods Developer. Each record is of a fixed length (for example. If you  need instructions for creating packages within the Developer.  Fixed Length. select Flat File Schema. (Note that any flat file schemas sharing records. Each record is separated by a delimiter. this procedure is broken down into sections: “Step 1: Add and Configure the Flat File Schema” on page 36 “Step 2: Specify Flat File Properties” on page 41 “Step 3: Define the Structure of the Flat File Schema” on page 48 “Step 4: Test the Flat File Schema” on page 68 Step 1: Add and Configure the Flat File Schema To add a new flat file schema 1 Create a package with a dependency on the WmFlatFile package by clicking   and  typing WmFlatFile in the Package box and its version number in the Version box. Creating and Editing Flat File Schemas and Dictionaries Creating a Flat File Schema Creating a flat file schema consists of a number of steps. 8 For all types of record parsers. Description Optional – Character that separates fields in a flat file  document. you should use the wm. Although you can create EDI flat file  schemas using the Flat File Schema Editor. Flat File Schema Developer’s Guide Version 7. 009. \uXXXX.3.1 37 . you can also select carriage return line feed (or  specify \r\n) if a record ends with the two–character CRLF. Software AG does not recommend it. Do not select this option. 013) Unicode characters (for example. Note: In subsequent steps you can specify delimiters using the Character property. The EDI Document Type option is displayed for  you to view existing EDI flat file schemas. if you specify 4 as the Character position. Creating and Editing Flat File Schemas and Dictionaries EDI Document Type. see the  webMethods EDI Module User’s Guide. you  have indicated that the field delimiter appears in the fifth  character position from the beginning of the document.b2b. For more information and steps. For the Record delimiter. use the following syntax: One character or character representation (for example.  When you specify delimiters.  Important! If you are using the webMethods EDI Module to process EDI  documents. 0X13) Octal value with prefix “0” or decimal value (for example.  \t for tab).  For example.  This guide does not provide information about creating EDI flat file schemas for  use with the webMethods EDI Module. the character position at which the  field delimiter for this document is located. where XXXX represents the unicode  value of the character) The space character is allowed as a delimiter.edi services to create your flat file schemas. \n for line terminator. Hexidecimal value with prefix “0X” (for example. 0X09. *. specify the following fields:  a For Field or Composite: Property Character –OR– Character position Optional – Starting from the beginning of the document and  counting from zero (0).   the record would appear as a\+b\+c+d\+e\+f.  –OR– Character position Optional – Starting from the beginning of the document and  counting from zero (0). you  have indicated that the release character appears in the sixth  character position from the beginning of the document. the  value of the record would be a+b+c and d+e+f. When using  the convertToString service to create a\+b\+c+d\+e\+f. if you specify 5 as the Character position. Flat File Schema Developer’s Guide Version 7. The character following the  release character will not be treated as a delimiter.1 38 . you  have indicated that the subfield delimiter appears in the  sixth character position from the beginning of the  document.  the convertToString service uses Quoted Release Character. you must  preface it with your release character. Creating and Editing Flat File Schemas and Dictionaries b For Subfield: Property Character –OR– Character position Optional – Starting from the beginning of the document and  counting from zero (0). When using + within a field as text. For example. Description Optional – Character that separates subfields in a flat file  document. original meaning. the character position at which the  subfield delimiter for this document is located. your field delimiter is + and your release  character is \.3. Property Character Description Optional – Character used to enable a delimiter to be used for  its intended. the character position at which the  release character for this document is located.  For example. If you specify both.  For example. c For Release Character: Specify either Release Character –or– Quoted Release Character. if you specify 5 as the Character position. When using the  convertToValues service to create the strings a+b+c and d+e+f.   For example. the value of  the record would be Doe. if you specify 3 as the Character position. you have  indicated that the record delimiter appears in the fourth  character position from the beginning of the document. If you specify both.  the Quoted Release Character will be used.“Doe. Flat File Schema Developer’s Guide Version 7. Jane”. When you want to use (. Any delimiter  characters that appear within this section will not be treated  as delimiters. the character position at which the record  delimiter for this document is located. if you specify 5 as the Character position. –OR– Character position Optional – Starting from the beginning of the document and  counting from zero (0).  the convertToString service uses Quoted Release Character. if you have specified  both the Release Character and the Quoted Release Character.3. complete the following Record fields:  Property Character –OR– Character position Starting from the beginning of the document and counting  from zero (0). John”. Creating and Editing Flat File Schemas and Dictionaries d For Quoted Release Character: Specify either Release Character –or– Quoted Release Character. John and Doe. Description Character that separates records in a flat file document.  When using the convertToString service. you  have indicated that the quoted release character appears in  the sixth character position from the beginning of the  document.1 39 .) Property Character Description Optional – Character used to enable a section of text within a  field to be represented as its literal value. 9 If you selected Delimiter for Record Parser.) and your release  character is “.  When using the convertToValues service to create the strings  Doe. you must preface it with your quoted release character. Jane”. When using the convertToString  service to create “Doe.“Doe.  For example. your field delimiter is (.) within a field as  text.  For example. John”. the record would appear as  “Doe. Jane. the character position at which the  quoted release character for this document is located. John and Doe. Jane.  complete the appropriate  Record Identifier property: Property Starts at Position Description Counting from zero (0).  This value cannot be null and must be an integer greater than or  equal to zero (0). Flat File Schema Developer’s Guide Version 7. or \t (tab). in characters. set the  useReadableDelimiterReporting variable to false.1 40 .  For example.3. Creating and Editing Flat File Schemas and Dictionaries Important! If records use a fixed position extractor. such as \r (carriage return). 11 To define the record identifier for this flat file schema. You will not be able to  extract the record delimiter character in a fixed position field. Important! If you use the webMethods EDI Module. –OR– Nth Field Counting from zero (0). complete the following Record Parser  field: Property Record length Description Length. indicates which field in each record you  want used as the record identifier. you have  indicated that the record identifier appears in the sixth  character position in each record. see “Customizing the Flat File Configuration  Settings” on page 74. if you specify 5 as the Starts at Position. This field is available only if you have  specified a field delimiter. the Delimiter record parser does not  include the record delimiter character in the parsed record. The default for this field is  zero (0). of each record in the flat file.  \n (line feed). 10 If you selected Fixed Length for Record Parser. For details. the character position at which the  record identifier is located. This variable controls how the  Delimiter record parser parses non‐readable characters. 3. click Delete to delete the default record for this flat file  schema. Note: If the floating record has an alternate name. This record is used to parse an  undefined data record when the convertToValues service fails to find a  match between the flat file and the flat file schema.1 41 . Displays the name of the flat file dictionary that contains the default  record. If a default record is not selected. Displays the name of the record reference that will be used as the  default record. Optional – The name of the record that is defined in the schema as a  floating record. Creating and Editing Flat File Schemas and Dictionaries Step 2: Specify Flat File Properties To specify properties for the flat file schema 1 2 View the Properties panel. For more information  about the Undefined Data property. convertToValues will generate  errors when it encounters undefined data. see  “Floating Records” on page 43. specify the alternate  name in this field. Under Default Record. Note: If the flat file you are parsing does not contain record identifiers. Delete Under Value. configure the following properties: Property Set Description Optional – Under Value. If the default record is specified when creating the flat file schema. Dictionary Name Floating Record Flat File Schema Developer’s Guide Version 7. The actual record definition still exists. but is no longer  assigned to this flat file schema. By selecting a default record. the record will be treated as  undefined data.  you must select a default record. click Set to select the default record for this flat  file schema from a flat file dictionary. If the Undefined Data property is set to False and the validate variable of  the convertToValues service is set to true.  any record that cannot be recognized will be parsed using this default  record. see page 42. a CSV  (comma separated values) file can be parsed as a special case of record  with no record identifier. For details about how the parser handles floating records. but with fixed field and record delimiters.  you would assign the appropriate area to a record  to identify in which section of the document the record belongs. Click Choices to display the Areas dialog box. 4 Under Settings. which enables you to use the  following buttons to add and edit areas. Note: For a file that is encoded using a multi‐byte encoding. For more information about the record–level  property. Click to insert a new area in a specific location in the list. the Areas property enables you to add and edit areas for this flat file  schema. you may have an address record that needs to specify the  shipping address in the document header. Creating and Editing Flat File Schemas and Dictionaries 3 Under Settings. see the Allow Undef Data property on page 57. it puts a placeholder  named unDefData in the resulting IS document and stores the record as a string in the  pipeline. This is the default.  If you want to allow undefined data. the behavior is different. If  you want to re‐parse such a file to extract fixed byte position fields. You now can choose whether to allow  undefined data at the record level.3. To differentiate these two  records. Property Description Click to add a new area to this flat file schema. Note: Areas are used primarily for EDI document parsing. If the validate variable of the convertToValues service is set  to true. For  example. the convertToValues service will generate errors when undefined data is  encountered. Flat File Schema Developer’s Guide Version 7. select True. Click to delete an existing area. You must save the flat  file schema before the new area will be available for use in your flat file  structure. the Undefined Data property helps control the generation of undefined  data errors at any location in the flat file schema. Then when  defining a record in “Step 3: Define the Structure of the Flat File  Schema” on page 48. If you do not want to allow undefined data in any location in this flat file schema. An area is a way to associate an arbitrary string with a given record. the service places unDefData and unDefBytes into the pipeline. you would create “Header” and “Detail” areas. but needs to specify the  billing address in the document detail. use unDefBytes. When the convertToValues service processes an undefined record.1 42 . select  False.  When you use a fixed length or variable length parser (but not a delimited parser) to  parse such a file. Creating and Editing Flat File Schemas and Dictionaries Floating Records You can use the Floating Record property to designate any single record of a given flat file  schema to be a floating record. This property appears in the Properties panel of the Flat File Schema  Editor (see the table in step 8 on page 55). Flat File Schema Developer’s Guide Version 7.1 43 . (The position in which  it appears in the parsed record is explained in the following sections.3. you would designate NTE to be a floating record so it may appear  anywhere in the EDI document without causing a validation error. and places each NTE record that appears in an EDI document  into this container at run time.e. The parser supports floating records for both inbound and outbound  parsing (i. By designating a floating record. while executing the convertToValues and convertToString services. If a flat file schema contains multiple instances of the  designated floating record at multiple record levels. For examples. For  example.. you enable that record to  appear in any position within a flat file without causing a parsing validation error. it ignores Rec2 and Rec3.) The parser creates a  container for NTE records. respectively).  If you do not use this property. the system creates a container for  each record level. see “Examples: Parsing Inbound Floating Records” on page 44 and  “Examples: Parsing Outbound Floating Records” on page 47. In addition. not the second  record. validation errors will occur if the record structure of an  inbound document does not match the record structure defined in its flat file schema. To solve this problem. This problem can also occur while converting outbound IS documents (IData objects) into  string documents. consider the following EDI document and its flat file schema (where all records  are mandatory except the record NTE): Flat file schema definition Rec1 Rec2 Rec3 Input EDI document Rec1 NTE Rec2 Output IS document Rec1 NTE NTE Rec3 The parser generates a validation error because it  expects NTE to be the last record.  and places NTE (1). A validation error is generated  if more than 99 NTE records appear in the document. Example 1: Flat file schema definition Rec1 NTE [] Max Occurs 99 Rec2 Rec3 Rec4 Rec5 Input EDI document Rec1 Rec2 Rec3 Rec4 NTE (1) NTE (2) NTE (3) Rec5 Output IS document Rec1 NTE [] NTE (1) NTE (2) NTE (3) Rec2 Rec3 Rec4 Rec5 In accordance with the schema definition. the  parser handles them as shown in the following examples. the parser creates an NTE array as the first  record. NTE (2). Creating and Editing Flat File Schemas and Dictionaries Examples: Parsing Inbound Floating Records When the convertToValues service receives a document that includes floating records. and NTE (3) into it. NTE records are not allowed prior  to the Rec1 record.1 44 . Assume that the Floating Record  property is set to the record NTE.3. Example 2: Flat file schema definition Rec1 NTE [] Max Occurs 99 Rec2 [] Max Occurs 99 NTE [] Max Occurs 99 Rec3 Rec4 Rec5 Input EDI document Rec1 NTE (1) Rec2 Rec3 NTE (2) Rec4 NTE (3) Rec2 NTE (4) Rec5 NTE (5) Output IS document Rec1 NTE [] NTE (1) NTE (5) Rec2 [] Rec2 NTE [] NTE (2) NTE (3) Rec3 Rec4 Rec2 NTE [] NTE (4) Rec5 Flat File Schema Developer’s Guide Version 7. Flat File Schema Developer’s Guide Version 7. Thus. and Rec2) match the  schema. as specified in the  schema definition. the  parser places NTE (2) in this container. in the Rec2 array. as specified in the schema definition. Creates another NTE container (an array) under Rec2. the next record in the document is Rec3 (followed by NTE (2)). This is valid.1 45 . In accordance with the schema definition. in accordance with the  schema definition. To determine which container to put NTE (2) in. Creates a Rec2 array. NTE (2) Rec3 Rec4 a The positions of the first three records (Rec1. the  parser looks for the last defined container at the current level. Rec4. b Even though the schema definition says the next record should be an NTE  (followed by Rec3). the parser: Creates an NTE container (an array) under Rec1. NTE (1). the parser simply: Places Rec3 into the Rec2 array. NTE (1) Rec2 [] Rec2 NTE [] <== NTE container for Rec2 array. and places NTE (1) into it. Creating and Editing Flat File Schemas and Dictionaries How Example 2 was Parsed 1 The first six records of the EDI document were parsed as follows: Input EDI document Rec1 NTE (1) Rec2 Rec3 NTE (2) Rec4 Output IS document Rec1 NTE [] <== NTE container for Rec1. c The parser places the next record.3. and places Rec2 into it.  the parser adds another Rec2 to the Rec2  array. the parser also creates another NTE  container. the parser places NTE (3) in the same container as  NTE (2). Just as with the first Rec2 in the array. Thus. Creating and Editing Flat File Schemas and Dictionaries 2 Parsing NTE (3): Input EDI document Rec1 NTE (1) Rec2 Rec3 NTE (2) Rec4 Output IS document Rec1 NTE [] NTE (1) Rec2 [] Rec2 NTE [] NTE (2) NTE (3) <== added to this container at current level Rec3 Rec4 NTE (3) To determine which container to put NTE (3) in. 3 Parsing Rec2 and NTE (4): Input EDI document Rec1 NTE (1) Rec2 Rec3 NTE (2) Rec4 NTE (3) Rec2 Output IS document Rec1 NTE [] NTE (1) Rec2 [] Rec2 NTE [] NTE NTE Rec3 Rec4 Rec2 NTE [] Rec2 NTE (2) (3) NTE (4) <== creates an NTE container for second (4) In accordance with the schema definition. for the second Rec2. the parser looks for the last defined  container at the current level.1 46 . Flat File Schema Developer’s Guide Version 7.3.   To determine which container to put NTE (5) in. assume that the Floating Record property is set to the record  NTE.3. the parser places Rec5 under Rec1.1 47 . Thus. the  parser places each floating record immediately following its parent record (as defined in  the IS document). the parser places NTE (5) in the same  container as NTE (1). the parser looks for the last  defined container at the current level. Creating and Editing Flat File Schemas and Dictionaries 4 Parsing Rec5 and NTE (5): Input EDI document Rec1 NTE (1) Rec2 Rec3 NTE (2) Rec4 NTE (3) Rec2 NTE (4) Rec5 Output IS document Rec1 NTE [] NTE (1) NTE (5) <== this container is same level as Rec5 (current level) Rec2 [] Rec2 NTE [] NTE (2) NTE (3) Rec3 Rec4 Rec2 NTE [] NTE (4) Rec5 NTE (5) a b In accordance with the schema definition. Example 1: Flat file schema definition Rec1 Rec2 NTE [] Rec3 Rec4 Input IS document Rec1 Rec2 Rec3 NTE [] NTE(1) NTE(2) Rec4 Output string Rec1!Rec2!Rec3!NTE(1)!NTE(2)!Rec4 Flat File Schema Developer’s Guide Version 7.  In the following examples. Examples: Parsing Outbound Floating Records When the convertToString service converts an IS document (an IData object) to a string.  you must set the validate  variable of the convertToValues service to true. Validator. and Undefined Data properties. This enables errors to be generated for the  Ordered. see Chapter 5. the parser places them after Rec1 in the  string.  click the Flat File Structure tab of the Flat File Schema Editor.1 48 . Example 2: Flat file schema definition Rec1 Rec2 NTE [] Rec3 Rec4 Input IS document Rec1 Rec2 Rec3 Rec4 NTE [] NTE(1) NTE(2) Output string Rec1!NTE(1)!NTE(2)!Rec2!Rec3!Rec4 Because NTE(1) and NTE(2) are children of Rec1. Mandatory. For more information about this  service. To enable validation. To define the structure of a flat file schema 1 With the flat file schema name selected in webMethods Developer Navigation Panel. Step 3: Define the Structure of the Flat File Schema Important! Validation is turned off by default. “WmFlatFile Built–in Services Reference” of this guide. Creating and Editing Flat File Schemas and Dictionaries Because NTE(1) and NTE(2) are children of Rec3. Flat File Schema Developer’s Guide Version 7. the parser places them after Rec3 in the  string.3.  click the name of the flat file schema in the Name column. select the dictionary.3.  . Select the element that you want to reference and then  click Next. and then click Next.  After selecting Record Reference. Navigate to the flat file dictionary in which the record is  located. You also can right–click an element and  3 Select one of the following.1 49 . click Next. After selecting Record Definition. Select to create a reference to a record definition in a flat file  dictionary. Creating and Editing Flat File Schemas and Dictionaries 2 To add the first record. The Select New wizard appears. Flat File Schema Developer’s Guide Version 7. Property Record Definition Record Reference Description Select to create a record definition to be used one time in this  flat file schema. and  then click  select Add. click Next.  The name of the record definition in  the flat file dictionary does not need to match the record identifier that appears in the  flat file.  When you have added all of the records for this level. If the element is a  definition.1 50 . The name of a record reference will  be matched to the record identifier in the record. Creating and Editing Flat File Schemas and Dictionaries 4 In the Enter Record Definition Name(s) dialog box. Flat File Schema Developer’s Guide Version 7. these two fields are empty. The name of a record reference does not have to match the name  of the record definition in the flat file dictionary. see the table in  step 8 on page 55. 5 In the Properties panel of the Flat File Schema Editor. The Dictionary field indicates  the flat file dictionary to which the record reference refers. The Referring To field indicates  the record definition to which the record reference refers. click   and type the record name. To add another record definition at this time. The record(s) is added to the flat file schema structure.3. specify the particular properties  for this record. For a list and further explanation of these properties. Important! This name must match the value of its record identifier exactly as it will  appear in the flat file. type the name of the record. click Finish.   and one for the element definition in the flat file dictionary. The remaining fields must be set in  the particular instance of the element in the flat file schema. You cannot edit the  dictionary definition detail line. The valid element selections  display for the element you have selected. type the Name of the record in the Enter Record Definition Name(s) dialog box. Creating and Editing Flat File Schemas and Dictionaries For element definitions. you see only one line of detail. Flat File Schema Developer’s Guide Version 7. For element references. select the element to which you want to add a child and click  .  see “Creating a Flat File Dictionary” on page 69. you  will see two lines of detail: one for the instance of that element in this flat file schema. You also can right–click an element and select New. In a flat file dictionary you  can specify only certain fields for each element. For information about creating flat file dictionaries. 6 To add more elements.  If you are adding a record definition.3.1 51 .  Note: The name(s) must match the value of the identifier for each record exactly as  it will appear in the flat file.  For a description of composite extractors. and Mandatory properties in the Enter Composite Definition Name(s) dialog box. click  .3. Creating and Editing Flat File Schemas and Dictionaries To add additional record definitions at this level. see  “Extractors” on page 61. Property Name Position Description Type the name of the composite. If you are adding a composite definition.  Flat File Schema Developer’s Guide Version 7. This pulls the subfield data from the  composite. Type the field number in the record that contains the composite  you want to extract. specify the Name. Position. the composite will not be  extracted.1 52 .  If you leave this property empty. Note: The extractor works only if a field and subfield delimiter  have been defined for this flat file schema. If is not selected.  If it is not selected. Creating and Editing Flat File Schemas and Dictionaries Property Mandatory Description Optional – Select the check box to require that this composite  appear in the flat file. Type the first byte to extract from the record. Start. Name Start End Type the name of the field.3. If it is selected and the  convertToValues service validate variable is set to  true. see “Extractors” on page 61.1 53 . and  Mandatory properties in the Enter Field Definition Name(s) dialog box. the composite is not required to appear in the  flat file. Optional – Select the check box to require that this  field appear in the flat file.  Mandatory Flat File Schema Developer’s Guide Version 7. Extractor Type Fixed Position Property Description Counting from zero (0). For more information about  field extractors. the extractor returns all bytes from  the byte specified in Start to the last byte in the  record or composite. Name. Type the first byte that is not included in the  extraction. If you are adding a field definition. –1). errors will be generated if the field does not  appear in the flat file. If it is selected and the convertToValues service validate  variable is set to true. To add additional composite definitions at this level. If you enter a negative number (for  example. click  . End. errors will be generated if the composite  does not appear in the flat file. extracts a fixed number of  bytes from a record. specify the Extractor Type. the field is not required to  appear in the flat file.  click Finish. 7 When you have added all of the elements for this level.  To add additional field definitions at this level.  This extractor returns the field as a key–value  pair. Navigate to the flat file dictionary in which the element is located. This  option is available only if you specified a field  delimiter when configuring your flat file schema. For more  information about field extractors. click Next.3. Name Position Type the name of the field. if  you type 1. errors will be generated if the field does not  appear in the flat file. select the  dictionary. the field is not required to  appear in the flat file. Creating and Editing Flat File Schemas and Dictionaries Extractor Type Nth Field Property Description Counting from zero (0). indicates the field that  you want to extract from the record. If is not selected. If you are adding an element reference. Flat File Schema Developer’s Guide Version 7. If it is selected and the  convertToValues service validate variable is set to  true. see  “Extractors” on page 61. the second field will be extracted. Type a value to indicate the position of the field  that you want to extract from the record. and then click Next. click  .  Mandatory Optional – Select the check box to require that this  field appear in the flat file. The key is the name of the field.1 54 . complete the following steps:  After selecting Reference. For example.  This value cannot be null and must be an integer  greater than or equal to zero (0). Select the element that you want to reference and then click Next. The value is  the String value of the field.  you can specify the following  properties in the Properties panel of the Flat File Schema Editor: Element Record Definition Property Ordered Mandatory Max Repeat Validator Area Position Allow Undef Data Check Fields Alternate Name Description Ordered Mandatory Max Repeat Area Position Allow Undef Data Local Description Mandatory * Extractor Validator * Check Fields * Alternate Name * Description * ID Code * Local Description ** For details..3. page 60 page 60 page 60 page 61 page 57 page 61 page 57 page 58 page 57 page 58 page 60 page 60 page 60 page 57 page 61 page 57 page 59 page 60 page 58 page 61 page 58 page 57 page 58 page 59 page 59 Record Reference Composite Definition * not available for composite definitions in record references ** not available for composite definitions in flat file schemas Composite Reference Mandatory * Extractor Alternate Name * Local Description page 60 page 58 page 57 page 59 * not available for composite references in record references Flat File Schema Developer’s Guide Version 7. see .. Creating and Editing Flat File Schemas and Dictionaries 8 For each of the following element levels and type.1 55 .  “Processing Flat Files Overview” of this  guide. page 60 page 58 page 61 page 59 page 58 page 57 page 58 page 59 page 59 * only available for field definitions in composite references or record  references Field  Reference Mandatory * Extractor * Local Description page 60 page 58 page 59 * not available for field definitions in composite references or record  references 9 After you have added all of the necessary elements to this flat file schema.  10 To map the output of the convertToValues service to another format. see “Mapping  Flat File Data” on page 27 of Chapter 2. see .3. click   on the Flat File Structure tab. Creating and Editing Flat File Schemas and Dictionaries Element Field Definition Property Mandatory Extractor Validator Format Service DataType Alternate Name Description ID Code Local Description * For details.. For more information about mapping flat file schemas.. click  . You now can use this flat file schema to parse and convert inbound flat files to IS  documents (IData objects) and convert outbound documents to flat files.  Flat File Schema Developer’s Guide Version 7.1 56 .  Use in record definitions and record references in flat file  schemas. in alphabetic order. field  definitions in composite definitions and record definitions. composite references in record definitions. Creating and Editing Flat File Schemas and Dictionaries Flat File Schema Property Descriptions The flat file schema properties that you can define using the Flat File Schema Editor are  described below.3. select the area you want to use for this  record.1 57 . If the  validate variable of the convertToValues service is set to true. select True to  allow undefined data at the record level and not generate errors  when undefined data is encountered. see the Areas property on page 42. For more  information about the Undefined Data property.  from the Area drop–down list.  see “Displaying Element Descriptions and Alternate Names in the  Flow Editor” on page 67.  composite. The default is True. This name will appear  as the document name in the document type that is generated by this  flat file schema. This name will also appear in the Flow Editor. For details. Use  this field to provide a more meaningful name that can be helpful  when mapping the record. Use in record descriptions and record references in flat file  schemas. For more  information. This field is used primarily for EDI document parsing. Select False to not allow undefined data at the record level. the  convertToValues service will generate errors when undefined data is  encountered. Alternate Name Optional. see page 42. Flat File Schema Developer’s Guide Version 7. Use in: record definitions and composite definitions in flat  file schemas. and field definitions in flat file dictionaries. If the schema–level Undefined Data property is set to True. It  will also appear as a tool tip comment in the Flow Editor. Property Allow Undef Data Description Optional. For example. If you have created areas for the flat file schema on the Settings tab. record. instead of using the record  name ST. Area Optional. An alternate name for the record definition. you could specify the alternate name Transaction Start.  composite. record. and field definitions in flat file  dictionaries. field definitions and field references in composite  definitions or record definitions. DataType Use in: field definitions in composite definitions and record  definitions.  For more information. For details. It will also appear as a  tool tip comment in the Flow Editor.  Flat File Schema Developer’s Guide Version 7. Describe the purpose of the record. Select False to allow extra fields at the end of a record or composite. or pulls the subfield data from  the composite. Use in: record definitions and composite definitions in flat  file schemas.3.  The default is False. and then type the field number in the record  that contains the composite you want to extract. see “Displaying  Element Descriptions and Alternate Names in the Flow Editor” on  page 67. For details.1 58 . see “Extractors” on page 61. It will also appear as a tool tip  comment in the Flow Editor. record.  If you leave this property empty. composite. composite. Note: The extractor works for a field only if field delimiters have been  defined for this flat file schema. Use in: record definitions and composite definitions in flat  file schemas. see “Displaying Element  Descriptions and Alternate Names in the Flow Editor” on page 67. Description Optional. fields in flat file dictionaries. Creating and Editing Flat File Schemas and Dictionaries Property Check Fields Description Optional. or field. Click the Extractor field. This  description will appear in the comments section of the document  type that is generated for this flat file schema. Extractor Use in: composite definitions in flat file schemas and record  references. field definitions in composite definitions and record  definitions. composite references in record definitions and record  references. The extractor works for a composite  only if field delimiters and subfield delimiters have been defined for  this flat file schema. Select the appropriate data type. This pulls the field  or composite data from the record. the composite will not be extracted. Select True to report as errors more fields at the end of the record or  composite than are defined in the flat file schema. and field definitions in flat file  dictionaries.  fields in flat file dictionaries. To clear the format service.  and then click OK. which is provided by your SEF file. to alter the format of the date field. composite. For the service to be visible in the browser. Since the record that is being referenced is stored in  a flat file dictionary. For example. see “Displaying Element Descriptions and  Alternate Names in the Flow Editor” on page 67. composite  references in record definitions or record references. Click the Format Service field to select the service you want to invoke  for a particular field when convertToValues or convertToString is called. The IDCode.flatFile:FormatService. Describe the record. composite  definitions in record references. field definitions and field references  in composite references or record references. Creating and Editing Flat File Schemas and Dictionaries Property Format Service Description Use in: field definitions in composite definitions or record  definitions. It will appear in the comments section of the  document type that is generated for this flat file schema. Flat File Schema Developer’s Guide Version 7. the template specification  for the service on its Input/Output tab must be pub. field definitions in  composite definitions or record definitions.  For information about format services. Use in: record references in flat file schemas.3. composite and field  definitions in flat file dictionaries. Local Description Optional. simply  clear the text box. it may be used differently in different flat file  schemas. Local descriptions will also appear as a tool tip comment in the Flow  Editor. For details. is used by the  WmEDI package. or field as it is used in this particular  flat file schema. For details. see “Format Services” on  page 66. ID Code Use in: composite definitions in flat file schemas. It will also  appear as a tool tip comment in the Flow Editor.1 59 .  you might invoke a service that changes the format of the field from  YYYYMMDD to MMDDYYYY. see  “Displaying Element Descriptions and Alternate Names in the Flow  Editor” on page 67. Select True to require that this record. If you set this property and the convertToValues service validate variable  is set to true. field definitions and field references in composite  definitions or record definitions. If you select True and the convertToValues service validate  variable is set to true. Use in record definitions and record references in flat file  schemas. composite.3.1 60 . errors will be generated if the number of record  instances exceeds the maximum repeat value. composite.  You can select Unlimited or type any positive integer. or field appear in  the flat file. If you select True and the convertToValues service validate  variable is set to true. errors will be generated if the records do not  appear in this order. For all default records. Select True to require that the child records of this record appear in the  flat file in the order that they appear in the flat file schema. The default  value is 1. Creating and Editing Flat File Schemas and Dictionaries Property Mandatory Description Optional. Max Repeat Optional. the  value is always Unlimited and cannot be changed. and  composite definitions in flat file schemas. Use in record definitions and record references in flat file  schemas. not composites or fields. or field to appear in  the flat file. errors will be generated if the record does not  appear in the flat file. Maximum number of times this record can repeat within the flat file. Ordered Optional. Use in: record definitions. composite references in  record definitions.  Select False to allow the child records to appear in any order in the  flat file. This  property applies only to records. record references. Flat File Schema Developer’s Guide Version 7.  Select False to not require the record. except for default records.  This value cannot be null and must be an integer  greater than or equal to zero (0). Position indicates the position of the field that you  want to extract from the record. the field values will not be returned correctly. To use these extractors for a field in a composite. This extractor returns the field as a key–value pair. Counting from zero (0). The key is the name of the  field. field definitions in composite definitions or record  definitions. record definitions Click the Validator field. The value is the String value of the field. This extractor is a variation of the Nth Field extractor and is available for  backward compatibility for users of the webMethods EDI Module. Software AG  recommends that you use this extractor instead of ID node. For example. the field  delimiter must be specified.3. if you type 1. ID Node. the second field will be  extracted. The value is an IS document (IData object) containing a key–value pair in which  the key is always “code. see “Validators” on page 62.” and the value is the String value of the field.  The key is the name of the field. or of a subfield within a  composite. If these extractors are used without the appropriate delimiter  set. Counting from  zero (0). or Fixed Position extractors. This value cannot be null and must be an integer greater than or equal to zero  (0). You extract fields from a composite using a Nth field extractor. ID Node. Position indicates the position of the field that you want to extract from the  record. Important! Validation is disabled by default. or field in the flat  file. To enable validation.1 61 . Software AG  does not recommend that you use the ID node extractor. composite. you  must set the validate variable of the convertToValues service to true. Use in: record definitions and composite definitions in flat  file schemas. Creating and Editing Flat File Schemas and Dictionaries Property Position Validator Description Reserved for future use. Nth Field. Extractors Extractors represent the location of a field within a record. This option is available only if you specified a field delimiter when  configuring your flat file schema. and then type the desired validation you  want to be performed on this record. Optional. while you  extract fields from a record using Nth field. For a list of valid validators. Note: To use Nth Field or ID Node extractors for a field or composite in a record. the subfield  delimiter must be specified.  Flat File Schema Developer’s Guide Version 7. This extractor returns the field as a key–value pair. End Position. Multi‐byte encoded records. Creating and Editing Flat File Schemas and Dictionaries Fixed Position. where n is the number of the field in the  composite or record. composites.040. Both of these validators indicate that if  Flat File Schema Developer’s Guide Version 7. In these rules. and multi‐byte  encoded records. For example. –1). in the following flat file: Record1*FieldA*FieldB*FieldC*FieldD*FieldE. First byte that is not included in the extraction. you  might enter the following in the Validator property: D5(010.050) A B C D E Code Field The record definition has five fields defined. the extractor returns all bytes from the byte specified in  the Start Position to the last byte in the record or composite. 0n and 0n0 represent the number of the  field defined in the record or composite. If you enter a negative  number (for example. For example: record = webMethods Start Position = 1 End Position = 7 Extracted bytes = ebMeth Validators Different types of validators are available for records. Fields using either length or code list validators.020) D5(030. the second field B and so on. you might enter the following  in the Validator property: C0102C030405 A B C D E Code Field To validate the appropriate fields using the UN/EDIFACT conditional validator. First byte to extract from the record. Conditional Validators Regardless of what type of flat file you are processing. fields.1 62 . the first  extracting field A. Counting from zero (0).3. To validate fields using the ANSI X12 conditional validator. extracts a fixed number of bytes from a record. you use the byte count validator. Each with an Nth Field extractor. Start Position. you follow the syntax rules created  by the EDI Standards bodies ANSI X12 or UN/EDIFACT to specify conditional validators  for a flat file record or composite. You validate: Records and composites using conditional validators.  then all  (D5) If a specified field is present. Field B is required. If Field C is present.040.050) Flat File Schema Developer’s Guide Version 7. if you switched the extractors for the first  and second field such that the first field extracted the value Field B and the second field  extracts the value Field A. ANSI X12 Example: C030405 UN/EDIFACT Example: D5(030. If you switched the  position of these fields in the record.040. ANSI X12 Example: R030405 UN/EDIFACT Example: D3(030. if Field D and Field E are present. The conditional validator refers to the location of the field in the definition. the conditional validator would indicate that if Field B is  present Field A is required. only one of the specified fields can be  present. position 1 This now indicates that if Field B is present Field A also must be present.1 63 . the  first specified field need not be present. However. Example: Record1 – conditional validator C0102 FieldB – Nth field extractor. position 1 FieldB – Nth field extractor. all of the fields  specified in a dependent set of fields also must  be present. ANSI X12 Rule Name (and Code) Required (R) UN/EDIFACT Rule Name (and Code) One or more (D3) Definition At least one of the specified fields must be  present. Field D and Field E are  required. Creating and Editing Flat File Schemas and Dictionaries Field A is present. position 2 FieldA – Nth field extractor. you would get the following. For example.050) Conditional (C)  If first. Example: Record1 – conditional validator C0102 Field A – Nth field extractor. Field C need not be present. ANSI X12 Example: E030405 UN/EDIFACT Example: D4(030.050) Exclusion (E) One or none (D4) At most. position 2 This indicates that if FieldA is present Field B also must be present. If a dependent field is present.3. not the  location of the data in the flat file.040.  If a dependent field is present. all others cannot be  included.  UN/EDIFACT Example: D7(030.  the first specified field need not be present.040. Minimum length. Code List Validator In the Conditions box. UN/EDIFACT Example: D1(030. The code list is a comma– separated list of the allowed values for this field. ANSI X12 Example: P030405 UN/EDIFACT Example: D2(010. type the appropriate code list conditions. you specify the maximum and minimum number of characters this  field can contain to be considered valid. then at  least one (D6) Definition If a specified field is present. –1). a maximum  length error will never be generated for this field. then none  (D7) Exactly one field may be present. If the field contains more characters than the number entered. If you enter a negative number (for example.050) N/A Field Validators You validate fields using either a length validator or a code list validator. Maximum number of characters that this field can contain to be  considered valid. Note: This validator validates only in ascending order and according to the ASCII values. Minimum number of characters that this field can contain to be  considered valid.050) If the first field is present. at least one of the  fields specified in a dependent set of fields also  must be present. Maximum length. an  error will be generated. If the value of the field is not contained  in the code list.020) N/A One and only one  (D1) If first.1 64 . Length Validator For a length validator.050) Paired (P) All or none (D2) All of the specified fields must be present or  absent.040. Flat File Schema Developer’s Guide Version 7. ANSI X12 Example: L030405 UN/EDIFACT Example: D6(030.3. Creating and Editing Flat File Schemas and Dictionaries ANSI X12 Rule Name (and Code) List  Conditional (L) UN/EDIFACT Rule Name (and Code) If first. an  error will be generated.040. You can enter zero (0). errors will be generated. If the field contains fewer characters than the number entered. regardless of its value.  Values are considered to be valid for a given range if all  of the following conditions are true: The value is the same length as the start and end strings of the range.  The extra comma in 1. If the field contains fewer bytes than the number entered. The value is lexically greater than or equal to the start string and lexically less  than or equal to the value of the end string. and DEF2. The range is specified as  start string:end string. if you enter ABC. which can occur within any type of code list. Minimum number of bytes that this field can contain to be considered  valid. and the second character of each string comes from the set 0–9. Creating and Editing Flat File Schemas and Dictionaries You can specify three different types of code lists: Simple Code List. the allowed values of the field  are ABC1. the allowed values of the field are: ABC1. ABC. Each set of code lists must have the same number  of bytes. separated  by a pipe (|). Byte Count Validator You use the byte count validator for multi‐byte encoded records. If the field contains more bytes than the number entered.DEF|1. an error will be  generated. a maximum length error  will never be generated for this field. Range List. Partition List.1 65 . DEF1. A comma separated list of valid codes. A partition joins together multiple code lists within one field. The code list validator allows for the right hand side of the partition to be optional. You can enter zero (0). A2:2B is not  valid because the first character of the start string does not come from the same  character set as the first character of the end string. For  example.2. and DEF. For example. DEF2. –1).2 indicates that the values 1 and 2 are optional. Minimum length. You specify the  maximum and minimum number of bytes this field can contain to be considered valid. Maximum length. For example A0:Z9 is valid. ABC2. A–Z or 0–9).2. The character value in the same position in the start and end string comes from  the same character set (a–z. an error will be  generated. if you enter ABC. A range list. ABC2. because the first character of each string comes from the  set A–Z.DEF|1. validates that a  string value is between a given start string and end string. Maximum number of bytes that this field can contain to be considered  valid. Flat File Schema Developer’s Guide Version 7. If you enter a negative number (for example.. regardless of its value.3. DEF1.. 1 66 . you  will receive an error message in the errorMessage output variable of the format service  indicating why this field could not be validated.flatFile:FormatService” on  page 88 in Chapter 5. see “pub. when using the  convertToValues service to convert a date field in a flat file into an IS document (IData object). Flat File Schema Developer’s Guide Version 7. Creating and Editing Flat File Schemas and Dictionaries Format Services You can use the Format Service property on the Flat File Structure tab of the Flat File Schema  Editor to specify the service you want to invoke for a particular field when convertToValues  or convertToString is called. you might invoke a service that changes the format of  the field from YYYYMMDD to MMDDYYYY. A format service formats the string and optionally ensures that the value of the string  meets the restrictions specified in the format service.  you can specify that a particular format service be invoked for that field during parsing. you simply clear the text box and save  the flat file schema or dictionary. Creating Format Services To create a format service for use with a field in a flat file schema or dictionary. For more information.  To alter the format of the date field. “WmFlatFile Built–in Services Reference”. the service  must implement the pub.cnf and set the  enableFormatting variable to false.  Working with Format Error Messages If the validate input variable of your format service was set to true to validate the format  and value of a field. For example. a value is not returned in an IS  document (IData object) for convertToValues or is not present in the input data for  convertToString) the format service assigned to that field will not be executed. To disable all format services within the WmFlatFile  package regardless of what is specified in each field definition. and that field does not meet the criteria specified in the service. For more detailed information about format services.3.flatFile:FormatService service as its template specification for the  format service (located on its Input/Output tab). open  IntegrationServer_directory\packages\WmFlatFile\config\ff. Disabling Format Services To disable the format service for a particular field. you can use the built–in format  services provided in the WmEDI package to format fields. see the  webMethods EDI Module User’s Guide and the webMethods EDI Module Built‐in Services  Reference. Note: If you are using the webMethods EDI Module.  Important! If a particular field does not have a value (that is. If you delete a format service. Enable the Show Variable’s Comment option in the webMethods Developer’s Flow Editor  as follows: a b c Click File   New in the menu bar.3. Displaying Element Descriptions and Alternate Names in the Flow Editor The webMethods Developer Flow Editor will display the values of several properties that  you specified for the elements of your schema. the Integration Server’s dependency manager will  ask whether it should update all the flat file schemas and flat file dictionaries that use that  format service with the new location or name of the format service.  The Flow Editor will display the following properties: Element Record definition Record reference Composite definition Property Description Alternate Name Local Description Description Alternate Name ID Code Alternate Name Local Description Description Alternate Name IDCode DataType Local Description Composite reference Field definition Field reference To display properties in the Flow Editor 1 2 Define values for the properties as described in step 8 of “Step 3: Define the Structure  of the Flat File Schema” on page 48. They are visible as tool tips when you  move the cursor over the elements. the dependency manager will list all schemas and dictionaries  that will be impacted by the deletion. and prompts you to confirm the deletion.1 67 . Flat File Schema Developer’s Guide Version 7. Creating and Editing Flat File Schemas and Dictionaries Managing Dictionary Dependencies on Format Services If you move or rename a format service. Click Show Variable’s Comment. Use these optional properties to provide helpful  comments and more meaningful names when mapping elements in flow services. Select Flow Editor in the navigation area. To test a flat file schema 1 2 In webMethods Developer Navigation panel. click OK. you may find that it is necessary to edit your flat  file schema. see Chapter 5. 4 5 6 After you have reviewed the results. For information about validation errors. Flat File Schema Developer’s Guide Version 7. Any errors found when parsing the flat file appear in the Errors section of the  Flat File Schema Editor. To run the test. testing a flat file schema always  performs validation regardless of you settings. “Validation Errors” of this  guide. Note: Although validation is turned off by default. 3 To select a flat file with which to test the flat file schema. and then click Open. see Appendix A. Note: If you make a change to the test file you are parsing. For more information about this service.  Click  . The test response you receive contains the same  information that would result from processing and validating a flat file. click  . double–click the flat file schema that  you want to test. Creating and Editing Flat File Schemas and Dictionaries Step 4: Test the Flat File Schema Testing a flat file schema involves viewing a flat file schema in a readable structure. you must set the validate variable of the convertToValues service to  true. The name of your test flat file appears in the  top portion of the Test tab.3. From the Encoding drop–down list. navigate to and  select the test flat file. The Select file and encoding dialog box appears. select the encoding for the flat file you are testing. “WmFlatFile Built–in  Services Reference” of this guide. The parsed and converted IS documents appear in the Results  panel. you must reload the file  before running a test.1 68 . To enable validation in the processing of  an actual flat file schema. This  enables you to locate errors in your flat file schema that are keeping your flat file  documents from being parsed correctly.  composites. and fields that can be used  across multiple flat file schemas. you edit the element and its child elements just as you  would elements in a flat file schema. except that you cannot add a record to a record. Like a flat file schema. a  flat file dictionary contains definitions of records. Creating and Editing Flat File Schemas and Dictionaries Creating a Flat File Dictionary You can create a flat file dictionary for use with flat file schemas.3.1 69 . Reusing these definitions reduces the amount of memory  consumed by a flat file schema. Flat File Dictionary After you have created elements. Flat File Schema Developer’s Guide Version 7. “Concepts” of this guide. Flat file dictionaries can also contain references to  composite and field definitions in this dictionary and/or in other dictionaries. see “When Should I Create a Flat File Dictionary?” on page 19 in  Chapter 1. For more information about the circumstances for which you might want to create and use  a flat file dictionary. The flat file dictionary you created is automatically selected. select Flat File Dictionary. and the Flat File Schema  Editor displays in the right pane of the Developer. or Field Definition) and click  an element and select New.3. You now can use the Flat File  Schema Editor to configure the flat file dictionary.  .1 70 . click File   New in the menu bar. Type the name of the new flat file dictionary. Creating and Editing Flat File Schemas and Dictionaries To create a flat file dictionary 1 In webMethods Developer. and then click Next. select the element type to which you want to add a child (Record Definition. 4 To add elements. You also can right–click  Flat File Schema Developer’s Guide Version 7. select its location (a folder in a  WmFlatFile–dependent package). and then click Finish. 2 3 In the New dialog box. Composite Definition.  see “Flat File Schema Property Descriptions” on  page 57.. (For a list of these  properties. Composite Definition Validator  Check Fields  Alternate Name  Description  ID Code page 61 page 58 page 57 page 58 page 59 Define all other composite definition properties in the  composite reference instance in the flat file schema. To add additional element definitions at this level. Creating and Editing Flat File Schemas and Dictionaries The valid element selections display for the element you have selected. see .. page 61 page 58 page 57 page 58 Define all other record definition properties in the record  reference instance in the flat file schema. For each of the  following element levels.1 71 . Flat File Schema Developer’s Guide Version 7.) You define child field definitions  and references within a composite the same way you define  the elements in a flat file schema.3. see “Flat File Schema Property  Descriptions” on page 57. click  5 . you can specify the following properties in the Properties  panel of the Flat File Schema Editor: Element Record Definition Property Validator  Check Fields  Alternate Name  Description For details. You cannot define child  elements for a field definition. Field Definition Validator  Format Service  DataType  Alternate Name  Description  ID Code page 61 page 59 page 58 page 57 page 58 page 59 Define all other field definition properties in the field reference  instance in the flat file schema.) You define child composite and field definitions and  references within a record the same way you define them in a  flat file schema. except that you cannot add a record to a  record. you edit the element and its child elements just as  you would elements in a flat file schema. (For a list  of these properties. After you have created elements. Re–structure the elements. the dependency manager will list all flat file schemas and  dictionaries that will be impacted by the deletion. and click to move the element  up or down in the flat file schema structure. Creating and Editing Flat File Schemas and Dictionaries 6 After you have added all of the elements to this flat file dictionary.1 72 . To rearrange the structure of your flat file schema.  Rename existing elements. it does not identify the names of the records. To do so. that is your responsibility. and click to delete. To do so.  to save  Note: Elements added the dictionary cannot be referenced until the dictionary has  been saved. see “Creating a Flat File Schema” on page 36. You now can create flat file schemas based on this flat file dictionary. and then select Rename. or composites that  reference the dictionary. the Integration Server’s dependency manager will ask  whether it should update all the flat file schemas and dictionaries that use this dictionary  with the new location or name of the dictionary. make the necessary changes on the Flat File Structure  tab and then save the flat file schema or dictionary. Editing a Flat File Schema or Dictionary Important! To edit a flat file schema or dictionary. Flat File Schema Developer’s Guide Version 7. right–click the element. For flat file schemas and dictionaries. Managing Flat File Dictionary Dependencies If you move or rename a dictionary. use the  buttons at the top of the Flat File Structure tab. If you delete a dictionary.3. Select the element you want to move. Button Description Select the element you want to delete. Select the element you want to move. fields. However. For information about access  control lists (ACLs) see “Setting Access Permissions” on page 73. you must have the proper access  permissions to do so and have locked the flat file schema. you can do the following: Edit any element properties. For a list of these settings and  properties. and prompts you to confirm the  deletion. click  the dictionary. and click to move the element  left or right in the flat file schema structure.  select the ACL level to which you want to grant  write access. Setting Access Permissions Administrators of the Integration Server can set access control list (ACL) permissions to  control user access and editing privileges for each flat file schema or flat file dictionary. under Permissions. This enables the ACL you select  to view this flat file schema or dictionary. double–click the flat file schema  for which you want to set permissions. Creating and Editing Flat File Schemas and Dictionaries The dependency manager also manages dictionary dependencies on format services in a  similar way. Click   to save the flat file schema permissions. see “Managing Dictionary Dependencies on Format Services” on page 67.3. This enables the ACL you select to view and edit this flat file schema or  dictionary. select  the ACL level to which you want to grant read access.1 73 . from the List ACL drop–down box. 4 Flat File Schema Developer’s Guide Version 7.  In the Properties panel.  To set access privileges for a flat file schema or dictionary 1 2 From the webMethods Developer Navigation Panel. 3 From the Write ACL drop–down box. true: Attempt to match the order of the fields in composites  and records to the order of the fields in composites and  records in the flat file schema.3. false: Do not enable the use of alternate code sets. You implement these flags in the configuration  file: IntegrationServer_directory\packages\WmFlatFile\config\ff.1 74 . Creating and Editing Flat File Schemas and Dictionaries Customizing the Flat File Configuration Settings The WmFlatFile package provides the following flags you can use to customize some  aspects of the package’s default behavior.cnf Flag alwaysSortFields Value Determines whether the pub. true (the default): Enable the use of alternate code sets. Example: useAlternateCodeSets=true Flat File Schema Developer’s Guide Version 7. Example: alwaysSortFields=true useAlternateCodeSets Determines whether to enable the use of alternate code sets. false (the default): Assume that the fields in composites  and records are in the same order as the flat file schema.flatFile:convertToString service checks  the order of the fields in composites and records that it receives  as input (in ffValues) against the flat file schema that is specified  in the ffSchema input parameter.  the value reported will be the non‐readable  carriage return code (decimal 13 or hexidecimal OD). such as \r (carriage return). false: The parser reports the delimiters as the actual  delimiter character.1 75 . This impacts how you can use the delimiter information in flow  mapping. the resulting value is abc\ndef If useReadableDelimiterReporting=false.g. set this variable  to false. Note: If you use the webMethods EDI Module. the resulting value is abc def Flat File Schema Developer’s Guide Version 7. If you use the delimiters directly in flows with  variable substitution. non‐printable characters will not be  substituted correctly when useReadableDelimiterReporting=true. \n (line feed). This variable does not impact  human‐readable delimiters such as | or *. Creating and Editing Flat File Schemas and Dictionaries Flag useReadableDelimiter Reporting Value Controls how the Delimiter record parser parses non‐readable  delimiters. or \t  (tab). if the delimiter is a  carriage return. when the output of the convertToValues service  shows that the record delimiter is \n and a user flow has an  input set to the following: abc%@delimiters\record%def the resulting value will be as follows: If useReadableDelimiterReporting=true.  true (the default): The parser reports the delimiters as  human‐readable characters.3. e. the carriage return  character is represented as \r. For example..  For example. 3.b2b. spacePad is set to right. fixed length fields are left justified. If spacePadJustifies=true and: spacePad is set to left. fixed length fields are right  justified.b2b. fixed length fields are right  justified.flatFile:convertToString and  wm. If spacePadJustifies=false (the default) and: spacePad is set to left. Creating and Editing Flat File Schemas and Dictionaries Flag spacePadJustifies Value Controls how the input parameter spacePad justifies fixed length  fields handled by the services pub. and spacePad is  set to left or right. spacePadJustifies has no effect when spacePad is set to none.edi:convertToString when the parameter  spacePad is set to left or right. Example: spacePadJustifies=false dontTrimControl Characters Determines how whitespace and control characters are handled  by the service wm. Example: dontTrimControlCharacters=true Flat File Schema Developer’s Guide Version 7.1 76 . and spacePad is set  to left or right. If dontTrimControlCharacters=true. If dontTrimControlCharacters=false. control characters are treated as  whitespace and truncated. fixed length fields are left  justified. the service does not truncate control  characters from delimited fields.edi:convertToString. spacePad is set to right. . . . . . . . .Chapter 4. . . . . . . . . . . . . . . . . 78 Flat File Content Handler and Content Type . . . . . . . . . . . . . . . . . . . . . . . 81 Submitting a Flat File to Integration Server via File Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending and Receiving Flat Files Overview . . . . . . . . . . . . . . . . . . . . . . 84 Flat File Schema Developer’s Guide Version 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Submitting a Flat File to Integration Server via HTTP . . . . . . . . . . . . . . . . . . .1 77 . . . . . . . . . . 79 Submitting a Flat File to Integration Server in a String Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Submitting a Flat File to Integration Server via an E–mail Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Submitting a Flat File to Integration Server via FTP . . . . . . 78 Choosing the Service to Receive the Flat File from the Content Handler . . .  For more information about File Polling. the InputStream is read  and the results are returned to the invoker of the service. Note: If you use Trading Networks. These services are described in “Choosing the Service to Receive the Flat File from  the Content Handler” in this chapter. which the target  service can convert into an IData object using pub. Send a flat file to a service as an e–mail message attachment.1 78 .” This content handler passes the contents of the flat file to the service specified  in the submit method in an InputStream named ffdata. The WmFlatFile package provides services that can be called within customized flow  services or the File Polling processing service to initially accept and consume inbound flat  files. for example.  For more information about how Trading Networks processes flat files.flatFile:convertToValues. see the  “Configuring Ports” section of the “Configuring the Server” chapter in the webMethods  Integration Server Administrator’s Guide. HTTP. Submit a flat file to a service in a String variable (of any name). see sections about  flat file TN document types in the webMethods Trading Networks Concepts Guide and  webMethods Trading Networks Administrator’s Guide Flat File Content Handler and Content Type You submit a flat file to a flow service using one of the methods discussed in this chapter. Flat File Schema Developer’s Guide Version 7. Sending and Receiving Flat Files Overview The webMethods Integration Server provides the following automated mechanisms for  sending and receiving any type of flat file. see  “Submitting a Flat File to Integration Server via File Polling” on page 84. etc. you can send flat files directly to Trading Networks.  The WmFlatFile package registers a content handler for the content type “application/x– wmflatfile. Submit a flat file to a service via File Polling.4. FTP. which is not included in this guide.  Post a flat file to a service via HTTP. If an InputStream or ByteArray  named ffreturn is present when the service completes execution. FTP a flat file to a service. For general steps to configure ports. wm.1 79 . public class ArbitraryFlatFileClient . This approach does not use the flat file content handler. IDataCursor inputsCursor = inputs.wm.*. you should code the target service to execute  pub.insertAfter(“orders”. Sending and Receiving Flat Files Choosing the Service to Receive the Flat File from the Content Handler Those methods that use the flat file content handler must do the following:  Accept an InputStream object called ffdata.insertAfter(“authCode”. . inputsCursor. the client 1) loads the flat  file into a String.create().4. import com. Flat File Schema Developer’s Guide Version 7.app.data.io. The invoked service then processes  the input data and can place parameters in the pipeline that will be returned to the java  client as determined by the specific scenario. “Processing Flat Files Overview” of this guide. import java. 2) puts the String into the element orders in an IS document (IData  object) named “inputs..b2b. When you use this approach. inputsCursor. see Chapter 5. Instead. The WmFlatFile package provides the pub.getcursor(). In this example. import com. inputsCursor. //––Load FF into orders string String orders = YourLoadFlatFileMethod(orderFile). the invoked service  must expect the contents of the flat file to be in a specific pipeline variable.wm.” and 3) invokes purch:postOrder on the server at localhost:5555. The java client  must place the source file in the pipeline as a String.*. orders). //––Put input values into IData object IData inputs = IDataFactory. authCode).util.last().*.*. the flat file) to an IS document  (IData object). For more information about using convertToValues. Return data in an InputStream or a ByteArray called ffreturn.  “WmFlatFile Built–in Services Reference” of this guide.  Submitting a Flat File to Integration Server in a String Variable One way to submit a flat file to the Integration Server is to pass the entire document to a  service in a String variable. so the  restrictions outlined in the previous section do not apply. The following code fragment illustrates how a Java client might submit a flat file to the  purch:postOrder service on the Integration Server. import com.e.client.flatFile:convertToValues to convert the String variable (i. Details about using this service to  process inbound documents are provided in “Processing Inbound Flat Files” on page 25  of Chapter 2.flatFile:convertToValues service to be used within  flow services to initially accept inbound flat files. if (inputsCursor.” When the Integration Server receives an HTTP POST request where Content–Type is  application/x–wmflatfile. –AND– Set the value of the Content–Type request–header field to “application/x–wmflatfile. “Processing Flat Files Overview” of this  guide. you must specify certain information. pub. Address the request to the URL of an service (for example. it passes the body of the request as an InputStream to the service  specified in the request’s URL. null).” Contain flat file data in the body of the message. Flat File Schema Developer’s Guide Version 7.. if you want to post a flat file to a service through  HTTP. The data must be the only text that  appears in the body of the request.connect(“localhost:5555”. “null”.1 80 . “postOrder”. they are not suitable clients for this type of submission. As discussed in Chapter 2. Building a Client that Posts a Flat File to a Service Regardless of which client you use. you must have a  client that can do the following: Send a string of data (a flat file) to the Integration Server using the HTTP POST  method. IData outputs = c.disconnect().invoke(“purch”.  http://rubicon:5555/invoke/purch/postOrder). c.process response } The Integration Server invokes postOrder to pass the flat file to convertToValues. Submitting a Flat File to Integration Server via HTTP A client can post a flat file to a service via HTTP. To build a client 1 2 3 4 Submit a POST request to the Integration Server. To use this approach. Because most browsers do not allow you to modify the  Content–Type header field. Set the Content–Type header field to “application/x–wmflatfile.client:http. Clients  that you might use to submit a flat file in this manner include PERL scripts (which allow  you to build and issue HTTP requests) or the Integration Server service.first(“response”)) { //.. Sending and Receiving Flat Files //––Submit request to server c. inputs). Do not assign it to a name=value pair. This will  produce an “orders” string that can be mapped to the ffdata input variable in the  convertToValues service. this service will produce an IS document (IData object).4.  where hostname is the name of the  machine running the Integration Server. folder. By default the FTP  port is assigned to port “8021.client:http to POST a  flat file to a service. When the Integration Server receives a flat file on the FTP listening port. To submit a flat file to the Integration Server via FTP. port is the port on which  the Integration Server is running.” However.1 81 . url To.bytes You also will set any optional HTTP variables. Set this Variable. such as authorization information.. this assignment is configurable.subfolder is the path to the  service folder names.string –OR– data. Submitting a Flat File to Integration Server via FTP You can FTP a flat file to the Integration Server’s FTP listening port. so you should  check with your Integration Server administrator to see which port is used for FTP  communications on your Integration Server.. This is the URL of the service that you want to invoke. data.. The format for  specifying the URL is http://hostname:port/invoke/  folder. and service name is the name of the service to  invoke.subfolder/service name. it passes it as an  InputStream to the service in the directory to which the file was FTP’d. Flat File Schema Developer’s Guide Version 7. The invoked service will have an InputStream ffdata object  in the pipeline that contains the flat file data.Content– Type “post” Name: Content–type Value: The specific content type for the document (application/ x–wmflatfile) This is the flat file that you want to post. that are  required by your application.4.. the service to which you want to pass  the document must take an InputStream as input for the ffdata variable.  webMethods services can be invoked via a URL. Sending and Receiving Flat Files The following example describes the values that you set if you use pub.” Example: http://rubicon:5555/invoke/MyFFProcessing/ ProcessFlatFile method headers. The following value would invoke the “ProcessFlatFile” flow  service located in the “MyFFProcessing” package on the “rubicon”  server with port number “5555. txt destinationflatfile. Therefore. not  IntegrationServer_directory\ns\Purchasing\ServiceName.txt Partner1PO. The file you send and the output file it produces (see below) are  written to a virtual directory system maintained in your Integration Server session. 3 Copy the flat file to this directory using the following command: put sourceflatfile. Each folder in the Developer  is treated as a directory when FTPing to the Integration Server. For example.txt. serverhost serverport username To set.client folder contains built–in services that you can use to FTP a file from the  Integration Server. Point to the directory that contains the service to which you want to pass the flat file. For example.purchaseRequests:rfq service. to  put a document called PurchaseOrder. Sending and Receiving Flat Files If you want to submit a flat file to a service through FTP. you would use the following FTP command: Example: put PurchaseOrder. destinationflatfile.txt. Set this variable. not the root directory of the target machine.4.txt on the Integration Server as  Partner1PO.. the directory name would be  \ns\purchasing\purchaseRequests\rfq.txt is the name of the destination file.client:ftp service. Flat File Schema Developer’s Guide Version 7. This is the valid user name on the target machine..txt is the name of source file that you want to pass to the  Integration Server. FTPing a File From a webMethods Integration Server The pub.txt. This is the port on the Integration Server that is listening for FTP  traffic. This is the name of the machine running the Integration Server. the application must specify  certain information.file content type Where sourceflatfile. and  application:x–wmflatfile indicates the content type of the file submitted. To submit a flat file via FTP 1 2 Initiate an FTP session on the Integration Server’s FTP listening port. you must set the variables listed in the  following table. To use the pub. if  you want to FTP a file to a service in the Purchasing folder.application:x–wmflatfile Note that the file you FTP to the Integration Server is never actually written to the  server’s file system.  Example: cd \ns\Purchasing\SubmitOrder Important! Note that the root directory for this operation is your Integration Server’s  namespace directory (ns). for the  purchasing..1 82 . you use  \ns\Purchasing\ServiceName as the path to that service..  For example. Important! When you end the FTP session..txt. “put” If you are sending to the Integration Server.txt. the Integration Server automatically deletes the  original file and its results from your session. For example. localfile remotefile For more information about these services.1 83 .out” is the name of the flat file initially FTP’d to the service. If  you are sending to the Integration Server. Getting Results from an FTP’d Document The results from a service executed by an FTP request are written to the same virtual  directory to which the flat file was initially FTP’d.. Flat File Schema Developer’s Guide Version 7. You retrieve this document using the FTP “get” command.  destinationflatfile. This file  contains the value of the output variable ffreturn of the invoked service.txt” on the Integration Server..txt. If sending to another  type of server.out “PurchaseOrder. \ns\Purchasing\SubmitOrder. this is the working directory of the FTP server. The name of the output file to which  results are written is sourcefile. Sending and Receiving Flat Files Set this variable. if you put a  document called “PurchaseOrder. This is the name of the remote file in which you want to save the  data you sending..out. For example.4.application:x–wmflatfile. For  example. you would use the  following FTP command to get its results: Example: get PurchaseOrder. This is the name of the source file. this is the local path to  the service that should be invoked after receiving the flat file.txt.txt. password command dirpath To set. It is a good practice to make each file name that you FTP to the Integration Server unique  (perhaps by attaching a timestamp to the name) so that you do not inadvertently  overwrite other FTP’d documents or their results during an FTP session. This is the valid password for the username in username. destinationflatfile. the file name should be  followed by the content–type. see the webMethods Integration Server Built‐In  Services Reference.  see the “Configuring Ports”  section of the “Configuring the Server” chapter in the webMethods Integration Server  Administrator’s Guide. To do this. To submit a flat file via email 1 2 3 Put the flat file in an e–mail attachment. (Consult your  Integration Server administrator to see whether an email port has been set up on your  Integration Server.” Specify the name of the service that will process the file in the e–mail’s subject line. the Integration Server  executes the service that you specified as the Processing Service. the document will be processed by the global service  if one is defined or. it passes the  document as an InputStream to the service configured in the pipeline variable ffdata. if not. When a file with this content type is posted to the directory on the Integration  Server that you are monitoring for flat files (Monitoring Directory).  Because the content type is “application/x–wmflatfile”. Sending and Receiving Flat Files Submitting a Flat File to Integration Server via File Polling You can send a flat file to the Integration Server via a File Polling processing service. when the Integration Server  receives the flat file in the appropriately configured Monitoring Directory. Requirements for Submitting a Flat File Document via an E-mail Message To submit a flat file to the Integration Server via an e–mail message. your Integration Server must be configured with  an e–mail port that monitors the mailbox to which the flat file will be sent. the Integration Server automatically  retrieves the message and passes that document as an InputStream to the service specified  on the e–mail’s subject line (or. the e–mail  port’s default service).) When a flat file arrives in the e–mail port’s mailbox.4. by the default service assigned to the e–mail port (if one has  Flat File Schema Developer’s Guide Version 7. your client program  must specify certain information. For  general steps to configure the File Polling listener port. Submitting a Flat File to Integration Server via an E–mail Message You can send a flat file document as an attachment to an e–mail message to an e–mail  mailbox and have the Integration Server automatically retrieve the e–mail message and  process the flat file it contains. Set the e–mail’s Content–Type header to “application/x–wmflatfile.1 84 . if a service is not specified on the subject line. To poll specifically for flat files. If  you leave the subject line empty. you must specify the Default Content Type as “application/x– wmflatfile”.  and then sent as an attachment of  an e–mail message to the sender of the original message. For more information about specifying the port’s default service. you must explicitly configure it to do so. Flat File Schema Developer’s Guide Version 7. A String specifying the fully qualified name of the service to  which the Integration Server will pass the attached document. This file contains the value of the output variable ffreturn of the invoked service. the results from a service  invoked through the port are written to sourcefile. the e–mail port does not return any results from requests that it  receives. filename A String containing the e–mail address to which the results of the  service will be sent. the e–mail port invokes its default  service (if one has been assigned to it). Getting Results from an Emailed Document If your e–mail port has been configured to return results. ffreturn  can be either an InputStream or a byte array..  For more information about configuring the e–mail port to return results. Example: orders:ProcessPO If you do not specify subject.out. see  the webMethods Integration Server Administrator’s Guide.. to subject To. see your  webMethods Integration Server Administrator’s Guide. contenttype attachments. The specific content type for the document (“application/x– wmflatfile”).. The service that will process the flat file must take an InputStream as input in the ffdata  variable.. Sending and Receiving Flat Files been assigned). see the  webMethods Integration Server Built‐In Services Reference. A string specifying the fully qualified name of the file containing  the flat file.1 85 .client:smtp to  email a flat file to a service. from attachments. Set this Variable. If you want the port to return results.4. For more information about using this service.txt. A String specifying the e–mail address monitored by the  Integration Server’s e–mail port. The following example describes the values that you would set if you used pub. Important! By default. 1 86 . Sending and Receiving Flat Files Flat File Schema Developer’s Guide Version 7.4. Chapter 5. WmFlatFile Built–in Services Reference Flat File Conversion Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Flat File Generation Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Flat File Generation IS Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Flat File Generation Sample Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Flat File Schema Developer’s Guide Version 7.1 87 5. WmFlatFile Built–in Services Reference Flat File Conversion Services Use the services in the pub.flatFile folder when converting between Flat File documents and IS documents  (IData objects). pub.flatFile:FormatService Use this specification when you create format services for fields in a flat file schema or dictionary. The  format service is invoked for a field when the pub.flatFile:convertToValues and pub.flatFile:convertToString services  are invoked. You create a format service to format the field String and ensure that the value of the String  meets the format restrictions of the format service. When creating a particular format service for use with  the Format Service property in a flat file schema or dictionary, the service you select must implement the  pub.flatFile:FormatService specification (located on its Input/Output tab). Important! If a particular field does not have a value (that is, a value is not returned in the IS document  (IData object) for the pub.flatFile:convertToValues service or is not present in the input data for the  pub.flatFile:convertToValues service) the format service assigned to that field will not be executed. Input Variables value direction String The field value to format. String Indicates the type of formatting to be applied to the field. Specify one of the  following: Value convertToString Description This field is in an outbound document and needs its internal  format converted to its external format. This field is in an inbound document and needs its external  format converted to its internal format. convertToValues validate String The value of the input parameter validate from the pub.flatFile:convertToValues  service. true The value of the convertToValues validate parameter is true  (validate). The value of the convertToValues validate parameter is false (do  not validate). This value is always false when the value of the  direction parameter is convertToString.  false minLength String Enables you to validate the minimum length of a field. If the field is extracted via  a Fixed Position Extractor, this is the number of bytes that are extracted. If the field is  not extracted via the Fixed Position Extractor and a Length Validator is associated with  this field, this is the minimum length that will be considered valid. Otherwise, this  parameter will not be present in the pipeline. Flat File Schema Developer’s Guide Version 7.1 88 5. WmFlatFile Built–in Services Reference maxLength String Enables you to validate the maximum length of a field. If the field is extracted via  a Fixed Position Extractor, this is the number of bytes that are extracted. If the field is  not extracted via the Fixed Position Extractor and a Length Validator is associated with  this field, this is the maximum length that will be considered valid. If the maximum  length is unlimited (–1) or there is no Length Validator, this parameter will not be  present in the pipeline.  Document Information that can be used by individual formatting services. This  information can be obtained from one of 3 locations: convertToString – You can specify FormatInfo in addition to the delimiter information  for a call to this service. convertToValues – If delimiter information is explicitly passed into the convertToValues  service, FormatInfo can be specified. From the UNEDIFACT UNA segment – The EDI document type automatically  extracts the decimal separator from the UNA segment. The only format services that use this feature are the decimal formatting services (for  implied decimal and decimal formats). The FormatInfo IS document should contain a  string called DecimalCharacter. If the decimal character is ‘,’ the number would be  formatted as 100,10 (European format) instead of 100.10, as is common in the US.  Note: Changes to the data in this object will be reflected in all other format services that  are invoked during execution of convertToString and convertToValues. FormatInfo Output Variables formattedValue meetsFormat String The field value with appropriate formatting applied. String Whether the value could be formatted properly. Value true false Description Indicates that the value could be properly formatted. Indicates that the value could not be properly formatted. errorMessage valueToValidate String If meetsFormat is false, this parameter provides a text message describing the  formatting error. String The value that will be used by the validator for this field. If this value is not  present, the value passed in the input variable value will be validated. This field is  used only for situations in which the input variable validate is set to true. Flat File Schema Developer’s Guide Version 7.1 89  This is the default. Value left Meaning Left justify the records (add blank spaces to the right of the records)  before the records are written to the output. Value false true Important! If you are upgrading from webMethods Integration Server version 4. Flat File Schema Developer’s Guide Version 7. WmFlatFile Built–in Services Reference pub. Note: This service does not validate the document.5. to  enable left or right justification you must add the following line to the  IntegrationServer_directory\packages\WmFlatFile\config\ff file: spacePadJustifies=false Then. By default. Create errors in output. Meaning Do not create errors in output. For details. String (optional) How to position the records in the flat file. Input Variables ffValues ffSchema spacePad Document The IData object representing the flat file. see “Customizing the Flat File Configuration Settings” on page 74. No spaces added. but you can set a flag to optionally return  the document as a byte array instead. right none signalError String Whether to create errors in the output.flatFile:convertToString Converts an IS document (IData object) to a flat file document based on the flat file schema that you  specify. String Namespace name of the flat file schema to use to convert the given IS  document to a string. this service returns the document as a string.6. Right justify the records (add blank spaces to the left of the records)  before the records are written to the output.1 90 . reload the WmFlatFile package so that this configuration setting will take  effect. String Character to use to ignore a record. field. 0X09. 013) Unicode characters (for example. field.1 91 . and the quoted  release character is “. Value true Description Trailing empty fields will be removed from the output. the string appears as “a*b”.5. If a release character occurs in a field or subfield before the  delimiter. A field separator remains to denote an empty field. WmFlatFile Built–in Services Reference noEmptyTrailing Fields String Whether trailing empty fields are to be removed from the output. String Character to use to separate fields. false delimiters Document (optional) The separator characters used to construct the output string. String Character to use to ignore a record. or subfield delimiter in  a field. For example. you can specify: One character or character representation (for example. For example. This is the default. field subfield release quotedRelease Flat File Schema Developer’s Guide Version 7. if it is set to true. *. If a quoted release character occurs in a field or subfield  before the delimiter. To  specify a delimiter. it will be prefixed with release before being written to the  output string. it will be prefixed with quotedrelease before  being written to the output string. \n for line terminator. For  example. or subfield delimiter in  a field. 0X13) Octal value with prefix “0” or decimal value (for example. If you want to specify  the two–character carriage return line feed (CRLF) characters.  specify \r\n. if  it is set to false. the output for a record with empty trailing fields  looks like the following: AAA*01*02********! (where ! is used as  segment terminator). \uXXXX where XXXX represents the unicode  value of the character) Value record Meaning String Character to use to separate records. 009. the output for a record with empty  trailing fields looks like the following: AAA*01*02! (where ! is used  as segment terminator). The string is pre‐ and appended  with the quoted release character. the field value is a*b. Used only  with records that have delimited fields.  \t for tab) Hexidecimal value with prefix “0X” (for example. if * is a delimiter. String Character to use to separate subfields. String The type of encoding used to write data to the output file. You should specify true for sortInput if the data  in ffValues is not in the same order as defined by ffSchema. The order of the undefined records appear in the final  document is random. note that: The service will run slower. WmFlatFile Built–in Services Reference FormatInfo Document Any values mapped to the FormatInfo variable will be  passed unmodified to all format services invoked by convertToString  and convertToValues. Important! If you select to sort the input records. This is the default. String (optional) Whether you want the service to sort the input records to match the  flat file schema specified in ffSchema. false You do not want the service to sort the input records to match the  flat file schema.1 92 . The default  encoding is UTF–8.  the order they appear in the final document is random. Returns the document as a byte array instead of a string. All undefined records will be sorted after the defined records. This  setting is useful (but optional) when parsing multi‐byte encodings. Value true Encoding sortInput Description You want the service to sort the input records to match the flat file  schema. If there are multiple records at the same level with the same name. returnAsBytes Value false true Flat File Schema Developer’s Guide Version 7. provide the name of the file you want created as a result of this  service.5. Description Returns the document as a string. The input records must match the order of the flat  file schema. This is the default. outputFileName String (optional) If you want the output returned in a file instead of in the string  output variable.  It is used only when the iterate variable has been set to true. Variable record Description String Character used to separate records. The string value is not returned.1 93 . Object String array containing messages pertaining to errors that occurred during  conversion. \uXXXX where XXXX represents the unicode  value of the character) The space character. String The full name of the flat file schema object used to parse the ffData object. If the delimiter is null.5. 0X13) Octal value with prefix “0” or decimal value (for example. InputStream. 0X09. Flat File Schema Developer’s Guide Version 7. WmFlatFile Built–in Services Reference Output Variables string bytes errorArray String Data that represents the flat file document. The default  encoding is UTF–8. returns the output as a byte array  encoded using the specified encoding. *. Specifying  one of these values will override any information set in the flat file schema. If you want to specify  the two–character carriage return line feed (CRLF) characters. Document (optional) An IData object that contains the segment terminator and the  field and subfield separators. you can specify: One character or character representation (for example.  \t for tab) Hexidecimal value with prefix “0X” (for example. it will be located using the  information defined in the flat file schema. this contains a value of null. \n for line terminator. 011. 023) Unicode characters (for example. pub.flatFile:convertToValues Converts a flat file document to an IS document (IData object) based on the input flat file schema. To specify a delimiter. you must specify all values.  specify \r\n. Input Variables ffData ffSchema  ffIterator encoding delimiters Object The flat file input with type of String. or ByteArray. Object (optional) An object that encapsulates and keeps track of the input data during  processing. Object If the input variable returnAsBytes=true. String (optional) The encoding of the InputStream passed in to ffData. Important! If you specify one delimiter value. If no errors are encountered.  field. This is the default. until all records are  processed. and the  quoted release character is “. If a quoted release character occurs in a field or subfield  before the delimiter. The string is pre‐ and appended  with the quoted release character.5. String Character to use to ignore a record. iterate String (optional) Whether you want to process the input all at one time or not.  Processes all input data at one time. the string appears as “a*b”. it will be prefixed with the release before being  written to the output ffValues. After all child records of the top  level record are processed. String Character used to ignore a record. field. or subfield delimiter  in a field. This is the default. Always create IS document even though all the fields are null. the iterator moves to the top level of  the next record in the flat file schema. Description No IS document (IData object) will be created if all the fields are  null. if * is a delimiter. Value true false Flat File Schema Developer’s Guide Version 7. quotedRelease FormatInfo Document Any values mapped to the FormatInfo variable will be  passed unmodified to all format services invoked by convertToString  and convertToValues.1 94 . WmFlatFile Built–in Services Reference field subfield release String Character used to separate fields. or subfield delimiter  in a field. it will be prefixed with quotedrelease before  being written to the output string. the field value is a*b. Description Processes top level records (children of the document root) in the  flat file schema one at a time. String Character used to separate subfields. Value true false createIfNull String (optional) Whether to create the IData object if all the fields are null. For example. If a release character occurs in a field or subfield before  the delimiter.  Use this option when validating the  structure of the ffData against the given flat file schema.  ffValues will not return data.5. Validation errors are  returned only if validate is set to true. false keepResults String (optional) Whether to return the parsed data in the ffValues output parameter. true returnErrors  String (optional) Whether to return the validation errors. Value asArray Description Return any validation errors with the ffData in an array called  errors. Note: The fixed length record parser ignores skipWhiteSpace. it preserves white space. This is the  default. Value true Description Ignore white spaces at the beginning of a record. When the flat file parser encounters more than the maximum number of  errors within a record. Return validation errors in the ffValues object. inResults both maxErrors String (optional) The maximum number of errors that can be returned from one  record.1 95 . false validate String (optional) Whether to return error messages that describe how ffData differs  from the flat file schema. Value true Description The parsed ffData will be returned in the output ffValues. This is the  default. This is the default. Value false Description Do not return error messages describing how ffData differs from  the specified flat file schema. This is the default. Flat File Schema Developer’s Guide Version 7. Record is used as it is identified (useful for positional data record). Return validation errors in both errors and ffValues. the parser will stop parsing and return the parsed data and  errors processed up until that point. WmFlatFile Built–in Services Reference skipWhiteSpace String (optional) Whether white space at the beginning of records will be ignored. Validation errors are returned only if validate is  set to true. Return errors describing how the given ffData violates the  constraints described in the flat file schema.  the count  of the next defined record will reflect the undefined  data. WmFlatFile Built–in Services Reference flags Document (optional) Flags that you can set to govern convertToValues options. the second is 2. For example. This is the default. Value true Description The @record–count field is added to each parsed  record. Value true Description When a conditional validation error occurs. the @record–count field for the next defined  record will be 8.  If there are records that are undefined data. The @record–count field is used to identify the record  number of each parsed record.  etc.  This is the default. detailedErrors String Whether you want detailed conditional validation error  information. When a conditional validation error occurs. “Validation Errors”.5. if the @record–count field for a  record is 2 and that record contains 5 undefined  records. the  service does not provide detail error information. This flag is only used when validate is true. false The @record–count field is not added to each parsed  record. Variable addRecordCount Description String Whether you want the service to add an additional field  (@record–count) to each parsed record in the resulting IData object  (ffValues). For more  information. This field contains the number of the parsed  record.  Conditional validators report only whether a  condition failed validation with no additional  information about the conditions that were violated. The first parsed record is 1. false Flat File Schema Developer’s Guide Version 7. the  output errors variable will contain detail information  about all the conditions that were violated. see Appendix A.1 96 . The service will report invalid records as errors prior  to locating the first valid record. Object (optional) An object that encapsulates and keeps track of the input records  during processing. This  is the default. at the end of fields. left right both Output Variables ffValues ffIterator Document The IData object that represents the input flat file data. When the ffIterator variable  is null. isValid String (optional) An array containing the validation errors. The validate input variable was set to true and errors were found.5. Value true Description The service will wait until it finds the first valid  record before reporting invalid records as errors. “Validation  Errors” of this guide. WmFlatFile Built–in Services Reference skipToFirst Record String Whether you want the service to wait until it finds the first  valid record before reporting invalid records as errors.  String Whether flat file contains validation errors. When  all input data has been processed. This is the default. The service will delete all blank spaces at the  beginning and end of all fields. It is used only when the iterate variable has been set to true. For more information about validation error codes see Appendix A. or both. The service will delete all blank spaces at the end of  all fields. Value none Description The service will not delete any blank spaces from  fields.1 97 . Value true false errors Description The validate input variable was set to true and no errors were found. the object becomes null. false trimWhitespace String Whether you want the service to delete any blank spaces at  the beginning of fields. or  the validate input variable was set to false. if any. you should exit the LOOP to discontinue processing. Flat File Schema Developer’s Guide Version 7. that were found in  ffData. The service will delete all blank spaces at the  beginning of all fields. Input Variables None Output Variables encodings String List A list of supported encodings.flatFile. WmFlatFile Built–in Services Reference pub. Input Variables FlatFileSchema PackageName DocumentTypeName String The fully–qualified name of the flat file schema for which you want to  generate an IS document type.  which are described in “Flat File Generation Sample Services” on page 111. Flat File Generation Services Use the services in the pub.flatFile.flatFile. The sample services are the  sample.jar installed. The sample.generate folder to create. and delete flat file dictionary entries.generate folder.generateFFSchema:fixedLength service.generate:createDocumentType Creates an IS document type that defines the XML representation of a flat file schema. contains sample  services that illustrate how to use the services in the pub.generateFFSchema folder.5. String The fully–qualified name that you want to assign to the created IS  document type. That is.flatFile. “Programmatically Creating Flat File Schemas and Dictionaries”. if you do not have converters.flatFile:getSupportedEncodings This service returns a list of supported encodings. pub. modify.1 98 . String The name of the Integration Server package in which you want the created  IS document type to be placed.  entire flat file dictionaries.generateFFSchema:delimited service and the sample.  not Java defaults. and flat file schemas. see  Appendix C. which is in the WmFlatFileSamples package. For more information about how to use these services. it returns null.flatFile. Output Variables None Flat File Schema Developer’s Guide Version 7.flatFile. This service will only report webMethods encodings.  the Integration Server determines if other  dictionaries depend on the dictionary being deleted. deleted will be either  true or false. Input Variables FFDictionaryName Output Variables deleted String Whether the flat file dictionary was successfully deleted. Value true false String The fully qualified name of the flat file dictionary that you want to delete. Output Variables None pub. The flat file dictionary was not successfully deleted.generate:createFFDictionary Creates an empty flat file dictionary. Flat File Schema Developer’s Guide Version 7.generate:findDependants service to return the names  of all flat file schemas and dictionaries that are dependent on the dictionary you are deleting. Before deleting the dictionary. This service throws an exception is if the flat file dictionary you want  to create already exists when the service is invoked.1 99 . String The name of the Integration Server package in which you want the created  flat file dictionary to be placed. Input Variables FFDictionaryName PackageName String The fully–qualified name of the flat file dictionary you want to create. and gives the user the option of cancelling the  deletion. Description The flat file dictionary was successfully deleted.flatFile.flatFile.generate:deleteFFDictionary Deletes a flat file dictionary. Usage Note Before you run this service. WmFlatFile Built–in Services Reference pub.flatFile. you should run the pub.5. WmFlatFile Built–in Services Reference pub. deleted will be either  true or false. Input Variables FFDictionaryName EntryName EntryType String The fully–qualified name of the flat file dictionary that contains the entry  that you want to delete. Description The flat file schema was successfully deleted. The flat file schema was not successfully deleted. Value true false Description The flat file dictionary entry was successfully deleted. Flat File Schema Developer’s Guide Version 7. pub. String The name of the entry that you want to delete. The flat file dictionary entry was not successfully deleted. Output Variables deleted String Whether the flat file dictionary entry was successfully deleted.generate:deleteFFSchema Deletes a flat file schema.flatFile. Input Variables FFSchemaName Output Variables deleted String Whether the flat file schema was successfully deleted. or  Field.5. Value true false String The fully–qualified name of the flat file schema that you want to delete.generate:deleteFFDictionaryEntry Deletes a single entry from a flat file dictionary. String The type of entry that you are deleting. Composite. deleted will be  either true or false.flatFile. Specify Record.1 100 . Output Variables references Document List The referenced objects and the packages that contain them.flatFile. String The name of the dependant object. String The name of the flat file dictionary whose dependants you want to find.generate:findDependants Returns the names of all flat file schemas and dictionaries that are dependent on a given flat file dictionary.1 101 . Input Variables name String The name of the flat file dictionary or flat file schema whose references you  want to find.5. Variable packageName name Description String The name of the package that contains the dependant  object.flatFile. WmFlatFile Built–in Services Reference pub. String The name of the referenced object.generate:findReferences Returns the names of all flat file dictionaries that are referenced by a given flat file dictionary or flat file  schema. Flat File Schema Developer’s Guide Version 7. pub. Input Variables FFDictionaryName String The fully–qualified name of the flat file dictionary that you want returned  as XML. Input Variables ffDictionaryName Output Variables dependants Document List The dependant objects and the packages that contain them. Variable packageName name Description String The name of the package that contains the referenced  object. pub.flatFile.generate:getFFDictionaryAsXML Returns a dictionary as an XML string.   pub.generate:getFFDictionaryEntryAsXML Returns a single dictionary entry as an XML string. The returned XML  string conforms to the pub. The returned XML  string conforms to the pub.generate:FFSchema IS document type. String The name of the entry that you want to returned as XML. Specify Record.1 102 . pub. Input Variables FFSchemaName String The fully–qualified name of the flat file schema that you want returned as  XML. Input Variables FFDictionaryName EntryName EntryType String The fully–qualified name of the flat file dictionary that contains the entry  that you want returned as XML. The returned XML string  conforms to the pub.generate:FFDictionary IS document type. Composite.flatFile.flatFile.flatFile.generate:getFFSchemaAsXML Returns the specified flat file schema as an XML string.flatFile. WmFlatFile Built–in Services Reference Output Variables FFXML String The returned flat file dictionary as an XML string. Flat File Schema Developer’s Guide Version 7. or  Field.generate:FFDictionary IS document type. String The type of entry that you want returned. Output Variables FFXML String The returned flat file schema as an XML string.5. Output Variables FFXML String The returned flat file dictionary entry as an XML string.flatFile. Input Variables FFDictionaryName EntryType String The fully–qualified name of the flat file dictionary that contains the entries  that you want listed.flatFile. “Programmatically Creating Flat File Schemas and  Dictionaries”. Output Variables EntryNames String List The list of returned flat file dictionary entries. use the pub.flatFile. String The type of entries that you want listed. Flat File Schema Developer’s Guide Version 7.5.generate:FFDictionary IS document type. String The flat file dictionary (as an XML string) that you want to create in the  Integration Server namespace. see the samples provided in the WmFlatFileSamples package  and that are described in “Flat File Generation Sample Services” on page 111.flatFile.1 103 .generate:deleteFFDictionary service  to delete the flat file dictionary before invoking this service. WmFlatFile Built–in Services Reference pub.generate:listFFDictionaryEntries Lists all entries in a specified flat file dictionary that are of a specified type. Specify Record. Composite.generate:saveXMLAsFFDictionary Creates a flat file dictionary in the Integration Server namespace by converting the specified flat file  dictionary that is in XML format into a namespace flat file dictionary. pub. If a flat file dictionary with the same  name already exists in the Integration Server namespace. String The name of the Integration Server package in which to save the flat file  dictionary. Input Variables FFDictionaryName PackageName FFXML String The fully–qualified name of the flat file dictionary that you want to create in  the Integration Server namespace. see “Creating a Service that Retrieves the XML File” on  page 140 in Appendix C. The XML string must conform to the  pub. For  sample code that shows how to retrieve the data for FFXML from an XML file in  the local file system. This service throws an exception is if a flat file  dictionary with the same name already exists when it is invoked.flatFile. Note: To see examples of how to supply the XML string in FFXML by mapping data  from another file. or  Field.   Output Variables saved String Whether the flat file dictionary was saved successfully. the service reports the structural validation  errors. It will have one of the  following values. the service proceeds with logical validation and  reports any logical validation errors. The flat file dictionary was not successfully saved. pub. If a flat file schema with the same name already  exists in the Integration Server namespace. When the XML string contains  no structural validation errors.generate:saveXMLASFFSchema Creates a flat file schema in the Integration Server namespace by converting the specified flat file schema  that is in XML format into a namespace flat file schema.generate:deleteFFSchema service to delete the flat  file schema before invoking this service.flatFile. The  default is 100. String List (optional) Warnings about the flat file dictionary that was created.flatFile. Logical validation of the XML contents. The validation occurs in two stages.  1 2 Structural validation of the XML. WmFlatFile Built–in Services Reference maxNumOfErrors String (optional) The maximum number of errors that you want returned.5. This service throws an exception is if a flat file schema with the  same name already exists when it is invoked. but does not proceed with logical validation. The service ensures the flat file dictionary is valid before saving it in the  Integration Server namespace. Flat File Schema Developer’s Guide Version 7. Description The flat file dictionary was successfully saved.flatFile. Value true false Errors Warnings Usage Note Use this service to add a new flat file dictionary. String List (optional) Errors that occurred while attempting to save the flat file  dictionary to the Integration Server namespace. Use the pub.generate:updateFFDictionaryEntryFromXML if  you want to update one or more entries in a flat file dictionary rather than creating a new flat file  dictionary.1 104 . If structural validation errors occur. use the pub. 1 105 . The flat file schema was not successfully saved. The service ensures the flat file schema is valid before saving it in the Integration  Server namespace. maxNumOfErrors String (optional) The maximum number of errors that you want returned. the service proceeds with logical validation and  reports any logical validation errors. see “Creating a Service that Retrieves the XML File” on  page 140 in Appendix C. String List (optional) Errors that occurred while attempting to save the flat file  schema to the Integration Server namespace. Note: To see examples of how to supply the XML string in FFXML by mapping data  from another file. String The name of the Integration Server package in which to save the flat file  schema. The  default is 100.flatFile. Value true false Errors Warnings Description The flat file schema was successfully saved. It will have one of the  following values. String List (optional) Warnings about the flat file schema that was created. WmFlatFile Built–in Services Reference Input Variables FFSchemaName PackageName FFXML String The fully–qualified name of the flat file schema that you want to create in the  Integration Server namespace. If structural validation errors occur. String The flat file schema (as an XML string) that you want to create in the  Integration Server namespace.  Flat File Schema Developer’s Guide Version 7. When the XML string contains  no structural validation errors. The XML string must conform to the  pub. see the samples provided in the WmFlatFileSamples package  and that are described in “Flat File Generation Sample Services” on page 111.5.generate:FFSchema IS document type. but does not proceed with logical validation. For  sample code that shows how to retrieve the data for FFXML from an XML file in  the local file system. “Programmatically Creating Flat File Schemas and  Dictionaries”. The validation occurs in two stages.  Output Variables saved String Whether the flat file schema was saved successfully. the service reports the structural validation  errors. Logical validation of the XML contents.  1 2 Structural validation of the XML. The dictionary entry was not successfully saved. The validation occurs in two stages. If structural validation errors occur. Logical validation of the XML contents. see “Creating a Service that Retrieves the XML File” on  page 140 in Appendix C. but does not proceed with logical validation. It will have one of the  following values. If the entry does not  already exist. This service goes  through all entries that you specify in the FFXML variable. If an entry with the same name and type  already exists in the flat file dictionary. Value true false Description The dictionary entry was successfully saved. For  sample code that shows how to retrieve the data for FFXML from an XML file in  the local file system. The XML string in  FFXML must conform to the pub. Input Variables FFDictionaryName FFXML String The fully–qualified name of the flat file dictionary that contains the entries  that you are replacing and/or adding.generate:updateFFDictionaryEntryFromXML Updates one or more entries in a flat file dictionary in the Integration Server namespace. When the XML string contains  no structural validation errors. “Programmatically Creating Flat File Schemas and  Dictionaries”. Note: To see examples of how to supply the XML string in FFXML by mapping data  from another file.  Output Variables saved String Whether the dictionary entry was saved successfully.  1 2 Structural validation of the XML. the service proceeds with logical validation and  reports any logical validation errors.flatFile. Flat File Schema Developer’s Guide Version 7.generate:FFDictionary IS document type.1 106 . this service overwrites the existing entry. the service reports the structural validation  errors. String The dictionary entries (as an XML string) that you want to use to replace an  existing entry or that you want to add to the flat file dictionary. maxNumOfErrors String (optional) The maximum number of errors that you want returned. this service creates the entry in the specified flat file dictionary. WmFlatFile Built–in Services Reference pub. This service ensures the entries are valid before saving them in the flat file  dictionary.5. The  default is 100.flatFile. see the samples provided in the WmFlatFileSamples package  and that are described in “Flat File Generation Sample Services” on page 111.  For more  information about how to use these IS document types. Flat File Schema Developer’s Guide Version 7.flatFile.xsd Variables FFDictionary Document The dictionary entries that you want to add or update.5. entire flat file dictionaries.1 107 . Document The definition of the record. WmFlatFile Built–in Services Reference Errors Warnings String List (optional) Errors that occurred while attempting to save the entry to the  flat file dictionary. The  information you specify in a record  definition is the same as the information that  you specify when creating a flat file  dictionary using the Flat File Schema Editor.flatFile. String List (optional) Warnings about the dictionary entry that was updated or  added. Variable EntryName RecordDefinition Description String The name of the record. see Chapter 3. see Appendix C. pub. Leave this  null if you do not want to add or update record entries.generate folder define the format of the information that you must  provide to add or update dictionary entries. Flat File Generation IS Document Types The IS document types in the pub.generate:FFDictionary This IS document type defines the format to use when supplying a flat file dictionary or dictionary entry  (in the FFXML variable) and the format that services return (in the FFXML variable) when you are  retrieving a flat file dictionary or dictionary entry. FFDictionary has  the following structure: RecordDictionary  Entry Document List (optional) The dictionary entries for records that  you want to add or update in the flat file dictionary. The structure for this IS document type is defined in the  following XML schema: IntegrationServer_directory\packages\WmFlatFile\pub\FFGeneration.  For descriptions of the fields. “Programmatically Creating Flat  File Schemas and Dictionaries”.  “Creating and Editing Flat File Schemas and  Dictionaries”. and flat file schemas.   “Creating and Editing Flat File Schemas and  Dictionaries”. The  information you specify in a field definition  is the same as the information that you  specify when creating a flat file dictionary  using the Flat File Schema Editor.flatFile. WmFlatFile Built–in Services Reference Composite DictionaryEntry Document List (optional) The dictionary entries for composites  that you want to add or update in the flat file dictionary.5. Document The definition of the composite. FieldDictionary Entry Document List (optional) The dictionary entries for fields that you  want to add or update in the flat file dictionary. see Chapter 3. be sure to supply all dictionary entries.generate:updateFFDictionaryEntryFromXML to update the flat file dictionary. see Chapter 3. For  descriptions of the fields. Document The definition of the field. Usage Notes If you are using this IS document type to supply a flat file dictionary as input to the  pub.generate:saveXMLAsFFDictionary. Variable EntryName FieldDefinition Description String The name of the field.1 108 .flatFile. Leave  this null if you do not want to add or update composite entries.  For descriptions of the fields. If you are using this IS  document type to update an existing dictionary. provide only the entries that you want to add or update  and invoke the pub. Leave this null if  you do not want to add or update field entries.  The information you specify in a composite  definition is the same as the information that  you specify when creating a flat file  dictionary using the Flat File Schema Editor. Flat File Schema Developer’s Guide Version 7.  “Creating and Editing Flat File Schemas and  Dictionaries”. Variable EntryName Composite  Definition Description String The name of the composite. Document Structure RecordStructure RecordUsage Flat File Schema Developer’s Guide Version 7. For a description of the fields.flatFile. The information that you specify for DocumentStructure  corresponds to the data you specify on the Flat File Structure tab in  the Flat File Schema Editor. WmFlatFile Built–in Services Reference pub. including either the  dictionary reference for  this record or the  definition of the record. For a description of the fields.5. Variable Ordered Description String Whether the child  records appear in the flat  file in the order they are  defined in the flat file  schema. Variable Ordered Description String Whether the child records appear in the  flat file in the order they are defined in the flat  file schema.xsd Variables FFSchema Document The flat file schema that you want to add or update. see  “Step 3: Define the Structure of the Flat File Schema” on page 48. The  structure for this IS document type is defined in the following XML schema: IntegrationServer_directory\packages\WmFlatFile\pub\FFGeneration. Document Information  about how the record is  used. Document List Definitions of the records within  the flat file.1 109 . see  “Step 1: Add and Configure the Flat File Schema” on page 36.generate:FFSchema This IS document type defines the format to use when supplying a flat file schema (in the FFXML variable)  and the format that services return (in the FFXML variable) when you are retrieving a flat file schema. FFSchema has the  following structure: Variable Delimiters Description Document The delimiters used in the flat files that adhere to this  flat file schema. Document The structure of the flat files that adhere to this flat file  schema. The information that you specify for Delimiters  corresponds to the data you specify on the Flat File Definition tab  in the Flat File Schema Editor. Document Where to locate the identifier to use to correlate a  record in the flat file to a record definition in the flat file schema. RecordParser Document The type of record parser. WmFlatFile Built–in Services Reference RecordStructure Document List Child records  of this record. Document Areas String List Areas for this flat file schema. An area is a way to  associate an arbitrary string with a given record. If you  specify a default record.1 110 . DefaultRecord Reference Record Identifier Undefined DataAllowed String Whether you want the pub. For  DelimitedParser.flatFile:convertToValues service to flag undefined  data errors. Document (optional) The dictionary name and entry name that  identifies the default record for the flat file schema.  Specify either the NthFieldIdentifier variable or the  FixedPositionIdentifier variable: Use NthFieldIdentifier to identify the field in the record  (counting from zero) that contains the identifier. VariableLengthParser. Use FixedPositionIdentifier to identify the character position  in the record (counting from zero) where the record  identifier is located. the default record is used for any record that  cannot be recognized. and EDIParser. you do not  need to specify a value. Flat File Schema Developer’s Guide Version 7. when using the flat file schema to parse  a flat file schema. In this IS document. specify  only the one variable that corresponds to the type of record  parser to use.flatFile:convertToValues service to  generate undefined data errors when you use this flat file  schema to convert a flat file to an IData object. Specify true if you want to allow undefined data and do not  want the pub. specify one of FixedLengthParser. VariableLengthParser. or EDIParser. just have the variable in the pipeline.  DelimitedParser.5. That is.flatFile:convertToValues service to flag  undefined data errors. This is a  recursive reference to the  RecordStructure defined in  FFSchema/DocumentStructu re. Specify false if you do not want to allow undefined data  and you do want the pub.  which is where the field occurs in the record Flat File Schema Developer’s Guide Version 7.flatFile. name. which is in the WmFlatFileSamples package. Note: If the floating record has an alternate name.txt definition file. The created flat file schema references a flat file  dictionary for record definitions.flatFile.1 111 . for example. contains sample  services that illustrate how to use the services in the pub. which follows a RecordDefinition and defines the child records of the previous record that  was defined by a RecordDefinition. address Field position. sample. which this service also creates. which is the maximum number times this child record can appear after its parent  record FieldDefinition. specify the  alternate name. The WmFlatFileSamples  package is located in the Knowledge Base on the Advantage Web site. which is a brief description of the contents of the field.txt definition file contains comma–separated data. which follows either a RecordDefinition or a ChildRecord. which defines a type of record that is contained in the flat file.generateFFSchema:delimited Creates a flat file schema for parsing a delimited flat file.flatFile. which is the identifier for the child record being defined. A ChildRecord contains the following: ChildRecord keyword Child record identifier. Each record in the . There  are three types of definitions in the . Flat File Generation Sample Services The sample.5.generateFFSchema folder. A RecordDefinition  contains the following: RecordDefinition keyword Record identifier. WmFlatFile Built–in Services Reference FloatingRecord String (optional) The name of the record that is defined in the  schema as a floating record.txt file: RecordDefinition. The flat file schema will be created based  on data in a . Description String Description of the flat file schema. It defines the fields that are in  the previous record that was defined by a RecordDefinition or a ChildRecord. A FieldDefinition  contains the following: FieldDefinition keyword Field name.generate folder. Repeat count. which is the identifier for the record being defined ChildRecord. String The name of the flat file dictionary associated with the flat file schema you  are creating.txt definition file to parse. WmFlatFile Built–in Services Reference The sample. String The name of the Integration Server package in which to create the flat file  schema and dictionary. which is an example of a delimited flat file that can be parsed using the flat file  schema created from the data in the FFDefinition.  referencing a dictionary entry that does not exist.5. Each record will contain the fields defined  by the corresponding FieldDefinitions. An error is  generated if this flat file schema already exists.1 112 . String The field number that contains the record identifier. String Character used to separate fields. Records will be nested as indicated by the ChildRecords.txt definition file that you can use as input to this service FFExample. String Character used to separate subfields.txt definition file and loops over each  RecordDefinition creating a flat file dictionary entry for each. Input Variables TXTFilename SchemaName DictionaryName PackageName RecordId Delimiters String The name of the . which is a sample . The dictionary will be created if it does not already exist. The first  RecordDefinition defined in the . If a record is listed in the .txt. The WmFlatFileSamples\pub\sample\flatFile\generateFFSchema\delimited directory contains the  following files to use with the sample: FFDefinition.generateFFSchema:delimited service parses the . Variable record field subfield Output Variables None Description String Character used to terminate records.txt file.txt. that record will appear in the flat file schema. Document An IData object that contains the segment terminator and the field and  subfield separators used by the flat files that the flat file schema will be used to  parse.txt definition file will be considered the root node of the flat file  document. Flat File Schema Developer’s Guide Version 7. All other records must be children of that record. String The fully–qualified name of the flat file schema to create.txt definition file as  a ChildRecord only (and not defined as a RecordDefinition).flatFile.  The created flat file schema contains record  definitions rather than referencing a flat file schema.csv. Field length. String The name of the Integration Server package in which to create the flat file  schema and dictionary. String The fully–qualified name of the flat file schema to create. Input Variables CSVFilename SchemaName PackageName RecordLength RecordId Output Variables None String The fully–qualified name of the CSV definition file to parse. Each record in the CSV definition file contains the following fields: Record identifier. address. name. The WmFlatFileSamples\pub\sample\flatFile\generateFFSchema\fixedLength directory contains the  following files to use with the sample: FFDefinition. which is a brief description of the contents of the field.1 113 . Field name. which is a sample CSV file that you can use as input to this service FFExample. which is the identifier for the record being defined.csv file. The flat file schema will be created based on data in a  CSV definition file.txt. which is number of bytes in the field. which is an example of a fixed length flat file that can be parsed using the flat file  schema created from the data in the FFDefinition. The sample.flatFile.generateFFSchema:fixedLength service  reads the CSV file and creates the flat file schema to parse a fixed length flat file.generateFFSchema:fixedLength Creates a flat file schema for parsing a fixed length flat file. String The number that indicates where in the record the record identifier starts. for example. String The number indicating the length of each record defined by the flat file  schema. Field start position. An error is  generated if this flat file schema already exists. The CSV file must be sorted by the record identifier. Flat File Schema Developer’s Guide Version 7.flatFile. WmFlatFile Built–in Services Reference sample.5. which is the position of the first byte to extract from the record. WmFlatFile Built–in Services Reference Flat File Schema Developer’s Guide Version 7.1 114 .5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Appendix A. . . . . . . . Validation Errors Validation Error Contents . . . . 116 Validation Error Codes . . . . . . . . . . . . . . . . . . . . . 120 Flat File Schema Developer’s Guide Version 7. . . . . .1 115 . . . . . . . . . . . . . . . . . flatFile:convertToValues service is set to true and an  object within the flat file does not conform to the flat file schema. If the service finds that an object is invalid.1 116 . which  appears nested in the error array in the variable childErrors.flatFile:convertToValues service only generates details about violated  conditions when the flag/detailedErrors input variable of the pub. the service generates  errors when validating the flat file.flatFile:convertToValues  Flat File Schema Developer’s Guide Version 7. Example of Validation Results This errors array contains the following types of information about the errors that  occurred in a record during validation. The pub.A. Validation Errors Validation Error Contents When the validate variable of the pub. Errors with conditional validators can generate detail information about the  conditions violated in a child errorDetails array. it returns  validation errors in the errors output of the convertToValues service. see “General Error Entries in the errors Array” on  page 117. Each error in a child record also generates one item within the parent record.  Each error in a record generates one entry in the errors array. For more information  about the fields in the errors array. one entry in the array for each violated  condition. General Error Entries in the errors Array An entry in the errors array contains the following information. this indicates the position of the field within the  composite. see “Entries for Conditional Validator  Errors in errorDetails Array” on page 117. For  a record. which  contains details about violated conditions. (Array).flatFile:convertToValues service to true. this indicates the position of  the field within the record. For information about  errorDetails entries. A brief description of the error.  For a composite. see “Validation  Error Codes” on page 120. The name of the element in the flat file schema that contained the  error. Variable in errors errorPosition Description Indicates where the error occurred within the parent element. this indicates the position of the record within the flat file. errorMessage errorCode reference badData childErrors Entries for Conditional Validator Errors in errorDetails Array The errorDetails array includes detail information about the conditions that were violated  when the following are true: When you set the validate and flag/detailedErrors input variables of the  pub. The value of the data that failed validation. For more information. See the table below the sample for more  information. Flat File Schema Developer’s Guide Version 7. see “Entries for Conditional Validator Errors in errorDetails Array”  on page 117.flatFile:convertToValues service encounters errors with conditional validator The following shows a sample of the errors array that includes the errorDetails array.  A number indicating the type of error. For a nested child record. For a list. –AND– The pub.A. Validation Errors service is set to true. Indicates that a field or subfield within the record or  composite generated a validation error.1 117 . flatFile:convertToValues  service generates the detail in errorDetails array described below. Validation Errors Example of Validation Results with Conditional Validation Errors 1 2 3 Portion of the array 1 Description For a description of this portion of the errors array.A. the pub.  When the flag/detailedErrors is true.  errors Flat File Schema Developer’s Guide Version 7.1 118 .flatFile:convertToValues service is set to false. see “General  Error Entries in the errors Array” on page 117. this is the only  information generated in the errors array about violated conditions. When the flag/detailedErrors input variable of the  pub. A. Validation Errors Portion of the array 2 Description To provide information about the conditions that were violated, the  convertToValues service generates an entry in the errorDetails array for  each violated condition. Variable in errorDetails errorPosition errorMessage errorCode reference badData condition errorDetails Description Always zero; the errorPosition is not meaningful at  this level of the errorDetails array. A brief description of the condition that was  violated. A number indicating the type of error. For a list,  see “Validation Error Codes” on page 120. Always null; the reference is not meaningful at this  level of the errorDetails array. Always null; the badData is not meaningful at this  level of the errorDetails array. The condition that was violated. Details about how the condition was violated. See  the description below. errorDetails 3 errorDetails The child errorDetails array contains detail about how the condition  was violated. The convertToValues service generates an entry for each  way the condition was violated. Variable in errorDetails errorPosition errorMessage errorCode reference badData Description Indicates the position in the record that contains  the field that caused the condition to be violated.  A brief description of the condition that was  violated. A number indicating the type of error. For a list,  see “Validation Error Codes” on page 120. The name of the element in the flat file schema that  contained the error. The value of the data that failed validation. Flat File Schema Developer’s Guide Version 7.1 119 A. Validation Errors Validation Error Codes The following table describes the validation error codes that you might receive when the  validate variable of the pub.flatFile:convertToValues service is set to true and you are validating  a flat file or testing a flat file schema. Error Code 1 Description In the flat file schema, the Mandatory drop‐down menu was set to true for  this element, but the element does not occur in the flat file. Reserved for future use. Unexpected element. This field is not allowed in the record or composite  in which it appears. In the flat file schema, a length validator was specified in the Validator  property for this field. The value in the flat file exceeded the maximum  length specified. In the flat file schema, a length validator was specified in the Validator  property for this field. The value in the flat file did not meet the minimum  length specified. Reserved for future use. In the flat file schema, a code list validator was specified in the Validator  property for this field. The value in the flat file was not listed in the flat file  schema as a valid value. Reserved for future use. Reserved for future use. In the flat file schema, a conditional validator was specified in the Validator  property for this composite or record. The contents of this composite or  record did not meet the conditional requirements. The errorMessage  variable contains the number of the condition that failed. If you had a  validation string of C010203R0405 and both conditions failed, the error  message would state that rules 0 and 1 were violated. If only the second is  violated, it states that the rule 1 was violated. If you require more detail about conditional validator errors, set the  flag/detailedErrors input variable of the pub.flatFile:convertToValues service to  true. For a description of the error details that convertToValues service  generates when you set flag/detailedErrors to true, see “Entries for  Conditional Validator Errors in errorDetails Array” on page 117. 2 3 4 5 6 7 8 9 10 Flat File Schema Developer’s Guide Version 7.1 120 A. Validation Errors Error Code 11 Description Indicates that this record is not defined anywhere in the flat file schema.  You will receive this error only when you have not specified a Default Record or selected Allow Undefined Data where this record appears in the flat  file. If you have specified either of these properties, you will not receive  this error. Indicates that this record is defined in this flat file schema, but it occurs in  the flat file in a location prohibited by the flat file schema. Reserved for future use. In the flat file schema, you specified a maximum repeat value in the Max Repeat property for a particular record. The number of record instances in  the flat file exceeded the specified maximum number of repeats. Reserved for future use. Within a record, this indicates that the record contains a composite or field  error. For a composite, this indicates the that composite contains a subfield  error. A string could not be formatted into the intended format. A format service  reported that the data could not be formatted properly. For information  about field format services, see “Format Services” on page 66 of Chapter 3,  “Creating and Editing Flat File Schemas and Dictionaries” of this guide. Indicates that a conditional validation rule requires a field, but that field is  not present in the data. Indicates that a field is excluded by a conditional validation rule, but the  field is present in the data. 12 13 14 15 16 17 18 19 Flat File Schema Developer’s Guide Version 7.1 121 Validation Errors Flat File Schema Developer’s Guide Version 7.1 122 .A. . . . . . . . . . . 127 Flat File Schema Developer’s Guide Version 7. . . 124 Stateful Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flat File Byte Count Parser Overview . . . . . . . . . . . . . . . . . . . . 124 Handling Partial Characters . .1 123 . . . . . . . . . . . . . . . . . . . . . .Appendix B. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A delimiter may be a single character.g. However. Flat File Schema Developer’s Guide Version 7. not characters. Important! Multi‐byte encoded files must run on JVM version 1. Partial characters are characters  that violate character boundary conditions. The parser still uses the String. Handling Partial Characters The parser reads and writes only complete characters. the byte count validator validates the total number of bytes in a  field. Both the convertToValues  and the convertToString services support byte‐count parsing for multi‐byte encodings. Thus.1 124 .  The field length validator.flatFile:convertToString” on page 90). In  addition. there is no functional difference  between parsing bytes and characters. Flat File Byte Count Parser Overview The flat file parser measures the lengths and positions of all records and fields in flat file  schemas in terms of bytes. COMP‐3  COBOL fields).B. Important! The parser does not support the writing or reading of binary data (e. Delimiter and  release character extractors still extract the specified character from the input file  based on a character position.. nor does it support multiple kinds of encodings within one file. Note: This change does not affect users who currently parse flat files using single‐byte  encodings because one byte equals one character. This parser supports both single‐byte encodings (equivalent to character encodings) and  multi‐byte encodings.length() method to validate field lengths (in  characters).  There is no change in the way in which the parser handles the following entities: Delimited fields and records. as described below. With multi‐byte encodings.5. a byte count can differ from a character  count since a single character can be encoded to multiple bytes. convertToString now includes an optional setting that returns a document as a byte  array instead of a string (see “pub.4 or later. Service Pack 2. but may not be byte based. the parser  measured all lengths and positions in characters. Prior to Version 6. Note: If the bytes that begin or end the record are  encoded to a valid character. consider the following multi‐byte encoding: 12121212 These eight bytes represent four two‐byte characters. 121 212 12 Flat File Schema Developer’s Guide Version 7. Record 2 contains one character. an  exception is thrown. and cannot be properly decoded. The  character formed by the third and fourth bytes is lost because these bytes span  Records 1 and 2. producing an undesirable result: Record 1: Record 2: Record 3: Note that: Record 1 contains one character.1 125 . Reading a fixed position field that  ends in the middle of a multi‐byte  character. The partial character is not included  in the field. formed by the seventh and eighth bytes. The last byte  is a partial character. To illustrate a case where the parser reads fixed position records that begin and end in the  middle of a multi‐byte character. the parser ignores it. If we specified a fixed length file  with a record length of three bytes instead of two bytes.B. Reading a fixed position record that  begins or ends in the middle of a  multi‐byte character. the parser would read this  encoding as follows.  The partial character is ignored. formed by the first two bytes of the file. How the Parser Handles the Condition The field starts on the next complete character. formed by the fifth and sixth bytes of the file. it will be the wrong  character. The field ends on the previous complete  character. Flat File Byte Count Parser Reading Partial Characters The following table describes how the parser reads partial characters: Character Boundary Condition Reading a fixed position field that  begins in the middle of a multi‐byte  character.  Record 3 contains one character. If the bytes encode to an invalid character.  For an example. and is replaced by one or more pad  characters. only complete characters are written to the output file. Writing to a fixed position field that  ends in the middle of a multi‐byte  character. but the string for that field encodes to more  than 10 bytes. the parser always truncates a string  on a character boundary. The field ends on the previous complete  character.B. The following table describes how the parser writes partial characters: Character Boundary Condition Writing a string to a fixed position  field where the string is longer than  the fixed position field (where it  breaks at a character boundary). Thus. Parsing the created file will likely result in  an encoding error. Does not generate an error during creation of the  file.  Keep this in mind when writing multi‐byte encodings to fixed length fields because it is  possible to specify a field or record that does not end on a character boundary. To illustrate a case where the parser writes to a fixed position field that ends in the middle  of a multi‐byte character. consider the following multi‐byte encoding: Number of Bytes in Field 4 4 Field Field1 Field2 Character 1 12 12 Character 2 12 345 The parser encodes this multi‐byte encoding as follows: Field Field1 Field2 Value 1212 12PP Flat File Schema Developer’s Guide Version 7. Flat File Byte Count Parser Writing Partial Character Encodings Partial characters present a similar problem when writing to a fixed length file. Writing to a fixed position field in  the middle of a delimited field that  contains a stateful encoding. see below. This  could result in the creation of invalid characters. the parser will truncate the byte array to fit into 10 bytes. This means that all encoding  information for a fixed position field is contained in the byte range specified for the field. In this case.1 126 . How the Parser Handles the Condition Truncates the string to fit the field. Consider a fixed length field that is 10 bytes. The partial character is not included  in the field. The parser  considers all fixed position fields to be “self contained”.  it considers character 1 and character 2 to be complete  characters. 3. B 4 8 The parser encodes this record as follows: |12O|45O  Flat File Schema Developer’s Guide Version 7. Stateful Encodings The parser can read any well‐formed document that adheres to the rules of the  document’s particular kind of encoding. and 5 because those three bytes would  extend beyond the end of the field.  The character “A” is represented by bytes 1 and 2.  The character “B” is represented by byte 3. It truncates bytes.1 127 . the parser considers character 2  to be a partial character.B. Note: Escape encodings behave similarly to stateful encodings. Stateful encodings have two specific bytes that indicate when the record’s state has  changed: | is a “shift‐in” byte that indicates a change from the normal state to an alternate state O (the character O. The parser truncates  characters preceding the escape sequence so that the integrity of the escape sequence is  maintained. Flat File Byte Count Parser The parser encodes Field1 properly. The parser encodes Field2 as follows: It considers character 1 to be a complete character Since byte 3 does not begin on a character boundary. 4. The parser can only write to files that have fixed  length fields or delimited records. Character value “C” encodes to 4 btyes: |45O. It replaces these three bytes with two pad  characters (represented by PP). not zero) is a “shift‐out” byte that indicates a change from the  alternate state to the normal state Writing Stateful Encodings Consider a record definition with the following four‐byte fields: Start Position 0 End Position 3 Field A Record Value Character value “AB” encodes to 5 bytes: |123O.   Thus. This truncation occurred on the character  boundary between the characters A and B. All fixed position fields must be  encoded as if they were a stand‐alone sequence of bytes. Note: A different method of encoding. In contrast.  The parser does not use this method of encoding. However. creating a properly encoded record. Using this method. Flat File Byte Count Parser Notice that the parser truncated byte 3 (the character “B”) from the first field so that the  field would fit within the four‐byte limit. extracting the value  for the second field produces: 45OP The parser cannot properly write this byte sequence.  delimited fields may carry stateful information from one field to the next field. No stateful encoding information  may be carried from one fixed position field to any other fixed position field. but delimited records are.  delimited records may not carry stateful information from one record to the next record. would have produced this  result: |12345OP where P is an added padding byte. to extend the record length to the required eight bytes. delimited fields are not necessarily “self contained”. using a “padding” byte.1 128 .B. Flat File Schema Developer’s Guide Version 7. . . 140 Flat File Schema Developer’s Guide Version 7. . . . 130 Creating Flat File Dictionary Entries. . . . . 140 Sample Flow Services for Working with XML Files . 134 Deleting Flat File Dictionary Entries. . . . . . . . . . . . . . . .Appendix C. . . . . . . . . and Schemas . . . Dictionaries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dictionaries. . . . . . . . . . . . . and Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Programmatically Creating Flat File Schemas and Dictionaries Overview . . . . . . . . . . . . . 130 Modifying Flat File Dictionary Entries. . . . . . . . . . and Schemas . . . . . . . . . . . . . . . . . . . . . . . Dictionaries. . . . . . . . . . . . . .1 129 . . . .  and delete: flat file dictionary entries entire flat file dictionaries flat file schemas To specify the data for the flat file dictionary entries. Dictionaries.generate  folder.generate:FFSchema IS document type. it should conform to the following XML schema:  IntegrationServer_directory\packages\WmFlatFile\pub\FFGeneration.flatFile.C.flatFile. convert the IData object  to an XML string. which is in the WmFlatFileSamples package.1 130 .  contains sample services that illustrate how to use the services in the pub.flatFile. Creating Flat File Dictionary Entries.flatFile. you  supply the data for the item you want to create. use the pub.xsd Create a service that maps the data to an IS document (IData object).flatFile.flatFile. Flat File Schema Developer’s Guide Version 7. which are described in “Flat File  Generation Sample Services” on page 111. and Schemas To create a flat file dictionary entry.  When creating the XML data.generate  folder to make the changes in the Integration Server namespace. The sample services are the sample.generateFFSchema:fixedLength service. For a flat file schema. then invoke the appropriate service to  create the item in the Integration Server namespace. or flat file  schemas. modify.generateFFSchema folder. entire flat file dictionaries. use the pub.generate folder to make the changes in the Integration Server namespace. entire flat file dictionary.generate folder of the WmFlatFile package to  programmatically create. Programmatically Creating Flat File Schemas and Dictionaries Overview You can use the services in the pub.flatFile.generateFFSchema:delimited service and the  sample. then invokes the appropriate services in the  pub. The sample. and then invoke the appropriate services in the pub.generate:FFDictionary IS  document type. The IS document  type to which the IData object must conform is provided in the WmFlatFile package: For a flat file dictionary entry or dictionary. you can: Create the information in an XML file and execute a service you create that retrieves the  XML data from the XML file.flatFile. or flat file schema.flatFile. flatFile.flatFile. For more information about the pub. For  more information. see “Creating a Service that Retrieves the  XML File” on page 140. When you invoke this  service: Set the encode input variable to true.flatFile.xsd 2 Retrieve the contents of the XML file as an XML string.generate:FFDictionary.flatFile. 3 Mapping Data 1 2 3 Create the entries in the Integration Server namespace by  invoking the pub.generate:updateFFDictionaryEntryFromXML  service. Programmatically Creating Flat File Schemas and Dictionaries Creating Flat File Dictionary Entries The following describes the basic steps to create flat file dictionary entries when using  either an XML file or mapping data: Using this method XML File Follow this procedure 1 Supply the data for the entries you want to create by creating  the XML file that contains the data and that conforms to the  XML schema: IntegrationServer_directory\packages\WmFlatFile\ pub\FFGeneration. Flat File Schema Developer’s Guide Version 7. Convert the IData object to an XML string by invoking the  pub. Set the documentTypeName input variable to  pub. see the webMethods Integration Server Built‐In Services  Reference.generate:FFDictionary IS  document type.1 131 .xml:documentToXMLString service.generate:updateFFDictionaryEntryFromXML  service. Map the data for the entries you want to create to an IData  object that conforms to the pub.C. Create the entries in the Integration Server namespace by  invoking the pub.xml:documentToXMLString  service. generate:saveXMLAsFFDictionary service throws an exception. When you invoke this  service: Set the encode input variable to true. This procedure describes how to create a flat file  dictionary that contains data.flatFile. Using this method XML File Follow this procedure 1 Supply the data that includes all entries for the dictionary you  want to create by creating an XML file that contains the data  and that conforms to the XML schema: IntegrationServer_directory\packages\WmFlatFile\ pub\FFGeneration. Map the data for all entries for the dictionary you want to  create to an IData object that conforms to the  pub. Important! The flat file dictionary you are creating must not already exist in the Integration  Server namespace.flatFile.generate:FFDictionary IS document type. For  more information. the  pub.xml:documentToXMLString service. see “Creating a Service that Retrieves the  XML File” on page 140. Flat File Schema Developer’s Guide Version 7.flatFile. If the flat file dictionary already exists. see  “Creating an Empty Flat File Dictionary” on page 133. If you want to create an empty flat file dictionary.xml:documentToXMLString  service. Set the documentTypeName input variable to  pub. 3 Mapping Data 1 2 3 Create the dictionary in the Integration Server namespace by  invoking the pub.generate:saveXMLAsFFDictionary service.C.1 132 .xsd 2 Retrieve the contents of the XML file as an XML string. Programmatically Creating Flat File Schemas and Dictionaries Creating an Entire Flat File Dictionary with Data The following describes the basic steps to create an entire flat file dictionary when using  either an XML file or mapping data.flatFile.generate:saveXMLAsFFDictionary service. see the webMethods Integration Server Built‐In Services  Reference. Convert the IData object to an XML string by invoking the  pub.flatFile. For more information about the pub. Create the dictionary in the Integration Server namespace by  invoking the pub.generate:FFDictionary. Using this method XML File Follow this procedure 1 Supply the data for the flat file schema you want to create by  creating an XML file that contains the data and that conforms  to the XML schema: IntegrationServer_directory\packages\WmFlatFile\ pub\FFGeneration. Follow this procedure 1 Create the empty dictionary in the Integration Server namespace by invoking the  pub.xsd 2 Retrieve the contents of the XML file as an XML string.C. Programmatically Creating Flat File Schemas and Dictionaries Creating an Empty Flat File Dictionary The following describes how to create an empty flat file dictionary. see “Creating a Service that Retrieves the  XML File” on page 140. Important! The flat file dictionary you are creating must not already exist in the Integration  Server namespace.generate:saveXMLASFFSchema service. If the flat file dictionary already exists. Creating a Flat File Schema The following describes the basic steps to create a flat file schema when using either an  XML file or mapping data: Important! The flat file schema you are creating must not already exist in the Integration  Server namespace.flatFile. the  pub. see “Creating an Entire Flat File Dictionary with  Data” on page 132.flatFile. For  more information. 3 Flat File Schema Developer’s Guide Version 7.generate:createFFDictionary service throws an exception. If the flat file schema already exists.flatFile.generate:saveXMLASFFSchema service throws an exception.generate:createFFDictionary service.1 133 . If you want to create a  flat file dictionary that contains data. the  pub.flatFile. Create the flat file schema in the Integration Server namespace  by invoking the pub. 1 134 . and Schemas This section describes how to modify an existing flat file dictionary entry.xml:documentToXMLString  service. You make your  modifications to the data. Programmatically Creating Flat File Schemas and Dictionaries Using this method Mapping Data Follow this procedure 1 Map the data for the flat file schema you want to create to an  IData object that conforms to the pub. Modifying an Existing Flat File Dictionary Entry To modify an existing flat file dictionary entry. entire flat file  dictionary. 2 Modifying Flat File Dictionary Entries.generate:FFSchema. see the webMethods Integration Server Built‐In Services  Reference.flatFile. 3 Create the dictionary in the Integration Server namespace by  invoking the pub. For more information about the pub.generate:saveXMLASFFSchema service. you first retrieve from the Integration  Server namespace the dictionary entry that you want to modify.flatFile. When you invoke this  service: Set the encode input variable to true. Dictionaries. or flat file schema. then invoke the appropriate service to write the changes back to  Flat File Schema Developer’s Guide Version 7. Convert the IData object to an XML string by invoking the  pub.flatFile.generate:FFSchema IS  document type.xml:documentToXMLString service.C. Set the documentTypeName input variable to  pub.   This creates an IData object that conforms to the  pub. The data is  returned as an XML string in the FFXML variable. 4 Mapping Data 1 2 3 Map data to the IData object to make your changes.flatFile.xml:XMLNodeToDocument service to convert the  XML node to an IData object.xml:xmlStringToXMLNode and  pub. The following describes the basic steps to modify a  dictionary entry either using an XML file or mapping data. Set the documentTypeName input variable to  pub.flatFile.1 135 .flatFile. For more information about the pub. Invoke the pub.xml:XMLNodeToDocument services.xml:xmlStringToXMLNode service to convert the  XML string to an XML node. For more information. Programmatically Creating Flat File Schemas and Dictionaries the Integration Server namespace. Retrieve the existing information for the dictionary entry from  the Integration Server namespace by invoking the  pub.flatFile. When you invoke this  service: Set the makeArrays input variable to false. Update the data for the dictionary entry in the XML file. see “Retrieving Namespace  Data to Write to an XML File” on page 141.generate:getFFDictionaryEntryAsXML service.generate:getFFDictionaryEntryAsXML service and write it to  an XML file. To convert the XML string in the FFXML variable to an IData  object: a b Invoke the pub. Update the dictionary entry in the Integration Server  namespace by invoking the  pub.generate:FFDictionary.C.flatFile.generate:updateFFDictionaryEntryFromXML service. For  more information. see the webMethods  Integration Server Built‐In Services Reference. The  XML file must conform to the XML schema: IntegrationServer_directory\packages\WmFlatFile\ pub\FFGeneration.  Using this method XML File Follow this procedure 1 Retrieve the existing information for the dictionary entry from  the Integration Server namespace by invoking the  pub.generate:FFDictionary IS document type. Flat File Schema Developer’s Guide Version 7.xsd 2 3 Retrieve the contents of the XML file as an XML string. see “Creating a Service that Retrieves the  XML File” on page 140. flatFile.generate:findDependants service and write it to an XML  file. 5 Update the dictionary entry in the Integration Server  namespace by invoking the  pub.flatFile. Set the documentTypeName input variable to  pub. you first retrieve from the Integration Server  namespace the item that you want to modify. For more information. For  more information. Create the flat file dictionary in the Integration Server  namespace again by invoking the  pub.generate:FFDictionary.xml:documentToXMLString service.generate:deleteFFDictionary service. Programmatically Creating Flat File Schemas and Dictionaries Using this method Follow this procedure 4 Convert the IData object to an XML string by invoking the  pub. You make your modifications to the data.  Delete the dictionary from the namespace before invoking the appropriate service to write  the changes back to the Integration Server namespace. 4 5 Flat File Schema Developer’s Guide Version 7.C. Modifying an Existing Flat File Dictionary To modify an existing flat file dictionary.1 136 . see “Creating a Service that Retrieves the  XML File” on page 140.generate:saveXMLAsFFDictionary service. Using this method XML File Follow this procedure 1 Retrieve the existing information for the flat file dictionary  from the Integration Server namespace by invoking the  pub. see “Retrieving Namespace Data to  Write to an XML File” on page 141. For more information about the pub.flatFile. When you invoke this  service: Set the encode input variable to true. see the webMethods Integration Server Built‐In Services  Reference. The  XML file must conform to the XML schema: IntegrationServer_directory\packages\WmFlatFile\ pub\FFGeneration.flatFile.generate:updateFFDictionaryEntryFromXML service. Delete the existing flat file dictionary from the Integration  Server namespace by invoking the  pub. Update the data for the flat file dictionary in the XML file.xml:documentToXMLString  service. The following describes the basic  steps to modify a flat file dictionary either using an XML file or mapping data.xsd 2 3 Retrieve the contents of the XML file as an XML string.flatFile. flatFile.flatFile. Set the documentTypeName input variable to  pub.generate:findDependants service. For more information about the pub. Programmatically Creating Flat File Schemas and Dictionaries Using this method Mapping Data Follow this procedure 1 Retrieve the existing information for the flat file dictionary  from the Integration Server namespace by invoking the  pub. see the webMethods  Integration Server Built‐In Services Reference.xml:XMLNodeToDocument services.xml:documentToXMLString  service.C.xml:xmlStringToXMLNode service to convert the  XML string to an XML node. 5 Delete the existing flat file dictionary from the Integration  Server namespace by invoking the  pub.xml:xmlStringToXMLNode and  pub. see the webMethods Integration Server Built‐In Services  Reference.flatFile.generate:FFDictionary IS document type.  This creates an IData object that conforms to the  pub.flatFile.flatFile. The data is returned as  an XML string in the FFXML variable. When you invoke this  service: Set the makeArrays input variable to false. When you invoke this  service: Set the encode input variable to true.generate:deleteFFDictionary service. For more information about the pub. 3 4 Map data to the IData object to make your changes. Set the documentTypeName input variable to  pub. Invoke the pub. Create the flat file dictionary in the Integration Server  namespace again by invoking the  pub.generate:FFDictionary. Convert the IData object to an XML string by invoking the  pub.xml:documentToXMLString service. To convert the XML string in the FFXML variable to an IData  object: a b Invoke the pub.1 137 .generate:FFDictionary. 2 6 Flat File Schema Developer’s Guide Version 7.xml:XMLNodeToDocument service to convert the  XML node to an IData object.generate:saveXMLAsFFDictionary service.flatFile. generate:getFFSchemaAsXML service and write it to an  XML file. Delete the existing flat file schema from the Integration Server  namespace by invoking the pub. see “Creating a Service that Retrieves the  XML File” on page 140. For more information.xsd 2 3 Retrieve the contents of the XML file as an XML string.C. see “Retrieving Namespace  Data to Write to an XML File” on page 141.generate:deleteFFSchema  service. Delete the item from the namespace before invoking the  appropriate service to write the changes back to the Integration Server namespace.flatFile. The  XML file must conform to the XML schema: IntegrationServer_directory\packages\WmFlatFile\ pub\FFGeneration.1 138 .flatFile. Update the data for the flat file schema in the XML file. You make your  modifications to the data. 4 5 Flat File Schema Developer’s Guide Version 7. For  more information. The  following describes the basic steps to modify a flat file schema either using an XML file or  mapping data.flatFile. Create the flat file schema in the Integration Server namespace  again by invoking the pub. Using this method XML File Follow this procedure 1 Retrieve the existing information for the flat file schema from  the Integration Server namespace by invoking the  pub. Programmatically Creating Flat File Schemas and Dictionaries Modifying an Existing Flat File Schema To modify an existing flat file dictionary or flat file schema.generate:saveXMLASFFSchema  service. you first retrieve from the  Integration Server namespace the item that you want to modify.  see the webMethods Integration Server Built‐In Services  Reference. To convert the XML string in the FFXML variable to an IData  object: a b Invoke the pub. Set the documentTypeName input variable to  pub. 2 6 Flat File Schema Developer’s Guide Version 7.generate:saveXMLASFFSchema  service.flatFile. For more information about the pub.C. Set the documentTypeName input variable to  pub.xml:XMLNodeToDocument services.xml:documentToXMLString service. 3 4 Map data to the IData object to make your changes.generate:getFFSchemaAsXML service.  This creates an IData object that conforms to the  pub.flatFile.generate:FFSchema IS document type.xml:xmlStringToXMLNode service to convert the  XML string to an XML node. Invoke the pub.flatFile.xml:xmlStringToXMLNode and  pub. Create the flat file schema in the Integration Server namespace  again by invoking the pub.generate:FFSchema.flatFile. When you invoke this  service: Set the makeArrays input variable to false. When you invoke this  service: Set the encode input variable to true. Convert the IData object to an XML string by invoking the  pub. For more information about the pub. 5 Delete the existing flat file schema from the Integration Server  namespace by invoking the pub.flatFile.xml:XMLNodeToDocument service to convert the  XML node to an IData object. Programmatically Creating Flat File Schemas and Dictionaries Using this method Mapping Data Follow this procedure 1 Retrieve the existing information for the flat file schema from  the Integration Server namespace by invoking the  pub.xml:documentToXMLString  service. The data is  returned as an XML string in the FFXML variable.generate:FFSchema. see the webMethods  Integration Server Built‐In Services Reference.1 139 .generate:deleteFFSchema  service.flatFile. file:getFile service to retrieve the XML file from the local file  system. see the webMethods Integration  Server Built‐In Services Reference. flat file dictionary entry entire flat file dictionary flat file schema Use this service to delete the item from the namespace pub. Sample code for retrieving data from an XML file 1 2 3 Flow Operation 1 Description Invoke the pub...C. Programmatically Creating Flat File Schemas and Dictionaries Deleting Flat File Dictionary Entries.generate:deleteFFDictionaryEntry pub.generate:deleteFFSchema Sample Flow Services for Working with XML Files This section shows sample flow services that show how to retrieve data from an XML file  in the local file system and how to retrieve data from the Integration Server namespace  that can be written to a file in the local file system. or flat file schema. The XML data must conform to the following XML schema:  IntegrationServer_directory\packages\WmFlatFile\pub\ FFGeneration. you  invoke the appropriate service.1 140 .xsd For more information about this service.flatFile.flatFile. Flat File Schema Developer’s Guide Version 7.flatFile. and Schemas To delete a flat file dictionary entry.  For this item. entire flat file dictionary.generate:deleteFFDictionary pub. Dictionaries. Creating a Service that Retrieves the XML File The following shows a sample flow service for retrieving data from an XML file. flatFile. With the INVOKE saveXMLAsFFSchema flow operation selected. the flow service invokes the  pub.string:bytesToString service to convert the file (in bytes format)  to a String. or  flat file schema. Invoke the appropriate service to make your changes to the Integration  Server namespace. In this sample.generate:saveXMLASFFSchema service.1 141 . see the webMethods  Integration Server Built‐In Services Reference. In this sample. 3 Retrieving Namespace Data to Write to an XML File The following shows a sample flow service that retrieves data from the Integration Server  namespace that can be written to an XML file.generate:saveXMLASFFSchema to save the XML data as a flat file  schema in the Integration Server namespace. For more information about this service. Flat File Schema Developer’s Guide Version 7.C. in the  pipeline.flatFile. Sample code for retrieving namespace data that can be written to an XML file 1 2 3 Flow Operation 1 Description Invoke the appropriate service to retrieve the Integration Server  namespace data for a flat file dictionary entry.string:bytesToString service to the  FFXML input of the pub. entire flat file dictionary. Programmatically Creating Flat File Schemas and Dictionaries Flow Operation 2 Description Invoke the pub. the flow service invokes the  pub.flatFile.generate:findDependants service to retrieve the data for an entire flat  file dictionary. map the output from the pub.  For more information about this service. in the pipeline.string:stringToBytes service to convert the namespace data (in  String format) to a byte[]. 3 Add code to or invoke a service that you create to write the byte[] to an  XML file. With the INVOKE stringToBytes flow operation selected.1 142 . Flat File Schema Developer’s Guide Version 7. Programmatically Creating Flat File Schemas and Dictionaries Flow Operation 2 Description Invoke the pub. map  the FFXML output from the pub.C.generate:findDependants service to the  input of the stringToBytes service.flatFile. see the  webMethods Integration Server Built‐In Services Reference. setting 73 alternate code sets.1 143 . managing dependencies on 72 flat file schemas programmatically 140 fomat services. managing dependencies on 67 delimited field extractors 11 delimited records 11 delimiter record parser defined 36 properties 39 delimiters.Index Index A access permissions. flat file 78 D default records 18 deleteFFDictionary service 99 deleteFFDictionaryEntry service 100 deleteFFSchema service 100 deleting flat file dictionaries entries programmatically 140 flat file dictionaries programmatically 140 flat file dictionaries. field 65 C character position field extractor 11 choosing services to receive flat files 79 code list validator 64 code sets. flat file 78 conventions used in this document 7 converting flat file to IS document (IData) 27 converting IS document (IData) to flat file 31 convertToString service 90 convertToValues service 93 createDocumentType service 98 createFFDictionary service 99 creating flat file dictionaries 69 adding entries programmatically 131 programmatically 132 programmatically creating empty dictionaries 133 when to create 19 creating flat file schemas 36 configuring the structure 48 adding element definitions 49 adding element references 49 record definition properties 55 programmatically 133 setting up flat file schemas 36 specifying properties 41 B byte count validator. specifying 37 Flat File Schema Developer’s Guide Version 7. enabling use of 74 alwaysSortFields variable 74 content type. alternate enabling use of 74 composite defined 10 extractors 61 reusing definitions 18 concepts flat file dictionaries 18 flat file schemas 12 flat files 10 flat files supported 11 overview 10 conditional validators 62 configuration file alwaysSortFields variable 74 customizing 74 enableFormatting variable 66 spacePadJustifies variable 76 useAlternateCodeSets variable 74 useReadableDelimiterReporting variable 75 configuring flat file schema structure 48 adding element definitions 49 adding element references 49 record definition properties 55 constraint types in flat file schemas 12 content handler. cnf configuration file alwaysSortFields variable 74 customizing 74 enableFormatting variable 66 spacePadJustifies variable 76 useAlternateCodeSets variable 74 useReadableDelimiterReporting variable 75 FFDictionary IS document type 107 FFSchema IS document type 109 field defined 10 extractors 61 reusing definitions 18 sorting 74 validators 64 findDependants service 101 findReferences service 101 fixed length record parser defined 36 properties 40 fixed length records 11 flat file dictionaries creating 69 creating empty dictionaries programmatically 133 creating entries programmatically 131 creating programmatically 132 defined 18 deleting entries programmatically 140 deleting programmatically 140 editing 72 Flat File Schema Editor 19 identifying 20 modifying entries programmatically 134 modifying programmatically 136 retrieving data for from XML file 140 setting access permissions 73 flat file dictionary entries. flat file creating empty dictionaries programmatically 133 creating programmatically 132 deleting programmatically 140 managing dependencies on 72 modifying programmatically 136 retrieving data for from XML file 140 dictionary entries.Index delimiters. retrieving data for from XML file 140 Flat File Schema Editor 19 Flat File Defintion tab 20 Flat File Structure tab 20 Properties panel 21 flat file schemas constraints content type 12 structural 12 syntax rule 12 creating 36 creating programmatically 133 defined 12 deleting programmatically 140 editing 72 Flat File Schema Editor 19 identifying 20 identifying records 14 modifying programmatically 138 retrieving data for from XML file 140 Flat File Schema Developer’s Guide Version 7. flat file creating programmatically 131 deleting programmatically 140 modifying programmatically 134 retrieving data for from XML file 140 documentation additional 8 conventions used 7 feedback 8 E EDI record parser 37 editing an existing flat file schema or dictionary 72 elements 10 reusing definitions 18 extractors 61 F ff. using readable and non-readable delimiters 75 diagrams flat file processing 24 inbound conversion and validation 26 outbound conversion 31 dictionaries.1 144 . record 15 identifying flat file schema records 14 identifying flat file schemas and dictionaries 20 inbound flat file processing 25 default records 18 diagram 26 how to 26 large files 30 mapping data 27 parsing 26 undefined data 16 validation error codes 12 validation error contents 12 IS documents (IData objects). 32 diagram 31 how to 31 parsing 31 G getFFDictionaryEntryAsXML service 102 getFFSchemaAsXML service 102 getSupportedEncodings service 98 Flat File Schema Developer’s Guide Version 7.1 145 . inbound parsing 44 examples of. requirements to receive flat files 79 format services 66 creating 66 disabling 66 error messages 66 managing dependencies on 67 processing 25 FormatService service 88 H handling large flat files 30 iterator variable of convertToValues service 94 I identifiers. field 64 listFFDictionaryEntries service 103 M mapping flat file data 27 modifying flat file dictionaries entries programmatically 134 flat file dictionaries programmatically 136 flat file schemas programmatically 138 O outbound flat file processing 31.Index setting access permissions 73 testing 68 validation 12 flat file user interface See Flat File schema Editor flat files creating from IS documents (IData objects) 31 defined 10 mapping 27 processing 24 sending and receiving 78 content handler 78 content type 78 services for receiving 79 via a flow service 79 via a string variable 79 via e-mail 84 via file polling 84 via FTP 81 via HTTP 80 via Trading Networks 78 services 88 types supported 11 floating records behavior of 43 examples of. creating from flat files 26 L large flat file handling 30 iterator variable of convertToValues service 94 length validator. outbound parsing 47 specifying in flat file schema 41 flow services. generate:deleteFFDictionaryEntry service 100 pub.generate:findDependants service 101 pub.flatFile.flatFile.flatFile. 32 diagram 31 how to 31 parsing 31 processing IS documents (IData) 27 program code conventions in this document 7 programmatically create empty flat file dictionaries 133 create flat file dictionaries 132 create flat file dictionary entries 131 create flat file schemas 133 delete flat file dictionaries 140 delete flat file dictionary entries 140 delete flat file schemas 140 modify flat file dictionaries 136 modify flat file dictionary entries 134 modify flat file schemas 138 properties of flat file schemas. defined 36 records.generate:getFFDictionaryEntryAsXML service 102 pub.flatFile.generate:listFFDictionaryEntries service 103 pub.generate:findReferences service 101 pub. specifying 41 pub.flatFile.flatFile:convertToString service 90 pub.generate:FFSchema IS document type 109 pub.flatFile.flatFile.flatFile.Index P parsers.flatFile:FormatService service 88 pub.flatFile.generate:saveXMLAsFFDictionary service 103 pub.generate:FFDictionary IS document type 107 pub.generate:deleteFFDictionary service 99 pub. outbound parsing 47 specifying in flat file schema 41 reusing element definitions 18 Flat File Schema Developer’s Guide Version 7.generate:saveXMLASFFSchema service 104 pub.generate:deleteFFSchema service 100 pub.flatFile.flatFile:getSupportedEncodings service 98 R record default 18 defined 10 identifying 14 reusing definitions 18 record identifiers 15 records with no identifiers 18 record parsers 14.generate:createFFDictionary service 99 pub. floating behavior of 43 examples of. inbound parsing 44 examples of.1 146 .generate:updateFFDictionaryEntryFromXML service 106 pub.flatFile:convertToValues service 93 pub.flatFile.generate:createDocumentType service 98 pub.generate:getFFSchemaAsXML service 102 pub.flatFile.flatFile.flatFile. 36 delimiter defined 36 properties 39 EDI 37 fixed length defined 36 properties 40 general properties 37 specifying delimiters 37 variable length.flatFile. record 14 parsing inbound flat files 26 outbound flat files 31 position field extractors 11 posting a flat file via HTTP 80 processing flat files 24 diagram 24 format services 25 inbound 25 default records 18 diagram 26 how to 26 large files 30 mapping data 27 parsing 26 undefined data 16 validation error codes 120 validation error contents 116 outbound 31. flat file creating programmatically 133 deleting programmatically 140 modifying programmatically 138 retrieving data for from XML file 140 sending and receiving flat files content handler 78 content type 78 overview 78 services for receiving 79 via a flow service 79 via a string variable 79 via e-mail 84 via file polling 84 via FTP 81 via Trading Networks 78 setting access permissions 73 setting up flat file schemas 36 sorting order of fields in composites and records 74 spacePadJustifies variable 76 submitting a flat file via a string variable 79 submitting a flat file via e-mail 84 submitting a flat file via file polling 84 submitting a flat file via FTP 81 submitting a flat file via HTTPsending and receiving flat files via HTTP 80 U undefined data 16 updateFFDictionaryEntryFromXML service 106 updating flat file dictionaries entries programmatically 134 flat file dictionaries programmatically 136 flat file schemas programmatically 138 useAlternateCodeSets variable 74 useReadableDelimiterReporting variable 75 V validation defined 12 error codes 120 error contents 116 validators 62 conditional 62 field 64 byte count 65 code list 64 length 64 variable length record parser. defined 36 variable length records 11 W WmFlatFile package contents 87 flat file services 88 X XML files.flatFile.generateFFSchema:fixedLength service 113 saveXMLAsFFDictionary service 103 saveXMLASFFSchema service 104 schemas. retrieving data from 140 T testing flat file schemas 68 Trading Networks.1 147 .flatFile.generateFFSchema:delimited service 111 sample.Index S sample. sending flat files to 78 troubleshooting information 8 typographical conventions in this document 7 Flat File Schema Developer’s Guide Version 7. Index Flat File Schema Developer’s Guide Version 7.1 148 .