# PKG_SERVICE PKG_SERVICE支持的接口请参见[表1]。 表1PKG_SERVICE | 接口名称 | 描述 | |:---|:---| | [PKG_SERVICE.SQL_IS_CONTEXT_ACTIVE] | 确认该CONTEXT是否已注册。 | | [PKG_SERVICE.SQL_CLEAN_ALL_CONTEXTS] | 取消所有注册的CONTEXT。 | | [PKG_SERVICE.SQL_REGISTER_CONTEXT] | 注册一个CONTEXT。 | | [PKG_SERVICE.SQL_UNREGISTER_CONTEXT] | 取消注册该CONTEXT。 | | [PKG_SERVICE.SQL_SET_SQL] | 向CONTEXT设置一条SQL语句，目前只支持SELECT。 | | [PKG_SERVICE.SQL_RUN] | 在一个CONTEXT上执行设置的SQL语句。 | | [PKG_SERVICE.SQL_NEXT_ROW] | 读取该CONTEXT中的下一行数据。 | | [PKG_SERVICE.SQL_GET_VALUE] | 读取该CONTEXT中动态定义的列值。 | | [PKG_SERVICE.SQL_SET_RESULT_TYPE] | 根据类型OID动态定义该CONTEXT的一个列。 | | [PKG_SERVICE.JOB_CANCEL] | 通过任务id来删除定时任务。 | | [PKG_SERVICE.JOB_FINISH] | 禁用或者启用定时任务。 | | [PKG_SERVICE.JOB_SUBMIT] | 提交一个定时任务。作业号由系统自动生成或由用户指定。 | | [PKG_SERVICE.JOB_UPDATE] | 修改定时任务的属性，包括任务内容、下次执行时间、执行间隔。 | | [PKG_SERVICE.SUBMIT_ON_NODES] | 提交一个任务到所有节点，作业号由系统自动生成。 | | [PKG_SERVICE.ISUBMIT_ON_NODES] | 提交一个任务到所有节点，作业号由用户指定。 | | [PKG_SERVICE.SQL_GET_ARRAY_RESULT] | 获取该CONTEXT中返回的数组值。 | | [PKG_SERVICE.SQL_GET_VARIABLE_RESULT] | 获取该CONTEXT中返回的列值。 | ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) 使用EXECUTE DIRECT ON语法执行PKG_SERVICE包中的函数时，如果GUC参数enable_udf_execute_direct的值为on，则可以执行；如果其值为off，则不可以执行。 - PKG_SERVICE.SQL_IS_CONTEXT_ACTIVE 该函数用于确认一个CONTEXT是否已注册。该函数传入待查找的CONTEXT id，如果该CONTEXT存在返回true，否则返回false。 PKG_SERVICE.SQL_IS_CONTEXT_ACTIVE原型为： ``` PKG_SERVICE.SQL_IS_CONTEXT_ACTIVE( context_id IN INTEGER ) RETURN BOOLEAN; ``` 表2PKG_SERVICE.SQL_IS_CONTEXT_ACTIVE接口参数说明 | 参数名称 | 描述 | |:---|:---| | context_id | 待查找的CONTEXT id号。 | - PKG_SERVICE.SQL_CLEAN_ALL_CONTEXTS 该函数用于取消所有CONTEXT。 PKG_SERVICE.SQL_CLEAN_ALL_CONTEXTS原型为： ``` PKG_SERVICE.SQL_CLEAN_ALL_CONTEXTS( ) RETURN VOID; ``` - PKG_SERVICE.SQL_REGISTER_CONTEXT 该函数用于打开一个CONTEXT。打开CONTEXT是后续对该CONTEXT进行各项操作的前提。该函数无需传入任何参数，内部会自动递增生成CONTEXT id，并将其作为返回值赋给一个INTEGER类型的变量。 PKG_SERVICE.SQL_REGISTER_CONTEXT原型为： ``` DBE_SQL.REGISTER_CONTEXT( ) RETURN INTEGER; ``` - PKG_SERVICE.SQL_UNREGISTER_CONTEXT 该函数用于关闭一个CONTEXT。关闭CONTEXT是该CONTEXT中各项操作的结束。如果在存储过程结束时未调用该函数，CONTEXT占用的内存将不会被释放，因此关闭CONTEXT非常重要。由于异常情况可能导致存储过程中途退出，从而导致CONTEXT未能关闭，建议存储过程中有异常处理，将该接口包含在内。 PKG_SERVICE.SQL_UNREGISTER_CONTEXT原型为： ``` PKG_SERVICE.SQL_UNREGISTER_CONTEXT( context_id IN INTEGER ) RETURN INTEGER; ``` 表3PKG_SERVICE.SQL_UNREGISTER_CONTEXT接口参数说明 | 参数名称 | 描述 | |:---|:---| | context_id | 计划关闭的CONTEXT id号。 | - PKG_SERVICE.SQL_SET_SQL 该函数用于解析指定游标的查询语句，被传入的查询语句会立即执行。目前仅支持SELECT查询语句的解析，且语句参数仅可通过text类型传递，长度不大于1G。 PKG_SERVICE.SQL_SET_SQL原型为： ``` PKG_SERVICE.SQL_SET_SQL( context_id IN INTEGER, query_string IN TEXT, language_flag IN INTEGER ) RETURN BOOLEAN; ``` 表4PKG_SERVICE.SQL_SET_SQL接口参数说明 | 参数名称 | 描述 | |:---|:---| | context_id | 执行查询语句解析的CONTEXT id。 | | query_string | 执行的查询语句。 | | language_flag | 版本语言号，指定不同版本的行为。 - 1为非兼容版本。 - 2为ORA兼容模式版本。 | - PKG_SERVICE.SQL_RUN 该函数用于执行一个给定的CONTEXT。该函数接收一个CONTEXT id，运行后获得的数据用于后续操作。目前仅支持SELECT查询语句的执行。 PKG_SERVICE.SQL_RUN原型为： ``` PKG_SERVICE.SQL_RUN( context_id IN INTEGER, ) RETURN INTEGER; ``` 表5PKG_SERVICE.SQL_RUN接口参数说明 | 参数名称 | 描述 | |:---|:---| | context_id | 执行查询语句解析的CONTEXT id。 | - PKG_SERVICE.SQL_NEXT_ROW 该函数返回执行SQL实际返回的数据行数，每一次调用该接口都会读取下一行数据，直到数据读取完毕获取不到新行为止。 PKG_SERVICE.SQL_NEXT_ROW原型为： ``` PKG_SERVICE.SQL_NEXT_ROW( context_id IN INTEGER, ) RETURN INTEGER; ``` 表6PKG_SERVICE.SQL_NEXT_ROW接口参数说明 | 参数名称 | 描述 | |:---|:---| | context_id | 执行的CONTEXT id。 | - PKG_SERVICE.SQL_GET_VALUE 该函数用于返回指定CONTEXT中在给定位置的CONTEXT元素值。该接口访问的是由PKG_SERVICE.SQL_NEXT_ROW获取的数据。 PKG_SERVICE.SQL_GET_VALUE原型为： ``` PKG_SERVICE.SQL_GET_VALUE( context_id IN INTEGER, pos IN INTEGER, col_type IN ANYELEMENT ) RETURN ANYELEMENT; ``` 表7PKG_SERVICE.SQL_GET_VALUE接口参数说明 | 参数名称 | 描述 | |:---|:---| | context_id | 执行的CONTEXT id。 | | pos | 动态定义列在查询中的位置。 | | col_type | 任意类型变量，定义列的返回值类型。 | - PKG_SERVICE.SQL_SET_RESULT_TYPE 该函数用于定义从指定CONTEXT返回的列。该接口只能应用于SELECT定义的CONTEXT中。定义的列通过查询列表的相对位置来标识，PKG_SERVICE.SQL_SET_RESULT_TYPE原型为： ``` PKG_SERVICE.SQL_SET_RESULT_TYPE( context_id IN INTEGER, pos IN INTEGER, coltype_oid IN ANYELEMENT, maxsize IN INTEGER ) RETURN INTEGER; ``` 表8PKG_SERVICE.SQL_SET_RESULT_TYPE接口参数说明 | 参数名称 | 描述 | |:---|:---| | context_id | 执行的CONTEXT id。 | | pos | 动态定义列在查询中的位置。 | | coltype_oid | 任意类型的变量，可根据变量类型得到对应类型OID。 | | maxsize | 定义的列的长度。 | - PKG_SERVICE.JOB_CANCEL 该函数用于删除指定的定时任务。 PKG_SERVICE.JOB_CANCEL原型为： ``` PKG_SERVICE.JOB_CANCEL( id IN INTEGER); ``` 表9PKG_SERVICE.JOB_CANCEL接口参数说明 | 参数 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | id | INTEGER | IN | 否 | 将要删除的定时任务的id。 | - PKG_SERVICE.JOB_FINISH 该函数用于禁用或者启用定时任务。 PKG_SERVICE.JOB_FINISH原型为： ``` PKG_SERVICE.JOB_FINISH( id IN INTEGER, broken IN BOOLEAN, next_time IN TIMESTAMP DEFAULT sysdate); ``` 表10PKG_SERVICE.JOB_FINISH接口参数说明 | 参数 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | id | INTEGER | IN | 否 | 将要禁用或启用的定时任务的id。 | | broken | BOOLEAN | IN | 否 | 状态标志位，true代表禁用，false代表启用。根据true或false值更新当前JOB的状态；如果为空值，则不改变原有JOB的状态。 | | next_time | TIMESTAMP | IN | 是 | 下次运行时间，默认为当前系统时间。该参数可以省略，为默认值。 - 如果参数broken状态为true，则更新该参数为'4000-1-1'。 - 如果参数broken状态为false，参数next_time不为空值时，更新指定JOB的next_time值；next_time为空值时，不更新next_time值。 | - PKG_SERVICE.JOB_SUBMIT 该函数用于提交一个系统提供的定时任务。 PKG_SERVICE.JOB_SUBMIT原型为： ``` PKG_SERVICE.JOB_SUBMIT( id IN BIGINT, content IN TEXT, next_time IN TIMESTAMP DEFAULT sysdate, interval_time IN TEXT DEFAULT 'null', job OUT INTEGER); ``` ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) - 当创建一个定时任务（JOB）时，系统默认将当前数据库和用户名与当前创建的定时任务绑定起来。 - 该接口函数可以通过CALL语句或SELECT语句调用，如果通过SELECT语句调用，可以不填写出参。如果在存储过程中，则需要通过PERFORM语句调用该接口函数。 - 如果提交的SQL语句任务使用到非PUBLIC的schema，应该指定表或者函数的schema，或者在SQL语句前添加SET current_schema = xxx;语句。 表11PKG_SERVICE.JOB_SUBMIT接口参数说明 | 参数 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | id | BIGINT | IN | 否 | 定时任务id。如果传入id为NULL，则内部会生成作业id。 | | content | TEXT | IN | 否 | 要执行的SQL语句。支持一个或多个DML、匿名块、调用存储过程的语句或三种类型混合的场景。 | | next_time | TIMESTAMP | IN | 否 | 下次作业运行时间。默认值为当前系统时间（sysdate）。如果是过去时间，在提交作业时表示立即执行。 | | interval_time | TEXT | IN | 是 | 用来计算下次作业运行时间的时间表达式，可以是interval表达式，也可以是sysdate加上一个NUMERIC值（例如：sysdate+1.0/24）。如果为空值或字符串"null"，表示只执行一次，执行后，JOB状态STATUS变成'd' ，表示不再执行。 | | job | INTEGER | OUT | 否 | 作业号。范围为1～3000000。当使用SELECT语句调用pkg_service.job_submit时，该参数可以省略。 | - PKG_SERVICE.JOB_UPDATE 该函数用于修改定时任务的属性，包括任务内容、下次执行时间和执行间隔。 PKG_SERVICE.JOB_UPDATE原型为： ``` PKG_SERVICE.JOB_UPDATE( id IN BIGINT, next_time IN TIMESTAMP, interval_time IN TEXT, content IN TEXT); ``` 表12PKG_SERVICE.JOB_UPDATE接口参数说明 | 参数 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | id | INTEGER | IN | 否 | 指定的定时任务id。 | | next_time | TIMESTAMP | IN | 是 | 下次运行时间。如果该参数为空值，则不更新指定JOB的next_time值，否则更新指定JOB的next_time值。 | | interval_time | TEXT | IN | 是 | 用来计算下次作业运行时间的时间表达式。 - 如果该参数为空值，不更新指定job的interval_time值。 - 如果该参数不为空值，会校验interval_time是否为有效的时间类型或interval类型，若是则更新指定JOB的interval_time值。 - 如果为字符串"null"，表示只执行一次，执行后，JOB状态STATUS变成'd' ，表示不再执行。 | | content | TEXT | IN | 是 | 执行的存储过程名或者SQL语句块。如果该参数为空值，则不更新指定JOB的content值，否则更新指定JOB的content值。 | 示例： ``` CREATE TABLE test_table(a int); CREATE TABLE CREATE OR REPLACE PROCEDURE test_job(a in int) IS BEGIN INSERT INTO test_table VALUES(a); COMMIT; END; / CREATE PROCEDURE --PKG_SERVICE.JOB_SUBMIT SELECT PKG_SERVICE.JOB_SUBMIT(NULL, 'call test_job(1);', to_date('20180101','yyyymmdd'),'sysdate+1'); job_submit ------------ 28269 (1 row) SELECT PKG_SERVICE.JOB_SUBMIT(NULL, 'call test_job(1);', to_date('20180101','yyyymmdd'),'sysdate+1.0/24'); job_submit ------------ 1506 (1 row) CALL PKG_SERVICE.JOB_SUBMIT(NULL, 'INSERT INTO test_table VALUES(1); call test_job(1); call test_job(1);', add_months(to_date('201701','yyyymm'),1), 'date_trunc(''day'',SYSDATE) + 1 +(8*60+30.0)/(24*60)' ,:jobid); job ------- 14131 (1 row) SELECT PKG_SERVICE.JOB_SUBMIT (101, 'insert_msg_statistic1;', sysdate, 'sysdate+3.0/24'); job_submit ------------ 101 (1 row) --PKG_SERVICE.JOB_UPDATE CALL PKG_SERVICE.JOB_UPDATE(101, sysdate, 'sysdate + 1.0/1440', 'call test_job(1);'); job_update ------------ (1 row) CALL PKG_SERVICE.JOB_UPDATE(101, sysdate, 'sysdate + 1.0/1440', 'insert into test_table values(1);'); job_update ------------ (1 row) --PKG_SERVICE.JOB_FINISH CALL PKG_SERVICE.JOB_FINISH(101,true); job_finish ------------ (1 row) --PKG_SERVICE.JOB_CANCEL CALL PKG_SERVICE.JOB_CANCEL(101); job_cancel ------------ (1 row) DROP TABLE test_table; DROP TABLE ``` - PKG_SERVICE.SUBMIT_ON_NODES 该函数用于创建一个所有CN/DN上的定时任务。仅sysadmin/monitor admin有权限调用该函数。 PKG_SERVICE.SUBMIT_ON_NODES原型为： ``` PKG_SERVICE.SUBMIT_ON_NODES( node_name IN NAME, database IN NAME, what IN TEXT, next_date IN TIMESTAMP WITHOUT TIME ZONE, job_interval IN TEXT, job OUT INTEGER); ``` 表13PKG_SERVICE.SUBMIT_ON_NODES接口参数说明 | 参数 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | node_name | TEXT | IN | 否 | 指定作业的执行节点，当前仅支持值为'ALL_NODE'（在所有节点执行）与'CCN'（在central coordinator执行）。 | | database | TEXT | IN | 否 | 集群作业所使用的database，节点类型为'ALL_NODE'时仅支持值为'postgres'。 | | what | TEXT | IN | 否 | 要执行的SQL语句。支持一个或多个DML、匿名块、调用存储过程的语句或三种类型混合的场景。 | | nextdate | TIMESTAMP | IN | 否 | 下次作业运行时间。默认值为当前系统时间（sysdate）。如果是过去时间，在提交作业时表示立即执行。 | | job_interval | TEXT | IN | 否 | 用来计算下次作业运行时间的时间表达式，可以是interval表达式，也可以是sysdate加上一个NUMERIC值（例如：sysdate+1.0/24）。如果为空值或字符串"null"，表示只执行一次，执行后，JOB状态STATUS变成'd'，表示不再执行。 | | job | INTEGER | OUT | 否 | 作业号。范围为1～3000000。当使用SELECT调用DBMS.SUBMIT_ON_NODES时，该参数可以省略。 | 示例： ``` SELECT pkg_service.submit_on_nodes('ALL_NODE', 'postgres', 'select capture_view_to_json(''dbe_perf.statement'', 0);', sysdate, 'interval ''60 second'''); submit_on_nodes ----------------- 12068 (1 row) SELECT pkg_service.submit_on_nodes('CCN', 'postgres', 'select capture_view_to_json(''dbe_perf.statement'', 0);', sysdate, 'interval ''60 second'''); submit_on_nodes ----------------- 9027 (1 row) ``` - PKG_SERVICE.ISUBMIT_ON_NODES ISUBMIT_ON_NODES与SUBMIT_ON_NODES语法功能相同，但其第一个参数是入参，即指定的作业号，SUBMIT最后一个参数是出参，表示系统自动生成的作业号。仅sysadmin/monitor admin有权限调用该函数。 - PKG_SERVICE.SQL_GET_ARRAY_RESULT 该函数用于返回绑定的数组类型的OUT参数的值，可以用来获取存储过程中的OUT参数。 PKG_SERVICE.SQL_GET_ARRAY_RESULT原型为： ``` PKG_SERVICE.SQL_GET_ARRAY_RESULT( context_id in int, pos in VARCHAR2, column_value inout anyarray, result_type in anyelement ); ``` 表14PKG_SERVICE.SQL_GET_ARRAY_RESULT接口参数说明 | 参数名称 | 描述 | |:---|:---| | context_id | 待查找的CONTEXT id号。 | | pos | 绑定的参数名。 | | column_value | 返回值。 | | result_type | 返回值类型。 | - PKG_SERVICE.SQL_GET_VARIABLE_RESULT 该函数用于返回绑定的非数组类型的OUT参数的值，可以用来获取存储过程中的OUT参数。 PKG_SERVICE.SQL_GET_VARIABLE_RESULT原型为： ``` PKG_SERVICE.SQL_GET_VARIABLE_RESULT( context_id in int, pos in VARCHAR2, result_type in anyelement ) RETURNS anyelement; ``` 表15PKG_SERVICE.SQL_GET_VARIABLE_RESULT接口参数说明 | 参数名称 | 描述 | |:---|:---| | context_id | 待查找的CONTEXT id号。 | | pos | 绑定的参数名。 | | result_type | 返回值类型。 |