z/OS V2R3.0 Communications Server: IP Sockets Application ... · C Socket application programming...

z/OS Communications Server

IP Sockets Application ProgrammingInterface Guide and ReferenceVersion 2 Release 3

SC27-3660-30

IBM

Note:Before using this information and the product it supports, be sure to read the general information under Notices on page875.

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: January 22, 2018

Copyright IBM Corporation 2000, 2018.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

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

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

About this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixWho should read this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixHow this document is organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixHow to use this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx

How to contact IBM service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxConventions and terminology that are used in this information . . . . . . . . . . . . . . . . . . xxHow to read a syntax diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiPrerequisite and related information . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv

Summary of changes for IP Sockets Application Programming Interface Guide andReference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxixChanges made in z/OS Communications Server Version 2 Release 3. . . . . . . . . . . . . . . . xxixChanges made in z/OS Version 2 Release 2 . . . . . . . . . . . . . . . . . . . . . . . . xxixz/OS Version 2 Release 1 summary of changes . . . . . . . . . . . . . . . . . . . . . . . xxix

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 . . . . . . . . . . . . . . 9

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

Client/server socket programs: Iterative server socket programs. . . . . . . . . . . . . . . . . 16Client/server socket programs: Concurrent server socket programs. . . . . . . . . . . . . . . . 17

Client/server socket programs: Call sequence in socket programs . . . . . . . . . . . . . . . . . 17Call sequence in stream socket sessions . . . . . . . . . . . . . . . . . . . . . . . . . 17Call sequence in datagram socket sessions . . . . . . . . . . . . . . . . . . . . . . . . 18

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

Part 2. Designing programs . . . . . . . . . . . . . . . . . . . . . . . . . 25

Chapter 3. Designing an iterative server program . . . . . . . . . . . . . . . . . 27Allocating sockets in an iterative server program . . . . . . . . . . . . . . . . . . . . . . . 27Binding sockets in an iterative server program. . . . . . . . . . . . . . . . . . . . . . . . 29

Binding with a known port number . . . . . . . . . . . . . . . . . . . . . . . . . . 29Binding using socket call gethostbyname . . . . . . . . . . . . . . . . . . . . . . . . 30Binding a socket to a specific port number . . . . . . . . . . . . . . . . . . . . . . . . 30

Listening for client connection requests in an iterative server program. . . . . . . . . . . . . . . . 32Accepting client connection requests in an iterative server program . . . . . . . . . . . . . . . . 33Transferring data between sockets in an iterative server program . . . . . . . . . . . . . . . . . 35

Copyright IBM Corp. 2000, 2018 iii

Closing a connection in an iterative server program . . . . . . . . . . . . . . . . . . . . . . 35Active and passive closing in an iterative server program . . . . . . . . . . . . . . . . . . . 35Shutdown call in an iterative server program . . . . . . . . . . . . . . . . . . . . . . . 37Linger option in an iterative server program . . . . . . . . . . . . . . . . . . . . . . . 37

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

Access to shared storage areas in a concurrent server program . . . . . . . . . . . . . . . . . 40Data set access in MVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Task and workload management in a concurrent server program . . . . . . . . . . . . . . . . 43Security considerations in a concurrent server program. . . . . . . . . . . . . . . . . . . . 44Reentrant code in a concurrent server program . . . . . . . . . . . . . . . . . . . . . . 44

Understanding the structure of a concurrent server program . . . . . . . . . . . . . . . . . . . 44Selecting requests in a concurrent server program . . . . . . . . . . . . . . . . . . . . . . 45Client connection requests in a concurrent server program. . . . . . . . . . . . . . . . . . . . 50

Passing sockets in a concurrent server program . . . . . . . . . . . . . . . . . . . . . . 50Transferring data between sockets in a concurrent server program . . . . . . . . . . . . . . . . . 54Closing a concurrent server program . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

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

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

Chapter 7. Transferring data between sockets . . . . . . . . . . . . . . . . . . . 61Transferring data between sockets: Streams and messages . . . . . . . . . . . . . . . . . . . . 61Transferring data between sockets: Data representation . . . . . . . . . . . . . . . . . . . . . 64Using send() and recv() calls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

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

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

Chapter 8. Designing IPv6 programs . . . . . . . . . . . . . . . . . . . . . . . 71

Chapter 9. Designing multicast programs . . . . . . . . . . . . . . . . . . . . . 73Designing multicast programs: Multicast source filters . . . . . . . . . . . . . . . . . . . . . 74Designing multicast programs: IPv4 multicast options . . . . . . . . . . . . . . . . . . . . . 75

IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP . . . . . . . . . . . . . . . . . . . . 76IP_ADD_SOURCE_MEMBERSHIP and IP_DROP_SOURCE_MEMBERSHIP . . . . . . . . . . . . . 79IP_BLOCK_SOURCE and IP_UNBLOCK_SOURCE . . . . . . . . . . . . . . . . . . . . . 80IP_MULTICAST_IF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81IP_MULTICAST_LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82IP_MULTICAST_TTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Designing multicast programs: IPv6 multicast options . . . . . . . . . . . . . . . . . . . . . 84IPV6_JOIN_GROUP and IPV6_LEAVE_GROUP . . . . . . . . . . . . . . . . . . . . . . 84IPV6_MULTICAST_IF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87IPV6_MULTICAST_LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88IPV6_MULTICAST_HOPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

iv z/OS V2R3.0 Communications Server: IP Sockets Application Programming Interface Guide and Reference

Designing multicast programs: Protocol-independent multicast options . . . . . . . . . . . . . . . 90MCAST_JOIN_GROUP and MCAST_LEAVE_GROUP . . . . . . . . . . . . . . . . . . . . 90MCAST_JOIN_SOURCE_GROUP and MCAST_LEAVE_SOURCE_GROUP . . . . . . . . . . . . . 93MCAST_BLOCK_SOURCE and MCAST_UNBLOCK_SOURCE . . . . . . . . . . . . . . . . . 94

Designing multicast programs: IOCTL multicast commands . . . . . . . . . . . . . . . . . . . 95SIOCGIPMSFILTER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95SIOCGMSFILTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96SIOCSIPMSFILTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96SIOCSMSFILTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Part 3. Application program interfaces . . . . . . . . . . . . . . . . . . . . 97

Chapter 10. C Socket application programming interface . . . . . . . . . . . . . . 99Compiler restrictions with C applications . . . . . . . . . . . . . . . . . . . . . . . . . 99Compiling and linking C applications . . . . . . . . . . . . . . . . . . . . . . . . . . 100

C application compatibility considerations. . . . . . . . . . . . . . . . . . . . . . . . 100C socket API: Non-reentrant modules . . . . . . . . . . . . . . . . . . . . . . . . . 100C socket API: Reentrant modules . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

C program compiler messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107C program abends. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107C socket implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108C socket header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Manifest.h header file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Prototyping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

C structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109C socket API error messages and return codes . . . . . . . . . . . . . . . . . . . . . . . 110C socket calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

accept() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110bind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112close() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116connect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116endhostent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119endnetent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120endprotoent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120endservent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120fcntl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121getclientid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122getdtablesize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123gethostbyaddr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123gethostbyname() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124gethostent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125gethostid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126gethostname() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126getibmopt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127getibmsockopt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129getnetbyaddr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130getnetbyname() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130getnetent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131getpeername() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132getprotobyname() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133getprotobynumber() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133getprotoent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134getservbyname() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135getservbyport() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135getservent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136getsockname() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137getsockopt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138givesocket() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143htonl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145htons() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Contents v

inet_addr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145inet_lnaof() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146inet_makeaddr() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147inet_netof() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147inet_network() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148inet_ntoa() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148ioctl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149listen(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151maxdesc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152ntohl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153ntohs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153read() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154readv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155recv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156recvfrom() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157recvmsg(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159select() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161selectex() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164send() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165sendmsg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167sendto() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169sethostent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170setibmopt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170setibmsockopt(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171setnetent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173setprotoent(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173setservent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174setsockopt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174shutdown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178sock_debug() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179sock_do_teststor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180socket() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180takesocket() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183tcperror() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184write() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185writev() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Sample C socket programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Executing TCPS and TCPC modules. . . . . . . . . . . . . . . . . . . . . . . . . . 187Executing UDPS and UDPC modules . . . . . . . . . . . . . . . . . . . . . . . . . 188C socket TCP client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188C socket TCP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190C socket UDP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191C socket UDP client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

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

Coding XTI calls: Initializing a transport endpoint . . . . . . . . . . . . . . . . . . . . . 196Coding XTI calls: Establishing a connection . . . . . . . . . . . . . . . . . . . . . . . 197Coding XTI calls: Transferring data . . . . . . . . . . . . . . . . . . . . . . . . . . 197Coding XTI calls: Releasing a connection . . . . . . . . . . . . . . . . . . . . . . . . 197Coding XTI calls: Disabling a connection . . . . . . . . . . . . . . . . . . . . . . . . 197Coding XTI calls: Managing events . . . . . . . . . . . . . . . . . . . . . . . . . . 198Coding XTI calls: Using utility calls . . . . . . . . . . . . . . . . . . . . . . . . . . 198Coding XTI calls: Using system calls . . . . . . . . . . . . . . . . . . . . . . . . . 198

Compiling and linking XTI applications using cataloged procedures . . . . . . . . . . . . . . . . 198XTICL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199XTIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

vi z/OS V2R3.0 Communications Server: IP Sockets Application Programming Interface Guide and Reference

XTIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Understanding XTI sample programs . . . . . . . . . . . . . . . . . . . . . . . . . . 202

XTI socket client sample program . . . . . . . . . . . . . . . . . . . . . . . . . . 203XTI socket server sample program . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Chapter 12. Macro application programming interface . . . . . . . . . . . . . . . 219Sockets API environmental restrictions and programming requirements . . . . . . . . . . . . . . . 219Sockets API input register information . . . . . . . . . . . . . . . . . . . . . . . . . . 220Sockets API output register information . . . . . . . . . . . . . . . . . . . . . . . . . 221Sockets API compatibility considerations . . . . . . . . . . . . . . . . . . . . . . . . . 221Defining storage for the macro API . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Understanding common parameter descriptions . . . . . . . . . . . . . . . . . . . . . . . 223Sockets API error messages and return codes . . . . . . . . . . . . . . . . . . . . . . . . 223Characteristics of sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Task management and asynchronous function processing. . . . . . . . . . . . . . . . . . . . 225

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

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

ACCEPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230BIND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233BIND2ADDRSEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236CANCEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240CONNECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242FCNTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245FREEADDRINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248GETADDRINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249GETCLIENTID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257GETHOSTBYADDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258GETHOSTBYNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261GETHOSTID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263GETHOSTNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264GETIBMOPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266GETNAMEINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269GETPEERNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273GETSOCKNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276GETSOCKOPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279GIVESOCKET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295GLOBAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297INET6_IS_SRCADDR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298INITAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302IOCTL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305LISTEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315NTOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317PTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320READV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322RECV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324RECVFROM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327RECVMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330SELECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334SELECTEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339SEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343SENDMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346SENDTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349SETSOCKOPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353SHUTDOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370SOCKET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372TAKESOCKET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

Contents vii

TASK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377TERMAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379WRITEV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

Macro interface assembler language sample programs . . . . . . . . . . . . . . . . . . . . . 383EZASOKAS sample server program for IPv4 . . . . . . . . . . . . . . . . . . . . . . . 383EZASOKAC sample client program for IPv4 . . . . . . . . . . . . . . . . . . . . . . . 390EZASO6AS sample server program for IPv6 . . . . . . . . . . . . . . . . . . . . . . . 396EZASO6AC sample client program for IPv6 . . . . . . . . . . . . . . . . . . . . . . . 406

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

COBOL language call format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417Assembler language call format . . . . . . . . . . . . . . . . . . . . . . . . . . . 418PL/I language call format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

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

ACCEPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419BIND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422BIND2ADDRSEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427CONNECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429FCNTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432FREEADDRINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434GETADDRINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435GETCLIENTID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444GETHOSTBYADDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445GETHOSTBYNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448GETHOSTID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450GETHOSTNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451GETIBMOPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452GETNAMEINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455GETPEERNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459GETSOCKNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461GETSOCKOPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463GIVESOCKET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479INET6_IS_SRCADDR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481INITAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484IOCTL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486LISTEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498NTOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500PTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504READV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506RECV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508RECVFROM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510RECVMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513SELECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517SELECTEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521SEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527SENDMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529SENDTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533SETSOCKOPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536SHUTDOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552SOCKET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554

viii z/OS V2R3.0 Communications Server: IP Sockets Application Programming Interface Guide and Reference

TAKESOCKET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556TERMAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558WRITEV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560

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

Call interface sample programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575Sample code for IPv4 server program . . . . . . . . . . . . . . . . . . . . . . . . . 575Sample program for IPv4 client program . . . . . . . . . . . . . . . . . . . . . . . . 578Sample code for IPv6 server program . . . . . . . . . . . . . . . . . . . . . . . . . 580Sample program for IPv6 client program . . . . . . . . . . . . . . . . . . . . . . . . 584Common variables used in PL/I sample programs . . . . . . . . . . . . . . . . . . . . . 587Common variables used in COBOL sample programs . . . . . . . . . . . . . . . . . . . . 597COBOL call interface sample IPv6 server program . . . . . . . . . . . . . . . . . . . . . 603COBOL call interface sample IPv6 client program . . . . . . . . . . . . . . . . . . . . . 614

Chapter 14. REXX socket application programming interface . . . . . . . . . . . . 623Overview of the REXX socket API . . . . . . . . . . . . . . . . . . . . . . . . . . . 623

Supported REXX APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623Prerequisites for using REXX sockets . . . . . . . . . . . . . . . . . . . . . . . . . 623Format of the REXX socket function and return values . . . . . . . . . . . . . . . . . . . 623REXX programming hints and tips . . . . . . . . . . . . . . . . . . . . . . . . . . 624How structures are represented . . . . . . . . . . . . . . . . . . . . . . . . . . . 626

REXX runtime functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630ACCEPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632BIND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636BIND2ADDRSEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639CONNECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640FCNTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643GETADDRINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645GETCLIENTID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655GETDOMAINNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656GETHOSTBYADDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657GETHOSTBYNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658GETHOSTID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660GETHOSTNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661GETNAMEINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662GETPEERNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664GETPROTOBYNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666GETPROTOBYNUMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667GETSERVBYNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668GETSERVBYPORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669GETSOCKNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670GETSOCKOPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671GIVESOCKET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681INET6ISSRCADDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683INITIALIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686IOCTL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687LISTEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699RECV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702RECVFROM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704RESOLVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707SELECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708SEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712SENDTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714SETSOCKOPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715SHUTDOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729

Contents ix

SOCKET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730SOCKETSET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732SOCKETSETLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733SOCKETSETSTATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734TAKESOCKET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736TERMINATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740

REXX socket sample programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741Overview of REXX sample programs . . . . . . . . . . . . . . . . . . . . . . . . . 742The REXX-EXEC RSCLIENT sample program for IPv4 . . . . . . . . . . . . . . . . . . . 744The REXX-EXEC RSSERVER sample program for IPv4 . . . . . . . . . . . . . . . . . . . 744The REXX-EXEC R6CLIENT sample program for IPv6. . . . . . . . . . . . . . . . . . . . 745The REXX-EXEC R6SERVER sample program for IPv6 . . . . . . . . . . . . . . . . . . . 745AT-TLS security definitions for REXX samples . . . . . . . . . . . . . . . . . . . . . . 746Running the REXX sample programs . . . . . . . . . . . . . . . . . . . . . . . . . 746Testing the GIVESOCKET and TAKESOCKET commands . . . . . . . . . . . . . . . . . . 746

Chapter 15. Pascal application programming interface. . . . . . . . . . . . . . . 747Steps for Pascal language API procedure calls . . . . . . . . . . . . . . . . . . . . . . . 747Pascal language API software requirements . . . . . . . . . . . . . . . . . . . . . . . . 748Pascal API header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748Pascal language API compatibility considerations . . . . . . . . . . . . . . . . . . . . . . 749Pascal language API data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . 749

Connection state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749Connection information record . . . . . . . . . . . . . . . . . . . . . . . . . . . 750Notification record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752File specification record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757

Pascal language API: using procedure calls . . . . . . . . . . . . . . . . . . . . . . . . 757Notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758TCP initialization procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758TCP termination procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758TCP communication procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . 758PING interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758Monitor procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758UDP communication procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . 758Raw IP interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758Timer routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758Host lookup routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759Assembler calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759Other routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759

Pascal return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759Pascal language API procedure calls . . . . . . . . . . . . . . . . . . . . . . . . . . . 761

AddUserNote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761BeginTcpIp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762ClearTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762CreateTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762DestroyTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763EndTcpIp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763GetHostNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763GetHostResol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764GetHostString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764GetIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765GetNextNote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766GetSmsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767IsLocalAddress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767IsLocalHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768MonQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769PingRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770RawIpClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771

x z/OS V2R3.0 Communications Server: IP Sockets Application Programming Interface Guide and Reference

RawIpOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771RawIpReceive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772RawIpSend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773ReadXlateTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774SayCalRe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775SayConSt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775SayIntAd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775SayIntNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776SayNotEn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776SayPorTy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777SayProTy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777SetTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777TcpAbort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778TcpClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779TcpFReceive, TcpReceive, and TcpWaitReceive . . . . . . . . . . . . . . . . . . . . . . 779TcpFSend, TcpSend, and TcpWaitSend . . . . . . . . . . . . . . . . . . . . . . . . . 782TcpNameChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784TcpOpen and TcpWaitOpen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784TcpOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786TcpStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787UdpClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788UdpNReceive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789UdpOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790UdpReceive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791UdpSend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792Unhandle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792

Sample Pascal program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793Building the sample Pascal API module . . . . . . . . . . . . . . . . . . . . . . . . 793Running the sample module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793Sample Pascal application program . . . . . . . . . . . . . . . . . . . . . . . . . . 794

Part 4. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799

Appendix A. Multitasking C socket sample program. . . . . . . . . . . . . . . . 801Server sample program in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801The subtask sample program in C . . . . . . . . . . . . . . . . . . . . . . . . . . . 806The client sample program in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808

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

Sockets return codes (ERRNOs) . . . . . . . . . . . . . . . . . . . . . . . . . . . 811z/OS UNIX return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822Additional return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822

Sockets extended ERRNOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822User abend U4093 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826

Contents xi

Appendix C. Address family cross reference . . . . . . . . . . . . . . . . . . . 829

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

Appendix E. Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . 839

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

Appendix G. Related protocol specifications . . . . . . . . . . . . . . . . . . . 847

Appendix H. Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . 871

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875Terms and conditions for product documentation . . . . . . . . . . . . . . . . . . . . . . 877IBM Online Privacy Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877Policy for unsupported hardware. . . . . . . . . . . . . . . . . . . . . . . . . . . . 878Minimum supported hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878Programming interface information . . . . . . . . . . . . . . . . . . . . . . . . . . . 878Policy for unsupported hardware. . . . . . . . . . . . . . . . . . . . . . . . . . . . 878Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879

Bibliography. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885

Communicating your comments to IBM . . . . . . . . . . . . . . . . . . . . . 901

xii z/OS V2R3.0 Communications Server: IP Sockets Application Programming Interface Guide and Reference

Figures

1. The TCP/IP protocol stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32. Socket concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43. TCP/IP networking API relationship on z/OS . . . . . . . . . . . . . . . . . . . . . . 74. The port concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105. Port number assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106. Iterative server main logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167. A typical stream socket session . . . . . . . . . . . . . . . . . . . . . . . . . . . 188. A typical datagram socket session . . . . . . . . . . . . . . . . . . . . . . . . . . 199. Socket call variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

10. MVS TCP/IP socket descriptor table . . . . . . . . . . . . . . . . . . . . . . . . . 2911. An application using the bind() call . . . . . . . . . . . . . . . . . . . . . . . . . 3012. A bind() call using gethostbyname() . . . . . . . . . . . . . . . . . . . . . . . . . 3013. Variables used for the BIND call . . . . . . . . . . . . . . . . . . . . . . . . . . 3114. Variables used by the listen call . . . . . . . . . . . . . . . . . . . . . . . . . . . 3215. Variables used by the ACCEPT call . . . . . . . . . . . . . . . . . . . . . . . . . 3416. Socket states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3517. Closing sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3618. Serialized access to a shared storage area . . . . . . . . . . . . . . . . . . . . . . . 4119. Synchronized use of a common service task. . . . . . . . . . . . . . . . . . . . . . . 4220. Concurrent server in an MVS address space. . . . . . . . . . . . . . . . . . . . . . . 4521. To set/test bits for SELECT calls . . . . . . . . . . . . . . . . . . . . . . . . . . 4822. An application using the select() call . . . . . . . . . . . . . . . . . . . . . . . . . 4923. Accepting a client connection . . . . . . . . . . . . . . . . . . . . . . . . . . . 5024. Giving a socket to a subtask . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5325. Taking sockets from the main process . . . . . . . . . . . . . . . . . . . . . . . . . 5426. Finding the IP address of a server host using gethostbyname() . . . . . . . . . . . . . . . . 5627. Layout of a message between a TPI client and a TPI server . . . . . . . . . . . . . . . . . 6228. Transaction request message segment . . . . . . . . . . . . . . . . . . . . . . . . . 6229. The TCP buffer flush technique . . . . . . . . . . . . . . . . . . . . . . . . . . . 6330. Big or little endian byte order for a 2-byte integer. . . . . . . . . . . . . . . . . . . . . 6531. An application using the send() and recv() calls . . . . . . . . . . . . . . . . . . . . . 6732. An application using the sendto() and recvfrom() Calls . . . . . . . . . . . . . . . . . . . 7033. IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP . . . . . . . . . . . . . . . . . . . 7934. IP_ADD_SOURCE_MEMBERSHIP and IP_DROP_SOURCE_MEMBERSHIP . . . . . . . . . . . . 8035. IP_BLOCK_SOURCE and IP_UNBLOCK_SOURCE . . . . . . . . . . . . . . . . . . . . 8136. IP_MULTICAST_IF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8237. IP_MULTICAST_LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8338. IP_MULTICAST_TTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8439. IPV6_JOIN_GROUP and IPV6_LEAVE_GROUP . . . . . . . . . . . . . . . . . . . . . 8740. IPV6_MULTICAST_IF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8841. IPV6_MULTICAST_LOOP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8942. IPV6_MULTICAST_HOPS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9043. MCAST_JOIN_GROUP and MCAST_LEAVE_GROUP . . . . . . . . . . . . . . . . . . . 9244. MCAST_JOIN_SOURCE_GROUP and MCAST_LEAVE_SOURCE_GROUP . . . . . . . . . . . . 9445. MCAST_BLOCK_SOURCE and MCAST_UNBLOCK_SOURCE . . . . . . . . . . . . . . . . 9546. Sample JCL for compiling non-reentrant modules . . . . . . . . . . . . . . . . . . . . 10247. Sample JCL for linking non-reentrant modules . . . . . . . . . . . . . . . . . . . . . 10348. Sample JCL for running non-reentrant modules . . . . . . . . . . . . . . . . . . . . . 10349. Sample JCL for compiling reentrant modules . . . . . . . . . . . . . . . . . . . . . . 10550. Sample JCL for prelinking and linking reentrant modules . . . . . . . . . . . . . . . . . . 10651. Sample JCL for running the reentrant program . . . . . . . . . . . . . . . . . . . . . 10752. C socket TCP client sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19053. C socket TCP server sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . 19154. C socket UDP server sample . . . . . . . . . . . . . . . . . . . . . . . . . . . 19355. C socket UDP client sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Copyright IBM Corp. 2000, 2018 xiii

56. Using XTI with TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19657. Sample compile and link-edit job control procedure. . . . . . . . . . . . . . . . . . . . 20058. Sample client execution job control procedure. . . . . . . . . . . . . . . . . . . . . . 20159. Sample server execution job control procedure . . . . . . . . . . . . . . . . . . . . . 20260. Sample client code for XTI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21061. Sample server code for XTI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21762. ECB input parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22663. User token setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22664. HOSTENT structure returned by the GETHOSTBYADDR macro . . . . . . . . . . . . . . . 26065. HOSTENT structure returned by the GETHOSTBYNAME macro . . . . . . . . . . . . . . . 26266. NUM_IMAGES field settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 26867. EZASOKAS sample server program for IPv4 . . . . . . . . . . . . . . . . . . . . . . 39068. EZASOKAC sample client program for IPv4 . . . . . . . . . . . . . . . . . . . . . . 39669. EZASO6AS sample server program for IPv6 . . . . . . . . . . . . . . . . . . . . . . 40670. EZASO6AC sample client program for IPv6 . . . . . . . . . . . . . . . . . . . . . . 41371. Storage definition statement examples . . . . . . . . . . . . . . . . . . . . . . . . 41972. ACCEPT call instructions example . . . . . . . . . . . . . . . . . . . . . . . . . 42173. BIND call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . . 42374. BIND2ADDRSEL call instruction example . . . . . . . . . . . . . . . . . . . . . . . 42675. CLOSE call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . 42876. CONNECT call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . 43077. FCNTL call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . 43378. FREEADDRINFO call instruction example . . . . . . . . . . . . . . . . . . . . . . . 43479. GETADDRINFO call instruction example . . . . . . . . . . . . . . . . . . . . . . . 43680. GETCLIENTID call instruction example. . . . . . . . . . . . . . . . . . . . . . . . 44581. GETHOSTBYADDR call instruction example . . . . . . . . . . . . . . . . . . . . . . 44682. HOSTENT structure that is returned by the GETHOSTBYADDR call . . . . . . . . . . . . . . 44783. GETHOSTBYNAME call instruction example . . . . . . . . . . . . . . . . . . . . . . 44884. HOSTENT structure returned by the GETHOSTYBYNAME call . . . . . . . . . . . . . . . . 44985. GETHOSTID call instruction example . . . . . . . . . . . . . . . . . . . . . . . . 45186. GETHOSTNAME call instruction example . . . . . . . . . . . . . . . . . . . . . . . 45287. GETIBMOPT call instruction example . . . . . . . . . . . . . . . . . . . . . . . . 45388. Example of name field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45489. GETNAMEINFO call instruction example . . . . . . . . . . . . . . . . . . . . . . . 45690. GETPEERNAME call instruction example . . . . . . . . . . . . . . . . . . . . . . . 46091. GETSOCKNAME call instruction example . . . . . . . . . . . . . . . . . . . . . . . 46292. GETSOCKOPT call instruction example . . . . . . . . . . . . . . . . . . . . . . . . 46493. GIVESOCKET call instruction example . . . . . . . . . . . . . . . . . . . . . . . . 48094. INET6_IS_SRCADDR call instruction example . . . . . . . . . . . . . . . . . . . . . 48295. INITAPI call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . 48596. IOCTL call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . 48897. COBOL language example for SIOCGHOMEIF6 . . . . . . . . . . . . . . . . . . . . . 49098. COBOL language example for SIOCGIFNAMEINDEX . . . . . . . . . . . . . . . . . . . 49299. COBOL II example for SIOCGIFCONF . . . . . . . . . . . . . . . . . . . . . . . . 498

100. LISTEN call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . 499101. NTOP call instruction example. . . . . . . . . . . . . . . . . . . . . . . . . . . 501102. PTON call instruction example. . . . . . . . . . . . . . . . . . . . . . . . . . . 503103. READ call instruction example. . . . . . . . . . . . . . . . . . . . . . . . . . . 505104. READV call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . 507105. RECV call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . . 509106. RECVFROM call instruction example . . . . . . . . . . . . . . . . . . . . . . . . 511107. RECVMSG call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . 515108. SELECT call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . 519109. SELECTEX call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . 523110. SEND call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . . 528111. SENDMSG call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . 531112. SENDTO call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . 534113. SETSOCKOPT call instruction example . . . . . . . . . . . . . . . . . . . . . . . . 536114. SHUTDOWN call instruction example . . . . . . . . . . . . . . . . . . . . . . . . 553115. SOCKET call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . 554116. TAKESOCKET call instruction example . . . . . . . . . . . . . . . . . . . . . . . . 557

xiv z/OS V2R3.0 Communications Server: IP Sockets Application Programming Interface Guide and Reference

117. TERMAPI call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . 558118. WRITE call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . 559119. WRITEV call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . . 561120. EZACIC04 EBCDIC-to-ASCII table . . . . . . . . . . . . . . . . . . . . . . . . . 563121. EZACIC04 call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . 563122. EZACIC05 ASCII-to-EBCDIC table . . . . . . . . . . . . . . . . . . . . . . . . . 564123. EZACIC05 call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . 564124. EZACIC06 call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . 565125. EZAZIC08 call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . 568126. EZACIC09 call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . 572127. EZACIC14 EBCDIC-to-ASCII table . . . . . . . . . . . . . . . . . . . . . . . . . 573128. EZACIC14 call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . 573129. EZACIC15 ASCII-to-EBCDIC table . . . . . . . . . . . . . . . . . . . . . . . . . 574130. EZACIC15 call instruction example . . . . . . . . . . . . . . . . . . . . . . . . . 574131. EZASOKPS PL/1 sample server program for IPv4 . . . . . . . . . . . . . . . . . . . . 578132. EZASOKPC PL/1 sample client program for IPv4 . . . . . . . . . . . . . . . . . . . . 580133. EZASO6PS PL/1 sample server program for IPv6 . . . . . . . . . . . . . . . . . . . . 584134. EZASO6PC PL/1 sample client program for IPv6 . . . . . . . . . . . . . . . . . . . . 587135. CBLOCK PL/1 common variables . . . . . . . . . . . . . . . . . . . . . . . . . 597136. EZACOBOL COBOL common variables . . . . . . . . . . . . . . . . . . . . . . . . 603137. EZASO6CS COBOL call interface sample IPv6 server program . . . . . . . . . . . . . . . . 614138. EZASO6CC COBOL call interface sample IPv6 client program . . . . . . . . . . . . . . . . 622139. ACCEPT command example . . . . . . . . . . . . . . . . . . . . . . . . . . . 635140. CLOSE command example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640141. CONNECT command example. . . . . . . . . . . . . . . . . . . . . . . . . . . 643142. FCNTL command example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645143. GETCLIENTID command example . . . . . . . . . . . . . . . . . . . . . . . . . 656144. GETDOMAINNAME command example . . . . . . . . . . . . . . . . . . . . . . . 657145. GETHOSTBYADDR command example . . . . . . . . . . . . . . . . . . . . . . . . 658146. GETHOSTBYNAME command example . . . . . . . . . . . . . . . . . . . . . . . 660147. GETHOSTID command example . . . . . . . . . . . . . . . . . . . . . . . . . . 661148. GETHOSTNAME command example . . . . . . . . . . . . . . . . . . . . . . . . 662149. GETNAMEINFO command example . . . . . . . . . . . . . . . . . . . . . . . . . 664150. GETPEERNAME command example . . . . . . . . . . . . . . . . . . . . . . . . . 666151. GETPROTOBYNAME command example . . . . . . . . . . . . . . . . . . . . . . . 667152. GETPROTOBYNUMBER command example . . . . . . . . . . . . . . . . . . . . . . 668153. GETSERVBYNAME command example . . . . . . . . . . . . . . . . . . . . . . . . 669154. GETSERVBYPORT command example . . . . . . . . . . . . . . . . . . . . . . . . 670155. GETSOCKNAME command example . . . . . . . . . . . . . . . . . . . . . . . . 671156. ASCII to EBCDIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675157. EBCDIC to ASCII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676158. GETSOCKOPT command example . . . . . . . . . . . . . . . . . . . . . . . . . 681159. READ command example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702160. READ command example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707161. RESOLVE command example . . . . . . . . . . . . . . . . . . . . . . . . . . . 708162. SELECT command example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711163. ASCII to EBCDIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723164. EBCDIC to ASCII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724165. SOCKET command example . . . . . . . . . . . . . . . . . . . . . . . . . . . 732166. SOCKETSET command example . . . . . . . . . . . . . . . . . . . . . . . . . . 733167. SOCKETSETLIST command example . . . . . . . . . . . . . . . . . . . . . . . . 734168. SOCKETSETSTATUS command example . . . . . . . . . . . . . . . . . . . . . . . 736169. TERMINATE command example . . . . . . . . . . . . . . . . . . . . . . . . . . 739170. VERSION command example . . . . . . . . . . . . . . . . . . . . . . . . . . . 740171. Pascal declaration of connection state type . . . . . . . . . . . . . . . . . . . . . . . 749172. Pascal declaration of connection information record. . . . . . . . . . . . . . . . . . . . 751173. Pascal declaration of socket type . . . . . . . . . . . . . . . . . . . . . . . . . . 752174. Notification record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753175. Pascal declaration of file specification record . . . . . . . . . . . . . . . . . . . . . . 757176. Sample calling sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761177. BeginTcpIp example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762

Figures xv

178. ClearTimer example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762179. Create timer example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763180. Destroy timer example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763181. EndTcpIp example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763182. GetHostNumber example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764183. GetHostResol example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764184. GetHostString example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765185. GetIdentity example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765186. GetNextNote example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766187. GetSmsg example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767188. Handle example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767189. IsLocalAddress example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768190. IsLocalHost example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768191. MonQuery example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769192. Monitor query record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769193. PingRequest example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770194. RawIpClose example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771195. RawIpOpen example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771196. RawIpReceive example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772197. RawIpSend example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773198. ReadXlateTable example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774199. SayCalRe example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775200. SayConSt example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775201. SayIntAd example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776202. SayIntNum example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776203. SayNotEn example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776204. SayPorTy example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777205. SayProTy example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777206. SetTimer example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778207. TcpAbort example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778208. TcpClose example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779209. TcpFReceive example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780210. TcpReceive example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780211. TcpWaitReceive example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780212. TcpFSend example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782213. TcpSend example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782214. TcpWaitSend example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783215. TcpNameChange example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784216. TcpOpen example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785217. TcpWaitOpen example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785218. TcpOption example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787219. TcpStatus example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788220. UdpClose example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789221. UdpNReceive example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789222. UdpOpen example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790223. UdpReceive example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791224. UdpSend example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792225. Unhandle example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793226. Sample Pascal API with receive option . . . . . . . . . . . . . . . . . . . . . . . . 794227. Sample Pascal API with send option . . . . . . . . . . . . . . . . . . . . . . . . . 794228. Sample Pascal application program . . . . . . . . . . . . . . . . . . . . . . . . . 798229. MTCSRVR C socket server program sample . . . . . . . . . . . . . . . . . . . . . . 806230. MTCCSUB C socket server program sample . . . . . . . . . . . . . . . . . . . . . . 808231. MTCCLNT C socket server program sample . . . . . . . . . . . . . . . . . . . . . . 810232. Example of abend U4093. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827

xvi z/OS V2R3.0 Communications Server: IP Sockets Application Programming Interface Guide and Reference

Tables

1. Socket programming interface actions . . . . . . . . . . . . . . . . . . . . . . . . . 202. TCP/IP data sets and applications . . . . . . . . . . . . . . . . . . . . . . . . . . 223. Effect of shutdown socket call . . . . . . . . . . . . . . . . . . . . . . . . . . . 374. First fullword passed in a bit string select() . . . . . . . . . . . . . . . . . . . . . . . 465. Second fullword passed in a bit string using select() . . . . . . . . . . . . . . . . . . . . 476. C structures in assembler language format . . . . . . . . . . . . . . . . . . . . . . . 1097. Initializing a call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1978. Establishing a connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1979. Transferring data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

10. Releasing a connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19711. Disabling a connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19712. Managing events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19813. Using utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19814. System function calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19815. OPTNAME options for GETSOCKOPT and SETSOCKOPT . . . . . . . . . . . . . . . . . 28116. IOCTL macro arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31217. OPTNAME options for GETSOCKOPT and SETSOCKOPT . . . . . . . . . . . . . . . . . 35618. OPTNAME options for GETSOCKOPT and SETSOCKOPT . . . . . . . . . . . . . . . . . 46519. IOCTL call arguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49620. OPTNAME options for GETSOCKOPT and SETSOCKOPT . . . . . . . . . . . . . . . . . 53721. REXX socket sample programs . . . . . . . . . . . . . . . . . . . . . . . . . . . 74222. TCP connection states. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75023. Pascal language return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 75924. Sockets ERRNOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81225. Sockets extended ERRNOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82226. C socket address families cross reference . . . . . . . . . . . . . . . . . . . . . . . 82927. MACRO, CALL, REXX, socket address families cross reference . . . . . . . . . . . . . . . . 83128. MACRO, CALL, REXX, exceptions . . . . . . . . . . . . . . . . . . . . . . . . . 83329. GETSOCKOPT/SETSOCKOPT command values for Macro, Assembler, COBOL and PL/I . . . . . . . 83530. GETSOCKOPT/SETSOCKOPT optname value for C programs . . . . . . . . . . . . . . . . 836

Copyright IBM Corp. 2000, 2018 xvii

xviii z/OS V2R3.0 Communications Server: IP Sockets Application Programming Interface Guide and Reference

About this document

This document describes the syntax of the TCP/IP application programminginterface (API). The APIs described in this document can be used to create TCP/IPclient and server applications or modify existing applications to communicateusing TCP/IP. The information in this document supports both IPv6 and IPv4.Unless explicitly noted, information describes IPv4 networking protocol. IPv6support is qualified within the text.

This document refers to Communications Server data sets by their default SMP/Edistribution library name. Your installation might, however, have different namesfor these data sets where allowed by SMP/E, your installation personnel, oradministration staff. For instance, this document refers to samples in SEZAINSTlibrary as simply in SEZAINST. Your installation might choose a data set name ofSYS1.SEZAINST, CS390.SEZAINST or other high-level qualifiers for the data setname.

To provide flexibility in writing new applications and adapting existingapplications, the following programming languages and interfaces are described:v C socketsv X/Open Transport Interface (XTI)v Assembler, PL/I, and COBOL socketsv REXX socketsv Pascal language

Who should read this documentThis document is intended for experienced programmers familiar with MVS, theIBM multiple virtual storage operating system, TCP/IP protocols, UNIX sockets,and data networks.

To use this document, you should be familiar with MVS and the IBM timesharingoption (TSO).

You should also be familiar with z/OS Communications Server and installing andcustomizing any required programming products for your network.

Depending on the design and function of your application, you should be familiarwith one or more of the following programming languages:v Assemblerv Cv COBOLv Pascalv PL/Iv REXX

How this document is organizedThis document is organized into the following parts:

Copyright IBM Corp. 2000, 2018 xix

v Part 1, Overview, on page 1 presents an overview of TCP/IP concepts andorganizing a TCP/IP application program.

v Part 2, Designing programs, on page 25 describes ways to design varioustypes of programs.

v Part 3, Application program interfaces, on page 97 describes the followingsocket application program interfaces (APIs): C Socket application programming interface (API) X/Open Transport Interface (XTI) Macro application programming interface (API) CALL instruction application programming interface (API) REXX socket application programming interface (API) Pascal application programming interface (API)

v Appendixes provide additional information for this document.v Notices on page 875 contains notices and trademarks used in this document.v Bibliography on page 881 contains descriptions of the documents in the z/OS

Communications Server library.

How to use this documentTo use this document, you should be familiar with z/OS TCP/IP Services and theTCP/IP suite of protocols.

How to contact IBM serviceFor immediate assistance, visit this website: http://www.software.ibm.com/support

Most problems can be resolved at this website, where you can submit questionsand problem reports electronically, and access a variety of diagnosis information.

For telephone assistance in problem diagnosis and resolution (in the United Statesor Puerto Rico), call the IBM Software Support Center anytime (1-800-IBM-SERV).You will receive a return call within 8 business hours (Monday Friday, 8:00 a.m. 5:00 p.m., local customer time).

Outside the United States or Puerto Rico, contact your local IBM representative oryour authorized IBM supplier.

If you would like to provide feedback on this publication, see Communicatingyour comments to IBM on page 901.

Conventions and terminology that are used in this informationCommands in this information that can be used in both TSO and z/OS UNIXenvironments use the following conventions:v When describing how to use the command in a TSO environment, the command

is presented in uppercase (for example, NETSTAT).v When describing how to use the command in a z/OS UNIX environment, the

command is presented in bold lowercase (for example, netstat).v When referring to the command in a general way in text, the command is

presented with an initial capital letter (for example, Netstat).

xx z/OS V2R3.0 Communications Server: IP Sockets Application Programming Interface Guide and Reference

http://www.software.ibm.com/supporthttp://www.software.ibm.com/support

All the exit routines described in this information are installation-wide exit routines.The installation-wide exit routines also called installation-wide exits, exit routines,and exits throughout this information.

The TPF logon manager, although included with VTAM, is an applicationprogram; therefore, the logon manager is documented separately from VTAM.

Samples used in this information might not be updated for each release. Evaluate asample carefully before applying it to your system.

Note: In this information, you might see the following Shared MemoryCommunications over Remote Direct Memory Access (SMC-R) terminology:v "RoCE Express", which is a generic term representing both IBM 10 GbE RoCE

Express and IBM 10 GbE RoCE Express2 capability. When this term is used inthis information, the processing being described applies to both features. Ifprocessing is applicable to only one feature, the full terminology, for instance,IBM 10 GbE RoCE Express will be used.

v RDMA network interface card (RNIC), which is used to refer to the IBM 10 GbERoCE Express or 10 GbE RoCE Express2Express feature.

v Shared RoCE environment, which means that the "RoCE Express" feature can beused concurrently, or shared, by multiple operating system instances. The featureis considered to operate in a shared RoCE environment even if you use it with asingle operating system instance.

For definitions of the terms and abbreviations that are used in this information,you can view the latest IBM terminology at the IBM Terminology website.

Clarification of notes

Information traditionally qualified as Notes is further qualified as follows:

Note Supplemental detail

Tip Offers shortcuts or alternative ways of performing an action; a hint

GuidelineCustomary way to perform a procedure

Rule Something you must do; limitations on your actions

RestrictionIndicates certain conditions are not supported; limitations on a product orfacility

RequirementDependencies, prerequisites

Result Indicates the outcome

How to read a syntax diagramThis syntax information applies to all commands and statements that do not havetheir own syntax described elsewhere.

The syntax diagram shows you how to specify a command so that the operatingsystem can correctly interpret what you type. Read the syntax diagram from left toright and from top to bottom, following the horizontal line (the main path).

About this document xxi

|||||

|

||||

http://www.ibm.com/software/globalization/terminology/index.jsp

Symbols and punctuation

The following symbols are used in syntax diagrams:

SymbolDescription

Marks the beginning of the command syntax.

Indicates that the command syntax is continued.

| Marks the beginning and end of a fragment or part of the commandsyntax.

Marks the end of the command syntax.

You must include all punctuation such as colons, semicolons, commas, quotationmarks, and minus signs that are shown in the syntax diagram.

Commands

Commands that can be used in both TSO and z/OS UNIX environments use thefollowing conventions in syntax diagrams:v When describing how to use the command in a TSO environment, the command

is presented in uppercase (for example, NETSTAT).v When describing how to use the command in a z/OS UNIX environment, the

command is presented in bold lowercase (for example, netstat).

Parameters

The following types of parameters are used in syntax diagrams.

RequiredRequired parameters are displayed on the main path.

OptionalOptional parameters are displayed below the main path.

DefaultDefault parameters are displayed above the main path.

Parameters are classified as keywords or variables. For the TSO and MVS consolecommands, the keywords are not case sensitive. You can code them in uppercaseor lowercase. If the keyword appears in the syntax diagram in both uppercase andlowercase, the uppercase portion is the abbreviation for the keyword (for example,OPERand).

For the z/OS UNIX commands, the keywords must be entered in the caseindicated in the syntax diagram.

Variables are italicized, appear in lowercase letters, and represent names or valuesyou supply. For example, a data set is a variable.

Syntax examples

In the following example, the PUt subcommand is a keyword. The requiredvariable parameter is local_file, and the optional variable parameter is foreign_file.Replace the variable parameters with your own values.

xxii z/OS V2R3.0 Communications Server: IP Sockets Application Programming Interface Guide and Reference

PUt local_fileforeign_file

Longer than one line

If a diagram is longer than one line, the first line ends with a single arrowheadand the second line begins with a single arrowhead.

The first line of a syntax diagram that is longer than one line

The continuation of the subcommands, parameters, or both

Required operands

Required operands and values appear on the main path line. You must coderequired operands and values.

REQUIRED_OPERAND

Optional values

Optional operands and values appear below the main path line. You do not haveto code optional operands and values.

OPERAND

Selecting more than one operand

An arrow returning to the left above a group of operands or values means morethan one can be selected, or a single one can be repeated.

,

REPEATABLE_OPERAND_OR_VALUE_1REPEATABLE_OPERAND_OR_VALUE_2REPEATABLE_OPER_OR_VALUE_1REPEATABLE_OPER_OR_VALUE_2

Nonalphanumeric characters

If a diagram shows a character that is not alphanumeric (such as parentheses,periods, commas, and equal signs), you must code the character as part of thesyntax. In this example, you must code OPERAND=(001,0.001).

OPERAND = ( 001 , 0.001 )

About this document xxiii

Blank spaces in syntax diagrams

If a diagram shows a blank space, you must code the blank space as part of thesyntax. In this example, you must code OPERAND=(001 FIXED).

OPERAND = ( 001 FIXED )

Default operands

Default operands and values appear above the main path line. TCP/IP uses thedefault if you omit the operand entirely.

DEFAULT

OPERAND

Variables

A word in all lowercase italics is a variable. Where you see a variable in the syntax,you must replace it with one of its allowable names or values, as defined in thetext.

variable

Syntax fragments

Some diagrams contain syntax fragments, which serve to break up diagrams thatare too long, too complex, or too repetitious. Syntax fragment names are in mixedcase and are shown in the diagram and in the heading of the fragment. Thefragment is placed below the main diagram.

Syntax fragment

Syntax fragment:

1ST_OPERAND , 2ND_OPERAND , 3RD_OPERAND

Prerequisite and related informationz/OS Communications Server function is described in the z/OS CommunicationsServer library. Descriptions of those documents are listed in Bibliography onpage 881, in the back of this document.

Required information

Before using this product, you should be familiar with TCP/IP, VTAM, MVS, andUNIX System Services.

xxiv z/OS V2R3.0 Communications Server: IP Sockets Application Programming Interface Guide and Reference

Softcopy information

Softcopy publications are available in the following collection.

Titles Description

IBM Z Redbooks The IBM Z subject areas range from e-business application development andenablement to hardware, networking, Linux, solutions, security, parallelsysplex, and many others. For more information about the Redbooks

publications, see http://www.redbooks.ibm.com/ and http://www.ibm.com/systems/z/os/zos/zfavorites/.

Other documents

This information explains how z/OS references information in other documents.

When possible, this information uses cross-document links that go directly to thetopic in reference using shortened versions of the document title. For completetitles and order numbers of the documents for all products that are part of z/OS,see z/OS Information Roadmap (SA23-2299). The Roadmap describes what level ofdocuments are supplied with each release of z/OS Communications Server, andalso describes each z/OS publication.

To find the complete z/OS library, visit the z/OS library in IBM Knowledge Center(www.ibm.com/support/knowledgecenter/SSLTBW/welcome).

Relevant RFCs are listed in an appendix of the IP documents. Architecturalspecifications for the SNA protocol are listed in an appendix of the SNAdocuments.

The following table lists documents that might be helpful to readers.

Title Number

DNS and BIND, Fifth Edition, O'Reilly Media, 2006 ISBN 13: 978-0596100575

Routing in the Internet, Second Edition, Christian Huitema (Prentice Hall 1999) ISBN 13: 978-0130226471

sendmail, Fourth Edition, Bryan Costales, Claus Assmann, George Jansen, andGregory Shapiro, O'Reilly Media, 2007

ISBN 13: 978-0596510299

SNA Formats GA27-3136

TCP/IP Illustrated, Volume 1: The Protocols, W. Richard Stevens, Addison-WesleyProfessional, 1994

ISBN 13: 978-0201633467

TCP/IP Illustrated, Volume 2: The Implementation, Gary R. Wright and W. RichardStevens, Addison-Wesley Professional, 1995

ISBN 13: 978-0201633542

TCP/IP Illustrated, Volume 3: TCP for Transactions, HTTP, NNTP, and the UNIX DomainProtocols, W. Richard Stevens, Addison-Wesley Professional, 1996

ISBN 13: 978-0201634952

TCP/IP Tutorial and Technical Overview GG24-3376

Understanding LDAP SG24-4986

z/OS Cryptographic Services System SSL Programming SC14-7495

z/OS IBM Tivoli Directory Server Administration and Use for z/OS SC23-6788

z/OS JES2 Initialization and Tuning Guide SA32-0991

z/OS Problem Management SC23-6844

z/OS MVS Diagnosis: Reference GA32-0904

About this document xxv

http://www.redbooks.ibm.comhttp://www.ibm.com/systems/z/os/zos/zfavorites/http://www.ibm.com/systems/z/os/zos/zfavorites/http://www.ibm.com/support/knowledgecenter/SSLTBW/welcomehttp://www.ibm.com/support/knowledgecenter/

Title Number

z/OS MVS Diagnosis: Tools and Service Aids GA32-0905

z/OS MVS Using the Subsystem Interface SA38-0679

z/OS Program Directory GI11-9848

z/OS UNIX System Services Command Reference SA23-2280

z/OS UNIX System Services Planning GA32-0884

z/OS UNIX System Services Programming: Assembler Callable Services Reference SA23-2281

z/OS UNIX System Services User's Guide SA23-2279

z/OS XL C/C++ Runtime Library Reference SC14-7314

z Systems: Open Systems Adapter-Express Customer's Guide and Reference SA22-7935

Redbooks publications

The following Redbooks publications might help you as you implement z/OSCommunications Server.

Title Number

IBM z/OS Communications Server TCP/IP Implementation, Volume 1: Base Functions,Connectivity, and Routing

SG24-8096

IBM z/OS Communications Server TCP/IP Implementation, Volume 2: StandardApplications

SG24-8097

IBM z/OS Communications Server TCP/IP Implementation, Volume 3: High Availability,Scalability, and Performance

SG24-8098

IBM z/OS Communications Server TCP/IP Implementation, Volume 4: Security andPolicy-Based Networking

SG24-8099

IBM Communication Controller Migration Guide SG24-6298

IP Network Design Guide SG24-2580

Managing OS/390 TCP/IP with SNMP SG24-5866

Migrating Subarea Networks to an IP Infrastructure Using Enterprise Extender SG24-5957

SecureWay Communications Server for OS/390 V2R8 TCP/IP: Guide to Enhancements SG24-5631

SNA and TCP/IP Integration SG24-5291

TCP/IP in a Sysplex SG24-5235

TCP/IP Tutorial and Technical Overview GG24-3376

Threadsafe Considerations for CICS SG24-6351

Where to find related information on the Internet

z/OS

This site provides information about z/OS Communications Server releaseavailability, migration information, downloads, and links to informationabout z/OS technology

http://www.ibm.com/systems/z/os/zos/

z/OS Internet Library

Use this site to view and download z/OS Communications Serverdocumentation

xxvi z/OS V2R3.0 Communications Server: IP Sockets Application Programming Interface Guide and Reference

http://www.ibm.com/systems/z/os/zos/

http://www.ibm.com/systems/z/os/zos/library/bkserv/

IBM Communications Server product

The primary home page for information about z/OS CommunicationsServer

http://www.software.ibm.com/network/commserver/

z/OS Communications Server product

The page contains z/OS Communications Server product introduction

http://www.ibm.com/software/products/en/commserver-zos

IBM Communications Server product support

Use this site to submit and track problems and search the z/OSCommunications Server knowledge base for Technotes, FAQs, whitepapers, and other z/OS Communications Server information

http://www.software.ibm.com/support

IBM Communications Server performance information

This site contains links to the most recent Communications Serverperformance reports

http://www.ibm.com/support/docview.wss?uid=swg27005524

IBM Systems Center publications

Use this site to view and order Redbooks publications, Redpapers, andTechnotes

http://www.redbooks.ibm.com/

IBM Systems Center flashes

Search the Technical Sales Library for Techdocs (including Flashes,presentations, Technotes, FAQs, white papers, Customer Support Plans,and Skills Transfer information)

http://www.ibm.com/support/techdocs/atsmastr.nsf

Tivoli NetView for z/OS

Use this site to view and download product documentation about TivoliNetView for z/OS

http://www.ibm.com/support/knowledgecenter/SSZJDU/welcome

RFCs

Search for and view Request for Comments documents in this section ofthe Internet Engineering Task Force website, with links to the RFCrepository and the IETF Working Groups web page

http://www.ietf.org/rfc.html

Internet drafts

View Internet-Drafts, which are working documents of the InternetEngineering Task Force (IETF) and other groups, in this section of theInternet Engineering Task Force website

http://www.ietf.org/ID.html

Information about web addresses can also be found in information APAR II11334.

About this document xxvii

http://www.ibm.com/systems/z/os/zos/library/bkserv/http://www.software.ibm.com/network/commserver/http://www.ibm.com/software/products/en/commserver-zoshttp://www.software.ibm.com/supporthttp://www.ibm.com/support/docview.wss?uid=swg27005524http://www.redbooks.ibm.comhttp://www.ibm.com/support/techdocshttp://www.ibm.com/support/knowledgecenter/SSZJDU/welcomehttp://www.rfc-editor.org/rfc.htmlhttp://www.ietf.org/ID.html

Note: Any pointers in this publication to websites are provided for convenienceonly and do not serve as an en

Date post:	13-Nov-2018
Category:	Documents
Upload:	phunglien
View:	243 times
Download:	1 times

z/OS V2R3.0 Communications Server: IP Sockets Application ... · C Socket application programming...

Documents