audit()

The system function SysLib.audit() writes tracking information to the system log or journal. A program can call this function in the following environments:
  • CICS® for z/OS® (writes to CICS journal)
  • IMS™ BMP (writes to IMS log)
  • IMS/VS (writes to IMS log)
  • z/OS batch (with limitations described below)
  SysLib.audit(
    record anyBasicRecord in
    [, jid SMALLINT in
    ])
record
The name of a record to be written to a journal file.

The first 2 bytes contain the length of the record to be written. The next 2 bytes contain a code that you specify to identify the source of the journal record, and the first byte of that code must be in the range X'A0' to X'FF'.

In addition to containing the record length and record identifier code, the first 28 bytes are reserved for system usage and should not contain user data. Bytes 29 to 32767 are available for audit data.

jid
An optional parameter that specifies the ID (1-99) of the journal file to which the service routine writes the record. If jid is omitted, the record is written, by default, to the system journal. The parameter is a 2-byte binary number.

SysVar.errorCode receives one of the status codes in the next table if you enclose SysLib.audit in a try...end block or if you are in VisualAge® Generator compatibility mode and VGVar.handleSysLibraryErrors is set to 1.

Value in SysVar.errorCode Description
00000000 Successful completion
00000201 Length error
00000202 User source code error
00000204 Journal identifier error
00000803 I/O error

If portability between CICS and non-CICS environments is required, you can develop a non-EGL program with the same name as the system function (audit) to receive the service call in non-CICS environments. When generating for an environment in which the service is not supported, the generator turns the function call into a call to the program with the same name. Alternatively, if the service is not supported in the non-CICS environment, you can test the value of SysVar.sysType to determine the runtime environment, then invoke SysLib.audit() only if you are running in CICS.

Behavior in IMS

The record is automatically converted to IMS log format when EGL adds 2 to the length and inserts 2 bytes of binary zeros following the length field. Only the first byte of the record identifier code is used. The second byte of the record identifier code is ignored. The jid parameter is ignored. IMS/VS has a maximum limit of 32765 bytes.

Limitations for support in z/OS batch

To use the SysLib.audit() function in z/OS batch, you must specify a PSB for the program, and the program must do at least one of the following:
  • References a PSB or PCB in any statement in the program
  • Has DL/I databases other than elawork or elamsg in the PSB definition
  • Uses VGLib.VGTDLI()
  • Associates at least one file with GSAM
If these conditions are met, SysLib.audit() will behave in the z/OS batch environment just as it does in IMS.

Example

move 32765 to wrkrec.length;
move "A" to wrkrec.code;
move 2 to jrnlid;
move "THIS IS THE DATA TO BE WRITTEN TO JOURNAL NUMBER 2" to wrkrec.data;
SysLib.audit(wrkrec, jrnlid);
Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.