The Display QHST 2 command displays QHST messages using a subfile
display. Several access paths are supported to allow quick access.
Access paths to the messages are created for:
- Date, time
- Job, User, Job number, date, time
- User, date, time
- Message ID, date, time
The messages in QHST must first be converted to the QHST2 file by the
CVTQHST2 command. CVTQHST2 can be specified at any time. It keeps
track of the last message converted and will only convert new
messages added since the last convert operation. A MTNQHST2 command
is also supported to delete QHST2 messages that are no longer needed.
The user of any of the commands must have *USE authority to the
TAACVTQHST authorization list.
See also the DSPQHST tool which provides a display or listing with
selection capability.
Excluding message IDs
---------------------
Since QHST may contain a large number of identical message IDs that
you may want to avoid, an 'exclude' parameter exists such as:
DSPQHST2 EXCLUDEID(CPFxxxx CPCxxxx)
If you typically want to exclude a list of specific message IDs, a
good tool to consider is FAVCMD. Assume you have created the
required files with CRTFAVCMD. You then enter the DSPQHST2 command
followed by ADDFAVCMD with a FAVID such as QHST:
DSPQHST2 EXCLUDEID(...)
ADDFAVCMD FAVID(QHST)
The next time you want the same DSPQHST2 command, you would enter:
EXCFAVCMD QHST
or the shorthand version
FV QHST
System handling of QHST
-----------------------
****************************************
* *
* You can get into trouble with *
* too low a setting of the *
* QHSTLOGSIZ system value. *
* A reasonable setting is to *
* use the maximum size supported *
* by the system for the release. *
* *
****************************************
QHST contains all of the messages sent to QSYSOPR. It also contains
some specific messages which are only sent to QHST. This includes
the job start message (CPF1124) and the job completion message
(CPF1164). Any application can also send messages to QHST.
Periodically (or when DSPLOG is used), the messages are written to a
QHST log file. These files are automatically created by the system
and have the generic name QHST with the year and day of the year plus
a modifier (e.g. QHST93150A).
A new log is started based on the setting of the QHSTLOGSIZ system
value. Therefore, there is always a current log which is still being
written to periodically and completed log files (old versions).
The completed log files are not automatically deleted by the system.
OA (Operating Assistant) has a function to delete old versions or you
can delete them yourself. The TAA DLTQHST command may also be used
to delete old QHST files.
DSPLOG causes the messages in the QHST message queue to be written to
the current log and then scans the log file(s) based on the command
parameters. No access paths are used to access the messages which
can make it awkward to use as well as slow.
The object names of the log files are QHSTnnnnnA. The nnnnnA value
is a julian date made up of YY (such as 03), the day number of the
year (such as 150) and a letter beginning with A. After the 'A' log
for the day, the system assigns B, and then C thru Z, and 0-9 if
necessary. Thus if you create less than 36 log files a day, the day
number assigned will match the exact day the file was created.
If you are creating a large number of logs every day, the system will
automatically roll over as if it is the next day. For example, if
the true day of the year is 150 and you have already written
QHSTYY1509, the next object name will be QHSTYY151A even though it is
created on YY150.
The text description of each log object contains the actual date/time
of the first and last entries in the log. The first 13 bytes are for
the first entry (in the format cyymmddhhmmss) and are followed by 13
bytes for the last entry (using the same format).
You can get in trouble by generating excess log files so the YYnnnA
part of the object name is not the current day number of the year.
If you perform cleanup of old log files, the system will attempt to
use the current day number unless it creates a duplicate. This can
result in the object names that are assigned not being in ascending
sequence thus causing the TAA tool to fail to convert the data.
Getting started with DSPQHST2
-----------------------------
To begin use of DSPQHST2, you must first create the QHST2 file
structure and convert messages to the QHST2 file. A typical command
would be:
CVTQHST2 QHST2LIB(xxx) CREATE(*YES)
This will create the QHST2 physical file and the logical files built
over the physical. Any existing QHST files in QSYS are then accessed
and converted.
You should specify a library on CVTQHST2 that will cause the QHST2
file to exist where it will be backed up on a regular basis. You do
not need to back up the QHST files in QSYS if you are using CVTQHST2
on a regular basis.
The current QHST file in QSYS is not complete until a new QHST file
is created by the system. When you run CVTQHST2, it determines the
last QHST file that was used and will convert it again, but only the
messages added since the last conversion are added to the QHST2 file.
Once a QHST file is complete (meaning a new QHST file has been
created by the system) and converted by CVTQHST2, you may delete the
QHST file in QSYS. A good cleanup command to consider is the TAA
tool DLTQHST (it will not delete the current QHST file).
Periodically you should clean out old messages from the QHST2 file
with the MTNQHST2 command such as:
MTNQHST2 RMVDAYS(nn)
This will cause the QHST2 file to be copied for all records that have
a date later that the date generated from the RMVDAYS parameter (the
default is 60). The data is copied to the QHST2T file which is
automatically created. The QHST2T file is then copied back and the
access paths rebuilt. MTNQHST2 should be specified at a low workload
period.
If an error occurs during the copy (or the system abnormally
terminates), the MTNQHST2 command has built in recovery processing.
Just issue the command again.
After the QHST2 file is built, you can convert additional QHST
entries by taking the defaults. A typical command would be:
CVTQHST2
Displaying the messages
-----------------------
When you are ready to display the QHST2 file, the simplest format of
the command is:
DSPQHST2
When the display appears, you are in the default mode of accessing
the records by date/time sequence. You can specify a date and time
in the -Position To- fields or use Rollup.
You can also change the access path used to read the records by use
of the F6 command key. A prompt appears and allows you to choose one
of the other access paths. When you return to the subfile display,
the default display appears for the option chosen. For example, if
you requested the *JOB access path, the lowest value job name would
appear first with the first record being the earliest date for that
job.
You can also specify which access path should be used by using
parameters on the DSPQHST2 command. However, there is less overhead
to change the access path being used than to return to the command
and specify the access path desired.
You can display the details of any message using Option 5 on the
subfile display. If the CPF1164 message is displayed (sent by the
system at end of job), the performance information from the message
data is displayed. This provides an easy access to the number of CPU
seconds, number of transactions, and the average response time is
calculated for the job.
From the detail message display, you can access the 2nd level help
for any message.
You can also directly access what is needed by using the parameters
on the DSPQHST2 command such as:
DSPQHST2 USER(xxxx)
or
DSPQHST2 PERIOD(bgntime bgndate endtime enddate)
Security considerations
-----------------------
The tool must be created by a user with Security Officer authority.
The user of any of the commands must have *USE authority to the
TAACVTQHST authorization list.
The physical files and data area are created as AUT(*EXCLUDE) and are
owned by the user of the CVTQHST2 command with CREATE(*YES). The
logical files are created as AUT(*USE).
To allow a user who did not create the files to display the data,
authorize the user to *USE of QHST2 and *USE to the authorization
list TAACVTQHST.
The TAAHSTEC program is created with USRPRF(*OWNER) in order to allow
access to the QHST files in QSYS.
Any subprograms called by the commands use only qualified calls to
TAATOOL programs or use USEADPAUT(*NO).
QHST2 Data Area
---------------
During the running of CVTQHST, the QHST2 data area will be created in
the same library as the QHST2 files. This data area contains the
text description of the last QHST file that was converted. The
information is used to bypass QHST files that have already been
converted the next time CVTQHST2 is run.
DSPQHST2 Command parameters *CMD
---------------------------
The DSPQHST2 command displays a subfile of the messages in the QHST2
file and allows selection and different access paths to be used.
PERIOD A 4 part parameter to determine the beginning and
ending date/time values.
The first part is the beginning time. The default
is *AVAIL which means the earliest time for the
beginning date specified. A specific time may be
entered as 100000 or with separators such as
10:00:00.
The second part is the beginning date. The default
is *CURRENT meaning the current date. A specific
date may be entered in job date format or the
special value *BEGIN which means the first date
found in the file.
The third part is the ending time. The default is
*AVAIL which means the latest time for the ending
date specified. A specific time may be entered as
100000 or with separators such as 10:00:00.
The fourth part is the ending date. The default is
*CURRENT meaning the current date. A specific date
may be entered in job date format or the special
value *END which means the last date found in the
file.
JOB The job name to be displayed. The default is *ALL
which causes the messages for any jobs to be
displayed. to be displayed. You can further
qualify the job with the USER and JOBNBR parameters.
The job specified is used to start reading records,
but does not prevent other job names from being
displayed (it only causes a 'Set lower limit'
function).
USER The user name to be displayed. The default is *ALL
which causes any user's messages to be displayed.
If JOB is also specified, the USER name is used to
further qualify the job name (the access path is
Job, User, Job number, date, and time).
If USER is specified without specifying JOB, it
causes a different access path (User, date, and
time), In this case, the user specified is used not
only for a 'set lower limit' function, but also for
a 'read equal' function so that only records that
match the user name will be displayed.
JOBNBR The job number to be displayed. The default is *ALL
which causes the messages from any job number to be
displayed. If JOB and USER are also specified, the
job number is used to further qualify the job name
(the access path is Job, User, Job number, date, and
time).
MSGID The Message ID to be displayed. The default is *ALL
which causes any message ID to be displayed.
Specifying MSGID causes a different access path
(Message ID, date, and time) to be used. The
Message ID specified is used not only for a 'set
lower limit' function, but also for a 'read equal'
function so that only records that match the Message
ID will be displayed.
You cannot specify MSGID with JOB, USER, or JOBNBR.
You can use both MSGID and DATE in which case the
subfile will only contain the message IDs that match
beginning with the date specified.
EXCLUDEID A list of up to 100 message IDs that should be
excluded. *NONE is the default.
QHST2LIB The library where the QHST2 file structure exists.
*LIBL is the default.
CVTQHST2 Command parameters *CMD
---------------------------
CVTQHST2 automatically determines the last message that was converted
from the previous CVTQHST2 command (if any) and only converts
messages that do not already exist in QHST2. A special message
TAA1015 is sent to QHST as part of the CVTQHST2 processing and then
DSPLOG is used to force any messages in the QHST message queue to the
current QHST log file. All log files are considered, but only new
messages (those that were added after the last CVTQHST2) are
converted. The log file that was current from the last use of
CVTQHST2 must be read to determine where to start converting new
messages.
QHST2LIB The library where the QHST2 file structure exists.
*LIBL is the default. If the file structure does
not exist, you must specify a library name and
CREATE(*YES).
CREATE A *YES/*NO value for whether to create the QHST2
physical file and the associated logical files. *NO
is the default. *YES must be specified to create
the file structure.
MTNQHST2 Command parameters *CMD
---------------------------
The MTNQHST2 command removes old messages that are no longer needed
in the QHST2 file structure. The messages that are specified to be
kept are copied to the QHST2T file and then copied back.
If an error occurs during the copying process, recovery is automatic
by just using MTNQHST2 again.
The message TAA1016 is sent to QHST if the MTNQHST2 command completes
successfully. This message will not be in the QHST2 file until the
next time CVTQHST2 is run.
QHST2LIB The library where the QHST2 file structure exists.
*LIBL is the default.
RMVDAYS The number of days old a message must be before it
is deleted. The default is 60. This means that any
messages older than 60 days would be deleted. The
minimum number of days is 5.
Restrictions
------------
The QHST messages must first be converted with the CVTQHST2 command.
The system only supports 132 bytes of 1st level text for messages in
QHST. DSPQHST2 captures up to 256 bytes of message data. If the 1st
level text is not completely shown by the DSPQHST2 detail display,
you can normally access the same information by using F7 to display
the 2nd level text.
Prerequisites
-------------
The following TAA Tools must be on your system:
ADDDAT Add date
ALCTMPMBR Allocate temporary member
CHKJOBCTL Check job control
EDTVAR Edit variable
FILEFDBCK File feedback
SNDCOMPMSG Send completion message
SNDESCMSG Send escape message
SNDSTSMSG Send status message
TAAARC TAA Archive (CPYTAA command)
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
CVTQHST2 *CMD TAAHSTE QATTCMD
MTNQHST2 *CMD TAAHSTE2 QATTCMD
DSPQHST2 *CMD TAAHSTE3 QATTCMD
TAAHSTEC *PGM CLP TAAHSTEC QATTCL
TAAHSTEC2 *PGM CLP TAAHSTEC2 QATTCL
TAAHSTEC3 *PGM CLP TAAHSTEC3 QATTCL
TAAHSTEC5 *PGM CLP TAAHSTEC5 QATTCL
TAAHSTEC6 *PGM CLP TAAHSTEC6 QATTCL
TAAHSTEC7 *PGM CLP TAAHSTEC7 QATTCL
TAAHSTEC8 *PGM CLP TAAHSTEC8 QATTCL
TAAHSTEC9 *PGM CLP TAAHSTEC9 QATTCL
TAAHSTEC13 *PGM CLP TAAHSTEC13 QATTCL
TAAHSTER *PGM RPG TAAHSTER QATTRPG
TAAHSTER3 *PGM RPG TAAHSTER3 QATTRPG
TAAHSTED *FILE DSPF TAAHSTED QATTDDS
QHST2 *FILE PF TAAHSTEP QATTDDS
TAAHSTEQ *FILE PF TAAHSTEP QATTDDS
QHST2L *FILE LF TAAHSTEL QATTDDS
QHST2L2 *FILE LF TAAHSTEL2 QATTDDS
QHST2L3 *FILE LF TAAHSTEL3 QATTDDS
QHST2L4 *FILE LF TAAHSTEL4 QATTDDS
QHST2L5 *FILE LF TAAHSTEL5 QATTDDS
QHST2T *FILE PF No source
QHST2 *DTAARA
QHST2B *DTAARA
The QHST2T file is created using the TAAHSTEP source as a duplicate
for use by the MTNQHST2 command.
The TAAHSTEQ file is created from TAAHSTEP source and is used for
compiling by other tools.
The QHST2 data area is used for recovery purposes by the MTNQHST2
command.
The QHST2B data area is used to determine the last QHST file
converted by the CVTQHST2 command.
The QHST2 file is accessed in arrival sequence.
The logical files have the following access paths:
QHST2L - By date and time
QHST2L2 - By job, user, job number, date, time
QHST2L3 - By user, date, time
QHST2L4 - By message ID, date, time
QHST2L5 - By job, user, date, time
Structure
---------
CVTQHST2 Cmd
TAAHSTEC CL pgm
TAAHSTEC6 CL pgm
TAAHSTEC7 CL pgm - Does CRTPF
TAAHSTEC5 CL pgm - Calls TAAHSTER to get last cvtd log ID
- Calls TAAHSTER to convert
TAAHSTER RPG Pgm
MTNQHST2 Cmd
TAAHSTEC2 CL pgm
TAAHSTEC8 CL pgm
QHST2 Data area
DSPQHST2 Cmd
TAAHSTEC3 CL pgm
TAAHSTER3 RPG Pgm
TAAHSTED Display file
TAAHSTEC9 CL Pgm
TAAHSTEC13 CL Pgm
|
