默认的，Pittypat 为每一个基于 SQL SERVER 运行的应用定义了一组公共的函数和存储过程，这些函数和存储过程位于 global.sql 文件中。

1. uuid_to_b64

   将一个 uniqueidentifier 类型的 UUID 转换为 URL 安全的 base64 格式的 UUID。

   1. 语法

      "uuid_to_b64"(@id uniqueidentifier) returns char(22)
      

      • @id

        一个 uniqueidentifier 类型的值。

      • 返回值

        一个 char(22) 类型的值。uniqueidentifier 16 个字节转换为 base64 的原始长度为 24，最后包含两个 =。此函数会去掉最后的两个 =，并使用 - 和 _ 分别替换 + 和 /，以确保 base64 对 URL 是安全的。

   2. 描述

      在前端，Pittypat 使用长度为 22 的 base64 字符串表示一个 UUID。从数据库中查询到的 UUID 被转换为 JSON 时就是使用长度为 22 的 base64 字符串表示。因此，一个 UUID 值在被发送到前端时需要首先被转换为 base64 字符串。默认的，中间层在将对象转换为 JSON 是会自动将 UUID 转换为 base64 字符串。

      此函数位于每一个应用的 global.sql 文件中。

   3. 示例

      declare @id char(22);
      set @id = "uuid_to_b64"(newid());
      

2. b64_to_uuid

   将一个长度为 22 的 URL 安全的 base64 格式的 UUID 字符串转换为 uniqueidentifier 类型。

   1. 语法

      "b64_to_uuid"(@id char(22)) returns uniqueidentifier
      

      • @id

        一个 char(22) 类型的 URL 安全的 base64 字符串值。转换之前会首先在最后添加两个 =，并使用 + 和 / 分别替换 - 和 _。

      • 返回值

        一个 uniqueidentifier 类型的值。

   2. 描述

      从客户端发送来的 UUID 是长度为 22 的 URL 安全的 base64 字符串，在数据库中需要首先转换为 uniqueidentifier 才能被数据库使用。

      此函数位于每一个应用的 global.sql 文件中。

   3. 示例

      declare @id uniqueidentifier;
      set @id = "b64_to_uuid"('EebWDJ01L9OtjqReYNzHAA');
      

3. like_escape

   转义用于 LIKE 运算符的字符串。

   1. 语法

      "like_escape"(@s nvarchar(max)) returns nvarchar(max)
      

      • @s

        要转义的字符串。

      • 返回值

        转义后的字符串。如果原始字符串是 null 或空字符串，则返回 null。使用 '[_]'、'[[]' 和 '[%]' 分别替换'_'、'[' 和 '%'。

   2. 描述

      从客户端来的数据中可能包含 _、[、%，这三个字符是 SQL SERVER 中 LIKE 运算符的特殊字符，需要对它们进行转义。为了支持模糊查询，同时在字符串前后添加 %。

      此函数位于每一个应用的 global.sql 文件中。

   3. 示例

      set @name = "like_escape"(@name);
      select * from "users" where @name is null or "name" like @name;
      

4. waln_log.log_op

   记录一条数据操作的日志消息。

   1. 语法

      exec "waln_log"."log_op"
          @userId uniqueidentifier, -- 用户 Id
          @opType tinyint, -- 操作类型代码
          @tableNames varchar(200), -- 数据库表名称 
          @procName varchar(128), -- 存储过程名称
          @success bit, -- 操作是否成功
          @body nvarchar(4000), -- 消息正文
          @_context nvarchar(4000), -- 当前环境变量参数
          @logId bigint out -- 日志消息的 Id
      

      • @userId

        当前用户的 Id。可以为 null，此时通常表示由系统自动记录的与用户无关的日志消息。

      • @opType

        操作类型代码，取值如下：

        取值	描述
        1	查询数据，也就是 select 语句。
        2	插入数据，也就是 insert 语句。
        4	更新数据，也就是 update 语句。
        8	删除数据，也就是 delete 语句。
        16	其他操作。

        可以是单个以上的值，或者以上值使用二进制或运算的组合，通常表示当前操作是多种操作的组合。

      • @tableNames

        数据操作涉及到的表的名称的列表，多个表之间建议使用 , 分隔。

      • @procName

        执行操作的存储过程的名称。

      • @success

        指示目标存储过程的操作是否执行成功。

      • @body

        操作日志消息的正文。

      • @_context

        当前上下文环境参数，这是一个 JSON 格式的字符串，其中包含了当前客户端的 IP 地址、首选语言等参数。格式为：{"ip":"IPv4|IPv6","lang":"zh-CN"}。参数值由中间层自动组织和传递。

      • @logId

        如果日志消息创建成功，向调用方返回新创建的日志消息的 Id。

   2. 描述

      在一些信息系统中，尤其是政府机构的信息系统，可能需要对关键的数据操作进行日志留痕。沃恩提供了一个 log 基础应用，专门用于记录数据操作的日志留痕消息。"waln_log"."log_op" 就是用于向 log 应用的数据库表中记录一条新的消息。通常在一个功能存储过程的最后调用该存储过程。

      此函数位于 waln.log 应用的 global.sql 文件中。

   3. 示例

      set @_log_id = null;
      exec "waln_log"."log_op"
          @userId, -- 当前用户的 Id
          4, -- 操作类型代码组合：1-查询、2-添加、4-更新、8-删除、16-其他
          'waln_authority.users', -- 相关数据库表的名称列表
          'waln_authority.p_users_edit', -- 存储过程名称
          @_success, -- 指示操作是否成功
          concat(N'修改了用户的信息，新的用户名为： ', @name, N' (', @loginName, ')。'), -- 详细的操作描述
          @_context, -- 当前环境变量参数
          @_log_id; -- 日志消息的 Id
      

      以上代码会由 Pittypat 自动生成。

5. waln_notifying.p_service_create

   向一组接收人发送一条通知消息。

   1. 语法

      exec "waln_notifying"."p_service_create"
          @senderId uniqueidentifier, -- 发送用户的 Id 
          @receivers nvarchar(max), -- 接收用户 Id 的列表
          @urgency tinyint, -- 紧急程度：1-常规，2-紧急，4-特急 
          @group nvarchar(30), -- 分组 
          @title nvarchar(50), -- 通知标题 
          @summary nvarchar(200), -- 通知消息摘要 
          @body nvarchar(max)), -- 通知正文内容 
          @bodyType tinyint, -- 正文类型代码：1-纯文本，2-HTML
          @funcUrl nvarchar(300), -- 目标功能路径 
          @refDataType nvarchar(64), -- 引用数据的类型 
          @refDataKey nvarchar(50), -- 引用数据键值 
          @attachmentName nvarchar(100), -- 附件文件名称 
          @attachmentMime nvarchar(100), -- 附件 MIME 类型 
          @attachmentSize bigint, -- 附件文件的大小 
          @attachmentUrl nvarchar(300), -- 文件路径 
          @attachmentUploaderId uniqueidentifier, -- 上传人的 Id 
          @attachmentUploadTime datetime2, -- 上传时间 
          @_context nvarchar(4000), -- 当前环境变量参数
          @_success bit out, -- 指示操作是否成功
          @_message nvarchar(4000) out  -- 操作中产生的消息
      

      • @senderId

        必须提供。消息发送人的 Id，通常是当前用户的 Id。用户应该来自于 waln.authority 应用。

      • @receivers

        必须提供。接收用户的 Id 的列表，多个之间使用 , 分隔。列表中的 Id 必须是长度为 22 的 base64 格式的 UUID。

      • @urgency

        必须提供。紧急程度代码：1-常规，2-紧急，4-特急，不支持组合模式。

      • @group

        可选。通知的分组名称，可以不提供。该参数由用户自定义，通常提供一个简短的分组名称，比如 “审核”、“审批”、“活动”。通知在通知中心列表中显示时会使用该分组名称对通知消息进行分组显示。如果通知的紧急程度不是常规，通知消息总是会被显示在 “紧急” 分组中。

      • @title

        必须提供。通知的标题，应该总是提供该参数。

      • @summary

        可选。通知消息的摘要。如果没有提供摘要信息，则自动截取通知正文的前 200 个字符。

      • @body

        必须提供。通知消息的正文。

      • @bodyType

        必须提供。通知正文的类型代码：1-纯文本，2-HTML。

      • @funcUrl

        可选。如果提供了该链接路径，那么通知标题将显示为一个链接，点击该链接会跳转到此路径。

      • @refDataType

        可选。通知消息引用的数据记录的类型，由调用方自定义。参见 $refDataKey。

      • @refDataKey

        可选。通知消息引用的数据记录的键值，由调用方自定义。

        通知消息在创建后，仍然可能因为一些原因被删除或者修改。业务系统在发送了通知消息后，无法获得通知消息自身的 Id 值，如果要对目标通知消息进行变更或删除，需要通过通知消息引用的数据来查找目标通知消息。

      • @attachmentName

        可选。通知消息附件文件的名称。

      • @attachmentMime

        可选。通知消息附件文件的 MIME 类型。

      • @attachmentSize

        可选。通知消息附件文件大小，单位：字节。

      • @attachmentUrl

        可选。通知消息附件文件的虚拟路径。

      • @attachmentUploaderId

        可选。通知消息附件文件上传用户的 Id。

      • @attachmentUploadTime

        可选。通知消息附件文件上传时间。

      • @_context

        可选。当前上下文环境参数，这是一个 JSON 格式的字符串，其中包含了当前客户端的 IP 地址、首选语言等参数。格式为：{"ip":"IPv4|IPv6","lang":"zh-CN"}。参数值由中间层自动组织和传递。

      • @_success

        如果通知消息发送成功，则返回 true，否则返回 false。

      • @_message

        当通知消息发送失败时，返回错误消息。

      • 返回结果集合

        除了 out 参数外，如果通知消息创建成功，此存储过程还返回两个结果集合。第一个结果集合为新创建的通知记录的列表，通知记录的结构为视图 waln_notifying.v_service_notification 的结构。第二个结果集合只有提供了附件时才会出现，而且结果集合中只有一条记录，记录结构为视图 waln_notifying.v_service_attachment 的结构。

   2. 描述

      沃恩提供的通知服务中除了面向最终用户的、具有用户界面的通知发送功能和通知列表外，还提供了服务形式的通知发送接口。开发者可以直接调用服务 API 向用户发送通知消息。

      此存储过程位于 waln.notifying 应用的 procedures.sql 文件中。

6. waln_notifying.p_service_update

   根据通知消息引用的数据记录键值更新此前已经发送的一组通知消息。

   1. 语法

      exec "waln_notifying"."p_service_update"
          @senderId uniqueidentifier, -- 发送用户的 Id 
          @refDataType nvarchar(64), -- 引用数据的类型 
          @refDataKey nvarchar(50), -- 引用数据键值 
          @urgency tinyint, -- 紧急程度：1-常规，2-紧急，4-特急 
          @group nvarchar(30), -- 分组 
          @title nvarchar(50), -- 通知标题 
          @summary nvarchar(200), -- 通知消息摘要 
          @body nvarchar(max), -- 通知正文内容 
          @bodyType tinyint, -- 正文类型代码：1-纯文本，2-HTML 
          @funcUrl nvarchar(300), -- 目标功能路径 
          @attachmentName nvarchar(100), -- 附件文件名称 
          @attachmentMime nvarchar(100), -- 附件 MIME 类型 
          @attachmentSize bigint, -- 附件文件的大小 
          @attachmentUrl nvarchar(300), -- 文件路径 
          @attachmentUploaderId uniqueidentifier, -- 上传人的 Id 
          @attachmentUploadTime datetime2, -- 上传时间 
          @oldAttachmentUrl nvarchar(300), -- 原附件文件路径 
          @_context nvarchar(4000), -- 当前环境变量参数
          @_success bit out, -- 指示操作是否成功
          @_message nvarchar(4000) out  -- 操作中产生的消息
      

      • @senderId

        必须提供。消息发送人的 Id，通常是当前用户的 Id。用户应该来自于 waln.authority 应用。

      • @refDataType

        必须提供。通知消息引用的数据记录的类型，由调用方自定义。参见 $refDataKey。

      • @refDataKey

        必须提供。通知消息引用的数据记录的键值，由调用方自定义。

      • @urgency

        必须提供。紧急程度代码：1-常规，2-紧急，4-特急，不支持组合模式。

      • @group

        可选。通知的分组名称，可以不提供。该参数由用户自定义，通常提供一个简短的分组名称，比如 “审核”、“审批”、“活动”。通知在通知中心列表中显示时会使用该分组名称对通知消息进行分组显示。如果通知的紧急程度不是常规，通知消息总是会被显示在 “紧急” 分组中。

      • @title

        必须提供。通知的标题，应该总是提供该参数。

      • @summary

        可选。通知消息的摘要。如果没有提供摘要信息，则自动截取通知正文的前 200 个字符。

      • @body

        必须提供。通知消息的正文。

      • @bodyType

        必须提供。通知正文的类型代码：1-纯文本，2-HTML。

      • @funcUrl

        可选。如果提供了该链接路径，那么通知标题将显示为一个链接，点击该链接会跳转到此路径。

      • @attachmentName

        可选。通知消息附件文件的名称。

      • @attachmentMime

        可选。通知消息附件文件的 MIME 类型。

      • @attachmentSize

        可选。通知消息附件文件大小，单位：字节。

      • @attachmentUrl

        可选。通知消息附件文件的虚拟路径。

      • @attachmentUploaderId

        可选。通知消息附件文件上传用户的 Id。

      • @attachmentUploadTime

        可选。通知消息附件文件上传时间。

      • @oldAttachmentUrl

        这是一个输出参数。如果前后附件不是同一个附件，那么原来的附件在没有其他通知消息引用的情况下将被删除。通过此参数返回原来附件的虚拟路径，这样中间层就可以使用 VirtualFile.delete() 删除附件文件，避免不再使用的附件占用磁盘空间。

      • @_context

        可选。当前上下文环境参数，这是一个 JSON 格式的字符串，其中包含了当前客户端的 IP 地址、首选语言等参数。格式为：{"ip":"IPv4|IPv6","lang":"zh-CN"}。参数值由中间层自动组织和传递。

      • @_success

        如果通知消息发送成功，则返回 true，否则返回 false。

      • @_message

        当通知消息发送失败时，返回错误消息。

      • 返回结果集合

        除了 out 参数外，如果通知消息更新成功，此存储过程还返回两个结果集合。第一个结果集合为新创建的通知记录的列表，通知记录的结构为视图 waln_notifying.v_service_notification 的结构。第二个结果集合只有提供了附件时才会出现，而且结果集合中只有一条记录，记录结构为视图 waln_notifying.v_service_attachment 的结构。

   2. 描述

      沃恩提供的通知服务中除了面向最终用户的、具有用户界面的通知发送功能和通知列表外，还提供了服务形式的通知发送接口。开发者可以直接调用服务 API 向用户发送通知消息。

      此存储过程位于 waln.notifying 应用的 procedures.sql 文件中。

7. waln_notifying.p_service_delete

   根据通知消息引用的数据记录键值删除此前已经发送的一组通知消息。

   1. 语法

      exec "waln_notifying"."p_service_delete"
          @senderId uniqueidentifier, -- 发送用户的 Id 
          @refDataType nvarchar(64), -- 引用数据的类型 
          @refDataKey nvarchar(50), -- 引用数据键值 
          @attachmentUrl nvarchar(300), -- 附件文件路径 
          @_context nvarchar(4000), -- 当前环境变量参数
          @_success bit out, -- 指示操作是否成功
          @_message nvarchar(4000) out  -- 操作中产生的消息
      

      • @senderId

        必须提供。消息发送人的 Id，通常是当前用户的 Id。用户应该来自于 waln.authority 应用。

      • @refDataType

        必须提供。通知消息引用的数据记录的类型，由调用方自定义。参见 $refDataKey。

      • @refDataKey

        必须提供。通知消息引用的数据记录的键值，由调用方自定义。

      • @attachmentUrl

        这是一个输出参数。通知的附件在没有其他通知消息引用的情况下将被删除。通过此参数返回原来附件的虚拟路径，这样中间层就可以使用 VirtualFile.delete() 删除附件文件，避免不再使用的附件占用磁盘空间。

      • @_context

        可选。当前上下文环境参数，这是一个 JSON 格式的字符串，其中包含了当前客户端的 IP 地址、首选语言等参数。格式为：{"ip":"IPv4|IPv6","lang":"zh-CN"}。参数值由中间层自动组织和传递。

      • @_success

        如果通知消息发送成功，则返回 true，否则返回 false。

      • @_message

        当通知消息发送失败时，返回错误消息。

   2. 描述

      沃恩提供的通知服务中除了面向最终用户的、具有用户界面的通知发送功能和通知列表外，还提供了服务形式的通知发送接口。开发者可以直接调用服务 API 向用户发送通知消息。

      此存储过程位于 waln.notifying 应用的 procedures.sql 文件中。

8. waln_notifying.p_service_details

   根据通知消息引用的数据记录键值查找此前已经发送的一条通知消息。

   1. 语法

      exec "waln_notifying"."p_service_details"
          @senderId uniqueidentifier, -- 发送用户的 Id 
          @refDataType nvarchar(64), -- 引用数据的类型 
          @refDataKey nvarchar(50), -- 引用数据键值 
          @_context nvarchar(4000), -- 当前环境变量参数
          @_success bit out, -- 指示操作是否成功
          @_message nvarchar(4000) out  -- 操作中产生的消息
      

      • @senderId

        必须提供。消息发送人的 Id，通常是当前用户的 Id。用户应该来自于 waln.authority 应用。

      • @refDataType

        必须提供。通知消息引用的数据记录的类型，由调用方自定义。参见 $refDataKey。

      • @refDataKey

        必须提供。通知消息引用的数据记录的键值，由调用方自定义。

      • @_context

        可选。当前上下文环境参数，这是一个 JSON 格式的字符串，其中包含了当前客户端的 IP 地址、首选语言等参数。格式为：{"ip":"IPv4|IPv6","lang":"zh-CN"}。参数值由中间层自动组织和传递。

      • @_success

        如果通知消息发送成功，则返回 true，否则返回 false。

      • @_message

        当通知消息发送失败时，返回错误消息。

      • 返回结果集合

        除了 out 参数外，如果通知消息查询成功，此存储过程还返回两个结果集合。第一个结果集合为相关通知记录中的一条，通知记录的结构为视图 waln_notifying.v_service_notification 的结构。第二个结果集合只有使用了附件时才会出现，而且结果集合中只有一条记录，记录结构为视图 waln_notifying.v_service_attachment 的结构。

   2. 描述

      沃恩提供的通知服务中除了面向最终用户的、具有用户界面的通知发送功能和通知列表外，还提供了服务形式的通知发送接口。开发者可以直接调用服务 API 向用户发送通知消息。

      此存储过程位于 waln.notifying 应用的 procedures.sql 文件中。

9. waln_calendar.p_calc_diff

   计算从起始日期到截至日期的工作日的数目。

   1. 语法

      exec "waln_calendar"."p_calc_diff"
          @from date, -- 起始日期 
          @to date, -- 截至日期 
          @days int, -- 工作日数目 
          @_context nvarchar(4000), -- 当前环境变量参数
          @_success bit out, -- 指示操作是否成功
          @_message nvarchar(4000) out  -- 操作中产生的消息
      

      • @from

        必须提供。计算的起始日期，计算时包含此日期。

      • @to

        必须提供。计算的截至日期，计算时包含此日期。可以早于、等于或晚于起始日期。如果早于起始日期，那么计算结果小于 0。

      • @days

        返回工作日数目。

      • @_context

        可选。当前上下文环境参数，这是一个 JSON 格式的字符串，其中包含了当前客户端的 IP 地址、首选语言等参数。格式为：{"ip":"IPv4|IPv6","lang":"zh-CN"}。参数值由中间层自动组织和传递。

      • @_success

        如果通知消息发送成功，则返回 true，否则返回 false。

      • @_message

        当通知消息发送失败时，返回错误消息。

   2. 描述

      在很多业务系统中，需要根据工作日而不是自然日来计划工作流程，需要提供针对工作日的计算支持。

      此存储过程位于 waln.calendar 应用的 procedures.sql 文件中。

10. waln_calendar.p_calc_add

    在指定的日期上添加指定工作日后返回一个新日期。

    1. 语法

       exec "waln_calendar"."p_calc_add"
           @from date, -- 起始日期 
           @days int, -- 工作日数目 
           @to date out, -- 新日期 
           @_context nvarchar(4000), -- 当前环境变量参数
           @_success bit out, -- 指示操作是否成功
           @_message nvarchar(4000) out  -- 操作中产生的消息
       

       • @from

         必须提供。计算的起始日期。

       • @days

         必须提供。要添加的工作日数目，可以大于 0、小于 0 或等于 0，分别返回晚于起始日期、早于起始日期或等于起始日期的值。

       • @to

         返回截至日期。

       • @_context

         可选。当前上下文环境参数，这是一个 JSON 格式的字符串，其中包含了当前客户端的 IP 地址、首选语言等参数。格式为：{"ip":"IPv4|IPv6","lang":"zh-CN"}。参数值由中间层自动组织和传递。

       • @_success

         如果通知消息发送成功，则返回 true，否则返回 false。

       • @_message

         当通知消息发送失败时，返回错误消息。

    2. 描述

       在很多业务系统中，需要根据工作日而不是自然日来计划工作流程，需要提供针对工作日的计算支持。

       此存储过程位于 waln.calendar 应用的 procedures.sql 文件中。