Robelle Tech: Numeric Formatting in Suprtool

October 2003

Get the most out of your Robelle Tools

New: Numeric Formatting in Suprtool

By Neil Armstrong

What with customers migrating applications or re-engineering them for a homesteading future with fewer budget resources, there is a lot of demand for enhancements to Suprtool that allow more report-related and data-export features. For example, we recently added $Number to convert ASCII numeric values to Binary, and Clean to remove invalid characters from ASCII fields.

Now we are adding $Edit, a function to format output fields with a COBOL-like edit-mask. This means that you will be able to have floating dollar signs and all the rest. Suprtool’s new edit-masks come in two styles: one mask for byte-type fields and another mask for numeric fields.

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-Type Formatting

For example, 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) >OUT $NULL (0)
FORMATDATE = 2003/09/24

>IN MYDATE.NEIL.GREEN (1) >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.

For byte-type fields, the only placeholder character is the “x”. The format characters are as follows:

B (space) / (slash) , (comma) . (period) + (plus) - (minus) * (asterisk) and Space.

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

Numeric-Type Formatting

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 several dollar signs, you get a floating dollar 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-

Numeric Format Characters

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.

Open Design Questions – Please Help

We have two small dilemmas in designing this new $edit feature. The first is the dollar sign. Not all countries use the US dollar symbol. However, most people we know who use COBOL, still use the dollar sign in the edit mask.

So for our European friends, how do we use the Euro symbol in the output, when the “$” sign is in the mask? Our current thought is to have a Set command that replaces the “$” in the output with alternate character(s), after the mask has been applied to the data.

If you wanted “CDN” to print instead of the dollar sign you could add the following to your task: >set dollarsign “CDN”

This would mean that field a, in the above example would look as follows: CDN11.11- although it would probably make more sense to use a trailing “$” sign in this case (e.g., zzzz.99-$), so the data would be formatted as 11.11- CDN

Of course, we don’t really need the Set command, since you could insert “CDN” to the output by specifying the following extract command: >extract “CDN”

So, do you think we need to provide this Set Dollarsign functionality?

The other question is, what to do when a data value overflows the size of the edit mask? Often edit masks are not large enough to hold the largest possible value for a numeric field, but the user knows that the actual values will never get that large. For example, many sites could assume that the sales-tax field will never overflow an edit mask like this: zz,zzz.99-

But what if for some reason the sales tax field ends up being over 100 thousand dollars? What should Suprtool do?

One thought is to fill the field with asterisks, as can be done with RPG and similar languages. However, our tech support department voted to have the default action of Suprtool be to stop and throw an error. Suprtool should also show the record/data that overflowed, so that you could take some action to resolve the problem. They also suggest a Set command, to fill the overflow field with asterisks and continue processing, but this would not be the default.

This is our current thinking and plan of attack, but what would you do? I will be posting these design questions to our Robelle-L list server to see what customers think we should do. Please send your comments to neil@robelle.com. We will see what choice users favor when Suprtool 4.7.10 is released, which is the version that contains this enhancement.