TAA Tools

The Check Inactive Job  Timeout (CHKINACT) tool provides a  function to
end or  disconnect inactive interactive  jobs.  The  typical example is
where  the user  has walked away  from the  workstation without signing
off.   The  system values  QINACTITV  and QINACTMSGQ  are used  plus  a
standard  program  which  runs  continuously  in  batch.    A  list  of
exception  devices/users may  be specified and  a list  of 'run status'
values may be used  to check whether to perform  an action on the  job.

Assume that you want  to set a standard that if no  activity occurs for
30  minutes at  a workstation,  the job should  be disconnected.   This
would force the user  to signon again  in order to  return to the  same
function.   CHKINACT  allows you  to easily  enforce  the standard  and
still allow for exceptions.

The  tool uses the  system values QINACTITV  for the timeout  value and
QINACTMSGQ  to  define  the TAAINACT  message  queue in  TAATOOL.   The
system will  send messages  to  the message  queue when  a timeout  has

A continuously  running job  CHKINACT is used  to wait for  messages to
arrive.   The  job then  checks a list  for device/user  exceptions and
the 'run status' of the job before taking any action.

A list  of  device/user  names  may  be entered  as  exceptions.    For
example,  if  you  have  a secured  area  for  the  operators  console,
executive  workstations, or a programmer  area, you may  want to ignore
the timeout.

A list of 'run  status' values may be  specified such as DSPW  (meaning
the job is  waiting for workstation input).   Other values such  as RUN
(the  job  is now  running)  would  be bypassed.    A  shipped list  is
provided  of the typical  status conditions that  indicate the user has
walked away.

To  understand the  tool,  you  should  do the  steps  in  the  section
'Testing the CHKINACT function'.

What causes an activity

If  all workstations  are active,  there are  no messages  sent  to the
specified message queue and no action will occur.

Note  that the  system  does not  wake up  at the  end of  the interval
specified and check all jobs  for activity.  Instead, each  interactive
job has a timer that will time out if no activity occurs.

If the user is  keying, but does not press Enter or  a Function key, no
interaction  with the system  occurs and it  would be considered  as no

If a  message  is  sent to  the  workstation  or to  the  user  of  the
workstation, the job is interrupted and it counts as an activity.

If CHGJOB is issued to the job, it counts as an activity.

Testing the CHKINACT function

  1    Assume that you  want to test  the function by using  a specific
       workstation  to test  the timeout.   Determine  the name  of the
       workstation   from   the  signon   display.     Signon   to  the
       workstation with  a  user  profile that  is  not active  on  the

  2    Leave  the   workstation  you   signed  onto  and   perform  the
       following  steps  at  a  different  workstation  as a  different

  3    To ignore the  timeout condition  for other workstations,  check
       the CHKINACT  Application Value  default.   As an *ALLOBJ  user,


       The 'Default  action' should be *IGNORE  meaning you will ignore
       any timeout  messages  for  devices that  are  not  specifically
       found in the file provided by CHKINACT.

  4    As an *ALLOBJ user, enter:


       This creates  the CHKINACTP  (physical) and CHKINACTL  (logical)
       files  in   QGPL  that  will   be  used  to   enter  device/user
       exceptions.     This  CHKINACTP  file   is  created  as  *PUBLIC
       *EXCLUDE.  You  may authorize other  users to display or  change
       the file using EDTOBJAUT.

       CRTINACT  also changes  the  message  queue to  be  used by  the
       QINACTMSGQ system value to TAAINACT in TAATOOL.

  5    Use  the  WRKINACT command  to enter  the  device name  and user
       that you want to test for:


       Use F6 to add a new record and enter it as:

         Seq      Device       User       Action
         ---      ------       ----       ------

         010      xxxxx        yyyyy      *DSCJOB

       Enter the device and user name to test with.

  6    As an *ALLOBJ  special authority user,  change the system  value
       for QINACTITV  to the  lowest timeout  value of  5 minutes  (the
       lowest  possible value).  Note  that the time is  in minutes and
       not in seconds.


       Use Option 2 and change the value to 5.

  7    Submit the batch  job to  listen for the  timeout messages  with
       the command:


       This submits the CHKINACT  job to the QSYSNOMAX job  queue which
       is attached to the QSYSWRK subsystem.

  8    If  the device  specified  is inactive  for 5  minutes,  the job
       will  be disconnected.   You  should see  the Signon  prompt for
       the job with the  CPI1131 message displayed describing  that the
       job was disconnected.

  9    End the CHKINACT job by entering:


  10   Display  the  CHKINACT  spooled  file  that was  created.    You
       should  see a line  for each device  that was  inactive for more
       than 5 minutes.   For the specific test  device, you should  see
       that the action was *DSCJOB (disconnected job).

  11   For further  testing you  may use  WRKINACT to  set a  different
       action for the device and/or name other device/users.

       Use SBMINACT to submit the batch job.

       You  may modify the actions  or devices with  WRKINACT while the
       CHKINACT job is active.   Any changes to  the file will be  used
       when the next timeout message occurs.

  12   Use  ENDINACT when  you  are  finished  and review  the  spooled

  13   It  is recommended  that you  reset  the QINACTITV  system value
       until you are ready to place CHKINACT tool into production.



   CRTINACT      Creates  the required CHKINACT files  in QGPL and sets
                 the QINACTMSGQ to TAAINACT  in TAATOOL.  This  command
                 is only used once.

   WRKINACT      Allows  entering exception  device/user  names into  a
                 file  and provides a  print option of the  data in the

   SBMINACT      Submits  the  CHKINACT  job  to  batch.    This  is  a
                 continuously  running job.   An  optional outfile  may
                 be output (See section on 'SBMINACT Outfile'.

   ENDINACT      Ends the  CHKINACT job.  A listing  is output with one
                 line for each job  that had a  timeout and the  action
                 that was taken.

Ending versus Disconnecting a job

When a timeout occurs, the action to be taken can be:

           *IGNORE        Continue processing
           *ENDJOB        End the job (ENDJOB command)
           *DSCJOB        Disconnect the job (DSCJOB command)

Disconnecting a job causes  the Signon prompt to be  displayed with the
CPI1131 message.   If the user  signons on, he continues  where he left
off.   The QDSCJOBITV system value determines how  long a job can be in
a disconnected  state before it  is ended.   The  shipped value is  240

Some jobs cannot  be disconnected.  Message CPF1358 may  be used by the
system when a job cannot be disconnected.

Ending  may  be  helpful and  may  cause problems.    For  example, the
operator may walk  away from  the workstation with  half a  transaction
entered (some  records may have been  updated) and record locks  may be
held.   Ending the  job will  release the locks,  but may leave  half a
transaction on the system.

If *ENDJOB  is  specified,  all  jobs  at  the  workstation  are  ended
including system request  and group jobs.  The  ENDJOB ADLINTJOBS(*ALL)
function is specified.

Which way to default

You must make  a decision for the default to  use for any timeouts that
occur  where  the  device/user  is not  specifically  identified  as an

  **   You  may use  a  default  of  *DSCJOB or  *ENDJOB  and  describe
       specific exceptions.   For example,  device DSP01 or  user JONES
       should  never be  disconnected if  a timeout  occurs.   For most
       situations this  would  be the  better  choice as  you  probably
       want  a  standard   of  'disconnect'  or  'end'   and  note  the
       exception device/users.


  **   You  may use  a  default of  *IGNORE (ignore  any  timeouts) and
       describe specific exceptions.   For example,  only device  DSP01
       or user JONES will be disconnected if a timeout occurs.

The  shipped default  is  *IGNORE.   If  you are  going  to change  the
default  to *DSCJOB or  *ENDJOB, it is  recommended that you  leave the
default  at *IGNORE, enter  the exceptions with  WRKINACT, and test for
a few  days.  The  listing produced  when ENDINACT  is used will  allow
you to  see the jobs that  are experiencing timeouts and  better tailor
the exceptions.

To change the default, enter:


Any  changes to  the Application  Value will take  place when  the next
timeout message is processed.

Entering exceptions with WRKINACT

The  WRKINACT  command  allows  you   to  enter  exceptions  into   the
CHKINACTP file  in QGPL.   You may  enter device  names and  user names
plus  the action to be  taken if a  timeout occurs.  The  action can be

The 'Seq'  field  controls the  order  in  which the  entries  will  be
tested.  The  first entry that  matches the device and  user determines
the  action and  no other  entries will  be processed  once a  match is
found.   For  example, you  would want  a device  name with  a specific
user name  to be  tested before the  entry for  the same  device and  a
user  name for  *ALL.   Specific user  and device  names should  have a
lower sequence value than generic or *ALL entries.

Directly  attached workstations have a specific  name that is used each
time a  signon occurs.   PC devices  may signon  using TCP  and have  a
different  name each  time signon  occurs.   Depending on  how your  PC
devices  are  attached and  configured, you  may  be able  to  assign a
name.  See the section on 'PC Device names'.

The device and  user names entered  may be specific,  generic, or  *ALL
(meaning any user).

      Device     User     Description
      ------     ----     -----------

      DSP01      JOE      Specific device and specific user
      DSP01      JO*      Specific device and a generic user
      DSP01      *ALL     Specific device and any user
      DSP0*      JOE      Generic device and specific user
      DSP0*      JO*      Generic device and generic user
      DSP0*      *ALL     Generic device and any user
      *ALL       JOE      Any device and a specific  user
      *ALL       JO*      Any device and a generic  user
      *ALL       *ALL     Invalid

You may make any  changes using WRKINACT while the  CHKINACT is active.
The changes  will be used  when the next timeout  message is processed.

The  order  of the  records in  the  file (sequence  number) determines
which entry is  used.  The  first entry that  meets the criteria  would
determine the action to be taken.

Implementing the CHKINACT tool

  **   It  is  assumed  that  you  have  entered  the  exceptions  with

  **   Ensure the system value is set for the proper timeout.


       Use Option 2 to change the value to your standard.

  **   Ensure the Application Value default is set correctly:


       For  typical  use,  you  will need  to  change  from  *IGNORE to
       either *DSCJOB or *ENDJOB.

  **   Enter the SBMINACT  command.  This command  may best be  entered
       as part of your startup program as:


  **   You  may end  the CHKINACT  job with  the command  ENDINACT.   A
       listing is  output with one line for  each timeout that occurred
       and the action  taken.  The  listing may be  reviewed to see  if
       any errors occurred.

Other CHKINACT options

  **   The CHKINACTP  file in QGPL  is set to  *EXCLUDE to prevent  the
       *PUBLIC from  viewing the file.   You may  authorize other users
       to display or change the data in the file using EDTOBJAUT.

  **   When  a  CPI1126 timeout  message  is received  by  the CHKINACT
       job, the 'run status'  of the job is  checked against a list  of
       values  to determine  if an  action should  be performed  on the

       A  shipped list  of status  conditions includes those  where the
       interactive  user  is  likely  to  have  'walked  away'.    This
       includes  DSPW   which  is   the  typical  condition   when  the
       workstation is waiting for input.

       The  CHKINACT  tool  applies  only  to  interactive jobs.    The
       shipped list does  not include those  conditions which  indicate
       the  application is  still  in control  (such  as MSGQ,  DLYJOB,
       etc.)  Typical interactive  jobs would  not go  into a  wait for
       several  minutes using a command such  as DLYJOB.  The following
       is the shipped list:

             DSPA     Waiting for WS input in an activity level
             DSPW     Waiting for WS input
             MLTA     Waiting for I/O completion from multiple files
                        in activity level
             MLTW     Waiting for I/O completion from multiple files
             MXDW     Waiting for I/O comp from a mixed device file

       You may review the  possible 'status' conditions that a  job may
       be in  by using  WRKACTJOB and requesting  help on  the 'status'

       Note  that the values SRP (a group  job is not the current group
       job) or SRQ (a system  request job is waiting to be  transferred
       to) are  not in the  shipped list.   This prevents  ending these
       jobs  because the user  may have a  different active job  at the

       To modify the shipped list, as an *ALLOBJ user, enter:


       The SBMINACT  command supports  the EFFTIME  parameter which  is
       designed  to allow  a  specific time  of  day processing.    For
       example,  if  you only  want  the CHKINACT  function  to operate
       after normal business hours or on the weekend.

Other comments

  **   When  the CHKINACT  job is  submitted, all  existing messages in
       the TAAINACT message  queue are cleared.   This prevents  action
       on old messages  if the CHKINACT was not  running for some time.

  **   If  DSCJOB is used  and there  are group jobs  or system request
       jobs active on  the same device,  disconnecting the current  job
       causes  the signon  prompt to  appear.   The other  jobs may  be
       re-accessed if the user signs on.

  **   The system  sends CPI1131 to the Signon  display if the user has
       been disconnected.   This describes  what has  occurred and  the
       message can be seen without signing on.

  **   If a job  is ended (using ENDJOB),  all jobs on the  same device
       (group jobs or system request jobs) are also ended.

  **   If  a job is  ended or  disconnected, a  message is sent  to the
       device  message queue  explaining why.   The user  would see the
       message when  signon occurs if  the device  message queue is  in
       break mode or if DSPMSG is used.

  **   If  a job  is disconnected,  when the  user signs  back  on, the
       message CPC1194 is sent to his message queue.

  **   If  WRKACTJOB is used,  you would normally see  the CHKINACT job
       is active with program  TAAJODJC11 running as a  BCH job with  a
       status of MSGW (waiting for a message to process).

  **   The  CHKINACT job  will only  process CPI1126  messages sent  by
       the  system when a timeout  occurs and the  TAA9891 message sent
       when ENDINACT is  used.   If any  other message  is received,  a
       message is  sent to  QSYSOPR describing  the error (the  message
       text includes the SENDER information).

  **   If a  job is disconnected or ended, a  message will exist in the
       CHKINACT  job log.   The job is set  for JOBMSGQFL(*WRAP) so the
       job will continue to run even  if the job log is full.   The job
       log is not output if the CHKINACT job completes normally.

  **   If ENDJOB  or DSCJOB fail, a  message is sent to  QSYSOPR and an
       error is noted on the listing.

Security considerations

  **   You must have *ALLOBJ authority to use CRTINACT.

  **   The  CHKINACTP file is set to  *PUBLIC *EXCLUDE to prevent other
       users from displaying the file.

  **   The  WRKINACT  command  requires   the  user  to  have   *CHANGE
       authority to the CHKINACTP file in QGPL.

  **   The CHKINACT  user space  and CHKINACT  data area  exist in  the
       TAASECURE   library.    The   library  is   shipped  as  *PUBLIC
       *EXCLUDE.  If  you have not  changed the library  authorization,
       an *ALLOBJ user is required to access the objects.

  **   The SBMINACT command is  available to the *PUBLIC.   The command
       is intended  to be placed in the start  up program where *PUBLIC
       authority  is desirable.   If you  want to  control the function
       better,  authorize  the command  to  the  user  of  the  startup
       program (normally QPGMR) and use *PUBLIC *EXCLUDE.

  **   The  SBMINACT command  will  fail in  the  CHKINACT job  already

  **   The   TAAJODJC11  program  that  is   submitted  to  listen  for
       messages adopts the QSECOFR owner  profile.  This allows  access
       to the CHKINACTP file, the ability to end jobs, etc.


An  optional outfile  exists for  the  SBMINACT function.   The  output
file  (if requested) will  contain the  same information as  appears on
the listing.

The intent of the outfile  is to allow you to  query the data for  such
information as:

      - Which users are being disconnected regularly
      - Which users should be considered to be disconnected

The name of the file  output is INACTP.  The model  outfile is TAAJODJM
with a format name of IAAJOBR.

PC Device Names

Most  terminal emulators are  capable of  specifying the  system device
name.   If a device  name is not requested  by the emulator, the system
assigns the name QPADEVnnnn where nnnn is a four digit number.

The  following  discussion  provides  details  about   configuring  the
system's  Client   Access  emulator   and  the  similar   IBM  Personal
Communications  (PCOMM emulator).  Other  emulators generally have some
degree of  device  name  customization, usually  accessible  through  a

The  system's  Client  Access   and  the  IBM  Personal  Communications
(PCOMM)   emulator   offer  flexible   device   naming   through  their
"Configure PC5250" dialog.

In  Windows(tm),  you   can  get  to   the  Client  Access   emulator's
"Configure PC5250"  dialog by  clicking Start,  Programs, i5/OS  Client
Access Emulator,  Start or Configure a Session.   "Configure a Session"
takes  you  directly  to  the  "Configure  PC5250"  dialog.    "Start a
Session" lets  you select  which  session to  open.   When the  session
opens, click communication, then configure.

On  the  left side  of  the dialog,  under  Workstation  ID, are  three
choices  (radio   buttons):  Computer  Name  (Windows  Computer  Name),
Windows user name, or a user specified name.

Selecting one of these sets the  base workstation ID.  In the  examples
that follow, let's  assume that we have used the  Windows Computer Name
and it is MARY.

On  the  right side  of the  dialog,  under Workstation  ID,  are three
check boxes.   At connection  time, these modify  the base  Workstation
ID as follows:

If "Add  prefix to indicate printer  of display" is  checked, a P  or S
is  added at the  front of  the workstation  ID to indicate  printer or
workstation.   If only this box  is checked, the workstation name would

If "Avoid  duplicate names  on this  workstation" is  checked, a  short
session  ID  (A or  B  or  C, etc.    )  is added  to  the  end of  the
workstation  ID.  If  only this  box is checked,  the workstation names
using this session would be MARYA, MARYB, etc.

If "Avoid  duplicate  names  with  other workstations"  is  checked,  a
character in  the range  of 1-9  and A-Z  is added  at the  end of  the
workstation  ID.  If  only this box  is checked, the  workstation names
using this session  would be MARY1,  MARY2, ...   MARY9, MARYA,  MARYB,

If  both  "Avoid  duplicate  names  on  this  workstation"  and  "Avoid
duplicate  names  with  other  workstations" are  checked,  workstation
names using this session would be MARYA1, MARYA2, MARYA3...MARYZZ.

If  the session is to be  used to make multiple concurrent connections,
it is  necessary  to use  one  or both  of the  last  two check  boxes.
Otherwise, whenever the  workstation ID is is use,  attempts to use the
session  for additional  connections will fail  with a  "device in use"

In our example,  assuming a base  workstation name of  MARY and one  or
both of  the "avoid duplicate names..."  check boxes, the  generic name
MARY*  can be  used  to control  this tool's  actions for  this  set of

CHKINACT escape messages you can monitor for

The ENDINACT command sends two escape messages:

      TAA9893    The CHKINACT job is not active

The other commands only resend messages from based on functions.

CRTINACT Command parameters                           *CMD

   SRCLIB        The  source  library  to  use  for  the  QATTDDS  file
                 source.  The  default is *TAAARC.   If a  full license
                 exists, the  source is used from the  TAA Archive.  If
                 a  demonstration  license exists,  the source  is used
                 from the QATTDDS file in the TAATOOL library.

                 A specific user library  may be named, but the  source
                 file must be QATTDDS.

WRKINACT Command parameters                           *CMD

   OUTPUT        How  to output  the  results.   *  is  the default  to
                 display   the  results  if   the  command  is  entered

                 If the  command  is  entered  in batch  or  *PRINT  is
                 specified, the results are printed.

SBMINACT Command parameters                           *CMD

   USER          The user profile  name of the job which  runs in batch
                 to  check for inactive  job timeouts.   The default is
                 *CURRENT for the user who enters SBMINACT.

                 A specific user  profile name  may be  entered if  the
                 user  of the  command is  authorized  to the  profile.
                 This  will allow  the messages  that  are sent  to the
                 jobs  being  ended or  disconnected  to be  sent  by a
                 user  profile  that  is  not  the  user  that  entered
                 SBMINACT.   For example,  you may choose  to set  up a
                 specific  user   profile  for  this  function  so  the
                 messages are more anonymous.

   EFFTIME       A 2 part parameter for  the start and end time of  the
                 CHKINACT  function.   The default  is  the entire  day
                 (000000 to 235959).

                 Specifying  a time  range will  allow  you to  run the
                 CHKINACT function during a  specific time of day  such
                 as after normal working hours or on the weekend.

                 If the  start time specified  is greater than  the end
                 time,  it  is assumed  that  the job  is  to run  over
                 midnight.   For example,  if EFFTIME(100000 060000) is
                 entered, the  start time will  be at  10PM and end  at

                 If you  specify an effective  time and do not  end the
                 CHKINACT  job, the job  will continue  and check again
                 the next time the start time is reached.

   OUTLIB        The library in which the  INACTP file will be  placed.
                 The  default  is  *NONE  meaning that  no  outfile  is
                 created.   If the INACTP file  does not already exist,
                 a library must be specified.

                 The model outfile  is TAAJODJM with  a format name  of

   OUTMBR        The member  of the  INACTP file  to be used.   If  the
                 member does  not exist, it  is added.   The default is

   REPLACE       A  *YES/*NO  value for  whether  the member  should be
                 cleared before writing  records into it.   The default
                 is *YES.

                 *NO  may  be  specified  to add  records  to  existing

ENDINACT Command parameters                           *CMD



You must have *ALLOBJ authority to use CRTINACT.


The following TAA Tools must be on your system:

     CHKALLOBJ       Check *ALLOBJ special authority
     CHKNAM          Check name
     CVTTIM          Convert time
     DUPTAADBF       Duplicate TAA Data Base file
     TAAARC          TAA Archive
     EDTVAR          Edit variable
     RSNLSTMSG       Resend last message
     RTVAPPVAL       Retrieve application value
     RTVJOBA2        Retrieve job attributes 2
     RTVJOBSTS       Retrieve job status
     RTVTIMSTM       Retrieve time stamp
     SNDCOMPMSG      Send completion message
     SNDDIAGMSG      Send diagnostic message
     SNDJLGMSG       Send job log message
     SNDESCMSG       Send escape message
     SNDSTSMSG       Send status message
     UPDPFILE        Update PFILE keyword


None, the tool is ready to use.

Objects used by the tool

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

   CRTINACT      *CMD                   TAAJODJ       QATTCMD
   SBMINACT      *CMD                   TAAJODJ2      QATTCMD
   WRKINACT      *CMD                   TAAJODJ3      QATTCMD
   ENDINACT      *CMD                   TAAJODJ4      QATTCMD
   TAAJODJC      *PGM       CLP         TAAJODJC      QATTCL
   TAAJODJC2     *PGM       CLP         TAAJODJC2     QATTCL
   TAAJODJC3     *PGM       CLP         TAAJODJC3     QATTCL
   TAAJODJC4     *PGM       CLP         TAAJODJC4     QATTCL
   TAAJODJC11    *PGM       CLP         TAAJODJC11    QATTCL
   TAAJODJR3     *PGM       RPG         TAAJODJR3     QATTRPG
   TAAJODJR11    *PGM       RPG         TAAJODJR11    QATTRPG
   TAAJODJP      *FILE      PF          TAAJODJP      QATTDDS
   TAAJODJL      *FILE      LF          TAAJODJL      QATTDDS

The *USRSPC and *DTAARA objects are in library TAASECURE.


   TAAJODJC   CL pgm     Sets the system values and creates files

   TAAJODJC2   CL pgm

      Submits     TAAJODJC11 CL Pgm  Waits on TAAINACT message queue
                    TAAJODJR11  RPG Pgm to access CHKINACTP file

   TAAJODJC3   CL pgm
     TAAJODJR3   RPG pgm
       TAAJODJD    Display file

   TAAJODJC4   CL pgm

Added to TAA Productivity tools March 15, 2003

Home Page Up to Top