TAA Tools
RPGDECSUBR      RPG DECIMAL SUBROUTINE                 TAARPHB

The RPG Decimal  subroutine provides an  RPG solution for  converting a
left  adjusted character  field (with  or  without decimal  position or
separator   characters)  into  a  decimal   field.    Various  validity
checking options exist.

The intent of the  subroutine is to allow  for a character field to  be
prompted  for  or passed  into  a program  that  may  contain either  a
special  value (such  as *START)  or a  decimal value.   The  data will
probably be stored as  a decimal value and  user code must convert  the
special values (such as  converting to -1).  The  subroutine is used to
convert the character string to a decimal value.

The concept  is similar to the function  provided by the system command
prompter that allows  special values in  a decimal field.   The  SPCVAL
keyword allows  a special  value (such as  *MAX) to  be converted  to a
unique decimal value (such as *START = -1).

The subroutine  may also be used whenever  left adjusted character data
must be converted to a decimal value.

A  variety of validity  checking is performed in  the subroutine.  Some
of  the checking  is  standard  (such  as  ensuring 15  or  less  valid
digits).  Some validity checking is based on user options such as:

     - Whether decimal positions exist (or are optional)
     - Whether a zero value is valid
     - A maximum and/or minimum number of digits
     - A maximum and/or minimum value
     - Whether a minus sign may exist (either before or after)

To  use  the  subroutine,  you   must  pass  a  required  input  field.
Optional  values may  also be passed  to allow  for additional validity
checking and  to describe  the data.   When  the  subroutine ends,  the
edited value  is passed back  in a right  adjusted decimal  field along
with  the number of  digits entered.   An error field  should be tested
after each use  of the  subroutine.   If an error  has occurred,  error
text is  provided in a  field that  is suitable to  be displayed to  an
end user.

A demonstration  program exists that  allows the special  value *MAX to
be  entered or a  decimal value.   Messages are returned.   The decimal
value is checked as follows:

         - The value must contain two decimal positions
         - A minimum of 3 digits must be entered
         - A maximum of 9 digits may be entered
         - A maximum value of 8888888.88 may be entered
         - A minus sign is not valid

Call the demonstration program (TAARPHBR)  and pass it up to a  22 byte
character variable (you must use quotes) such as:

            CALL   TAARPHBR PARM('300.23')

                         or

            CALL   TAARPHBR PARM('*MAX')

You can try invalid values such as:

                       300        No decimal positions
                          .00     Less than minimum length
                  12345678.90     More than max length
                       3A0.23     Invalid data
                      -312.34     Minus sign not expected
                   8888888.89     Greater than maximum value

Using the subroutine
--------------------

To use the subroutine, first use CPYTAA:

             CPYTAA     TAAARCMBR(TAARPHBR)

By default,  this will  copy the source  to member TAARPHBR  in QATTRPG
in TAATOOL.

You  can then  use the  copy/browse function  of SEU  to copy  the code
into any of  your programs.   Follow the instructions  within the  code
for how to:

  **   Insert the code at the proper points within your program.

  **   Remove the demonstration code

  **   Add your own unique code

The fields used  within the subroutine and for  communication all begin
with the letters ZD to avoid conflicts with your field names.

For standard  use, there is no reason to understand  the logic of or to
modify the subroutine  code.  Only  the fields passed to  and from  the
subroutine must be understood.

Required input field
--------------------

The  character data  should  be passed  left  adjusted into  the  field
ZDWRKI  which is  defined as  22  bytes.   The field  should  be padded
(with blanks).  A typical calc spec would be:

     C                     MOVELxxx       ZDWRKI    P      Input work

By default, the field is assumed to:

         - Have 0 decimal positions (decimal positions are not valid)
         - Not allow a minus sign
         - Allow up to 15 digits to be entered
         - Allow a 0 value to be valid
         - Not allow separator characters

To change the defaults, see the section on Input Options.

The input field cannot be all blank and cannot have leading blanks.

Return fields (after executing the subroutine)
----------------------------------------------

These  fields are  reset to  zeros or  blanks at  the beginning  of the
subroutine each time it is executed.

   ZDDECA        The answer  in decimal  (right adjusted).   The  field
                 is *DEC  LEN(15 0).   Any decimal  position characters
                 or  separator  characters  have been  removed.    If a
                 minus value was  entered and  a minus  sign is  valid,
                 the field will be negative.

   ZDVLDD        The number  of digits  in the  answer.   The field  is
                 *DEC  LEN(3  0).   This  includes  any  digits to  the
                 right of the decimal position.

   ZDVLDP        The number of  decimal positions in  the answer.   The
                 field  is   *DEC  LEN(3  0).     This  value   may  be
                 meaningful  if you have  specified that the  number of
                 decimal positions is optional.

   ZDERRN        The  error number if any.   The field is *CHAR LEN(2).
                 If  a good  value  is  returned,  the  field  will  be
                 blank.

                 If an  error has occurred, the field  will contain the
                 error  number assigned  to  the error.   Refer  to the
                 ZDERRC and ZDERRT  array data for  the meaning of  the
                 codes and text.

   ZDETXT        The error  text if any.   The field is  *CHAR LEN(60).
                 If  a  good  value  is  returned,  the field  will  be
                 blank.  If an error  has occurred, the field  contains
                 error text  which is  suitable to  be displayed to  an
                 end user.   Refer to the ZDERRC  and ZDERRT array data
                 for the meaning of the codes and text.

Input options (before executing the subroutine)
-----------------------------------------------

These  fields  are  not  reset  by the  subroutine.    If  you  use the
subroutine for multiple user  fields, you may need to vary  the options
before each use of the subroutine.

   ZDDECP        The number  of decimal positions  to be entered.   The
                 field  is *DEC  LEN(1 0).   The default  is zero which
                 means no decimals are valid.

                 For example,  if a  value such  as 2  is entered,  the
                 ZDWRKI value  must have  a decimal  position character
                 and two digits to the right of the character.

                 If  entering decimal positions  is optional,  use a -1
                 value.  The  return result field  ZDVLDP will  contain
                 the number of decimal positions found.

                 See the  ZDDECC field to  define the  decimal position
                 character.

   ZDALWM        Whether  a minus  sign  is allowed.   The  field  is a
                 *CHAR  LEN(4).   The default  is blank  which means no
                 minus sign may exist  (the ZDWRKI value is  considered
                 positive).

                 A  *YES may  be entered  to  allow for  a minus  sign.
                 The  minus sign  may be  to the left  or right  of the
                 value such as -300 or 300-.

                 Any value  other than  *YES is  considered  to be  the
                 default.

   ZDMAXL        The maximum  length in  digits which  may be  entered.
                 The  field is  *DEC LEN(2  0).   The subroutine  has a
                 limit of  15 which  acts as  the default.   A  smaller
                 number may be specified.

                 If a specific  number of digits is required,  both the
                 maximum and minimum should be the same value.

                 If you  move a character field of  length 5 to ZDWRKI,
                 by  definition the  field cannot  contain more  than 5
                 digits.   If  it is  a  5 digit  field,  but you  only
                 allow  an  entry  of  4  digits,  you  should  specify
                 ZDMAXL.

   ZDMINL        The  minimum length  in digits  which may  be entered.
                 The  field is  *DEC  LEN(2  0).    The  default  is  0
                 meaning there is no minimum.

                 If you  specify a value, there  must be at  least that
                 number  of  digits entered  (including  digits  to the
                 right of the decimal position).

   ZDALW0        Whether a zero  value is  valid.  The  field is  *CHAR
                 LEN(3).   The default  is blank  which means to  allow
                 zero  values.  *NO  may be  specified to  prevent zero
                 values.

                 Any  value  other than  *NO  is considered  to  be the
                 default.

   ZDMAXV        The maximum value that  may be entered.  The  field is
                 *DEC LEN(15  0).   The default is  0 meaning  there is
                 no   maximum  value.     After  the   input  field  is
                 converted to a  decimal value, it  is compared to  the
                 maximum  value  (if  one   exists).    The  comparison
                 ignores any decimal positions.

                 For  example, if the largest  allowed value is 888.88,
                 enter a maximum of 88888.

                 If an  error  occurs,  the  text  of  the  message  is
                 'Greater than  maximum  value'.   You can  concatenate
                 up to  22 bytes of  additional text to  the message by
                 using the ZDMAXT field.

   ZDMINV        The  minimum value that may be  entered.  The field is
                 *DEC LEN(15  0).  The  default is  0 meaning there  is
                 no  minimum   value.     After  the  input   field  is
                 converted  to a decimal  value, it is  compared to the
                 minimum  value  (if  one  exists).    The   comparison
                 ignores any decimal positions.

                 For example,  if the smallest  allowed value  is 1.01,
                 enter a minimum of 101.

                 If an  error occurs, the text of  the message is 'Less
                 than minimum value'.   You  can concatenate  up to  22
                 bytes of additional  text to the message by  using the
                 ZDMINT field.

   ZDMAXT        The  additional   text  to  be   concatenated  to  the
                 'Greater  than  maximum  value'  error  message.   The
                 field  is  *CHAR  LEN(22).    The  default   is  blank
                 meaning there  is no additional  text.  The  intent of
                 the  field  is to  allow  you  to tailor  the  text to
                 provide meaningful feedback.   If the user must  enter
                 a 2  decimal position  field with  separators that  is
                 less  than 888888,  you could provide  additional text
                 such as '8,888.88'.

   ZDMINT        The additional text  to be concatenated  to the  'Less
                 than  minimum value'  error  message.   The  field  is
                 *CHAR  LEN(22).   The default  is blank  meaning there
                 is  no additional  text.  The  intent of  the field is
                 to  allow   you  to   tailor  the   text  to   provide
                 meaningful  feedback.   If  the user  must  enter a  2
                 decimal  position  field that  is less  than  100, you
                 could provide additional text such as '1.00'.

   ZDDECC        The  character  to  be  used  to  denote  the  decimal
                 position.   The field  is *CHAR  LEN(1).  The  default
                 is  blank which  means '.' (US  notation).   Any value
                 may be entered.

   ZDALWS        Whether to  allow a  separator character.   The  field
                 is *CHAR  LEN(4).   The default  is blank which  means
                 no  separator  characters  are  valid.   *YES  may  be
                 entered   to  allow  for   a  separator  character  as
                 defined by the ZDSEPC field.

                 Any value  other than  *YES  is considered  to be  the
                 default.

   ZDSEPC        The  character  to be  used  to  denote the  separator
                 character.   The field  is *CHAR LEN(1).   The default
                 is blank which  means ','  (US notation).   Any  value
                 may be entered.

                 Separator characters  are just  ignored in  the field.
                 If  a value such as  3,23.00 is entered,  the value is
                 considered valid and 32300 would be returned.

Typical application solutions
-----------------------------

Assume you  have a  decimal field  in the  data base  and you  want  to
allow the  end user to  enter either  one or more  special values or  a
number.   The special values  will be translated  into specific numbers
for  the field.   For example,  if all of  the data  should be positive
values, you can use either  0 or specific negative values (such  as -1)
to represent the special values.

Or, if  you want to  allow a special  value of *MAX, you  could reserve
an  all 9s value in  the data and  prevent the user  from keying all 9s
by placing a maximum value on the field such as 99998.

Assume the field will also be  used in a change mode where the  current
number  will be  shown  or  the special  value.    Now your  code  must
translate  the  unique value  in the  data  base to  the  special value
(such as  -1 becomes  *MAX).   Actual  values  must be  displayed  left
justified.

If the field has  no editing characters (such as a  decimal point), you
can  use the  ZEDIT TAA  Tool to  edit the  value.   This  provides the
ZEDITL  subroutine  which will  strip off  any  leading zeros  and left
adjust the value.

If the field has  editing characters and you  would like to display  an
edited  value, then  the EDTVAR2  TAA Tool  should be  considered.   It
allows  you to input a decimal  field and a normal RPG  edit code.  The
return value  is  left  adjusted edited  value  which is  ready  to  be
displayed.

The following code  provides an example of how the  subroutines for the
two  tools  EDTVAR2 and  DECRPGSUBR  would work  together  with  a *MAX
special value that is  converted to 0.   The amount  field in the  data
base is  named  AMT.   Note that  both  subroutines require  additional
code that is not shown.

     C* If 0, display *MAX (the display field is DSPVAL)
     C           AMT       IFEQ 0                          If 0
     C                     MOVEL'*MAX'    DSPVAL 22 P      Display valu
     C                     ENDIF                           If 0
     C* If GT 0, display edited value left adjusted
     C           AMT       IFGT 0                          If GT 0
     C                     MOVE AMT       ZEINP            Input field
     C                     MOVE 'L'       ZEEDTC           Edit code
     C                     MOVE '2'       ZEDECP           Nbr of decs
     C                     EXSR ZEEDIT                     Edit subr
     C                     MOVELZEODS     DSPVAL    P      Edited value
     C                     ENDIF                           If GT 0
     C* Display the value and allow user to change
     C*
     C* After user has pressed Enter
     C*
     C           DSPVAL    IFEQ '*MAX'                     If *MAX
     C                     Z-ADD0         AMT              Use 0
     C                     ENDIF                           If *MAX
     C* If not *MAX, use RPG Dec Subr
     C           DSPVAL    IFNE '*MAX'                     Not *MAX
     C                     MOVELDSPVAL    ZDWRKI    P      Input field
     C                     Z-ADD2         ZDDECP           Dec pos
     C                     Z-ADD9999999   ZDMAXV           Max value
     C                     EXSR ZDDECS                     RPG Dec Subr
     C           ZDERRN    IFNE *BLANKS                    Not blanks
     C* User coding to re-display with error text from ZDETXT
     C                     ENDIF                           Not blanks
     C* Good value entered
     C                     MOVE ZDDECA    AMT              DB field
     C                     ENDIF                           Not *MAX

Restrictions
------------

See the previous details.

Prerequisites
-------------

None.

Implementation
--------------

None,  the demonstration is  ready to  use.   To use the  subroutine in
your own application, follow the previous instructions.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   TAARPHBR      *PGM       RPG         TAARPHBR      QATTRPG

The   TAARPHBR  source  is  both  a   working  program  for  use  as  a
demonstration as  well as  containing the  subroutine and  instructions
that should be copied into your program.
					

Added to TAA Productivity tools August 1, 1997


Home Page Up to Top