z/OS Communications ServerVersion 2 Release 4

IP Sockets Application ProgrammingInterface Guide and Reference

IBM

SC27-3660-40

Note:

Before using this information and the product it supports, be sure to read the general information under“Notices” on page 803.

This edition applies to Version 2 Release 4 of z/OS® (5650-ZOS), and to subsequent releases and modifications untilotherwise indicated in new editions.

Last updated: 2019-07-02© Copyright International Business Machines Corporation 2000, 2019.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

Figures............................................................................................................... xiii

Tables...............................................................................................................xxiii

About this document.......................................................................................... xxvWho should read this document.............................................................................................................. xxvHow this document is organized.............................................................................................................. xxvHow to use this document.......................................................................................................................xxvi

How to contact IBM service............................................................................................................... xxviConventions and terminology that are used in this information............................................................ xxviHow to read a syntax diagram................................................................................................................ xxviiPrerequisite and related information....................................................................................................... xxx

Summary of changes for IP Sockets Application Programming Interface Guideand Reference.............................................................................................. xxxvChanges made in z/OS Communications Server Version 2 Release 4.................................................. xxxvChanges made in z/OS Communications Server Version 2 Release 3.................................................. xxxvChanges made in z/OS Version 2 Release 2...........................................................................................xxxv

Part 1. Overview....................................................................................................1

Chapter 1. Introducing TCP/IP concepts.....................................................................................................3TCP/IP concepts..................................................................................................................................... 3Understanding sockets concepts...........................................................................................................4

Introducing TCP/IP concepts: Programming with sockets..............................................................5Introducing TCP/IP concepts: Selecting sockets ............................................................................ 5Introducing TCP/IP concepts: Socket libraries................................................................................ 6Introducing TCP/IP concepts: Address families.............................................................................. 8Introducing TCP/IP concepts: Addressing sockets in an Internet domain..................................... 8

Chapter 2. Organizing a TCP/IP application program............................................................................... 13Client and server socket programs...................................................................................................... 13

Client/server socket programs: Iterative server socket programs............................................... 13Client/server socket programs: Concurrent server socket programs........................................... 14

Client/server socket programs: Call sequence in socket programs................................................... 15Call sequence in stream socket sessions.......................................................................................15Call sequence in datagram socket sessions.................................................................................. 16

Client/server socket programs: Blocking, nonblocking, and asynchronous socket calls.................. 17Client/server socket programs: Testing a program using a miscellaneous server.............................19Client/server socket programs: Testing a local machine using a loopback address..........................19Client/server socket programs: Accessing required data sets........................................................... 20

Part 2. Designing programs.................................................................................. 21

Chapter 3. Designing an iterative server program.................................................................................... 23Allocating sockets in an iterative server program............................................................................... 23Binding sockets in an iterative server program................................................................................... 25

Binding with a known port number................................................................................................ 25Binding using socket call gethostbyname......................................................................................25

iii

Binding a socket to a specific port number....................................................................................26Listening for client connection requests in an iterative server program............................................ 27Accepting client connection requests in an iterative server program................................................ 28Transferring data between sockets in an iterative server program.................................................... 30Closing a connection in an iterative server program........................................................................... 30

Active and passive closing in an iterative server program.............................................................30Shutdown call in an iterative server program................................................................................ 31Linger option in an iterative server program.................................................................................. 32

Chapter 4. Designing a concurrent server program..................................................................................33Concurrent servers in native MVS environment.................................................................................. 33MVS subtasking considerations in a concurrent server program....................................................... 34

Access to shared storage areas in a concurrent server program.................................................. 34Data set access in MVS................................................................................................................... 35Task and workload management in a concurrent server program................................................36Security considerations in a concurrent server program...............................................................36Reentrant code in a concurrent server program............................................................................37

Understanding the structure of a concurrent server program............................................................ 37Selecting requests in a concurrent server program............................................................................ 37Client connection requests in a concurrent server program...............................................................42

Passing sockets in a concurrent server program........................................................................... 42Transferring data between sockets in a concurrent server program..................................................45Closing a concurrent server program...................................................................................................45

Chapter 5. Designing a client program...................................................................................................... 47Allocating a socket in a client program................................................................................................47Connecting to a server in a client program..........................................................................................47Transferring data between sockets in a client program......................................................................48Closing a client program.......................................................................................................................48

Chapter 6. Designing a program to use datagram sockets.......................................................................49Datagram socket characteristics......................................................................................................... 49Understanding datagram socket program structure...........................................................................49Allocating a datagram socket...............................................................................................................50Binding datagram sockets to port numbers........................................................................................ 50Streamline data transfer using connect call........................................................................................50Transferring data between datagram sockets.....................................................................................50

Chapter 7. Transferring data between sockets.........................................................................................51Transferring data between sockets: Streams and messages............................................................. 51Transferring data between sockets: Data representation...................................................................54Using send() and recv() calls................................................................................................................55

The send() and recv() call conversation......................................................................................... 55Using socket calls in a network application................................................................................... 56Reading and writing data from and to a socket............................................................................. 57

Using sendto() and recvfrom() calls.....................................................................................................59

Chapter 8. Designing IPv6 programs ........................................................................................................61

Chapter 9. Designing multicast programs ................................................................................................63Designing multicast programs: Multicast source filters......................................................................63Designing multicast programs: IPv4 multicast options ..................................................................... 65

IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP................................................................... 65IP_ADD_SOURCE_MEMBERSHIP and IP_DROP_SOURCE_MEMBERSHIP................................... 68IP_BLOCK_SOURCE and IP_UNBLOCK_SOURCE...........................................................................69IP_MULTICAST_IF...........................................................................................................................70IP_MULTICAST_LOOP..................................................................................................................... 71IP_MULTICAST_TTL........................................................................................................................ 72

iv

Designing multicast programs: IPv6 multicast options...................................................................... 73IPV6_JOIN_GROUP and IPV6_LEAVE_GROUP..............................................................................73IPV6_MULTICAST_IF......................................................................................................................76IPV6_MULTICAST_LOOP................................................................................................................ 76IPV6_MULTICAST_HOPS................................................................................................................77

Designing multicast programs: Protocol-independent multicast options..........................................78MCAST_JOIN_GROUP and MCAST_LEAVE_GROUP.......................................................................78MCAST_JOIN_SOURCE_GROUP and MCAST_LEAVE_SOURCE_GROUP....................................... 80MCAST_BLOCK_SOURCE and MCAST_UNBLOCK_SOURCE.......................................................... 80

Designing multicast programs: IOCTL multicast commands..............................................................81SIOCGIPMSFILTER......................................................................................................................... 81SIOCGMSFILTER............................................................................................................................. 82SIOCSIPMSFILTER..........................................................................................................................82SIOCSMSFILTER............................................................................................................................. 82

Part 3. Application program interfaces................................................................. 83

Chapter 10. C Socket application programming interface........................................................................85Compiler restrictions with C applications............................................................................................85Compiling and linking C applications...................................................................................................86

C application compatibility considerations....................................................................................86C socket API: Non-reentrant modules........................................................................................... 86C socket API: Reentrant modules.................................................................................................. 88

C program compiler messages............................................................................................................ 91C program abends................................................................................................................................ 91C socket implementation..................................................................................................................... 92C socket header files............................................................................................................................ 92

Manifest.h header file..................................................................................................................... 93Prototyping......................................................................................................................................93

C structures.......................................................................................................................................... 93C socket API error messages and return codes.................................................................................. 94C socket calls........................................................................................................................................94

accept() .......................................................................................................................................... 94bind() .............................................................................................................................................. 96close() .............................................................................................................................................99connect() ........................................................................................................................................ 99endhostent() ................................................................................................................................ 102endnetent() .................................................................................................................................. 102endprotoent() ...............................................................................................................................103endservent() .................................................................................................................................103fcntl() ............................................................................................................................................103getclientid() ..................................................................................................................................105getdtablesize() ............................................................................................................................. 105gethostbyaddr() ........................................................................................................................... 106gethostbyname() ..........................................................................................................................107gethostent() ................................................................................................................................. 108gethostid() ....................................................................................................................................108gethostname() ..............................................................................................................................109getibmopt() .................................................................................................................................. 109getibmsockopt() ...........................................................................................................................111getnetbyaddr() ............................................................................................................................. 112getnetbyname() ........................................................................................................................... 112getnetent() ................................................................................................................................... 113getpeername() ............................................................................................................................. 114getprotobyname() ........................................................................................................................ 115getprotobynumber() .................................................................................................................... 115getprotoent() ................................................................................................................................116

v

getservbyname() ..........................................................................................................................116getservbyport() ............................................................................................................................ 117getservent() ..................................................................................................................................118getsockname() ............................................................................................................................. 118getsockopt() ................................................................................................................................. 119givesocket() ..................................................................................................................................124htonl() ...........................................................................................................................................125htons() .......................................................................................................................................... 126inet_addr() ................................................................................................................................... 126inet_lnaof() ...................................................................................................................................127inet_makeaddr() .......................................................................................................................... 127inet_netof() .................................................................................................................................. 128inet_network() ............................................................................................................................. 128inet_ntoa() ................................................................................................................................... 129ioctl() ............................................................................................................................................ 129listen() .......................................................................................................................................... 131maxdesc() .................................................................................................................................... 132ntohl() ...........................................................................................................................................133ntohs() .......................................................................................................................................... 133read() ............................................................................................................................................134readv() .......................................................................................................................................... 135recv() ............................................................................................................................................ 136recvfrom() .................................................................................................................................... 137recvmsg() ..................................................................................................................................... 139select() ......................................................................................................................................... 140selectex() ..................................................................................................................................... 143send() ........................................................................................................................................... 144sendmsg() .................................................................................................................................... 145sendto() ........................................................................................................................................147sethostent() ..................................................................................................................................148setibmopt() .................................................................................................................................. 149setibmsockopt() ...........................................................................................................................150setnetent() ................................................................................................................................... 151setprotoent() ................................................................................................................................152setservent() ..................................................................................................................................152setsockopt() ................................................................................................................................. 153shutdown() ................................................................................................................................... 156sock_debug() ............................................................................................................................... 157sock_do_teststor()........................................................................................................................157socket() ........................................................................................................................................ 158takesocket() ................................................................................................................................. 160tcperror() ......................................................................................................................................161write() ...........................................................................................................................................162writev() ......................................................................................................................................... 163

Sample C socket programs................................................................................................................ 164Executing TCPS and TCPC modules............................................................................................. 164Executing UDPS and UDPC modules............................................................................................164C socket TCP client....................................................................................................................... 165C socket TCP server...................................................................................................................... 166C socket UDP server..................................................................................................................... 168C socket UDP client...................................................................................................................... 170

Chapter 11. X/Open Transport Interface ............................................................................................... 173XTI software requirements................................................................................................................173What is provided with XTI..................................................................................................................173How XTI works in the z/OS environment...........................................................................................173Creating an application using the XTI protocol................................................................................. 174Coding XTI calls..................................................................................................................................174

vi

Coding XTI calls: Initializing a transport endpoint...................................................................... 174Coding XTI calls: Establishing a connection................................................................................ 175Coding XTI calls: Transferring data.............................................................................................. 175Coding XTI calls: Releasing a connection.................................................................................... 175Coding XTI calls: Disabling a connection.....................................................................................175Coding XTI calls: Managing events.............................................................................................. 176Coding XTI calls: Using utility calls.............................................................................................. 176Coding XTI calls: Using system calls............................................................................................176

Compiling and linking XTI applications using cataloged procedures...............................................177XTICL.............................................................................................................................................177XTIC...............................................................................................................................................179XTIS...............................................................................................................................................180

Understanding XTI sample programs................................................................................................180XTI socket client sample program............................................................................................... 181XTI socket server sample program.............................................................................................. 186

Chapter 12. Macro application programming interface..........................................................................193Sockets API environmental restrictions and programming requirements.......................................193Sockets API input register information............................................................................................. 194Sockets API output register information...........................................................................................195Sockets API compatibility considerations.........................................................................................195Defining storage for the macro API ...................................................................................................195Understanding common parameter descriptions............................................................................. 197Sockets API error messages and return codes................................................................................. 197Characteristics of sockets..................................................................................................................197Task management and asynchronous function processing..............................................................198

Macro API asynchronous function processing: How it works..................................................... 199Asynchronous exit environmental and programming considerations........................................ 201

Using an unsolicited event-exit routine.............................................................................................201Diagnosing problems in applications using the macro API.............................................................. 202Macros for assembler programs........................................................................................................ 202

ACCEPT......................................................................................................................................... 203BIND..............................................................................................................................................206BIND2ADDRSEL............................................................................................................................209CANCEL......................................................................................................................................... 212CLOSE............................................................................................................................................213CONNECT...................................................................................................................................... 215FCNTL............................................................................................................................................218FREEADDRINFO............................................................................................................................220GETADDRINFO..............................................................................................................................221GETCLIENTID................................................................................................................................228GETHOSTBYADDR........................................................................................................................ 230GETHOSTBYNAME........................................................................................................................232GETHOSTID.................................................................................................................................. 234GETHOSTNAME............................................................................................................................ 236GETIBMOPT.................................................................................................................................. 238GETNAMEINFO............................................................................................................................. 240GETPEERNAME.............................................................................................................................245GETSOCKNAME............................................................................................................................ 248GETSOCKOPT................................................................................................................................251GIVESOCKET.................................................................................................................................268GLOBAL......................................................................................................................................... 270INET6_IS_SRCADDR.................................................................................................................... 271INITAPI......................................................................................................................................... 274IOCTL............................................................................................................................................ 278LISTEN.......................................................................................................................................... 287NTOP............................................................................................................................................. 289PTON............................................................................................................................................. 291

vii

READ............................................................................................................................................. 293READV........................................................................................................................................... 295RECV..............................................................................................................................................297RECVFROM....................................................................................................................................301RECVMSG......................................................................................................................................305SELECT.......................................................................................................................................... 309SELECTEX......................................................................................................................................313SEND............................................................................................................................................. 318SENDMSG......................................................................................................................................320SENDTO.........................................................................................................................................324SETSOCKOPT................................................................................................................................ 327SHUTDOWN.................................................................................................................................. 345SOCKET......................................................................................................................................... 347TAKESOCKET................................................................................................................................ 350TASK..............................................................................................................................................352TERMAPI....................................................................................................................................... 353WRITE........................................................................................................................................... 354WRITEV......................................................................................................................................... 356

Macro interface assembler language sample programs...................................................................358EZASOKAS sample server program for IPv4............................................................................... 358EZASOKAC sample client program for IPv4................................................................................ 365EZASO6AS sample server program for IPv6............................................................................... 371EZASO6AC sample client program for IPv6.................................................................................381

Chapter 13. CALL instruction application programming interface.........................................................389CALL instruction API environmental restrictions and programming requirements.........................389CALL instruction API output register information............................................................................. 390CALL instruction API compatibility considerations...........................................................................390CALL instruction application programming interface (API).............................................................. 391Understanding COBOL, Assembler, and PL/I call formats................................................................391

COBOL language call format.........................................................................................................391Assembler language call format...................................................................................................391PL/I language call format............................................................................................................. 391

Converting parameter descriptions................................................................................................... 392Diagnosing problems in applications using the CALL instruction API..............................................392CALL instruction API error messages and return codes................................................................... 393Code CALL instructions...................................................................................................................... 393

ACCEPT......................................................................................................................................... 393BIND..............................................................................................................................................395BIND2ADDRSEL............................................................................................................................397CLOSE............................................................................................................................................400CONNECT...................................................................................................................................... 401FCNTL............................................................................................................................................404FREEADDRINFO............................................................................................................................406GETADDRINFO..............................................................................................................................407GETCLIENTID................................................................................................................................414GETHOSTBYADDR........................................................................................................................ 415GETHOSTBYNAME........................................................................................................................418GETHOSTID.................................................................................................................................. 420GETHOSTNAME............................................................................................................................ 421GETIBMOPT.................................................................................................................................. 422GETNAMEINFO............................................................................................................................. 424GETPEERNAME.............................................................................................................................428GETSOCKNAME............................................................................................................................ 430GETSOCKOPT................................................................................................................................432GIVESOCKET.................................................................................................................................448INET6_IS_SRCADDR.................................................................................................................... 450INITAPI......................................................................................................................................... 453

viii

IOCTL............................................................................................................................................ 455LISTEN.......................................................................................................................................... 464NTOP............................................................................................................................................. 465PTON............................................................................................................................................. 467READ............................................................................................................................................. 469READV........................................................................................................................................... 470RECV..............................................................................................................................................472RECVFROM....................................................................................................................................474RECVMSG......................................................................................................................................477SELECT.......................................................................................................................................... 481SELECTEX......................................................................................................................................485SEND............................................................................................................................................. 489SENDMSG......................................................................................................................................491SENDTO.........................................................................................................................................494SETSOCKOPT................................................................................................................................ 497SHUTDOWN.................................................................................................................................. 513SOCKET......................................................................................................................................... 515TAKESOCKET................................................................................................................................ 517TERMAPI....................................................................................................................................... 519WRITE........................................................................................................................................... 519WRITEV......................................................................................................................................... 521

Using data translation programs for socket call interface................................................................ 522Assembler language utility programs call format........................................................................522Data translation............................................................................................................................ 522Bit-string processing.....................................................................................................................523

Call interface sample programs.........................................................................................................534Sample code for IPv4 server program......................................................................................... 534Sample program for IPv4 client program.................................................................................... 537Sample code for IPv6 server program......................................................................................... 539Sample program for IPv6 client program.................................................................................... 543Common variables used in PL/I sample programs......................................................................546Common variables used in COBOL sample programs................................................................. 554COBOL call interface sample IPv6 server program..................................................................... 559COBOL call interface sample IPv6 client program...................................................................... 568

Chapter 14. REXX socket application programming interface...............................................................577Overview.............................................................................................................................................577

Supported REXX APIs...................................................................................................................577Prerequisites for using REXX sockets.......................................................................................... 577Format of the REXX socket function and return values...............................................................577REXX programming hints and tips................................................................................................578How structures are represented.................................................................................................. 580

Runtime functions..............................................................................................................................583ACCEPT......................................................................................................................................... 586BIND..............................................................................................................................................588BIND2ADDRSEL............................................................................................................................590CLOSE............................................................................................................................................592CONNECT...................................................................................................................................... 593FCNTL............................................................................................................................................596GETADDRINFO..............................................................................................................................597GETCLIENTID................................................................................................................................605GETDOMAINNAME....................................................................................................................... 607GETHOSTBYADDR........................................................................................................................ 607GETHOSTBYNAME........................................................................................................................608GETHOSTID.................................................................................................................................. 610GETHOSTNAME............................................................................................................................ 611GETNAMEINFO............................................................................................................................. 612GETPEERNAME.............................................................................................................................614

ix

GETPROTOBYNAME..................................................................................................................... 615GETPROTOBYNUMBER.................................................................................................................616GETSERVBYNAME........................................................................................................................ 617GETSERVBYPORT......................................................................................................................... 618GETSOCKNAME............................................................................................................................ 619GETSOCKOPT................................................................................................................................620GIVESOCKET.................................................................................................................................628INET6ISSRCADDR........................................................................................................................ 630INITIALIZE....................................................................................................................................632IOCTL............................................................................................................................................ 633LISTEN.......................................................................................................................................... 643READ............................................................................................................................................. 644RECV..............................................................................................................................................646RECVFROM....................................................................................................................................648RESOLVE....................................................................................................................................... 651SELECT.......................................................................................................................................... 652SEND............................................................................................................................................. 654SENDTO.........................................................................................................................................656SETSOCKOPT................................................................................................................................ 658SHUTDOWN.................................................................................................................................. 668SOCKET......................................................................................................................................... 669SOCKETSET...................................................................................................................................671SOCKETSETLIST........................................................................................................................... 672SOCKETSETSTATUS......................................................................................................................673TAKESOCKET................................................................................................................................ 674TERMINATE...................................................................................................................................676VERSION....................................................................................................................................... 677WRITE........................................................................................................................................... 677

Sample programs............................................................................................................................... 679Overview of REXX sample programs............................................................................................679The REXX-EXEC RSCLIENT sample program for IPv4.................................................................681The REXX-EXEC RSSERVER sample program for IPv4................................................................682The REXX-EXEC R6CLIENT sample program for IPv6.................................................................682The REXX-EXEC R6SERVER sample program for IPv6................................................................682AT-TLS security definitions for REXX samples.............................................................................683Running the REXX sample programs........................................................................................... 683Testing the GIVESOCKET and TAKESOCKET commands............................................................ 683

Chapter 15. Pascal application programming interface.........................................................................685Steps for Pascal language API procedure calls.................................................................................685Pascal language API software requirements.................................................................................... 686Pascal API header files...................................................................................................................... 686Pascal language API compatibility considerations........................................................................... 686Pascal language API data structures.................................................................................................687

Connection state...........................................................................................................................687Connection information record.................................................................................................... 688Notification record........................................................................................................................689File specification record............................................................................................................... 693

Pascal language API: using procedure calls......................................................................................694Notifications..................................................................................................................................694TCP initialization procedures........................................................................................................694TCP termination procedure.......................................................................................................... 694TCP communication procedures.................................................................................................. 694PING interface.............................................................................................................................. 694Monitor procedures...................................................................................................................... 694UDP communication procedures................................................................................................. 694Raw IP interface........................................................................................................................... 694Timer routines...............................................................................................................................694

x

Host lookup routines.................................................................................................................... 695Assembler calls.............................................................................................................................695Other routines...............................................................................................................................695

Pascal return codes............................................................................................................................695Pascal language API procedure calls................................................................................................ 697

AddUserNote................................................................................................................................ 697BeginTcpIp.................................................................................................................................... 698ClearTimer.................................................................................................................................... 698CreateTimer.................................................................................................................................. 699DestroyTimer................................................................................................................................ 699EndTcpIp.......................................................................................................................................699GetHostNumber............................................................................................................................700GetHostResol................................................................................................................................700GetHostString............................................................................................................................... 701GetIdentity....................................................................................................................................701GetNextNote................................................................................................................................. 702GetSmsg........................................................................................................................................703Handle...........................................................................................................................................703IsLocalAddress............................................................................................................................. 703IsLocalHost................................................................................................................................... 704MonQuery......................................................................................................................................705PingRequest..................................................................................................................................706RawIpClose...................................................................................................................................706RawIpOpen................................................................................................................................... 707RawIpReceive............................................................................................................................... 708RawIpSend....................................................................................................................................708ReadXlateTable............................................................................................................................. 709SayCalRe....................................................................................................................................... 710SayConSt.......................................................................................................................................710SayIntAd....................................................................................................................................... 711SayIntNum.................................................................................................................................... 711SayNotEn.......................................................................................................................................712SayPorTy....................................................................................................................................... 712SayProTy........................................................................................................................................712SetTimer........................................................................................................................................713TcpAbort........................................................................................................................................713TcpClose........................................................................................................................................714TcpFReceive, TcpReceive, and TcpWaitReceive.......................................................................... 714TcpFSend, TcpSend, and TcpWaitSend........................................................................................716TcpNameChange...........................................................................................................................718TcpOpen and TcpWaitOpen.......................................................................................................... 719TcpOption......................................................................................................................................721TcpStatus...................................................................................................................................... 721UdpClose.......................................................................................................................................722UdpNReceive................................................................................................................................ 723UdpOpen....................................................................................................................................... 724UdpReceive................................................................................................................................... 725UdpSend....................................................................................................................................... 725Unhandle.......................................................................................................................................726

Sample Pascal program..................................................................................................................... 727Building the sample Pascal API module...................................................................................... 727Running the sample module........................................................................................................ 727Sample Pascal application program............................................................................................ 728

Appendix A. Multitasking C socket sample program............................................ 733Server sample program in C.................................................................................................................... 733The subtask sample program in C...........................................................................................................738

xi

The client sample program in C...............................................................................................................740

Appendix B. Socket call error return codes......................................................... 743System error codes for socket calls........................................................................................................ 743

Sockets return codes (ERRNOs)........................................................................................................ 743z/OS UNIX return codes.......................................................................................................................... 754Additional return codes........................................................................................................................... 754

Sockets extended ERRNOs................................................................................................................ 755User abend U4093...................................................................................................................................759

Appendix C. Address family cross reference....................................................... 761

Appendix D. GETSOCKOPT/SETSOCKOPT command values.................................767

Appendix E. Abbreviations and acronyms........................................................... 771

Appendix F. GETNAMEINFO flags and returned information examples.................777

Appendix G. Related protocol specifications.......................................................779

Appendix H. Accessibility.................................................................................. 799

Notices..............................................................................................................803Terms and conditions for product documentation................................................................................. 804IBM Online Privacy Statement................................................................................................................ 805Policy for unsupported hardware............................................................................................................805Minimum supported hardware................................................................................................................805Programming interface information........................................................................................................806Policy for unsupported hardware............................................................................................................806Trademarks.............................................................................................................................................. 806

Bibliography...................................................................................................... 807

Index................................................................................................................ 813

Communicating your comments to IBM.............................................................. 829

xii

Figures

1. The TCP/IP protocol stack.............................................................................................................................3

2. Socket concept.............................................................................................................................................. 4

3. TCP/IP networking API relationship on z/OS................................................................................................6

4. The port concept........................................................................................................................................... 9

5. Port number assignments............................................................................................................................. 9

6. Iterative server main logic.......................................................................................................................... 14

7. A typical stream socket session..................................................................................................................16

8. A typical datagram socket session............................................................................................................. 17

9. Socket call variables....................................................................................................................................24

10. MVS TCP/IP socket descriptor table.........................................................................................................24

11. An application using the bind() call.......................................................................................................... 25

12. A bind() call using gethostbyname().........................................................................................................26

13. Variables used for the BIND call...............................................................................................................26

14. Variables used by the listen call............................................................................................................... 28

15. Variables used by the ACCEPT call........................................................................................................... 29

16. Socket states.............................................................................................................................................30

17. Closing sockets......................................................................................................................................... 31

18. Serialized access to a shared storage area.............................................................................................. 34

19. Synchronized use of a common service task........................................................................................... 35

20. Concurrent server in an MVS address space............................................................................................37

21. To set/test bits for SELECT calls............................................................................................................... 40

22. An application using the select() call........................................................................................................41

23. Accepting a client connection...................................................................................................................42

xiii

24. Giving a socket to a subtask..................................................................................................................... 44

25. Taking sockets from the main process..................................................................................................... 45

26. Finding the IP address of a server host using gethostbyname()............................................................. 47

27. Layout of a message between a TPI client and a TPI server................................................................... 52

28. Transaction request message segment................................................................................................... 52

29. The TCP buffer flush technique................................................................................................................ 53

30. Big or little endian byte order for a 2-byte integer...................................................................................54

31. An application using the send() and recv() calls...................................................................................... 56

32. An application using the sendto() and recvfrom() Calls...........................................................................59

33. IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP............................................................................. 68

34. IP_ADD_SOURCE_MEMBERSHIP and IP_DROP_SOURCE_MEMBERSHIP..............................................69

35. IP_BLOCK_SOURCE and IP_UNBLOCK_SOURCE..................................................................................... 70

36. IP_MULTICAST_IF .................................................................................................................................... 71

37. IP_MULTICAST_LOOP............................................................................................................................... 72

38. IP_MULTICAST_TTL...................................................................................................................................73

39. IPV6_JOIN_GROUP and IPV6_LEAVE_GROUP .......................................................................................76

40. IPV6_MULTICAST_IF................................................................................................................................ 76

41. IPV6_MULTICAST_LOOP ..........................................................................................................................77

42. IPV6_MULTICAST_HOPS.......................................................................................................................... 78

43. MCAST_JOIN_GROUP and MCAST_LEAVE_GROUP................................................................................. 79

44. MCAST_JOIN_SOURCE_GROUP and MCAST_LEAVE_SOURCE_GROUP................................................. 80

45. MCAST_BLOCK_SOURCE and MCAST_UNBLOCK_SOURCE.....................................................................81

46. Sample JCL for compiling non-reentrant modules.................................................................................. 87

47. Sample JCL for linking non-reentrant modules....................................................................................... 88

48. Sample JCL for running non-reentrant modules......................................................................................88

xiv

49. Sample JCL for compiling reentrant modules..........................................................................................89

50. Sample JCL for prelinking and linking reentrant modules.......................................................................90

51. Sample JCL for running the reentrant program....................................................................................... 91

52. C socket TCP client sample.................................................................................................................... 166

53. C socket TCP server sample................................................................................................................... 168

54. C socket UDP server sample...................................................................................................................170

55. C socket UDP client sample....................................................................................................................171

56. Using XTI with TCP⁄IP............................................................................................................................. 174

57. Sample compile and link-edit job control procedure.............................................................................178

58. Sample client execution job control procedure..................................................................................... 179

59. Sample server execution job control procedure....................................................................................180

60. Sample client code for XTI..................................................................................................................... 186

61. Sample server code for XTI.................................................................................................................... 192

62. ECB input parameter...............................................................................................................................199

63. User token setting...................................................................................................................................199

64. HOSTENT structure returned by the GETHOSTBYADDR macro............................................................ 231

65. HOSTENT structure returned by the GETHOSTBYNAME macro........................................................... 234

66. NUM_IMAGES field settings................................................................................................................... 239

67. EZASOKAS sample server program for IPv4..........................................................................................365

68. EZASOKAC sample client program for IPv4...........................................................................................371

69. EZASO6AS sample server program for IPv6..........................................................................................380

70. EZASO6AC sample client program for IPv6...........................................................................................388

71. Storage definition statement examples................................................................................................. 392

72. ACCEPT call instructions example..........................................................................................................394

73. BIND call instruction example................................................................................................................396

xv

74. BIND2ADDRSEL call instruction example..............................................................................................399

75. CLOSE call instruction example..............................................................................................................401

76. CONNECT call instruction example........................................................................................................ 403

77. FCNTL call instruction example..............................................................................................................405

78. FREEADDRINFO call instruction example..............................................................................................406

79. GETADDRINFO call instruction example................................................................................................408

80. GETCLIENTID call instruction example..................................................................................................415

81. GETHOSTBYADDR call instruction example.......................................................................................... 416

82. HOSTENT structure that is returned by the GETHOSTBYADDR call......................................................417

83. GETHOSTBYNAME call instruction example..........................................................................................418

84. HOSTENT structure returned by the GETHOSTYBYNAME call..............................................................419

85. GETHOSTID call instruction example.................................................................................................... 420

86. GETHOSTNAME call instruction example.............................................................................................. 421

87. GETIBMOPT call instruction example.................................................................................................... 423

88. Example of name field ........................................................................................................................... 424

89. GETNAMEINFO call instruction example............................................................................................... 425

90. GETPEERNAME call instruction example...............................................................................................429

91. GETSOCKNAME call instruction example.............................................................................................. 431

92. GETSOCKOPT call instruction example..................................................................................................433

93. GIVESOCKET call instruction example...................................................................................................449

94. INET6_IS_SRCADDR call instruction example...................................................................................... 451

95. INITAPI call instruction example........................................................................................................... 454

96. IOCTL call instruction example.............................................................................................................. 456

97. COBOL language example for SIOCGHOMEIF6..................................................................................... 457

98. COBOL language example for SIOCGIFNAMEINDEX............................................................................ 459

xvi

99. COBOL II example for SIOCGIFCONF.................................................................................................... 464

100. LISTEN call instruction example.......................................................................................................... 465

101. NTOP call instruction example............................................................................................................. 466

102. PTON call instruction example............................................................................................................. 468

103. READ call instruction example............................................................................................................. 470

104. READV call instruction example...........................................................................................................471

105. RECV call instruction example............................................................................................................. 473

106. RECVFROM call instruction example................................................................................................... 475

107. RECVMSG call instruction example......................................................................................................479

108. SELECT call instruction example..........................................................................................................483

109. SELECTEX call instruction example..................................................................................................... 486

110. SEND call instruction example............................................................................................................. 490

111. SENDMSG call instruction example..................................................................................................... 492

112. SENDTO call instruction example.........................................................................................................495

113. SETSOCKOPT call instruction example................................................................................................498

114. SHUTDOWN call instruction example.................................................................................................. 514

115. SOCKET call instruction example.........................................................................................................515

116. TAKESOCKET call instruction example................................................................................................ 518

117. TERMAPI call instruction example.......................................................................................................519

118. WRITE call instruction example........................................................................................................... 520

119. WRITEV call instruction example.........................................................................................................521

120. EZACIC04 EBCDIC-to-ASCII table.......................................................................................................523

121. EZACIC04 call instruction example..................................................................................................... 524

122. EZACIC05 ASCII-to-EBCDIC table.......................................................................................................524

123. EZACIC05 call instruct