In this section: |
FOCUS contains a user exit designed to log FOCUS usage statistics, to capture attempted violations of the DBA rules specified in the Master File, and to trap violations detected by external security systems such as RACF and ACF2. Usage statistics are provided following the completion of FOCUS commands that access data, such as TABLE, MATCH, and MODIFY, whether entered live or executed from a procedure, and DBA violations are logged as detected. External security violations can be trapped before any data is accessed and can cause an orderly exit from FOCUS.
The exit routine is also called once at the start of the FOCUS session and once at the end, to permit orderly initialization and wrap-up procedures. FOCUS provides the necessary information in the exit routine calling sequence, but it does not write an accounting or security log. The responsibility for managing these files and any other resources needed by this facility resides with the installation-written accounting exit.
The distributed copy of FOCUS contains a dummy version of this exit routine. To activate a live version, a small interface routine and the user code are link edited into FOCUS. The user code can be written in any language or mixture of languages, and it can issue all system macros except STAI and STAX. It is entered through a standard IBM CALL macro, at entry point UACCT. Since this code becomes an integral part of the FOCUS code, name conflicts with FOCUS routines must be avoided and it is suggested that all user-written programs start with the letters UA.
The UACCT exit is called at different times for different purposes, but the calling sequence is the same in all cases. The first argument indicates which type of call is being made. For example, in COBOL the UACCT calling sequence is:
ENTRY UACCT USING CALLTYPE ATCB BILLCODE
COMMAND FILE LINENO PROCEDURE STATS UACVTAll arguments are input arguments and must not be modified by the called program, except as noted in the section dealing with external security violations.
Argument | Description | |
|---|---|---|
CALLTYPE | 4-byte binary integer | |
-1 | Initialization call, made at start of job or session. | |
-2 | Wrap-up call, made at end of job or session. | |
0 | Usage statistics call, made following the completion of most FOCUS commands. | |
1 | DBA violation call, made as detected. | |
2 | FOCUS starting processing call, made after parsing but before data access. | |
ATCB | 4-byte address The address of the FOCUS task control block. The TSO userid or batch job name and various other items can be obtained from this standard IBM control block. Not meaningful under CMS. The ATCB parameter is present in all calls. The remaining arguments are also present but they are meaningful only when the CALLTYPE is 0, 1 or 2. | |
BILLCODE | 8 characters FOCUS billing code, set by the FOCUS command SET BILLCODE=value. This argument is included to enable accounting distinctions within a user ID. | |
COMMAND | 8 characters FOCUS command name to which the exit call applies. | |
FILE | 8 characters FOCUS file name. | |
LINENO | 4-byte binary integer The current FOCEXEC procedure line number. | |
PROCEDURE | 8 characters The name of the FOCEXEC containing the command that triggers the call to the Usage Accounting exit. Dialogue Manager commands and comment lines do not trigger calls to Usage Accounting. If the command that triggers the call is terminal input, PROCEDURE is blank. | |
STATS | 17 fullword binary integers Contains either usage statistics or DBA violation data. Ignore it if the call is to signal start of processing (CALLTYPE = 2). | |
UACVT | Not currently in use. | |
The UACCT exit is called with CALLTYPE=0 for the following FOCUS commands:
The commands marked with an asterisk also generate a start of processing call to UACCT (CALLTYPE=2).
When CALLTYPE is 0, the 17 STATS words contain the information displayed by the ? STATS command. These statistics are also posted as Dialogue Manager parameters, under the &name shown. All statistics are per command, not cumulative over the FOCUS session.
|
Word |
Dialogue Manager Variable |
|---|---|
|
STATS(1) |
&RETCODE FOCUS return code posted by the command (this is not the return code posted when FOCUS exits). Zero indicates that the command executed successfully. |
|
STATS(2) |
&RECORDS The number of records retrieved by a TABLE, TABLEF or GRAPH command. When more than one segment is referenced by the command, a record is a path in the referenced subtree. |
|
STATS(3) |
&LINES The number of lines created by the report, or the number of records SAVED or HELD, before the application of IF TOTAL tests. |
|
STATS(4) |
Reserved. |
|
STATS(5) |
&BASEIO The number of 4096 bytes pages read or written in the FOCUS database. The value will be zero for non-FOCUS files. |
|
STATS(6) |
The number of reads issued when reporting from a non-FOCUS file. The value will be zero for FOCUS files. Each read is a QSAM GET, ISAM GET, or one call to the interface module. In the case of data adapters, such as the IMS/DB, IDMS, TOTAL, ADABAS, and FOCSAM interfaces, each call produces one instance of one segment. |
STATS(7) to STATS(16) are statistics posted by the MODIFY and SCAN commands. These statistics will have the value zero for all other commands.
|
Word |
Dialogue Manager Variable |
|---|---|
|
STATS(7) |
&TRANS |
|
STATS(8) |
&ACCEPTS |
|
STATS(9) |
&INPUT |
|
STATS(10) |
&CHANGED |
|
STATS(11) |
&DELETED |
|
STATS(12) |
&NOMATCH |
|
STATS(13) |
&DUPLS |
|
STATS(14) |
&FORMAT |
|
STATS(15) |
&INVALID |
|
STATS(16) |
&REJECTS |
|
STATS(17) |
&SORTIO The number of reads and writes to the FOCSORT scratch file. Zero indicates that the sort phase of the report is executed entirely in core. |
Note: FOCUS databases and the FOCSORT scratch file are BDAM data sets and, as such, must be formatted before they can be used. Formatting occurs when the CREATE command is issued or when the FOCUS database is extended in the course of a MODIFY command; FOCSORT is formatted by the first write to it. The formatting I/O activity is not included in the &BASEIO or in the &SORTIO statistics.
Execution time DBA violations arising from insufficient access rights generate one of several FOCUS error messages, depending on the nature of the violation, and the accounting exit routine is called with CALLTYPE=1 to log this event. The call to log the violation occurs before the corresponding error message is displayed (before the user is made aware that the violation was detected).
All of the calling arguments are as documented in UACCT Calling Sequence, except the STATS area, which, in lieu of statistics, contains the following items:
|
Word |
Description |
|---|---|
|
STAT(1) |
4 byte binary integer The FOCUS error message number (for example 47, 56). |
|
STAT(2) |
4-byte binary integer The length, in bytes, of the variable portion of the error message. |
|
STAT(3) |
A character string of the length indicated by STAT(2), the variable portion of the error message. This will be the FOCUS file name or field name to which the message refers. |
The possible error messages follow. The variable portion of the message is shown in brackets.
(FOC047) USER DOES NOT HAVE SUFFICIENT ACCESS RIGHTS TO FILE:<file>
(FOC052) USER DOES NOT HAVE ACCESS TO THE FIELD:<fieldname>
(FOCO54) THE FILE IS PROTECTED BY DIFFERENT DBA ADMINISTRATOR:<file>
(FOCO56) THE USER'S ACCESS RIGHTS DO NOT ALLOW INCLUDE OR DELETE:<file>
Error messages 54 and 56 can occur only with FOCUS databases, but 47 and 52 can occur in any FOCUS-readable file protected by the DBA feature.
These exit calls are made after parsing and verification of the retrieval commands (TABLE, TABLEF, GRAPH, MATCH) and of the SCAN and MODIFY commands, but before any attempt is made to access the data. For retrieval commands, the start of processing call is made for all types of data, sequential and VSAM files, IMS data source, FOCUS data sources, and, in the case of VSAM and QSAM files, before they are opened. The CALLTYPE is 2 and all other arguments are exactly as for the Usage Statistics call which will follow, except, of course, that the STATS argument is not available.
The UACCT exit routine can perform any type of accounting or logging activity, and it can also interrogate external security systems such as RACF or ACF2 to determine if the current FOCUS command is accessing secured files or data sets. If a security violation is detected, UACCT can terminate FOCUS gracefully by changing the input COMMAND argument to 8 bytes of binary zeroes. In this event FOCUS will return to the operating system with a return code of 8.
The COMMAND argument is the only modifiable argument in the UACCT calling sequence; all other arguments must be left as they were.
FOCUS can be terminated in this way in all UACCT calls in which the CALLTYPE is 0, 1, or 2, but the most logical time to do it is in a type 2 call, after all parsing has been done and before any data access is attempted.
To install the Usage Accounting exit routine (UACCT) on CMS, you must replace a dummy version of the code that calls UACCT with a working version. This is achieved by copying the files on the maintenance disk. The distribution tape contains the dummy code as file UAINT TEXT and the working version as UAINTSYS TEXT. Take the following steps to install the UACCT exit routine on CMS:
COPYFILE UAINT TEXT A UAINTDUM TEXT A (REPL OLDDATE)
COPYFILE UAINTSYS TEXT A UAINT TEXT A (REPL OLDDATE)
| Information Builders |