第八章 使用 ^%ZSTART 和 ^%ZSTOP 例程自定义启动和停止行为 - 设计注意事项

第八章 使用 ^%ZSTART 和 ^%ZSTOP 例程自定义启动和停止行为 - 设计注意事项

IRIS 可以在特定事件发生时执行自定义代码。需要两个步骤：

1. 定义 ^%ZSTART 例程、^%ZSTOP 例程或两者。

   注意：^%ZSTART 和 ^%ZSTOP 不包含在 IRIS 中，必须由用户创建。

   在这些例程中，可以定义子例程以在特定活动开始或停止时执行。

   ^%ZSTART 和 ^%ZSTOP 必须在 %SYS 命名空间中创建和定义，尽管它们可以映射到非默认数据库。

2. 使用管理门户配置 IRIS 以调用所需的子程序。

具体来说，如果定义例程 ^%ZSTART 和 ^%ZSTOP 并包含具有特定名称的子例程，系统会在活动开始或结束时自动调用这些子例程。子程序名称如下：

• SYSTEM — 当 IRIS 作为系统启动或停止时执行
• LOGIN — 当用户使用 %Service_Console 或 Service_Telnet 服务执行登录或注销时执行。
• JOB - 在 JOB 开始或结束时执行
• CALLIN：— 在外部程序开始或完成 CALLIN 时执行

例如，当用户登录时，系统会自动调用 LOGIN^%ZSTART（如果已定义）并且已使用管理门户启用此子例程。

这些子例程并非旨在进行复杂的计算或长时间运行。长时间的计算或潜在的长时间操作（如网络访问）将延迟活动的完成，直到被调用的例程返回。在这种情况下，用户可能需要很长时间才能登录，或者 JOB 吞吐量可能会因为启动时间太长而减少。

注意：这些子程序作为正常 IRIS 操作的一部分被调用。这意味着异常终止 IRIS 的外部事件（例如电源故障）不会生成对 ^%ZSTOP 的调用。

注意：如果系统实现了 ^%ZSTOP，并且应用程序实现了一个或多个 $HALT 例程，则直到最后一个 $HALT 以 HALT 命令终止时才执行 ^%ZSTOP 代码。 $HALT 例程未能发出其自己的 HALT 命令可能会阻止 ^%ZSTOP 代码运行。

设计注意事项

因为 ^%ZSTART 和 ^%ZSTOP 在某种程度上受限的环境中运行，设计者必须记住几件事，即：

• 例程必须用 ObjectScript 编写。
• 由于 ^%ZSTART 本质上就像使用无参数的新命令启动一样运行，因此它不能用于执行诸如为用户初始化局部变量之类的任务。
• 当调用任何例程入口点时，没有值作为参数传递。如果不同的算法适用于各种情况，被调用的入口点必须通过检查例程外部的数据来确定要做什么：全局变量、系统变量等。
• 确保例程在所有可能的条件下都表现良好。它们应该是防御性的。也就是说，他们应该检查以确保完成任务所需的所有资源都在手边，如果可能的话，在计算开始之前为他们预留这些资源。出现的错误被报告为系统功能的故障，因此从错误控制和处理的角度考虑设计是很重要的。在资源丢失或出现错误的情况下，未能正确考虑恢复会产生各种后果:系统间IRIS可能无法启动；Studio等主要功能可能行为怪异；或者可能发生更微妙和隐蔽的后果，而这些后果没有被立即发现。强烈建议在模拟条件下仔细编写和调试这些例程，然后在投入生产系统之前在模拟环境条件下进行测试。
• 不应该假设在以前的调用或不同的入口点中发现的条件仍然有效。例如，在对JOB^%ZSTART的连续调用之间，前一个调用使用的文件可能已经在这个调用发生之前被删除了。
• 每个入口点都应该有效地执行其任务。如果任务的一部分可能需要长时间运行，建议将足够的信息排队以完成任务，供应用程序的另一部分稍后完成。
• 如果一个入口点希望持久地保存数据，比如出于统计的目的，它必须使用像全局或外部文件这样的东西来保存数据。
• 例程应该对它们所运行的环境做最少的假设。例如，这些例程的开发人员不能假设程序总是在特定的作业号下执行。设计人员不能假定将以特定顺序调用各个入口点。提出实现 IRIS的多个过程的顺序很少是确定的。
• 该例程不能假设它在系统启动期间的特定时间点被调用。启动过程中的事件顺序可能会因发布而异，甚至会因重启而改变。
• 除了少数例外，例程必须让事情保持原样。作为这一原则的一个例证，在子例程中重新赋值$IO而不在进入和退出时保存和恢复它几乎是错误的来源。调用例程无法知道这些内容是否已更改，调用方很难防御执行环境的任何可能更改。因此，不干扰系统处理上下文的负担在于被调用的子例程。
• 无更改规则的一般例外是允许更改特定于应用程序或安装的进程本地值。例如，SYSTEM^%ZSTART入口点可以设置系统范围的默认值。同样，对于应用程序测试，它可以将日期设置为特定值，以验证月末处理。
• ^%ZSTOP不能包含对远程数据库中全局变量的引用。在调用它的时候，其中一些可能不再可以访问。
• 一旦在关闭过程中调用 SYSTEM^%ZSTOP，用户将无法再使用 JOB 命令启动新进程。允许现有流程完成。
• 如果这些例程映射到与 IRISSYS 不同的数据库，则 IRIS 将尝试从该数据库而不是 IRISSYS 执行它们。当然， IRIS 会事先确保调用例程具有对该数据库的适当访问权限。管理员有责任确保例程可以访问它从该命名空间所需的任何应用程序全局变量和映射。
• SYSTEM^%ZSTART 和 SYSTEM^%ZSTOP 在 $USERNAME 设置为 %SYSTEM 且 $ROLES 设置为 %All 的情况下运行。要使用不同的用户名运行代码，请使用 $SYSTEM.Security.Login() 设置所需的名称，然后继续您的自定义代码。如果在 SYSTEM^%ZSTART 代码中使用 JOB 来启动任何其他进程，这些进程将继承与启动进程相同的用户名（和角色）。

注意：^%ZSTART 和 ^%ZSTOP 中的所有入口点都在系统操作的关键点调用，并且可能对系统操作甚至系统数据产生广泛影响。这些例程的特定用途使得这种高级特权成为必要。因此，必须确保这些入口点可以调用的所有代码都已经过全面测试。此外，不允许通过 XECUTE 或间接运行任何用户指定的代码。

• 退出（即停止）进程可能会在任何需要分布式缓存集群数据服务器回答的引用上收到 <FUNCTION>错误。

注意：在升级时， IRIS 仅保留映射到 IRISSYS 数据库的 %Z* 例程，如果 .INT 或 .MAC 代码可用，则重新编译它们。在其他数据库中保存例程是站点管理员的责任。