使用 PHP 在 CICS 上构建 REST 服务

在 CICS 中设置书库应用程序

这个部分概述在 CICS 中安装示例 LIBRARY 应用程序所需的管理任务，并描述如何从客户端上对该程序使用 COMMAREA 接口。必须使用这个接口编写用于访问书库程序的 PHP 脚本。

设置书库应用程序的步骤

书库应用程序要求创建并填充一个 VSAM 文件，并编译一个 COBOL 程序。同时也需要该文件和程序的 CICS 资源定义。下面详细描述这些步骤。假设您具有关于 CICS 配置流程的基础知识。

除了 PHP 之外（后文将就此进行讨论），还没有其他可以调用 LIBRARY 程序的机制（尽管您可以开发一个）。因此，用于验证文件和程序是否正确安装的方法还很少。由于这个原因，设置说明建议使用 CEMT 手动打开文件和加载程序，这样做可以检查这些定义。

创建和定义 VSAM 文件

示例书库程序需要一个 VSAM KSDS，用于保存目录内容。代码归档中的 library/jcl/LIBFILE 文件包含用于删除和重新创建所需数据集的示例 JCL，并使用适合的原始数据填充数据集。这个 JCL 必须传输到 z/OS® 系统的适当位置，并做出以下更改：

    * 使用适合您的环境的 JOB 卡替换原来的 JOB 卡。
    * 使用适合您的系统的数据集名称替换原来的数据集名称的所有实例（P8BUILD.CICS650.LIBRARY.LIBFILE）。在后面的 CICS FILE 定义中需要用到这里选择的名称。
    * 可选。您可以编辑书库的原始数据，保持一致性和完整性（见下面的解释）。

下面的步骤将完成 VSAM 文件的创建和定义：

   1. 提交前面修改的 LIBFILE JCL，并检查是否成功执行。
   2. 登录 CICS，并使用带有以下属性的 CEDA（或其他机制）创建一个 CICS FILE 定义：

      表 1. 创建 VSAM FILE 定义时使用的属性

      属性 值
      FILE LIBFILE
      GROUP LIBRARY
      DSName <As specified in LIBFILE JCL>
      RECORD FORMAT F
      ADD Yes
      BROWSE Yes
      DELETE Yes
      READ Yes
      UPDATE Yes


   3. 安装 LIBFILE 定义，并检查是否成功。
   4. 可选。使用 CEMT，或打开 LIBFILE 并检查是否成功打开：

      CEMT SET FILE(LIBFILE) OPEN


      建议使用这个步骤检查是否正确创建和定义文件，因为设置的检查可能不全面。

编译和定义 COBOL 程序

LIBRARY 应用程序的源代码位于 library/cobol/LIBRARY 文件中，用于编译源代码的示例 JCL 位于 library/jcl/LIBCOBOL 文件中，它们都包含在本文提供的示例代码压缩文件中。必须将这些文件传输到您的 z/OS 系统的适当位置，并且需要根据以下说明修改 LIBCOBOL JCL。提供的版本如下所示：

清单 1. 用于编译 LIBRARY 程序的 JCL

//LIBCOBOL JOB USER=P8BUILD,CLASS=A,MSGCLASS=A,NOTIFY=&SYSUID
// JCLLIB ORDER=CTS320.CICS650.SDFHPROC
//COMPCOB EXEC DFHZITCL,
//        PROGLIB=P8BUILD.CICS650.LOAD,
//        LNGPRFX=PP.COBOL390.V340,
//        CBLPARM=('NODYNAM,LIB,ADATA,RENT',  COMPILER OPTIONS
//          'CICS(''COBOL2,SP'')'),       TRANSLATOR OPTIONS
//        INDEX=CTS320.CICS650,
//        LIBPRFX=PP.ADLE370.ZOS190,
//        DSCTLIB=P8BUILD.CICS650.COPY
//COBOL.SYSIN  DD DSN=P8BUILD.CICS650.COBOL(LIBRARY),DISP=SHR
//COBOL.SYSADATA DD DSN=P8BUILD.CICS650.COBADATA(LIBRARY),
//        DISP=SHR
//LKED.SYSIN DD *
   NAME LIBRARY(R)
/*


需要做出以下更改：

    * 提供一个适合的 JOB 卡。
    * 更改所有数据集名称和前缀，让它们适合您的 z/OS 和 CICS。
    * 确保 COBOL.SYSADATA DD 定义指向一个带有可变长度记录的 PDS 成员，它适合保存 ADATA 输出。请参考 COBOL 编译器文档了解更多细节。

通过以下步骤完成 LIBRARY 应用程序的编译和安装：

   1. 提交前面修改的 LIBCOBOL JCL，并检查是否成功执行。
   2. 登录 CICS 并使用 CEDA（或其他机制）创建一个具有以下属性的 CICS PROGRAM：

      表 2. CICS PROGRAM 属性

      属性 值
      PROGRAM LIBRARY
      GROUP LIBRARY
      Language COBOL


   3. 安装 LIBRARY 程序定义并检查是否成功。
   4. 可选。对 LIBRARY 程序使用 CEMT 或 NEWCOPY，并检查它是否加载：

      CEMT SET PROGRAM(LIBRARY) NEWCOPY


      建议使用这个步骤检查该程序是否正确编译和定义，因为设置的检查可能不全面。

如何使用 COBOL Library 应用程序

CICS COMMAREA 应用程序的一个约定是，当被调用时，将向它传递一个包含输入数据的储存区域，有时也包含需要执行的操作的说明。在处理完成之后，将使用输出数据和来自该操作的响应代码覆盖存储区域。COMMAREA 存储区域的格式通常在一个 COBOL Copybook 中定义，后者包含在目标程序及其调用方中。

要使用这样的 CICS 程序，您不仅要了解该程序输入输出时所需的 COMMAREA 格式，还需要了解它支持的操作、期望的输入输出数据和响应代码。在 CA1S 中，由 JZOS 生成的记录类执行 COMMAREA 的数据结构的构建和解释。不过，PHP 应该负责设置所需的输入字段，并使用 JZOS 生成的 API 提取合适的输出数据。

本文提供的示例 Library 应用程序遵循这个标准模式，因此 PHP 程序员需要了解生成的 JZOS 记录类和 COMMAREA 接口的使用，以便能够从 PHP 脚本正确地调用 Library 应用程序。

书库的 COMMAREA 格式

下面展示了定义书库应用程序使用的 COMMAREA 格式的 COBOL 数据定义：

清单 2. 书库应用程序的 COBOL 数据定义

      01 DFHCOMMAREA.                                            
     *    LIBRARY COMMAREA structure                             
          03 LIB-REQUEST-TYPE          PIC X(6).                 
          03 LIB-RETURN-CODE           PIC 9(2).                 
          03 LIB-ITEM-COUNT            PIC 9(4).                 
          03 LIB-BOOK-ITEM OCCURS 24 TIMES.                      
              05 BOOK-ITEM-REF          PIC 9(4).                
              05 BOOK-TITLE             PIC X(20).               
              05 BOOK-AUTHOR            PIC X(20).               
              05 BOOK-LOAN-STATUS       PIC 9(2).                
                 88 BOOK-ONLOAN VALUE 1.                         
                 88 BOOK-UNLENT VALUE 0.                         
              05 BOOK-BORROWER          PIC X(20).               
              05 FILLER                 PIC X(14).


JZOS 记录生成器工具（随后介绍）将清单 2 中的定义转换成可以从 PHP 使用的 API，以从 COMMAREA 获取或设置字段。COBOL 中使用的字段名和 PHP 方法之间有一个直观的映射，因此可以将它们关联起来。

书库应用程序的使用

您只需了解目标 CICS 程序所需的 COMMAREA 格式，就能够正确调用该程序。此外，还需要程序的使用信息，比如程序支持什么操作，如何在 COMMAREA 中指定它们，每个操作的其他输入和输出，以及可能的结果和响应。清单 3 给出了书库应用程序的参考使用信息。

因为本文提供了调用书库应用程序所需的示例 PHP 脚本，所以您在首次设置时不需要这些信息，但您在理解、修改和重新实现脚本时，必须参考这些信息。

LIB-REQUEST-TYPE 是一个包含 6 个字符的文本字段，它决定书库应用程序将要执行的操作。在调用书库应用程序之前，必须将这个字段设置为以下值之一：

表 3. 书库应用程序的 LIB-REQUEST-TYPE 字段
LIB-REQUEST-TYPE 书库操作
LIST 通过数组 LIB-BOOK-ITEM 返回一个列出库中所有图书的列表。
库的最大容量最多只能包含 24 个元素。每个项都包含相关图书的完整细节。现有的图书数目由 LIB-ITEM-COUNT 返回。
QUERY 在第一个元素 LIB-BOOK-ITEM(1) 中返回指定图书的细节。
在 BOOK-ITEM-REF(1) 中输入所请求的图书的索引（参考）。
ADD 向书库添加一本新书；在 LIB-BOOK-ITEM(1) 中提供细节。假设库中还有空间（最大图书储存数为 24 本），新书的索引由 BOOK-ITEM-REF(1) 返回。
DELETE 从库中（如果存在的话）删除由 BOOK-ITEM-REF(1) 标识的图书。
BORROW 将由 BOOK-ITEM-REF(1) 指定的图书标记为正在借阅，并向这本书的记录中添加借阅者的名称（BOOK-BORROWER(1)）。
RETURN 将指定的书标记为未借阅，并从这本书的记录中删除借阅者的名字。由 BOOK-ITEM-REF(1) 标识将要返回的图书。

对于图书返回，书库应用程序根据请求操作的结果将 LIB-RETURN-CODE 设置为 2 位数字值：

表 4. 书库应用程序的返回代码
LIB-RETURN-CODE 含义
文件名 值 操作 条件
LIBRARY-OK 0 All 成功完成。
LIBRARY-NOTFOUND 1 All except LIST, ADD 在库中未找到指定的图书。
LIBRARY-ONLOAN 2 BORROW 图书已经借出。
LIBRARY-DUPLICATE 3 Not used 不应该发生。
LIBRARY-INVREQ 4 All 无效的用户请求。
LIBRARY-FULL 5 ADD 书库已满（最多只能储存 24 本书！）
LIBRARY-ERROR 99 All 意外处理错误。

在书库应用程序的 level-01 数据部分 (LIBRARY-CONSTANTS) 定义可用的请求类型和返回代码，这意味着可以通过 JZOS 记录生成器在 PHP 脚本中使用它们，实现方法与 COMMAREA 数据类似。

总体而言，如果要从 PHP 调用 CICS 程序，PHP 程序员需要具有等价于表 4 的信息，这些信息通常由维护该程序的 CICS 程序员以适当的形式提供。