使用 @CICSProgram 准备要由 CICS 程序调用的 OSGi 应用程序

注释可用于使 CICS 应用程序调用 Java main 方法 - CICS 会为您创建程序资源。 OSGi 应用程序在 OSGi JVM 服务器中运行，并且可以部署在 OSGi 捆绑软件 JAR 中。

1. 将 @CICSProgram 包添加到项目的依赖关系。
   • CICS Explorer 如果在 CICS Explorer 中使用预安装的 IBM® CICS Java SDK，则 SDK 包括 OSGi JVM 服务器库，作为 CICS TS 6.1 目标平台模板。
   • GradleMaven 如果您正在使用自己的构建工具链，那么需要声明对 Maven Central 上可用的 com.ibm.cics.server.invocation.annotations 工件的依赖关系，或者使用 com.ibm.cics.server.invocation.annotations.jar 文件。 有关更多信息，请参阅 使用 Gradle 和 Maven 管理 Java 依赖关系 以及 手动导入 Java 库。
2. 创建类以包含 CICS 调用的方法。 创建类是最佳实践，因为它使特定于 CICS的代码与应用程序的其他代码保持独立。
3. 对于您希望获得 CICS® LINK 资格的每个 Java 方法，请使用 @CICSProgram 对该方法进行注释。 安装应用程序时， CICS 会自动生成相应的 PROGRAM 定义 (或者您可以手动创建定义，这些定义将优先)。
4. 使用 @CICSProgram 注释对每个相关方法进行注释时，请为其提供 PROGRAM 名称的参数，例如 @CICSProgram("PROGNAME")。 CICS PROGRAM 名称必须:
   • 长度为 1-8 个字符。
   • 与模式 A-Z A-z 0-9 @#匹配。

   如何在简单类中注释 Java 方法的示例:

   public class CustomerLinkTarget
   {
       @CICSProgram("CUSTGET")
       public void getCustomer()
       {
           // do work here
       }
   }

5. 对 OSGi 捆绑软件项目启用注释处理。
   • CICS Explorer 如果您正在使用 CICS Explorer® ，请选择
     • 将鼠标悬停在带有警告下划线的 @CICSProgram 注释上，并使用快速修订来启用自动化处理，或者:
     • 右键单击插件项目并选择属性。 搜索 " 注释处理 " 页面，然后检查 启用特定于项目的设置 和 启用注释处理。
   • GradleMaven 如果要使用构建工具链 (例如 Gradle 或 Maven) ，请将 Java 编译器配置为使用 com.ibm.cics.server.invocation 作为注释处理器，如 使用 Gradle 和 Maven 管理 Java 依赖关系中所述。
6. 验证是否正确指定了注释。
   • CICS Explorer 如果您使用 CICS Explorer ，则会自动进行验证，以确保您的注解位置正确，且注解的方法和包含的类满足以下要求。
   • Maven 如果在 Eclipse中使用 Maven ，那么可以使用 m2e-apt 插件根据 pom.xml 文件中指定的依赖关系来获取在 Eclipse中配置的注释处理。

   注释必须:

   • 在方法上。
   • 具有 PROGRAM 名称的值属性。

   方法必须:

   • 具体而不抽象。
   • 没有参数。
   • 声明为 void。

   该类必须:

   • 除非所有带注释的方法都是静态的，否则请使用没有自变量 (隐式或显式) 的构造函数。
   • 顶级-非嵌套或匿名。
   • 没有多个使用相同 PROGRAM 名称进行注释的方法。
7. 编写注释方法的内容，这可能涉及:
   1. 从通道获取容器
   2. 从通道中的容器获取输入数据
   3. 使用数据映射代码将输入数据转换为 Java 对象
   4. 调用应用程序业务逻辑
   5. 使用数据映射代码将生成的 Java 对象转换为输出数据
   6. 将输出数据放在通道内的容器中

   具有单个方法 (使用 @CICSProgram 注释进行注释) 的类的示例，包括从容器获取输入数据并将输出数据放入容器中的代码:

   public class CustomerLinkTarget
   {
       @CICSProgram("CUSTGET")
       public void getCustomer()
       {
           Channel currentChannel = Task.getTask().getCurrentChannel();
           Container dataContainer = currentChannel.getContainer("DATA");
   
           // do work here
   
           Container resultContainer = currentChannel.createContainer("RESULT");
           byte[] results = null; // change this to be the result of the work
           resultContainer.put(results);
       }
   }

8. 构建应用程序。
   • CICS Explorer 如果使用 CICS Explorer ，可以右键单击 Web 项目并选择导出 > JAR 文件 ，或右键单击包含 CICS Bundle 项目并选择导出 Bundle 到 z/OS UNIX 文件系统。
   • 如果您正在使用 CICS 构建工具箱，那么将自动调用注释处理器。
   • GradleMaven 如果要使用其他工具构建 Java 代码，请确保使用 Maven Central 上的工件正确指定对 CICS 注释和注释处理器配置的依赖关系。 如果根据步骤 1 和 5 执行此操作，那么在构建期间将自动解析这些步骤。
     否则，必须确保 com.ibm.cics.server.invocation.annotations.jar JAR 文件 (定义 @CICSProgram 注释) 位于 Java 编译器的类路径上。 此外，请确保 com.ibm.cics.server.invocation.jar JAR 文件 (包含注释处理器) 位于 Java 编译器的类路径上，或者在 -processorpath 选项中以其他方式指定。 您可以在 z/OS® UNIX 上的 usshome/lib 目录中找到这两个 JAR 文件，其中 usshome 是 USSHOME 系统初始化参数的值。

     注: CICS 注释处理器会在 com.ibm.cics.server 包中生成其他类和 XML 文件，以表示带注释的资源以及带注释的代码。
9. 部署您的应用程序。 请参阅 在 JVM 服务器中部署 OSGi 捆绑软件 以获取更多信息。

EXEC CICS LINK PROGRAM("CUSTGET") CHANNEL()