SendSMS Manual

Contents

Licence

SendSMS can be tested for a period of 20 days without any charge. To use SendSMS after this period it has to be registered. Every user has to agree to our Allgemeinen Nutzungs- und Geschäftsbedingungen (sorry, but until now this document exists only in German language).

Summary

SendSMS is a program to send and to receive short messages (SMS) to GSM phones or pagers using the protocols TAP, UCP, SMPP, CIMD2 or GSM. SendSMS can also play/record voice messages.

SendSMS has (among others) the following topics:

The Server-Edition has all features of the Standard-Edition and additionally the following features: The Professional-Edition has all features of the Server-Edition and additionally the following features: Topics marked with (*) are only available in the registered version.

Installation

You have only to decompress the ZIP file (alternatively the tar.Z file) in a temporary directory and to call 'setup' or './setup'. The installation program asks for the most recent parameters (to test SendSMS) and copies the required files into the destination directory.

After running setup you should edit the file sendsms.pro and delete all not required provider definitions. For some providers there are multiple definitions (modem, ISDN, GSM) preconfigured, from which you should delete all not required or move the one you use to the top.

Attention, before any automated call of SendSMS test wether the hangup procedure (ESCAPE Sequence or dropping DTR) works with your local modem.

In the Unix versions the owner of the file sendsms must have enough rights to use the modemdevice and to create files (in the spool directory, lock directory, ...) and the Set-User-ID Bit has to be set.

Configuration

Normaly there is no more configuration required after running the setup program. With the configuration files and the command line parametere you have although the possibility to adapte SendSMS for optimal use in many different cases.

To configure SendSMS, edit the file sendsms.cfg.

In the file sendsms.pro you can define the different providers (which provider uses TAP, UCP, ..., which phonenumbers are to be used for them and what is the predial code for them).

Your personal phone book with aliases can be defined in the file sendsms.pbk.

Comments are always prefixed by ';'.

All configuration files will be searched by default in the directory in which the executable is located. This can be changed by specifying explicit a configurationfile on the command line or by setting the environment variable SendSMS. In the latter case the value of this environment variable will be used as the searchpath for the configurationfiles.

sendsms.cfg

In this file you can configure SendSMS in the chapter [SendSMS]. In the chapter [Device] you can configure your communication interface (devices) and the in chapter [SMSGUI] the usage of the graphical frontend. The chapters [ALLOW] and [Deny] are used to define user access restrictions and [BLACKLIST] to specify numbers to which no messages should be sent. In the registered version you can define as many devices as you want. In the connection phase SendSMS tries to use the first defined device. If this went wrong (device is locked) the next one is used. If no device can be used there will be a delay (REDIALDELAY) and then the whole will be repeated (REDIALCOUNT).

In the chapter [SendSMS] you can specify the following keywords to configure SendSMS. Every keyword has to be entered in an own line.

BINLOCKS=0
Specifies whether the lockfile should be binary or ascii (only unix).

COUNTRYCODE=+49
Specifies the international country code (fpr example '+49' for Germany or '+1' for North America). If this parameter is not or wrong specified SendSMS will dial for national calls also the international prefix with the country code which won't work.

FOOTER=
Specifies an optional footer line (text which will be appended to every message) [only available in the registered version]

HEADER=
Specifies an optional header line (text which will preceed every message) [only available in the registered version]

INTERNATIONALPREFIX=00
Specifies a sequence of digits to substitute a '+'sign in front of a phone number and to identify international numbers (default: "00").

LOCKDIR=/var/spool/uucp
Specifies the directory to look for and to generate a lockfile (only unix).

LOGFILE=sendsms.log
Specifies a file in which all actions will be logged. If you specify 'syslog' (only unix) the logging will be handled through the syslog daemon (Facility=LOG_DAEMON, Priority=LOG_INFO). [only available in the registered version]

LOGLEVEL=255
This parameter can be used to define different levels of logging. The specified value will be treated as a bit field, with following used bits:
Bit0informative messages (for example that a message has been received)
Bit1Warnings (for example that the SMSC has overridden the validity period)
Bit2Errors (for example that a provider can not be accessed)
[only available in the registered version]

LONGDISTANCEPREFIX=0
Specifies a digit (maybe multiple), which are required for making national long distance calls (if you for example want to dial the international number +49 721 9109550 from within Germany then the country code '+49' has to be substituted by the LONGDISTANCEPREFIX 0).

MAXERRORS=
Specifies the count of errors (not transmitted messages) to accept until SendSMS will be terminated. If this parameter isn't set or is set to 0 the program will not terminate after an error. This parameter has only sense if you send messages to multiple recipients. Running in server mode this parameter is ignored.

PHONE=
Your own phonenumber, from which the message will be submitted.

PRIORITY=-5
With this you can set the priority to execute SendSMS. The value has to be in the range from -15 (high priority) to 15 (low priority).

RCZEROIFOK=1
Specifies that the returncode 0 should be used if one or messages have been successfully sent (Unixstyle). This should be used for example for usage within an email system. If this parameter isn't set the count of submitted messages wil be returned.

RECEIVEDIR=received
Specifies the directory where received SMS's should be saved (GSM). [only available in the registered version]

REDIALCOUNT=3
Specifies the count of redial attempts (see RETRYCOUNT, too). [only available in the registered version]

REDIALDELAY=60
Specifies the count of seconds to wait between two dial attempts. While this time the modem will not be locked. [only available in the registered version]

RETRYCOUNT=3
Specifies the max. number of retrys to send a message. Running in server mode this means how often the message is leaved in the spool directory. In opposit to REDIALCOUNT this will take effect after every faulty transmission and not only if there is no available modem or the connection is not established. (after faulty transmission) [only available in the registered version]

RETRYDELAY=60
Specifies the count of seconds to wait between two dial attempts. While this time the modem will not be locked. [only available in the registered version]

SHOWURL=0
Suppress appending 'http://www.bai.de' to the outgoing message. [only available in the registered version]

SHOWSENDSMS=0
Suppress appending 'SendSMS from ...' to the outgoing message. [only available in the registered version]

SPOOLDIR=/var/spool/sendsms
Specifies the directory to spool messages. [only available in the registered version]

UNSENTDIR=unsent
Specifies a directory in which unsent messages (server mode) are archived.

In the chapter [Device] you can specify the following keywords to configure your modem. Every keyword has to be entered in an own line. (Please check your modem description (if you have one) for the corresponding modem commands)

ADDRESS=
Specifies the IP-address of an ISDN-router for usage with a RemoteCAPI (BINTEC extensions).

BAUD=4800
Specifies the baudrate (300, 600, 1200, 2400, 4800 or 9600). This value is only used if it isn't defined in sendsms.pro for the provider to be called. (not used with TAPI)

BCHANNELINFO=3,0,0,0,0,ff
Using a leased line with CAPI2.0 the operation parameters have to be defined here (specifying single bytes in hey format sperated with comma). The coding scheme can be found in the CAPI documentation. The most common codings are listed below:
3,0,0,0,0,ff 1. channel, 64 kbit/s, DTE mode
3,1,0,0,0,ff 1. Channel, 64 kbit/s, DCE mode
3,0,0,0,0,0,ff 2. Channel, 64 kbit/s, DTE mode
3,1,0,0,0,0,ff 2. Channel, 64 kbit/s, DCE mode

BEEP=AT#VTS=[960,0,6]
Specifies a command to generate a tone signal (recoding of a voice message with a voice modem). (not used with TAPI)

CONNECTTIMEOUT=40
Specifies the time (in seconds) to wait for a connection after the dial command.

CONTROLLER=1
If you are using multiple ISDN adapters in your computer you specify here to which adapter the definiton belongs.

DATABITS=8
Specifies the count of databits (7 or 8). This value is only used if it isn't defined in sendsms.pro for the provider to be called. (not used with TAPI)

DEVICE=COM1
Specifies the device to which your modem is connected. (Attention: on unix you have to take notice that the owner of the file sendsms is allowed to use the device).

If you are using CAPI 2.0 you have to specify the path to the CAPI-DLL/-Shared-Object (Windows, OS/2, Linux) or to the CAPI-device (Unix) here.

Using Windows SendSMS tries first to open the device exclusive. If this doesn't work (maybe because of RAS) the device is opend using the TAPI-interface. With this you have the ability to share the modem with other applikations, but you can't use all features of SendSMS.

DEVICETYPE=Modem
Specifies the kind of hardware to be used for communication (Modem, Voice modem, GSM 07.05, CAPI 2.0, CAPI 2.0 (BINTEC), X.25 (EICON) or SERIAL).

DIALPREFIX=ATDT0w
Specifies the command to dial a number.
Using the CAPI interface with a PBX you can specify here the number ti get a line (normally 0). (not used with TAPI)

DIALSUFFIX=
For some modems/ISDN-Terminaladapters it is required to append some additional AT commands to the phonenumber. This commands can be defined here. This value is only used if it isn't defined in sendsms.pro for the provider to be called. (not used with TAPI)

ESCAPE=+++
Specifies the escape sequence to switch the modem from data to command mode. ATTENTION! The escape sequence is only used, if you explicity specify it. If not specified the DTR signal will be dropped for one second. Define the escape sequence only if dropping DTR doesn't work.

HANGUP=ATH
Specifies the command to hang up.

INIT=ATQ0E1V1L1
Specifies the initialization command for your modem. You have to set your modem to:

(not used with TAPI)

INIT2=
Sepcifies a second initialization command for your modem. (not used with TAPI)

LINETYPE=ANALOG
Specifies the kind of phone line (ANALOG, ISDN, X.25 or X.31). This parameter can also be defined within a provider definition. SendSMS will automatically select a corresponding device for a selected provider.
For example: If you select the provider D1_ISDN (LINETYPE=ISDN) then only Devices which are also defined with LINETYPE=ISDN are used.

MSGDELAY=<n>
Specifies a count of seconds to wait between sending two messages within one single connection (normally not required).

MSN=24
Specifies the phone number of the ISDN adapter (if you are using CAPI 2.0). Here you have to enter the number of the line to which the ISDN adapter is connected. Using a PBX this is the internal number. If you specify no or a wrong number it is possible that you can't get any connection. This parameter can be overriden by the command line option -m.

NAME=Modem1
Identifies a devices by a unique name. Using that name with the command line option -d a specific device can be preselected. This is only required if multiple devices are configured and the automatic device choice should be avoided.

ORIGINATINGADDR=01234..
Specifies the originating address (local number) to use for X.25 (only in Professional-Edition).

PACKETLEN=128
Specifies the X.25 or X.31 packet length (default: 128).

PARITY=NONE
Specifies the kind of parity (NONE, EVEN or ODD). This value is only used if it isn't defined in sendsms.pro for the provider to be called. This command will be executed after the standard initialization. For some GSM cards it is necessary to specify a memoryaddress (AT+CPMS="ME") what can be done with this parameter. (not used with TAPI)

PDUWITHOUTSCA=1
Some GSM modems require a PDU without the SCA (in contrast to GSM 07.05). This parameter ist for example required for Siemens M1, Falcom A1 or Xircom CreditCard, and may not be set for Siemens E10, Siemens S10, Nokia DataCard, Kokia CarPhone or Nokia Data Suite.

PLAYDTMF=AT#VTS=
Specifies the command to play a DTMF sequence (only voicemodem). (not used with TAPI)

PIN="1234"
Specifies the PIN for your SIM (GSM devices). If you are using a GSM card which doesn't require any PIN (AT+CPIN? doesn't work) you have to leave this blank. For some devices you have to enclose the PIN in quotes (") but be aware that this can result in errors with other devices.

PORT=6000
Using the RemoteCAPI (BINTEC extensions) this specifies the port on which a ISDN-router listens for RemoteCAPI calls. Using an Eicon-X.25-card this defines the port to use for makeing a connection.

PUK="1234"
Specifies the PUK for your SIM (GSM devices). If you are using a GSM card which doesn't require any PIN (AT+CPIN? doesn't work) you have to leave this blank. For some devices you have to enclose the PIN in quotes (") but be aware that this can result in errors with other devices.

RESET=ATZ
Specifies the command to reset your modem (normally ATZ).

RTSCTS=1
Specifies to use the hardware flowcontrol.

SIMPHONE= Specifies the phone number of the SIM used with the corresponding GSM module. This parameter is only required if the module doesn't support the command +CNUM.

STARTVOICEMODE=AT#CLS=8
Specifies the command to set a voice modem to voice mode. This is required for recording/playing voice messages. (not used with TAPI)

STOPBITS=1
Specifies the count of stopbits (1 or 2). This value is only used if it isn't defined in sendsms.pro for the provider to be called. (not used with TAPI)

STOPVOICEMODE=AT#CLS=0
Specifies the command to cancel voice mode (voice modem). (not used with TAPI)

SUPPRESSREINIT=1
If this parameter is used, a device will only be initialized opening it the first time (only in server mode). With all subsequent openings communication will start immediately without any initialization. So you can get a much better throughput. This parameter should only be used if it is sure, that no other application will access the device and maybe change the settings.

TEI=1
Specifies the TIE (Terminal Endpoint Identifier) to be used for a X.31 connection.

USEDCHANNEL=1
Specifies that the D-channel should be used for a X.31-connection. If this parameter isn't set =1 a B-channel will be used.

VOICECOMPRESSION=ALAW
If this parameter is specified then recoreded messages will be stored as WAV-files and you can play WAV-files if they use a supported format. Until know ALAW (ISDN in Europe) and ULAW (ISDN in USA) are supported (8kHz, 1 channel, 8 bit).

VOICERECEIVE=AT#VRX
Specifies the command for a voice modem to start voice receive mode (recording of voice messages). (not used with TAPI)

VOICETRANSMIT=AT#VTX
Specifies the command for a voice modem to start voice transmit mode (playing of voice messages). (not used with TAPI)

WAITAFTERWRITE=1
Specifies the count of seconds to wait after writing to the device (normally 0)

WINDOWSIZE=2
Specifies the X.25 window size (default: 7) or the B3 window size for use with X.31 (default: 2).

X31CHANNELS=0,0,1,1,0,0
Specifies the X.31 channels to be used. You have to specify - speperated by commas -

If this parameter isn't specified the default (0,0,1,1,0,0) will be used, what will work in most cases.

XONXOFF=1
Specifies to use the software flowcontrol.

In the chapter [SMSGUI] you can specify the following keywords. Every keyword has to be entered in an own line.

cfgEditable=1
Specifies whether an enduser of the graphical frontend may modify the configuration file sendsms.cfg (=1) or not (=0). Even if this parameter is set to 1 an enduser can only modify sendsms.cfg if he has write access to the file.

proEditable=1
Specifies whether an enduser of the graphical frontend may modify the provider definition file sendsms.pro (=1) or not (=0). Even if this parameter is set to 1 an enduser can only modify sendsms.pro if he has write access to the file.

showLogfile=0
Specifies whether an enduser of the graphical frontend may be able to display the logfile of SendSMS (=1) or not (=0). Even if this parameter is set to 1 an enduser is only able to display the logfile if he has read access to the logfile.

In the chapters [ALLOW] and [DENY] you can specify the following keywords. Every keyword has to be entered in an own line. Allways only one of both lists will be used. If both are defined the ALLOW list will be used.

USER= This parameter can be defined multiple times. Each time this parameter appears it will specify a userid which may or may not use SendSMS. If the userid are specified in the chapter [ALLOW] only these users may use the program. If the users are specified in the chapter [DENY] all useres except the specifies may use the program.

In the chapter [BLACKLIST] you can specify the following keywords. Every keyword has to be entered in an own line.

PHONE= This parameter can be defined multiple times. Each time this parameter appears it will specify a phone number to which no messages should be sent. If the specified number ends with a '&' this will be a prefix. That means that all numbers will be blocked which starts with the specified sequenz. The numbers have to be specified in that format that would be sent to the provider, so you have to notice possible transformations (see parameter PREFIX).

sendsms.pro

In this file you can define different providers. Many providers are preconfigured and can be used without any changes. But all not required provider definitions should be deleted. For some providers there are multiple definitions (modem, ISDN, GSM) preconfigured, from which you should delete all not required or move the one you use to the top. For a provider definition you have to enter a chapter by entering a line of the form
[<provider>]
In every chapter you can specify the following parameters:
(for all UCP-providers you should set MODEMINIT in a way to force your modem to use V.42/LAPM)

ADDRESS=<ip-address>
This parameter specifies the IP address of a provider. In case of a TCP/IP connections you have to specify this instead of PHONE (see also PHONE).

ADDRNPI=9
Specifies the NumberingPlanIdentity. This parameter is only required for use with large accounts with UCP or SMPP. Please ask your provider for the value.

ADDRTON=0
Specifies the TypeOfNumber. This parameter is only required for use with large accounts with UCP or SMPP. Please ask your provider for the value.

ADDRESSRANGE=
Specifies the Address Range (only SMPP). Please ask your provider for the value.

AUTOALERT=<phone number>
This parameter is only used in server mode and if the server was started with the parameter -aRECEIVE to read incoming messages. In this case every time the server processes the queue for the corresponding provider the service computer is called and asked for incoming messages for the specified phone number (using a less queue delay this can be very expensive). Using CIMD2 a phone number has to be specified, but this number isn't used.

AUTOCONNECT=<n>
This parameter is only used in server mode and if the server was started with the parameter -aRECEIVE to read incoming messages. In this case every time the server processes the queue for the corresponding provider the service computer is automatically called and SendSMS waits the specified count of seconds for incoming messages. The difference to AUTOALERT is that there is only traffic on the line if there are realy messages waiting. In ths case of a X.25/X.31 connection this will cause no additional costs.

B1PROTOCOL=64K-HDLC
With this parameter you specify which B1 protocol (ISDN, physical layer) should be used. This is only required if the connection is established with CAPI and the provider doesn't support the default protocols. Using an ISDN terminaladapter you have to select the protocol with an AT command in MODEMINIT. Following selections are possible:

64K-HDLC 64 kbit/s with HDLC framing
64K-TRANS 64 kbit/s bit-transparent operation with byte framin from the network
V.110-ASYNC V.110 asynchronous operation with start/stop byte framing
V.110-SYNC V.110 synchronous operation with HDLC framing
T.30-FAX3 T.30 modem for fax group 3
64K-INVERT 64 kbit/s inverted with HDLC framing
56K-TRANS 56 kbit/s bit-transparent operation with byte framing from the network
MODEM-NEGOTIATION Modem with full negotiation
MODEM-ASYNC Modem asynchronous operation with start/stop byte framing
MODEM-SYNC Modem synchronous operation with HDLC framing

B2PROTOCOL=X.75-SLP
With this parameter you specify which B2 protocol (ISDN, data link layer) should be used. This is only required if the connection is established with CAPI and the provider doesn't support the default protocols. Using an ISDN terminaladapter you have to select the protocol with an AT command in MODEMINIT. Following selections are possible:

X.75-SLP ISO 7776 (X.75 SLP)
TRANS Transparent
SDLC SDLC
LAPD-X.25 LAPD in accordance with Q.921 for D channel X.25
T.30-FAX3 T.30 for fax group 3
PPP Point-to-Point Protocol
IGNORE Transparent (ignoring framing errors of B1 protocol)
MODEM Modem with full negotiation
X.75-SLP-V.42 ISO 7776 (X.75 SLP) with V.42 bis compression
V.120-ASYNC V.120 asynchronous mode
V.120-ASYNC-V.42 V.120 asynchronous mode with V.42 bis compression
V.120-TRANS V.120 bit-transparent mode
LAPD LAPD in accordance with Q.921

B3PROTOCOL=TRANS
With this parameter you specify which B3 protocol (ISDN, network layer) should be used. This is only required if the connection is established with CAPI and the provider doesn't support the default protocols. Using an ISDN terminaladapter you have to select the protocol with an AT command in MODEMINIT. Following selections are possible:

TRANS Transparent
T.90NL T.90NL with compatibility to T.70NL
X.25-DTE-DTE ISO 8202 (X.25 DTE-DTE)
X.25-DCE X.25 DCE
T.30-FAX3 T.30 for fax group 3
T.30-FAX3-EXT T.30 for fax group 3 extended
MODEM Modem

BAUD=4800
Specifies the baudrate (300, 600, 1200, 2400, 4800 or 9600). If this parameter isn't specified the value from sendsms.cfg will be used.

BDATALEN=1024
Specifies the max. length of data blocks (CAPI; this is not the length of a message). The value has to be in the range between 128 and 2048.

CIP=UNRESTRICTED-DIGITAL
With this parameter you can specify (normally not required) a CIP value (Compatibility Information Profile) for connections with CAPI. Using an ISDN terminaladapter you have to select the CIP value with an AT command in MODEMINIT. Following selections are possible:

SPEECH Speech
UNRESTRICTED-DIGITAL unrestricted digital information
RESTRICTED-DIGITAL restricted digital information
3.1KHZ-AUDIO 3.1 kHz audio
7KHZ-AUDIO 7 kHz audio
VIDEO Video
PACKET-MODE packet mode
56KBIT-RATE-ADAPTION 56 kbit/s rate adaption
UNRESTRICTED-DIGITAL-WITH-TONES unrestricted digital information with tones/announcements
TELEPHONY Telephony

DATABITS=8
Specifies the count of databits (7 or 8). If this parameter isn't specified the value from sendsms.cfg will be used.

DEVICE=
Here you can specify the name of a device (as defined in sendsms.cfg with the parameter NAME) to force the usage of this device for that provider.

DIALSUFFIX=
For some modems/ISDN terminaladapters it is required to append some additional AT commands to the phonenumber. This commands can be defined here. If this parameter isn't specified the value from sendsms.cfg will be used.

LINETYPE=ANALOG
Specifies the connectiontype of the specified phone-number/address (for that provider) (ANALOG, ISDN, TCP, X.25 or X.31). This parameter can also be defined within a device definition. SendSMS will automatically select a corresponding device for a selected provider.
For example: If you select the provider D1_ISDN (LINETYPE=ISDN) then only Devices which are also defined with LINETYPE=ISDN are used.

MAXMSG=
Specifies the max. count of messages which can be send in a single connection. If this parameter is specified the connection is canceled after the corresponding count of messages is sent and if required a new connection will be established. This is neccessary because some providers have a limit for sending multiple messages per connection. Running in server mode this parameter specifies the max. count of messages to process before the server continues to handle the next provider.

MODEMINIT=
Specifies an additional initialize command for the modem. This command is called after the initialize command defined in sendsms.cfg and doesn't substitute it. Commonly this command can be left blank. It is only needed, if you want to force your modem to use a specific protocol. For example you should use V.42/LAPM for providers using UCP.

MSGDELAY=<n>
Specifies a count of seconds to wait between sending two messages within one single connection (normally not required).

MSGLEN=
Specifies the max. length of a message (number of characters respectively number of seconds). If the protocol is SKYPER or SCALL (German pagers) then this parameter is set automatically. In the unregistered version the max. length is limited to 60 characters or 5 seconds.

MSGTYPE=
Specifies the kind of message: NUMERIC (only digits), ALPHANUMERIC (characters and digits) or TONE (no characters, only beeping). If the protocol is SKYPER or SCALL (German pagers) then this parameter is set automatically. In case of Scall and Skyper the modem has to be configured for not filtering XON/XOFF characters.

ORIGINATINGADDR=01234..
Specifies the originating address (phone number) to use for that provider (only in Professional-Edition).

PASSWORD=
For some providers a password (Authentication Code for UCP) is required, which you can specify here. Please ask your provider for the value.

PARITY=NONE
Specifies the kind of parity (NONE, EVEN or ODD). If this parameter isn't specified the value from sendsms.cfg will be used.

PHONE=
Specifies the phonenumber of the provider. If the last character of the number is a '&', this means that the specified number will be appended by the number of the recipient.
If you are using the GSM protocol you have to enter the SMSC-address in the form +<a><b><c>, where <a> is the countrycode (without zeros), <b> the areacode (without zero) and <c> the phonenumber.
This parameter can be defined multiple times.

PROTOCOLTIMEOUT=60
Specifies the time (in seconds) to wait for a response from the service computer. If this parameter isn't defined following default values will be used, which are higher then the protocol limits:

TAP 30 seconds
UCP 120 seconds
GSM 160 seconds
SMPP 30 seconds
CIMD2 30 seconds

PORT=<n>
Specifies the (destination) port number to use for a TCP/IP connection.

PREFIX=
Specifies the predialcode for the corresponding provider. With this prefix SendSMS tries to identify the provider to which the phonenumber of the recipient belongs. If the value contains a | the value consists of two parts. The first part is to recognize the provider and the second is to replace that prefix. So you can remove a prefix (PREFIX=+491656|) or replace a prefix with another (PREFIX=+49179|49179). This parameter can be defined multiple times.

PROTOCOL=
Specifies the protocol (TAP (Telocator Alphanumeric Protocol), TAPAIM (TAP-protocol with AIM-extensions), UCP (Universal Computer Protocol), GSM (Global System for Mobile communication), UUS (User-User-Signalling), SMPP (Short Message Peer to Peer), CIMD2 (Computer Interface to Message Distribution), DTMF, Scall, Skyper or CityRuf) which the provider uses. DTMF is for use with some pager services (only numeric messages) and can only be used with CAPI 2.0 or with a voicemodem. UUS is an Euro-ISDN service (not supported in all countrys) and can only be used with CAPI 2.0.

For the protocol UCP you can additionally select between different function codes for sending (UCP[01], UCP[30] or UCP[51]; using a large account you should use function 51). The functions 30 and 51 will additionally transmit the originator address (phone number) and a validity period (if defined). But these functions are not supported by all providers.

SOURCEPORT=<n>
Specifies the (source) port number to use for a TCP/IP connection.

STOPBITS=1
Specifies the count of stopbits (1 or 2). If this parameter isn't specified the value from sendsms.cfg will be used.

SYSTEMID=
Specifies the System ID (only SMPP). Please ask your provider for the value.

SYSTEMTYPE=
Specifies the System Type (only SMPP). Please ask your provider for the value.

TRANSTABLE=tap.ctt
Specifies a character translation table (see also Character Translation Tables).

UCP60PASSWORD=
If a UCP provider is using the password option (function 60) you have to define that parameter. Normaly this is only required for large accounts. Additionally the parameter USEUCP60=1 has to be defined.

USERID=
For some providers (CIMD2 or UCP (function 60)) a UserID is required, which you can specify here. Please ask your provider for the value.

USEUCP60=1
Specifies that a session has to be started (with UCP function 60) before SMSs can be sent. Additionally the parameter UCP60PASSWORD should be defined.

WAITAFTERCONNECT=
For some providers (using the UCP-protocol) there must be a delay between the Connect message of the modem and the first outgoing message. This parameter specifies the duration in seconds of this delay. This seems only be necessary if your modem isn't set to V.42/LAPM. So the better way is to set in MODEMINIT (see below) such an AT command.

example

[D1]
PHONE=01712092522
PROTOCOL=TAP
PREFIX=+49171
MSGTYPE=ALPHANUMERIC
MSGLEN=160

sendsms.pbk

In this file you can enter a chapter for every in sendsms.pro defined provider with aliases. Every chapter starts with a line of the form:
[<provider>]
Every alias has to be entered in an own line and has to be of the form:

<alias>=<phone>

The phone book is only available in the registered version!!!!

example

[D1]
wobo=01714160598        ; Wolfgang Böcherer

Character Translation Tables

Due to the fact that every by SendSMS supported protocol uses its own character set and many providers modify these charcter sets SendSMS offers the possiblity to define specific character translation tables for every provider. If for one provider no explicit table is specified a default table is used. To define a table for a provider you have to generate a file in the following format an specify this file within the provider definition in the parameter TRANSTABLE:
For every chacter you have to enter one line with three hexcodes, separated by blanks. The first code specifies the code of the character to translate, the second the code used by the provider for that character and the third the code (ISO 8859-1) to translate back a received character.

Voice messages

Additionaly to the ability to communicate with GSM phones and pagers SendSMS can also communicate with "normal" phones. To use this feature you have to use a voice modem or CAPI 2.0. There are preconfigured entrys in the provider file (sendsms.pro) to use voice messages. To play a voice message that message has to be in the native coding format of the corresponding device (this formats differ between different modem manufactures). To play voice messages in different formats you have to use conversion programms. Many such conversion programms are freely available (for example sox or mgetty+sendfax). To play a voice message you have to call SendSMS in the same way as if you send a text message, except that you have to explicitly specify the predefined provider VOICE (for voice modem) or VOICE_ISDN (for CAPI 2.0):
sendsms -pVOICE 07246942484 -fvoice.dat
oder
sendsms -pVOICE 07246942484 < voice.dat
In both cases the specified number will be called and the voice message stored in the file voice.dat will be played.

Server mode

In the registered version of SendSMS is a server mode available (-q). With this, you can force a SendSMS-instance to run in the background and check the spool directory in regular periods. If there are messages to send they will be send all at once. If a server is running all other instances of SendSMS spool their messages, instead of sending them directly over the phoneline. So you have the ability to collect messages and send them within one single connection and to save money. With additional parameters you can force SendSMS, whether a server is running or not, to spool the messages or to send them directly.

If you are using a GSM device you have the ability to receive and store SMSs (-aRECEIVE).

To spool messages you only have to call SendSMS or you can generate the spool files by yourself (ASCII format). The spool files have to be placed in the directory <SPOOLDIR> (defined in sendsms.cfg). In that directory there has to be a subdirectory for every provider for which messages are spooled. Every spooled message has to be placed in a separate file, which should not end with '.dat'. The following is a example for a spool file:

[D1_ISDN]
COUNT=0
PHONE=491714160598
DCS=240
SPLIT=10
FROM=wobo
SMS=This is a spool file.
The parameter COUNT specifies the actual count of send attempts, SPLIT specifies the max. number of SMSs the message should be split into and DCS means DataCodingScheme (see GSM 03.38). Each line in the spool file may contain up to 3000 characters. If the spooled message is longer you have to specify the message in multiple lines (each up to 3000 characters and starting with SMS=). For Linefeeds you have to enter the escape sequence '\n' and for a backslash '\\'.

Userexit

With the parameter -u you can specify an userexit. This is an external program or script, which will always be called by SendSMS when a message has been sent or received or when a message couldn't be sent (only if running in server mode). The called program gets the following command line arguments: The userexit can also be a function located in a DLL or in a so-library (shared object). For that you have to separate the name of the DLL/so-library from the name of the function by a masterspace (@) (-u<dll>@<function>).

Deferred sending and validity period

SendSMS offers the possibility to send messages to a later time. You have to specify that time with a command line parameter (-S).

Another possibility is to send the message now, but to specify with the parameter -D the time at which the service computer should deliver the message.

With the parameter -V a validity period can be specified. If this parameter is specified, the message will be deleted if it couldn't be delivered within the specified period.

Each parameter has to be specified as an offset to the actual time (minutes prefixed with a plus signe, e.g. -S+10) or as an absolute time/date value (hhmmDDMMYYYY (hh = hour, mm = minute, DD = day, MM = month, YYYY = year), e.g. -V203031122020)). These parameters are not supported by all protocols/providers.

Choosing a desired function

Additionally to sending messages SendSMS is also able to query the status of messages, to delete messages and to receive messages. This functionallity depends on the used protocol (UCP, TAP, GSM) and on the used provider. In most cases these functions are only available for GSM service providers and only if the provider uses UCP or the AIM extensions for TAP. It is also required that the used phone line supports CLI (Calling Line Identifikation).

You choose the desired function on the command line by adding the parameter -a<action>. If the parameter isn't specified the value for <action> will be set to SEND. Otherwise you can select between SEND, CONFIRM, RECEICE, STATUS, DELETE and CHGPWD which have the following meanings:

SEND to send a message
CONFIRM to send a message and show the status (whether the message has been delivered or stored on the service computer) afterwards
STATUS to query the status of a former transmitted message
DELETE to delete a former transmitted but not already delivered message
RECEIVE to receive messages
CHGPWD to change the sessopn password (UCP function 60)

In every case the phone number of the recipient has to be specified (at least for the german provider D1 with the format 49171... (to query the status or to delete a message)). To delete a message you have also to enter the identification number/timestamp of the message (will be shown after the message has been transmitted). You can find some examples in the chapter Calling syntax.

Calling syntax

SendSMS will be executed as follows:

sendsms [options] {<phoneNo> | <alias> | -g<groupFile>} [{<message> | < <msgFile> | -f<msgFile>}]

options are (case sensitive):
-a<action> specifies the requested action (SEND, CONFIRM, RECEIVE, STATUS, DELETE or CHGPWD)
-b<pbkFile> specifies the phone book file (sendsms.pbk)
-c<cfgFile> specifies the configuration file (sendsms.cfg)
-C<msgClass> message Class (0-3); see Data Coding Scheme in GSM 03.38 (default is 1; 0 for immediate display)
-d<device> preselect a specific device
-D<deliver time> specifies the time (hhmmDDMMYYYY) when the message should be delivered (from the service computer)
-f<msgFile> specifies the name of a filen which contents will be send as the message
-g<groupFile> specifies the name of a group file with recipient numbers
-h shows the help
-H shows the version of SendSMS
-i installs SendSMS (server mode) as a service (WindowsNT only)
-m<MSN> specifies the MSN to use (CAPI 2.0 only)
-M<SMS> specifies the message to send (required if the message starts with a '-')
-n start SendSMS standalone (even if there is a server running)
-N<n> split the specified message in up to <n> SMSs (default is 1)
-o<originator> sets the originator of the message (default is the user ID)
-O<originatingAddressr> sets the originating address of the message which will be shown to the recipient (only with Professional-Edition)
-p<provider> specifies the provider for the corresponding phonenumber
-P<pidFileName> specifies the pid file to use (default is sendsms.pid
-q<n>[s] start SendSMS as a server and check queue every <n> minutes or [seconds]
-r<proFile> specifies the provider definition file (sendsms.pro)
-R usage of the parameter ReplyPathRequest (see GSM 03.40)
-s spool messages (even if there is no server running)
-S<start time> specifies the time (hhmmDDMMYYYY) when the message should be sent (from the local computer)
-t<character set> selects the character set for the message (iso8859, cp850 or binary)
-u<userexit> specifies a program/batch file which will be launched when a message as been sent or received (Servermodus)
-U<userdataheader> hex coded UserDataHeader (see GSM 03.40) without length (for example for ringing tones)
-v verbose, shows the communication with the device on the screen
-V<validity period> specifies the period (hhmmDDMMYYYY) until the message should be valid
-x uninstalls the service SendSMS (WindowsNT only)

Ex.: sendsms 0171xxxxx "I am testing SendSMS"

You have to specify at least one parameter - the phonenumber of the recipient or an alias (from the phone book). Alternatively the parameter -p can be used to specify the name of a file which contains multiple phonenumbers. With such a file it is possible to send one messages to multiple recipients. The specified file must have the following format:

[<provider1>]
PHONE=<number1>
PHONE=<number2>
PHONE=<number3>
PHONE=<alias1>
PHONE=<alias2>

[<provider2>]
PHONE=<number4>

Inclosed in brackets ([]) you have to specify providers (which are defined in sendsms.pro), followed by multiple lines with phonenumbers of recipients. Every line contains a phonenumber (PHONE=...) of a recipient (number or alias), which belongs to the corresponding provider and to which the message should be send in one connection. In the above example the message will be send to 5 recipients of <provider1> using the same connection. The message will also be send to one recipient of <provider2>.

The second parameter is the message, enclosed by ' (ATTENTION: depending on the shell you are using some characters are substituted by the shell (for example '!') or you have to enclose the message by " instead of '). If you specify the message on the commad line the message may not start with a minus (in that case the message has to be specified with the command line parameter -M). Alternativly you can specify the message by redirecting it from a file (< msgFile) or with the Parameter -f<msgFile>, where <msgFile> is the name of the file that will be send (at least the first n characters). If you specify only one parameter on the command line (the recipient), the message will be read from the console. If you want to send a message to a provider, which can't be identified by the predial code of the recipients phonenumber you have to specify the corresponding provider (as defined in sendsms.pro) with the parameter -p<provider>. For Example: you want to send a message to a Quix-pager. SendSMS can't recognize the provider (Quix_News), because the number has no predial code. That's why you have to specify -pQuix_News.

Binary messages have to be entered hex coded (without length). For every binary character you have to enter two characters (0-9 und A-F). The message "ABC" is hex coded "414243". For ringing tones or operator logos you have also to specify an hex coded UserDataHeader (without length) using the parameter -U. For a ringing tone you have for example to specify -U050415811581 (see GSM 03.40 and Narrowband Sockets Specification (Intel, Nokia)). For ringing tones and operator logos you can also use - instead of the hex coded UserDataHeader - the predefined values -Uringtone, -Uoperatorlogo, -UCompactBusinessCard, -UGenericBusinessCard (vCard), -UvCalendar and -UPicture can be used (if the receiver supports the Smart Messaging Specification).

If you start SendSMS with the parameter -q<n> SendSMS works as a server and checks every <n> minutes (or every <n> seconds if <n> ends with a 's') the spool directory (<n> = 0 means to check only one time and terminate). If there are spooled messages they will be sent with a minimum number of connections. If there are spooled messages they will be sent with a minimum number of connections. If there runs a server every new instance will be started in spoolmode. This can be manipulated with the parameters -s (always spool) and -n (never spool).

The -t parameter specifies in which character set the message is entered. By default SendSMS uses under OS/2 the codepage 850 (cp850) and in all other versions ISO-8859 (iso8859). If the message is not entered in the standard character set then you have to specify this parameter.

Examples:
sendsms 01714160598 test
The message "test" will be sent to the specified number.

sendsms -pD1 -aCONFIRM 01714160598 "This is a test message"
The message "This is a test message" will be sent to the specified number using the provider D1. After transmitting the message the program waits for a confirmation which will indicate whether the message has been delivered to the reciptient or has been stored on the service computer.

sendsms 01714160598 -fmsg.txt
sendsms 01714160598 -dModem1 < msg.txt
In both cases the content of the file msg.txt will be sent to the specified number. In the second case the device Modem1 (parameter NAME in chapter [Device] ins sendsms.cfg) is preselected.

sendsms -ggroup "Alert for all"
The message "Alert for all" will be sent to all numbers which are listed in the file group.

sendsms -pVOICE 07246942484 < voice.dat
sendsms -pVOICE 07246942484 -fvoice.dat
A voice message (voice modem or CAPI 2.0) will be send to the specified number. The file voice.dat has to contain the voice message in the native format for the used device.

sendsms -pUUS 4160598 "This is a test message"
The message "This is a test message" will be submitted to the phone number 4160598 via UUS (only with CAPI 2.0). This will only wotk if the service UUS is supported by the netwotk provider and by both communication partners. The message will be submitted in the D-channel without any fee.

sendsms -pVOICE -aRECEIVE 07246942484 -fvoice.dat
The specified number will be called and a voice message will be stored in the native device format to the file voice.dat.

sendsms -aSTATUS 491714160598 1141863480
The status of the message 1141863480 (this number has been shown after transmitting a message) for the phone number 01714160598 will be queried.

sendsms -aDELETE 491714160598 1141863480
The message 1141863480 for the phone number 01714160598 will be deleted (if the message has not already been delivered).

sendsms -q5s
Starts SendSMS in server mode with a queue delay of 5 seconds.

sendsms -q5s -aRECEIVE
Starts SendSMS in server mode with a queue delay of 5 seconds. Additionaly all defined GSM devices and providers for which the parameter AUTOALERT or AUTOCONNECT is defined are checked for incoming messages.

sendsms -q5s -aRECEIVE -pD1_X31
Starts SendSMS in server mode. Because there is a provider exilicitly specified the server will only process this provider and will keep the phone line open as long as the server runs.

sendsms -aCHGPWD -pD1_X31 password
A connection to the provider will be established to change the password (UCP function 60).

sendsms 01724160598 -tbinary -Uringtone -fringtone
A ringingtone, which is contained in binary form (hex coded) in the file ringtone, will be sent. This is only possible if the receiver supports the Smart Messaging Specification and the provider doe NOT use TAP.

Integration into Email systems

Following .forward file should demonstrate how easy SendSMS can be integrated into an Email system (Unix). You only have to generate a .forward file in your homedir with the following content:
\wobo, "| /usr/local/sendsms/forward.sms"
With this file, all arriving Emails will be forwarded to the userid wobo (here you have to enter your own userid, so that you have the same normal access to the Emails as you will have without the .forward file) and the follwong script forward.sms will be called. This script sends a message (containing the originator and the subject of the Email) to the specified phonenumber by SendSMS.

#! /bin/sh
egrep -ih '^From:|^Subject:' | /usr/local/sendsms/sendsms 01711234567 > /dev/null
exit 0

An direct integration in sendmail is very easy, too. For this you have only to define in sendmail.cf a MTA (for example Msendsms, ...) and in 'Rule Set 0' a rule which defines under which conditions SendSMS or a script file - one like forward.sms - should be called.

Using WindowsNT/Windows 9x it is possible to be informed by SendSMS about incoming emails with the freeware product POSTIE.

Integration into WWW servers

SendSMS can easily be integrated into WWW servers. SendSMS will automatically recognize wether it is invoked from a http server and will handle some special actions in accordance to the environment. As an example for an integration into a http server you can use the Perl script (Perl5) sendsms.cgi. To install that example you only have to copy the files sendsms.cgi and sendsms.ini to the cgi-bin directory of the http server and to adapte the file sendsms.ini (path, language and configuration files). Maybe you have also have to change the path to your Perl interpreter in the first line of sendsms.cgi. Please remember that the userid under which the http-server is running requires access rights to SendSMS.

The script will be invoked by entering the following into the Address field of yout brwoser:
http://<server>/cgi-bin/sendsms.cgi
or by making such a link in your own pages.

Graphical user interface

One optional part of SendSMS is a graphical user interface implemnted in Java (requires Java Runtime Environment (JRE) 1.2 or higher (http://www.javasoft.com/j2se/). To call that user interface you can use the included script or batch files (smsgui). After the starting the user interface for the first time the most requiered input fields are displayed. Selecting the menu option "Settings/Expert mode" you can get more options. After entering a phone number, a message text and selecting the button 'Send' SendSMS will be launched and the output is displayed in an automatically selected page. Every sent message will be stored in a journal which you can use (journals context menu) to query a status report for a message or to delete a message.

X.25/X.31

The SendSMS-Professional-Edition is also able to transmit messages via X.25 or X.31 (X.25 over ISDN). To use X.25 you an Eicon-X.25-card with the required drivers has to be installed. To use X.31 you require a X.31 capable device and the special service X.31 from your telephone company (they will assign you a TEI). With this you only have to define a special provider in sendsms.pro and a device in sendsms.cfg (see below). All other handling is exactly as it is with a modem connection.

Example (X.25):
sendsms.cfg sendsms.pro
[Device]
DEVICETYPE=X.25 (EICON)
LINETYPE=X.25
DEVICE=ex25.dll
CONNECTTIMEOUT=5
PACKETLEN=2048
WINDOWSIZE=7
ORIGINATINGADDR=<local adress>
[D1_X25]
PHONE=012345....
LINETYPE=X.25
PROTOCOL=UCP[51]
PREFIX=+49170|+49170
PREFIX=+49171|+49171
PREFIX=+49175|+49175
MSGTYPE=ALPHANUMERIC
MSGLEN=160
USEUCP60=1 ; only if function 60 is required
UCP60PASSWORD=<password> ; if the password option is used
USERID=<large account>

Example (X.31):
sendsms.cfg sendsms.pro
[Device]
DEVICETYPE=CAPI 2.0
LINETYPE=X.31
DEVICE=capi2032.dll
CONNECTTIMEOUT=5
USEDCHANNEL=1
TEI=1
X31CHANNELS=0,0,1,2,0,0
MSN=25
[D1_X31]
PHONE=012345....
LINETYPE=X.31
PROTOCOL=UCP[51]
PREFIX=+49170|+49170
PREFIX=+49171|+49171
PREFIX=+49175|+49175
MSGTYPE=ALPHANUMERIC
MSGLEN=160
USEUCP60=1 ; only if function 60 is required
UCP60PASSWORD=<password> ; if the password option is used
USERID=<large account>

TCP/IP

The SendSMSProfessional-Edition is also able to transmit messages via TCP/IP. To use TCP/IP connections you have to install and configure TCP/IP on your computer and to define a special provider in sendsms.pro with LINETYP=TCP (see below). You do not need to define any device to use TCP/IP connections. All other handling is exactly as it is with a modem connection.

Example:
sendsms.pro
[D1_TCP]
ADDRESS=127.1.1.1
PORT=12345
LINETYPE=TCP
PROTOCOL=UCP[51]
PREFIX=+49170|+49170
PREFIX=+49171|+49171
PREFIX=+49175|+49175
MSGTYPE=ALPHANUMERIC
MSGLEN=160
USEUCP60=1 ; only if function 60 is required
UCP60PASSWORD=<password> ; if the password option is used
USERID=<large account>

Return codes

SendSMS returns the count of successfully processed messages (return code 0 means that SendSMS terminated normally but was not abel to send or receive any messages). If the return code is negative then this is an errorcode, which is described in the file sendsms.err. This feature is only available in the registered version. Be aware that some Unix shells return the return code as an 'unsigned byte'. Thatswhy the return code is in the range between 0 and 255, where all values above 127 are error codes.

If the parameter RCZEROIFOK=1 is specified in sendsms.cfg SendSMS returns 0 if one ore more messages have been submitted. This is usefull for usage within (for example) an email system.

Abbreviations

AIMApplication Interface Module
APIApplication Programming Interface
BAIBöcherer Angewandte Informatik
CAPICOMMON-ISDN-API
CIMD2Computer Interface to Message Distribution
DLLDynamic Link Library
DTMFDual Tone Multiplexed Frequency
ETSIEuropean Telecommunications Standard Institute
GSMGlobal System for Mobile computing
IPInternet Protocol
MOMobile Originated
MTMobile Terminated
SIMSubscriber Identity Module
SMPPShort Message Peer to Peer
SMSShort Message Service
SMSCShort Message Service Center
SOShared Object
TAPTelecator Alphanumeric Protocol
TAPITelephony API
TCPTransmission Control Protocol
UCPUniversal Computer Protocol
UUSUser User Signalling

Where can I get the newest version?

You can always get the newest version from www.bai.de.

Problems/Questions

Please send an Email including the following information: to info@bai.de.


Böcherer Angewandte Informatik
 
Scheffelstraße 17a
D-76135 Karlsruhe
Tel: +49 (0)721 9109 550
Fax: +49 (0)721 9109 555
Email: info@bai.de
WWW: http://www.bai.de