The UACCT exit is called at different times for different purposes, but the calling sequence is always the same. The first argument indicates the type of call being made. For example, in COBOL the UACCT calling sequence is:

ENTRY UACCT USING CALLTYPE ATCB BILLCODE
    COMMAND FILE LINENO PROCEDURE STATS UACVT

All arguments are input arguments and must not be modified by the called program, except as noted in External Security Violations.

The UACCT exit is called with CALLTYPE=0 for the following FOCUS commands:

TABLE*
TABLEF*
MODIFY*
GRAPH*
SCAN*
MATCH
HOLD
SAVE
SAVB
ANALYSE
REBUILD
CMS/TSO
CREATE
RETYPE
REPLOT

Commands designated with an asterisk (*) also generate a starting-processing call to UACCT (CALLTYPE=2).

When CALLTYPE is 0 the 17 STATS words contain information that can be displayed by issuing the ? STATS command. These statistics are also posted as Dialogue Manager parameters, under the &name shown. All statistics are per command, not cumulative for the FOCUS session.

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 (for example, before the user is made aware that the violation was detected). All the calling arguments are as documented previously, except the STATS area, which in lieu of statistics contains the following items:

(FOC047) USER DOES NOT HAVE SUFFICIENT ACCESS RIGHTS TO FILE:<file>

(FOC052) USER DOES NOT HAVE SUFFICIENT ACCESS RIGHTS TO FIELD:<fieldname>

(FOC054) FILE PROTECTED BY DIFFERENT DBA:<file>

(FOC056) USER ACCESS RIGHTS DO NOT ALLOW INCLUDE OR DELETE:<file>

These exit calls are made following the 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 the processing call is made for all types of data—sequential and VSAM files, IMS data sources, 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 the same as for the Usage Statistics call that will follow, except 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 dealing with 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 issue the following diagnostic message and return to the operating system with a return code of 8:

(FOC999) FOCUS TERMINATED BY USER EXIT ROUTINE UACCT

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 CALLTYPE is 0, 1 or 2, but the most logical time to do so is in a type 2 call after all the parsing has been done and before any data access is attempted. In TSO, the ATCB argument points to the FOCUS task control block, which points at the userid or job name, and the FILE argument is the FOCUS name of the data source to be accessed. In the case of QSAM and VSAM files, it is the ddname to which the data set was allocated, and the dsname can easily be obtained using a RDJFCB macro. In the case of FOCUS data sources it is also the ddname to which the data source has been allocated, except when the logical data source is spread over several data sets, allocated under different ddnames. In the case of IMS or IDMS data sources there is no connection between this FOCUS file name and the physical data sets to be accessed, and the FOCUS file name corresponds to a logical view of these data sources—a PCB in the case of IMS, a subschema for IDMS.

The following listing shows how to link edit the UACCT exit routine into FOCUS. In this example, COBOL user code (in object form) is allocated to ddname USERCODE and is brought in with the INCLUDE USERCODE statement. Any other routines called should also have INCLUDE statements code before the INCLUDE MAINTAIN (UAINT) statement.

//LINK1  EXEC PGM=IEWL,PARM='LET,NCAL,LIST,MAP,SIZE=1024K'
//SYSLMOD...DD  DISP=OLD,DSN=prefix.FOCLIB.LOAD <-- FOCUS load library
//MAINTAIN..DD  DISP=SHR,DSN=prefix.FOCCTL.DATA <-- Maintenance library
//UACCT  ...DD  DISP=SHR,DSN=prefix.user.code   <-- Compiled UACCT code
//SYSUT1 ...DD  UNIT=SYSDA,SPACE=(CYL,(5,5))
//SYSPRINT..DD  SYSOUT=*
//SYSLIN  ..DD  *
  INCLUDE UACCT        .....<-- UACCT and any programs it calls
  INCLUDE MAINTAIN(UAINT)  .<-- Real exit-calling routine
  REPLACE CHARGE        ....<-- Use the new exit-calling routine
  INCLUDE SYSLMOD(CORFOC)   <-- FOCUS itself
  INCLUDE MAINTAIN(CORFOC)  <-- Linkage editor control cards
  NAME  FOCUS(R)       .....<-- Output module
/*

The last three INCLUDE statements must execute in the order shown. The UAINT member of the FOCCTL.DATA PDS replaces the dummy UACCT interface shipped in the distributed version of FOCUS.