Merge branch 'IvorySQL:master' into master

Author: yuanyl630

.coderabbit.yaml

@@ -0,0 +1,11 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+# Minimal configuration for getting started
+# language: "zh-CN"
+language: "en-US"
+reviews:
+  profile: "chill"
+  high_level_summary: true
+  auto_review:
+    enabled: true
+    drafts: false
+    base_branches: ["master", "v5.0", "v4.6", "v1.17"]

CN/modules/ROOT/nav.adoc

@@ -24,7 +24,9 @@
 **** xref:master/6.3.1.adoc[like]
 **** xref:master/6.3.3.adoc[RowID]
 **** xref:master/6.3.2.adoc[OUT 参数]
-**** xref:master/6.4.adoc[国标GB18030]
+**** xref:master/6.3.4.adoc[%TYPE、%ROWTYPE]
+**** xref:master/6.3.5.adoc[NLS 参数]
+*** xref:master/6.4.adoc[国标GB18030]
 ** Oracle兼容功能列表
 *** xref:master/7.1.adoc[1、框架设计]
 *** xref:master/7.2.adoc[2、GUC框架]
@@ -41,6 +43,8 @@
 *** xref:master/7.13.adoc[13、不可见列]
 *** xref:master/7.14.adoc[14、RowID]
 *** xref:master/7.15.adoc[15、OUT 参数]
+*** xref:master/7.16.adoc[16、%TYPE、%ROWTYPE]
+*** xref:master/7.17.adoc[17、NLS 参数]
 ** IvorySQL贡献指南
 *** xref:master/8.1.adoc[社区贡献指南]
 *** xref:master/8.2.adoc[asciidoc语法快速参考]

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

@@ -0,0 +1,104 @@
+:sectnums:
+:sectnumlevels: 5
+
+:imagesdir: ./_images
+
+= %ROWTYPE、%TYPE
+
+== 目的
+
+IvorySQL提供了兼容Oracle的plsql数据类型功能，包括%TYPE、%ROWTYPE。
+
+== 实现说明
+
+=== 引用类型发生变化时，如何确保%TYPE声明的变量也随之相应改变
+
+这是一个被动的过程。 当前的实现方案是记录函数（存储过程）与 tablename.columname 的依赖关系。当引用类型发生变化时，根据依赖关系，让函数（存储过程）缓存失效。这样一来，函数被调用时就会执行强制编译。从而确保函数获取最新的变量类型。
+
+在系统表 pg_proc 中添加一个字段 prostatus 用来表示函数（存储过程）状态，有3种状态: validate(v)，invalidate(i)，N/A(n)。函数编译成功后，这个状态会被设置为valid。
+
+在解析函数内容时，plisql_parse_cwordtype，plisql_parse_wordrowtype，plisql_parse_cwordrowtype 等函数识别出%TYPE， %ROWTYPE引用的对象，并记录在 plisql_referenced_object 链表中，最后添加到 pg_depend 系统表中。
+
+增加一种新的依赖类型 DEPENDENCY_TYPE = 't'，表示%TYPE或%ROWTYPE依赖。在添加对象引用关系到pg_depend系统表时，设置依赖类型为 't'。
+
+对表进行操作时（修改表类型、删除表等），查看系统表pg_depend，如果存在依赖类型deptype=’t’，并且依赖对象是函数，则调用函数 plisql_free_function 删除函数缓存，并修改 pg_proc 系统表中的函数状态prostatus 为 N/A(n)。
+
+
+=== %TYPE声明的变量继承引用变量的约束
+
+在 PLiSQL_type 结构体中添加成员 bool notnull;
+
+```
+/*
+ * Postgres data type
+ */
+typedef struct PLiSQL_type
+{
+	bool		notnull;		/* the type is built by variable%type,
+								 * isnull or notnull of the variable */
+```
+
+在负责解析%TYPE类型函数的plisql_parse_wordtype或plisql_parse_cwordtype函数中，判断如果引用变量类型指定了NOT NULL约束，为返回的datatype的成员 bool notnull 属性赋值为true。
+在pl_gram.y 文件的 decl_statement 语法中，根据PLiSQL_type 的成员 bool notnull 为变量PLiSQL_variable *var的notnull属性赋值。这样就继承了引用变量的约束。
+
+
+=== 表名%ROWTYPE或视图名%ROWTYPE作为函数或存储过程的参数类型和函数返回值类型
+
+在 ora_gram.y 中为 func_type 添加%ROWTYPE支持。
+
+```
+| type_function_name attrs '%' ROWTYPE
+				{
+					$$ = makeTypeNameFromNameList(lcons(makeString($1), $2));
+					$$->row_type = true;
+					$$->location = @1;
+				}			
+```
+
+在 TypeName 结构体中添加成员 bool row_type 用来标记是否指定了%ROWTYPE。
+
+```
+typedef struct TypeName
+{
+	bool		pct_type;		/* %TYPE specified? */
+	bool		row_type;	/* %ROWTYPE specified? */
+```	
+	
+在 LookupTypeName 函数中，如果 TypeName 的成员 row_type 为 TRUE，则根据TypeName的成员names中获得schema名与表名，然后获取表的typeoid。
+
+=== INSERT语句增强
+
+在 ora_gram.y 中添加新的语法，支持 VALUES 后面不带括号’(‘。
+
+```
+values_clause_no_parens:
+			VALUES columnref
+				{
+					SelectStmt *n = makeNode(SelectStmt);
+					n->valuesLists = list_make1(list_make1($2));
+					n->valuesIsrow = true;
+					$$ = (Node *) n;
+				}
+```
+				
+为结构体 SelectStmt 添加一个字段 bool valuesIsrow 表示 values 是一个 row。
+
+在为insert语句做 transform 时，也就是函数 transformInsertStmt 中，在处理 INSERT ... VALUES 语句时，如果 valuesIsrow 为true，调用新函数 transformRowExpression，将 row_variable 转换成等价的 row_variable.field1,...,row_variable.fieldN。
+
+=== UPDATE语句增强
+
+在UPDATE语句做transform时候，也就是transformUpdateStmt的时候，如果是Oralce兼容模式，调用新添加的 transformIvyUpdateTargetList 函数。
+在这个新函数中，对于参数origTlist(即targetList)中没有名字为row的情况，按原来UPDATE的transform流程执行 transformUpdateTargetList 函数。
+
+对参数origTlist中有名字为row的情况：因为PostgreSQL中row可以作为列名，而Oracle 中row是保留关键字，不可以作为列名，所以需要区分row是否是表中的列，如果row不是要更新的表中的列，则调用新函数 transformUpdateRowTargetList 把语句
+```
+UPDATE table_name SET ROW = row_variable [WHERE …]; 
+```
+转换成等价的 
+```
+UPDATE table_name SET table_name.column1 = row_variable.column1, table_name.column2 = row_variable.filed2,… table_name.columnN = row_variable.columnN [WHERE …];
+```
+
+如果语句“UPDATE table_name SET ROW = row_variable”中的变量 row_variable不是组合类型，就按原来UPDATE的transform流程执行 transformUpdateTargetList 函数；
+如果语句中的变量 row_variable 是组合类型，表中的名为row的那一列也是组合类型，并且两者的类型Oid也一样，则按原来UPDATE的transform流程执行 transformUpdateTargetList 函数； 
+其他所有情况，调用新函数 transformUpdateRowTargetList 处理；

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

@@ -0,0 +1,159 @@
+
+:sectnums:
+:sectnumlevels: 5
+
+
+= **功能概述**
+
+IvorySQL提供了兼容Oracle的NLS参数功能，包含如下参数。
+
+[cols="3,7"]
+|====
+|*参数名称*|*功能描述*
+|ivorysql.datetime_ignore_nls_mask | 表示日期格式是否忽略NLS参数影响，默认为0。
+|nls_length_semantics | 兼容Oracle的同名参数，表示char/varchar/varchar2的类型修饰符的大小单位是字节还是字符。
+|nls_date_format | 表示默认的日期格式，可以通过show命令查看，默认为‘YYYY-MM-DD’。
+|nls_timestamp_format | 兼容Oracle的同名参数，控制带时间的日期格式。
+|nls_timestamp_tz_format | 兼容Oracle的同名参数，控制带时区的日期时间格式。
+|nls_territory | 兼容Oracle的同名参数，指定数据库的默认区域。
+|nls_iso_currency | 兼容Oracle的同名参数，指定的国家和区域制定唯一的货币符号。
+|nls_currency | 兼容Oracle的同名参数，指定显示本地货币的符号，对应数字字符串格式中占位符L。
+|====
+
+== 实现原理
+
+=== `nls_length_semantics` 参数
+
+IvorySQL中的数据类型存在一个属性修饰符 `typmod` ，是对类型的补充说明，比如在 `VARCHAR(n)` 类型中，`n` 就是类型修饰符。
+
+在创建或修改表的列时可以指定长度类型，例如:
+```c
+	ivorysql=# create table t1(name varchar2(2 byte));
+```
+
+对于列类型为 `CHAR` 、 `VARCHAR` 和 `VARCHAR2` 字符型的列，当没有显式指定列的长度类型时，IvorySQL使用 `nls_length_semantics` 参数的值来决定长度类型，有 `byte` 和 `char` 两种值，默认为 `byte` 。
+
+需要特别注意的是， `nls_length_semantics` 参数的值仅影响新创建的列，对已经存在的列不会产生任何影响。
+
+在语法解析文件 ora_gram.y中，存在如下代码来根据 `nls_length_semantics` 把原本的 `char/varchar/varchar2` 类型改成 `oracharchar` 或者 `oracharbyte` ：
+
+```c
+CharacterWithLength:  character '(' Iconst ')'
+				{
+					if (ORA_PARSER == compatible_db)
+					{
+						if (strcmp($1, "bpchar"))
+						{
+							if (nls_length_semantics == NLS_LENGTH_CHAR)
+								$1 = "oravarcharchar";
+							else
+								$1 = "oravarcharbyte";
+						}
+						else
+						{
+							if (nls_length_semantics == NLS_LENGTH_CHAR)
+								$1 = "oracharchar";
+							else
+								$1 = "oracharbyte";
+						}
+
+						$$ = OracleSystemTypeName($1);
+						$$->typmods = list_make1(makeIntConst($3, @3));
+						$$->location = @1;
+					}
+					else
+					{
+						...
+					}
+				}
+		;
+
+```
+
+IvorySQL 中数据类型 `oracharchar` 和 `oracharbyte` 的修饰符输入输出函数包括：
+```c
+oravarcharchartypmodout() 
+oravarcharbytetypmodout() 
+oracharbytetypmodout()
+oracharchartypmodout() 
+```
+
+上面这些函数调用C语言实现的函数 `anychar_typmodout()` ，后者根据 `nls_length_semantics` 的值来调整输出的内容是否包含 `byte/char` 的说明。
+
+`nls_length_semantics` 另一个作用是限制表中的列长度：
+根据上述代码在语法解析文件 ora_gram.y中，如果原本的 `varchar` 类型被转换成了 `oracharchar` 类型，则函数 `oravarcharchar()` 会被调用，而 `pg_mbcharcliplen()` 函数计算字符长度，而不是字节长度。
+
+```c
+Datum
+oravarcharchar(PG_FUNCTION_ARGS)
+{
+	VarChar    *source = PG_GETARG_VARCHAR_PP(0);
+	int32		typmod = PG_GETARG_INT32(1);
+	bool		isExplicit = PG_GETARG_BOOL(2);
+	int32		len,
+				maxlen;
+	size_t		maxmblen;
+	char	   *s_data;
+
+	len = VARSIZE_ANY_EXHDR(source);
+	s_data = VARDATA_ANY(source);
+	maxlen = typmod - VARHDRSZ;
+
+	/* No work if typmod is invalid or supplied data fits it already */
+	if (maxlen < 0 || len <= maxlen)
+		PG_RETURN_VARCHAR_P(source);
+
+	maxmblen = pg_mbcharcliplen(s_data, len, maxlen);
+
+	...
+}
+```
+
+=== GUC参数 `datetime_ignore_nls_mask`
+
+这个参数被定义为一个int值，低四位分别表示是否在相应的日期时间格式上忽略NLS参数的影响，掩码定义如下：
+```c
+#define ORADATE_MASK			0x01
+#define ORATIMESTAMP_MASK		0x02
+#define ORATIMESTAMPTZ_MASK		0x04
+#define ORATIMESTAMPLTZ_MASK	0x08
+```
+
+在源代码中，这个GUC参数被用于下面这些函数：
+```c
+oradate_in()
+oratimestamp_in()
+oratimestampltz_in()
+oratimestamptz_in()
+```
+
+如果相应的掩码被设置，则调用原生PG的处理函数，否则调用兼容代码并忽略NLS格式。
+
+=== GUC参数 `nls_date_format`/`nls_timestamp_format`/`nls_timestamp_tz_format`
+
+这三个GUC参数，在函数 `ora_do_to_timestamp()` 中做为格式字符串，对输入的字符串进行格式检查与模式识别。
+
+下面是其默认值，可以通过设置其值为"pg"使其失效。"pg"表示禁用NLS特定行为，恢复为PostgreSQL的默认行为。
+```c
+char	   *nls_date_format = "YYYY-MM-DD";
+char	   *nls_timestamp_format = "YYYY-MM-DD HH24:MI:SS.FF6";
+char	   *nls_timestamp_tz_format = "YYYY-MM-DD HH24:MI:SS.FF6 TZH:TZM";
+```
+
+=== GUC参数 `nls_currency`/`nls_iso_currency`/`nls_territory`
+
+目前，`nls_territory` 和 `nls_iso_currency` 支持CHINA与AMERICA两个值。
+
+默认值如下:
+
+```c
+char	   *nls_territory = "AMERICA";
+char	   *nls_currency = "$";
+char	   *nls_iso_currency = "AMERICA";
+```
+
+这三个参数将在oracle兼容函数 `to_number()` 中被使用。
+[NOTE]
+====
+`to_number()` 函数尚未实现。
+====