CREATETIME Command

ADDRESS VOX Commands › Notification Manager Database Maintenance Commands › CREATETIME Command

CREATETIME Command

The CREATETIME command creates a new time block.

This command has the following format:

ADDRESS VOX "CREATETIME ENTITY(key or name)
   DOW(SUN|MON|...|SAT|)|BGNDATE(mm/dd)[ENDDATE(mm/dd)]
   BGNTIME(hh:mm)
   ENDTIME(hh:mm)
  {TELL(method key or name) ASK(method key or name) | FORTO(entity name or key)}
  [NAME(name)]
  [PRIORITY(n)]"

ENTITY

Specifies the key or name of the entity for this time block.

DOW

Specifies the days of the week on which this time block is active.

Days are specified as the first three characters of their English names. You can specify any number of days in any order. If you specify this operand, you cannot specify the BGNDATE and ENDDATE operands.

Separate the days of the week with spaces.

BGNDATE

Specifies the first date (no year is specified) on which this time block is active. The period is active starting on this date every year. If you specify this operand, you can specify the ENDDATE operand, but not the DOW operand.

ENDDATE

(Optional) Specifies the last date (no year is specified) on which this time block becomes active. The period becomes inactive after this date every year. If you specify this operand, you must specify the BGNDATE operand, but not the DOW operand. If not specified, the default value for ENDDATE will be the same value that is specified for BGNDATE.

BGNTIME

Specifies the time, in military time format (00:00 to 23:59), at which this time block becomes active on the specified dates or days of the week.

ENDTIME

Specifies the time, in military time format (00:00 to 23:59), at which this time block becomes inactive on the specified dates or days of the week.

Note: To have a time block active from 10:00 a.m. to 1:00 p.m., you must specify the ENDTIME as 13:00. If you specify BGNTIME(10:00) ENDTIME(12:59), the minute from 12:59 to 13:00 is not covered by the time block.

TELL

Specifies the name of the tell method to use during this time block.

If you specify this operand, you cannot specify the FORTO operand.

ASK

Specifies the name of the ask method to use during this time block. If you specify this operand, you cannot specify the FORTO operand.

FORTO

Specifies the name or key of the entity to forward to during this time block.

If you specify this operand, you cannot specify the TELL or ASK operand.

NAME

(Optional) Specifies the name to assign to this time block. Names can only contain uppercase and lowercase letters, numbers, blanks, and the following special characters: - _ @ # . $ % / ; : \

PRIORITY

(Optional) If multiple time blocks apply to a particular time of day, an algorithm is used to determine the order in which they are attempted.

This operand controls rule two of that ordering. The default ordering algorithm is as follows:

Time blocks with a BGNDATE and ENDDATE are always performed before time blocks with a DOW.
Time blocks with a higher priority are performed sooner.
If two time blocks with a BGNDATE and ENDDATE apply, then the one whose BGNDATE is closest to the current date is performed first.
If two time blocks with a DOW apply, the one whose first active day of the week is closest to the current day of the week is performed first.
If there is still a tie, the time block whose start time is closest to the current time is performed first.
If there is still a tie, the time block whose end time is closest to the current time is performed first.
If there is still a tie, the order is random/undefined.

Note: The priority operand overrides all of these rules except the first.

Return Information:

After CREATETIME executes, it sets the special REXX return code variable RC.

If the command executes successfully, the RC variable contains a value of zero. The REXX variable vox.CreateTime.NewKey contains the key of the newly created time block.
If the command does not execute successfully, the RC variable contains a nonzero value. Additionally, the VOX.ERROR variable contains the complete VOX error message, which includes the four digit return code and error message text.

Example:

The following example creates an entry in the database indicating that from 8:00 a.m. to 9:00 a.m. between the dates of 07/20 and 07/24 each year, the MyMethod method can be used to tell Joe.

ADDRESS VOX "CreateTime ENTITY(Joe) BGNDATE(07/20) ENDDATE(07/24) BGNTIME(08:00) ENDTIME(09:00) TELL(MyMethod)"