Administering the Carapace Database

script cadmin.cpl

interface Admin

COM progId Carapace.Admin

script	`cadmin.cpl`
interface	`Admin`
COM progId	`Carapace.Admin`

The Carapace Database is administered via the Admin interface.

Admin Creation

An Admin is created by using the create function eg.

    (create Admin user aud)

where user is a String name for the user and aud is an Auditor object.

Admin Methods

The Carapace database stores the following information:

audit -- timestamp records of activities performed
authentication -- information about users, passwords, roles and accessible resources
message stores -- messages stored for users or other computer systems
scheduler -- scheduled jobs run by the Carapace Hub

This Admin interface provides the administration access to all this data. The methods it offers can be grouped as follows:

audit contents audit contents administration

audit types audit type administration

extensions administration of the audit extensions

object extensions administration of the audit object extensions

error classes error class administration

activities activity administration

user user administration

addresses address administration

roles role administration

resources resource administration

mail domains mail domain administration

message store message store administration

MTA queues queues to remote MTAs

scheduler scheduled jobs -- what the job entails and the times it is to be run

Audit Contents Administration

This set of methods administer the data held within the audit.

purgeAudit purge the audit contents

`purgeAudit`

Durge the audit contents -- all records are purged up until the supplied time. The different types of audit can be purged separately since the audit type is an argument to this function.

To purge all audit records, use an auditType of ALL.

Arguments:

auditType String

time String

Return type: the empty List

Audit Type Administration

The audit holds different types of information -- these methods administer the types held.

createType create a new audit type

types list the audit types

typesTbl list the audit types and their descriptions

deleteType delete the supplied audit type

`createType`

Create a new audit type.

Arguments:

type String

description String

extension String

(optional) objectType String

Return type: the empty List

`types`

List the audit types.

Arguments: none

Return type: the empty List

`typesTbl`

List the audit types, their descriptions, extension table and (if present) object type.

Arguments: none

Return type: the empty List

`deleteType`

Delete the supplied audit type.

Arguments:

type String

Return type: the empty List

Audit Extension Administration

The audit can be extended to hold additional activity information -- these methods deal with these audit extensions.

createExtension create an extension for the Carapace audit

extensions list the configured extensions to the audit

extensionsTbl list each extension table and its database alias

deleteExtension delete an audit extension

`createExtension`

Create an extension for the Carapace audit. The name of the extension is the name of the database table which holds the information. The alias is a unique alias within the database for that table.

Arguments:

extensionName String

alias String

description String

definition List

columnInfo List

The definition is a list of SQL statements (maybe only one) including the CREATE TABLE statement for the database table. Other statements may create the appropriate indexes etc.

The columnInfo argument is a list of column-definition lists. Each column-definition list is formed from the following Strings as follows:

heading name of the heading for this column

columnName actual name of the column within the extension table

columnDataType data type for the column -- values are:

integer
string
real
binary
enum

columnInfo information for the column depending on the columnDataType -- for enum columns, this is a select statement which returns the list of values allowed for the column

canFilter determines whether this column can be used for filtering -- values are Y or N

chooseByDefault determines whether this column is selected by setting up the filter -- values are Y or N

Return type: the empty List

`extensions`

List the configured extensions to the audit.

Arguments: none

Return type: List

`extensionsTbl`

List each extension table and its database alias.

Arguments: none

Return type: List

`deleteExtension`

Delete an audit extension.

Arguments:

extensionName String

Return type: the empty List

Audit Object Extension Administration

The audit can hold information about arbitrary kinds of object. These methods allow such object extensions to be administered.

createObjectExtension create a new object extension

objectExtensions list the object extensions

objectExtensionTbl list the object extensions and all their details

deleteObjectExtension delete the supplied object extension

`createObjectExtension`

Create a new object extension.

Arguments:

objectType String

package String

storageClass String

filterClass String

adminClass String

Return type: the empty List

`objectExtensions`

List the object extensions.

Arguments: none

Return type: the empty List

`objectExtensionTbl`

List the object extensions and all their details.

Arguments: none

Return type: the empty List

`deleteObjectExtension`

Delete delete the supplied object extension.

Arguments:

type String

Return type: the empty List

Error Class Administration

Activities can fail so the audit holds error information for all failed activities. Errors are grouped into classes -- for example there is a Comms class of errors for communications. These methods allow the error class information to be administered.

createErrorClass create a new error class

errorClasses list the set of error classes ie. each error class and its corresponding mnemonic

errorClassesTbl list each error class, mnemonic and description

deleteErrorClass delete the supplied error class

`createErrorClass`

Create a new error class. Error classes below 100 are reserved.

Arguments:

class Integer

mnemonic String

description String

Return type: the empty List

`errorClasses`

List the set of error classes ie. each error class and its corresponding mnemonic.

Arguments: none

Return type: List

`errorClassesTbl`

List each error class, mnemonic and description.

Arguments: none

Return type: List

`deleteErrorClass`

Delete the supplied error class.

Arguments:

class Integer

Return type: the empty List

Address Administration

A user or computer system can be identified in many different ways. Carapace allows different types of address to be stored so that users can be identified correctly. These methods allow the types of address to be administered.

addAddressType create a new type of address

addressTypes list the available address types

addressTypesTbl list the available address types along with their descriptions

deleteAddressType delete the supplied address type

`addAddressType`

Create a new type of address.

Arguments:

addressType String

description String

Return type: the empty List

`addressTypes`

List the available address types.

Arguments: none

Return type: List

`addressTypesTbl`

List the available address types and their descriptions.

Arguments: none

Return type: List

`deleteAddressType`

Delete the supplied address type.

Arguments:

addressType String

Return type: the empty List

Activity Administration

Each type of audit holds information about activities performed. These methods allow the list of allowed activities to be administered for a given audit type.

createActivity create a new activity for the given audit type

activities list the activities for the supplied audit type

activitiesTbl list the activities and their descriptions

deleteActivity delete the activity for the given audit type

`createActivity`

Create a new activity for the given audit type.

Arguments:

auditType String

activity String

description String

Return type: the empty List

`activities`

List the activities for the supplied audit type.

Arguments: none

Return type: List

`activitiesTbl`

List the activities and their descriptions.

Arguments: none

Return type: List

`deleteActivity`

Delete the activity for the given audit type.

Arguments:

auditType String

activity String

Return type: List

User Administration

Various information about users of the system is required -- these methods allow the user information to be administered.

createUser create a new user

users list the user ids within the database

deleteUser delete the identified user

addUserRole grant the role to the supplied user

userRoles list the roles for the user

userRolesTbl list the roles which are granted to the user and their descriptions

deleteUserRole delete the role from the supplied user

addUserAddress add an address for the supplied user

userAddresses list all the addresses of a given type for the user

userAddressTbl list all the addresses for the user

deleteUserAddress remove the address from the supplied user

findUsers list all users having the supplied address

checkPassword check the password for the supplied user

setPassword set the password for the supplied user

setPasswordValidity set the date & time the user's password becomes valid

setPasswordExpiry set the date & time the user's password expires

updateUser update the user details

userExists test if the supplied user exists

userDetails list the user details

`createUser`

Create a new user. All other details are set for the user using the methods updateUser, setPassword, addUserRole.

Arguments:

userId String

Return type: the empty List

`users`

List the user ids within the database.

Arguments: none

Return type: List

`deleteUser`

Create a new activity for the given audit type.

Arguments:

userId String

Return type: the empty List

`addUserRole`

Grant the role to the supplied user.

Arguments:

userId String

role String

Return type: the empty List

`userRoles`

List the roles for the user.

Arguments:

userId String

Return type: List

`userRolesTbl`

List the roles which are granted to the user and their descriptions.

Arguments:

userId String

Return type: the empty List

`deleteUserRole`

Delete the role from the supplied user.

Arguments:

userId String

role String

Return type: the empty List

`addUserAddress`

Add an address for the supplied user.

Arguments:

userId String

addressType String

address String

Return type: the empty List

`userAddresses`

List all the addresses of a given type for the user.

Arguments:

userId String

addressType String

Return type: List

`userAddressTbl`

List all the addresses for the user. A list of (addressType, address) pairs is returned.

Arguments:

userId String

Return type: the empty List

`deleteUserAddress`

Delete the address from the supplied user.

Arguments:

userId String

addressType String

address String

Return type: the empty List

`findUsers`

List all users having the supplied address. A list of userId Strings is returned.

Arguments:

addressType String

address String

Return type: List

`checkPassword`

Check the password for the supplied user.

Arguments:

userId String

password String

Return type: the empty List is returned if the password does not match.

`setPassword`

Set the password for the supplied user.

Arguments:

userId String

password String

expiry String

Return type: the empty List

`setPasswordValidity`

Set the date & time the user's password becomes valid.

Arguments:

userId String

validity String

Return type: the empty List

`setPasswordExpiry`

Set the date & time the user's password expires.

Arguments:

userId String

expiry String

Return type: the empty List

`updateUser`

Update the user details. The supplied newAttributes is a list of attribute/value pairs.

Arguments:

userId String

newAttributes List

Return type: the empty List

`userExists`

Tests if the supplied user exists.

Arguments:

userId String

Return type: Object -- or the empty list if no such user.

`userDetails`

List the user details. The list of attributes required is supplied. The list of attribute/value pairs is returned.

Note: if no attributes are supplied, this is taken to mean all attributes are required.

Arguments:

userId String

attributes List

Return type: List

Role Administration

A user can adopt a particular role when accessing the system. These methods allow the list of available roles to be administered along with the resources which are accessible to each role.

createRole create a new role

roles list the roles within the database

rolesTbl list each role and its description

deleteRole delete the identified role

addRoleResource add the resource to the supplied role

roleResources list the roles for the given resource

roleResourcesTbl list the resources which are available to the given role and their descriptions

deleteRoleResource delete the resource from the supplied role

`createRole`

Create a new role.

Arguments:

role String

description String

Return type: the empty List

`roles`

List the roles within the database.

Arguments: none

Return type: List

`rolesTbl`

List each role and its description.

Arguments: none

Return type: List

`deleteRole`

Delete the identified role.

Arguments:

role String

Return type: the empty List

`addRoleResource`

Add the resource to the supplied role.

Arguments:

role String

resource String

Return type: the empty List

`roleResources`

List the roles for the given resource.

Arguments:

role String

Return type: List

`roleResourcesTbl`

List the resources which are available to the given role and their descriptions.

Arguments:

role String

Return type: List

`deleteRoleResource`

Delete the resource from the supplied role.

Arguments:

role String

resource String

Return type: the empty List

Resource Administration

Resources are attached to each role. These methods allow the set of resources to be administered.

createResource create a new resource

resources list the resources

resourcesTbl list the roles and their description

deleteResource delete the identified resource

`createResource`

Create a new resource.

Arguments:

resource String

Return type: the empty List

`resources`

List the resources.

Arguments: none

Return type: List

`resourcesTbl`

List the roles and their description.

Arguments: none

Return type: List

`deleteResource`

Delete the identified resource.

Arguments:

resource String

Return type: the empty List

Mail Domain Administration

Mail is organised into domains -- a domain defines a set of addresses e.g. a company or even an entire country could form one domain. These methods allow the list of mail domains within Carapace to be adminstered.

getDomain extract the mail domain in standard format from the supplied address

inLocalDomain determine if the supplied address is local

addLocalDomain add a local mail domain -- so that message stores can be configured to hold mail for users within this domain

localDomains list the local mail domains

deleteLocalDomain delete the local mail domain

`getDomain`

Extract the mail domain in standard format from the supplied address.

Arguments:

addressType String

address String

Return type: String

`inLocalDomain`

Determine if the supplied address is local.

Arguments:

addressType String

address String

Return type: String or, if not local, the empty List

`addLocalDomain`

Add a local mail domain -- so that message stores can be configured to hold mail for users within this domain.

Arguments:

domainName String

Return type: the empty List

`localDomains`

List the local mail domains.

Arguments: none

Return type: List

`deleteLocalDomain`

Delete the supplied local mail domain.

Arguments:

domain String

Return type: the empty List

Message Store Administration

Messages for users are held within message stores. These methods allow administration of the Carapace message stores.

isMSUser determine if the supplied user has a message store

createMS create a message store for the supplied user

createMSHandler create a message store handler

unlockMS unlock the message store for the supplied user

deleteMS delete the message store for the supplied user

summariseMSContents summarise the contents of the message stores

listMSUsers list those users which have a message store

`isMSUser`

Determine if the supplied user has a message store.

Arguments:

userId String

Return type: Object

`createMS`

Create a message store for the supplied user.

Arguments:

userId String

Return type: the empty List

`createMSHandler`

Create a message store handler.

Arguments:

userId String

pkgName String

handlerClass String

Return type: the empty List

`unlockMS`

Unlock the message store for the supplied user. A message store is locked when it is accessed by a user. If for some untoward reason (eg. power failure) the message store remains marked as locked when no user is active, this function simply marks the message store as available.

Arguments:

userId String

Return type: the empty List

`deleteMS`

Delete the message store for the supplied user.

Arguments:

userId String

Return type: the empty List

`summariseMSContents`

Summarise the contents of the message stores. A list of rows is returned where each row is a List of the following data for a user:

userId -- String
message store id -- Integer
no. of stored messages -- Integer
total length of all stored messages -- Integer
timestamp of the oldest message stored -- String
timestamp of the most recent message stored -- String

Arguments: none

Return type: List

`listMSUsers`

List those users which have a message store. A list of userId strings is returned.

Arguments: none

Return type: List

MTA Queue Administration

Messages destined for domains not held within Carapace are queued for transfer to the appropriate domain. These methods adminster the queues for the Carapace Message Transfer Agents (MTAs).

mtaQueueTbl list the table of defined MTA queues

mtaQueues list the queues for the supplied MTA

createMtaQueue create a message queue to a remote MTA

updateMtaQueue update the details about a queue to a remote MTA

deleteMtaQueue delete a message queue to a remote MTA

expireMtaMessage expire a message queued for a remote MTA

`mtaQueueTbl`

List the table of defined MTA queues. The returned information contains a list for each queue with the following:

queue identifier
remote MTA name
address type for messages to this MTA
retry interval (minutes) for retrying connections to this MTA
warn interval (minutes) -- time when warnings are sent if this MTA cannot be contacted
expiry interval (minutes) -- time when messages are purged from the queue if this MTA cannot be contacted

Arguments: none

Return type: List

`mtaQueues`

List the queues for the supplied MTA. If the supplied MTA name is the empty string then a list of all queues for all MTAs is returned.

Arguments:

mtaName String

Return type: List

`createMtaQueue`

Create a message queue to a remote MTA.

Arguments:

queueId String

remoteMTA String

addressType String

retryInterval integer

warnInterval integer

expiryInterval integer

Return type: the empty List

`updateMtaQueue`

Update a message queue to a remote MTA. The supplied attribute-value list of details contains one or more of the following keys:

qId the queue identifier

remoteMTA the name of the MTA

addrType the type of addressing for this MTA

retryInterval the interval between connection attempts

warnInterval the interval when warnings are generated about connection failures

expiryInterval the interval after which messages in the queue are expired

Arguments:

queueId String

details List

Return type: the empty List

`deleteMtaQueue`

Delete a message queue to a remote MTA.

Arguments:

queueId String

Return type: the empty List

`expireMtaMessage`

Expire a message queued for a remote MTA.

Arguments:

msgId String

Return type: the empty List

Scheduler Administration

Within the Carapace Hub jobs can be configured and scheduled to run at various dates and times. The following set of methods deal with scheduler configuration.

createJob create a job which can be scheduled

modifyJob modify a job which can be scheduled

deleteJob delete a job so that it can no longer be scheduled

activateJob mark a job so that it is included in each day's schedule as defined by its times to run

deactivateJob mark a job so that it is never included in a day's schedule regardless of the times configured for it to run

jobsTbl return a list summarising all configured jobs

jobs list the names of all configured jobs

activeJobs list the names of all active configured jobs

inactiveJobs list the names of all inactive configured jobs

getJob get the definition of a job from the database

jobStatuses list the possible status values for a job

buildSchedule build the schedule for the given day within the database

clearSchedule clear the schedule for the given day and all preceding days from the database

getSchedule return the schedule for the given day -- this does not set up the job schedule within the database

newJobs return a list (... (name startTime) ...) for all new jobs active and status = scheduled up to the current time. The status for all returned jobs is set to 'pending'.

expireJobs expire all non-completed jobs before the supplied time

setJobStatus set the status for the supplied job

`createJob`

Create a job which can be scheduled.

Arguments:

name String

description String

package String

className String

method String

args List

spec List

Return type: the empty List

`modifyJob`

Modify a job which can be scheduled. The attribute argument must be one of the following:

description
specification
pkgName
pkgName
handlerClass
methodName
args

The values for all the above attributes are Strings apart from args and specification where the value must be a List.

Arguments:

name String

attribute String

value Object

Return type: the empty List

`deleteJob`

Delete a job so that it can no longer be scheduled.

Arguments:

name String

Return type: the empty List

`activateJob`

Mark a job so that it is included in each day's schedule as defined by its times to run.

Arguments:

name String

timeNow Integer

Return type: the empty List

`deactivateJob`

Mark a job so that it is never included in a day's schedule regardless of the times configured for it to run.

Arguments:

name String

Return type: the empty List

`jobsTbl`

Return a list summarising all configured jobs. Every entry in the returned List is itself a list of the following items:

name
description
package name
class name
method name
args -- encoded as a String

Arguments: none

Return type: List

`jobs`

List the names of all configured jobs.

Arguments: none

Return type: List

`activeJobs`

List the names of all active configured jobs.

Arguments: none

Return type: the empty List

`inactiveJobs`

List the names of all inactive configured jobs.

Arguments: none

Return type: the empty List

`getJob`

Get the definition of a job from the database.

Arguments:

name String

Return type: JobSchedule

`jobStatuses`

List the possible status values for a job. A List of Strings is returned.

Arguments: none

Return type: List

`buildSchedule`

Build the schedule for the given day within the database. The supplied argument is the time in the epoch identifying the day for which the schedule is required.

Arguments:

today Integer

Return type: the empty List

`clearSchedule`

Clear the schedule for the given day and all preceding days from the database. The supplied argument is the time in the epoch identifying the day for which the schedule is to be cleared.

Arguments:

today Integer

Return type: the empty List

`getSchedule`

Return the schedule for the given day -- this does not set up the job schedule within the database. The supplied argument is the time in the epoch identifying the day for which the schedule is required.

Each entry in the returned List is itself a list of the following items:

time (in seconds from the epoch) when the job is scheduled to run
name of the job
description of the job

Arguments:

today Integer

Return type: List

`newJobs`

Return a list (... (name startTime) ...) for all new jobs active and status = scheduled up to the current time. The status for all returned jobs is set to 'pending'.

The returned start times are in minutes from midnight.

Arguments:

toTime Integer

Return type: List

`expireJobs`

Expire all non-completed jobs before the supplied time.

Arguments:

thresholdTime Integer

Return type: the empty List

`setJobStatus`

Set the status for the supplied job. The supplied startTime is supplied as minutes from midnight.

Arguments:

name String

startTime Integer

newStatus String

Return type: the empty List

Contents Index Current topic: audit Related topics: databases

`audit contents`	audit contents administration
`audit types`	audit type administration
`extensions`	administration of the audit extensions
`object extensions`	administration of the audit object extensions
`error classes`	error class administration
`activities`	activity administration
`user`	user administration
`addresses`	address administration
`roles`	role administration
`resources`	resource administration
`mail domains`	mail domain administration
`message store`	message store administration
`MTA queues`	queues to remote MTAs
`scheduler`	scheduled jobs -- what the job entails and the times it is to be run

`createType`	create a new audit type
`types`	list the audit types
`typesTbl`	list the audit types and their descriptions
`deleteType`	delete the supplied audit type

type	`String`
description	`String`
extension	`String`
(optional) objectType	`String`

`createExtension`	create an extension for the Carapace audit
`extensions`	list the configured extensions to the audit
`extensionsTbl`	list each extension table and its database alias
`deleteExtension`	delete an audit extension

extensionName	`String`
alias	`String`
description	`String`
definition	`List`
columnInfo	`List`

heading	name of the heading for this column
columnName	actual name of the column within the extension table
columnDataType	data type for the column -- values are: `integer` `string` `real` `binary` `enum`
columnInfo	information for the column depending on the `columnDataType` -- for `enum` columns, this is a `select` statement which returns the list of values allowed for the column
canFilter	determines whether this column can be used for filtering -- values are `Y` or `N`
chooseByDefault	determines whether this column is selected by setting up the filter -- values are `Y` or `N`

`createObjectExtension`	create a new object extension
`objectExtensions`	list the object extensions
`objectExtensionTbl`	list the object extensions and all their details
`deleteObjectExtension`	delete the supplied object extension

objectType	`String`
package	`String`
storageClass	`String`
filterClass	`String`
adminClass	`String`

`createErrorClass`	create a new error class
`errorClasses`	list the set of error classes ie. each error class and its corresponding mnemonic
`errorClassesTbl`	list each error class, mnemonic and description
`deleteErrorClass`	delete the supplied error class

`addAddressType`	create a new type of address
`addressTypes`	list the available address types
`addressTypesTbl`	list the available address types along with their descriptions
`deleteAddressType`	delete the supplied address type

`createActivity`	create a new activity for the given audit type
`activities`	list the activities for the supplied audit type
`activitiesTbl`	list the activities and their descriptions
`deleteActivity`	delete the activity for the given audit type

`createUser`	create a new user
`users`	list the user ids within the database
`deleteUser`	delete the identified user
`addUserRole`	grant the role to the supplied user
`userRoles`	list the roles for the user
`userRolesTbl`	list the roles which are granted to the user and their descriptions
`deleteUserRole`	delete the role from the supplied user
`addUserAddress`	add an address for the supplied user
`userAddresses`	list all the addresses of a given type for the user
`userAddressTbl`	list all the addresses for the user
`deleteUserAddress`	remove the address from the supplied user
`findUsers`	list all users having the supplied address
`checkPassword`	check the password for the supplied user
`setPassword`	set the password for the supplied user
`setPasswordValidity`	set the date & time the user's password becomes valid
`setPasswordExpiry`	set the date & time the user's password expires
`updateUser`	update the user details
`userExists`	test if the supplied user exists
`userDetails`	list the user details

`createRole`	create a new role
`roles`	list the roles within the database
`rolesTbl`	list each role and its description
`deleteRole`	delete the identified role
`addRoleResource`	add the resource to the supplied role
`roleResources`	list the roles for the given resource
`roleResourcesTbl`	list the resources which are available to the given role and their descriptions
`deleteRoleResource`	delete the resource from the supplied role

`createResource`	create a new resource
`resources`	list the resources
`resourcesTbl`	list the roles and their description
`deleteResource`	delete the identified resource

`getDomain`	extract the mail domain in standard format from the supplied address
`inLocalDomain`	determine if the supplied address is local
`addLocalDomain`	add a local mail domain -- so that message stores can be configured to hold mail for users within this domain
`localDomains`	list the local mail domains
`deleteLocalDomain`	delete the local mail domain

`isMSUser`	determine if the supplied user has a message store
`createMS`	create a message store for the supplied user
`createMSHandler`	create a message store handler
`unlockMS`	unlock the message store for the supplied user
`deleteMS`	delete the message store for the supplied user
`summariseMSContents`	summarise the contents of the message stores
`listMSUsers`	list those users which have a message store

`mtaQueueTbl`	list the table of defined MTA queues
`mtaQueues`	list the queues for the supplied MTA
`createMtaQueue`	create a message queue to a remote MTA
`updateMtaQueue`	update the details about a queue to a remote MTA
`deleteMtaQueue`	delete a message queue to a remote MTA
`expireMtaMessage`	expire a message queued for a remote MTA

queueId	`String`
remoteMTA	`String`
addressType	`String`
retryInterval	`integer`
warnInterval	`integer`
expiryInterval	`integer`

`qId`	the queue identifier
`remoteMTA`	the name of the MTA
`addrType`	the type of addressing for this MTA
`retryInterval`	the interval between connection attempts
`warnInterval`	the interval when warnings are generated about connection failures
`expiryInterval`	the interval after which messages in the queue are expired

`createJob`	create a job which can be scheduled
`modifyJob`	modify a job which can be scheduled
`deleteJob`	delete a job so that it can no longer be scheduled
`activateJob`	mark a job so that it is included in each day's schedule as defined by its times to run
`deactivateJob`	mark a job so that it is never included in a day's schedule regardless of the times configured for it to run
`jobsTbl`	return a list summarising all configured jobs
`jobs`	list the names of all configured jobs
`activeJobs`	list the names of all active configured jobs
`inactiveJobs`	list the names of all inactive configured jobs
`getJob`	get the definition of a job from the database
`jobStatuses`	list the possible status values for a job
`buildSchedule`	build the schedule for the given day within the database
`clearSchedule`	clear the schedule for the given day and all preceding days from the database
`getSchedule`	return the schedule for the given day -- this does not set up the job schedule within the database
`newJobs`	return a list `(... (name startTime) ...)` for all new jobs active and status = scheduled up to the current time. The status for all returned jobs is set to 'pending'.
`expireJobs`	expire all non-completed jobs before the supplied time
`setJobStatus`	set the status for the supplied job