JAMS User Guide

Chapter 2
Getting Started with JAMS

This chapter provides a step by step guide to getting started with the Job Access and Management System, also known as JAMS.

2.1 After the Installation

After JAMS has been installed, with no changes to your existing jobs and no information in the JAMS database, JAMS provides many useful benefits.

2.1.1 Job Execution History

JAMS monitors all batch jobs on the system, even jobs which were not submitted by JAMS. You can use the History Inquiry function to review what jobs have run, their execution statistics and completion status. If you retain your log files, they will be available for review as well.

2.1.2 Job Failure Alerting

JAMS can alert you when any batch job fails. Simply select the Configuration option from the Management Options menu and supply the OpenVMS Usernames and/or operator classes for the people who should be notified when a job fails. JAMS can notify you of a failed job via VMSmail, broadcast messages and OPCOM messages.

2.1.3 Job Monitoring and Management

The Monitor Jobs menu option can be used to monitor and manage all batch jobs on your system. This feature provides a powerful, easy to learn interface to OpenVMS batch processing.

2.2 Defining and Using JAMS Jobs

JAMS has been designed to be very easy to implement because the implementation can be done in phases, a Job at a time. JAMS will start providing useful information within minutes of installation. The benefits of JAMS will continue to accrue as you implement more jobs.

In order to expand JAMS capabilities, you need to enter information into the JAMS database. To begin, you need to understand three terms which are used extensively in JAMS. These terms are System, Job and Setup.

A System is a logical group of jobs. A JAMS System Definition defines things which are common to all jobs within the System.

A Job is a command or command procedure. Most sites are already using command procedures for their batch processing. You can continue to use your existing command procedures after installing JAMS. In order to take full advantage of JAMS, you will need to enter information about your batch jobs into the JAMS database, this is a Job Definition.

A Setup is the definition of a particular occurrence or view of one or more jobs. Setups are commonly used to schedule a job, or stream of jobs, to automatically execute at a regular interval.

2.3 Systems Definitions

In JAMS, Job and Setup Definitions must belong to a particular System. This means that you must create at least one System Definition before you can create any Job or Setup Definitions.

Let's create the simplest System possible. We'll call it the DEMO System. For these examples we will use the command line interface. Please keep in mind that you can use this interface or the screen based interface to define Systems.

The JAMS command would be:

JAMS> DEFINE SYSTEM DEMO SYSTEM_DEF> END_SYSTEM

That's simple! This illustrates that, although a JAMS System definition has many potential attributes, you do not have to define anything which isn't useful to your environment.

Note

The previous example showed the results of entering the commands at the JAMS> prompt. It will be easier to follow along if you use a text editor to create a JAMS command file. This way, you won't have to retype the commands each time we add to them. You simply edit your command procedure and then execute it from the JAMS> prompt by typing @filename.ext . From now on, the examples will show the contents of the command procedure, without the prompts.

While the DEMO System is simple, it isn't very useful. Let's expand the definition to make it more useful.

DEFINE SYSTEM DEMO DESCRIPTION "Demo System" DEFAULT SOURCE LOCATION DEMO$DISK:[DEMO.DCL] BATCH QUEUE PROD_QUE1 MAIL NOTIFICATION "JOHN" END_SYSTEM

There, now we have a description of this System, and some defaults which will make it easier to create job definitions. There are a lot more attributes which we could specify but, we'll keep it simple for now.

One thing to note, a System Definition has an Access Control List (ACL) which controls who may manipulate the jobs in the System. Since we didn't specify an ACL in the definition, JAMS provided a default ACL which grants us complete access. No one else has any access at all.

2.4 Job Definitions

The most basic Job definition consists of the Job's name and System I.D. Entering this information into the JAMS database will provide more meaningful reporting, because jobs will be grouped by System. The System definition will also enable a finer degree of control over who should receive notification of abnormal Job terminations.

Let's create the simplest Job possible. We'll call it DEMOJOB1 and make it a member of the DEMO System. The JAMS command would be:

DEFINE JOB DEMOJOB1 SYSTEM DEMO END_JOB

While is is extremely simple, it could be a complete job definition because the System definition provides a lot of default values. If the command procedure for this job was named DEMOJOB1.COM and was located in DEMO$DISK:[DEMO.DCL] and it didn't require any parameters, this would be a complete definition. We could submit the job with the command:

JAMS SUBMIT DEMOJOB1

JAMS would prompt for the scheduled date and time and submit DEMO$DISK:[DEMO.DCL]DEMOJOB1.COM to the PROD_QUE1 batch queue (which it picked up from the System Definition).

2.4.1 Automatic Job Submission

So far, DEMOJOB1 is simple but, not very useful. The first thing that most people want to do with JAMS is automate the submission of jobs. We can manually submit DEMOJOB1, let's see what we have to do to automatically submit it.

DEFINE JOB DEMOJOB1 SYSTEM DEMO AUTO SUBMIT SCHEDULED DATE "MONDAY, WEDNESDAY, FRIDAY" SCHEDULED TIME 14:00 END_JOB

Now JAMS will automatically submit DEMOJOB1 every Monday, Wednesday and Friday at 2:00 PM. One word of caution, JAMS generally schedules about 24 hours in advance so a new job definition won't be automatically scheduled until the day after it's created.

Notice how the scheduled date is a natural language specification. JAMS understands almost any date specification including complicated ones like "LAST WORKDAY OF MONTH", "2ND TUESDAY OF MONTH" or "FIRST DAY OF NEXT MONTH".

2.4.2 Parameters

Command procedures can be much more powerful if you can pass parameters to them. Likewise, batch jobs can be more powerful if they can handle parameters. JAMS has very powerful parameter handling capabilities. Let's add some parameters to our demo job.

We've added two parameters to DEMOJOB1, P1 is a date parameter and P2 is a text parameter. Perhaps the DEMOJOB1 job produces a sales report of sales since the specified date for the specified sales category. Notice that the default value for the date parameter is a natural language date specification.

If you used the JAMS SUBMIT command now, JAMS would prompt you for the values for these parameters using a "fill in the blanks" form.

In this example we used parameter names of P1 and P2 which will be familiar to DCL programmers. You want to use "Pn" parameter named for your existing command procedures but, JAMS supports up to 255 parameters per job with names up to 31 characters in length. See the JAMS Reference Manual for more information on this.

2.4.3 Source Code

A JAMS Job definition can also include the command procedure for the job. For clarity, the previous examples didn't include the command procedure. Here's an example which includes the source code.

DEFINE JOB DEMOJOB1 SYSTEM DEMO AUTO SUBMIT SCHEDULED DATE "MONDAY, WEDNESDAY, FRIDAY" SCHEDULED TIME 14:00 PARAMETER P1 PROMPT "Start Date" DATE DEFAULT VALUE "FIRST DAY OF MONTH" END_PARAMETER PARAMETER P2 PROMPT "Sales Category" TEXT LENGTH 4 DEFAULT VALUE "ALL" END_PARAMETER SOURCE IS $! $! The command procedure for the job can be contained $! in the job definition too! $! $ RUN DEMOPROGRAM $! END_SOURCE END_JOB

2.5 Setup Definitions

A JAMS Setup Definition sets up up one or more jobs to run. A Setup can specify values for parameters, schedules and many other attributes of a job. In our Job Definition example, the DEMOJOB1 job is going to automatically run every Monday, Wednesday and Friday to produce a report for all sales categories of sales since the beginning of the month. Suppose the manager of the XYZ sales category wants this report weekly for just the XYZ category. We could create another job which is nearly identical to DEMOJOB1 but a better approach may be to create a Setup Definition which runs the DEMOJOB1 job with difference parameters. Here is that Setup definition:

This setup definition runs the DEMOJOB1 job with a different schedule and different parameters.

Setups can contain more than one job. Once the managers of the other sales categories see how useful this weekly report is, they will want the same report for their sales category. The setup could wind up looking like this:

DEFINE SETUP DEMOJOB1_WEEKLY SYSTEM DEMO AUTO SUBMIT SCHEDULED DATE "FRIDAY" SCHEDULED TIME 18:00 JOB DEMOJOB1 STEP 1 PARAMETER P1 DEFAULT VALUE "MONDAY" END_PARAMETER PARAMETER P2 DEFAULT VALUE "XYZ" END_PARAMETER END_JOB JOB DEMOJOB1 STEP 2 PARAMETER P1 DEFAULT VALUE "MONDAY" END_PARAMETER PARAMETER P2 DEFAULT VALUE "ABC" END_PARAMETER END_JOB JOB DEMOJOB1 STEP 3 PARAMETER P1 DEFAULT VALUE "MONDAY" END_PARAMETER PARAMETER P2 DEFAULT VALUE "DEF" END_PARAMETER END_JOB END_SETUP

Now, the DEMOJOB1_WEEKLY Setup runs the DEMOJOB1 Job three times with different parameters. Since we specified sequential steps, the jobs will run one at a time. We could also put more than one job in a step to run jobs in parallel.

2.6 Sequencing

One of the most important responsibilities of a job scheduling system is to properly sequence and regulate job execution. It must make sure that a job's prerequisites are met before a job is released and it must make sure that it doesn't overload the systems with batch processing. JAMS provides a number of feature in this area.

2.6.1 Setups

A Setup sets up one or more Jobs to run. A Setup is the simplest way to sequence a stream of Jobs. The Jobs in a Setup run in order based upon the step which the job is assigned. If more than one Job is assigned the same step, those Jobs can run in parallel.

In addition to a step, each Job in the Setup also contains attributes that define what should happen if the Job fails. These attributes include:

Minimum acceptable completion severity.
Should the Setup wait for the completion of this job?
Should the Setup halt if the job fails?

2.6.2 Dependencies

A Job or Setup can have an unlimited number of dependencies. There are job completion dependencies and variable dependencies.

2.6.2.1 Job Dependencies

A job completion dependency insures that a prerequisite job has completed before a job is released. One key question is, completed since when? The default is since the last time that the depending job completed. You can change this since job or eliminate the since job and use an absolute time range.

Let's add a Job dependency to our demo job (note that this is a partial Job definition).

DEFINE JOB DEMOJOB1 ... DEPENDS ON JOB RUN_FIRST END_DEPEND ... END_JOB

This dependency will make the DEMOJOB1 job wait if the RUN_FIRST job hasn't completed successfully since the last time that DEMOJOB1 completed successfully.

Let's change this dependency a little.

DEFINE JOB DEMOJOB1 ... DEPENDS ON JOB RUN_FIRST SINCE JOB RUN_LAST END_DEPEND ... END_JOB

Now this dependency will make the DEMOJOB1 job wait if the RUN_FIRST job hasn't completed successfully since the last time that a third job (RUN_LAST) completed successfully.

We can also eliminate the since job.

DEFINE JOB DEMOJOB1 ... DEPENDS ON JOB RUN_FIRST NO SINCE JOB WITHIN 12 HOURS END_DEPEND ... END_JOB

Now this dependency will make the DEMOJOB1 job wait if the RUN_FIRST job hasn't completed successfully within the past 12 hours.

2.6.2.2 Variable Dependencies

A JAMS Variable is persistent named piece of data. It has a name, datatype and current value. JAMS Variable have a number of uses one of which is being used in a dependency. A Variable dependency is simply a test of the value of a variable. If the test is true, the dependency is satisfied.

Let's add a Variable dependency to our demo job (note that this is a partial Job definition).

DEFINE JOB DEMOJOB1 ... DEPENDS ON VARIABLE FREESPACE > 25000 END_DEPEND ... END_JOB

This dependency looks at the JAMS Variable named FREESPACE. If it's value is greater than 25,000 the dependency is satisfied.

2.6.3 Precheck Jobs

A Precheck Job is a user written dependency. When a Job's dependencies are satisfied JAMS will submit the Job's Precheck Job (if it has one), if the Precheck Job completes successfully JAMS will release the main Job. If the Precheck fails, the main Job will continue to hold and JAMS will resubmit the Precheck job after the defined delay.

The Precheck job can also exit with the JAMS_CANCELJOB status which tells JAMS that the main job doesn't need to run. JAMS will then process the main job as if it has just completed and it will be removed from the schedule. Let's see what we would add to a Job (or Setup) definition to add a Precheck Job (note that this is a partial Job definition).

DEFINE JOB DEMOJOB1 ... PRECHECK JOB CHECK_EDI_TRANSMISSION PRECHECK INTERVAL 00:15 ... END_JOB

You can see that we only needed to add two lines to the job definition in order to specify a Precheck Job. The second line is optional, if we had left it out the interval would default to 5 minutes.

2.6.4 Resources

Resources are a very powerful scheduling tool because they let you define the requirements for your jobs and then JAMS will figure out which jobs can run together, how many jobs can run simultaneously etc. In JAMS, a Resource is created with a command like this:

CREATE RESOURCE SALES_DATABASE/AVAILABLE=100

In this example we've created a Resource called SALES_DATABASE and we specified that we have 100 available. Now we can add Resource Requirements to System, Job or Setup definitions by simply adding a like like this:

DEFINE JOB DEMOJOB1 ... REQUIRES SALES_DATABASE QUANTITY 25 ... END_JOB

Now, there must be 25 units of the SALES_DATABASE available or the DEMOJOB1 will remain pending. You will never have more than 4 occurrences of DEMOJOB1 running concurrently.

Just think of the possibilities, is the SALES_DATABASE resource represents a database named Sales, a job which requires exclusive access to the sales database simply has to specify that it requires 100 units of SALES_DATABASE. If you have a problem with the sales database you can simply change the quantity available to zero and jobs will stop running.

Contents

Index

JAMS User Guide

Chapter 2Getting Started with JAMS

2.6.2 Dependencies

Chapter 2
Getting Started with JAMS