The PowerSocket Library

Network Programming using PowerBuilder
and Winsock Version 1.1

PowerSocket Version 2.1 - January 8, 1999

Authors, Copyright, and Purchasing information
Getting Started
Winsock User Object Functions
- htonl() Convert an unsigned long value from host byte order to network byte order.
- htons() Convert an integer value from host byte order to network byte order.
- inet_addr() Convert a string containing an IP address in the Internet standard ``.'' notation to an unsigned long value in network byte order.
- inet_ntoa() Convert an unsigned long value in network byte order to the string equivalent IP address in Internet standard ``.'' notation.
- ntohl() Convert an unsigned long value from network byte order to host byte order.
- ntohs() Convert an integer value from network byte order to host byte order.
- wsselect() Perform synchronous I/O multiplexing.
- gethostbyaddr() Retrieve the name(s) and address corresponding to an IP address provided as an unsigned long value in network byte order.
- gethostbyname() Retrieve the name(s) and address corresponding to a host name.
- gethostname() Retrieve the name of the local host.
- getprotobyname() Retrieve the protocol name and number corresponding to a protocol name.
- getprotobynumber() Retrieve the protocol name and number corresponding to a protocol number.
- getservbyname() Retrieve the service name and port corresponding to a service name.
- getservbyport() Retrieve the service name and port corresponding to a port.
- WSACancelAsyncRequest() Cancel an outstanding instance of a WSAAsyncGetXByY() function.
- WSACancelBlockingCall() Cancel an outstanding "blocking" API call
- WSAGetLastError() Obtain details of last Windows Sockets API error
- WSAIsBlocking() Determine if the underlying Windows Sockets DLL is already blocking an existing call for this thread
- WSASetLastError() Set the error to be returned by a subsequent WSAGetLastError()
- WSAAsyncGetHostByAddr() Get host information corresponding to an address - asynchronous version
- WSAAsyncGetHostByName() Get host information corresponding to a hostname - asynchronous version.
- WSAAsyncGetProtoByName() Get protocol information corresponding to a protocol name - asynchronous version.
- WSAAsyncGetProtoByNumber() Get protocol information corresponding to a protocol number - asynchronous version.
- WSAAsyncGetServByName() Get service information corresponding to a service name and protocol -- asynchronous version.
- WSAAsyncGetServByPort() Get service information corresponding to a port and protocol - asynchronous version.
- return_hostent() Read a string buffer containing a hostent structure and return a pbhostent structure.
- return_servent() Read a string buffer containing a servent structure and return a pbservent structure.
- return_protoent() Read a string buffer containing a protoent structure and return a pbprotoent structure.
- WSAGetSelectError() Return the upper 16 bits (the error code portion) of the LongParm value passed as a parameter.
- WSAGetSelectEvent() Return the lower 16 bits (the network event code portion) of the LongParm value passed as a parameter.
- WSAGetAsyncBufLen() Return the lower 16 bits (the required buffer length portion) of the LongParm value passed as a parameter.
- WSAGetAsyncError() Return the upper 16 bits (the error code portion) of the LongParm value passed as a parameter.
- WSOr() Perform a binary OR operation on two integers and return the result.
- WSAUnhookBlockingHook() Restore the original blocking hook function.
Socket User Object
- accept() An incoming connection is acknowledged and associated with an immediately created socket. The original socket is returned to the listening state.
- bind() Assign a local name to an unnamed socket.
- closesocket() Remove a socket descriptor from the per-process object reference table. Only blocks if SO_LINGER is set.
- wsconnect() Initiate a connection on the specified socket.
- getpeername() Retrieve the name of the peer connected to the specified socket descriptor.
- getsockname() Retrieve the current name for the specified socket
- getsockopt() Retrieve options associated with the specified socket descriptor.
- ioctlsocket() Provide control for descriptors.
- listen() Listen for incoming connections on a specified socket.
- recv() Receive data from a connected socket.
- recvfrom() Receive data from either a connected or unconnected socket.
- send() Send data to a connected socket.
- sendto() Send data to either a connected or unconnected socket.
- setsockopt() Store options associated with the specified socket descriptor.
- shutdown() Shut down part of a full-duplex connection.
- socket() Create an endpoint for communication and return a socket descriptor.
- WSAAsyncSelect() Perform asynchronous version of wsselect()
- GetSocketNumber()
SocketStream User Object
SocketDGram User Object

Authors, Copyright, and Purchasing

Ted Coombs

Home Page

Visit PowerBuilder Interactive on the Web

This is a shareware product. The price is (U.S.) $50.00 for a single license. Each programmer who uses the PowerSocket Library needs their own license. A single license gives a single programmer:

Full product support

Unlimited electronic delivery of bug-fixes

A comprehensive programmer's guide

Sample code, including several full sample applications

The right to distribute the PowerSocket Library version 2.1 without this file and without the accompanying PowerSocket Library documentation

If you do not have a license for the PowerSocket Library version 2.1, then you have the following rights:

You may distribute the PowerSocket Library version 2.1 only if you include this file, and all accompanying documentation, un-altered.

You may use the PowerSocket Library version 2.1 in your programs provided that your programs are:

For the purpose of your own education,

For the purpose of evaluating the PowerSocket Library, or,

For your own personal (non-commercial) use.

You have the right to purchase as many licenses as you or your organization require.

You can now license and download the PowerSocket Library source code!

Go to DigitalMarketplace.com at:
http://www.digitalmarketplace.com/members/product.asp?dept=71&pfid=170

The PowerSocket Library source code license gives you the right to create derivative works based upon the PowerSocket Library source code as well as compile and distribute your compiled code to an unlimited number of users or developers for them to use in binary form. It also protects your investment in your application by giving you a permanent license to the source code of this third-party development library.

Copyright (c) 1995, 1996, 1997, 1998, 1999 by Jason Coombs and Ted Coombs

All rights reserved.

Getting Started

Do the following to begin writing Winsock 1.1 applications using the PowerSocket Library:

Add the Winsock.PBL to your application's library search path.

Read about the winsock user object.

Read about the socket user object.

Read about the socketstream user object.

Read about the socketdgram user object.

Contact PowerBuilder Interactive for the most up-to-date documentation and some useful tips on getting started.

Purchase your copy of the PowerSocket Library.

Start programming!

Winsock User Object

Every application created with the PowerSocket Library must have one global winsock user object. The winsock user object is a non-visual user object that serves three purposes in your application:

The constructor event of the winsock user object calls the Winsock function WSAStartup() to register the application with your Winsock DLL.

The destructor event of the winsock user object calls the Winsock function WSACleanup() to de-register the application with the Winsock DLL.

The winsock user object contains all of the Winsock functions that do not require a socket, such as GetHostByName(), and it provides your application with important constants used by every Winsock function.

Declare a global winsock user object variable in your application by adding the following line in the Declare Global Variables window:

winsock ws

Now your application has a global winsock user object variable. Add the following to the Open event of your application object to create a new winsock user object and store it in the ws variable:

ws = create winsock

In the application object's close event, enter the following to destroy the winsock user object when the application closes:

destroy ws

Your application is now Winsock enabled.

The winsock user object contains an important instance variable, wsInfo. wsInfo is the WSAData structure that is filled with information specific to your Winsock DLL by the WSAStartup() Winsock function. The format for the WSAData structure is:

	wVersion			unsignedInteger
	wHighVersion		unsignedIinteger
	szDescription[257]	character
	szSystemStatus[129]	character
	iMaxSockets		unsignedinteger
	iMaxUdpDg			unsignedinteger
	lpVendorInfo		string

The members of this structure are:

wVersion: The version of the Windows Sockets specification.
wHighVersion: The highest version of the Windows Sockets specification that this DLL can support. Normally this will be the same as wVersion.
szDescription: A character string where a description of the Windows Sockets implementation, including vendor identification is copied.
szSystemStatus: A character string where relevant status or configuration information is copied.
iMaxSockets: The maximum number of sockets which a single process can potentially open. Application developers may use this number as a crude indication of whether the Windows Sockets implementation is usable by the application. For example, an X Windows server might check iMaxSockets when first started: if it is less than 8, the application would display an error message instructing the user to reconfigure the networking software. (This is a situation in which the szSystemStatus text might be used.) There is no guarantee that a particular application can actually allocate iMaxSockets sockets, since there may be other Windows Sockets applications in use.
iMaxUdpDg: The size in bytes of the largest UDP datagram that can be sent or received by a Windows Sockets application. If the Winsock DLL imposes no limit, iMaxUdpDg is zero. The minimum value of iMaxUdpDg for a Windows Sockets implementation is 512. Note that regardless of the value of iMaxUdpDg, it is inadvisable to attempt to send a broadcast datagram which is larger than the Maximum Transmission Unit (MTU) for the network. (The Windows Sockets API does not provide a mechanism to discover the MTU, but it must be no less than 512 bytes.)
lpVendorInfo: A string buffer which contains a vendor-specific data structure. The definition of this structure is different for each vendor's Winsock DLL and can not be supplied in this documentation. To access the contents of this structure, you must pass this string by reference to an external C function that can read the vendor-specific data structure out of the string buffer.

winsock.WSAStartup()

Description

The WSAStartup() function is called to register the application with the Windows Sockets services so that subsequent Winsock API calls can be made. This function is automatically run when a Winsock User Object is created.

integer winsock.WSAStartup ( integer wVersionRequired, ref WSAData lpWSAData )

wVersionRequired: Highest version of Windows Sockets support the caller can use.
lpWSAData: A WSAData structure variable that will receive the details of the Windows sockets implementation.

Remarks

This function is automatically run when a new winsock user object is created. It's normally not necessary to call this function again.

Return Value

If no error occurs, WSAStartup() returns a zero. Otherwise it returns one of the error codes listed below.

Error Codes

winsock.WSASYSNOTREADY: Indicates the underlying network subsystem is not ready for network communication
winsock.WSAVERNOTSUPPORTED: The verion of Windows Sockets requested is not supported.
winsock.WSAEINVAL: The Windows Sockets version specified by the application is not supported.

winsock.WSACleanup()

Description

There must be a WSACleanup() for every WSAStartup(). Therefore, this function is automatically called when a Winsock User Object is destroyed.

integer winsock.WSACleanup ()

Remarks

This function is automatically called when a Winsock User Object is destroyed. It's normally not necessary to call it directly in your application.

Return Value

If no error occurs, WSACleanup() returns a zero. Otherwise it returns one of the error codes listed below.

Error Codes

winsock.WSANOTINITIALISED: Indicates that a WSAStartup() was not successfully run.
winsock.WSAENETDOWN: The network subsystem has failed.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.

winsock.htonl()

Description

Convert a ulong from host to network byte order.

ulong winsock.htonl ( ulong hostlong )

hostlong: An unsigned long value in host byte order.

Remarks

This routine takes an unsigned long value in host byte order and returns an unsigned long value in network byte order.

Return Value

winsock.htonl() returns the value in network byte order.

winsock.htons()

Description

Convert a uint from host to network byte order.

uint winsock.htons ( uint hostint )

hostint: An unsigned integer value in host byte order.

Remarks

This routine takes an unsigned integer value in host byte order and returns an unsigned integer value in network byte order.

Return Value

winsock.htons() returns the value in network byte order.

winsock.inet_addr()

Description

Converts a string containing an IP address in the Internet standard "." notation to an unsigned long value in network byte order.

ulong winsock.inet_addr ( string cp )

cp: A string containing an IP address in the Internet standard ``.'' notation.

Remarks

This function converts the string value specified by the cp parameter from an IP address in the Internet standard ``.'' notation to an unsigned long value in network byte order. This unsigned long value is suitable for use in other PowerSocket Library functions that require an Internet IP address in unsigned long / network byte order format. IP Addresses on the Internet

Values specified using the ``.'' notation take one of the following forms:

a.b.c.d
a.b.c
a.b
a

When four parts are specified, each is interpreted as a byte of data and is assigned individually to the four bytes of an unsigned long to create a value in network byte order. Note that network byte order, on the Intel architecture, means that the bytes are assigned from right to left, such that the bytes referred to above appear ordered as {d c b a} within the unsigned long value instead of as {a b c d}.

When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as ``128.net.host''.

When a two part address is specified, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as ``net.host''.

When only one part is given, the value is stored directly in the network address without any byte rearrangement.

Return Value

If no error occurs, winsock.inet_addr() returns an unsigned long containing a suitable binary representation of the IP address given. If the passed-in string does not contain a legitimate Internet address, for example if a portion of an ``a.b.c.d'' address exceeds 255, inet_addr()returns the value INADDR_NONE.

winsock.inet_ntoa()

Description

Converts an unsigned long value in network byte order to the string equivalent IP address in the Internet standard ``.'' notation.

string winsock.inet_ntoa ( ulong ulAddr )

ulAddr: An unsigned long value representing an IP address in network byte order.

Remarks

This function takes an unsigned long value in network byte order and returns a string representing the address in ``.'' notation as ``a.b.c.d''.

Return Value

If no error occurs, inet_ntoa() returns a string value containing the text address in Internet standard ``.'' notation. Otherwise, the string returned is set equal to NULL.

winsock.ntohl()

Description

Convert a ulong from network to host byte order.

ulong winsock.ntohl ( ulong netlong )

netlong: An unsigned long value in network byte order.

Remarks

This routine takes an unsigned long value in network byte order and returns an unsigned long value in host byte order.

Return Value

ntohl() returns the value in host byte order.

winsock.ntohs()

Description

Convert an integer from network to host byte order.

integer winsock.ntohs ( integer netint )

netint: An integer value in network byte order.

Remarks

This function takes an integer in network byte order and returns an integer in host byte order.

Return Value

ntohs() returns an integer value in host byte order.

winsock.wsselect()

Description

Determine the status of one or more sockets, waiting if necessary.

long winsock.wsselect ( pbfd_set readfds, pbfd_set writefds, pbfd_set exceptfds, timeval timeout )

readfds: A pbfd_set structure containing the sockets to be checked for readability
writefds: A pbfd_set structure containing the sockets to be checked for writeability
exceptfds: A pbfd_set structure containing the sockets to be checked for errors
timeout: A timeval structure specifying the maximum time for wsselect() to wait; set equal to NULL for a blocking operation.

Remarks

This function is used to determine the status of one or more sockets. For each socket, the caller may request information on read, write or error status. The set of sockets for which a given status is requested is indicated by a pbfd_set structure. Upon return, the structures are updated to reflect the sockets that meet the specified condition. The number of sockets meeting all three of the conditions is returned by wsselect().

The pbfd_set structure has the following form:

     integer fd_count
     socket fd_array[128]

When the wsselect() function is first called, the fd_array element in each pbfd_set structure should contain a number of socket objects equal to the value in the fd_count element. When the wsselect() function completes, the fd_count element of each pbfd_set structure is set equal to the number of sockets in fd_array that meet the specified condition, and the order of the sockets in fd_array is changed so that the first fd_count number of sockets are the sockets that meet the specified condition. Note that the size of fd_array is not changed, so it is incorrect to rely on the size of fd_array when manipulating the result set.

The parameter readfds identifies those sockets which are to be checked for readability. If the socket is currently listen()ing, it will be marked as readable if an incoming connection request has been received, so that an accept() is guaranteed to complete without blocking. For other sockets, readability means that queued data is available for reading or, for sockets of typewinsock.SOCK_STREAM, that the virtual socket corresponding to the socket has been closed, so that a recv() or recvfrom() is guaranteed to complete without blocking. If the virtual circuit was closed gracefully, then a recv() will return immediately with 0 bytes read; if the virtual circuit was closed abortively, then a recv() will complete immediately with the error code winsock.WSAECONNRESET. The presence of out-of-band data will be checked if the socket option winsock.SO_OOBINLINE has been enabled (see setsockopt()).

The parameter writefds identifies those sockets which are to be checked for writeability. If a socket is wsconnect()ing (non-blocking), writeability means that the connection establishment is complete. For other sockets, writeability means that a send() or sendto() will complete without blocking. [It is not specified how long this guarantee can be assumed to be valid]

The parameter exceptfds identifies those sockets which are to be checked for the presence of out-of-band data or any exceptional error conditions. Note that out-of-band data will only be reported in this way if the optionwinsock.SO_OOBINLINE is FALSE. For a winsock.SOCK_STREAM, the breaking of the connection by the peer or due to winsock.KEEPALIVE failure will be indicated as an exception. If a socket is wsconnect()ing (non-blocking), failure of the connect attempt is indicated in exceptfds.

Any of readfds, writefds, or exceptfds may be set equal to NULL if no descriptors are of interest.

The parameter timeout controls how long the wsselect() may take to complete. If timeout is a null structure, wsselect() will block indefinitely until at least one descriptor meets the specified criteria. Otherwise, timeout specifies the maximum time that wsselect() should wait before returning. If the timeval is initialized to {0, 0}, wsselect() will return immediately; this is used to "poll" the state of the selected sockets. If this is the case, then thewsselect() call is considered nonblocking and the standard assumptions for nonblocking calls apply. For example, the blocking hook must not be called, and the Windows Sockets implementation must not yield.

Return Value

wsselect() returns the total number of sockets which are ready and contained in the pbfd_set structures, or 0 if the time limit expired, or winsock.SOCKET_ERROR if an error occurred. If the return value is winsock.SOCKET_ERROR, WSAGetLastError() may be used to retrieve a specific error code.

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINVAL: The timeout value is not valid.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAENOTSOCK: One of the pbfd_set structures contains an entry which is not a socket.

winsock.gethostbyaddr()

Description

Get host information corresponding to an address.

pbhostent winsock.gethostbyaddr ( ulong ulAddr )

ulAddr: An unsigned long value representing an IP address in network byte order.

Remarks

gethostbyaddr() returns a pbhostent structure that contains the name(s) and address(es) which correspond to the given address. The pbhostent structure has the following form:

     string h_name
     string h_aliases[]
     integer h_addrtype
     integer h_length
     ulong h_addr_list[]

The members of this structure are:

h_name: Official name of the host.
h_aliases[]: A variable-length array of alternate names for the host.
h_addrtype: The type of address being returned; this is always winsock.PF_INET.
h_length: The length, in bytes, of each address; for winsock.PF_INET, this is always 4.
h_addr_list[]: A variable-length array of addresses for the host. Addresses are unsigned long values in network byte order.

Return Value

If no error occurs, gethostbyaddr() returns a valid pbhostent structure. Otherwise, the pbhostent structure is equal to NULL and a specific error number may be retrieved by callingWSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAHOST_NOT_FOUND: Authoritative Answer Host not found.
winsock.WSATRY_AGAIN: Non-Authoritative Host not found, or SERVERFAIL.
winsock.WSANO_RECOVERY: Non recoverable errors, FORMERR, REFUSED, NOTIMP.
winsock.WSANO_DATA: Valid name, no data record of requested type.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()

winsock.gethostbyname()

Description

Get host information corresponding to a hostname.

pbhostent winsock.gethostbyname ( string name )

name: The name of the host.

Remarks

gethostbyname() returns a pbhostent structure as described under winsock.gethostbyaddr(). The contents of this structure correspond to the hostname name.

Return Value

If no error occurs, gethostbyname() returns a valid pbhostent structure. Otherwise the pbhostent structure is equal to NULL a specific error number may be retrieved by calling winsock.WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAHOST_NOT_FOUND: Authoritative Answer Host not found.
winsock.WSATRY_AGAIN: Non-Authoritative Host not found, or SERVERFAIL.
winsock.WSANO_RECOVERY: Non recoverable errors, FORMERR, REFUSED, NOTIMP.
winsock.WSANO_DATA: Valid name, no data record of requested type.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()

winsock.gethostname()

Description

Return the standard host name for the local machine.

int winsock.gethostname ( ref string name, integer namelen )

name: A string variable that will receive the host name.
namelen: The length of the buffer available in the string variable.

Remarks

This routine returns the name of the local host into the string variable specified by the name parameter. The form of the host name is dependent on the Windows Sockets implementation--it may be a simple host name, or it may be a fully qualified domain name. However, it is guaranteed that the name returned will be successfully parsed by gethostbyname() andWSAAsyncGetHostByName().

It is extremely important that the string variable used to receive the host name be filled with the number of characters specified by the namelen parameter before this function is used. A good way to do this is by using the space() function like this:

     sHostNameVariable = space(50)
     ws.gethostname(sHostNameVariable,50)

Return Value

If no error occurs, gethostname() reutrns 0, otherwise it returns winsock.SOCKET_ERROR and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSAEFAULT: The namelen parameter is too small
winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.

winsock.getprotobyname()

Description

Get protocol information corresponding to a protocol name.

pbprotoent getprotobyname ( string name )

name: A protocol name.

Remarks

getprotobyname() returns the following structure which contains the name(s) and protocol number which correspond to the given protocol name.

     string p_name
     string p_aliases[]
     integer p_proto

The members of this structure are:

p_name: Official name of the protocol.
p_aliases: A variable-length array of alternate names.
p_proto: The protocol number.

Return Value

If no error occurs, getprotobyname() returns a valid pbprotoent structure. Otherwise the structure is equal to NULL and a specific error number may be retrieved by callingWSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSANO_RECOVERY: Non recoverable errors, FORMERR, REFUSED, NOTIMP.
winsock.WSANO_DATA: Valid name, no data record of requested type.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()

winsock.getprotobynumber()

Description

Get protocol information corresponding to a protocol number.

pbprotoent winsock.getprotobynumber ( int number )

number: A protocol number.

Remarks

This function returns a pbprotoent structure as described in getprotobyname(). The contents of the structure correspond to the given protocol number.

Return Value

If no error occurs, getprotobynumber() returns a valid pbprotoent structure. Otherwise the structure is equal to NULL and a specific error number may be retrieved by callingWSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSANO_RECOVERY: Non recoverable errors, FORMERR, REFUSED, NOTIMP.
winsock.WSANO_DATA: Valid name, no data record of requested type.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()

winsock.getservbyname()

Description

Get service information corresponding to a service name and protocol.

pbservent getservbyname ( string name, string proto )

name: A service name.
proto: An protocol name. If this is NULL,getservbyname() returns the first service entry for which thename matches the s_name or one of the s_aliases. Otherwisegetservbyname() matches both the name and the proto.

Remarks

getservbyname() returns the following structure which contains the name(s) and service number which correspond to the given service name.

     string s_name
     string s_aliases[]
     integer s_port
     string s_proto

The members of this structure are:

s_name: Official name of the service.
s_aliases[]: A variable-length array of alternate names.
s_port: The port number at which the service may be contacted.
s_proto: The name of the protocol to use when contacting the service.

Return Value

If no error occurs, getservbyname() returns a valid pbservent structure. Otherwise the structure is equal to NULL and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSANO_RECOVERY: Non recoverable errors, FORMERR, REFUSED, NOTIMP.
winsock.WSANO_DATA: Valid name, no data record of requested type.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()

winsock.getservbyport()

Description

Get service information corresponding to a port and protocol.

pbservent winsock.getservbyport ( int port, string proto )

port: The port for a service.
proto: Aprotocol name. If this is NULL,getservbyport() returns the first service entry for which the portmatches the s_port. Otherwise getservbyport() matches both theport and the proto.

Remarks

getservbyport() returns a pbservent structure as described in getservbyname().

Return Value

If no error occurs, getservbyport() returns a valid pbservent structure described above. Otherwise the structure is equal to NULL and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSANO_RECOVERY: Non recoverable errors, FORMERR, REFUSED, NOTIMP.
winsock.WSANO_DATA: Valid name, no data record of requested type.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()

winsock.WSACancelAsyncRequest()

Description

Cancel an incomplete asynchronous operation.

int winsock.WSACancelAsyncRequest ( uint hAsyncTaskHandle )

hAsyncTaskHandle: Specifies the asynchronous operation to be canceled.

Remarks

The WSACancelAsyncRequest() function is used to cancel an asynchronous operation which was initiated by one of theWSAAsyncGetXByY() functions such as WSAAsyncGetHostByName(). The operation to be canceled is identified by the hAsyncTaskHandle parameter, which should be set to the asynchronous task handle as returned by the initiating function.Return Value The value returned byWSACancelAsyncRequest() is 0 if the operation was successfully canceled. Otherwise the value winsock.SOCKET_ERROR is returned, and a specific error number may be retrieved by callingWSAGetLastError().

Comments

An attempt to cancel an existing asynchronousWSAAsyncGetXByY() operation can fail with an error code of winsock.WSAEALREADY for two reasons. Firstly, the original operation has already completed and the application has dealt with the resultant message. Secondly, the original operation has already completed but the resultant message is still waiting in the application window queue.

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINVAL: Indicates that the specified asynchronous task handle was invalid
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEALREADY: The asynchronous routine being canceled has already completed.

winsock.WSACancelBlockingCall()

Description

Cancel a blocking call which is currently in progress.

int winsock.WSACancelBlockingCall ( )

Remarks

This function cancels any outstanding blocking operation. It is normally used in two situations:

An application is processing a message which has been received while a blocking call is in progress. In this case,WSAIsBlocking() will be true.
A blocking call is in progress, and Windows Sockets has called back to the application's "blocking hook" function (as established by WSASetBlockingHook()).

In each case, the original blocking call will terminate as soon as possible with the error winsock.WSAEINTR. (In (1), the termination will not take place until Windows message scheduling has caused control to revert to the blocking routine in Windows Sockets. In (2), the blocking call will be terminated as soon as the blocking hook function completes.)

In the case of a blocking wsconnect() operation, the Windows Sockets implementation will terminate the blocking call as soon as possible, but it may not be possible for the socket resources to be released until the connection has completed (and then been reset) or timed out. This is likely to be noticeable only if the application immediately tries to open a new socket (if no sockets are available), or to wsconnect() to the same peer.

Cancelling an accept() or a wsselect() call does not adversely impact the sockets passed to these calls. Only the particular call fails; any operation that was legal before the cancel is legal after the cancel, and the state of the socket is not affected in any way.

Cancelling any operation other than accept() and wsselect() can leave the socket in an indeterminate state. If an application cancels a blocking operation on a socket, the only operation that the application can depend on being able to perform on the socket is a call to closesocket(), although other operations may work on some Windows Sockets implementations. If an application desires maximum portability, it must be careful not to depend on performing operations after a cancel. An application may reset the connection by setting the timeout on winsock.SO_LINGER to 0.

If a cancel operation comprimised the integrity of a winsock.SOCK_STREAM's data stream in any way, the Windows Sockets implementation must reset the connection and fail all future operations other than closesocket() with winsock.WSAECONNABORTED.

Return Value

The value returned by WSACancelBlockingCall() is 0 if the operation was successfully canceled. Otherwise the value winsock.SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().Comments Note that it is possible that the network operation completes before the WSACancelBlockingCall() is processed, for example if data is received into the user buffer at interrupt time while the application is in a blocking hook. In this case, the blocking operation will return successfully as if WSACancelBlockingCall() had never been called. Note that theWSACancelBlockingCall() still succeeds in this case; the only way to know with certainty that an operation was actually cancelled is to check for a return code of WSAEINTR from the blocking call.

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINVAL: Indicates that there is no outstanding blocking call.

winsock.WSAGetLastError()

Description

Get the error status for the last operation which failed.

int winsock.WSAGetLastError ( )

Remarks

This function returns the last network error that occurred. When a particular Windows Sockets API function indicates that an error has occurred, this function should be called to retrieve the appropriate error code.

Return Value

The return value indicates the error code for the last Windows Sockets API routine performed by this thread.

winsock.WSAIsBlocking()

Description

Determine if a blocking call is in progress.

integer winsock.WSAIsBlocking ( )

Remarks

This function allows a task to determine if it is executing while waiting for a previous blocking call to complete.

Return Value

The return value is non-zero if there is an outstanding blocking function awaiting completion. Otherwise, it is 0.

Comments

Although a call issued on a blocking socket appears to an application program as though it "blocks", the Windows Sockets DLL has to relinquish the processor to allow other applications to run. This means that it is possible for the application which issued the blocking call to be re-entered, depending on the message(s) it receives. In this instance, theWSAIsBlocking() function can be used to ascertain whether the task has been re-entered while waiting for an outstanding blocking call to complete. Note that Windows Sockets prohibits more than one outstanding call per thread.

winsock.WSASetLastError()

Description

Set the error code which can be retrieved by WSAGetLastError().

winsock.WSASetLastError ( int iError )

Remarks

This function allows an application to set the error code to be returned by a subsequent WSAGetLastError() call for the current thread. Note that any subsequent Windows Sockets routine called by the application will override the error code as set by this routine.

iError: Specifies the error code to be returned by a subsequent WSAGetLastError() call.

Return Value

None.

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.

winsock.WSAAsyncGetHostByAddr()

Description

Get host information corresponding to an address - asynchronous version.

uint winsock.WSAAsyncGetHostByAddr ( uint hWnd, uint wMsg, ulong ulAddr, ref string buf, int buflen )

hWnd: The handle of the window which should receive a message when the asynchronous request completes.
wMsg: The number of the event to trigger in the window referenced by hWnd when the asynchronous request completes.
ulAddr: An unsigned long value in network byte order representing an IP address for which you want to retrieve host information.
buf: A string variable WHICH SHOULD CONTAIN winsock.MAXGETHOSTSTRUCT CHARACTERS (see below) that will receive the hostent data.
buflen: The size of the buf string, usually winsock.MAXGETHOSTSTRUCT.

Remarks

This function is an asynchronous version of gethostbyaddr(), and is used to retrieve host name and address information corresponding to a network address. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the string buffer provided by the caller and the window hWnd receives message wMsg.

Note: The string variable buf must continue to exist after the WSAAsyncGetHostByAddr function call in order for Winsock to write the hostent data successfully when the asynchronous function completes. Try to avoid making this string a global variable, but be certain that the variable will not be destroyed before WSAAsyncGetHostByAddr completes. Do not declare this string as a local variable in the event script or function that calls WSAAsyncGetHostByAddr! The event script or function will finish, destroying the variable, before WSAAsyncGetHostByAddr is done processing and an error will occur.

The wMsg parameter contains the number of the event that you want to have triggered when the asynchronous function completes. It is in the script for this event that your program should perform whatever processing is required to make use of the hostent structure provided by WSAAsyncGetHostByAddr. The very first thing this script should do is call winsock.return_hostent() to convert the hostent structure in buf to a pbhostent structure which your PowerScript code can use. For example, assuming that the name of your buf variable is sBuffer, the PowerScript code would look like this:

     pbhostent pbheTmp
	
	pbheTmp = ws.return_hostent(sBuffer)
	
	...

The event code 1024 corresponds to the pbm_custom01 event in PowerBuilder. The event code for each subsequent pbm_customXX event can be determined easily using the following formula:

     (event code) = (pbm_customXX number) + 1023

As an example, the event code for the pbm_custom02 event is 1025.

Sometimes the same event is triggered by multiple asynchronous functions. When this is the case, one needs a way to determine which asynchronous function triggered the event so that the correct processing may be performed. The PowerScript message system object makes this possible. the WordParm attribute contains the asynchronous task handle of the WSAAsync function that triggered the wMsg event. The WordParm attribute of the message system object is accessed like this in your wMsg event script:

     message.WordParm

To find out if an error occurred during the processing of the asynchronous function, use the winsock.WSAGetAsyncError() function to read the high 16 bits of the message system object's LongParm attribute, like this:

     integer iError
	
     iError = ws.WSAGetAsyncError(message.LongParm)

An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a hostent structure. Note that if the error code is winsock.WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of the message system object's LongParm attribute contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetHostByAddr() function call with a buffer large enough to receive all the desired information.

Use the winsock.WSAGetAsyncBufLen() function to read the low 16 bits of the message system object's LongParm attribute, like this:

     integer iBufLen
	
     iBufLen = ws.WSAGetAsyncError(message.LongParm)

Return Value

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself. If the operation was successfully initiated, WSAAsyncGetHostByAddr() returns a nonzero value of type uint which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the WordParm message system object attribute.

If the asynchronous operation could not be initiated,WSAAsyncGetHostByAddr() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes

The following error codes may be set when the hWnd window receives the wMsg event message. As described above, the error code may be extracted from the LongParm attribute of the message system object using the WSAGetAsyncError function.

winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAENOBUFS: No/insufficient buffer space is available
winsock.WSAHOST_NOT_FOUND: Authoritative Answer Host not found.
winsock.WSATRY_AGAIN: Non-Authoritative Host not found, or SERVERFAIL.
winsock.WSANO_RECOVERY: Non recoverable errors, FORMERR, REFUSED, NOTIMP.
winsock.WSANO_DATA: Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEWOULDBLOCK: The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

winsock.WSAAsyncGetHostByName()

Description

Get host information corresponding to a hostname - asynchronous version.

uint winsock.WSAAsyncGetHostByName ( uint hWnd, uint wMsg, string name, ref stringbuf, int buflen )

hWnd: The handle of the window which should receive a message when the asynchronous request completes.
wMsg: The number of the event to trigger in the window referenced by hWnd when the asynchronous request completes.
name: The name of the host.
buf: A string variable WHICH SHOULD CONTAIN winsock.MAXGETHOSTSTRUCT CHARACTERS (see below) that will receive the hostent data.
buflen: The size of the buf string, usually winsock.MAXGETHOSTSTRUCT.

Remarks

This function is an asynchronous version ofgethostbyname(), and is used to retrieve host name and address information corresponding to a hostname. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back anasynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.
See WSAAsyncGetHostByAddr for further details.

Return Value

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself. If the operation was successfully initiated, WSAAsyncGetHostByName() returns a nonzero value of type uint which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the WordParm message system object attribute.

If the asynchronous operation could not be initiated,WSAAsyncGetHostByName() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes

The following error codes may be set when the hWnd window receives the wMsg event message. The error code may be extracted from the LongParm attribute of the message system object using the WSAGetAsyncError function.

winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAENOBUFS: No/insufficient buffer space is available
winsock.WSAHOST_NOT_FOUND: Authoritative Answer Host not found.
winsock.WSATRY_AGAIN: Non-Authoritative Host not found, or SERVERFAIL.
winsock.WSANO_RECOVERY: Non recoverable errors, FORMERR, REFUSED, NOTIMP.
winsock.WSANO_DATA: Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEWOULDBLOCK: The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

winsock.WSAAsyncGetProtoByName()

Description

Get protocol information corresponding to a protocol name - asynchronous version.

uint winsock.WSAAsyncGetProtoByName ( uint hWnd, uint wMsg, string name, ref stringbuf, int buflen )

hWnd: The handle of the window which should receive a message when the asynchronous request completes.
wMsg: The number of the event to trigger in the window referenced by hWnd when the asynchronous request completes.
name: The protocol name to be resolved.
buf: A string variable WHICH SHOULD CONTAIN winsock.MAXGETHOSTSTRUCT CHARACTERS (see below) that will receive the protoent data.
buflen: The size of the buf string, usually winsock.MAXGETHOSTSTRUCT.

Remarks

This function is an asynchronous version ofgetprotobyname(), and is used to retrieve the protocol name and number corresponding to a protocol name. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

Note: The string variable buf must continue to exist after the WSAAsyncGetProtoByName function call in order for Winsock to write the protoent data successfully when the asynchronous function completes. Try to avoid making this string a global variable, but be certain that the variable will not be destroyed before WSAAsyncGetProtoByName completes. Do not declare this string as a local variable in the event script or function that calls WSAAsyncGetProtoByName! The event script or function will finish, destroying the variable, before WSAAsyncGetProtoByName is done processing and an error will occur.

The wMsg parameter contains the number of the event that you want to have triggered when the asynchronous function completes. It is in the script for this event that your program should perform whatever processing is required to make use of the protoent structure provided by WSAAsyncGetProtoByName. The very first thing this script should do is call winsock.return_protoent() to convert the protoent structure in buf to a pbprotoent structure which your PowerScript code can use. For example, assuming that the name of your buf variable is sBuffer, the PowerScript code would look like this:

     pbprotoent pbpeTmp

	pbpeTmp = ws.return_protoent(sBuffer)

	...

The event code 1024 corresponds to the pbm_custom01 event in PowerBuilder. The event code for each subsequent pbm_customXX event can be determined easily using the following formula:

     (event code) = (pbm_customXX number) + 1023

As an example, the event code for the pbm_custom02 event is 1025.

     message.WordParm

     integer iError
	
     iError = ws.WSAGetAsyncError(message.LongParm)

An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a protoent structure. Note that if the error code is winsock.WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of the message system object's LongParm attribute contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetProtoByName() function call with a buffer large enough to receive all the desired information.

Use the winsock.WSAGetAsyncBufLen() function to read the low 16 bits of the message system object's LongParm attribute, like this:

     integer iBufLen
	
     iBufLen = ws.WSAGetAsyncError(message.LongParm)

Return Value

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself. If the operation was successfully initiated, WSAAsyncGetProtoByName() returns a nonzero value of type uint which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the WordParm message system object attribute.

If the asynchronous operation could not be initiated,WSAAsyncGetProtoByName() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAENOBUFS: No/insufficient buffer space is available
winsock.WSAHOST_NOT_FOUND: Authoritative Answer Host not found.
winsock.WSATRY_AGAIN: Non-Authoritative Host not found, or SERVERFAIL.
winsock.WSANO_RECOVERY: Non recoverable errors, FORMERR, REFUSED, NOTIMP.
winsock.WSANO_DATA: Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEWOULDBLOCK: The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

winsock.WSAAsyncGetProtoByNumber()

Description

Get protocol information corresponding to a protocol number - asynchronous version.

uint winsock.WSAAsyncGetProtoByNumber ( uint hWnd, uint wMsg, int number, ref stringbuf, int buflen )

hWnd: The handle of the window which should receive a message when the asynchronous request completes.
wMsg: The number of the event to trigger in the window referenced by hWnd when the asynchronous request completes.
number: The protocol number to be resolved.
buf: A string variable WHICH SHOULD CONTAIN winsock.MAXGETHOSTSTRUCT CHARACTERS (see below) that will receive the protoent data.
buflen: The size of the buf string, usually winsock.MAXGETHOSTSTRUCT.

Remarks

This function is an asynchronous version of getprotobynumber(), and is used to retrieve the protocol name and number corresponding to a protocol number. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

See WSAAsyncGetProtoByName for further details.

Return Value

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself. If the operation was successfully initiated, WSAAsyncGetProtoByNumber() returns a nonzero value of type uint which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the WordParm message system object attribute.

If the asynchronous operation could not be initiated,WSAAsyncGetProtoByNumber() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAENOBUFS: No/insufficient buffer space is available
winsock.WSAHOST_NOT_FOUND: Authoritative Answer Host not found.
winsock.WSATRY_AGAIN: Non-Authoritative Host not found, or SERVERFAIL.
winsock.WSANO_RECOVERY: Non recoverable errors, FORMERR, REFUSED, NOTIMP.
winsock.WSANO_DATA: Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEWOULDBLOCK: The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

winsock.WSAAsyncGetServByName()

Description

Get service information corresponding to a service name and protocol -- asynchronous version.

uint winsock.WSAAsyncGetServByName ( uint hWnd, uint wMsg, string name, stringproto, ref string buf, int buflen )

hWnd: The handle of the window which should receive a message when the asynchronous request completes.
wMsg: The number of the event to trigger in the window referenced by hWnd when the asynchronous request completes.
name: A service name.
proto: A protocol name. This may be NULL, in which caseWSAAsyncGetServByName() will search for the first service entry for which s_name or one of the s_aliases matches the givenname. Otherwise WSAAsyncGetServByName() matches both name and proto.
buf: A string variable WHICH SHOULD CONTAIN winsock.MAXGETHOSTSTRUCT CHARACTERS (see below) that will receive the servent data.
buflen: The size of the buf string, usually winsock.MAXGETHOSTSTRUCT.

Remarks

This function is an asynchronous version of getservbyname(), and is used to retrieve service information corresponding to a service name. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

Note: The string variable buf must continue to exist after the WSAAsyncGetServByName function call in order for Winsock to write the servent data successfully when the asynchronous function completes. Try to avoid making this string a global variable, but be certain that the variable will not be destroyed before WSAAsyncGetServByName completes. Do not declare this string as a local variable in the event script or function that calls WSAAsyncGetServByName! The event script or function will finish, destroying the variable, before WSAAsyncGetServByName is done processing and an error will occur.

The wMsg parameter contains the number of the event that you want to have triggered when the asynchronous function completes. It is in the script for this event that your program should perform whatever processing is required to make use of the servent structure provided by WSAAsyncGetServByName. The very first thing this script should do is call winsock.return_servent() to convert the servent structure in buf to a pbservent structure which your PowerScript code can use. For example, assuming that the name of your buf variable is sBuffer, the PowerScript code would look like this:

     pbservent pbseTmp
	
	pbseTmp = ws.return_servent(sBuffer)
	
	...

The event code 1024 corresponds to the pbm_custom01 event in PowerBuilder. The event code for each subsequent pbm_customXX event can be determined easily using the following formula:

     (event code) = (pbm_customXX number) + 1023

As an example, the event code for the pbm_custom02 event is 1025.

     message.WordParm

     integer iError
	
     iError = ws.WSAGetAsyncError(message.LongParm)

An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a servent structure. Note that if the error code is winsock.WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of the message system object's LongParm attribute contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetServByName() function call with a buffer large enough to receive all the desired information.

Use the winsock.WSAGetAsyncBufLen() function to read the low 16 bits of the message system object's LongParm attribute, like this:

     integer iBufLen
	
     iBufLen = ws.WSAGetAsyncError(message.LongParm)

Return Value

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself. If the operation was successfully initiated, WSAAsyncGetServByName() returns a nonzero value of type uint which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the WordParm message system object attribute.

If the asynchronous operation could not be initiated,WSAAsyncGetServByName() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAENOBUFS: No/insufficient buffer space is available
winsock.WSAHOST_NOT_FOUND: Authoritative Answer Host not found.
winsock.WSATRY_AGAIN: Non-Authoritative Host not found, or SERVERFAIL.
winsock.WSANO_RECOVERY: Non recoverable errors, FORMERR, REFUSED, NOTIMP.
winsock.WSANO_DATA: Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEWOULDBLOCK: The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

winsock.WSAAsyncGetServByPort()

Description

Get service information corresponding to a port and protocol - asynchronous version.

uint winsock.WSAAsyncGetServByPort ( uint hWnd, uint wMsg, int port, stringproto, ref string buf, int buflen )

hWnd: The handle of the window which should receive a message when the asynchronous request completes.
wMsg: The number of the event to trigger in the window referenced by hWnd when the asynchronous request completes.
port: The port number for the service.
proto: A protocol name. This may be NULL, in which caseWSAAsyncGetServByPort() will search for the first service entry for which s_port match the given port. OtherwiseWSAAsyncGetServByPort() matches both port and proto.
buf: A string variable WHICH SHOULD CONTAIN winsock.MAXGETHOSTSTRUCT CHARACTERS (see below) that will receive the servent data.
buflen: The size of the buf string, usually winsock.MAXGETHOSTSTRUCT.

Remarks

This function is an asynchronous version of getservbyport(), and is used to retrieve service information corresponding to a port number. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

See WSAAsyncGetServByName() for further details.

Return Value

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself. If the operation was successfully initiated, WSAAsyncGetServByPort() returns a nonzero value of type uint which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the WordParm message system object attribute.

If the asynchronous operation could not be initiated,WSAAsyncGetServByPort() returns a zero value, and a specific error number may be retrieved by callingWSAGetLastError().

Error Codes

winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAENOBUFS: No/insufficient buffer space is available
winsock.WSAHOST_NOT_FOUND: Authoritative Answer Host not found.
winsock.WSATRY_AGAIN: Non-Authoritative Host not found, or SERVERFAIL.
winsock.WSANO_RECOVERY: Non recoverable errors, FORMERR, REFUSED, NOTIMP.
winsock.WSANO_DATA: Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEWOULDBLOCK: The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

winsock.return_hostent()

Description

Read a string buffer containing a hostent structure and return a pbhostent structure.

pbhostent winsock.return_hostent ( ref string buf )

buf: A string variable filled with a hostent structure after a successful WSAAsyncGetHost* function call.

Remarks

The return_hostent() function is used to convert a string buffer populated by the WSAAsyncGetHostByName() and WSAAsyncGetHostByAddr() functions into a pbhostent structure that can be used in PowerBuilder. The string buffer acts as temporary storage space for a hostent structure and this function must be used to extract the hostent information from the string buffer.

Return Value

This function returns a pbhostent structure containing the information stored in the hostent structure within the string buffer. If an error occurs, the pbhostent structure is set equal to NULL.

winsock.return_servent()

Description

Read a string buffer containing a servent structure and return a pbservent structure.

pbservent winsock.return_servent ( ref string buf )

buf: A string variable filled with a servent structure after a successful WSAAsyncGetServ* function call.

Remarks

The return_servent() function is used to convert a string buffer populated by the WSAAsyncGetServByName() and WSAAsyncGetServByPort() functions into a pbservent structure that can be used in PowerBuilder. The string buffer acts as temporary storage space for a servent structure and this function must be used to extract the servent information from the string buffer.

Return Value

This function returns a pbservent structure containing the information stored in the servent structure within the string buffer. If an error occurs, the pbservent structure is set equal to NULL.

winsock.return_protoent()

Description

Read a string buffer containing a protoent structure and return a pbprotoent structure.

pbprotoent winsock.return_protoent ( ref string buf )

buf: A string variable filled with a protoent structure after a successful WSAAsyncGetProto* function call.

Remarks

The return_protoent() function is used to convert a string buffer populated by the WSAAsyncGetProtoByName() and WSAAsyncGetProtoByNumber() functions into a pbprotoent structure that can be used in PowerBuilder. The string buffer acts as temporary storage space for a protoent structure and this function must be used to extract the protoent information from the string buffer.

Return Value

This function returns a pbprotoent structure containing the information stored in the protoent structure within the string buffer. If an error occurs, the pbprotoent structure is set equal to NULL.

winsock.WSAGetSelectError()

Description

Return the upper 16 bits (the error code portion) of the LongParm value passed as a parameter.

integer winsock.WSAGetSelectError ( long LongParm )

LongParm: A long value obtained from the LongParm attribute of the PowerBuilder message system object message.LongParm and passed to this function as a parameter.

Remarks

This function accepts a long value and returns the upper 16 bits of the long as an integer value. Its purpose is to return an error code value embedded in the LongParm attribute of the PowerBuilder message system object after the (possibly unsuccessful) completion of the asynchronous socket function WSAAsyncSelect().

Return Value

Integer value representing the Winsock error code embedded in LongParm.

winsock.WSAGetSelectEvent()

Description

Return the lower 16 bits (the network event code portion) of the LongParm value passed as a parameter.

integer winsock.WSAGetSelectEvent ( long LongParm )

LongParm: A long value obtained from the LongParm attribute of the PowerBuilder message system object message.LongParm and passed to this function as a parameter.

Remarks

This function accepts a long value and returns the lower 16 bits of the long as an integer value. Its purpose is to return a network event code value embedded in the LongParm attribute of the PowerBuilder message system object after the (possibly unsuccessful) completion of the asynchronous socket function WSAAsyncSelect().

Return Value

Integer value representing the Winsock network event code embedded in LongParm.

winsock.WSAGetAsyncBufLen()

Description

Return the lower 16 bits (the required buffer length portion) of the LongParm value passed as a parameter.

integer winsock.WSAGetAsyncBufLen ( long LongParm )

LongParm: A long value obtained from the LongParm attribute of the PowerBuilder message system object message.LongParm and passed to this function as a parameter.

Remarks

This function accepts a long value and returns the lower 16 bits of the long as an integer value. Its purpose is to return the required buffer length value embedded in the LongParm attribute of the PowerBuilder message system object after the unsuccessful completion of one of the asynchronous database functions WSAAsyncGetXByY.

Return Value

Integer value representing the required buffer length value embedded in LongParm.

winsock.WSAGetAsyncError()

Description

Return the upper 16 bits (the error code portion) of the LongParm value passed as a parameter.

integer winsock.WSAGetAsyncError ( long LongParm )

LongParm: A long value obtained from the LongParm attribute of the PowerBuilder message system object message.LongParm and passed to this function as a parameter.

Remarks

Return Value

Integer value representing the Winsock error code embedded in LongParm.

winsock.WSOr()

Description

Perform a binary OR operation on two integers and return the result.

integer winsock.WSOr ( integer intone, integer inttwo )

intone: One of the two integers to be OR'ed together.
inttwo: The other of the two integers to be OR'ed together.

Remarks

This function accepts two integers, performs a binary OR using those two integers, and returns the resulting integer.

Return Value

Integer.

winsock.WSAUnhookBlockingHook()

Description

Restore the original blocking hook function.

integer winsock.WSAUnhookBlockingHook ( )

Remarks

This function removes any previous blocking hook that has been installed and reinstalls the default blocking mechanism.

Return Value

A return value of 0 indicates the operation was successful. Otherwise, the value winsock.SOCKET_ERROR is returned.

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before calling this function.

Socket User Object

The socket user object encapsulates a socket descriptor (also known as a socket handle or a socket number) along with the functions that operate on the socket descriptor. Create a socket user object, or one of its descendants (SocketStream or SocketDGram) to create and use a socket in your program.

SocketStream User Object

The socketstream user object is inherited from the socket user object. The only difference between the socketstream user object and the socket user object is that the socketstream user object automatically creates a new stream socket by calling the socket() function in its constructor event. Creating a socketstream user object simply saves you this one step in your PowerScript code.

SocketDGram User Object

The socketdgram user object is inherited from the socket user object. The only difference between the socketdgram user object and the socket user object is that the socketdgram user object automatically creates a new datagram socket by calling the socket() function in its constructor event. Creating a socketdgram user object simply saves you this one step in your PowerScript code.

socket.accept()

Description

Accept a connection on a socket.

uint socket.accept ( ref ulong ulAddr, ref int iPort )

ulAddr: An unsigned long variable which receives the address, in network byte order, of the computer that originated the socket connection to this listen()ing socket object.
iPort: An integer variable which receives the port number of the originating socket.

Remarks

This routine extracts the first connection on the queue of pending connections for the listen()ing socket object, creates a new socket with the same properties as this one and returns a socket number for the new socket. If no pending connections are present on the queue, and the socket is not marked as non-blocking,accept() blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue,accept() returns an error as described below. The original socket remains open and listen()ing.

In PowerBuilder, each socket number is encapsulated within a socket object. When a new socket is created by the accept() function, a new socket object must be initialized with socket number of the socket created by accept(). The socket.initsocket() function must be called after creating a new socket object and must be given the socket number of the new accept()ed socket. The following PowerScript code illustrates this, assuming that ssSocket is a bound and listening stream socket:

     socket sockNewSocket
	uint uiNewSocketNumber
	ulong ulAddrTmp
	int iPortTmp
	
	uiNewSocketNumber = ssSocket.accept(ulAddrTmp,iPortTmp)
	
	sockNewSocket = create socket
	sockNewSocket.initsocket(uiNewSocketNumber)

The argument ulAddr is the variable which is to be filled with the address of the computer that originated the socket connection. The argument iPort is the variable which is to be filled with the port number that the originating computer is using for this socket connection. This call is used with connection-based socket types such aswinsock.SOCK_STREAM.

Return Value

If no error occurs, accept() returns a value of type uint which is the socket number for the new, accepted socket. Otherwise, a value of winsock.INVALID_SOCKET is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()
winsock.WSAEINPROGRESS: A blocking Windows Sockets call is in progress.
winsock.WSAEINVAL: listen() was not invoked prior to accept().
winsock.WSAEMFILE: The queue is empty upon entry to accept() and there are no descriptors available.
winsock.WSAENOBUFS: No buffer space is available.
winsock.WSAENOTSOCK: The descriptor is not a socket.
winsock.WSAEOPNOTSUPP: The referenced socket is not a type that supports connection-oriented service.
winsock.WSAEWOULDBLOCK: The socket is marked as non-blocking and no connections are present to be accepted.

socket.bind()

Description

Associate a local address with a socket.

int socket.bind ( ulong ulAddr, int iPort )

ulAddr: The IP address, as an unsigned long in network byte order, to which the socket is to be bound.
iPort: The port number to which the socket is to be bound.

Remarks

This routine is used on an unconnected datagram or stream socket, before subsequent wsconnect()s or listen()s. When a socket is created, it exists but it has no name assigned.bind() establishes the local association (host address/port number) of the socket by assigning a local name to an unnamed socket.

If iPort equals 0 then a unique port between 1024 and 5000 is assigned to the socket. The application may use getsockname() after bind() to learn the address that has been assigned to it, but note that getsockname() will not necessarily fill in the Internet address until the socket is connected, since several Internet addresses may be valid if the host is multi-homed.

Return Value

If no error occurs, bind() returns 0. Otherwise, it returns winsock.SOCKET_ERROR, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEADDRINUSE: The specified address is already in use. (See the SO_REUSEADDR socket option under setsockopt().)
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()
winsock.WSAEINPROGRESS: A blocking Windows Sockets call is in progress.
winsock.WSAEAFNOSUPPORT: The specified address family is not supported by this protocol.
winsock.WSAEINVAL: The socket is already bound to an address.
winsock.WSAENOBUFS: Not enough buffers available, too many connections.
winsock.WSAENOTSOCK: The descriptor is not a socket.

socket.closesocket()

Description

Close a socket.

int socket.closesocket ( )

Remarks

This function closes a socket. More precisely, it releases the socket descriptor, so that further references to the socket's number will fail with the error winsock.WSAENOTSOCK. closesocket() does not destroy the PowerBuilder socket object. If this is the last reference to the underlying socket, the associated naming information and queued data are discarded.

The semantics of closesocket() are affected by the socket optionswinsock.SO_LINGER and winsock.SO_DONTLINGER as follows:

Option		Interval	Type of close		Wait for close?
---------------	---------------	-----------------------	----------------
SO_DONTLINGER	Don't care	Graceful		No
SO_LINGER	Zero		Hard			No
SO_LINGER	Non-zero	Graceful		Yes

If winsock.SO_LINGER is set (i.e. the l_onoff field of the linger structure is non-zero; see getsockopt() and setsockopt()) with a zero timeout interval (l_linger is zero), closesocket() is not blocked even if queued data has not yet been sent or acknowledged. This is called a "hard" close, because the socket is closed immediately, and any unsent data is lost. Any recv() call on the remote side of the circuit can fail with winsock.WSAECONNRESET.

If winsock.SO_LINGER is set with a non-zero timeout interval, the closesocket() call blocks until the remaining data has been sent or until the timeout expires. This is called a graceful disconnect. Note that if the socket is set to non-blocking and winsock.SO_LINGER is set to a non-zero timeout, the call to closesocket() will fail with an error of winsock.WSAEWOULDBLOCK. If winsock.SO_DONTLINGER is set on a stream socket (i.e. the l_onoff field of the linger structure is zero; see getsockopt() and setsockopt()), the closesocket() call will return immediately. However, any data queued for transmission will be sent if possible before the underlying socket is closed. This is also called a graceful disconnect. Note that in this case the Windows Sockets implementation may not release the socket and other resources for an arbitrary period, which may affect applications which expect to use all available sockets.

Return Value

If no error occurs, closesocket() returns 0. Otherwise, a value of winsock.SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAENOTSOCK: The descriptor is not a socket.
winsock.WSAEINPROGRESS: A blocking Windows Sockets call is in progress.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall().
winsock.WSAEWOULDBLOCK: The socket is marked as nonblocking and SO_LINGER is set to a nonzero timeout value.

socket.wsconnect()

Description

Establish a connection to a peer.

int socket.wsconnect ( ulong ulAddr, int iPort )

ulAddr: The IP address of the computer to which to connect, as an unsigned long value in network byte order.
iPort: The port number to which to connect.

Remarks

This function is used to create a connection to the specified foreign association. If the socket is unbound, unique values are assigned to the local association by the system, and the socket is marked as bound.

For stream sockets (type winsock.SOCK_STREAM), an active connection is initiated to the foreign host and port number specified. When the socket call completes successfully, the socket is ready to send/receive data.

For a datagram socket (type winsock.SOCK_DGRAM), a default destination is set, which will be used on subsequent send() and recv() calls.

On a non-blocking socket, if the return value is winsock.SOCKET_ERROR an application should call WSAGetLastError(). If this indicates an error code of winsock.WSAEWOULDBLOCK, then your application can either:

Use wsselect() to determine the completion of the connection request by checking if the socket is writeable, or
If your application is using the message-basedWSAAsyncSelect() to indicate interest in connection events, then your application will receive an FD_CONNECT message when the connect operation is complete.

Return Value

If no error occurs, wsconnect() returns 0. Otherwise, it returns winsock.SOCKET_ERROR, and a specific error code may be retrieved by calling WSAGetLastError().

On a blocking socket, the return value indicates success or failure of the connection attempt.

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEADDRINUSE: The specified address is already in use.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()
winsock.WSAEINPROGRESS: A blocking Windows Sockets call is in progress.
winsock.WSAEADDRNOTAVAIL: The specified address is not available from the local machine.
winsock.WSAEAFNOSUPPORT: Addresses in the specified family cannot be used with this socket.
winsock.WSAECONNREFUSED: The attempt to connect was forcefully rejected.
winsock.WSAEDESTADDREQ: A destination address is required.
winsock.WSAEINVAL: The socket is not already bound to an address.
winsock.WSAEISCONN: The socket is already connected.
winsock.WSAEMFILE: No more file descriptors are available.
winsock.WSAENETUNREACH: The network can't be reached from this host at this time.
winsock.WSAENOBUFS: No buffer space is available. The socket cannot be connected.
winsock.WSAENOTSOCK: The descriptor is not a socket.
winsock.WSAETIMEDOUT: Attempt to connect timed out without establishing a connection
winsock.WSAEWOULDBLOCK: The socket is marked as non-blocking and the connection cannot be completed immediately. It is possible to winsock.wsselect() the socket while it is connecting by wsselect()ing it for writing.

socket.getpeername()

Description

Get the address of the peer to which a socket is connected.

int socket.getpeername( ref ulong ulAddr, ref int iPort )

ulAddr: An unsigned long variable which is to receive the IP address of the peer in network byte order.
iPort: An integer variable which is to receive the port number of the peer's socket connection.

Remarks

getpeername() retrieves the name of the peer connected to the socket and stores it in the variables provided as parameters. It is used on a connected datagram or stream socket.

Return Value

If no error occurs, getpeername() returns 0. Otherwise, a value of winsock.SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINPROGRESS: A blocking Windows Sockets call is in progress.
winsock.WSAENOTCONN: The socket is not connected.
winsock.WSAENOTSOCK: The descriptor is not a socket.

socket.getsockname()

Description

Get the local name for a socket.

int socket.getsockname(ref ulong ulAddr, ref int iPort )

ulAddr: An unsigned long variable which is to receive the IP address of the peer in network byte order.
iPort: An integer variable which is to receive the port number of the peer's socket connection.

Remarks

getsockname() retrieves the current name for the socket. It is used on a bound and/or connected socket to obtain the local association for the socket. This call is especially useful when a wsconnect() call has been made without doing a bind() first; this call provides the only means by which you can determine the local association which has been set by the system.

Return Value

If no error occurs, getsockname() returns 0. Otherwise, a value of winsock.SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAENOTSOCK: The descriptor is not a socket.
winsock.WSAEINVAL: The socket has not been bound to an address with bind().

socket.getsockopt()

Description

Retrieve a socket option.

int socket.getsockopt ( int level, int optname, ref int optvalint, ref linger optvallinger )

level: The level at which the option is defined; the only supported levels are winsock.SOL_SOCKET and winsock.IPPROTO_TCP.
optname: The socket option for which the value is to be retrieved.
optvalint: The integer variable in which the integer return value for the requested option is to be returned.
optvallinger: The linger structure variable in which the linger structure return value for the winsock.SO_LINGER option is to be returned.

Remarks

getsockopt() retrieves the current value for a socket option associated with a socket of any type, in any state, and stores the result in either optvalint or optvallinger depending on the type of information returned for the requested option. Options may exist at multiple protocol levels, but they are always present at the uppermost ``socket'' level. Options affect socket operations, such as whether an operation blocks or not, the routing of packets, out-of-band data transfer, etc.

If the option was never set with setsockopt(), then getsockopt() returns the default value for the option.

The following options are supported for getsockopt(). The Type identifies the type of information returned. The winsock.TCP_NODELAY option uses level winsock.IPPROTO_TCP, all other options use level winsock.SOL_SOCKET. Note that a type of BOOL indicates that the information returned for the option is an integer with a value of 1 for true or 0 for false.

Value		Type		Meaning
---------------	---------------	-----------------------------------------------
SO_ACCEPTCONN	BOOL		Socket is listen()ing.
SO_BROADCAST	BOOL		Socket is configured for the transmission of
				broadcast messages.
SO_DEBUG	BOOL		Debugging is enabled.  
SO_DONTLINGER	BOOL		If true, the SO_LINGER option is disabled..
SO_DONTROUTE	BOOL		Routing is disabled.
SO_ERROR	int		Retrieve error status and clear.
SO_KEEPALIVE	BOOL		Keepalives are being sent.
SO_LINGER	       linger	Returns the current linger options.
SO_OOBINLINE	BOOL		Out-of-band data is being received in the
				normal data stream.  
SO_RCVBUF	int		Buffer size for receives
SO_REUSEADDR	BOOL		The socket may be bound to an address which
				is already in use.
SO_SNDBUF	int		Buffer size for sends
SO_TYPE		int		The type of the socket (e.g. SOCK_STREAM).  
TCP_NODELAY	BOOL		Disables the Nagle algorithm for send
				coalescing.

Calling getsockopt() with an unsupported option will result in an error code of winsock.WSAENOPROTOOPT being returned from WSAGetLastError().

Return Value

If no error occurs, getsockopt() returns 0. Otherwise, a value of winsock.SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAENOPROTOOPT: The option is unknown or unsupported. In particular, SO_BROADCAST is not supported on sockets of type SOCK_STREAM, while SO_ACCEPTCON, SO_DONTLINGER, SO_KEEPALIVE, SO_LINGER and SO_OOBINLINE are not supported on sockets of type SOCK_DGRAM.
winsock.WSAENOPROTOOPT: The option is unknown or unsupported. In particular, SO_BROADCAST is not supported on sockets of type SOCK_STREAM, while SO_ACCEPTCONN, SO_DONTLINGER, SO_KEEPALIVE, SO_LINGER and SO_OOBINLINE are not supported on sockets of type SOCK_DGRAM.
winsock.WSAENOTSOCK: The descriptor is not a socket.

socket.ioctlsocket()

Description

Control the mode of a socket.

int socket.ioctlsocket ( long cmd, ref ulong argp )

cmd: The command to perform on the socket.
argp: An unsigned long variable as a parameter for cmd.

Remarks

This routine may be used on any socket in any state. It is used to get or retrieve operating parameters associated with the socket, independent of the protocol and communications subsystem. The following commands are supported:

winsock.FIONBIO: Enable or disable non-blocking mode on the socket. argp is non-zero if non-blocking mode is to be enabled and zero if it is to be disabled. When a socket is created, it operates in blocking mode (i.e. non-blocking mode is disabled).
The WSAAsyncSelect() routine automatically sets a socket to nonblocking mode. If WSAAsyncSelect() has been issued on a socket, then any attempt to use ioctlsocket() to set the socket back to blocking mode will fail with winsock.WSAEINVAL. To set the socket back to blocking mode, an application must first disable WSAAsyncSelect() by callingWSAAsyncSelect() with the lEvent parameter equal to 0.
winsock.FIONREAD: Determine the amount of data which can be read atomically from socket. argp is the unsigned long variable in whichioctlsocket() stores the result. If the socket is of type winsock.SOCK_STREAM,winsock.FIONREAD returns the total amount of data which may be read in a singlerecv(); this is normally the same as the total amount of data queued on the socket. If the socket is of type winsock.SOCK_DGRAM, winsock.FIONREAD returns the size of the first datagram queued on the socket.
winsock.SIOCATMARK: Determine whether or not all out-of-band data has been read. This applies only to a socket of type winsock.SOCK_STREAM which has been configured for in-line reception of any out-of-band data (SO_OOBINLINE). If no out-of-band data is waiting to be read, the operation returns TRUE. Otherwise it returns FALSE, and the next recv() or recvfrom() performed on the socket will retrieve some or all of the data preceding the "mark"; the application should use the winsock.SIOCATMARK operation to determine whether any remains. If there is any normal data preceding the "urgent" (out of band) data, it will be received in order. (Note that a recv() or recvfrom() will never mix out-of-band and normal data in the same call.) argp is the ulong variable in which ioctlsocket() stores the result.

Return Value

Upon successful completion, the ioctlsocket() returns 0. Otherwise, a value of winsock.SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINVAL: cmd is not a valid command, or argp is not an acceptable parameter for cmd, or the command is not applicable to the type of socket supplied
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAENOTSOCK: The descriptor is not a socket.

socket.listen()

Description

Tell a socket to listen for incoming connection.

int socket.listen(int backlog )

backlog: The maximum length to which the queue of pending connections may grow.

Remarks

To accept connections, a socket is first created then a backlog for incoming connections is specified with listen(), and then the connections are accepted with accept().listen() applies only to sockets that support connections, i.e. those of type winsock.SOCK_STREAM. The socket is put into ``passive'' mode where incoming connections are acknowledged and queued pending acceptance by the process.

This function is typically used by servers that could have more than one connection request at a time: if a connection request arrives with the queue full, the client will receive an error with an indication of winsock.WSAECONNREFUSED.listen() attempts to continue to function rationally when there are no available descriptors. It will accept connections until the queue is emptied. If descriptors become available, a later call to listen() or accept() will re-fill the queue to the current or most recent ``backlog'', if possible, and resume listening for incoming connections.

Return Value

If no error occurs, listen() returns 0. Otherwise, a value of winsock.SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEADDRINUSE: An attempt has been made to listen() on an address in use.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEFAULT: An invalid argument was given.
winsock.WSAEINVAL: The socket has not been bound with bind() or is already connected.
winsock.WSAEISCONN: The socket is already connected.
winsock.WSAEMFILE: No more file descriptors are available.
winsock.WSAENOBUFS: No buffer space is available.
winsock.WSAENOTSOCK: The descriptor is not a socket.
winsock.WSAEOPNOTSUPP: The referenced socket is not of a type that supports the listen() operation.

socket.recv()

Description

Receive data from a socket.

int socket.recv ( ref blob buf, int len, int flags )

buf: A blob variable which will receive incoming data. Use the PowerScript string() function to convert blobs to strings if you need to receive text over the socket.
len: The length of buf.
flags: Specifies the way in which the call is made.

Remarks

This function is used on connected datagram or stream sockets and is used to read incoming data.

For sockets of type SOCK_STREAM, as much information as is currently available up to the size of the buffer supplied is returned. If the socket has been configured for in-line reception of out-of-band data (socket option SO_OOBINLINE) and out-of-band data is unread, only out-of-band data will be returned. The application may use the ioctlsocket() SIOCATMARK to determine whether any more out-of-band data remains to be read.

For datagram sockets, data is extracted from the first enqueued datagram, up to the size of the size of the string buffer supplied. If the datagram is larger than the buffer supplied, the excess data is lost, and recv() returns the error winsock.WSAEMSGSIZE. If no incoming data is available at the socket, the recv() call waits for data to arrive unless the socket is non-blocking. In this case a value ofwinsock.SOCKET_ERROR is returned with the error code set to winsock.WSAEWOULDBLOCK. The wsselect() or WSAAsyncSelect() calls may be used to determine when more data arrives. If the socket is of type SOCK_STREAM and the remote side has shut down the connection gracefully, a recv() will complete immediately with 0 bytes received. If the connection has been abortively disconnected, a recv()will fail with the error winsock.WSAECONNRESET.

Flags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by or-ing any of the following values:

winsock.MSG_PEEK: Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue.
winsock.MSG_OOB: Process out-of-band data.

Return Value

If no error occurs, recv() returns the number of bytes received. If the connection has been closed, it returns 0. Otherwise, a value of winsock.SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAENOTCONN: The socket is not connected.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAENOTSOCK: The descriptor is not a socket.
winsock.WSAEOPNOTSUPP: MSG_OOB was specified, but the socket is not of type SOCK_STREAM.
winsock.WSAESHUTDOWN: The socket has been shutdown; it is not possible to recv() on a socket after shutdown() has been invoked with how set to 0 or 2.
winsock.WSAEWOULDBLOCK: The socket is marked as non-blocking and the receive operation would block.
winsock.WSAEMSGSIZE: The datagram was too large to fit into the specified buffer and was truncated.
winsock.WSAEINVAL: The socket has not been bound with bind().
winsock.WSAECONNABORTED: The virtual circuit was aborted due to timeout or other failure.
winsock.WSAECONNRESET: The virtual circuit was reset by the remote side.

socket.recvfrom()

Description

Receive a datagram and store the source address.

int socket.recvfrom ( ref blobbuf, int len, int flags, ref ulong from, ref int iPort )

buf: A blob variable which will receive incoming data. Use the PowerScript string() function to convert blobs to strings if you need to receive text over the socket.
len: The length of buf.
flags: Specifies the way in which the call is made.
from: An unsigned long variable which will receive the address of the source of the datagram in network byte order.
iPort: An integer variable which will receive the port number of the source of the datagram.

Remarks

This function is used to read incoming data on a (possibly connected) socket and capture the address from which the data was sent.

For datagram sockets, data is extracted from the first enqueued datagram, up to the size of the size of the string buffer supplied. If the datagram is larger than the buffer supplied, the buffer is filled with the first part of the message, the excess data is lost, and recvfrom() returns the error codewinsock.WSAEMSGSIZE. If the socket is of type SOCK_DGRAM, the network address of the peer which sent the data is copied to the from and iPort variables if no incoming data is available at the socket, the recvfrom() call waits for data to arrive unless the socket is non-blocking. In this case a value of winsock.SOCKET_ERROR is returned with the error code set to winsock.WSAEWOULDBLOCK. The wsselect() or WSAAsyncSelect() calls may be used to determine when more data arrives. If the socket is of type SOCK_STREAM and the remote side has shut down the connection gracefully, a recvfrom() will complete immediately with 0 bytes received. If the connection has been abortively disconnected, arecvfrom() will fail with the error winsock.WSAECONNRESET.

winsock.MSG_PEEK: Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue.
winsock.MSG_OOB: Process out-of-band data.

Return Value

If no error occurs, recvfrom() returns the number of bytes received. If the connection has been closed, it returns 0. Otherwise, a value of winsock.SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEINVAL: The socket has not been bound with bind().
winsock.WSAENOTCONN: The socket is not connected (SOCK_STREAM only).
winsock.WSAENOTSOCK: The descriptor is not a socket.
winsock.WSAEOPNOTSUPP: MSG_OOB was specified, but the socket is not of type SOCK_STREAM.
winsock.WSAESHUTDOWN: The socket has been shutdown; it is not possible to recvfrom() on a socket after shutdown() has been invoked with how set to 0 or 2.
winsock.WSAEWOULDBLOCK: The socket is marked as non-blocking and the recvfrom() operation would block.
winsock.WSAEMSGSIZE: The datagram was too large to fit into the specified buffer and was truncated.
winsock.WSAECONNABORTED: The virtual circuit was aborted due to timeout or other failure.
winsock.WSCONNRESET: The virtual circuit was reset by the remote side.

socket.send()

Description

Send data on a connected socket.

int socket.send ( blob buf, int len, int flags )

buf: A blob containing the data to be transmitted. Use the PowerScript blob() function to convert strings to blobs if you need to send text over the socket.
len: The length of the data in buf.
flags: Specifies the way in which the call is made.

Remarks

send() is used on connected datagram or stream sockets and is used to write outgoing data on a socket. For datagram sockets, care must be taken not to exceed the maximum IP packet size of the underlying subnets, which is given by the iMaxUdpDg element in the WSAData structure attribute of theWinsock User Object. If the data is too long to pass atomically through the underlying protocol the error winsock.WSAEMSGSIZE is returned, and no data is transmitted. Note that the successful completion of a send() does not indicate that the data was successfully delivered.

If no buffer space is available within the transport system to hold the data to be transmitted, send() will block unless the socket has been placed in a non-blocking I/O mode. On non-blocking SOCK_STREAM sockets, the number of bytes written may be between 1 and the requested length, depending on buffer availability on both the local and foreign hosts. The wsselect() call may be used to determine when it is possible to send more data.

winsock.MSG_DONTROUTE: Specifies that the data should not be subject to routing.
winsock.MSG_OOB: Send out-of-band data (SOCK_STREAM only)

Return Value

If no error occurs, send() returns the total number of characters sent. (Note that this may be less than the number indicated bylen.) Otherwise, a value of winsock.SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEACCES: The requested address is a broadcast address, but the appropriate flag was not set.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEFAULT: The buf is not in a valid part of the user address space.
winsock.WSAENETRESET: The connection must be reset because the Windows Sockets implementation dropped it.
winsock.WSAENOBUFS: The Windows Sockets implementation reports a buffer deadlock.
winsock.WSAENOTCONN: The socket is not connected.
winsock.WSAENOTSOCK: The descriptor is not a socket.
winsock.WSAEOPNOTSUPP: MSG_OOB was specified, but the socket is not of type SOCK_STREAM.
winsock.WSAESHUTDOWN: The socket has been shutdown; it is not possible to send() on a socket after shutdown() has been invoked with how set to 1 or 2.
winsock.WSAEWOULDBLOCK: The socket is marked as non-blocking and the requested operation would block.
winsock.WSAEMSGSIZE: The socket is of type SOCK_DGRAM, and the datagram is larger than the maximum supported by the Windows Sockets implementation.
winsock.WSAEINVAL: The socket has not been bound with bind().
winsock.WSAECONNABORTED: The virtual circuit was aborted due to timeout or other failure.
winsock.WSAECONNRESET: The virtual circuit was reset by the remote side.

socket.sendto()

Description

Send data to a specific destination.

int socket.sendto ( blob buf, int len, int flags, ulong to, int iPort )

buf: A blob containing the data to be transmitted. Use the PowerScript blob() function to convert strings to blobs if you need to send text over the socket.
len: The length of the data in buf.
flags: Specifies the way in which the call is made.
to: An unsigned long value representing an IP address in network byte order.
iPort: The port to which data is to be sent.

Remarks

sendto() is used on datagram or stream sockets and is used to write outgoing data on a socket. For datagram sockets, care must be taken not to exceed the maximum IP packet size of the underlying subnets, which is given by the iMaxUdpDg element in the WSAData structure attribute of theWinsock User Object.

If the data is too long to pass atomically through the underlying protocol the error winsock.WSAEMSGSIZE is returned, and no data is transmitted. Note that the successful completion of a sendto() does not indicate that the data was successfully delivered.

sendto() is normally used on a SOCK_DGRAM socket to send a datagram to a specific peer socket identified by the to parameter. On a SOCK_STREAM socket, the to and iPort parameters are ignored; in this case thesendto() is equivalent to send().

To send a broadcast (on a SOCK_DGRAM only), the address in the to parameter should be constructed using the special IP address winsock.INADDR_BROADCAST together with the intended port number. It is generally inadvisable for a broadcast datagram to exceed the size at which fragmentation may occur, which implies that the data portion of the datagram (excluding headers) should not exceed 512 bytes.

If no buffer space is available within the transport system to hold the data to be transmitted, sendto() will block unless the socket has been placed in a non-blocking I/O mode. On non-blocking SOCK_STREAM sockets, the number of bytes written may be between 1 and the requested length, depending on buffer availability on both the local and foreign hosts. The wsselect() call may be used to determine when it is possible to send more data.

winsock.MSG_DONTROUTE: Specifies that the data should not be subject to routing.
winsock.MSG_OOB: Send out-of-band data (SOCK_STREAM only)

Return Value

If no error occurs, sendto() returns the total number of characters sent. (Note that this may be less than the number indicated by len.) Otherwise, a value of winsock.SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEACCES: The requested address is a broadcast address, but the appropriate flag was not set.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEFAULT: The buf or to are not in a valid part of the user address space, or the to argument is too small (less than the sizeof a struct sockaddr).
winsock.WSAENETRESET: The connection must be reset because the Windows Sockets implementation dropped it.
winsock.WSAENOBUFS: The Windows Sockets implementation reports a buffer deadlock.
winsock.WSAENOTCONN: The socket is not connected (SOCK_STREAM only).
winsock.WSAENOTSOCK: The descriptor is not a socket.
winsock.WSAEOPNOTSUPP: MSG_OOB was specified, but the socket is not of type SOCK_STREAM.
winsock.WSAESHUTDOWN: The socket has been shutdown; it is not possible to sendto() on a socket after shutdown() has been invoked with how set to 1 or 2.
winsock.WSAEWOULDBLOCK: The socket is marked as non-blocking and the requested operation would block.
winsock.WSAEMSGSIZE: The socket is of type SOCK_DGRAM, and the datagram is larger than the maximum supported by the Windows Sockets implementation.
winsock.WSAECONNABORTED: The virtual circuit was aborted due to timeout or other failure.
winsock.WSAECONNRESET: The virtual circuit was reset by the remote side.
winsock.WSAEADDRNOTAVAIL: The specified address is not available from the local machine.
winsock.WSAEAFNOSUPPORT: Addresses in the specified family cannot be used with this socket.
winsock.WSAEDESTADDRREQ: A destination address is required.
winsock.WSAENETUNREACH: The network can't be reached from this host at this time.

socket.setsockopt()

Description

Set a socket option.

int socket.setsockopt ( intlevel, int optname, int optvalint, linger optvallinger )

level: The level at which the option is defined; the only supported levels are SOL_SOCKET and IPPROTO_TCP.
optname: The socket option for which the value is to be set.
optvalint: An integer containing the new value for optname if optname requires an integer value.
optvallinger: A linger structure containing the new value for optname if optname requires a linger structure.

Remarks

setsockopt() sets the current value for a socket option associated with a socket of any type, in any state. Although options may exist at multiple protocol levels, this specification only defines options that exist at the uppermost ``socket'' level. Options affect socket operations, such as whether expedited data is received in the normal data stream, whether broadcast messages may be sent on the socket, etc. There are two types of socket options: Boolean options that enable or disable a feature or behavior, and options which require an integer value or structure. To enable a Boolean option, optvalint is a nonzero integer. To disable the option optval is equal to zero.

For options that require an integer value, optvalint is an integer that is the desired value for the option. For options that require a linger structure, optvallinger is a linger structure containing the desired values for the option.

SO_LINGER controls the action taken when unsent data is queued on a socket and a closesocket() is performed. See closesocket() for a description of the way in which the SO_LINGER settings affect the semantics of closesocket(). The application sets the desired behavior by creating a linger structure, which contains the following elements:

	int	l_onoff;
	int	l_linger;

To enable SO_LINGER, the application should set l_onoff to a non-zero value, set l_linger to 0 or the desired timeout (in seconds), and callsetsockopt(). To enable SO_DONTLINGER (i.e. disable SO_LINGER)l_onoff should be set to zero and setsockopt() should be called.

By default, a socket may not be bound (see bind()) to a local address which is already in use. On occasions, however, it may be desirable to "re-use" an address in this way. Since every connection is uniquely identified by the combination of local and remote addresses, there is no problem with having two sockets bound to the same local address as long as the remote addresses are different. To inform the Windows Sockets implementation that a bind() on a socket should not be disallowed because the desired address is already in use by another socket, the application should set the SO_REUSEADDR socket option for the socket before issuing the bind(). Note that the option is interpreted only at the time of the bind(): it is therefore unnecessary (but harmless) to set the option on a socket which is not to be bound to an existing address, and setting or resetting the option after the bind() has no effect on this or any other socket..

An application may request that the Windows Sockets implementation enable the use of "keep-alive" packets on TCP connections by turning on the SO_KEEPALIVE socket option. A Windows Sockets implementation need not support the use of keep-alives: if it does, the precise semantics are implementation-specific but should conform to section 4.2.3.6 of RFC 1122: Requirements for Internet Hosts -- Communication Layers. If a connection is dropped as the result of "keep-alives" the error code WSAENETRESET is returned to any calls in progress on the socket, and any subsequent calls will fail with WSAENOTCONN.

The TCP_NODELAY option disables the Nagle algorithm. The Nagle algorithm is used to reduce the number of small packets sent by a host by buffering unacknowledged send data until a full-size packet can be sent. However, for some applications this algorithm can impede performance, and TCP_NODELAY may be used to turn it off. Application writers should not set TCP_NODELAY unless the impact of doing so is well-understood and desired, since setting TCP_NODELAY can have a significant negative impact of network performance. TCP_NODELAY is the only supported socket option which uses level IPPROTO_TCP; all other options use level SOL_SOCKET.

The following options are supported for setsockopt(). The Type identifies whether the optvalint or optvallinger parameter is used to pass desired values:

Value		Type		Meaning
--------------- ---------------	-----------------------------------------------
SO_BROADCAST	BOOL		Allow transmission of broadcast messages on the
				socket.
SO_DEBUG	BOOL		Record debugging information.  
SO_DONTLINGER	BOOL		Don't block close waiting for unsent data to be
				sent.  Setting this option is equivalent to
				setting SO_LINGER with l_onoff set to
				zero.
SO_DONTROUTE	BOOL		Don't route: send directly to interface.
SO_KEEPALIVE	BOOL		Send keepalives
SO_LINGER	      linger	Linger on close if unsent data is present
SO_OOBINLINE	BOOL		Receive out-of-band data in the normal data
				stream.  
SO_RCVBUF	int		Specify buffer size for receives
SO_REUSEADDR	BOOL		Allow the socket to be bound to an address
				which is already in use.  (See bind().)
SO_SNDBUF	int		Specify buffer size for sends
TCP_NODELAY	BOOL		Disables the Nagle algorithm for send
				coalascing.

Return Value

If no error occurs, setsockopt() returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEFAULT: optval is not in a valid part of the process address space.
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEINVAL: level is not valid, or the information in optval is not valid.
winsock.WSAENETRESET: Connection has timed out when SO_KEEPALIVE is set.
winsock.WSAENOPROTOOPT: The option is unknown or unsupported. In particular, SO_BROADCAST is not supported on sockets of type SOCK_STREAM, while SO_DONTLINGER, SO_KEEPALIVE, SO_LINGER and SO_OOBINLINE are not supported on sockets of type SOCK_DGRAM.
winsock.WSAENOTCONN: Connection has been reset when SO_KEEPALIVE is set.
winsock.WSAENOTSOCK: The descriptor is not a socket.

socket.shutdown()

Description

Disable sends and/or receives on a socket.

int shutdown ( int how )

how: A flag that describes what types of operation will no longer be allowed.

Remarks

shutdown() is used on all types of sockets to disable reception, transmission, or both.

If how is 0, subsequent receives on the socket will be disallowed. This has no effect on the lower protocol layers. For TCP, the TCP window is not changed and incoming data will be accepted (but not acknowledged) until the window is exhausted. For UDP, incoming datagrams are accepted and queued. In no case will an ICMP error packet be generated.

If how is 1, subsequent sends are disallowed. For TCP sockets, a FIN will be sent.

Setting how to 2 disables both sends and receives as described above. Note that shutdown() does not close the socket, and resources attached to the socket will not be freed until closesocket() is invoked.

Comments

shutdown() does not block regardless of the SO_LINGER setting on the socket.

An application should not rely on being able to re-use a socket after it has been shut down. In particular, a Windows Sockets implementation is not required to support the use of wsconnect() on such a socket.

Return Value

If no error occurs, shutdown() returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINVAL: how is not valid.
winsock.WSAEINTR: The (blocking) call was canceled via WSACancelBlockingCall()
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAENOTCONN: The socket is not connected (SOCK_STREAM only).
winsock.WSAENOTSOCK: The descriptor is not a socket.

socket.socket()

Description

Create a socket.

uint socket.socket ( int type )

type: A type specification for the new socket, either winsock.SOCK_STREAM or winsock.SOCK_DGRAM.

Remarks

socket() allocates a socket descriptor of the specified type, as well as related resources. The following type specifications are supported:

winsock.SOCK_STREAM: Provides sequenced, reliable, two-way, connection-based byte streams with an out-of-band data transmission mechanism. Uses TCP for the Internet address family.
winsock.SOCK_DGRAM: Supports datagrams, which are connectionless, unreliable buffers of a fixed (typically small) maximum length. Uses UDP for the Internet address family.

Sockets of type SOCK_STREAM are full-duplex byte streams. A stream socket must be in a connected state before any data may be sent or received on it. A connection to another socket is created with a wsconnect() call. Once connected, data may be transferred using send() and recv() calls. When a session has been completed, a closesocket() must be performed. Out-of-band data may also be transmitted as described in send() and received as described in recv().

The communications protocols used to implement a SOCK_STREAM ensure that data is not lost or duplicated. If data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, the connection is considered broken and subsequent calls will fail with the error code set to WSAETIMEDOUT.

SOCK_DGRAM sockets allow sending and receiving of datagrams to and from arbitrary peers using sendto() and recvfrom(). If such a socket is wsconnect()ed to a specific peer, datagrams may be send to that peer send() and may be received from (only) this peer using recv().

Return Value

If no error occurs, socket() returns an unsigned integer representing the number of the new socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEAFNOSUPPORT: The specified address family is not supported..
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
winsock.WSAEMFILE: No more file descriptors are available.
winsock.WSAENOBUFS: No buffer space is available. The socket cannot be created.
winsock.WSAEPROTONOSUPPORT: The specified protocol is not supported.
winsock.WSAEPROTOTYPE: The specified protocol is the wrong type for this socket.
winsock.WSAESOCKTNOSUPPORT: The specified socket type is not supported in this address family.

socket.WSAAsyncSelect()

Description

Request event notification for a socket.

int socket.WSAAsyncSelect ( uint hWnd, uint wMsg, long lEvent )

hWnd: A handle identifying the window which should receive a message when a network event occurs.
wMsg: The number of the event to trigger in the window referenced by hWnd when an event specified by lEvent occurs.
lEvent: A bitmask which specifies a combination of network events in which the application is interested.

Remarks

This function is used to request that the Windows Sockets DLL should send a message to the window hWnd whenever it detects any of the network events specified by the lEvent parameter. The message which should be sent is specified by the wMsg parameter. The lEvent parameter is constructed by or'ing any of the values specified in the following list using the WSOr() function.

winsock.FD_READ: Want to receive notification of readiness for reading
winsock.FD_WRITE: Want to receive notification of readiness for writing
winsock.FD_OOB: Want to receive notification of the arrival of out-of-band data
winsock.FD_ACCEPT: Want to receive notification of incoming connections
winsock.FD_CONNECT: Want to receive notification of completed connection
winsock.FD_CLOSE: Want to receive notification of socket closure

Issuing a WSAAsyncSelect() for a socket cancels any previousWSAAsyncSelect() for the same socket. For example, to receive notification for both reading and writing, the application must callWSAAsyncSelect() with both FD_READ and FD_WRITE, as follows:

     long lEvents
	int iResult
	uint hWnd
	
	lEvents = ws.WSOr(ws.FD_READ,ws.FD_WRITE)
	
	hWnd = HANDLE(parent)
	
	iResult = ws.WSAAsyncSelect(hWnd, 1024, lEvents)

It is not possible to specify different messages for different events. The second call will cancel the effects of the first.

To cancel all notification -- i.e., to indicate that the Windows Sockets implementation should send no further messages related to network events on the socket -- lEvent should be set to zero.

Although in this instance WSAAsyncSelect() immediately disables event message posting for the socket, it is possible that messages may be waiting in the application's message queue. The application must therefore be prepared to receive network event messages even after cancellation. Closing a socket with closesocket() also cancels WSAAsyncSelect() message sending, but the same caveat about messages in the queue prior to the closesocket() still applies.

Since an accept()'ed socket has the same properties as the listening socket used to accept it, anyWSAAsyncSelect() events set for the listening socket apply to the accepted socket. For example, if a listening socket has WSAAsyncSelect()events FD_ACCEPT, FD_READ, and FD_WRITE, then any socket accepted on that listening socket will also have FD_ACCEPT, FD_READ, and FD_WRITE events with the same wMsg value used for messages. If a different wMsg or events are desired, the application should call WSAAsyncSelect(), passing the accepted socket and the desired new information.

[Note: There is a timing window between the accept() call and the call to WSAAsyncSelect() to change the events orwMsg. An application which desires a different wMsg for the listening and accept()'ed sockets should ask for only FD_ACCEPT events on the listening socket, then set appropriate events after the accept(). Since FD_ACCEPT is never sent for a connected socket and FD_READ, FD_WRITE, FD_OOB, and FD_CLOSE are never sent for listening sockets, this will not impose difficulties.]

When one of the nominated network events occurs on the specified sockets, the application's window hWnd receives message wMsg. The WordParm attribute of the PowerBuilder message system object identifies, by number, the socket on which a network event has occurred. The low 16 bits of the message object's LongParm attribute specifies the network event that has occurred. The high 16 bits of LongParm contain any error code.

The error and event codes may be extracted from LongParm using theWSAGetSelectError() and WSAGetSelectEvent() functions.

The possible network event codes which may be returned are as follows:

winsock.FD_READ: Socket message.WordParm is ready for reading
winsock.FD_WRITE: Socket message.WordParm is ready for writing
winsock.FD_OOB: Out-of-band data ready for reading on socket message.WordParm.
winsock.FD_ACCEPT: Socket message.WordParm is ready for accepting a new incoming connection
winsock.FD_CONNECT: Connection on socket message.WordParm completed
winsock.FD_CLOSE: Connection identified by socket message.WordParm has been closed

Return Value

The return value is 0 if the application's declaration of interest in the network event set was successful. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().

Comments

Although WSAAsyncSelect() can be called with interest in multiple events, the application window will receive a single message for each network event. As in the case of the wsselect() function, WSAAsyncSelect() will frequently be used to determine when a data transfer operation (send() or recv()) can be issued with the expectation of immediate success. Nevertheless, a robust application must be prepared for the possibility that it may receive a message and issue a Windows Sockets API call which returns WSAEWOULDBLOCK immediately. For example, the following sequence of events is possible:

data arrives on socket; Windows Sockets postsWSAAsyncSelect message
application processes some other message
while processing, application issues anioctlsocket(ws.FIONREAD...) and notices that there is data ready to be read
application issues a recv() to read the data
application loops to process next message, eventually reaching theWSAAsyncSelect message indicating that data is ready to read
application issues recv(), which fails with the error WSAEWOULDBLOCK.

Other sequences are possible.

The Windows Sockets DLL will not continually flood an application with messages for a particular network event. Having successfully posted notification of a particular event to an application window, no further message(s) for that network event will be posted to the application window until the application makes the function call which implicitly re-enables notification of that network event.

winsock.FD_READ: recv() or recvfrom()
winsock.FD_WRITE: send() or sendto()
winsock.FD_OOB: recv()
winsock.FD_ACCEPT: accept()
winsock.FD_CONNECT: NONE
winsock.FD_CLOSE: NONE

Any call to the reenabling routine, even one which fails, results in reenabling of message posting for the relevent event.

For FD_READ, FD_OOB, and FD_ACCEPT events, message posting is "level-triggerred." This means that if the reenabling routine is called and the relevent event is still valid after the call, a WSAAsyncSelect()message is posted to the application. This allows an application to be event-driven and not concern itself with the amount of data that arrives at any one time. Consider the following sequence:

Windows Sockets DLL receives 100 bytes of data on a socket and posts an FD_READ message.
The application issues recv(buf,50,0) to read 50 bytes.
The Windows Sockets DLL posts another FD_READ message since there is still data to be read.

With these semantics, an application need not read all available data in response to an FD_READ message--a single recv() in response to each FD_READ message is appropriate. If an application issues multiple recv() calls in response to a single FD_READ, it may receive multiple FD_READ messages. Such an application may wish to disable FD_READ messages before starting the recv() calls by calling WSAAsyncSelect() with the FD_READ event not set.

If an event is true when the application initially callsWSAAsyncSelect() or when the reenabling function is called, then a message is posted as appropriate. For example, if an application calls listen(), a connect attempt is made, then the application calls WSAAsyncSelect()specifying that it wants to receive FD_ACCEPT messages for the socket, the Windows Sockets implementation posts an FD_ACCEPT message immediately.

The FD_WRITE event is handled slightly differently. An FD_WRITE message is posted when a socket is first connected with wsconnect() or accepted with accept(), and then after a send() or sendto() fails with WSAEWOULDBLOCK and buffer space becomes available. Therefore, an application can assume that sends are possible starting from the first FD_WRITE message and lasting until a send returns WSAEWOULDBLOCK. After such a failure the application will be notified that sends are again possible with an FD_WRITE message.

The FD_OOB event is used only when a socket is configured to receive out-of-band data separately. If the socket is configured to receive out-of-band data in-line, the out-of-band (expedited) data is treated as normal data and the application should register an interest in, and will receive, FD_READ events, not FD_OOB events. An application may set or inspect the way in which out-of-band data is to be handled by using setsockopt() or getsockopt for the SO_OOBINLINE option.

The error code in an FD_CLOSE message indicates whether the socket close was graceful or abortive. If the error code is 0, then the close was graceful; if the error code is WSAECONNRESET, then the socket's virtual socket was abortively disconnected. This only applies to sockets of type SOCK_STREAM.

The FD_CLOSE message is posted when a close indication is received for the virtual circuit corresponding to the socket. In TCP terms, this means that the FD_CLOSE is posted when the connection goes into the FIN WAIT or CLOSE WAIT states. This results from the remote end performing a shutdown() on the send side or a closesocket().

Please note your application will receive ONLY an FD_CLOSE message to indicate closure of a virtual circuit. It will NOT receive an FD_READ message to indicate this condition.

Error Codes

winsock.WSANOTINITIALISED: A successful WSAStartup() must occur before using this API.
winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAEINVAL: Indicates that one of the specified parameters was invalid
winsock.WSAEINPROGRESS: A blocking Windows Sockets operation is in progress.
Additional error codes may be set when an application window receives a message. This error code is extracted from the LongParm attribute of the message system object using the WSAGetSelectError() function. Possible error codes for each network event are:

Event: FD_CONNECT

Error Codes

winsock.WSAEADDRINUSE: The specified address is already in use.
winsock.WSAEADDRNOTAVAIL: The specified address is not available from the local machine.
winsock.WSAEAFNOSUPPORT: Addresses in the specified family cannot be used with this socket.
winsock.cWSAECONNREFUSED: The attempt to connect was forcefully rejected.
winsock.WSAEDESTADDRREQ: A destination address is required.
winsock.WSAEINVAL: The socket is already bound to an address.
winsock.WSAEISCONN: The socket is already connected.
winsock.WSAEMFILE: No more file descriptors are available.
winsock.WSAENETUNREACH: The network can't be reached from this host at this time.
winsock.WSAENOBUFS: No buffer space is available. The socket cannot be connected.
winsock.WSAENOTCONN: The socket is not connected.
winsock.WSAENOTSOCK: The descriptor is a file, not a socket.
winsock.WSAETIMEDOUT: Attempt to connect timed out without establishing a connection

Event: FD_CLOSE

Error Codes

winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.
winsock.WSAECONNRESET: The connection is reset by the remote side.
winsock.WSAECONNABORTED: The connection was aborted due to timeout or other failure.

Event: FD_READ
Event: FD_WRITE
Event: FD_OOB
Event: FD_ACCEPT

Error Code

winsock.WSAENETDOWN: The Windows Sockets implementation has detected that the network subsystem has failed.

socket.GetSocketNumber()

Description

Get the socket number (also known as the socket descriptor or socket handle) for a socket object.

uint socket.GetSocketNumber ( )

Remarks

This function is used to obtain the socket number for a socket object.

Return Value

Returns an unsigned integer representing the socket number for the socket object.

The PowerSocket Library

Network Programming using PowerBuilderand Winsock Version 1.1

PowerSocket Version 2.1 - January 8, 1999

Table of Contents

You can now license and download the PowerSocket Library source code!

Copyright (c) 1995, 1996, 1997, 1998, 1999 by Jason Coombs and Ted Coombs

All rights reserved.

Description

Remarks

Return Value

Error Codes

See Also

Description

Remarks

Return Value

Error Codes

See Also

Description

Remarks

Return Value

See Also

Description

Remarks

Return Value

See Also

Description

Remarks

Return Value

See Also

Description

Remarks

Return Value

See Also

Description

Remarks

Return Value

See Also

Description

Remarks

Return Value

See Also

Description

Remarks

Return Value

Error Codes

See Also

Description

Remarks

Return Value

Error Codes

See Also

Description

Remarks

Return Value

Error Codes

See Also

Description

Remarks

Return Value

Error Codes

See Also

Description

Remarks

Return Value

Error Codes

See Also

Description

Remarks

Return Value

Error Codes

See Also

Description

Remarks

Return Value

Error Codes

Description

Remarks

Return Value

Error Codes

See Also

Network Programming using PowerBuilder
and Winsock Version 1.1