This document describes the Adabas Review 4.6 enhancements.
Note:
You must have Adabas 8.2 SP4 installed to use the new features in this
release.
Adabas Review4.6 SP2 now allows you to perform Adabas Review SYSREVDB (online) functions from your own Natural programs. Adabas Review now provides an API called RVCALL that allows you to start reports, list started reports, remove reports, close reports, suspend reports, and reactivate suspended reports. You can also obtain the first Adabas Review hub ID found for a specified SVC and the database ID associated with LFILE 241. Finally, you can use the RVCALL API to set the LFILE definition to zero so you can obtain information about the Adabas Review address space.
To support RVCALL the following members are provided in your SYSREVDB library.
Ten example programs named "RVCALL01" through "RVCALL10" are provided as examples of how to perform specific RVCALL functions.
| Example Program | RVCALL Function Demonstrated |
|---|---|
| RVCALL01 | START function. Use this function to start a specific report, specifying many of its parameters. |
| RVCALL02 | DELETE function. Use this function to remove a report from Adabas Review. |
| RVCALL03 | CLOSE function. Use this function to close a report. |
| RVCALL04 | SUSPEND function. Use this function to suspend a report. |
| RVCALL05 | REACT function. Use this function to reactivate a suspended report. |
| RVCALL06 | LIST function. Use this function to list started reports. |
| RVCALL07 | GETHUBID function. Use this function to obtain the hub ID of a specific SVC. |
| RVCALL08 | GETDBID function. Use this function to obtain the DBID associated with LFILE 241. |
| RVCALL09 | EZSTART function. Use this function to start a report for one or all DBIDs. Very few parameters are required. |
| RVCALL10 | VIEWON and VIEWOFF functions. Use these functions to obtain access to the Adabas Review address space from your Natural program (VIEWON must make a change to your environment to allow this access) and to restore your original working environment (VIEWOFF). Using the VIEWON function allows you to obtain information about the Adabas Review address space within your Natural program. |
A parameter area member, L-RVCALL. This member contains the parameter definitions for information that will be passed as input to RVCALL functions and as output from RVCALL functions.
The RVCALL subprogram, N-RVCALL.
For complete information about the RVCALL API, read Performing Adabas Review Online Functions from Natural Programs.
Adabas Review 4.6 SP2 introduces an enhanced user profiling (security) system. The following enhancements have been made:
You can now set up group profiles, based on the groups set up by your Natural Security administrator. When a user logs on, Adabas Review looks for a group profile first and then for an individual user profile. It uses the first profile found (group profiles take precedence over individual user profiles). If neither a group nor individual user profile is found, the default profile is used.
Note:
Natural Security is only required if you want to use group IDs, but
not otherwise.
You can now set up user profiles with access only to specific DBIDs.
The number of access rules available for you to secure has been increased.
When you enter MENU the first time you start Adabas Review, it now detects that profiling system has not yet been installed and installs it automatically. Prior to this version of Adabas Review, one profile would be installed, the profile named DEFAULT. Starting with this version, two profiles are installed: the DEFAULT profile and a profile with the same name as the user ID of the person installing Adabas Review (the user that entered MENU). Both profiles will have administrator privileges.
If you have user profiles from an older version of Adabas Review, it detects that these user profiles are older and do not conform to the current Adabas Review user profile standards and conventions. It then attempts to migrate your user profiles to the current standard. You are given the option to proceed with the migration or exit Adabas Review. For more information, read Migrating User Profiles.
For complete information about user profiling, read Maintaining User Profiles.
The behavior of the AA command is different in BS2000 environments, compared to how it operates in z/OS and z/VSE environments. In BS2000 environments, this command will now skip the Available SVCs screen and go straight to the Available Targets screen because there is only one router available to you in BS2000.
Adabas Review 4.6 SP2 introduces the ability to manage client reporting from your own applications by making calls to a module, REVCLRP, that Software AG provides. From within your own program, you can call REVCLRP with requests to start or stop Adabas Review client reporting or a request to supply its current status.
In addition, a new ADARUN parameter, RVCLIENT, has been introduced in this release. Use the RVCLIENT parameter to activate client reporting when you want to run client reports in batch environments.
For more information about the REVCLRP module, read Managing Client Reporting in Batch. For more information about the ADARUN RVCLIENT parameter, read RVCLIENT Parameter: Adabas Review Client Reporting Activation.
Adabas Review 4.6 SP2 introduces support for client monitoring in Com-plete environments under z/OS. This support was not available in 4.6 SP1. For more information, read Client Reporting Support under Com-plete.
The fixed record length (LRECL or REC-SIZE) for RVUPRTnn data sets (logical printer files) has been generally increased to 160. If you are using fixed files, new files with the increased length should be created.
Adabas Review 4.6 SP2 introduces a new field, ESTCPU that can be used to estimate the approximate CPU time used by each Adabas command. The values shown in this field are only relative approximations of the CPU time used; they are not based on any actual CPU times and are calculated, instead, based on an algorithm. The algorithm used varies for each Adabas command type and is based on the number of instructions, I/Os, descriptors, and fields used. The algorithm used varies for each Adabas command type and is based on the number of instructions, number of I/Os, and number of descriptors used.
This new field can be used as a SUM, MIN, MAX and/or AVG field.
Adabas Review 4.6 SP1 introduces the following changes in its supplied Natural user exits.
The P-UEXIT2 user exit is no longer called when PF3 is clicked on the Main Menu of SYSREVDB (the online portion of Adabas Review) nor is it called when the EXIT command is entered on the Main Menu. Instead, it is now called when PF12 is clicked on the Main Menu or when a termination command (such as FIN, QUIT, or LOGON) is entered on the Main Menu.
A new Natural user exit, P-UEXIT3 is introduced. This new user exit is called when PF3 is clicked on the Main Menu of SYSREVDB or when the EXIT command is entered on the Main Menu.
For complete information about the Adabas Review Natural user exits, read P-UEXIT1, P-UEXIT2 and P-UEXIT3: Review Natural User Exits.
Adabas Review 4.6 SP1 introduces support for Adabas Review client reporting. Client reporting allows you to collect client data you can use to determine where command processing time is spent. It is currently provided for Adabas Review hub 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.
Caution:
The process required to collect client data increases the resource
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.
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. If you will be using client reporting, Natural zap NA77060 must be applied to support use of SYSREVDB activation of client reporting. In addition, you must have Adabas 8.2 SP4 installed to use this new feature.
For complete information about client reporting, read About Adabas Review Client Reporting
This section describes all of the areas of change made to Adabas Review and Adabas in support of client reporting:
A new field category, CMON, has been added in this release to support client reporting. CMON fields are report fields that are derived from client reporting log records. They include the following fields:
| Field System Name | Description |
|---|---|
| CDURA | The total client duration time. 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.
Measurement for this field starts immediately after the command is passed to the server (when it is posted from the Adabas link routine to the Adabas address space and SVC-4 router processing is performed). Measurement stops when the client picks up the command result information from the server (performing SVC-16 router processing within the Adabas link routine). |
| CRCVDURA | The client receive time. This is the time (in
seconds) it takes the Adabas link routine to retrieve a processed command from
the server.
Measurement for this field starts immediately after the server posts the Adabas link routine to retrieve the command result information (performing SVC-12 router processing) . Measurement stops when the Adabas link routine retrieves the command information from the server address space (performing SVC-16 router processing). |
| CWRKDURA | The client wait time, or the time in which the
server works for the client. This is the time (in seconds) in which the client
waits for the command to be processed by the server.
Measurement for this field starts immediately after the command is passed to the server for processing (when it is posted from the Adabas link routine to the Adabas address space and SVC-4 processing is performed). Measurement stops when the Adabas link routine retrieves the command information from the server address space (performing SVC-12 router processing). |
For more information about these fields, read Client Reporting Fields (CMON).
The batch REPORT statement has a new parameter, CLASS, you can use to specify whether the 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.
Some reorganization of the SYSREVDB menus was necessary to support client reporting. Specifically:
A new menu now provides access to Adabas Review specialty reports. You can access this menu from the SYSREVDB using a new Edit Specialty Reports (ES) function.
The Edit Buffer Pool Report (EB), Edit Pulse Report (EL), and Edit Cluster Services Report (EX) functions originally on the SYSREVDB main menu have been moved to the new menu.
A new Review Client Management (CM) function is now provided on the menu. You can use this function to turn the client reporting engine on and off. While you can run client reports anytime, the client reporting engine must be on (active) if you want to data collected for those client reports.
A new Edit Client Report (EC) function is now provided on the menu. You can use this function to maintain client report definitions.
To see these altered menus and for more information, read Maintaining Report Definitions.
The following new screens have been added to SYSREVDB in support of client reporting:
A new Client Management screen is now available. You can use this screen to turn the client reporting engine on (activate it) and off (deactivate it) and to review its status online. The client reporting engine is must be on if you want to run client reporting reports.
To see these new screens and for more information, read Managing Client Reporting Online.
A new Edit Client Report screen is now available. You can use this screen to maintain client report definitions
For more information, read Maintaining Standard Database and Client Reporting Reports.
A new Report Field Selection screen replaces the original Database Field Selection screen. The Report Field Selection screen can be accessed when you are editing any Adabas Review database or client reporting report. It can be used to select the field categories from which you select fields for the report.
The new Report Field Selection screen includes logic that limits the categories you can select to those appropriate for the type of report (database or client reporting) that you are editing. Depending on the type of report, some categories of may or not be available. For example, the client reporting field category is only available if you are editing a client reporting report.
In addition, even if a field category is available for both database and client reporting reports, some fields are not applicable to both report types, so the fields available for selection within the category differ. For example, only a subset of the fields included in the Adabas Control Block field category are available for client reporting reports.
To see these changed screens and for more information, read Maintaining Report Definitions
The Report Definitions (LR) and Started Reports (LS) screens in SYSREVDB have been altered to support client reporting. Each of these screens now include a column that identifies the type of report so you can easily identify the client reports in the list. Normal database reports are identified by a "D" in the column; client reports are identified by a "C" in the column. The Report Definitions screen shows this information in the Type column; the Started Reports screen shows this information in the Typ column.
To see these changed screens and for more information, read Maintaining Report Definitions
The following new commands have been added to SYSREVDB in support of client reporting:
| Command | Use to... |
|---|---|
| CM | manage the client reporting engine (turn it on or off). This command displays the new Client Management screen. |
| EC | access and edit a client report. This command displays the new Edit Client Report screen. |
| ES | access the Specialty Report Types menu, which provides access to the Buffer Pool, Pulse, Client, and Cluster Services reports. This menu also allows you to review client monitor management settings. |
For complete information about Adabas Review commands, refer to the Command Reference.
The name of REVEXITB has been changed to REVEXIT1 in this release in z/OS and z/VSE environments. It is still called REVEXITB in BS2000 environments.
The Adabas Review exits include REVEXIT1 (formerly REVEXITB in z/OS and z/VSE environments, but still REVEXITB in BS2000 environments) and REVEXIT2. These exits should be linked with ADALNK during installation, with the appropriate Adabas link globals table parameters (LGBLSET). The link globals table parameters specified via LGBLSET identify which exit entry points (REVEXIT1 or REVEXIT2) are called. If the LGBLSET parameter REVIEW=YES is set, then the exit is called by ADALNK before the Adabas call as entry point REVEXIT1; if the LGBLSET parameters RVCLNT and REVHID are also specified, then the exit is also called after the Adabas call as entry point REVEXIT2.
The modules used to perform the linkage between REVEXIT and ADALNK are provided with your Adabas Review installation with names in the format RDBLXsys, where sys is a three-character code representing the link environment (for example, MVS for z/OS environments, VSE for z/VSE, COM for Com-plete environments, IMS for IMS environments, and BS2 for BS2000 environments). For more information about performing this linkage, read the appropriate Adabas Review installation documentation.
Note:
A return code 4 from the link-edit of the globals table is acceptable
because it indicates that the Review exit (REVEXITB or REVEXIT1) has not been
resolved by this step. The next link-edit step in the sample jobs should
resolve this and finish with return code zero.
An additional keyword was added to the Adabas link globals table (LGBLSET) to support the use of the name REVEXITB in releases prior to Adabas Review 4.6. For more information, read Adabas Link Routine Support.
Two new keywords have been added to the Adabas link globals table (LGBLSET) in support of client monitoring: RVCLNT and REVREL. For complete information, read Adabas Link Routine Enhancements.
The Database System Environment screen that appears when you enter the TECH command has been updated to include a line indicating whether or not client reporting is turned on or not or if it is not installed.
For more information, read Accessing Technical System Information in Getting Started.
This release introduces some new values that can be specified in some of the fields of an Adabas Review user profile:
Values "AUTO" or "LFILE" can be specified for the default Adabas Review target DBID or hub ID.
Note:
Support for the new "AUTO" value
executes module ADATMZ in the Natural environment to obtain hub location
information. ADATMZ dynamically loads the CCSTCK and ADALNKR modules. If CCSTCK
or ADALNKR cannot be loaded, subsequent calls to ADATMZ might lead to problems.
Be sure that modules ADATMZ, ADALNKR, CCSTCK, ASC2EBC, and EBC2ASC, which are
available in the Adabas or WAL load libraries, are also available for the TP
monitor.
The value "LFILE" can be specified for the Adabas Review repository DBID and file number.
In all cases, specifying "LFILE" causes the value to be taken from the LFILE value of the Natural session.
If "AUTO" is specified, the value is determined from the SVC (or IDTNAME) of the current Natural session. If a single hub is running under the current SVC (or IDTNAME), that hub ID is used. If more than one hub ID is active, the first hub ID found under the SVC is used. If no hub is running, the value is determined as if "LFILE" were specified.
For complete information, read User Profile Access Rules.
A new AH command has been added that allows you to display the hubs available for the selected SVC (or IDTNAME) and to select one from the list.
For complete information about the AH command, read Listing and Selecting Available Adabas Review Hubs.
The HUB command now has a new valid value: "AUTO". Traditionally, only a hub ID could be specified on the HUB command. If "AUTO" is specified, the value of the hub ID is determined from the SVC (or IDTNAME) of the current Natural session. If only one hub is running under the current SVC (or IDTNAME), that hub ID is used; if multiple hubs are running on this SVC (or IDTNAME), a pop-up window appears allowing you to select the hub to use.
For complete information about the HUB command , read HUB Command.
This version displays the SVC of the Natural session on the Database System Environment screen. This provides a quick method for you to determine the SVC number.
Note:
SVC information does not appear on this screen in BS2000
environments; BS2000 does not use SVCs.
In addition, the version of ADATMZ code used by Adabas Review to obtain hub location information is also displayed on the Database System Environment screen.
For more information, read Accessing Technical System Information in Getting Started.
The output of the DCLIENT operator command has been changed in this version of Adabas Review. The new output no longer includes the "Wbuf" column, which was redundant as the same information is provided in the "Buf" column. In addition, the columns have been slightly renamed and the number of DBID=ALL reports as well as the number of database reports is now available.
For complete information about the new format of the DCLIENT command output, read DCLIENT Operator Command.
When running reports in hub mode, you can now specify the database ID value for the reports as "ALL". This will trigger a DBID=ALL report.
In hub mode, a DBID=ALL report collects data from all databases running on the same SVC as the hub (the databases must have been started with the ADARUN REVIEW parameter set to a hub ID). For such reports, the reporting link is automatically established with Adabas Review.You can specify DBID=ALL for user-defined reports and for most of the predefined Adabas Review reports except for the Buffer Pool reports, the Pulse reports, and the Cluster Services reports.
In local mode, a DBID=ALL report collects data only from the local database.
Note:
You must have Adabas 8.2 SP4 installed to use this new
feature.
For more information, read Specifying the Report DBID in Maintaining Report Definitions.
In this release, Adabas Review key performance indicator (KPI) statistics are now provided to webMethods Optimize for Infrastructure. Using the Optimize component of webMethods Optimize for Infrastructure, you can monitor the status of these statistics as well as the overall status of your system. This support is available in version 8.2 (and later versions) of webMethods Optimize for Infrastructure.
The key performance indicator statistics that are passed from Adabas Review to Optimize provide information about the Adabas Review system itself and not about the monitoring data collected by Adabas Review. The KPIs that are passed include statistics such as the number of records sent to Adabas Review, the CPU time used by Adabas Review, the memory usage of Adabas Review, and number of I/Os performed by Adabas Review.
The following table summarizes the changes made to Adabas Review fields in this release. For complete information about fields, read Field Reference.
| Field Name | Change |
|---|---|
| CDURA | This is a new field that shows the total client duration time. 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. For complete information, read About Adabas Review Client Reporting. |
| CRCVDURA | This is a new field that shows the client receive time. This is the time (in seconds) it takes the Adabas link routine to retrieve a processed command from the server. For complete information, read About Adabas Review Client Reporting. |
| CWRKDURA | This is a new field that shows the client wait time, or the time in which the server works for the client. This is the time (in seconds) in which the client waits for the command to be processed by the server. For complete information, read About Adabas Review Client Reporting. |
| ESTCPU | This new field can be used to estimate the approximate CPU time used by each Adabas command. The values shown in this field are only relative approximations of the CPU time used; they are not based on any actual CPU times and are calculated, instead, based on an algorithm. The algorithm used varies for each Adabas command type and is based on the number of instructions, I/Os, descriptors, and fields used. This new field can be used as a SUM, MIN, MAX and/or AVG field. |
| ROUTDURA | This is a new alternate field name for field ROUTTIME. |
| THDURA | This is a new alternate field name for field THTIME. |
The following table summarizes the changes made to Adabas Review commands in this release.
| Command | Change |
|---|---|
| AA | The behavior of the AA command has changed in BS2000 environments. In BS2000 environments, this command will now skip the Available SVCs screen and go straight to the Available Targets screen because there is only one router available to you in BS2000. |
| AH | This is a new command that allows you to list the available Adabas Review hubs for a selected SVC. For complete information about the AH command, read Listing and Selecting Available Adabas Review Hubs. |
| HUB | A new valid value, "AUTO", has been added to the HUB command. For complete information , read HUB Command. |
| TECH | The SVC of the Natural session is now displayed
on the Database System Environment screen
produced by running this command. For more information, read
Accessing
Technical System Information in
Getting
Started.
Note: |
The following table summarizes the changes made to operator commands in this release.
| Command | Change |
|---|---|
| DCLIENT | The output for this command has changed. For complete information about the new format of the command output, read DCLIENT Operator Command. |
The following table summarizes the ADARUN parameter changes made in support of this version of Adabas Review.
| Parameter | New or Changed | Enhancement Description |
|---|---|---|
| RVCLIENT | New | This new parameter can be used to activate client reporting when you want to run client reports in batch environments. |
Several new keywords have been added to the Adabas link globals table (LGBLSET) for this release.
| Parameter | Description | Syntax |
|---|---|---|
| REVHID | Specifies the preferred Adabas Review hub ID.
This value can be checked during Adabas CICS TP monitoring installation or
during the monitor activate process.
If REVHID is set to zero (0), the preferred Adabas Review hub ID is dynamic. When the hub ID is dynamic, it cannot be checked during Adabas CICS TP monitoring installation and the call to turn on client reporting must supply the correct Adabas Review hub ID to use. If REVHID is specified, REVIEW=YES must also be specified. If REVHID is specified and REVIEW=NO is also specified, the assembly of the globals table will abort with condition code 16 and the following message is given: REVHID requires REVIEW=YES |
REVHID=hubid |
| RVCLNT | Indicates whether the Adabas Review client
reporting exit should be active. The default is NO.
If RVCLNT=YES is specified, REVIEW=YES must also be specified. If RVCLNT=YES is specified and REVIEW=NO is also specified, the assembly of the globals table will abort with condition code 16 and the following message is given: RVCLNT=YES requires REVIEW=YES |
RVCLNT={YES|NO} |
| REVREL | Specifies the level of Adabas Review support to
be generated in the link globals table module. This is necessary because Review
4.6 and later releases have changed the Review pre-call exit name from
"REVEXITB" to "REVEXIT1".
Valid values are "45" or
"46" (without the quotes). If other values are given
the assembly of the globals table will fail with condition code 16 and MNOTE
messages from the assembler.
When REVREL=45 is specified, it indicates that support for Adabas Review release 4.5 and earlier should be used. The Adabas Review REVEXITB exit name is used and an associated external reference statement is generated when the globals table is assembled. When REVREL=45 is specified, the RVCLNT keyword must be set to NO. If RVCLNT=YES and REVREL=45 are both specified, the assembly of the globals table will fail with condition code 16 and MNOTE messages from the assembler. When REVREL=46 is specified it indicates that support for Adabas Review release 4.6 and later should be used. The Adabas Review REVEXIT1 exit name is used and an associated external reference statement is generated when the globals table is assembled. In either case, use of the REVREL keyword alone does not provide support for Adabas Review. To provide support for Adabas Review, the REVIEW keyword must also be set to YES. The default is currently "45", but will be changed to "46" in a future release. |
REVREL={45 | 46} |
