Upgrade Guide to Websydian Version 5.5/5.5 SP1

This document describes the upgrade process for upgrading Websydian applications from version 4.0/4.01 to Websydian 5.5 or Websydian 5.5 SP1.

When upgrading from versions prior to 4.0/4.01 the upgrade guides for these versions should be applied before this document is read.

Upgrade from Websydian 5.5 to Websydian 5.5 SP1

When upgrading from Websydian 5.5 to Websydian 5.5 SP1 no special action is required. Attach the Websydian 5.5 SP1 group models to the host group model and use the Websydian 5.5 SP1 runtime objects instead of the previously deployed Websydian 5.5 runtime objects.

If you at the same time upgrade from a previous version of Plex it is necessary to regenerate and build the application.

Please be aware of any special requirements regarding the Plex upgrade. E.g. an upgrade from Plex 5.5 GA to Plex 5.5 SP1 requires a regeneration of all objects on the Windows and Java platforms.

Plex Version

The Websydian 5.5 group models can be used with Plex 4.0 and above.

The Websydian 5.5 SP1 group models can be used with Plex 5.0 and above.

To upgrade from a previous version of Websydian to Websydian 5.5 or Websydian 5.5 SP1 please follow the steps in the following sections.

After an upgrade it is necessary to generate and build the model.

General

HTTP header names and values changed

Some of the literal values for HTTP header name and value fields have been changed so header values now are in lower case and the first letter in each word in header names is in upper case. This means that the spelling of HTTP header values and names now follow the W3C standard for the HTTP protocol.

The table below shows the fields which have had some of the literal values changed.

This change should not affect any Websydian applications as the header names/values now are in the correct case.

Empty strings outputted correctly (Windows CWA)

In CA Plex a string is considered to be empty if it only contains spaces. For the PageGenerator functions this had the effect that if a field in WsyDetails or WsyGrid only contained spaces, then these spaces would be ignored and the PageGenerator would replace the replacement marker with the empty string.

This has now been corrected so a field containing only spaces is replaced correctly in the template.

This bug correction only applies to the Windows CWA platform.

New parameter in WSYBASE/WriteToFile

The parameter JavaEncoding has been added to the Input variable in the WriteToFile function. The parameter only has an effect on the Java platform, and the value of the parameter determines the encoding of the text written to the file.

The previous behavior was that the platforms default encoding was used. The same behavior can be obtained by using the value JavaEncoding.Default when calling WriteToFile.

When using WriteToFile on another platform this parameter has no effect.

When upgrading a Websydian application to Websydian 5.5, all calls to the WriteToFile function (if any) should have the field JavaEncoding added to the input parameter mapping.

WebEndUserSession cannot find WPKAF027.dll (CWA)

The WebEndUserSesssion function in the Session Management pattern tried to call the function DwaClientUpdateSession (WPKAF027) which only should be called in a DWA environment.

WebEndUserSesssion has been changed so it only calls DwaClientUpdateSession in DWA applications. This means that the workaround inserted in the edit point Start logout user in Websydian Server can be removed.

TransacXML

TransacXML Access

WSYDOM/DomServices.GetStringLength deprecated

The function WSYDOM/DomServices.GetStringLength has been deprecated. Instead use the function SDSTRING/GetLength.

TransacXML Modeller

Namespace support

There are now full support for namespaces in Websydian TransacXML. If existing XML models does not belong to a namespace, no further action is necessary when upgrading the XML model to Websydian 5.5.

However, if the XML model belongs to a namespace and the LongName entity has been used to specify prefixes for the XML elements, then this must be changed to use the built-in support for namespaces.

Please refer to the documentation on namespaces for more details.

Scope of CreateDTD function changed

The scope of the CreateDTD function has been moved from the XmlElement entity to the XmlElementWithServiceFunctions entity.

If the CreateDTD function is used in the development process, then make sure that all elements inheriting from XmlElement also inherits from XmlElementWithServiceFunctions.

XmlElement functions validates element type and name

Two types of validation has been inserted in the XmlElement functions shown in the table below:

Element type validation

This validation ensures that the object reference being validated is a reference to an XML element node.

Element name validation

This validation ensures that the object reference references a node with the same name as the scoping XmlElement entity.

E.g. when calling the function MyOrderHeader.MyOrderDetail.SingleFetch the above validation ensures that the input field ObjectElement references an XML element node with the name MyOrderDetail.

While some of the XmlElement functions validates against the scoping entity other functions expect the parent entity as input. E.g. when calling the function MyOrderHeader.MyOrderDetail.InsertRow the validation ensures that the input field ParentElement references an XML element node with the name MyOrderHeader.

The table below shows what each XmlElement function validates.

This change can have an impact on existing applications if some of the XmlElement functions have been called "out of scope".

The recommended approach when upgrading is to make sure that all calls to TransacXML functions comply to the above validation rules. If there is a specific requirement for not doing so, then the validation can be disabled by inserting the following statement in the edit point Set input element node:

Set Validate<ObjectReference> = <ObjectReference.NULL>

WSYXML/GetUnscopedName deprecated

The function WSYXML/GetUnscopedName has been deprecated and an implement No triple has been added to the function so it can no longer be used.

In all of the XmlElement functions the unscoped name of the scoping XmlElement entity can be retrieved in the field GetName<localName>. If there is a requirement to retrieve the unscoped name of another XmlElement entity the meta function +GetNameOfEntity should be used, populating the meta variable WSYXML/+EntityObject with the XmlElement entity in question before the call to the meta function.

WSYXML/XmlTopFunction deprecated

The function WSYXML/XmlTopFunction has been deprecated and an implement No triple has been added to the function. Instead use the functions ImportXmlDocument and ExportXmlDocument

XmlElement functions by default set to implement No

The functions are:

• XmlElement.FlatView
• XmlElement.UpdateRow
• XmlRepeatingElement.ProcessGroup

InsertRow fixed and changed inheritance

As the InsertRow and InsertRowDangling functions almost do the same the InsertRow function has been changed so it now inherits from the InsertRowDangling function.

In previous versions of Websydian there was a bug in the InsertRow function so it did insert an element if the XmlElement did not contain any simple elements. This has now been fixed.

When upgrading remove code in the InsertRow function that solved the above mentioned bug, and also revisit other code inserted in the InsertRow function as the context of some of the edits point have changed due to the changed inheritance.

Added functionality to GetFirstOccurrence

An extra input field has been added to the GetFirstOccurrence function. The field is Parent<ParentElement> and the content of the field determines the context for where GetFirstOccurrence should search for the first occurrence of the XML element node corresponding to the scoping XmlElement entity.

If the field ParentElement is null then the behaviour of GetFirstOccurrence is as in previous versions. However, if one would like to restrict the search to a given sub-tree of the XML document, then the content of ParentElement should point to the parent element from where the search should start.

The added functionality is useful when searching downwards in the XML document from a given parent node to a complex element child.

When upgrading an existing application map with <ParentElement.NULL> in all existing calls to GetFirstOccurrence.

ProcessGroup processes all instances of a given element

A bug in the ProcessGroup function caused it to process all instances of the scoping XML element found in the XML document instead of only those instances that occurred as child elements to the parent XML element supplied as input to the ProcessGroup function.

This has now been fixed so the workaround to this bug should be removed from the edit point Before selectNodes from the ProcessGroup functions when upgrading to Websydian 5.5.

Modelling of repeating element fields have been changed

E.g. if the XML element has one repeating element field (called MyChild) then this was modelled creating both a MyChild entity and MyChild field using the triples below.

With the change in Websydian 5.5 the overhead of the extra XML entity is avoided so only the triples shown in the table below are needed.

In pre-Websydian 5.5 versions the functions scoped to the repeating element entity (entity MyChild) was used to insert and process repeating element fields. As the entity has been removed from the Websydian 5.5 model of repeating element fields, extra functions have been scoped to the repeating element fields. Thus when using repeating element fields call the functions scoped to the field. For further details please look here.

If there are any repeating element fields in the XML model the following must be done when upgrading the model to Websydian 5.5.

1. Change the triples as described above for each instance of a repeating element field.
2. Change all calls to the repeating element entity functions to the corresponding functions scoped to the repeating element field.

TransacXML Web Services

The web service part of TransacXML has been modified in order to solve various bugs and to provide better usability. Please refer to the web service upgrade guide for more details on how to upgrade a Websydian web service application from a previous version of Websydian to Websydian 5.5.

iSeries

iSeries date, time, and timestamp formatting functions

Changes have been made to the objects WSYDEDTWD, WSYDEDTWT and WSYDEDTWTS in order to format date, time, and timestamp fields according to the information found in the data areas WSYDDATMSK, WSYTMEMSK and WSYDTMSMSK.

The parameter interface of these objects have changed. The source code is still available to the Websydian developer.

If current projects have a customized version of one of these objects make sure to use the supplied objects instead. Make sure to enter correct information in the required data areas.

DWA

ApplicationServiceListener function

In previous versions of Websydian the ApplicationServiceListener function would send a dialog message to the desktop in the case of an error. This has now been changed so the function outputs the error to stderr. For the different platforms this means that the error messages can be found here:

Windows

Error messages are sent to stderr and to the desktop as dialog messages. The latter can be disabled and messages sent to stderr can be redirected to a file.

Java

By default all error messages will be sent to the console window of the application. Alternatively this can be redirected to a file.

iSeries

All error messages can be found in the job log of the application service.

For more details please refer to the section on how to start an application service.

iSeries DWA commands changed

The parameter interface for the iSeries DWA commands (ENDWS, ENDAS, STRWS, STRAS, STRJVAAS) has been modified. If any of these commands have been called by CL programs these calls should be modified so they match the changed parameter interface.

Java

Deploy web service as J2EE application

If deploying a web service as a J2EE application then the SoapProcessor function should be based on the HttpSoap.Abstract.J2eeSoapProcessor function rather than the standard SoapProcessor.

Please refer to the following sections for details:

• Deploying J2EE applications
• J2eeSoapProcessor