Each field in a client message and each field in a server message, includes properties that can be used at runtime to enforce certain constraints on the data value that the field may contain. For example, for a numeric field in a message, you can optionally configure a minimum and maximum allowed value. If there is an attempt to set a field to a value that violates the configured constraints, an exception is thrown at runtime.
The exception can be caught by your orchestration and handled to provide an appropriate error message. Refer to Understanding Orchestration and Handling Exceptional or Abnormal Conditions for more information.
In addition, if you create an MVC Web presentation project, a Web Forms Application presentation project, or a Web Forms Mobile Application presentation project, ePortal generates a web page that enforces any constraints that you have configured in the corresponding client message. Refer to the following topics for more information:
Runtime Error Checking for Numeric Message Fields
You can configure the following properties for a numeric field in a client message or a server message:
MinValue – The minimum value allowed for the field. If this is empty, no minimum is enforced.
MaxValue – The maximum value allowed for the field. If this is empty, no maximum is enforced.
StepValue – The step value for the field. This is a positive value that represents the granularity required for a numeric value. For example, the step would be 1 for an integral type, and 0.01 for a decimal value that can specify two decimal places. Leave the step value empty to indicate a default value. For integral types, the default is 1. For decimal and floating point types, the default is that no step value is enforced.
Notes:
The ePortal runtime code currently does not use StepValue for error checking; however, StepValue is used to set the HTML5 step attribute for a Web Forms Application presentation project or a Web Forms Mobile Application project. Refer to Validation Performed by HTML5-Compatible Browsers for more information.
If you set ControlStyle to Slider, you should explicitly configure values for MinValue, MaxValue, and StepValue instead of leaving them blank, since these settings are used to generate the slider control. Refer to Controlling the Look and Feel in All Data Source Projects for more information.
If ePortal detects an attempt to set a field to a value which is outside the range defined by MinValue and MaxValue, then an OutOfRangeException is thrown. Refer to Handling Exceptional or Abnormal Conditions for more information.
Runtime Error Checking for String Message Fields
You can configure the following properties for a string field in a client message or a server message:
Required – If set to True, a value is required for this field. If set to False, the empty string is a legal value for this field. If set to True and the field is set to an empty string, an InvalidFormatException is thrown at runtime.
Pattern – Defines the pattern that the field value must match if it is not empty. If the field value is empty, it is never validated against a pattern. If the pattern is empty, then no pattern match is performed. When a pattern is configured, the format of the pattern is a regular expression as defined by the Standard ECMA-262 ECMAScript Language Specification Edition 5.1 (June 2011). Note that ECMAScript is the more formal name for JavaScript. When pattern matching is performed, the pattern must match the entire string value for the field; otherwise, an InvalidFormatException is thrown at runtime.
MaxBytes – The maximum size of the field in bytes. After a string value is encoded into the application character set, it must not exceed this size, or an InputDataOverflowException is thrown at runtime. If this property is empty, then no size validation is performed during the orchestration phase; however, an error may still be detected as the value is sent to the server.
DoubleByteCharsOnly – This field applies to Asian character sets only. If set to True, this field is restricted to double-byte characters. If set to False, no validation is performed. If DoubleByteCharsOnly is set to True and a single-byte character is detected in the field, an InvalidCastException is thrown at runtime.
Refer to Handling Exceptional or Abnormal Conditions for information on runtime exceptions.
Other Properties Related to Runtime Error Checking
You can configure the following properties for a numeric or string field in a client message or a server message:
ValidateOnClientInputOnly
True if validation should be performed for client input only; otherwise, false. The default is false. This property does not apply to output-only fields.
If true, this field is validated only at the following times:
When a web browser or mobile page is submitted.
When a web service method is called.
If false, this field is validated whenever the value is set in the generated C# message class; this can be due to an input or output operation or due to an assign operation during an orchestration step.
A typical case for setting ValidateOnClientInputOnly to true for a particular input/output field is if the validation constraints do not hold on output from the ClearPath server. For example, if a field is required on input, but may be empty on output, you could set Required to true and ValidateOnClientInputOnly to true to require the end user to enter a value on input, but to allow the ClearPath server to return an empty value on output.
Description
This is a short string which describes the type of value the field represents. If you create an MVC Web Presentation, a Web Forms Application presentation projector a Web Forms Mobile Application presentation project , this value is used as a tooltip for the corresponding field on the web page. Typically, a tooltip is displayed if you hover a mouse pointer over a field; some mobile browsers may also provide some alternate means of displaying a tooltip. If you create a WCF Web Service Application project, this value is used to document the corresponding parameter for the web service method. In addition, this value may be appended to the validation error message to help the end user determine the expected input for a field when an error is detected. Refer to Validating MVC Web Pages and Validating Web Forms Pages for more information.
Automatically Configured Runtime Checking for ePortal Messages
When you create a server message, ePortal automatically configures any constraints implied by the artifacts that you used to create the server message. For example, consider the case where you imported the example COBOL 01 record to create an ePortal server message.
For MCP COBOL:
01 INPUT-RECORD.
05 NUM-FIELD1 PIC 99.
05 NUM-FIELD2 PIC S999V9.
05 STRING-FIELD1 PIC XXX.
05 STRING-FIELD2 PIC XXX USAGE NATIONAL.
05 GROUP1-COUNT PIC 9.
05 GROUP1 OCCURS 1 TO 4 TIMES DEPENDING ON GROUP1-COUNT.
10 STRING-FIELD3 PIC XXX USAGE KANJI.
For OS 2200 COBOL:
01 INPUT-RECORD.
05 NUM-FIELD1 PIC 99.
05 NUM-FIELD2 PIC S999V9.
05 STRING-FIELD1 PIC XXX.
05 STRING-FIELD2 PIC XXX USAGE DISPLAY-2.
05 GROUP1-COUNT PIC 9.
05 GROUP1 OCCURS 1 TO 4 TIMES DEPENDING ON GROUP1-COUNT.
10 STRING-FIELD3 PIC XXX USAGE DISP-2.
During the import, ePortal automatically sets the runtime error checking properties as shown in the following tables. You can override these settings by editing the resulting server message and/or client message. Refer to Modifying Client Messages for more information.
| Field Name | Max Value | Min Value | Step Value |
| NUM_FIELD1 | 99 | 0 | 1 |
| NUM_FIELD2 | 999.9 | -999.9 | 0.1 |
| GROUP1_COUNT | 4 | 1 | 1 |
| Field Name | Required | Pattern | MaxBytes | DoubleByteCharsOnly |
| STRING_FIELD1 | False | empty | 3 | False |
| STRING_FIELD2 | False | empty | 6 | True |
| STRING_FIELD3 | False | empty | 6 | True |
Note: When importing COBOL, Required is always set to False, since ePortal has no way of knowing if a particular string field is required. Similarly, Pattern is always set to empty since ePortal does not know a particular pattern to enforce. In both cases, the user must explicitly configure these properties in order to cause ePortal to perform runtime error checking; however, when importing MCP SDF forms or OS 2200 DPS forms, an input/output field marked as required has the Required property set to True, and ValidateOnClientInputOnly property set to True.
Disabling Runtime Error Checking for the Entire Data Source Project
Unisys recommends that you enable runtime error checking in order to detect invalid data as early as possible. However, as noted above, you can disable runtime error checking on a field-by-field basis by configuring message field properties appropriately.
You can also disable one or more types of error checking for the entire data source project by configuring the data source project property Runtime Error Checks Performed. Refer to Data Source Project Property Pages Dialog for more information.
Note: ePortal must always verify that a user-supplied data value can be converted to the data type of the corresponding message field. This means that some implied range checking is always enabled for numeric data. For example, if a field in an ePortal message is defined as data type short, then ePortal will always detect a value outside the range for a short (-32768 to 32767) and throw an OutOfRangeException.