diff --git a/CN/modules/ROOT/pages/master/compatibility_features_design/dbms_scheduler_impl.adoc b/CN/modules/ROOT/pages/master/compatibility_features_design/dbms_scheduler_impl.adoc new file mode 100644 index 00000000..88f08700 --- /dev/null +++ b/CN/modules/ROOT/pages/master/compatibility_features_design/dbms_scheduler_impl.adoc @@ -0,0 +1,9 @@ += DBMS_SCHEDULER 实现 + +此包使用 `sys` 模式下的表存储作业、程序、计划和执行记录。作业所有者可以通过 `sys.user_scheduler_jobs` 查看作业定义,通过 `sys.user_scheduler_job_run_details` 查看运行记录。 + +`EVALUATE_CALENDAR_STRING` 根据时间戳和重复表达式计算下次运行时间。`RUN_JOB(..., use_current_session => TRUE)` 在调用方的后端进程中执行作业。启用后台调度前,可先评估调度表达式并同步运行作业。 + +自动执行要求服务器启动时在 `shared_preload_libraries` 中加载 `ivorysql_ora`,并设置 `ivorysql.scheduler = on`。启动器在 `ivorysql.scheduler_databases` 指定的数据库中派发作业。包和目录定义见 `dbms_scheduler--1.0.sql`,启动器和作业进程分别实现在同一源码目录的 `scheduler_launcher.c` 和 `scheduler_worker.c` 中。 + +同步执行示例见 xref:master/oracle_compatibility/compat_dbms_scheduler.adoc[DBMS_SCHEDULER 用法]。 diff --git a/CN/modules/ROOT/pages/master/oracle_compatibility/compat_dbms_scheduler.adoc b/CN/modules/ROOT/pages/master/oracle_compatibility/compat_dbms_scheduler.adoc new file mode 100644 index 00000000..8a986c7d --- /dev/null +++ b/CN/modules/ROOT/pages/master/oracle_compatibility/compat_dbms_scheduler.adoc @@ -0,0 +1,56 @@ += DBMS_SCHEDULER 包 + +通过 Oracle 模式端口连接数据库后使用此包。 + +== 检查调度表达式 + +`EVALUATE_CALENDAR_STRING` 通过第四个参数返回下一个匹配的时间。本示例将会话时区设为 UTC。表达式每天在 09:30:00 匹配一次,因此从 7 月 1 日中午开始搜索会返回 7 月 2 日 09:30:00。 + +[source,sql] +---- +SET TIME ZONE 'UTC'; + +DECLARE + next_run TIMESTAMP WITH TIME ZONE; +BEGIN + DBMS_SCHEDULER.EVALUATE_CALENDAR_STRING( + 'FREQ=DAILY;BYHOUR=9;BYMINUTE=30;BYSECOND=0', + CAST('2026-01-01 00:00:00 +00:00' AS TIMESTAMP WITH TIME ZONE), + CAST('2026-07-01 12:00:00 +00:00' AS TIMESTAMP WITH TIME ZONE), + next_run); + RAISE NOTICE '%', next_run AT TIME ZONE 'UTC'; +END; +/ + +RESET TIME ZONE; +---- + +== 在当前会话中手动运行作业 + +以下示例创建禁用状态的作业,供手动运行。`RUN_JOB` 在 `use_current_session => TRUE` 时同步执行,便于在删除作业前检查执行效果。查询返回一行,值为 `ran`。 + +[source,sql] +---- +CREATE TABLE scheduler_demo_log (message VARCHAR2(30)); + +BEGIN + DBMS_SCHEDULER.CREATE_JOB( + job_name => 'scheduler_demo_job', + job_type => 'PLSQL_BLOCK', + job_action => 'BEGIN INSERT INTO scheduler_demo_log VALUES (''ran''); END;', + enabled => FALSE, + auto_drop => FALSE); + DBMS_SCHEDULER.RUN_JOB('scheduler_demo_job', use_current_session => TRUE); +END; +/ + +SELECT message FROM scheduler_demo_log; + +BEGIN + DBMS_SCHEDULER.DROP_JOB('scheduler_demo_job'); +END; +/ +DROP TABLE scheduler_demo_log; +---- + +后台定时执行的配置见 xref:master/compatibility_features_design/dbms_scheduler_impl.adoc[DBMS_SCHEDULER 实现]。 diff --git a/EN/modules/ROOT/pages/master/compatibility_features_design/dbms_scheduler_impl.adoc b/EN/modules/ROOT/pages/master/compatibility_features_design/dbms_scheduler_impl.adoc new file mode 100644 index 00000000..71a46830 --- /dev/null +++ b/EN/modules/ROOT/pages/master/compatibility_features_design/dbms_scheduler_impl.adoc @@ -0,0 +1,9 @@ += DBMS_SCHEDULER implementation + +The package uses tables under `sys` to store jobs, programs, schedules, and execution records. Job owners can inspect their job definitions through `sys.user_scheduler_jobs` and run records through `sys.user_scheduler_job_run_details`. + +`EVALUATE_CALENDAR_STRING` computes the next occurrence from timestamps and a repeat expression. `RUN_JOB(..., use_current_session => TRUE)` executes the job in the calling backend. Calendar evaluation and synchronous execution can be used before enabling background scheduling. + +Automatic execution requires the `ivorysql_ora` library in `shared_preload_libraries` and `ivorysql.scheduler = on` at server startup. The launcher dispatches work in databases configured in `ivorysql.scheduler_databases`. The package and catalog definitions are in `dbms_scheduler--1.0.sql`; the launcher and job worker are implemented in `scheduler_launcher.c` and `scheduler_worker.c` in the same source directory. + +See xref:master/oracle_compatibility/compat_dbms_scheduler.adoc[DBMS_SCHEDULER usage] for a synchronous example. diff --git a/EN/modules/ROOT/pages/master/oracle_compatibility/compat_dbms_scheduler.adoc b/EN/modules/ROOT/pages/master/oracle_compatibility/compat_dbms_scheduler.adoc new file mode 100644 index 00000000..6edf8671 --- /dev/null +++ b/EN/modules/ROOT/pages/master/oracle_compatibility/compat_dbms_scheduler.adoc @@ -0,0 +1,56 @@ += DBMS_SCHEDULER package + +Use the package in a database reached through the Oracle-mode port. + +== Check a calendar expression + +`EVALUATE_CALENDAR_STRING` returns a matching timestamp through its fourth argument. This example sets the session time zone to UTC. The expression matches every day at 09:30:00, so a search starting July 1 at noon returns July 2 at 09:30:00. + +[source,sql] +---- +SET TIME ZONE 'UTC'; + +DECLARE + next_run TIMESTAMP WITH TIME ZONE; +BEGIN + DBMS_SCHEDULER.EVALUATE_CALENDAR_STRING( + 'FREQ=DAILY;BYHOUR=9;BYMINUTE=30;BYSECOND=0', + CAST('2026-01-01 00:00:00 +00:00' AS TIMESTAMP WITH TIME ZONE), + CAST('2026-07-01 12:00:00 +00:00' AS TIMESTAMP WITH TIME ZONE), + next_run); + RAISE NOTICE '%', next_run AT TIME ZONE 'UTC'; +END; +/ + +RESET TIME ZONE; +---- + +== Run a job once in the current session + +This example creates a disabled job so it can be run on demand. `RUN_JOB` with `use_current_session => TRUE` runs synchronously and lets you inspect the effect before dropping the job. The query returns one row with `ran`. + +[source,sql] +---- +CREATE TABLE scheduler_demo_log (message VARCHAR2(30)); + +BEGIN + DBMS_SCHEDULER.CREATE_JOB( + job_name => 'scheduler_demo_job', + job_type => 'PLSQL_BLOCK', + job_action => 'BEGIN INSERT INTO scheduler_demo_log VALUES (''ran''); END;', + enabled => FALSE, + auto_drop => FALSE); + DBMS_SCHEDULER.RUN_JOB('scheduler_demo_job', use_current_session => TRUE); +END; +/ + +SELECT message FROM scheduler_demo_log; + +BEGIN + DBMS_SCHEDULER.DROP_JOB('scheduler_demo_job'); +END; +/ +DROP TABLE scheduler_demo_log; +---- + +For scheduled execution in the background, see xref:master/compatibility_features_design/dbms_scheduler_impl.adoc[DBMS_SCHEDULER implementation].