[Robelle-l] design decisions for new feature

[Neil Armstrong]

Dear Robelle-L,

Below is an article that will be in the NewsWire and is posted on our web=20
site. However, I want/need opinions on the
design dilemma indicated at the bottom of the article. I am pretty much=20
finished this feature, with the exception of the
two design questions at the end, so please read on and send me your=
 feedback.

All the best,

Neil

With customers migrating applications or re-engineering them for a=20
homesteading future with fewer budget resources, there is a lot of demand=20
for enhancements to Suprtool that allow more report-related and data-export=
=20
features. Recently, for example, we added $number to convert ASCII numeric=
=20
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=20
COBOL-like edit mask. This means you will be able to have floating dollar=20
signs and all the rest. Suprtool=92s new edit masks come in two styles: one=
=20
mask for byte-type fields and another mask for numeric fields.

Placeholders and Format Characters

An edit mask consists of "placeholder" characters, such as =939=94 for a=20
numeric column, and =93format=94 characters, such as =93.=94 for the decimal=
 place.=20
Sometimes an edit- mask character can act as both a placeholder and a=20
format character, such as the "$".

Byte Formatting

For example, lets say you have a data that is in ccyymmdd format in an
X8 field. Here is how you would use a =93xxxx/xx/xx=94 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=3D$edit(a,"xxxx/xx/xx")
  >list
  >xeq
  >IN MYDATE.NEIL.GREEN (0) >OUT $NULL (0)
  FORMATDATE      =3D 2003/09/24

  >IN MYDATE.NEIL.GREEN (1) >OUT $NULL (1)
  FORMATDATE      =3D 2003/09/24

As you see from the example above, the placeholder character is the "x" and
the "/" is an edit mask character.

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

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

You can insert a space either specifying a "B" or by putting a Space 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     (SD Version B.00.00)
        Entry:                     Offset
           POSTAL-CODE          X6      1
     Limit: 10000  EOF: 2  Entry Length: 6  Blocking: 128
  >def post1,1,7,byte
  >def post2,1,7,byte
  >ext post1=3D$edit(postal-code,"xxx xxx")
  >ext post2=3D$edit(postal-code,"xxxbxxx")

  >list
  >xeq

  >IN POSTAL.NEIL.GREEN (0) >OUT $NULL (0)
  POST1           =3D L2H 1L2        POST2           =3D L2H 1L2

  >IN POSTAL.NEIL.GREEN (1) >OUT $NULL (1)
  POST1           =3D L2H 1L2        POST2           =3D L2H 1L2


Numeric Formatting

Our $edit masks for numeric fields are patterned after what is support in=20
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 number is=20
small, there will be leading zeros

  "$"    if you specify several dollar signs, you get a floating dollar=20
sign. This means that there can be as many numeric positions as there are=20
dollar signs, but if they are not all needed because the value is small,=20
the $ floats to the right next to the first digit and the preceding=20
positions are blank.

"*"     if there are enough digits in the value, the * position is replaced=
=20
by a numeric digit; if not, an asterisk is printed. Leading asterisks are=20
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,=
=20
there will be leading spaces, not leading zeroes.

For example,

  >ext a=3D$edit(int-field,"$$,$$$.99-")
  >ext b=3D$edit(int-field,"99,999.99-")
  >ext c=3D$edit(int-field,"cr99999.99")
  >ext d=3D$edit(int-field,"-$9999.99")
  >ext e=3D$edit(int-field,"**,***.99+")
  >list
  >xeq
  >IN FILE1SD.NEIL.GREEN (0) >OUT $NULL (0)
  A               =3D    $11.11-     B               =3D 00,011.11-
  C               =3D CR00011.11     D               =3D  -$0011.11
  E               =3D ****11.11-

  >IN FILE1SD.NEIL.GREEN (1) >OUT $NULL (1)
  A               =3D    $22.22-     B               =3D 00,022.22-
  C               =3D CR00022.22     D               =3D  -$0022.22
  E               =3D ****22.22-

Numeric Format Characters

As shown in the example above, there are also numerous format characters=20
for numeric edits, including four ways to specify the sign.

You can specify a sign, with +, -, or the typical accounting specification=
=20
of "CR" and "DB". You will note in the example above that the "cr" in the=20
mask was up-shifted to be "CR". This is because the entire mask is=20
up-shifted as the mask is being parsed.

Open Design Questions =96 Please Help!

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

So for our Euro friends, how do we get Euro symbol to be used when the "$"=
=20
sign is in the mask. Our current thought is to have a Set command that=20
replaces the "$" with alternate character(s), after the mask has been=20
applied to the data.

If you wanted "CDN" to print instead of the dollar sign you could add the=20
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=20
this case so the data would be formatted as:

   11.11- CDN

Of course, we don=92t really need the Set command, since you could insert=20
"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=20
the edit mask? Often edit masks are not large enough to hold the largest=20
possible value for a numeric field, but the user knows that the actual=20
values will never get that large.

For example, many sites could assume that the sales-tax field will never=20
overflow an edit mask like this:

  zz,zzz.99-

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

One thought is to fill the field with asterisks, as can be done with RPG=20
and similar languages. However, our tech support department voted to have=20
the default action of Suprtool be to stop and throw an error. Suprtool=20
should also show the record/data that overflowed, so that you could take=20
some action to resolve the problem. They also suggest a Set command, to=20
fill the overflow field with asterisks and continue processing, but this=20
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 question to our Robelle-L listserver to see=
=20
what customers think we should. Please send your comments to=20
<mailto:neil@robelle.com>neil@robelle.com - we will see what choice users=20
favor when Suprtool 4.7.10 is released, which is the version that contains=
=20
this enhancement. =20