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
occurred.
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
activity.
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
system.
2 Leave the workstation you signed onto and perform the
following steps at a different workstation as a different
user.
3 To ignore the timeout condition for other workstations, check
the CHKINACT Application Value default. As an *ALLOBJ user,
enter:
EDTAPPVAL APPVAL(TAASECURE/CHKINACT)
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:
CRTINACT
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:
WRKINACT
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.
WRKSYSVAL SYSVAL(QINACTITV).
Use Option 2 and change the value to 5.
7 Submit the batch job to listen for the timeout messages with
the command:
SBMINACT
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:
ENDINACT
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
file.
13 It is recommended that you reset the QINACTITV system value
until you are ready to place CHKINACT tool into production.
CHGSYSVAL SYSVAL(QINACTITV) VALUE('30')
Commands
--------
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
file.
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
minutes.
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
exception.
** 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.
or
** 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:
EDTAPPVAL APPVAL(TAASECURE/CHKINACT)
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
*IGNORE, *DSCJOB, or *ENDJOB.
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 Valid and overrides the CHKINACT appvalue
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
WRKINACT.
** Ensure the system value is set for the proper timeout.
WRKSYSVAL SYSVAL(QINACTITV).
Use Option 2 to change the value to your standard.
** Ensure the Application Value default is set correctly:
EDTAPPVAL APPVAL(TAASECURE/CHKINACT)
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:
TAATOOL/SBMINACT
** 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
job.
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'
column.
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
device.
To modify the shipped list, as an *ALLOBJ user, enter:
EDTCONARR DTAARA(TAASECURE/CHKINACT)
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
active.
** 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.
SBMINACT Outfile
----------------
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
menu.
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
be SMARY.
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,
etc.
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"
message.
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
connections.
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
interactively.
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
6AM.
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
INAJOBR.
OUTMBR The member of the INACTP file to be used. If the
member does not exist, it is added. The default is
INACTP.
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
data.
ENDINACT Command parameters *CMD
---------------------------
None
Restrictions
------------
You must have *ALLOBJ authority to use CRTINACT.
Prerequisites
-------------
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
Implementation
--------------
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
TAAJODJD *FILE DSPF TAAJODJD QATTDDS
TAAJODJP *FILE PF TAAJODJP QATTDDS
TAAJODJL *FILE LF TAAJODJL QATTDDS
CHKINACT *USRSPC
CHKINACT *DTAARA
The *USRSPC and *DTAARA objects are in library TAASECURE.
Structure
---------
CRTINACT Cmd
TAAJODJC CL pgm Sets the system values and creates files
SBMINACT Cmd
TAAJODJC2 CL pgm
Submits TAAJODJC11 CL Pgm Waits on TAAINACT message queue
TAAJODJR11 RPG Pgm to access CHKINACTP file
WRKINACT Cmd
TAAJODJC3 CL pgm
TAAJODJR3 RPG pgm
TAAJODJD Display file
ENDINACT Cmd
TAAJODJC4 CL pgm
|
