The schedule command creates and manages jobs related to ClearCase and ClearCase LT and arranges to execute them at specified times. A job consists of an executable program, or task, that the scheduler runs one or more times with a given set of arguments.
In ClearCase, the scheduler is available on any host that runs the albd_server. In ClearCase LT, the scheduler is available on the ClearCase LT server host only.
Note: For the pathnames of the files and directories described in this section, see the sections, UNIX Files and Windows Files.
The scheduler relies on two data repositories:
A task must be defined in the task database before you can schedule it. The task database is a single text file, task_registry. You can add task definitions to the task database by editing this file using a text editor. You must not change the definitions of standard tasks, but you can add your own task definitions at the end of the file. For more information, see “Task Definition Syntax”.
Standard tasks reside in the directory tasks. These tasks are not editable. Tasks that you define can reside anywhere in the file system, but the recommended location is the directory tasks. This directory contains a task, ccase_local_day, that is intended for user-defined operations to be run daily. The directory contains another task, ccase_local_wk, that is intended for user-defined tasks to be run weekly. You can customize these two tasks using a text editor or can create entirely new tasks.
The database of jobs is the file db. This is a binary file that you read and edit by using the schedule command. When you use the schedule command to change the job database, you use the job definition language described in “Job Definition Syntax”.
ClearCase and ClearCase LT install a template for an initial task database, which contains definitions for standard tasks, as the file task_registry. The albd_server uses this template to create the first version of the actual task database, task_registry.
Templates are installed for two customized tasks, ccase_local_day and ccase_local_wk, in the directory templates. The albd_server uses these templates to create initial versions of these tasks in the directory tasks.
ClearCase and ClearCase LT install an initial set of job definitions as the text file initial_schedule. These job definitions rely on task definitions in the task registry template. The albd_server uses these job definitions to create the first version of the job database, db.
Note: Do not edit or delete any files in the directory tree whose root is scheduler.
When no job database exists, the albd_server uses the initial set of job definitions in the file initial_schedule to create a default schedule. This schedule consists of some jobs run daily and other jobs run weekly.
Daily jobs:
Weekly jobs:
The default schedule also includes three jobs to automate the synchronization of MultiSite replicas. These jobs are designed to run daily but are disabled by default, whether or not MultiSite is installed. For more information about these jobs and how to enable them for use with MultiSite, see the Administrator's Guide for Rational ClearCase MultiSite.
You can arrange for a job to run under a variety of schedules:
For daily, weekly, and monthly schedules, you can specify starting and ending dates for the job. To run a job one time, you can specify a daily schedule with identical start and end dates.
The –edit and –set options create or modify jobs by using a declarative job definition language. The –get option displays a textual representation of currently defined jobs using the same language.
The job definition language has the following general features:
A job definition file consists of a sequence of job definitions. Each job definition begins with the statement Job.Begin and ends with the statement Job.End. Between these statements are other statements that define job properties. A statement that defines a job property has the following form:
Some properties have fields. In this case the definition of a property consists of a sequence of statements, one for each field, with the following form:
Some fields themselves have subfields.
The value portion of some property definitions can contain a sequence of individual values separated by commas. No white space can appear before or after a comma that separates two values in a sequence. For the Args property, individual values are separated by white space.
Job properties are of two types:
Table 12 lists editable job properties.
Table 12. Editable Job Properties
Property | Field | Value | Default |
---|---|---|---|
Name | name_string (quoted if it contains white space; must be unique across jobs) | No default; a value is required. | |
Description | Begin | desc_string (on subsequent lines only; maximum 255 characters) | "" |
End | (none) | ||
Schedule | [a] | [b] | No default; a value is required. |
Task | task_id (unsigned) | task_name (string) | No default; a value is required. | |
Args | arg_string [...] (arg_string quoted if it contains white space) | No args | |
DeleteWhenCompleted | TRUE | FALSE | FALSE | |
NotifyInfo | OnEvents | JobBegin | JobEndOK | JobEndOKWithMsgs | JobEndFail | JobDeleted | JobModified [,...] | If no NotifyInfo field is specified, no notifications are issued; if any NotifyInfo field is specified, all must be specified. |
Using | |||
Recipients | address [,...] | ||
See Table 13 See Table 13 |
Table 13 lists fields of the Schedule property. Schedules are of two types:
The Monthly, Weekly, Daily, and Sequential fields are mutually exclusive; each job must have one and only one of these fields.
The StartDate, LastDate, FirstStartTime, StartTimeRestartFrequency, and LastStartTime fields are optional. One or more of these fields can appear along with a Monthly, Weekly, or Daily field. StartDate and LastDate determine the first and last dates the job is eligible to run on its monthly, weekly, or daily schedule. FirstStartTime determines what time the job first runs on each day it is scheduled. StartTimeRestartFrequency specifies an interval to wait before running the job again. LastStartTime is meaningful only with StartTimeRestartFrequency; it determines the last time the job is eligible to run on each day it is scheduled. If StartTimeRestartFrequency is specified for a job, the job will run every StartTimeRestartFrequency (for example, every two hours) until midnight or LastStartTime, whichever is earlier.
All dates and times are local to the host on which the scheduler is running. Date outputs are displayed in ISO format regardless of any user-specified preference for the display format of dates.
Table 13. Fields of the Job Schedule Property
Table 14 lists read-only job properties. For the LastCompletionInfo property, ExitStatus is the value returned by the wait() system call on UNIX or by the GetExitCodeProcess() function on Windows. Only the first 511 bytes of standard output and error messages are displayed.
Table 14. Read-Only Job Properties
Following is an example definition the scheduler could display with the –get option for a job scheduled to run sequentially, including job properties defined by the scheduler:
Job.Begin
Job.Id: 1
Job.Name: "Daily VOB Pool Scrubbing"
Job.Description.Begin:
Scrub the cleartext and derived object storage pools of all local VOBs.
Job.Description.End:
Job.Schedule.Daily.Frequency: 1
Job.Schedule.StartDate: 2002-12-30
Job.Schedule.FirstStartTime: 04:30:00
Job.DeleteWhenCompleted: FALSE
Job.Task: 3
# Job.Task: "VOB Pool Scrubber"
Job.Args:
Job.NotifyInfo.OnEvents: JobEndOKWithMsgs,JobEndFail
Job.NotifyInfo.Using: email
Job.NotifyInfo.Recipients: root
Job.Created: 2002-12-30T15:18:06-05 by rational.com/root@phenol
Job.LastModified: 2002-12-30T15:18:06-05 by rational.com/root@phenol
Job.Predefined: TRUE
Job.NextRunTime: 2003-01-10T04:30:00-05
Job.LastCompletionInfo.ProcessId: 21511
Job.LastCompletionInfo.Started: 2003-01-09T04:30:00-05
Job.LastCompletionInfo.Ended: 2003-01-09T04:39:27-05
Job.LastCompletionInfo.ExitStatus: 0x100
Job.LastCompletionInfo.Messages.Begin:
Thu Jan 9 04:39:26 EST 2003
ClearCase scrubber failed on phenol with exit status 1
Some VOBs were NOT scrubbed
See phenol:/var/adm/rational/clearcase/log/scrubber_log
Job.LastCompletionInfo.Messages.End:
Job.End
A task must be defined in the task database before you can schedule the task. The task database is a text file, which you can edit using a text editor. The task database contains definitions that use a declarative task definition language similar to the job definition language.
The task definition language has the following general features:
The task database file consists of a sequence of task definitions. Each task definition begins with the statement Task.Begin and ends with the statement Task.End. Between these statements are other statements that define task properties. A statement that defines a task property has the following form:
In the task database, definitions of standard tasks appear first. You must not change or delete any of these definitions. You can add task definitions of your own at the end of the task database file.
Table 15 lists task properties.
The scheduler uses the task Id property in a job definition to identify the task to run. If any scheduled jobs use a task Id, you must be careful not to change the task's Id property in the task database without also changing all references to that property in the database of scheduled jobs.
The Pathname value is the pathname of the executable to be invoked when the task is run. The pathname can be relative or absolute. If it is relative, the scheduler looks first for the task in these directories in this order:
Platform | First location | Second location |
---|---|---|
UNIX | ccase-home-dir/config/scheduler/tasks | /var/adm/rational/clearcase/scheduler/tasks |
Windows | ccase-home-dir\config\scheduler\tasks | ccase-home-dir\var\scheduler\tasks |
The optional UIInfo property describes the task's command-line interface, such as the types of arguments the task can take. This property is used internally by ClearCase and ClearCase LT; do not specify it for a user-defined task.
Following is an example read-only definition for a standard task:
Task.Begin Task.Id: 2 Task.Name: "View Space" Task.Pathname: view_space.sh Task.UIInfo: "view-spec" Task.End
Following is an example definition for a user-defined task:
Each task runs in a separate process started by the albd_server. A task has the following execution environment:
The scheduler maintains a single access control list (ACL). The ACL determines who is allowed access to the scheduler and to the ACL itself.
The –edit –acl and –set –acl options modify the ACL using a declarative ACL definition language. The –get –acl option displays the current ACL.
The ACL definition consists of a sequence of ACL entries. Each ACL entry must occupy a single line. Leading white space, lines beginning with number sign (#), and blank lines are ignored. Each ACL entry has the following form:
Table 16 lists the identity types and identities allowed in ACL entries. The identity types are case insensitive.
Table 16. Identity Types and Identities in Scheduler ACL Entries
Identity Type | Identity |
---|---|
Everyone | (None) |
Domain | domain_name |
Group | domain_name/group_name | domain_name\group_name |
User | domain_name/user_name | domain_name\user_name |
In the identity portion of an ACL entry, the domain_name is an NIS domain for UNIX clients of the scheduler and a Windows NT Server domain for Windows clients of the scheduler. Note that you must supply a domain in the identity portion of a Group or User ACL entry. For an ACL entry with a Windows NT Server domain, group_name must be a global group, and user_name must be a domain user account. Names of domains, groups, and users are case insensitive for the scheduler.
Note that no white space can appear anywhere in an identity_type:identity specification.
Table 17 lists the access types allowed in ACL entries. The access types are case insensitive.
Table 17. Access Types In Scheduler ACL Entries
Access type | Access to schedule | Access to ACL |
---|---|---|
Read | Read only | Read only |
Change | Read and write; can start jobs | Read only |
Full | Read and write; can start jobs | Read and write |
Each combination of domain and group or of domain and user represents a single identity. (Note that NIS domains differ from Windows NT Server domains, so a group or user in an NIS domain represents a different identity from the same group or user in a Windows NT Server domain.) Each single identity can have only one access type. However, access rights are inherited from Everyone to Domain to Group to User in such a way that each user has the least restrictive of all these access rights that apply to that user. For example, if a user's ACL entry specifies Read access but the ACL entry for the user's group specifies Change access, the user has Change access. The order of ACL entries is not significant.
Access rights of these identities to a scheduler on a remote host are determined by the scheduler's ACL. The default ACL is as follows:
This means that by default, everyone can read the schedule, but only the highly privileged identities logged on to the computer where the scheduler is running can modify the schedule or the ACL.
Following is an example ACL definition:
The UNIX examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.
The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.
In cleartool single-command mode, cmd-context represents the UNIX shell or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.
cmd-context schedule –get –job "Daily VOB Pool Scrubbing"
Job.Begin
Job.Id: 1
Job.Name: "Daily VOB Pool Scrubbing"
Job.Description.Begin:
Scrub the cleartext and derived object storage pools of all local VOBs.
Job.Description.End:
Job.Schedule.Daily.Frequency: 1
Job.Schedule.StartDate: 2002-12-30
Job.Schedule.FirstStartTime: 04:30:00
Job.DeleteWhenCompleted: FALSE
Job.Task: 3
# Job.Task: "VOB Pool Scrubber"
Job.Args:
Job.NotifyInfo.OnEvents: JobEndOKWithMsgs,JobEndFail
Job.NotifyInfo.Using: email
Job.NotifyInfo.Recipients: root
Job.Created: 2002-12-30T15:18:06-05 by rational.com/root@phenol
Job.LastModified: 2002-12-30T15:18:06-05 by rational.com/root@phenol
Job.Predefined: TRUE
Job.NextRunTime: 2003-01-10T04:30:00-05
Job.LastCompletionInfo.ProcessId: 21511
Job.LastCompletionInfo.Started: 2003-01-09T04:30:00-05
Job.LastCompletionInfo.Ended: 2003-01-09T04:39:27-05
Job.LastCompletionInfo.ExitStatus: 0x100
Job.LastCompletionInfo.Messages.Begin:
Thu Jan 9 04:39:26 EST 2003
ClearCase scrubber failed on phenol with exit status 1
Some VOBs were NOT scrubbed
See phenol:/var/adm/rational/clearcase/log/scrubber_log
Job.LastCompletionInfo.Messages.End:
Job.End
ccase-home-dir/config/scheduler/initial_schedule |
ccase-home-dir/config/scheduler/tasks/templates/task_registry |
ccase-home-dir/config/scheduler/tasks/templates/ccase_local_day.sh |
ccase-home-dir/config/scheduler/tasks/templates/ccase_local_wk.sh |
/var/adm/rational/clearcase/scheduler/db |
/var/adm/rational/clearcase/scheduler/tasks/task_registry |
/var/adm/rational/clearcase/scheduler/tasks/ccase_local_day.sh |
/var/adm/rational/clearcase/scheduler/tasks/ccase_local_wk.sh |
ccase-home-dir\config\scheduler\initial_schedule |
ccase-home-dir\config\scheduler\tasks\templates\task_registry |
ccase-home-dir\config\scheduler\tasks\templates\ccase_local_day.bat |
ccase-home-dir\config\scheduler\tasks\templates\ccase_local_wk.bat |
ccase-home-dir\var\scheduler\db |
ccase-home-dir\var\scheduler\tasks\task_registry |
ccase-home-dir\var\scheduler\tasks\ccase_local_day.bat |
ccase-home-dir\var\scheduler\tasks\ccase_local_wk.bat |
Copyright© 2003 Rational Software. All Rights Reserved.