MCP Sockets Service Programming Guide
Total Page:16
File Type:pdf, Size:1020Kb
ClearPath Enterprise Servers MCP Sockets Service Programming Guide ClearPath MCP Release 8.0 Printed in USA February 2003 4310 3530–006 ClearPath Enterprise Servers MCP Sockets Service Programming Guide UNISYS © 2003 Unisys Corporation. All rights reserved. ClearPath MCP Release 8.0 Printed in USA February 2003 4310 3530–006 NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the products described in this document are set forth in such agreement. Unisys cannot accept any financial or other responsibility that may be the result of your use of the information in this document or software material, including direct, special, or consequential damages. You should be very careful to ensure that the use of this information and/or software material complies with the laws, rules, and regulations of the jurisdictions with respect to which it is used. The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions. Notice to Government End Users: This is commercial computer software or hardware documentation developed at private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data rights clauses. Correspondence regarding this publication can be e-mailed to [email protected]. Unisys and ClearPath are registered trademarks of Unisys Corporation in the United States and other countries. All other brands and products referenced in this document are acknowledged to be the trademarks or registered trademarks of their respective holders. ClearPath Enterprise ClearPath Enterprise Servers Servers MCP Sockets Service MCP Sockets Service Programming Guide Programming Guide ClearPath MCP Release ClearPath MCP 8.0 Release 8.0 4310 3530–006 4310 3530–006 Bend here, peel upwards and apply to spine. Contents Section 1. Introduction What’s New .......................................................................................... 1–1 What Is a Socket? ................................................................................. 1–1 Port File Differences.............................................................................. 1–3 Socket Communication States.............................................................. 1–5 Sockets Overview ................................................................................. 1–7 Section 2. Sockets Library Interface C Compiler Sockets.h File ..................................................................... 2–1 SocketSupport Library........................................................................... 2–2 Purpose of this Library......................................................... 2–2 Functions.............................................................................. 2–2 Accessing the Library........................................................... 2–5 Common Data Structures .................................................... 2–5 Array Parameters ................................................................. 2–5 Using Secure Sockets Layer (SSL) ...................................... 2–7 Socket Call Errors................................................................. 2–7 Section 3. The MCP Sockets API Purpose of the Sockets Service ............................................................ 3–1 Standards and Conformance................................................................. 3–1 Out of Band (Urgent) Data ................................................... 3–1 SockLib_Bind ....................................................................... 3–1 SockLib_IOCtl ...................................................................... 3–2 SockLib_Select..................................................................... 3–2 SockLib_Send/SockLib_SendTo........................................... 3–2 SockLib_SetSockOpt/SockLib_GetSockOpt ........................ 3–2 SockLib_Socket.................................................................... 3–3 Section 4. Declarations to the Sockets API Programming Declarations.................................................................... 4–1 SockLib_Accept ................................................................... 4–1 SockLib_Bind ....................................................................... 4–3 SockLib_Close...................................................................... 4–5 SockLib_Connect ................................................................. 4–7 SockLib_GetHostByAddr ..................................................... 4–9 SockLib_GetHostByName ................................................. 4–12 4310 3530–006 iii Contents SockLib_GetHostName ..................................................... 4–14 SockLib_GetPeerName ..................................................... 4–16 SockLib_GetSockName ..................................................... 4–17 SockLib_GetSockOpt......................................................... 4–18 SockLib_IOCtl .................................................................... 4–20 SockLib_Listen................................................................... 4–22 SockLib_Recv .................................................................... 4–24 SockLib_RecvFrom............................................................ 4–28 SockLib_Resume............................................................... 4–30 SockLib_Select .................................................................. 4–31 SockLib_Send .................................................................... 4–35 SockLib_SendTo ................................................................ 4–38 SockLib_SetSockOpt ......................................................... 4–39 SockLib_Shutdown............................................................ 4–47 SockLib_Socket ................................................................. 4–49 SockLib_Suspend .............................................................. 4–50 iv 4310 3530–006 Figures 1–1. Socket Communication Overview...................................................................... 1–5 2–1. Overview of the Sockets Library Interface......................................................... 2–1 4310 3530–006 v Figures vi 4310 3530–006 Tables 2–1. Error Codes......................................................................................................... 2–7 2–2. System Error Codes ......................................................................................... 2–10 4310 3530–006 vii Tables viii 4310 3530–006 Section 1 Introduction The MCP Sockets Service Programming Guide is a reference for programmers who use the MCP Sockets Service API. This guide is a reference for programs written in ALGOL, COBOL, NEWP, and C, and is intended for MCP environment programmers. What’s New The following information is new to the MCP 8.0 release of the MCP Sockets Service API: • In Section 4 a new function, “SockLib_Select (),”is provided that allows you to wait for input, open notification, or change in output window on a group of sockets. • The MCP 8.0 release supports the Transport Level Security (TLS) Internet standard [RFC 2246]. What Is a Socket? A socket is a TCP/IP network access point, through which data can be read and written. Sockets using the TCP protocol offer a virtual two-way pipe across the network to a specific remote server, while sockets using the UDP (User Datagram Protocol) allow the user to send and receive messages with other hosts in the network. Before sending data, the socket must be “bound” to a local IP address and port number, and, in the case of TCP sockets, must be connected to the remote socket. Data reading and writing to the socket can either be synchronous, in which the operation does not return until the data has been sent or received (also known as blocking), or asynchronous, in which the user has more control over when the operation is returned (also known as non-blocking). MCP sockets are always blocking (non-blocking sockets are not currently supported); but a timeout can be specified in order to restrict the duration of the blocking. Client software using TCP sockets usually follows the standard client algorithm: 1. Establish a socket. 2. Connect to the required server. 3. Communicate with the server through a well-defined protocol. 4. Close the socket. 4310 3530–006 1–1 Introduction Using socket API calls, this algorithm can be described with the following program flow: socket() bind() connect() recv() send() close() 004 The UDP client algorithm is very similar to the TCP client algorithm. Server software over TCP sockets operates similarly, but must already be executing and waiting for client requests on a well-known port number. Server software usually follows the following algorithm: 1. Establish a socket. 2. Bind to a well-known TCP port number for this service. 3. Tell the socket to look for incoming requests. 4. Receive client requests for service and process them (permanently). 1–2 4310 3530–006 Introduction Using the socket API, this algorithm can be shown as: socket() bind() listen() accept() send() recv() close() 001 The preceding program flow is