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
|
