$Edit
The $Edit function performs numeric and alphanumeric editing. This function returns a string modified according to a user-specified edit pattern.
Description
$Edit enables you to perform the types of editing listed in the following table:
| Type | Provides the ability to edit an input string... |
|---|---|
| Numeric | In a manner similar to numeric editing in COBOL. Note the following differences:
Exponential notation, the scale position character (P), the sign character (S), and repetition notation (the use of parentheses to enclose an integer) are not supported by $Edit. The B character is not supported. However, a blank (a space) in the mask provides the same functionality as the B character. A colon is supported as a simple edit character. Overflow (to the left of the decimal point) is handled by returning a string of # characters. |
| Alphanumeric | By:
Inserting characters at designated points Removing blanks from the input string Truncating the output at designated points either conditionally or unconditionally |
Syntax
The format of the $Edit function is:
$Edit(input, mask [, justification] [, edit-type])
Where:
- input specifies the input data to be edited. The input can be either numeric or string.
If numeric editing is performed, string input is converted to numerics prior to editing.
If alphanumeric editing is performed, numeric input is converted to a string prior to editing.
- mask specifies the edit mask. The mask can be either numeric or alphanumeric. The characters that can be used to define each type of edit mask are discussed in detail beginning with the "$Edit numeric edit mask characters" table, below.
- justification specifies the direction in which the input and mask are processed. Justification options are:
- L for left-justification, the default for alphanumeric editing
- R for right-justification, the default for numeric editing
- edit-type specifies the type of editing. Edit type options are N for numeric editing and A for alphanumeric editing. The default edit type is N.
Alternate syntax
Alternatively, you can invoke $Edit with this format:
$Edit{A | N} (input, mask[, justification])
where the arguments are the same as described above, except that edit-type is specified after $Edit, rather than after the justification argument.
Numeric edit mask
A numeric edit mask can contain up to 255 characters and have as many as 15 digit positions. Justification of the result defaults to right justification for numeric editing. Left justification causes all leading and trailing blanks to be removed from the resulting string. If the result of a numeric edit is all blanks and left justification has been requested, a null string is returned. A numeric edit mask consists of one or more of the characters listed in the following table. The use of the characters within each character type is described after the table.
| Character | Type | Description |
|---|---|---|
| 9 | Data | The position contains a number (0-9). |
| blank | Simple | A blank is embedded in the specified position. |
| 0 | Simple | A numeric zero appears in the specified position. |
| , | Simple | A comma appears in the specified position. |
| / | Simple | A slash appears in the specified position. |
| : | Simple | A colon appears in the specified position. |
| . | Actual decimal | A decimal point (period) appears in the position and specifies decimal alignment. A period can appear only once in a mask. |
| CR | Fixed | CR appears in the output string if the input argument is negative. If the input argument is positive, two spaces appear rather than CR. CR can be specified only once in a mask and must be specified in the right-most position of the mask. |
| DB | Fixed | DB appears in the output string if the input argument is negative. If the input argument is positive, two spaces appear rather than DB. DB can be specified only once in a mask and must be specified in the right-most position of the mask. |
| $ | Fixed or float | A dollar sign appears in the specified position in the output string for a fixed $. For a float $, the position might contain either a dollar sign, a digit, or a space depending upon the location of the float character. |
| + | Fixed or float | The sign of the output string with a fixed + can be either positive or negative, depending on the value of the input argument. A plus or minus sign is placed in the specified position in the output string. For a float +, a plus sign, minus sign, digit, or space might be placed in the output string depending upon the location of the float character. |
| - | Fixed or float | A minus sign is placed in the output string for a fixed - only Float if the value of the input argument is negative. For a float -, a minus sign, digit, or a space might be placed, depending upon the location of the float character. If the input argument is a positive value, a space replaces a minus sign. |
| Z | Suppress | Any leading character position that contains a zero is to be replaced by a space. |
| * | Suppress | Any leading character position that contains a zero is to be replaced with an asterisk. |
| V | Assumed decimal | The position of an assumed decimal point. The V character can appear only once in a character string.The V does not denote an actual character position; space is not reserved for it in storage. |
Each character type (data, simple insertion, actual decimal, fixed, float, suppression, and assumed decimal) is discussed in detail below.
- Data — When a data edit character (9) is used, the numeric value in the input string replaces the appropriate data character in the mask. If the input argument has fewer characters than the mask, a 0 is returned in each unfilled position. For example:
$Edit(2573,'99999')
returns the value:
02573.
- Simple insertion — When a simple insertion character (a blank, zero, comma, slash, or colon) is used, the specified mask positions are reserved and replaced by the appropriate character in the output string. For example:
$Edit(2573478977,'9,999,999,999')
returns the value:
2,573,478,977.
- Actual decimal — When the actual decimal character (the period) is used, the specified decimal position is reserved and placed in the output string and the input string is decimal aligned. For example:
$Edit(25.734,'99999.99')
returns the value:
00025.73.
Note: If the mask contains fewer digits to the right of the decimal point than the input argument, the input argument is scaled by dropping the excess digits to the right of the decimal point.
- Fixed — When a fixed edit character (CR, DB, $, +, -) is used, the specified leading or trailing position is reserved and replaced with the appropriate character in the output string. A fixed edit character can occur only once in a mask. For example:
$EDIT(-457.22,'$999.99CR')
returns the value:
$457.22CR.
Consider the following when using fixed edit characters:
- A mask can contain at most one fixed sign character (+, -, CR, or DB).
- If the edit mask contains a trailing fixed sign character and that character is set to blanks in the result, right justification causes the trailing blank to be retained.
- When a + or - is specified, it must be the first or last character in the mask.
- No more than one $ and one +, -, CR, or DB can be specified within a mask. The $ must either be specified in the left-most position of the mask or be preceded only by a + or -.
- Float — When float edit characters ($, +, or -) are used, the specified positions are reserved in the output string. (A float mask must contain at least two consecutive float characters of the same type.) Float characters can be specified in any leading character position to the left of the decimal point. Float characters also can be specified in any trailing character position to the right of the decimal point only if all digit positions are represented by the float character.
The float character is inserted immediately to the left of either the first significant digit, a digit position specified with a 9, or a decimal point, whichever is furthest to the left. All positions to the left of the inserted float character are replaced with blanks. For example:
$Edit(-8283.56,'$$$$$$999.99CR')
returns the value:
$8283.56CR.
Note the following considerations when using float edit characters:
- Floating $, +, and - characters are mutually exclusive within the mask.
- The float mask can be interrupted by one or more simple characters or by an assumed or actual decimal point. Simple insertion characters to the left of the floating character actually used in the output string are converted to blanks in the output string. For example:
$Edit(-123456.789, '++,+++,999.99')
returns a value of:
-123,456.78.
- If float characters appear in all the numeric data positions and the value of the input argument is zero, the output string contains all spaces. For example:
$Edit(0000.00, '$$,$$$,$$$.$$')
returns a null string.
- Suppression — When a suppression character (Z or *) is used, the specified position is reserved and replaced with the appropriate character in the output string. One or more suppression characters can be specified in a mask; however, Z and * are mutually exclusive.
A suppression character can be specified in any leading character position to the left of the decimal point. A suppression character also can be specified in any trailing character position to the right of the decimal point only if all positions to the right are represented by the suppression character.
$Edit returns the value of the suppression character (a blank for each Z or an asterisk for each *) for each leading position that has a value of 0, stopping at the left-most position that either contains nonzero data or is an actual decimal point.
For example:
$Edit(+84783.56,'$Z,ZZZ,ZZZ.ZZ')
returns the value
$84,783.56. Note that any simple edit characters (a blank, zero, comma, slash, or colon) to the left of the stopping point are replaced with the suppression character (blank or *).In addition, if all data positions in the mask are represented by suppression characters and the value of the input is zero, all characters in the mask (including simple insertion characters) are replaced with the suppression character. For example:
$Edit(0,'$ZZ,ZZZ')
returns all blanks.
- Assumed decimal — When the assumed decimal character is used, the input is decimal aligned. However, the decimal does not occupy an output position. For example:
$Edit(.12345,'999V 99')
returns the value:
000 12.
Note these additional considerations when defining a numeric edit mask:
- The mask must contain at least one occurrence of 9, Z, or * or more than one occurrence of +, -, or $.
- All characters except the assumed decimal character (V) are counted in the size of the output string.
- The special character (.) and the assumed character (V) are mutually exclusive within a mask.
- The $ fixed character and the + or - floating characters are mutually exclusive.
- Floating edit characters and suppression characters are all mutually exclusive.
- Floating edit characters and suppression characters to the left of an actual or assumed decimal point cannot be preceded by the data edit character (9). A suppression character to the left of an actual or assumed decimal point also cannot be preceded by a float character.
- The mask should be large enough to accommodate the input string or truncation occurs. If the mask contains fewer digits to the right of the decimal point than the input argument, the input argument is scaled by dropping the excess digits to the right of the decimal point.
Alphanumeric edit mask
An alphanumeric edit mask can contain up to 255 characters and as many as 255 edit character positions. Justification of the result defaults to left justification for alphanumeric editing. If the input string is a null string, the mask is still processed. If the string is longer than the number of character positions indicated in the mask, the excess characters in the input string are ignored. An alphanumeric edit mask can consist of one or more of these character types:
| Character | Used in alphanumeric edit masks... | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Insertion | Any character can be an insertion character. However, if the insertion character is not a letter (A-Z, a-z), a digit (0-9), or a blank, it must be preceded by an escape character. | ||||||||
| Escape (!) | The escape character indicates that the next character in the edit mask is interpreted literally (as an inserted character rather than as a selection character). The escape character must precede non-alphanumeric insertion characters.
If the justification argument is R (processing from right to left), the escape character must be to the right of the insertion character. If the justification argument is L (processing from left to right), the escape character must be to the left of the insertion character. If the escape character is the last character in the mask, it is ignored. If the escape character is omitted before a non-alphanumeric insertion character, the mask is considered invalid, a null result is returned, and an error message is issued. | ||||||||
| Simple selection | The following characters are considered simple selection characters:
| ||||||||
| Special selection | The following characters are considered special selection characters:
|
When a special selection character is used, truncation is handled in the following manner:
- The processing direction (in the direction specified by the justification option) determines how the less-than (<) or greater-than (>) character is handled:
When a less-than or greater-than character points in the processing direction, it acts as a continuation character and is handled as follows:
- The next remaining input character is placed in the result and the next character in the mask is processed.
- For no remaining input characters, the result is unaffected and the next character in the mask is processed.
- If a less-than or greater-than character points in the direction opposite from the processing direction, it acts as a truncation character and is handled as follows:
- For several remaining input characters, the next input character is placed in the result and the next character in the mask is processed.
- For one remaining input character, that character is placed in the result and the result is truncated after the character.
- For no remaining input characters, the result is truncated after the previous result character.
- The vertical-bar character (|) has the following effect:
- For several remaining input characters, the next input character is placed in the result and the next character in the mask is processed.
- For one remaining input character, that character is placed in the result and the result is truncated after the character.
- For no remaining input characters, a blank is placed in the result and the result is truncated after the blank.
- The underscore character (_) has the following effect:
- If there are several remaining input characters, the next input character is placed in the result and the next character in the mask is processed.
- If there is only one remaining input character, that character is placed in the result and all subsequent insertion characters are replaced with blanks.
- If there are no remaining input characters, a blank is placed in the result and all subsequent insertion characters are replaced with blanks.
Examples
Example 1
This example illustrates the use of a right-justified edit mask to format a phone number with an area code:
$edit(6171234567,'(!+++)! >++-!++++','R','A')
results in the following output:
(617) 123-4567
Example 2
If the same edit mask were used for a string that did not contain an area code, as shown below:
$edit(2344567,'(!+++)! >++-!++++','R','A')
the following output would result:
234-4567
Example 3
This example illustrates the use of a left-justified edit mask for formatting phone numbers, some of which have extensions of two, three, or four digits:
$edit(%phone,'!(+++!) +++!-+++ EXT ++++',,'A')
The value of the input argument and the output that would result from using the preceding example are listed in this table:
| Input | Output |
|---|---|
|
61712345671111 |
(617) 123-4567 EXT 1111 |
|
2122344567 |
(212) 234-4567 |
|
516765432134 |
(516) 765-4321 EXT 34 |
Error conditions
Certain errors that can occur when using $Edit produce the following results:
- A null string is returned if the input argument or edit mask is omitted, or if the edit mask is invalid, or if data is incompatible with the edit type (for example, alpha data when the edit mask is numeric).
- The default for the type of editing indicated by the edit mask is used if the justification option is invalid.
- A string of # characters (with a length equal to the number of output positions in the edit mask) is returned if a numeric editing overflow occurs to the left of the decimal point.
Other error conditions for $Edit generate a Model 204 error message.