TAA Tools
SNDOBJLCKM      SEND OBJECT LOCK MESSAGE               TAALICT

The  Send  Object  Lock  Message  command  sends  a  break  message  to
workstations  that have jobs  with locks on  up to 100  different named
objects.    An option  exists to  end the  jobs  after sending  a break
message.   SNDOBJLCKM can  be used to  inform users  that an  exclusive
function  is  needed  for  the  objects  and  ending  of  the  jobs  is
required.   A listing that describes the  actions taken is displayed or
output.

You must have *JOBCTL special authority to use SNDOBJLCKM.

A typical command would be:

             SNDOBJLCKM    OBJ((LIBA QSYS *LIB)) ACTION(*SEND) +
                             MSG('Please signoff as backup +
                             will begin to LIBA in 30 minutes.') +

Break messages would be  sent to all workstations  where the job has  a
lock on library LIBA.   Because the system places a lock  on LIBA if it
is  on  a  job's  library list,  this  technique  can  be effective  in
determining who is using an application.   If the same job name  exists
for multiple interactive jobs and  each holds a lock on one  or more of
the named objects,  only a single message will be  sent.  See the later
discussion  of 'Multiple  Jobs at a  Workstation'.  A  listing would be
displayed with the list of  users and any batch jobs that hold  a lock.

After  a  15  minute delay,  you  could  send  another message  with  a
stronger wording.

After  a 30 minute time period,  you could end the  jobs holding a lock
by:

             SNDOBJLCKM    OBJ((LIBA QSYS *LIB)) ACTION(*ENDJOB) +
                             MSG('Your job will end in 10 seconds.) +
                             DLYJOBWAIT(10)

If ACTION(*CHECK)  had  been specified,  the  listing  of who  has  the
locks would  be displayed  without sending any  messages or  ending any
jobs.

SNDOBJLCKM  could be run  at a specific  time using a  function such as
the Job Scheduler.

An option exists  to send a  message to  a message queue  if any  batch
job holds  a lock  on the  named objects.   This would  allow a  system
operator  to  take  action   in  addition  to  the  interactive  users.
Another  option  allows an  escape  message to  be  sent if  batch jobs
exist that hold the specified locks.

You may optionally omit specific jobs or users.

While the  system  does place  a lock  on  any library  that  is on  an
active job's library  list, the system does not lock  a program when it
is  called (nor the library where the  program exists).  If the program
opens a data  base file,  a lock  is placed on  the file,  but not  the
library.   Consequently, ending  all locks on  the library  object does
not guarantee that objects within the library are not being used.

SNDOBJLCKM allows  the sending of messages to jobs  for up to 100 named
objects that  have  locks.    Only  a  single  message  is  sent  to  a
workstation regardless of:

  **   If a job has more than one of the specified objects locked.

  **   If multiple  jobs at the  same workstation have  one or more  of
       the specified locks.

For example, you  can send a message if you  have more than one library
that  needs to  be backed  up and the  libraries are  on library lists.
Or you  may want  to backup  a a specific  library that  is on  library
lists, but  other users  may have a  lock on a  specific file  or files
within  the same  library without having  the library  on their library
list.

System lock support
-------------------

Most actions that change objects will  cause a lock to be placed on  an
object while the system  performs a function.  A file that  is open for
any function  will have a lock.  Neither  of these functions will cause
a lock on the library where the object exists.

Locking a library typically  occurs because the library  is on a  job's
library list.

Most locking  occurs implicitly  such as when  a file  is opened.   The
ALCOBJ command may be used to specifically lock an object.

Not  all  object  types may  be  locked.    Different  lock levels  are
available  for different object types such  as *SHRRD (shared for read)
and *EXCL (exclusive).  Not all object types allow all lock levels.

Note the  major exception to  system locking  is with program  objects.
The system does  not lock a program when it is  called (nor the library
where  the program exists).  The only  full proof method of determining
that a  library is  not being  used is  to shutdown  to the  restricted
state.

However,  if you  are  attempting to  back up  a  library, 'read  only'
objects  such as  programs, display  files, and  commands can  be saved
even if they are being used.

What happens with SNDOBJLCKM when a user goes home
--------------------------------------------------

If an interactive user has  gone home and still  retains a lock on  one
or more of the  specified objects, the message sent  by SNDOBJLCKM will
cause  a  break at  the  workstation.   The  message  is displayed  and
remains  there until  either the  Enter key  is pressed  or the  job is
ended.  If  an additional message  is sent by  SNDOBJLCKM, it will  not
be displayed (the first message is still displayed).

If  ACTION(*ENDJOB) is  specified,  the  job will  be  ended after  the
delay  times.   If multiple  jobs are active  at the  same workstation,
you can  end all  jobs by  specifying ADLINTJOBS(*ALL).   Depending  on
the type of jobs, this may take a few minutes.

ENDJOB Command used
-------------------

Some parameters  are passed  thru by  the SNDOBJLCKM  command and  some
take the defaults on ENDJOB.

  **   The  DELAY  parameter  is  passed  thru  from SNDOBJLCKM.    The
       default is the same as on ENDJOB (30 seconds).

  **   The ADLINTJOBS parameter  is passed thru  from SNDOBJLCKM.   The
       default is the same as on ENDJOB (*NONE).

  **   The other  parameters default to  the ENDJOB parameters  such as
       OPTION(*CNTRLD).

Multiple Jobs at a Workstation
------------------------------

Some workstation  devices support a 'hot key' to  switch to a different
job.    These are  considered different  job names  and would  act like
different workstations.

The Operating System  supports two methods  of having multiple jobs  at
the same workstation 1) System Request and 2) Group jobs.

The break  message that  occurs goes to  the workstation  message queue
(not  the user's  message queue).   If there  are multiple  jobs at the
same workstation, this may cause  some confusion as the active job  may
not hold  the lock that  you are attempting to  free up.   Your message
text should account for this.

Because of  the way the system handles jobs that  are not active at the
workstation, you must consider the use of ADLINTJOBS(*ALL).

  **   System request jobs

       A system  request job  may have  the same  or a  different  user
       name.

              If the default  of ADLINTJOBS(*NONE) is used and  the job
              that  is active  has the  lock, it  will  be ended.   The
              inactive job will then become the active job.

              If  the  default  of ADLINTJOBS(*NONE)  is  used  and the
              secondary job  (function  of 'PGM-QMNSYSRQ')  is the  one
              you  are attempting  to end,  it will  not end  until the
              user  transfers back to  the job.   If the  user has gone
              home, the  job will not  end.   If the  user switches  to
              the job  holding the  lock, the job  will be  ended after
              the ENDJOB DELAY limit has been reached.

              If   ADLINTJOBS(*ALL)   is  specified,   all   jobs  will
              eventually end,  but  each  job  uses  the  ENDJOB  delay
              time.

  **   Group jobs

       Group jobs all have the same user name.

              If  the default  of  ADLINTJOBS(*NONE)  is used  and  the
              group  job  that  is active  has  the  lock,  it will  be
              ended.  The next group job will then become active.

              If  the  default  of ADLINTJOBS(*NONE)  is  used  and the
              group that has  the lock  is not active,  it will not  be
              ended  until the  user switches  to that  group job.   If
              the  user switches to  the job holding the  lock, the job
              will be  ended  after the  ENDJOB  DELAY limit  has  been
              reached.   If the user  has gone  home, the job  will not
              end.

              If   ADLINTJOBS(*ALL)   is  specified,   all   jobs  will
              eventually end.

SNDOBJLCKM escape messages you can monitor for
----------------------------------------------

      TAA9891    No locks are held on any of the named objects.
      TAA9892    Batch jobs retain locks
                   Sent if BCHESCMSG(*YES) is specified

Escape messages from based on functions will be re-sent.

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

   OBJ           A list  of up  to 100  objects that  will be  checked.
                 This is  a 3  part parameter  of object, library,  and
                 object  type.   The library  value defaults  to *LIBL.
                 A specific library or *CURLIB may also be used.

                 Only specific object types may be checked.

                 For  example, a library,  a data base  file, or a data
                 area may be checked.   For the complete list,  use the
                 prompter.   While *FILE is a valid  type, locks cannot
                 be  placed on  certain  file types  such as  a printer
                 file.

   ACTION        The action to be performed.

                 *CHECK is  the default  to provide  a  listing of  the
                 jobs  that would  be  sent a  message.   Using  *CHECK
                 allows  you to  review what would  happen if  *SEND or
                 *ENDJOB were specified.

                 *SEND may be specified to  send a string of text  that
                 is specified  in  the MSG  parameter.   When *SEND  is
                 used, the MSG parameter cannot be *NONE.

                 *ENDJOB  may be  specified to  send  a string  of text
                 that  is specified in  the MSG parameter  and then end
                 the  job  based  on  the  ENDJOBWAIT   and  ADLINTJOBS
                 parameters.   When *ENDJOB is used,  the MSG parameter
                 cannot be *NONE.

   MSG           The  text  of  the  message  to  be  sent  as a  break
                 message to workstations where  jobs are holding  locks
                 on one  or more of the  specified objects.  Up  to 256
                 bytes  may  be  sent.   The  message  is  sent to  the
                 workstation message queue.   Only one message is  sent
                 even if:

                 -  Multiple objects  are specified  and  a single  job
                 holds more than one lock.

                 -  Multiple jobs  exist  at the  same  workstation (eg
                 group  jobs) and  one or more  jobs hold  locks on one
                 of the specified locks.

                 The  number  of  seconds  to  wait   after  sending  a
                 message  until  the  ENDJOB  command  is  run.    This
                 differs from the ENDJOB DELAY parameter.

                 The  number of  seconds  to wait  after ENDJOB  is run
                 for a  job before  the  job is  cancelled  abnormally.
                 The value is  passed thru to the  ENDJOB command DELAY
                 parameter.    The  wait  time  allows  jobs  that  are
                 listening for a 'cancel' to cleanup properly.

                 Specifies   whether   additional   interactive    jobs
                 associated  with the  job  being  ended will  also  be
                 ended.    The  value  is  passed  thru to  the  ENDJOB
                 command.

                 If  you have multiple  jobs at a  workstation that you
                 are trying  to end  and the  user has  gone home,  you
                 will  probably   need  to  specify  *ALL.     See  the
                 discussion  of  'Multiple Jobs  at  a  Workstation' in
                 the tool documentation.

                 *NONE is  the  default  meaning  the  additional  jobs
                 will not be ended.

                 *GRPJOB may be  specified to end any  additional group
                 jobs.

                 *ALL  may  be specified  to end  all  additional jobs.
                 This includes group jobs and secondary jobs.

                 A list of  up to 100  job names that  will be  omitted
                 from  receiving   a  message.     If  a   job  (either
                 interactive or  batch) is named that holds  a lock, it
                 will not appear as an exception.

                 The  default is *NONE meaning, no  job names are to be
                 omitted.

                 You may want to  omit certain jobs you know  will have
                 a lock  that will be special cased  by whatever action
                 you need to perform.

                 A  list of up to  100 user names that  will be omitted
                 from receiving a  message.   If a user  is named  that
                 holds a lock, it will not appear as an exception.

                 The default  is *NONE  meaning, no  user names are  to
                 be omitted.

                 You  may want to  use this  to omit certain  users you
                 know will have a  lock that will  be special cased  by
                 whatever action you need to perform.

   OUTPUT        How  to output  the  results.   *  is the  default  to
                 display  the spooled  file if  the command  is entered
                 interactively.   The spooled file  is deleted after it
                 is displayed.

                 If the  command  is  entered  in batch  or  *PRINT  is
                 specified,  the spooled file  is output  and retained.

   BCHMSGQ       Whether  to send a  message to a message  queue if any
                 batch  jobs  hold  a  lock.    *NONE  is  the  default
                 meaning a message will not be sent.

                 A qualified  name of  a message  queue may  be entered
                 such  as QSYSOPR  in  QSYS.   If the  library  name is
                 blank, *LIBL will  be used.   A specific library  name
                 or *CURLIB may be entered.

   BCHESCMSG     A *YES/*NO  parameter for  whether to  send an  escape
                 message if any batch jobs hold a lock.

                 *NO  is   the  default  to  send   only  a  completion
                 message.

                 *YES  may  be specified  to  cause the  TAA9892 escape
                 message to  be sent.    This allows  a time  dependent
                 job  to cause  an  action if  batch  jobs exist  which
                 hold a lock.


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

You must have *JOBCTL special authority to use SNDOBJLCKM.

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

The following TAA Tools must be on your system:

     CHKDUPLST       Check duplicate list
     CHKJOBCTL       Check *JOBCTL special authority
     CHKOBJ3         Check object 3
     CVTOBJLCK       Convert object lock
     EDTVAR          Edit variable
     EXTLST          Extract list
     EXTLST2         Extract list 2
     RSNLSTMSG       Resend last message
     RTVJOBA2        Retrieve job attributes 2
     RTVSYSVAL3      Retrieve system value 3
     SNDCOMPMSG      Send completion message
     SNDDIAGMSG      Send diagnostic 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
   ------        ----    ---------      ----------    ----------

   SNDOBJLCKM    *CMD                   TAALICT       QATTCMD
   TAALICTC      *PGM       CLP         TAALICTC      QATTCL
   TAALICTC2     *PGM       CLP         TAALICTC2     QATTCL
   TAALICTR      *PGM       RPG         TAALICTR      QATTRPG
					

Added to TAA Productivity tools January 15, 2009


Home Page Up to Top