schedule

Schedules and manages jobs to be run one or more times

Applicability

Product

Command type

VersionVault

cleartool subcommand

Platform

UNIX

Linux

Windows

Synopsis

  • VersionVault—Display information about jobs, tasks, or protection:
    sched/ule [ –f/orce ] [ –hos/t hostname ] –get
    [ –sch/edule | –job job-id-or-name | –tas/ks | –acl ]
  • VersionVault—Edit a schedule or the scheduler's protection information:
    sched/ule [ –f/orce ] [ –hos/t hostname ] –edi/t [ –sch/edule | –acl ]
  • VersionVault—Set a schedule or protection using definitions in a file:
    sched/ule [ –f/orce ] [ –hos/t hostname ] –set
    [ –sch/edule | –acl ] defn-file-pname
  • VersionVault—Perform an operation on a scheduled job:
    sched/ule [ –f/orce ] [ –hos/t hostname ]
    [ –del/ete | –run | –wai/t | –sta/tus ] job-id-or-name

Description

The schedule command creates and manages jobs related to VersionVault 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.

The scheduler is available on any host that runs the albd_server.

Note: For the pathnames of the files and directories described in this section, see the sections, UNIX and Linux files and Windows files.

Task and job storage

The scheduler relies on two data repositories:

  • A database of tasks available for scheduling
  • A database of jobs, or scheduled tasks

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.

Task and job database initialization

VersionVault installs 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.

VersionVault installs 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.

Default schedule

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 that are run weekly and other jobs that are run daily. Weekly jobs are run by default. Daily jobs are not run by default: you must explicitly enable them.

Daily jobs:

  • Scrub cleartext and derived object storage pools of all local VOBs, using scrubber.
  • Copy the VOB database for all local VOBs that are configured for snapshots, using vob_snapshot.
  • Copy the VersionVault registry from the primary registry server host (when run on a backup registry server host), using rgy_backup.
  • Run user-defined daily operations in ccase_local_day.
  • Generate and cache data on disk space used by all local views, using space.
  • Generate and cache data on disk space used by all local VOBs, using space.

Weekly jobs:

  • Scrub some logs (see the Help).
  • Scrub the databases of all local VOBs, using vob_scrubber.
  • Run user-defined weekly operations in ccase_local_wk.
  • Generate and cache data on disk space used by derived objects in all local VOBs, using dospace.

Job timing options

You can arrange for a job to run under a variety of schedules:

  • Run daily or every n days, starting at a specified time of day and possibly repeating at a specified time interval during the day.
  • Run weekly or every n weeks, on one or more days of each week, starting at a specified time of day and possibly repeating at a specified time interval during the day.
  • Run monthly or every n months, on a specified day of the month, starting at a specified time of day and possibly repeating at a specified time interval during the day.
  • Run immediately after another job finishes.

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.

Job definition syntax

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:

  • Each statement must occupy a single line, though job descriptions and output messages can occupy more than one line.
  • The language is case-insensitive.
  • Leading white space, lines beginning with a number sign (#), and blank lines are ignored, except within job descriptions.
  • The quotation character is double quote (").

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:

Job.property_name: value

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:

Job.property_name.field: value

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:

  • Editable. You can define or modify the property. Some properties and fields are required; others are optional and have default values. When you define or modify a property, you must specify fields and subfields of that property in the order listed in Table 1 and Table 2.
  • Read-only. The scheduler defines the property, and you cannot define or modify it. When you create a job definition, the scheduler ignores all definitions of read-only properties. When you edit an existing job definition, the scheduler ignores all definitions of read-only properties except for Id. When you edit an existing job definition, the scheduler uses the Id, if present (and if not present, the Name), to identify the job to modify.

The following table lists editable job properties.

Table 1. 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

See Table 2

See Table 2

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

email

Recipients

address [,...]

Table 2 lists fields of the Schedule property. Schedules are of two types:

  • Periodic. The job runs on one or more days specified by the Monthly, Weekly, or Daily field.
  • Sequential. The job runs following completion of another job specified by the Sequential field.

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 2. Fields of the job schedule property

Schedule field

Subfield

Value

Default

Monthly

Frequency

every_n_months (unsigned)

No default; if any Monthly subfield is specified, all must be specified.

Day

day_number | ordinal_spec day_spec

(day_number ::= 1 ... 31)

(ordinal_spec ::= First | Second | Third | Fourth | Last)

(day_spec ::= Mon | Tue | Wed | Thu | Fri | Sat |Sun | Weekday | Weekendday | Day)

Weekly

Frequency

every_n_weeks (unsigned)

No default; if any Weekly subfield is specified, all must be specified.

Days

Mon | Tue | Wed | Thu | Fri | Sat | Sun [,...]

Daily

Frequency

every_n_days (unsigned)

No default

StartDate

[d]dmonth[yy]yy

(month ::= January ... December | Jan ... Dec)

(Dates in ISO format are also accepted.)

Today

LastDate

StartDate |[d]dmonth[yy]yy

(month ::= January ... December | Jan ... Dec)

(Dates in ISO format are also accepted.)

No last date

FirstStartTime

[h]h:[m]m:[s]s (24-hour format)

Now

StartTimeRestart Frequency

[h]h:[m]m:[s]s (24-hour format)

No restart

LastStartTime

[h]h:[m]m:[s]s (24-hour format)

Midnight

Sequential

FollowsJob

job_id (unsigned) | job_name (string)

No default

Table 3 lists read-only job properties. For the LastCompletionInfo property, ExitStatus is the value returned by the wait() system call on UNIX or Linux or by the GetExitCodeProcess() function on Windows. Only the first 511 bytes of standard output and error messages are displayed.

Table 3. Read-only job properties

Property

Field

Value

Id

job_id (unsigned)

Predefined

TRUE | FALSE

Created

YYYYMMDDThh:mm:ss±hh:mm by user.group@host

LastModified

YYYYMMDDThh:mm:ss±hh:mm by user.group@host

NextRunTime

YYYYMMDDThh:mm:ss±hh:mm

RunningStatus ProcessId

process_id (unsigned)

Started

YYYYMMDDThh:mm:ss±hh:mm

LastCompletionInfo ProcessId

process_id (unsigned)

Started

YYYYMMDDThh:mm:ss±hh:mm

Ended

YYYYMMDDThh:mm:ss±hh:mm

ExitStatus

exit_status (hexadecimal)

Begin

output_and_error_messages (on subsequent lines only)

End

(None)

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: 2020-06-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: 2020-06-30T15:18:06-05 by hcl.com/root@phenol
    Job.LastModified: 2020-06-30T15:18:06-05 by hcl.com/root@phenol
    Job.Predefined: TRUE
    Job.NextRunTime: 2020-06-10T04:30:00-05
    Job.LastCompletionInfo.ProcessId: 21511
    Job.LastCompletionInfo.Started: 2020-06-09T04:30:00-05
    Job.LastCompletionInfo.Ended: 2020-06-09T04:39:27-05
    Job.LastCompletionInfo.ExitStatus: 0x100
    Job.LastCompletionInfo.Messages.Begin:
2020-06-09T04:39:26
VersionVault scrubber failed on phenol with exit status 1
Some VOBs were NOT scrubbed
See phenol:/var/adm/hcl/versionvault/log/scrubber_log
    Job.LastCompletionInfo.Messages.End:
Job.End

Task definition syntax

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:

  • Each statement must occupy a single line.
  • The language is case insensitive.
  • Leading white space, lines beginning with a number sign (#), and blank lines are ignored.
  • The quotation character is double quote (").

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:

Task.property_name: value

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 4 lists task properties.

Table 4. Task properties
Property Value

Id

task_id (unsigned; must be unique across tasks; for user-defined tasks, must be 100 or greater)

Name

name_string (quoted if it contains white space; must be unique across tasks)

Pathname

pathname_string (quoted if it contains white space)

UIInfo

info_string (private to VersionVault)

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 and Linux

versionvault-home-dir/config/scheduler/tasks

/var/adm/hcl/versionvault/scheduler/tasks

Windows

versionvault-home-dir\config\scheduler\tasks

versionvault-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 VersionVault; 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:

Task.Begin
    Task.Id:       100
    Task.Name:     "Daily Local Tasks"
    Task.Pathname: ccase_local_day.sh
Task.End

Job execution environment

Each task runs in a separate process started by the albd_server. A task has the following execution environment:

  • The user identity of the task is the same as that of the albd_server (root on UNIX or Linux; for Windows, look at the albd_server to see what user it is running as).
  • The standard input stream is closed.
  • Standard output and error messages are redirected to a file and captured by the scheduler as part of the job's LastCompletionInfo property.
  • The current directory is undefined.
  • Environment variables are those in effect for the albd_server. In addition, on Windows systems, CLEARCASEHOME is set to versionvault-home-dir.

Restrictions

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:

identity_type:identity access_type

Table 5 lists the identity types and identities allowed in ACL entries. The identity types are case insensitive.

Table 5. 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 or Linux clients of the scheduler and a Windows 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 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 6 lists the access types allowed in ACL entries. The access types are case insensitive.

Table 6. 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 domains, so a group or user in an NIS domain represents a different identity from the same group or user in a Windows 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.

In VersionVault, root (UNIX and Linux) or a member of the VersionVault administrators group (Windows) always has Full access to the scheduler on the local host (the computer where that user is logged on).

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:

Everyone: Read

These rights allow everyone to 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:

# NIS domain acme.com
Domain:acme.com Read
# Windows NT Server domain acme
Domain:acme Read
Group:acme\users Change
User:acme.com\fran Full
User:acme\fran Full
Note: On UNIX systems and Linux, an identity such as vobadm may be listed as having full access to the scheduler ACL, and yet sometimes denied access to it. This can occur because the identity exists as a local identity in /etc/passwd and as an NIS domain identity, but the computer has been configured to read the local /etc/passwd file only. In this case, /etc/nsswitch.conf shows the entry, passwd: files and you may correct the situation by editing the entry as follows: passwd: nis files. Alternatively, use a domain-wide identity: User:domainname/<userid | vobadm> Full. (To obtain the NIS domain name, use the domainname command).

Options and arguments

Specifying the host

–hos/t hostname
Specifies the host whose schedule the command operates on. The default is the local host.

Disabling prompts for confirmation

–f/orce
Suppresses all prompts to confirm changes. By default, the command asks for confirmation before changing a schedule or ACL.

Displaying information about jobs, tasks, or ACL

–get [ –sch/edule ]
Displays currently scheduled jobs using the scheduler's job definition language. For more information, see Job definition syntax. This is the default action for the –get option.
–get –job job-id-or-name
Displays the currently scheduled job identified by job-id-or-name, which is either a number representing the job ID or a string representing the job name. The job display uses the scheduler's job definition language. For more information, see Job definition syntax.
–get –tas/ks
Displays the tasks defined in the task database using the scheduler's task definition language. For more information, see Task definition syntax.
–get –acl
Displays the scheduler's access control list (ACL) using the scheduler's ACL definition language. For more information, see Restrictions.

Editing a schedule or ACL

–edi/t [ –sch/edule ]
Opens in a text editor a schedule that contains definitions of currently scheduled jobs that use the scheduler's job definition language. You can use the editor to add, delete, or modify job definitions. When you are finished, save the modified schedule and quit the text editor. The scheduler then replaces the current schedule with the edited version. For more information, see Job definition syntax. This is the default action for the –edit option.
–edi/t –acl
Opens in a text editor a file that contains the current ACL entries that use the scheduler's ACL definition language. You can use the editor to add, delete, or modify ACL entries. When you are finished, save the modified ACL and quit the text editor. The scheduler then replaces the current ACL with the edited version. For more information, see Restrictions.

Setting a schedule or ACL using definitions in a file

–set [ –sch/edule ] defn-file-pname
Replaces all currently scheduled jobs with the jobs defined in the file whose pathname is defn-file-pname. The definitions in the file use the scheduler's job definition language. For more information, see Job definition syntax. This is the default action for the –set option.
–set –acl defn-file-pname
Replaces the current ACL with the ACL defined in the file whose pathname is defn-file-pname. The definitions in the file use the scheduler's ACL definition language. For more information, see Restrictions.

Operating on a scheduled job

–del/ete job-id-or-name
Deletes the scheduled job identified by job-id-or-name, which is either a number representing the job ID or a string representing the job name.
–run job-id-or-name
Immediately executes the scheduled job identified by job-id-or-name, which is either a number representing the job ID or a string representing the job name. Dependant jobs of job-id-or-name, if any, are not run. The job is run in the scheduler's job execution environment. For more information, see Job execution environment.
–wai/t job-id-or-name
Waits for completion and displays status of the scheduled job identifiedjob-id-or-name, which is either a number representing the job ID or a string representing the job name. This option has no effect if the job is not running.
–sta/tus job-id-or-name
Displays the status of the scheduled job identified by job-id-or-name, which is either a number representing the job ID or a string representing the job name. Displays the most recent process ID, start time, end time, and exit status for the job.

Examples

The UNIX system and Linux examples in this section are written for use in csh. If you use another shell, you might 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 might 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 system and Linux shells or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

  • Display the scheduled job named "Daily VOB Pool Scrubbing".

    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: 2020-06-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: 2020-06-30T15:18:06-05 by hcl.com/root@phenol
        Job.LastModified: 2020-06-30T15:18:06-05 by hcl.com/root@phenol
        Job.Predefined: TRUE
        Job.NextRunTime: 2020-06-10T04:30:00-05
        Job.LastCompletionInfo.ProcessId: 21511
        Job.LastCompletionInfo.Started: 2020-06-09T04:30:00-05
        Job.LastCompletionInfo.Ended: 2020-06-09T04:39:27-05
        Job.LastCompletionInfo.ExitStatus: 0x100
        Job.LastCompletionInfo.Messages.Begin:
    2020-06-09T04:39:26
    VersionVault scrubber failed on phenol with exit status 1
    Some VOBs were NOT scrubbed
    See phenol:/var/adm/hcl/versionvault/log/scrubber_log
        Job.LastCompletionInfo.Messages.End:
    Job.End

  • Edit the scheduler ACL.

    cmd-context schedule –edit –acl
    Replace the ACL? [yes]

  • Set the schedule on host acme1 from job definitions in the file jobdefs.txt.

    cmd-context schedule –host acme1 –set jobdefs.txt
    Replace the entire schedule? [yes]

  • Display the status of the scheduled job with the ID 2.

    cmd-context schedule –status 2
    Job is not currently running.

        RunningJob.CompletionInfo.ProcessId: 21518
        RunningJob.CompletionInfo.Started: 2020-06-09T04:39:27-05
        RunningJob.CompletionInfo.Ended: 2020-06-09T04:40:03-05
        RunningJob.CompletionInfo.ExitStatus: 0x0

UNIX and Linux files

  • versionvault-home-dir/config/scheduler/initial_schedule
  • versionvault-home-dir/config/scheduler/tasks/templates/task_registry
  • versionvault-home-dir/config/scheduler/tasks/templates/ccase_local_day.sh
  • versionvault-home-dir/config/scheduler/tasks/templates/ccase_local_wk.sh
  • /var/adm/hcl/versionvault/scheduler/db
  • /var/adm/hcl/versionvault/scheduler/tasks/task_registry
  • /var/adm/hcl/versionvault/scheduler/tasks/ccase_local_day.sh
  • /var/adm/hcl/versionvault/scheduler/tasks/ccase_local_wk.sh

Windows files

  • versionvault-home-dir\config\scheduler\initial_schedule
  • versionvault-home-dir\config\scheduler\tasks\templates\task_registry
  • versionvault-home-dir\config\scheduler\tasks\templates\ccase_local_day.bat
  • versionvault-home-dir\config\scheduler\tasks\templates\ccase_local_wk.bat
  • versionvault-home-dir\var\scheduler\db
  • versionvault-home-dir\var\scheduler\tasks\task_registry
  • versionvault-home-dir\var\scheduler\tasks\ccase_local_day.bat
  • versionvault-home-dir\var\scheduler\tasks\ccase_local_wk.bat