TAA Tools
LOCKMSG       PRODUCING A MESSAGE ON A LOCKED RECORD      TAADBFF

In some  applications, an interactive  user or a  batch job may  not be
able to  access a record for update because  another job has the record
locked.    There  are  many  different  approaches  to  minimize locked
record conditions.

If the  application is  written such that  it cannot  proceed until  it
accesses  the  record,  it is  desirable  to  have  a simple  means  of
identifying  the problem,  informing  the end  user and  then informing
either the user who has the lock or the system operator.

In the interactive  example described  later, an RPG  program is  coded
to  handle  an  error  indication  on a  CHAIN  operation  and  call  a
standard  CL program (TAADBFFC).   The standard CL  program senses that
a  locked  record  condition  exists   and  sends  a  message  to   the
workstation operator describing the problem and offers three choices:

  **   'R' to return to RPG and retry the CHAIN operation.

  **   'J' to  send a message  to the  job which holds  the lock.   The
       message  states  the  problem  and  requests the  operator  (who
       holds  the lock) to end the  transaction.  If the message cannot
       be sent to the  job with the lock (it  may be a batch  job), the
       user is  informed.   The CL program  returns to the  RPG program
       and retries the CHAIN operation.

  **   'S'  to send  a message  to the  system operator  describing the
       problem.   The  CL  program  returns  to  the  RPG  program  and
       retries the CHAIN operation.

The same technique cannot be used in COBOL.

The example  shown may not suit  your needs specifically, but  the same
technique may be used to send messages, delay the job, etc.

Alternatives are provided:

  **   The  same options are  given to the  operator, but the  TAA Tool
       PMTOPR is  used instead  of the  message interface.   PMTOPR  is
       generally  a   more  preferable  interface   than  the   use  of
       messages.  See the TAADBFFE program.

  **   The  same  options plus  an  option  to allow  a  Cancel.   This
       requires  more work  in the RPG  program, but can  be helpful in
       some  situations.   The  PMTOPR  interface  is used.    See  the
       TAADBFFF program.

  **   An option  allowing cancel  is also provided  to send  a message
       to  the submitter if a batch  job runs into a  record lock.  See
       the TAADBFFG program.

Comparison with RPG default
---------------------------

In V2R1,  RPG  changed  the  default  so that  if  there  is  no  error
indicator  defined on  a CHAIN  or  READ operation),  RPG1218 would  be
issued  to the operator.   The message is not  issued until the timeout
occurs  (the  timeout   period  is  specified   by  the  file   WAITRCD
parameter).  The  message states the  fact that a locked  record exists
and provides  the operator with several options.   It does not describe
who has the lock.

The  LOCKMSG solution is  similar in that  it does not  occur until the
timeout occurs.   However, the text of  the LOCKMSG message will  state
what user  has the lock  and the text of  the message is  aimed more at
end users rather than at programmers.

The  RPG default message also  allows the user to  enter many different
responses such as 'G'  which will branch the  program to the  beginning
of calculations.   This can produce some unknown impacts  to a program.
The  LOCKMSG solution  never escapes  from the  program logic  which is
trying to  access a  record for  update until  the  lock is  satisfied.
See the TAADBFFF program for a 'Cancel' option.

Using the LOCKMSG tool
----------------------

Normally, you  will want to  change the WAITRCD  parameter of the  file
when using  this technique.   WAITRCD will default  to 60 seconds.   An
OVRDBF  command with a lower WAITRCD  value would normally be specified
for those programs  which use this technique  so the operator does  not
have to  wait 60 seconds  for a response from  the system.   A value of
5,  10, or 15  seconds is more  appropriate.  You  may also permanently
change the file you are using with CHGPF or CHGLF.

There are two additions required to a normal RPG program:

  **   The  program  status  data   structure  must  be  declared   and
       specified  as 333  bytes.   The  entire data  structure will  be
       passed  to  the CL  program as  a  single parameter.    The data
       structure contains the  message which states  which job has  the
       lock.

       The following data structure spec is needed

     ISTATUS     SDS                            333

  **   A 'Do Until' operation  should be performed and repeated  if the
       CHAIN error  indicator is on.   If the CHAIN  error indicator is
       on, a call is made to the CL program TAADBFFC.

       The  following  'Do  Until'  loop  is  performed  once  and then
       repeated if indicator 55 is on.

     C                     SETOF                     55    Initialize
     C           *IN55     DOUEQ*OFF                       Until off
     C           keyfld    CHAINyourfile             2055  Chain
     C   55                CALL 'TAADBFFC'                 Call
     C                     PARM           STATUS           Pgm status
     C                     ENDDO                           Until off

The RPG program accesses a  keyed record for update.  If the  record is
locked, indicator 55  will be on and the call to  TAADBFFC occurs.  The
'Do  Until' continues  until  indicator 55  is off  (i.e.   the program
keeps trying to access the record until the lock is available).

Indicator 20 is used for the 'not found' condition.

Note that the  program neither  aborts nor  proceeds without  achieving
the lock.  The program stays in a loop of:

  **   Trying to achieve the lock.

  **   If the record is locked, the program will wait.

  **   If the  lock becomes  available during  the WAITRCD period,  the
       CHAIN  is satisfied and  indicator 55 will  be off (the  DO loop
       ends).

  **   If  the  WAITRCD  timeout   occurs,  the  TAADBFFC  program   is
       invoked.  This  causes the message to  be sent or resent  to the
       operator.   When the CL program returns to  RPG, indicator 55 is
       still on and the DO loop is executed again.

Using the standard program in batch
-----------------------------------

If  a  batch  program  invokes  TAADBFFC, a  message  will  be  sent to
QSYSOPR stating the  problem and requesting  a reply.   If no reply  is
received in  120 seconds, the  program returns and the  CHAIN operation
is  repeated.  If the system operator  does not take action for several
minutes, there  will be  duplicates  of the  same message  in  QSYSOPR.
Only the  last message has  meaning when replied  to.  Replying  to the
previous messages will be ignored.

Alternative method for PMTOPR use (TAADBFFE program)
----------------------------------------------------

The  TAADBFFC program  uses SNDUSRMSG.    This causes  a message  to be
sent to the 'Display  Program Messages' display.   This display can  be
awkward to work  with.  Instead of  this approach, a second  program is
available  TAADBFFE which uses  the TAA tool  PMTOPR.  The  PMTOPR tool
displays  a  single display  with  the appropriate  text  and available
choices.  Some  users prefer this type  of interface as opposed  to the
'Display Program Messages' display.

To use  the alternative  method, you  only need to  change the  name of
the program being called in the previously described code.

     C   55                CALL 'TAADBFFE'                 Call

Alternative method with Cancel option (TAADBFFF program)
--------------------------------------------------------

The  TAADBFFF program uses  PMTOPR in the  same manner  as the TAADBFFE
program.  An  additional option  is provided for  C = Cancel.   If  you
use this  option, you  must code for  the Cancel  possibility.   The CL
program  TAADBFFF has  two parameters.   The first  is the  same status
data structure used  in the  other programs.   The second  is a  return
code which will contain the value:

  **   OTHER  -  Some  unusual data  base  error  has  occurred.    You
       probably want to abort and look at the job log.

  **   CANCEL -  The user took the  cancel option.  If you  have only a
       single  record which  is being accessed  as part  of the update,
       branching  to  prompt for  a  new  record  would  be  a  typical
       action.

  **   RETRY - The CHAIN operation should be tried again.

The following would be typical of the RPG coding needed:

     C                     SETOF                     55    Initialize
     C           *IN55     DOUEQ*OFF                       Until off
     C           keyfld    CHAINyourfile             2055  Chain
     C* If an error occurs, use TAA Tool LOCKMSG (pass pgm sts DS)
     C   55                DO                              Some error
     C                     CALL 'TAADBFFF'                 Call
     C                     PARM           STATUS           Pgm status
     C                     PARM           LCKRTN  8        Lock return
     C* Check return values from TAADBFFF
     C* Check for OTHER (some other DB error). Set H1 and abort
     C           LCKRTN    IFEQ 'OTHER   '                 Other error
     C                     SETON                     H1    Set return
     C                     RETRN                           Return
     C                     ENDIF                           Other error
     C* If Cancel, insert the appropriate code
     C           LCKRTN    IFEQ 'CANCEL  '                 If cancel
     C*
     C*   Probably a GOTO to a re-prompt
     C*
     C                     ENDIF                           If cancel
     C* If not RETRY,  abort. TAADBFFF passed unexpected value.
     C           LCKRTN    IFNE 'RETRY   '                 If not retry
     C                     SETON                     H2    Set return
     C                     RETRN                           Return
     C                     ENDIF                           If not retry
     C* RETRY was returned. Do the DO loop again
     C                     ENDDO                           Some error
     C                     ENDDO                           Until off

Alternative method for submitter of batch (TAADBFFG)
----------------------------------------------------

The TAADBFFG is designed to allow:

  **   The  same type  of interface  for an  interactive job  that runs
       into  a  locked record.    The TAA1001  message is  sent  to the
       interactive user  to  respond to  with R,  J,  and S  values  as
       described for the previous alternatives.

  **   A message to the  submitter of the job if a batch  job runs into
       a  locked record.    Options exist  to  R =  Retry, J  =  Send a
       message to the job holding the lock,  S = Send a message to  the
       system operator, or C = Cancel the batch job.

The CL program TAADBFFG has four parameters:

  **   The   STATUS  data   structure   described  for   the   previous
       alternatives.

  **   The wait time after responding J before retrying.

  **   The wait time after responding S before retrying.

  **   A return  code describing how the user responded.   If the value
       is  CANCEL or ERROR, you may add  your own cleanup code (see the
       sample code).    The batch  job  will then  end  with an  escape
       message.

                 The  other  return  codes  describe whether  the  user
                 responded  with R,  J, or  S.  There  is no  user code
                 needed as  the RPG  code should  just  loop trying  to
                 obtain the lock.

The following would be typical of the RPG coding needed:

     I* RPG status data structure
     ISTATUS     SDS                            333

     C****************************************************************
     C*                                                              *
     C*  The wait values determine how long to wait if no response   *
     C*    is received.  After the wait, a retry will occur.         *
     C*                                                              *
     C*  Set the WAIT1 value to the number of seconds to wait after  *
     C*    sending a message to the job with the lock.               *
     C*                                                              *
     C*  Set the WAIT2 value to the number of seconds to wait after  *
     C*    sending a message to the System Operator.                 *
     C*                                                              *
     C**************************************************************
     C                     Z-ADD60        WAIT1   30       Job wait
     C                     Z-ADD90        WAIT2   30       Sys op wait

     C* Sample code for mainline processing
     C                     SETOF                     55    Initialize
     C           *IN55     DOUEQ*OFF                       Until off
     C           keyfld    CHAINyourfile             2055  Chain
     C   55                DO
     C                     CALL 'TAADBFFG'                 Call
     C                     PARM           STATUS           Pgm status
     C                     PARM           WAIT1            Job wait
     C                     PARM           WAIT2            Sys op wait
     C                     PARM           RTNCDE  8        Return code
     C****************************************************************
     C*                                                              *
     C*     Process the CANCEL return code                           *
     C*       Sample code is provided                                *
     C*       You may want to add some code to cleanup               *
     C*                                                              *
     C*       The other return codes of RETRY, SYSOPR, and JOB       *
     C*         stay in the DOUEQ *OFF loop.                         *
     C*                                                              *
     C****************************************************************
     C           RTNCDE    IFEQ 'CANCEL'                   Cancel
     C           RTNCDE    OREQ 'ERROR'                    Cancel
     C* Add your own cleanup code if any
     C           'TAATOOL/'CAT  'ABORT'   CMDEXC 20        Abort
     C                     CALL 'QCMDEXC'                  QCMDEXC
     C                     PARM           CMDEXC           Command
     C                     PARM 20        CMDLEN 155       Command
     C                     ENDIF                           Cancel
     C                     ENDDO
     C                     ENDDO                           Until off
     C* Your code after a successful access of the record for update

Considerations
--------------

The TAADBFFC  program sends a predefined  message in a message  file to
the  end user  who has  timed out on  the locked  record condition.   A
predefined message is used since  it allows a 2nd  level of text.   (An
impromptu message within the  program can only send the  first level of
text).   The message ID is TAA1011 in  TAATOOL/TAAMSGF and it is placed
in the message file as part of the TAATOOL library.

The  TAADBFFC/TAADBFFE  programs  will  abnormally  end  if  the  error
condition is  other than  a  locked record.   You  may  want to  handle
other exceptions in the CL or RPG program.

Testing for locked record conditions
------------------------------------

Testing  for locked record  conditions may  not be  easy in  all cases.
Consider  the use of  the TAA Tool  LCK1STRCD.  It will  lock the first
record in a file.

Command parameters                                    *CMD
------------------

No command interface is provided.

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

The function  is dependent upon  the format  of the  message text  (not
the message data)  of CPF5027.  The  function is coded for  the English
version  of  this  message.    Non-English  versions  may  not  operate
correctly.   A  subsequent  release  could change  the  format  of  the
message in which case the program must be modified.


Security considerations
-----------------------

The 4 CL  programs are created with  USRPRF(*OWNER).  The tool  must be
created  by  someone  who   is  authorized  to  the  SNDBRKMSG  command
(typically   QPGMR).    This  allows  the  end  users  to  execute  the
SNDBRKMSG command within the program.

The program itself has public authority.

There are  no known  security exposures  with the  function unless  you
normally prevent users from sending messages to other users.

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

The following TAA Tools must be on your system:

      PMTOPR       Prompt operator
      SNDESCMSG    Send escape message

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

The tool  is ready to  be included in an  RPG program.   You should use
an  OVRDBF command  to specify  a lower value  for WAITRCD  rather than
using the 60 second default (or use CHGPF/CHGLF).

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

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

   TAAMSGF       *MSGF                         No source
   TAADBFFC      *PGM          CLP         TAADBFFC       QATTCL
   TAADBFFE      *PGM          CLP         TAADBFFE       QATTCL
   TAADBFFF      *PGM          CLP         TAADBFFF       QATTCL
   TAADBFFG      *PGM          CLP         TAADBFFG       QATTCL
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top