knowledge transfer: datawindow xml export/import in powerbuilder 9.0

Knowledge Transfer: DataWindow XML Export/Import in PowerBuilder 9.0

13 - 2©2000 Sybase, Inc. and its subsidiaries. All rights reserved.

John Strano PowerBuilder Evangelist [email protected]


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 XMLExtensible 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 XML Names

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 ParsingDOM Parser DOM provides API access to XML tree model Useful if manipulating or re-traversing the documentSAX Parser Event-driven Useful if extracting data once in single traversalCore Interfaces Specified by W3C Extensions denoted by ‘DOM Level 2’, ‘DOM Level 3’


Industry-leading Parser ImplementationsJava 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.0Apache 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<?xml version=“1.0” encoding=“UTF-8”?>

<!DOCTYPE menu SYSTEM menu.dtd><menu>

<meal name=“breakfast”><food>Scrambled Eggs

</food><food>Hash Browns

</food><drink>Orange Juice

</drink></meal><meal name=“snack”>

<food>Chips

</food></meal>

</menu>

menu

meal

drinkfoodfoodname

“OrangeJuice”

“HashBrowns”

“ScrambledEggs”

“breakfast”

meal


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 2Detail 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 TemplateContains: 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 PowerScriptExport.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’ }”

Parameter Description

value (exp) Name of one of XML Templates previously saved in DW Painterfor this DW object


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”



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 PowerScriptExport.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 }”

Parameter Values Meaning

"Yes", TRUE, 1, exp Elements in Template Header section areiterated as group headers (Default)

value

"No", FALSE, 0, exp Groups are not distinguished


DataWindow Properties in PowerScriptExport.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 }”


"Yes", TRUE, 1, exp Whitespace is included in exported XMLdocument to beautify

value

"No", FALSE, 0, exp No extra whitespace included (Default)



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 }”

PowerBuilder Enumerated Value Numeric value Meaning

XMLNone! 0 Metadata not generated (Default)

XMLSchema! 1 XML Schema generated for XML document

XMLDTD! 2 DTD generated for XML document



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 }”

PowerBuilder Enumerated Value Numeric value Meaning

MetaDataInternal! 0 Metadata saved inside XML document(Default)

MetaDataExternal! 1 Metadata saved in an external file (.xsd or.dtd) with reference from the XML document


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> …<output>


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:complexType><xs:sequence>

<xs:element ref="dept_id"/><xs:element ref="dept_name"/><xs:element ref="dept_head_id"/>

</xs:sequence></xs:complexType>

</xs:element><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 DataDataWindow Painter

File…Save Rows As… menu itemSave as type: XML


Methods to Export XML DataSaveAs method

integer dwcontrol.SaveAs ( string filename,saveastype saveastype,boolean colheading )

SaveAsType

PowerBuilder Enumerated Value Numeric Value Meaning

XML! 15 XML



Data.XML

String containing DataWindow data exported in XML.PowerBuilder dot notation:

dw_control.Object.DataWindow.Data.XML

Describe argument:“DataWindow.Data.XML”



Data.XMLSchema

String containing XML Schema generated from Template.PowerBuilder dot notation:

dw_control.Object.DataWindow.Data.XMLSchema

Describe argument:“DataWindow.Data.XMLSchema”



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 Datalong dwcontrol.ImportFile ( { saveastype importtype, }

string filename {, long startrow {, long endrow {, longstartcolumn {, long endcolumn {, long dwstartcolumn }}}}} )

long dwcontrol.ImportString ( { saveastype importtype, }string string {, long startrow {, long endrow {, longstartcolumn {, long endcolumn {, long dwstartcolumn }}}}} )

long dwcontrol.ImportClipboard ( { saveastype importtype{, long startrow {, long endrow {, long startcolumn {, longendcolumn {, 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 ImportXML 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 4102 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

“Starts Detail” marker


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 PowerScriptImport.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’ }”


value (exp) Name of one of XML Templates previously saved in DW Painterfor this DW object


DataWindow Properties in PowerScriptImport.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’ }”


"Yes", TRUE, 1 Trace logging enabledvalue

"No", FALSE, 0 Trace logging disabled (Default)


DataWindow Properties in PowerScriptImport.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’ }”


value Path and name of trace output file


Generating DataWindow Presentationin 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 PresentationDataWindow Painter

File…Save Rows As… menu itemSave as type: XSL-FO


Methods to Export XML PresentationSaveAs method

integer dwcontrol.SaveAs ( string filename,saveastype saveastype,boolean colheading )

SaveAsType

PowerBuilder Enumerated Value Numeric Value Meaning

XSLFO! 16 XSL Formatting Objects



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 FunctionsNew 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_retstring ls_errll_ret = XMLParseFile(“c:\temp\mydoc.xml”, ls_err)If ll_ret <> 0 then

// do something, XMLParseFile returned errorEnd 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 StranoPowerBuilder [email protected]

knowledge transfer: datawindow xml export/import in powerbuilder 9.0

Documents