Logging Activity in the HLIPRINT File

In this section: HLIPRINT File Contents HLIPRINT File Contents (Extended Format) Creating and Using an HLIPRINT/HLIERROR File Writing Reports With the Extended HLIPRINT Trace

FOCUS can record all user actions on the sink machine in a sequential file called HLIPRINT. Each HLI command is a single action. Each MODIFY transaction, Maintain transaction, or TABLE request may execute a series of actions such as opening and closing databases, reading databases, matching keys, and changing values. When you start the server using the ECHO option, ddname HLIPRINT records:

• Each user action.
• The database on which the action took place.
• The database segment read or modified by the action.
• The user ID that issued the action.

In addition, FOCUS offers an extended form of the HLIPRINT file when you start the server using the STAT option. In addition to the information displayed by the ECHO option, the extended form lists the following:

• Date and time of the action.
• The CPU time it took to execute the action.
• The number of I/O operations required to execute the action.
• The name of the FOCUS procedure (FOCEXEC) executing the action.
• For MODIFY and Maintain requests with Case Logic, the name of the case executing the action.

The HLIPRINT file has three uses:

• It provides a guide for restarting procedures that end prematurely. The restart must be tailored to the application because the HLIPRINT file does not log transaction data.
• It provides a means for performing usage accounting based on the number of actions.
• It provides a means for monitoring database use, particularly during testing of new procedures.

Note: If you display the HLIPRINT file in a system editor, the first column is reserved for print control characters.

HLIPRINT File Contents

In this section: The NEW Command for HLI Maintain

The following shows a sample HLIPRINT file obtained with the ECHO option. The columns are described following the diagram:

CMD   FILENAME       STATUS  NEWSEG  TARGET ANCHOR  NTEST  USERID  REF NUMB

OPN   FOCUSSU FOCUS  F    0                         DIW            00000001
RD    CAR     FOCUS  A    0                       1 DIW            00000002
OPN   CAR     FOCUS  A    0                         EFO            000000O3
MINT  CAR     FOCUS  A    0                         EFO            00000004
MATA  CAR     FOCUS  A    0  ORIGIN                 EFO            00000005
MATB  CAR     FOCUS  A    0  COMP                   EFO            00000006
MDEL  CAR     FOCUS  A    0  COMP                   EFO            00000007
MATB  CAR     FOCUS  A    0  ORIGIN                 NNR            00000008
MATB  CAR     FOCUS  A    1  COMP                   NNR            00000009
MINC  CAR     FOCUS  A    0  COMP                   NNR            00000010
MATB  CAR     FOCUS  A    0  ORIGIN                 MHK            00000011
MATB  CAR     FOCUS  A    0  COMP                   MHK            00000012
MDEL  CAR     FOCUS  A    0  COMP                   MHK            00000013
MATB  CAR     FOCUS  A    0  ORIGIN                 EFO            00000014
MATB  CAR     FOCUS  A    1  COMP                   EFO            00000015
MINC  CAR     FOCUS  A    0  COMP                   EFO            00000016
MATB  CAR     FOCUS  A    0  ORIGIN                 NNR            00000017
MATA  CAR     FOCUS  A    1  COMP                   NNR            00000018
MINC  CAR     FOCUS  A    0  COMP                   NNR            00000019
CLO   CAR     FOCUS  A    0                         NNR            00000020
CLO   FOCUSSU FOCUS  *    0                         NNR            00000021

The following describes the columns on the output:

CMD

Type of action. Can be one of the following:

OPN Open a file.

RD Read a page from a FOCUS database.

MINT MODIFY/SU initialization.

MATB, MATA, MATC, MATD Match a field value or values in the database (MODIFY MATCH subcommand).

MINC Include a new segment instance (MODIFY INCLUDE subcommand).

MUPD Update a segment instance (MODIFY UPDATE subcommand).

MDEL Delete a segment instance and its descendants (MODIFY DELETE subcommand).

MNEX Place the current position at the next segment instance in the segment chain (MODIFY NEXT subcommand).

MREP Place the current position at the first segment instance in the segment chain (MODIFY REPOSITION subcommand).

MCMT COMMIT subcommand.

MRBK ROLLBACK subcommand.

NEW Used by Maintain.

SAV Write transactions from buffer into the database. (How FOCUS writes transactions into the database is discussed in SU and the FOCUS Language.)

CLO Close a file.

Any other type of action in this column is an HLI command issued when using HLI with SU.

FILENAME

STATUS

0 if the action executed normally.

1 if a MATCH statement cannot locate a segment instance (ON NOMATCH condition), or if a NEXT statement reaches the end of a segment chain (ON NONEXT condition).

Otherwise, the value is a FOCURRENT field or an HLI status code. SU and the FOCUS Language, lists FOCURRENT field values; HLI Status Codes Returned in FCB Word 24, lists HLI status codes.

NEWSEG

For HLI only, the name of the first segment of new information.

TARGET

The segment in the FOCUS database read or modified by the action.

ANCHOR

For HLI only, the anchor segment.

NTEST

For HLI only, the number of test conditions qualifying a retrieved record.

For FOCUS users, the number of the database page that was read by an RD action (a page is a 4096-byte physical record of a FOCUS file or a 16K-byte record for an XFOCUS file).

USERID

The user ID that issued the action.

REF NUMB

The number of the action in the HLIPRINT file.

The REF NUMB number helps determine the last time a segment was changed. Use the FOCUS ? FILE command to display a chart showing when each segment in a FOCUS database was last changed. (This query is described in full in the Developing Applications manual.) The last column in the chart is labeled LAST TRANS NUMBER. This column lists a number for each segment in the file.

If the file was last modified under SU, the numbers in the LAST TRANS NUMB column will refer to the REF NUMB column in the HLIPRINT file, pointing to the last action performed on the segment (usually a CLO or SAV action).

The NEW Command for HLI Maintain

Maintain SU has an HLI command called NEW. This command provides a performance enhancement in the buffer size that is sent back from the SU server. It also receives arguments in the form of HLI commands. So when a database is opened with Maintain for an update action, the NEW command will appear in HLIPRINT with an OPN command as an argument. This is shown in the following sample HLIPRINT file.

CMD  FILENAME        STATUS  NEWSEG  TARGET  ANCHOR  NTEST USERID  REF NUMB

OPN  FOCUSSU  FOCUS  A    0                                PMSPAK  00000001
RD   EMPLOYEE FOCUS  A    0                              1 PMSPAK  00000002
RD   JOBFILE FOCUS   A    0                              1 PMSPAK  00000003
RD   EDUCFILEFOCUS   A    0                              1 PMSPAK  00000004
OPN  EMPLOYEEFOCUS   A    0                                PMSPAK  00000005
NEW  EMPLOYEEFOCUS   A    0  OPEN    00000048 00000312     PMSPAK  00000006

HLIPRINT File Contents (Extended Format)

The following shows a sample extended HLIPRINT file. The columns are the same as those in the simple HLIPRINT file described in the previous section, with the exception of the additions described following the sample output:

Note: A Master File is supplied for the extended HLIPRINT file (called HLIPRINT MASTER) that allows you to write FOCUS reports from the file. Consult Writing Reports With the Extended HLIPRINT Trace for examples.

Additional columns are:

DATE

Date the action was executed, in YYMMDD (year, month, day) format.

TIME

Time the action finished execution, in HHMMSS (hours, minutes, seconds) format.

VTIME

Amount of virtual CPU time required to execute the action. If the action took longer than 99.99 seconds to execute, VTIME displays a value of 99.99. Note that the value of VTIME is .0000 for the first action after the sink machine was started.

TTIME

The same as VTIME except it is the amount of total CPU time.

IOS

Number of database input/output (I/O) operations performed to complete the action. This number reflects only I/O operations on FOCUS databases and does not include I/O operations to other files such as Master Files. If the action required more than 9999 I/O operations, IOS displays a value of 9999.

PROCNAME

For FOCUS users, the name of the FOCUS procedure (FOCEXEC) executing the action. If the user is executing a FOCUS request live on the terminal, PROCNAME is blank.

For HLI users, the contents of FCB words 7 and 8. SU does not use words 7 and 8, so HLI users can define the contents of these words and have them displayed in the PROCNAME column.

CASE NAME

For MODIFY and Maintain requests only.

If the request defines a temporary field called SUPRINTNAME (pronounced "SU print name"), CASE NAME is the value of this field. SUPRINTNAME must be an alphanumeric field no longer than 12 characters.

For example, if your MODIFY or Maintain request contains the statement

COMPUTE SUPRINTNAME/A12 = 'MARK'; 

then the CASE NAME column will display the value MARK until the next COMPUTE statement places another value in the SUPRINTNAME field.

If the request does not define SUPRINTNAME but does use Case Logic, CASE NAME is the name of the case that executed the action.

Otherwise, CASE NAME is blank.

Creating and Using an HLIPRINT/HLIERROR File

To record activity in the HLIPRINT/HLIERROR file, follow these instructions when starting the sink machine:

1. If you are recording the HLIPRINT file on disk or tape, make sure that there is adequate storage space for the file. The HLIPRINT file can grow very quickly; a single MODIFY transaction, Maintain transaction, or TABLE command can generate several actions and several lines of output. One day's use can produce many thousands of lines. If the space reserved for HLIPRINT becomes full, the sink machine cannot recover.

2. Define the HLIPRINT/HLIERROR file using the CMS FILEDEF command. If the file is new, give the file the following characteristics:
   • For simple HLIPRINT files (ECHO option): a fixed-length, blocked format, a record length of 88 characters. The blocksize must be a multiple of 88.
   • For extended HLIPRINT files (STAT option): a fixed-length, blocked format (RECFM FB), a record length of 133 characters. The blocksize must be a multiple of 133.

In general, the larger the blocksize, the fewer I/O operations FOCUS will perform. However, if the sink machine terminates abnormally, any records on the last unwritten block are lost.

For example, to record actions in a new file called SULOG DATA on the T disk of the sink machine, enter:

FILEDEF HLIPRINT DISK SULOG DATA T (RECFM FB LRECL 88 BLOCK 8800)
FILEDEF HLIERROR DISK SUERROR DATA T (RECFM FB LRECL 88 BLOCK 8800)

or

FILEDEF HLIPRINT DISK SULOG DATA T (RECFM FBA LRECL 133 BLOCK 13300)
FILEDEF HLIERROR DISK SUERROR DATA T (RECFM FBA LRECL 133 BLOCK 13300)

If the file exists, the new output will replace the present file contents. If you want to append the new output to the present file contents instead, add the DISP MOD parameter. For example, if you decide in a later session to append new output to the SULOG file contents, you would enter:

FILEDEF HLIPRINT DISK SULOG DATA T (DISP MOD) 

If you start the sink machine with your own EXEC, you can include the FILEDEF command in the EXEC (see Starting a Sink Machine).

The HLIPRINT file can be FILEDEFed to tape, to any disk to which the sink machine has write access, or to a virtual printer, reader, or punch.

3. Start the sink machine with the following command

   IUCVMAIN password [ECHO|STAT|TRACE] 

or

FOCUS SU password [ECHO|STAT|TRACE] [(IUCV [NODISC] ]

where:

password

Is a password up to eight characters long. You must enter a password or FOCUS will interpret the ECHO or STAT parameter as the password.

ECHO

Records actions in a simple HLIPRINT file.

STAT

Records actions in an extended HLIPRINT file.

TRACE

Records activity in an extended HLIPRINT file in addition to activating the FSTRACE trace described in Tracing Sink Machine Processing.

NODISC

Prevents the sink machine from automatically disconnecting after startup.

If you start the sink machine with your own EXEC, add the password and the ECHO parameter to the line in the EXEC that invokes the IUCVMAIN module. For example, if your EXEC is called SUSTART and your password is ABC, then SUSTART EXEC should contain the line:

IUCVMAIN ABC ECHO

4. If you are using the extended HLIPRINT file and you want to print it, add the CC parameter to the CMS PRINT command. This enables the printer to interpret the control characters in column 1. For example:

   PRINT SULOG DATA T (CC

Writing Reports With the Extended HLIPRINT Trace

A Master File named HLIPRINT MASTER is provided with FOCUS for the extended HLIPRINT trace. You can produce summary reports of your HLIPRINT trace with the FOCUS TABLE command. These summary reports may be used to:

• Determine peak sink machine usage by user, time of day, database, or application.
• Discover performance problems in procedures or in database design.
• Perform usage accounting.

Before issuing your report request, you must first FILEDEF ddname HLIPRINT to the trace file. For example, if your HLIPRINT file was called SULOG DATA T, you would issue the following command from within FOCUS:

CMS FILEDEF HLIPRINT DISK SULOG DATA T 

This sample report request determines the total amount of CPU and I/O operations used by the sink machine on behalf of each user:

TABLE FILE HLIPRINT
SUM VTIME AND TTIME AND IOS
BY USERID
END

Another report request could locate performance problems in an application:

TABLE FILE HLIPRINT
SUM VTIME AND TTIME AND IOS
BY PROC NAME BY CASE NAME
ON PROC NAME SUMMARIZE
END

The output is:

In this report, the case LOCATE in the procedure CARMOD consumes most of the CPU time and I/O resources. This particular part of the application might be redesigned to run more efficiently.

For more information about report requests, see the Creating Reports manual.