Using Natural batch jobs, you can start and review Adabas Review reports and perform various other Adabas Review reporting functions.
To run the batch job in the correct environment, you must specify the:
Target ID (the database or hub ID with which the subsequent program or programs will communicate). This is referred to as the DBID/Hub or current Adabas Review target in SYSREVDB. This must be specified explicitly when running in hub mode.
Database ID and file number where the Adabas Review repository file is located. These are referred to as the Repository DBID and Repository File in SYSREVDB. This information is required when accessing history data in the batch job.
This document covers the following topics:
Setting the Nucleus ID in Sysplex Environments using Batch Natural
Printing Technical System Information for Review in Batch Natural
The following table summarizes the Natural batch programs and statements supplied with and supported by Adabas Review.
| Program or Statement | Use to... |
|---|---|
| ACTIVATE program | Reactivate a suspended Adabas Review report in batch Natural. |
| CLOSE program | Close a started Adabas Review report in batch Natural. If it is a history report, history will be written. |
| COMPRESS program | Compress history data in a specified history report for a specified time span. |
| COPYREP program | Copy an Adabas Review report definition to a report definition with the specified new unique name. |
| DBTECH program | Print Adabas Review technical system information. |
| DELDEF program | Delete a specified Adabas Review report definition from the Adabas Review repository. |
| DELHIST program | Delete history data in a specified Adabas Review history report for a specified time span. |
| DELREP program | Purge started reports and report data for a specified Adabas Review report in batch Natural. |
| HISTORY program | Display history data in a specified history report for a specified time span using the traditional display module. |
| HISTORYX program | Display history data in a specified history report for a specified time span using the Software AG Editor. |
| NUCID program | Set the current nucleus ID. This can only be used in sysplex environments. |
| SET statement | Override the Natural default and SYSREVDB values for the target ID, database ID, and file number used in a batch run. |
| SETCM program | Turn client reporting on or off. |
| START program | Start an Adabas Review report in batch Natural. |
| SUSPEND program | Suspend an Adabas Review report in batch Natural. |
| SWITCH program | Force a log switch for the specified Adabas Review report in batch Natural. |
| TERM program | Terminate the Natural session. |
| ULDREP program | Unload specified Adabas Review report definitions to a sequential data set as defined by the Natural work file CMWKF01. |
| VIEW program | View a started Adabas Review report in batch Natural using the traditional display module. |
| VIEWX program | View a started Adabas Review report in batch Natural using the Software AG Editor. |
The default target ID is the database in which the Natural logical system file is located. If the LFILE parameter for logical file number 241 is specified, the DBID value from this parameter will be taken. The default for the repository database ID and file number are specified using the Natural LFILE parameter for logical file number 241.
A defined SYSREVDB (online Natural) user profile overrides any default settings. However, the target ID setting can be specified in SYSREVDB using the command MENU HUB=hubid prior to issuing the START command for a report. If the parameter is set to "AUTO", the first hub found on the SVC will be used.
However, both the Natural default settings and the SYSREVDB user profile settings of the target ID, database ID, and file number can be overridden using the SET statement in any of the existing batch Natural job streams.
The syntax of the SET statement is:
The SET statement overrides the Natural default and SYSREVDB values for the target ID, database ID, and file number. The values specified by SET remain in effect until changed by a new SET statement.
When you specify the SET statement in a batch Natural job stream, you must also specify one or more of the following: a TARGET parameter and value, a DBID parameter and value, or a FILE (alternatively FNR) parameter and value. Only one of each parameter type can be specified in a single SET statement (for example, you cannot specify two DBID parameters in the same SET statement). If you specify more than one of the parameters (for example, a TARGET and a DBID parameter), they can be specified in any order and should be separated with commas.
The following is an example of the SET statement in a batch Natural job stream:
//CMSYNIN DD * LOGON SYSREVDB SET TARGET=558,DBID=559,FILE=24 START REVIEW.REPORT.NAME FIN //*
You can set the nucleus ID in a sysplex environment using the NUCID Natural batch program provided with Adabas Review.
NUCID operates in much the same way as the other batch Natural Review programs. Its syntax is:
NUCID nucid
For nucid, specify the nucleus ID you want to use. Up to five numeric characters can be specified for the nucleus ID.
Review report definitions can be unloaded to a sequential data set for backup, archive or for the purpose of moving the definition to a different Review system. There are two batch Natural programs to accomplish this, ULDREP and LODREP. ULDREP unloads report definitions to a sequential data set as defined by the Natural work file CMWKF01. LODREP restores report definitions from the same sequential data set.
The job control statements to run ULDREP and LODREP are the same as other Review batch Natural jobs such as START, VIEW and DELHIST.
Two wildcard characters are provided that you can use to quickly specify more than one report definition name:
An asterisk (*) wildcard character can be used to specify
any string of characters. For example, specifying Report.Number*
as the report definition name would select all report definitions with names
starting with the letters "Report Number". This
would select reports with names "Report Number1",
"Report Number99", and "Report Number
One".
As another example, specifying File.*.Report
would select all report definitions with names that start with the word
"File" and end with the word
"Report". This would select reports with the
following names: "File Usage Report" and
"File Detail Report", and even "File
Usage Detail Report".
A question mark (?) wildcard character can be used to
specify any single character. For example, specifying
Report.Number? as the report definition name would select all
report definitions with names starting with the letters "Report
Number" and one other character. This would select reports with
names Report Number1 through Report
Number9, and even "Report NumberA",
but would not select "Report Number10" (because it
includes two extra characters at the end).
Combinations of these wildcard characters can be specified for a
report name. For example, specifying I/O.Summary.*.Report? would
allow you to select reports with names such as "I/O Summary by
RABN Report1", "I/O Summary by RABN
ReportA", and "I/O Summary by Volume
Report9".
The ULDREP program allows you to specify more than one report name (with or without the use of wildcard characters), with each name on a different line. The sequence of report names ends when a period (.), the word "END", or the word "FIN" are encountered on their own line.
ULDREP report.name
[report.name2]...
{. | END | FIN}
where report.name is the report name with periods between each word in the report name. Wildcard characters can be used in the report names.
The following is an example that unloads report definitions with names starting with "NATURAL SUM" as well as report definitions with names starting with "CMD".
ULDREP NATURAL.SUM* CMD* END
Note:
Unloaded reports will show "NEED
RG" as their display program, indicating that the display program
for the report must be regenerated once the report has been reloaded by the
LODREP program. The only exceptions are the Buffer Pool reports, which always
call the display program BUFFPOOL.
The LODREP program allows you to restore report definitions from a sequential data set defined by the Natural work file CMWKF01. You can only specify a single report definition name to the LODREP program, although that report definition name may use wildcard characters (which will select multiple report definitions with similar names, if they exist in the data set). However, you can specify more than one LODREP program in a run. Furthermore, the LODREP program allows you to indicate whether or not the restored report definition can overwrite and replace an already existing definition with the same name.
LODREP report.name [Y|N]
where report.name is the report name with periods between each word in the report name. Wildcard characters can be used in the report name. Specify "Y" or "N" to indicate whether existing report definitions with the same name can be replaced by the restored report definitions; the default is "N" (replacement does not occur).
The following examples restore and replace all report definitions with names starting with "CMD" and "FILE".
LODREP CMD* Y LODREP FILE* Y
You can create an exact copy of a report definition and give it a new report name using the COPYREP Natural batch program provided with Adabas Review. A new report display program is also generated.
The purpose of this program is to allow you to create a uniquely named report from a template report, start the report copy, run your user programs, view the output from the report copy, and then delete the report copy. During all processing, the template report remains unchanged. An example of this is shown in Example 2: COPYREP with DELREP at the end of this section.
COPYREP operates in much the same way as the other batch Natural Review programs. Its syntax is:
COPYREP NAME=report.name,NEWNAME=new.report.name
Two additional parameters STACKPARM and GO=YES can also be used.
Each parameter of the COPYREP Natural batch program is described here in alphabetical order.
- GO=YES
Specify GO=YES to indicate that the values of the STACKPARM parameters should be consolidated and the copy should be executed. GO=YES should only be specified if the STACKPARM parameter is also specified. If STACKPARM is not used, GO=YES should not be specified either. For more information, read about the STACKPARM parameter.
- NAME
Use the NAME parameter to specify the name of the report you want to copy. Report names must have periods between the words of the names to allow Natural to pass the parameters to COPYREP as a continuous string. In addition, there should be no spaces between the report name and the equal sign. Errors will result if the report name does not have periods between the words of the name or if there is a space between the report name and the equal sign (NAME=rptname).
- NEWNAME
Use the NEWNAME parameter to specify the unique name of the new report created by the copy processing. Report names must have periods between the words of the names to allow Natural to pass the parameters to COPYREP as a continuous string. In addition, there should be no spaces between the report name and the equal sign. Errors will result if the report name does not have periods between the words of the name or if there is a space between the report name and the equal sign (NEWNAME=rptname).
- STACKPARM
Because report names can be up to 32 bytes in length, it is possible that the parameters and names of the report to be copied and the new report created by the copy will not fit on one line of the batch job. This is a Natural limitation. To alleviate this problem, use the STACKPARM parameter. Invoke COPYREP multiple times, passing a STACKPARM parameter with each invocation, and then invoke it one last time using only the GO=YES parameter. All of the STACKPARM parameter specifications will be remembered and then used when the GO=YES parameter is issued.
For example:
COPYREP STACKPARM=NAME=long.report.name.to.be.copied COPYREP STACKPARM=NEWNAME=long.report.name.of.new.report.created.by.the.copy COPYREP GO=YES
You can start a report using the START Natural batch program provided with Adabas Review. Optionally, you can specify a DBID using START to start the report only for the specified DBID.
Note:
The specified value (either DBID or ALL) will overwrite the
default definition. In case the default definition of the DBID field is blank
and there is no parameter specified with the START command then a DBID=ALL
report will be started.
START operates in much the same way as the other batch Natural Review programs. Its syntax is:
START report.name,[dbid | DBID=dbid]
or
START report.name [dbid | DBID=dbid]
For report.name, specify
the name of the report you want to start. Report names must contain periods
between the words of the names to allow Natural to pass the parameters to START
as a continuous string. Errors will result if the report name does not contain
periods between the words of the name.
For dbid, specify the
database ID or the value ALL for which you want the report started. The report
will then collect data from the specified DBID or ALL. The comma between the
report name and the DBID (as shown in the first of the above syntax options) is
not required.
Some examples of valid START commands:
START MY.REPORT START MY.REPORT,123 START MY.REPORT 123 START MY.REPORT,DBID=123 START MY.REPORT,ALL START MY.REPORT DBID=ALL
You can suspend a report using the SUSPEND Natural batch program provided with Adabas Review. Optionally, you can specify a DBID using SUSPEND to suspend the report only for the specified DBID.
SUSPEND operates in much the same way as the other batch Natural Review programs. Its syntax is:
SUSPEND report.name,[dbid]
For report.name, specify the name of the report you want to suspend. Report names must have periods between the words of the names to allow Natural to pass the parameters to SUSPEND as a continuous string. Errors will result if the report name does not have periods between the words of the name.
For dbid, specify the database ID for which you want the report suspended. The comma between the report name and the DBID is required.
You can reactivate a suspended report in batch Natural using the ACTIVATE Natural batch program provided with Adabas Review. Optionally, you can specify a DBID using ACTIVATE to reactivate the report only for the specified DBID.
ACTIVATE operates in much the same way as the other batch Natural Review programs. Its syntax is:
ACTIVATE report.name,[dbid]
For report.name, specify the name of the report you want to reactivate. Report names must have periods between the words of the names to allow Natural to pass the parameters to ACTIVATE as a continuous string. Errors will result if the report name does not have periods between the words of the name.
For dbid, specify the database ID for which you want the report reactivated. The comma between the report name and the DBID is required.
You can view a started report using the VIEW or VIEWX Natural batch program provided with Adabas Review. Optionally, you can specify a DBID using START to view the report only for the specified DBID.
VIEW and VIEWX operate in much the same way as the other batch Natural Review programs. Their syntax is:
VIEW report.name,[dbid]
or
VIEWX report.name,[dbid]
The VIEWX command behaves exactly the same as the VIEW command. However, data will be displayed using RX-*, SX-* or CX-* modules instead of RD-*, SR-* or CR-* modules. These modules use the Software AG Editor to show the data.
For report.name, specify the name of the started report you want to view. Report names must have periods between the words of the names to allow Natural to pass the parameters to START as a continuous string. Errors will result if the report name does not have periods between the words of the name.
For dbid, specify the database ID of the report you want to view. The comma between the report name and the DBID is required.
You can close a started report in batch Natural using the CLOSE Natural batch program provided with Adabas Review. Optionally, you can specify a DBID using CLOSE to close the report only for the specified DBID.
CLOSE operates in much the same way as the other batch Natural Review programs. Its syntax is:
CLOSE report.name,[dbid]
For report.name, specify the name of the report you want to close. Report names must have periods between the words of the names to allow Natural to pass the parameters to CLOSE as a continuous string. Errors will result if the report name does not have periods between the words of the name.
For dbid, specify the database ID for which you want the report closed. The comma between the report name and the DBID is required.
You can turn client reporting on or off in batch Natural using the SETCM Natural batch program provided with Adabas Review.
SETCM operates in much the same way as the other batch Natural Review programs. Its syntax is:
SETCM HUB=nnnnn,MODE= ON|OFF
For nnnnn, specify the hub ID you want to use. Up to five numeric characters can be specified for the hub ID.
Specify ON to turn client reporting on; specify OFF to turn it off. The comma between the hub ID and ON or OFF is required.
You can switch the log file for an Adabas Review report using the SWITCH Natural batch program provided with Adabas Review. Optionally, you can specify a DBID using SWITCH to switch the log file for the report only for the specified DBID.
SWITCH operates in much the same way as the other batch Natural Review programs. Its syntax is:
SWITCH report.name,[dbid]
For report.name, specify the name of the report for which you want the log file switched. Report names must have periods between the words of the names to allow Natural to pass the parameters to START as a continuous string. Errors will result if the report name does not have periods between the words of the name.
For dbid, specify the database ID for which you want the log file switched. The comma between the report name and the DBID is required.
You can print Adabas Review technical system information using the DBTECH Natural batch program provided with Adabas Review.
DBTECH operates in much the same way as the other batch Natural Review programs. Its syntax is:
DBTECH
There are no parameters.
You may also use batch Natural programs to display, purge, or compress history data from the Adabas Review repository. Adabas Review provides sample jobs to perform these tasks.
Notes:
To use these jobs:
Add the report name and date or date and time range. All dates are entered in yyyy-mm-dd format; all times are entered in hh:mm:ss format.
Enter any embedded blanks in the report name as periods.
To display history data:
The following Natural statements are contained in the display history data job stream:
LOGON SYSREVDB <--logon to Review Natural library. HISTORY A.HISTORY.REPORT start-date start-time end-date end-time <--report name, dates and times. FIN /*
To display history data with the Software AG Editor, enter:
LOGON SYSREVDB <--logon to Review Natural library. HISTORYX A.HISTORY.REPORT start-date start-time end-date end-time <--report name, dates and times. FIN /*
If no time is specified the start-time will default to 00:00:01 and the end-time will default to 23:59:59.
To delete history data:
The following Natural statements are contained in the delete history data job stream:
LOGON SYSREVDB <--logon to Review Natural library. DELHIST A.HISTORY.REPORT start-date end-date <--report name and dates. FIN /*
To compress history reports:
The following Natural statements are contained in the compress history job stream:
LOGON SYSREVDB <--logon to Review Natural library. COMPRESS A.HISTORY.REPORT start-date end-date et-factor <--report info. FIN /*
You can delete a report definition from the Adabas Review repository using the DELDEF Natural batch program provided with Adabas Review.
DELDEF operates in much the same way as the other batch Natural Review programs. Its syntax is:
DELDEF report.name
Report names must have periods between the words of the names to allow Natural to pass the parameters to DELDEF as a continuous string.
You can purge started reports and report data using the DELREP Natural batch program provided with Adabas Review.
DELREP operates in much the same way as the other batch Natural Review programs. Its syntax is:
DELREP report.name
Report names must have periods between the words of the names to allow Natural to pass the parameters to DELREP as a continuous string.
You can terminate the Natural session using the TERM Natural batch program provided with Adabas Review.
TERM operates in much the same way as the other batch Natural Review programs. Its syntax is:
TERM
There are no parameters.
This section provides examples using these batch Natural programs in Adabas Review:
Note:
The reports in this section are examples only, used to
demonstrate the use of the Natural programs described in this section. We do
not supply these reports in sample jobs in Adabas Review.
A batch Natural job (PAYROLL1) is run each night. When the job is completed, Adabas summary statistics are requested to determine the number of Adabas calls issued by the job, the files accessed, the type of Adabas commands issued, and a summary of ASSO, DATA, and WORK I/Os for each command type within each file.
To implement the request for Adabas summary statistics:
Ensure that the Review load library is in the STEPLIB concatenation.
Define the following report definition and related processing rules to Adabas Review:
10:49:13 A D A B A S - R E V I E W 2016-05-21
Edit Report Target=15690
Detail/Summary: S
Report Name: TRACE PAYROLL REPORT____________ DBID to Monitor: __559
+-----------------------------------------------------------------------------+
| Field Order Sum Min Max Avg Pct Rate Cost Round |
|-----------------------------------------------------------------------------|
| FILE____ _10 _ _ _ _ _ _ _ ________ ______ |
| CMD_____ _20 _ _ _ _ _ _ _ ________ ______ |
| COMMANDS ___ X _ _ _ _ _ _ ________ ______ |
| ASSOIO__ ___ X _ _ _ _ _ _ ________ ______ |
| DATAIO__ ___ X _ _ _ _ _ _ ________ ______ |
| WORKIO__ ___ X _ _ _ _ _ _ ________ ______ |
| ________ ___ _ _ _ _ _ _ _ ________ ______ |
| ________ ___ _ _ _ _ _ _ _ ________ ______ |
| ________ ___ _ _ _ _ _ _ _ ________ ______ |
| ________ ___ _ _ _ _ _ _ _ ________ ______ |
+---------------------------------- Page 1 -----------------------------------+
This report contains processing rules
Command: ______________________________________________________________________
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
Help Optns Exit SOnly Save Start - + Rules Flds Menu |
20:47:59 A D A B A S - R E V I E W 2016-05-21
Report Processing Rules Target=15690
TRACE PAYROLL REPORT
+-----------------------------------------------------------------------------+
! Field Op Value And/Or !
!-----------------------------------------------------------------------------!
! JOBNAME_ EQ PAYROLL1________________________________________________ ___ !
! ________ __ ________________________________________________________ ___ !
! ________ __ ________________________________________________________ ___ !
! ________ __ ________________________________________________________ ___ !
! ________ __ ________________________________________________________ ___ !
! ________ __ ________________________________________________________ ___ !
! ________ __ ________________________________________________________ ___ !
! ________ __ ________________________________________________________ ___ !
! ________ __ ________________________________________________________ ___ !
! ________ __ ________________________________________________________ ___ !
+---------------------------------- Page 1 -----------------------------------
Command: ______________________________________________________________________
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
Help Optns Exit SOnly Save Start - + Flds Menu
|
Save the report definition.
Change the PAYROLL1 job stream if necessary to produce the required results shown below:
LOGON SYSREVDB <---logon to SET DBID=559,FILE=24,TARGET=15690 Review Natural library START TRACE.PAYROLL.REPORT targetid <---start Review report LOGON PAYROLL * * PAYROLL1 NATURAL STREAM * LOGON SYSREVDB <---logon to Review Natural SET DBID=559,FILE=24,TARGET=15690 library VIEW TRACE.PAYROLL.REPORT targetid <---to display report results DELREP TRACE.PAYROLL.REPORT targetid <---to delete report results FIN
In the following example of a Review Natural batch program, the report named "Rate of Commands and I/Os by Date Report" is copied to a new report named "Command and I/O Rate by Date Report". Then user program XXXX is run on database 559, file 24, and target 41. The report copy is then started on database 559, file 24, and target 41 and its output is displayed, deleted, and the report copy is purged. Note that the original report, "Rate of Commands and I/Os by Date Report", remains unchanged by all processing.
LOGON SYSREVDB SET DBID=559,FILE=24,TARGET=41 COPYREP STACKPARM=NAME=Rate.of.Commands.and.I/Os.by.Date.Report COPYREP STACKPARM=NEWNAME=Command.and.I/O.Rate.by.Date.Report COPYREP GO=YES LOGON USERLIB USERPROG XXXX LOGON SYSREVDB SET DBID=559,FILE=24,TARGET=41 VIEW Command.and.I/O.Rate.by.Date.Report DELREP Command.and.I/O.Rate.by.Date.Report DELDEF Command.and.I/O.Rate.by.Date.Report FIN