Integration

Integration Overview

PageGate is designed to easily integrate with other applications, giving them wireless messaging capabilities. Once integrated, your application will be able to send messages to all the recipients and groups that have been setup in PageGate, and even send messages through PageGate for recipients that aren't actually setup in PageGate's database (see the Ad-Hoc section of this help file for more information).

GetAscii Module

The GetAscii Module, also known as the Commandline/Ascii interface is the most commonly used module to integrate other software with PageGate. There are four different ways the GetAscii interface can be used to accept messages from other applications: commandline, text file, registry polling, windows messages.

Commandline:

PageGate includes two executable file that can be run to pass messages into its message queue: sendpage.exe and sendpage32.exe. Sendpage.exe is a 16-bit program, and sendpage32 is a 32-bit program. Depending on how the programs are to be called, you may need to use one or the other. To use the executables, run them and provide the recipient, sender, and message information as parameters on the commandline. For example, to send a message to Joe from Brian with the message Testing 123, you could use this command: sendpage Joe Brian Testing 123. Detailed information about the use of the sendpage programs can be found in this help documentation in the 'GetAscii' section (under 'Modules').

Text file:

PageGate can extract message information from text files. By default the GetAscii module looks for text files in a single location, with a predefined file format, and a predefined naming convention. The GetAscii module also supports 'Advanced Polling Options', which enable GetAscii to read files from multiple folders and from files that aren't in the standard format. GetAscii can even 'watch' files for additions or changes, and then extract message data from them. Detailed information about the use of the GetAscii text file interface can be found in this help file in the 'GetAscii' section (under 'Modules').

Registry Polling:

The GetAscii interface can accept messages that are passed to it via the Windows registry. Messages written to a predefined location in the registry will be picked up by the GetAscii interface. The application to be integrated with PageGate must be running on the same computer as the GetAscii module to use this integration method. Here is what you should do:

Create a new key under this existing key: HKEY_LOCAL_MACHINE\Software\NotePage\Transfer\Messages\. The name of the new key should be unique so it doesn't get overwritten by the next message. Under the new key, the following values should be created:

Ready - REG_DWORD - should be initially set to zero (0)

To - REG_SZ - the PageGate recipient or group to receive the message

From - REG_SZ - the sender of the message

Message = REG_SZ - the message text

After all the values are written, set the 'Ready' value to one (1). This signals PageGate that the entry is complete and can be read in. These new entries are automatically removed by the GetAscii interface after they are read in.

Windows Messages:

This option enables other software to send new messages to the GetAscii interface by sending it a 'Windows Message'. Windows Messages can be sent by using the SendMessage() Windows API call. The application to be integrated with PageGate must be running on the same computer as the GetAscii module to use this integration method. This method may require a little more programming experience that the previous methods, but it is more efficient than the previous methods, and is fairly easy to implement. Here is the syntax of the API call:

SendMessage(PGHandle, WM_COPYDATA, MyHandle, CopyDataStructure)

Please refer to a Windows API reference for syntax and usage information

The current PageGate handle (PGHandle) can be read from the registry at: HKEY_LOCAL_MACHINE\Software\NotePage\Transfer\Handle.

The CopyDataStructure should contain a string value with the following format:

sendpage recipient sender message

The 'sendpage' text must be a the beginning of the string. The 'recipient' label should be replaced with the name of an existing PageGate recipient or group. The 'Sender' label should be replaced with the sender's name. The 'message' label should be replaced with the actual text of the message to be sent.

How to tell if the GetAscii interface is currently running:

1. Read the PageGate database file (pagegate.mdb). The current location of the PageGate database can be read from the registry: HKEY_LOCAL_MACHINE\Software\NotePage\Transfer\DBDir. It is in a format compatible with MS Access 2000. In the 'Control' table, the 'getascii_state' field will be True if the GetAscii module is running.

2. Read the registry. The registry value HKEY_LOCAL_MACHINE\Software\NotePage\Transfer\Running will have a value of 1 when GetAscii is running

3. Use the OpenEvent API call. When GetAscii starts it creates a Windows event named 'NotePageIsRunning'. This event is destroyed when GetAscii stops. The API call OpenEvent(0,0,"NotePageIsRunning") will return a non-zero result if the GetAscii interface is running.

How to get a list of current PageGate recipients and groups:

1. Read the PageGate database file (pagegate.mdb). The current location of the PageGate database can be read from the registry: HKEY_LOCAL_MACHINE\Software\NotePage\Transfer\DBDir. It is in a format compatible with MS Access 2000. The 'Users' table has an entry for each valid PageGate recipient and group.

2. Read the registry. The GetAscii interface keeps an up-to-date list of all the PageGate recipients and groups in the Windows registry: HKEY_LOCAL_MACHINE\Software\NotePage\Transfer\Recipients and HKEY_LOCAL_MACHINE\Software\NotePage\Groups.

Direct Database Access

Developers that are familiar with database access can directly integrate with PageGate's database. This is probably the most efficient way to add messages to the message queue, but may not be an option in all programming environments. Another downside to this method is that it may be version specific (if the database structure changes in a future version of PageGate, the integration may stop working). PageGate uses a Jet 4.0 database as it's back end. This is a MS Access 2000 compatible database. If you have the ability to write to MS Access 2000 databases, then you can write to the PageGate's database directly. New messages can be added to the PageGate's message queue by adding a new record to the 'messages' table in the 'pagegate.mdb' database. The field definitions and descriptions of the 'messages' table follows:

user - text field - name of an existing recipient or group to send message to

pin - text field - not used, but must be set to a zero length string ("") - can't be Null

message - memo field - text of the message to be sent

carrier - text field - not used, but must be set to a zero length string ("") - can't be Null

date_time_requested - date field - date and time to send message (usually the current time)

date_time_sent - date field - not used

frm - text field - name of sender

sent - boolean field - set to false

error - boolean field - set to false

ascii_file - text field - not used, but must be set to a zero length string ("") - can't be Null

mail_file - text field - not used, but must be set to a zero length string ("") - can't be Null

lock - boolean field - set to false

scheduled - boolean field - set to false

reliapage_index - numeric field - not used

repeat_interval - numeric field - not used

repeat_stop - date field - not used

station - numeric field - should be set to a number > 10 can be used to when printing reports to identify source of the messages

message_id - auto number field - not used

retries - numeric field - not used

last_try - date field - not used

transaction - numeric field - must be a unique number (long integer) - best way to handle this is to edit the control database record, read the current value of the 'unique' field, increment it, and then write this value back to the control table. The transaction number can be reused after about an hour

dialer - numeric field - not used

GetMail Module

More and more modern applications are building in the ability to send email. If your application supports email, it can easily be integrated with PageGate by using PageGate's email interface. The GetMail interface can be used to integrate applications running on different platforms (Unix, Mac, etc.). Please refer to the GetMail section of this manual for more details.


Web Interface

Webpage developers can use the GetWeb interface to send messages to PageGate from their webpages (HTML, ASP, JavaScript, Java, etc.). A small CGI program (webgate.exe) is used to accomplish this. The webgate CGI can be used with either a POST or GET method. The POST method can be used by creating a form on your webpage and pointing to the webgate.exe program in the FORM ACTION statement. The GET method is more popular with scripting languages such as JavaScript and Java. It allows the webgate CGI to be called with a command similar to one that could be entered into a browser's URL field. The GetWeb interface can be used to enable PageGate to be integrated with applications running on different platforms (Unix, Mac, etc.). Please refer to the GetWeb section of this manual for more details.