Sample programs: sending and receiving HTTP requests in chunks

Sample programs DFH$WBCA (assembler language), DFH$WBCC (C), and DFH0WBCO (COBOL) demonstrate how CICS®, as an HTTP client, can send a request in sections or chunks to an HTTP server and receive a chunked message in response. Sample programs DFH$WBHA (assembler language), DFH$WBHC (C), and DFH0WBHO (COBOL) demonstrate how CICS, as an HTTP server, can receive a request in chunks from an HTTP client and send a chunked response.

1. Identify the CICS region that will be the HTTP client.
   To try out the sample programs, you have three options:
   • You can use the same CICS region as both the server and the client; the requests will go out of and into the region as they would with two separate CICS regions, and the results are the same. In this case, no further CICS web support setup is required, because a CICS region that operates as an HTTP server can also operate as an HTTP client.
   • You can use a different CICS region as the client, which has already been set up for CICS web support. Again, in this case, no further CICS web support setup is required.
   • You can use a different CICS region as the client, which has not yet been set up for CICS web support. In this case, you must carry out some basic CICS web support setup, described in Step 2.
2. Optional: If you are using a different CICS region as the HTTP client, and the region has not yet been set up for CICS web support, carry out basic setup:
   1. Enable TCP/IP support for the CICS region, following the instructions in Enabling TCP/IP in a CICS(r) region .
      This process includes setting up Communications Server and establishing access to a DNS, or domain name, server through z/OS®.
   2. Specify the system initialization parameter TCPIP=YES for the region to activate CICS TCP/IP services.
   This setup enables the CICS region to function as an HTTP client.
3. In the CICS region that you set up as an HTTP server, identify the TCPIPSERVICE definition for a port that the client region can use to make its requests.
   Select any port that is defined with the HTTP protocol, but does not use SSL, so with a TCPIPSERVICE definition that specifies PROTOCOL(HTTP) and SSL(NO). You can choose any suitable port because the sample URIMAP definition DFH$URI4, which is used on the server to access the server chunking sample program, matches any host name and port number.
4. In the HTTP client region, modify the supplied sample URIMAP definition DFH$URI3, which is provided in the DFH$WEB resource definition group. Because DFH$WEB is a protected group, you copy the definition to another group to enable editing.
   DFH$URI3 is a URIMAP definition with a usage attribute of CLIENT. It specifies the components of the URL that the sample programs use to make the requests to the HTTP server region.
   1. Do not change the scheme (SCHEME attribute) specified in DFH$URI3 as HTTP.
   2. DFH$URI3 specifies a dummy host name (HOST attribute). Modify it to insert the real host name:
      • Specify the host name assigned to the z/OS image for the HTTP server region. If you do not know the host name, you can use the IP address from the TCPIPSERVICE definition that you selected in Step 3.
      • If the TCPIPSERVICE definition that you selected is for a port number other than 80 (the commonly used port number for HTTP), specify the port number from the TCPIPSERVICE definition after the host name, with a colon separating the host name and port number.
   3. Do not change the path (PATH attribute) specified in DFH$URI3 as /chunking_sample_application , which is matched by DFH$URI4.
5. In the HTTP client region, install your modified URIMAP definition DFH$URI3.
6. In the HTTP client region, install the PROFILE definition DFH$WBPF, which is provided in the DFH$WEB resource definition group.
7. Translate and compile a client and a server sample program in the required language.
   The chunking sample programs are not compiled when you receive them. The sample programs are supplied in the SDFHSAMP library. Here are the names of the sample programs and their corresponding transactions:

   Type of Sample	Language	Program	Transaction
   Client chunking sample	assembler	DFH$WBCA	WBCA
   Client chunking sample	C	DFH$WBCC	WBCC
   Client chunking sample	COBOL	DFH0WBCO	WBCO
   Server chunking sample	assembler	DFH$WBHA	-
   Server chunking sample	C	DFH$WBHC	-
   Server chunking sample	COBOL	DFH0WBHO	-

8. In the HTTP server region, install the PROGRAM resource definition for your chosen server chunking sample program, and install the supplied sample URIMAP definition DFH$URI4.
   The resource definitions are provided in the DFH$WEB resource definition group.
   1. If you chose the C® or COBOL sample, modify the supplied sample URIMAP definition DFH$URI4 before installing it.
      Because DFH$WEB is a protected group, copy the definition to another group to enable editing.
   2. Change the program (PROGRAM attribute) specified by DFH$URI4, from DFH$WBHA (the assembler language chunking sample program), to your preferred server chunking sample program.
   3. Install your modified URIMAP definition DFH$URI4.
9. In the HTTP client region, install the PROGRAM resource definition and the corresponding TRANSACTION resource definition for your chosen client chunking sample program.
   The resource definitions are provided in the DFH$WEB resource definition group.
10. In the HTTP client region, run the transaction for your chosen client chunking sample.
    The sample program sends information messages to your terminal when it sends all four chunks of the message and two header trailers to the HTTP server successfully. A message is also displayed confirming that the receive occurred. If any of the sends fail, an error message is given instead. The content of the actual HTTP requests and responses is not displayed.
11. In the HTTP server region, your chosen server chunking sample is called by the corresponding client chunking sample.
    The sample program sends information messages to your terminal when it sends all four chunks of the message and two header trailers to the waiting HTTP client successfully. If any of the sends fail, an error message is given instead. The content of the actual HTTP requests and responses is not displayed.
12. When you have finished using the sample programs, for security reasons disable the URIMAP definitions, DFH$URI3 and DFH$URI4, and uninstall the sample TCPIPSERVICE definition HTTPNSS, if you were using it.