Knowledge Transfer: DataWindow XML Export/Import in PowerBuilder 9.0

John Strano PowerBuilder Evangelist StranoJ@Sybase.com

Module Objectives Review the basic concepts of XML Defining XML Templates in the DataWindow Painter New Properties to control exporting & importing DataWindow data in XML Enhanced methods for exporting & importing DataWindow data in XML Generating DataWindow presentation in XSL-FO PowerScript functions for XML document parsing/validation

Review of XML Extensible Markup Language Extends the ability to represent data Metadata language=tags & layout can be customized Data can be hierarchically structured with nesting Easily parsed across applications, platforms, enterprises, and Web for data interchange World Wide Web Consortium (W3C) XML 1.0 Recommendation at http://www.w3.org/TR/REC-xml

XML Document Well-Formed if structure follows XML syntax rules Contains one or more elements Element is a tree containing start-tag, content, end-tag Start-tag is a name, enclosed by angle brackets, with optional attributes Attribute names must be unique for element; order insignificant Attribute values must be quoted One root; all element tags properly nested Parsed element cannot contain recursive reference to itself Valid if structure conforms to a DTD or Schema DTD defines grammar for XML document Subset can be internal or external

XML Names and Entity References can only contain alphanumeric characters (also non-english, such as ä, ç etc.), _ Underscore, - Hyphen, . Period have to start with letter or underscore are case-sensitive Predefined entity references cannot occur within element text content and have to be replaced &lt replaces < (less-than sign) &gt replaces > (greater-than sign) &amp replaces & (ampersand) &quot replaces '' (double quote) &apos replaces ' (single quote)

XML Document Example <?xml version="1.0" encoding="UTF-8"?> <tag_name>  root element <tag_name2 attribute="female"> <name> <emp_fname>Fran</emp_fname>  text content <emp_lname>Whitney</emp_lname> </name> <empty_element></empty_element>  empty element <another_empty_element/>  alternative notation </tag_name2> </tag_name>

XML Parsing DOM Parser DOM provides API access to XML tree model Useful if manipulating or re-traversing the document SAX Parser Event-driven Useful if extracting data once in single traversal Core Interfaces Specified by W3C Extensions denoted by ‘DOM Level 2’, ‘DOM Level 3’

Industry-leading Parser Implementations Java Apache Xerces Java JDOM Higher level than DOM interface Native MSXML Apache Xerces-C++ Ports available on Win32, Solaris, HP-UX, AIX

XML Parsing in PowerBuilder 9.0 Apache Xerces-C++ Integration Integrated as internal ‘XML Service’ in PBXerces90.dll PB9 GA dependent on xerces-c_1_5_1.dll Post-PB9 likely dependent on xerces-c_2_1_0.dll Consumed by: DataWindow Painter DataWindow Engine Deploy with Pbdwe90.dll for DW XML apps PBVM If calling PowerScript XML parse/validation functions PBDom90.dll (PBDom90.pbd) More on this (PBDOM) presented in KT by Bio Liong Lim

XML Modeled by DOM Tree menu meal meal name food food drink <?xml version=“1.0” encoding=“UTF-8”?> <!DOCTYPE menu SYSTEM menu.dtd> <menu> <meal name=“breakfast”> <food> Scrambled Eggs </food> Hash Browns <drink> Orange Juice </drink> </meal> <meal name=“snack”> Chips </menu> menu meal meal name food food drink “breakfast” “Scrambled Eggs” “Hash Browns” “Orange Juice”

Mapping DataWindow to DOM Tree

DataWindow Export/Import Template Defines the mapping between values from a DataWindow and locations in an external document format, like XML References can be: DataWindow control values (text) Column Computed column Text control Computed field Nested report DataWindow Expressions (evaluated at runtime) Data source column

DataWindow Export/Import Template References in Template are specific to a DW namespace Template persists within DW definition in PBL & SRD as a dependent object Multiple Templates may be defined & saved for a DW Each must be uniquely named within a DW namespace Template applied at runtime or in Painter by name with the new DW property UseTemplate Used for DW data export, data import, or both

Export/Import Template - XML View DataWindow Painter

Other Items in an XML Template XML declaration Document Type declaration Root element (required) Child elements (any level of nesting) Attributes Literal text Comments Processing instructions CDATA sections

XML Template Divided in 2 Header Section Optionally contains: XML declaration (dialog) Document type declaration (dialog) Comments (dialog) Processing instructions (dialog) Root element (required) Child elements (non-iterative) Group Header elements* (iterative) Child elements (iterative)

XML Template Divided in 2 Detail Section Iterated for each row; can contain: Detail (Row) Start element* Child or sibling elements to the Detail Start element Content and Attribute values (dialog) DataWindow control references (dialog) Drag-drop from the Control List View DataWindow Expressions (dialog) Drag-drop from the Column Specification View Literal text Comments, PIs, and CDATA sections

Attributes Dialog

View Features Item-specific context menus, label-editing & dialogs Header/Detail marked by line across TreeView Drag-and-drop from Control List View and Column Specification View View-level menu New New Default Open (dialog) Save, SaveAs (dialog) Delete

Default Template Contains: XML declaration Root element (defaults to DataWindow name) Detail Start element (defaults to DW name + “_row”) Child elements of the Detail Start element named for each DataWindow column with content reference Useful as starting point Same structure assumed for XML export or import in Painter or at runtime if no UseTemplate specified

Grouped DataWindow: Grouping Elements in Template

Nested & Composite DataWindows: Referencing a Nested Report in Template

DataWindow Properties View

DataWindow Properties in PowerScript Export.XML.UseTemplate Controls logical structure & mapping of XML data exported by DataWindow. PowerBuilder dot notation: dw_control.Object.DataWindow.Export.XML.UseTemplate Describe and Modify argument: “DataWindow.Export.XML.UseTemplate { = ‘value’ }”

DataWindow Properties in PowerScript Export.XML.TemplateCount Returns number of Templates saved for DataWindow. PowerBuilder dot notation: dw_control.Object.DataWindow.Export.XML.TemplateCount Describe argument: “DataWindow.Export.XML.TemplateCount”

DataWindow Properties in PowerScript Export.XML.Template[1..n].Name Returns name of Template by array index (storage order). PowerBuilder dot notation: dw_control.Object.DataWindow.Export.XML.Template[1..n].Name Describe argument: “DataWindow.Export.XML.Template[” + n + “].Name”

Runtime Template Enumeration Example

DataWindow Properties in PowerScript Export.XML.HeadGroups Controls iteration of elements in Template Header section as group headers. PowerBuilder dot notation: dw_control.Object.DataWindow.Export.XML.HeadGroups Describe and Modify argument: “DataWindow.Export.XML.HeadGroups { = value }”

DataWindow Properties in PowerScript Export.XML.IncludeWhitespace Controls formatting of exported XML document by including whitespace to beautify. PowerBuilder dot notation: dw_control.Object.DataWindow.Export.XML.IncludeWhitespace Describe and Modify argument: “DataWindow.Export.XML.IncludeWhitespace { = value }”

DataWindow Properties in PowerScript Export.XML.MetaDataType Controls type of metadata to accompany exported XML. PowerBuilder dot notation: dw_control.Object.DataWindow.Export.XML.MetaDataType Describe and Modify argument: “DataWindow.Export.XML.MetaDataType { = value }”

DataWindow Properties in PowerScript Export.XML.SaveMetaData Controls location of generated metadata. PowerBuilder dot notation: dw_control.Object.DataWindow.Export.XML.SaveMetaData Describe and Modify argument: “DataWindow.Export.XML.SaveMetaData { = value }”

Example XMLDocument XML Document with external grammar references <?xml version="1.0" encoding="UTF-8" standalone="no"?> <output xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="output.xsd"> - or - <!DOCTYPE output SYSTEM "output.dtd"> <output> <output_row> <dept_id>100</dept_id> <dept_name>R & D</dept_name> <dept_head_id>501</dept_head_id> </output_row> …

Example DTD <?xml version="1.0" encoding="UTF-8"?> <!ELEMENT output (output_row*)> <!ELEMENT output_row (dept_id, dept_name, dept_head_id)> <!ELEMENT dept_id (#PCDATA)> <!ELEMENT dept_name (#PCDATA)> <!ELEMENT dept_head_id (#PCDATA)>

Example XMLSchema <?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="output"> <xs:complexType> <xs:sequence> <xs:element ref="output_row" maxOccurs="unbounded" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="output_row"> <xs:element ref="dept_id"/> <xs:element ref="dept_name"/> <xs:element ref="dept_head_id"/> <xs:element name="dept_id" type="xs:int"/> <xs:element name="dept_name" type="xs:string"/> <xs:element name="dept_head_id" type="xs:int" nillable="true"/> </xs:schema>

Schema Options Dialog

Methods to Export XML Data DataWindow Painter File…Save Rows As… menu item Save as type: XML

Methods to Export XML Data SaveAs method integer dwcontrol.SaveAs ( string filename, saveastype saveastype, boolean colheading ) SaveAsType

DataWindow Properties in PowerScript Data.XML String containing DataWindow data exported in XML. PowerBuilder dot notation: dw_control.Object.DataWindow.Data.XML Describe argument: “DataWindow.Data.XML”

DataWindow Properties in PowerScript Data.XMLSchema String containing XML Schema generated from Template. PowerBuilder dot notation: dw_control.Object.DataWindow.Data.XMLSchema Describe argument: “DataWindow.Data.XMLSchema”

DataWindow Properties in PowerScript Data.XMLDTD String containing DTD generated from Template. PowerBuilder dot notation: dw_control.Object.DataWindow.Data.XMLDTD Describe argument: “DataWindow.Data.XMLDTD”

Importing XML Data into DataWindow Analogous to XML export DataWindow Import methods enhanced XML Default Import Assumes coincident column data in XML document XML Template Import Piggybacks off same XML Template as for export to interpret logical structure and DataWindow mapping of XML document to import Internally uses SAX parser for performance

Methods to Import XML Data long dwcontrol.ImportFile ( { saveastype importtype, } string filename {, long startrow {, long endrow {, long startcolumn {, long endcolumn {, long dwstartcolumn }}}}} ) long dwcontrol.ImportString ( { saveastype importtype, } string string {, long startrow {, long endrow {, long long dwcontrol.ImportClipboard ( { saveastype importtype {, long startrow {, long endrow {, long startcolumn {, long endcolumn {, long dwstartcolumn }}}}}} ) Example: dw_1.ImportFile( XML!, "c:\temp\customers.xml") Possible SaveAsTypes for import are XML!, CSV! and TXT!

DataWindow XML Default Import Import without Import.XML.UseTemplate specified XML document data (element text content) has to correspond to DataWindow column definition XML element text content is imported in order of occurrence within XML document Element tag names and all other content of the XML document are ignored XML nesting within the document is disregarded

Empty Elements in XML Default Import Empty elements are assumed to be empty values and imported as such into the DataWindow column An element that contains only space, carriage return, new line or tab characters is treated as an empty element An element that contains no text content, but any other content, e.g. a child element or comment, it is not regarded as an empty element and will be skipped for import

Example XML Default Import XML Document: <?xml version="1.0" encoding="UTF-8"?> <employee_list> <employee dept_id="100"> <emp_id>102</emp_id> <manager></manager>  empty element <name> <emp_fname>Fran</emp_fname> <emp_lname>Whitney</emp_lname> </name> </employee> </employee_list> Column Import into DataWindow: Column 1 Column 2 Column 3 Column 4 102 Fran Whitney

Advantages of XML Template Import XML document structure doesn’t have to match DataWindow columns Order of elements within XML doesn’t have to reflect DataWindow column order Attribute values can be imported

DataWindow XML Template Import Import Template needs to be created in DataWindow painter XML Template View Template for export may be reused for import Import.XML.UseTemplate property needs to be set in DataWindow painter or programmatically NOTE: Nested DataWindow XML export supported via SaveAs() per TeamSybase request. But, like other import formats XML import does not currently support importing nested output.

XML Template View

XML Import Template Defines mappings between XML element and attribute names of the XML document and DataWindow column names Reflects nesting level where element and/or attribute import items can be located within the XML document If “Starts Detail” marker exists, element and attribute contents above this marker line are ignored If “Starts Detail” marker does not exist, all element and attribute mappings within the template are used for import Other information within the Template (controls, comments, etc.) is ignored

Example XML Document... <?xml version="1.0" encoding="UTF-8" standalone="no"?> <emp_list> <employee_list_row> <emp_id>102</emp_id> <emp_fname>Fran</emp_fname> <emp_lname>Whitney</emp_lname> <street>49 East Washington Street</street> <city>Needham</city> <state>MA</state> <zip_code>02192 </zip_code> <phone>6175553985</phone> </employee_list_row> </emp_list>

Example XML Template Import

XML Import Properties in the DW Painter

DataWindow Properties in PowerScript Import.XML.UseTemplate Controls logical structure & mapping of XML data imported by DataWindow. PowerBuilder dot notation: dw_control.Object.DataWindow.Import.XML.UseTemplate Describe and Modify argument: “DataWindow.Import.XML.UseTemplate { = ‘value’ }”

DataWindow Properties in PowerScript Import.XML.Trace Enables trace logging during DataWindow XML import. PowerBuilder dot notation: dw_control.Object.DataWindow.Import.XML.Trace Describe and Modify argument: “DataWindow.Import.XML.Trace { = ‘value’ }”

DataWindow Properties in PowerScript Import.XML.TraceFile Specifies name of file for DataWindow XML import trace logging. PowerBuilder dot notation: dw_control.Object.DataWindow.Import.XML.TraceFile Describe and Modify argument: “DataWindow.Import.XML.TraceFile { = ‘value’ }”

Generating DataWindow Presentation in XML: XSL-FO XSL Formatting Objects Part 2 of XSL W3C Recommendation covering presentation or formatting of XML XSL 1.0 (aka XSL-FO) Recommendation at: http://www.w3.org/TR/xsl/slice6.html#fo-section XSL-FO processors can render to PDF, etc. Apache XML FOP Project http://xml.apache.org/fop Check Software on left side of: http://www.w3.org/Style/XSL

Methods to Export XML Presentation DataWindow Painter File…Save Rows As… menu item Save as type: XSL-FO

Methods to Export XML Presentation SaveAs method integer dwcontrol.SaveAs ( string filename, saveastype saveastype, boolean colheading ) SaveAsType

DataWindow Properties in PowerScript Data.XSLFO String containing DataWindow data & presentation in XSL Formatting Objects PowerBuilder dot notation: dw_control.Object.DataWindow.Data.XSLFO Describe argument: “DataWindow.Data.XSLFO”

Processing XSL-FO to PDF using FOP

PowerScript XML Parsing/Validation Parsing/validation of XML document in PowerScript can determine whether XML document is wellformed complies to W3C XML specification can determine whether XML document is valid also matches a given grammar (DTD or XMLSchema) uses Apache Xerces SAX http://xml.apache.org/xerces-c/index.html needs PBXerces90.dll and Xerces-C_1_5_1.dll in the path NOTE: The Apache Xerces parser does not support parsing internal XMLSchema (MS format) although this can be generated with SaveAs()

XML Parsing/Validation Functions New PowerScript system functions: XMLParseFile long = XMLParseFile(string xmlfilename {,valscheme validationscheme } {,string parsingerrors } {,boolean namespaceprocessing {,boolean schemaprocessing {,boolean schemafullchecking }}}) XMLParseString long = XMLParseString(string xmlstring {,valscheme validationscheme } {,string parsingerrors } {,boolean namespaceprocessing {,boolean schemaprocessing {,boolean schemafullchecking }}})

Validation Scheme ValScheme – new PowerBuilder enumerated value ValNever! Only check for wellformedness ValAlways! Validate the XML document. If no DTD or XMLSchema exists the parse check will give an error ValAuto! If DTD or XMLSchema exists validate the XML document, otherwise check for wellformedness only Example, checking XML file for wellformedness only: XMLParseFile(“c:\temp\mydoc.xml”, ValNever!)

Suppressing Error Messages To suppress the error message box when the parser detects errors supply the optional argument string parsingerrors Example: long ll_ret string ls_err ll_ret = XMLParseFile(“c:\temp\mydoc.xml”, ls_err) If ll_ret <> 0 then // do something, XMLParseFile returned error End if

Further Grammar Parsing Arguments namespaceprocessing (defaults to FALSE) If TRUE, the parser enforces the rules defined by the name space specification If the validationscheme is set to ValAlways or ValAuto, then the document must contain a grammar that supports name spaces schemaprocessing (defaults to FALSE) If TRUE, the parser will process XMLSchema namespaceprocessing must also be turned on schemafullchecking (defaults to FALSE) If TRUE the schema grammar itself is checked for additional errors Only takes effect if schemaprocessing is set to TRUE

More Parsing/Validation Examples If external XMLSchema is referenced the document will be validated, otherwise the parser will check for wellformedness: XMLParseFile(“c:\temp\mydoc.xml”, TRUE, TRUE) Parses XML document string, validates against a referenced XMLSchema (has to exist), saves any possible errors in a string variable (suppresses message boxes on error): XMLParseString(s_myXMLstring, ValAlways!, ls_err, TRUE, TRUE) Parses XML document, validates against a referenced XMLSchema (has to exist) – also parses Schema itself for additional errors: XMLParseFile(“c:\temp\mydoc.xml”, ValAlways!, TRUE TRUE,TRUE)

Q & A John Strano PowerBuilder Evangelist StranoJ@Sybase.com