Mobilchange news Documentation Contents User Documentation Administrator Documentation Index of terms Technical Support On-line Search
Scripting application programming

This document describes programming of script applications for MobilChange. It assumes that the reader has knowledge of VBScript or Visual Basic language.

Content

Introduction

If standard Mobilchange functionality is not enough, you can extend it using MobilChange VBS scripting. Script applications can be used in MobilChange Enterprise only, this feature is disabled in MobilChange Standard.

All user script applications run in UMS.TaskManager service environment. It checks their functioning and restarts them if necessary. Scripts are run inside Windows Scripting Host.

User applications are stored under MobilChange/script/ folder. Various sample applications can be found in MobilChange/samples/ folder. How to use them is commented directly in source code.

back to top of page

Differences of MobilChange VBS scripting

Some Mobilchange libraries are written in Visual Basic Script (VBS in next text). To make user script as simple as possible, technology of includes is used (known for example from C programming language).

Libraries are linked to the user code by this command:
  
'#include "file.vbs"
  

Filename in quotations can contain also path relative to the MobilChange/script/ folder.

During UMS.TaskManager starting is inside "startup" task MX_<task name> compiled file MobilChange/script/<task name>.vbs, attached includes and resulting file is stored into MobilChange/script/run/<task name>.vbs. This file is then executed. So if VBscript interpreter reports syntax error on line 200, you must find line 200 in compiled file under MobilChange/script/run/ folder, repair error in source file in MobilChange/script/ folder and finally restart UMS.TaskManager to recompile the script.

Information stated above are valid until MobilChange version 4.6.23. Higher versions do not use including - it was replaced by WSF jobs technology:

back to top of page

Start of program

The source code of user script until MobilChange version 4.6.23 must always begin with the following two lines (it is not necessary in higher versions):
  
Option Explicit
'#include "include\mx_script_app.vbs"
  

back to top of page

User function OnInit()

When executing the user script, OnInit function is called after all necessary initialization is finished. This function takes three parameters which must be initialized.
AppName The script must fill this variable with its own name (the name used when it was added into the system).
ServerName Application enters the name of MobilChange server to be worked with here. Local server (the computer running this application) is identified using empty string ("").

In present version, enter empty string only.

IddleTime Here the script specifies how often is OnIddle function to be called. The amount of time entered is in milliseconds. Minimum value recommended is 5000, maximum is 60000. When UMS.Taskmanger is being stopped it waits for this amount of time for script application finishing. So don't set too high value to not delay Taskmanager for a long period of time.
(Return
Value)		 Text string "OK" if everything is correct,
"ERROR" string in case that an error occurred.

When the user code returns "ERROR", the script is terminated and then restarted.

Here is an example of a complete function OnInit():
  
Function OnInit( AppName, ServerName, IddleTime )
    AppName = "pizza"       ' application "pizza"
    ServerName = ""         ' local server
    IddleTime = 10000       ' 10 seconds, recommended
    ' There can be done additinal initialization tasks
    OnInit = "OK"          ' return status
End Function
  
WARNING!! Inside OnInit() you CAN NOT use MobilChange.SendSMS/SendSMSEx functions - not all components for SMS sending are already initialized.

back to top of page

User Function OnReceivedSMS()

As soon as script application receives an SMS, user function OnReceivedSMS() is called. This function is passed information about SMS in three parameters. However this function is here only for backward compatibility. Preferred way of processing incoming messages is to use OnNotification() function, which also receives information about incoming SMS and has extended data available for every message.
FromNumber The phone number of the sender in international format.
TimeReceived Time the SMS was received in the following form of text string: YYYY/MM/DD hh:mm:ss
MessageBody Text of the received SMS.
(Return
Value)		 Text string "OK" if everything is correct,
"ERROR" string in case that an error occurred.

When the user code returns "ERROR", the script is terminated and then restarted. The SMS stays in the queue and it will be passed to the script after restarting.

A complete example of the OnReceivedSMS() function in Pizza user application. It answers the received SMS and pastes a copy of the original message into it.
  
Function OnReceivedSMS( FromNumber, TimeReceived, MessageBody )
    Dim rc

    MXLog "Working on received SMS..."

    MXLog "Sending reply..." 
    rc = MobilChange.SendSMS( FromNumber, 
            "PIZZA SERVICE: You have ordered pizza -" 
            + MessageBody + "- from phone number " + FromNumber + ".", True )
    MXLog "MobilChange.SendSms() = " & rc
    If rc <> "OK" Then
        MXLog "ERROR: " + MobilChange.LastError
    End If
    
    OnReceivedSMS = "OK"    ' return status
End Function
  

back to top of page

User Function OnNotification()

Whenever script application receives any SMS, (non)delivery report etc., OnNotification() user fuction is called with these parameters:
MessageType Type of message. Possible values:
  • "sent_ok" - SMS was sent to SMS center
  • "sent_ok_nodr" - SMS was sent to SMS center, but information about SMS delivery will not be delivered
  • "sent_ok_wait" - SMS was sent to SMS center. Information about SMS (non)delivery will be delivered
  • "sent_ok_dr" - SMS was sent succesfully
  • "sent_err_send" - SMS wasn't sent
  • "sent_err_timeout" - Error during SMS sending
  • "sent_err_ndr" - SMS was sent to SMS center, but recipient was unavailable
  • "void" - Unknown event
  • "rcv_sms" - Received SMS. It is processed by OnReceivedSMS function
  • "e_toolong" - SMS is longer then preset limit
  • "preview" - Preview of the message split into more SMS
  • "oplock_unsupp" - Invalid activation key for GSM network
  • "oplock_tampered" - Attempt to send message into prohibited GSM network
  • "e_nosms" - User is not allowed to use Mobilchange
Attr Attribute collection of the message, it is instance of FxExtObj.DSVariantCol object. Collection can contain these items:
  • "msg_type" - Type of message. Same value as MessageType parameter
  • "description" - Short description of the message
  • "name" - original phone number of the SMS recipient
  • "number" - normalized phone number of the SMS recipient
  • "user_app_id" - application identifier entered in SendSmsEx function
  • "time" - Time when SMS was sent in format yyyy/mm/dd HH:MM:SS
  • "rcv" - Time when information SMS was received in format yyyy/mm/dd HH:MM:SS
  • "operator" - GSM operator name
  • "line" - Name of line to GSM operator
  • "cost" - Cost of operation
  • "num" - Number of SMS which message was split to
  • "text" - Message body
  • "drtext" - Text of information about delivery from operator
(return
value)		 Text string "OK" if everything is correct,
"ERROR" string in case that an error occurred.

When the user code returns "ERROR", the script is terminated and then restarted. The SMS stays in the queue and it will be passed to the script after restarting.

back to top of page

User function OnIddle()

System calls function OnIddle() in case that during the specified period (set by the user in OnInit()) were not received any messages. It is intended for sending device status messages, database listings etc.
(Return
Value)		 Text string "OK" if everything is correct,
"ERROR" string in case that an error occurred.

When the user code returns "ERROR", the script is terminated and then restarted.

Sample of OnIddle() function:
  
Function OnIddle
    ' There can be done anything...
    OnIddle = "OK"          ' return status
End Function
  

back to top of page

User Function OnShutdown()

OnShutdown() function is called by system when UMS.TaskManager is being terminated, for example when shutting down the computer. It allows closing database connections, deleting temporary files etc.
(Return
Value)		 Text string "OK" if everything is correct,
"ERROR" string in case that an error occurred.

When the user code returns "ERROR", the script is terminated and then restarted.

Sample of OnShutdown() function:
  
Function OnShutdown
    ' There can be done anything...
    OnShutdown = "OK"          ' return status
End Function
  

back to top of page

Functions and Properties of MobilChange

MobilChange offers several functions and properties to be used by the scripts. For example these allow scripts sending of SMS messages.

MobilChange.SendSMS() Function

MobilChange.SendSMS() function sends an SMS. The syntax is:

MobilChange.SendSMS( to, text, nomodify )
MobilChange.SendSMS( to, text, nomodify, fromName, fromSMTP, fromEmail, language, DR )
to (text string) The phone number of recipient.
text (text string) Text of message.
nomodify (True/False) If is True, the text of message is being sent in exact form as was entered by application. If is False, the text is processed via MobilChange server the same way as sent e-mails, i.e. the spaces are skipped, decoded czech etc.
fromName (text string) The name of user whos name is used by application when sending SMS.
The delivery report will be sent to this name.
fromEmail (text string) E-mail address of the user, who is used by application when sending SMS, but only in the range of local e-mail system (i.e. ex. EX: address of Exchange server).
The delivery report will be sent to this address.
fromSMTP (text string) SMTP address of the user who is used by application when sending SMS.
This address is used for formating an outgoing SMS (if NoModify=False).
language (text string) User's language code, whos used by application when sending SMS.
You can use the same codes, as used in MobilChange - a names of subdirectories in MobilChange/data/ directory, ie. CZ, UK, GE...
DR (True/False) If is True, the delivery report is required. If is False, the delivery report is not required.
(return
value)		 Text string "OK", when everything is alright,
string "ERROR" in the case when an error has occured.

Usage example:
  
Dim rc
rc = MobilChange.SendSMS( "+420603899285", "Hello, World!", True )
MXLog "MobilChange.SendSms() = " & rc
If rc <> "OK" Then
    MXLog "ERROR: " + MobilChange.LastError
End If
  

back to top of page

Function MobilChange.SendSMSEx()

Function MobilChange.SendSMSEx() sends SMS message, but it has more options than SendSMS(). Syntax is as follows:

MobilChange.SendSMSEx( To, Text, Nomodify, fromName, fromEmail, fromSMTP, language, DR, SendNotify, Priority, UserAppId, OtherOptions )
To (text string) The phone number of recipient.
Text (text string) Text of message.
NoModify (True/False) Pokud je If is True, the text of message is being sent in exact form as was entered by application. If is False, text is processed via MobilChange server in the same way as sent e-mails, i.e. the spaces are removed, czech is recoded etc.
FromName (text string) The name of user whos name is used by application when sending SMS. Use "$Aapp_name" here (without quotations).
The delivery report will be sent to this name.
FromEmail (text string) E-mail address of the user, who is used by application when sending SMS, but only in the range of local e-mail system (i.e. EX: address of Exchange server). Use "$Aapp_name" here (without quotations).
The delivery report will be sent to this email.
FromSMTP (text string) SMTP address of the user who is used by application when sending SMS. Use "$Aapp_name" here (without quotations).
This address is used during formatting of the message being sent, if NoModify=False.
Language (text string) User's language code, which is used by application when sending SMS.
Delivery report will be sent in this language.
Use "AA" for applications (without quotations).
DR (True/False) If True, delivery report is required. if False, application doesn't request delivery report.
SendNotify (True/False) If True, information about sending into SMS center is required. If False, application doesn't require information about sending into SMS center.
Priority (text string) Message priority. Allowed values: "high", "normal", "low" (without quotations).
UserAppId (text string) Message application identifier. If it is used, it can be found also in report about sending/(non)delivering, so application knows which message is related to.
OtherOptions (text string) Other settings, separated by "|". Available settings:
  • from_number=XXXX - phone number which will be set as sender of the SMS (linedriver must support this feature - only on direct connection to GSM operator, and this number must be enabled by operator)
  • via_line=YYYY - through which Mobilchange line this message will be sent
(return
value)		 Text string "OK", when everything is alright,
string "ERROR" in the case when an error has occured.

back to top of page

MobilChange.LastError Property

MobilChange.LastError property contains text description of the last error resulting from the script subsystem of MobilExChange.

A sample usage can be found in the description of MobilChange.SendSMS() function.

back to top of page

MXLog() Function

MXLog function is used for logging program events. By default, events are written on console listing only when using debugging mode of UMS.TaskManager service. Syntax:

MXLog text

A sample usage can be found in the description of MobilChange.SendSMS() function. Function has no return value.

New from MobilChange 3.0: MXLog function can also write the message text into log file "\Mobilchange\log\<date-YYYYMMDD>.<script-name>.txt".
Using of filelog is set in registry:

File logs are turned off after installation.

back to top of page

Function MXSendMail()

Function MXSendMail send an e-mail message (regardless on type of e-mail server you're using). Syntax:

MXSendMail(SenderName, SenderEmail, RecipientName, RecipientEmail, Subject, Text, Priority)

where Priority is number - 1 (low), 2 (normal) nebo 3 (high). If you are using Lotus Notes gateway, then SenderName, SenderEmail parameters are ignored - they are taken from Notes ID of the user, under which context gateway runs.

Return value is text string

Sample of usage:
  
rc = MXSendMail ("SMS server", "smss@yourfirm.com", "Charles Brown", "cbro@hotmail.com", "Automatic reply", _
	"Your SMS from " & FromNumber & " was received and processed at " & Now, 2)
 

back to top of page

Function MxDeleteSMS()

Function MxDeleteSMS allows to delete incoming SMS any time during processing. Standard behavior is like this: An error in your application leads to repeated application starting - and if it sends SMS, user receives still the same SMS. Now you can at any point of incoming SMS processing (inside OnReceivedSMS or OnNotification) call MxDeleteSMS function, which immediately deletes incoming SMS - so in case of error next SMS will be processed. Function has no return value. Syntax:

MxDeleteSMS

Sample of usage:
  
Function OnReceivedSMS( FromNumber, TimeReceived, MessageBody ) 

        MxDeleteSMS 

         ... SMS processing  continues here ...
 

back to top of page

Adding Script to MobilChange

If you want to use your script application in MobilChange, you have to add it to the system and set forwarding and filtering of incoming SMS, so it would receive only messages relevant to it.

Adding of scripts into MobilChange is described thoroughly in this document.

For editing forwarding rules use MxRouteCfg program.

back to top of page

Script Debugging

If you want to see output of your script on the screen you can run UMS.TaskManager in debug mode. Go to Start menu and select Programs -> Mobilchange -> Scripting -> Run UMS.TaskManager on desktop. UMS.Taskmanager will start in debug mode, precompiles scripts and after a while (max 30 seconds) start registered applications. The screen will display output of all applications running in UMS.TaskManager.

Now click on the icon in the upper left corner of the console window and select "Properties", "Layout" tab and set "Screen buffer size" "Height" to 9999. When finished, click "OK" and "Save settings for all windows with same title". A scrollbar will appear on the right side of the console window so you can view older outputs. Press a [Pause]/[Break] key to pause all running programs and their output, pressing any key will activate them.

Press "Ctrl-C" keys in the console window to stop UMS.TaskManager debugging (this applies also for running script as described below).

Another option is to disable task being debugged in umsTaskCfg and run it "manually" from command prompt by this command:
cscript script_name.wsf
or, if you require to use debugger, by:
cscript //X //D script_name.wsf

If you want your application to run in a separate window (so its output was not mixed with the output of other UMS.TaskManager applications), press "Ctrl-C" to quit UMS.TaskManager, and using umsTaskCfg switch "Share console" setting off for this application (in normal tasks). Then start debugging again.

Warning for VoiceChange users: VoiceChange also uses UMS.TaskManager. VoiceChange will not therefore service any incoming calls during the time when UMS.TaskManager is stopped (not running either as a service nor in debugging mode)!

back to top of page