Creates a schedule definition and stores it in the transfer
database. The schedule definition specifies when and how often
a transfer should execute. A transfer can have only one schedule
definition associated with it. Replication Option returns an
error if you attempt to define a schedule for a transfer that
already has one.
1 – Format
(B)0[mD[4mEFINE[m [4mSCHEDULE[m qq> FOR qq> transfer-name qqqk
lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqj
mqqqwqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqwqk
mqq> [4mSTART[m qq> start-date-time qqqj x
lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqj
mqqqwqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqwqk
mqq> [4mEVERY[m qqwq> every-delta-time qqqqqwqqj x
mq> every-absolute-time qqj x
lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqj
mqwqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqwqk
mq> [4mRETRY[m q> count q> [4mTIMES[m qwqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqwj x
mq> [4mRETRY[m [4mEVERY[m qq> delta-time qj x
lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqj
mqq> [4mEND[m qwqqqqqqqqqqqqqqqqqqqwqwqqqqqqqqqqqqqwqqq> .
mqq> transfer-name qj mq> SCHEDULE qj
1.1 – transfer-name
The transfer for which this schedule is being defined. The
transfer must already exist when you create a schedule definition
for it. The transfer-name parameter is required.
1.2 – start-date-time
The time to execute the initial transfer. You can specify an
absolute or delta time. If you supply an absolute time, the
initial transfer will be executed at the time specified. If you
use a delta time, Replication Option uses the current time and
the delta-time value to calculate the actual transfer time. The
START clause is optional. If you do not include a START clause,
the start time is set to the current time so that the transfer
will execute as soon as the transfer schedule definition is
processed.
The start-date-time parameter uses the following absolute and
delta-time formats. You can omit any of the trailing fields in
the date or time. You can omit any of the fields in the middle
of the format as long as you include the punctuation marks. For
more information on date and time formats, see the entry on the
$BINTIM OpenVMS system service in the OpenVMS documentation set.
Absolute-time
dd-mmm-yyyy hh:mm:ss.cc
Delta time
dddd:hh:mm:ss.cc
In the absolute and delta time designations, the abbreviations
have the following meanings:
dddd Number of days
dd Day of the month
mmm Month
yyyy Year
hh Hours
mm Minutes
ss Seconds
cc Hundredths of a second
1.3 – every-delta-time
Used to calculate the time to execute the next transfer. The
EVERY clause is optional. If you specify the EVERY clause, you
must specify either every-delta-time or every-absolute-time. If
you omit the EVERY clause, the transfer occurs only once.
The valid specification for every-delta-time is the delta format
used by the $BINTIM OpenVMS system service. The delta time you
specify is the time from the completion of the last transfer
sequence until the start of the next one. A transfer sequence
is the set of transfers from the first attempt until one of the
following conditions is met: the execution is successful, the
maximum number of retries specified in the RETRY clause has been
reached, or a fatal error has occurred (one for which retries are
not attempted).
1.4 – every-absolute-time
(B)0[mevery-absolute-time =
qqqqqwqqqqqq> [4mDAY[m qqqqqqwqqwqqqqqqqqqqq>qqqqqqqqqwqwqqq>
tqqqqqq> [4mWEEK[m qqqqqu mqq> [4mAT[m qq> at-time qqj x
tqqqqqq> [4mMONTH[m qqqqj x
mqqwqqq> weekday qqqwqqqqqqqqqq>qqqqqqqqwqqwqqj
x mq> [4mAT[m qq>at-time qqj x
mqqqqqqqqqqqqqqqq , <qqqqqqqqqqqqqqqqqqqj
Used to calculate the time to execute the next transfer. The
EVERY clause is optional. If you specify the EVERY clause, you
must specify either every-absolute-time or every-delta-time. If
you omit the EVERY clause, the transfer occurs only once.
1.4.1 – DAY
The transfer executes on a daily basis.
1.4.2 – WEEK
The transfer occurs every week on the same day of the week as the
initial transfer.
1.4.3 – MONTH
The transfer occurs on a monthly cycle on the same day of the
month as the initial transfer.
Note that if the initial transfer starts on the 31st of the
month and the transfer schedule specifies EVERY MONTH, the
next execution of the transfer will be on the last day of the
following month, whether the last day is the 28th, 29th, 30th, or
31st.
1.4.4 – weekday
The transfer executes on the weekdays that you list. If you
list more than one weekday, separate the days with commas. Valid
weekday specifications are:
SUNDAY
MONDAY
TUESDAY
WEDNESDAY
THURSDAY
FRIDAY
SATURDAY
1.4.5 – at-time
Qualifies every-absolute-time by specifying the time of day at
which the transfer should occur. This parameter is optional.
If you specify DAY, WEEK, or MONTH, but do not specify an at-
time, Replication Option uses the time of day of the initial
transfer. In the case of a list of weekdays, the at-time for
each day can be specified. If the at-time for any weekday is not
specified, the default is the time used for the previous entry in
the list. For the first entry in the list, the time of day of the
initial transfer is used, if none is specified.
1.5 – count
The maximum number of times to retry a transfer if a transfer
execution fails. If you do not include a retry count or if the
count value is set to zero, Replication Option does not attempt
to retry the transfer until the next scheduled transfer time as
indicated by the EVERY clause.
Replication Option does not retry a transfer if the transfer
failed as a result of a fatal error. You can recover from a fatal
error only by manual intervention.
1.6 – delta-time
The length of time Replication Option waits between the time of
the last failed attempt and the time of the next retry attempt.
The RETRY EVERY delta-time clause is optional and can only be
specified if the RETRY count TIMES clause is included.
If you specify RETRY count TIMES in the schedule definition,
but do not specify RETRY EVERY delta-time, Replication Option
attempts the retry immediately. See the description of the start-
date-time parameter earlier in this section for valid delta-time
values.
2 – More
To define a transfer schedule, you must have the same user
identification code (UIC) as the user who defined the transfer,
or have the ALTER transfer privilege or the OpenVMS BYPASS
privilege. If you try to define a transfer schedule for a
transfer defined by a user with a different UIC, and you do
not have the appropriate access right or privilege, Replication
Option returns an error message and prevents the schedule
from executing. If you have BYPASS privilege and define a
schedule for a transfer associated with a different UIC, the
UIC associated with the transfer does not change.
When you define a schedule for a transfer in the unscheduled
state, that transfer is placed in the scheduled state. If the
transfer is in the suspended state, it remains in the suspended
state. To place the suspended transfer in the scheduled state,
use the START TRANSFER statement. When the transfer executes,
Replication Option places the transfer in the active state.
You cannot modify a schedule definition using RDO. If you need to
change a parameter value in a schedule definition, you must first
delete the schedule using the DELETE SCHEDULE statement and then
define a new schedule, or, use the SQL ALTER SCHEDULE statement.
When you define a one-time-only transfer schedule and specify
a transfer time that has already passed, issuing a START
TRANSFER statement changes the transfer status from suspended
to scheduled. However, when you issue a SHOW TRANSFER STATUS
statement, the "next transfer to be executed" phrase is not
included. To avoid this problem and cause the transfer to
execute, use the START TRANSFER NOW statement.
You must execute the DEFINE SCHEDULE statement outside of the
scope of a transaction. If you issue this statement when a
transaction is outstanding, Replication Option returns an error
message.
You can change the default date/time format that was established
before VMS Version 5.0 to a date/time format that complies with
the LIB$ international date and time formatting routines of VMS
Version 5.0 and higher. For example, you might want to change the
input format from 1-APR-1989 to one that allows entry of dates in
the form April 1, 1989. You can change the output format as well.
To change the input date/time format, define the LIB$DT_INPUT_
FORMAT logical name as discussed in the OpenVMS RTL Library (LIB$)
documentation. To change the output date/time format, define the
logical name LIB$DT_FORMAT. If you change the date/time format from
the one used prior to VMS Version 5.0, then you must place the date
and time in quotation marks. If you continue to use the date
/time format in effect before VMS Version 5.0, you can enter the
date and time with or without quotation marks as you wish. ,b
For further information about the date/time routines provided by
the OpenVMS Run-Time Library, refer to the OpenVMS RTL Library
(LIB$) documentation. Refer also to the Oracle Rdb documentation
set for details specific to that product's use of international
date/time formats.
Replication Option does not guarantee the reexecution of
a transfer at the specified rate. If the copy process is
tied up for any reason and cannot finish its task before the
next transfer repetition cycle, the copy process ignores the
repetition. The cycle is reset to the next expected transfer
time.
A replication transfer with a schedule that runs on an infrequent
basis can consume a considerable amount of disk space in the
source database. For example, if a replication transfer is
scheduled to occur once a month, any new or changed records
to be transferred are duplicated in the relation RDB$CHANGES
in the source database and are retained for the remainder of
the month until the schedule starts the transfer. This space is
released only after the duplicate records have been transferred
and erased. Thus, for the entire month that the duplication
records are stored, they take up disk space. In general, you
should not choose an infrequent transfer cycle if the number of
daily changes to the source database is high.
In addition, even if this monthly replication transfers only a
single record each month, another problem can arise if other
replication transfers use the same source database. Although
those transfers might execute more frequently than once a month,
their records are not necessarily erased from the RDB$CHANGES
relation right away. Replication Option erases the records only
if no records entered earlier are waiting to be transferred.
3 – Examples
Example 1
Executes the NH_EMPLOYEES transfer at 1:24 a.m. on June 24,
1988. The transfer will then execute every day at 5:30 p.m.
If a nonfatal error occurs, the transfer execution will be
retried three times with 30 minutes between the end of the failed
transfer execution and the start of the next one.
RDO> DEFINE SCHEDULE FOR NH_EMPLOYEES
cont> START 24-JUN-1988 01:24:00.00 <---- Absolute time
cont> EVERY DAY AT 17:30 <---- Absolute time
cont> RETRY 3 TIMES
cont> RETRY EVERY 0 00:30:00
cont> END SCHEDULE.
Example 2
This example uses a delta-time specification to have 36 hours
(1 day plus 12 hours) between the completion of one transfer
execution and the beginning of the next. The example uses two
delta times, EVERY 1 12:00 and RETRY EVERY 0 03:00:00. EVERY 1
12:00 states that there will be 36 hours (1 day plus 12 hours)
between the completion of the first transfer and the beginning
of the next. If transfer execution does not succeed on the first
attempt, the transfer schedule permits Replication Option to
make up to five additional attempts to complete the transfer.
RETRY EVERY 0 03:00:00 means Replication Option should retry
the transfer three hours after a nonfatal failure until the
transfer completes successfully or until the maximum of five
retries has been attempted. If the transfer does not complete
successfully after five retries, the next attempt will be 36
hours after the last failed attempt.
RDO> DEFINE SCHEDULE FOR NH_EMPLOYEES
cont> START 15-MAY-1988
cont> EVERY 1 12:00 !<---- 1 day plus 12 hours
cont> RETRY 5 TIMES
cont> RETRY EVERY 0 03:00:00 !<---- 3 hours
cont> END.
Example 3
The following transfer schedule causes Replication Option
to execute a transfer for the first time at 12 noon on the
15th of October 1988. Subsequent transfers will occur every
day thereafter at 5:30 p.m. If an error occurs preventing a
successful transfer, Replication Option will retry every 30
minutes until the transfer is successful or the maximum of three
retries has been reached.
RDO> DEFINE SCHEDULE FOR NH_EMPLOYEES
cont> START 15-OCT-1988 12:00
cont> EVERY DAY AT 17:30 !<---- Every day
cont> RETRY 3 TIMES
cont> RETRY EVERY 0 00:30:00
cont> END SCHEDULE.
Example 4
The following schedule definition assumes that you want to
execute the transfer immediately after you complete the schedule
definition and, therefore, it contains no START clause. If
the system time is 20-OCT-1988 16:00:00 when you complete the
DEFINE SCHEDULE statement, the next execution of the NH_EMPLOYEES
transfer will start on 20-NOV-1988 16:00:00.
RDO> DEFINE SCHEDULE FOR NH_EMPLOYEES
cont> EVERY MONTH
cont> RETRY 3 TIMES
cont> RETRY EVERY 0 00:30:00
cont> END.
Example 5
This example calls for the NH_EMPLOYEES transfer to execute at
3:00 p.m. every Wednesday. The schedule definition calls for a
maximum of three retries occurring at intervals of 30 minutes.
RDO> DEFINE SCHEDULE FOR NH_EMPLOYEES
cont> START 12-NOV-1988 15:00:00.00
cont> EVERY WEDNESDAY AT 15:00:00 !<---- Wednesdays at 3 p.m.
cont> RETRY 3 TIMES
cont> RETRY EVERY 0 00:30:00
cont> END.
Example 6
The following example causes an initial transfer to execute on
the 15th of July at 5 p.m., on every Monday after the 15th at
5 p.m., every Tuesday at 11 a.m., and every Friday at 11 a.m.
Because a RETRY clause is not specified, even if a nonfatal
failure occurs, the transfer will not execute until the next
regularly scheduled time.
RDO> DEFINE SCHEDULE FOR NH_EMPLOYEES
cont> START 15-JUL-1988 17:00
cont> EVERY MONDAY, TUESDAY AT 11:00, FRIDAY
cont> END.
Example 7
This example causes a transfer to start at midnight on July 15th
and on the 15th of every month thereafter at 7 p.m.
RDO> DEFINE SCHEDULE FOR NH_EMPLOYEES
cont> START 15-JUL-1988
cont> EVERY MONTH AT 19:00
cont> END.