{INCLUDE _LOGOS.HTM}

PicLan-IP Sockets API

PicLan-IP version 2.0.0 (build 111)
February 14, 1997

The PicLan-IP TCP Sockets API (Application Programming Interface) is designed to allow applications programs to directly communicate with external hosts over TCP/IP stream-based connections as well as via UDP datagrams. With the current release of this API, only client appliations are supported:

Overview

The general proceedure is for an application to: It is very important that your application return resources that are allocated to TCP/IP network connections when they exit.  To assist you in insuring that resources are returned, you can call PLX.TCP.CLEANUP(...) which will call PLX.TCP.RESET(...) for all allocated connections that have not been previously closed for a particular port.  You should always call PLX.TCP.CLEANUP(...) at the beginning and end of every application that uses the PicLan-IP socket API.

Subroutines

All of these functions are implemented as mv/BASIC subroutines and are CALLed from within your mv/BASIC application code.  The subroutines are defined and cataloged in the PICLAN-IP account. In order to use these subroutines from your application you must follow these proceedures: To ease the process of setting up q-pointers and cataloging subroutines, you can copy the contents of the NEWAC file in the PICLAN-IP account into the master dictionary of your application account.

These subroutines are designed to not use any mv/BASIC common and should be compatible with most application programs without difficulty.

Function Groups

General Utility Cleanup
TCP Stream Open
Read
Write
Send Close
Status
Reset
DNS Query Get Host Address
Application Protocol HTTP

General Utility Functions

These functions are general purpose functions that help to manage PicLan-IP sockets API resources.

PLX.CLEANUP( )

This function will release any resources that are currently allocated on a port by port basis.  You should call this function at the beginning of every program that uses the PicLan-IP sockets API and again just before the exit of every program that uses the PicLan-IP sockets API.

This function will close any open TCP/IP connections and release any socket resources for connections that were allocated by the current port.

TCP Stream Functions

These functions are used to open, read, write, and close TCP stream connections.
notes:  It is allowable to open steam connections to the current host. You may also use these functions from within PicLan-IP web applications, but be careful to allocate multiple PicLan-IP server processes to prevent deadlocks.

PLX.TCP.OPEN(IPAddr,TCPPort,Handle,Error)

Open a new TCP connection.
IPAddr The IP address of the remote host.
TcpPort The TCP port number on the remote host.
Handle The handle of a TCP socket allocated for the connection.
Error An error string or null if no error has occurred.
This function will allocate resources associated with a connection. You must call PLX.TCP.RESET(...) or PLX.TCP.CLEANUP(...) to release these resources.

PLX.TCP.READ(Handle,Options,MaxLen,MaxTime,Data,Status,Error)

Read data from an open TCP connection.
Handle The TCP socket handle returned from PLX.TCP.OPEN(...).
Options X - read data in hex.
MaxLen The maximum number of bytes to read.
MaxTime The number of seconds to wait for data.  0 seconds indicates a return immediately with only buffered data.
Data The data that has been read.
Status CLOSED - The connection has been closed from the other end.
Error An error string or null if no error has occurred. If there is an error the handle is automatically deallocated.

PLX.TCP.WRITE(Handle,Options,MaxTime,Data,Error)

Write data to an open TCP connection.
Handle The TCP socket handle returned from PLX.TCP.OPEN(...).
Options X - write data in hex.
MaxTime The maximum amount of time to wait trying to write the data.
Data The data to write.  On return, this variable will contain any residual data that was not written in the MaxTime period.
Error An error string or null if no error has occurred. If there is an error the handle is automatically deallocated.

PLX.TCP.WRITE.FIN(Handle,Error)

Send a FIN packet closing a TCP connection.
Handle The TCP socket handle returned from PLX.TCP.OPEN(...).
Error An error string or null if no error has occurred. If there is an error the handle is automatically deallocated.
You will still need to call PLX.TCP.RESET(...) or PLX.CLEANUP(...) to actually delete the resources associated with the TCP connection.

PLX.TCP.STATUS(Handle,State,Error)

Get the status of a connection.
Handle The TCP socket handle returned from PLX.TCP.OPEN(...).
State The TCP state number for the connection.
TCP
State		 State
Description		 Notes
1 Closed The connection is closed
2 Listen The connection is waiting for an inbound connection
3 Syn Sent Connection is opening
4 Syn Received Connection is opening
5 Established Normal state for an open connection
6 Fin Wait 1 A close has been sent
7 Fin Wait 2 A close has been sent
8 Closed Wait A close has been received
9 Last Ack A close has been sent and received
10 Closing A close has been sent and received
11 Time Wait A close has been sent and received
Native PicLan-IP systems can return any of the above status codes. PicLan-IP systems running on Windows NT or Unix hosts may not be able to return all possible TCP/IP state codes because of underlying WinSock or Sockets limitations.  You should design your application to be "permissive" of returned states wherever possible.

For a more complete description of TCP/IP connection states, you should refer to TCP/IP RFC documentation or texts such as Internetworking with TCP/IP - Volume I, Douglas E. Comer.
Error An error string or null if no error has occurred. If there is an error the handle is automatically deallocated.

PLX.TCP.RESET(Handle)

Hard close a TCP connection and deallocate the associated handle.
Handle The TCP socket handle returned from PLX.TCP.OPEN(...).

DNS Query Functions

These functions are available to query the default Domain Name Server(s). In general, these functions are used to convert host names into IP addresses.

PicLan caches DNS queries according to the TTL (Time To Live) values supplied in DNS responses.  These cached entries are used to service DNS queries without waiting for network responses whenever possible. If you wish to clear the DNS cache, execute:

PLX.DNS.GET.HOST.ADDR(HostName,IPAddr,Error)

Resolve an IP addresse from a domain name.  This function uses the PicLan-IP internal DNS name table cache file and will make DNS queries as required.
HostName The DNS name of the host to resolve.
IPAdd The result IP address in decimal format.
Error An error string or null if no error has occurred.

Application Protocol Functions

These functions are implemented using the lower-level API calls to implement useful high-level internet functions

PLX.HTTP(URL,Options,Data,Error)

Query a web site with a GET method.
URL The URL of the web page to retrieve.
Options V - verbose, print messages showing progress
Data The resulting web page as a Pick text variable.  Lines are delimited with Pick attribute marks.
Error An error string or null if no error has occurred.
A sample application that calls PLX.HTTP is included with source in PLIP.BP PLIP-HTTP.

{INCLUDE _GEN_FTR.HTM}