Version 4.6.2
 —  Administration  —

Performing Adabas Review Online Functions from Natural Programs

You can perform Adabas Review SYSREVDB (online) functions from your own Natural programs. Adabas Review provides an API, 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 obtain access to the Adabas Review address space from your Natural program and then to restore your original working environment when you are done.

To support RVCALL the following members are provided in your SYSREVDB library.

The rest of this document describes the functions of the RVCALL API, providing specific information about input parameters and output parameters for each:


START Function: Start a Report for a Single DBID, Specifying Many Parameters (RVCALL01)

You can use the START function to start a report from your Natural program for a single database.

Example program RVCALL01 is provided to show the use of this function.

Note:
A simpler method of starting a report using RVCALL is to use the EZSTART function, described later in this section.

Input Parameters

Input parameters should be specified as defined in the L-RVCALL member. Some input parameters are required for this function. The following table describes the possible input parameters and whether or not they are required. The fields that are listed as "Maybe" (indicating that they may be required) are required only if the defined online report specifies comparable values.

Parameter Required? Description
RVC-FUNCTION Yes This parameter should be set to "START".
RVC-REVIEW-TARGET Yes The target database or hub ID to which calls should be routed.
RVC-NUCID No The nucleus ID to which calls should be routed. When specified, calls are routed to the RVC-REVIEW-TARGET database and this nucleus (DBID/NUCID) combination.
RVC-REPORT-NAME Yes The exact report name. This name must exactly match the name of a defined online report.
RVC-DBID Yes The database ID (DBID) that should be monitored. This is the database from which data should be collected for the report.
RVC-ACCOUNT-FIELDS Maybe List the fields in the order in which they should be displayed. This list must exactly match the defined online report definition.
RVC-SUMMARY-FIELDS Maybe List the report fields whose total values should be calculated and displayed. Field names in the list should be separated with commas. Every field in the list will have its total calculated and displayed in the report. This list must exactly match the defined online report definition.
RVC-MAXIMUM-FIELDS Maybe List the report fields whose maximum values should be displayed in the report. Field names in the list should be separated with commas. Every field in the list will have its maximum value displayed in the report. This list must exactly match the defined online report definition.
RVC-MINIMUM-FIELDS Maybe List the report fields whose minimum values should be displayed in the report. Field names in the list should be separated with commas. Every field in the list will have its minimum value displayed in the report. This list must exactly match the defined online report definition.
RVC-AVERAGE-FIELDS Maybe List the report fields whose average values should be calculated and displayed in the report. Field names in the list should be separated with commas. Every field in the list will have its average value calculated and displayed in the report. This list must exactly match the defined online report definition.
RVC-PERCENT-FIELDS Maybe List the report fields whose percentage values should be calculated and displayed in the report. Field names in the list should be separated with commas. Every field in the list will have its percentage of the total field value calculated and displayed in the report. This list must exactly match the defined online report definition.
RVC-RATE-FIELDS Maybe List the report fields whose rate per second values should be calculated and displayed in the report. Field names in the list should be separated with commas. Every field in the list will have its rate per second calculated and displayed in the report. This list must exactly match the defined online report definition.
RVC-RANGE-FIELDS Maybe This parameter is reserved for Software AG use.
RVC-SELECT-FIELDS Maybe Processing rules for the report. This list or processing rules must exactly match the defined online report definition.
RVC-DISPLAY-PROGRAM Maybe The name of the Natural display program to use for the report. The default is "RVCALL00". This must exactly match the defined online report definition.
RVC-MAXIMUM-STORAGE Maybe The maximum amount of storage available for a summary report (specified in K). The default is 8K. This parameter should only be specified when a summary report is requested. This must exactly match the defined online report definition.
RVC-REPORT-FORMAT Maybe Indicates whether the report is a summary ("S") or detailed ("D") report. Valid values are "S" or "D"; "S" is the default. This must exactly match the defined online report definition.
RVC-DISPLAY-OPTION Maybe The sort option specifying how the data is to be sorted on a summary report. Possible display types are:
  • "SORTED": sort in ascending order by control break;

  • "USAGE": sort in descending order by command count;

  • "SUMFIELD": sort in descending order by the first field marked as a summary field;

  • "SORTEDDE": sort in descending order by control break; or

  • "DATETIME": sort in ascending order by the start date and time of the control break interval.

This parameter should only be specified when a summary report is requested. This must exactly match the defined online report definition.

RVC-PRINT Maybe For a detailed report, specify whether or not the report is printed at database termination. For a summary report, specify whether or not the report is printed at database termination or when its refresh/history interval is reached. Valid values are "Y" (print the report) or "N" (do not print the report); the default value is "Y". This must exactly match the defined online report definition.
RVC-BREAK Maybe Indicates whether or not subtotals are printed at control breaks ("Y") or are suppressed ("N") on the summary report. The default is "Y". This parameter should only be specified when a summary report is requested. This must exactly match the defined online report definition.
RVC-WRAP Maybe Indicates whether or not the data collected for a summary report that has SEQUENCE as the first ORDER (control break) field can reuse data elements (i.e., wrap) once the total number of ENTRIES specified have been filled. Valid values are "Y" or "N"; the default is "N". This parameter should only be specified when a summary report is requested. This must exactly match the defined online report definition.
RVC-RESTART Maybe Indicates whether the summary report is restarted after the specified refresh/history interval or after the RVC-MAXIMUM-STORAGE limit (see the RVC-MAXIMUM-STORAGE parameter) is reached. Valid values are "Y" or "N"; the default is "Y". If "Y" is specified for the RVC-RESTART parameter, the summary report is refreshed automatically. If "N" is specified for the RVC-RESTART parameter, the summary report will be set with status "I" (inactive). Then, when the RVC-MAXIMUM-STORAGE parameter limit or the refresh/history interval are reached, the report will be closed. This parameter should only be specified when a summary report is requested. This must exactly match the defined online report definition.
RVC-LIMIT Maybe The maximum number of entries that the detailed or summary report can print. The default value allows all entries to be printed. When the limit is reached, the report will remain active, but no further data will be collected. This must exactly match the defined online report definition.
RVC-ENTRIES Maybe The maximum number of entries (that is, unique control breaks) that a summary report can maintain. This option is used to restrict the amount of data collected. When the limit is reached, the report will remain active, but no further data will be collected. This parameter should only be specified when a summary report is requested. This must exactly match the defined online report definition.
RVC-ADALIMIT Maybe The minimum command count for printing on a summary report. If ADALIMIT=100, only entries with a command count of 100 or higher are printed on the report. The default value (1) means that all entries are printed. This must exactly match the defined online report definition.
RVC-HISTORY Maybe Indicates whether the data collected by the report is to be written to an Adabas Review repository and stored as history data. Valid values are "Y" (store history data) and "N" (do not store history data). If "N" is specified, all other history parameters (RVC-HISTORY-INTERVAL, RVC-HISTORY-DBID, RVC-HISTORY-FNR, and RVC-HISTORY-SVC) are ignored. If "Y" is specified, the other history parameters are required. This must exactly match the defined online report definition.
RVC-HISTORY-INTERVAL Maybe The history interval in minutes. This is the time interval during which history data is collected by the report. This must exactly match the defined online report definition.
RVC-HISTORY-DBID Maybe The database ID (DBID) of the Adabas Review repository used to store the history data. This must exactly match the defined online report definition.
RVC-HISTORY-FNR Maybe The file number of the Adabas Review repository used to store the history data. This must exactly match the defined online report definition.
RVC-HISTORY-SVC Maybe The Adabas SVC number used to communicate with the Adabas Review repository in order to write the history data. This must exactly match the defined online report definition.

Returned Information

Check the following parameters for the results of RVCALL processing for this function.

Parameter Description
RVC-RESPONSE-CODE The return code indicating the success of RVCALL processing. A return code of zero ("0") indicates that processing completed successfully.
RVC-RESPONSE-MSG The RVCALL error message that occurred as a result of RVCALL processing. For complete information, read RVCALL* - Adabas Review RVCALL API Messages.
RVC-ADABAS-RESPCODE The Adabas response code resulting from RVCALL processing. For complete information, read Adabas Response Codes.

Top of page

DELETE Function: Remove a Report (RVCALL02)

You can use the DELETE function to remove a report from Adabas Review. All information that has been accumulated by the report will be deleted. If the report was defined as a history report, all history information will also be deleted.

Example program RVCALL02 is provided to show the use of this function.

Input Parameters

Input parameters should be specified as defined in the L-RVCALL member. Some input parameters are required for this function. The following table describes the possible input parameters and whether or not they are required:

Parameter Required? Description
RVC-FUNCTION Yes This parameter should be set to "DELETE".
RVC-REVIEW-TARGET Yes The target database or hub ID to which calls should be routed.
RVC-NUCID No The nucleus ID to which calls should be routed. When specified, calls are routed to the RVC-REVIEW-TARGET database and this nucleus (DBID/NUCID) combination.
RVC-REPORT-NAME Yes The exact report name. This name must exactly match the name of a defined online report.

Returned Information

Check the following parameters for the results of RVCALL processing for this function.

Parameter Description
RVC-RESPONSE-CODE The return code indicating the success of RVCALL processing. A return code of zero ("0") indicates that processing completed successfully.
RVC-RESPONSE-MSG The RVCALL error message that occurred as a result of RVCALL processing. For complete information, read RVCALL* - Adabas Review RVCALL API Messages.
RVC-ADABAS-RESPCODE The Adabas response code resulting from RVCALL processing. For complete information, read Adabas Response Codes.

Top of page

CLOSE Function: Close a Report (RVCALL03)

You can use the CLOSE function to remove a report from Adabas Review. All information that has been accumulated by the report will be deleted. However, if the report was defined as a history report, all history information remains written to the Adabas Review repository, if applicable. The report will then be restarted if RESTART=Y was specified on the Report Options screen when the online report was created or if the RVC-RESTART parameter was set to "Y" in an RVCALL run.

Example program RVCALL03 is provided to show the use of this function.

Input Parameters

Input parameters should be specified as defined in the L-RVCALL member. Some input parameters are required for this function. The following table describes the possible input parameters and whether or not they are required:

Parameter Required? Description
RVC-FUNCTION Yes This parameter should be set to "CLOSE".
RVC-REVIEW-TARGET Yes The target database or hub ID to which calls should be routed.
RVC-NUCID No The nucleus ID to which calls should be routed. When specified, calls are routed to the RVC-REVIEW-TARGET database and this nucleus (DBID/NUCID) combination.
RVC-REPORT-NAME Yes The exact report name. This name must exactly match the name of a defined online report.

Returned Information

Check the following parameters for the results of RVCALL processing for this function.

Parameter Description
RVC-RESPONSE-CODE The return code indicating the success of RVCALL processing. A return code of zero ("0") indicates that processing completed successfully.
RVC-RESPONSE-MSG The RVCALL error message that occurred as a result of RVCALL processing. For complete information, read RVCALL* - Adabas Review RVCALL API Messages.
RVC-ADABAS-RESPCODE The Adabas response code resulting from RVCALL processing. For complete information, read Adabas Response Codes.

Top of page

SUSPEND Function: Suspend a Report (RVCALL04)

You can use the SUSPEND function to suspend the accumulation of data for a report. The report will remain in storage and can still be viewed. In addition, the report data accumulation can be reactivated using the REACT function.

Example program RVCALL04 is provided to show the use of this function.

Input Parameters

Input parameters should be specified as defined in the L-RVCALL member. Some input parameters are required for this function. The following table describes the possible input parameters and whether or not they are required:

Parameter Required? Description
RVC-FUNCTION Yes This parameter should be set to "SUSPEND".
RVC-REVIEW-TARGET Yes The target database or hub ID to which calls should be routed.
RVC-NUCID No The nucleus ID to which calls should be routed. When specified, calls are routed to the RVC-REVIEW-TARGET database and this nucleus (DBID/NUCID) combination.
RVC-REPORT-NAME Yes The exact report name. This name must exactly match the name of a defined online report.

Returned Information

Check the following parameters for the results of RVCALL processing for this function.

Parameter Description
RVC-RESPONSE-CODE The return code indicating the success of RVCALL processing. A return code of zero ("0") indicates that processing completed successfully.
RVC-RESPONSE-MSG The RVCALL error message that occurred as a result of RVCALL processing. For complete information, read RVCALL* - Adabas Review RVCALL API Messages.
RVC-ADABAS-RESPCODE The Adabas response code resulting from RVCALL processing. For complete information, read Adabas Response Codes.

Top of page

REACT Function: Reactivate a Suspended Report (RVCALL05)

You can use the REACT function to reactivate data collection for a report for which data collection was previously suspended. The report will resume accumulating data. No data will be lost; however, data that might have been collected during the suspension period will be missing.

Example program RVCALL05 is provided to show the use of this function.

Input Parameters

Input parameters should be specified as defined in the L-RVCALL member. Some input parameters are required for this function. The following table describes the possible input parameters and whether or not they are required:

Parameter Required? Description
RVC-FUNCTION Yes This parameter should be set to "REACT".
RVC-REVIEW-TARGET Yes The target database or hub ID to which calls should be routed.
RVC-NUCID No The nucleus ID to which calls should be routed. When specified, calls are routed to the RVC-REVIEW-TARGET database and this nucleus (DBID/NUCID) combination.
RVC-REPORT-NAME Yes The exact report name. This name must exactly match the name of a defined online report.

Returned Information

Check the following parameters for the results of RVCALL processing for this function.

Parameter Description
RVC-RESPONSE-CODE The return code indicating the success of RVCALL processing. A return code of zero ("0") indicates that processing completed successfully.
RVC-RESPONSE-MSG The RVCALL error message that occurred as a result of RVCALL processing. For complete information, read RVCALL* - Adabas Review RVCALL API Messages.
RVC-ADABAS-RESPCODE The Adabas response code resulting from RVCALL processing. For complete information, read Adabas Response Codes.

Top of page

LIST Function: List Started Reports (RVCALL06)

You can use the LIST function to receive an array of the reports that have been started, up to a maximum of 250 REPORT. All reports are shown, regardless of whether they are active or suspended.

Example program RVCALL06 is provided to show the use of this function.

Input Parameters

Input parameters should be specified as defined in the L-RVCALL member. Some input parameters are required for this function. The following table describes the possible input parameters and whether or not they are required:

Parameter Required? Description
RVC-FUNCTION Yes This parameter should be set to "LIST".
RVC-REVIEW-TARGET Yes The target database or hub ID to which calls should be routed.
RVC-NUCID No The nucleus ID to which calls should be routed. When specified, calls are routed to the RVC-REVIEW-TARGET database and this nucleus (DBID/NUCID) combination.

Returned Information

The following parameters are returned. Study them for the results of RVCALL processing for this function.

Parameter Description
RVC-RESPONSE-CODE The return code indicating the success of RVCALL processing. A return code of zero ("0") indicates that processing completed successfully.
RVC-RESPONSE-MSG The RVCALL error message that occurred as a result of RVCALL processing. For complete information, read RVCALL* - Adabas Review RVCALL API Messages.
RVC-ADABAS-RESPCODE The Adabas response code resulting from RVCALL processing. For complete information, read Adabas Response Codes.
RVC-LIST-NUMBER The number of started reports.
RVC-LIST-NAME The name of the started report.
RVC-LIST-START The time the report was started in HH:MM format.
RVC-LIST-START-DATE The date the report was started in YYYY-MM-DD format.
RVC-LIST-RTYPE Indicates whether the report is a regular Adabas Review report ("D") or an Adabas Review client report ("C").
RVC-LIST-RSTATUS The report status. Possible values are active ("A"), suspended ("S"), or insufficient ("I").
RVC-LIST-RFORMAT The report format indicator ("D", for detailed; "S" for summary).
RVC-LIST-HIST The report history indicator ("Y" if history data has been requested; "N" if it has not).
RVC-LIST-RNUM The report number.
RVC-LIST-PROG The report program name.
RVC-LIST-LOG The current Adabas Review log file number.
RVC-LIST-TARGET-ALPHA This parameter will be set to "ALL" if "ALL" was specified for monitoring DBIDs. Otherwise, it will be blank and should be ignored.
RVC-LIST-TARGET-NUMERIC This parameter will be set to the database ID of the monitored database if a specific database ID was specified to be monitored. Otherwise, it will be blank and should be ignored.

Top of page

GETHUBID Function: Obtain a Hub ID (RVCALL07)

You can use the GETHUBID function to return the first Adabas Review hub ID found to your Natural program.

Example program RVCALL07 is provided to show the use of this function.

Input Parameters

Input parameters should be specified as defined in the L-RVCALL member. Some input parameters are required for this function. The following table describes the possible input parameters and whether or not they are required:

Parameter Required? Description
RVC-FUNCTION Yes This parameter should be set to "GETHUBID".
RVC-SVC Yes The SVC that should be searched for the hub ID.

Returned Information

Check the following parameters for the results of RVCALL processing for this function.

Parameter Description
RVC-REVIEW-TARGET The first Adabas Review hub ID found under the SVC specified in the GETHUBID call.
RVC-RESPONSE-CODE The return code indicating the success of RVCALL processing. A return code of zero ("0") indicates that processing completed successfully.
RVC-RESPONSE-MSG The RVCALL error message that occurred as a result of RVCALL processing. For complete information, read RVCALL* - Adabas Review RVCALL API Messages.
RVC-ADABAS-RESPCODE The Adabas response code resulting from RVCALL processing. For complete information, read Adabas Response Codes.

Top of page

GETDBID Function: Obtain LFILE DBID (RVCALL08)

You can use the GETDBID function to return the database ID associated with the Natural logical file (LFILE) 241 to your Natural program.

Example program RVCALL08 is provided to show the use of this function.

Input Parameters

Input parameters should be specified as defined in the L-RVCALL member. Some input parameters are required for this function. The following table describes the possible input parameters and whether or not they are required:

Parameter Required? Description
RVC-FUNCTION Yes This parameter should be set to "GETDBID".

Returned Information

Check the following parameters for the results of RVCALL processing for this function.

Parameter Description
RVC-DBID The database ID (DBID) associated with Natural LFILE 241.
RVC-RESPONSE-CODE The return code indicating the success of RVCALL processing. A return code of zero ("0") indicates that processing completed successfully.
RVC-RESPONSE-MSG The RVCALL error message that occurred as a result of RVCALL processing. For complete information, read RVCALL* - Adabas Review RVCALL API Messages.
RVC-ADABAS-RESPCODE The Adabas response code resulting from RVCALL processing. For complete information, read Adabas Response Codes.

Top of page

EZSTART Function: Start Reports for One or All DBIDs (RVCALL09)

You can use the EZSTART function to start a report from your Natural program for one or more databases. Very few parameters are required because the reports started with EZSTART automatically use the definitions already specified for the report in SYSREVDB.

Example program RVCALL09 is provided to show the use of this function.

Input Parameters

Input parameters should be specified as defined in the L-RVCALL member. Some input parameters are required for this function. The following table describes the possible input parameters and whether or not they are required:

Parameter Required? Description
RVC-FUNCTION Yes This parameter should be set to "EZSTART".
RVC-REVIEW-TARGET Yes The target database or hub ID to which calls should be routed.
RVC-NUCID No The nucleus ID to which calls should be routed. When specified, calls are routed to the RVC-REVIEW-TARGET database and this nucleus (DBID/NUCID) combination.
RVC-REPORT-NAME Yes The exact report name. This name must exactly match the name of a defined online report.
RVC-DBID
or
RVC-ALL
Yes Specify either:
  • the database ID (DBID) that should be monitored (this is the database from which data should be collected for the report) in the RVC-DBID parameter; or

  • "ALL" for the RVC-ALL parameter to indicate that all DBIDs should be monitored.

Caution:
Be careful that you do not specify a hub ID in RVC-DBID. This is not programmatically prevented and will cause errors.

Returned Information

Check the following parameters for the results of RVCALL processing for this function.

Parameter Description
RVC-RESPONSE-CODE The return code indicating the success of RVCALL processing. A return code of zero ("0") indicates that processing completed successfully.
RVC-RESPONSE-MSG The RVCALL error message that occurred as a result of RVCALL processing. For complete information, read RVCALL* - Adabas Review RVCALL API Messages.
RVC-ADABAS-RESPCODE The Adabas response code resulting from RVCALL processing. For complete information, read Adabas Response Codes.

Top of page

VIEWON Function: Access the Review Address Space (RVCALL10)

You can use the VIEWON function to obtain access to the Adabas Review address space from your Natural program. When subsequent FINDs are issued by your Natural program, the information returned comes from within the executing Adabas Review address space. VIEWON must make a change to your environment to allow this. Use the VIEWOFF function to restore your original working environment.

Warning:
You must execute the VIEWON and VIEWOFF functions in the same Natural program (information is retained in the local parameter area for the LFILE). They must be executed in pairs; if they are not it can create an unstable situation for your environment.

Example program RVCALL10 is provided to show the use of this function.

Input Parameters

Input parameters should be specified as defined in the L-RVCALL member. Some input parameters are required for this function. The following table describes the possible input parameters and whether or not they are required:

Parameter Required? Description
RVC-FUNCTION Yes This parameter should be set to "VIEWON".
RVC-REVIEW-TARGET Yes The target database or hub ID to which calls should be routed.
RVC-NUCID No The nucleus ID to which calls should be routed. When specified, calls are routed to the RVC-REVIEW-TARGET database and this nucleus (DBID/NUCID) combination.
RVC-DBID Yes The database ID (DBID) that should be monitored, This is the database from which data should be collected for the report.

Returned Information

Check the following parameters for the results of RVCALL processing for this function.

Parameter Description
RVC-RESPONSE-CODE The return code indicating the success of RVCALL processing. A return code of zero ("0") indicates that processing completed successfully.
RVC-RESPONSE-MSG The RVCALL error message that occurred as a result of RVCALL processing. For complete information, read RVCALL* - Adabas Review RVCALL API Messages.
RVC-ADABAS-RESPCODE The Adabas response code resulting from RVCALL processing. For complete information, read Adabas Response Codes.

Top of page

VIEWOFF Function: Restore the Adabas Review Environment (RVCALL10)

You can use the VIEWOFF function to restore your original working environment after having executed a VIEWON. Use this function once your Natural program has finished gathering information when the VIEWON function had been specified.

Warning:
You must execute the VIEWON and VIEWOFF functions in the same Natural program (information is retained in the local parameter area for the LFILE). They must be executed in pairs; if they are not it can create an unstable situation for your environment.

Example program RVCALL10 is provided to show the use of this function.

Input Parameters

Input parameters should be specified as defined in the L-RVCALL member. Some input parameters are required for this function. The following table describes the possible input parameters and whether or not they are required:

Parameter Required? Description
RVC-FUNCTION Yes This parameter should be set to "VIEWOFF".
RVC-REVIEW-TARGET Yes The target database or hub ID to which calls should be routed.
RVC-NUCID No The nucleus ID to which calls should be routed. When specified, calls are routed to the RVC-REVIEW-TARGET database and this nucleus (DBID/NUCID) combination.

Returned Information

Check the following parameters for the results of RVCALL processing for this function.

Parameter Description
RVC-RESPONSE-CODE The return code indicating the success of RVCALL processing. A return code of zero ("0") indicates that processing completed successfully.
RVC-RESPONSE-MSG The RVCALL error message that occurred as a result of RVCALL processing. For complete information, read RVCALL* - Adabas Review RVCALL API Messages.
RVC-ADABAS-RESPCODE The Adabas response code resulting from RVCALL processing. For complete information, read Adabas Response Codes.

Top of page