Contents Index JAMS Home Support

This chapter explains the use of Execution Methods, Job Parsing and Template Libraries.

5.1 Command Files

Batch processing generally requires the use of command files (sometimes referred to as batch files). Most sites are already using a large number of command files for their batch processing. You can continue to use your existing batch processing procedures after installing JAMS. In order to take full advantage of JAMS, you must use the JAMS command file template expansion capabilities.

Using command file templates provides the following advantages over normal command files:

• Job command files are simplified and standardized.
• You can have up to 255 parameters per Job.
• Report printing information can be maintained by non-technical personnel.
• Report printing information can be changed at submit time.
• Parameter substitution may take place in data areas of command files.

In order to access the full capabilities of JAMS you must use command file templates. Fortunately, command file templates make batch command files very simple.

When a Job which uses templates is submitted, JAMS combines text modules in a text library with the Job's command file to produce a temporary, expanded command file. The template text library is defined in the Job's System definition.

The text modules in a Template library can be created, extracted and replaced with the OpenVMS LIBRARY/TEXT command.

The following is an example of a traditional batch command file:

$! $! Print Inventory Audit Trail $! $! P1 = Starting date in the form MM/DD/YY $! P2 = Ending date in the form MM/DD/YY $! P3 = Inventory transaction Code $! $ on error then goto ERROR_ROUTINE $! $ if (P1 .eqs. "") then goto PARM_ERROR $ if (P2 .eqs. "") then goto PARM_ERROR $ if (P3 .eqs. "") then goto PARM_ERROR $! $ define PINV010_PRINT PRINT_DIR:PINV010.LIS $! $ RUN INV_EXE:PINV010.EXE $! $ print/nofeed/que=FAST_LP/FORM=2_PART/DELETE PINV010_PRINT $! $ EXIT $! $PARM_ERROR: $ REQUEST "Job PINV010 is aborting because of invalid parameters." $! $ERROR_ROUTINE: $ REQUEST "Error running PINV010, please check the log." $ EXIT

The command file needed for this Job when using command file template expansion is shown in the following example:

$! $! Print Inventory Audit Trail $! $! P1 = Starting date in the form MM/DD/YY $! P2 = Ending date in the form MM/DD/YY $! P3 = Inventory transaction Code $! $ RUN INV_EXE:PINV010.EXE $!

You can see how much more simple the command file is which uses command file template expansion. This is because the standard portions of the command file have been removed and placed in a JAMS template. You can establish a standard template style for each System I.D. When a Job is submitted, JAMS will parse the template definition and merge the templates with the Job's command file to produce a temporary command file which is executed.

The next example shows this command file after expansion. This is the command file which is actually submitted for execution.

$! $! JAMS Main Job Structure $! $ JAMS_RON := 341 $ JAMS_JOB_NAME := PINV010 $ JAMS_SYSTEM_ID := INVENTORY $ JAMS_SUBMITTED_BY := FRANK $ JAMS_SUBMIT_TIME := 10-JAN-1991 09:03 $! $ P1 := "01/10/91" $ P2 := "01/15/91" $ P3 := "OPN" $! $ DEFINE PINV010_PRINT PRINT_DIR:PINV010.00000155 $! $! $! Print Inventory Audit Trail $! $! P1 = Starting date in the form MM/DD/YY $! P2 = Ending date in the form MM/DD/YY $! P3 = Inventory transaction Code $! $ RUN INV_EXE:PINV010.EXE $! $ PRINT/NOFEED/QUEUE=FAST_LP/DELETE - /FORM=2_PART/COPIES=1 - PINV010_PRINT $!

1. These standard DCL Symbols are defined for all Jobs. You can modify which Symbols are defined by modifying the JAMS_MAIN template module.
2. Define Symbols for all of the Job's parameters.
3. Define a logical name for all of the Job's report files. You can modify the definition of this logical by modifying the DEFINE_REPORTS template module.
4. The Job's command file is inserted. Any parameter references are replaced with the value of the parameter.
5. The report file is printed. You can modify the way reports are printed by modifying the PRINT template module.

JAMS will parse a Job if the Job's Execution Method has a job_module specified.

When a parsed Job is submitted, JAMS will look in the Job's System definition for the name and location of the template text library. The template text library must contain the job_module named in the Method definition. This module is the starting point for command file expansion. JAMS will parse this module to produce the temporary command file. Example 5-1 shows the JAMS_MAIN module from the default template library as it is after you install JAMS.

As JAMS parses the text module, it replaces parameter references with their values and expands function references. Depending upon how you reference the Job's source, you may also be able to include Parameter and Function references in your Job file.

Example 5-1 JAMS_MAIN Template Module

$! $! JAMS Main Job Structure $! $ JAMS_RON :=<<jams_ron>> $ JAMS_JOB_NAME := <<jams_job_name>> $ JAMS_SETUP_NAME := <<jams_setup_name>> $ JAMS_SYSTEM_ID := <<jams_system_id>> $ JAMS_SUBMITTED_BY := <<jams_submitted_by>> $ JAMS_SUBMIT_TIME := <<jams_submit_time>> $! <%SYMBOLS(PARAMETER)%> $! <%DEFINE_REPORTS(LOGICAL)%> $! <%JAMS_JOB%> $! <%SET_EXPIRE%> $! <%PRINT_ALL(PRINT_ALL)%> $!

1. Define DCL Symbols for some of the JAMS predefined parameters.
2. Expand the text module SYMBOLS once for each of the Job's parameters.
3. Expand the text module DEFINE_REPORTS once for each of the Job's Reports.
4. Insert the Job's command file here.
5. Expand the text module SET_EXPIRE once for each of the Job's reports.
6. Expand the text module PRINT_ALL once for each report which has not been printed.

A Simple Parameter Reference has the following format:

<<parameter-name[(format)]>>

The parameter name must be either a parameter defined in the Job Definition, the name of a JAMS Variable Definition or a JAMS predefined parameter. JAMS predefined parameters contain information about the Job, Setup and User which can be used in your Job's command template or in a Template library module. The valid JAMS predefined parameters are listed in Table 5-1.

The format, if specified, provides format information for the parameter's data. Valid format specifications vary depending on the parameter's data type. Valid formats for each data type are listed in Table 5-2.

Table 5-1 JAMS Predefined Parameters

Name	Description
JAMS_COMMAND_FILENAME	The full filename of the Job's command file.
JAMS_DESC_LN1	If this Job was submitted by using a Setup definition, this is the first line of the Setup's description. Otherwise, this is the first line of the Job's description.
JAMS_DESC_LN2	If this Job was submitted by using a Setup definition, this is the second line of the Setup's description. Otherwise, this is the second line of the Job's description.
JAMS_JOB_DESC_LN1	This is the first line of the Job's description.
JAMS_JOB_DESC_LN2	This is the second line of the Job's description.
JAMS_JOB_NAME	This is the name of the Job as defined in the JAMS database.
JAMS_LOG_DIR	The text specified in the System's Log Location field.
JAMS_LOG_SPEC	The expanded Log file specification.
JAMS_MAIL_ADR	This is the text specified in the OpenVMS Mail Address field of the Job's System Definition.
JAMS_NAME	If this Job was submitted by using a Setup definition, this is the name of the Setup. Otherwise, this is the name of the Job.
JAMS_OPER_CLASSES	This is the text specified in the Operator Classes field of the Job's System Definition.
JAMS_PRINT_DIR	This is the text specified in the Print File directory field of the Job's System definition.
JAMS_REPLY_USERS	This is the text specified in the OpenVMS Reply Username List field of the Job's System Definition.
JAMS_RON	The Job's run occurrence number. This number is unique to this specific occurrence of a Job. It is similar to the Job's queue entry number except that a RON is not reset until it exceeds 2 billion.
JAMS_SETUP_DESC_LN1	If this Job was submitted by using a Setup definition, this is the first line of the Setup's description. Otherwise, this is a null string.
JAMS_SETUP_DESC_LN2	If this Job was submitted by using a Setup definition, this is the second line of the Setup's description. Otherwise, this is a null string.
JAMS_SETUP_NAME	If this Job was submitted by using a Setup definition, this is the name of the Setup. Otherwise, this is a null string.
JAMS_SUBMITTED_BY	This is the OpenVMS username of the person who submitted the Job. This may not be the same as the OpenVMS username which the Job runs under.
JAMS_SUBMIT_TIME	This is the date and time that the Job was submitted.
JAMS_SYSTEM_DESC	This is a description of the Job's System.
JAMS_SYSTEM_ID	This is the Job's System I.D.
JAMS_TEMP_DIR	The text specified in the Directory for Temporary files field of the Configuration screen.

Table 5-2 Data Types and Formats

Data Type	Format	Description
Text	FILL	Does not trim trailing spaces.
	integer	Expands or trims the data to integer bytes.
INTEGER	DEC	Base ten (decimal) notation.
	HEX	Base 16 (hexadecimal) notation.
	OCT	Base eight (octal) notation.
	integer	Base ten (decimal) notation with leading zeros to fill to integer bytes.
DATE	DD-MMM-YYYY	Default date format.
	MMDDYY
	MM/DD/YY
	MM/DD/YYYY
	MM-DD-YY
	MM-DD-YYYY
	YYMMDD
	YYYYMMDD
TIME	HH:MM	24 hour format (military time).
	HH:MM AM	12 hour format.
	HHMM	24 hour format (military time).
	HHMMAM	12 hour format.

5.2.2 Qualified Parameter References

A Qualified Parameter Reference has the following format:

<<data-class\data-name\parameter-name[(format)]>>

Qualified Parameters are used to obtain the value of fields in a Job's Report or Parameter Definitions. The data-class must be one of either REPORT, PRINT, LOGICAL or PARAMETER. The REPORT, PRINT and LOGICAL data classes are used to obtain values from one of the Job's Report definitions and the PARAMETER data class is used to obtain values from one of the Job's Parameter definitions.

The REPORT, PRINT and LOGICAL data classes are nearly identical. In fact, in the context of a qualified parameter reference, REPORT and LOGICAL are identical. The difference between the REPORT and LOGICAL data classes is explained in Table 5-3. The PRINT data class is identical to the REPORT and LOGICAL data classes except that the PRINT data class marks the referenced Report as printed. See Section 5.2.4, for additional information on the implications of marking a Report as being printed.

The data-name specifies from which Report or Parameter you want to obtain a value.

The valid parameter-names which you can use in a Qualified Parameter Reference depend on which data class you specified. The valid parameter names for each data class are listed in Table 5-4.

The optional (format) specification accepts the same values as a simple parameter. These values are explained in Table 5-2.

5.2.3 Function References

A Function Reference has the following format:

<%function-name[(data-class[\data-name[\parameter-name]])]%>

A Function Reference expands a text module one or more times. The function-name is the name of the text module in the template library. The name JAMS_JOB is reserved and specifies the Job's command file. The text module is expanded in the context of a data-class. The valid data classes are explained in Table 5-3.

Table 5-3 Data Classes

Class	Description
LOGICAL	Used to specify information from a Job's Reports which have unique logical names. If a Job has five Reports defined, but two of the Reports have the same logical name, then there are only four logical name data items.
PARAMETER	Used to specify information on a Job's parameters.
PRINT	Used to specify information from a Job's Reports which will be printed and have not yet been printed. A Report is considered printed when it is referenced using the PRINT data class. A Report will not be printed if the number of copies specified in the Report definition is zero.
REPORT	Used to specify information from a Job's Reports.

When a Function Reference is expanded, it is expanded once for each occurrence of the specified data class. If the function reference also includes the data-name, the function is expanded only once, for the specified data name. The data-name is the name of a particular occurrence of the specified data-class, for example, the name of a Report or Parameter. This syntax is generally used only in a Job's command template.

When a function's text module is expanded, it is done in the context of one occurrence of the specified data-class. When the text of the function includes a Parameter Reference, it can reference either one of the JAMS predefined parameters listed in Table 5-1 or a parameter specific to the data class. The parameters available for each of the data classes are listed in Table 5-4.

Table 5-4 Data Class Parameters

Class	Parameter Name	Description
LOGICAL	COPIES	The number of copies of the Report which should be printed.
	DELETE	If the retention days is zero, returns DELETE, otherwise returns NODELETE
	DESCRIPTION	The text in the Report's Description field.
	DESC_LN1	The text in the Report's Description field.
	FORM	The form on which the Report should be printed.
	FILENAME	The text in the Report's Filename field.
	LOGICAL	The Report's Logical Name.
	QUALIFIERS	The text specified in the Qualifiers field of the Report definition.
	QUEUE	The print queue where the Report should be printed.
	REPORT	The Report I.D.
	RETENTION	The number of days that the Report file should be retained.
REPORT	Same as LOGICAL
PARAMETER	NAME	The name of the parameter.
	VALUE	The current value of the parameter.
	QVALUE	The quoted, current value of the parameter. Enclosed in double quotes if the data type is text.
PRINT	Same as LOGICAL

5.2.4 Controlling Report Printing

It is important to understand the difference between the REPORT, PRINT and LOGICAL data classes and how you can use these data classes to control when and how your Reports are printed.

In the simplest case of a Job which produces one Report, you generally will not need to use the functionality provided by the three different data classes. But suppose we make the Job a little more difficult. Let's assume that the Job produces two Reports, and that we want to print the first Report before the Job finishes (while the second Report is being Generated). And, let's suppose that we want to print the second Report on two different print queues. This type of scenario occurs in most OpenVMS shops and is easily handled by JAMS.

5.2.4.1 Base Functionality

First let's look at base functionality. You define the Job and it's two Reports. When the command file is parsed and expanded, JAMS will define a logical name for each of the Reports and generate two PRINT commands at the end of the Job.

5.2.4.2 Printing a Report More than Once

In order to make JAMS print the second Report twice, we simply use Job Maintenance to define a third Report. However, we give the second and third Reports the same logical name. Now when JAMS parses the command file it will define two logical names (because the LOGICAL data class treats the second and third Reports as one in the same since they have the same logical name). Then, JAMS will generate three PRINT commands at the end of the command file (because the PRINT data class does not merge Reports based on the logical name).

5.2.4.3 Controlling Print Time

Now, to force the first Report to print before the end of the Job, we have two options. Both options entail modifying the Job's command file so that a PRINT command is issued as soon as the first Report is ready to print. If we simply insert a OpenVMS PRINT command, the Report will certainly start printing early, but JAMS would issue a second PRINT command at the end of the Job. The trick is to reference the Report using the PRINT data class which will mark the Report as printed and thus prevent JAMS from generating a PRINT command at the end of the Job.

Our two options are to either use a function call to the PRINT function or to reference the Report using Qualified Parameter Reference and the PRINT data class.

5.2.5 An Example of Template Expansions

The following is an example which illustrates many of the features which have been explained in the preceeding sections.

This is an example of a Job which has two Reports. We have added one customized text module to the Template Library which is used to distribute a Report via OpenVMS Mail. This module must be invoked in the context of a REPORT, LOGICAL or PRINT data class because it references parameters which are specific to these classes. The following is the exact text of this module:

$! $! Distribute a Report via OpenVMS Mail $! $ MAIL/SUBJECT="<<DESCRIPTION>>" - /PERSONAL_NAME="JAMS Batch Job" - <<LOGICAL>> <<JAMS_SUBMITTED_BY>> $!

The Job in this example runs two programs, each of which will produce one Report. The programs which the Job runs accept values for their parameters from SYS$INPUT (as does the COBOL ACCEPT verb). The exact text of the Job's command file is shown in Example 5-2.

Example 5-2 Sample Jobs command file

$! $RUN PRD_EXE:PROJECT_DETAIL.EXE <<JAMS_JOB_NAME>> <<REPORT\PROJDTL\DESCRIPTION>> <<START_DATE(YYMMDD)>> <<END_DATE(YYMMDD)>> <<PROJECT>> $! <%PRINT(PRINT\PROJDTL)%> $! $RUN PRD_EXE:PROJECT_SUMMARY.EXE <<JAMS_JOB_NAME>> <<REPORT\PROJSUM\DESCRIPTION>> <<START_DATE(YYMMDD)>> <<END_DATE(YYMMDD)>> <<PROJECT>> $! <%MAIL(PRINT\PROJSUM)%> $!

1. This program accepts the Job Name so it can be printed in the headings of the report. (A simple parameter reference to a JAMS predefined parameter).
2. It also accepts the Report Description which will be printed in the headings of the report. (A qualified parameter reference to a Report data class parameter).
3. Accept the date parameters and force the correct format. (A simple parameter reference with formatting).
4. Tell JAMS to insert the PRINT command here so that the report will start printing before the Job has finished. (A function reference).
5. Invoke our custom MAIL function to mail the second report to the user who submitted the Job.

When this Job is requested by an end-user (via the Job Submission menu option), JAMS will parse the Job file and produce a temporary command file which is a combination of the JAMS_MAIN text module, the Job's command file and any template text modules which are referenced during the parsing. Example 5-3 shows the temporary command file which JAMS will create.

Example 5-3 Sample Job's command file after parsing

$! $! JAMS Main Job Structure $! $ JAMS_RON := 834962 $ JAMS_JOB_NAME := PROJECT_DTL_SUM $ JAMS_SETUP_NAME := $ JAMS_SYSTEM_ID := PROJECTCTL $ JAMS_SUBMITTED_BY := GBUSH $ JAMS_SUBMIT_TIME := 15-APR-1991 09:53 $! $ START_DATE == "02-AUG-1991" $ END_DATE == "11-APR-1991" $! $ DEFINE PROJDTL - 'f$parse("","PROJCTL_REP:PROJDTL.000CBD92",,,"SYNTAX_ONLY") $ DEFINE PROJSUM 'f$parse("","PROJCTL_REP:PROJSUM.000CBD92",,,"SYNTAX_ONLY") $! $! $RUN PRD_EXE:PROJECT_DETAIL.EXE PROJECT_DTL_SUM Detailed Expenses for a Project 900802 910411 DSTORM $! $ SET FILE/EXPIRATION_DATE="TODAY+5-" PROJSUM $ PRINT/NOFEED/QUEUE=OVAL_LN03/NODELETE - /FORM=DEFAULT/COPIES=1 - PROJSUM $! $! $RUN PRD_EXE:PROJECT_SUMMARY.EXE PROJECT_DTL_SUM Summary of Expenses for a Project 900802 910204 DSTORM $! $! $! Distribute a Report via OpenVMS Mail $! $ MAIL/SUBJECT="Summary of Expenses for a Project" - /PERSONAL_NAME="JAMS Batch Job" - PROJSUM GBUSH $! $! $!

1. Define DCL symbols for some of the predefined parameters.
2. Define DCL symbols for each of the Job's parameters.
3. Define logical names for our report files.
4. This is the beginning of our Job's command file.
5. This is the text from the PRINT function which we specified in our command file.
6. Here is our expanded MAIL function.
7. The JAMS_MAIN text module calls the PRINT function at the end of the JOB, but since we have already referenced both of our reports using the PRINT data class, there are no reports to print.

When you write DCL command procedures you can use the ON ERROR statement to trap errors which occur during the processing of the command procedure. The standard JAMS template library does not include any error trapping. If an error occurs the command exits and returns a status value which represents the error which caused the job to fail. JAMS uses the exit status of a job to determine if the job was successful.

If you want to trap errors in your command procedures, make sure that you save the status code of the error which caused the job to fail and use this saved value when the job exits. This is the only way that JAMS will know that the job failed.

Example 5-4 shows a fragment of a command procedure which traps errors and also exits with the correct status code.

Example 5-4 Trapping DCL errors

$! $ ON ERROR THEN GOTO ERROR_RTN ! Set error trapping $! . . . $! $ERROR_RTN: $ saved_status = $STATUS ! Save the bad status value $! $! Cleanup after the error $! $ EXIT saved_status ! Exit with the bad status value $!

Copyright © 2000, MVP Systems, Inc. All rights reserved.