ActiveXperts SMS Messaging Server Manual

© 1999-2010 ActiveXperts Software B.V.  contact@activexperts.com

 

1. Introduction

1.1. Product Overview

SMS Messaging Server is an SMS messaging framework that enables sending, receiving and processing SMS messages. The framework is designed to support virtually any scenario where low-and high volume SMS messaging is required.

Use SMS Messaging Server in the following scenarios:

• Mobile users can receive critical information while they are away from the office;
• Mobile users can receive notifications when important e-mails (from specific users or with specific subjects) have arrived;
• Companies can route urgent calls to the service personnel;
• Companies can send daily (stock) prices to their personnel or customers;
• Remote workers can update their time sheets;
• IT personnel can remotely restart services or reboot servers;
• Multimedia companies - like radio stations and television stations - can setup their own voting system, enabling customers to bring out votes and request voting reports;
• Entertainment companies - like bars and dancings - can send out information about special events to their customers;
• Emergency Response Centers can offer a service to locals to report crime by a short message.

This is just selection of scenarios. There are a lot of other scenarios where SMS Messaging Server can be used.

SMS Messaging Server consists of the following components:

• A Windows Service, running in the background. This service is responsible for sending, receiving and processing SMS- and e-mail messages;
• A Configuration Database, containing all configuration parameters.
• A Message Database, containing all in- and outgoing messages.
• A Manager application to make changes to the configuration and view messages;
• A Channel Wizard to detect and test attached GSM devices and to setup and test an SMPP account;
• A Monitor application to view real-time what's happening inside the system;
• An API (Application Programming Interface) to allow custom scripting;
• A collection of samples showing how to broadcast SMS messages and how to process incoming messages.

The databases may be any OLE/DB compliant database. The SMS Messaging framework is tested against MS Access, MS SQL and MySQL.

1.2. Features

SMS Messaging Server features the following:

• SMS Send and SMS Receive, on multiple channels simultaneously;
• Support for GSM Modems and GSM phones (GSM 07.05 and GSM 07.07 specifications) for low- and medium volume messaging;
• Support for HTTP-compliant SMSC centers for medium-volume messaging;
• Support for SMPP-compliant SMSC centers (SMPP 3.4 / 5.0) for high-volume messaging;
• Central, vendor-independent database to store messages;
• Support for Unicode messages, to support messages in Arabic, Chinese, etc.;
• Support for multi-part messages to allow messages larger than 160 characters;
• Support for WAP Push messages and WAP Bookmark messages;
• Support for SMS delivery verification (also known as 'delivery reports' or 'status reports');
• Routing of messages through different providers;
• Blocking of messages, based on message content, recipient addresses, etc.;
• Billing;
• Full TAPI (Windows Telephony) support;
• SMTP- and POP3 support;
• Advanced logging and tracing;
• Integration of VBScript to process incoming messages;
• Multi-threading architecture; allows sending/receiving messages on multiple channels (modems, SMPP providers, SMTP, POP3) simultaneously;
• Framework which can be fully customized.

1.3. About SMS

Introduction

The Short Message Service (SMS) is part of the GSM specification and allows messages to be sent to and from GSM mobile networks throughout the world. A single short message can contain up to 160 characters and comprise of words, numbers or an alphanumeric combination.

Short messages can be received with voice, data and fax calls. SMS also provides confirmation that a short message has been delivered to its destination. Non-textual short messages can also be sent to carry 8-bit binary data. Messages comprising of Unicode character sets which include Arabic and Chinese characters can also be carrier in SMS.

SMS is a store and forward service where a short message is sent via a Short Message Service Center (SMSC). An advantage of this is that the destination mobile device does not have to be on the network at the time when the message is sent. If a destination mobile device is not available at the time the message is sent, the SMSC service center will retry to deliver the message. Delivery of a short message takes only a few seconds from SMSC to the mobile device.

SMS messages can be up to 140 octets or 160 characters in length and can carry information coded in different ways. The most common 'coding scheme' is the GSM default alphabet. This allows a simplified text alphabet to be coded into 7 bits per character.

Most advanced applications will typically use 8-bit data where the SMSC makes no assumptions on the coding scheme and allows applications to use the 140 octets as they wish.

GSM modems

SMS Messaging Server supports GSM modems to send and receive SMS Messages. It supports a broad range of GSM modems that support the ETSI GSM 07.05 guidelines. Modern GSM devices (made by Nokia, Siemens, Sony Ericsson, etc.) use the similar subset of AT+C command set and are, as a result, also supported by ActiveXperts SMS Messaging Server. You can connect a GSM modem through one of the following interfaces:

• Serial port;
• USB interface;
• Bluetooth;
• Infrared.

SMS Messaging Server supports TAPI drivers (like 'Standard 9600 bps Modem') to make configuration of GSM modems easier. Using TAPI, you can configure the baud rate, initialization strings, etc. through the standard Windows Control Panel.

The Falcom Samba 75 GSM/GPRS modems and WaveCom Fastrack Supreme 10 modems are recommended for use with the SMS Messaging Server.

The SMS Messaging Server software can also be purchased bundled with a Falcom Samba 75 GSM/GPRS modem:

• License of ActiveXperts SMS Messaging Server;
• Falcom Samba 75 GSM/GPRS modem.

For more information and pricing, please check the ActiveXperts web site at www.activexperts.com/sales/bx008/.

HTTP Providers (SMS over HTTP)

SMS Messaging Server supports HTTP compliant SMSC providers, where SMS messages are delivered to the SMS provider via HTTP. The provider delivers the messages to the mobile phones.

The HTTP SMS protocol can only be used to send SMS messages. It allows a client (i.e. ActiveXperts SMS Message Server) to access the SMSC's ('Short Message Server Center') using the HTTP protocol to send SMS messages. To allow connection between SMS Messaging Server and an HTTP compliant SMSC center an IP connection between these two systems is required.

You need to sign-up with an HTTP-compliant SMS center before you can actually use their service. It normally requires a small sign-up free and a fee for an SMS bundle per month.

SMS Messaging Server provides free HTTP SMS messaging for a limited number of SMS messages. You can connect to the ActiveXperts HTTP SMS gateway and send messages right after installation without the need to sign-up with an SMSC center first.

SMPP Providers

SMS Messaging Server supports SMPP 3.5 compliant SMSC providers.

The SMPP protocol allows a client (i.e. ActiveXperts SMS Message Server) to access the SMSC's ('Short Message Server Center') systems to send and/or receive SMS messages. To allow connection between SMS Messaging Server and an SMPP compliant SMSC center an IP connection between these two systems is required.

Usually, an SMSC center provides multiple sites, to ensure that the service is always available. An SMSC provider ensures high-volume and high throughput messaging.

You need to sign-up with an SMPP-compliant center before you can actually use their service. It normally requires a small sign-up free, and a fee for an SMS bundle per month.

SMS Messaging Server provides free SMPP messaging for a limited number of SMS messages. You can connect to the ActiveXperts SMPP SMS gateway and send/receive messages right after installation without the need to sign-up with an SMSC center first.

There is a list of SMPP providers recommended by ActiveXperts Software hosted here.

1.4. Product Design

Introduction

The SMS Messaging Server consists of the following components (see figure):

• SMS Messaging Server service, a multi-threading SMS Messaging engine;
• Configuration Database, a vendor independent configuration database;
• Message Database, a vendor independent database where all incoming and outgoing messages are stored;
• Applications and Scripts;
• GSM Modem channels, HTTP Provider channels and SMPP Provider channels;
• SMTP and POP3 channels;
• VBScript Triggers to process incoming messages;

	Figure 1: SMS Messaging Server Design

The configuration information is stored in a database. This database can be any OLE/DB compliant database, including MS SQL Server. By default the SMS Messaging Server ships with an MS Access configuration database named Configuration.mdb.

Messages are stored in a different OLE/DB compliant database to separate them from the configuration database. By default the SMS Messaging Server ships with an MS Access message database named Messages.mdb. When using high volumes you may want to migrate this database to MS SQL when possible. This can easily be configured using our migration wizard.

A Channel is a communication device or a communication protocol. Channels are defined for each type communication device or account. For instance, channels can be defined for each GSM modem, each SMPP provider, each POP3 or SMTP account, etc. These Channels are stored in the Configuration Database. The SMS Messaging Server service reads the Channel configuration from the Configuration Database and controls each Channel by a separate process (also called 'thread').

Triggers are VBScript programs which process incoming messages. As soon as a new message is received by the system, VBScript program(s) are launched based on certain condition(s). A trigger is a pair that consists of a SQL-like condition and a VBScript program. If the trigger's condition is matched, the associated VBScript program is called.

The SMS Messaging Server service is responsible for controlling the Channels. The SMS Messaging Server service reads messages from the Message Database and provides these to the designated channel, it also polls the channels regularly to see if there are any new incoming messages. The SMS Messaging Server triggers VBScript programs whenever there are new messages in the Message Database. Scripts are only triggered when a certain condition is matched.

The SMS Messaging Server Manager provides a GUI for managing the Configuration database as well as viewing and manipulating the Messaging database. Using this Manager application new Channels can be created, existing Channels can be modified or deleted, and general options can be modified. This Manager application can also be used to view Messages and define Filters on the Message database.

SMS Messaging Server is shipped with a selection of ActiveX/COM objects to manage the Configuration Database and the Message Database. This way Administrators can fully customize the User Interface of the product, it also enables them to generate new messages themselves from a script or a custom application.

1.5. Sending Messages

To be able to send a message there must be a channel configured which is able to send messages of this type. For instance, to send an SMS message a channel must be configured that is able to send SMS messages. The following channels are capable of sending SMS messages:

• The GSM Channel
• The HTTP Channel
• The SMPP Channel

When an SMS Channel has been setup there SMS messages can be send in the following ways:

• Using the SMS Messaging Server Manager;
• From any other application using the SMS Messaging Server API;.

Each of these methods send the sends a message by first posting it to the SMS Messaging Server service. The service will ultimately send the message through the configured channel.

For more information about sending messages, see Send and Receive Messages.

1.6. Processing Messages

To be able to receive and process messages there must be a channel configured which is able to receive messages of this type. For instance, to receive and process an SMS message there must be a channel configured that is able to receive SMS messages. The following channels are capable of receiving SMS messages:

• The GSM Channel
• The SMPP Channel

Messages are received in the SMS Messaging Server service and put into the Message database where they can be inspected by using either the SMS Messaging Server Manager application or the SMS Messaging Server API.

Incoming messages will be processed by triggers based on keyword or values in either subject, body, recipient address, etc. Read more about Projects and Triggers here.

2. System Requirements

2.1. System Requirements

The ActiveXperts SMS Messaging Server service only runs on a Windows workstation or server platforms, and must meet either of the following requirements:

	CPU	Memory	SP	Disk Space
Windows 2012	1.4GHz (x64) single core	2GB	-	10GB
Windows 2008 R2	1.4GHz (x64) single core	2GB	-	10GB
Windows 2008	1.4GHz (x64) / 1GHz (x86) single core	2GB	-	10GB
Windows 2003 R2	733MHz (x64) / 550MHz (x86) single core	1GB	SP1 or higher	10GB
Windows 2003	733MHz (x64) / 550MHz (x86) single core	512MB	SP1 or higher	10GB
Windows 8	1GHz (x64/x86) single core	2GB (x64/x86)	-	10GB
Windows Vista	1GHz (x64/x86) single core	1GB (x64/x86)	SP1 or higher	10GB
Windows 7	1GHz (x64/x86) single core	1GB (x64/x86)	SP1 or higher	10GB
Windows XP	233MHz (x86) / 733MHz (x64) single core	512MB (x64/x86)	SP1 or higher	10GB

3. Installation

3.1. Introduction

The following components will be installed:

• The SMS- and e-mail communication modules;
• A Configuration Database to store all configuration settings;
• A Message Database to store all incoming- and outgoing messages;
• A Windows Service to send- and receive messages and control the message database;
• A Monitor application to monitor the engine; it shows real-time channel information;
• A Wizard to guide you through the process of configuring new channels;
• A Manager application to allow changes to the configuration and create/modify/delete messages;
• An API to provide an interface to the Message Database. This interface can be used from VBScript, VB .NET, Word, Excel, etc.;
• API samples for VBScript, VB .NET, C# .NET, HTML, ASP, ASP .NET and more.

3.2. Installation

Download the installation file from the ActiveXperts Download area (www.activexperts.com/download) and run this installation program on the server that you assigned as the central SMS Messaging Server.

Step 1 - Welcome Message

This is where the installation begins.

Step 2 - Registration information

Here, you can enter your Registration code. If you want to try the software, enter 'EVALUATION' as the registration code. You will be able to use the full-functioning software for 30 days. When you decide to buy after 30 days, you don't need to re-install the product; the Manager application allows you to enter the registration code.

Step 3 - Choose Destination Folder

Choose a destination folder. Setup will copy all components and files to this location. Make sure to have approximately 500 MB of free hard disk space available.

Step 4 - Select Program Folder

Specify a name for the Program folder.

Step 5 - Service Account

The 'ActiveXperts SMS Messaging Server service' can either log on using the built-in Local System account, or log on using a Local- or Domain administrative account. SMS Messaging Server does not need an Domain Administrative account, unless you migrate your Message Database to an MS SQL Server that requires Windows Authentication. With MS SQL Server Windows Authentication, a computer account is required that has administrative privileges on both machines (usually, a Domain Administrator account is used).

Step 6 - Finish

The software is installed now. You can optionally launch the Channel Wizard application to configure your channels.

3.3. Upgrading

Version 5.3 to version 5.4

By following these steps you will be able to upgrade and migrate your configuration from SMS Messaging Server 5.3 to SMS Messaging Server 5.4.

1. Backup.

   • Make a backup of your current installation. Preferable by imaging your server.
   • If you have the Message, Archive and/or Logging database(s) running on a separate database server, make sure to backup these as well.

2. Uninstall the current installation.

   • Uninstall the current installation through the 'Install programs/features' option.
   • Close any applications that may be running and may access the SMS Messaging Server database or API.

3. Rename all of the old resources.

   • Rename the old installation directory ('C:\Program Files\ActiveXperts\SMS Messaging Server') to 'C:\Program Files\ActiveXperts\SMS Messaging Server 53'.
   • If you have migrated the Message, Archive and/or Logging database to MySQL or MSSQL, rename these databases. In MSSQL, remember to rename the database files as well, since they will not automatically be renamed when renaming the database.

4. Install the updated version.

   • Run the installation for the new version.
   • Don't run the channel wizard after the installation.
   • If you want to ultimately run the Message, Archive and/or Logging database in either MySQL or MSSQL. Migrate these databases now.

5. Migrate the old data to the new installation.

   • Make sure the SMS Messaging Server Service as well as the SMS Messaging Server Manager application are closed.
   • Download this script file to the SMS Messaging Server host: 'Upgrade53to54.vbs'. Run the script by double-clicking it. On 64 bit OS you will need to start the script from the command line by executing: 'c:\windows\SysWOW64\wscript.exe "<PathToScript>\Upgrade53to54.vbs"'.
   • Follow the instructions in this script to migrate the information in the old Configuration, Message, Archiving and/or Logging database as well as the projects to the new installation.

6. Verify that the migration has completed successfully.

   • Startup the new SMS Messaging Server Manager Application as well as the SMS Messaging Server service.
   • Double check the channel settings for all installed channels to make sure everything is still set correctly. Some parameters may have changed.
   • If applicable, check the advanced settings in the registry in HKEY_LOCAL_MACHINE\SOFTWARE\ActiveXperts\SMS Messaging Server.
   • Verify that your projects are there and the triggers are running.
   • Re-compile and start any application that use the SMS Messaging Server API or database.

Version 5.2 to version 5.3

By following these steps you will be able to upgrade and migrate your configuration from SMS Messaging Server 5.2 to SMS Messaging Server 5.3.

1. Backup.

   • Make a backup of your current installation. Preferable by imaging your server.
   • If you have the Message, Archive and/or Logging database(s) running on a separate database server, make sure to backup these as well.

2. Uninstall the current installation.

   • Uninstall the current installation through the 'Install programs/features' option.
   • Close any applications that may be running and may access the SMS Messaging Server database or API.

3. Rename all of the old resources.

   • Rename the old installation directory ('C:\Program Files\ActiveXperts\SMS Messaging Server') to 'C:\Program Files\ActiveXperts\SMS Messaging Server 52'.
   • If you have migrated the Message, Archive and/or Logging database to MySQL or MSSQL, rename these databases. In MSSQL, remember to rename the database files as well, since they will not automatically be renamed when renaming the database.

4. Install the updated version.

   • Run the installation for the new version.
   • Don't run the channel wizard after the installation.
   • If you want to ultimately run the Message, Archive and/or Logging database in either MySQL or MSSQL. Migrate these databases now.

5. Migrate the old data to the new installation.

   • Make sure the SMS Messaging Server Service as well as the SMS Messaging Server Manager application are closed.
   • Download this script file to the SMS Messaging Server host: 'Upgrade52to53.vbs'. Run the script by double-clicking it. On 64 bit OS you will need to start the script from the command line by executing: 'c:\windows\SysWOW64\wscript.exe "<PathToScript>\Upgrade52to53.vbs"'.
   • Follow the instructions in this script to migrate the information in the old Configuration, Message, Archiving and/or Logging database as well as the projects to the new installation.

6. Verify that the migration has completed successfully.

   • Startup the new SMS Messaging Server Manager Application as well as the SMS Messaging Server service.
   • Double check the channel settings for all installed channels to make sure everything is still set correctly. Some parameters may have changed.
   • If applicable, check the advanced settings in the registry in HKEY_LOCAL_MACHINE\SOFTWARE\ActiveXperts\SMS Messaging Server.
   • Verify that your projects are there and the triggers are running.
   • Re-compile and start any application that use the SMS Messaging Server API or database.

Versions prior to 5.2

When upgrading between versions before 5.2 it is not possible to keep the configuration or messages. You will have to start out with a clean installation and re-configure any existing channels and projects. To install an upgrade follow these steps:

1. Backup.

   • Make a backup of your current installation. Preferable by imaging your server.
   • If you have the Message, Archive and/or Logging database(s) running on a separate database server, make sure to backup these as well.

2. Uninstall the current installation.

   • Uninstall the current installation through the 'Install programs/features' option.
   • Close any applications that may be running and may access the SMS Messaging Server database or API

3. Copy old projects.

   • The old installation directory ('C:\Program Files\ActiveXperts\SMS Messaging Server'), by default, contains your project implementations. These are not compatible with the new version. You can make a copy of these for future reference.
   • Remove the old installation directory.

4. Install the updated version.

   • Run the installation for the new version.
   • Perform database migrations if necessary.

5. Reconfigure the new SMS Messaging Server.

   • Configure the messaging channels.
   • Re-implement the projects.
   • Re-configure / re-compile other applications that access the SMS Messaging Server database or API.

4. Configuration

4.1. Introduction

ActiveXperts SMS Messaging Server stores its configuration in the Configuration Database. This configuration database includes the following items:

• Channel information;
• Trigger information;
• Location of the Message Database;
• Location of the Archive Database;
• Log settings;
• Directories used for temporary files.

The actual messages are NOT stored in the Configuration Database, but are stored in a separate Message Database (see also Message Database).

The Configuration Database is an MS Access based database file called CONFIGURATION.MDB, and is located in the "<INSTALL-DIR>\CFG" directory. The database includes the following tables:

• Table 'Options'. This table stores generic program settings, including log settings, location of the directory for temporary files, location of the message database, and so on;
• Table 'Triggers'. This table stores the scripts that can be triggered when a new message arrives in the system, including the condition and location of the script;
• Table 'Channels_GsmModem'. This table stores configuration information of all GSM modems connected to the server;
• Table 'Channels_Http'. Each record in this table includes information like: HTTP URL of the provider, login and password, and more;
• Table 'Channels_Smpp'. Each record in this table includes information like: IP address of the provider, login and password, and more;
• Table 'Channels_Pop3'. Each record in this table includes the host name (or IP address) of the POP3 server, as well as individual POP3 accounts;
• Table 'Channels_Smtp'. Contains information about the SMTP server, including authentication information (if required).

To select any of the above configurable items:

1. Launch the SMS Messaging Server Manager application from the Start menu;
2. Open the Configuration folder. All items will now be listed.

Alternatively, you can use the SMS Messaging Server API (Advanced Classes) to access and/or modify the configuration items.

4.2. Databases

ActiveXperts SMS Messaging Server uses various databases:

• The Configuration Database to store all program settings. This is an MS Access database, and you cannot change the location of this database. You can neither migrate it to another database;
• The Message Database. The Message Database contains all incoming and outgoing SMS- and e-mail messages. By default it is an MS Access database, which can be migrated to MS SQL Server or MySQL;
• The Archive Database. The Message Database contains all archived incoming and outgoing SMS- and e-mail messages. By default, messages are archived after 7 days, i.e. the messages are moved from the Message Database to the Archive database;
• Log Database. The Log Database contains log information about all types of events in the system.

To change the Database Settings:

1. Launch the SMS Messaging Server Manager application from the Start menu.
2. Open the Configurations folder and click on Databases.

You can now edit the Database options for the Message Database, Archive Database and Log Database. You can also migrate one or more of the above databases to MS SQL Server or MySQL.

In the Database Configuration dialog, you can configure the following options:

Item	Description
Database Type	Can be an MS Access, MS SQL or MySQL database. Default: MS Access. When you select MS SQL Server or MySQL, you will be asked to migrate to MS SQL Server or MySQL. Once confirmed, a Database Migration Wizard will guide you through the process of migrating to the database.
Connection String	The OLE/DB compliant database connection string. An MS SQL or MySQL connection string may contain the password for the MS SQL Server. To hide this password for other users, you can use the <% PASSWORD %> placeholder and specify the actual password in 'Password' property (see below). For example: Driver={SQL Server};Server=MyServer;Database=MyDatabase;Uid=sa;Pwd=<% PASSWORD %>
Password	Password used in the above 'Connection String'; Only required when the connection string contains the <% PASSWORD %> placeholder.

4.3. Channels

A 'Channel' represents a communication device or protocol, to send and/or receive messages. For example, to use the SMS Messaging Server with a GSM modem, a GSM channel needs to be defined. To use the SMS Messaging Server for sending out e-mail an SMTP channel needs to be defined.

ActiveXperts SMS Messaging Server has the following types of channels:

• GSM Device; Represents a GSM modem or mobile phone.
• SMPP Server; Represents a connection to an SMPP provider. For high performance send/receive SMS.
• HTTP Server; Represents an HTTP configuration to send through HTTP 'GET' or 'POST' messages.
• POP3 Server; Represents a single POP3 server. To receive e-mail from one or more accounts.
• SMTP Server; Represents a single SMTP server. To send out e-mail.
• File Pickup; Represents a directory on the local or a remote server. To automatically process files.

4.4. GSM Device Channels

You can define a 'GSM Device Channel' to send and/or receive SMS messages using a GSM Modem or GSM Phone with modem capabilities. The GSM Modem should be connected to the server where the SMS Messaging Server service is running, through one of the following hardware interfaces:

• Serial COM port;
• USB port;
• Bluetooth (or Infrared port).

To add/edit/delete a GSM Device Channel:

1. Launch the SMS Messaging Server Manager application from the Start menu.
2. Open the Configurations folder and click on Channels.
3. Create a new GSM Device Channel, or modify an existing GSM Device Channel.

In the GSM Device Channel dialog, you can configure the following items:

Item	Description
Description	A smart description for this channel.
Enable/Disable channel	You can enable/disable a channel at any time. When a channel is disabled, the SMS Messaging Server service will stop sending/receiving messages through this channel.
Enable/Disable Send	You can enable/disable sending messages through this channel at any time.
Enable/Disable Receive	You can enable/disable receiving messages through this channel at any time.
Device	Windows Telephony driver or direct COM port of the GSM device. It is recommended to use a Windows Telephony device, like 'Standard 9600 bps Modem', rather than direct COM ports (like COM1:). Windows Telephony devices can be configured from the Windows Control Panel.
Speed	This sets the communication speed between the server and the device. It can only be configured for a direct COM port. If it is set to 'Default', the default port speed will be selected (as configured in the Windows Control Panel).
Message Storage	Storage where SMS messages are stored when they are received from the telecom operator. It depends on the type of GSM device where SMS messages are stored. The most basic GSM devices are not equipped with device memory; these devices can store only a limited number of SMS messages on the SIM card. Advanced GSM devices are equipped with extra memory on the device. SMS messages are stored directly on the device memory. SMS Messaging Server can read incoming SMS messages from three different locations: ALL Use all storage modes (default). Always tries to read all memory stores (SM / ME / MT). The SMS Messaging Server removes the duplicates so messages that are in multiple stores are only inserted into the message database once. SM Retrieve messages directly from SIM card. Use this setting when the device doesn't have a memory buffer to store SMS messages; ME Retrieve messages from the device memory. Advanced GSM devices come with built-in memory to enlarge the number of stored SMS messages on the device; MT Combined storage. The GSM should return all messages from both SM and ME storages.
Reports Storage	Storage where delivery reports are stored when received from the network. Some devices do not have the ability to store reports. These devices cannot be used to check the delivery of messages. It is recommended to use a Wavecom Fastrack Supreme 10 or Falcom Samba modem which have a dedicated storage for reports. There are three values: ALL Retrieve reports from all storage modes (default). Always tries to read from all memory stores (SM / ME / MT / SR) SM Retrieve reports directly from SIM card. Use this setting when the device doesn't have a memory buffer to store reports; ME Retrieve reports from the device memory. Only applies to advanced GSM devices with built-in memory to enlarge the number of stored reports on the device; MT Combined storage. The GSM should return all messages from both SM and ME storages. SR Retrieve reports from the dedicated status report memory. Not all devices support this memory.
Pin Code	Specifies the Pin Code on the SIM card. Only requires when the SIM card requires a Pin Code.
Subscriber ID	The Subscriber ID is the actual SMS mobile number associated with the SIM card of the GSM modem. This number cannot be read from the GSM device by ActiveXperts SMS Messaging Server, and therefore needs to be configured manually for your own convenience. The Subscriber ID will be used in the Message Database to indicate the sender (for outgoing SMS messages) or Recipient (for incoming SMS messages).
Check Every	Indicates the polling frequency. By default, the SMS Messaging Server service checks for new incoming SMS messages every 10 seconds.
SMS Limit	The maximum number of outgoing SMS messages allowed per day (sending only) on this channel. You can put a limit on the number of outgoing SMS messages per channel, per day, to reduce costs per channel. Set this to '0' to allow an unlimited number of messages to be sent.
Large Messages	Indicates how large outgoing messages (i.e. messages longer than 160 characters) should be treated. There are three options: Truncate messages larger than 160 characters (part of the message will be lost); Send the large message as multi-part message. Each part is sent as a separate SMS message. On the remote mobile phone, the parts are collected and displayed as one single message. Note that the costs for one SMS part in a multi-part message is the same as the costs for one single 160 character SMS message. Don't send the large message at all (message will fail)
Leave copy of incoming message on device or SIM card	By default, messages will be deleted from the SIM card (SM) or Device Memory (ME) after SMS Messaging Server received them. If you want to keep a copy of the messages on the SIM card (or device), enable this option, but be aware that the SIM/Device memory will run out of free memory.
Request delivery report	To ensure that a message is received by the remote mobile phone, you can request a delivery report (status report) for every outgoing message. The SMS Messaging Server will update the message status according to the report when it is received. Receiving status reports must be supported by the GSM device. It can take several minutes or even hours for a status report to arrive. Some providers will, in some instances, not sent a status report at all.

NOTE: The configuration of a single GSM Device Channel is stored in the Channel_Gsm table in the Configuration Database, as a single record.

4.5. HTTP Channels

HTTP is a simple and fast way to send out a large number of SMS messages in a short amount of time.

You need to sign-up with a commercial HTTP SMSC provider before you can actually make use of SMS via HTTP. It normally requires a small sign-up free and a fee for an SMS bundle per month.

ActiveXperts SMS Messaging Server provides free HTTP messaging for a limited number of SMS messages. You can connect to the free ActiveXperts HTTP gateway (post.activexperts-labs.com) and send/receive messages right after installation, without the need to sign-up with a commercial HTTP Provider first to try ActiveXperts SMS Messaging Server.

To add/edit/delete an HTTP Channel:

1. Launch the SMS Messaging Server Manager application from the Start menu;
2. Open the Configurations folder and click on Channels;
3. Create a new HTTP Channel, or modify an existing HTTP Channel.

Load and Save HTTP Provider Settings

In the HTTP Channel creation wizard, you can load HTTP provider settings from a file. Once the channel has been created, you can use the Load button to reload Provider Settings, or use the Save button to save changes to a file.

Edit HTTP Provider Settings

Item	Description
Description	A description for this channel.
Enable/Disable channel	You can enable/disable a channel at any time. When the channel is disabled, the SMS Messaging Server service will stop sending messages through this channel.
URL	The URL to the HTTP server. For instance "http://post.activexperts-labs.com:8080/sendsms/default.asp" or "http://82.78.65.2:8080/sendsms/default.asp". You can use a number of placeholders in specifying the URL, these will be replaced with actual data from SMS message.
Post data	If the 'Post Data' text-field is filled the HTTP requist will be 'POST' instead of 'GET'. You can use a number of placeholders in specifying the Post Data, these will be replaced with actual data from SMS message.
Reply Includes	The text that should be present in the server reply to either indicate success or failure of sending the SMS message. Use the drop-down to the right to select 'On success' or 'On failure'
From address	Mobile number associated with this HTTP channel. It is the mobile number as it will be displayed on the recipient's mobile phone.
SMS Limit	The maximum number of outgoing SMS messages allowed per day (sending only) on this channel. You can put a limit on the number of outgoing SMS messages per channel, per day, to reduce costs per channel. Set this to '0' to allow an unlimited number of messages to be sent.
Advanced HTTP Settings	This is where the proxy-server settings and HTTP authorization settings can be specified.

You can save the provider settings to a file using the Save button. use the Load button to load provider settings.

4.6. SMPP Channels

The SMPP (Short Message Peer to Peer) protocol is a TCP/IP protocol to connect to an SMPP compliant provider over the internet. SMPP is designed for higher volumes of SMS traffic.

You need to sign-up with a commercial SMPP SMSC provider before you can actually make use of SMPP. It normally requires a small sign-up free and a fee for an SMS bundle per month.

However, ActiveXperts SMS Messaging Server provides free SMPP messaging for a limited number of SMS messages. You can connect to the free ActiveXperts SMPP server (smpp.activexperts-labs.com) and send/receive messages right after installation, without the need to sign-up with a commercial SMPP Provider first to try ActiveXperts SMS Messaging Server.

Here is a list of SMPP providers.

To add/edit/delete an SMPP Channel:

1. Launch the SMS Messaging Server Manager application from the Start menu;
2. Open the Configurations folder and click on Channels;
3. Create a new SMPP Channel or modify an existing SMPP Channel.

Load and Save SMPP Provider Settings

In the SMPP Channel creation wizard, you can load SMPP provider settings from a file. Once the channel has been created, you can use the Load button to reload Provider Settings, or use the Save button to save changes to a file.

Edit SMPP Provider Settings

SMPP Channel Settings:

Item	Description
Description	A description for this channel.
Enable/Disable channel	You can enable/disable a channel at any time. When a channel is disabled, the SMS Messaging Server service will stop sending/receiving messages through this channel.
Enable/Disable Send	You can enable/disable sending messages through this channel at any time.
Enable/Disable Receive	You can enable/disable receiving messages through this channel at any time.
Host	The host name or IP address of the SMPP server. For instance "smpp.activexperts-labs.com" or "82.78.65.2".
Port	The TCP port number of the SMPP server. The standard port number for SMPP is 2775 but most providers use other port numbers for security reasons.
SystemID	The SystemID is the login for your SMPP provider; it is used to identify yourself with the SMPP provider. This ID is, along with your password, provided by your SMPP provider.
Password	The password associated with the System ID.
System Type	Use 'SMPP' unless otherwise specified by your provider
Check Every	Indicates the polling frequency. By default, the SMS Messaging Server service checks for new incoming SMS messages every 10 seconds.
SMS Limit	The maximum number of outgoing SMS messages allowed per day (sending only) on this channel. You can put a limit on the number of outgoing SMS messages per channel, per day, to reduce costs per channel.
Large Messages	Indicates how large outgoing messages (i.e. messages longer than 160 characters) should be treated. There are three options: Truncate messages larger than 160 characters (part of the message will be lost); Send the large message as multi-part message. Each part is sent as a separate SMS message. On the remote mobile phone, the parts are collected and displayed as one single message. Note that the costs for one SMS part in a multi-part message is the same as the costs for one single 160 character SMS message. Don't send the large message at all (message will fail).

SMPP Advanced Settings:

Item	Description
Enquire Interval	The interval at which the SMPP client should send 'Enquire' packets to the remote server. An SMSC expects the client to send these packets to test if the connection is still valid.
Dl. Report Format	The format for the message reference in a delivery report. Normally, when a delivery report is received for a specific SMS message, this message is referenced using the same ID that was used to identify this message after it was submitted to the server for the first time. This is the default ('ID is text') setting. Some providers, like mBlox, deviate by giving the message reference as a hexadecimal ID on submitting the message and refering to the message using the same ID in decimal in the delivery report. This is the 'ID is decimal' setting.
Protocol Version	SMS Messaging Server is compliant with SMPP v.3.3, SMPP v.3.4 and SMPP 5.0. Most providers support 3.4
Address Range	The address range is only used when receiving messages. All messages with this address that are received by the SMPP provider should be routed to the messaging server. If you do not know the Address Range, set to the same number as the From Address field or leave the field empty. To specify a full range, you can use UNIX regular expressions. Please read FAQ Q8300035 for more information about the Address Range and UNIX regular expressions.
Address TON	The Type Of Number of the address range.
Address NPI	The Numbering Plan Indicator of the address range.
Bind TLV's	This is where you can specify additional information that need to be send when connecting to the SMSC. Only configure this when it is specifically required by the SMSC.
Service Type	Specify the service type that should be sent with each message. Normally this field can be left empty. This is usually used to specify 'USSD' when subscribing to USSD service, or 'WAP' for WAP services etc.
From Address	The from address that should be sent with each message if the message does not already specify a from address.
Default Charset	The character set that should be set default for each message. This will be applied if the message specifies the 'Channel Default' character set.
Request Delivery Report	Whether or not each message requires a delivery report. If this is set to true the SMS Messaging Server will request a delivery report for each message.
From TON	The Type Of Number of the from address.
From NPI	The Numbering Plan Indicator of the from address.
To TON	The Type Of Number of the to address.
To NPI	The Numbering Plan Indicator of the to address.
Message TLV's	Specify TLV values that will be send with every message that is send through this channel.

You can save the provider settings to a file using the Save button. Use the Load button to load provider settings.

4.7. POP3 Channels

In the Internet the POP3 (Post Office Protocol 3) protocol is used for receiving e-mail messages. It is a standard relating to the delivery and receipt of electronic mail, and is offered by the vast majority of ISP's (Internet Service Providers).

To add/edit/delete a POP3 Channel:

1. Launch the SMS Messaging Server Manager application from the Start menu.
2. Open the Configurations folder and click on Channels.
3. Create a new POP3 Channel, or modify an existing POP3 Channel.

POP3 Channel Settings:

Item	Description
Description	A description for this channel.
Enable/Disable channel	You can enable/disable a channel at any time. When a channel is disabled, the SMS Messaging Server service will stop sending/receiving messages through this channel.
Host	The host name or IP address of the POP3 server. For instance "pop3.yourdomain.dom" or "192.168.1.1".
Secure mail server	Should be checked when the mail server requires a secure (SSL/TLS) connection.
Leave a copy messages on the server	By default, messages will be deleted on the POP3 server after receive. Some mail servers, like GMail, remove messages from the mail drop anyway, regardless of this setting.
Truncate messages larger than	To prevent the Message Database from growing too large, you can truncate incoming messages. By default, messages larger than 10K will be truncated to 10K.
Check for new messages every	Indicates the polling frequency. By default, ActiveXperts SMS Messaging Server checks every 30 seconds for new messages.

In order to receive e-mails from a POP3 server, you need to configure one or more POP3 accounts. ActiveXperts SMS Messaging Server will use these account to log on to the POP3 servers and retrieve the e-mail messages.

POP3 Account Settings:

Item	Description
Enable/Disable Account	You can enable/disable this account at any time.
E-mail Address	E-mail address associated with the POP3 account.
Account Name	The Account Name property is used to log on to the POP3 server.
Password	The Password property is used to log on to the POP3 server.

4.8. SMTP Channels

Simple Mail Transfer Protocol (SMTP) is the Protocol used to transport e-mail messages between mail servers. Designed in 1982 and still in use today. It became the widely accepted standard for the transfer of email.

SMTP Settings:

Item	Description
Description	A description for this channel.
Enable/Disable channel	You can enable/disable a channel at any time. When this channel is disabled the SMS Messaging Server service will stop sending messages through this channel.
Host	The host name or IP address of the SMTP server. For instance "smtp.yourdomain.dom" or "192.168.1.1".
Secure mail server	Should be checked when the mail server requires a secure (SSL/TLS) connection.
Mail server requires authentication	Some SMTP servers require authentication before you can actually send SMTP messages. When you enable it, you must also provide a valid 'Account' and 'Password'.
Account Name	The Account Name property is used to log on to the SMTP server.
Password	The Password property is used to log on to the SMTP server.
Name	Friendly name of the sender. It will be shown as the sender's friendly name by most POP3 clients.
E-mail Address	E-mail address. This address will appear as the sender's address by the recipient's POP3 client.
Reply Address	Reply address. If this address is not set the 'E-mail Address' field will be used as the reply address.

4.9. File Channels

File channels are very usefull when messages are delivered to the system as files in a directory. The file channel will read the file from the directory and add it to the message database as a new record. This way you can fire a trigger on an incoming text file.

After a file is read, the following two items are stored into a new incoming Message record:

• File name is stored in the 'FromAddress' field of the Message record;
• Body of the file (i.e. the file content) is stored in the 'Body' field of the Message record.

After the incoming Message is created and ready to be processed by a Trigger. The file will be deleted.

This channel supports unicode files if they are encoded as UCS-2 Little Endian.

File Settings:

Item	Description
Description	A description for this channel.
Enable/Disable channel	You can enable/disable a channel at any time. When the channel is disabled, the SMS Messaging Server service will stop receiving messages through this channel.
Directory	The directory to check for new text files.
File Specs	This specifies the pattern for the file names that need to be picked up.
Max Size	Specifies the maximum number of KB's that will be read from a file.
Check every ..	Specifies how often the directory will be checked for new files.

4.10. Triggers

To add/edit/delete a trigger:

1. Launch the SMS Messaging Server Manager application from the Start menu;
2. Open the Configurations folder and click on Triggers.

The following Items can be configured in the Trigger dialog:

Item	Description
Enable this trigger	Enable or disable the trigger. When the trigger is disabled the associated VBScript file will not invoked.
Description	A friendly description for this trigger.
Condition	A SQL like expression. Incoming messages that match the condition will be processed by the VBScript program (see below).
Script	Relative path to the VBScript file.

Triggers are processed one-by-one. For each incoming message, the top-most trigger is processed. To change the processing order of the triggers, click on the Change Processing Order item.

For more information on how to write your own triggers, read Projects and Triggers.

4.11. Routing

Routing can be used to specify general rules for outgoing messages. To see the routing rules:

1. Launch the SMS Messaging Server Manager application from the Start menu.
2. Open the Configurations folder and click on Routing.

In this window routing rules can be individually enabled or disabled en edited. To add routing rules click on 'Add route...'.

A routing rule has the following configurable items:

Item	Description
Field	The field or property of the outgoing message this rule will apply to. This can be one of the following: From The 'from' address or phone number To The 'to' address or phone number Cc The Carbon Copy (cc) field. Only applies to e-mail messages Bcc The Blind Carbon Copy (bcc) field. Only applies to e-mail messages Subject The subject field. Only applies to e-mail messages Body The message body
Condition	The condition that needs to be true on the selected field in the outgoing message to trigger this rule. The condition is used in combination with the text specified in 'value'. The condition can be one of the following: INCLUDES Includes the specified text NOT INCLUDES Does not include the specified text STARTS WITH Starts with the specified text NOT STARTS WITH Does not start with the specified text EQUALS Equals the specified text NOT EQUALS Does not equal the specified text
Value	This is used in combination with 'condition' and 'field' to create an expression which should evaluate to true for this routing rule to be triggered.
Channel	Which channel the message should be routed to when this rule is triggered. This will be either on of the existing channels or the 'Round-Robin' option. The Round-Robin option will select every available channel in turn. Each following message will be send to the next channel.
Type	The channel type that should be used. In combination with Round-Robin you can have the rule only select channels of type 'SMS' or 'EMAIL'
Description	A custom description of this rule. This can be a user defined string which may describe this rule or the motivation for this rule.

4.12. Blocking

Blocking can be used to block outgoing messages. To see the blocking rules:

1. Launch the SMS Messaging Server Manager application from the Start menu.
2. Open the Configurations folder and click on Blocking.

In this window blocking rules can be individually enabled or disabled en edited. To add blocking rules click on 'Add item...'.

A blocking rule has the following configurable items:

Item	Description
Field	The field or property of the outgoing message this rule will apply to. This can be one of the following: From The 'from' address or phone number To The 'to' address or phone number Cc The Carbon Copy (cc) field. Only applies to e-mail messages Bcc The Blind Carbon Copy (bcc) field. Only applies to e-mail messages Subject The subject field. Only applies to e-mail messages Body The message body
Condition	The condition that needs to be true on the selected field in the outgoing message to trigger this rule. The condition is used in combination with the text specified in 'value'. The condition can be one of the following: INCLUDES Includes the specified text NOT INCLUDES Does not include the specified text STARTS WITH Starts with the specified text NOT STARTS WITH Does not start with the specified text EQUALS Equals the specified text NOT EQUALS Does not equal the specified text
Value	This is used in combination with 'condition' and 'field' to create an expression which should evaluate to true for this blocking rule to be triggered.
Description	A custom description of this rule. This can be a user defined string which may describe this rule or the motivation for this rule.

4.13. Options

To change the General Program Options:

1. Launch the SMS Messaging Server Manager application from the Start menu;
2. Open the Configurations folder and click on Options.

In the Options dialog you can configure the following items:

Item	Description
Logging Enabled/Disabled	Enable or disable logging.
Log to File / Log to Database	Choose whether the software should write logging information to a plain ASCII file or to an OLE/DB compliant database.
Log Directory	Directory where Log files should be written. Each record is written as a single line to a plain ASCII file. Fields are separated by a configurable separator.
Field separator	Only used when 'Log to File' is selected. The 'Field separator' separates the fields of one line in the ASCII log file.
Maximum Size	Maximum size of a Log File. When this maximum size is exceeded a new Log File will be created.
Temporary Files Directory	Location of the directory where the service can write its temporary files. This field should be left default unless you want to improve performance by writing the temporary files to a faster drive.
Queue Files Directory	Location of the directory where the service writes incoming and outgoing messages. To improve performance, you can assign a different directory (for instance: a high-speed RAID configuration).
Message Database configuration	For more information on the Message Database configuration, please read Message Database.
Archive Database configuration	For more information on the Archive Database configuration, please read Message Database.

5. Send and Receive

5.1. Introduction

Before sending or receiving SMS or E-mail messages one or more channels need to be set up to send or receive the message through. Find more information about setting up channels here.

Receiving messages

After setting up the channel configuration messages will be automatically received by the SMS Messaging Server service application. The service will add all incoming messages to the message database and execute triggers when applicable.

Sending messages

Sending messages is just a matter of adding messages to the message database. The SMS Messaging Server service application will pickup any newly added messages and send them out through the appropriate channel automatically. The service will first apply any blocking rules that may have been configured. Next it will apply the routing rules for all of the messages that are not blocked. The messages that are not explicitly matched by a routing rule will be routed 'round-robin' over all available and compatible channels.

Messages can be added to the message database by either using the manager, using the bulk wizard, using the API and by directly adding messages to the message database. The following sections will explain these options in detail.

5.2. Using the manager

When in the SMS Messaging Server manager application you can send out an e-mail or SMS message at any time by right-clicking on the message table and selecting 'New message...'. This will open the 'Create new message' dialog. From this dialog you can create one or more SMS or e-mail messages that will be added to the message database.

The dialog offers the option to either create the new message(s) directly or to 'Create using Script'. The first option will add new messages to the database. The second option will create a VBScript which can be run from the command line to programmatically add the message to the database. The 'Create using Script' options is especially useful to create a template for a script.

5.3. Using the Bulk Wizard

For sending out a large amount of customized SMS messages or e-mail messages you can use the Bulk Wizard. The bulk wizard is designed to be able to connect to a number of data sources such as any ADO compatible database (MSSQL, MySQL, etc..), Excel spreadsheets or CSV files. By following the steps in the wizard it is easy to send out large numbers of customized or personalized messages.

The Bulk Wizard will ultimately add all of the generated messages into the message database by using the public API. The service will pick them up and send them out.

5.4. Using the API

The SMS Messaging Server API is a simple way to add new messages and query existing messages in the message database as well as the archive database. This is an ActiveX based API which makes it accessible from most platforms that are available on MS Windows, such as C++, C#, VB and VB.Net. It's also easy to use from script based languages like Javascript, VBScript and Powershell.

The main advantage for using the API is that it abstracts away from the database layer. When using the API the user does not need to know where the database is located. Also, more complex aspects, such as the optional TLV values for messages that are beeing sent or received through SMPP. are wrapped in accessible objects.

Find more information and examples about using the API here. There are also a great number of examples included in our installation package here.

5.5. Using the database

To sent SMS or E-mail messages through the SMS Messaging server from a Linux or Unix host there's also the possibility to insert new messages directly into the message database. For all fields there are sensible defaults, so to insert a message into the database which needs to be picked up by the service only a small number of fields needs to be set.

For example. To send a new message to "+440123456789" this SQL statement will suffice:

  INSERT INTO Messages 
    (Body, ToAddress, DirectionID, TypeID, StatusID) 
  VALUES 
    ('Hello, World', '+440123456789', 2, 1, 1);

This inserts a new message into the database with the body text 'Hello, World', which will be send to '+440123456789'. The direction id of '2' indicates this is an outgoing messages. The type-id of '1' indicated this is an SMS message. Find the values for these constants here.

Find more information about the message database and all of the fields that are can be used here.

6. Message Database

6.1. Introduction

The Message Database contains all incoming and outgoing SMS- and e-mail messages. Out of the box it is an MS Access database, but it can be migrated easily to MS SQL Server at any time.

The location of the messages is indicated by a DSN connection string, defined in the Options of the software. To see the location of the database:

• Start the Manager application;
• Open the Configuration Folder and select Databases;
• Click on the Message Database link.

The Message Database that is shipped with the installation is called MESSAGES.MDB and is located in the <INSTALL-DIR>\MSG directory.

The Message Database contains 6 tables:

• Table Messages - all incoming and outgoing SMS- and e-mail messages;
• Tables DirectionIDs, Status, StatusDetails, Type and BodyFormat - definitions tables used for various fields of the 'Messages' table.

6.2. 'Messages' Table

The Messages table contains the following fields:

Field	Type	Description
ID	Auto Number	Record primary key. This value is automatically generated when a new record is inserted.
DirectionID	Number	Message direction: Incoming or outgoing. Values are defined in the 'Directions' table (see below).
TypeID	Number	Message type: SMS or e-mail. Values are defined in the 'Type' table (see below).
StatusID	Number	Status of the message. Status is can be Pending, Success or Failed. Values are defined in the 'Status' table (see below).
StatusDetailsID	Number	Detailed information about the status. The 'StatusDetails' field gives detailed information what happened with the message, the reason for failure etc., whereas the 'Status' only indicates the global status (success, failure or pending). Values are defined in the 'StatusDetails' table (see below).
ChannelID	Number	For incoming messages: The channel that received the message. For outgoing, scheduled messages: Preferred channel. If you set this value to 0, the first available channel will pickup the message. For outgoing, sent/failed messages: The channel that picked up the message to deliver it to the recipient.
BillingID	String	Only used for outgoing messages. When using the Manager application the BillingID is taken from the following registry key: HKCU\Software\ActiveXperts\SMS Messaging Server\Billing\BillingID. This registry entry is set on installation, but can be changed at any time.
MessageReference	Memo	Message reference(s) assigned by the provider. For multipart messages multiple message references will be separated by ','.
ScheduledTimeSecs	Number	Scheduled time (in seconds after 01/01/1970). Used for outgoing messages only. 0 indicates: immediate send.
LastUpdateSecs	Number	Last update time (in seconds after 01/01/1970). Each time a record is updated by the software, this property is updated automatically.
FromAddress	String	Sender address of the message.
Priority	Number	Priority of outgoing messages. A lower number is a higher priority and will be scheduled before lower priorities (higher numbers).
ReadReceipt	Boolean	Request a read recipient. Only applies to e-mail messages.
ToAddress	String	Recipient address of the message. Multiple addresses are allowed; use a comma or semicolon as a separator.
Subject	String	Subject of the message (only applicable for e-mail messages).
BodyFormatID	Number	Body-format of the message. Values are defined in the 'Bodyformats' table (see below).
CharsetID	Number	Character set of the message. Values are defined in the 'Charset' table (see below).
Modifier	Number	Additional optional modifiers. This is a BIT field and the values are OR'ed together. Currently the only modifier available is the FLASH modifier for SMS Messages which is defined as '1'.
Header	Memo	Header of an incoming e-mail message. Header is not used with SMS messages and outgoing e-mail messages
Body	Memo	Body of the message. This can include ASCII text data as well as binary data.
Trace	Memo	Trace of the message. This multi-line field contains the progress of a message, including date and time.
CustomField1	Number	User field. Available to use for any purpose
CustomField2	String	User field. Available to use for any purpose
sysLock, sysHash, sysArchive	Boolean	Internal use.

6.3. Other Tables

The Message Database has 6 tables. The Messages table is the most important one. The other 5 tables are: Directions, Status, StatusDetails, Type and BodyFormat - definitions tables used for various fields of the 'Messages' table.

Table: Directions

The Directions table contains definitions for the direction of a message:

Field	Type	Values
Direction	Number	0 - Undefined. 1 - Incoming. 2 - Outgoing.

Table: Type

The Type table contains definitions for the type of a message:

Field	Type	Values
Type	Number	0 - Undefined. 1 - SMS. 3 - E-mail.

Table: Status

The Status table contains definitions for the status of a message:

Field	Type	Values
Status	Number	0 - Undefined. 1 - Pending. 2 - Success. 3 - Failure.

Table: StatusDetails

The StatusDetails table contains definitions for the status details of a message:

Field	Type	Values
StatusDetails	Number	0 - Undefined. 100 - Received; waiting to be processed. 101 - Received; processed successfully 102 - Received; no processing required, no triggers defined 103 - Received; processing failure 104 - Received; no processing required, no trigger condition matched 110 - Received; processing failure 200 - Scheduled. 201 - Queued. 202 - Submitted, waiting provider response. 203 - Submitted, waiting for delivery report. 210 - Generic error. 211 - No channel can handle this message. 212 - Message undeliverable. 213 - Delivery failed. 214 - Delivery timed out. 216 - Blocked. 216 - No more credits. 220 - Sent. 221 - Delivered. 255 - Locked by the system.

The difference between Sent and Delivered is in receiving a delivery report. When a delivery reports is received for a message and the delivery report contains the status 'delivered' the message was delivered. If the report contains the status 'accepted', 'unknown' or 'sent'. It is was send but whether or not is was delivered is unknown. The message status will be set to 'Sent'

When Request Delivery Report is not enabled the final status for a successfully sent message is always 'Sent'.

Table: BodyFormats

The BodyFormats table contains definitions for the body format of a message:

Field	Type	Values
Format	Number	0 - Text (Normal). 2 - Data. 6 - WAP Push. 200 - HTML.

Table: Charsets

The Charsets table contains definitions for the character set of a message:

Field	Type	Values
Format	Number	1 - Channel default. 2 - Unicode.

Table: Modifiers

The Modifiers table contains definitions for the modifiers of a message:

Field	Type	Values
Format	Number	1 - (SMS) Flash message.

Table: ReportLookup

The ReportLookup table contains the message references for messages that are waiting for a delivery report. This table is used by the SMS Messaging Server service to able to quickly match incoming delivery reports.

Field	Type	Values
MessageId	Number	The message id.
Reference	Text	The message reference.
ChannelId	Number	The channel id this message was sent on.
CreateTime	Number	Time this record was created.

6.4. Archiving Messages

Database Archiving can improve performance when dealing with a large Message Database.

Consider an SMS Messaging Server scenario where more than 1000 SMS messages are broadcasted daily. It would end up with a database of 50.000 messages after one month and over a 500.000 messages after a year. Most probably you do not need instance access to these messages regularly. However, you do not want to delete these messages.

ActiveXperts SMS Messaging Servers' Archiving feature allows you to automatically archive messages. Archiving is a continuous process in the system. By default, messages are archived after 7 days: they are moved from the Message Database to the Archive Database.

To change the Archiving Settings:

1. Launch the Manager application from the Start menu, open the Configurations folder and click on Options.
2. Enable Archiving, Enable/disable archiving.
3. Archive after n Days. If archiving is enabled, all messages older than n days will be moved to the Archive Database.

To change the location of the archive database, open the Configurations folder, click on Databases and click on Archive Database. By default, this connection string is set to <INSTALL-DIR>\MSG\ARCHIVE.MDB.

6.5. Migrating the Database

Migrating to MS SQL or MySQL using the Manager

You can migrate the Message Database to MS SQL or MySQL using the 'MS SQL Migration Wizard' or 'MySQL Migration Wizard'.

To start the Migration Wizard:

1. Launch the Manager application from the Start menu, open the Server Tools folder and click on Database Migration.
2. Click on MS SQL Server on MySQL Server. A wizard will now guide you through the process of migrating the message Database.

Most people prefer to have a separate database for SMS Messaging Server on the database Server. However, you can choose to use an existing database that is already used for other purposes. You can even choose to have three separate databases: one for the message database, one for the archive database and one for the log database.

The actual migration of the MS Access database to MS SQL is performed by two VBScript programs, located in the <INSTALL-DIR>\SYS\MIGRATION SCRIPTS\ directory:

1. createdb.vbs - to create the database tables;
2. copydb.vbs - to move the records to the new database.

The Manager first launches createdb.vbs to create the database(s) and database tables. Then copydb.vbs is launched to move all records to the new database(s).

Migrating to MS SQL or MySQL from the command line

Advanced database user can also launch the database migration scripts from the command line instead of using the Manager to migrate the database to MS SQL.

To launch the script from the command line:

1. Launch a new console window, by typing cmd.exe in the Run field from the Windows Start Menu or select Command Prompt from the Windows Accessories Folder;
2. First launch createdb.vbs. When the script has completed successfully, launch copydb.vbs.

createdb.vbs

Usage:	createdb -h hostname -u [username ] -p [password ] -c [connector] -dm [Message-database] -da [archive-database] -dl [log-database]
Flags:	-h hostname Hostname or IP address of the (remote) MS SQL Server
	-u username Username used to log on on the (remote) MS SQL Server. Only required if you want to login to the MS SQL server using SQL Server Authentication. To use Windows authentication, do not use the -u option.
	-p password Password used for the user name as specified by the '-u' option.
	- c connector Connector to be used. Only applies to MySQL. If not specified, the following default is used: MySQL ODBC 5.1 Driver
	-dm message-database Name of the new message database.
	-da archive-database Name of the new archive database. Can be the same database name as specified by the '-dm' option.
	-dl log-database Name of the new log database. Can be the same database name as specified by the '-dm' option.
Example:	createdb -h sqlsrv02 -u sa -p topsecret -dm SmsDatabase -da SmsDatabase -dl SmsDatabase

copydb.vbs

Usage:	copydb -h hostname -u [username] -p [password] -c [connector] -dm [message-database] -da [archive-database] -dl [log-database]
Flags:	-h hostname : Hostname or IP address of the (remote) MS SQL Server
	-u username : Username used to log on on the (remote) MS SQL Server. Only required if you want to login to the MS SQL server using SQL Server Authentication. To use Windows authentication, do not use the -u option.
	-p password : Password used for the user name as specified by the '-u' option.
	-c connector : Connector to be used. Only applies to MySQL. If not specified, the following default is used: MySQL ODBC 5.1 Driver
	-dm message-database : name of the message database.
	-da archive-database : name of the archive database. Can be the same database name as specified by the '-dm' option.
	-dl log-database : name of the new database. Can be the same database name as specified by the '-dm' option.
Example:	copydb -h sqlsrv02 -u sa -p topsecret -dm SmsDatabase -da SmsDatabase -dl SmsDatabase

7. API

7.1. Introduction

The ActiveXperts SMS Messaging Server API defines an interface to its Messages Database. This makes it an Open System.

The API contains functions to filter, read, write, modify and delete messages in the Message Database.

A few scenario's where the API can be used:

• To send SMS messages from a 3rd party application.
• To implement triggers: as soon as a new message arrives in the system, the SMS Messaging Server will trigger a VBScript program (or multiple VBScript programs), based on a condition. This trigger can use the API to change the status of the incoming message, to create a reply message, etc.
• To define a custom ASP/ASP.NET based web interface, where web users can create new SMS messages and read/filter incoming messages.
• To send out a batch of SMS messages every morning, for instance to notify IT Administrators about the completion status of a backup, or to tell a department about upcoming meetings on that day.
• To build a customized user interface with various message views.

VBScript sample: Read SMS numbers from an MS Access database, and use these with SMS Messaging Server

To demonstrate how the API can be used, we start with a simple VBScript sample that shows how to send out SMS messages using mobile numbers from an MS Access Database.

Let's take an MS Access Database 'Students.mdb' that contains the following table:

ID#	FirstName	LastName	MobileNumber
8000	John	Doe	+440000000
8001	Edward	Smiths	+440000001
8002	Peter	Williams	+440000002

The following VBScript program reads the SMS numbers from the above database and creates new SMS message record for each number:

  Option Explicit
  
  Dim objConstants, objMessageDB, objMessageOut, strDatabase, objDBConnection, RS
  
  Set objConstants  = CreateObject( "AxMmServer.Constants" ) 
  Set objMessageDB  = CreateObject( "AxMmServer.MessageDB" ) 
  
  strDatabase = InputBox( "Enter the path to the Students MS Access database", _
                          "Enter Path", "c:\temp\students.mdb" )
  If( strDatabase = "" ) Then
     WScript.Echo "Finished. "
     WScript.Quit
  End If
  
  objMessageDB.Open
  WScript.Echo "Open Message Database, result: " & objMessageDB.LastError
  If( objMessageDB.LastError <> 0 ) Then
     WScript.Echo "Finished. "
     WScript.Quit
  End If
  
  Set objDBConnection = CreateObject( "ADODB.Connection" )
  objDBConnection.Open "Driver={Microsoft Access Driver (*.mdb)}; DBQ=" & strDatabase & ";"
  
  Set RS = objDBConnection.Execute( "SELECT * FROM Students" )
  
  While Not RS.EOF
     Set objMessageOut = objMessageDB.Create
     WScript.Echo "New message created, result: " & objMessageDB.LastError
     If( objMessageDB.LastError = 0 ) Then
        objMessageOut.DirectionID = objConstants.MESSAGEDIRECTION_OUT
        objMessageOut.TypeID      = objConstants.MESSAGETYPE_SMS 
        objMessageOut.StatusID    = objConstants.MESSAGESTATUS_PENDING
        objMessageOut.ToAddress   = RS( "MobileNumber" )
        objMessageOut.ChannelID   = 0  ' Any available SMS channel
        objMessageOut.Body        = "Hello, world!"
        objMessageDB.Save objMessageOut
        WScript.Echo "Message #" & objMessageOut.ID & " saved, result: " & objMessageDB.LastError
     End If
  
     RS.MoveNext
  WEnd
  
  objMessageDB.Close
  WScript.Echo "Message Database closed."
  
  objDBConnection.Close
  
  WScript.Echo "Finished."

VB .NET sample: Read SMS numbers from an MS Access database, and use these with SMS Messaging Server

The same sample as in 8.1.1., converted to VB .NET:

  Module Module1
    Const STR_STUDENTSDATABASE = "c:\students\students.mdb"
  
    Sub Main()
  
      Dim objMessageDB As New AXMMCFGLib.XMessageDB()
      Dim objMessageDB As New AXMMCFGLib.XConstants()
      Dim objMessage As New AXMMCFGLib.XMessage()
      Dim objConn As New ADODB.Connection()
      Dim objRs As New ADODB.Recordset()
  
      objMessageDB.Open()
      Console.WriteLine("Open, result: " & objMessageDB.LastError)
      If (objMessageDB.LastError <> 0) Then
        GoTo _EndMain
      End If
  
      objConn.ConnectionString = "Driver={Microsoft Access Driver (*.mdb)}; DBQ=" & _
            STR_STUDENTSDATABASE & ";"
      objConn.Open()
      objRs = objConn.Execute("SELECT * FROM Students")
  
      Do While Not objRs.EOF
        Console.WriteLine(objRs("MobileNumber").Value)
  
        objMessage = objMessageDB.Create
        Console.WriteLine("New message created, result: " & objMessageDB.LastError)
        If (objMessageDB.LastError = 0) Then
          objMessage.DirectionID = objConstants.MESSAGEDIRECTION_OUT
          objMessage.TypeID = objConstants.MESSAGETYPE_SMS
          objMessage.StatusID = objConstants.MESSAGESTATUS_PENDING
          objMessage.ToAddress = objRs("MobileNumber").Value
          objMessage.ChannelID = 0  ' Any available SMS channel
          objMessage.Body = "Hello, world!"
          objMessageDB.Save(objMessage)
          Console.WriteLine("Message #" & objMessage.ID & " saved, result: " & _
            objMessageDB.LastError)          
        End If
        
        objRs.MoveNext()
      Loop
  
      _EndMain:
        objMessageDB.Close()
  
    End Sub
  End Module

7.2. Classes

The SMS Messaging Server API is a collection of classes. Each class has several properties and functions ('methods') defined.

The following three classes are the most used classes in the API:

Class: MessageDB

This class represents the Message Database, i.e. the collection of all Message Records in the database. Please read 'MessageDB Class' for a complete overview of all properties and methods of this class.

Class: Message

This class represents a single Message record in the Message Database. The class provides properties, where each property represents a single records field. Please read 'Message Class' for a complete overview of all properties and methods of this class.

Class: Constants

This class defines all contants used in the API. There are constants for status information, for body formats, etc. Please read 'Constants Class' for a complete overview of all properties and methods of this class.

The following classes can be used to view and modify all SMS Messaging Server configuration items:

Administration Classes

The ActiveXperts SMS Messaging Server provides access to all its configuration items, through the API. The classes allow you to view and modify channels, triggers, and general options.

7.3. MessageDB Class

Properties

Property	Type	Description
LastError	number	Completion code of the last called function.

Functions

Function	Description
Open	Open the Message Database.
Close	Close the Message Database.
Count	Count messages in the Message Database.
Create	Create a new message in the Message Database.
Delete	Delete a message.
Load	Load a message.
FindFirstMessage	Return the first message that matches the condition.
FindNextMessage	Returns the next message that matches the condition.
GetDirectionDescription	Look-up the friendly description of the given description code.
GetTypeDescription	Look-up the friendly description of the given type-code.
GetStatusDescription	Look-up the friendly description of the given status-code.
GetBodyFormatDescription	Look-up the friendly format description of the given body format code.

LastError property

Completion code of the last called function. To find the error description of a given error code, go to the online error codes codes page.

Example:

   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
   Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
  
   ...

Open function

Open the Message Database. You must open the message database before you can perform any operation on the Message Database, like counting records, creating new records, deleting records, etc. When you're finished accessing the database, you must call Close in order to close the database.

Parameters:

  ReadWrite (Optional, Boolean). Default is true; false opens the database for read only.

Return value:

  Always 0. Check LastError property to see if the function was completed successfully.

Example:

  Option Explicit
  
  Dim objMessageDB
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  ...
  
  objMessageDB.Close                                         ' Close the Database
  WScript.Echo "Closed."

Close function

Close the Message Database. You must call this function to close the Message Database that was open by the Open call.
You can even call this function if a preceding Open was not completed successfully (the function will then simply be ignored).

Parameters:

  None.

Return value:

  Always 0. Check LastError property to see if the function was completed successfully.

Example:

  Option Explicit
  
  Dim objMessageDB
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  ...
  
  objMessageDB.Close                                         ' Close the Database
  WScript.Echo "Closed."

Count function

Count the number of messages in the Message Database. You can apply a filter. When an empty string is passed as filter, all messages are filtered. For more information about filters, click here.

Parameters:

  Filter (String) - A message filter. Pass an empty string to filter all messages.

Return value:

  Number of messages. Check LastError property to see if the function was completed successfully.

Example:

     Option Explicit
  
     Dim objMessageDB, objConstants, numRecords
     Dim strFilter
  
     Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
     Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
     objMessageDB.Open 
     WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
     If( objMessageDB.LastError <> 0 ) Then
        WScript.Quit
     End If
  
     ' Count all messages in the database with direction Outgoing and status Success 
     strFilter = "DirectionID=" & objConstants.MESSAGEDIRECTION_IN & " AND " & _
                 "StatusID=" & objConstants.MESSAGESTATUS_SUCCESS
     numRecords = objMessageDB.Count( strFilter )               ' Count the records
     WScript.Echo "Count, result: " &  objMessageDB.LastError   
     If( objMessageDB.LastError <> 0 ) Then
        objMessageDB.Close
        WScript.Quit
     End If
  
     WScript.Echo "Number of messages: " &  numRecords  
  
     objMessageDB.Close                                         ' Close the Database
     WScript.Echo "Closed."                                     
  

Create function

Create a new message in the Message Database.

Parameters:

  None.

Return value:

  A new Message object. Check LastError property to see if the function was completed successfully.

Example:

  Option Explicit
  
  Dim objMessageDB, objMessage, objConstants
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError       ' Open the Database
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  Set objMessage   = objMessageDB.Create
  WScript.Echo "Create, result: " & objMessageDB.LastError
  If( objMessageDB.LastError <> 0 ) Then
    objMessageDB.Close
    WScript.Quit
  End If  
  
  WScript.Echo "Message successfully created, recordID: " & objMessage.ID
  
  objMessage.DirectionID  = objConstants.MESSAGEDIRECTION_OUT
  objMessage.TypeID       = objConstants.MESSAGETYPE_SMS
  objMessage.StatusID     = objConstants.MESSAGESTATUS_PENDING
  objMessage.ToAddress    = "+31624896641"
  objMessage.Body         = "Test message"
  
  objMessageDB.Save( objMessage )
  WScript.Echo "Save, result " & objMessageDB.LastError
  
  objMessageDB.Close
  WScript.Echo "Closed."

Delete function

Delete a message from the Message Database. You can apply a filter. When an empty string is passed as filter, all messages are deleted. For more information about filters, click here.

Parameters:

  Filter (String) - A message filter. Pass an empty string to filter all messages.

Return value:

  Always 0. Check LastError property to see if the function was completed successfully.

Example:

  Option Explicit
  
  Dim objMessageDB, objConstants
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  objMessageDB.Delete( "ID > 46 And ID < 49" )               ' Delete Message with ID=47 or ID=48
  WScript.Echo "Delete, result: " & objMessageDB.LastError
  
  objMessageDB.Close                                         ' Close the Database
  WScript.Echo "Closed."

Load function

Load a message from the Message Database.

Parameters:

  Message ID (Number) - Record ID of the message in the Messages database

Return value:

  A new Message object. Check LastError property to see if the function was completed successfully.

Example:

  Option Explicit
  
  Dim objMessageDB, objMessage, objConstants
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  Set objMessage   = objMessageDB.Load( 5 )                  ' Load Message with Message ID 5
  WScript.Echo "Load, result: " & objMessageDB.LastError
  If( objMessageDB.LastError <> 0 ) Then
    objMessageDB.Close
    WScript.Quit
  End If  
  
  WScript.Echo "Message successfully loaded, ID: " & objMessage.ID
  
  objMessageDB.Close
  WScript.Echo "Closed."

FindFirstMessage function

Find messages in the Message Database. You can apply a filter to filter messages. When an empty string is passed as filter, all messages are selected. The filter can be formatted as an SQL 'WHERE' clause.

Parameters FindFirstMessage:

  Filter (String)          - A message filter. Pass an empty string to find all messages.
  Order (String, Optional) - Indicates how the results are sorted. 
                             Examples: "Sender", "Sender ASC", "Recipient DESC", "ID ASC, Sender DESC"
  Top (Number, Optional)   - Set a limit to the number of records in the result.

Return value:

  A new Message object. Check LastError property to see if the function was completed successfully.

Example:

  Option Explicit
  
  Dim objMessageDB, objMessage, objConstants
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  ' Open the Database
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError    
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  ' Find all messages
  ' Start with the first message that matches the qualification
  Set objMessage = objMessageDB.FindFirstMessage( "" )     
  While( objMessageDB.LastError = 0 ) 
    WScript.Echo "Message found: " & objMessage.ID
    WScript.Echo "  Sender: "    & objMessage.FromAddress
    WScript.Echo "  Recipient: " & objMessage.ToAddress
    ' Find next message
    Set objMessage = objMessageDB.FindNextMessage()        
  WEnd  
  
  ' Find all outgoing messages sorted on Status (Ascending)
  WScript.Echo vbCrLf
  Set objMessage = objMessageDB.FindFirstMessage( "DirectionID = " & _
                   objConstants.MESSAGEDIRECTION_OUT, "Status ASC" )
  While( objMessageDB.LastError = 0 ) 
    WScript.Echo "Message found: " & objMessage.ID
    WScript.Echo "  Sender: "    & objMessage.FromAddress
    WScript.Echo "  Recipient: " & objMessage.ToAddress
    Set objMessage   = objMessageDB.FindNextMessage()  
  WEnd  
  
  objMessageDB.Close
  WScript.Echo "Closed."

FindNextMessage function

Find messages in the Message Database. You can apply a filter to filter messages. When an empty string is passed as filter, all messages are selected. The filter can be formatted as an SQL 'WHERE' clause.

Parameters FindNextMessage:

   None.

Return value:

   A new Message object. Check LastError property to see if the function was completed successfully.

Example:

  Option Explicit
  
  Dim objMessageDB, objMessage, objConstants
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  ' Open the Database
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError    
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  ' Find all messages
  ' Start with the first message that matches the qualification
  Set objMessage = objMessageDB.FindFirstMessage( "" )     
  While( objMessageDB.LastError = 0 ) 
    WScript.Echo "Message found: " & objMessage.ID
    WScript.Echo "  Sender: "    & objMessage.FromAddress
    WScript.Echo "  Recipient: " & objMessage.ToAddress
    ' Find next message
    Set objMessage = objMessageDB.FindNextMessage()        
  WEnd  
  
  ' Find all outgoing messages sorted on Status (Ascending)
  WScript.Echo vbCrLf
  Set objMessage = objMessageDB.FindFirstMessage( "DirectionID = " & _
                   objConstants.MESSAGEDIRECTION_OUT, "Status ASC" )
  While( objMessageDB.LastError = 0 ) 
    WScript.Echo "Message found: " & objMessage.ID
    WScript.Echo "  Sender: "    & objMessage.FromAddress
    WScript.Echo "  Recipient: " & objMessage.ToAddress
    Set objMessage   = objMessageDB.FindNextMessage()  
  WEnd  
  
  objMessageDB.Close
  WScript.Echo "Closed."

GetDirectionDescription function

GetDirectionDescription returns the friendly description of the given Direction.

Parameters:

  A numeric code.

Return value:

  The description string.

Example:

  Option Explicit
  
  Dim objMessageDB, objMessage, objConstants
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" )
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  ' Find first message that matches the qualification
  Set objMessage   = objMessageDB.FindFirstMessage( "" )     
  If( objMessageDB.LastError = 0 ) Then
    WScript.Echo "Messgage ID: " & objMessage.ID
    WScript.Echo "Direction ID: " & objMessage.DirectionID
    WScript.Echo "Direction string: " & _
          objMessageDB.GetDirectionDescription( objMessage.DirectionID )
    WScript.Echo "TypeID: " & objMessage.TypeID
    WScript.Echo "Type string: " & objMessageDB.GetTypeDescription( objMessage.TypeID )
    WScript.Echo "StatusID: " & objMessage.StatusID
    WScript.Echo "Status string: " & objMessageDB.GetStatusDescription( objMessage.StatusID )
    WScript.Echo "BodyFormatID: " & objMessage.BodyFormatID
    WScript.Echo "BodyFormat string: " & _
          objMessageDB.GetBodyFormatDescription( objMessage.BodyFormatID )
  End If  
  
  objMessageDB.Close
  WScript.Echo "Closed."

GetTypeDescription function

GetTypeDescription returns the friendly description of the given Type.

Parameters:

  A numeric code.

Return value:

  The description string.

Example:

  Option Explicit
  
  Dim objMessageDB, objMessage, objConstants
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" )
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  ' Find first message that matches the qualification
  Set objMessage   = objMessageDB.FindFirstMessage( "" )     
  If( objMessageDB.LastError = 0 ) Then
    WScript.Echo "Messgage ID: " & objMessage.ID
    WScript.Echo "Direction ID: " & objMessage.DirectionID
    WScript.Echo "Direction string: " & _
          objMessageDB.GetDirectionDescription( objMessage.DirectionID )
    WScript.Echo "TypeID: " & objMessage.TypeID
    WScript.Echo "Type string: " & objMessageDB.GetTypeDescription( objMessage.TypeID )
    WScript.Echo "StatusID: " & objMessage.StatusID
    WScript.Echo "Status string: " & objMessageDB.GetStatusDescription( objMessage.StatusID )
    WScript.Echo "BodyFormatID: " & objMessage.BodyFormatID
    WScript.Echo "BodyFormat string: " & _
          objMessageDB.GetBodyFormatDescription( objMessage.BodyFormatID )
  End If  
  
  objMessageDB.Close
  WScript.Echo "Closed."

GetStatusDescription function

GetStatusDescription returns the friendly description of the given Status.

Parameters:

  A numeric code.

Return value:

  The description string.

Example:

  Option Explicit
  
  Dim objMessageDB, objMessage, objConstants
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" )
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  ' Find first message that matches the qualification
  Set objMessage   = objMessageDB.FindFirstMessage( "" )     
  If( objMessageDB.LastError = 0 ) Then
    WScript.Echo "Messgage ID: " & objMessage.ID
    WScript.Echo "Direction ID: " & objMessage.DirectionID
    WScript.Echo "Direction string: " & _
          objMessageDB.GetDirectionDescription( objMessage.DirectionID )
    WScript.Echo "TypeID: " & objMessage.TypeID
    WScript.Echo "Type string: " & objMessageDB.GetTypeDescription( objMessage.TypeID )
    WScript.Echo "StatusID: " & objMessage.StatusID
    WScript.Echo "Status string: " & objMessageDB.GetStatusDescription( objMessage.StatusID )
    WScript.Echo "BodyFormatID: " & objMessage.BodyFormatID
    WScript.Echo "BodyFormat string: " & _
          objMessageDB.GetBodyFormatDescription( objMessage.BodyFormatID )
  End If  
  
  objMessageDB.Close
  WScript.Echo "Closed."

GetBodyFormatDescription function

GetBodyFormatDescription returns the friendly description of the given BodyFormat.

Parameters:

  A numeric code.

Return value:

  The description string.

Example:

  Option Explicit
  
  Dim objMessageDB, objMessage, objConstants
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" )
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  ' Find first message that matches the qualification
  Set objMessage   = objMessageDB.FindFirstMessage( "" )     
  If( objMessageDB.LastError = 0 ) Then
    WScript.Echo "Messgage ID: " & objMessage.ID
    WScript.Echo "Direction ID: " & objMessage.DirectionID
    WScript.Echo "Direction string: " & _
          objMessageDB.GetDirectionDescription( objMessage.DirectionID )
    WScript.Echo "TypeID: " & objMessage.TypeID
    WScript.Echo "Type string: " & objMessageDB.GetTypeDescription( objMessage.TypeID )
    WScript.Echo "StatusID: " & objMessage.StatusID
    WScript.Echo "Status string: " & objMessageDB.GetStatusDescription( objMessage.StatusID )
    WScript.Echo "BodyFormatID: " & objMessage.BodyFormatID
    WScript.Echo "BodyFormat string: " & _
          objMessageDB.GetBodyFormatDescription( objMessage.BodyFormatID )
  End If  
  
  objMessageDB.Close
  WScript.Echo "Closed."

7.4. Message Class

Properties

Property	Type	Description
ID	Number	ID of the message.
DirectionID	Number	Message direction. Incoming or outgoing.
TypeID	Number	Type of message. SMS or E-mail.
StatusID	Number	Status of a message.
StatusDetailsID	Number	Additional detailed information about the status of a message.
ChannelID	Number	Channel ID of the Channel that sent/received the message.
BillingID	String	Billing ID used for accounting.
MessageReference	String	Used internally by the service to check the delivery reports.
ScheduledTimeSecs	Number	Scheduled time in seconds after 01/01/1970.
LastUpdateSecs	Number	Last update time in seconds after 01/01/1970.
SentTimeSecs	Number	Sent time in seconds after 01/01/1970.
ReceivedTimeSecs	Number	Receive time in seconds after 01/01/1970.
FromAddress	String	Sender address of the message.
Priority	Number	The message priority.
ReadReceipt	Boolean	Request a read recipient. Only applies to e-mail messages.
ToAddress	String	Recipient address of the message.
CcAddress	String	CC address of the message (only applies to e-mail messages).
BccAddress	String	BCC address of the message (only applies to e-mail messages).
Subject	String	Subject the message. Only applies to E-mail messages.
Header	String	Header the message. Only applies to incoming E-mail messages.
Body	String	The body message of the message.
BodyFormatID	Number	Format of the Message Body.
Charset	Number	Character set of the message.
Modifier	Number	Indicates the message modifiers
Trace	Memo	Trace information.
CustomField1	Number	Custom number field
CustomField2	String	Custom string field
LastError	Number	Completion code of the last called function.

Functions

Function	Description
Clear	Resets all properties of the object to the initial values.
AddTrace	Adds a trace line to the 'Trace' propery.
GetLastUpdateString	Returns the LastUpdateSecs property as a friendly string.
GetScheduleTimeString	Returns the ScheduledTimeSecs property as a friendly string.
GetTlv	Returns a TLV object for a specific Tag value
AddTlv	Add a TLV object to this message
GetFirstTlv	Get the first TLV attached to this message
GetNextTlv	Get the next TLV attached to this message

ID property

ID of the message. It is the unique record ID in the Messages database.

DirectionID property

Direction of the message. Click here to see a list of valid Direction values.

TypeID property

Type of message. Click here here to see a list of valid Type values.

StatusID property

Status of the message. Click here here to see a list of valid Status values.

StatusDetailsID property

Status details of the message. Click here here to see a list of valid StatusDetails values.

ChannelID property

The StatusDetails property gives you more detailed information about the status of a message. You should use the StatusID property to retrieve the status of a message. You can use the StatusDetails property to retrieve more detailed information.

For instance, when the StatusID is set to MESSAGESTATUS_FAILED, 'StatusDetails' will give you detailed information about the reason of the failure.
Click here to see a list of valid StatusDetails values.

BillingID property

Only used for outgoing messages. When using the Manager application, the BillingID is taken from the following registry key: HKCU\Software\ActiveXperts\SMS Messaging Server\Billing\BillingID. This registry entry is set on installation, but can be changed at any time.

MessageReference property

A unique string, assigned to each outgoing SMS message by the SMS Messaging Server service. This Message Reference is used by the system to check acknowledgement messages (status reports). When using a GSM modem its not the provider message reference but our own.

ScheduledTimeSecs property

Scheduled time (in seconds after 01/01/1970). Used for outgoing messages only. 0 indicates: immediate send. Use GetScheduleTimeString to get a friendly string representation of this property.

LastUpdateSecs property

Last update time (in seconds after 01/01/1970). Each time a record is updated, this property is updated automatically. Use GetLastUpdateStringString to get a friendly string representation of this property.

SentTimeSecs property

Sent time (in seconds after 01/01/1970). This time is set when the message is sent throught the channel.

ReceivedTimeSecs property

Receive time (in seconds after 01/01/1970). This time is set when the message is received by the channel.

FromAddress property

Sender address of the message. Can be either an e-mail address or SMS number (depends on the type of message).

Priority property

The message priority. Click here to see a list of valid Priority values.

ReadReceipt property

Request a read receipt. Only applies to e-mail messages.

ToAddress property

Recipient address of the message. Can be either an e-mail address or SMS number (depends on the type of message).

CcAddress property

CC address of the message (only applies to e-mail messages).

BccAddress property

BCC address of the message (only applies to e-mail messages).

Subject property

The subject of the message. This value only applies to e-mail messages; it is ignored for SMS messages.

Header property

The header of a message. This header information is only used for incoming e-mail messages.

Body property

Actual body of the message. Can be either ASCII data (for e-mail messages and regular SMS messages) or binary data (for advanced SMS messages, like Unicode messages or WAP messages).

BodyFormatID property

Indicates the body format of the Body of the message. Use the BodyFormat property for instance to send out SMS messages as binary data instead of plain SMS. For a list of valid BodyFormat values, click here.

Charset property

Indicates the body character set.

Modifier property

Indicates which modifiers are active for this message. Currently there is only one modifier available namely the 'Flash' modifier for SMS messages. This modifier is defined as '1'.

Trace property

Trace of the message. This multi-line field contains the progress of a message, including date and time.

CustomField1 property

Custom number field. You can use this field to attach data related to your own business logic to a message.

CustomField2 property

Custom string field. You can use this field to attach data related to your own business logic to a message.

LastError property

The last error code. This property is used in combination with the Tlv functions

Clear function

Clear all properties.

Parameters:

   None.

Return value:

   Always 0.

Example:

  Option Explicit
  
  Dim objMessageDB, objMessage, objConstants
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  Set objMessage   = objMessageDB.FindFirstMessage( "" )     ' Find first message
  WScript.Echo "FindFirstMessage, result: " &  objMessageDB.LastError    
  If( objMessageDB.LastError <> 0 ) Then
    objMessageDB.Close
    WScript.Quit
  End If  
  
  WScript.Echo "Sender: " & objMessage.FromAddress
  
  objMessage.Clear                                           ' Clear the object
  
  WScript.Echo "Sender: " & objMessage.FromAddress
  
  objMessageDB.Close

AddTrace function

Adds a trace line to the Trace property. You do not need to add date and time, it will be done by the AddTrace function itself.

Parameters:

  The String that needs to be traced.

Return value:

  None.

Example:

  Option Explicit
  
  Dim objMessageDB, objMessage, objConstants
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  Set objMessage   = objMessageDB.FindFirstMessage( "" )     ' Find first message
  WScript.Echo "FindFirstMessage, result: " &  objMessageDB.LastError    
  If( objMessageDB.LastError <> 0 ) Then
    objMessageDB.Close
    WScript.Quit
  End If  
  
  WScript.Echo "Trace: " & objMessage.Trace
  
  objMessage.AddTrace( "Hello, world" )
  
  WScript.Echo vbCrLf
  WScript.Echo "Trace: " & objMessage.Trace
  
  objMessageDB.Save( objMessage )                            ' Save the modified message
  
  objMessageDB.Close

GetLastUpdateString function

Returns the LastUpdateSecs property as a friendly string.

Parameters:

  None.

Return value:

  The LastUpdateSecs property as a friendly string.

Example:

  Option Explicit
  
  Dim objMessageDB, objMessage, objConstants
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  Set objMessage   = objMessageDB.FindFirstMessage( "" )     ' Find first message
  WScript.Echo "FindFirstMessage, result: " &  objMessageDB.LastError    
  If( objMessageDB.LastError <> 0 ) Then
    objMessageDB.Close
    WScript.Quit
  End If  
  
  ' Print the LastUpdateSecs property, as a numeric value and as a friendly string
  WScript.Echo "LastUpdate: " & objMessage.LastUpdateSecs & _
          " (" & objMessage.GetLastUpdateString() & ")"
  
  objMessageDB.Close

GetScheduleTimeString function

Returns the ScheduledTimeSecs property as a friendly string.

Parameters:

  None

Return value:

  The ScheduledTimeSecs property as a friendly string

Example:

   Option Explicit
  
   Dim objMessageDB, objMessage, objConstants
  
   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
   Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
   If( objMessageDB.LastError <> 0 ) Then
      WScript.Quit
   End If
  
   Set objMessage   = objMessageDB.FindFirstMessage( "" )     ' Find first message
   WScript.Echo "FindFirstMessage, result: " &  objMessageDB.LastError    
   If( objMessageDB.LastError <> 0 ) Then
      objMessageDB.Close
      WScript.Quit
   End If  
  
  ' Print the ScheduledTimeSecs property, as a numeric value and as a friendly string
   WScript.Echo "ScheduleTime: " & objMessage.ScheduledTimeSecs & _
        "(" & objMessage.GetScheduleTimeString() & ")"
  
   objMessageDB.Close

GetTlv function

Get a specific TLV from this message

Parameters:

  Tlv Tag value

Return value:

  Tlv object

Example:

  Option Explicit
    
   Dim objMessageDB, objMessage, objConstants, objTlv
  
   Const SENDER_NAME = 12345  
  
   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
   Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
   If( objMessageDB.LastError <> 0 ) Then
      WScript.Quit
   End If
  
   Set objMessage   = objMessageDB.FindFirstMessage( "" )     ' Find first message
   While objMessageDB.LastError = 0   
      ' Print billing information ..
      Set objTlv = objMessageDB.GetTLV(SENDER_NAME)
      Script.Echo "Message ID: " & objMessage.ID & " has Sender name: " & objTlv.ValueAsString
      Set objMessage = objMessageDB.FindNextMessage
   Wend
    
   objMessageDB.Close  

AddTlv function

Add a TLV to this message.

Parameters:

  Tlv

Return value:

  None

Example:

  Option Explicit
  
  Dim objMessageDB, objMessage, objConstants, objTlv
  
  Const SENDER_NAME = 12345
  
  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  objMessageDB.Open 
  WScript.Echo "Open, result: " &  objMessageDB.LastError       ' Open the Database
  If( objMessageDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  Set objMessage   = objMessageDB.Create
  WScript.Echo "Create, result: " & objMessageDB.LastError
  If( objMessageDB.LastError <> 0 ) Then
    objMessageDB.Close
    WScript.Quit
  End If  
      
  WScript.Echo "Message successfully created, recordID: " & objMessage.ID
  
  objMessage.DirectionID  = objConstants.MESSAGEDIRECTION_OUT
  objMessage.TypeID       = objConstants.MESSAGETYPE_SMS
  objMessage.StatusID     = objConstants.MESSAGESTATUS_PENDING                               
  objMessage.ToAddress    = "+31000000000"
  objMessage.Body         = "Test message"
  
  Set objTlv = CreateObject( "AxMmServer.TLV" ) 
  objTlv.Tag = SENDER_NAME
  objTlv.ValueAsString = "John"
  objMessage.AddTlv objTlv
  
  objMessageDB.Save( objMessage )
  WScript.Echo "Save, result " & objMessageDB.LastError
  
  objMessageDB.Close
  WScript.Echo "Closed."

GetFirstTlv function

Get the first TLV that was attached to this message.

Parameters:

  None

Return value:

  Tlv object

Example:

  Option Explicit
   Option Explicit
    
   Dim objMessageDB, objMessage, objConstants, objTlv
  
   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
   Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
   If( objMessageDB.LastError <> 0 ) Then
      WScript.Quit
   End If
  
   Set objMessage   = objMessageDB.FindFirstMessage( "" )     ' Find first message
   While objMessageDB.LastError = 0         
      Set objTlv = objMessage.GetFirstTlv
      While objMessage.LastError = 0
        WScript.Echo "Message ID: " & objMessage.ID & " has TLV: " & objTlv.Tag & _
          " Value: " & objTlv.ValueAsHexString
        Set objTlv = objMessage.GetNextTlv
      Wend
      Set objMessage = objMessageDB.FindNextMessage
   Wend
    
   objMessageDB.Close 

GetNextTlv function

Get the next TLV that was attached to this message.

Parameters:

  None

Return value:

  Tlv object

Example:

  Option Explicit
   Option Explicit
    
   Dim objMessageDB, objMessage, objConstants, objTlv
  
   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
   Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
   If( objMessageDB.LastError <> 0 ) Then
      WScript.Quit
   End If
  
   Set objMessage   = objMessageDB.FindFirstMessage( "" )     ' Find first message
   While objMessageDB.LastError = 0         
      Set objTlv = objMessage.GetFirstTlv
      While objMessage.LastError = 0
        WScript.Echo "Message ID: " & objMessage.ID & " has TLV: " & objTlv.Tag & _
          " Value: " & objTlv.ValueAsHexString
        Set objTlv = objMessage.GetNextTlv
      Wend
      Set objMessage = objMessageDB.FindNextMessage
   Wend
    
   objMessageDB.Close 

7.5. Tlv Class

Tlv's (Tag, Length, Value) are optional data which can be send or received with an SMS Message when using the SMPP channel.

While there are a number of Tlv's suggested in the SMPP specification they are mainly meant to support future or provider specific requirements.

To find out how to use a Tlv or what type of information is contained in the value part the Tag should be looked up in either the SMPP specification or you provider specific documentation.

Properties

Property	Type	Description
Length	Number	The length of the Value part
Tag	Number	The tag value for this Tlv
ValueAsString	Number	A string representation of this Tlv value
ValueAsHexString	Number	A binary representation of this Tlv value
ValueAsInt32	Number	An 32 bit unsigned integer representation of this Tlv value
ValueAsInt16	Number	An 16 bit unsigned integer representation of this Tlv value
ValueAsInt8	Number	An 8 bit unsigned integer representation of this Tlv value

Functions

Function	Description
Clear	Clears the Tlv tag, length and value

Length property

The length of the Value part. This property is readonly.

Tag property

The tag value for this Tlv. This is the identifying part of a Tlv

ValueAsString property

A string representation of this Tlv value. Before printing this on a console, make sure it supposed to be a string value by checking the tag value against your providers Tlv information.

ValueAsHexString property

A binary representation of this Tlv value. The binary is formatted as an hexadecimal string. E.g a Tlv value of the string 'John' will become: '4A6F686E00'.

ValueAsInt32 property

An 32 bit unsigned integer representation of this Tlv value

ValueAsInt16 property

An 16 bit unsigned integer representation of this Tlv value

ValueAsInt8 property

An 8 bit unsigned integer representation of this Tlv value

Clear function

Clears the Tlv tag, length and value

7.6. ArchiveDB Class

Once messages have been archived they can no longer be found through the MessageDB class. Instead they are now reachable from the ArchiveDB class.

Properties

Property	Type	Description
LastError	number	Completion code of the last called function

Functions

Function	Description
Open	Open the archive database
Close	Close the archive database
Count	Count messages in the archive database
Load	Load a message
FindFirstMessage	Returns the first message that matches the condition
FindNextMessage	Returns the next message that matches the condition

LastError property

Completion code of the last called function. To find the error description of a given error code, go to the online error codes codes page.

Example:

  Option Explicit
            
  Dim objArchiveDB, objConstants
            
  Set objConstants  = CreateObject( "AxMmServer.Constants" ) 
  Set objArchiveDB  = CreateObject( "AxMmServer.ArchiveDB" ) 
            
  objArchiveDB.Open 
  WScript.Echo "Open, result: " &  objArchiveDB.LastError    ' Open the Database

Open function

Open the archive database. You must open the archive database before you can perform any operation on the archive database, like counting records, creating new records, deleting records, etc. When you're finished accessing the database, you must call Close in order to close the database.

Parameters:

  ReadWrite (Optional, Boolean). Default is true; false opens the database for read only.

Return value:

  Always 0. Check LastError property to see if the function was completed successfully.

Example:

  Option Explicit
        
  Dim objArchiveDB, objConstants
            
  Set objConstants  = CreateObject( "AxMmServer.Constants" ) 
  Set objArchiveDB  = CreateObject( "AxMmServer.ArchiveDB" ) 
            
  objArchiveDB.Open 
  WScript.Echo "Open, result: " &  objArchiveDB.LastError    ' Open the Database

Close function

Parameters:

  None

Return value:

  Always 0. Check LastError property to see if the function was completed successfully.

Example:

  Option Explicit
  
  Dim objArchiveDB, objConstants
            
  Set objConstants  = CreateObject( "AxMmServer.Constants" ) 
  Set objArchiveDB  = CreateObject( "AxMmServer.ArchiveDB" ) 
            
  objArchiveDB.Open 
  WScript.Echo "Open, result: " &  objArchiveDB.LastError    ' Open the Database
  objArchiveDB.Close

Count function

Parameters:

  Filter (String) - A message filter. Pass an empty string to filter all messages.

Return value:

  The number of messages. Check LastError property to see if the function was completed successfully.

Example:

  Option Explicit
 
  Dim objArchiveDB, objConstants, numRecords
  Dim strFilter

  Set objConstants  = CreateObject( "AxMmServer.Constants" ) 
  Set objArchiveDB  = CreateObject( "AxMmServer.ArchiveDB" ) 

  objArchiveDB.Open 
  WScript.Echo "Open, result: " &  objArchiveDB.LastError' Open the Database
  If( objArchiveDB.LastError <> 0 ) Then
    WScript.Quit
  End If

  ' Count all messages in the database with direction Outgoing and status Success 
  strFilter = "DirectionID=" & objConstants.MESSAGEDIRECTION_IN & " AND " & _
             "StatusID=" & objConstants.MESSAGESTATUS_SUCCESS
  numRecords = objArchiveDB.Count( strFilter )               ' Count the records
  WScript.Echo "Count, result: " &  objArchiveDB.LastError   
  If( objArchiveDB.LastError <> 0 ) Then
    objArchiveDB.Close
    WScript.Quit
  End If

  WScript.Echo "Number of messages: " &  numRecords  

  objArchiveDB.Close                                         ' Close the Database
  WScript.Echo "Closed."                                     
  

Load function

Parameters:

  Message ID (Number) - Record ID of the message in the Messages database.

Return value:

  A new message object. Check LastError property to see if the function was completed successfully.

Example:

  Option Explicit
  
  Dim objArchiveDB, objMessage, objConstants
  
  Set objConstants  = CreateObject( "AxMmServer.Constants" ) 
  Set objArchiveDB  = CreateObject( "AxMmServer.ArchiveDB" ) 
  
  objArchiveDB.Open 
  WScript.Echo "Open, result: " &  objArchiveDB.LastError    ' Open the Database
  If( objArchiveDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  Set objMessage   = objArchiveDB.Load( 5 )                      ' Load Message with Message ID 5
  WScript.Echo "Load, result: " & objArchiveDB.LastError
  If( objArchiveDB.LastError <> 0 ) Then
    objArchiveDB.Close
    WScript.Quit
  End If  
  
  WScript.Echo "Message successfully loaded, ID: " & objMessage.ID
  
  objArchiveDB.Close
  WScript.Echo "Closed."

FindFirstMessage function

Parameters:

  Filter (String) - A message filter. Pass an empty string to filter all messages.

Return value:

  A new message object. Check LastError property to see if the function was completed successfully.

Example:

  Option Explicit
  
  Dim objArchiveDB, objMessage, objConstants
  
  Set objArchiveDB = CreateObject( "AxMmServer.ArchiveDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  ' Open the Database
  objArchiveDB.Open 
  WScript.Echo "Open, result: " &  objArchiveDB.LastError    
  If( objArchiveDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  ' Find all messages
  ' Start with the first message that matches the qualification
  Set objMessage = objArchiveDB.FindFirstMessage( "" )     
  While( objArchiveDB.LastError = 0 ) 
    WScript.Echo "Message found: " & objMessage.ID
    WScript.Echo "  Sender: "    & objMessage.FromAddress
    WScript.Echo "  Recipient: " & objMessage.ToAddress
    ' Find next message
    Set objMessage = objArchiveDB.FindNextMessage()        
  WEnd  

FindNextMessage function

Parameters:

  None

Return value:

  A new message object. Check LastError property to see if the function was completed successfully.

Example:

  Option Explicit
  
  Dim objArchiveDB, objMessage, objConstants
  
  Set objArchiveDB = CreateObject( "AxMmServer.ArchiveDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  ' Open the Database
  objArchiveDB.Open 
  WScript.Echo "Open, result: " &  objArchiveDB.LastError    
  If( objArchiveDB.LastError <> 0 ) Then
    WScript.Quit
  End If
  
  ' Find all messages
  ' Start with the first message that matches the qualification
  Set objMessage = objArchiveDB.FindFirstMessage( "" )     
  While( objArchiveDB.LastError = 0 ) 
    WScript.Echo "Message found: " & objMessage.ID
    WScript.Echo "  Sender: "    & objMessage.FromAddress
    WScript.Echo "  Recipient: " & objMessage.ToAddress
    ' Find next message
    Set objMessage = objArchiveDB.FindNextMessage()        
  WEnd  

7.7. Constants Class

Type definitions

Constant	Value	Description
MESSAGETYPE_UNDEFINED	0	Type of message is undefined.
MESSAGETYPE_SMS	1	SMS message.
MESSAGETYPE_EMAIL	3	E-mail message.
MESSAGETYPE_FILE	4	E-mail message.

A Message Type indicates the type of a message. The constants below can be used with the Message.TypeID property, and can also be used in any of the MessageDB methods that require a filter:

Example:

  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  n = objMessageDB.Count( "TypeID = " & objConstants.MESSAGETYPE_EMAIL ) 
  WScript.Echo "Number of e-mail messages in the message database: " & n
  ...

Direction definitions

Constant	Value	Description
MESSAGEDIRECTION_UNDEFINED	0	Direction of message is unknown.
MESSAGEDIRECTION_IN	1	Incoming message.
MESSAGEDIRECTION_OUT	2	Outgoing message.

A Message Direction indicates the direction of a message. The constants below can be used with the Message.DirectionID property, and can also be used in any of the MessageDB methods that require a filter:

Example:

  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  n = objMessageDB.Count( "DirectionID = " & objConstants.MESSAGEDIRECTION_IN ) 
  WScript.Echo "Number of incoming messages in the message database: " & n
     ...

Status definitions

Constant	Value	Description
MESSAGESTATUS_UNDEFINED	0	There is no status info.
MESSAGESTATUS_PENDING	1	Message is pending. The ActiveXperts SMS Messaging Server services is about to process the message.
MESSAGESTATUS_SUCCESS	2	Message was successfully sent, received or processed.
MESSAGESTATUS_FAILED	3	Failed to send, receive or process the message.

A Message Status indicates the status of a message. The constants below can be used with the Message.StatusID property, and can also be used in any of the MessageDB methods that require a filter:

Example:

  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  n = objMessageDB.Count( "StatusID = " & objConstants.MESSAGESTATUS_SUCCESS & _
      " AND DirectionID = " & objConstants.MESSAGEDIRECTION_OUT ) 
  WScript.Echo "Number of successfully sent (outgoing) messages in the message database: " & n
  ...

Status details definitions

Constant	Value	Description
MESSAGESTATUSDETAILS_UNDEFINED	0	There are no status details.
MESSAGESTATUSDETAILS_NOTPROCESSEDYET	100	Message was received but has not been processed yet.
MESSAGESTATUSDETAILS_PROCESSED	101	Message was received and successfully processed.
MESSAGESTATUSDETAILS_PROCESSEDNOSCRIPTS	102	Message was received, no trigger scripts defined.
MESSAGESTATUSDETAILS_PROCESSEDNOSCRIPTSINVOKED	104	Received. No processing required, no trigger condition matched
MESSAGESTATUSDETAILS_PROCESSINGFAILURE	110	Received; processing failure
MESSAGESTATUSDETAILS_SCHEDULED	200	Message is scheduled.
MESSAGESTATUSDETAILS_QUEUED	201	Message is queued for sending. This means that is has been picked up by the ActiveXperts SMS Messaging Server service.
MESSAGESTATUSDETAILS_PENDINGRESPONSE	202	Message is send, waiting for a provider response:
MESSAGESTATUSDETAILS_PENDINGDELIVERY	203	Message is send, waiting for a delivery report
MESSAGESTATUSDETAILS_GENERICFAILURE	210	A generic failure occurred.
MESSAGESTATUSDETAILS_NOAVAILABLECHANNEL	211	The server couldn't find any enabled channel capable of sending this type of message.
MESSAGESTATUSDETAILS_UNDELIVERABLE	212	The service tried to send out the message but could not deliver the message. Check the 'Trace' field of the Message for additional information.
MESSAGESTATUSDETAILS_DELIVERFAILED	213	The message was submitted to the provider but the provider failed to deliver the message. Check the 'Trace' field of the Message for additional information.
MESSAGESTATUSDETAILS_DELIVERTIMEOUT	214	The message was successfully submitted to the provider but there was no positive/negative acknowledgement within a certain period (configurable).
MESSAGESTATUSDETAILS_FAILEDBLOCKED	216	The message was blocked.
MESSAGESTATUSDETAILS_FAILEDNOCREDITS	217	There are insufficient credits to send the message
MESSAGESTATUSDETAILS_SENT	220	The message was successfully sent. The message either did not require a delivery report or the delivery report has no information about actual delivery.
MESSAGESTATUSDETAILS_DELIVERED	221	The message was successfully delivered.

The Message.StatusDetailsID property gives you more detailed info about the status of a message than Message.StatusID For instance, when the Status of a message is set to MESSAGESTATUS_FAILED, 'StatusDetails' will tell you the reason for this error. 'StatusDetails' can hold one of the following values:

Example:

  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  n = objMessageDB.Count( "StatusID = " & objConstants.MESSAGESTATUS_FAILED & _
      " AND StatusDetails = " & objConstants.MESSAGESTATUSDETAILS_NACK ) 
  WScript.Echo "Number of SMS messages that failed because of a negative acknowledgement: " & n
  ...

Body format definitions

Constant	Value	Description
MESSAGEBODYFORMAT_SMS_TEXT	0	Plain text (only for SMS messages, i.e. messages that have Message.Type set to MESSAGETYPE_SMS)
MESSAGEBODYFORMAT_SMS_DATA	2	Data (only for SMS messages)
MESSAGEBODYFORMAT_SMS_WAPPUSH	6	WAP Push (only for SMS messages)
MESSAGEBODYFORMAT_EMAIL_TEXT	0	Normal E-mail (only for e-mail messages)
MESSAGEBODYFORMAT_EMAIL_HTML	1	HTML formatted e-mail (only for e-mail messages)

A BodyFormat indicates the type of format of the body of the SMS/E-mail message. You can assign the following Body Format constants to the Message.BodyFormatID property.

Example:

  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  n = objMessageDB.Count( "DirectionID=" & objConstants.MESSAGEDIRECTION_OUT & _
      " AND BodyFormatID=" & objConstants.MESSAGEBODYFORMAT_SMS_WAPPUSH ) 
  WScript.Echo "Number of outgoing WAP Push messages in the message database: " & n
  ...

Priority definitions

Constant	Value	Description
MESSAGEPRIORITY_DEFAULT	0	Default priority
MESSAGEPRIORITY_HIGHEST	1	Highest priority
MESSAGEPRIORITY_HIGH	2	High priority
MESSAGEPRIORITY_MEDIUM	3	Medium priority
MESSAGEPRIORITY_LOW	4	Low priority
MESSAGEPRIORITY_LOWEST	5	Lowest priority

A Priority indicates the priority of an e-mail messages. You can assign the following priority values to the Message.Priority property.

Example:

  Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
  Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
  n = objMessageDB.Count( "DirectionID=" & objConstants.MESSAGEDIRECTION_OUT & _
      " AND Priority=" & objConstants.MESSAGEPRIORITY_HIGH ) 
  WScript.Echo "Number of outgoing WAP Push messages in the message database: " & n
  ...

8. Projects and Triggers

8.1. Projects

A Project is a collection of triggers and (database) files, necessary to implement a case. A Project typically includes the following files:

• One or more triggers in order to process incoming messages;
• Database files or Database connections, if any;
• Documentation;
• Log files (optional).

Let's take a closer look at one of the Case Studies published on the ActiveXperts web site: The HotRadio case.
You can explore this project in the following way:

1. Launch the SMS Messaging Server Manager application from the Start menu;
2. Select the Projects folder and right-click on Hotradio Radio Station;
3. A pop up menu appears; click on Explore.

Now, you see the files used for the HotRadio case:

• README.TXT - contains some background information of the case;
• Database\PlayAndWin.mdb - database file for the Play-and-Win item, where the audience can give answers to questions via SMS;
• Database\WePlayYourMusic.mdb - database file for the We Play Your Music Item item, where the audience can request a specific song via SMS;
• Triggers\PlayAndWin.vbs - VBScript file that processes incoming Play-and-Win answers;
• Triggers\WePlayYourMusic.vbs - VBScript file that processes incoming We Play Your Music requests.

8.2. Triggers

Incoming SMS- and E-mail messages are processed by so called triggers. You can define multiple triggers, to allow messages to be processed by multiple scripts.

Each individual trigger is a pair that consists of a condition and an associated VBScript. When the condition is matched, the associated VBScript program is invoked.

The condition is an SQL-like condition that selects filters incoming messages:

Example:	Messages received from '+4411111111' should be stored in 'DB1.MDB', and Messages received from '+4422222222' should be stored in 'DB2.MDB'.
Solution:	One trigger filters with condition: "Sender = '+4411111111'" and VBScript: "SCRIPT1.VBS" and another one with condition: "Sender = '+44122222222'" and VBScript: "SCRIPT2.VBS". "SCRIPT1.VBS" and "SCRIPT2.VBS" are responsible for storing the information in "DB1.MDB" and "DB2.MDB".

As soon as a new message is received through one of the channels, the status of the message is set to MESSAGESTATUS_PENDING, which means that the message has been received but has not been processed by the system yet. Immediately, the system tries to match the trigger condition(s) and invoke the associated VBScript program(s).

The SMS Messaging Server handles the triggers in the following way:

• It filters all messages that were just received, i.e. messages that match the following condition: DirectionID = MESSAGEDIRECTION_IN AND StatusID = MESSAGESTATUS_PENDING.
• For each message it tries to match the message properties with the condition that is associated with the trigger. If the condition is matched the VBScript that is associated with the trigger is executed.
• The system will try the next trigger, but only if the StatusID of the message is still MESSAGESTATUS_PENDING (i.e. the previous trigger didn't set the status to MESSAGESTATUS_ERROR or MESSAGESTATUS_SUCCESS).

When none of the Trigger conditions is matched the SMS Messaging Server system will change the status of the message to MESSAGESTATUS_SUCCESS. This indicates that there was no error while processing the message. It is a good practice to define a trigger that is executed when none of the trigger conditions are matched.

8.3. Creating a New Project

You can create a new Project in the following way:

1. Launch the SMS Messaging Server Manager application from the Start menu;
2. Right-click on the Projects folder and select Create New Project;
3. Enter a name for this Project in the Project Name field; the name will also be used for the directory where the Project files are stored;
4. Enter a friendly description in the Description field;
5. If you want to process incoming SMS- and/or E-mail messages, you can create one or more Triggers by pressing the Add Trigger button.

Chapter A Case Study best demonstrates how to create a project and how to create new triggers.

8.4. Case Study

Let's demonstrate the above with a small sample:

A company called 'SouthWind' is running ActiveXperts SMS Messaging Server. It has two cases running simultaneously. The first case is a workflow system, where 3 dedicated employees (+4400000001, +4400000002 and +4400000003) can send their workflow results to the central office through SMS. The second case is to serve product database requests via SMS, so employees and customers can query a product database from remote, to retrieve price information and stock quantities.

An incoming message is analyzed on its contents: if it is received from one of the '+44000000x' numbers, it is apparently a workflow request. If not, the body of the message is checked for the existence of the 'PRODUCT' keyword. If it does contain this keyword, it is apparently a product database request. If not, the message is neither a workflow message nor a product database query, so the system replies with the following SMS message: "Request cannot be handled by the system".

To implement this system, we will define a new Project with three triggers: one trigger to process the workflow requests, one trigger to process the product requests, and one trigger to process all other SMS messages.

We first create a new Project with the following properties:

Property	Value
Project Name	SouthWind
Description	SouthWind Project to handle incoming workflow requests and incoming product requests

You can now create the triggers:

#	Condition	Script
1)	DirectionID = MESSAGEDIRECTION_IN AND StatusID = MESSAGESTATUS_PENDING AND (FromAddress='+4400000001' OR FromAddress='+4400000002' OR FromAddress='+4400000003)	Projects\SouthWind\Triggers\WorkFlow.vbs
2)	DirectionID = MESSAGEDIRECTION_IN AND StatusID = MESSAGESTATUS_PENDING AND Body LIKE '%PRODUCT%'	Projects\SouthWind\Triggers\ProductInfo.vbs
3)	DirectionID = MESSAGEDIRECTION_IN AND StatusID = MESSAGESTATUS_PENDING	Projects\SouthWind\Triggers\UnknownMessage.vbs

It is important that Trigger 3) has a lower priority than the other triggers. You can change the processing order in the Triggers Processing order dialog:

• Launch the SMS Messaging Server Manager application from the Start menu;
• Select the Configuration folder and click on Triggers;
• Click on Change Processing Order.

Script 1: [Projects\Workflow\Triggers\WorkFlow.vbs]

The first script is executed if the first condition is matched. The script performs the following actions:

• It sets the status of the incoming message to MESSAGESTATUS_SUCCESS instead of MESSAGESTATUS_PENDING, so it won't match the condition of the second and third trigger;
• It updates the custom workflow database (implementation of this update is beyond the scope of this sample);
• It generates a new outgoing pending SMS message, addressed to the sender of the incoming message, to thank the sender for the SMS message.

The script:

  Option Explicit
  
  ' Declaration of global objects
  Dim g_objMessageDB, g_objConstants
  
  ' Creation of global objects
  Set g_objConstants  = CreateObject( "AxMmServer.Constants" )
  Set g_objMessageDB  = CreateObject( "AxMmServer.MessageDB" ) 
  
  Function ProcessMessage( numMessageID )
  
   Dim objMessageIn, objMessageOut
  
   g_objMessageDB.Open      ' Open the message database
   If( g_objMessageDB.LastError <> 0 ) Then
     Exit Function
   End If
  
   ' Retrieve the message that has just been received.
   Set objMessageIn   = g_objMessageDB.FindFirstMessage( "ID = " & numMessageID ) 
   If g_objMessageDB.LastError <> 0 Then
     g_objMessageDB.Close
     Exit Function
   End If
  
   ' Set incoming SMS message status to SUCCESS, so it won't be processed by the next trigger
   objMessageIn.StatusID = g_objConstants.MESSAGESTATUS_SUCCESS 
   g_objMessageDB.Save objMessageIn
  
   ' Update the workflow - custom function
   UpdateWorkflow( objMessageIn.Sender, objMessageIn.Body ) 
  
   ' Create a new reply message, and save it
   Set objMessageOut = g_objMessageDB.Create
   g_objDebugger.WriteLine " New message created, result: [" & g_objMessageDB.LastError & "]"
   If( g_objMessageDB.LastError = 0 ) Then
     objMessageOut.DirectionID = g_objConstants.MESSAGEDIRECTION_OUT
     objMessageOut.TypeID      = objMessageIn.TypeID
     objMessageOut.StatusID    = g_objConstants.MESSAGESTATUS_PENDING
     objMessageOut.To          = objMessageIn.Sender 
     objMessageOut.ChannelID   = 0  ' Any available SMS channel
     objMessageOut.Body        = "Your request has been processed successfully."
     g_objMessageDB.Save objMessageOut
   End If
  
  End Function
  
  
  Function UpdateWorkflow( strSender, strBody )
    ' Custom function to update the sender's workflow data
  End Function

Script 2: [Projects\ProductInfo\Triggers\ProductInfo.vbs]

This script is very similar to the first script. Instead of updating a worksheet, the script fetches Product information based on the request, and replies it to the original sender.

  Option Explicit
  
  ' Declaration of global objects
  Dim g_objMessageDB, g_objConstants
  
  ' Creation of global objects
  Set g_objConstants  = CreateObject( "AxMmServer.Constants" )
  Set g_objMessageDB  = CreateObject( "AxMmServer.MessageDB" ) 
  
  Function ProcessMessage( numMessageID )
  
   Dim objMessageIn, objMessageOut, strProductInfo
  
   g_objMessageDB.Open   ' Open the message database
   If( g_objMessageDB.LastError <> 0 ) Then
     Exit Function
   End If
  
   ' Retrieve the message that has just been received.
   Set objMessageIn   = g_objMessageDB.FindFirstMessage( "ID = " & numMessageID ) 
   If g_objMessageDB.LastError <> 0 Then
     g_objMessageDB.Close
     Exit Function
   End If
  
   ' Set incoming SMS message status to SUCCESS, so it won't be processed by the next trigger
   objMessageIn.StatusID = g_objConstants.MESSAGESTATUS_SUCCESS 
   g_objMessageDB.Save objMessageIn
  
   ' Retrieve product info from a custom database - custom function
   strProductInfo = GetProductInfo( objMessageIn.Body ) 
  
   ' Create a new reply message, and save it
   Set objMessageOut = g_objMessageDB.Create
   g_objDebugger.WriteLine " New message created, result: [" & g_objMessageDB.LastError & "]"
   If( g_objMessageDB.LastError = 0 ) Then
     objMessageOut.DirectionID = g_objConstants.MESSAGEDIRECTION_OUT
     objMessageOut.TypeID      = objMessageIn.TypeID 
     objMessageOut.StatusID    = g_objConstants.MESSAGESTATUS_PENDING
     objMessageOut.To          = objMessageIn.Sender 
     objMessageOut.ChannelID   = 0  ' Any available SMS channel
     objMessageOut.Body        = strProductInfo
     g_objMessageDB.Save objMessageOut
   End If
  
  End Function
  
  
  Function GetProductInfo( strBody )
  ' Custom function to update the sender's workflow data
  ...
  GetProductInfo = "In Stock: XXX; Price: YYY"
  End Function

Script 3: [Projects\Misc\Triggers\UnknownMessage.vbs]

This script is very similar to the first script. It only replies to the original sender that the request is invalid.

  Option Explicit
  
  ' Declaration of global objects
  Dim g_objMessageDB, g_objConstants
  
  ' Creation of global objects
  Set g_objConstants  = CreateObject( "AxMmServer.Constants" )
  Set g_objMessageDB  = CreateObject( "AxMmServer.MessageDB" ) 
  
  Function ProcessMessage( numMessageID )
  
   Dim objMessageIn, objMessageOut, strProductInfo
  
   g_objMessageDB.Open   ' Open the message database
   If( g_objMessageDB.LastError <> 0 ) Then
     Exit Function
   End If
  
   ' Retrieve the message that has just been received.
   Set objMessageIn   = g_objMessageDB.FindFirstMessage( "ID = " & numMessageID ) 
   If g_objMessageDB.LastError <> 0 Then
     g_objMessageDB.Close
     Exit Function
   End If
  
   ' Set incoming SMS message status to SUCCESS, so it won't be processed by the next trigger
   objMessageIn.Status = g_objConstants.MESSAGESTATUS_SUCCESS 
   g_objMessageDB.Save objMessageIn
  
   ' Create a new reply message, and save it
   Set objMessageOut = g_objMessageDB.Create
   g_objDebugger.WriteLine " New message created, result: [" & g_objMessageDB.LastError & "]"
   If( g_objMessageDB.LastError = 0 ) Then
     objMessageOut.DirectionID = g_objConstants.MESSAGEDIRECTION_OUT
     objMessageOut.TypeID      = objMessageIn.TypeID
     objMessageOut.StatusID    = g_objConstants.MESSAGESTATUS_PENDING
     objMessageOut.To          = objMessageIn.Sender 
     objMessageOut.ChannelID   = 0  ' Any available SMS channel
     objMessageOut.Body        = "Invalid request."
     g_objMessageDB.Save objMessageOut
   End If
  
  End Function

9. Troubleshooting

9.1. Introduction

ActiveXperts SMS Messaging Server is designed with one thing in mind: let the user have complete control over the product. This means that the system should display and log exactly what it is doing, how things are working and why things do not work. The following things will help you with that:

• ActiveXperts SMS Messaging Server Monitor The Monitor application shows you real-time information about Channels, Message Database and the VBScript engine;
• Trace Files Trace files show you detailed information about Channels, Message Database and VBScript engine, over a long period of time.

ActiveXperts SMS Messaging Server can be tuned to improve performance. It is actually the performance of the ActiveXperts SMS Messaging Server service that can be tuned. This service is has sub-processes (so called 'threads') to send- and receive SMS- and e-mail messages, manage the Message Database, controlling the Communication Channels and executing the Triggers.

9.2. Error Codes

When a function is called, the result of the function is stored in the object's LastError property. When LastError is 0, it means that the last called function completed successfully; otherwise, an error occured.

The value of the LastError tells you why the function failed. All error codes are listed on the ActiveXperts web site:

www.activexperts.com/support/errorcodes (list of error codes). Here, you can also lookup a specific error to find its description.

9.3. Server Monitor

The ActiveXperts SMS Messaging Server Monitor shows real-time information about:

• Each communication channel. See what a channel is actually doing, which commands are sent etc.;
• The Message database. See how often the Message Database is scanned, when it is archived, etc.;
• The VBScript engine. You can see what is actually being processed by the system, and locate errors when there are (syntax) errors in the script.

To launch the Monitor application:

• Launch the SMS Messaging Server Monitor application from the Start menu.

By default, the ActiveXperts SMS Messaging Server Monitor shows the following items:

• All enabled GSM Modem Channels;
• All enabled HTTP Channels;
• All enabled SMPP Channels;
• All enabled POP3 Channels;
• All enabled SMTP Channels;
• The Message Database;
• The VBScript Engine.

You can show additional Channels by selecting Select "Channels..." from the Windows Menu.

9.4. Tracing

The ActiveXperts SMS Messaging Server Monitor provides tracing for the following items:

• Each communication channel;
• Message database;
• VBScript engine.

To enable tracing for a particular channel or thread, you must enable it through the registry, by assigning a Log File to it:

1. Open a registry editor (REGEDIT.EXE or REGEDT32.EXE);
2. Open the HKLM\Software\ActiveXperts\SMS Messaging Server\Trace key;
3. Open the key of the item that you want to trace, and specify a valid trace filename;
4. Restart the Service.

It's important to restart the service after changing one of the Trace items.

Tracing will decrease the performance of the ActiveXperts SMS Messaging Server service. So, just use tracing for troubleshooting purposes, and make sure you turn-off the trace file(s) by assigning an empty string to the LogFile value in the Trace keys.

9.5. Performance tuning

There are number of registry settings that can be changed to fine-tune the performance for specific environments or use cases. For any of these settings to take effect it is important to restart the service after changing them.

The following table provides an overview of these settings that can be found in:

HKLM\Software\ActiveXperts\SMS Messaging Server\Performance

Key	Description
AdoCommandRetryPeriodSecs	If an ADO operation fails, this is the number of seconds the SMS Messaging Server will continue to retry the operation.
AdoCommandTimeoutSecs	The command timeout in the ADO layer.
AdoConnectionTimeoutSecs	The connection timeout in the ADO layer.
AdoOptimisticLocking	Whether or not to use optimistic locking when opening a database connection.
CheckArchiverIntervalSecs	The interval period in seconds for the archiver to check if anything needs to be done.
CheckNewMessageDbIntervalSecs	The interval period in seconds for the message database to check if there are any new messages to send.
CheckNewMessagesQueueIntervalSecs	The interval period in seconds for the message database to check the file queue to see if there are any new messages received.
DelayStartSecs	The number of seconds to delay starting up the service after the service is started. This can be used to fix problems if, for instance, a local MSSQL instance takes more time to startup.
DeliveryReportTimeoutSecs	The timeout in in seconds for receiving delivery reports. If a delivery report is not received within this timeframe the message status will be set to failed. This applies to all SMS protocols that support delivery reports.
InFileQueueSize	The maximum number of queue items in the 'In' file queue. This determines the maximum number of messages that can be received and queued in the file queue before the message database picks the items up.
OutFileQueueSize	The maximum number of queue items that can be put in the output file queue to be sent. If the queue is file the messages will be kept 'Pending' in the message database.
QueueTimeoutSecs	The maximum number of seconds a message can remain in the 'Queued' state. If this timeout expires it is assumed that item was not send and will be set to failed.
ResponseTimeoutSecs	The maximum number of seconds a message can remain the 'Pending response' state. If this timeout expires it is assumed that there will not be a response from the server and the item will be set to failed.
SendMessageIntervalSecs	The interval period in seconds for a channel to check if there are any new messages in the file queue to send.
ThreadsFile	The maxium number of file pickup threads.
ThreadsGsm	The maximum number of GSM threads.
ThreadsHttp	The maximum number of HTTP threads.
ThreadsPop3	The maximum number of POP3 threads.
ThreadsSmpp	The maximum number of SMPP threads.
ThreadsSmtp	The maximum number of SMTP threads.

9.6. Advanced settings

There a number of advance configuration settings that should only be required in specific situations. For any of these settings to take effect it is important to restart the service after changing them.

Some of these settings are general settings that will be applied to all channels of a certain protocol or message type. Other settings can be set per channel.

The following table provides an overview of the general / channel independant settings that can be found in:

HKLM\Software\ActiveXperts\SMS Messaging Server\AdvancedSettings

Key	Description
SmppReconnectDelaySecs	The number of seconds before re-connecting when a connection is dropped by the server.
SmppOutMemoryQueueSize	The maximum number of outgoing items in the SMPP memory queue. Items are put into the SMPP in-memory queue for sending when they are picked-up from the file queue. If the in-memory queue if full the items will be left in the file queue.
SmppInMemoryQueueSize	The maximum number of incoming items in the SMPP memory queue. Items are put into the SMPP in-memory queue when they are received, the SMPP thread will pick them from the in-memory queue and put them into the file queue. The database thread picks them up from the file queue and puts them into the database. If the in-memory queue is full the SMPP thread will reject new incoming messages, the SMSC should try re-sending them.
SmppConnectTimeoutSecs	The SMPP connection timeout in seconds.
SmppCommandTimeoutSecs	The SMPP command timeout in seconds. If an SMSC does not confirm a command within this number of second the client will drop the connection.
SmppSubmitMode	The SMPP submit mode. This determines the packet used to send out SMS messages. This can be either 'SUBMIT_SM' (1, default) or 'DATA_SM' (2).
SmppBindTimeoutSecs	The SMPP bind timeout in seconds. The connection will fail if the server does not respond to a bind command within this number of seconds.
GsmSendTimeoutSecs	GSM send message timeout in seconds.
GsmReceiveTimeoutSecs	GSM receive message timeout in seconds.
GsmNetworkTimeoutSecs	GSM connect to network timeout in seconds.
GsmCharacterIntervalMs	The interval in milliseconds between sending character to the GSM device. This is independant of the device baudrate. This can be used to support some old or low-quality devices.
GsmCommandIntervalMs	The interval in milliseconds between sending commands to the GSM device. This is independant of the device baudrate. This can be used to support some old or low-quality devices.

The following table provides an overview of the channel specific settings that can be found in:

HKLM\Software\ActiveXperts\SMS Messaging Server\AdvancedSettings\<ChannelId>

Key	Description
MessageIntervalMs	Applies to GSM, HTTP, SMPP and SMTP. The minimum interval between sendout out messages on this channel in milliseconds. This is a way to throttle the channel if, for instance, the provider has a limit to the rate of messages that can be sent.
AssembleMultipart	Applies to SMPP and GSM. Set to non-zero to enable automatically assembling incoming multipart message.
ExtractPort	Applies to SMPP and GSM. Set to non-zero to enable automatically extract application port information from an SMS.
MultipartMode	Applies to SMPP and GSM. Specifies how multipart messages will be split up and sent. 8Bit UDH (default) 16Bit UDH SAR TLV (SMPP only) Payload TLV (SMPP only)
MaxPendingPdus	Applies to SMPP. Maximum number of PDU's that can be left open on the SMSC. This affects the number of SMS messages that can be sent at the same time.
SevenBitEncoding	Applies to SMPP. Specify whether incoming, outgoing or none or both messages are either encoded in 7bits or use the GSM character set in 8 bits. 0 None 1 Incoming messages use GSM charset in 7 bits 2 Outgoing messages use GSM charset in 7 bits 3 In- and Outgoing messages use GSM charset in 7 bits 4 Incoming messages use GSM charset in 8 bits 5 Outgoing messages use GSM charset in 8 bits 6 In- and Outgoing messages use GSM charset in 8 bits
ApplyDeliveryReports	Applies to SMPP. Delivery reports are applied to the message instead of beeing received as a seperate SMS message.
ValidityPeriod	Applies to GSM. Specify the validity period in minutes for SMS messages
ExtraInitString	Applies to GSM. This is an extra initialization string that will be sent to the GSM modem after the modem connection has been opened and initialized by the messaging server service. Each time before a batch of SMS messages is sent and before the GSM check for received messages. This will be sent right after the GSM PIN code status check.
ExtraInitStringTimeoutMs	Applies to GSM. This is the timeout of the ExtraInitString string. The execution of this string cannot take longer than the amount of milliseconds specified here. If it does take longer for the GSM modem to reply the operation will be considered to have failed.

10. Support

10.1. FAQ

Visit our website for a complete list of FAQ's at: http://www.activexperts.com/support

10.2. Contact us

Please contact our website for support questions about this product, or send an email to our support-staff:

Website: http://www.activexperts.com/support

E-mail: support@activexperts.com

11. Licensing

11.1. Purchase

Please visit www.activexperts.com/sales to buy the product. Here, you can also find the latest prices.
You can also contact us via email: sales@activexperts.com After you purchase the product, you will receive one or more product registration keys.

11.2. Product Activation

After you purchase the product, you will receive a registration code. This code must be entered on the target computer(s).

Appendix A License Agreement

  PLEASE READ THIS SOFTWARE LICENSE AGREEMENT CAREFULLY BEFORE 
  DOWNLOADING OR USING THE SOFTWARE.  BY CLICKING ON THE 
  "ACCEPT" BUTTON, OPENING THE PACKAGE, DOWNLOADING THE PRODUCT, 
  OR USING THE EQUIPMENT THAT CONTAINS THIS PRODUCT, YOU ARE 
  CONSENTING TO BE BOUND BY THIS AGREEMENT. IF YOU DO NOT AGREE 
  TO ALL OF THE TERMS OF THIS AGREEMENT, CLICK THE "DO NOT 
  ACCEPT" BUTTON AND THE INSTALLATION PROCESS WILL NOT CONTINUE, 
  RETURN THE PRODUCT TO THE PLACE OF PURCHASE FOR A FULL REFUND, 
  OR DO NOT DOWNLOAD THE PRODUCT.
  
  GENERAL
  In this Software License Agreement:
  (i) "ActiveXperts" means ActiveXperts Software B.V.
  (ii) "Customer" means the individual(s), organization or business entity 
  buying a license of the Software from ActiveXperts or its Distributors 
  or its Resellers.
  (iii) "Software" means computer programs (and their storage medium) 
  supplied by ActiveXperts and known collectively as "ActiveComport" 
  in which ActiveXperts has property rights and any user manuals, 
  operating instructions, brochures and all other documentation relating 
  to the said computer programs (the expression "Software" to include all 
  or any part or any combination of Software).
  
  1. LICENSE GRANT
  ActiveXperts grants Customer the following rights provided that you 
  comply with all terms and conditions of this License Agreement:
  
  (a) Installation and use. Customer may install, use, access, display and 
  run one copy of the Software on a single computer, such as a 
  workstation, terminal or other device ("Workstation Computer"). A 
  "License Pack" allows you to install, use, access, display and run 
  additional copies of the Software up to the number of "Licensed Copies" 
  specified above.
  
  (b) Reservation of Rights. ActiveXperts reserves all rights not 
  expressly granted to you in this License Agreement.
  
  2. UPGRADES AND SUPPLEMENTS
  To use a product identified as an upgrade, you must first be licensed 
  for the Software as eligible for the upgrade. After upgrading, Customer 
  may no longer use the product that formed the basis for Customer's 
  upgrade eligibility.
  
  This License Agreement applies to updates or supplements to the original 
  Software provided by ActiveXperts, unless we provide other terms along 
  with the update or supplement.
  
  3. LIMITATION ON REVERSE ENGINEERING,DECOMPILATION, AND DISASSEMBLY
  Customer may not reverse engineer, decompile, or disassemble the 
  Software, except and only to the extent that it is expressly permitted 
  by applicable law notwithstanding this limitation.
  
  4. TERMINATION
  Without prejudice to any other rights, ActiveXperts may cancel this 
  License Agreement if Customer does not abide by the terms and conditions 
  of this License Agreement, in which case you must destroy all copies of 
  the Software and all of its component parts.
  
  5. NOT FOR RESALE SOFTWARE
  Software identified as "Not for Resale" or "NFR," may not be resold, 
  transferred or used for any purpose other than demonstration, test or 
  evaluation.
  
  6. LIMITED WARRANTY
  ActiveXperts warrants that for a period of ninety (90) days from the 
  date of shipment from ActiveXperts: (i) the media on which the Software 
  is furnished will be free of defects in materials and workmanship under 
  normal use; and (ii) the Software substantially conforms to its 
  published specifications. Except for the foregoing, the Software is 
  provided AS IS. This limited warranty extends only to Customer as the 
  original licensee. Customer's exclusive remedy and the entire liability 
  of ActiveXperts and its suppliers under this limited warranty will be, 
  at ActiveXperts or its service center's option, repair, replacement, or 
  refund of the Software if reported (or, upon request, returned) to the 
  party supplying the Software to Customer. In no event does ActiveXperts 
  warrant that the Software is error free or that Customer will be able to 
  operate the Software without problems or interruptions.
  This warranty does not apply if the software (a) has been altered, 
  except by ActiveXperts, (b) has not been installed, operated, repaired, 
  or maintained in accordance with instructions supplied by ActiveXperts, 
  (c) has been subjected to abnormal physical or electrical stress, 
  misuse, negligence, or accident, or (d) is used in ultrahazardous 
  activities.
  
  
  7. LIMITATION OF LIABILITY AND REMEDIES.
  Notwithstanding any damages that you might incur for any reason 
  whatsoever (including, without limitation, all damages referenced above 
  and all direct or general damages), the entire liability of ActiveXperts 
  and any of its suppliers under any provision of this License Agreement 
  and your exclusive remedy for all of the foregoing (except for any 
  remedy of repair or replacement elected by ActiveXperts with respect to 
  any breach of the Limited Warranty) shall be limited to the greater of 
  the amount actually paid by you for the Software or U.S.$5.00. The 
  foregoing limitations, exclusions and disclaimers (including Sections 4, 
  5 and 6 above) shall apply to the maximum extent permitted by applicable 
  law, even if any remedy fails its essential purpose.
  
  8. ENTIRE AGREEMENT
  
  This License Agreement (including any addendum or amendment to this 
  License Agreements which is included with the Software) are the entire 
  agreement between you and ActiveXperts relating to the Software and the 
  support services (if any) and they supersede all prior or 
  contemporaneous oral or written communications, proposals and 
  representations with respect to the Software or any other subject matter 
  covered by this License Agreement. To the extent the terms of any 
  ActiveXperts policies or programs for support services conflict with the 
  terms of this License Agreement, the terms of this License Agreement 
  shall control.
  
  This Agreement shall be construed in accordance with the laws of The 
  Netherlands and the Dutch courts shall have sole jurisdiction in any 
  dispute relating to these conditions. If any part of these conditions 
  shall be or become invalid or unenforceable in any way and to any extent 
  by any existing or future rule of law, order, statute or regulation 
  applicable thereto, then the same shall to the extent of such invalidity 
  or enforceability be deemed to have been deleted from the conditions 
  which shall remain in full force and effect as regards all other 
  provisions.
  
  9. Copyright
  The Software is protected by copyright and other intellectual property 
  laws and treaties. ActiveXperts or its suppliers own the title, 
  copyright, and other intellectual property rights in the Software. The 
  Software is licensed, not sold.