Implementing FOCLOG

In this section:

Overview of FOCLOG Implementation
Allocating the FOCLOG Log File
Activating FOCLOG
Validating the FOCLOG Configuration
Running the FOCLOG Reports

The person implementing FOCLOG should be a system administrator with the ability to create and allocate data sets and who can assign RACF rules. Knowledge of FOCUS is not required.

The modules, FOCEXECs, and Master File needed to run FOCLOG and the FOCLOG reports are distributed as part of the standard FOCUS libraries. No installation steps are required. The administrator only needs to:

Rename the distributed sample FOCUSLOG file.
The sample file is distributed as member FLOGSAMP in the ERRORS.DATA library. Rename this file so that the member name is FOCUSLOG.
Create a log file and activate it by specifying its fully qualified name (data set name) in the FOCUSLOG file.

If your site standards require you to implement new features in a test environment, create a temporary FOCUSLOG ERRORS file.

Create a copy of your FOCUS production CLIST and concatenate your ERRORS library in front of the FOCUS production ERRORS library.

Create a temporary log file and place its fully qualified SFS directory name in your private version of the FOCUSLOG ERRORS file.

After validating the FOCLOG implementation, remove your private FOCUSLOG file from your CLIST or minidisk.

Overview of FOCLOG Implementation

Reference:

Usage Notes for FOCLOG

These steps provide a high-level overview of the FOCLOG implementation process:

Allocate the FOCLOG data set.
Activate FOCLOG.
Validate the FOCLOG configuration.
Move FOCLOG to your production FOCUS environment.
Run the reports supplied with FOCLOG after collecting log data for whatever period you deem appropriate.

Reference: Usage Notes for FOCLOG

To avoid archiving the FOCLOG data set, it should not be managed by DFSMS.
To keep the FOCLOG file a manageable size, the log was designed to capture only those commands that allow you to analyze the function of FOCUS applications at your site. Therefore, by design, only the following commands are captured in the log file: RUN (to run a compiled MODIFY), MAINTAIN, CREATE, FSCAN (as FOC$SCAN), GRAPH, HOLD, MATCH FILE, MODIFY, RETYPE, SCAN, TABLE, and TABLEF. Other commands issued during one of these requests (for example, JOIN or CHECK FILE) are not captured in the log file. However, if a JOIN or cross reference is in effect, all of the joined files are listed in the log after a TABLE request that references the join. MATCH FILE captures only the first file.
The following commands are not captured in the log file: REBUILD, JOIN, CHECK FILE, MORE.
In the event that the log file becomes full, recording stops for all users. To replace the log file, you can rename the full log file and allocate another empty file with the name of the original log file. Logging will resume the next time a user session ends (at FIN).

Allocating the FOCLOG Log File

How to:

Allocate the FOCLOG Log File
Estimate the Size of the Log File

You must have a log file allocated and reference it in the FOCUSLOG ERRORS file in order to initiate logging. You should first determine the size of the log file required as described in How to Estimate the Size of the Log File.

Procedure: How to Allocate the FOCLOG Log File

Allocate a physical sequential file with LRECL 256 and RECFM VB using the size estimate you determined in Step 1.
Edit and submit the following job to allocate the FOCLOG log file after adding an appropriate job card:
```
//* add job card here 
//FLALLOC  EXEC PGM=IEFBR14
//FOCLOGF  DD DSN=flhlq.FOCLOG.DATA,DISP=(NEW,CATLG),
//            VOL=SER=volser,UNIT=unit,SPACE=(CYL,(p,s)),
//            DCB=(RECFM=VB,LRECL=256,BLKSIZE=12288),DSORG=PS
/*
```
where:

flhlq

Is the high-level qualifier for the FOCLOG file.

unit

Is a valid DASD unit for the FOCLOG file.

volser

Is the volume serial number of the unit on which you want to store the FOCLOG file.

p

Is the primary space allocation in cylinders.

s

Is the secondary space allocation in cylinders.
Using your security interface (for example, RACF), authorize all of your FOCUS users in the entire sysplex to have write access across the sysplex to this file.

The following are suggestions for naming conventions for you log file:

Create a separate log for each day of the week, for example FOCLOGMO, FOCLOGTU, FOCLOGWE, FOCLOGTH,FOCLOGFR, FOCLOGSA, and FOCLOGTU
Use a numbering convention such as FOCLOG1, FOCLOG2, FOCLOG3, and so on, to name multiple log files.
Name log files by system and date, such as S1091507. Where S1 represents System number 1 and 091507 represents the day of the year (in this example, September 15, 2007).
Allocate the log file as a Generation Data Group (GDG) in which case the system creates a naming convention by using index number for each generation.

Procedure: How to Estimate the Size of the Log File

The size of the log file required depends on factors such as the number of users and FOCUS applications in your environment, plus the length of time for which you wish to capture information.

Consider these suggestions when estimating its size:

Estimating user session statistics. A sample user session lasting one hour and containing 26 DD allocations running 25 TABLE requests will produce approximately 77 output records to the log. There will be one session record for the user session, 26 DSNS records (one per DD allocation), and 50 records from the TABLE requests (2 per request). Assuming that the average number of bytes per record is 50, this sample user session will produce 3850 bytes of output in the log.

One cylinder on an IBM 3390-3 device contains 737280 bytes. Therefore, approximately 190 user sessions of this size would fill one cylinder (737280 / 3850).

To apply this calculation at your site, you must evaluate the number of allocations in your production FOCUS CLIST/JCL and estimate how many TABLE requests each session is likely to run in an hour. Then use the following formulas to estimate the size of the log file:

bytes_per_hr = no_of_users * ((1+ number_of_allocs + (2 * 
avg_no_of_TABLEs)) * 50)
 
user_sessions_per_cylinder =  737280  / bytes_per_hr

Determine how many user sessions you wish to log per day, week, or month and allocate cylinders accordingly. For example, using the sample session described above, eight cylinders would be adequate for collecting 190 user sessions per hour for an eight hour period.

Collecting sample data. If you don't know the level of FOCUS usage at your site, and cannot apply the above technique, you may just wish to collect data for a given period using a large log file and see how long it takes to fill or how much is used. For example, allocate a 100-cylinder log file for use in production for one business day and at day's end, use ISPF to determine how much of the log was populated. If you used 10 cylinders of the log file on a fairly typical day, a good estimate for the size is 10 cylinders per day. Extend this to determine numbers of cylinders required for longer periods. The only penalty for under-sizing your log is that logging stops when the log is full.

In designing the log file, also take the following considerations into account:

You can easily FTP or email small logs to other locations (for example, your Desktop) for analysis with tools such as WebFOCUS or Excel.
Large log files can capture data for longer periods without continuous monitoring, but require more time for usage review and are slower when generating reports.

Activating FOCLOG

Reference:

Notes on Activation and Deactivation of Logging

Usage can be logged at three levels, producing either a short form log, a detailed log, or a summary log, as described in the examples that follow.

Activation of logging requires three components:

The presence of a FOCUSLOG member in the concatenation of data sets allocated to DDNAME ERRORS.
The FOCUSLOG file must contain the name of the FOCLOG log file.
An indicator for the type of log desired.

Note: If you perform these steps, you will automatically activate FOCLOG. Do not perform these steps until you are ready to activate FOCLOG.

Example: Requesting a Default Form of the Log

The FOCUSLOG file in this example points to a FOCLOG file named FLHLQ.FOCLOG.DATA. Because the data set name is followed by blanks, this generates a default form of the log containing information about all attributes defined in the FOCLOG Master File, except the data set names of the FOCEXEC files, Access Files, and Master Files.

FLHLQ.FOCLOG.DATA

Example: Requesting a Detailed Form of the Log

This FOCUSLOG member produces a detailed form of the log containing everything in the FOCLOG Master File plus the data set names of FOCEXEC files, Master Files, and Access Files.

To create the detailed log, the FOCLOG file named FLHLQ.FOCLOG.DATA must be followed by at least one blank and the word DETAIL:

FLHLQ.FOCLOG.DATA DETAIL

Example: Requesting a Session Summary Form of the Log

This FOCUSLOG member points to the same log file as the one defined in Requesting a Default Form of the Log on z/OS, but this request creates a session summary form of the log containing only information contained in the session segment of the FOCLOG Master File.

To create a session summary log, the FOCLOG file named FLHLQ.FOCLOG.DATA must be followed by at least one blank plus the word SESSION:

FLHLQ.FOCLOG.DATA SUMMARY

Reference: Notes on Activation and Deactivation of Logging

When FOCUS is initiated, it checks for the presence of the log file. If the FOCUSLOG file is present, usage data is written to memory during the FOCUS session. The information stored in memory is written to the log file at FIN, during FOCUS termination, if a valid log file exists. Therefore, FOCLOG does not produce any unnecessary overhead or use additional CPU cycles for capturing usage data.

Because logging depends on having a FOCUSLOG file, you can deactivate FOCLOG by renaming the FOCUSLOG file.

Note:

Renaming the log file itself does not deactivate logging, it only prevents the log from being copied from memory to a file. However, you can use this technique to save an old log and start a new log file. For example, if the old log file is named FLHLQ.FOCLOG.DATA, rename it to FLHLQ.FOCLOG.DATA1, and allocate a new file as FLHLQ.FOCLOG.DATA.
Log replacement should be done as quickly as possible to avoid losing data that should be captured in the log.

Validating the FOCLOG Configuration

This step validates your FOCLOG configuration and enables you to confirm that the log file was allocated and defined properly. It does not test FOCUS functionality, which is not impacted by FOCLOG.

To create the validation environment, make a test copy of your FOCUS production CLIST or batch job. This CLIST should allocate the production versions of the ERRORS, MASTER, and FOCEXEC DDNAMEs.
Run the test CLIST or batch job to enter FOCUS.
Next, execute a request to populate the log:
At the FOCUS prompt, issue the following command and press Enter to create a temporary FOCUS database named CAR and load it with data:
```
EX FLVALPOP
```
The following messages display:
```
>  NEW FILE CAR      ON 09/15/2007 AT 09.06.57
 CAR      ON 09/15/2007 AT 09.06.57
 WARNING..TRANSACTIONS ARE NOT IN SAME SORT ORDER AS FOCUS FILE
 PROCESSING EFFICIENCY MAY BE DEGRADED
 TRANSACTIONS:       TOTAL =    53  ACCEPTED=    53  REJECTED=     0
 SEGMENTS:           INPUT =   102  UPDATED =     0  DELETED =     0
```
You can ignore any warning messages. The important thing to note is that 53 transactions were accepted and that 102 segments were input. Note: If you have problems running this procedure, please contact the Information Builders Customer Support Services staff.
Exit from FOCUS by issuing the following command and pressing Enter:
```
FIN
```
Ending the FOCUS session updates the log with the information about the procedure you executed.
Run the test CLIST or batch job to enter FOCUS again.
You will now execute a request to produce a validation report from the log.
1. Issue the following command to allocate your log file so that you can issue a report request against it. Replace flhlq with the high-level qualifier for your log file data set. (Note: Before pressing Enter, make sure the data set name is the name of the log file you specified in the FOCUSLOG member of your production ERRORS.DATA library.):
```
DYNAM ALLOC DD FOCLOG DA flhlq.FOCLOG.DATA SHR REU
```
2. Issue the following command and then press Enter to report from the log:
```
EX FLVALRPT
```
  The following messages display to indicate that the report is ready to view:
```
>   NUMBER OF RECORDS IN TABLE=        3  LINES=      3
     PAUSE.. PLEASE ISSUE CARRIAGE RETURN WHEN READY
```
  Press Enter to view the report. It should be similar to the following, but display your session statistics and user ID:
```
PAGE     1
 
VALIDATION OF SESSION COMMANDS ISSUED
 
STARTDATE  SESSTART     USERID  COMMAND   FNAME    RECORDS    LINES
---------  --------     ------  -------   -----    -------    -----
2007/09/15 11:45:05.260 FLHLQ   CREATE    .              0        0
                        FLHLQ   MODIFY    CAR          102        0
                        FLHLQ   TABLE     CAR           18        1
```
  This output shows that the log is working properly. After producing the report, the procedure deallocates DDNAMEs CAR and FOCLOG. Note: If you have problems running this request, please contact the Information Builders Customer Support Services staff.
  
  Press Enter to close the report window.
Exit from FOCUS by issuing the following command and then pressing Enter:
```
FIN
```

You have now completed the configuration and validation process. You can now notify your FOCUS Administrator that the product is available for use.

Note: This validation procedure added data to the log file that does not reflect actual FOCUS usage at your site. Therefore, you should edit the log file to delete this data before putting the log into production. To delete the data, open the log file in the ISPF Edit Panel and delete the lines that contain the data.

Example: Sample FOCUS Session

When you enter an online FOCUS session, you see a banner similar to the following. The two carets at the bottom (> >) are the FOCUS prompt, although your site may have changed the prompt:

  FOCUS  7.6.3   09/15/2007  10.12.52
 
OBSERVED CPU:
******* CEC:  machine type N/A   model ID N/A              capacity N/A
******* LPAR: name N/A                                     capacity N/A
******* Processor AF4A Model 2066-00 Max 02  Site
LICENSED CPU(S):
******* Processor 5394 Model 9672-F0 Max 01 >Registration 57E3C86A0887

The following command executes the request that populates the log:

>  > ex flvalpop

The following messages display:

>   NEW FILE CAR      ON 09/15/2007 AT 09.06.57
 CAR      ON 09/15/2007 AT 09.06.57
 WARNING..TRANSACTIONS ARE NOT IN SAME SORT ORDER AS FOCUS FILE
 PROCESSING EFFICIENCY MAY BE DEGRADED
 TRANSACTIONS:         TOTAL =    53  ACCEPTED=    53  REJECTED=     0
 SEGMENTS:             INPUT =   102  UPDATED =     0  DELETED =     0

The next command ends the FOCUS session and updates the log with statistics regarding the FLVALPOP request:

> fin

Next, we run the CLIST again to go back into FOCUS:

  FOCUS  7.6.3   09/15/2007  10.12.52
 
OBSERVED CPU:
******* CEC:  machine type N/A   model ID N/A              capacity N/A
******* LPAR: name N/A                                     capacity N/A
******* Processor AF4A Model 2066-00 Max 02  Site
LICENSED CPU(S):
******* Processor 5394 Model 9672-F0 Max 01 >Registration 57E3C86A0887

Now we allocate the log file and issue the FLVALRPT request to view information from the log:

>  > dynam alloc dd foclog da flhlq.foclog.data shr reu
>  > ex flvalrpt

The following messages display to indicate that the report is ready to view

>   NUMBER OF RECORDS IN TABLE=        3  LINES=      3
 
 PAUSE.. PLEASE ISSUE CARRIAGE RETURN WHEN READY

Pressing Enter displays the report:

PAGE     1
 
VALIDATION OF SESSION COMMANDS ISSUED
 
STARTDATE   SESSTART      USERID    COMMAND   FNAME     RECORDS    LINES
---------   --------      ------    -------   -----     -------    -----
2007/09/15  11:45:05.260  FLHLQ     CREATE    .               0        0
                          FLHLQ     MODIFY    CAR           102        0
                          FLHLQ     TABLE     CAR            18        1

Next, press Enter to close the report window and return to the FOCUS prompt.

Execute the FIN command to end the FOCUS session:

> fin

Now empty the log file (using ISPF Edit) before putting the log into production.