TAA Tools
SETJOBLOG      SET JOB LOG TO FORCE AT END OF JOB         TAALOGA

The job log  default (in a job  description) is LOG(4 0  *NOLIST) which
means you do not get a job log unless a job abnormally ends.

In batch, you  can get a job log by specifying a  value such as LOG(4 0
*MSG).

For  interactive  jobs, if  you specify  SIGNOFF  and take  the default
LOG(*NOLIST),  this  overrides  any  job  specifications  of   the  LOG
parameter.    You would  not  get  a job  log  regardless  of your  LOG
parameter.

If  you write programs that monitor for  all conditions (e.g.  CPF0000)
and allow some form of recovery,  it is often desirable to force a  job
log at  the end  of job  so that a  programmer can  see the  details of
what  went wrong.    For example,  assume you  have a  user  menu which
allows various options.  If the  menu program monitors for CPF0000  and
allows the user to  make another choice, the job  log information could
be lost if the normal signoff occurs.

The  programmer  could issue  the  DSPJOBLOG command  at  the point  of
error,  but  since this  can be  a slow  running  command, a  method of
setting a switch which can be tested at job end may be preferable.

The Set Job Log  function allows you to force  a job log from  either a
batch or interactive job.

Two commands are provided:

  **   SETJOBLOG - Sets  a data area in QTEMP to signal  that a job log
       should  be forced  at end of  job.   This command  would be used
       whenever your  program detects  an unforeseen  error  condition,
       but sill allows recovery.

  **   FRCJOBLOG -  Checks the  SETJOBLOG data  area and  forces a  job
       log if needed.  This command would be issued at job end.

The typical use of the commands is as follows:

          .
          .
        MONMSG       MSGID(CPF0000) EXEC(DO)
        SETJOBLOG
          .
        ENDDO
          .
          .
          .
        FRCJOBLOG
        ENDPGM

SETJOBLOG
---------

When the SETJOBLOG command  is issued, it will create a data area named
SETJOBLOG  in  QTEMP  (if it does not already exist). The value will be
set  to  'Y'.  A completion message is sent to the job log to designate
the point where the SETJOBLOG command occurred.

Interactive use of FRCJOBLOG
----------------------------

An end  user will normally end  a job by executing  the Signoff command
based on  one of  the options  on a  user written  menu  (not a  system
menu).  If  this is the case,  instead of executing SIGNOFF,  you would
execute FRCJOBLOG.

FRCJOBLOG  will test for  the existence of  the SETJOBLOG data  area in
QTEMP  and that it has a value of 'Y'.   If not, the SIGNOFF command is
executed with the default (*NOLIST).

If the data area has a value of 'Y':

  **   A message  is  sent to  a specified  message  queue (default  is
       QSYSOPR) stating that the job log was forced by FRCJOBLOG.

  **   A completion  message is sent  to the job log  stating FRCJOBLOG
       forced the job log.

  **   SIGNOFF is executed with LOG(*LIST)

Note that the job ends normally.

Batch use of FRCJOBLOG
----------------------

The  FRCJOBLOG command would  be executed  at the end  of the  job.  If
the data area  is not  set, the command  ends normally and  the job  is
ended by your normal coding.

If the data area  is set, the LOG parameter is set to  (4 0 *MSG) using
CHGJOB.   Messages are sent as in the interactive  case.  A return then
occurs and the job is  ended by your instructions.   Note that the  job
ends normally.

Using SIGNOFF from a System Menu
--------------------------------

When SIGNOFF occurs  from a system  menu, the FRCJOBLOG command  is not
given control  and the user  can end a  job without getting  a job log.
There are several solutions to this:

  **   Prevent  the user  from entering  such a  command.  This  can be
       easily done if  end users operate  from your own supplied  menus
       (not system supplied).   If you allow use  of the System Request
       menu, the end user could still execute the SIGNOFF command.

  **   Make  the SIGNOFF  command private.   The command  is shipped as
       authorized to the public.  You would need to do the following:

         --   Use  EDTOBJAUT  and  specify  *EXCLUDE  for  the  *PUBLIC
              user.

         --   Authorize  those users  (e.g.   programmers)  who do  not
              use your own menus for signoff.

         --   Make  the  CPP for  the FRCJOBLOG  command  operate under
              adopted authority.   The  program is  already set  to  do
              this  by  the  normal  create  function.    Assuming  the
              SETJOBLOG   function  is  created   by  a  user   who  is
              authorized   to  SIGNOFF,   the  function   will  operate
              correctly if the SIGNOFF command is made private.

  **   Replace the system version  of the SIGNOFF command.   This could
       be  done  by  placing your  own  version  of  the command  in  a
       library  in  front  of  QSYS.    Your  command  could issue  the
       FRCJOBLOG command.

SETJOBLOG Data Area
-------------------

The data area  is created in QTEMP  by the first  use of the  SETJOBLOG
command.  Each use of SETJOBLOG changes the contents to 'Y'.

The FRCJOBLOG command will only force the job log if a 'Y' exists.

There is  no support to change  the value to other  than a 'Y'.   It is
possible  for you to  do this  with a CHGDTAARA  command if you  have a
need.

SETJOBLOG command parameters                          *CMD
----------------------------

The command has no parameters.

FRCJOBLOG command parameters                          *CMD
----------------------------

   MSGQ          The qualified name of a  message queue to be sent  the
                 message describing that  the job log was forced.   The
                 default is *LIBL/QSYSOPR.

                 The intent  of this parameter  is that someone  in the
                 installation  should be made  to find the  job log and
                 look for the problem.

                 It  would  be possible  to  always  specify  the  same
                 queue  which could be  assigned to  a programmer.   If
                 this  is the  case, you  should consider  changing the
                 command default.

Using the Job Log to find problems
----------------------------------

Because  the  SETJOBLOG  command   sends  a  completion  message   with
'SETJOBLOG' in the text,  it is possible to use DSPSPLF on  the job log
and then specify a scan for SETJOBLOG.

The  first use  of SETJOBLOG will  cause the  create of the  data area.
You should  see  the  completion  message  for  the  CRTDTAARA  command
followed by the completion message for SETJOBLOG.

The  messages that  precede  the SETJOBLOG  entry  should describe  the
error condition.

You may  find multiple SETJOBLOG  commands in the job  log.  Therefore,
you  should scan for  multiple occurrences and not  just the first one.

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

None.

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

The following TAA Tools must be on your system:

           SNDCOMPMSG     Send completion message

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

The  tool  is  ready  to  use,  but  you  should  follow  the  previous
instructions  about  the SIGNOFF  command  being  used  from an  system
menu.

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

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

   SETJOBLOG     *CMD                      TAALOGA        QATTCMD
   FRCJOBLOG     *CMD                      TAALOGA2       QATTCMD
   TAALOGAC      *PGM          CLP         TAALOGAC       QATTCL
   TAALOGAC2     *PGM          CLP         TAALOGAC2      QATTCL

Structure
---------

SETJOBLOG
   TAALOGAC   CL pgm

FRCJOBLOG
   TAALOGAC2  CL pgm
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top