1. Knowledge Transfer: DataWindow XML Export/Import in PowerBuilder 9.0

2. John Strano
PowerBuilder Evangelist

3. 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

4. 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

5. 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

6. 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)

7. 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>

8. 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’

9. 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

10. 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

11. 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”

12. Mapping DataWindow to DOM Tree

13. 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

14. 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

15. Export/Import Template - XML View DataWindow Painter

16. 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

17. 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)

18. 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

19. Attributes Dialog

20. 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

21. 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

22. Grouped DataWindow: Grouping Elements in Template

23. Nested & Composite DataWindows: Referencing a Nested Report in Template

24. DataWindow Properties View

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

26. 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”

27. 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”

28. Runtime Template Enumeration Example

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

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

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

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

33. Example XMLDocument XML Document with external grammar references
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<output xmlns:xsi=" 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> …

34. 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)>

35. Example XMLSchema <?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="
<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>

36. Schema Options Dialog

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

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

39. 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”

40. 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”

41. 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”

42. 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

43. 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!

44. 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

45. 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

46. 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
Fran Whitney

47. 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

48. 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.

49. XML Template View

50. 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

51. 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> </zip_code>
<phone> </phone>
</employee_list_row>
</emp_list>

52. Example XML Template Import

53. XML Import Properties in the DW Painter

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

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

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

57. 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:
XSL-FO processors can render to PDF, etc.
Apache XML FOP Project
Check Software on left side of:

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

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

60. 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”

61. Processing XSL-FO to PDF using FOP

62. 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
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()

63. 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 }}})

64. 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!)

65. 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

66. 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

67. 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)

68. Q & A
John Strano
PowerBuilder Evangelist