PIC_FormatFields

Validates the format of the current field or all fields on the current page and uses another to replace problem characters.

Syntax

bool PIC_FormatFields ()

Parameters

None.

Returns

Always True.

Level

All levels.

Details

Lowers the Confidence Rating of any character in a field that does not satisfy the PictureString criteria.

This action adjusts the character confidence of a field, and optionally replaces characters that are based on the picture string set for the field. It is similar to the FilterFields action.

This action has two roles, if a character in the field does not match the picture string format that is defined for that field.

It replaces any problem characters with an alternative character from a secondary recognition engine, if one exists. If an alternative recognition character does not exist, then the original character is unchanged.
Attention: There must be an equal number of alternative characters as the field length, and the alternative character must also be valid within the field's picture string for substitution to occur. If the alternative recognition character is also not a valid picture string character, then no substitution occurs.
It lowers the Confidence Rating of any character in a field that does not satisfy the picture string's criteria.

Alternative recognition characters are removed from the field after execution.

Important: This Action is recursive and affects all child fields of the calling node.

Picture Strings:

This action works with picture strings that are defined for a field. The picture string must be stored in a field variable called PictureString. Picture strings improve and filter recognition results, and are used to limit characters that are typed into that field during verify. The PIC_FormatFields and PIC_FilterFields actions can be called to enforce PictureString after recognition rules are started. The PIC_ApplyPictureString action is an exception that does not use the PictureString variable.

Recognition actions do not pay attention to this property. Individual recognition engines have their own parameters to help guide the recognition. The Web Verify task always enforces PictureString. Thick client Verify panels that are constructed by Batch Pilot Autoform also enforces PictureString specifications.

PIC_FilterFields replaces non-matching characters with low confidence spaces. PIC_FormatFields lowers the confidence. The DCEdit control enforces them during verify.

The picture values can be set in PictureString in two ways.

Use the rrunner action rrSet in a rule set. With this action, you can specify the PictureString variable and set it to the value that you want.
In the Zones tab of Datacap Studio, right-click on the field you want and choose Manage Variables.

While not direct input to this action as a standard parameter, here are the valid picture string characters that can be set in the PictureString field variable and are then used by this action.

A: Alphabetic characters only or a space. Numeric and punctuation characters are not valid.
a: Alphabetic, space and punctuation characters.
D: Dates. The dates must be expressed with numeric characters. You can delimit months, dates, and years with hyphens, periods, and forward slashes.
F: Float numbers, which are fractional numbers. To accommodate fractional values, you can include both numbers and a period (for the decimal separator) in this picture string. The F character allows minus signs to represent negative numbers.
f: Numeric and punctuation characters.
L: Lowercase alphabetic and space characters.
l: Lowercase alphabetic, space, and punctuation characters.
N: Numeric characters only.
n: Uppercase alphabetic, numeric, or space characters.
P: Punctuation and space characters.
T: Time values. These values are expressed in numbers with a colon. In addition, the characters P, M, and A are allowed to distinguish between morning and afternoon times, and colon characters are allowed to delimit hours, minutes, and seconds.
U: Uppercase alphabetic and space characters.
u: Uppercase alphabetic, space, and punctuation characters.
X: Alphabetic, space and numeric characters.
x: Alphabetic, space, numeric, and punctuation characters.
Z: Any character.
#: Numeric characters and the minus sign.

PIC_SetPictureCharacter can be used to define up to 10 more application-specific picture strings at run time, identified as 0 through 9.

Example

rrSet("AN,@F.PictureString")
PIC_FormatFields()

This example expects the current field to contain a single alphabetic character followed by an unlimited number of digits. Here the PictureString variable is set at run time, but it can instead be configured at design time in the setup DCO in Datacap Studio.