For many years, SNA has been the communications method for IBM mainframes. However, the IBM mainframe has been dragged — clawing and screaming — into the world of IP. Now application programmers are being asked to write TCP/IP programs to communicate with off-platform applications. These off-platform applications can be a simple customer balance inquiry or a complicated modeling tool. The primary IBM Application Programming Interface (API) for IP is the EZA interface. The EZASMI macro is used for Assembler while the EZASOKET High-Level Language (HLL) interface is used for COBOL and sometimes Assembler. Although additional options are available when using the macro interface, a programmer can easily write a full-featured IP program using the HLL interface. Examples in this article will discuss the HLL interface with the end result being a programming example designed for use in a CICS environment. However, the calls discussed here can also be used in the batch environment. There are actually three major methods to use IP: Transmission Control Protocol (TCP), User Datagram Protocol (UDP), and Internet Control Message Protocol (ICMP). An application programmer would normally only use TCP, so this article will not discuss UDP or ICMP.
There are two sides of a TCP/IP conversation — the server side and the client side. A mainframe programmer may be required to write either side. A programmer will normally write a server program when the mainframe has data that some other system needs, while a client program will normally be required when the mainframe needs to extract data stored on another system. “Normal” does not mean “always.” A mainframe program that would normally be designed as the client might be designed to be the server side of the conversation simply because the mainframe has greater availability (i.e., uptime).
In this article, I will first discuss the simpler programming requirements for the client side, then move into the more complex server programming. You can download several executable sample TCP/IP programs from www.vse2pdf.com/coolstuff. I recommend that you download the BSTTEZ10, BSTTEZ11, BSTTEZ12, and BSTTEZ13 programs, along with the BSTTEZA copybook. Figures 1 through 8 are also available for download at www.vse2pdf.com/coolstuff. They are condensed versions of the main EZA API calls extracted from these programs. To shorten the sample code, I have combined multiple lines when it would not greatly affect the readability of the sample code.
Before I discuss the actual programming, let’s examine the basics of using the EZA HLL API. Figure 9 shows a basic call.
The function field will indicate to the API what service is being requested. The input_options may be several fields that are used by the API, but are not updated. The output_options may be several fields that will be updated by the API. The field errno provides detailed information about any errors but is only valid when retcode is “-1.” A zero or positive value in retcode indicates a successful call. For many calls, there will not be any “output options” fields as such. Instead, the response from the call is solely contained within the retcode field.
In the samples in Figures 1 through 8, any option that is not normally used by a programmer is set in the coding paragraph. All other options need to be set by the program logic prior to performing the specific paragraph. Examples of how to set the input option fields are included at the start of each paragraph as comments. Examples of how to handle the output option fields are included at the end of each paragraph as comments.
There are several rules you can follow to handle the retcode and errno fields:
- If retcode is -1, an error occurred during the call. Any other number (including negative numbers) indicates a successful completion.
- The errno field contains the actual error code only when the retcode indicates an error. At other times, this field is unpredictable.
- For calls that return data to the program, the retcode field contains the length of the data returned. It is not unusual for a receive type call to return a zero length. The programmer should be ready to issue another receive.
WRITING A CLIENT
There are five basic steps to programming the client: initialization, creating a connection, transferring the data, closing the connection, and termination. Figure 10 shows the process flow between a client and a simple server.