Copyright: Copyright Aldea Interactive 1996-1997. All rights reserved.


AGCtrl : Introduction

The purpose of this manual is to provide you all the information about the ActiveX control called AGCtrl. You will find the documentation of all the methods, properties and events of this control.

AGCtrl allows any 32-bit Windows application to be a client of an Active Gateway Server. Once inserted in a Visual Basic form, a Lotus Notes document or even a Microsoft Excel spreadsheet, AGCtrl is able to exchange data with any other Active Gateway client.

Frame Management

AGCtrl owns a frame called the main frame. In this frame you can set or get data you want to exchange with other Active Gateway peers.

To use this frame, there are several frame management functions. Like any other frame, you can add to main frame, slots of any type such as strings, numbers and also frames or arrays.

To handle most of the frame management tasks you will use:

•	AGCtrl::SetSlotValue
This function allows you to set the value of a slot in the main frame. You’ll be able to create subframes, add slots to them and send them to other Active Gateway peers.

•	AGCtrl::GetSlotValue
This function allows you to get the value of a slot in the main frame. You’ll be able to read the content of the frame you will receive from your peers.

Communications Management

Managing communications with AGCtrl is very easy. The four basic functions are:

•	AGCtrl::Open to open a connection

•	AGCtrl::Close to close a connection

•	AGCtrl::Get to receive a frame

•	AGCtrl::Send to send a frame

The following sample (written in Visual Basic) shows a very simple use of the control. The purpose is to ask the current time of the machine which runs an Active Gateway Server.

Dim nError As Integer
Dim vValue As VARIANT
nError = AGCtrl1.Open("MySelf", "www.aldea-interactive.com", "AGTime:Aldea", 0, 10000)
nError = AGCtrl1.SetSlotValue("QUESION.REQUEST","TIME")
nError = AGCtrl1.Send("QUESTION")	' Send the frame stored in the slot called "QUESTION"
nError = AGCtrl1.Get("RESPONSE")	' Receive the response frame and store it in the
 	' slot called "RESPONSE"
vValue = AGCtrl1.GetSlotValue("RESPONSE.TIME")
nError = AGCtrl1.Close()

In this example, the control:

1.	opens a connection to the AGTime extension (whose ID is "AGTime:Aldea") via the Server "www.aldea-interactive.com" registering itself to the Server by the ID "MySelf".

1.	creates the "REQUEST" slot in the "QUESTION" subframe and set its value ("TIME").

2.	sends the "QUESTION" subframe.

3.	receives the response frame sent by the extension and places it into the slot called "RESPONSE".

4.	sets the value of vValue with the content of the "TIME" slot of the "RESPONSE" subframe.

1.	closes the connection.

Please note that the value of nError is never tested in order to simplify this example. In a real application, you should always test the return values and handle any failure (e.g. if the server is not reachable).


AGCtrl : Members
Members of AGCtrl

Connect / Disconnect

AGCtrl::Close
AGCtrl::Open

Sending / Receiving of data

AGCtrl::Get
AGCtrl::GetFrom
AGCtrl::Send
AGCtrl::SendTo

Manage frames

AGCtrl::AddArraySlot
AGCtrl::DumpFrame
AGCtrl::GetFileFromSlot
AGCtrl::GetSlotValue
AGCtrl::HasSlot
AGCtrl::Is<type>
AGCtrl::Length
AGCtrl::PutFileIntoSlot
AGCtrl::RemoveSlot
AGCtrl::Reset
AGCtrl::SetLength
AGCtrl::SetSlotEmptyArray
AGCtrl::SetSlotEmptyFrame
AGCtrl::SetSlotNil
AGCtrl::SetSlotTrue
AGCtrl::SetSlotValue

Miscellaneous

AGCtrl::AldeaErrorToString
AGCtrl::GetHostAddress
AGCtrl::GetHostName
AGCtrl::GetPeer
AGCtrl::IsOpen
AGCtrl::KillTimer
AGCtrl::Ping
AGCtrl::SetPeer
AGCtrl::SetTimeout
AGCtrl::SetTimer

Properties

AGCtrl::PortName

Event

AGCtrl::Timer


AGCtrl::AddArraySlot

Adding an element in an array

long AGCtrl::AddArraySlot(BSTR sPath, VARIANT vValue)

Parameters

sPath	Access path to a slot of the array. Names of slots must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows you to separate slots. The apostrophe (') and space are prohibited. This parameter is not case sensitive.

vValue	Value of the new element.

Return Value

Error code of type AldeaError.

aeNoError (= 0)	If the slot is really an array and if the element was really added.

aePathError	If the slot specified by sPath does not exist, if it is not of type array, or if an error occurred when adding the slot.

Description

This allows you to add an element at the end of an array. For example, if the array contains 5 elements, the new element is added in the 6th position.The slot specified by sPath must be an array, otherwise AddArraySlot returns the aePathError error. The added value vValue must be a VARIANT of one of the types supported by Active Gateway: boolean, string, symbol (string beginning by (')), byte, long integer (long), short integer (short), simple precision floating-point number (float), double precision floating-point number (double), date.

Example

Dim nError As Integer
' adding a slot in array "An_Array" whose value is a string "New Element"
nError = AGCtrl1.AddArraySlot("An_Array", "New Element")

if the array had a first element, the results is the following frame :
{ frame at 0xx
An_Array: [ array at 0xx
0 : 456,
1 : "New Element",
   ],
}

See also

AGCtrl::Length, AGCtrl::SetLength


AGCtrl::AldeaErrorToString

Retrieving a string associated to the error of type AldeaError

VARIANT AGCtrl::AldeaErrorToString(long nError)

Parameters

nError	The value of the error

Return Value

VARIANT string associated to the error.

Description

This allows you to convert an AldeaError error code in a string representing the type of error.

Warning

This function is an aid to applications development using AGCtrl. Its return values are not  representative for the final user.

Example

Dim nError As Integer
Dim vError As Variant
nError = AGCtrl1.Open(...)
' if nError = 0, vError would contain the string "aeNoError"
vError = AGCtrl1.AldeaErrorToString(nError)


AGCtrl::Close

Closing the current connection

long AGCtrl::Close()

Return values

aeNoError (= 0)	If no error occurred.

aeNotConnected	If the connection was closed or if there is no opened connection.

Description

This closes the connection of the control. In the case of a synchronous connection, all the frames sent by the peer and not yet received are lost. If the peer tries to communicate after the call of AGCtrl::Close, it will be answered that the channel has been broken (aeChannelBroken).

Example

Dim nError As Integer
' close the connection
nError = AGCtrl1.Close()

See also

AGCtrl::Open


AGCtrl::DumpFrame

Retrieving a string designing the frame

VARIANT AGCtrl::DumpFrame()

Return value

VARIANT string.

Description

This function allows you to retrieve a string containing a representation of the frame of the control.

Example of string:

{ frame at 0xx
prenom : "John" (String),
nom : "Doe" (String),
age : 30 (Long),
adresse : { frame at 0xx
street : "Lafayette" (String),
city : "New York" (String),
},
}

DumpFrame is an aid to applications development using AGCtrl. It is recommended not to use it outside the debugging phase because the bigger the frame is, the longer the time is for processing.  This process requires a lot of memory and some problems with memory may occur.

Example

Dim vDump As Variant

vDump = AGCtrl1.DumpFrame()


AGCtrl::Get

Getting a frame

long AGCtrl::Get(BSTR sPath)

Parameters

sPath	An access path where the frame you get must be stored. If sPath is NULL or empty, the received frame replaces the frame of the control.

Return values

Error code of type AldeaError.

aeNoError (= 0)	If no error occurred.

aeNoDataInStack	Only in asynchronous mode, if there is no frame in the server stack for us.

aePathError	If the access path for the frame is incorrect.

aeSendNeeded	Only in synchronous confirmed mode, you try to retrieve data while the peer is trying to retrieve some at the same time. It is necessary to call AGCtrl::Send.

aeTimeout	If the time needed to complete the task expired .

aeChannelBroken	If there was a transmission error between the server and the peer (the connection has been closed).

aeOutOfMemory	In the case of memory problem.

aeFrameError, aeConvertToBufferError, aeConvertFromBufferError
If there was an internal error when accessing to a frame.

aeBuffError	If there was an internal error when accessing a buffer.

aeGenericError	If an error was detected but not identified.

Description

AGCtrl::Get allows you to receive a frame and to put it in the slot specified by sPath. If you use a synchronous connection (confirmed or not), the frame is received from the peer that is specified in the function AGCtrl::Open. If you use an asynchronous connection, the frame is received from the peer(s) specified in the function AGCtrl::Open or specified by the function AGCtrl::SetPeer.

In confirmed synchronous mode, if somebody tries to do a AGCtrl::Get while the peer is trying to receive data, the error aeSendNeeded is generated.

Remarks

If you use the asynchronous mode and if more than one peer is specified, the received frame is the first one destined to the control and which comes from one of the specified peers ; a slot called peername is added to the frame, giving the peer name who sent the frame.

Example

Dim nError As Integer

nError = AGCtrl1.Get("SubFrame")	' Get a frame and store it into the slot named "SubFrame"

See also

AGCtrl::GetFrom, AGCtrl::Send, AGCtrl::SendTo


AGCtrl::GetFileFromSlot

Saving a file stored in a slot

long AGCtrl::GetFileFromSlot(BSTR sPath, BSTR sFileName)

Parameters

sPath	Access path to a slot of the array. Names of slots must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows you to separate slots. The apostrophe (') and space are prohibited. This parameter is not case sensitive.

sFileName	Path on disk where the file will be saved. Warning: if this file already exists, it is destroyed, otherwise it is created. If the path is wrong, if there is a hard drive space problem, or if the  file specified cannot be erased, an error occurs.

Return value

Error code of type AldeaError.

aeNoError (= 0)	The file from the slot specified by sPath was saved in the file whose path is specified by the parameter sFileName.

aeOpenFileError	The file whose path is specified by the parameter sFileName could not be opened in writing mode (wrong path, not enough space left, or the existence of a file of the same name which cannot be destroyed).

aePathError	If the slot specified by sPath does not exist or if the file slot (buffer type) was not inserted with the function AGCtrl::PutFileIntoSlot.

aeGenericError	If an error was detected but not identified.

Description

This method allows you to save on disk a file, which have been stored before in a frame of the control using the method AGCtrl::PutFileIntoSlot.

This function is used for transmitting files of any type. For example, if a peer ‘A’ wants to transmit a file to a peer ‘B’, he puts the file to transmit in the frame of the control using AGCtrl::PutFileIntoSlot, then he transmits the frame to the peer ‘B’ who can retieve the file using the method AGCtrl::GetFileFromSlot.

Example

Dim nError As Integer

' The file is saved in "e:\fichier.txt"
nError = AGCtrl1.GetFileFromSlot("sous_frame.fichier", "e:\fichier.txt")

See also

AGCtrl::PutFileIntoSlot


AGCtrl::GetFrom

Getting a frame from one or several peers

long AGCtrl::GetFrom(BSTR sPath, BSTR sPeerPath)

Parameters

sPath	An acces path of this frame  in the default frame. If the path is NULL or empty, the whole frame is sent.

sPeerPath	Name(s) of the peer(s) from whom the frame is waited for.

Return values

Error code of type AldeaError.

aeNoError (= 0)	If no error occurred.

aeNoDataInStack	If there is no frame for us in the server stack.

aePathError	If the access path for the frame is wrong.

aeModeIsNotAsync	If the connection mode is not asynchronous.

aeBadPeerName	If the name of the peer(s) is empty.

aeTimeout	If the time needed to complete the task expired .

aeChannelBroken	If there was a communication error between the server and the client (the connection has been closed).

aeOutOfMemory	If there is a lack of memory.

aeFrameError, aeConvertToBufferError, aeConvertFromBufferError
If there was an internal error when accessing to a frame .

aeBuffError	If there was an internal error when accessing to a buffer.

aeGenericError	If an error was detected but not identified.

Description

This method works the same way as the AGCtrl::Get method in the asynchronous connection. In addition, you can specify the name of peer(s).

Warning

This method only works in an asynchronous connection.

Example

Dim nError As Integer

' Get the first frame from the peer called "Peer1" or any peer whose name begin with "TEST"

nError = AGCtrl1.GetFrom("SubFrame","Peer1;TEST*")

See also

AGCtrl::Get, AGCtrl::Send, AGCtrl::SendTo


AGCtrl::GetHostAddress

Retrieving a string containing the Host IP address

VARIANT AGCtrl::GetHostAddress()

Return value

VARIANT string containing the IP address of the host which the control is running on.

Description

This function allows you to retrieve the IP address of the machine which the control is running on(for example "208.2.1.1"). The value returned is a VARIANT of string type.

Use this function to create unique IDs.

Example

Dim vHostAddress As Variant

vHostAddress = AGCtrl1.GetHostAddress()

See also

AGCtrl::GetHostName


AGCtrl::GetHostName

Retrieving a string containing the host DNS name

VARIANT AGCtrl::GetHostName()

Return value

VARIANT string containing the DNS name of the host which the control is running on.

Description

This function allows you to retrieve the DNS name of the machine which the control is running on (for example "home.dom.com"). The value returned is a VARIANT of a string type.

Example

Dim vHostName As Variant

vHostName = AGCtrl1.GetHostName()

See also

AGCtrl::GetHostAddress


AGCtrl::GetPeer

Returning the I.D of the peer (s)

long AGCtrl::GetPeer(VARIANT* vPeer)

Parameters

vPeer	On exit, provide a string containing the name of the peer(s).

Return values

Error code of type AldeaError.

aeNoError	If no error occurred.

aeNotConnected	If there was no active connection.

Description

Allows you to know the ID of the peer(s). If there is more than one peer (asynchronous mode), they have to be separated by ";".

Example

Dim nError As Integer
Dim vPeer As Variant

' Recuperate the I.D of the peer(s).

nError = AGCtrl1.GetPeer(vPeer)

See also

AGCtrl::SetPeer


AGCtrl::IsOpen

To test if the connection is open

long AGCtrl::IsOpen(BOOL bCheck)

Parameters

bCheck	To test the connection to the server over the network if the value is TRUE,  on the host if the value is FALSE.

Return values

A value of type AldeaError:

aeNoError	The connection is open and works properly.

aeChannelBroken	The connection is closed.

Description

Tests if the connection was opened. If bCheck is FALSE, the test was made only on the host, otherwise the connection to the server is tested, which can take some time, and more on the Internet.

Example

if (AGCtrl1.IsOpen(false) = true) then
/* CONNECTION OPENED IN OUR SIDE (CLIENT) */
if (AGCtrl1.IsOpen(true) = true)

/* CONNECTION OPENDED AND TESTED GOING TO PEER */
Else

/* THE CONNECTION WAS IN FACT CLOSED WITH THE SERVER */
End If
Else

/* CONNECTION IS CLOSED */
End If

See also

AGCTrl::Pingt


AGCtrl::GetSlotValue

Retrieving the value of a slot

VARIANT AGCtrl::GetSlotValue(BSTR sPath)

Parameters

sPath	An access path to a slot of the array. Names of slots must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows you  to separate the slots. The apostrophe (') and space are prohibited. This parameter is not case sensitive.

Return values

Value of the slot or VARIANT of type VT_EMPTY if the slot does not exist.

Description

This method allows you to get the value of a slot. If the slot specified by sPath does not exist, the returned VARIANT is empty (type VT_EMPTY).

Example

Dim vValue As Variant

vValue = AGCtrl1.GetSlotValue("SubFrame.Slot1")

See also

AGCtrl::SetSlotValue


AGCtrl::HasSlot

Testing the existence of a slot

long AGCtrl::HasSlot(BSTR sPath)

Parameters

sPath	An access path to a slot of the array. Names of slots must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows you to separate the slots. The apostrophe (') and space are prohibited. This parameter is not case sensitive.

Return value

Error code of type AldeaError.

aeNoError (= 0)	If the slot exists.

aePathError 	If the slot does not exist.

Description

Tests the existence of a slot.

Example

Dim nError As Integer

nError = AGCtrl1.HasSlot("A_Slot")

If (nError = 0) Then
‘ The slot exists
Else
‘ The slot doesn't exist
End If

See also

AGCtrl::Is<type>


AGCtrl::Is<type>

To test if a slot is a particular type

long AGCtrl::IsNil(BSTR sPath)
long AGCtrl::IsTrue(BSTR sPath)
long AGCtrl::IsArray(BSTR sPath)
long AGCtrl::IsFrame(BSTR sPath)
long AGCtrl::IsString(BSTR sPath)
long AGCtrl::IsSymbol(BSTR sPath)
long AGCtrl::IsByte(BSTR sPath)
long AGCtrl::IsShort(BSTR sPath)
long AGCtrl::IsBool(BSTR sPath)
long AGCtrl::IsLong(BSTR sPath)
long AGCtrl::IsFloat(BSTR sPath)
long AGCtrl::IsDouble(BSTR sPath)
long AGCtrl::IsDateTime(BSTR sPath)
long AGCtrl::IsBuff(BSTR sPath)

Parameters

sPath	An access path to a slot of the array. Names of slots must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows you  to separate the slots. The apostrophe (') and space are prohibited. This parameter is not case sensitive.

Return value

Error code of type AldeaError.

aeNoError	If the slot is the correct type.

aeTypeMismatch	If the slot exist but is not the correct type.

aePathError 	If the slot does not exist.

Description

Tests the existence of a slot and if it is the correct type corresponding to the method used.

Remarks

The method AGCtrl::IsBool allows you to test if a slot is of the boolean type.. Methods AGCtrl::IsNil and AGCtrl::IsTrue allows you to test if a slot is of the boolean type and its value is nil (false) or true.

Example

Dim nError As Integer

'test if the slot "A_Slot" have a type of boolean and its value is nil

nError = AGCtrl1.IsNil("A_Slot")

' test if the slot "A_Slot" have a type of long
nError = AGCtrl1.IsLong("A_Slot")

See also

AGCtrl::HasSlot


AGCtrl::KillTimer

Destruction of a timer

long KillTimer(long nIDEvent)

Parameters

nIDEvent	Identification number of the timer to kill.

Return value

Error code of type AldeaError.

aeNoError (= 0)	If the timer was killed.

aeGenericError	If the timer was not killed.

Description

This function allows you to stop a timer which has been launched with the function AGCtrl::SetTimer.

Example

Dim nError As Integer

' Kill the timer number 1
nError = AGCtrl1.KillTimer(1)

See also

AGCtrl::SetTimer, AGCtrl::Timer


AGCtrl::Length

Giving the length of an array

long AGCtrl::Length(BSTR sPath, VARIANT* vLength)

Parameters

sPath	An access path to a slot of the array. Names of slots must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows you  to separate slots. The apostrophe (') and space are prohibited. This parameter is not case sensitive..

vLength	On exit, the variant contains the value of the length of the array.

Return value

Error code of type AldeaError.

aeNoError (= 0)	If the slot is correct an array and vLength is well positioned.

aePathError	If the slot does not exist or is not an array.

Description

Gives the length of an array.

The slot accessed must be an array, otherwise the aePathError error code is returned.

Example

Dim nError As Integer

Dim vVariantLongueur As Variant

nError = AGCtrl1.Length("An_Array", vVariantLongueur)

See also

AGCtrl::SetLength


AGCtrl::Timer

Creation of a timer event

void AGCtrl::Timer(long nIDEvent)

Parameters

nIDEvent	Identification number of the launched timer.

Description

When a timer is created using the function AGCtrl::SetTimer, an event is launched at regular intervals. The identification number and the value of intervals are declared by calling up the command AGCtrl::SetTimer.

See also

AGCtrl::SetTimer, AGCtrl::KillTimer


AGCtrl::Open

Parameters	Return values	Description	Example	See also

To open the connection

long AGCtrl::Open(BSTR sClientName, BSTR sServerName, BSTR sPeer, long iLinkType, long iTimeout)

Parameters

sClientName	ID of the client. This string must be unique during the time of the connection. Two Active Gateway clients with the same name cannot be connected at the same time.

sServerName	String specifying the server address. This can be a standard IP address (ex. : 127.0.0.1), or DSN name (ex. : www.aldea-interactive.com).

sPeer	The ID of the peer set in a string.

iLinkType	Type of the connection wanted :
ac_lmSyncWithoutConf (= 0) synchronous without confirmation. The two peers must connect at the same time. They can communicate together during all the connection time. When a frame is sent, the function AGCtrl::Send exits when the frame  arrived at the server (and not to the peer).
ac_lmSyncWithConf (= 1) synchronous with confirmation. The two peers must connect at the same time. They can communicate together during all the connection time. When a frame is sent, the function AGCtrl::Send exits when the peer received the frame.
ac_lmAsync (= 2) asynchronous (mode "store and forward"). The peer is not forced to be connected. Transmitted data are temporarily stored on the server until the peer gets them.

iTimeout	Value of maximum waiting time, in milliseconds, for each task of the connection process.

Return values

Error code of type AldeaError.

aeNoError (= 0)	If no error occurred.

aeBadServer	If the address is a wrong IP address or if the address is a DNS name and the resolution failed.

aeServerNotResponding
If the server does not respond (verify if the server is running and if the connection port is working);

aeServerNeeded	If the server address is not specified. (empty string)

aeTimeout	If the time needed to complete the connection tasks has expired .

aeTimeoutPeer	If the time needed to connect with the peer has expired.

aeChannelInvalid, aeWouldBlock, aeGenericOpenError, aeGenericWriteError

If an internal TCP/IP error occurred. (TCP/IP not running)

aeChannelBroken	If there was a transmission error between the server and the peer. (the connection has been closed)

aeOutOfMemory	If there is a lack of memory.

aeFrameError, aeFrameToBuffError, aeConvertFromBufferError
If there was an internal error when accessing a frame .

aeBuffError	If there was an internal error when accessing a buffer.

aeAlreadyConnected
If a connection is already open. (a call to Open has already been done successfully)

aeBadLoginFrame	If there is an error during the connection to the server. (frame of connection is not valid)

aeBadMode	If the peer is an extension (DLL) and the connecting mode is not synchronous without confirmation.

aeGenericError	If an error was detected but not identified.

aePeerIsLinked	If the peer is already connected with the server in synchronous mode with another peer.

aePeerModeIsAsync
If the peer is already connected with the server in asynchronous mode.

aeConnectionAlreadyExist
If a peer with the same name is already connected to the server.

aePeerModeIsSyncWithConf
If you try to connect to the server in synchronous mode without confirmation while the peer is trying to connect in synchronous mode with confirmation.

aePeerModeIsSyncWithoutConf
If you try to connect to the server in synchronous mode with confirmation while the peer is trying to connect in synchronous mode without confirmation.

Description

Opens a connection to a single peer in the synchronous modes.

In the asynchronous mode, there can be more than one peer. Each of them needs to be connected.

On one hand there can be at most one connection for a control.  On the other hand, it is possible to use controls from one application (or from the same Web page) to realize simultaneous connections. However, it is necessary to take different peer names for each connection.

The time-out is the maximum waiting time acceptable between two internal operations of communication. Thus, it is possible that the total time of the connecting operation may take more than the value of the time-out.

For example, during a call to Open with a time-out of 10 seconds, the peer tries to contact the server in a maximum delay of 10 seconds; when the server is found, it lasts until the second peer connects (synchronous mode) for a delay of 10 seconds. So, the total time for this external operation of opening connection can take more time than the value of the time-out.

In asynchronous mode, the ID of the peer you passed to the function AGCtrl::Open can be changed later using the function AGCtrl::SetPeer. In synchronous mode (with confirmation or without confirmation), it is not possible to change the peer using the function AGCtrl::SetPeer, and functions AGCtrl::SendTo and AGCtrl::GetFrom cannot be used.

Example

Dim nError As Integer

' Opening of a connection with the server server.domain.fr in synchronous without confirmation
' with as ID of client ClientA and as ID of peer ClientB
' the timeout is of 10000 milliseconds that is to say 10 seconds

nError = AGCtrl1.Open("ClientA", "serveur.domain.fr", "ClientB", 0, 10000)

See also

AGCtrl::Close, AGCtrl::SetPeer, AGCtrl::GetPeer, AGCtrl::SetTimeout


AGCtrl::Ping

To verify the connection to the server

long AGCtrl::Ping(VARIANT* vTime)

Parameters

vTime	On exit, the time taken by the test. This value is indicative and allows you to evaluate the response time on distant networks. (Internet for example)

Return value

Error code of type AldeaError.

aeNoError (= 0)	If the connection is working.

aeTimeout	If the time needed to complete the task has expired .

aeChannelInvalid, aeWouldBlock, aeGenericOpenError, aeGenericWriteError
If an internal TCP/IP error occurred (TCP/IP not running).

aeChannelBroken	If there was a transmission error between the server and the peer (the connection has been closed).

aeNotConnected	If the connection is closed or if there is no connection opened.

aeOutOfMemory	If there is a lack of memory.

aeFrameError, aeConvertToBufferError, aeConvertFromBufferError
If there was an internal error when accessing a frame .

aeBuffError	If there was an internal error when accessing a buffer.

Description

Allows you to verify the connection to the server. If the connection to the server works properly the function returns aeNoError. If the control is not connected to the server, the function returns aeNotConnected.

Example

Dim nError As Integer

Dim vDuree As Variant

nError = AGCtrl1.Ping(vDuree)


AGCtrl::PortName

Property PortName

Description

Contains the value of the TCP/IP port to contact the server.


AGCtrl::PutFileIntoSlot

Inserting a file in a frame

long AGCtrl::PutFileIntoSlot(BSTR sPath, BSTR sFileName)

Parameters

sPath	Access path to a slot of the array. The slot names must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows you to separate slots. The apostrophe (') and space are prohibited.This parameter is not case sensitive. If the slot already exists, it is destroyed, otherwise it is created.

sFileName	Indicates the path of the file on disk you want to store in the frame. If the path is wrong or if the file in not accessible in reading mode, an error is generated.

Return value

Error code of type AldeaError.

aeNoError (= 0)	The file whose path is specified by the parameter sFileName has been inserted in the frame of the control.

aeOpenFileError	The file whose file is specified by the parameter sFileName could not be opened in reading mode. (File not found or impossible to access in reading mode)

aeOutOfMemory	If there is a lack of memory;

aeGenericError	If an error was detected but not identified.

Description

This method allows you to insert data of a file in a slot  of the frame of the control. If the path of the file on disk is incorrect or if the file is not accessible in reading mode, an error is generated. The string sPath specifies the slot in which the data of the file will be placed. If the slot already exists, it is destroyed, otherwise it is created.

This function works on any kind of file. When the peer receives the frame, he can retrieve the file using AGCtrl::GetFileFromSlot.

Warning

Do not use this method with large files. If you try to transmit files whose size is bigger than the capacity of the memory your computer or the computer receiving the file, some problems of memory and time of transmission could occur.

Example

Dim nError As Integer

' Store the file "c:\autoexec.bat" in the slot "subframe.file"
nError = AGCtrl1.PutFileIntoSlot("subframe.file", "c:\autoexec.bat")

See also

AGCtrl::GetFileFromSlot


AGCtrl::RemoveSlot

Destroying a slot

long AGCtrl::RemoveSlot(BSTR sPath)

Parameters

sPath	Access path to a slot of the array. The slot name must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows you to separate slots. The apostrophe (') and space are prohibited. This parameter is not case sensitive.

Return values

Error code of type AldeaError.

aeNoError (= 0)	If no error occurred.

aePathError	If the path is wrong.

Description

This method allows you to destroy a slot. If this slot is a frame or an array, its elements are destroyed.

Example

Dim nError As Integer

AGCtrl1.RemoveSlot("SubFrame.Slot1")

See also

AGCtrl::SetSlotValue, AGCtrl::Reset


AGCtrl::Reset

Destroying all the slots of a frame or of an array

long AGCtrl::Reset(BSTR sPath)

Parameters

sPath	Access path to a slot of the array. Names of slots must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows you to separate slots. The apostrophe (') and space are prohibited.  This parameter is not case sensitive.

Return values

Error code of type AldeaError.

aeNoError (= 0)	If no error occurred.

aePathError	If the path to the slot is wrong (the slot does not exist or is not a frame or an array).

Description

This method allows you to clear a frame, which means the destruction of all the frame slots. sPath must specify a frame, otherwise an error is generated. To clear the principal frame, you have to pass an empty path.

Example

Dim nError As Integer

AGCtrl1.Reset("SubFrame")

Get the following frame:

{ frame at 0xx

...

SubFrame : { frame at 0xx

    },

...

}

See also

AGCtrl::RemoveSlot


AGCtrl::Send

Sending a frame to peer(s)

long AGCtrl::Send(BSTR sPath)

Parameters

sPath	An access path of the frame you want to send. If sPath is NULL or empty, the entire frame is sent.

Return values

Error code of type AldeaError.

aeNoError (= 0)	If no error occurred.

aePathError	If the access path for the frame is wrong. (The slot does not exist or is not a frame)

aeGetNeeded	Only in synchronous confirmed mode: you try to send data while the peer is trying to send data at the same time. It is necessary to call AGCtrl::Get.

aeTimeout	If the time needed to complete the task has expired.

aeGenericWriteError
If an internal TCP/IP occurred (TCP/IP not running).

aeChannelBroken	If there was a transmission error between the server and the peer (the connection has been closed).

aeOutOfMemory	If there is a lack of memory.

aeFrameError, aeConvertToBufferError, aeConvertFromBufferError
If there was an internal error when accessing a frame .

aeBuffError	If there was an internal error when accessing a buffer.

aeGenericError	If an error was detected but not identified.

Description

AGCtrl::Send allows you to send the principal frame of the control or a child frame (subframe). If you are in synchronous mode (with confirmation or without confirmation), the frame is sent to the peer specified in the method AGCtrl::Open. If the mode is asynchronous, the frame is sent to the peer(s) specified in the method AGCtrl::Open or specified by the method AGCtrl::SetPeer.

In synchronous mode without confirmation, the function returns aeNoError only when the peer have received the frame (with AGCtrl::Get). In synchronous mode with confirmation, if you try to do a Send while the peer is sending data, the error aeGetNeeded is generated.

Example

Dim nError As Integer

nError = AGCtrl1.Send("")	' Send of all the frame

nError = AGCtrl1.Send("SubFrame")	' Send the child frame "SubFrame"

See also

AGCtrl::SendTo, AGCtrl::Get, AGCtrl::GetFrom


AGCtrl::SendTo

Sending a frame to one or more peers

long AGCtrl::SendTo(BSTR sPath, BSTR sPeerPath)

Parameters

sPath	Access path of the frame you want to send. If sPath is NULL or empty, the entire frame is sent.

sPeerPath	Names of the peer(s) to whose the frame will be send.

Return value

Error code of type AldeaError.

aeNoError (= 0)	If no error occurred.

aePathError	If the access path for the frame is wrong. (if the slot does not exist or is not a frame)

aeModeIsNotAsync	If the connection mode is not asynchronous.

aeBadPeerName	If the name of the peer(s) is empty.

aeTimeout	If the time needed to complete the task expired.

aeGenericWriteError
If an internal TCP/IP error occurred. (TCP/IP not running)

aeChannelBroken	If there was a transmission error between the server and the peer (the connection has been closed).

aeOutOfMemory	If there is a lack of memory.

aeFrameError, aeConvertToBufferError, aeConvertFromBufferError
If there was an internal error when accessing a frame .

aeBuffError	If there was an internal error when accessing a buffer.

aeGenericError	If an error was detected but not identified.

Description

This method allows you to send a frame to one or more peer. For example, if you specify as peers "ClientA;ClientB", the frame will be stored in a stack of the server for ClientA and ClientB. At the time they connect, they will be able to retrieve this frame.

Warning

This method works only in asynchronous mode.

Remarks

It is possible to use the character (*) as wildcards. For example, if you specify as peer "Client*", this means that you will store in the server a frame for all the clients whose name begin with "Client", and who have an entry in the stack of the server.

Example

Dim nError As Integer

' A child frame sending to peer Correspondant1

nError  = AGCtrl1.SendTo("SubFrame","Correspondant1")

' all the frame sending to all the peers whose names begin by Correspondant and by AutreCorrespondant and who have an entry to the stack of the server

nError  = AGCtrl1.SendTo("","Correspondant*;AutreCorrespondant")

See also

AGCtrl::Send, AGCtrl::Get, AGCtrl::GetFrom


AGCtrl::SetLength

Resizing an array

long AGCtrl::SetLength(BSTR sPath, long iLength)

Parameters

sPath	Access path to a slot of the array. Names of slots must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows you to separate slots. The apostrophe (') and space are prohibited.  This parameter is not case sensitive.

iLength	New size of the array.

Return value

Error codeof type AldeaError.

aeNoError (= 0)	If the slot is an array and if the resizing was correctly done.

aePathError	If the specified slot does not exist or is not an array.

aeBadLength	If the specified size is wrong.

Description

This method allows you to resize an array. If the new size is inferior to the actual size, the last elements are erased. If the new size is superior, some elements with a nil value (boolean FALSE) are added in complement.

The slot accessed must be an array.

Example

Dim nError As Integer

nError = AGCtrl1.SetLength("An_Array", 10)

See also

AGCtrl::Length


AGCtrl::SetPeer

Changing the ID of the peer(s)

long AGCtrl::SetPeer(BSTR sPeer)

Parameters

sPeer	Name of the peer(s).

Return values

Error code of type AldeaError.

aeNoError (= 0)	If no error occured.

aeNotConnected	If there is no active connection.

aeModeIsNotAsync	If the connection mode is not asynchronous.

Description

If there are more than one peer, they have to be separated by ";". The asynchronous mode allows you to exchange data with more than one peer. It is possible to use the character "*" as wildcards.

For example, if you want to send or to get data from peers whose names begin by Client and Application, you pass the following string to AGCtrl::SetPeer : "Client*;Application" (do not put space before and after the ";").

In the case of a synchronous connection, to change the peer, you have to close the current connection and to open another.

Warning

This function only works in asynchronous mode (call to AGCtrl::Open with parameter ac_lmAsync).

Remarks

In asynchronous mode, you can use the method AGCtrl::GetFrom in place of the couple SetPeer/Get, and the method AGCtrl::SendTo in place of the couple SetPeer/Send, except that AGCtrl::GetFrom and AGCtrl::SendTo do not modify the peer(s) specified by SetPeer.

Example :

AGCtrl1.SetPeer("ClientC;ClientD;App*")

AGCtrl1.Get("") // The peers are "ClientC;ClientD;App*"

AGCtrl1.SendTo("", "ClientA") // we specify the peer : "ClientA"

AGCtrl1.Send("") // The peers are always "ClientC;ClientD;App*"

Example

Dim nError As Integer

' We change the ID of the peer(s)

nError = AGCtrl1.SetPeer("ClientC;ClientD;App*")

...

nError = AGCtrl1.SetPeer("ClientD")

See also

AGCtrl::GetPeer


AGCtrl::SetSlotEmptyArray

Creating an empty array in a slot

long AGCtrl::SetSlotEmptyArray(BSTR sPath)

Parameters

sPath	An access path to a slot of the array. Names of slots must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows you to separate slots. The apostrophe (') and space are prohibited. This parameter is not case sensitive.

Return value

Error code of type AldeaError.

aeNoError (= 0)	If the array is created.

aePathError	If sPath is empty or NULL.

Description

This method allows you to create a slot of empty array type. If a slot of the same name already exists, it is destroyed.

Example

Dim nError As Integer

nError = AGCtrl1.SetSlotEmptyArray("Un_nouveau_tableau_vide")

We get the following frame :

{ frame at 0xx

Un_nouveau_tableau_vide : [ array at 0xx

    ],

}

See also

AGCtrl::SetSlotEmptyFrame


AGCtrl::SetSlotEmptyFrame

Create an empty frame in a slot

long AGCtrl::SetSlotEmptyFrame(BSTR sPath)

Parameters

sPath	Access path to a slot of the array. Names of slots must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows to separate slots. The apostrophe (') and space are prohibited. This parameter is not case sensitive.

Return value

Error code of type AldeaError.

aeNoError (= 0)	If the frame is created.

aePathError	If sPath is empty or NULL.

Description

This method allows you to create a slot of the empty frame type. If a slot of the same name already exists, it is destroyed.

Example

Dim nError As Integer

nError = AGCtrl1.SetSlotEmptyFrame("Une_nouvelle_frame_vide")

You get the following frame:

{ frame at 0xx

Une_nouvelle_frame_vide : { frame at 0xx

    },

}

See also

AGCtrl::SetSlotEmptyArray


AGCtrl::SetSlotNil

Changing the value of a slot to nil

long AGCtrl::SetSlotNil(BSTR sPath)

Parameters

sPath	Access path to a slot of the array. Names of slots must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows you to separate slots. The apostrophe (') and space are prohibited. This parameter is not case sensitive.

Return value

Error code of type AldeaError.

aeNoError (= 0)	If no error occurred.

aePathError	If there was a problem during the adding of the slot.

Description

This method allows you to change the value of a slot to nil (boolean of value FALSE). If the slot does not exist, it is created.

Example

Dim nError As Integer

nError = AGCtrl1.SetSlotNil("A_Slot")

See also

AGCtrl::SetSlotTrue


AGCtrl::SetSlotTrue

Changing the value of a slot to true

long AGCtrl::SetSlotTrue(BSTR sPath)

Parameters

sPath	An access path to a slot of the array. Names of slots must not contain  accentuated characters (ASCII codes greather than 127). The point (.) allows you to separate slots. The apostrophe (') and space are prohibited. This parameter is not case sensitive.

Return value

Error code of type AldeaError.

aeNoError (= 0)	If no error occurred.

aePathError	If there was a problem during the adding of the slot.

Description

This method allows you to change the value of a slot to TRUE (boolean of value TRUE). If the slot does not exist, it is created.

Example

Dim nError As Integer

nError = AGCtrl1.SetSlotTrue("A_Slot")

See also

AGCtrl::SetSlotNil


AGCtrl::SetSlotValue

Changing the value of a slot

long AGCtrl::SetSlotValue(BSTR sPath, VARIANT vValue)

Parameters

sPath	An access path to a slot of the array. Names of slots must not contain accentuated characters (ASCII codes greather than 127). The point (.) allows you to separate slots. The apostrophe (') and space are prohibited. This parameter is not case sensitive. If the slot already exists, it is destroyed, otherwise it is created.

vValue	Value of the slot.

Return values

Error code of type AldeaError.

aeNoError (= 0)	If no error occurred.

aePathError	If the path to the slot is wrong.

aeOutOfMemory	If there is a lack of memory.

Description

This allows you to add a slot to the frame of the control. The added value vValue is a VARIANT which must be one of the types supported by Active Gateway, that means boolean, string, symbol (string beginning by (')), byte, long integer (long), short integer (short), simple precision floating-point number (float), double precision floating-point number (double), date.

Example

Dim nError As Integer

' Clear the frame to begin the example
AGCtrl1.Reset("")

AGCtrl1.SetSlotValue("SubFrame.Slot1", "A String")

AGCtrl1.SetSlotValue("SubFrame.Slot2", 10.0)

AGCtrl1.SetSlotValue("Name", "John")

Dim vDump As Variant

vDump = AGCtrl1.DumpFrame()

the variant vDump the string of representation of the following frame:

{ frame at 0xx

SubFrame : { frame at 0xx

slot1 : "A String" (String),

slot2 : 10.0 (float),

    },

name : "John",

}

See also

AGCtrl::GetSlotValue


AGCtrl::SetTimeout

Changing the value of the timeout

long AGCtrl::SetTimeout(long iTimeout)

Parameters

iTimeout	Value for the maximum  waiting time allowed, in milliseconds, for an operation.

Return values

Error code of type AldeaError.

aeNoError (= 0)	If the timeout is changed.

aeBadTimeout	If the timeout is inferior to zero.

aeNotConnected	If there is no current connection.

aeChannelInvalid	If the channel of communication is out.

Description

This method allows you to change the value of the timeout. The time-out is the maximum waiting time acceptable between two internal operations of communication. Thus, it is possible that the total time of  the connecting operation may take more than the value of the time-out.

For example, during a call to Open with a time-out of 10 seconds, the peer tries to contact the server in a maximum delay of 10 seconds; when the server is found, it lasts until the second peer connects (synchronous mode) for a delay of 10 seconds. So, the total time for this external operation of opening connection can take more time than the value of the time-out.

Example

Dim nError As Integer

' we fixe the timeout to 15 seconds
nError = AGCtrl1.SetTimeout(15000)


AGCtrl::SetTimer

Creating a timer

long AGCtrl::SetTimer(long nIDEvent, long nElapse)

Parameters

nIDEvent	Identification number of the timer to create.

Return value

Error code of type AldeaError.

aeNoError (= 0)	The timer is created.

aeGenericError	If the timer cannot be created. The system refuses the creation of the timer. Warning: it is not possible to create more than one timer with the same identification number (parameter nIDEvent).

Description

This method allows you  to create a timer giving it an identification number. At the time the timer is created, the event AGCtrl::Timer is generated at regular intervals, each nElapse milliseconds, with as parameter the identification number. To erase this timer, you have to call the function AGCtrl::KillTimer with as parameter the same identification number.

This function allows you to use the service of timers even when your environment does not offer this (in a Web page for example).

Example

Dim nError As Integer

' Create the timer number 2 which is active all the 3 seconds (3000 milliseconds)
nError = AGCtrl1.SetTimer(2, 3000)

See also

AGCtrl::KillTimer, AGCtrl::Timer