Workbench User Guide : C. Data Format Templates : Varchar Templates : How You Can Create a Custom Varchar Template
 
Share this page          
How You Can Create a Custom Varchar Template
In addition to the sample varchar templates that OpenROAD provides, you can design your own templates. For example, you might want a template that limits entry in a particular position to one of three characters.
To create a custom varchar template, you can use any combination of the predefined special characters, user-defined special characters, and customized character sets. OpenROAD lets you define up to 12 different custom character sets in a single template.
After a custom character set is defined in a template, you can use it any number of times in the template. Combining custom character sets, constant characters, and the special characters gives you full flexibility in creating a template that suits your needs.
Using Special Characters
OpenROAD provides a number of special characters that you can use in a custom varchar template. Each special character represents a set of characters from which the end user can choose to enter at the specified position.
In our previous example, the special characters “a” and “z” represent alphabetic characters and digits, respectively. Therefore, using the aaazz template, end users can make entries such as “Afm35” or “pRt44” but not entries such as “2acm5” or “C342d.” They must enter alphabetic characters in the first three places and numeric characters in the last two places.
The following table describes the special characters that you can use in a varchar template:
Character
Description
a
Any alphabetic character
h
Any hexadecimal digit
n
Any digit (the default is 0)
o
Any printable 7-bit character
p
Any printable character
q
Any character that can be the first character in an OpenROAD name
r
Any character that can be the second or subsequent character in an OpenROAD name
s
Any 7-bit character
t
Any character (the default is a space)
x
Alphabetic and numeric characters
z
Digits (the default is a space)
i, j, k, l, m
User-defined characters. For more information about defining these special characters, see How You Can Define a Special Character for a Character Set.
You can use templates to perform the following tasks:
Enforce mandatory entry (the end user must make an entry).
All of the special characters support mandatory entry.
For information about using mandatory entry, see How You Can Force Mandatory Entry.
Force the case of an entry.
Insert a default entry if the end user fails to make an entry.
If you want to force the case of an end user's entry or insert a default entry if the end user makes no entry, you must use a user-defined special character.
Note:  The predefined special characters do not support forced case or default entries.
The Escape Character
In addition to the special characters, a template can also include constant (or literal) characters. To specify that a character be read as a literal in a template, precede the character with the backslash escape character (\).
How You Can Define a Character Set
You can limit an end user's entries to some set of characters that are broader or more narrow than those available using the predefined special characters. To accommodate these needs, OpenROAD lets you define a custom character set. If the set you want is small (for example, one or two characters), use the following syntax:
[c{c}]
where c represents the valid character or characters. You can include any number of valid characters. Simply use this syntax in the template in the positions where you want the specified characters. You must include the square brackets.
For example, the following template lets the end user enter only the letters “a,” “b,” or “c” in the first position:
[abc]nnn
If you want to specify a range of characters, use the following syntax:
[c-c2]
where c represents the beginning character in the range and c2 represents the ending character, for example [a-g].
For either syntax, OpenROAD forces the end user to enter one of the specified characters in the specified position.
In either syntax, the case of the characters is unimportant for alphabetic characters. You can use an uppercase or lowercase character to represent the character. To force the end user's entry to either case, use the special formatting character that specifies forced case. (For more information about forcing case, see How You Can Specify Uppercase or Lowercase.)
When you define a character set for a single position this way, you cannot enforce mandatory entry in that position. To enforce mandatory entry, define the character set with a user-defined special character.
If you are defining a large character set or are using the set in several places in your custom template, define a special character to represent the set and use that character in the template. For information about defining special characters, see How You Can Define a Special Character for a Character Set.
How You Can Define a Special Character for a Character Set
In addition to the predefined special characters for varchar templates, OpenROAD provides five special characters (“i,” “j,” “k,” “l,” and “m”) whose meaning you can define by associating one of the user-defined special characters with a custom character set. This feature makes it easy to define a custom character set and specify that set in several positions in your custom template.
To use a user-defined special character, define the special character at the first instance of its use in the template and then put the special character in the template for subsequent occurrences.
In the same way that OpenROAD defines each of its predefined characters to represent some set of characters, you can define each of these special characters to represent some set of one or more characters. To do so, use the following syntax:
[c=c1{c2}]
where c is one of the five special characters and c1 and c2 represent the characters that you want to include in the set of characters defined for the special character. You can include any number of characters in the set.
You can also specify a range of characters for your special character. For example:
[c=c1-c2]
In this case, c represents the special character, c1 represents the beginning of the range, and c2 represents its end.
When you include a user-defined special character in a template, the first instance of the character in the template must be its definition. For subsequent occurrences, you just use the special character. In the following template example, the special character “j” represents the numbers “4” and “6”:
[j=46]aazaj
This template describes a field of six characters, of which the first and last must be either a 4 or a 6.
Special Characters in User-defined Character Sets
OpenROAD provides a set of predefined special characters that you can use in the definition of a custom character set. These characters can appear only in a character set definition. You cannot place them directly in a template definition.
These special characters are useful because you can force the case or apply a default to any of the characters represented by these built-in special characters. (The predefined special characters—described in Using Special Characters)—do not allow you to apply forced case or a default to any of the characters that they represent.)
The following table lists the predefined special characters that you can use in a custom character set definition:
Character
Represents
#
Any digit
@
Any alphabetic character
*
Any printable character
+
Any printable character (only 7 bits)
&
Any character that can be the first character in a name
%
The second and subsequent characters in a name
:
Any hexadecimal digit
Use these characters to force the case of an entry or to provide a default for the entry. For example, the following template specifies a four-letter entry:
aaaa
If you want the first position to be an uppercase letter, you cannot force case on the special character “a.” Instead, you must use the special character “@”:
[@/u]aaa
To include any of these special characters literally in the template, use the escape character with the character. For example, the following template lets the end user enter a two-figure percentage value:
nn\%
How You Can Specify a Default Character
To specify a default character for a position, include the following syntax in your character set definition:
//c
where c is the default character.
For example, assume that you want end users to enter a 4-digit number. Users must enter at least two numbers, but if they fail to enter the final two numbers, the numeral “1” should appear in those positions. The following template achieves this behavior:
nn[#//1][#//1]
The "n" forces entry of a digit in those positions. The other two positions allow entry of a digit, but insert the specified default if the end user does not make an entry.
When you specify a default character for a position, OpenROAD inserts the default character whenever the end user inserts a space in that position or fails to make an entry in that position. The only exception occurs when the space is a valid entry for that position. In such instances, OpenROAD places the space in the position. If a space is not a valid entry, then OpenROAD places the default character in the position.
OpenROAD always considers the specified default character a valid character for the position even if it is not part of the character set defined for that position by the template.
How You Can Specify Uppercase or Lowercase
To force the case of the end user's entry, use the following values in the special character definition.
For uppercase
/U or /u
For lowercase
/L or /l
You can include only one case specification in each special character definition. For example, to have the end user enter a part number that consists of an uppercase letter from A–D, followed by three numbers, you could use the following template:
[a-d/U]nnn
The end user can make entries in lowercase or uppercase, but the data will appear in the field in uppercase.