Which API to use?

As discussed already, the selection of the appropriate language and API to use depends on:
  • Portability

    Ease of cross-platform development (single source code).

  • Compatibility

    The IBM Z platform provides source compatibility between z/OS®, z/VM and z/VSE when using LE programming interfaces.

    LE/VSE focuses on the interfaces defined by the C feature test macro _XOPEN_SOURCE_EXTENDED, where for example z/OS additionally provides slightly different interfaces, enabled by the feature test macro OE_SOCKETS.

  • Serviceability

    By decoupling the socket application from the TCP/IP product allows maintaining (servicing) both parts independently.

Portability, compatibility and serviceability aspects show up differently, depending on the programming language chosen.

Assembler

The SOCKET macro provided by TCP/IP not only supports writing socket based applications, but grants access to the built-in Telnet, FTP and LPR application level protocols as well. If Telnet, FTP and LPR protocol access isn't required, an LE conforming Assembler program can call the LE/VSE C socket interfaces instead of using the SOCKET macro to gain independence from the TCP/IP service level.

TCP/IP service affecting the SOCKET macro might require to reassemble the application.

The EZASMI macro and the EZASOKET call interface are mostly compatible with the corresponding z/OS interfaces. This eases cross-platform development. With both interfaces, socket applications are decoupled from the TCP/IP product, which allows both parts to be serviced independently.

COBOL and PL/I

Using the TCP/IP preprocessor API (EXEC TCP …) a stub routine linked edited with the user application
  • COBOL - IPNETXCO.OBJ
  • PL/I - IPNETXP.OBJ

TCP/IP service affecting those modules might require to re-link the application.

The following screen shows an example of the usage of the preprocessor interface. 

*
*    Attempt to open a connection
*
 EXEC TCP OPEN FOREIGNPORT(2000)
               FOREIGNIP(IPADDRESS)
               LOCALPORT(0)
               RESULTAREA(RESULTS)
               DESCRIPTOR(MY-DESC)
               ACTIVE
               WAIT(YES)
               ERROR(SECOND-TEST)
 END-EXEC.

Note that the EZASOKET call interface can be used with COBOL for VSE and PL/I for VSE programs as well.

C Language

Acknowledging the dominance of C in TCP/IP environments, LE/VSE provides C socket interfaces only. However, LE/VSE as well as the Language Environments in z/OS and z/VM, allows to call LE services from Assembler, COBOL and PL/I too. In addition you can also use the EZASOKET interface from COBOL and PL/1 programs.

The figure below shows the logical control flow of a LE/VSE C based socket application. The LE/C runtime decouples the application from a specific TCP/IP product. The LE/C TCP/IP Socket API Multiplexer allows to select an appropriate TCP/IP stack at runtime. Per default, the $EDCTCPV.PHASE is used to work with the TCP/IP stack partition. To use other LE/C TCP/IP Interface routines you can configure the LE/C TCP/IP Socket API Multiplexer. For example, phase IJBLFPLE to use the LFP LE/C TCP/IP interface or phase BSTTTCP6 to use the IPv6/VSE interface. To configure the multiplexer, use skeleton EDCTCPMC in ICCF library 62. Refer to Selecting the TCP/IP and SSL Implementation to use for information about how to select the TCP/IP and SSL implementation to use with your application using the LE/C Socket API Multiplexer.

Figure 1. Control Flow when using LE/VSE C Sockets with different TCP/IP stacks.
The control flow when using LE/VSE C Sockets is as follows: The socket application / LE/VSE stub routine calls the LE/VSE C-runtime, which then calls the LE/C socket API multiplexer. Then one of the TCP/IP stack partitions is called. Further explanation of this figure is provided in the surrounding text
Note:
  1. If you use the C for VSE compiler, you should use the socket API provided by the Language Environment® 1.4. The C header files required are provided in VSE library PRD2.SCEEBASE.
  2. If you use a non-LE enabled C compiler, for example C/370, you are restricted to use the native TCP/IP for z/VSE BSD-C interface. This includes the usage of the socket.h include file shipped in VSE library PRD2.TCPIPC.

The LE/C Socket Interface can be used with TCP/IP for z/VSE, IPv6/VSE, and Linux® Fast Path. For details refer to the corresponding product information.