Validation properties

The validation properties restrict what is accepted when the user enters data in a text form.

The properties are as follows:

fill

The fill property indicates whether the user is required to enter data in each field position. Valid values are no (the default) and yes.

inputRequired

The inputRequired property indicates whether the user is required to place data in the field. Valid values are no (the default) and yes.

If the user does not place data in the field when the property value is yes, EGL run time displays a message, as described in relation to the field property inputRequiredMsgKey.

inputRequiredMsgKey

The property inputRequiredMsgKey identifies the message that is displayed if the field property inputRequired is set to yes and the user fails to place data into the field.

The message table (the data table that contains the message) is identified in the program property msgTablePrefix. For details on the data-table name, see DataTable part in EGL source format.

The value of inputRequiredMsgKey is a string or literal that matches an entry of the first column in the message table.

If a numeric key is used with a message table that expects a character key, the number is converted to a character string. If a string literal is used with a message table that expects a numeric key, the value in the string must be a signed or unsigned integer.

isDecimalDigit

The isDecimalDigit property determines whether to check that the input value includes only decimal digits, which are as follows: 

  0123456789

Valid values are no (the default) and yes.

This property applies only to character fields.

isHexDigit

The isHexDigit property determines whether to check that the input value includes only hexadecimal digits, which are as follows: 

  0123456789abcdefABCDEF

Valid values are no (the default) and yes.

This property applies only to character fields.

minimumInput

The minimumInput property indicates the minimum number of characters that the user is required to place in the field, if the user places any data in the field. The default is 0.

If the user places fewer than the minimum number of characters, EGL run time displays a message, as described in relation to the field property minimumInputMsgKey.

minimumInputMsgKey

The property minimumInputMsgKey identifies the message that is displayed if the user acts as follows:

  • Places data in the field; and

  • Places fewer characters than the value specified in the property minimumInputRequired.

The message table (the table that contains the message) is identified in the program property msgTablePrefix. For details on the table name, see DataTable part in EGL source format.

The value of minimumInputMsgKey is a string or literal that matches an entry of the first column in the message table.

If a numeric key is used with a message table that expects a character key, the number is converted to a character string. If a string literal is used with a message table that expects a numeric key, the value in the string must be a signed or unsigned integer.

needsSOSI

The needsSO/SI property is used only for a multibyte field (a field of type MBCHAR) and indicates whether EGL does a special check when the user enters data of type MBCHAR on an ASCII device. Valid values are yes (the default) and no. The check determines whether the input can be converted properly to the host SO/SI format.

The property is useful because, during conversion, trailing blanks are deleted from the end of a multibyte string to allow for insertion of SO/SI delimiters around each substring of double-byte characters. For a proper conversion, the form field must have at least two blanks for each double-byte string in the multibyte value.

If needsSO/SI is set to no, the user can fill the input field, in which case the conversion truncates data without warning.

If needsSO/SI is set to yes, however, the result is as follows when the user enters multibyte data:

  • The value is accepted as is because enough blanks are provided; or

  • The value is truncated, and the user receives a warning message.

Set needsSOSI to yes if the user's ASCII input of multibyte data may be used on a z/OS or iSeries system.

range

The range property indicates the lowest and highest values that valid for user input. The property is only used for numeric fields. The format of the property is as follows: 

  range = (lowestValue, highestValue)

lowestValue

The lowest value that is valid.

highestValue

The highest value that is valid.

If the user's input is outside the specified range, EGL run time displays a message, as described in relation to the field property rangeMsgKey.

This property applies only to numeric fields.

rangeMsgKey

The property rangeMsgKey identifies the message that is displayed if the field property range is set and the user places out-of-range data into the field.

The message table (the table that contains the message) is identified in the program property msgTablePrefix. For details on the table name, see DataTable part in EGL source format.

The value of rangeMsgKey is a string or literal that matches an entry of the first column in the message table.

If a numeric key is used with a message table that expects a character key, the number is converted to a character string. If a string literal is used with a message table that expects a numeric key, the value in the string must be a signed or unsigned integer.

This property applies only to numeric fields.

typeChkMsgKey

The property typeChkMsgKey identifies the message that is displayed if the input data is not appropriate for the field type.

The message table (the table that contains the message) is identified in the program property msgTablePrefix. For details on the table name, see DataTable part in EGL source format.

The value of typeChkMsgKey is a string or literal that matches an entry of the first column in the message table.

If a numeric key is used with a message table that expects a character key, the number is converted to a character string. If a string literal is used with a message table that expects a numeric key, the value in the string must be a signed or unsigned integer.

validator

The validator property identifies a validator function, which is logic that runs after the EGL run time does the elementary validation checks, if any. Those checks are described in relation to the following properties:

  • inputRequired

  • isDecimalDigit

  • isHexDigit

  • minimumInput

  • needsSOSI

  • range

The elementary checks precede use of the validator table (as described in relation to the validatorTable property), and all checks precede use of the validator property. This order of events is important because the validator function can do cross-field checking, and such checking often requires valid field values.

The value of validator is a validator function that your write. You code that function with no parameters and such that, if the function detects an error, it requests the re-display of the form by invoking sysLib.validationFailed.

If validation fails when you specify one of the two system functions, the displayed message is based on the value of the property validatorMsgKey. If validation fails when you specify a validator function of your own, however, the function does not use validatorMsgKey, but displays a message by invoking sysLib.validationFailed.

validatorMsgKey

The property validatorMsgKey identifies a message that is displayed in the following case:

  • The validator property indicates use of sysLib.verifyChkDigitMod10 or sysLib.verifyChkDigitMod11; and

  • The specified function indicates that the user's input is in error.

The message table (the table that contains the message) is identified in the program property msgTablePrefix. For details on the table name, see DataTable part in EGL source format.

The value of validatorMsgKey is a string or literal that matches an entry of the first column in the message table.

If a numeric key is used with a message table that expects a character key, the number is converted to a character string. If a string literal is used with a message table that expects a numeric key, the value in the string must be a signed or unsigned integer.

validatorTable

The validatorTable property identifies a validator table, which is a dataTable part that acts as the basis of a comparison with user input. Use of a validator table occurs after the EGL run time does the elementary validation checks, if any. Those elementary checks are described in relation to the following properties:

  • inputRequired

  • isDecimalDigit

  • isHexDigit

  • minimumInput

  • needsSOSI

  • range

All checks precede use of the validator property, which specifies a validation function that does cross-value validation.

You can specify a validator table that is of any of the following types, as described in DataTable part in EGL source format:

matchInvalidTable

Indicates that the user's input must be different from any value in the first column of the data table.

matchValidTable

Indicates that the user's input must match a value in the first column of the data table.

rangeChkTable

Indicates that the user's input must match a value that is between the values in the first and second column of at least one data-table row. (The range is inclusive; the user's input is also valid if it matches a value in the first or second column of any row.)

If validation fails, the displayed message is based on the value of the property validatorTableMsgKey.

validatorTableMsgKey

The property validatorTableMsgKey identifies the message that is displayed if the user provides data that does not correspond to the requirements of the validator table, which is the table specified in the property validatorTable.

The message table (the table that contains the message) is identified in the program property msgTablePrefix. For details on the message-table name, see DataTable part in EGL source format.

The value of validatorTableMsgKey is a string or literal that matches an entry of the first column in the message table.

If a numeric key is used with a message table that expects a character key, the number is converted to a character string. If a string literal is used with a message table that expects a numeric key, the value in the string must be a signed or unsigned integer.

Related concepts
Text forms

Related reference
DataTable part in EGL source format
sysLib.validationFailed
sysLib.verifyChkDigitMod10
sysLib.verifyChkDigitMod11