Fact Sheet: UNIFACE V7.2.06 - Three-tier inter-component communication

[back to index]

Description of functionality

UNIFACE V7.2.06 delivers strong support for three-tier development by adding a group of new tools, Proc statements, functions, and an XML stream data type.

This fact sheet describes the following topics:

1. Three tier development
2. Loosely coupled connections
3. Using the DTD Editor
   1. Starting the DTD Editor
   2. Compiling a DTD
   3. Generating a DTD from a component's structure
   4. Generating a DTD from an entity
   5. Defining relationships in an XML stream
   6. Defining additional DTD properties
4. Changes to the Repository
5. New command line switches
   1. /dtd
6. Changed Proc statements
   1. params
   2. variables
   3. validate
7. New Proc statements
   1. xmlload
   2. xmlsave
   3. retrieve/reconnect
8. New Proc functions
   1. $occcrc
   2. $occproperties
   3. $occstatus
9. DTD mapping lists
10. Sample code
11. Known limitations
12. Known bugs

1. Three-tier development

Three-tier development is a multitiered architecture, where components are placed into the following layers:

• Data access tier this includes all components handling access to persistent data sources
• Business tier this includes all components handling business logic
• Presentation tier this includes all components handling the user interface of the application

Each layer is specialized, so components only carry out the functions of one of the layers. This requirement is already supported by the specialized UNIFACE component types, including services, forms, and UNIFACE Server Pages.

In layered architectures it is a good programming practice to have loosely coupled connections between components. The internal structure of a component must be clearly separated from the component signature.

UNIFACE V7.2.06 adds support for loosely coupled connections to the existing support for specialized components to deliver comprehensive support for three-tier development.

2. Loosely coupled connections

UNIFACE V7.2.06 enables loosely coupled connections between components by using XML streams to pass data between components as disconnected record sets (record sets that do not maintain state with their data source are disconnected). The XML format is used because the XML standard enables interchange of data in a structured and self-describing text-based format. Components can generate XML streams using xmlsave, a new Proc statement. XML streams can be loaded into component fields using xmlload (also new).

The XML stream structure is described by Document Type Definitions (DTDs), which are stored in the .urr file (for UNIFACE components) or included in the XML stream itself (for non-UNIFACE components). DTDs are defined in the XML standard.

Differences in field and entity names painted on components on different tiers are handled by a mapping system, which can be defined at application model level, or in Proc code on components.

UNIFACE places field data in elements as string data. Meta data, such as state information and validation error information, is placed in the attributes of elements representing fields and entities. This information is used to reconnect the XML stream data to the database. The attributes used by UNIFACE are:

• status the status of an occurrence, which can be one of the following values:
  • "est" The occurrence exists in the database
  • "new" The occurrence is new, that is, it does not exist in the database
  • "del" The occurrence is marked for deletion
• id a unique identifier (primary key) for the occurrence
• crc a cyclical redundancy checksum (CRC) based on the field values at the time the occurrence was saved into an XML stream. When the XML stream is reconnected to the database, the CRC value is recalculated and compared with the CRC value in the XML stream. The CRC values must match or the occurrence is not reconnected. This results in behavior identical to optimistic locking.
• valerr if a data validation error occurred while reconnecting data from an XML stream to a database, the validation errors can be written to an XML stream sent back to the calling component. The valerr attribute fires the appropriate field or occurrence-level On Error trigger when the XML stream is loaded by a component.

In addition to these attributes, UNIFACE also supports attributes defined as FIXED in a DTD (that is, attributes that allow only a single value). FIXED attributes are useful for declaring name spaces for element names.

3. Using the DTD Editor

UNIFACE now features a DTD Editor that allows users to create and modify DTDs within the Development Environment.

The DTD Editor has the following ways of displaying DTDs:

• a Text View, which shows the DTD in its native text format
• a Tree View, which shows the DTD in a logical tree structure

3.1 Starting the DTD Editor

To start the DTD Editor, do the following:

1. Start the UNIFACE Model Editor.
2. Select an application model.
3. Click Go To >DTDs.
4. Select a DTD or enter the name of a new DTD.
5. Click OK.

3.2 Compiling DTDs

To compile a DTD, do the following:

1. Open the DTD in the DTD Editor, as described in Starting the DTD Editor.
2. Select File >Compile.

You can also compile DTDs from the command line, using the new /dtd command line switch.

3.3 Generating DTDs from a component's structure

To generate a DTD from a component's painted structure of entities and fields, do the following:

1. Start the DTD Editor.
2. Create a new DTD, or open an existing DTD.
3. Select Edit—>Load Component Structure.
4. Select the component from the list, and click OK.

This generates a DTD that defines an XML stream with a structure corresponding to the field and entity structure from the component.

Generating a DTD from the component's structure overwrites all declarations already stored in the DTD.

Note: Ensure that you have painted all relevant fields on the component, because fields that are not painted on the component are not added to the DTD.

3.4 Generating DTDs from entities

To generate a DTD from entities defined in your application model, do the following:

1. Start the DTD Editor.
2. Create a new DTD, or open an existing DTD.
3. Click Wizard. This displays the DTD Wizard.
4. Select the root element of the tree, or select an entity element.
5. Right-click, and select Insert Entity from the popup menu.
6. Select an entity from the list.
7. Click OK.
8. Add fields to the entity by selecting Load Fields from the popup menu. Select the fields you need from the list and click OK.
9. Add attributes to the elements you have generated by selecting the elements and selecting Select Attributes from the popup menu.
10. Compile the DTD.

This generates a DTD that defines a structure corresponding to the entity selected in steps 5, 6, and 7.

3.5 Defining relationships in XML streams

Entities are represented as elements in XML, and inner entities are represented as elements nested within the start and end tags of the outer entity.

To define inner-outer entity relationships in an XML stream, do one of the following:

• Create a component with the relationships painted using frames-within-frames. Generate the DTD from the component structure, as described in Generating a DTD from a component's structure.
• Load the inner entities using the Tree View, as described in Generating a DTD from an application model.

3.6 Defining additional DTD properties

To go to the Define DTD Properties form, click Properties on the Define DTD form.

The following properties can be defined on the Define DTD Properties form:

• Description is a short description of the DTD and its purpose
• File Name is the name of the DTD file created during compilation of the DTD
• External Reference is a URI reference to the DTD. An XML stream can use this reference to locate the DTD
• Comment is additional information about the DTD
• Default Mapping is the default mapping between elements defined in the DTD and fields and entities on a UNIFACE component

External Reference and File Name are properties that support 3GL components, by providing alternative ways of supplying the DTD to a component. These properties are not required, and are ignored by UNIFACE components.

4. Changes to the Repository

A new Repository entity has beenadded to the DICT model:

• Table name UCDTYP.DICT
• Fields:
  • UTIMESTAMP last modification
  • UDTDNAME Short name of DTD
  • UMODELNAME Application model name
  • UDESCR Description
  • UTYPE Reserved for future use
  • USTATE Reserved for future use
  • UDTDFILE Name of DTD file created during compilation
  • UDEFMAP Default mapping of elements to fields and entities
  • UEXTREF URI reference to DTD
  • UCOMMENT comments
  • UDEFINITION DTD data

5. New command line switches

5.1 /dtd

Compile all DTD objects in the Repository.

Compilation of DTD objects updates the URR file. If a DTD specifies a file name in its properties, compilation of that DTD also creates a text file for that DTD.

6. Changed Proc statements

6.1 params

The params statement now allows xmlstream parameters:

params

xmlstream [DTD:DTDname] XMLparam : IN | OUT| INOUT

endparams

Where:

• DTD: specifies that the XML stream is defined using a DTD (this is to ensure compatibility with future developments in the XML standard)
• DTDname is the DTD used to validate the XML stream
• XMLparam is the XML parameter name that contains the XML stream

XML stream parameters are exposed as string parameters in the Signature Editor.

DTDname is a literal string or constant using the following format:

"Name.Model"

Where:

• Name is the name of the DTD as specified in the application model
• Model is the name of the DTD's application model

6.2 variables

The variables statement now allows xmlstream variables:

variables

xmlstream [DTD:DTDname] XMLvariable

endvariables

Where:

• DTD: specifies that the XML stream is defined using a DTD (this is to ensure compatibility with future developments in the XML standard)
• DTDname is the DTD used to validate the XML stream
• XMLvariable is the XML variable name that contains the XML stream

xmlstream variables can be manipulated using UNIFACE string-handling Proc.

DTDname is a literal string, variable, or constant using the following format:

"Name.Model"

Where:

• Name is the name of the DTD as specified in the application model
• Model is the name of the DTD's application model

6.3 validate

The validation process, and the behavior of the validate statement, is altered in V7.2.06. The validation process has been changed to be consistent on all UNIFACE component types.

validate validates all occurrences specified by the statement's arguments and switches. The validation process does not stop at the first validation error. Instead, all validation errors are identified, with On Error triggers fired for each error. At the end of the validation process, $procerror, $dataerrorcontext and $procerrorcontext are set to the values returned by the first validation error.

This validation process occurs identically on UNIFACE Server Pages, forms, services, reports and object services.

The syntax of the validate statement is unchanged.

7. New Proc statements

7.1 xmlload

Load data from an XML stream into occurrences painted on the component.

xmlload{/incldefmap} XMLvariable, DTDname{, DTDmapping}

Where:

• incldefmap instructs xmlload to use the default DTD mapping defined in the DTD Editor
• XMLvariable is the field, variable, or parameter containing the XML stream
• DTDname is the DTD used to validate the XML stream
• DTDmapping is a UNIFACE list mapping elements to field names

If both /incldefmap and DTDMapping are specified, the DTD mapping defined in DTDmapping overrides the default DTD mapping.

DTDname is a literal string, variable, or constant using the following format:

"{DTD:}Name.Model"

Where:

• DTD: specifies that the XML stream is defined using a DTD (this is to ensure compatibility with future developments in the XML standard)
• Name is the name of the DTD as specified in the application model
• Model is the name of the DTD's application model

7.2 xmlsave

Place component data in an XML stream.

xmlsave{/mod}{/dtd | /ref}{/incldefmap}{/one} XMLvariable, DTDname, DTDmapping

Where:

• /mod includes only modified occurrences in the XML stream
• /dtd includes the DTD in the XML stream
• /ref includes the URI location of the DTD in the XML stream
• /incldefmap instructs xmlsave to use the default DTD mapping defined in the DTD Editor
• /one includes only the current outer occurrence (with all inner occurrences) in the XML stream
• XMLvariable is the field, variable, or parameter containing the XML stream
• DTDname is the DTD used to generate and validate the XML stream
• DTDmapping is a UNIFACE list mapping elements to field names

For more information on the syntax for DTDname, see xmlload.

7.3 retrieve/reconnect

Reconnect data loaded from an XML stream with the database.

retrieve/reconnect {EntityName}

Where EntityName is the name of an entity painted on the component.

Note: retrieve/reconnect resolves the occurrence state information stored in the occurrence meta information, and fires all validate triggers. Occurrences in the XML stream are treated as new if state attributes are not defined in the DTD.

8. New Proc functions

8.1 $occcrc

Set or return the checksum of an occurrence.

$occcrc (EntityName)
$occcrc (EntityName) = CheckSum

Where:

• EntityName is an entity name
• CheckSum is an eight-character hexadecimal string

$occcrc returns an eight-character hexadecimal string.

8.2 $occproperties

Return or set the properties of an occurrence.

$occproperties (EntityName)
$occproperties (EntityName) = Property

Where:

• EntityName is an entity name
• Property is an associative list

This function sets or returns the properties of an occurrence using an associative list. The values returned in the Property list include:

• errormsg occurrence-level validation error messages

8.3 $occstatus

Set and return the reconnect status of an occurrence.

$occstatus (EntityName)
$occstatus (EntityName) = ReconnectStatus

Where:

• EntityName is the name of an entity
• ReconnectStatus is one of the following:
  • "" occurrence not created by xmlload
  • "est" the occurrence exists in the database
  • "new" the occurrence is new, that is, it does not exist in the database
  • "del" the occurrence is marked for deletion

9. DTD mapping lists

DTD mapping lists map the values of elements in a DTD stream to fields on a component.

Default DTD mapping lists can be defined in the DTD Editor. DTD mapping lists can also be defined in Proc, for use in the Proc statements xmlload and xmlsave.

DTD mapping lists are GOLD ; separated UNIFACE lists. Each list item has the following syntax:

"ElementName=TargetName;..."

Where:

• ElementName is the name of an element in the DTD and is case-sensitive.
• TargetName is the name of a field or entity. The fields or entities do not have to be present on the target component. Values that cannot be mapped to a painted field are ignored. TargetName is case-insensitive.

10. Sample code

The following sample Proc code shows how to send and receive data using xmlstream parameters.

10.1 XMLIN operation

The XMLIN operation receives an XML stream and reconnects the data to the database.

operation XMLIN

; This operation receives and reconnects an XML stream.
 

params
   xmlstream [DTD:ABCDTD.ABC]  MYSTREAM  : IN
endparams


clear

xmlload MYSTREAM, "DTD:ABCDTD.ABC"
retrieve/reconnect
...

10.2 XMLOUT operation

The XMLOUT operation creates an XML stream.

operation XMLOUT

; This operation saves data to XML.


params
   xmlstream [DTD:ABCDTD.ABC]  MYSTREAM  : OUT
endparams


clear
retrieve



xmlsave MYSTREAM, "DTD:ABCDTD.ABC"
...

11. Known limitations

UNIFACE V7.2.06 Beta has the following known limitations in its support for XML stream data transport:

• XML streams are currently checked for well-formedness, but are not validated using the specified DTD. DTDs are used for generating XML streams and for communicating the structure of the XML stream to 3GL components
• XML streams are not recognised as data types in the URB and the Signature Editor. XML streams are treated as strings instead. DTD names are not declared in component signatures

12. Known bugs

The following known bugs are in the UNIFACE V7.2.06 Beta release:

• The DTD: Rename form does not check element names for compliance with XML element naming rules.
• GOLD G does not completely clear the Select Attributes form.
• xmlload can crash on SO6 if no DTD, or an incorrect DTD, is specified.
• Selecting Edit—>Validate does not check element names for compliance with XML element naming rules.
• xmlsave/mod does not check the value of $formmod.
• DTDs are stored when leaving the Define DTD form, inclusive of when the DTD Wizard is started, and when form is cancelled.