Use FOCUS security attributes to specify that a user-written program be called immediately after a TABLE or GRAPH command has completed, but before the report is printed. Activate this user-written program by assigning the value PROGRAM to the RESTRICT attribute. The program is passed the statistics of the run, or number of records retrieved, lines of sorted results, and the identity of each data field that was active in the run. You can use this user program exit to:

• Monitor the retrieval activity for particular data sources. For example, the number of requests, number of records retrieved, distribution of usage by user category (by userid or password identity).
• Monitor the usage frequency of items in a data source.
• Perform usage accounting based on values such as number of records retrieved.
• Provide another level of security in which the user program exit determines whether the report should be displayed.

The accounting aspects of this feature are enforceable only for the TABLE and GRAPH commands, not the TABLEF command.

Activate a DBA user program by adding the following attributes to the security section of any Master File for each user that you want the program to monitor

USER=name, ACCESS=R, RESTRICT=PROGRAM,
NAME=pgmname, VALUE=returncode,$

where:

name

Is the arbitrary code name used to identify the user (8 bytes).

pgmname

Is the name of the user-written program (8 bytes).

returncode

Must be matched with the VALUE specified for this user (8 bytes).

For example:

USER=PETER, ACCESS=R, RESTRICT=PROGRAM,
NAME=PETER1, VALUE=D76,$

Calls the program Peter1 which will return a value. If the value is D76, then this passes DBA.

You can specify other restrictions for the users mentioned in addition to calling the program.

The user program must be coded as a subroutine in a language that can be dynamically linked at FOCUS execution time in the operating environment. COBOL is acceptable in all environments, as are PL/I and Assembler. Languages acceptable for different environments are covered in the Overview and Operating Environments manual.

Six arguments are supplied to the user program. The first five are computed by FOCUS; the last is returned by the user program to FOCUS. The value of the last argument is matched to a value provided in the DBA section of the Master File. The purpose of this is to prevent a spurious program of the same name from being substituted for the real one. If the DBA value and the retrieval value do not match, the report is not printed and FOCUS exits immediately.

The arguments to the call are:

FILEID

NUMB

ACT

RECORDS

LINES

RETVALUE

You can make a VALUE condition for some overall limitation on retrieval ability. For instance, you can limit the maximum number of records a user can retrieve in a single TABLE request. This restriction can be activated if a selected segment is referred to in the request, or it can be active for every request.

Record limitation is added by the phrase

RESTRICT=VALUE ,NAME= {segname|SYSTEM} ,VALUE=RECORDLIMIT EQ n,$

where:

n

Is an integer greater than 0.

For example:

USER=TILLY, ACCESS=R, RESTRICT=VALUE, NAME=SYSTEM,
VALUE=RECORDLIMIT EQ 1000, $

or

USER=TILLY, ACCESS=R, RESTRICT=VALUE, NAME=COMPSEG,
VALUE=RECORDLIMIT EQ 1000, $

The second example limits the number of records retrieved only if fields from segment COMPSEG are referred to in the report request.

For non-FOCUS data sources, READLIMIT EQ can be used exactly as RECORDLIMIT EQ to set an automatic maximum on the number of successful reads issued for sequential data sources or the number of calls made to an external file system.

The Usage Accounting and Security Exit Routine (UACCT) provides information for an installation:

• To log FOCUS usage after FOCUS commands which access data, such as TABLE, MODIFY, or MATCH.
• To capture attempted violations of the DBA provisions in the Master File.
• To trap violations detected by external security systems.

The distributed copy of FOCUS contains a dummy version of the UACCT exit routine. To use a working version of UACCT, you must install it as described in your installation documentation.