Client reporting allows you to collect client data you can use to determine where command processing time is spent. Client reporting is currently provided for Adabas Review hubs only in z/OS environments using the TSO, CICS, and IMS monitors; it is not currently supported in Com-plete. Client reporting is intended as a diagnostic tool and can be activated and deactivated as needed.
Data for client reports is normally collected in the client address space from the client as well as the Adabas data server. Note that data for client reports can be collected when Adabas Review is running either local or hub mode, but can only be transferred to and reported from a hub.
Caution:
The process required to collect client data increases the
overhead of your system. We therefore recommend that you activate client
reporting only for as long as it takes to diagnose a problem. We do not
recommend that client reporting be activated all the time.
This document covers the following topics:
Client reporting is currently supported for Adabas Review hubs in z/OS environments and only if ADARUN PROGRAM=USER. For complete information on how to install client reporting, read Installation Phase 2, in the Adabas Review z/OS Installation Guide. Installation of client reporting support involves performing the following tasks at some point in the Adabas Review installation:
You will need to set two new LGBLSET macro keywords, RVCLNT (used to indicate whether client reporting is allowed for the hub) and REVHID (which specifies the hub ID). New globals tables must be assembled with these keywords.
The new globals tables must be linked with the appropriate Adabas Review exit modules (which include REVEXIT2).
The Adabas Review exit modules are RDBLXMVS (batch/TSO), RDBLXCIC (CICS), and RDBLXCOM (Com-plete). These modules contain the batch/TSO, CICS, and Com-plete components of Adabas Review that will be used with the Adabas Version 8 CICS link routine.
While client reporting is active, the REVEXIT2 link routine will collect data and send it to the preferred Adabas Review hub after each Adabas call.
Once client reporting is activated, client data collection occurs for each Adabas call from within the ADALNK routine where it has been activated.
Refer to the Adabas Review Release Notes for information about compatibility with Adabas versions.
If Adabas Review is installed with its CICS link routine, SYSREVDB (which is used to activate and deactivate client reporting) must be running in the same CICS and using the same task-related user exit (TRUE) that will process client data.
Status messages are provided during installation indicating whether or not client reporting is supported by the system. After installation, if client reporting is supported by the CICS system, client reporting state messages are produced indicating when client reporting is activated or deactivated.
Once client reporting is allowed, it is not automatically activated. Instead, you must manually activate it in one of the following ways.
Use the Client Management screen in SYSREVDB to activate it online.
Set the ADARUN RVCLIENT parameter to "ACTIVE" to activate it when you want to run client reports in batch environments (ADARUN PROGRAM=USER).
Call the batch module REVCLRP, specifying its RVCLFUNC parameter as "ON" to activate it within your own application program.
Call the Natural Batch program SETCM with MODE=ON to activate it.
Activate and deactivate client reporting data collection as needed by your installation. To verify if client reporting is turned on correctly please review any LNKRVX* or RVCL* messages appearing on the console log. For more information, read Managing Client Reporting. Because of the system overhead that can occur while client reporting statistics are collected, we do not recommend that you leave it activated for very long.
The following diagram depicts the client reporting data collection process when client reporting has been activated.
When the Adabas call is processed after client reporting has been activated, the Adabas SVC captures the timing data necessary to produce the data stored in the client reporting fields. Then REVEXIT2 collects and sends that data, via Trans-port, to the preferred Adabas Review hub for the call. The client reporting data is included within a subset of a command log record.
Caution:
This process has some impact on the performance of CICS. We
therefore recommend that you run client reporting for controlled periods of
time as a diagnostic tool only.
Data collection occurs for each Adabas where each Adabas link routine has been prepared to support it.
Data for client reports is normally collected in the client address space from the client as well as the Adabas data server. Note that data for client reports can be collected when Adabas Review is running either local or hub mode, but can only be transferred to and reported from a hub.
When client reporting is activated, three data fields, specific to client reporting, are collected and included with a subset of the command log record:
The total client duration time is collected and stored in the CDURA field.. This is the total time (in seconds) in which the client waits for the command to be processed by the server and the time it takes the ADALNK portion of the client to retrieve the command results. CDURA is the sum of the CRCVDURA and CWRKDURA fields.
The client receive time is stored in the CRCVDURA field. This is the time (in seconds) it takes the Adabas link routine to retrieve a processed command from the server.
The client wait time, or the time in which the server works for the client, is stored in the CWRKDURA field. This is the time (in seconds) in which the client waits for the command to be processed by the server.
Note:
For more information on how duration fields are calculated in
Adabas Review, read Adabas Review Duration
Field Derivations.
These specific client reporting fields become available for reports only when client reporting is activated. For complete information about the specific client reporting fields, read about the Client Reporting Field (CMON) field category.
In addition, a subset of the other field data collected by Adabas Review from the Adabas server is also available for client reports. This includes the data for the Adabas Review fields ADADURA, CQDURA, DBID, JOBNAME, NUCID, ROUTTIME, SEQUENCE, and TOTDURA. If you do not want to collect this data, the appropriate ADARUN parameter of the Adabas server has to be set as described in Adabas Nucleus (PROGRAM=ADANUC) ADARUN REVIEW Parameter Setting Considerations for Data Collection Under Client Reporting.
For a complete list of fields available for client reports, read Fields Available for Client Reporting.
Use the Edit Client Report screen in SYSREVDB to create a client report definition. For more information, read Maintaining Standard Database and Client Reports.
In addition, you can use the CLASS parameter of the batch REPORT statement to specify whether the batch report to be generated is a client reporting report. Valid values are "STANDARD" (the report is a standard report) and "CLIENT" (the report is a client reporting report). The default is "STANDARD". The CLASS parameter can be specified on both detailed and summary reports. For more information about the CLASS parameter, read REPORT Statement.
Data for client reports is normally collected in the client address space from the client as well as the Adabas data server. Note that data for client reports can be collected when Adabas Review is running either local or hub mode, but can only be transferred to and reported from a hub.
Once client reporting is activated (turned on), data is collected for the three specific client reporting data fields: CDURA, CRCVDURA, and CWRKDURA. Data for these fields is collected regardless of the ADARUN REVIEW parameter setting of the databases which are called from within this client program. However, some reporting fields (see the list below) in client reports are affected by the setting of the ADARUN REVIEW parameter:
To start, run, or stop client reports, the ADARUN REVIEW parameter must not be specified in the Adabas nucleus job. You prepare the Adabas Review client (RVCLNT=YES) specify the hub ID (REVHID) in the ADALNK parameter settings that support client reports.
Important:
If an ADALNK batch link routine has been modified to
accommodate the needs of an Adabas product extension (such as Adabas Review),
it should not be used for the Adabas nucleus or Adabas utility jobs.
The Adabas nucleus must run with the ADARUN parameter CLOGLAYOUT set to "8" (CLOGLAYOUT=8).
To collect data from the Adabas server in the following Adabas Review fields (while client reporting is turned on), the ADARUN REVIEW parameter specified in the Adabas nucleus job must be set to "LOCAL" or to a hub ID. If it is set to "NO", data is not collected for the following fields:
ADADURA
CQDURA
JOBNAME
NUCID
ROUTTIME
SEQUENCE
TOTDURA
If you do not want to collect the Adabas server data in these fields for a given database, you can either:
Set the ADARUN REVIEW parameter to "LOCAL" for the given database, and do not define any reports (manually started or autostarted) for this database; or
Set the ADARUN REVIEW parameter to an invalid hub ID to avoid any standard reporting for this database.
Data will be collected for these additional fields and the overhead in the Adabas server will be minimal.
For more information about the ADARUN REVIEW parameter, read REVIEW Parameter: Adabas Review Control.