Installation: How to Make Sure That the Program Works
It's easy to install SMS Reception Center. You have to download the distribution, smsrc.zip, unzip the archive and run setup.exe. You will be asked about target directory and whether you want to have shortcuts on your desktop and in the Start menu. Well, you've done it; now we are to ensure that the program works with your phone or modem.
Starting SMS Reception Center
Find the icon on your desktop and double-click on it.
Alternatively, you may use Start menu -> Programs -> SMS Reception Center.
You will see the main window of the program:
What you see is a graphic interface of the editor that we will use to define actions which are taken on each incoming message. Now we want to check if the program works with your phone, and the empty list of actions is good enough for the first steps, so don't try to change the list now. Go to the menu instead and select Run -> Install. Now you will see the popup dialog window:
We are about to start the SMS Reception service. What is that service, at last?
SMS Reception Center separates two different tasks from each other: editing rulesets (action lists) for message handling is one task, and processing messages (in connection with a phone) is another one. You prepare a list of actions in the Editor, then you have to feed it to the Service which will work with the phone and act as you instructed it.
There are two modes for running the service, Desktop mode and NT Service mode. The first mode is the most appropriate for debugging and testing purposes, so we will use it now.
At this step you must select a COM port which is connected with a phone. When you use data cable, this port will be COM1 or COM2 in most cases. If infrared connection is used, there is usually some software-emulatedCOM-port, and you have to select this emulated port. Some NOKIA phones require vendor-specific software to work properly as a modem; this software may provide a virtual COM-port too. Virtual COM-port is usually accessible as COM3, COM4 or COM5.
Now you are about to start SmsRc service. Please ensure that you have no worthy unread messages in your phone. They will be silently removed! If you have a chance to receive a worthy message at any time, don't do this test until you learn how to store incoming messages in a text file.
Select a port and click OK button (or press Enter). Now look at the system tray at the windows task bar. You will see the SmsRc service icon there.
When you move mouse pointer to that icon, the tooltip message is displayed. If everything is alright and the program works with your phone correctly, this message will become looking like this: Ericsson (R520) on COM2, i.e. it will contain the phone's manufacturer name and model name.
Initial message is always Connecting to phone on COMn; if it doesn't change in a few seconds as described above, there is some problem and the program is not working with you phone now. What to do in such a situation?
If you click on the tray icon with right mouse button, you will see a menu. In case of problems, select Save debug log in this menu and choose a log file name. E-mail us (mailto:firstname.lastname@example.org), name your phone, describe the connection you use and attach the debug log. We will try to get it working.
A simple example: writing a message to a file
Now let's go back to editor window and create an action which will store each incoming message in a text file.
Select Edit -> Insert -> Store message... and you will see dialog window with action parameters you are allowed to set up:
Here is the description of parameters that we'll use now:
File name is a name of the text file where all incoming messages will be stored;
Log entry format is a model for each line added to this text file;
Description is just a brief human-readable description of this action; it is displayed in the list of actions just for your own comfort, it doesn't affect the action itself.
The picture above is an illustration of variable substitutions in parameters. The Log entry format field contains a reference to the Sender variable. When a message arrives, this variable is set to the phone number of the message's originator.
When you right-click on a field that allows variable substitutuions, the popup menu with available variables appears. On this picture we see this menu with predefined variables in it: these variables are set for each incoming message automatically.
Sender is a message's originator phone number;
Message is the message's text;
word#0 is the first word of the message's text;
word#1 is the second word of the message's text;
word#1-end is the message text with the first word excluded from it.
Variable substitutions are always denoted with [%Varname%].
Please choose a file name as you like, define Log entry format to be [%Sender%] wrote: [%Message%] and press Enter key to save this action.
The list of actions in the editor will now look like this:
Let's see how this example works. We have changed the list of actions, but the service doesn't know anything about it — we need to use Menu -> Run -> Install... to tell the service about changes. Let's do it now...
Testing the actions
Now we want to check our action list to ensure that it will react properly on each incoming message; but you don't want to waste time and money on sending real SMS to your phone.
There is a feature in SMS Reception Center which is good for such a test. When Desktop SmsRc service is running, you can go to the menu and select Run -> Test message... there; then you will see a dialog window:
When you fill these two fields and click on the OK button, you make SmsRc service think that there was an incoming message. This message is handled exactly the same way as any real incoming message will be handled.
In the example we're discussing now, the sender's phone and message's text that you type in this window will be appended to the text file that you have selected. When you are sure that messages are handled in the way you like, you can switch to real messages.
Unregistered users, plese remember: SmsRc service won't handle more than 6 messages per session before registering the program, including both test messages and real ones. You should restart the service after each 6 messages processed.
Let's now learn a new feature of SMS Reception Center — conditional actions. If you want SMS Reception Center to take different actions depending on message's sender or body, you'll certainly need this feature.
Here we described the condition under which this action is taken: the message's sender number must be +79165551234. Note that we also checked Take no further action after this one; thus if the phone receives any message from +79165551234, it will be stored in the file we selected, and no further actions will be taken on that message.
There are four types of string comparison that may be used to describe action's condition. We are using exact match in this example, but it's good to know what do the other types mean:
is like means that variable's value must match the pattern you give, and the following metacharacters are allowed in the pattern: * (star) matches any sequence of characters, ? (question mark) matches exacly one character of any sort, [chars] matches exactly one character of c, h, a, r, s.
contains means that variable's value must contain a string that you give as a pattern
matches regexp means that you give a regular expression as a pattern, and the condition is considered true if the variable's value matches this regular expression. Read Tcl:regexp if you want to know 1) what is regular expression and 2) what flavour of regexp is supported in SMS Reception Center.
Now it's time to begin to use action lists that contain more than one action. I recommend to use unconditional Store message action as the first one; thus, no incoming message can ever be lost due to erroneous setup.
Now let's try a new type of action, Send message. Go to the menu and select Edit -> Insert -> Send message.
Look at the example above: each incoming message is unconditionally forwarded to four recipients. Two of these recipients are mobile phones, and the other two are user, computer, or workgroup names.
Now remember what we learned before about generating test messages (pseudo-incoming messages, really). The point is that, together with message forwarding facility, this feature may turn SMS Reception Center into the program for sending bulk SMS!
Imagine that after setting up this example and starting the SmsRc service, you use Run -> Test message facility discussed before:
There is no real incoming message involved, as you already know. But the action you've set up will react on the test message exactly as on any real incoming message. Thus this messsage will be really forwarded to four recipients.
CAUTION: Never forward incoming messages to your own phone unconditionally! If you do this, SMS Reception Center can enter the infinite loop of receiving-message-and-forwarding-it-to-itself, which is not what you want.
Let's now discuss more complex example of message forwarding. The list of recipients will depend on the first word of a message's text, and only the rest of the text will be forwarded.
In this example, a message is forwarded to the given four recipients only if it's first word contains 4MANAGERS. Thus 4MANAGERS is a keyword which denotes the list to which a message must be forwarded.
Combining several such actions enables you to maintain several lists of recipients.
The last about this example: note that we used containing instead of is exactly in the condition. There is a reason behind that: if you set up several actions of this kind, the first word of messages text may contain more than one keyword! If there are two actions with keywords 4MANAGERS and 4DEVELOPERS, they both will be triggered if the keyword is 4MANAGERS,4DEVELOPERS.
The First Step to Databases
In this section, we will build the example that uses relation database to keep a list of recipients to which incoming SMS will be forwarded.
First we need to create a database accessible through some ODBC driver. It may be Microsoft™Access file.
Create a table called SMSLists with the following columns in it:
Then add some records to this table. ListKeyword must contain a keyword that is used to denote the particular list of recipients, and Recipient must contain the phone number or computer⁄workgroup⁄user name. To reproduce our previous example, the table must contain those records:
Now let's return to SMS Reception Center and create a new action: Edit -> Insert -> Execute SQL...
Click on the Connect DB button and select appropriate ODBC driver and connection parameters for your database. It's good if you have some experience with ODBC, but even if you don't, the ODBC interface for database selection is rather intuitive and easy to use.
When you have selected the database that contains the SMSLists table mentioned above, let's set up another parameters of this action:
The simple SQL query will produce a one-column result containing all recipients for particular keyword. We stated explicitly that we expect a one-column result from this query, and this result must be stored in variable named Recipients. Note, it's the first time we defined a new variable!
Save this action and add another one; as you've already guessed, it's a Send message action. Now we can use Recipients variable in the Send to parameter:
Now you know enough to set up message forwarding using the database to keep several lists of recipients. Notice that all database-related actions share the same ODBC connection. Thus if the location of your database has changed, you need to adjust connection string for one such action only: another actions will use the new connection automatically.
Databases, part 2: Implementing Subscription and Unsubscription
The previous example has a drawback: the table of recipients to whom a message is forwarded has to be maintained by hand. Let's improve this example, so any recipient may subscribe and unsubscribe to any SMSing list by sending a special message.
Take the previous example and insert a new action in the beginning of action list:
Action type: Execute SQL
Condition: word#0 is exactly SUBSCRIBE
SQL query: INSERT INTO SMSLists (ListKeywords, Recipient) VALUES ([%word#1%],[%Sender%])
Check the Take no further action... checkbox.
Now anyone who sends a message SUBSCRIBE 4MANAGERS will receive all messages for this list. Now, let's set up the unsubscription:
Action type: Execute SQL
Condition: word#0 is exactly UNSUBSCRIBE
SQL query: DELETE * FROM SMSLists WHERE Recipient=[%Sender%] AND ListKeyword=[%word#1%]
Check the Take no further action... checkbox.
You may improve this example in many ways, e. g. add a keyword to cancel all the subscriptions for a sender, or add a command which temporary disables message forwarding. And if you use powerful SQL engine that supports stored procedures and user-defined functions, you'll be able to handle incoming SMS messages in any complex way that you like.
Databases: Spooling Outgoing Messages
There's some unobvious fact about SMS Reception Center. If it connects with a database, that database is checked for presence of a special table, OutgoingSMs. If this table exists it is used as a source of messages to be sent out.
To use this feature, you must create a table named OutgoingSMs with the following columns in it:
MsgID: integer, unique, possibly flagged as IDENTITY in case of MS SQL Server
Text: I recommend varchar. There's no need to limit its length to 160 characters: larger messages will be split before sending.
Target: varchar, the recipient's phone number. It may start with "+" (international), but all other characters must be digits. No dashes, commas, spaces, braces or other separators in the middle!
Status: integer; 0(zero) means that the message is to be sent, and 1 means that the message was sent already. Notice that it has nothing to do with GSM operator's status reports. Status=1 doesn't mean that the message was read or even received. It was sent.
Status=2 means that the message was not sent after 3 retries. It may be the hardware problem or operator's fault; you have to set Status back to 0 if you want the message's delivery to be attempted next time.
These columns are mandatory, but the table may have any other columns as well.
You should insert records with Status=0 into this table; when the SmsRc service is running, it takes all these records, sends out the messages and then updates Status to 1, thus indicating that the message was sent.
Where do you want to go tomorrow?
Now you have read about some significant features of SMS Reception Center, but some other features were left behind, as they are intended for expert users only. We are working on a document that will describe these features also, but you may investigate them yourself if you're an expert:
If you want to use SMS Reception Center together with some SQL server and some Web server, you should consider running it as NT Service. Thus you won't have to log in to the computer that receives and handles SMS messages.
If you want to control your PC remotely via SMS or to monitor its status, you should look at the Run program action type. If you have command-line console program which does the job you need, you may run it remotely with SMS Reception Center and get back the result. You can find a lot of programs of this kind in Microsoft®Windows® Resource Kit.
If you want variables to be adjusted before processing a message, you should look at the Tweak variable action type. As an example, you may need to remove international prefix and country code from sender's number; this action type is intended to do the job.
The other things that weren't mentioned in this document we consider obvious to you: e.g. how to use cut-copy-paste and new-open-save file in the editor. We believe that you don't need any explanations on this topics.