|
|
This document describes how Websydian handles formatting of data when generating HTML pages and how data sent from the browser is interpreted.
Websydian generates HTML pages based on document templates. A document template is essentially an HTML document containing replacement markers where data should be inserted. At runtime Websydian reads the templates and substitutes the replacement markers with data read from fields in the WsyDetails/WsyGrid in the PageGenerator function. In this process Websydian must choose how the field values from WsyDetails/WsyGrid should be formatted when inserted in the HTML page as text.
When a user activates an event (e.g. by clicking on a button, link, etc.) in the browser values from the form are sent from the browser to the Websydian application. All values are sent as text but they might not all be interpreted as text strings. Some values might be interpreted as dates or numbers. This is handled by Websydian as it automatically converts the text values to field values in the WebInput variable in the EventHandler function. In order to do so Websydian must have information about how the data is formatted so it correctly can be read and stored in the EventHandler WebInput variable.
Websydian supports 5 different field types:
The date, time, and timestamp fields are also known as datetime fields and are treated the same way in Websydian.
The next sections will describe in detail how field values are converted from the representation in the Action Diagram fields to a text representation on an HTML page and back.
If a character field has an edit mask specified in the Plex
model this edit mask will be used when the field value is sent to
the HTML page.
Example:
If the edit mask is '###-##-##' and the value is
'1231212' then the output to the HTML page will be '123-12-12'.
Please note that this is handled differently on the iSeries platform. Please refer to Formatting Values on the iSeries for details.
The use of edit masks on character fields are not recommended if the field at the same time occurs as an input field. This is because Websydian does not convert the formatted value back to the original value. In the above example this would mean that when the formatted value was returned to the Websydian application the field in the WebInput variable would contain the value '123-12-12' instead of the original value '1231212'.
If there is a need for using edit masks for character fields that are used both as input and output the edit point 'Edit parameter name' in the EventHandler function can be used to strip the input value for the characters that were inserted as specified by the edit mask.
If a numeric field has an edit mask with a non-empty large property then the large property is used as the edit mask for the numeric field. If the large property is empty or no edit mask is defined, Websydian automatically generates an edit mask based on the length and decimal triple definitions.
The format of the auto generated edit mask is '##…##0.0…0' where the number of zeroes after the decimal point corresponds to the decimal places triple of the field and the total number of digits (excluding the decimal point) corresponds to the length triple of the field.
The decimal separator and the thousand separator used when formatting numeric field values are taken from the system settings.
Please note that this is handled differently on the iSeries platform. Please refer to Formatting Values on the iSeries for details.
If the value sent from the browser only consists of digits, a decimal separator, thousand separators, and an optional decimal sign, Websydian has no problems in converting the value into a numeric field. However, if the edit mask contains other than those previously mentioned characters Websydian will not be able to parse the value into a numeric field. The edit point 'Edit parameter name' in the EventHandler function can be used to add some extra parsing of numeric values if this is required.
The decimal separator and the thousand separator used when parsing values are taken from the system settings.
The behavior on the iSeries platform is the same as described in the previous section for Java and Windows. The only change is that the decimal and thousand separators are read from data areas listed in the table below.
| Data area | Description | Default |
|---|---|---|
| WSYDDECSEP | Defines the decimal separator for numeric values at input. | . (dot) |
| WSYDTHUSEP | Defines the thousand separator for numeric values at input. | , (comma) |
When datetime field values are formatted Websydian will always use an edit mask to do this. How the edit mask is found is summarized in the table below.
| Edit Mask State | Action |
|---|---|
| Field has an edit mask. | Use the large property of the edit mask object. |
| Field has an empty edit mask. | Get edit mask from Windows system settings. |
| Field has no edit mask. | Read edit mask from INI file. |
If a datetime field does not have an edit mask associated with it then the edit mask will be read from the INI file using the keys shown in the table below.
| INI file key | Description | Default |
|---|---|---|
| DATE | Describes how a date field value is formatted. | yy/mm/dd |
| TIME | Describes how a time field value is formatted. | hh:mm:ss |
| TIMESTAMP | Describes how a timestamp field value if formatted. | yy/mm/dd hh:mm |
The format of edit masks is described in the CA Plex "User's Guide", chapter 6.
When a value is converted into a datetime field the edit mask in the INI file is used to determine the sequence of each section of the datetime value (date, month, year, time, …). The edit mask is only used to determine the sequence of the datetime sections and Websydian can only parse datetime values represented in numeric form, e.g. the date "Sep 22, 1992" can not be parsed by Websydian.
Please note that default valid date separators supported by the EventHandler is slash (/), dash (-) and dot (.).
Please note that the default valid time separatos supported by the EventHandler is dot (.) and colon (:)
On the iSeries the PageGenerator function in itself does not perform any special formatting of datetime field values. Instead special functions are called that can be customized to format the values as desired. Please refer to Formatting Values on the iSeries for details.
When a value is converted into a datetime field an edit mask read from a data area is used to determine the sequence of each section of the datetime value (date, month, year, time, …). The edit mask is only used to determine the sequence of the datetime sections and Websydian can only parse datetime values represented in numeric form, e.g. the date "Sep 22, 1992" can not be parsed by Websydian. The data areas are listed in the table below.
| Data area | Description | Default |
|---|---|---|
| WSYDDATMSK | Specifies the format of a date value. | yyyy/mm/dd |
| WSYDTMEMSK | Specifies the format of a time value. | hh:mm:ss |
| WSYDTMSMSK | Specifies the format of a timestamp value. | yyyy/mm/dd hh:mm:ss |
Please note that default valid date separators supported by the EventHandler is slash (/), dash (-) and dot (.).
Please note that the default valid time separatos supported by the EventHandler is dot (.) and colon (:)
After changing the values in these data areas, you must restart the application services or any page that has already been shown will use the old formats.
When datetime field values are formatted Websydian will always use an edit mask to do this. How the edit mask is found is summarized in the table below.
| Edit Mask State | Action |
|---|---|
| Field has an edit mask. | Use the large property of the edit mask object. |
| Field has an empty edit mask. | A blank edit mask is used which will result in that no value will be displayed. |
| Field has no edit mask. | Read edit mask from Plex property file. |
If a datetime field does not have an edit mask associated with it then the edit mask will be read from the INI file using the keys shown in the table below.
| Property file key | Description | Default |
|---|---|---|
| HTML.DATE | Describes how a date field value is formatted. | yy/mm/dd |
| HTML.TIME | Describes how a time field value is formatted. | hh:mm:ss |
| HTML.TIMESTAMP | Describes how a timestamp field value if formatted. | yy/mm/dd hh:mm |
The format of edit masks can be found in the Plex online help or in the Sun Java documentation for the java.text.SimpleDateFormat class.
When a value is converted into a datetime field the edit mask in the property file is used to determine the sequence of each section of the datetime value (date, month, year, time, …). The edit mask is only used to determine the sequence of the datetime sections and Websydian can only parse datetime values represented in numeric form, e.g. the date "Sep 22, 1992" can not be parsed by Websydian.
Please note that default valid date separators supported by the EventHandler is slash (/), dash (-) and dot (.).
Please note that the default valid time separatos supported by the EventHandler is dot (.) and colon (:)
Websydian applications residing on the iSeries use special runtime functions to format field values before they are inserted into the HTML page. The RPG source code for these functions can be found in the source file QRPGLESRC in the Websydian runtime library (WSYDxxx). Each of these functions are described in detail below.
This function formats numeric values. The parameter list for the function is listed below.
| Parameter name | Input/ Output |
Type | Length | Decimal places | Description |
|---|---|---|---|---|---|
| NUMDAT | Input | Numeric | 30 | 9 | The numeric field value to be formatted. |
| DECPLA | Input | Numeric | 7 | 0 | Number of decimal places for field. |
| DATA | Output | Alphanumeric | 256 | - | The formatted numeric value returned to caller. |
| EDTMASK | Input | Alphanumeric | 100 | - | If the field had an edit mask it will be sent with this parameter. |
This function does not use the edit mask but instead formats the numeric value based on the number of decimal places. If 0 then the edit code Z is used. Otherwise the edit code J is used to format the number.
This function formats character fields. The parameter list for the function is listed below.
| Parameter name | Input/ Output |
Type | Length | Decimal places | Description |
|---|---|---|---|---|---|
| VALUE | Input Output |
Alphanumeric | 256 | - | The character field value to be formatted. The result is returned in this field. |
| EDTMASK | Input | Alphanumeric | 100 | - | The edit mask for the field. |
The default behavior for this function is to do nothing. The dual field is left untouched.
This function formats date values. The parameter list for the function is listed below.
| Parameter name | Input/ Output |
Type | Length | Decimal places | Description |
|---|---|---|---|---|---|
| iDate | Input | Alphanumeric | 10 | - | The date field value to be formatted. |
| oData | Output | Alphanumeric | 256 | - | The formatted date value returned to caller. |
| iGlobalMask | Input | Alphanumeric | 100 | - | Global edit mask from the dataarea WSYDDATMSK |
| iLocalMask | Input | Alphanumeric | 100 | - | Edit mask of the field |
| oErrCode | Output | Alphanumeric | 7 | - | Returning status |
| oErrMsg | Output | Alphanumeric | 256 | - | Message text |
The default behavior of this function is to format the date field according to the date mask supplied in the dataarea WSYDDATMSK.
This function formats time values. The parameter list for the function is listed below.
| Parameter name | Input/ Output |
Type | Length | Decimal places | Description |
|---|---|---|---|---|---|
| iTime | Input | Alphanumeric | 8 | - | The time field value to be formatted. |
| oData | Output | Alphanumeric | 256 | - | The formatted time value returned to caller. |
| iGlobalMask | Input | Alphanumeric | 100 | - | Global edit mask from the dataarea WSYDTMEMSK |
| iLocalMask | Input | Alphanumeric | 100 | - | Edit mask of the field |
| oErrCode | Output | Alphanumeric | 7 | - | Returning status |
| oErrMsg | Output | Alphanumeric | 256 | - | Message text |
The default behavior of this function is to format the time field according to the time mask supplied in the dataarea WSYDTMEMSK.
This function formats timestamp values. The parameter list for the function is listed below.
| Parameter name | Input/ Output |
Type | Length | Decimal places | Description |
|---|---|---|---|---|---|
| iTimeStamp | Input | Alphanumeric | 26 | - | The timestamp field value to be formatted. |
| oData | Output | Alphanumeric | 256 | - | The formatted timestamp value returned to caller. |
| iGlobalMask | Input | Alphanumeric | 100 | - | Global edit mask from the dataarea WSYDTMSMSK |
| iLocalMask | Input | Alphanumeric | 100 | - | Edit mask of the field |
| oErrCode | Output | Alphanumeric | 7 | - | Returning status |
| oErrMsg | Output | Alphanumeric | 256 | - | Message text |
The default behavior of this function is to format the timestamp field according to the timestamp mask supplied in the dataarea WSYDTMSMSK.
Online documentation - Websydian v6.5