Appendix A: Edit Patterns 

The effects of an edit pattern include the following:

• displaying predetermined characters in specified positions in the field
• restricting data entry or display to valid characters
• restricting the number of characters that can be entered or shown in the field.

Some elements can be applied only to left entry or right entry fields. For example, characters in left entry fields only need to satisfy the requirements of their position in the field; characters in right entry fields must satisfy the requirements of the edit pattern for all positions to their right.

The following sections examine all of the elements used in edit patterns. Related elements have been grouped into sections as follows:

• Number elements
• Sign elements
• Decimal point elements
• Character elements
• Date elements

The following table lists the number element symbols and their meanings. Note that correct symbol case is important.

Table A1-1: Element Symbols Meanings
 

Symbol	Meaning
*	Print a digit in this position. If it is an empty leading position, print "*" instead. If it is an empty trailing position after a decimal point, print "0".
9	Print a digit in this position. If it is an empty leading position, print "0" instead. If it is an empty trailing position after a decimal point, print "0".
Z	Print a digit in this position. If it is an empty leading position, print a space instead. If it is an empty trailing position after a decimal point, print "0".
F	Print a digit in this position. If it is an empty leading position, print nothing. If it is an empty trailing position after a decimal point, print "0".

Notes:

1. The locations of leading positions in a field differ for right entry and left entry fields. They are similar, however, in that a leading position is considered empty if it does not affect the value of the data in the field.
2. In a right entry field, the leading positions occur between the left side of the value and the extreme left side of the field. In a right entry field - usually used for numeric data - a leading position is considered empty if it contains a "0" or no character.
3. In a left entry field, the leading positions occur between the right side of the value and the extreme right side of the field. In a left entry field usually used for text data leading position is considered empty only if it does not contain any characters.
4. By way of example, consider the entry "100". As numeric data in a right entry field its value does not change when it is padded with leading characters of the number "0": 00100. As text data in a left entry field, however, its value does change when it is padded with leading characters of the number "0": 10000.
5. A trailing position after a decimal point can occur only in a right entry field. The default decimal point lies to the right of the right side of the field, so that no trailing zeros are normally displayed. To designate a position within the field as the decimal place, the edit pattern decimal element should be used (see the section on "Decimal Point Elements", following).
6. The difference between the "Z" and "F" elements is noticeable only when they are used in conjunction with certain other elements: the string of blanks displayed by the "Z" element in leading positions is indistinguishable from the nulls displayed by the "F" element unless they are preceded by some other character. The difference in effect is, however, evident when these elements are preceded by a sign.

1. The following examples show the effects of number elements on the display of both right entry and left entry field.

   Entry: 1234567
   
   Left Entry Field    Right Entry Field    Pattern
   1234567***          ***1234567           **********
   1234567000          0001234567           9999999999
   1234567                1234567           ZZZZZZZZZZ
   1234567                1234567           FFFFFFFFFF
   
   Entry: 0000000000
   
   Left Entry Field    Right Entry Field    Pattern
   0000000000          **********           **********
   0000000000          0000000000           9999999999
   0000000000                               ZZZZZZZZZZ
   0000000000                               FFFFFFFFFF

   In the right entry fields, this entry is treated as having only empty leading positions.

   In the left entry fields, this entry is treated as not having empty leading positions. Since there are no empty positions, the entry is displayed as entered in all of the left entry fields.

2. The entry in this example is composed of six numeric characters. The entry is less than the length allowed by the edit patterns, providing empty leading positions in both right entry and left entry fields.

   Entry: 001100
   
   Left Entry Field    Right Entry Field    Pattern
   001100****          ******1100           **********
   0011000000          0000001100           9999999999
   0011000000                1100           ZZZZZZZZZZ
   1234567                   1100           FFFFFFFFFF

   In the right entry fields, this entry is treated as having six empty leading positions: the four empty positions on the left side of the data, plus the two leading "0"s (zeros) in the entry. The edit pattern determines the characters that will be displayed in the empty leading positions.

   In the left entry fields, this entry is treated as having four empty leading positions: the four positions on the right side of the data. The removal of the two leading "0"s in the entry would change its value; these positions are not considered empty leading positions and the "0"s are displayed as entered.

A.1.2 Sign Elements

The following table lists the sign element symbols and their meanings. Note that correct symbol case is important.

Table A1-2: Element Symbols and Meanings
 

Symbol	Meaning
S	If the value to be printed is negative, print "-" at this position; if it is positive, print "+".
-	If the value to be printed is negative, print "-" at this position; if it is positive, print a space.
N	If the value to be printed is negative, print "-" at this position; if it is positive, print nothing.
|	Distinguishes between positive and negative entries in an edit pattern. When used with two different edit patterns, it formats a positive value according to the first pattern; and negative value according to the second. The edit patterns may include any of the elements described in this chapter.  There may be only one "|" per field.

Notes:

1. During data entry, pressing the "plus" or "minus" keys -while in a field which contains a sign element in its edit pattern - sets the sign in the designated position within the field. Pressing the "plus" or "minus" keys will not enter the sign at the cursor position.
2. Sign elements must be used in conjunction with number elements. An edit pattern composed of a single sign element is invalid.

The following tables show the effects of sign elements, in conjunction with number elements, on data display.

1. The entry in this example is a positive number composed of nine digits. The entry is the maximum length (nine digits and the sign) allowed by the edit pattern.

   Entry: 123456789
   
   Field          Pattern
   +123456789     SZZZZZZZZZ
   123456789      -ZZZZZZZZZ
   123456789      NZZZZZZZZZ

2. The entry in this example is a negative number composed of nine digits. The entry is the maximum length allowed by the edit pattern (nine digits and the sign).

   Entry: -123456789
   
   Field          Pattern
   -123456789     SZZZZZZZZZ
   -123456789     -ZZZZZZZZZ
   -123456789     NZZZZZZZZZ

A.1.3 Decimal Point Elements

The following table gives the decimal element symbol and its meaning. Note that correct symbol case is important.

Table A1-3: Decimal Element Symbols and Meanings
 

Symbol	Meaning
V	Position of the value's decimal point. If "V" is not used, the decimal point is assumed to be at the extreme right of the field.

Notes: This symbol does not produce any output; a decimal point character can be displayed in a field using a character element to print a period (.) in the appropriate position.

Examples

The following example illustrates the effects of decimal elements, in conjunction with numeric elements, on data display.

1. This entry is composed of two numeric characters with a decimal place. Note that the decimal point character is not displayed in the fields.

   Entry: 1.1
   
   Right Entry    Field Pattern
            1     ZZZZZZZZZZ
           11     ZZZZZZZZVZ
          110     ZZZZZZZVZZ

A.1.4 Character Elements

The following table lists the character element symbols and their meanings. Note that correct symbol case is important.

Table A1-4: Character Elements Symbols and Meanings
 

Symbol	Meaning
A	Print a letter in this field position. If there is no data in this field position, print a space.
X	Print an alphanumeric character in this field position. If there is no data in this field position, print a space.
C	Print any printable character in this field position. If there is no data in this field position, print a space.
character	Print the specified character in this field position.
\character	Print the character following the "\" in this field position. If the character would normally be a special character, its special meaning is lost.
@character	Print the character following the "@" sign but do not print it if it would occur in an otherwise empty position, i.e., in a leading position. If the character would normally be a special character, its special meaning is lost.

Notes: The character elements which force the display of a specific character in a specified field must be used in conjunction with elements that format data supplied for the field. It is not possible to specify an edit pattern composed solely of forced-display character elements.

Examples

The following examples illustrate the effects of character elements on data display.

1. Here, the value satisfies the requirements of all the edit patterns and is displayed as entered.

   Entry: asdfasdfas
   
   Field         Pattern
   asdfasdfas    CCCCCCCCCC
   asdfasdfas    XXXXXXXXXX
   asdfasdfas    AAAAAAAAAA

2. In this example, text "12344567890" does not match pattern "AAAAAAAAAA".

   Entry: asdfasdfas
   
   Field         Pattern
   1234567890    CCCCCCCCCC
   1234567890    XXXXXXXXXX
                 AAAAAAAAAA

   This value does not satisfy the requirements of the third edit pattern, which restricts characters to letters. Attempts to display it in the associated field produce an error message. The value satisfies the requirements of the remaining edit patterns, and is displayed as entered.

3. In this example, the text "!@#$%^&*()"does not match pattern "XXXXXXXXXX".

   Entry: !@#$%^&*()
   
   Field        Pattern
   !@#$%^&*()   CCCCCCCCCC
                XXXXXXXXXX
                AAAAAAAAAA

   This value does not satisfy the requirements of the third edit pattern, which restricts valid characters to letters, and of the second edit pattern, which restricts valid characters to letters and numbers. Attempts to display the value in the associated fields are met with an error message. The value does satisfy the requirements of the first edit pattern and is displayed as entered.

4. This example illustrates the effects of forced character elements, in conjunction with other character elements, on data display.

   Entry: asdf
   
   Field        Pattern
   asdf         CCCC@!CCCC@!
   asdf!    !   CCCC!CCCC!

   The entry in this example consists of four characters. The value satisfies the requirements of both edit patterns and is displayed with the specified forced characters in the specified locations. Note that no character is forced in the first field because it would appear in an otherwise empty leading position, which is prohibited by the edit pattern.

A.1.5 Date Elements

The following table lists the date element symbols and their meanings. Note that correct symbol case is important.

Table A1-5: Date Elements Symbols and Meanings
 

Symbol	Meaning
MM	Print the month in this position.
DD	Print the day in this position.
YY	Print the year in this position.

Notes:

1. A date element symbol must consist of at least two characters; a single character is not a valid date element symbol. Date element symbols may be separated by other edit pattern elements. Characters in a date element symbol may not be separated by other edit pattern elements.
2. Date elements can be used with fields of any data type. However, fields of data type DATE must be in the generic date or date(0) format.
3. Edit patterns with date elements assume date data is in universal format (i.e., YYYYMMDD). In fields of a valid DATE data type (i.e., generic date or date(0)), the value will already be in universal format. If the field is of a data type other than DATE (e.g., CHAR or INTEGER) the value must be converted to universal format if it is not in that format already.
4. On data entry, date elements serve only to display templates in the field and to restrict input to digits. The entered date value is not checked for validity and does not have to be entered in universal format.
5. Date elements need not be used in conjunction to produce a complete date. An incomplete date value will be converted to generic format and stored internally with missing date information replaced by "0"s. This is true also for fields in which only a partial date is entered before exiting the field. If the field is re-entered, the date value will be converted back to the appropriate data format for completion.
6. Months must be entered as numerals. Alphabetic characters cannot be entered into field positions associated with date elements.
7. If the year is entered as two digits, the default for the first two digits is "19", i.e., the twentieth century.

The following examples illustrate the effects of date elements, in conjunction with forced character elements, on data display. In all examples, the entry field is of data type CHAR.

1. Since the display fields in this example are of data type DATE, Empress 4GL first attempts to interpret the entry string according to universal format. (It then attempts to interpret it according to the data type of the display field.) After that, it interprets the entry string according to MSDATEPIC. The interpreted value, now in universal format, is run through the edit pattern and displayed.

   Entry: 31/1/92
   
   Field          Pattern
   31/01/92       DD/MM/YY
   31/01/1992     DD/MM/YYYY
   1992           yyyy

2. The display fields in this example are of data type DATE. The entry is a numeric string in universal date format. Since the entry string is already in universal format, it is accepted by the edit pattern.

   Entry: 19920131
   
   Char Field       Pattern
   31/01/92         DD/MM/YY
   31/01/1992       DD/MM/YYYY
   1992             yyyy

3. The display fields in this example are of data type DATE. The entry in this example is a string of alphabetic characters. Since the fields are of data type DATE, Empress 4GL attempts to interpret the string in accordance with the universal format, then in accordance with the field data type, and then in accordance with MSDATEPIC. Since the entry string is not a valid date value, all these attempts fail. The error message indicates that the entered value could not be interpreted.

   Entry: 31/1/92
   
   Date Field       Pattern
                    DD/MM/YY
                    DD/MM/YYYY
                    yyyy

   The expression failed - invalid argument or operand.

4. This example illustrates the effect of entering the date 31/01/92 into each of the fields on the screen. Only the appropriate part of the date is entered into each field.

   Entry: 31/1/92
   
   Field         Pattern
   3_/__/__      DD/MM/YY
   3_/__/____    DD/MM/YYYY
   1___          yyyy

   This screen shows the effects of entering the first numeric character of the appropriate date value. Fields are fully defined on the screen when the first character is entered. Slashes are displayed in the field in accordance with the associated edit pattern. Attempts to enter a non-numeric character are rejected and signalled with a beep.

   No interpretation of data values is performed on entry. If data checking is required, it must be performed in the exit script of each field.