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:
-
Create a TCP connection to a destination host with PLX.TCP.OPEN(...)
-
Converse over the connection with:
-
PLX.TCP.READ(...)
-
PLX.TCP.WRITE(...)
-
PLX.TCP.STATUS(...)
-
You may read and write data in either ASCII or HEX. Reading and writing
in hex allows mv/BASIC application to manipulate binary data without encountering
segment mark compatibility issues.
-
Optionally close the connection with PLX.TCP.WRITE.FIN(...)
-
Deallocate resources associated with the connection with PLX.TCP.RESET(...)
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:
-
Compile your mv/BASIC code with PRECISION 4
-
Catalog all program files in PLIP.BP
-
Have access to the following account files:
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 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:
CLEAR-FILE DATA PLIP.CTRL,DNS.CACHE
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.
© Copyright 1996-1998 Modular Software
Corporation.All rights Reserved.
