Software User's Guide
The SPS/Scheduler
Click here for the User's Guide of the previous version.

Table of contents

  1. Introduction
  2. The scheduler.pm program
  3. The Main Screen
  4. Process Definition Screen
    1. Process name
    2. Project name
    3. Privileged
    4. Priority
    5. Command
    6. Output path
    7. Current directory
    8. Shutdown command
    9. Modified by
    10. Modified at
    11. CPU limit
    12. Suspend
    13. Start at
    14. End at
    15. Interval
    16. Days of week
    17. Run on holidays
    18. Completion window
    19. Start on dates
    20. Dependencies
    21. Start job
    22. Restart attempts
    23. Next command
    24. Abend command
  5. Process documentation
  6. Command buttons
    1. Next/Previous
    2. Save
    3. Start
    4. Reschedule
    5. Terminate
    6. Delete
    7. Output
  7. The Reports Table (scheduler_reports.table)
    1. report
    2. from
    3. to
    4. process
    5. project
    6. counts_only
    7. did_not_run
    8. failed
    9. process_definitions
    10. suspended
    11. output_path
    12. email
  8. Email-ed HTML-formatted reports
  9. The Holidays Table (sps_holidays.table)
  10. Working with multiple environments


Introduction

The SPS/Application Scheduler-Monitor is a complete, integrated package designed to control and monitor all applications running on the system. The Monitor automates all application startups, shutdowns and recovery procedures based on predefined time schedules. SPS allows complete automation of batch cycles and keeps on-line applications up and running at all times. Single-point control of operations at all application levels minimizes risk of human error and prevents production disasters.


The scheduler.pm program

scheduler.pm

Purpose

Start this program in the background using start_scheduler.cm.

CRT Form

 -------------------------------- SPS/Scheduler -------------------------------
-envionment: PROD
-command:
-name
-lams_input_q:
-users: Soft.SysAdmin

Lineal Form

scheduler.pm [-envionment] [-command] [-name][-lams_input_q] [-users] 

Arguments

-environment

The name of a valid Scheduler Envionrment you wish to work with.

-command

It is possible to send commands to the Scheduler Server Process without going into the screen interface. This allows to start and stop processes from command macros and from sub-processes that are running in the background. Scheduler supports the following commands:

-name

A valid Process or Project name on which "command" will be executed. Or a valid report-name when runnig reports.

-lams_input_q

The path name of the SPS/Logs & Alert Manager main input queue. You may use this option to send messages directly into the LAMS system.

-users

Use this argument to define which users should receive all system messages. For example, every time a process is started or completes, the monitor sends a message to the terminal's 25 line. By default, messages are sent to the user who started the monitor. You may use this field to add more user names to this notification.


The Main Screen


Click to enlarge.

The Main screen list all defined process. Click any of the navigation keys - Next, Back, First, Last to select the desired page. If you are looking for a specific process, enter the first few letters in the Start field and click Go. If you wish to define a new process - click Add. To select an existing process, click on its name.


Process Definition Screen


Click to enlarge.
Process A unique name that identifies the process throughout the system.

Project The name of the logical Project or Group the process belongs to. This is an optional feature that later on, will allow you to start and/or stop groups of processes. For more information see the scheduler command description.

Privileged A yes/no cycle field that defines the privileges of the process.

Priority Defines the system priority that Scheduler will assign to the process at startup time. Valid values are 0-9.

Command Defines the command Scheduler will execute. The user may define any VOS or user-defined internal, external, programs and/or command macros.

Output path The full path name of a file or an I/O device. The process will attach its default_output_port to this path. If the user does not provide a value for this field, Scheduler will use the Process Name as the Output File name, for example, [process_name].out.

Current directory The full path name of the directory from which Scheduler will start the process.

Shutdown command A relative/full path name to a command macro or a program name that should be used to stop the process. By default, the monitor uses the VOS stop_process command to stop processes. The Shutdown Command may be used if more graceful shutdown procedures are required. If you choose this option, make sure that your procedure causes the process to stop.

Modified by Specifies the name of the user who last modified the process definition. This is an output-only field automatically set by SPS.

Modified at Specifies the date and time of the last change to the process definition. This is an output-only field automatically set by SPS.
CPU limit An optional feature that allows you to automatically stop processes that consume unexpected amounts of CPU. Specify time limit in seconds. Process that was stopped for exceeding its CPU limit will terminate with VOS error number 3439-e$kill_this_process and will not be automatically restarted by the Monitor.

Suspend A yes/no switch that used to suspend the process. The Scheduler will not starts a uspended process.

Start at A standard VOS date_time string that defines when Scheduler should start the process. If the user leaves this field with blanks, then the process will have no scheduling and will start when the Monitor comes up. For valid date_time formats, see the VOS documentation on the s$cv_to_int_date_time command.

Examples: 18:00, 94-12-09 08:00. Tuesday 18:00.

End at A standard VOS date_time string that defines when Scheduler should terminate the process. The feature allows to automatically stop running processes at a specified time. For valid date_time formats, see the VOS documentation on the s$cv_to_int_date_time command.

Interval A valid VOS Relative Time Expression (see documentation on the s$cv_to_int_date_time) that defines the intervals between each process re-submission. The system will automatically start the process based on this Interval. When left blank, Scheduler will run the process only once.

Examples: + 1 day, + 1 hour + 30 minutes , +1 month

Days of week A seven-character string that defines the days of the week on which the process may run. Valid characters in this string are 'Y' (yes) and 'N' (no). For example, a 'NYYYYYN' means that the process may run only on weekdays and that Scheduler will not start it on Saturdays (7) and Sundays (1).

Run on holidays A yes/no switch that defines whether the process should run on holidays. Use the sps_holidays.table to define the holidays and non-business days.

Completion window A time specified in minutes indicating a successful completion. This is used internally by the scheduler when evaluating dependant processes. This will be best explained by an example:

Process B is scheduled to run at 18:00 and is dependent on the successful completion of process A. Process A has a completion window of 60 (1 hour). At 18:00 Scheduler will look at the last run of A before starting process B. If A has completed successfully after 17:00 (within the last hour), it will go ahead and start process B, otherwise it will report an error indicating that B was not started because process A has not completed successfully.

Start dates Start dates allows to specify up to 5 start-dates in advance. This option should be used only if the process must be started at irregular intervals. If you use start-dates you must specify "table" in the interval field.

Dependencies Dependencies allows the definition of up to 5 dependent processes. The Scheduler will only start the process if all specified dependent processes have successfully completed within their respective Completion window.

Start job A name of another Scheduler process you wish to start the current job completes.

Restart attempts In the case of a process failure, this field defines how many times to automatically restart the process. By default, a failed process will not be restarted. It is recommended not to exceed 2-3 attempts to restart a failed process. Allowed values are 0 to 9.

Next command Any standard VOS command that Scheduler should execute when the process completes successfully. Using this field allows chaining of processes, for example, process B will start after process A. The system will issue an equivalent of a start_process command on the command that you specify. There are two ways of using this feature:

  • With the first method, enter any command line that Scheduler should start it as a sub-process. The command will execute only once.

  • Enter "scheduler -name [Process Name]" as the command line. By using this method, Scheduler will continue to monitor the new Completion Command process.

Abend command Any standard VOS command that Scheduler should execute when the process aborts. Using this field allows the definition of any recovery procedures. The Failure command will be triggered after the process was unsuccessfully restarted (if restart attempts was specified). Note that the Monitor detects application failure by examining the VOS command status. Make sure that your failed application does not reset the command status before terminating.


Process documentation

Every process may have an associated doumentation file that will be automatically displayed in the Process Details screen. To apply a document to a process, save the documentation as follows under the documentation directory:

SPS>scheduler>documentation>[process_name].doc


Command buttons

Next/Previous The Next/Previous buttons are used to move forward and backwards within the table to the next or previous process without having to go back to the Main screen.

Save The Save button saves any changes made to the process definition. To create a new copy or occurrence of a process, click the process give it a new process name and click Save.

Start Clicking the Start button will send a Start Process command to the Scheduler. Scheduler will not start a suspended process.

Reschedule Clicking the Reschedule button will send a reschedule command to the Scheduler. Scheduler will then schedule the process as necessary.

Terminate Clicking the Terminate button will send a stop-process command to the Scheduler. Scheduler will then stop the running process or remove a scheduled event.

Delete Clicking the Delete button will send a delete-process command to the Scheduler. Scheduler will then remove the process from the database. The user cannot execute this command while the process is running.

Output When clicking the Output button, the system will locate the marked process' OUTPUT_FILE and display it.Scheduler sets an Implicit Lock on output_files. This allows the user to display these files while the process is still running.


The Reports Table (scheduler_reports.table)

The Reports Table is used to define frequently-used reports. Each report is identified with a unique logical name. To produce a report execute: scheulder.pm -command report -envionment [name] -name [Report]
organization: relative;
index : report no_duplicates;
fields :

report char (32) var,
from char (32) var,
to char (32) var,
process char (32) var,
project char (32) var,

counts_only bit (1) aligned,
did_not_run bit (1) aligned,
failed bit (1) aligned,
process_definitions bit (1) aligned,
suspended bit (1) aligned,

output_path char (256) var,
email char (32) var;
end;

report A unique name that identifies the Report. To produce a report execute:

schduler.pm -report [report-name]

from A standard-VOS data-time that define the time start date/time selection criteria.
to A standard-VOS data-time that define the time end date/time selection criteria.
process An option that allows the user to select log records that relate to the specified process name(s). If the user does not provide a value, all processes will be selected. Star-names are supported.

project An option that allows the user to select log records that relate to the specified Project name(s).

counts_only When set, the program will produce a "counts-only"-formatted report.

did_not_run When set, the program will produce a "Did-Not-Run" report listing only processes that have not completed within the report's timeframe.

failed When set, the program will produce a report listing only processes that have failed within the report's timeframe.

process_definitions When set, the report will include all process-definition data as stored in the configuration database.

suspended When set, the program will produce a process-definition reports only for those processes that are suspended.

output_path The relative or full path name of the report file.
email You can choose to send the report via you E-Mail Server to selected users. Simply enter their email nick-names as defined in the sps_email_server.table.


Email-ed HTML-formatted reports

Process Definitions Report
Click to enlarge.
Process Activity Report
Click to enlarge.


The Holidays Table (sps_holidays.table)

The Holidays table (sps_holidays.table), is basically a list of holidays. You'll need to update it once a year and create it. You need to enter dates in the standard yy-mm-dd format.
organization: relative;
index : holiday no_duplicates;
fields : holiday char (8);
end;

Working with multiple environments

In most cases, you can simply use all the default settings and start one Server process using the
start_scheduler command. However, if you need to create and work with separate QA environments, you may do so while using the following suggested command macros.

Start the Servers

&begin_parameters
env env:string,req,allow (QA, QA2, QA3,PROD),=PROD
&end_parameters
!change_current_dir (master_disk)>SPS>scheduler

start_server.cm &env&