add userenv .adoc

Author: OreoYang

CN/modules/ROOT/nav.adoc

@@ -28,6 +28,7 @@
 **** xref:master/6.3.5.adoc[NLS 参数]
 *** 内置函数
 **** xref:master/6.4.1.adoc[sys_context]
+**** xref:master/6.4.2.adoc[userenv]
 *** xref:master/6.5.adoc[国标GB18030]
 ** Oracle兼容功能列表
 *** xref:master/7.1.adoc[1、框架设计]

CN/modules/ROOT/pages/master/6.4.2.adoc

@@ -0,0 +1,57 @@
+
+:sectnums:
+:sectnumlevels: 5
+
+
+= **功能概述**
+
+IvorySQL提供兼容Oracle内置函数`USERENV('parameter')`,用于返回当前会话的相关信息。
+这是一个遗留函数，建议使用 SYS_CONTEXT 函数及其内置的 USERENV 命名空间来获取当前功能。
+
+== 实现原理
+
+`USERENV` 通过Bison规则解析函数调用，检查参数合法性并映射到对应的具体SQL函数。
+解析规则在 `ora_gram.y` 中实现，逻辑如下：
+```c
+USERENV '(' Sconst ')'
+	{
+		char *normalized_param = downcase_identifier($3, strlen($3), true, true);
+
+		#define CHECK_AND_CALL(param, func_name) \
+			if (strcmp(normalized_param, param) == 0) \
+				$$ = (Node *) makeFuncCall(OracleSystemFuncName(func_name), NIL, COERCE_EXPLICIT_CALL, @1);
+
+		CHECK_AND_CALL("client_info", "get_client_info")
+		else CHECK_AND_CALL("entryid", "get_entryid")
+		else CHECK_AND_CALL("terminal", "get_terminal")
+		else CHECK_AND_CALL("isdba", "get_isdba")
+		else CHECK_AND_CALL("lang", "get_lang")
+		else CHECK_AND_CALL("language", "get_language")
+		else CHECK_AND_CALL("sessionid", "get_sessionid")
+		else CHECK_AND_CALL("sid", "get_sid")
+		else
+			ereport(ERROR,
+					(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+						errmsg("invalid USERENV parameter: \"%s\".", $3)));
+		#undef CHECK_AND_CALL
+	}
+```
+具体功能则是在 `builtin_functions--1.0.sql` 中实现。例如：
+```sql
+CREATE OR REPLACE FUNCTION sys.get_language() 
+RETURNS varchar2 
+AS $$
+	SELECT (regexp_split_to_array(current_setting('lc_monetary'), '\.'))[1]||'.'||pg_client_encoding();
+$$ LANGUAGE sql STRICT;
+```
+
+== USERENV支持的参数
+[cols="2,8"]
+|====
+|*参数名称*|*返回值*
+|sid | 当前session的用户ID。
+|sessionid | 返回审计会话标识符。
+|language | 返回数据库当前会话的语言、地域和字符集。
+|lang | 返回ISO缩写语言名称。
+|isdba | 如果用户已经被认证为管理员;或者是通过操作系统或口令文件具有管理员特权的，返回“TRUE"，否则返回"FALSE"。
+|====

EN/modules/ROOT/nav.adoc

@@ -27,6 +27,7 @@
 *** xref:master/6.3.5.adoc[NLS Parameters]
 ** Built-in Functions
 *** xref:master/6.4.1.adoc[sys_context]
+*** xref:master/6.4.2.adoc[userenv]
 ** xref:master/6.5.adoc[GB18030 Character Set]
 * List of Oracle compatible features
 ** xref:master/7.1.adoc[1、Ivorysql frame design]

EN/modules/ROOT/pages/master/6.4.2.adoc

@@ -0,0 +1,57 @@
+:sectnums:
+:sectnumlevels: 5
+
+= **Feature Overview**
+
+IvorySQL provides compatibility with Oracle's built-in function `USERENV('parameter')`, which is used to return information about the current session.
+This is a legacy function, and IvorySQL recommends taht you can use the `SYS_CONTEXT` function with its built-in `USERENV` namespace for current functionality.
+
+== Implementation Principle
+
+`USERENV` parses function calls through Bison rules, checks parameter validity, and maps them to corresponding SQL functions.
+The parsing rules are implemented in `ora_gram.y`, with the following logic:
+
+```c
+USERENV '(' Sconst ')'
+    {
+        char *normalized_param = downcase_identifier($3, strlen($3), true, true);
+
+        #define CHECK_AND_CALL(param, func_name) \
+            if (strcmp(normalized_param, param) == 0) \
+                $$ = (Node *) makeFuncCall(OracleSystemFuncName(func_name), NIL, COERCE_EXPLICIT_CALL, @1);
+
+        CHECK_AND_CALL("client_info", "get_client_info")
+        else CHECK_AND_CALL("entryid", "get_entryid")
+        else CHECK_AND_CALL("terminal", "get_terminal")
+        else CHECK_AND_CALL("isdba", "get_isdba")
+        else CHECK_AND_CALL("lang", "get_lang")
+        else CHECK_AND_CALL("language", "get_language")
+        else CHECK_AND_CALL("sessionid", "get_sessionid")
+        else CHECK_AND_CALL("sid", "get_sid")
+        else
+            ereport(ERROR,
+                    (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+                     errmsg("invalid USERENV parameter: \"%s\".", $3)));
+        #undef CHECK_AND_CALL
+    }
+```
+The specific functionality is implemented in `builtin_functions--1.0.sql`. For example:
+```sql
+CREATE OR REPLACE FUNCTION sys.get_language() 
+RETURNS varchar2 
+AS $$
+    SELECT (regexp_split_to_array(current_setting('lc_monetary'), '\\.'))[1]||'.'||pg_client_encoding();
+$$ LANGUAGE sql STRICT;
+```
+
+== Supported Parameters for USERENV
+
+[cols="3,7"] 
+|==== 
+|Parameter Name|Return Value 
+|sid | The user ID of the current session. 
+|sessionid | Returns the audit session identifier. 
+|language | Returns the language, territory, and character set of the current database session. 
+|lang | Returns the ISO abbreviation of the language name. 
+|isdba | Returns "TRUE" if the user has been authenticated as an administrator or has administrator privileges through the operating system or password file; otherwise, returns "FALSE". 
+|====