10 SQL 参考-10.5 PL/SQL 指南（Oracle 方言）-10.5.14 预定义函数/过程/包-Transwarp Inceptor-星环科技

关系型分析引擎

文档搜索

10.5.14 预定义函数/过程/包

更新时间：11/15/2023, 11:13:44 AM

在 Inceptor 中有一些系统预定义的函数/过程/包，可以用来直接调用，此外，我们可以通过相关命令随时查看系统内预定义的函数/过程/包的有关信息，具体查看方法可参见注意事项章节。

Inceptor 中一共有十个系统预定义的函数/过程，如下所示，我们将分章节介绍每一个函数/过程的具体内容及使用方法。

需要注意的是，Inceptor 中仅支持部分系统预定义的异常，也就是说对于 sqlcode，sqlerrm 函数，并非每一种异常发生，都会返回相对应的 Error code 和 Error message。

Inceptor 对于系统预定义异常的支持情况，可仔细阅读异常章节，获取更多信息。

set_env

语法格式

Inceptor 中，set_env(string,string) 是一个过程：

PROCEDURE set_env(enVar IN STRING, value IN STRING)复制

形参 enVar 的参数类型为 IN，数据类型为字符串，用来存放环境变量的名称。
形参 value 的参数类型为 IN，数据类型为字符串，相应地用来存放环境变量的值。

使用示例

请参考 set_env 与 get_env 的使用案例。

get_env

语法格式

get_env(string) 是一个函数，该函数用来返回 set_env 中环境变量的所对应的值。

FUNCTION get_env(enVar IN STRING) RETURN STRING复制

形参 enVar 的参数类型为 IN，数据类型为字符串。

使用示例

例 195. set_env 与 get_env 的使用

!set plsqlUseSlash true
DECLARE
  a STRING
  b STRING
BEGIN
  -- 调用过程 set_env，定义一个名为 aa 的环境变量，值为 hello。
  set_env('aa','hello')
  -- 调用函数 get_env，获取环境变量 aa 的值，并赋值给 a。
  a := get_env('aa')
  -- 输出变量 a 的值，可以发现变量 a 与环境变量 aa 的值相同。
  DBMS_OUTPUT.PUT_LINE('the value of a is: '||a)
  set_env('bb','world')
  b:= get_env('bb')
  DBMS_OUTPUT.PUT_LINE('the value of b is: '||b)
END;
/复制

输出结果为:

+---------------------------+
|          output           |
+---------------------------+
| the value of a is: hello  |
| the value of b is: world  |
+---------------------------+复制

sqlcode()

语法格式

sqlcode() 是一个不带参数的函数，用来返回当异常发生时，当前异常的 Error code。

FUNCTION sqlcode() RETURN INT复制

使用示例

例 196. sqlcode 与 sqlerrm 的使用

!set plsqlUseSlash true
DECLARE
   test_record transactions%rowtype
   v_code INT
   v_errm STRING
BEGIN
    SELECT *
    INTO test_record
    FROM transactions
    WHERE acc_num=6513065;
    dbms_output.put_line(test_record.trans_time)
EXCEPTION
    WHEN TOO_MANY_ROWS THEN
    -- 当异常发生时，获取当前异常的 Error code，并赋值给变量 v_code。
    v_code := sqlcode()
    dbms_output.put_line('error code is: ' ||v_code)
END;
/复制

输出结果为:

+-----------------------+
|        output         |
+-----------------------+
| error code is: -1422  |
+-----------------------+复制

sqlerrm()

语法格式

不带参数的 sqlerrm() 函数，用来返回当异常发生时，当前异常的 Error message。

FUNCTION sqlerrm() RETURN STRING复制

使用示例

例 197. sqlcode 与 sqlerrm 的使用

!set plsqlUseSlash true
DECLARE
   test_record transactions%rowtype
   v_code INT
   v_errm STRING
BEGIN
    SELECT *
    INTO test_record
    FROM transactions
    WHERE acc_num=6513065;
    dbms_output.put_line(test_record.trans_time)
EXCEPTION
    WHEN TOO_MANY_ROWS THEN
    -- 当异常发生时，获取当前异常的 Error message，并赋值给变量 v_errm。
    v_errm := sqlerrm()
    dbms_output.put_line('error message is: ' ||v_errm)
END;
/复制

输出结果为:

+----------------------------------+
|              output              |
+----------------------------------+
| error message is: TOO_MANY_ROWS  |
+----------------------------------+复制

sqlerrm

语法格式

带参数的 sqlerrm(int)，用来返回既定 Error code 下的 Error message。

FUNCTION sqlerrm(errCode IN INT) RETURN STRING复制

errCode：指定 Error code。

使用示例

例 198. sqlcode 与 sqlerrm 的使用

!set plsqlUseSlash true
DECLARE
   test_record transactions%rowtype
   v_code INT
   v_errm STRING
BEGIN
    SELECT *
    INTO test_record
    FROM transactions
    WHERE acc_num=6513065;
    dbms_output.put_line(test_record.trans_time)
EXCEPTION
    WHEN TOO_MANY_ROWS THEN
    -- 当异常 -1422 发生时，获取对应异常的 Error message，并赋值给变量 v_errm。
    v_errm := sqlerrm(-1422)
    dbms_output.put_line('error message of -1422 is: ' ||v_errm)
END;
/复制

输出结果为:

+-------------------------------------------+
|                  output                   |
+-------------------------------------------+
| error message of -1422 is: TOO_MANY_ROWS  |
+-------------------------------------------+复制

get_columns

语法格式

作为函数使用，get_columns(string,nestedtable<string>)返回数据表中的列名。
```
FUNCTION get_columns(table IN STRING) RETURN复制
```
作为过程使用，get_columns(string,nestedtable<string>) 返回数据表的列名。其中 columns 参数表示排除的字段，即哪些字段不在结果中显示。
```
PROCEDURE default.get_columns_test(columns IN  STRING)复制
```

使用示例

例 199. get_columns 的使用

-- 最终输出的字符串 s 的值，与最开始的值相比，少了最后一个列名之后的逗号。
!set plsqlUseSlash true
CREATE OR REPLACE PROCEDURE get_columns_test()
IS
  TYPE nest_table is TABLE of STRING
  TYPE nest_table_1 is TABLE of STRING
  -- 声明一个已定义好的 nest_table 类型的变量 a_table。
  a_table nest_table
  -- 声明一个已定义好的 nest_table1 类型的变量 b_table，默认为 null 值。
  b_table nest_table_1 default null
  s string
BEGIN
  -- 给变量 a_table 赋值。
  a_table := nest_table('this','is','a','table','ID')
  -- 使用 get_columns 函数，获取表 transactions 的列名,并赋值给变量 b_table。
  b_table := get_columns("transactions")
  DBMS_OUTPUT.PUT_LINE('a_table:')
  -- 依次打印出变量 a_table 的值。
  FOR i in a_table.first() .. a_table.last() LOOP
     DBMS_OUTPUT.PUT_LINE(a_table(i))
  END LOOP;
  IF b_table is not null THEN
    -- 将变量 b_table 的值用逗号连接起来，并赋值给变量 s。
    FOR i in b_table.first() .. b_table.last() LOOP
     s := s || b_table(i) || ", "
     END LOOP;
  END;
  DBMS_OUTPUT.PUT_LINE('b_table:')
  -- instr 函数返回字符串 s 中从右往左数第一次出现逗号的位置，设为 m，substr 函数是从字符串 s 中第一个字符开始截取长度为 m-1 的字符串。
  -- 用于去除最后一个逗号“,”
  s := substr(s,1,oracle_instr(s,',',-1)-1)
  DBMS_OUTPUT.PUT_LINE(s)
END;
/

BEGIN
  get_columns_test()
END;
/复制

输出结果为:

+---------------------------------------------------------------------+
|                               output                                |
+---------------------------------------------------------------------+
| a_table:                                                            |
| this                                                                |
| is                                                                  |
| a                                                                   |
| table                                                               |
| ID                                                                  |
| b_table:                                                            |
| trans_id, acc_num, trans_time, trans_type, stock_id, price, amount  |
+---------------------------------------------------------------------+复制

raise_application_error

语法格式

在Inceptor PL/SQL 中，可以使用预定义函数 raise_application_error(int,string[,bool])，来抛出带有指定 error code, error message 的异常：

FUNCTION raise_application_error(errorCode IN INT, msg IN STRING[, keepExistError IN BOOL]) RETURN EXCEPTION复制

目前第三个参数 keepExistError 是可选的，且没有任何作用。

使用示例

例 200. raise_application_error 的使用

!set plsqlUseSlash true
DECLARE
  num_tables INT
BEGIN
  -- 查询表 transactions 的行数，并赋值给变量 num_tables。
  SELECT COUNT(*) INTO num_tables FROM transactions;
   IF num_tables < 1000 THEN
     -- 如果表 transactions 的行数小于 1000，则抛出异常。
     RAISE_APPLICATION_ERROR
      (-20101, 'Expecting at least 1000 tables')
    ELSE
      -- 否则，就输出表 transactions 的行数。
      dbms_output.put_line(num_tables)
    END IF
END;
/复制

输出结果为:

 EXECUTION FAILED: Task EXEC PLSQL error PLException: [Error -20101] Expecting at least 1000 tables
*********************************************
System function raise_application_error (LINE -1, COLUMN -1, TEXT "null")
ANONYMOUS BLOCK (LINE 8, COLUMN 5, TEXT "RAISE_APPLICATION_ERROR
      (-20101, 'Expecting at least 1000 tables')")
*********************************************复制

例 201. 上述例子不抛出异常的情况

!set plsqlUseSlash true
DECLARE
  num_tables INT
BEGIN
  -- 查询表 transactions 的行数，并赋值给变量 num_tables。
  SELECT COUNT(*) INTO num_tables FROM transactions;
   IF num_tables < 10  THEN
     -- 如果表 transactions 的行数小于 10，则抛出异常。
     RAISE_APPLICATION_ERROR
      (-20101, 'Expecting at least 1000 tables')
    ELSE
      -- 否则，就输出表 transactions 的行数。
      dbms_output.put_line(num_tables)
    END IF
END;
/复制

输出结果为:

+---------+
| output  |
+---------+
| 20      |
+---------+复制

PUT_LINE

语法格式

Inceptor 中，put_line(string) 是一个过程，形参 msg 的参数类型为 IN，数据类型为字符串，该过程用来打印出字符串的值。

PROCEDURE dbms_output.put_line(msg IN STRING)复制

注意事项

在 Inceptor 中使用 PUT_LINE 函数时，如果程序正常运行，则 PUT_LINE 会统一打印到终端。
如果程序运行过程中出现了未被处理的异常，可以设置相关命令，将 PUT_LINE 正常打印出的内容连同异常栈一起打印到终端。
更多用法说明，可参见注意事项章节。

使用示例

例 202. 程序正常运行时，PUT_LINE 的打印

!set plsqlUseSlash true
-- 创建名为 put_line_test 的函数，形参 v1 的数据类型为整数型，返回值为双精度类型。
CREATE OR REPLACE FUNCTION put_line_test(v1 int)
   RETURN DOUBLE
IS
  v2 DOUBLE
  v3 STRING
BEGIN
   -- 使用 put_line 函数，打印出 null 值。
   put_line(null)
   DBMS_OUTPUT.PUT_LINE(v1)
   v2 := 2
   v3 := "I'm a string."
   put_line(v2)
   -- 使用 put_line 函数，打印出变量 v2 的值。
   DBMS_OUTPUT.PUT_LINE('v2: ' || v2)
   -- 使用 put_line 函数，打印出字符串 v2+v1。
   put_line('v2 + v1')
   DBMS_OUTPUT.PUT_LINE(v2 + v1)
   -- 使用 put_line 函数,打印出 v3 的值。
   put_line(v3)
   v3 := null
   DBMS_OUTPUT.PUT_LINE(v3)
   -- 函数返回值为 v1 和 v2 的乘积。
   return v2 * v1
END;
/

BEGIN
  dbms_output.put_line("Executing put_line_test(1)")
  -- 使用 put_line 函数，打印出 put_line_test(1) 的全部值。
  put_line(put_line_test(1))
END;
/复制

输出结果:

+-----------------------------+
|           output            |
+-----------------------------+
| Executing put_line_test(1)  |
| null                        |
| 1                           |
| 2.0                         |
| v2: 2.0                     |
| v2 + v1                     |
| 3.0                         |
| I'm a string.               |
| null                        |
| 2.0                         |
+-----------------------------+复制

dbms_output

语法格式

dbms_output 包内有一个过程，该过程可以实现将字符（包括变量和常量）的值打印出来，我们通常调用包内过程，来打印变量或者常量的值。

PACKAGE dbms_output IS
   PROCEDURE dbms_output.put_line(msg IN STRING)
PACKAGE BODY dbms_output IS
   PROCEDURE dbms_output.put_line(msg IN STRING)复制

注意事项

Inceptor 中，包 dbms_output 是系统预定义的，包内只有一个名为 put_line 的过程，且 put_line 过程也是系统预定义的。
在实际的使用中，可以直接调用过程 put_line 打印结果，也可以调用包内过程 put_line 来打印结果。

使用示例

例 203. 使用包内过程，打印结果

调用包内过程 put_line。

!set plsqlUseSlash true
BEGIN
FOR test IN 1..5 LOOP
dbms_output.put_line('test:'||test)
END LOOP;
END;
/复制

输出结果为:

+---------+
| output  |
+---------+
| test:1  |
| test:2  |
| test:3  |
| test:4  |
| test:5  |
+---------+复制

owa_util

语法格式

在 Inceptor 中，系统预定义包 owa_util，仅支持包内过程 who_called_me，有四个形参，参数类型均为 OUT 类型，每次调用包内过程 who_called_me 时，每一个形参都会获得一个具体的值，即实参。

PACKAGE owa_util IS
   PROCEDURE owa_util.who_called_me(owner OUT STRING, name OUT STRING, lineno OUT INT, type OUT STRING)
PACKAGE BODY owa_util IS
   PROCEDURE owa_util.who_called_me(owner OUT STRING, name OUT STRING, lineno OUT INT, type OUT STRING)复制

owner 是存储过程的创建者信息。
name 是存储过程调用者的名字信息。
lineno 是调用语句在调用者中的行号。
type 通常表明程序的类型，包括 ANONYMOUS_BLOCK, FUNCTION, PROCEDURE, PACKAGE BODY。

使用示例

例 204. 创建过程 outer_proc()

!set plsqlUseSlash true
-- 创建一个名为 outer_proc() 的过程。
CREATE OR REPLACE PROCEDURE outer_proc()
IS
-- 分别声明四个变量。
v_owner STRING
v_name STRING
v_lineno INT
v_type STRING
BEGIN
  DBMS_OUTPUT.PUT_LINE('Outer outer proc')
  -- 调用包内过程 owa_util.who_called_me，其中 v_owner, v_name, v_lineno, v_type 分别用来储存相对应形参所获得的值。
  owa_util.who_called_me(v_owner, v_name, v_lineno, v_type)
  -- 依次输出四个变量的值。
  DBMS_OUTPUT.PUT_LINE('Owner: ' || v_owner)
  DBMS_OUTPUT.PUT_LINE('Name: ' || v_name)
  DBMS_OUTPUT.PUT_LINE('Lineno: ' || v_lineno)
  DBMS_OUTPUT.PUT_LINE('Type: ' || v_type)
END;
/
BEGIN
  outer_proc()
END;
/复制

输出结果为:

+------------------------+
|         output         |
+------------------------+
| Outer outer proc       |
| Owner:                 |
| Name:                  |
| Lineno: 2              |
| Type: ANONYMOUS_BLOCK  |
+------------------------+复制

上一篇：10.5.13 Packages 下一篇：10.5.15 异常

本页导航

set_env
get_env
sqlcode()
sqlerrm()
sqlerrm
get_columns
raise_application_error
PUT_LINE
dbms_output
owa_util

大数据基础平台

大数据云平台

数据库

数据开发工具

智能分析工具

AI基础设施平台

软硬一体产品

金融解决方案

交通解决方案

医疗解决方案

教育解决方案

能源解决方案

制造业解决方案

政府解决方案

运营商解决方案

set_env

get_env

sqlcode()

sqlerrm()

sqlerrm

get_columns

raise_application_error

PUT_LINE

dbms_output

owa_util

咨询热线