structs in uniface

| STRUCTS IN UNIFACEDaniel IseliUniface CSS

Agenda

• The purpose of structs• Using structs• Best practices

The purpose of structs

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)

The purpose of structs

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

The purpose of structs

What is a struct?

• A Struct only exists:

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

parameter

1

Demo

The purpose of structs

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

The purpose of structs

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

The purpose of structs

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)

The purpose of structs

Struct Example

The purpose of structs

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.

The purpose of structs

Struct Variables

The purpose of structs

Struct Parameters

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

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

The purpose of structs

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

The purpose of structs

Struct Access Operators

• De-reference operator: -><name>

• Collection of members with specified name

The purpose of structs

Struct Access Operators

vBookStruct->chapter

vBookStruct->*vBookStruct->*

The purpose of structs

Struct Access Operators

• De-reference operator: ->*

• Special case: returns collection to all members

vBookStruct->*vBookStruct->c*

The purpose of structs

Struct Access Operators

• De-reference operator: ->*

• Special case: returns collection to all members

The purpose of structs

Struct Access Operators

vBookStruct->*

vBookStruct->chapter{2}

The purpose of structs

Struct Access Operators

• Struct index operator: {index}

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

The purpose of structs

Struct Access Operators

vBookStruct->chapter{2}

The purpose of structs

Proc for Manipulating Structs

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

• $equalStructRefs

The purpose of structs

Struct Functions

• $dbgString• $dbgStringPlain

• $collSize• $memberCount

• $isLeaf• $isScalar• $istags

The purpose of structs

Struct Functions

• $index

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

The purpose of structs

Setting Struct Functions

• Most functions only return information

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

The purpose of structs

Struct Annotations

• Descriptive data elements• Known as tags

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

The purpose of structs

Struct Annotations

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

• No specific position• Not counted / treated as members

The purpose of structs

Struct Annotations for Data Conversion

• Specific for complex data format

• componentToStruct / xmlToStruct:• Set annotations

• structToComponent / structToXml:• Use annotations for conversion process

The purpose of structs

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

The purpose of structs

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

The purpose of structs

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

The purpose of structs

Creating Structs (Explicitly)

• $newstruct

variablesstruct vStruct

endvariables

vStruct = $newstruct

The purpose of structs

variablesstruct vStruct

endvariables

vStruct = "My Book"

Creating Structs (Implicitly)

• Assigning value to a struct variable / parameter

The purpose of structs

variablesstruct vStruct

endvariables

vStruct->$name = "My Book"

Creating Structs (Implicitly)

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

The purpose of structs

variablesstruct vStruct

endvariables

xmlToStruct vStruct, "Book.xml"

Creating Structs (Implicitly)

• Proc conversion instruction:• xmlToStruct• componentToStruct

The purpose of structs

Deleting Structs

• No Proc command• Deleted when:

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

variablesstruct vStruct

endvariables

vStruct = ""

The purpose of structs

Deleting Structs

vStruct1 = ""

The purpose of structs

Deleting Structs

vStruct1 = ""

The purpose of structs

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 &amp; … </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

Best practicesStruct usage in the IDE10

Controller ViewView

View

Repository

Structured data exchange

managed using Structs

Best practicesStruct usage in the IDE10

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"

Best practicesWhat to avoid?

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

Best practicesWhat to avoid?

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

Best practicesWhat to avoid?

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)