Upload
others
View
18
Download
0
Embed Size (px)
Citation preview
z/OS Communications ServerVersion 2 Release 3
IP Sockets Application ProgrammingInterface Guide and Reference
IBM
SC27-3660-30
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 3 of z/OS® (5650-ZOS), and to subsequent releases and modifications untilotherwise indicated in new editions.
Last updated: 2019-06-21© 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 3.................................................. xxxvChanges made in z/OS Version 2 Release 2...........................................................................................xxxvz/OS Version 2 Release 1 summary of changes.....................................................................................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.......................................................................................................................................... 642READ............................................................................................................................................. 643RECV..............................................................................................................................................646RECVFROM....................................................................................................................................647RESOLVE....................................................................................................................................... 650SELECT.......................................................................................................................................... 651SEND............................................................................................................................................. 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................................................................................................................ 754User 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. EZACIC0