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.
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.
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)
EZSTART Function: Start Reports for One or All DBIDs (RVCALL09)
VIEWOFF Function: Restore the Adabas Review Environment (RVCALL10)
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 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:
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. |
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. |
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 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. |
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. |
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 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. |
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. |
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 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. |
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. |
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 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. |
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. |
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 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. |
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. |
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 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. |
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. |
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 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". |
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. |
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 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:
Caution: |
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. |
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 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. |
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. |
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 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. |
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. |