脚本使用手册 - 函数

下面是支持的函数列表

一、集合操作函数

LENGTH

功能：返回集合（Collection）的元素数量
适用场景：获取数组、列表、集合等容器对象的元素个数，用于循环控制、数据统计等

参数列表

参数名	类型	是否必填	默认值	说明
`Collection`	`Object`	否	`空列表 []`	要计算元素数量的集合对象（数组、字典、List、Set 等）

返回值

返回值类型	说明
`Integer`	返回集合中的元素数量（不存在时返回 `0`）

使用示例

w:set (arr = [1, 2, 3, 4, 5])
w:set (count = LENGTH(arr))
w:log("INFO", "数组长度: {}", count) // 输出: 5

GET

按下标访问集合元素，与 collection[index] 写法等价（字典按键访问请直接使用 collection[key] 语法）。

功能：返回集合（Collection）中指定索引位置的元素
适用场景：从数组、列表等集合中按索引获取特定元素，支持索引越界时返回默认值

参数列表

参数名	类型	是否必填	默认值	说明
`Collection`	`Object`	是	-	要获取元素的集合对象（支持 List、Set、Array 等）
`Index`	`Integer`	是	-	要获取的元素索引（从 0 开始）
`ValueIfOut`	`Object`	否	`null`	索引超出范围时返回的默认值

返回值

返回值类型	说明
`Object`	返回集合中指定索引的元素，索引越界时返回 `ValueIfOut`

使用示例

w:set (arr = ["Apple", "Banana", "Orange"])
w:set (first = GET(arr, 0))
w:set (second = GET(arr, 1))
w:log("INFO", "第一个: {}, 第二个: {}", first, second)
w:set (third = GET(arr, 2))     // "Orange"
w:set (third = arr[2])          // "Orange"

COLLECTION_ADD

功能：向集合中添加元素，返回添加后的新集合
适用场景：在循环或数据处理过程中向数组/列表追加元素，支持去重添加

参数列表

参数名	类型	是否必填	默认值	说明
`Collection`	`Object`	是	`空列表 []`	要添加元素的集合对象
`Item`	`Object`	是	`""`	要添加的新元素
`Distinct`	`Boolean`	否	`false`	是否去重：`true` 时集合中已存在相同元素则不重复添加

返回值

返回值类型	说明
`Object`	返回添加元素后的新集合（数组）

使用示例

w:set (arr = [1, 2, 3])
w:set (arr = COLLECTION_ADD(arr, 4))          // [1, 2, 3, 4]
w:set (arr = COLLECTION_ADD(arr, 4, true))    // 去重添加，结果仍为 [1, 2, 3, 4]

COLLECTION_CONTAINS

功能：判断集合中是否包含指定元素
适用场景：处理数组、列表等集合时，检查某个元素是否已存在

参数列表

参数名	类型	是否必填	默认值	说明
`Collection`	`Array`	是	`空列表 []`	要检查的集合对象
`Item`	`Object`	是	`""`	要查找的元素

返回值

返回值类型	说明
`Boolean`	集合中包含指定元素返回 `true`，否则返回 `false`

使用示例

w:set (arr = ["Apple", "Banana", "Orange"])
w:set (exists = COLLECTION_CONTAINS(arr, "Banana"))   // true
w:log("INFO", "是否包含 Banana: {}", exists)

二、XML 处理函数

XML_OPEN

功能：打开 XML 文件或直接解析 XML 字符串，返回文档根节点（DOM Document 对象）
适用场景：读取 XML 报文/文件后，配合 XPATH、XML_FETCH 等函数进行数据提取

参数列表

参数名	类型	是否必填	默认值	说明
`SOURCE`	`Object`	是	-	输入的 XML 内容或 XML 文件路径，支持 String 内容、String 路径、File 对象或 Path 对象
`TYPE`	`String`	否	`null`	指定 SOURCE 的类型：`CONTENTS`（内容）或 `PATH`（文件路径）；不传时若字符串是已存在的文件路径则自动按文件处理

返回值

返回值类型	说明
`Object`	返回 XML 文档根节点对象（`Document`），用于后续 XML 操作

使用示例

w:// 打开 XML 文件
w:set (xml_doc = XML_OPEN("D:/data/order.xml"))

w:// 解析 XML 字符串
w:set (xml_doc = XML_OPEN('<root><item>value</item></root>', "CONTENTS"))

注意事项

资源释放：推荐使用 try (...) 资源块自动关闭，或显式调用 XML_CLOSE，避免资源泄漏。

XML_FETCH

功能：遍历 XML 节点的子节点，将每个子节点的值写入以 _ 为前缀的变量（变量名为子节点名）。若子节点本身是值，变量值为字符串；若子节点还含有子节点，变量值为该子节点（NODE 类型），可继续嵌套调用 XML_FETCH
适用场景：需要将 XML 节点的各个子元素快速映射为变量名的批量数据处理

参数列表

参数名	类型	是否必填	默认值	说明
`XmlNode`	`Object`	是	-	XML 节点对象（由 `XML_OPEN`、`XPATH` 等返回）

返回值

返回值类型	说明
`Integer`	返回读取到的子节点数量（无子节点返回 `0`）

使用示例

text

w:
w:  {
w:      //   <ROOT>
w:      //     <abc>"value"</abc>
w:      //     <abc2>
w:      //       <child1>"value1"</child1>
w:      //       <child2>"value2"</child2>
w:      //       <child3>"value3"</child3>
w:      //     </abc2>
w:      //   </ROOT>
w:
w:      try (doc_root = XML_OPEN(xml_file_or_xml_string)) {
w:          if (XML_FETCH(doc_root) > 0) {
w:              {{ "" + _abc }}
w:
w:              if (XML_FETCH(_abc2) > 0) {
w:                  {{ "" + _child1 + _child2 + _child3 }}
w:              }
w:          }
w:      }
w:  }

XML_ENCODE

功能：对字符串进行 XML 转义（将 <、>、&、"、' 等特殊字符转换为 XML 实体）
适用场景：将文本内容拼接到 XML 报文前，对特殊字符进行转义，避免破坏 XML 结构

参数列表

参数名	类型	是否必填	默认值	说明
`STR`	`String`	否	`""`	需要进行 XML 转义的字符串

返回值

返回值类型	说明
`String`	返回转义后的 XML 字符串

使用示例

w:set (text = "A < B & C > D")
w:set (encoded = XML_ENCODE(text))
w:log("INFO", "转义后: {}", encoded)   // A &lt; B &amp; C &gt; D

XML_DECODE

功能：对 XML 实体字符串进行反转义（将 <、>、& 等实体还原为原始字符）
适用场景：从 XML 报文中读取到转义后的文本内容，需要还原为原始字符串时使用

参数列表

参数名	类型	是否必填	默认值	说明
`STR`	`String`	是	-	需要进行 XML 反转义的字符串

返回值

返回值类型	说明
`String`	返回反转义后的原始字符串

使用示例

w:set (xml_text = "A &lt; B &amp; C")
w:set (decoded = XML_DECODE(xml_text))
w:log("INFO", "反转义后: {}", decoded)   // A < B & C

XPATH

功能：按 XPath 表达式从 XML 节点取值，支持多种返回类型、候选路径和默认值
适用场景：从 XML 文档中提取指定路径的数据，支持取单一值、节点列表等

参数列表

参数名	类型	是否必填	默认值	说明
`XmlNode`	`Object`	是	-	XML 节点对象（由 `XML_OPEN`、`XPATH` 等返回）
`XPath`	`String`	是	-	要计算的 XPath 表达式
`ReturnType`	`String`	否	`STRING`	返回类型，可选值：`LONG`、`NUMBER`、`STRING`、`BOOLEAN`、`NODESET`、`NODE`、`DECIMAL`
`Candidate`	`String`	否	`null`	候选 XPath 表达式（当主 XPath 不存在或为空时使用）
`DefaultValue`	`String`	否	`null`	当 XPath 不存在或值为空时返回的默认值

返回值

返回值类型	说明
`Object`	返回 XPath 查询结果，类型由 `ReturnType` 参数决定

返回类型映射

ReturnType	返回类型	说明
`STRING`	`String`	返回字符串（默认）
`LONG`	`Long`	返回长整型（整数）
`NUMBER`	`Double`	返回双精度浮点数
`DECIMAL`	`BigDecimal`	返回高精度小数
`BOOLEAN`	`Boolean`	返回布尔值
`NODESET`	`Array`	返回节点列表（数组）
`NODE`	`Object`	返回单个节点对象

使用示例

获取单一值

w:set (po_number = XPATH(xml_doc, "/WorkbookEntity/Sheets/Sheet/Cells/Cell[@loc='A2']/text()"))

获取列表

w:set (TS_ITEMS = XPATH($xml_doc, $TS + "/NADLoop", "NODESET"))
w:for (TS_ITEM: $TS_ITEMS)
w:end

使用 Type 名称

w:set (quantity = XPATH(xml_doc, "/WorkbookEntity/Sheets/Sheet/Cells/Cell[@loc='D" + index + "']/text()", "STRING"))

NODE_TO_XML

功能：将 XML DOM 节点对象序列化为 XML 字符串
适用场景：对 XML 节点进行修改后，需要将节点重新输出为 XML 文本（不包含 XML 声明头，不缩进）

参数列表

参数名	类型	是否必填	默认值	说明
`XmlNode`	`Object`	是	-	XML 节点对象（由 `XML_OPEN`、`XPATH` 等返回）

返回值

返回值类型	说明
`String`	返回节点对应的 XML 字符串

使用示例

w:set (doc = XML_OPEN(xml_file))
w:set (node = XPATH(doc, "/Root/Item", "NODE"))
w:set (xml_str = NODE_TO_XML(node))
w:log("INFO", "节点 XML: {}", xml_str)   // <Item><Id>1</Id><Name>Tom</Name></Item>

注意事项

输出不包含 <?xml ... ?> 声明头，且不进行缩进格式化。
序列化前会移除节点中的空白文本节点。

XML_CLOSE

功能：关闭 XML 文档，释放资源
适用场景：在 try 资源块或脚本结束时显式关闭 XML 文档。XML 文档为内存管理对象，此函数实际不释放资源，固定返回 true

参数列表

参数名	类型	是否必填	默认值	说明
`XML_DOC`	`Object`	是	-	需要关闭的 XML 文档对象

返回值

返回值类型	说明
`Boolean`	固定返回 `true`

使用示例

text

w:  xml_doc = XML_OPEN("xml file path")
w:  order   = XPATH($xml_doc, "xpath")
{{ $order }}
w:  XML_CLOSE($xml_doc)

XML_TO_JSON

功能：将 XML 字符串转换为 JSON 字符串
适用场景：需要把 XML 报文转换为 JSON 结构处理时使用。转换规则：
节点名以 Loop 结尾（不区分大小写）的节点转换为 JSON 数组；
包含 type="array" 属性的对象节点，移除该属性后转换为 JSON 数组；
其他节点保持原样，递归处理子节点。

参数列表

参数名	类型	是否必填	默认值	说明
`XmlString`	`String`	是	-	输入的 XML 字符串

返回值

返回值类型	说明
`String`	返回转换后的 JSON 字符串（带缩进格式化）；输入为 `null` 时返回 `null`

使用示例

w:set (xml_str = FILE_READ("D:/data/order.xml"))
w:set (json_str = XML_TO_JSON(xml_str))
w:log("INFO", "JSON: {}", json_str)

OUT_XML_NODE

功能：根据节点名和文本值生成一个完整的 XML 节点字符串（<Name>Text</Name>），文本会自动进行 XML 转义
适用场景：手工拼接 XML 报文时，快速生成单个 XML 节点，避免遗漏转义

参数列表

参数名	类型	是否必填	默认值	说明
`Name`	`String`	是	`""`	XML 节点名；为空或 `"null"` 时返回空字符串
`Text`	`String`	否	`""`	XML 节点文本内容，会自动进行 XML 1.1 转义
`IgnoreEmpty`	`Boolean`	否	`false`	是否忽略空值：`true` 且文本为空时返回空字符串

返回值

返回值类型	说明
`String`	返回 `<Name>Text</Name>` 形式的 XML 节点字符串

使用示例

w:set (node1 = OUT_XML_NODE("OrderNo", "PO20260909001"))
w:log("INFO", "{}", node1)   // <OrderNo>PO20260909001</OrderNo>

w:set (node2 = OUT_XML_NODE("Remark", "", true))   // 空值且忽略，返回 ""
w:set (node3 = OUT_XML_NODE("Desc", "A < B"))      // <Desc>A &lt; B</Desc>

三、XML VTD 处理函数

XML_OPEN_VTD

功能：使用 VTD-XML 解析器打开 XML 文件或 XML 内容，返回 XML 上下文对象
适用场景：需要高效解析和处理 XML 文件时，支持 XPath 查询、增量读取等操作

参数列表

参数名	类型	是否必填	默认值	说明
`Source`	`Object`	是	-	指定输入的 XML 内容或 XML 文件路径，支持 String 内容、String 路径、File 对象或 Path 对象

返回值

返回值类型	说明
`Object`	返回 VTD-XML 上下文对象（`XmlVTDContext`），用于后续 XML 操作

返回值对象属性

属性名	类型	说明
`_parser`	`VTDGen`	VTD-XML 解析器对象
`_navigator`	`VTDNav`	VTD-XML 导航器对象
`_selector`	`AutoPilot`	XPath 选择器对象
`_xpath`	`String`	当前 XPath 表达式

注意事项

资源释放：推荐使用 try (...) 资源块自动关闭，或显式调用 XML_CLOSE_VTD，避免资源泄漏。

XPATH_VTD

功能：使用 VTD-XML 解析器执行 XPath 查询，获取 XML 节点值
适用场景：从 XML 文档中提取指定路径的数据，支持默认值、候选路径和多种返回类型

参数列表

参数名	类型	是否必填	默认值	说明
`Context`	`Object`	是	-	XML-VTD 上下文对象（由 `XML_OPEN_VTD` 返回）或 DOM Node 对象
`XPath`	`String`	是	-	要计算的 XPath 表达式
`ReturnType`	`String`	否	`STRING`	指定返回类型：`STRING`、`LONG`、`NUMBER`、`DECIMAL`、`BOOLEAN`
`Candidate`	`String`	否	`null`	候选 XPath 表达式（当主 XPath 不存在或为空时使用）
`DefaultValue`	`Object`	否	`null`	当 XPath 不存在或值为空时返回的默认值

返回值

返回值类型	说明
`Object`	返回 XPath 查询结果，类型由 `ReturnType` 参数决定

返回类型映射

ReturnType	返回类型	说明
`STRING`	`String`	返回字符串（默认）
`LONG`	`Long`	返回长整型（整数）
`NUMBER`	`Double`	返回双精度浮点数
`DECIMAL`	`BigDecimal`	返回高精度小数
`BOOLEAN`	`Boolean`	返回布尔值

XPATH_VTD_MOVE

功能：将 VTD-XML 游标移动到 XPath 指定的节点位置
适用场景：需要在 XML 文档中定位到特定节点，为后续的节点遍历、读取或更新操作做准备

参数列表

参数名	类型	是否必填	默认值	说明
`Context`	`Object`	是	-	XML-VTD 上下文对象（由 `XML_OPEN_VTD` 返回）
`XPath`	`String`	是	-	要定位的 XPath 表达式

返回值

返回值类型	说明
`Boolean`	移动成功返回 `true`，否则返回 `false`

XML_CLOSE_VTD

功能：关闭 VTD-XML 上下文对象并释放相关资源
适用场景：在完成 XML 文档操作后，调用此方法释放 VTD-XML 解析器占用的内存资源，避免内存泄漏

参数列表

参数名	类型	是否必填	默认值	说明
`XmlVTD`	`Object`	是	-	需要关闭的 XML-VTD 上下文对象（由 `XML_OPEN_VTD` 返回）

返回值

返回值类型	说明
`Boolean`	关闭成功返回 `true`

四、JSON 处理函数

JSON_OPEN

功能：打开 JSON 文件或直接解析 JSON 字符串，返回 JSON 节点对象
适用场景：读取 JSON 报文/文件后，配合 JSON_PATH、JSON_FETCH、JSON_IS_ARRAY 等函数进行数据提取

参数列表

参数名	类型	是否必填	默认值	说明
`SOURCE`	`Object`	是	-	输入的 JSON 内容、JSON 文件路径，支持 String 内容、String 路径、File 对象或 Path 对象
`TYPE`	`String`	否	`null`	指定 SOURCE 的类型：`CONTENTS`（内容）或 `PATH`（文件路径）；不传时若字符串是已存在的文件路径则自动按文件处理

返回值

返回值类型	说明
`Object`	返回 JSON 节点对象（`JsonNode`），用于后续 JSON 操作

使用示例

w:// 打开 JSON 文件
w:set (json_doc = JSON_OPEN("D:/data/order.json"))

w:// 解析 JSON 字符串
w:set (json_doc = JSON_OPEN('{"id":1,"name":"Tom"}', "CONTENTS"))

注意事项

资源释放：推荐使用 try (...) 资源块自动关闭，或显式调用 JSON_CLOSE，避免资源泄漏。

JSON_FETCH

遍历 JSON 节点的所有子节点，将每个子节点的值写入以 _ 为前缀的变量（变量名为子节点名）。若子节点本身包含下级节点，变量值为子节点集合，可继续嵌套调用 JSON_FETCH；否则变量值为子节点的字符串值。返回读取到的子节点数。

功能：提取当前 JSON 节点的所有子节点为变量
适用场景：需要将 JSON 对象的各个字段快速映射为变量名的批量数据处理

参数列表

参数名	类型	是否必填	默认值	说明
`JsonNode`	`Object`	是	-	JSON 节点对象（由 `JSON_OPEN` 返回）

返回值

返回值类型	说明
`Integer`	返回读取到的子节点数量

使用示例

text

w:
w:  {
w:      try (json_doc = JSON_OPEN(json_file_or_json_string)) {
w:          if (JSON_FETCH(json_doc) > 0) {
w:              {{ "" + _id + _name }}
w:          }
w:      }
w:  }

JSON_ENCODE

功能：对字符串进行 JSON 转义（将 "、\、换行、制表符等特殊字符转换为 JSON 转义形式）
适用场景：将文本内容拼接到 JSON 报文中前，对特殊字符进行转义

参数列表

参数名	类型	是否必填	默认值	说明
`STR`	`String`	否	`""`	需要进行 JSON 转义的字符串

返回值

返回值类型	说明
`String`	返回转义后的 JSON 字符串

使用示例

w:set (text = "He said \"Hello\"\nNext line")
w:set (encoded = JSON_ENCODE(text))

JSON_DECODE

功能：对 JSON 转义字符串进行反转义，还原为原始字符串
适用场景：从 JSON 报文中读取到转义后的文本内容，需要还原原始字符时使用

参数列表

参数名	类型	是否必填	默认值	说明
`STR`	`String`	是	-	需要进行 JSON 反转义的字符串

返回值

返回值类型	说明
`String`	返回反转义后的原始字符串

使用示例

w:set (json_text = "He said \\\"Hello\\\"")
w:set (decoded = JSON_DECODE(json_text))

JSON_PATH

功能：按路径从 JSON 文档取值，支持多种返回类型、候选路径和默认值
适用场景：从 JSON 文档中提取指定路径的数据，支持取单一值、节点列表等

参数列表

参数名	类型	是否必填	默认值	说明
`JsonNode`	`Object`	是	-	JSON 节点对象（由 `JSON_OPEN`、`JSON_PATH` 等返回）
`JsonPath`	`String`	是	-	要计算的 JSON Path 表达式
`ReturnType`	`String`	否	`STRING`	返回类型，可选值：`LONG`、`NUMBER`、`STRING`、`BOOLEAN`、`NODESET`、`NODE`、`DECIMAL`
`Candidate`	`String`	否	`null`	候选 JSON Path 表达式（当主路径不存在或为空时使用）
`DefaultValue`	`String`	否	`null`	当 JSON Path 不存在或值为空时返回的默认值

返回值

返回值类型	说明
`Object`	返回 JSON Path 查询结果，类型由 `ReturnType` 参数决定

返回类型映射

ReturnType	返回类型	说明
`STRING`	`String`	返回字符串（默认）
`LONG`	`Long`	返回长整型
`NUMBER`	`Double`	返回双精度浮点数
`DECIMAL`	`Decimal`	返回高精度小数
`BOOLEAN`	`Boolean`	返回布尔值
`NODESET`	`Array`	返回节点列表（数组）
`NODE`	`Object`	返回单个节点对象

使用示例

text

w:  DOC_ITEMS = []
w:  if (JSON_IS_ARRAY($json_doc)) {
w:    DOC_ITEMS = JSON_PATH($json_doc, "", "NODESET")
w:  } else {
w:    DOC_ITEMS = [JSON_PATH($json_doc, "", "NODE")]
w:  }

JSON_IS_ARRAY

功能：判断 JSON 节点（按指定路径）是否为数组类型
适用场景：在遍历 JSON 文档前判断根节点或子节点是数组还是对象，以决定使用 NODESET 还是 NODE 方式取值

参数列表

参数名	类型	是否必填	默认值	说明
`JsonNode`	`Object`	是	-	JSON 节点对象（由 `JSON_OPEN` 返回）
`JsonPath`	`String`	否	`""`	要判断的 JSON Path 表达式；为空时判断当前节点

返回值

返回值类型	说明
`Boolean`	节点为数组类型返回 `true`，否则返回 `false`

使用示例

text

w:  if (JSON_IS_ARRAY($json_doc)) {
w:    DOC_ITEMS = JSON_PATH($json_doc, "", "NODESET")
w:  } else {
w:    DOC_ITEMS = [JSON_PATH($json_doc, "", "NODE")]
w:  }

NODE_TO_JSON

功能：将 JSON 节点对象序列化为 JSON 字符串
适用场景：对 JSON 文档处理完成后，需要将整个 JSON 文档输出为 JSON 文本时使用

参数列表

参数名	类型	是否必填	默认值	说明
`JsonNode`	`Object`	是	-	JSON 节点对象（由 `JSON_OPEN` 返回）

返回值

返回值类型	说明
`String`	返回整个 JSON 文档对应的 JSON 字符串；输入为 `null` 时返回 `null`

使用示例

w:set (json_doc = JSON_OPEN(json_str))
w:set (json_text = NODE_TO_JSON(json_doc))
w:log("INFO", "JSON 文本: {}", json_text)

JSON_CLOSE

功能：关闭 JSON 文档（占位函数，保持与 XML/CSV 等资源类函数一致的写法）
适用场景：在 try 资源块或脚本结束时显式关闭 JSON 文档。JSON 文档为内存管理对象，此函数实际不释放资源，固定返回 true

参数列表

参数名	类型	是否必填	默认值	说明
`JSON_DOC`	`Object`	是	-	需要关闭的 JSON 文档对象

返回值

返回值类型	说明
`Boolean`	固定返回 `true`

JSON_TO_XML

功能：将 JSON 字符串转换为 XML 字符串
适用场景：需要把 JSON 报文转换为 XML 报文时使用。若 JSON 根节点为数组，会自动包装到 <data> 根元素下；输出不包含 XML 声明头

参数列表

参数名	类型	是否必填	默认值	说明
`JsonString`	`String`	是	-	输入的 JSON 字符串

返回值

返回值类型	说明
`String`	返回转换后的 XML 字符串（带缩进格式化）；输入为 `null` 时返回 `null`

使用示例

w:set (json_str = '{"order":{"id":"PO001","name":"Tom"}}')
w:set (xml_str = JSON_TO_XML(json_str))
w:log("INFO", "XML: {}", xml_str)

JSON_CHECK

功能：检查给定数据是否为合法的 JSON 格式
适用场景：在解析外部数据前校验其是否为有效 JSON，避免解析失败

参数列表

参数名	类型	是否必填	默认值	说明
`SOURCE`	`Object`	是	-	待检查的数据，支持 JSON 节点对象、JSON 字符串、File 对象或 Path 对象；为 `null` 时返回 `false`

返回值

返回值类型	说明
`Boolean`	数据为合法 JSON 返回 `true`，否则返回 `false`（异常信息会输出到日志）

使用示例

w:set (content = FILE_READ("D:/data/message.dat"))
w:if (JSON_CHECK(content))
w:  set (json_doc = JSON_OPEN(content, "CONTENTS"))
w:else
w:  log("WARN", "内容不是合法的 JSON")
w:end

五、CSV 处理函数

CSV_OPEN

功能：打开 CSV 文件，返回 CSV 读取器对象（CSVParser）
适用场景：读取 CSV 文件时，通过此方法获取读取器，配合 CSV_NEXT、CSV_READ 遍历数据

参数列表

参数名	类型	是否必填	默认值	说明
`CSVFile`	`Object`	是	-	输入的 CSV 文件，支持 String 路径、File 对象或 Path 对象
`Format`	`String`	否	`default`	CSV 解析格式，可选值：`DEFAULT`、`EXCEL`、`INFORMIX_UNLOAD`、`INFORMIX_UNLOAD_CSV`、`MONGODB_CSV`、`MONGODB_TSV`、`MYSQL`、`ORACLE`、`POSTGRESQL_CSV`、`POSTGRESQL_TEXT`、`RFC4180`
`Charset`	`String`	否	`utf-8`	CSV 文件字符集
`Delimiter`	`String`	否	`,`	分隔符字符
`Quoter`	`String`	否	`"`	引用符字符
`SkipHeader`	`Boolean`	否	`true`	是否忽略表头；`true` 时跳过首行表头

返回值

返回值类型	说明
`Object`	返回 CSV 读取器对象（`CSVParser`）

使用示例

text

w:  csv_doc  = CSV_OPEN("csv file path")
w:  csv_iter = CSV_NEXT($csv_doc)
w:  while ($csv_iter != null) {
w:    column1 = CSV_READ($csv_iter, 1)
w:    column2 = CSV_READ($csv_iter, 2)
  {{ $column1 }} {{ $column2 }}
w:  }
w:  CSV_CLOSE(csv_doc)

注意事项

资源释放：推荐使用 try (...) 资源块自动关闭，或显式调用 CSV_CLOSE，避免资源泄漏。

CSV_NEXT

功能：将游标移动到下一行，返回当前行记录对象；无更多行时返回 null
适用场景：遍历 CSV 文件数据时，逐行获取记录

参数列表

参数名	类型	是否必填	默认值	说明
`CSVReader`	`Object`	是	-	CSV 读取器对象（由 `CSV_OPEN` 返回）
`FetchSize`	`Integer`	否	`1`	每次移动的行数

返回值

返回值类型	说明
`Object`	返回当前行记录对象（`CSVRecord`）；到达文件末尾时返回 `null`

使用示例

text

w:  csv_iter = CSV_NEXT($csv_doc)
w:  while ($csv_iter != null) {
w:    column1 = CSV_READ($csv_iter, 1)
  {{ $column1 }}
w:  }

CSV_READ

功能：读取当前行指定列的值（列号从 1 开始）
适用场景：从 CSV_NEXT 返回的行记录中按列号提取字段值

参数列表

参数名	类型	是否必填	默认值	说明
`CSVRecord`	`Object`	是	-	行记录对象（由 `CSV_NEXT` 返回）
`Column`	`Integer`	是	-	列索引（从 1 开始）

返回值

返回值类型	说明
`String`	返回指定列的字符串值

使用示例

text

w:  csv_iter = CSV_NEXT($csv_doc)
w:  column1 = CSV_READ($csv_iter, 1)
w:  column2 = CSV_READ($csv_iter, 2)

CSV_CLOSE

功能：关闭 CSV 文档，释放资源
适用场景：在完成 CSV 文件操作后，调用此方法释放读取器占用的资源

参数列表

参数名	类型	是否必填	默认值	说明
`CSVReader`	`Object`	是	-	需要关闭的 CSV 读取器对象（由 `CSV_OPEN` 返回）

返回值

返回值类型	说明
`Boolean`	固定返回 `true`

使用示例

text

w:  CSV_CLOSE(csv_doc)

六、数据库操作函数

DB_LOAD

功能：加载外部JDBC驱动JAR文件 适用场景：需要动态加载数据库驱动JAR文件的场景

参数列表

参数名	类型	是否必填	默认值	说明
`JDBCJar`	`String`	是	-	JDBC驱动JAR文件路径
`DriverClass`	`String`	否	`null`	JDBC驱动类全名

返回值

返回值类型	说明
`Object`	返回加载的JDBC驱动对象

使用示例

// 示例1：加载外部的MySQL JDBC默认的驱动类（假设用户已经把jar文件上传到EDI_APP_DATA目录下）
w:expr (DB_LOAD(${EDI_APP_DATA} + "mysql-connector-java-8.0.28.jar"))

// 示例2：加载外部的Oracle JDBC指定的驱动类（假设用户已经把jar文件上传到EDI_APP_DATA目录下）
w:expr (DB_LOAD(${EDI_APP_DATA} + "lib/ojdbc10.jar", "oracle.jdbc.driver.OracleDriver"))

注意事项

加载驱动：函数已提前加载PostgreSQL, SQLServer和SQLite JDBC驱动，无须使用此方法来加载它们。
加载驱动类：驱动类可以不指定, 函数会自动地从指定的JDBC-jar中检索。

DB_CONN

功能：打开数据库连接，返回可操作的数据库连接对象。
适用场景：需要通过JDBC连接数据库的场景（如PostgreSQL, SQLServer, MySQL、Oracle等关系型数据库）。

参数列表

参数名	类型	是否必填	默认值	说明
`ConnUrl`	`String`	是	-	JDBC连接URL（如：`jdbc:mysql://localhost:3306/db`）。
`User`	`String`	否	`null`	数据库用户名。
`Password`	`String`	否	`null`	数据库密码。

返回值

返回值类型	说明
`Object`	返回已建立的数据库连接对象，可直接用于执行SQL操作。

使用示例

// 示例1：连接PostgreSQL数据库（无须提前加载驱动）
w:set (conn = DB_CONN("jdbc:postgresql://localhost:5432/mydb", "myUsername", "myPassword"))
    ...
w:expr (DB_CLOSE(conn))

// 示例2：连接MySQL数据库（须提前加载驱动，假设用户已经把jar文件上传到EDI_APP_DATA目录下）
w:expr (DB_LOAD(${EDI_APP_DATA} + "/lib/mysql-connector-java-8.0.28.jar"))
w:set (conn = DB_CONN("jdbc:mysql://localhost:3306/mydb", "myUsername", "myPassword"))
    ...
w:expr (DB_CLOSE(conn))

注意事项

资源释放：推荐使用 try (...) 资源块自动关闭，或显式调用 DB_CLOSE，避免资源泄漏。

DB_STMT

功能：创建数据库语句对象，用于执行SQL查询
适用场景：需要通过连接对象创建Statement或PreparedStatement时使用

参数列表

参数名	类型	是否必填	默认值	说明
`Conn`	`Object`	是	-	有效的数据库连接对象
`SQL`	`String`	否	`null`	要预编译的SQL语句（不传则创建普通Statement）

返回值

返回值类型	说明
`Object`	返回Statement/PreparedStatement对象

使用示例

// 示例1：创建普通Statement
w:set (pstmt = DB_STMT(conn))
  ...
w:expr (DB_CLOSE(pstmt))

// 示例2：创建PreparedStatement
w:set (pstmt = DB_STMT(conn, "SELECT * FROM users WHERE id=?"))
  ...
w:expr (DB_CLOSE(pstmt))

注意事项

连接有效性：传入的连接对象必须处于打开状态
SQL预编译：当提供SQL参数时会创建PreparedStatement
资源释放：调用方需负责关闭语句，避免资源泄漏。

DB_QUERY

功能：执行数据库查询并返回结果集
适用场景：需要通过Statement或PreparedStatement执行SQL查询并获取结果

参数列表

参数名	类型	是否必填	默认值	说明
`Stmt`	`Object`	是	-	有效的Statement/PreparedStatement对象
`Query`	`String`	否	`null`	要执行的SQL语句（动态SQL时使用）
`Params`	`Array`	否	`null`	SQL参数值数组（需与Query配合使用）

返回值

返回值类型	说明
`Object`	返回ResultSet结果集对象

使用示例

// 示例1：使用Statement执行查询
w:set (stmt = DB_STMT(conn))
w:set (rs = DB_QUERY(stmt, "SELECT * FROM users"))
  ...
w:expr (DB_CLOSE(rs))

// 示例2：使用PreparedStatement执行动态查询
w:set (pstmt = DB_STMT(conn, "SELECT * FROM users WHERE height > ? AND age > ?"))
w:set (rs = DB_QUERY(pstmt, null, [180, 18]))
  ...
w:expr (DB_CLOSE(rs))

注意事项

参数绑定：Params数组元素顺序必须与SQL中的?占位符对应
资源释放：调用方需负责关闭结果集，避免资源泄漏。

DB_CLOSE

功能：关闭数据库连接、语句或结果集对象，释放资源。
适用场景：需要手动释放JDBC资源（如Connection/Statement/ResultSet）的场景。

参数列表

参数名	类型	是否必填	默认值	说明
`ObjectToClose`	`Object`	是	-	需要被释放资源的对象。

返回值

返回值类型	说明
`Bool`	返回关闭操作结果（`true`=成功，`false`=失败）。

使用示例

// 示例1：关闭结果集对象
w:expr (DB_CLOSE(rs))

// 示例2：关闭语句对象
w:expr (DB_CLOSE(stmt))

// 示例3：关闭连接对象
w:expr (DB_CLOSE(conn))

注意事项

关闭顺序：推荐关闭顺序 ResultSet → Statement → Connection

七、结果集处理函数

RS_OPEN

打开数据库查询，返回结果集句柄。通常配合 try 资源块在结束时自动释放。

功能：基于已有的数据库连接对象或直接通过 JDBC URL 建立连接并执行查询，返回结果集上下文
适用场景：需要快速建立数据库连接并获取查询结果的场景

参数列表

参数名	类型	是否必填	默认值	说明
`ConnOrUrl`	`Object`	是	-	数据库连接对象（`Connection`/`DbConnection`）或 JDBC 连接 URL 字符串（如：`jdbc:mysql://host:port/db`）
`Query`	`String`	是	-	要执行的SQL查询语句
`Params`	`Array`	否	`null`	SQL查询参数数组（与 SQL 中的 `?` 占位符按顺序对应）
`User`	`String`	否	`null`	数据库用户名（仅当第一个参数为 URL 字符串时生效）
`Password`	`String`	否	`null`	数据库密码（仅当第一个参数为 URL 字符串时生效）

返回值

返回值类型	说明
`Object`	返回包含结果集的数据库上下文对象

使用示例

// 示例1：查询PostgreSQL数据库
w:set (context = RS_OPEN("jdbc:postgresql://localhost:3306/mydb", "SELECT * FROM products"))
    ...
w:expr (RS_CLOSE(context))

// 示例2：带参数查询PostgreSQL数据库
w:set (context = RS_OPEN("jdbc:postgresql://localhost:3306/mydb", "SELECT * FROM users WHERE height > ? AND age > ?", [180, 18]))
    ...
w:expr (RS_CLOSE(context))

// 示例3：查询指定的MySQL数据库（须提前加载驱动，假设用户已经把jar文件上传到EDI_APP_DATA目录下）
w:expr (DB_LOAD(${EDI_APP_DATA} + "/lib/mysql-connector-java-8.0.28.jar"))
w:set (context = RS_OPEN("jdbc:mysql://localhost:3306/mydb", "SELECT * FROM users WHERE height > ? AND age > ?", [180, 18], "myUsername", "myPassword"))
    ...
w:expr (RS_CLOSE(context))

注意事项

参数绑定：Params数组元素顺序必须与SQL中的?占位符对应
资源释放：推荐使用 try (...) 资源块自动关闭，或显式调用 RS_CLOSE，避免资源泄漏
共享连接：当第一个参数传入外部已有的连接对象时，RS_CLOSE 只关闭语句和结果集，不会关闭该共享连接；传入 URL 字符串时由本函数创建的连接会一并关闭。

RS_NEXT

功能：移动结果集游标到下一行
适用场景：遍历数据库查询结果时使用

参数列表

参数名	类型	是否必填	默认值	说明
`ResultSetOrContext`	`Object`	是	-	结果集对象或数据库上下文对象

返回值

返回值类型	说明
`Bool`	`true`表示有下一行数据，`false`表示已到达结果集末尾

使用示例

// 示例1：基本用法
w:while (RS_NEXT(rs))
    ...
w:end

// 示例2：结合上下文对象使用
w:while (RS_NEXT(context))
    ...
w:end

注意事项

资源管理：不要在已关闭的结果集上调用。

RS_FETCH

将游标移动到结果集的下一行，并把当前行每一列的值写入以 _ 为前缀的变量（变量名为列名，值类型由数据库决定）。存在下一行返回 true，结果集结束返回 false。

功能：下移结果集游标并提取当前行的所有列值转换为变量 适用场景：遍历查询结果，将整行数据快速映射到变量名的批量数据处理

参数列表

参数名	类型	是否必填	默认值	说明
`ResultSetOrContext`	`Object`	是	-	结果集对象或数据库上下文对象

返回值

返回值类型	说明
`Bool`	`true`表示成功提取并存在下一行，`false`表示结果集结束

使用示例

text

w:
w:  {
w:      //   +-----------------+
w:      //   | Id | Name | Age |
w:      //   +-----------------+
w:      //   | 1  | Tom  | 20  |
w:      //   | 2  | Jack | 30  |
w:      //   | 3  | John | 40  |
w:      //   +-----------------+
w:
w:      try (rs1 = RS_OPEN(db_urls, "<SQL_QUERY>", ["<PARAMETER_SET>"])) {
w:          // 列值自动转为以下划线加上列名为名字的变量，如果列被指定了别名则是下划线加上列的别名
w:          while (RS_FETCH(rs1)) {
w:              {{ "" + _Id + _Name + _Age }}
w:          }
w:      }
w:  }

注意事项

列名包含特殊字符：使用AS给列设置别名（如SELECT col AS my_col）
变量名冲突：通过列别名重命名
遇到特殊类型列：配合使用RS_GET来转换数据

RS_GET

功能：从数据库结果集中读取指定列的值
适用场景：需要从查询结果中提取特定列数据时使用

参数列表

参数名	类型	是否必填	默认值	说明
`Context`	`Object`	是	-	通过`DB_OPEN`获取的数据库上下文对象
`Column`	`Object`	是	-	列索引(从1开始)或列名字符串
`DataType`	`String`	否	`VARCHAR`	指定返回值的JDBC数据类型可选值： `VARCHAR`, `BIT`, `BOOLEAN`, `TINYINT`, `SMALLINT`, `INTEGER`, `BIGINT`, `FLOAT`, `REAL`, `DOUBLE`, `NUMERIC`, `DECIMAL`, `CHAR`, `LONGVARCHAR`, `DATE`, `TIME`, `TIMESTAMP`

返回值

返回值类型	说明
`Object`	返回指定列的值

使用示例

// 示例1：按列名获取字符串值
name = RS_GET(ctx, "username", "VARCHAR")

// 示例2：按索引获取整数值
age = RS_GET(ctx, 2, "INTEGER")

// 示例3：获取日期值（使用默认VARCHAR类型）
date = RS_GET(ctx, "create_time")

注意事项

列指定方式：列索引从1开始；列名大小写敏感。
数据类型转换：类型不匹配会导致转换异常。

RS_CLOSE

功能：关闭由RS_OPEN函数返回的数据库上下文对象。
适用场景：需要手动释放数据库上下文资源的场景。

参数列表

参数名	类型	是否必填	默认值	说明
`ObjectToClose`	`Object`	是	-	需要被释放资源的对象。

返回值

返回值类型	说明
`Bool`	返回关闭操作结果（`true`=成功，`false`=失败）。

使用示例

// 示例1：关闭包含结果集的数据库上下文对象
w:expr (RS_CLOSE(context))

八、Excel 处理函数

EXCEL_OPEN

功能：打开Excel文件并返回Excel上下文对象。
适用场景：需要读取或操作Excel文件时，通过此方法获取上下文，支持 xls 和 xlsx 两种格式。

参数列表

参数名	类型	是否必填	默认值	说明
`ExcelFile`	`Object`	是	-	指定输入的Excel文件，接受String路径、File对象或Path对象
`ExcelFormat`	`String`	否	`xlsx`	指定Excel文件格式，接受`xls`或`xlsx`字符串值（不区分大小写）

返回值

返回值类型	说明
`Object`	返回Excel上下文对象（`ExcelContext`），包含工作簿、工作表、行等操作接口

使用示例

// 示例
w:try (excel_open_file = EXCEL_OPEN(${O_FILE})){
    ......
w:}

注意事项

文件格式：如果不指定 ExcelFormat 参数，默认按 xlsx 格式处理。对于 xls 文件，需明确指定格式为 "xls"，否则会抛出异常。
文件存在性：确保目标Excel文件存在且可读。
资源管理：推荐使用 try (...) 资源块自动关闭，或显式调用 EXCEL_CLOSE，避免资源泄漏。ExcelContext 实现了 AutoCloseable 接口。
参数类型：ExcelFile 参数支持 String、File、Path 三种类型，传入其他类型会抛出异常。
内存占用：大文件操作时注意内存使用（尤其是 xlsx 格式），建议操作完成后及时关闭上下文。
返回值对象生命周期：返回的上下文对象在调用 EXCEL_CLOSE 后即失效，不可再使用。

EXCEL_READ

功能：从Excel文件中读取指定工作表和单元格的值
适用场景：需要读取Excel文件中特定单元格的数据时，通过Excel上下文对象和单元格定位参数获取值

参数列表

参数名	类型	是否必填	默认值	说明
`ExcelContext`	`Object`	是	-	Excel上下文对象（由`EXCEL_OPEN`返回）
`SheetName`	`String`	是	-	工作表名称，指定从哪个Sheet读取数据
`CellAddressOrRowNumber`	`Object`	是	-	单元格地址（如"A1"）或行号（从0开始），二选一方式定位
`ColumnNumber`	`Integer`	否	`0`	列号（从0开始），当`CellAddressOrRowNumber`为行号时必填

返回值

返回值类型	说明
`Object`	返回单元格的值，类型根据单元格内容动态决定（String/Double/Boolean/DateTime/Null）

使用示例

w:set (TITLE = EXCEL_READ(excel_open_file, "Sheet1", "A1"))

注意事项

上下文有效性：传入的ExcelContext必须是有效的（未调用EXCEL_CLOSE），否则方法会抛出异常。
参数二选一：CellAddressOrRowNumber支持两种传参方式：- - 传入String类型：作为单元格地址（如"A1"、"B5"）。
传入数值类型：作为行号，此时需配合ColumnNumber参数指定列号。
Sheet缓存优化：同一上下文连续读取同一Sheet时，不会重复获取Sheet对象，提升性能。
行缓存优化：同一上下文连续读取同一行时，不会重复获取Row对象，提升性能。
日期处理：Excel中的日期单元格会被解析为LocalDateTime对象，而非数值。
公式处理：公式单元格会自动计算公式结果并返回计算后的值。
空值处理：空单元格或空行返回null，不会抛出异常。
列号默认值：当使用行号方式且不指定ColumnNumber时，默认读取第0列。

EXCEL_NUM_OF_ROWS

功能：读取Excel文件中指定工作表的总行数
适用场景：需要获取Excel工作表的行数时，用于遍历数据前的边界判断或数据统计

参数列表

参数名	类型	是否必填	默认值	说明
`ExcelContext`	`Object`	是	-	Excel上下文对象（由`EXCEL_OPEN`返回）
`SheetName`	`String`	是	-	工作表名称，指定要统计行数的Sheet

返回值

返回值类型	说明
`Integer`	返回指定Sheet的总行数（从1开始计数）

使用示例

......
w:set (TOTAL_ROWS = EXCEL_NUM_OF_ROWS(excel_open_file, "Sheet1"))
......

注意事项

上下文有效性：传入的ExcelContext必须是有效的（未调用EXCEL_CLOSE），否则方法会抛出异常。
Sheet缓存优化：同一上下文连续查询同一Sheet的行数时，不会重复获取Sheet对象，提升性能。
行数计算特点：POI的getLastRowNum()返回的是最后一行有内容或曾经有内容的行的索引（从0开始），所以总行数 = lastRowNum + 1。
空表判断：如果工作表完全为空（lastRowNum = -1），则返回 0。
性能考虑：此方法只获取行数信息，不会加载所有行数据，性能开销小。
配合遍历使用：常用于EXCEL_READ配合循环遍历所有行数据时的边界控制。
线程安全：此方法非线程安全，同一ExcelContext不应在多线程中同时操作。

EXCEL_CLOSE

功能：关闭Excel上下文并释放相关资源
适用场景：在完成Excel文件操作后，调用此方法释放工作簿资源，避免内存泄漏

参数列表

参数名	类型	是否必填	默认值	说明
`ExcelContext`	`Object`	是	-	需要关闭的Excel上下文对象（由`EXCEL_OPEN`返回）

返回值

返回值类型	说明
`Boolean`	关闭成功返回 `true`

使用示例

w:set (result = EXCEL_CLOSE(excel_open_file))

注意事项

资源释放：EXCEL_CLOSE会关闭底层的工作簿（Workbook）并释放内存资源，调用后ExcelContext对象将失效
可重复调用：多次调用EXCEL_CLOSE不会抛出异常（内部做了空值判断），但建议只调用一次
内存管理：对于大文件，及时调用EXCEL_CLOSE可以显著降低内存占用
上下文失效：关闭后的上下文对象不可再传递给EXCEL_READ等方法，否则会抛出异常

九、日期时间函数

NOW

功能：返回当前系统时间戳
适用场景：获取脚本执行时刻的当前时间，常用于日期计算、日志记录等

参数列表

无参数

返回值

返回值类型	说明
`Object`	返回当前时间的 `Timestamp` 对象

使用示例

w:set (current = NOW())
w:set (tomorrow = DATETIME_OFFSET(NOW(), 0, 0, 1))
w:log("INFO", "当前时间: {}", DATETIME_FORMAT(current, null, "yyyy-MM-dd HH:mm:ss"))

TIME_FORMAT

功能：格式化时间字符串（仅包含时分秒）
适用场景：将时间字符串或 Java 时间对象按指定格式输出

参数列表

参数名	类型	是否必填	默认值	说明
`Time`	`Object`	是	-	时间字符串或 Java 时间对象（`java.util.Date`）
`TimeStringPattern`	`String`	否	`null`	输入时间的格式（当 `Time` 为字符串时必填），如 `HH:mm:ss`
`OutputTimeStringPattern`	`String`	否	`HH:mm:ss`	输出时间格式

返回值

返回值类型	说明
`String`	返回格式化后的时间字符串

使用示例

w:set (time_str = TIME_FORMAT("09:05:03", "HH:mm:ss", "HH时mm分ss秒"))
w:log("INFO", "{}", time_str)   // 09时05分03秒

注意事项

当 Time 为字符串时，必须提供 TimeStringPattern，否则抛出异常。
当 Time 为 Java 日期对象时，取其中的时间部分（时、分、秒）。

DATE

功能：将日期字符串解析为日期对象
适用场景：把字符串形式的日期转换为可参与日期计算（如 DATE_DIFF、DATE_FORMAT）的日期对象

参数列表

参数名	类型	是否必填	默认值	说明
`Date`	`String`	是	-	日期字符串
`DateStringPattern`	`String`	否	`null`	输入日期格式，如 `yyyy-MM-dd`；不传时按 ISO 标准格式（`yyyy-MM-dd`）解析

返回值

返回值类型	说明
`Object`	返回 `java.sql.Date` 日期对象

使用示例

w:set (d1 = DATE("2026-09-09"))
w:set (d2 = DATE("09/09/2026", "dd/MM/yyyy"))

DATE_DIFF

功能：计算两个日期之间的差值
适用场景：计算两个日期相差的天数、周数、月数或年数（DATA2 - DATA1）

参数列表

参数名	类型	是否必填	默认值	说明
`DATA1`	`Object`	是	-	起始日期（日期对象）
`DATA2`	`Object`	是	-	结束日期（日期对象）
`INTERVAL`	`String`	否	`day`	差值单位：`day`（天）、`weeks`（周）、`months`（月）、`year`（年），其他值按天处理

返回值

返回值类型	说明
`Integer`	返回两个日期之间的差值（`DATA2 - DATA1`，可为负数）

使用示例

w:set (d1 = DATE("2026-01-01"))
w:set (d2 = DATE("2026-09-09"))
w:set (days = DATE_DIFF(d1, d2))              // 相差天数
w:set (months = DATE_DIFF(d1, d2, "months"))  // 相差月数
w:log("INFO", "相差 {} 天", days)

DATE_FORMAT

功能：格式化日期字符串或日期对象
适用场景：将各种格式的日期字符串/日期对象统一转换为指定格式输出，支持 EDI 常用日期格式与多语言

参数列表

参数名	类型	是否必填	默认值	说明
`Date`	`Object`	是	-	日期字符串或 Java 日期对象（`java.sql.Date`/`java.util.Date`）
`DateStringPattern`	`String`	否	`null`	输入日期格式（当 `Date` 为字符串时必填）。特殊值：`EDI_8`（8 位 EDI 日期 `yyyyMMdd`）、`EDI_6`（6 位 EDI 日期 `yyMMdd`，世纪取当前年份）、`AUTO`（自动匹配常见格式）
`OutputDateStringPattern`	`String`	否	`yyyy-MM-dd`	输出日期格式
`Language`	`String`	否	`null`	输入日期的语言区域（如 `en`、`de`），用于解析月份/星期等文字
`OutputLanguage`	`String`	否	`null`	输出日期的语言区域

返回值

返回值类型	说明
`String`	返回格式化后的日期字符串

使用示例

w:set (d1 = DATE_FORMAT("20260909", "EDI_8", "yyyy-MM-dd"))        // 2026-09-09
w:set (d2 = DATE_FORMAT("260909", "EDI_6", "yyyy/MM/dd"))          // 2026/09/09
w:set (d3 = DATE_FORMAT("2026-09-09", "yyyy-MM-dd", "dd-MMM-yyyy", null, "en"))  // 09-Sep-2026
w:set (d4 = DATE_FORMAT(DATE("2026-09-09"), null, "yyyyMMdd"))     // 20260909

注意事项

当 Date 为字符串时，必须提供 DateStringPattern，否则抛出异常。
EDI_8 要求输入恰好 8 位字符，EDI_6 要求恰好 6 位字符，否则抛出异常。
AUTO 模式可自动匹配 yyyy-MM-dd、yyyy/MM/dd、dd-MM-yyyy、MM/dd/yyyy、yyyyMMdd 等常见格式。

DATETIME

功能：将日期时间字符串解析为时间戳对象
适用场景：把字符串形式的日期时间转换为可参与时间计算（如 DATETIME_DIFF、DATETIME_OFFSET）的时间戳对象

参数列表

参数名	类型	是否必填	默认值	说明
`Datetime`	`String`	是	-	日期时间字符串
`DatetimeStringPattern`	`String`	否	`null`	输入日期时间格式；不传时按 ISO 标准格式解析；特殊值 `EPOCH_MILLI` 表示输入为毫秒级时间戳数字字符串

返回值

返回值类型	说明
`Object`	返回 `Timestamp` 时间戳对象

使用示例

w:set (dt1 = DATETIME("2026-09-09T10:30:00"))
w:set (dt2 = DATETIME("2026-09-09 10:30:00", "yyyy-MM-dd HH:mm:ss"))
w:set (dt3 = DATETIME("1788940200000", "EPOCH_MILLI"))

DATETIME_DIFF

功能：计算两个日期时间之间的差值
适用场景：计算两个时间点相差的天、时、分、秒或毫秒数（DATATIME2 - DATATIME1）

参数列表

参数名	类型	是否必填	默认值	说明
`DATATIME1`	`Object`	是	-	起始时间（`Timestamp` 时间戳对象，由 `NOW`、`DATETIME` 等返回）
`DATATIME2`	`Object`	是	-	结束时间（`Timestamp` 时间戳对象）
`INTERVAL`	`String`	否	`day`	差值单位：`day`（天）、`hour`（小时）、`minute`（分）、`second`（秒）、`millisecond`（毫秒），其他值按天处理

返回值

返回值类型	说明
`Integer`	返回两个时间之间的差值（可为负数）

使用示例

w:set (t1 = DATETIME("2026-09-09 08:00:00", "yyyy-MM-dd HH:mm:ss"))
w:set (t2 = DATETIME("2026-09-09 10:30:00", "yyyy-MM-dd HH:mm:ss"))
w:set (hours = DATETIME_DIFF(t1, t2, "hour"))      // 2
w:set (mins  = DATETIME_DIFF(t1, t2, "minute"))    // 150

DATETIME_FORMAT

功能：格式化日期时间字符串或时间戳对象
适用场景：将各种格式的日期时间统一转换为指定格式输出，支持毫秒级时间戳（EPOCH_MILLI）与多语言

参数列表

参数名	类型	是否必填	默认值	说明
`Datetime`	`Object`	是	-	日期时间字符串或 Java 时间对象（`Timestamp`/`LocalDateTime`）
`DatetimeStringPattern`	`String`	否	`null`	输入日期时间格式（当 `Datetime` 为字符串时必填）。特殊值：`EPOCH_MILLI`（输入为毫秒时间戳）、`AUTO`（自动匹配常见格式）
`OutputDatetimeStringPattern`	`String`	否	`yyyy-MM-dd HH:mm:ss`	输出日期时间格式；特殊值 `EPOCH_MILLI` 表示输出毫秒级时间戳字符串
`Language`	`String`	否	`null`	输入日期时间的语言区域
`OutputLanguage`	`String`	否	`null`	输出日期时间的语言区域

返回值

返回值类型	说明
`String`	返回格式化后的日期时间字符串

使用示例

w:set (s1 = DATETIME_FORMAT("2026-09-09 10:30:00", "yyyy-MM-dd HH:mm:ss", "yyyy/MM/dd HH:mm"))
w:log("INFO", "{}", s1)   // 2026/09/09 10:30

w:set (s2 = DATETIME_FORMAT("1788940200000", "EPOCH_MILLI", "yyyy-MM-dd HH:mm:ss"))
w:set (s3 = DATETIME_FORMAT(NOW(), null, "EPOCH_MILLI"))

注意事项

当 Datetime 为字符串时，必须提供 DatetimeStringPattern，否则抛出异常。
AUTO 模式可自动匹配 yyyy-MM-dd HH:mm:ss、yyyy/MM/dd HH:mm:ss、yyyyMMddHHmmss 等常见格式。

DATETIME_OFFSET

功能：对给定的时间戳（TIMESTAMP）进行年、月、日、时、分、秒的偏移计算，返回偏移后的新时间戳。
适用场景：需要动态调整日期时间的场景（如计算未来/过去的某个时间点）。

参数列表

参数名	类型	是否必填	默认值	说明
`TIMESTAMP`	`Object`	是	-	原始时间戳（需能被解析为有效日期时间）。
`YEAR_OFFSET`	`Long`	否	`0`	年偏移量（正数=未来，负数=过去）。
`MONTH_OFFSET`	`Long`	否	`0`	月偏移量（支持跨年计算）。
`DAY_OFFSET`	`Long`	否	`0`	日偏移量（支持跨月计算）。
`HOUR_OFFSET`	`Long`	否	`0`	小时偏移量（支持跨日计算）。
`MINUTE_OFFSET`	`Long`	否	`0`	分钟偏移量（支持跨小时计算）。
`SECOND_OFFSET`	`Long`	否	`0`	秒偏移量（支持跨分钟计算）。

返回值

返回值类型	说明
`Object`	返回偏移后的时间戳对象，格式与输入一致。

使用示例

// 示例1：当前时间 + 1年2个月3天
DATETIME_OFFSET(NOW(), 1, 2, 3);

// 示例2：指定时间戳 - 5小时30分钟
DATETIME_OFFSET(NOW(), 0, 0, 0, -5, -30, 0);

注意事项

空偏移量：如果某个偏移量参数为 0 或未提供，则该维度不进行偏移。
边界处理：自动处理跨月、跨年等边界情况（如 MONTH_OFFSET=12 会自动进位为年）。
输入校验：若 TIMESTAMP 无法解析为有效时间，可能返回错误或 null。

十、字符串处理函数

STRING_FORMAT

功能：按格式化模板对字符串进行格式化，用法与 Java 的 String.format 一致
适用场景：数字补零、字符串对齐、数值格式化等场景

<Return> = STRING_FORMAT(<Format>, <Param1>, ..., <Param5>)

参数列表

参数名	类型	是否必填	默认值	说明
`Format`	`String`	是	-	格式化模板，如 `%010d`、`%-10s`、`%.2f`
`Param1` ~ `Param5`	`Object`	否	`null`	模板参数，按顺序对应模板中的占位符（最多 5 个）

返回值

返回值类型	说明
`String`	返回格式化后的字符串

使用示例

bash

w:set (NUM = 123)
w:set (FORMATTED_NUM = STRING_FORMAT("%010d", NUM))   // 0000000123，数字前补零到 10 位
w:set (TEXT = STRING_FORMAT("%-10s|", "ABC"))         // ABC       |，左对齐补空格
w:set (PRICE = STRING_FORMAT("%.2f", 12.345))         // 12.35，保留两位小数

STRING_LENGTH

功能：返回字符串的长度（计算前会先去除首尾空白）
适用场景：校验字符串长度、截取前的边界判断等

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	否	`""`	输入字符串

返回值

返回值类型	说明
`Integer`	返回字符串去除首尾空白后的长度；`null` 时返回 `0`

使用示例

w:set (len = STRING_LENGTH("  Hello  "))   // 5
w:log("INFO", "长度: {}", len)

判断内容是否不为空（推荐使用 STRING_LENGTH(...) > 0，配合 STRING_DEFAULT 去除空白并兜底空值）：

text

w:
w:  equipment_number = STRING_DEFAULT(XPATH($xml_doc, "/docs/doc/equipment_number/text()"))
w:  equipment_unit   = STRING_DEFAULT(XPATH($xml_doc, "/docs/doc/equipment_unit/text()"))
w:  if (STRING_LENGTH(equipment_number) > 0) {
w:      <EQDLoop>
w:          <EQD>
w:              w: if (STRING_LENGTH(equipment_unit) > 0) {
w:              <EQD01>
w:                  <C01>{{ equipment_unit }}</C01>
w:              </EQD01>
w:              w: }
w:              <EQD02>
w:                  <C01>{{ equipment_number }}</C01>
w:              </EQD02>
w:          </EQD>
w:      </EQDLoop>
w:  }

判断内容是否为空（推荐使用 0 >= STRING_LENGTH(...)，即 >= 形式）：

text

w:
w:  despatch_datetime = STRING_DEFAULT(XPATH($xml_doc, "/docs/doc/despatch_datetime/text()"))
w:  if (0 >= STRING_LENGTH(despatch_datetime)) {
w:      Error_Msg_Zh = STRING_FORMAT("发货日期不能为空.")
w:      Error_Msg_En = STRING_FORMAT("The delivery date cannot be empty.")
w:      export (GLOBAL_WORKFLOW, Error_Msg_Zh as E_ERROR_MSG_ZH, Error_Msg_En as E_ERROR_MSG_EN)
w:      throw Error_Prefix + Error_Msg_En
w:  }

注意事项

先去空白再计算：内部会先对输入字符串调用 trim() 去除首尾空白，再计算长度；null 输入返回 0。
空值判断推荐写法：判断是否为空用 0 >= STRING_LENGTH(x)，判断是否不为空用 STRING_LENGTH(x) > 0，并配合 STRING_DEFAULT 处理 "null" 字符串与首尾空白。

STRING_INDEX_OF

功能：查找子字符串在字符串中第一次出现的位置（索引从 0 开始）
适用场景：判断子串是否存在、定位分隔符位置等

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	是	`""`	被查找的字符串
`Substring`	`String`	是	`""`	要查找的子字符串

返回值

返回值类型	说明
`Integer`	返回第一次出现的索引（从 0 开始）；未找到返回 `-1`

使用示例

w:set (idx = STRING_INDEX_OF("Hello World", "World"))   // 6
w:set (no  = STRING_INDEX_OF("Hello World", "xyz"))     // -1

STRING_LAST_INDEX_OF

功能：查找子字符串在字符串中最后一次出现的位置（索引从 0 开始）
适用场景：定位最后一个分隔符、提取文件名等场景

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	是	`""`	被查找的字符串
`Substring`	`String`	是	`""`	要查找的子字符串

返回值

返回值类型	说明
`Integer`	返回最后一次出现的索引（从 0 开始）；未找到返回 `-1`

使用示例

w:set (idx = STRING_LAST_INDEX_OF("a/b/c.txt", "/"))   // 3
w:log("INFO", "最后一个斜杠位置: {}", idx)

STRING_SPLIT

功能：按分隔符将字符串拆分为字符串数组
适用场景：解析以分隔符拼接的文本（如 CSV 行、键值对、报文字段等）

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	是	-	输入字符串
`Separator`	`String`	否	`null`	分隔符，按正则表达式处理；`

返回值

返回值类型	说明
`Array`	返回拆分后的字符串数组

使用示例

w:set (arr = STRING_SPLIT("Apple,Banana,Orange", ","))
w:log("INFO", "第一段: {}", GET(arr, 0))   // Apple

w:set (parts = STRING_SPLIT("a|b|c", "|"))  // 竖线自动按普通字符处理

STRING_SPLIT_WORD

功能：将字符串按固定长度拆分为多行（以单词为边界，空格/换行处折行）
适用场景：标签打印、报文分行等需要把长文本按每行固定字符数换行的场景

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	是	-	输入字符串
`Count`	`Integer`	否	`null`	每行的最大字符数

返回值

返回值类型	说明
`Array`	返回拆分后的每行字符串数组

使用示例

w:set (lines = STRING_SPLIT_WORD("GitHub secret scanning protects users", 20))
w:for (line : lines)
w:  log("INFO", "行: {}", line)
w:end

STRING_SUBSTRING

功能：截取字符串的子串，用法与 Java 的 String.substring 一致
适用场景：从固定长度报文中提取字段、截取前缀/后缀等

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	是	-	输入字符串
`start`	`Integer`	否	`0`	起始位置（从 0 开始，包含）
`end`	`Integer`	否	字符串长度	结束位置（不包含）；超出字符串长度时自动按字符串长度处理

返回值

返回值类型	说明
`String`	返回截取的子串；输入为空时返回 `""`

使用示例

w:set (sub1 = STRING_SUBSTRING("Hello World", 0, 5))   // Hello
w:set (sub2 = STRING_SUBSTRING("Hello World", 6))      // World

STRING_TOUPPER

功能：将字符串中的字母全部转换为大写
适用场景：编码统一、大小写不敏感比较前的归一化处理

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	否	`""`	输入字符串

返回值

返回值类型	说明
`String`	返回大写字符串；输入为空时返回 `""`

使用示例

w:set (upper = STRING_TOUPPER("hello"))   // HELLO

STRING_TOLOWER

功能：将字符串中的字母全部转换为小写
适用场景：编码统一、大小写不敏感比较前的归一化处理

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	否	`""`	输入字符串

返回值

返回值类型	说明
`String`	返回小写字符串；输入为空时返回 `""`

使用示例

w:set (lower = STRING_TOLOWER("HELLO"))   // hello

STRING_MATCH

功能：用正则表达式匹配整个字符串，返回是否匹配成功
适用场景：校验字符串格式（如邮箱、手机号、报文编码规则等）

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	是	`""`	待匹配的字符串
`Regex`	`String`	是	`""`	正则表达式（匹配整个字符串）

返回值

返回值类型	说明
`Boolean`	整个字符串与正则表达式匹配返回 `true`，否则返回 `false`

使用示例

w:set (ok = STRING_MATCH("13800138000", "^1[3-9]\\d{9}$"))   // true
w:set (no = STRING_MATCH("abc", "^\\d+$"))                   // false

注意事项

该函数对应 Java 的 String.matches，正则必须匹配整个字符串才算成功；部分匹配请在正则中使用 .* 前后补齐。

STRING_REPLACE

功能：将字符串中所有匹配的子串替换为新字符串（按正则表达式匹配，对应 Java 的 replaceAll）
适用场景：报文内容替换、清除特定字符、文本规范化等

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	是	`""`	输入字符串
`Old`	`String`	是	`""`	要被替换的子串（正则表达式）
`New`	`String`	是	`""`	替换后的新字符串

返回值

返回值类型	说明
`String`	返回替换后的字符串；输入为 `null` 时返回 `""`

使用示例

w:set (r1 = STRING_REPLACE("a-b-c", "-", "/"))     // a/b/c
w:set (r2 = STRING_REPLACE("a1b2c3", "\\d", "X"))  // aXbXcX，数字替换为 X

STRING_TRIM

功能：去除字符串首尾的空白字符
适用场景：清洗报文字段、用户输入等文本前后的多余空格

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	否	`""`	输入字符串

返回值

返回值类型	说明
`String`	返回去除首尾空白后的字符串；输入为 `null` 时返回 `null`

使用示例

w:set (v = STRING_TRIM("  Hello  "))   // Hello

STRING_TRIM_START

功能：去除字符串开头（左侧）的空白字符
适用场景：只需要清除行首/字段前导空格的场景

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	否	`""`	输入字符串

返回值

返回值类型	说明
`String`	返回去除前导空白后的字符串；输入为 `null` 时返回 `null`

使用示例

w:set (v = STRING_TRIM_START("  Hello  "))   // "Hello  "

STRING_TRIM_END

功能：去除字符串结尾（右侧）的空白字符
适用场景：只需要清除行尾/字段尾部空格的场景

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	否	`""`	输入字符串

返回值

返回值类型	说明
`String`	返回去除尾部空白后的字符串；输入为 `null` 时返回 `null`

使用示例

w:set (v = STRING_TRIM_END("  Hello  "))   // "  Hello"

STRING_STRIP

功能：先去除首尾空白，再移除字符串首尾指定的字符
适用场景：去除字段两端的引号、分隔符、包裹符号等

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	是	`""`	输入字符串
`StripChars`	`String`	否	`""`	要从首尾移除的字符集合（如 `"\"'"` 表示移除引号）；不传则仅去空白

返回值

返回值类型	说明
`String`	返回处理后的字符串；输入为 `null` 时返回 `""`

使用示例

w:set (v1 = STRING_STRIP("\"Hello\"", "\""))   // Hello
w:set (v2 = STRING_STRIP("  [ABC]  ", "[]"))   // [ABC] → ABC（先去空白再移除方括号）

STRING_DEFAULT

功能：对字符串去除首尾空白，并将 null、空串、"null" 字符串转为默认值（默认值为空时返回 ""）
适用场景：从 XPATH/JSON_PATH 等取值后做兜底清洗，避免 "null" 字面量或前后空白污染后续输出；常与 STRING_LENGTH 配合做空值判断

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	否	`""`	输入字符串
`Default`	`String`	否	`""`	默认值，当输入为空或 `"null"` 时使用

返回值

返回值类型	说明
`String`	输入非空时返回输入（去除首尾空白）；否则返回默认值（默认值为空时返回 `""`）

使用示例

w:set (v1 = STRING_DEFAULT("", "N/A"))        // N/A
w:set (v2 = STRING_DEFAULT("null", "N/A"))    // N/A
w:set (v3 = STRING_DEFAULT("PO001", "N/A"))   // PO001
w:set (v4 = STRING_DEFAULT("  PO001  "))      // PO001  (去除前后空格)

配合 XPATH 取值并做兜底清洗（常见用法）：

text

w:
w:  // XPATH 未命中时可能返回 "null" 字符串，STRING_DEFAULT 可同时去空白并兜底
w:  equipment_number = STRING_DEFAULT(XPATH($xml_doc, "/docs/doc/equipment_number/text()"))
w:  if (STRING_LENGTH(equipment_number) > 0) {
w:      // ...使用 equipment_number
w:  }

STRING_START_WITH

功能：判断字符串是否以指定前缀开头
适用场景：报文类型识别、文件前缀判断等

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	是	`""`	输入字符串
`Start`	`String`	是	`""`	要检查的前缀
`IgnoreCase`	`Boolean`	否	`false`	是否忽略大小写

返回值

返回值类型	说明
`Boolean`	字符串以指定前缀开头返回 `true`；输入为 `null` 时返回 `false`

使用示例

w:set (ok = STRING_START_WITH("PO20260909", "PO"))           // true
w:set (no = STRING_START_WITH("PO20260909", "so"))           // false
w:set (yes = STRING_START_WITH("PO20260909", "po", true))    // true，忽略大小写

STRING_END_WITH

功能：判断字符串是否以指定后缀结尾
适用场景：文件扩展名判断、报文结尾标识识别等

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	是	`""`	输入字符串
`End`	`String`	是	`""`	要检查的后缀
`IgnoreCase`	`Boolean`	否	`false`	是否忽略大小写

返回值

返回值类型	说明
`Boolean`	字符串以指定后缀结尾返回 `true`；输入为 `null` 时返回 `false`

使用示例

w:set (ok = STRING_END_WITH("order.xml", ".xml"))            // true
w:set (yes = STRING_END_WITH("order.XML", ".xml", true))     // true，忽略大小写

STRING_REMOVE_SYMBOL

功能：移除字符串中的标点符号、连字符、空格等非字母数字字符（会先去除重音符号），只保留英文字母和数字
适用场景：清洗地址、名称等字段以便比较或生成编码

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	是	`""`	输入字符串
`IgnoreSymbol`	`String`	否	`""`	需要额外保留的符号（除字母数字外，这些字符也不会被移除）

返回值

返回值类型	说明
`String`	返回仅包含字母、数字（及指定保留符号）的字符串

使用示例

w:set (v1 = STRING_REMOVE_SYMBOL("A-B C.D!"))        // ABCD
w:set (v2 = STRING_REMOVE_SYMBOL("123-456-7890", "-"))  // 123-456-7890，保留连字符

十一、文件操作函数

FILE_GETNAME

功能：返回文件的名称（不含目录路径），等价于 Java 的 File.getName()
适用场景：从文件完整路径中提取文件名

参数列表

参数名	类型	是否必填	默认值	说明
`File`	`Object`	是	-	文件对象，支持 String 路径、File 对象或 Path 对象；为 `null` 时返回 `null`

返回值

返回值类型	说明
`String`	返回文件名称

使用示例

w:set (name = FILE_GETNAME("D:/data/order.xml"))   // order.xml
w:log("INFO", "文件名: {}", name)

FILE_GETEXT

功能：返回文件的扩展名
适用场景：根据扩展名判断文件类型（如区分 xml、csv、xlsx）

参数列表

参数名	类型	是否必填	默认值	说明
`File`	`Object`	是	-	文件对象，支持 String 路径、File 对象或 Path 对象；为 `null` 时返回 `""`

返回值

返回值类型	说明
`String`	返回文件的扩展名（不含 `.`），无扩展名时返回空串

使用示例

w:set (ext = FILE_GETEXT("D:/data/order.xml"))   // xml
w:log("INFO", "扩展名: {}", ext)

FILE_GETPATH

功能：返回文件的完整（规范）路径，等价于 Java 的 File.getCanonicalPath()
适用场景：获取文件的绝对路径，用于日志记录或后续文件操作

参数列表

参数名	类型	是否必填	默认值	说明
`File`	`Object`	是	-	文件对象，支持 String 路径、File 对象或 Path 对象；为 `null` 时返回 `null`

返回值

返回值类型	说明
`String`	返回文件的完整路径

使用示例

w:set (path = FILE_GETPATH(${O_FILE}))
w:log("INFO", "完整路径: {}", path)

FILE_GETFOLDER

功能：返回文件所在文件夹的路径；若传入的本身是文件夹，则返回该文件夹路径
适用场景：定位文件所在目录，用于同目录下查找、输出配套文件等

参数列表

参数名	类型	是否必填	默认值	说明
`File`	`Object`	是	-	文件或文件夹对象，支持 String 路径、File 对象或 Path 对象；为 `null` 时返回 `null`

返回值

返回值类型	说明
`String`	返回文件所在文件夹（父目录）的路径；入参为文件夹时返回其自身路径

使用示例

w:set (folder = FILE_GETFOLDER("D:/data/in/order.xml"))   // D:\data\in
w:log("INFO", "所在目录: {}", folder)

FILE_MKDIR

功能：创建文件夹（包括所有必需的父目录）
适用场景：需要在本地或远程文件系统中创建目录时，自动创建不存在的父级目录

参数列表

参数名	类型	是否必填	默认值	说明
`FolderPath`	`Object`	是	-	要创建的文件夹路径，支持String、File、Path对象
`User`	`String`	否	`null`	访问远程文件时的用户名
`Password`	`String`	否	`null`	访问远程文件时的密码
`Domain`	`String`	否	`null`	访问远程文件时的域

返回值

返回值类型	说明
`Boolean`	创建成功返回 `true`

特性说明

自动创建父目录：如果父目录不存在，会自动创建所有必需的父目录（类似 mkdir -p）
已存在不报错：如果文件夹已存在，不会抛出异常，返回 true
支持远程路径：支持 SMB、FTP 等远程文件协议

FILE_READ

功能：读取文件内容并以字符串形式返回
适用场景：需要读取文本文件（如配置、日志、XML、EDI 等）的全部内容时使用

参数列表

参数名	类型	是否必填	默认值	说明
`FILE`	`Object`	是	-	要读取的文件，支持 String 路径、File 对象或 Path 对象

返回值

返回值类型	说明
`String`	返回文件的全部内容（文本格式）

使用示例

w:set (content = FILE_READ("D:/data/config.txt"))
w:log("INFO", "文件内容: {}", content)

FILE_COPY

功能：复制文件或文件夹到目标路径
适用场景：需要复制单个文件或整个文件夹时，支持覆盖、递归复制、跳过已存在文件等多种选项，并支持远程文件访问认证

参数列表

参数名	类型	是否必填	默认值	说明
`From`	`Object`	是	-	源文件路径，支持String、File、Path对象
`To`	`Object`	是	-	目标文件路径，支持String、File、Path对象
`Options`	`String`	否	`Overwrite,Recursive`	逗号分隔的复制选项，可选值：`Overwrite`、`Recursive`、`SkipExisted`
`User`	`String`	否	`null`	访问远程文件时的用户名
`Password`	`String`	否	`null`	访问远程文件时的密码
`Domain`	`String`	否	`null`	访问远程文件时的域

返回值

返回值类型	说明
`Boolean`	复制成功返回 `true`

复制选项说明

选项	说明
`Overwrite`	如果目标文件已存在，覆盖它（默认启用）
`Recursive`	递归复制子目录和文件（默认启用）
`SkipExisted`	如果目标文件已存在，跳过不覆盖（优先级高于 `Overwrite`）

使用示例

w:scan_path = FILE_GETPATH(${O_INPROCESS_TEMP})
w:set (result = FILE_COPY(${O_FILE},scan_path))
w:log("INFO", "复制result: {}", result)
w:set(file_list = FILE_SCAN_DIR(scan_path,null,"file")) 
w:set(result = "")
w:for(file : file_list) {
w:  set(result = result + FILE_GETNAME(file) + "|")
w:  log ("INFO", "result: {}", result)
w:}

注意事项

默认行为：如果不指定 Options 参数，默认使用 Overwrite,Recursive，即覆盖已存在文件并递归复制子目录
选项优先级：当同时指定 Overwrite 和 SkipExisted 时，SkipExisted 优先（先检查是否存在，存在则跳过）
递归复制：复制目录时，如果不指定 Recursive 选项，只会复制空目录（不包含子文件和子目录）
远程文件支持：支持 SMB、FTP 等远程文件协议，需通过 User、Password、Domain 参数提供认证信息
资源管理：方法内部使用 try-with-resources 自动管理文件资源，调用方无需手动关闭
返回值：方法始终返回 true，如果复制失败会抛出异常，因此通过异常处理来判断是否成功
权限要求：需要有源文件的读取权限和目标路径的写入权限

FILE_EXISTS

功能：检查文件或目录是否存在
适用场景：在执行文件操作前，先判断文件或目录是否存在，避免操作失败

参数列表

参数名	类型	是否必填	默认值	说明
`FilePath`	`Object`	是	-	要检查的文件或文件夹路径，支持String、File、Path对象
`User`	`String`	否	`null`	访问远程文件时的用户名
`Password`	`String`	否	`null`	访问远程文件时的密码
`Domain`	`String`	否	`null`	访问远程文件时的域

返回值

返回值类型	说明
`Boolean`	文件或目录存在返回 `true`，否则返回 `false`

FILE_MOVE

功能：移动或重命名文件/文件夹
适用场景：需要将文件或文件夹从一个位置移动到另一个位置，或在同一目录下重命名时使用。支持本地和远程文件系统

参数列表

参数名	类型	是否必填	默认值	说明
`From`	`Object`	是	-	源文件/文件夹路径，支持String、File、Path对象
`To`	`Object`	是	-	目标文件/文件夹路径，支持String、File、Path对象
`Options`	`String`	否	`null`	逗号分隔的移动选项，可选值：`Overwrite`、`SkipExisted`
`User`	`String`	否	`null`	访问远程文件时的用户名
`Password`	`String`	否	`null`	访问远程文件时的密码
`Domain`	`String`	否	`null`	访问远程文件时的域

返回值

返回值类型	说明
`Boolean`	移动成功返回 `true`

FILE_RENAME

功能：重命名文件或文件夹
适用场景：需要修改文件或文件夹名称时，支持本地和远程文件系统的重命名操作

参数列表

参数名	类型	是否必填	默认值	说明
`FilePath`	`Object`	是	-	要重命名的文件或文件夹路径，支持String、File、Path对象
`FileName`	`String`	是	-	新的文件或文件夹名称（仅名称，不包含路径）
`User`	`String`	否	`null`	访问远程文件时的用户名
`Password`	`String`	否	`null`	访问远程文件时的密码
`Domain`	`String`	否	`null`	访问远程文件时的域

返回值

返回值类型	说明
`Boolean`	重命名成功返回 `true`

说明

FileName 参数只包含新名称，不包含路径
例如：原文件 /data/file.txt，新名称 newname.txt，结果为 /data/newname.txt

FILE_SCAN_DIR

扫描文件的脚本函数。支持通配符模式的目录扫描，可以通过过滤文件/文件夹类型来限制递归深度

功能：扫描目录并支持Glob模式匹配，可过滤文件/文件夹类型并限制递归深度
适用场景：需要批量查找符合特定模式的文件或目录时，支持通配符匹配、类型过滤和深度控制

参数列表

参数名	类型	是否必填	默认值	说明
`FilePath`	`Object`	是	-	根搜索路径，支持普通目录、单个文件或Glob模式（如`D:/logs`、`D:/log/file.log`）
`FileName`	`String`	否	`null`	Glob表达式匹配条目名称，如`*.txt`、`log?.csv`
`FileKind`	`String`	否	`all`	过滤返回条目类型：`all`（默认）/ `file`（仅文件）/ `dir`（仅目录）
`MaxDepth`	`Integer`	否	`0`	最大子目录遍历深度，`0`表示仅根级别
`User`	`String`	否	`null`	用户名（用于认证）
`Password`	`String`	否	`null`	密码（用于认证）
`Domain`	`String`	否	`null`	域（用于认证）

返回值

返回值类型	说明
`Array`	返回匹配的绝对路径字符串数组

使用示例

w:scan_path = FILE_GETPATH(${O_INPROCESS_TEMP})
   w:log ("INFO", "scan_path: {}", scan_path)
w:set (files = FILE_SCAN_DIR(scan_path, null, "file"))
   w:log ("INFO", "files length: {}", LENGTH(files))
w:for (file : files) {
   w:log ("INFO", "file: {}", file)
w:}
w:set (dirs = FILE_SCAN_DIR(scan_path, null, "dir"))
   w:log ("INFO", "dirs length: {}", LENGTH(dirs))
w:for (dir : dirs) {
   w:log ("INFO", "dir: {}", dir)
w:}

注意事项

FilePath参数：支持多种输入方式：
- 普通目录路径：扫描该目录下所有条目
- 单个文件路径：返回该文件本身（如果存在）
- Glob模式路径：如D:/log*/file*.log，会自动展开匹配
FileName与FilePath关系：
- 当FilePath为目录时，FileName作为子条目的Glob匹配模式
- 当FilePath本身包含Glb模式时，FileName参数会被忽略
- FileName为null时表示匹配所有条目
FileKind过滤：
- all（默认）：返回文件和目录
- file：仅返回文件
- dir：仅返回目录
MaxDepth深度控制：
- 0（默认）：仅扫描根级别，不进入子目录
- 1：扫描根级别和第一层子目录
- n：扫描到第n层子目录
- 注意：深度从根目录开始计数，根目录为第0层
认证参数：当访问需要认证的远程文件系统（如网络共享、FTP等）时，提供User、Password和Domain参数
资源管理：方法内部会自动关闭文件资源（使用try-with-resources），调用方无需手动释放
返回结果：返回的是绝对路径字符串数组，可用于后续文件操作（如FILE_OPEN、FILE_READ等）
性能考虑：大目录扫描时建议合理设置MaxDepth，避免递归过深导致性能问题
通配符语法：
- *：匹配任意数量的字符（包括零个）
- ?：匹配单个字符
- **：匹配任意数量的目录层级（仅当FilePath为Glob模式时生效）

十二、编码生成函数

GEN_SSCC

功能：根据 GS1 厂商识别代码和序列号生成 SSCC（Serial Shipping Container Code，货运包装箱代码）
适用场景：物流标签、托盘/包装箱条码生成场景，自动计算校验位

参数列表

参数名	类型	是否必填	默认值	说明
`CompanyPrefix`	`String`	是	-	GS1 厂商识别代码（GCP），由 GS1 成员组织分配给企业
`SerialNumber`	`String`	是	-	SSCC 序列号

返回值

返回值类型	说明
`String`	返回生成的 SSCC 编码

使用示例

w:set (sscc = GEN_SSCC("1234567", "000000001"))
w:log("INFO", "SSCC: {}", sscc)

GEN_LABEL

功能：根据前缀和序列号生成定长标签编码（前缀 + 补零 + 序列号）
适用场景：生成固定长度的物流标签、批次号等编码

参数列表

参数名	类型	是否必填	默认值	说明
`Prefix`	`String`	是	-	标签编码前缀
`SerialNumber`	`String`	是	-	序列号
`length`	`Integer`	是	-	标签编码总长度

返回值

返回值类型	说明
`String`	返回定长标签编码：前缀 + 中间补零 + 序列号，总长度为 `length`

使用示例

w:set (label = GEN_LABEL("LP", "123", 10))   // LP00000123
w:log("INFO", "标签: {}", label)

注意事项

当前缀长度与序列号长度之和大于 length 时，会抛出异常。

GEN_ID

功能：生成序列化的 ID 字符串，结构为「前缀 + 可选日期 + 零填充自增序号」，每次调用序号自动 +1
适用场景：生成业务单据号、流水号等需要持续自增且定长的编号

例如, 00001 --> 99999 --> 00001

参数列表

参数名	类型	是否必填	默认值	说明
`PREFIX`	`String`	是	-	前缀字符
`LENGTH`	`Integer`	是	-	生成 ID 的总长度
`PATTERN`	`String`	否	`null`	日期格式，例如 `"yyMMdd"`，传入时 ID 中会插入当前日期
`RESET_BY_DAY`	`Boolean`	否	`false`	是否按天重置序号（每天从 1 重新开始）

返回值

返回值类型	说明
`String`	返回定长 ID 字符串

使用示例

// 第一次调用 1001
w:set (id = GEN_ID("1", 3))
// 第二次调用 10002
w:set (id = GEN_ID("1", 4))
// 包含日期 125060103
w:set (id = GEN_ID("1", 9, "yyMMdd"))
// 重置日期，第二天调用 125060201
w:set (id = GEN_ID("1", 9, "yyMMdd", true))

注意事项

序号持久化在 EDI_HOME 目录下的 .generated_id.txt 文件中，脚本重启后继续自增。
当 LENGTH 小于「前缀 + 日期」长度时会抛出异常。
序号部分按剩余长度零填充（如剩余 5 位、序号为 1 时输出 00001），超过长度范围后取模循环。

十三、数学计算函数

MATH_CEIL

功能：对数值向上取整（天花板取整）
适用场景：分页计算、箱数计算等需要向上进位的场景

参数列表

参数名	类型	是否必填	默认值	说明
`Value`	`Double`	是	-	要向上取整的浮点数

返回值

返回值类型	说明
`Integer`	返回向上取整后的整数

使用示例

w:set (v = MATH_CEIL(12.1))   // 13

MATH_FLOOR

功能：对数值向下取整（地板取整）
适用场景：舍去小数部分、取整计算等场景

参数列表

参数名	类型	是否必填	默认值	说明
`Value`	`Double`	是	-	要向下取整的浮点数

返回值

返回值类型	说明
`Integer`	返回向下取整后的整数

使用示例

w:set (v = MATH_FLOOR(12.9))   // 12

MATH_ROUND

功能：对数值四舍五入取整
适用场景：常规数值取整场景

参数列表

参数名	类型	是否必填	默认值	说明
`Value`	`Double`	是	-	要四舍五入的浮点数

返回值

返回值类型	说明
`Integer`	返回四舍五入后的整数

使用示例

w:set (v1 = MATH_ROUND(12.4))   // 12
w:set (v2 = MATH_ROUND(12.5))   // 13

MATH_RANDOM

功能：生成指定范围内的随机整数
适用场景：生成随机端口、测试数据、抽样等场景

参数列表

参数名	类型	是否必填	默认值	说明
`Min`	`Integer`	否	`0`	随机数最小值（包含）
`Max`	`Integer`	否	`100`	随机数最大值（包含）

返回值

返回值类型	说明
`Integer`	返回 `[Min, Max]` 范围内的随机整数

使用示例

w:set (r1 = MATH_RANDOM())        // 0 ~ 100 之间的随机整数
w:set (r2 = MATH_RANDOM(1, 10))   // 1 ~ 10 之间的随机整数

注意事项

当 Min 大于 Max 时会抛出异常。

FLOAT_FORMAT

功能：对浮点数字符串进行小数位格式化（四舍五入），可选去除小数末尾的 0
适用场景：金额、数量、重量等数值的统一格式化输出

参数列表

参数名	类型	是否必填	默认值	说明
`Value`	`String`	否	`""`	浮点数字符串；为空时返回 `""`
`Decimal`	`Integer`	否	`0`	保留的小数位数（四舍五入）
`Strip`	`Boolean`	否	`false`	是否去除小数末尾多余的 `0`（如 `123.4500` → `123.45`，`123.000` → `123`）

返回值

返回值类型	说明
`String`	返回格式化后的浮点数字符串；输入无法解析为数值时返回去除空白后的原字符串

使用示例

w:set (f1 = FLOAT_FORMAT("123.4567", 2))           // 123.46
w:set (f2 = FLOAT_FORMAT("123.4500", 3))           // 123.450
w:set (f3 = FLOAT_FORMAT("123.4500", 3, true))     // 123.45
w:set (f4 = FLOAT_FORMAT("123.0000", 3, true))     // 123

十四、随机数函数

RANDOM_NUMBER

功能：生成指定位数的随机数字字符串（每一位为 0~9，首位允许为 0）
适用场景：生成随机验证码、临时密码、随机流水号等

参数列表

参数名	类型	是否必填	默认值	说明
`Length`	`Integer`	否	`6`	返回字符串的位数

返回值

返回值类型	说明
`String`	返回指定位数的随机数字字符串

使用示例

w:set (code = RANDOM_NUMBER(6))    // 如 "483920"
w:log("INFO", "验证码: {}", code)

注意事项

Length 必须大于 0，否则抛出异常。

十五、加密解密函数

ENCRYPT_AES

功能：使用 AES 算法（AES/ECB/PKCS5Padding）对字符串加密，返回 Base64 编码的密文
适用场景：脚本中敏感信息（如密码、令牌）的加密存储/传输

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	否	`""`	待加密的明文；为空时返回 `""`
`SecretKey`	`String`	否	`ChinLink_N4K8B9T`	AES 密钥（需为 16/24/32 字节）

返回值

返回值类型	说明
`String`	返回 Base64 编码的密文

使用示例

w:set (cipher = ENCRYPT_AES("myPassword"))
w:set (cipher2 = ENCRYPT_AES("myPassword", "MyOwnKey12345678"))

DECRYPT_AES

功能：使用 AES 算法（AES/ECB/PKCS5Padding）对 Base64 密文解密
适用场景：与 ENCRYPT_AES 配对使用，解密敏感信息

参数列表

参数名	类型	是否必填	默认值	说明
`String`	`String`	否	`""`	待解密的 Base64 密文；为空时返回 `""`
`SecretKey`	`String`	否	`ChinLink_N4K8B9T`	AES 密钥（须与加密时使用的密钥一致）

返回值

返回值类型	说明
`String`	返回解密后的明文

使用示例

w:set (plain = DECRYPT_AES(cipher))
w:log("INFO", "解密结果: {}", plain)   // myPassword

十六、工具函数

NULL

功能：返回 null 值
适用场景：需要显式给变量赋空值、或在表达式中传递空值时使用

参数列表

无参数

返回值

返回值类型	说明
`Object`	返回 `null`

使用示例

w:set (result = NULL())

SNOWFLAKE

功能：生成雪花算法（Snowflake）分布式唯一 ID
适用场景：需要生成全局唯一、趋势递增的长整型 ID（节点 ID 根据本机网卡 MAC 自动生成）

参数列表

无参数

返回值

返回值类型	说明
`Integer`	返回 Snowflake 长整型唯一 ID

使用示例

w:set (id = SNOWFLAKE())
w:log("INFO", "唯一 ID: {}", id)

LOG

功能：记录日志。第一个参数为日志级别，第二个参数为日志模板（{} 为占位符，按顺序对应后续参数）
适用场景：在脚本执行过程中输出调试、运行日志

参数列表

参数名	类型	是否必填	默认值	说明
`Level`	`String`	是	-	日志级别，可选值：`FATAL`、`ERROR`、`WARN`、`INFO`、`DEBUG`、`TRACE`
`Message`	`String`	是	-	日志消息模板，使用 `{}` 作为占位符
`Param1` ~ `Param9`	`Object`	否	`null`	模板参数，按顺序对应模板中的 `{}` 占位符（最多 9 个）

返回值

返回值类型	说明
`Boolean`	写入日志成功返回 `true`，失败返回 `false`

使用示例

text

w:  LOG("INFO", "check variable {}", var1)
w:  LOG("ERROR", "a={}, b={}", a, b)

DEBUG

功能：控制脚本调试开关，会触发 engine 把被执行的代码行输出到日志中
适用场景：排查脚本执行问题时，开启调试以追踪被执行的代码行

参数列表

参数名	类型	是否必填	默认值	说明
`debuggable`	`Boolean`	否	`null`	`true` 启用调试，`false` 关闭调试；不传时仅返回当前调试状态

返回值

返回值类型	说明
`Boolean`	返回当前调试状态（启用为 `true`，未启用为 `false`）

使用示例

DEBUG()        // 返回当前是否在调试状态，默认 false
DEBUG(true)    // 启用调试，日志中记录所有被执行的代码行
DEBUG(false)   // 关闭调试

DEFINE

功能：定义/赋值变量，或检查指定变量是否已定义（注册函数名为 DEFINE，实现类描述名为 DEFINED）
适用场景：动态创建变量，或在引用变量前判断其是否已存在

<Return> = DEFINE(<VARIABLE_NAME>, <VARIABLE_VALUE>)

参数列表

参数名	类型	是否必填	默认值	说明
`VARIABLE_NAME`	`String`	是	-	变量名
`VARIABLE_VALUE`	`Object`	否	不传	变量值；传入时定义/赋值该变量，不传时仅检查变量是否已存在

返回值

返回值类型	说明
`Boolean`	返回调用前该变量是否已定义：已定义返回 `true`，否则返回 `false`

使用示例

w:set (exists = DEFINE("my_var"))        // 检查变量是否已定义，返回 false
w:expr (DEFINE("my_var", "hello"))       // 定义并赋值
w:set (exists = DEFINE("my_var"))        // 返回 true

AS_VALUE

功能：使用变量名获取变量的值，如果变量不存在则使用默认值代替
适用场景：引用可能未定义的变量时提供兜底默认值，避免变量不存在导致脚本中断

参数列表

参数名	类型	是否必填	默认值	说明
`Name`	`String`	是	-	变量名
`Default`	`Object`	否	`null`	变量不存在时返回的默认值

返回值

返回值类型	说明
`Object`	返回变量值；变量不存在时返回默认值

使用示例

w:set (a = "abc")
w:set (b = AS_VALUE(a, "a"))
// b = abc

w:set (b = AS_VALUE(a, "a"))
// b = a（变量 a 不存在时使用默认值 "a"）

CONVERT

功能：转换值的类型
适用场景：需要将变量值转换为指定类型（如布尔、数字、十进制、长整型、字符串）时使用，支持指定语言区域

参数列表

参数名	类型	是否必填	默认值	说明
`value`	`Object`	是	-	原始值
`pattern`	`String`	是	-	目标类型名称，可选值：`BOOLEAN`、`NUMBER`、`DECIMAL`、`LONG`、`STRING`
`culture`	`String`	否	`null`	语言区域（如 `de_DE`），用于本地化数值解析

返回值

返回值类型	说明
`Object`	返回转换类型后的值

使用示例

w:set (unit_cost = CONVERT(unit_cost, "DECIMAL"))

转换类型并设定 Culture

w:set (unit_cost = CONVERT(unit_cost, "DECIMAL", "de_DE"))

COLUMN_INDEX

功能：将从 0 开始的列序号转换为 Excel 列名（A、B、…、Z、AA、AB、…），可附加后缀
适用场景：通过循环序号动态生成 Excel 单元格地址（如 A1、B2、AA10）

参数列表

参数名	类型	是否必填	默认值	说明
`index`	`Integer`	是	-	列序号（从 0 开始，0 对应 A）
`suffix`	`String`	否	`""`	追加在列名后的后缀（通常是行号，如 `"1"`）

返回值

返回值类型	说明
`String`	返回 Excel 风格的列名（含后缀）

使用示例

w:set (c1 = COLUMN_INDEX(0))     // A
w:set (c2 = COLUMN_INDEX(25))    // Z
w:set (c3 = COLUMN_INDEX(26))    // AA
w:set (cell = COLUMN_INDEX(0, 1))   // A1
w:log("INFO", "单元格地址: {}", cell)

VALID_TYPE

功能：校验值的类型是否与指定类型一致
适用场景：在处理变量前判断其类型是否符合预期，避免类型不匹配导致的运行时错误

参数列表

参数名	类型	是否必填	默认值	说明
`value`	`Object`	是	-	待校验的值
`datatype`	`String`	是	`STRING`	验证类型，可选值：`NUMBER`、`STRING`、`BOOLEAN`、`NODESET`、`NODE`、`LONG`、`DECIMAL`

返回值

返回值类型	说明
`Boolean`	值的类型与指定类型一致返回 `true`，否则返回 `false`

使用示例

w:set (value = 123)
// Return False
w:set (valid = VALID_TYPE(value, "STRING"))

// Return True
w:set (valid = VALID_TYPE(value, "NUMBER"))

十七、线程控制函数

SLEEP

功能：让当前脚本执行线程休眠指定的毫秒数
适用场景：等待外部系统处理、轮询间隔控制、接口限流等场景

参数列表

参数名	类型	是否必填	默认值	说明
`Value`	`Integer`	是	`0`	休眠时间，单位毫秒；大于 0 时生效

返回值

返回值类型	说明
`Boolean`	休眠结束后返回 `true`

使用示例

w:expr (SLEEP(2000))   // 休眠 2 秒
w:log("INFO", "休眠结束")

十八、锁函数

LOCK

功能：按名称获取锁并加锁（基于可重入锁 ReentrantLock），用于多线程/多实例间的代码段互斥
适用场景：多个脚本或线程可能同时操作同一共享资源（如序列号文件、外部接口）时，用命名锁保证临界区串行执行

参数列表

参数名	类型	是否必填	默认值	说明
`LockerName`	`String`	是	-	锁名称（不区分大小写，内部统一转大写）；同名锁在全局共享同一个锁对象

返回值

返回值类型	说明
`Object`	返回已加锁的锁对象，需传递给 `UNLOCK` 进行解锁；调用后当前线程持有锁

使用示例

推荐使用 try ... finally 结构，在 finally 中释放锁，确保异常情况下锁也能被释放：

text

w:set (locker = LOCK("ORDER_ID_LOCK"))
w:try {
w:    id = GEN_ID("PO", 8)
w:} finally {
w:    UNLOCK(locker)
w:}

注意事项

LOCK 会阻塞直到获取到锁；加锁后必须配对调用 UNLOCK，否则锁不会释放。
必须放在 try ... finally 的 finally 块中释放：即使临界区抛出异常，也能保证锁被释放，避免死锁。
锁为可重入锁，同一线程可多次获取同一把锁（加锁次数与解锁次数需一致）。

UNLOCK

功能：释放由 LOCK 获取的锁
适用场景：临界区操作完成后释放锁，建议放在 finally 块中确保执行

参数列表

参数名	类型	是否必填	默认值	说明
`LockedObject`	`Object`	是	-	`LOCK` 返回的锁对象；为 `null` 时抛出异常

返回值

返回值类型	说明
`Object`	返回解锁后的锁对象

使用示例

必须放在 finally 块中释放锁（与 LOCK 配套使用）：

text

w:set (locker = LOCK("ORDER_ID_LOCK"))
w:try {
w:    id = GEN_ID("PO", 8)
w:} finally {
w:    UNLOCK(locker)
w:}

十九、Odoo 集成函数

XMLPRC_AUTHENTICATION

功能：通过 XML-RPC 调用 Odoo 等系统的 authenticate 接口进行登录认证，返回用户 ID（uid）
适用场景：对接 Odoo（OpenERP）系统时，先认证获取 uid，再调用 XMLPRC_EXECUTE_KW 执行业务操作

参数列表

参数名	类型	是否必填	默认值	说明
`url`	`String`	是	-	服务基础地址（如 `http://host:8069`），函数会自动拼接 `/xmlrpc/2/common`
`user`	`String`	是	-	登录用户名
`api-token`	`String`	是	-	API Token / 登录密码
`database`	`String`	是	-	数据库名称

返回值

返回值类型	说明
`String`	认证成功返回 uid 字符串；uid 无效时返回空串；登录失败抛出异常

使用示例

w:set (uid = XMLPRC_AUTHENTICATION("http://odoo-host:8069", "admin", "my_api_token", "mydb"))
w:log("INFO", "登录 uid: {}", uid)

XMLPRC_EXECUTE_KW

功能：通过 XML-RPC 调用 Odoo 等系统的 execute_kw 接口，执行指定模型的方法
适用场景：在 Odoo 中查询/创建/更新/删除业务数据（如 search_read、create、write 等）

参数列表

参数名	类型	是否必填	默认值	说明
`url`	`String`	是	-	服务基础地址，函数会自动拼接 `/xmlrpc/2/object`
`uid`	`String`	是	-	`XMLPRC_AUTHENTICATION` 返回的用户 ID
`api-token`	`String`	是	-	API Token / 登录密码
`database`	`String`	是	-	数据库名称
`model`	`String`	是	-	Odoo 模型名，如 `res.partner`、`sale.order`
`method`	`String`	是	-	模型方法名，如 `search_read`、`create`、`write`
`arrayParameters`	`Array`	否	`null`	位置参数数组（按方法签名顺序传参，如域过滤条件、字段列表等）
`mapParameters`	`Dictionary`	否	`null`	命名参数字典（如 `limit`、`offset`、`context` 等）
`resp-format`	`String`	否	`json`	响应保存到文件时的格式：`json` 或 `xml`（仅在指定 `resp-file-name` 时生效）
`resp-file-name`	`String`	否	`null`	保存响应数据的文件名；文件写入 `O_INPROCESS_TEMP` 目录，文件已存在时会抛出异常

返回值

返回值类型	说明
`Object`	简单类型（数字、布尔、字符串等）直接返回字符串；复杂结构返回 JSON 节点对象（可用 `JSON_PATH` 提取数据）；无结果返回 `null`

使用示例

w:set (uid = XMLPRC_AUTHENTICATION("http://odoo-host:8069", "admin", "token", "mydb"))

w:// 查询 res.partner，前 10 条
w:set (partners = XMLPRC_EXECUTE_KW(
w:    "http://odoo-host:8069", uid, "token", "mydb",
w:    "res.partner", "search_read",
w:    [[["customer", "=", true]], ["id", "name"]],
w:    {"limit": 10}))
w:log("INFO", "客户数量: {}", LENGTH(partners))

注意事项

arrayParameters 中的数组、字典会被递归转换为 XML-RPC 支持的类型。
指定 resp-file-name 时，响应内容会同时写入 O_INPROCESS_TEMP 目录下的文件；若文件已存在会抛出异常，避免覆盖。

二十、已废弃函数

NODE_FETCH_CHILDREN_AS_VARIABLES

已废弃（Deprecated）：等价于 XML_FETCH，请使用 XML_FETCH 代替。

RS_FETCH_ROW_AS_VARIABLES

已废弃（Deprecated）：等价于 RS_FETCH，请使用 RS_FETCH 代替。

脚本使用手册 - 函数 ​

一、集合操作函数 ​

LENGTH ​

参数列表 ​

返回值 ​

使用示例 ​

GET ​

参数列表 ​

返回值 ​

使用示例 ​

COLLECTION_ADD ​

参数列表 ​

返回值 ​

使用示例 ​

COLLECTION_CONTAINS ​

参数列表 ​

返回值 ​

使用示例 ​

二、XML 处理函数 ​

XML_OPEN ​

参数列表 ​

返回值 ​

使用示例 ​

注意事项 ​

XML_FETCH ​

参数列表 ​

返回值 ​

使用示例 ​

XML_ENCODE ​

参数列表 ​

返回值 ​

使用示例 ​

XML_DECODE ​

参数列表 ​

返回值 ​

使用示例 ​

XPATH ​

参数列表 ​

返回值 ​

返回类型映射 ​

使用示例 ​

NODE_TO_XML ​

参数列表 ​

返回值 ​

使用示例 ​

注意事项 ​

XML_CLOSE ​

参数列表 ​

返回值 ​

使用示例 ​

XML_TO_JSON ​

参数列表 ​

返回值 ​

使用示例 ​

OUT_XML_NODE ​

参数列表 ​

返回值 ​

使用示例 ​

三、XML VTD 处理函数 ​

XML_OPEN_VTD ​

参数列表 ​

返回值 ​

返回值对象属性 ​

注意事项 ​

XPATH_VTD ​

参数列表 ​

返回值 ​

返回类型映射 ​

XPATH_VTD_MOVE ​

参数列表 ​

返回值 ​

XML_CLOSE_VTD ​

参数列表 ​

返回值 ​

四、JSON 处理函数 ​

JSON_OPEN ​

参数列表 ​

返回值 ​

使用示例 ​

注意事项 ​

脚本使用手册 - 函数

一、集合操作函数

LENGTH

参数列表

返回值

使用示例

GET

参数列表

返回值

使用示例

COLLECTION_ADD

参数列表

返回值

使用示例

COLLECTION_CONTAINS

参数列表

返回值

使用示例

二、XML 处理函数

XML_OPEN

参数列表

返回值

使用示例

注意事项

XML_FETCH

参数列表

返回值

使用示例

XML_ENCODE

参数列表

返回值

使用示例

XML_DECODE

参数列表

返回值

使用示例

XPATH

参数列表

返回值

返回类型映射

使用示例

NODE_TO_XML

参数列表

返回值

使用示例

注意事项

XML_CLOSE

参数列表

返回值

使用示例

XML_TO_JSON

参数列表

返回值

使用示例

OUT_XML_NODE

参数列表

返回值

使用示例

三、XML VTD 处理函数

XML_OPEN_VTD

参数列表

返回值

返回值对象属性

注意事项

XPATH_VTD

参数列表

返回值

返回类型映射

XPATH_VTD_MOVE

参数列表

返回值

XML_CLOSE_VTD

参数列表

返回值

四、JSON 处理函数

JSON_OPEN

参数列表

返回值

使用示例

注意事项