HP 3000 Manuals HP 3000 Manuals
Using Job Files
There are three types of job files used with HP ALLBASE/BRW to start a
background job (in batch mode) to execute the report:
* The standard job file (BRWJ000.PUB.SYS)
* Your own amended version of the standard job file
(BRWJOB.yourgroup.youracct or BRWJOB.PUB.SYS)
* A report job file (any name of your choice)
When you request a report using HP ALLBASE/BRW or BRWSTART and you type
the name of the report's execution file in the Report field on the
Request Report screen, HP ALLBASE/BRW uses the standard job file or your
amended standard job file.
All the parameters used in the report are taken from the execution file
and displayed on the Request Report screen, so you can assign values to
them. HP ALLBASE/BRW also displays the prompts and default values (if
any) for user, group, and account passwords, job input priority,
schedule, and so on. When you press Start Report on the Request Report
screen, these values are assigned to the parameters in the standard job
file and used to execute the report. The values for any user-defined
parameters used in the report are assigned to the report execution file.
NOTE The following values do not appear on the Request Report screen,
but HP ALLBASE/BRW prompts you for these values when you choose
Start Report.
* $USER
* $GROUP
* $ACCT
* $USERPASS
* $GROUPPASS
* $ACCTPASS
The defaults for $USER, $GROUP, and $ACCT come from your MPE logon.
There are no defaults for passwords.
When you request a report using HP ALLBASE/BRW or BRWSTART and you type
the name of a report job file in the Report field on the Request Report
screen, HP ALLBASE/BRW uses that report job file to execute the report.
(See the section "Report Job Files" later in this chapter.)
The original standard job file for running reports is held in the file
BRWJ000.PUB.SYS: a listing of this file is shown on the next page.
Note that the standard job file calls BRWEXEC.PUB.SYS (line 23 of the job
file). The BRWEXEC program actually executes the report.
_________________________________________________________________________________
| |
| 1 DEFINE JOB TEMPLATE |
| 2 COMMENT |
| 3 COMMENT This is the Standard Report Job for HP ALLBASE/BRW |
| 4 COMMENT reports. |
| 5 COMMENT |
| 6 $USER |
| 7 $USERPASS |
| 8 $GROUP |
| 9 $GROUPPASS |
| 10 $ACCT |
| 11 $ACCTPASS |
| 12 !JOB ^$REPORT,^$USER/^$USERPASS.^$ACCT/^$ACCTPASS,^$GROUP/^$GROUPPASS&|
| 13 !;INPRI=$INPRI |
| 14 !TELL ^$USER.^$ACCT; Report ^$TELLREPORT started |
| 15 !SETJCW CIERROR = 0 |
| 16 !CONTINUE |
| 17 ^$PRINTFILE |
| 18 !IF CIERROR <> 0 THEN |
| 19 ! TELL ^$USER.^$ACCT; >>>Invalid Printfile for Report ^$TELLREPORT<<< |
| 20 ! EOJ |
| 21 ! ENDIF |
| 22 !CONTINUE |
| 23 !RUN BRWEXEC.PUB.SYS |
| 24 ^$REPORT |
| 25 ^$PARMS |
| 26 !EOD |
| 27 !IF JCW >= FATAL THEN |
| 28 ! TELL ^$USER.^$ACCT; >>>Report ^$TELLREPORT failed <<< |
| 29 ! EOJ |
| 30 ! ENDIF |
| 31 !IF JCW = WARN THEN |
| 32 ! TELL ^$USER.^$ACCT; >>>No Data found for Report ^$TELLREPORT <<<|
| 33 ! EOJ |
| 34 ! ENDIF |
| 35 !TELL ^$USER.^$ACCT; Report ^$TELLREPORT finished |
| 36 !EOJ |
_________________________________________________________________________________
Amending the Standard Job File
You can substitute an amended job file for the standard job file. That
is, you can write a job file to your own specifications (or edit a copy
of the standard job file) and substitute it for the standard job file.
You give it the name BRWJOB. Then, whenever you type an execution file
name on the Report field in the Request Report screen, HP ALLBASE/BRW
will use your amended job file in place of the standard job file.
Which Standard Job File?.
It is possible for you to create and maintain several amended versions of
the standard job file on your system. You can have a different standard
job file for each group on your HP 3000. When requesting a report, HP
ALLBASE/BRW looks for the standard job file in this order:
* BRWJOB.logon-group.logon-account;
* BRWJOB.PUB.logon-account;
* BRWJOB.PUB.SYS;
* BRWJxxx.PUB.SYS (where xxx is the Native Language Support number
returned by the Native Language Support intrinsics);
* BRWJ000.PUB.SYS.
To substitute an amended standard job file
1. Make a copy of BRWJ000.PUB.SYS and put it in the group and
directory where it will be used by your HP ALLBASE/BRW report.
Call the copy
BRWJOB.logon-group.logon-account
2. Edit the copy of the file, substituting the parameters that are
correct for your report, and save the file.
After you have created BRWJOB for your report, when you give the name of
an execution file in the Report field of the Request Report screen, HP
ALLBASE/BRW uses that amended version.
Using ReportJob Files
In addition to the standard job file (or an amended standard job file),
you can create your own job files called report job files. You use the
job files to start and schedule multiple reports (multi-pass reports) and
application batch programs.
To avoid starting each report and batch program of a multi-pass report
separately, you can set up a report job file with parameters. You can
schedule and start the multi-pass report like a single report. (See
Chapter 12 for more information about multi-pass reporting.)
Using a report job file also means that you have to enter the parameter
values only once for all reports in that job, including the application
batch programs.
A report job file has these two parts:
* A header, containing parameter definitions and optional
default values for parameters, job schedule and print file
characteristics.
* A body, which is an MPE job, containing parameters anywhere that
actual parameter values are to be inserted.
To create a report job file
1. Use an editor program to create a report job file as you would an
MPE job file.
2. Define user-defined parameters in the report job header between
the BEGINPARMS clause and the ENDPARMS clause.
3. Define standard parameters, such as $PRINTFILE, in the report job
header outside the BEGINPARMS clause and the ENDPARMS clause.
4. Create the body of the job file, which is an MPE job. Use the
parameters in the body anywhere that actual parameter values are
to be inserted.
To run a report with a report job file
1. When you are ready to run the report, type the name of the report
job file in the Report field on the Request Report screen.
Parameters in ReportJob Files
There are two types of parameter in report job files:
* User-defined parameters. These are parameters that you have
defined in the report job file header, in the BEGINPARMS/ENDPARMS
clause. Once defined, these parameters can be used anywhere in
the report job file body. Note that if you use a report job file,
HP ALLBASE/BRW will only display those parameters defined in the
BEGINPARMS/ENDPARMS clause in the Parameters field on the Request
Report screen. That is, if you want to assign a value to a
parameter in a report at run-time, you must define the parameter
in the BEGINPARMS/ ENDPARMS clause.
* HP ALLBASE/BRW standard parameters. These are parameters supplied
with HP ALLBASE/BRW. For example, the user, group, and
account from which the job will be streamed, the printfile
characteristics, report name, and so on. You define these in the
report job file header, but outside the BEGINPARMS/ENDPARMS
clause. Only if you define these parameters will you be able to
assign a value for them on the Request Report screen.
Parameters (both user-defined and standard parameters) can be used
anywhere in the report job file body by specifying a control (^)
character followed by the parameter name, as shown here:
^sales-area
Example: Using parameters in the report job file
In the following example of a report job file, first one report
(salesan1.rspec) executes and creates an output file. When the second
report (salesan2.rspec) executes, it reads this output file and prints
the report. Note the user-defined parameters in the BEGINPARMS/ENDPARMS
clause; the HP ALLBASE/BRW standard parameter $PRINTFILE; and that the
execution files to be used in the job are explicitly defined within the
report job file, on lines 14 and 24.
If this report job file is requested from a Request Report screen, the
three user-defined parameters sales-area, sales-%, and product-line will
be displayed in the Request Report screen Parameter field, with the
default value for sales-%. Default values for the Request Report screen
fields Print File Name, Print Device, Output Priority, and No of Copies
are taken from the definition of the standard parameter $PRINTFILE on
line 8.
_______________________________________________________________________
| |
| |
| 1 DEFINE JOB TEMPLATE |
| 2 BEGINPARMS |
| 3 sales-area (P, SU16) |
| 4 sales-% (P, I) >=10 |
| 4 product-line (P, SU2) |
| 5 comment sales-% is percent share of product sales per area |
| 6 ENDPARMS |
| 7 $PRINTFILE salesan; DEV=LP,12,1 |
| 8 comment end of report job file header |
| 9 !JOB salesan, mgr.rdemo,pub |
| 10 !TELL mgr.rdemo; *** Sales Analysis Report started *** |
| 11 !CONTINUE |
| 12 !RUN BRWEXEC.PUB.SYS |
| 13 salesan1.rspec |
| 14 sales-area ^sales-area |
| 15 !EOD |
| 16 !IF JCW >= FATAL THEN |
| 17 ! TELL mgr.rsdemo; >>> Sales Analysis (Pass 1) failed <<<|
| 18 ! EOJ |
| 19 !ENDIF |
| 20 ^$printfile |
| 21 !CONTINUE |
| 22 !RUN BRWEXEC.PUB.SYS |
| 23 salesan2.rspec |
| 24 percent-sales ^sales-% |
| 25 product-line ^product-line |
| 26 !EOD |
| 27 !IF JCW >= FATAL THEN |
| 28 ! TELL mgr.rsdemo; >>> Sales Analysis (Pass 2) failed <<< |
| 29 ! EOJ |
| 30 !ENDIF |
| 31 !TELL mgr.rsdemo; *** Sales Analysis Report finished *** |
| 32 !EOJ |
_______________________________________________________________________
Report JobFile Header
The report job file header is defined with declaration commands. Except
in the first line in the file, you can enter each command with upper- and
lower- case, leading and separating blanks.
A report job file header always begins with:
DEFINE JOB TEMPLATE
This line is always left-justified in the first line of the file.
The header always ends with the command:
!JOB
The !JOB command is always the first line of the report job file body.
In the report job file header you define parameters which are used for
the job.
Characteristics of parameters
Characteristics of parameters in a report job header are as follows:
* Once defined, the parameters can be used anywhere within a job.
* You can define default values for parameters, for the job
schedule, and for the print file.
* If you want to assign a value to a parameter used in a report, you
must define that parameter in the report job file header. Only
parameters defined in the report job file header are displayed on
the Request Report screen.
User-Defined Parameters
You specify user-defined parameters in the BEGINPARMS/ENDPARMS clause of
the report job header. BEGINPARMS and ENDPARMS are required at the
beginning and end of the parameter definition, respectively.
You define user-defined parameters between the two statements, one
parameter per line, using the syntax shown below.
BEGINPARMS
parmname(ptype,rtype[,mode])[default value]
ENDPARMS
The following table further describes the syntax for user-defined
parameters.
Sytax for User-Defined Parameters
------------------------------------------------------------------------------------------
| |
| Statement Description |
| Element |
| |
------------------------------------------------------------------------------------------
| |
| parmname The parameter name (&parmname) must follow these rules: |
| |
| |
| * It can have up to 19 characters. |
| |
| * It must begin with a letter, $, @ or #. |
| |
| * It cannot contain ^ characters, blanks or parentheses. |
| |
| * It must not be the name of a standard parameter. |
| |
| ptype One of the following parameter types: |
| |
| |
| P = comparison predicate |
| |
| S = single value |
| |
| L = list of values |
| |
| rtype One of these result types for the parameter: |
| |
| |
| Sx = a string in which x must be the string |
| length |
| |
| SUx = a string in which all lower-case letters |
| in parameter value will be shifted up. |
| |
| N = fixed point numeric |
| |
| I = integer |
| |
| R = floating point Real |
| |
| D = date |
| |
| T = time |
| |
| mode This is optional and can be either F for R: |
| |
| |
| F = freeze value |
| |
| R = value required |
| |
| default value This is optional and has these characteristics: |
| |
| |
| * It can be up to 55 characters |
| |
| * It can be defined in an extra line using the continuation |
| character ampersand (&). |
| |
------------------------------------------------------------------------------------------
Examples
Examples of parameters are:
sales-area (P, SU16)
sales-% (P, I) >=10
product-line (P,SU2)
Standard Parameters
HP ALLBASE/BRW standard parameters are parameters supplied with HP
ALLBASE/BRW that can be used in any report job file. They refer to
values used to stream a job, and are associated with fields on the
Request Report screen or to values assigned in response to a prompt at
the Request Report screen.
Standard parameters are defined in the report file header, but outside
the BEGINPARMS/ENDPARMS clause. That is, the standard parameters come
after the ENDPARMS clause and before the !JOB command. Once defined, a
standard parameter can be used in the report job file body.
The following table shows the HP ALLBASE/BRW standard parameters.
Parameter: Prompt: Prompt or Field
---------------------------------------------------------------------------------------
$USER user name Prompts for value
$ACCT account name Prompts for value
$GROUP group name Prompts for value
$USERPASS user password Prompts for value
$ACCTPASS account password Prompts for value
$GROUPPASS group password Prompts for value
$REPORT report name and password Takes value from field on the
Request Report screen.
$TELLREPORT report name and password. Takes value from field on the
The password is not printed Request Report screen.
by MPE TELL command.
$PRINTFILE printfile characteristics Takes value from field on the
Request Report screen.
$INPRI job input priority Takes value from field on the
Request Report screen.
NOTE If you omit any standard parameters, a user requesting the report
cannot assign a value to them at run-time. For example, if you do
not include the standard parameter $USERPASS in the report job file
header, the 'User Password' prompt will not appear on the Request
Report screen when you choose Start Report.
NOTE The $PRINTFILE parameter is made up of values from various fields
on the Request Report screen, for example, Output Priority, No of
Copies, Print Device etc.. When using HP ALLBASE/BRW Intrinsics,
the parameter $PRINTFILE is itself split into many smaller
parameters. See Chapter 20, HP ALLBASE/BRW Intrinsics.
Example: Using combinations of parameters
You can use a combination of some or all standard parameters in a report
job file header. For example, to allow a report job file to log-on with
a variable user name and password but with a fixed account, specify:
DEFINE JOB TEMPLATE
BEGINPARMS
. . .
ENDPARMS
$user
$userpass
!JOB ^$user/^$userpass.MYACCT,PUB
!TELL ^user.MYACCT; *** report job file starts***
. . .
In the above example, only the prompts for User and User Password will be
displayed on the Request Report screen.
The standard parameters are used in the JOB command, but they could also
be used anywhere else in the report job body.
Default Job Schedule
A default job schedule can be defined for a report job file in this
format:
SCHEDULED schedule
Where schedule can be like one of these examples:
DATE = 08/31/86
DAY = MON
DAY = 15
(that is, on the 15th day of the next month)
DAY = -2
(that is, 1 day before month-end)
IN = 2, 12
(that is, after 2 days, 12 hours)
AT = 13:30
(that is, at 1:30 pm)
DATE = 02/08/87; AT = 14:45
(that is, on 8th February 1987, at 2:45 pm)
DAY = 15 ; AT = 10:15
(that is, on the 15th day of the next month, at
10:15 am)
See the description of the STREAM command in the MPE Commands Reference
Manual for more about job schedules.
Print FileCharacteristics
Print file characteristics can be changed when you start the report job
file if the $PRINTFILE parameter is specified.
You can optionally define defaults for print device, output priority,
number of copies, CCTL-codes, and environment file.
When you use the $PRINTFILE parameter in the report job file body, HP
ALLBASE/BRW inserts a FILE command with the actual print file
characteristics. Place the $PRINTFILE parameter in the first column of
the line in the body of the report job file where you want the FILE
command to be.
NOTE The $PRINTFILE parameter must be defined in the job header, but
outside of the BEGINPARMS/ENDPARMS clause before you can use the
parameter in the file body.
[REV BEG]
The $PRINTFILE parameter is defined in the header as follows:
$PRINTFILE formal file
[;DEV=device,[outpri,copies]];CCTL/NOCCTL[;ENV = environment file]
[REV END]
formal file the print file name specified in the report (on the
Define Selection screen);
device the optional, default print device, and if specified,
then also:
outpri an optional, default output priority, used with DEV
copies an optional, default number of copies, used with DEV
CCTL/NOCCTL either CCTL, to include carriage-control characters in
the printfile (for example, to skip lines), or NOCCTL,
not to include such characters. If you select NOCCTL,
HP ALLBASE/BRW inserts a blank line in the printfile for
every line that must be skipped.
environment the optional name for an environment file for the
file printfile.
When more than one report is run in a job, more than one default
printfile may occur. To print each report to $PRINTFILE, insert
^$PRINTFILE default printfile in the report body before the BRWEXEC
command for each report.
Example
The following is an example of defining the $PRINTFILE parameter in the
header of the report job file and using it in the body of the report job
file.
DEFINE JOB TEMPLATE
BEGINPARMS
. . .
ENDPARMS
$PRINTFILE expenses; DEV=,,3;CCTL;ENV = ENV1.ENV.SYS
$INPRI 5
!JOB expenses,MGR.MYACCT;inpri=^$INPRI
. . .
^$PRINTFILE
!CONTINUE
!RUN BRWEXEC.PUB.SYS
expense2
. . .
The above example sets the Job Input Priority to 5 using the standard
$INPRI parameter. Note that the job command line is modified to accept
the value of $INPRI.
Comments
Comments can be included anywhere in the report job file header, except
in the first line and after a parameter definition which ends with the
continuation character, ampersand (&).
For example:
COMMENT This is a comment