编写转换器程序

要编写转换器程序，需要构造解码和编码函数，并考虑代码页转换问题。

注意: 本主题包含产品敏感的编程接口和关联的指导信息。

您可以使用汇编程序， C ， COBOL 或 PL/I 编写转换器程序。 转换器程序的参考信息中描述了依赖于语言的头文件，包含文件和副本。

解码函数：查看并处理 HTTP 请求

转换器程序的解码函数接收来自 Web 客户机的 HTTP 请求，以及用于提供有关该请求的更多信息的参数列表。 HTTP 请求会传递到转换器程序的一块 32K 存储器中， 该存储器区域由参数列表中的指针表示。 请求已被分为多个单独的元素，例如，方法、请求头和请求主体。 （请注意，如果请求太长而不适合存储器块，那么其余数据将不传递到转换器程序。） 如果处理路径中使用分析器程序，那么分析器程序可能修改了请求的内容。

在 CICS Web Support 的转换器程序中，可以使用 EXEC CICS WEB API 命令来检查 HTTP 请求 (如果您愿意)。 WEB EXTRACT 命令检索有关请求的信息（如方法和版本）。 WEB READ HTTPHEADER 命令或 HTTPHEADER 浏览命令可用于读取 HTTP 头。 WEB RECEIVE 命令可用于接收请求的主体。 如果使用任意一个 EXEC CICS WEB API 命令，那么请注意，这些命令将返回 Web 客户机请求中的原始信息，而且您不能使用它们来查看分析器程序所做的任何修改。 分析器程序所做的更改只会在直接传递给转换器程序的参数列表和存储器块中反映出来。

参数列表中提供了用户编写的应用程序的名称，这些程序用于为响应提供数据，而名称来自请求的 URIMAP 定义或由分析器程序设置。 如果使用了分析器程序，那么它可以通过用户令牌向转换器程序提供更多的信息。

通过使用您所获得的关于 Web 客户机请求的信息，转换器程序的解码函数需要：
  • 确定是否应该继续处理请求，或者 CICS® 是否应该向 Web 客户机返回错误响应。
  • 指定要处理请求并提供响应的用户编写的应用程序名。 如果名称已从 URIMAP 定义或由分析器程序输入，那么转换器程序可以接受或更改此内容。
  • 构造传递到用户编写的应用程序的 COMMAREA。 COMMAREA 包括来自 Web 客户机请求的数据，该请求已转换为应用程序可接受的输入格式。 可以复用包含 HTTP 请求的存储器块，或者可以指定新的 COMMAREA。

编码函数：生成响应

当用户编写的应用程序已通过使用由转换器程序提供的输入执行处理时， 转换器程序的编码函数会从应用程序接收输出 COMMAREA。 使用该数据，转换器程序的编码函数需要：
  • 如果需要多个应用程序提供数据，那么调用更多的应用程序。 为了做到这一点，编码函数会设置循环响应来再次调用解码函数。 解码函数更改应用程序的名称，并在 COMMAREA 中提供合适的输入。 输出将再次返回到编码函数。 从转换器程序调用多个应用程序 具有有关此操作的更多信息。
  • 构造要发送到 Web 客户机的 HTTP 响应。

在 CICS Web Support 的转换器程序中，可以使用 EXEC CICS WEB API 命令来生成响应并将它发送到 Web 客户机。 WEB WRITE HTTPHEADER 命令可用于编写响应的 HTTP 头。 WEB SEND 命令可用于组装并发送响应。

或者，可使用转换器程序在存储器缓冲区中手动构造 HTTP 响应， 然后将它返回给 CICS，以便发送到 Web 客户机。 响应必须包含 HTTP 版本、状态码、状态文本、所需的任何 HTTP 头和消息体。 响应的格式应该符合您正在遵从的 HTTP 协议规范（HTTP/1.0 或 HTTP/1.1）。 要获取 HTTP 响应的存储缓冲区，您可以：
  • 发出 GETMAIN 命令以获取存储器。
  • 使用在处理的早期阶段（例如分析器程序）中获得的存储器。
  • 构造用户编写的应用程序返回的 COMMAREA 中的响应。
用于响应的区域的第一个字必须包含区域长度（也就是说，HTTP 响应长度加 4）。 在转换器程序的编码函数的出口，参数列表中的数据指针必须指向该存储器块。 （如果使用 EXEC CICS WEB API 命令来发送响应，那么 CICS 会忽略并丢弃该指针所表示的任何存储器块。）

无论您使用哪种方法来构造 HTTP 响应， CICS 通常都会插入一些适用于 HTTP/1.0 或 HTTP/1.1 响应的 HTTP 头，这些头在 CICS Web Support 的 HTTP 头引用中列出。 如果转换器程序生成的响应已包含这些头，那么 CICS 不会替换这些头。 如果分析器程序针对CICS TS V 3 之前的兼容性处理标记了响应，因为 Web 客户机需要与 CICS TS V 3 之前接收的响应相同的响应，那么将仅使用在 CICS Transaction Server for z/OS®V 3 发行版 1 之前发送到客户机的头。 仅当使用转换器程序在存储器块中手动生成响应时，该标志才起作用。 如果转换器程序使用 EXEC CICS WEB API 命令发送响应，那么该标志无效。

代码页转换

在转换器程序中使用 EXEC CICS WEB API 命令来查看 HTTP 请求并生成响应时，将按照您在命令中指定的方式进行代码页转换，其方式与使用 EXEC CICS WEB API 命令的任何其他程序相同。

转换器程序无法为传入 32K 存储器块的 HTTP 请求指定代码页转换设置。 如果从 URIMAP 定义直接调用转换器程序，并且 Web 客户机请求的头指示消息体为文本，那么 CICS 将使用以下标准设置来转换存储器块中提供的消息体:
  • 对于字符集，如果 Web 客户机的请求具有用于命名 CICS支持的字符集的 Content-Type 头，那么将使用该字符集。 如果 Web 客户机的请求没有 Content-Type 头或指定的字符集不受支持，那么使用 ISO-8859-1 字符集。
  • 对于主机代码页， CICS 使用本地 CICS 区域的缺省代码页，如 LOCALCCSID 系统初始化参数中所指定。

如果这些标准设置不合适，或者如果不希望进行代码页转换，那么在处理路径中使用分析器程序来指定备用代码页转换设置， 或使用 EXEC CICS WEB API 命令来处理请求。

如果转换器程序在存储器缓冲区中手动构造 HTTP 响应，那么 CICS 将镜像对在 32K 存储器块中传递的请求执行的代码页转换。 通过使用由分析器程序指定的字符集和主机代码页设置，或在缺少分析器程序时使用本主题中描述的标准设置， 将响应发送到 Web 客户机。 如果分析器程序禁止对请求执行代码页转换，那么不会对响应主体执行代码页转换。 如果此结果不适合，请改为使用 EXEC CICS WEB API 命令生成响应。

CICS 业务逻辑接口的转换器程序

将转换器程序与 CICS 业务逻辑接口配合使用时，存在一些限制，这些限制可能会影响您构造传递到用户编写的应用程序的 COMMAREA 的方式以及包含响应的存储器的缓冲区。 有关更多信息，请参阅 偏移方式和指针方式。

不要在为 CICS 业务逻辑接口编写的转换器程序中使用 EXEC CICS WEB API 命令。