The Retrieve Object Lock command is designed to assist when an object
is locked and you suspect there may be a single job holding one or
more locks on the object. If only a single job holds one or more
locks, return variables will describe the job and the strongest lock
to allow a message to be sent. If locks exist from multiple jobs,
the TAA9891 escape message is issued.
If a lock is not in a 'HELD' status, it is not considered to exist.
If no locks exist, the command completes normally and the JOB return
variable is set to *NONE.
If the only locks held are by the current job, the command completes
normally and the JOB return variable is set to *SAME and the other
return parameters will be blank.
When a job requires an object that is locked, there is often not much
that an application can do other than send a message saying 'Use
WRKOBJLCK to see who has the lock'. This is especially true of batch
jobs which by the time this type of message may be read by a human,
it is too late to determine the job that had the lock. Using
RTVOBJLCK can help provide a better error message.
For data base objects, a single job will often hold more than one
lock on the object. RTVOBJLCK does not consider this an error and
will return information about the strongest lock. The strongest lock
is determined by the highest in ascending sequence of:
*SHRRD
*SHRNUP
*SHRUPD
*EXCLRD
*EXCL
A typical series of commands to retrieve the lock information on the
first member of FILEA would be:
DCL &JOB *CHAR LEN(10)
DCL &USER *CHAR LEN(10)
DCL &JOBNBR *CHAR LEN(6)
DCL &QLFJOB *CHAR LEN(28)
DCL &LOCK *CHAR LEN(6)
DCL &LOCKSTS *CHAR LEN(5)
DCL &LOCKTYPE *CHAR LEN(6)
.
RTVOBJLCK OBJ(FILEA) OBJTYPE(*FILE) MBR(*FIRST) +
JOB(&JOB) USER(&USER) JOBNBR(&JOBNBR) +
QLFJOB(&QLFJOB) LOCK(&LOCK) +
LOCKSTS(&LOCKSTS)
MONMSG MSGID(TAA9891) EXEC(DO) /* Mult locks */
/* */
/* Your handling of multiple locks */
/* */
ENDDO /* Mult locks */
IF (&JOB *EQ '*NONE') DO /* No locks */
/* */
/* Your handling of no locks */
/* */
ENDDO /* No locks */
IF (&JOB *EQ '*SAME') DO /* Same job */
/* */
/* Your handling of the same job */
/* holds the only locks */
/* */
ENDDO /* Same job */
/* */
/* Your handling of a single job */
/* (not the current job) holding */
/* one or more locks. */
/* A message could be sent to the */
/* user or QSYSOPR describing */
/* the condition or a message */
/* placed in the job log. */
/* */
Data Base files
---------------
When you open a file for update, a specific member is opened which
causes two locks:
- A lock on the member for *SHRRD
- A lock on the member data for *SHRUPD
Therefore, the typical use on a data base file is to specify a member
name (or *FIRST) on RTVOBJLCK.
RTVOBJLCK escape messages you can monitor for
---------------------------------------------
TAA9891 Multiple locks exist
Escape messages from based on functions will be re-sent.
RTVOBJLCK Command parameters *CMD
----------------------------
OBJ The qualified name of the object to retrieve lock
information for if a single job (not the current
job) holds one or more locks on the object.
The qualified library defaults to *LIBL. A specific
library or *CURLIB may also be used.
OBJTYPE The type of object to retrieve information for. For
the list of supported types, use the command
prompter.
MBR The member of a data base file if any.
*NONE is the default meaning no member exists (the
object type does not have a member) or only the file
object will be checked.
When checking a data base object, a member name
would normally be entered or the special value
*FIRST.
JOB The job name of the single job that holds one or
more locks on the object. If no locks are held,
*NONE is returned. If the only locks are held by
the current job, the return value is *SAME. This is
a required return variable that must be declared as
*CHAR LEN(10).
USER The user of the single job that holds one or more
locks on the object. This is an optional return
variable that if used must be declared as *CHAR
LEN(10).
JOBNBR The job number of the single job that holds one or
more locks on the object. This is an optional
return variable that if used must be declared as
*CHAR LEN(6).
QLFJOB The qualified job name of the single job that holds
one or more locks on the object. This is an
optional return variable that if used must be
declared as *CHAR LEN(28).
LOCK The strongest lock that is held by a job that holds
one or more locks. The strongest lock is determined
by the ascending sequence of the following locks:
*SHRRD, *SHRUPD, *SHRNUP, *EXCLRD, or *EXCL. This
is an optional return variable that if used must be
declared as *CHAR LEN(7).
LOCKSTS The lock status of the strongest lock that is held
by a job that holds one or more locks on the object.
The value that will be returned will be one of HELD,
WAIT, or REQ. This is an optional return variable
that if used must be declared as *CHAR LEN(5).
Note that locks that are not in a 'HELD' status are
not considered to exist.
LOCKTYPE The lock type of the strongest lock that is held by
a job that holds one or more locks on the object.
The value is only applicable to data base files.
The return values will be MBR, DATA, or ACCPTH.
This is an optional return variable that if used
must be declared as *CHAR LEN(6).
Restrictions
------------
Because the RTVOBJLCK command returns variables, it may only be used
in a CL program.
Prerequisites
-------------
The following TAA Tools must be on your system:
CVTOBJLCK Convert object lock
EDTVAR Edit variable
RSNLSTMSG Resend last message
SNDESCINF Send escape information
SNDESCMSG Send escape message
SORTDBF Sort data base file
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
RTVOBJLCK *CMD TAAOBMF QATTCMD
TAAOBMFC *PGM CLP TAAOBMFC QATTCL
|
