@DATABASE TCP Commands

@NODE Main "GUI Extension TCP Commands"

                                   @{b}GUI Extension@{ub}

                                   @{u}TCP Commands@{uu}
                                     @{u}04/04/98@{uu}

                                  @{" Introduction " LINK "Introduction"}
                                  @{"   Commands   " LINK "Commands"}
@ENDNODE

@NODE "Introduction"
@NEXT "Commands"
@PREV "Main"
@TOC "Main"
                                  !!!
                                  o o
                  +-----------oOO-(_)-OOo----------------+
                  |                                      |
                  |  Pietro Ghizzoni - Dairymen Soft     |
                  |     E-Mail:  ghizzo@agonet.it        |
                  |            Team AMIGA                |
                  |                                      |
                  | Amos Professional Team Coordinator   |
                  |                                      |
                  +--------------------------------------+

This document was created by Giark (C. Edward Stewart) after examining the
TCP example programs and email response from Pietro Ghizzoni.

These docs cover version 1.70.
@ENDNODE

@NODE "Commands"
@NEXT "Tcp Address"
@PREV "Introduction"
@TOC "Main"

                               @{u}The TCP Command List@{uu}

@{" =Tcp Address*       " LINK "Tcp Address"}
@{" =Tcp Buffer         " LINK "Tcp Buffer"}
@{" =Tcp Channel        " LINK "Tcp Channel"}
@{" =Tcp Check          " LINK "Tcp Check"}
@{" Tcp Close           " LINK "Tcp Close"}
@{" =Tcp Close A        " LINK "Tcp Close"}
@{" =Tcp Code           " LINK "Tcp Code"}
@{" =Tcp Count          " LINK "Tcp Count"}
@{" =Tcp Error          " LINK "Tcp Error"}
@{" =Tcp F Open(A,B$,C) " LINK "Tcp F Open"}
@{" =Tcp Free(A)*       " LINK "Tcp Free"}
@{" =Tcp Get(A,B,C)     " LINK "Tcp Get"}
@{" Tcp Limit A         " LINK "Tcp Limit"}
@{" =Tcp Line$(A)       " LINK "Tcp Line$"}
@{" =Tcp Open(A,B$)     " LINK "Tcp Open"}
@{" =Tcp Packet         " LINK "Tcp Packet"}
@{" =Tcp Put(A,B,C)     " LINK "Tcp Put"}
@{" =Tcp Put$(A,B$)     " LINK "Tcp Put$"}
@{" =Tcp Read(A,B,C,D)  " LINK "Tcp Read"}
@{" =Tcp Remove A*      " LINK "Tcp Remove"}
@{" Tcp Reset           " LINK "Tcp Reset"}
@{" =Tcp Response*      " LINK "Tcp Response"}
@{" =Tcp Send(A,B,C,D)  " LINK "Tcp Send"}
@{" =Tcp Send$(A,B$,C)  " LINK "Tcp Send$"}
@{" Tcp Set A,B*        " LINK "Tcp Set"}
@{" =Tcp Signal(A,B,C)* " LINK "Tcp Signal"}
@{" =Tcp Time           " LINK "Tcp Time"}
@{" Tcp Trash           " LINK "Tcp Trash"}
@{" =Tcp Type           " LINK "Tcp Type"}
@{" =Tcp User*          " LINK "Tcp Remove"}

* - these commands are new and have not been fully documented yet. Use them at
    your own risk.
@ENDNODE

@NODE "Tcp Address"
@NEXT "Tcp Buffer"
@PREV "Commands"
@TOC "Main"
=Tcp Address
@ENDNODE

@NODE "Tcp Buffer"
@NEXT "Tcp Channel"
@PREV "Tcp Address"
@TOC "Main"
=Tcp Buffer

Returns the buffer address associated with the TCP/IP message returned by
Gui Wait.

e.g if you receive the result of a read request Tcp Buffer is the address
where the data is stored.
@ENDNODE

@NODE "Tcp Channel"
@NEXT "Tcp Check"
@PREV "Tcp Buffer"
@TOC "Main"
=Tcp Channel

Returns the channel number associated with the TCP/IP message returned by
Gui Wait
@ENDNODE

@NODE "Tcp Check"
@NEXT "Tcp Close"
@PREV "Tcp Channel"
@TOC "Main"
=Tcp Check

Check to see if there is data waiting to be read. Returns True (-1) or
False (0).
@ENDNODE

@NODE "Tcp Close"
@NEXT "Tcp Code"
@PREV "Tcp Check"
@TOC "Main"
Tcp Close

Close all open TCP connections

Tcp Close <logical file number>

Close <logical file number> TCP connection
@ENDNODE

@NODE "Tcp Code"
@NEXT "Tcp Count"
@PREV "Tcp Close"
@TOC "Main"
=Tcp Code

When you receive a TCP/IP message (Gui Wait returns -9) you can obtain the
associated code

e.g. if you receive the result of a read request, Tcp Code returns the number
of bytes received. If it's a write request, Tcp Code returns the number of
bytes transferred.
@ENDNODE

@NODE "Tcp Count"
@NEXT "Tcp Error"
@PREV "Tcp Code"
@TOC "Main"
=Tcp Count

This function returns the number of asynchronous requests sent to the
device that are waiting for responses.
@ENDNODE

@NODE "Tcp Error"
@NEXT "Tcp F Open"
@PREV "Tcp Count"
@TOC "Main"
=Tcp Error

This function returns the DOS error code of the last error. When @{"Tcp Code" LINK "Tcp Code"}
equals -1 there has been a transfer error.
@ENDNODE

@NODE "Tcp F Open"
@NEXT "Tcp Free"
@PREV "Tcp Error"
@TOC "Main"
=Tcp F Open(<logical file number>,<path$>)

Open a file to write your incoming TCP data to.

e.g. X=Tcp F Open(2,"RAM:IRC.log")
@ENDNODE

@NODE "Tcp Free"
@NEXT "Tcp Get"
@PREV "Tcp F Open"
@TOC "Main"
=Tcp Free()
@ENDNODE

@NODE "Tcp Get"
@NEXT "Tcp Limit"
@PREV "Tcp Free"
@TOC "Main"
=Tcp Get(<logical file number>,<buffer>,<size>)

This function works the same way as @{"Tcp Read" LINK "Tcp Read"} only, like @{"Tcp Put" LINK "Tcp Put"}, the
command is @{I}synchronous@{UI}. The program will halt and wait for a
message to come from the TCP connection.

This command can be set to time out by using the @{"Tcp Limit" LINK "Tcp Limit"} command.

The function returns the number of bytes read.
@ENDNODE

@NODE "Tcp Limit"
@NEXT "Tcp Line$"
@PREV "Tcp Get"
@TOC "Main"
Tcp Limit <value>

Set a timeout period for @{"Tcp Get" LINK "Tcp Get"} and @{"Tcp Get$" LINK "Tcp Get$"} commands. If there is no data
available after the specified value (the value must be set as a Wait
command would be, in jiffies (50=1 Second (PAL) 60=1 Second (NTSC))), the
@{"Tcp Get" LINK "Tcp Get"} command will exit and return -1.
@ENDNODE

@NODE "Tcp Line$"
@NEXT "Tcp Open"
@PREV "Tcp Limit"
@TOC "Main"
=Tcp Line$(<logical file number>)

Reads a line of text from the specified channel. As with @{"Tcp Get" LINK "Tcp Get"}, you can
specify the timeout period using @{"Tcp Limit" LINK "Tcp Limit"}.
@ENDNODE

@NODE "Tcp Open"
@NEXT "Tcp Packet"
@PREV "Line$"
@TOC "Main"
=Tcp Open(<logical file number>,<port data$>)

Open a TCP channel using the port data

e.g. X=Tcp Open(1,"timequake.unterlab.org/6667") to open a port to IRC
@ENDNODE

@NODE "Tcp Packet"
@NEXT "Tcp Put"
@PREV "Tcp Open"
@TOC "Main"
=Tcp Packet

Returns the Packet ID of the last TCP/IP message received.

e.g.

A=Tcp Read(1,Start(10),100)
B=Tcp Send(2,Start(11),100)
C=Tcp Send(3,Start(12),100)
D=Gui Wait
IF D=-9 : Rem TCP/IP message received.
 PKT=Tcp Packet
 If PKT=A : Rem received the answer to A request
 Else If PKT=B : Rem received the answer to B request
 Else If PKT=C : Rem received the answer to C request
Endif
@ENDNODE

@NODE "Tcp Put"
@NEXT "Tcp Put$"
@PREV "Tcp Packet"
@TOC "Main"
=Tcp Put(<logical file number>,<buffer>,<size>)

This command works the same way as @{"Tcp Send" LINK "Tcp Send"}. The difference is that Tcp Put
is a @{I}synchronous@{UI} command. The program will halt until the data is
sent. This means you don't have to monitor the number of bytes sent, etc.
yourself.

The function returns the number of bytes sent.
@ENDNODE

@NODE "Tcp Put$"
@NEXT "Tcp Read"
@PREV "Tcp Put"
@TOC "Main"
=Tcp Put$(<logical file number>,<string$>)

Send a string to the TCP port

e.g. X=Tcp Put$(1,"NICK Giark")

This command works the same way as @{"Tcp Send$" LINK "Tcp Send$"}. The difference is that Tcp
Put$ is a @{I}synchronous@{UI} command. The program will halt until the data
is sent. This means you don't have to monitor the number of bytes sent, etc.
yourself.

The function returns the number of bytes sent.
@ENDNODE

@NODE "Tcp Read"
@NEXT "Tcp Remove"
@PREV "Tcp Put$"
@TOC "Main"
=Tcp Read(<logical file number>,<buffer>,<size>)

Get <size> bytes from the channel, and put them into the <buffer>, a
previously defined AMOS bank.

e.g  S=Start(10) : X=Tcp Read(1,S,100)

Using the bank as a buffer allows the command to run asynchronously. The
command doesn't wait for data to become available, it just sends a request
to the channel. When there is data to be read, Gui Wait will inform you.

A very simple example:

S=Start(10)
A=Tcp Read(1,S,100)
B=Gui Wait
If B=-9 : Rem TCP/IP message received
 D=Tcp Code : Rem D=number of bytes received
 B=Tcp Buffer : Rem B=address of the buffer where the data is stored
EndIf

The function returns the Packet ID.
@ENDNODE

@NODE "Tcp Remove"
@NEXT "Tcp Reset"
@PREV "Tcp Read"
@TOC "Main"
Tcp Remove A

@ENDNODE

@NODE "Tcp Reset"
@NEXT "Tcp Response"
@PREV "Tcp Remove"
@TOC "Main"
Tcp Reset

Resets the TCP internal timer. After using @{"Tcp Time" LINK "Tcp Time"} you can read the amount
of time elapsed since the last Tcp Reset.
@ENDNODE

@NODE "Tcp Response"
@NEXT "Tcp Send"
@PREV "Tcp Reset"
@TOC "Main"
=Tcp Response

@ENDNODE

@NODE "Tcp Send"
@NEXT "Tcp Send$"
@PREV "Tcp Response"
@TOC "Main"
=Tcp Send(<logical file number>,<buffer>,<code>)

Send the specified number of bytes, starting from <buffer>, to the channel.
Like @{"Tcp Read" LINK "Tcp Read"}, this command is asynchronous. The command doesn't wait for the
end of the transfer, but quits immediately so your program can continue its
work. When the transfer is complete, you will receive a TCP/IP message. See
the @{"above" LINK "Tcp Read"} example.

e.g. X=Tcp Send(1,S,125)

The function returns the Packet ID.
@ENDNODE

@NODE "Tcp Send$"
@NEXT "Tcp Set"
@PREV "Tcp Send"
@TOC "Main"
=Tcp Send$(<logical file number>,<string$>)

Send <string$> to the specified <logical file number>

The function returns the Packet ID.
@ENDNODE

@NODE "Tcp Set"
@NEXT "Tcp Signal"
@PREV "Tcp Send$"
@TOC "Main"
Tcp Set
@ENDNODE

@NODE "Tcp Signal"
@NEXT "Tcp Time"
@PREV "Tcp Set"
@TOC "Main"
=Tcp Signal(A,B)

@ENDNODE

@NODE "Tcp Time"
@NEXT "Tcp Trash"
@PREV "Tcp Signal"
@TOC "Main"
=Tcp Time

Returns the amount of time elapsed since the last @{"Tcp Reset" LINK "Tcp Reset"}.
@ENDNODE

@NODE "Tcp Trash"
@NEXT "Tcp Type"
@PREV "Tcp Time"
@TOC "Main"
Tcp Trash

Clear @{B}all@{UB} messages from the TCP/IP port. Take care when using this command.
@ENDNODE

@NODE "Tcp Type"
@NEXT "Tcp User"
@PREV "Tcp Trash"
@TOC "Main"
=Tcp Type

Returns the type of TCP/IP message received.

87 (Asc("R")) - Received an answer to a read request
98 (Asc("W")) - Received an answer to a send request
@ENDNODE

@NODE "Tcp User"
@PREV "Tcp Type"
@TOC "Main"
Tcp User
@ENDNODE