TAA Tools
RPGVALCHK       RPG VALIDITY CHECKING DEMONSTRATION        TAARPGC

             *********************************************
             *                                           *
             *    This tool will be removed in the       *
             *    next release. You should consider      *
             *    using the Data Base trigger support    *
             *    as a better solution.                  *
             *                                           *
             *********************************************

Validity checking  of new records or  changes to a  data base can  be a
complex  function.   Not only must  the code  be properly  written, but
many error messages must be described.

If  several programs  update the  same data base,  a good  deal of code
may need to be duplicated.

The following describes  a technique that can  be used to simplify  the
coding and assist  in ensuring that only good data  is entered into the
data base.

The  code  is in  a  demonstration form  which  allows you  to  try the
sample as well as using it as a base for your own programs.

Advantages
----------

  **   The programs which change the  data base only need to provide  a
       'hook' to  the specific validity  checking program for  the file
       that  they change.   A few standard  entries are also  needed in
       the workstation file.

       For example, the  typical solution  to error  handling with  DDS
       requires the  ERRMSG keyword and  a unique indicator.   Removing
       the error  handling makes both the display  file and the program
       smaller.

  **   The  validity  checking  functions  are  written  in  a separate
       program  which is  devoted  to  providing whatever  checking  is
       needed  and appropriate  error text.   The  same program  can be
       called  from any  program that changes  the file  using the same
       format.  This tends to  centralize all of the rules regarding  a
       given  file  and  can  give   the  responsibility  to  a  single
       program.

  **   The  validity   checking  program  can  be  written  by  someone
       devoted to  the  task  rather  than someone  who  is  trying  to
       perform both  the production task  and validity checking.   This
       will generally produce a better result.

  **   The  validity checking  routine can  perform whatever  checks it
       needs  to.  If it needs  to access other files  it can do so and
       enforce referential integrity.

  **   The validity checker  is written  in a HLL.   The example  shows
       RPG  code.   Externally described  data  is used  to define  the
       record   passed  from  the  main  program.     No  new  language
       specifications are  needed.   You  can  write the  most  complex
       rules in a language you already know.

  **   The validity  checker can be  changed at  any time.   Unlike DDS
       validity  checking  statements, a  change  in  validity checking
       does not  require re-creating  the file,  copying the  data  and
       rebuilding access paths.

  **   The sample  is written  for an  interactive program.   The  same
       technique could be used by a batch program.

  **   Error  message capability is  provided.   If the  operator makes
       an  error, one line of  text is written to the  display.  If the
       operator does  not understand  the message, a  function key  may
       be pressed to access a second level.

       Both the first  level and second level of  text reside as source
       statements  in an  array within  the validity  checking program.
       Other  techniques  are  possible,  but  this  is   the  simplest
       approach.   The second level of  text is presented in  a subfile
       and  has no reasonable bounds  on size (The limit  of the system
       2nd level text is 3000 bytes).

       Note that  the  validity  checking program  approach  is  better
       than  similar  functions  supplied  in  DDS  because  the  error
       messages   can   be  more   specific.     DDS   error   text  is
       non-specific.    For example,  you see  only  an 'Out  of range'
       statement without  any  details for  the operator  to  determine
       what the correct  range is.  The VALUES  keyword operates in the
       same manner.

       The  system  allows  you  to  define  messages  which  exist  in
       message files  to be  used  in an  application and  can  display
       both a  1st and 2nd  level.  While  this has the  advantage that
       it  can  be  maintained separately  (no  program  re-creation to
       make a  change)  and  allows substitution  values,  it  has  the
       disadvantage of not  being easy to  see what the text  will look
       like to  the operator.   The SEU entry  is much closer  to 'What
       you see is what you get'.

  **   Two  forms of  error handling are  provided.  The  default is to
       lock the  keyboard  and require  the reset  key  to be  pressed.
       The  alternate form  does  not  lock the  keyboard.   The  input
       fields  as  keyed by  the operator  remain  on the  display with
       either technique.

  **   The validity checking program also  provides a solution for  the
       case  where the  main program  is  both reading  and adding  new
       records  to RPG  and  an initialized  format is  needed  for new
       records.   This is  the problem  that is  caused  by RPG  having
       only a  single work area  for fields.   When a read  occurs, all
       of the fields  are filled with data.  When  you are adding a new
       record,  it  is  normal  to  not  add  all  of  the  fields  and
       therefore your program  must initialize  those fields which  are
       not being added in this program.

Disadvantages
-------------

  **   The input field  in error is not highlighted  on the display nor
       is  the cursor placed  on the  field.  It  is up  to the message
       text to describe the error.

  **   Variables cannot be placed into the message text.

  **   The validity  checking is not  enforced for  a given  file.   It
       can  only be  performed if  the  programs that  change the  file
       call  the validity checker.   DFU  programs can change  the file
       independently of the validity checker.

  **   If the  data  base definition  is  changed, you  must  at  least
       re-create the  validity checking program.   If not,  the program
       will  abnormally terminate  (assuming you  take the  default for
       LVLCHK(*YES).    See  the  discussion  of  level  check  in  the
       program logic section.

  **   Only one error message  at a time is displayed to  the operator.
       If  multiple  errors  exist,   the  operator  must  correct  one
       problem  at a  time and keep  pressing Enter  to get  all of the
       error  messages.    Your  code   can  control  which  error   is
       displayed first.

Trying the sample
-----------------

Call the  following program which  has already been  created.   The new
records  will be written  to the TAARPGCP  file in TAATOOL.   This file
is cleared each time the  call to the CL  program occurs.  The  purpose
of writing  records  is to  allow you  to see  that the  initialization
function for fields not used in the program is working properly.

      CALL     TAARPGCC

A  screen  will  be   displayed  with  three  fields.    The  following
describes the validity checking that is coded for each field.

  **   Field A - One character field

              Any entry is valid except W, Y and Z.

  **   A  'Z'  entry will  produce an  error that  says  that Z  is not
       valid.  Second level text exists.

  **   A 'Y'  entry will  produce  an error  that says  that  Y is  not
       valid.  No second level text exists.

  **   A 'W'  entry will  produce an  error, but there  is no  text for
       the message (a programmer error).

  **   Field B - One character field

              It  must be  one of  the following  values (A  B D  E F).
              Second level text describes the valid values.

  **   Field C - numeric field keyed as a digits field

A value less than 5 will  produce an error message.  Second level  text
of multiple pages is available.

If  an error  condition  occurs,  the keyboard  will  be  locked.   The
specific message  occurs on line 24.  A  general message occurs on line
25 (similar to that used by ERRMSG).

Leaving the keyboard unlocked on an error
-----------------------------------------

The code  is very  similar whether  the keyboard  should be  locked  or
unlocked.   A  separate  record  format  (ERRLN2) is  provided  in  the
display file TAARPGCD.   The display file does  not need to be created.

The  RPG  program TAARPGCR  must be  changed to  do  a WRITE  to ERRLN2
instead of ERRLN1.

The RPG program TAARPGCR2 must  be changed so a constant does  not tell
the operator to  'Press reset'.  See the  instructions at the beginning
of the program.

Records written to TAARPGCP
---------------------------

The file TAARPGCP in TAATOOL is defined with fields:

   FLDA   *CHAR LEN(1)    Entered by the program
   FLDB   *CHAR LEN(1)    Entered by the program
   FLDC   *DEC  LEN(3 0)  Entered by the program
   FLDD   *CHAR LEN(1)    Not entered - should be initialized
   FLDE   *CHAR LEN(1)    Not entered - should be initialized
   FLDF   *DEC  LEN(3 0)  Not entered - should be initialized
   FLDG   *DEC  LEN(3 0)  Not entered - should be initialized

Difference between help text and error text
-------------------------------------------

Help  text should normally  be created to describe  the overall concept
of a screen or field and what the specific values are.

Error text  is useful  when  the operator  makes an  error and  a  very
specific statement  must be  made.  Because  only one  line of  text is
shown for  the first level of error text, the  message tends to be very
terse and unlike help text.

The second level  of error text and  general help text  can have a  lot
in common.   For  this reason you  may want  to use  the DDS help  text
facility to  provide for general help (it can  be cursor sensitive) and
use  the  validity checking  function  second level  for  very specific
error situations.

Note that there  is no  link to any  help text for  the field from  the
validity checking second  level error text.  Nor can  the error text be
accessed  by the operator unless  an incorrect entry  in a field causes
the validity check function to be invoked.

A reasonable  solution  might be  to provide  help  text as  you  would
normally.   Then provide  the first  level error  text in the  validity
checking  solution.  You could  either have no second  level or minimal
second level error text.  You  could easily modify the code to  prevent
the  display of  second  level  text,  but probably  a  more  practical
solution is  to use it  where it is  really helpful.   You could modify
the  second level  error text  display to  refer the  user to  the help
text function if your application has provided it.

Another reasonable  approach is  to not  provide any  help for  certain
displays, but only error text if the operator makes an error.

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

The demonstration is ready to run.

The  source for the  programs is  of value  when you  want to  copy the
code  or the concept.   The code is reasonably  well documented and the
program  logic  section  at  the  end  of  this  tool  discussion  will
describe more of the details.

The following are some things to consider when you implement:

  **   You  should decide  on  your strategy  of  whether  to lock  the
       keyboard  or not  lock the keyboard  on an  error.  Some  of the
       sample code should be dropped once your strategy is decided.

  **   The sequence  of steps  for  how to  handle  the screen  in  the
       TAARPGCR  program must  be  followed  properly.   Otherwise  the
       operator  may  lose  the input  fields  that  have already  been
       keyed.

  **   Your   display  file  must  be   specified  RSTDSP(*YES).    The
       validity  checking program  will  write  it's  own  display  for
       second  level  help  and  RSTDSP(*YES)  is needed  to  put  your
       display back to the previous version.

  **   In  most cases there will be  a single validity checking program
       per file.  However, if  you have different formats for the  file
       that are  used to update or  add through, you may  need multiple
       programs.

  **   Your  validity checking rules  may need  to be sensitive  to the
       type of function being performed.   For example, on an add,  the
       program which is adding  may not be inserting all  of the fields
       into  the  record.   In  some approaches,  the  request for  VAL
       should be split into a request to ADD or UPD.

  **   The  validity  checking  program  has  both  skeleton  code that
       needs to be  copied and places  for your checking and  messages.
       Note the  sample shows a GOTO  instruction if an error  is found
       while  performing each logical checking step.   The steps should
       be written  in the sequence  that you  want them  checked.   For
       example,  if  the  operator  makes  multiple  errors,  the  GOTO
       allows  the  error messages  to  occur in  the  sequence  of the
       logic.  Only the first error found will be displayed.

  **   The assignment  of  'Error  IDs'  should be  considered.    A  4
       character  code is  used.   The  sample  shows numbers  such  as
       '0010'.   Any characters are  valid, but you  will probably want
       to  develop a  convention to assist  in determining  new IDs and
       documentation.

  **   The  approach can  be  used  to  provide  referential  integrity
       between  the  file being  changed  and  other associated  files.
       For  example, if  the user  does an  add, the  validity checking
       program could  ensure that  the same  key exists  in a  separate
       file.   Conversely, if the  user does  a delete, you  could pass
       the  delete request  (as  a new  request type)  to  the validity
       checker which  could ensure  that no  records exist  in  another
       file.

  **   The  record  initialization  function (for  new  records  to  be
       added)  is part  of the  validity checking  program.   Because a
       data  structure is  initialized to  blanks, the  Z-ADD operation
       must be used  to initialize each numeric  field.  When the  file
       definition  is  changed to  include  a  new  numeric field,  the
       validity  checking program  must also  be changed  to initialize
       the new field.

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

The following TAA Tools must be on your system

            SNDESCMSG     Send escape message

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

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

   TAARPGCP      *FILE         PF          TAARPGCP       QATTDDS
   TAARPGCD      *FILE         DSPF        TAARPGCD       QATTDDS
   TAARPGCE      *FILE         DSPF        TAARPGCE       QATTDDS
   TAARPGCC      *PGM          CLP         TAARPGCC       QATTCL
   TAARPGCR      *PGM          RPG         TAARPGCR       QATTRPG
   TAARPGCR2     *PGM          RPG         TAARPGCR2      QATTRPG
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top