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


Active Gateway User Manual
Introduction

This manual introduces the whole set of Active Gateway Components. Its purpose is to help you to start using Active Gateway. If you are looking for reference information, you should refer to one of these four books:

•	"Active Gateway Server Reference Manual"

•	"Active Gateway Extensions Reference Manual"

•	"Active Gateway C++ Client Reference Manual "

•	"Active Gateway Control Reference Manual "

This manual is divided into two parts:

1	Active Gateway Components Installation

2	The Fundamentals of Active Gateway:

•	Clients and Server,

•	Communication Modes,

•	Data Structures terms.


Active Gateway components installation
Introduction

Four component types are installed by the Active Gateway setup program:

1	The server

2	The extensions

3	The clients

4	The examples


Server installation
Active Gateway Server Installation

The standard setup program installs the Active Gateway server for Win32 platforms. It installs also the AGDLL utility, which allows the configuration of  Active Gateway Server Extensions.

For more information about these components, see the "Active Gateway Server Reference Manual".

Note:

Active Gateway uses the TCP/IP protocol. Active Gateway clients and the server only run if this protocol is installed. To do this, use the "Network" control panel to add the TCP/IP protocol, or refer to the relevant Microsoft documentation.

To install an Active Gateway Server on a computer you MUST use the setup program. If you just copy the files you won’t be able to start the Active Gateway Server.


Extensions Installation

The Active Gateway server extensions are dynamic-link libraries (dlls) written in C++, which add functionalities to Active Gateway servers.

The setup program provides only one extension: AGTime. This extension is provided with its source code as a sample. It is also a good starting point to develop your own extensions.

You can get other extensions independently (see the Internet site http://activegateway.aldea-interactive.com/). Aldea Interactive has released two Active Gateway Server Extensions: AGText to generate delimited text file and AGSQL to query SQL relational databases.

The standard setup program of an Extension register the extension to the Active Gateway Server. If you develop an extension, you need to register it manually.

When the server starts up it loads all the registered extensions. The value of the entry "Dll" under the key "HKEY_LOCAL_MACHINE\SOFTWARE\Aldea Interactive\Active Gateway\AGServer\Extensions" contains the full path of all the registered extensions.

You can modify the Registry manually, but we recommand you to use AGDLL (Active Gateway Extensions Manager). This tool is a graphics utility that automatically updates the Registry for you.

AGDLL allows you to manage local or remote Active Gateway servers. But the server has to be launched to process all the management tasks. To update the Registry, AGDLL connects itself as a standard client to the management task (the monitor) of the server. If the server is not running, AGDLL cannot connect to it.

If you registered an extension that crashes the Server, just delete, move or rename the extension. The server will not be able to locate it so it will not try to load it at its next start.

Warning

Modifying the Windows Registry may be hazardous. If you manually modify the Registry, take all the necessary measures for saving it before to avoid damaging it. If you damage your Registry you might not be able to restart your system.

To modify the key under Windows 95, you need to use the REGEDIT.exe utility and under Windows NT, the REGEDT32.exe utility. The key modification dialog allows a multi-line edition. Each line indicates an extension to load with the complete file name of the dll (path followed by the file name).

In the following screen shot of the REGEDT32.exe tool under Windows NT, three extensions will be loaded at the start of the server. Their complete paths are:

•	E:\Program Files\ActiveGateway\AGServer\AGText.dll,

•	E:\Program Files\ActiveGateway\AGServer\AGTime.dll,

•	and E:\Program Files\ActiveGateway\AGServer\AGSQL.dll


Clients Installation

The standard installation program installs the following Active Gateway clients for Win32:

•	AGCtrl ActiveX control,

•	AGCore library.

Note:

Active Gateway uses the TCP/IP protocol. The Active Gateway clients and server only run if this protocol is installed. To do this, use the "Network" control panel to add the TCP/IP protocol or refer to the Microsoft documentation.

The ActiveX control

To install the ActiveX Control run the setup program located in the subdirectory Clients\AGCtrl\Install. This program makes all the necessary registration needed for an ActiveX Control. You will find two directories Disk1 and Disk2 that may be use to create installation disks (standard 1.44 Meg floppy disks).

The AGCore library

To use the AGCore library, no specific installation is needed, just complete the normal Active Gateway installation  demanding  the clients installation. You will find AGCore.dll in the Clients\Win32Libs directory.

In case of problem

If you encounter any installation problems, do not  hesitate to contact us.


Examples installation
Installation of Examples

The standard installation program installs the following Active Gateway examples for Win32:

•	AGClient: a client under Microsoft Visual C++ 4.2.

•	AGClientVB: a client under Visual Basic.

•	AGChat: a peer-to-peer chat program under Visual Basic.

•	AGMail: a mail program under Visual Basic.

•	AGTime: Active Gateway server extension under Microsoft Visual C++ 4.2
An Active Gateway Server Extension sample. a good base to begin the development of your own extension.

•	AGClientTime: the specific client of AGTime under Microsoft Visual C++ 4.2


Clients and Server

Active Gateway architecture mixes two kinds of clients and servers.

When you speak of Active Gateway components, AGServer is a server and AGCore and AGCtrl are clients. The clients connect themselves to the Active Gateway Server.

When you speak of a Client/Server you create using Active Gateway, the Client Applications are an application containing AGCtrl or linked with AGCore and the Server Application is another application (using AGCore or AGCtrl) or an Active Gateway Server Extension (a dll using the AGsAPI).


Communication modes

The communications between Active Gateway clients and its peers can be done under three modes:

•	synchronous without confirmation mode,

•	synchronous with confirmation mode,

•	and the asynchronous mode called « store and forward ».

The two first modes are comparatively rigid:

•	they are « point to point », that means that they make a client contacts a unique client.

•	it is impossible to change the peer during the connection

•	the two clients must be connected at the same time.

The mode with confirmation allows you to know if the peer has received all the data sent to him. The first mode does not allow you to know this.

The last mode is more flexible. When a client makes a connection in asynchronous mode:

•	it can have more than one peer,

•	it can change peers during the connection,

•	the peers do not need to be connected at the same time to receive a message.


Synchronous mode without confirmation
Synchronous Without Confirmation Mode

In this mode (also called "connected without confirmation mode"), the communication is made between a client and a unique peer, without transmission confirmation.

When a communication is started, it is not possible to change the peer. To do this, you have to close the current communication and to open another. In this mode, when you send data, you are sure that the data reached the server but not if the data were received by the peer.

This is the only mode used to communicate with the Active Gateway server extensions.


Synchronous mode with confirmation
Synchronous With Confirmation Mode

This mode (also called "connected with confirmation mode") looks like the synchronous without confirmation mode. It is not possible to change the peer during the communication. When using this mode is that you are sure that all the data sent was received.

This mode seems to be more reliable than the preceding mode. However; please note that it consumes more bandwidth and time because of the confirmation messages that are generated by the components.


Synchronous and asynchronous
Asynchronous Mode « Store and Forward »

This mode (also called "not connected mode") establishes a virtual communication with one or more peers. These peers do not have to be connected to the Server. The Active Gateway Server stores the transmitted data in a stack (a sort of mail box). When a client connects to the server, it can retrieve all the data that are waiting for it.

In this mode, a client is  able to broadcast messages to other peers. This means that a message is sent once to the Server but distributed to all the peers it was destined for.

When a client retrieves a message from its stack, the message can be from any peer who the client is virtually connected to.

Suppose that  "ClientA" client want to send data to "ClientB" in asynchronous mode, "ClientB" does not need to be connected at the same time.

•	"ClientA" will connect to the Active Gateway server and send messages to "ClientB’s" stack (a sort of mailbox). These messages will be stored by the server.

•	When "ClientB" will connects to the server, it will be able to retrieve all the data that are waiting in its stack.


Data structure
Data Structures

To exchange information between peers, Active Gateway needs to use a data structure. Active Gateway offers an set of objects which can contain different types of data. These objects are dynamic and flexible. They adapt to all the situations to allow the easy integration of the ActiveGateway technology in your applications. These objects are useable from any client type, which can be an application using the AGCtrl ActiveX control or an application using the AGCore dll in C++.

There are three object types:

•	the slots which are data storage object ,

•	the frames which are collections named slots,

•	the arrays which are arrays of indexed slots.


Slots

The slots are abstract objects comparable to data storage boxes. Those boxes can contain data of several types.

The simple types are: • Boolean: true or nil (false) • Byte (signed integer on one byte) • DateTime (date and time) • Double (signed real on eight bytes) • Float (signed real on four bytes) • Long (signed integer on four bytes) • Short (signed integer on two bytes) • String  and the complex types are: • Array (indexed array of slots) • Buffer  • Frame (named slots collection)

A slot can only contain one piece of data at the same time. To store more than one piece ofdata, it is necessary to use a complex type object: an array or a frame.

It is possible to modify a slot. The new value can be of another type. Thus, in a slot, you can put alternatively a boolean, then a frame, then an integer. Slots make memory allocation or deallocation of data they store.

In a general way, you do not need to use explicitly slots. Their handling is implicit by the frames or the arrays.

For Visual Basic or Lotus Script users, slots is similar to the Variant type.


Frames

A frame is a collection of named slots. When initialized, the frame is empty. It is possible to add it, delete or modify slots. The slots can be of different types. There is no theoretical limit of the slots number. But technical limits exist (hardware memory capacity, ...).
Here is a frame example about a class and its students and its teacher. Remark the frame contains an array of frames.

{frame

Teacher : "John Doe",
Class : 23,
StudentsList :[array
0 :	{frame
Name : "Cline",
FirstName : "Richard",
Age : 36,
}
1 :	{frame
Name : "Bush",
FirstName : "Kevin",
Age : 21,
}
...
20 :	{frame
Nom : "Smith",
FirstName : "John",
Age : 20,
}
],
}

To build this frame, the C++ code is the following (code using AGCtrl are very similar):

Frame["Teacher"] = "John Doe";
Frame["Class "] = 23;
Frame["StudentsList.0.Name"] = "Cline";
Frame["StudentsList.0.FirstName"] = "Richard";
Frame["StudentsList.0.Age"] = 19;
Frame["StudentsList.1.Name"] = "Bush";
Frame["StudentsList.1.FirstName"] = "Kevin";
Frame["StudentsList.1.Age"] = 21;
...

In C++, you can also use intermediary frames and arrays:

Frame["Teacher"] = "John Doe";
Frame["Class "] = 23;
PersonFrame["Name"] = "Cline";
PersonFrame["FirstName"] = "Richard";
PersonFrame["Age"] = 19;
ArrayStudents.AddArraySlot(PersonFrame);	// Add a frame element
PersonFrame["Name"] = "Bush";
PersonFrame["FirstName"] = "Kevin";
PersonFrame["Age"] = 21;
...
ArrayStudents.AddArraySlot(PersonFrame);	// Add a frame element
...
Frame["StudentsList"] = ArrayStudents;


Arrays

An array is a zero-based array of indexed slots. The slots can be of different types. There is no theoretical limit of the elements number. But, it always exists a technical limit (hardware memory capacity, ...).
An array is totally dynamic. When it is created, it is empty. It grow up at time as elements are added. It is too possible to resize the array to enlarge it, this adds empty slots (to the nil boolean value) or reduce it (this automatically deletes slots).

CAldeaArray oSampleArray;	// Creates an empty array
oSampleArray[12] = 19;	// Put the 12 element (the 13th ) to the
// 19 value (integer).
// 0 to 11 elements are created and have a
// NIL value (or NULL or FALSE)
oSampleArray.SetLength(120) ;	// Adds 13 to 119 elements to NIL to
// have 120 elements
oSampleArray.SetLength(10) ;	// Deletes all the 10 to end element