structs in uniface

| STRUCTS IN UNIFACEDaniel IseliUniface CSS

Agenda

• The purpose of structs• Using structs• Best practices

The purpose of structs


What is a struct?

Tree-like data structure Manipulate complex data dynamically

Transform complex data: XML data Uniface component data JSON (coming soon)


What is a struct?

• Collection of data objects / nodes

• Organized hierarchically under single root node

• Struct member: node that has a parent node

• Nested Struct: member that is Struct


What is a struct?

• A Struct only exists:

• In memory• As long as referenced by struct variable /

parameter

1

Demo


Structs and Members

• Struct consists of:• One top node• 0-n sub-nodes (members)

• Each member can hold:• A scalar data value (e.g. number, string, or date)• Or another (nested) Struct


Structs and Members

• Struct / Struct member can have a name• Is case-sensitive• Can be an empty string

• Members can have the same name.

• Members are sequentially ordered


Struct Leaves

• Struct member that has:• No value• Or only single scalar value

• Adding member to leaf:• Changes to nested Struct• Value of former leaf held in nameless Struct

(scalar Struct)


Struct Example


Struct Variables

• Does not contain value• Contains 0-n references to nodes• Can contain multiple references to different nodes• Several variables can refer to one Struct node.


Struct Variables


Struct Parameters

• Structs can be passed as parameters:• By reference• By value

• Default behavior:• By reference: partner operations and entries• By value: public operations


Struct Parameters

• Behavior can be changed during declaration

• Limitation of by reference:• Only works with locals instances• Passing to remote instance will throw error

vBookStruct->chapter


Struct Access Operators

• De-reference operator: -><name>

• Collection of members with specified name



vBookStruct->chapter

vBookStruct->*vBookStruct->*



• De-reference operator: ->*

• Special case: returns collection to all members

vBookStruct->*vBookStruct->c*



• De-reference operator: ->*

• Special case: returns collection to all members



vBookStruct->*

vBookStruct->chapter{2}



• Struct index operator: {index}

• Reference to single member based on index position in collection of references



vBookStruct->chapter{2}


Proc for Manipulating Structs

• Struct data type• $newstruct• componentToStruct• structToComponent• xmlToStruct• structToXml

• $equalStructRefs


Struct Functions

• $dbgString• $dbgStringPlain

• $collSize• $memberCount

• $isLeaf• $isScalar• $istags


Struct Functions

• $index

• $name• $parent• $scalar• $tags


Setting Struct Functions

• Most functions only return information

• Functions that can change data:• $index• $parent• $tags


Struct Annotations

• Descriptive data elements• Known as tags

• Contain information to:• Correctly convert data to / from specific formats• Interpret data correctly


Struct Annotations

• Each node has special child• Node accessed using $tags

• No specific position• Not counted / treated as members


Struct Annotations for Data Conversion

• Specific for complex data format

• componentToStruct / xmlToStruct:• Set annotations

• structToComponent / structToXml:• Use annotations for conversion process


Struct Annotations for Data Conversion<?xml version='1.0' ?><!DOCTYPE UNIFACE PUBLIC "UNIFACE.DTD" "UNIFACE.DTD"><UNIFACE release="9.6" xmlengine="2.0"><TABLE>

[] [$tags] [xmlVersion] = 1.0 [xmlClass] = document [UNIFACE] [$tags] [xmlClass] = element [release] = "9.6" [$tags] [xmlClass] = attribute [xmlengine] = "2.0" [$tags] [xmlClass] = attribute [TABLE] [$tags] [xmlClass] = element

xmlToStruct


Struct Annotations for XMLTag Values

xmlClass documentelementattribute…

xmlNamespaceURI Value of the namespace string

xmlNamespaceAlias Value of the alias string

xmlVersion Value of the version attribute in the <?xml … ?> declaration

xmlEncoding Value of the encoding attribute in the <?xml … ?> declaration

xmlStandAlone Value of the standalone attribute in the <?xml … ?> declaration

xmlDataType Data type

xmlTypeNamespace Namespace of URI of a schema-defined data type


Struct Annotations for XMLTag Values

xmlTypeCategory simple complex

xmlAttrMode #IMPLIED#REQUIRED#FIXED

xmlPublicID Formal Public Id used to identify the DTD

xmlSystemID URI for the file containing the DTD

xmlNotation Name of notation declaration


Creating Structs (Explicitly)

• $newstruct

variablesstruct vStruct

endvariables

vStruct = $newstruct



endvariables

vStruct = "My Book"

Creating Structs (Implicitly)

• Assigning value to a struct variable / parameter



endvariables

vStruct->$name = "My Book"


• Assigning value to:• $name• $parent• $scalar• $tags



endvariables

xmlToStruct vStruct, "Book.xml"


• Proc conversion instruction:• xmlToStruct• componentToStruct


Deleting Structs

• No Proc command• Deleted when:

• not referenced by struct variable/parameter• not owned by another Struct


endvariables

vStruct = ""


Deleting Structs

vStruct1 = ""

Using structs

Using structsTransforming Complex Data Using Structs

struct data type enables dynamic transformations of complex data. For example:• XML from web services into component data structure• Component data into a nested XML data• Merge data from different components• Extract information from any type of complex data

Using structsStructs for XML Data

Basic Struct that represents XML data:

1. Top-level Struct for document

2. Named node with element name

3. Named with attribute name

4. Named leaf with element name

5. Named Struct with application name

Demo<?xml version="1.0"?><CATALOG> <CD> <TITLE>Empire Burlesque</TITLE> <ARTIST>Bob Dylan</ARTIST> <COUNTRY>USA</COUNTRY> <COMPANY>Columbia</COMPANY> <PRICE>10.90</PRICE> <YEAR>1985</YEAR> </CD></CATALOG>

<?xml version="1.0"?><CATALOG> <CD TITLE="Empire Burlesque"> <ARTIST>Bob Dylan</ARTIST> <COUNTRY>USA</COUNTRY> <COMPANY>Columbia</COMPANY> <YEAR>1985</YEAR> <PRICES> <PRICE CURRENCY="USD">10.90</PRICE> <PRICE CURRENCY="EUR">10.00</PRICE> <PRICE CURRENCY="GBP">8.50</PRICE> </PRICES> </CD></CATALOG>

Transform XML -> XML

2

Demo

Using structsStructs for Uniface Component Data

Struct that represents Uniface component data

1. Top-level Struct withcomponent name

2. Named nodes for entities

3. Fixed named node OCC

4. Named leaf with field name

5. Named nodes for inner entites

Demo

Transform CMP -> CMP

3

Demo

Using structsMusic City Web Service Example

• Calling Music City Web Service

• Returned XML Data converted to Struct• Struct transformed to match component structure• Struct loaded into component

<?xml version="1.0" encoding="UTF-8"?><ufnc:parameter xmlns:ufnc="urn:uniface:applic:complexparameter"> <ns0:artists xmlns:ns0="urn:uniface:applic:musiccityplex"> <ns0:artist> <ns0:artist_id>333</ns0:artist_id> <ns0:gid>703c7062-cc25-47e0-919e-ef740b88c725</ns0:gid> <ns0:name>Chris von Sneidern</ns0:name> <ns0:begin_date_year>0000</ns0:begin_date_year> <ns0:begin_date_month>00</ns0:begin_date_month> <ns0:begin_date_day>00</ns0:begin_date_day> <ns0:end_date_year>0</ns0:end_date_year> <ns0:end_date_month>0</ns0:end_date_month> <ns0:end_date_day>0</ns0:end_date_day> <ns0:type>Person</ns0:type> <ns0:gender/> <ns0:country> <ns0:code>US</ns0:code> <ns0:name>United States</ns0:name> </ns0:country> <ns0:comment/> <ns0:ipi_code/> <ns0:last_updated>2011-12-11T08:39:58.00</ns0:last_updated> <ns0:artist_credit_name> <ns0:position>0</ns0:position> <ns0:join_phrase>\\N</ns0:join_phrase> <ns0:artist_credit> <ns0:artist_count>1</ns0:artist_count> <ns0:ref_count>122</ns0:ref_count> <ns0:created>2012-02-14T14:17:01.00</ns0:created> <ns0:release_group> <ns0:type>Album</ns0:type> <ns0:comment/> <ns0:name>Sight & … </ns0:release_group>

Using structsMusic City Web Service Example

Transform XML -> CMP

4

Demo

Using structsxmlToStruct vs. xmlToStruct/schema

• xmlToStruct:• Uniface data type of all elements/attributes is string.

• xmlToStruct/schema:• Elements/attributes with predefined data types

included as scalar Structs of matching Uniface data types.

• Values are converted to Uniface format.

Using structsXML Schemas

• What is a schema?

• XML Schema is an XML-based alternative to DTD.• An XML schema describes the structure of an XML

document.• The XML Schema language is also referred to as XML

Schema Definition (XSD).

<!– parameter.xsd --><?xml version="1.0" encoding="UTF-8"?><xsd:schema elementFormDefault="qualified" targetNamespace="urn:uniface:applic:complexparameter" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ufnc="urn:uniface:applic:complexparameter"> <xsd:element name="parameter" type="ufnc:parameter" /> <xsd:complexType name="parameter"> <xsd:sequence> <xsd:any minOccurs="0" /> </xsd:sequence> </xsd:complexType></xsd:schema>

<!– musiccityplex.xsd --><?xml version="1.0" encoding="utf-8"?><xsd:schema elementFormDefault="qualified" targetNamespace="urn:uniface:applic:musiccityplex" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:mc="urn:uniface:applic:musiccityplex"> <xsd:element name="artists" type="mc:artists"/> <xsd:complexType name="artists"> <xsd:sequence> <xsd:element name="artist" type="mc:artist“ minOccurs="0" maxOccurs="unbounded" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="artist"> <xsd:sequence> <xsd:element name="artist_id" type="xsd:int"/> <xsd:element name="gid" type="xsd:string"/> <xsd:element name="name" type="xsd:string"/> <xsd:element name="begin_date_year" type="xsd:short" …/> … <xsd:element name="country" type="mc:country" …/> … <xsd:element name="last_updated" type="xsd:dateTime"/> … </xsd:sequence> </xsd:complexType>

Using structsMusic City Web Service Example (2)

• XSD Samples:

; Create Schema ListvSchemaList = ""vItems = ""putitem/id vItems, "NAMESPACE", %\ "urn:uniface:applic:complexparameter"putitem/id vItems, "LOCATION", "parameter.xsd"putitem vSchemaList, -1, vItemsvItems = ""putitem/id vItems, "NAMESPACE", %\ "urn:uniface:applic:musiccityplex"putitem/id vItems, "LOCATION", "musiccityplex.xsd"putitem vSchemaList, -1, vItems; xmltostruct/schemaxmltostruct/schema $Struct$, vXmlData, vSchemaList

Using structsMusic City Web Service Example (2)

• How to use:

5

Demo

Need more info?Go to:

Best practices

Best practicesStruct usage in the IDE10


Controller ViewView

View

Repository

Structured data exchange

managed using Structs


Some direct spin offs: More efficient use of Memory Performance improvements Consistency improvement Documentation improvements

A lot of improvements available in release 9.6.02

; Do

vStruct2 = vStruct->Node11->Node21vStruct2->Node31 = "A"vStruct2->Node32 = "B"vStruct2->Node33 = "C"vStruct2->Node33 = "D"

; Don’t

vStruct->Node11->Node21->Node31 = "A"vStruct->Node11->Node21->Node32 = "B"vStruct->Node11->Node21->Node33 = "C"vStruct->Node11->Node21->Node33 = "D"

Best practicesWhat to avoid?

Minimize loops through the Struct Minimize amount of Proc code in the deepest

branches

; Do

vStruct2 = vStruct->Node11->Node21vStruct2->Node31 = "A"vStruct2->Node32 = "B"vStruct2->Node33 = "C"vStruct2->Node33 = "D"


Minimize loops through the Struct Minimize amount of Proc code in the deepest

branches

; Do

N = vStruct->$collSizewhile (I <= N); ...

; Don’t

while (I <= vStruct->$collSize); ...


Use by reference wherever possible, instead of by value

Minimize usage of $collsize and $membercount

Adress Struct members with ->*{index} instead of -><name>{index} where possible

; Do

N = vStruct->$collSizewhile (I <= N); ...


Use by reference wherever possible, instead of by value

Minimize usage of $collsize and $membercount

Adress Struct members with ->*{index} instead of -><name>{index} where possible

Summary:

• Structs are used for manipulating complex data

• Structs can be used for transforming data sent to and received from web services

• Structs will play an increasingly important role in Uniface (e.g. Uniface 10)

structs in uniface

Technology