Utilities Used with Adabas Auditing

Various Adabas utilities and specific utility functions are used in auditing. Some of these utilities and functions apply only to the source Adabas nucleus, some of them apply only to the Adabas Audit Server, and some of them apply to both the Adabas nucleus and the Adabas Audit Server.

The following table lists the utilities and utility functions which apply to the use of Adabas Auditing and indicate whether they are relevant to the Adabas Audit Server and/or Adabas database.

Utility and Function Adabas Audit Server Adabas Database
ADAARP REPLAY Yes No
ADACHK ALOGPRINT Yes No
ADACMP COMPRESS AUDITNM= No Yes
ADADBS ADDALOG Yes No
ADADBS AUDITSERVER Yes No
ADADBS DELALOG Yes No
ADADBS MODFCB AUDITNM= No Yes
ADADBS OPERCOM AUDCONNECT Yes Yes
ADADBS OPERCOM DAUDPARM and DAUDSTAT Yes Yes
ADADBS OPERCOM FEOFAL Yes No
ADADEF DEFINE AUDITSERVER Yes No
ADADEF MODIFY AUDITSERVER Yes No
ADAFRM ALOGFRM Yes No
ADALOD LOAD Yes Yes
ADAORD STORE Yes No
ADAREP REPORT Yes Yes
ADARES ALCOPY Yes No

The following sections describe these utilities and functions in detail.


ADAARP Utility: Replay ALOG Events from PLOGs

The ADAARP utility, also known as the Replay Utility, provides a mechanism by which you can read an Adabas PLOG and resend Adabas events to one or more Audit Servers. This utility reads the sequential (merged) PLOG of an Adabas database and, based on the parameters you specify, sends related data to one or more Audit Servers.

Note:
The version of Audit software used by the ADAARP utility job must match the version used by the Audit Server.

ADAARP sends the events to the Audit Server in unsynchronous mode: the new Adabas events are processed concurrently with the replayed events - no synchronization is performed.

The net effect of unsynchronized mode replay processing is that the target application receives event data reconstructed from the PLOG data sets at the same time and interleaved with any new event data produced by Adabas. The data is not processed in the chronologically correct sequence.

Note:
The audit item record contains the time (UABIITIM) when the audit item was created in the source nucleus. The replayed event will show this time. Hence it could be used as sort criteria for chronological order.

When replay processing is initiated, a token is assigned to the replay process. This token can be used to cancel the replay process, if necessary.

This section covers the following topics:

Functional Overview

The Replay Utility can recover event data of update commands (Updates, Inserts, Deletes) from the sequential PLOG data sets (after copying and merging them) for the time over which auditing processing was interrupted. You must be sure to supply the correct:

  • PLOG information

  • Date and Time settings

  • File number settings

  • Target Audit Server information

New replay data items and items processing for the same database files can be occurring simultaneously.

The following processing occurs once the Replay Utility is started:

  1. The Replay Utility reads through all transactions on the specified sequential PLOG, starting with records with the specified start (from) date and time, and ending with records with the stop (to) date and time. Start and stop times are specified in the Replay Utility run.

  2. As records are read, only those for fully completed commands on the specified database files are processed:

    • If FROMDATE/FROMTIME is not specified, all event data are sent to the Audit Server.

    • If TODATE/TOTIME is specified, replay processing stops when a PLOG record is read that has a timestamp higher than or equal to TOTIME.

    • If TODATE/TOTIME is not specified, ADAARP processing stops after reading the last block of the PLOG.

  3. Event data selected for processing are sent to the target Audit Servers selected for the run.

All date and time parameters are specified in local time. FROMDATE, FROMTIME, TODATE and TOTIME are internally converted to UTC since the time stamps on the PLOG are written in UTC. This conversion is always done based on the current time difference between local time and UTC.

ADAARP Prerequisites

The following prerequisites must be met to effectively use the Replay Utility in batch mode:

  • Verify that the following ADARUN parameters are specified in ADAARP JCL (DDCARD):

    ADARUN PROG=ADAARP,DBID=dbid,SVC=svc,MODE=MULTI,LAP=size

    where dbid is the Adabas database ID on which the files that are being replayed reside, svc is the SVC number to be used for communications with Adabas and the Audit Server, and size is size of the Auditing pool. Running the Replay Utility with MODE=SINGLE will default to MODE=MULTI.

  • Verify that the correct PLOG is used for the run and that it is a sequential PLOG, not a dual PLOG. The PLOG is specified with the DD name DDSIIN.

  • Specify valid values for ADAARP parameters (DDKARTE), as appropriate.

  • Specify Auditing parameters (ADAANP DD statement).

  • Either the Adabas database must be active or the DDASSO DD statement must be specified in the JCL, identifying the ASSO data set for the run. ADAARP will attempt to issue a call to Adabas to obtain the GCB, FCBs, and FDTs from the nucleus. If this call fails, it will attempt to read this information itself using the ASSO data set specified in the Replay Utility run.

ADAARP Syntax and Parameters

The syntax and parameters vary depending how much protection log shall be processed.

ADAARP REPLAY { [FROMDATE=yyyymmdd [FROMTIME=hhmmss]]
      [TODATE=yyyymmdd [TOTIME=hhmmss]]	 }

Optional Parameters

Parameter Description Default
FROMDATE Specifies a start date in yyyymmdd format. Replay processing will include PLOG records that ended at or after this date. Replay Utility processing starts at the beginning of the PLOG and includes all PLOG records.
FROMTIME Specifies a start time in hhmmss format. Replay processing will include PLOG records that ended at or after this time. This parameter cannot be specified unless the FROMDATE parameter is specified also. Replay Utility processing starts at the beginning of the PLOG records for the date specified by the FROMDATE parameter, if any, and includes all PLOG records.
TODATE Specifies an end date in yyyymmdd format. Replay processing will stop with PLOG records that ended at or after this date. Replay Utility processing stops at the end of the PLOG and includes all PLOG records.
TOTIME Specifies an end time in hhmmss format. Replay processing will stop with PLOG records that ended at or after this time. This parameter cannot be specified unless the TODATE parameter is specified also. Replay Utility processing stops at the end of the PLOG records for the date specified by the TODATE parameter, if any, and includes all PLOG records.

Syntax of Auditing parameters read from ADAANP dataset

These parameters are described in the ADABAS Nucleus Auditing parameters (ADAANP) section of this documentation.

Only the following file-related parameters are relevant for the ADAARP utility:

Parameter Description Valid Values Default
FILE

The FILE parameter denotes the start of a group of auditing parameters related to one or more files. The FILE parameter is specified as a word standing by itself.

-

-

FLIST

The parameter FLIST is used to give the list of one or more files that relate to the current FILE definition. The FLIST parameter will allow the user to specify one or more files singly or as a range of files.

-

-

FSERVERID

Server ID – This definition specifies the Audit Server ID to be used when data is collected for the file(s).

If this parameter is not specified for the file, the global server ID is used.

The server ID may not be set to the database ID associated with the currently active nucleus.

1 - 65,535

-

FDELDS

Control collection of the data storage image for a delete command.

FIELDS|NO|YES

YES

FINSDS

Control collection of the data storage image for an insert command.

FIELDS|NO|YES

YES

FUPDAI

Control collection of the data storage (after) image for an update command.

FIELDS|NO|YES

YES

FUPDBI

Collect the before image of data storage for an update command – This definition specifies whether the before image of data storage will be collected for an update command issued for the file(s).

FIELDS|NO|YES

When value 'FIELDS' is set, the before image of data storage will be collected if one or more fields specified in the FUPDFIELDS parameter is referenced by an update command issued for the file(s). When value 'NO' is set, the before image of data storage will not be collected for an update command issued for the file(s). When value 'YES' is set, the before image of data storage will be collected for an update command issued for the file(s).

NO

Other ADAANP parameters are ignored.

Example:

Original event
UABI -- 'CMD' audit item with 4 data elements for subscription SUB1
     IT 2022-07-28 16:31:56.761966.629 dbid 8/0
     AS 2022-07-28 16:32:02.006011.751
     secuid='',fnr=22, isn=1109, cmd=A1

Replayed event
UABI -- 'CMD' audit item with 4 data elements for subscription SUB1
     IT 2022-07-28 16:31:56.761938.129 dbid 8/0
     AS 2022-07-28 16:33:47.652451.004
     secuid='',fnr=22, isn=1109, cmd=A1 		

Sample JCL

The following sample JCL could be used to run ADAARP. In this sample, PLOG records from files 1, 4, and 6 of the Adabas database are replayed.

Note:
The ASSO data set is required in the JCL if the Adabas database is inactive.

//ADAARP   JOB
//*
//*  ADAARP: Sample JCL to invoke ADAARP to process completed
//*          commands starting at the beginning of the PLOG and
//*          ending at the end of the PLOG for files 1, 4, and 6.
//*
//RPL      EXEC  PGM=ADARUN
//STEPLIB  DD  DISP=SHR,DSN=ADABAS.Vvrs.LOAD  <=== Adabas load lib 
//DDASSOR1 DD  DISP=SHR,DSN=EXAMPLE.DBdbid.ASSOR1 <=== Adabas ASSO
//DDSIIN   DD  DISP=SHR,DSN=EXAMPLE.PLOG101   <=== Sequential PLOGs
//         DD  DISP=SHR,DSN=EXAMPLE.PLOG102   <=== (concatenated)
//         DD  DISP=SHR,DSN=EXAMPLE.PLOG103
//DDDRUCK  DD  SYSOUT=X
//DDPRINT  DD  SYSOUT=X
//SYSUDUMP DD  SYSOUT=X
//DDCARD   DD  *
ADARUN PROG=ADAARP,DBID=dbid,SVC=svc,MODE=MULTI,DEVICE=3390,LAP=10M
//DDKARTE  DD  *
ADAARP REPLAY 
//ADAANP  DD   *
ADAANP GLOBAL                 
ADAANP GSERVERID=2052         
*                    
* FILE PARAMETERS    
*                    
ADAANP FILE          
ADAANP FLIST=1,4,6     
ADAANP FSERVERID=2052
ADAANP FUPDAI=YES    
ADAANP FUPDBI=NO     
ADAANP FUPDFB=YES    
//

ADACHK ALOGPRINT

The ADACHK ALOGPRINT function can be used to print the contents of any block or range of blocks in the audit log (ALOG) data set while concurrent updates are running.

 ADACHK ALOGPRINT	RABN={rabn|rabn1-rabn2}[,{rabn|rabn1-rabn2}]...
                       [ABEND]   
                       [DEVICE=device]   
                       [ERRLIM={error-threshold-count|100}]   
                       [LAYOUT={SHORT|MEDIUM|LONG}]   
                       [NOUSERABEND]   
                       [NUMBER={number|1}]   
                       [TEST]

The following sections cover the topics:

Essential Parameters

RABN: RABNs to Be Processed

The RABNs or ranges of RABNs to be printed or dumped.

Optional Parameters and Subparameters

ABEND34: Change User Abend 35 to 34

This optional parameter can be used to change a user abend 35 to user abend 34 if a utility error occurs. This ensures that a dump is produced when the utility terminates abnormally.

The NOUSERABEND, TEST, and ABEND34 parameters affect the processing of the entire ADACHK run.

DEVICE: Device Type

The device type that contains the data set to be printed. This parameter is required if the device type is different from the standard device type assigned by the ADARUN DEVICE parameter.

ERRLIM: Error Threshold

The maximum number of errors that this ADACHK utility function will tolerate before terminating. Valid values are any positive integer equal or less than 5000. If no valid value is specified for this parameter, a default of "100" is used.

If a value less than 0 or greater than 5000 is specified, the following error will result, and the default value will be used:

CHK413E, ERROR: Parameter ERRLIM is incorrect.

NUMBER: Command Log Data Set Number

The number of the multiple (two through eight) audit log (ALOG) data set from which the blocks are to be printed. If NUMBER is not specified, the blocks are taken from DD/ALOGR1 (the default).

LAYOUT: Report Detail Level

The level of data produced for the report or dump. Valid values are described in the following table. For more information about the output sections described below, read the Adabas for Mainframes documentation > Utilities > Functional Overview > ADACHK Print Function Output Format.

Valid Values Description
SHORT Specify this value to produce the minimum output, printing sections 1 and 2 of the possible output. This is the default.
MEDIUM Specify this value to produce medium-level output, printing sections 1 and 3 of the possible output.
LONG Specify this value to produce extensively-detailed output, printing all three sections of the possible output.

Note:
The results from the LAYOUT=LONG setting are what you get when you run the equivalent ADAICK utility function.

NOUSERABEND: Termination without Abend

When a parameter error or a functional error occurs while this utility function is running, the utility ordinarily prints an error message and terminates with user abend 34 (with a dump) or user abend 35 (without a dump). If NOUSERABEND is specified, the utility will not abend after printing the error message. Instead, the message "utility TERMINATED DUE TO ERROR CONDITION" is displayed and the utility terminates with condition code 20.

Note:
When NOUSERABEND is specified, we recommend that it be specified as the first parameter of the utility function (before all other parameters). This is necessary to ensure that its parameter error processing occurs properly.

TEST: Test Syntax

The TEST parameter tests the operation syntax without actually performing the operation. Note that the validity of values and variables cannot be tested: only the syntax of the specified parameters can be tested. See section Adabas for Mainframes documentation > Utilities > ADACHK Utility: Database Consistency Check Utility that Runs Concurrently with Normal Database Operations > Functional Overview > Syntax Checking with the TEST Parameter for more information about using the TEST parameter in ADACHK functions.

The NOUSERABEND, TEST, and ABEND34 parameters affect the processing of the entire ADACHK run.

Example

In the following example, audit log RABNs 1, 2, 30-31, and 2000 are printed from DD/ALOG1.

ADACHK ALOGPRINT RABN=1,2,30-31,2000

ADACMP COMPRESS AUDITNM=

The ADACMP COMPRESS parameter AUDITNM= is used to assign an Audit Name to an Adabas file when it is compressed by ADACMP.

The Audit Name is an 8-character alphanumeric identifier used to track auditing information for Adabas files and must be unique across all Adabas files used in auditing. The Audit Name must be enclosed in single quotes if it contains embedded blanks.

Example

Assign the Audit Name ACCOUNTS to file 100:

ADACMP COMPRESS FILE=100,AUDITNM=ACCOUNTS

ADADBS ADDALOG

The ADDALOG function allows you to dynamically add a new audit log (ALOG) data set without terminating your current Audit Server session. Using this utility function, you can specify up to eight ALOG data sets. This will reduce the chances of a wait condition in the Audit Server when the Audit Server waits for an available ALOG. You might find this particularly useful during busier times of the month or year.

To add an ALOG data set dynamically, the Audit Server must know about its JCL at startup time. We recommend that you set up your Audit Server startup jobs to include definition statements for the maximum number of ALOG data sets as you plan to use, but limit the actual usage of the ALOGs using the ADARUN NALOG parameter. For example, you might start a nucleus with eight ALOG definitions in the Audit Server startup JCL, but limit the number of ALOGs actually used during Audit Server processing to three ALOGs by setting the NALOG parameter to "3". When the Audit Server starts up, only three ALOGs will be opened and logged in the PPT, even though eight are defined in the JCL. The additional ALOG data sets can then be dynamically added using this ADADBS ADDALOG utility.

Note:
Any ALOG data sets you add dynamically will not be retained once you recycle your Audit Server. To retain these new ALOG data sets when the Audit Server is stopped and restarted, alter the Audit Server startup JCL as well. You must ensure that the number of ALOG definition statements in the JCL matches the increased number of ALOG data sets and that the NALOG ADARUN parameter setting includes the new ALOG data sets.

Running the ADADBS ADDALOG utility function is invalid when the Audit Server is running with dual ALOGs.

ADADBS ADDALOG	NUMBER=alog-ds-number   
               [NOUSERABEND]   
               [ALOGDEV=device-type]   
               [TEST]

The following sections cover the topics:

Essential Parameters

NUMBER: ALOG Data Set Number

Use the NUMBER parameter to specify the number of the nonsequential ALOG data set to be added. Valid values are integers ranging from "2" through "8".

Note:
Be sure that the Audit Server startup JCL allows for this additional ALOG data set by including a definition statement for the data set. If a definition statement is not already specified for this ALOG data set in the Audit Server startup JCL, you will need to add it now and recycle the server. Ideally, you would already have included definition statements in the JCL for all potential ALOG data sets, even though they are not all in use when the Audit Server starts up.

Optional Parameters

ALOGDEV

Use the optional ALOGDEV parameter to specify the device type to be used for the new ALOG data set. This parameter is required only if a different device type from the device type specified by the ADARUN DEVICE parameter is to be used. The default is to use the device type specified by the ADARUN DEVICE parameter.

NOUSERABEND: Termination without Abend

When a parameter error or a functional error occurs while this utility function is running, the utility ordinarily prints an error message and terminates with user abend 34 (with a dump) or user abend 35 (without a dump). If NOUSERABEND is specified, the utility will not abend after printing the error message. Instead, the message "utility TERMINATED DUE TO ERROR CONDITION" is displayed and the utility terminates with condition code 20.

Note:
When NOUSERABEND is specified, we recommend that it be specified as the first parameter of the utility function (before all other parameters). This is necessary to ensure that its parameter error processing occurs properly.

TEST: Test Syntax

The TEST parameter tests the operation syntax without actually performing the operation. TEST checks only the syntax of the specified parameters; not the validity of values and variables. See the Adabas for Mainframes documentation > Utilities > ADADBS Utility: Database Services > Functional Overview > Syntax Checking with the TEST Parameter for more information about using the TEST parameter in ADADBS functions.

Example

In the following example, ALOG data set 3 is dynamically added using a 3390 device.

ADADBS ADDALOG NUMBER=3,ALOGDEV=3390

ADADBS AUDITING

The ADADBS AUDITING function provides activation and deactivation of Adabas files that are participating in auditing. This function should be used for Adabas databases with auditing enabled. It is not valid for use with Adabas Audit Servers.

ADADBS AUDITING {ACTIVATE | DEACTIVATE }   
                 FILE=filenumber    
                 NUCID=nucid  

The following sections cover the topics:

Essential Parameters

One of the parameters, ACTIVATE or DEACTIVATE, as well as the FILE parameter must be set. There is no default.

ACTIVATE: Adabas Database File Activation Request

The ACTIVATE parameter requests activation for the specified file. The specified file must not be actively participating in auditing.

DEACTIVATE: Adabas Database File Deactivation Request

The DEACTIVATE parameter requests deactivation for the specified file. The specified file must be actively participating in auditing.

FILE: Adabas Database File Number

The FILE=filenumber parameter indicates the ADABAS file to be activated or deactivated.

Optional Parameters

NUCID: Nucleus ID for a Cluster Database

The NUCID=nucid parameter identifies the nucleus ID in a cluster database. It applies only to cluster databases and is not valid for non-cluster databases.

Examples

The following example requests that the Adabas Database deactivate file 100 from sending audit information to the Audit Server.

ADADBS AUDITING ACTIVATE,FILE=100

The following example requests that the Adabas Database deactivate file 100 from sending audit information to the Audit Server.

ADADBS AUDITING DEACTIVATE,FILE=100

ADADBS AUDITSERVER

The ADADBS AUDITSERVER function provides activation, deactivation, open, and close control of Adabas Audit Server resources. It also provides a means to display the databases and files that audit information is being collected for. This function should be used with Adabas Audit Servers; it is not valid for use with Adabas databases.

ADADBS AUDITSERVER {ACTIVATE | DEACTIVATE | OPEN | CLOSE | DISPLAYDB}   
                    DESTINATION=dest-name   
                    SUBSCRIPTION=sub-id  

The following sections cover the topics:

Essential Parameters

One of the parameters, ACTIVATE, DEACTIVATE, OPEN, CLOSE, or DISPLAYDB must be set. There is no default.

ACTIVATE: Audit Server Resource Activation Request

The ACTIVATE parameter requests activation for the specified destination or subscription.

DEACTIVATE: Audit Server Resource Deactivation Request

The DEACTIVATE parameter requests deactivation for the specified destination or subscription.

OPEN: Audit Server Resource Open Request

The OPEN parameter requests that a closed destination be opened. When this parameter is specified, the DESTINATION parameter must be specified.

CLOSE: Audit Server Resource Close Request

The CLOSE parameter requests that an open destination be closed. When this parameter is specified, the DESTINATION parameter must be specified.

DISPLAYDB: Display Audit Server Databases and Files Request

The DISPLAYDB parameter requests that all databases and files known to the audit server be listed. Neither DESTINATION nor SUBSCRIPTION are specified.

Note:
The source Adabas Database may or may not be actively generating audit information for the files listed.

Optional Parameters

DESTINATION: Audit Destination

The DESTINATION parameter can only be specified when the ACTIVATE, DEACTIVATE, OPEN, or CLOSE parameters are specified. The DESTINATION parameter supplies the name of the destination that should be activated, deactivated, opened, or closed. The destination specified must be defined to the Audit Server.

If ACTIVATE is specified, the destination must already be inactive. If DEACTIVATE is specified, the destination must already be activated.

If OPEN is specified, the destination must be in a closed state. If CLOSE is specified, the destination must be in an open state.

The DESTINATION parameter is mutually exclusive with the SUBSCRIPTION parameter.

SUBSCRIPTION: Audit Subscription

The SUBSCRIPTION parameter can only be specified when the ACTIVATE or DEACTIVATE parameters are specified.

The subscription specified for the SUBSCRIPTION parameter must be defined to the Audit Server. It specifies the ID of the subscription definition to use.

If ACTIVATE is specified, the subscription must already be deactivated. If DEACTIVATE is specified, the subscription must already be activated.

The SUBSCRIPTION parameter is mutually exclusive with the DESTINATION parameter.

Examples

The following example requests that the Audit Server activate the destination defined by the DEST0001 destination. The destination is currently inactive.

ADADBS AUDITSERVER ACTIVATE,DESTINATION=DEST0001

The following example requests that the Audit Server activate the subscription defined by the SUBS0001 subscription. The subscription is currently inactive.

ADADBS AUDITSERVER ACTIVATE,SUBSCRIPTION=SUBS0001

The following example requests that the Audit Server deactivate the destination defined by the DEST0001 destination. The destination is currently active.

ADADBS AUDITSERVER DEACTIVATE,DESTINATION=DEST0001

The following example requests that the Audit Server deactivate the subscription defined by the SUBS0001 subscription. The subscription is currently active.

ADADBS AUDITSERVER DEACTIVATE,SUBSCRIPTION=SUBS0001

The following example requests that the Audit Server open destination DEST0001.

ADADBS AUDITSERVER OPEN,DESTINATION=DEST0001

The following example requests that the Audit Server close destination DEST0001.

ADADBS AUDITSERVER CLOSE,DESTINATION=DEST0001

ADADBS DELALOG

The DELALOG function allows you to dynamically delete an audit log (ALOG) data set without terminating your current Audit Server session.

Note:
Any ALOG data sets you delete dynamically may reappear once you recycle your Audit Server. To ensure the ALOG data set is dropped when the Audit Server is stopped and restarted, alter the Audit Server startup JCL as well, ensuring that the NALOG ADARUN parameter setting is reduced to account for the dropped ALOG data sets.

Running the ADADBS DELALOG utility function is invalid when the Audit Server is running with dual ALOGs.

ADADBS DELALOG	NUMBER=alog-ds-number   
               [NOUSERABEND]   
               [TEST]

The following sections cover the topics:

Essential Parameters

NUMBER: ALOG Data Set Number

Use the NUMBER parameter to specify the number of the nonsequential ALOG data set to be deleted. Valid values are integers ranging from "2" through "8".

Optional Parameters

NOUSERABEND: Termination without Abend

When a parameter error or a functional error occurs while this utility function is running, the utility ordinarily prints an error message and terminates with user abend 34 (with a dump) or user abend 35 (without a dump). If NOUSERABEND is specified, the utility will not abend after printing the error message. Instead, the message "utility TERMINATED DUE TO ERROR CONDITION" is displayed and the utility terminates with condition code 20.

Note:
When NOUSERABEND is specified, we recommend that it be specified as the first parameter of the utility function (before all other parameters). This is necessary to ensure that its parameter error processing occurs properly.

TEST: Test Syntax

The TEST parameter tests the operation syntax without actually performing the operation. TEST checks only the syntax of the specified parameters; not the validity of values and variables. See the Adabas for Mainframes documentation > Utilities >ADADBS Utility: Database Services > Functional Overview > Syntax Checking with the TEST Parameter for more information about using the TEST parameter in ADADBS functions.

Example

In the following example, ALOG data set 3 is dynamically deleted from its 3390 device.

ADADBS DELALOG NUMBER=3,ALOGDEV=3390

ADADBS MODFCB AUDITNM=

The ADADBS MODFCB parameter AUDITNM= is used to assign an Audit Name to an Adabas file that is participating in auditing.

The Audit Name is an 8-character alphanumeric identifier used to track auditing information for Adabas files and must be unique across all Adabas files used in auditing. The Audit Name must be enclosed in single quotes if it contains embedded blanks.

Example: Assign the Audit Name PAYROLL to file 100

ADADBS MODFCB FILE=100,AUDITNM=PAYROLL

ADADBS OPERCOM AUDCONNECT

This command is used to dynamically force a connection attempt to a specific Auditing Server or Adabas database ID, or to all related Auditing Server or Adabas database IDs.

ADADBS OPERCOM AUDCONNECT={dbid|ALL}
									

The following sections cover the topics:

Essential Parameters

Either of the two parameters, dbid or ALL, must be set. There is no default.

dbid: Database ID

The specified Auditing Server or Adabas database ID.

ALL

All known Auditing Server or Adabas database IDs.

ADADBS OPERCOM DAUDPARM and DAUDSTAT

ADADBS OPERCOM has two new functions: DAUDPARM and DAUDSTAT. These functions are available for Adabas Audit Servers and Adabas nuclei.

ADADBS OPERCOM DAUDPARM

Use DAUDPARM to display the audit parameters for an Adabas nucleus (with auditing turned on) or for an Adabas Audit Server.

When DAUDPARM is issued against an Adabas nucleus (with auditing turned on), the parameter definitions listed include global parameter definitions, file-related parameter definitions, and database parameter definitions.

For example:

ADADBS OPERCOM DAUDPARM

Auditing definitions:

Global definitions:
  Connect count .... :              10
  Connect interval   :              60
  Audit pool warning:
   Message interval   :              50
   Message limit .... :              20
   Warn increment ... :              12
   Warn percent ..... :              70

File definitions:

File   100
  Server ID ........ :   1702
  Access commands:
   ACBX ............ :  Fields
   Data Storage..... :  No
   Client info ..... :  Fields
   Format buffer ... :  Yes
   Search buffer ... :  No
   Value buffer .... :  Yes
  Delete commands:
   ACBX ............ :  No
   Data Storage..... :  Yes
   Client info ..... :  No
  Insert commands:
   ACBX ............ :  No
   Data Storage..... :  Yes
   Client info ..... :  No
   Format buffer ... :  Yes
  Update commands:
   ACBX ............ :  No
   Before Image .... :  Fields
   After Image ..... :  Yes
   Client info ..... :  No
   Format buffer ... :  Yes
  Access Fields: AA,AB,AC,AD,AE,AF,AG,AH,AI,AJ,AK,AL,
                 AM,AN,AO,AP,AQ,AR,AS,AT,AU,AV,AW
  Update Fields: AA,AB,AC,AD

File   101
  Server ID ........ :   1702
  Access commands:
   ACBX ............ :  Yes
   Data Storage..... :  Fields
   Client info ..... :  Yes
   Format buffer ... :  No
   Search buffer ... :  Yes
   Value buffer .... :  No
  Delete commands:
   ACBX ............ :  Yes
   Data Storage..... :  No
   Client info ..... :  Yes
  Insert commands:
   ACBX ............ :  Yes
   Data Storage..... :  No
   Client info ..... :  Yes
   Format buffer ... :  No
  Update commands:
   ACBX ............ :  Fields
   Before Image .... :  Yes
   After Image ..... :  No
   Client info ..... :  Fields
   Format buffer ... :  No
  Access Fields: A1,A2,A3,A4,A5,A6,A7,A8,A9,AA,AB,AC
  Update Fields: AA

When DAUDPARM is issued against an Adabas Audit Server, the following parameters are listed:

  • Global Parameters

  • Destinations

  • Subscriptions

    • Format buffers used

    • Filters used

    • Filter definitions

For example:

ADADBS OPERCOM DAUDPARM

Audit Server definitions:

Global definitions:
  Audit pool warning:
   Increment ....... :             10
   Message interval  :            120
   Message limit ... :              6
   Percent ......... :             60
  Broker stub name   : BROKER
  Connect count .... :              3
  Connect interval   :             30
  Maximum output size:        100,000
  Open at start .... : YES
  Open retry count   :             10
  Open retry interval:              0
  Queue full delay   :             60
  Subtasks ......... :              0
  Subtask wait time  :             10
  Log input ........ : NO

 Audit Destination PAYROLL                                                                                               
   Active at start up : Yes 
   Open at start .... : Yes 
   Allow logging .... : Yes 

Subscription PAYROLLS
  Active at start up : Yes 
  Destination(s) ... : PAYROLL

   DBID / File ...... :  1701 /     1 
    Data origin       : Mainframe 
    Read/Find items . : Yes 
      Request info    : Yes 
      Client info .   : Yes 
      Format buffer   : Yes 
      Search buffer   : No 
      Value buffer    : No 
    Insert items .... : Yes 
      Request info    : Yes 
      Client info .   : Yes 
      Format buffer   : Yes 
    Update items .... : Yes 
      Request info    : Yes 
      Client info .   : Yes 
      Format buffer   : Yes 
      Data storage BI : No 
    Delete items .... : Yes 
      Request info    : Yes 
      Client info .   : Yes 
    Data AI global format      : PAYROL 
    Data BI global format      : PAYROL 
    Data filter format         : PAYROL
    Data filter                : PAYFLTR
     Include filter: PAYFLTR
      Group:    1 
       Condition:    1 
        Source Field: AT 
         Begin byte     1, Length     9 
         Before Image 
         After Image 
          PE   1, MU   2 
              greater than or equal to 
        Target Field: AT 
         Begin byte     1, Length     9 
         Before Image 
         After Image 
          PE   1, MU   3 
    LUW Client info format     : CLIENTL 
    Client info global format  : CLIENT 
    ACBX global format         : REQUEST 

ADADBS OPERCOM DAUDSTAT

Use DAUDSTAT to display the audit statistics for an Adabas nucleus (with auditing turned on) or for an Adabas Audit Server.

When DAUDSTAT is issued against an Adabas nucleus (with auditing turned on), the statistics listed include:

  • The global statistics

    • The total number of audit items completely processed

    • The current number of pending audit items (items that have been committed, but not yet processed)

    • The current number of incomplete items that will be audited (but are not yet committed)

    • The number of items rejected due to error

  • The file related statistics for every file

    • The total number of audit items completely processed for a file

    • The current number of pending audit items for a file (items that have been committed, but not yet processed)

    • The current number of incomplete items for a file that will be audited (but are not yet committed)

When DAUDSTAT is issued against an Adabas Audit Server, the statistics related to destinations, global values, and subscriptions in the database are listed.

ADADBS OPERCOM FEOFAL

The ADADBS OPERCOM FEOFAL command closes the current dual or multiple audit log and switches to another audit log. This command is valid only if dual or multiple audit logging is in effect and only for Adabas Audit Servers.

Command Syntax:

ADADBS OPERCOM FEOFAL

ADADEF DEFINE AUDITSERVER Function

The AUDITSERVER parameter controls whether the database you are defining is an Adabas database or an Adabas Audit Server.

AUDITSERVER: Set the Adabas Audit Server

The AUDITSERVER parameter is used with ADADEF DEFINE to control whether a normal Adabas database is being defined, or whether an Adabas Audit Server is being defined.

Possible values are “YES” or “NO” (the default). Specify “YES” to define an Adabas Audit Server and “NO” to define a normal Adabas database.

Examples

Define an Adabas Audit Server:

ADADEF DEFINE AUDITSERVER=YES

Define a normal Adabas database:

ADADEF DEFINE AUDITSERVER=NO

ADADEF MODIFY AUDITSERVER Function

The AUDITSERVER parameter controls whether the database that is running is an Adabas database or an Adabas Audit Server.

AUDITSERVER: Set the Adabas Audit Server

The AUDITSERVER parameter is used with ADADEF MODIFY to control whether the running database is to be a normal Adabas database or an Adabas Audit Server.

Possible values are “YES” or “NO” (the default). Specify “YES” to modify a normal Adabas database to run as an Adabas Audit Server and “NO” to modify an Adabas Audit Server to run as a normal Adabas database.

Examples

Modify a normal Adabas database to run as an Adabas Audit Server:

ADADEF MODIFY AUDITSERVER=YES

Modify an existing Adabas Audit Server to run as a normal Adabas database:

ADADEF MODIFY AUDITSERVER=NO

ADAFRM ALOGFRM

The ALOGFRM function allows you to format audit logs (ALOGs) in a similar way that PLOGFRM is used to format protection logs (PLOGs).

Formatting must be performed before any new audit log data set can be used by the Audit Server.

ADAFRM ALOGFRM	SIZE=size
               [DEVICE=device-type]
               [{FROMRABN={starting-rabn | NUMBER={dataset-number|1}}]
               [NOUSERABEND]
               [VOLIOCOUNT=nnn|4]

The following sections cover the topics:

Essential Parameters

SIZE: Size of Area to be Formatted

SIZE specifies the size of the area to be formatted (or reset). Blocks (a decimal value followed by a "B") or cylinders may be specified.

Optional Parameters

DEVICE: Device Type

DEVICE is the physical device type upon which the area to be formatted is contained. If DEVICE is not specified, the device type specified by the ADARUN DEVICE parameter is used.

FROMRABN: Starting RABN

FROMRABN specifies the RABN at which formatting is to begin. This parameter may only be used for an existing data set. NUMBER cannot be specified in the same ADAFRM job as FROMRABN.

When FROMRABN is specified with the ALOGFRM function, formatting begins at the FROMRABN point and continues up to the highest complete track before the RABN computed from FROMRABN + SIZE (assuming a size specified in or converted to blocks). This means that the last track within the specified range (FROMRABN + SIZE) will be formatted only if all the track's RABNs are within that range.

On z/OS, FROMRABN should only be used to reformat existing blocks as the last record pointer in the VTOC cannot be modified by function FROMRABN.

NOUSERABEND: Termination without Abend

When a parameter error or a functional error occurs while this utility function is running, the utility ordinarily prints an error message and terminates with user abend 34 (with a dump) or user abend 35 (without a dump). If NOUSERABEND is specified, the utility will not abend after printing the error message. Instead, the message "utility TERMINATED DUE TO ERROR CONDITION" is displayed and the utility terminates with condition code 20.

Note:
When NOUSERABEND is specified, we recommend that it be specified as the first parameter of the utility function (before all other parameters). This is necessary to ensure that its parameter error processing occurs properly.

NUMBER: Data Set Number

NUMBER selects the nonsequential audit log to be formatted. The default is 1 (first data set). Values allowed are 1 through 8. ADAFRM ALOGFRM function statements cannot specify (and will not default to) a NUMBER value if other ADAFRM statements in the same job specify a FROMRABN value.

NUMBER must match the number suffix of the related ALOG data definition (DD) statement.

VOLIOCOUNT: Number of Concurrent I/Os per Volume per Data Set

VOLIOCOUNT specifies the number of concurrent I/Os per volume to process for a data set. The minimum value you can specify is "1"; maximum is "256". The default value is "4". The setting of this parameter can affect the processing speed of the ADAFRM utility.

Example

In the following example, one cylinder for nonsequential audit log data set 1, and 1 cylinder for nonsequential audit log data set 2 are to be formatted.

ADAFRM ALOGFRM SIZE=1,DEVICE=3390,NUMBER=1
ADAFRM ALOGFRM SIZE=1,DEVICE=3390,NUMBER=2

ADALOD LOAD Parameters

ADALOD LOAD has additional auditing-related parameters for both the Adabas Audit Server and Adabas databases.

ADALOD LOAD Parameters for the Adabas Audit Server

The following parameters are applicable to the loading of auditing-related system files into the Adabas Audit Server.

AUDITING: Loading the Auditing system file

The AUDITING parameter is used to request the load of an Auditing system file into the Audit Server. It may not be specified for loading a file on a normal Adabas database.

The Auditing system file stores auditing-related definitions and is maintained by Adabas Auditing Configuration. When it is loaded into the Audit Server, it can be read during Audit Server start-up.

The contents of DD/EBAND are ignored when loading an Auditing system file.

For more information about Adabas system files, read the FILE parameter of the ADALOD LOAD function in the Adabas for Mainframes documentation > Utilities > ADALOD Utility: File Loader.

SLOG: Loading the Auditing Subscription Logging (SLOG) system file

The SLOG parameter is used to request the load of an Auditing SLOG system file into the Audit Server. It may not be specified for loading a file on a normal Adabas database.

The use and maintenance of the Auditing SLOG system file is controlled by Adabas Auditing Configuration.

The contents of DD/EBAND are ignored when loading an Auditing system file.

Note:
User application files should not be loaded on the Adabas Audit Server.

Examples:

Load the Auditing system file into the Audit Server:

ADALOD LOAD FILE=8,AUDITING

Load an Auditing SLOG system file into the Audit Server:

ADALOD LOAD FILE=30,SLOG

ADALOD LOAD Parameters for the Adabas Database

The ADALOD LOAD parameter AUDITNM= is used to assign an Audit Name to an Adabas file when it is loaded by ADALOD.

The Audit Name is an 8-character alphanumeric identifier used to track auditing information for Adabas files and must be unique across all Adabas files used in auditing. The Audit Name must be enclosed in single quotes if it contains embedded blanks.

Example: Assign the Audit Name VEHICLES to file 100

ADALOD LOAD FILE=100,AUDITNM=VEHICLES

ADAORD STORE

ADAORD STORE has the following additional auditing-related parameters for use with the Adabas Audit Server.

AUDITING: Store the Auditing system file

The AUDITING parameter is used to request the store of the Auditing system file from the DDFILEA/FILEA tape as the new Auditing system file for the Audit Server. The new Auditing system file must have the same file number as the old Auditing system file. AUDITING may not be specified for storing a file on a normal Adabas database.

When the AUDITING parameter is not specified, the Auditing system file on the DDFILEA/FILEA is not stored in the Audit Server, even if it is specified by a FILE or ALLFILES parameter.

SLOG: Store the Auditing Subscription Logging (SLOG) system file

The SLOG parameter is used to request the store of the Auditing SLOG system file from the DDFILEA/FILEA tape as the new Auditing SLOG system file for the Audit Server. The new Auditing SLOG system file must have the same file number as the old Auditing SLOG system file. SLOG may not be specified for storing a file on a normal Adabas database.

When the SLOG parameter is not specified, the Auditing SLOG system file on the DDFILEA/FILEA is not stored in the Audit Server, even if it is specified by a FILE or ALLFILES parameter.

Note:
User application files should not be loaded on the Adabas Audit Server.

Examples:

Store the Auditing system file from DDFILEA/FILA into the Audit Server:

ADAORD STORE FILE=8,AUDITING

Store the Auditing SLOG system file from DDFILEA/FILEA into the Audit Server:

ADAORD STORE ALLFILES,SLOG

ADAREP REPORT

The ADAREP utility displays information about the status of auditing for the database, files, and the Adabas Audit Server.

The following sections cover the topics:

General Information Section

When ADAREP is run against an Audit Server, the general information section includes the following additional information:

When the Audit Server is defined:

Auditing             = Yes

When an Auditing system file is loaded:

Auditing File         = <file number>

When an Auditing SLOG system file is loaded:

Audit SLOG File        = <file number>

File Information Section

The file information section includes the following when an Audit Name is defined for a file in an Adabas database:

Audit Name          <auditname>              
AUDIT-ID          <timestamp when audit Name first created>

Note:

The Audit Name is the value assigned by:

  • The ADALOD utility with ADALOD LOAD AUDITNM=

  • The ADADBS utility with ADADBS MODFCB AUDITNM=

  • The ADACMP utility with ADACMP COMPRESS AUDITNM=

Example Report

Audit Name          MYAUDTID                                                       
AUDIT-ID          2021-01-05 22:59:09.387214

Checkpoint Information Section

The following new auditing-related checkpoints are provided if the CPLIST or CPEXLIST parameters are specified:

Type Name Originator Description
85 SYNS ADADBS ADADBS AUDITING function
86 SYNS ADADBS ADADBS AUDITSERVER function

ADARES ALCOPY

The ALCOPY function allows you to convert dual/multiple audit logs to sequential logs. The data set that has the earlier time stamp is copied to a sequential data set. Once the ALCOPY function is completed successfully, the copied data set is marked as empty. This function may, therefore, be used only once for any given data set.

Once the ADARES ALCOPY job has run for an ALOG data set, the ADARES utility checks the PPT to determine whether any additional ALOG data sets need to be copied. If so, it invokes the Audit Server user exit 12 to accommodate the number of data sets that need copying. For example, if NALOG=8, once the initial ALCOPY job completes, the ADARES utility will issue a call to the Audit Server to invoke user exit 12 for each uncopied ALOG data set it detects. When it invokes user exit 12, it uses the flag "F" to identify this type of call. This flag is processed as a new EX12TYPE value in user exit 12.

For more information about user exit 12, see Adabas for Mainframes > User, Hyperdescriptor, Collation Descriptor, and SMF Exits > User Exit 12 (Multiple Data Set Log Processing).

ADARES ALCOPY	[DUALALD=device-type]
                [NOUSERABEND]
                [OPENOUT]
                [TEST]
                [TWOCOPIES]

The following sections cover the topics:

Optional Parameters

ADARES ALCOPY can be specified with no parameters.

DUALALD: Dual Audit Log Device Type

DUALALD specifies the device type used for the dual audit log data sets. This parameter is required if the device type used for the audit log data set is different from the one specified with the ADARUN DEVICE parameter.

NOUSERABEND: Termination without Abend

When a parameter error or a functional error occurs while this utility function is running, the utility ordinarily prints an error message and terminates with user abend 34 (with a dump) or user abend 35 (without a dump). If NOUSERABEND is specified, the utility will not abend after printing the error message. Instead, the message "utility TERMINATED DUE TO ERROR CONDITION" is displayed and the utility terminates with condition code 20.

Note:
When NOUSERABEND is specified, we recommend that you specify it as the first parameter of the utility function (before all other parameters). This way you ensure that NOUSERABEND's parameter error processing occurs properly.

OPENOUT: Open DDSIAUS1/2 or SIAUS1/2 Data Sets

The OPENOUT parameter specifies that ADARES opens the DD/SIAUS1/2 output data sets, even if no data is actually to be copied. Without OPENOUT, the sequential output data sets are not opened if ADARES detects an end-of-file condition while attempting to read the first input record. This may cause problems in some operating system environments. With OPENOUT, the output data sets are opened before the first input record is read.

TEST: Test Syntax

The TEST parameter tests the operation syntax without actually performing the operation. TEST checks only the syntax of the specified parameters; not the validity of values and variables.

TWOCOPIES: Create Two Copies of Output

TWOCOPIES causes two copies of the output to be created.

Example

In the following example, the oldest dual audit log is to be copied to a sequential data set.

ADARES ALCOPY