EZASOKET APIs

XCICS/TS supports EZASOKET to emulate, as closely as possible, the IBM implementation documented in SC31-8518-01, "OS/390 SecureWay Communications Server: IP CICS Sockets Guide Version 2 Release 8" (1999). It also supports some, though not all, of the features introduced in the z/OS implementation documented in SC31-8807-02, "z/OS Communications Server: IP CICS Sockets Guide Version 1 Release 5" (2004).

The APIs currently supported are:

•

INITAPI

•

BIND

•

CONNECT

•	GETCLIENTID

•	GETHOSTBYNAME

•	GETHOSTBYADDR

•	GIVESOCKET

•

LISTEN

•

SELECT

•

SOCKET

•

READ

•

RECV

•

RECVFROM

•

SEND

•

SENDTO

•	TAKESOCKET

•

WRITE

Examples

XFRAME distribution contains some example programs that the demonstrates the usage of EZASOKET calls. They may be found in the $XFRAMEHOME/samples/xcics/ezasoket directory.

Differences

There are only few differences between IBM CICS and XCICS/TS implementation of EZASOKET. They involve:

•

INITAPI

•	TAKESOCKET and GIVESOCKET

•	SELECT calls between GIVESOCKET and CLOSE calls

INITAPI

INITAPI call has no effect on XCICS/TS: it may coded in the program but it causes no effect.

GIVESOCKET and TAKESOCKET

With GIVESOCKET and TAKESOCKET calls, the socket is passed between two "peer" processes, via the XCICS core process (main): the socket transfer is implemented with a proprietary mechanism, therefore programmers must only be aware of the following small differences while coding of application:

•	there is no need to call the GETCLIENTID

•	the socket identifier to transfer from the listener program to the server program is the return code of the GIVESOCKET call

This example shows the difference.

In the listener program:

CALL EZASOKET USING   EZASOKET-GIVESOCKET
                     CHILD-SOCKET
                     GIVESOCKET-CLIENT
                     EZASOKET-ERRNO
                     EZASOKET-RETCODE.
IF EZASOKET-RETCODE < 0
   PERFORM ERROR-HANDLING
END-IF
MOVE EZASOKET-RETCODE TO COMMAREA-SOCKET-ID
EXEC CICS START TRANSID('esrv')
               FROM(COMMAREA)
               LENGTH(LENGTH OF COMMAREA)
END-EXEC.

In the server program:

EXEC CICS RETRIEVE INTO(COMMAREA)
                  LENGTH(CALEN)
END-EXEC
CALL EZASOKET USING   EZASOKET-TAKESOCKET
                    COMMAREA-SOCKET-ID
                     TAKESOCKET-CLIENT
                     EZASOKET-ERRNO
                     EZASOKET-RETCODE.
IF EZASOKET-RETCODE < 0
   PERFORM ERROR-HANDLING
END-IF
MOVE EZASOKET-RETCODE TO CLIENT-SOCKET

SELECT between GIVESOCKET and CLOSE

As explained before, the GIVESOCKET passes the socket descriptor to another process through the core process, which is activated in parallel. There is therefore no longer need for the listener program to monitor the socket the wait for the other task to perform the GIVESOKET.

These calls to the SELECT should be removed.