[Robelle-l] test new $edit feature
Neil Armstrong
neil@robelle.com
Fri, 10 Oct 2003 12:06:58 -0400
Dear Robelle-L,
I am looking for any keen Suprtool users to try a new feature called $edit.
Below is the draft docs for
this new feature. If you are interested in trying this then please e-mail
me at neil@robelle.com. I have some
formatting fixes to do to the docs, and some minor content changes, but the
basics are here.
Please let me know if you would like to test out this feature. Internal
testing results have been very
favourable.
Sincerely,
Neil Armstrong
Robelle
$Edit Function
Suprtool now has the ability to format fields using edit-mask
features similar to edit-mask features found in Cobol. Suprtool
employs two distinct types of edit-masks: one for byte type fields
and the other for numeric fields.
The type of mask utilized depends on the source type of the field.
If the source field is numeric, then the numeric edit-mask logic
is applied, if the source field is byte type, then the byte
edit-mask logic and characters apply.
The target field, must always be a byte type field.
Placeholders and Format Characters
An edit-mask consists of "placeholder" characters, such as "9" for
a numeric column, and "format" characters, such as "." for the
decimal place. Sometimes an edit-mask character acts as both a
placeholder and a format character, such as the "$" in floating
dollar signs.
Byte field edit masks
For Byte type fields there are two placeholder characters. These
are:
X place the data in the matching column for the X in the
edit-mask
Z place the data in the matching column unless the data is a
zero, if the
data is a zero then replace with a space
The format characters are as follows:
B (space) / (slash) , (comma) . (period) + (plus) - (minus) *
(asterisk) and a Space.
Suppose you have data that is in ccyymmdd format in an X8 field.
Here is how you would use a "xxxx/xx/xx" mask to format the data:
>in mydate
>form
File: MYDATE.TEST.NEIL (SD Version B.00.00)
Entry: Offset
A X8 1 <CCYYMMDD>
Limit: 10000 EOF: 2 Entry Length: 8
>def formatdate,1,10
>ext formatdate=$edit(a,"xxxx/xx/xx")
>list
>xeq
>IN MYDATE.NEIL.GREEN (0) gt;OUT $NULL (0)
FORMATDATE = 2003/09/24
>IN MYDATE.NEIL.GREEN (1) gt;OUT $NULL (1)
FORMATDATE = 2003/09/24
As you see in the example above, the placeholder character is the
"x" and the "/" is the format character.
You insert a space either by specifying a "B" or by putting an
actual Space character in the edit-mask. An example of inserting
a space might be the formatting of Canadian postal codes (e.g.,
V3R 7K1):
>in postal
>form
File: POSTAL.NEIL.GREEN
Entry: Offset
POSTAL-CODE X6 1
Limit: 10000 EOF: 2 Entry Length: 6
>def post1,1,7,byte
>def post2,1,7,byte
>ext post1=$edit(postal-code,"xxx xxx")
>ext post2=$edit(postal-code,"xxxbxxx")
>list
>xeq
>IN POSTAL.NEIL.GREEN (0) >OUT $NULL (0)
POST1 = L2H 1L2 POST2 = L2H 1L2
>IN POSTAL.NEIL.GREEN (1) >OUT $NULL (1)
POST1 = L2H 1L2 POST2 = L2H 1L2
Z-placeholder for byte-fields
The Z-placeholder character for byte-fields works differently than
when editing numeric fields. For byte type fields, if the Z
placeholder and the corresponding data is "0", then the zero is
suppressed, regardless of the position. This is primarily for
suppression of zeroes in byte type date fields:
ext a=$edit(date-field,"xxxx/zx/zx")
The above edit mask would then edit a byte type date of 20031005,
to be:
2003/10/ 5
Overflow and limits
An edit mask is limited to 32 characters in total for both numeric
and byte type fields. If data overflows the edit-mask, by default
Suprtool will fill that field with asterisks. There is an option
to have Suprtool stop when it encounters a formatting overflow:
>set editstoperror on
will force Suprtool to stop if there is data left over to place
whenapplying the edit-mask. Data in terms of byte-type fields is
anything to the left of the last character in the edit-mask when
applying it to the data that is not equal to a space.
Therefore if your data consists of:
" L2H1L2"
and your edit mask is:
"xxxBxxx"
It is not considered an overflow since there are only spaces to
the left of the "L". If the data was:
" JL2H1L2"
An overflow exception would occur.
Numeric field edit-masks
Our edit-masks for numeric fields are patterned after those in
COBOL. We provide four placeholder characters, each with a
slightly different effect:
"9" - insert a digit from 0 to 9 in this position; if the value
is small, there will be leading zeros
"$" - if you specify more than one dollar sign, you get a
floatingdollar sign.
This means that there can be as many numeric positions as there
are dollar
signs, but if some positions are not needed because the value
is small, the $
floats to the right next to the first digit and the preceding
positions are
blank.
"*" - if there are enough digits in the value, the * position
is replaced
by a numeric digit; if not, an asterisk is printed. Leading
asterisks are
often used for check writing, so that no one can insert a
different value.
"z" - insert a numeric digit at this position; if the number is
small,
there will be leading spaces, not leading zeroes.
For example:
>ext a=$edit(int-field,"$$,$$$.99-")
>ext b=$edit(int-field,"99,999.99-")
>ext c=$edit(int-field,"cr99999.99")
>ext d=$edit(int-field,"-$9999.99")
>ext e=$edit(int-field,"**,***.99+")
>ext f=$edit(int-field,"zz,zzz.99+")
>list
>xeq
>IN FILE1SD.NEIL.GREEN (0) >OUT $NULL (0)
A = $11.11- B = 00,011.11-
C = CR00011.11 D = -$0011.11
E = ****11.11- F = 11.11-
>IN FILE1SD.NEIL.GREEN (1) >OUT $NULL (1)
A = $22.22- B = 00,022.22-
C = CR00022.22 D = -$0022.22
E = ****22.22- F = 22.22-
Signs
As shown in the example above, there are also numerous format
characters for numeric edits, including four ways to specify the
sign.
You can specify a sign, with +, -, or the typical accounting
specification of "CR" and "DB". You will note in the example
above that the "cr" in the mask was up-shifted to be "CR". This
is because the entire mask is up-shifted as the mask is being
parsed.
You can specify more than one sign in a numeric field edit,
although Suprtool will give you a warning, that two sign edit-mask
characters does not really make sense.
Cobol gives a Questionable warning when compiling an edit-mask
with two sign characters. Suprtool, will apply the sign in both
places.
Keep in mind that most data has three states:
1) Postive 2) Negative 3) Neutral
Any neutral data will not display the sign. If you specify a "+"
sign in the edit-mask and the data is negative, it will of course
display a "-" sign.
Decimal Places
For numeric-type edits, Suprtool attempts to adjust the data
according to the number of decimal places in the edit-mask, when
compared to the number of decimal places defined in the field.
For example if the data field has one decimal place, and the edit
mask has two decimal places, then the data is adjusted:
Data and Edit mask:
102.3 ZZZZ.99
will result in the final data being:
102.30
Similarly, if the data has three decimal places and the edit-mask
only has two, then the data will be rounded appropriately with the
same rules as outline in the $number function.
You can specify more than one decimal place in an edit-mask,
however, Suprtool will print a warning and it will utilize the
right-most decimal place for data alignment.
The decimal place character will be defined by the value of the
character defined by:
>set decimalsymbol "."
If you define another character as the decimal symbol, Suprtool
will use that character as the point to align the decimals. If
you define a decimal symbol that is not an allowed edit-mask
character with set decimalsymbol, Suprtool will assume that the
field has zero decimal places and adjust the data accordingly.
Currency and Dollar signs
Suprtool edit-masks support both fixed and floating dollar signs.
Logic for floating dollar-signs will be invoked if more than two
dollar signs are defined in the edit-mask.
A floating-dollar edit mask attempts to but the dollar sign at the
left most position of the significant data. For example if you
have the following data and edit mask:
0001234.54 $$$$$$.$$
the data would end up as:
$1234.54
Suprtool will not however, put the dollar sign to the right of the
decimal place. If you had the same edit mask and the data was,
.09, the data would end up being formatted as:
$.09
Similarily, the $edit function will attempt to place the dollar
sign correctly in most cases. For example Suprtool will not
format data in the form of:
$,123.50
Suprtool, does attempt to fixup these cases and would format the
data in the following manner:
$123.50
Overflow and floating dollars
If the amount of numbers in the data is equal to the number of
placeholder dollar signs, then the dollar sign is dropped and not
added to the edited field.
12345.50 $$$$$.99
would result in:
12345.50
Set CurrencySymbol
If Set CurrencySymbol is not equal to "$", then after the
formatting has been applied, whatever symbol(s) are defined within
the set command, are used to replace the "$" symbol in the data.
For example, if you have the Currency symbol set as "CDN".
>set currencysymbol "CDN"
Suprtool will replace the "$" after the edit-mask has been applied
with CDN, provided there is room to the left of the dollar-sign.
It is recommended that if you are using multiple characters for
the dollar symbol that you leave enough characters to the left of
the symbol.
For example if the CurrencySymbol is defined as CDN, then you
should leave two spaces to the left of a fixed dollar sign
definition. If there is not enough room, to put in the currency
symbol then the dollar symbol is blank.
Overflow and limits
An edit mask is limited to 32 characters in total for both numeric
and byte type fields. If data overflows the edit-mask, by default
Suprtool will fill that field with asterisks. There is an option
to have Suprtool stop when it encounters a formatting overflow:
>set editstoperror on
will force Suprtool to stop if there is data left over to place
when applying the edit-mask. Data in terms of numeric-type fields
is anything to the left of the last character in the edit-mask
when applying it to the data that is not equal to a "0".