896 lines
38 KiB
HTML
896 lines
38 KiB
HTML
<HTML><Head><Title>
|
|
yaps
|
|
</Title></Head><Body>
|
|
|
|
|
|
<H1>Table of Contents</H1>
|
|
|
|
<Ol Compact>
|
|
<Li> <a href="#intro">Introduction</a>
|
|
<Li> <a href="#install">Installation</a>
|
|
<Li> <a href="#config">Configuration</a>
|
|
<Li> <a href="#cmdline">Command Line</a>
|
|
<Li> <a href="#syntax">Sending/Expecting Syntax</a>
|
|
<Li> <a href="#script">Scripting</a>
|
|
<Li> <a href="#sample">Examples</a>
|
|
<Li> <a href="#chlog">Changelog</a>
|
|
</Ol>
|
|
|
|
|
|
<H1 ID="intro">Introduction</H1>
|
|
|
|
Welcome to <em>Yaps</em>, Yet Another Paging Package. The program is used
|
|
to send textual messages to a remote paging device using a modem gateway.
|
|
Many pager companies offer such modem gateways and are using specific
|
|
protocols. The most often used one, TAP is implemented beside others (more
|
|
or less complete.) This command line program uses a global and a private
|
|
configuration file to get information about each paging service, installed
|
|
modems and possibly other.<P>
|
|
|
|
As the main part is implemented as a library it is not very complicated to
|
|
write a client/server solution. For the legal status see the File
|
|
<a href="COPYING.GPL">Copying</a>.
|
|
|
|
|
|
<H1 ID="install">Installation</H1>
|
|
|
|
The software is written, tested and designed on and for Unix(tm) like
|
|
operating systems and requires the so called Posix system calls and function
|
|
library. Gnumake and GCC are required, too (or some changes to the Makefile
|
|
and the code may be neccessary.) It is known to run at least on following
|
|
operating systems:
|
|
<Ul Compact>
|
|
<Li> <a href="http://www.linux.org/">Linux</a> (native system)
|
|
<Li> <a href="http://www.sun.com/">Solaris 2.5.1</a> (Frank Käfer)
|
|
<Li> <a href="http://www.sun.com/">SunOS 4.1.3 aka Solaris 1.1</a> (Frank
|
|
Käfer)
|
|
</Ul>
|
|
(more may follow.)<P>
|
|
|
|
Typically these steps should be enough to install the package:
|
|
<Dl>
|
|
<Dt> Edit Config
|
|
<Dd> For GCC the settings of CC and CFLAGS should be okay. Define
|
|
<strong>SLANG=True</strong>, if you like to use the SLang scripting
|
|
language, which can be found on
|
|
<a href="ftp://space.mit.edu/pub/davis/slang/">space.mit.edu</a>. Install it
|
|
somewhere the compiler can find it. Define <strong>LUA=True</strong> for
|
|
using the lua scripting language, which is located on
|
|
<a href="ftp://ftp.icad.puc-rio.br/pub/lua">ftp.icad.puc-rio.br</a>. READ
|
|
THE COPYRIGHT RELATED FILES OF EACH PACKAGE BEFORE INSTALLING IT!
|
|
<Dt> Edit config.h
|
|
<Dd> This is used to adapt the software to various variants of Unix(tm). If
|
|
you do not have a regex.h file, either set HAVE_REGEX_T to zero or install
|
|
the GNU regular expression library. Be sure the library and includefile can
|
|
be found by the compiler and the name of the header file is
|
|
<em>regex.h</em>, otherwise make a (symbolic) link to this file. Add the
|
|
libary to <em>EXLIB =</em> in Config.
|
|
<Dt> make depend
|
|
<Dd> This create the dependency file which will be included during make.
|
|
<Dt> make (or make all)
|
|
<Dd> This compiles the library, the program driver and links the program.
|
|
The documentation is created using lynx. As lynx is not on every system the
|
|
already formated result is included as well.
|
|
<Dt> make install
|
|
<Dd> This copies the program and the global configuration file to the final
|
|
location. This step requires a working <em>install</em> program. If this is
|
|
missing, you have to install it by hand (well, two files should not be too
|
|
much.)
|
|
<Dt> Edit the global configuration file
|
|
<Dd> With your favorite editor you should edit the global configuration file
|
|
(which will be installed as <em>/etc/yaps.rc</em> on default) and change
|
|
everything as required. See the <a href="#config">Configuration</a> section
|
|
for a detailed description of the contents of the file.
|
|
<Dt> Done!
|
|
<Dd> You may play around with your configuration until you are satisfied,
|
|
but this fine tuning is up to you.
|
|
</Dl><P>
|
|
|
|
If you have problems during compilation, feel free to send me a
|
|
<a href="mailto:yaps@nitmar.tnet.de">mail</a>.
|
|
|
|
|
|
<H1 ID="config">Configuration</H1>
|
|
|
|
The program reads first the global configuration file <em>/etc/yaps.rc</em>
|
|
(when not overwritten by command line switch), then the local one in
|
|
<em>~/.yapsrc</em> to get its configuration. Command line options may
|
|
overwrite some settings in these files. Both configuration files have the
|
|
same layout where the local one can overwrite settings of the global one.
|
|
Each file is seperated in sections, where a section is started with
|
|
<strong>[<name>]</strong> or <strong>[]</strong> for the global
|
|
section. When a file is opened all entries are stored in the global section
|
|
until a section name appears. If a section expression [..] is followed by a
|
|
comma seperate list of names, then these are the fallback sections, i.e.
|
|
variables not found int his section are taken from the fallback sections
|
|
before trying the global one.<P>
|
|
|
|
If the first character is a bar (<strong>|</strong>) then the rest is taken
|
|
as a filename to be included at this point. The current section is
|
|
<strong>NOT</strong> affected by this call.
|
|
|
|
Each line may have exactly one entry (or a comment starting with a hash sign
|
|
in the first column) where the variable name is seperated by whitespaces
|
|
from its value. If the first character of the value is a backslash
|
|
(<strong>\</strong>), then this is removed. This allowes creating values
|
|
starting with whitespaces. But if a value should start with a backslash
|
|
itself, be sure to escape it with another backslash. A line can split over
|
|
several physical line, if each line (expect the last one) ends with a
|
|
backslash. If the value starts with an opening curly bracket (<em>{</em>)
|
|
then all lines up to the closing curly bracket (<em>}</em>) in the first
|
|
column are taken as the value for that variable. The brackets (and the lines
|
|
where they appear) are not part of the value.<P>
|
|
|
|
The value may either be textual, numeric, boolean or a check expression.
|
|
Textual values are starting with the first non whitespace character and
|
|
continue to the end of the line. Numeric values are a sequence of digits
|
|
which are parsed by the C-function <em>atoi(3)</em>. Boolean may either be
|
|
<em>T</em>, <em>Y</em>, <em>1</em> or <em>+</em> for true and <em>F</em>,
|
|
<em>N</em>, <em>0</em> or <em>-</em> for false (or in greater detail,
|
|
everything that is not true is false.) Case is here not significant. The
|
|
check is a sequence of special characters which must match the given string.
|
|
If a <em>></em> is found, then the rest is optional, but must still
|
|
match, if a <em><</em> is found and the string is not at its end, it is
|
|
considered as too long. These characters are supported:
|
|
<Ul Compact>
|
|
<Li> <em>1</em> numeric
|
|
<Li> <em>h</em> hexadecimal
|
|
<Li> <em>l</em> lowercase
|
|
<Li> <em>u</em> uppercase
|
|
<Li> <em>a</em> alpha
|
|
<Li> <em>n</em> alphanumeric
|
|
<Li> <em>p</em> printable
|
|
<Li> <em>x</em> ascii
|
|
<Li> every other character matches every character
|
|
</Ul>
|
|
Some simple examples:
|
|
<Ul Compact>
|
|
<Li> <strong>>1</strong> A string with unlimited length, but made only
|
|
out of numeric values.
|
|
<Li> <strong>aaa</strong> A string of exact three alpha characters.
|
|
<Li> <strong>>xxxx<</strong> A string of length zero up to four made
|
|
of ASCII characters.
|
|
<Li> <strong>....>1111<</strong> A string starting with exact four
|
|
characters, followed by zero to four numeric characters.
|
|
</Ul>
|
|
|
|
Alternative one can specify the check by a description, if the checkstring
|
|
is prefixed by a plus sign. This is then a comma seperated list of checks,
|
|
which are seperated by an equal sign into variable and value. These
|
|
variables are supported:
|
|
<Ul>
|
|
<Li> <strong>type=<type></strong> Each character in the string must
|
|
match the type, which may be one of the following:
|
|
<Ul Compact>
|
|
<Li> <strong>numeric</strong> only digits are allowed.
|
|
<Li> <strong>sedecimal</strong> only hexdigits are allowed.
|
|
<Li> <strong>lower</strong> only lowercase characters are allowed.
|
|
<Li> <strong>upper</strong> only uppercase characters are allowed.
|
|
<Li> <strong>alpha</strong> only alpha characters are allowed.
|
|
<Li> <strong>alphanumeric</strong> only digits and alpha characters are
|
|
allowed.
|
|
<Li> <strong>print</strong> only printable characters are allowed.
|
|
<Li> <strong>ascii</strong> only ASCII characters are allowed.
|
|
</Ul>
|
|
<Li> <strong>length=<length></strong> The string must have exact this
|
|
length.
|
|
<Li> <strong>minimum=<length></strong> The string must at least this
|
|
length.
|
|
<Li> <strong>maximum=<length></strong> The string must not be longer
|
|
than this length.
|
|
</Ul>
|
|
<P>
|
|
|
|
The global section defines global values or default values for other
|
|
sections. Some section may not inherit these values, but currently there is
|
|
only one and is marked as such.<P>
|
|
|
|
<H2>Global section</H2>
|
|
|
|
These are typical found in the global section and can be overwritten in
|
|
other sections, if required.
|
|
|
|
<Dl>
|
|
<Dt> services <text>
|
|
<Dd> This is the comma seperated list of available services.
|
|
<Dt> call-id <text>
|
|
<Dd> If the pager allows to send the source caller id this id is used, if
|
|
not overwritten by a command line argument.
|
|
<Dt> signature <text>
|
|
<Dd> If this is present, then the text is appended to each message sent to
|
|
the pager (and if use-signature is True).
|
|
<Dt> verbose <num>
|
|
<Dd> Sets the debugging/verbosity level. The bigger the number, the more
|
|
output is generated.
|
|
<Dt> logfile <text>
|
|
<Dd> If the given text is a valid filename the status of a sending request
|
|
is loged there.
|
|
<Dt> <a ID="logstr"></a>logstring <text>
|
|
<Dd> If this is present, then only these parts are logged, which match the
|
|
given string. Currently these elements are supported:
|
|
<Ul Plain Compact>
|
|
<Li> <strong>+</strong> message had been trasmitted successfully
|
|
<Li> <strong>-</strong> message had not been transmitted
|
|
<Li> <strong>*</strong> part had been transmitted successfully
|
|
<Li> <strong>/</strong> part had not been transmitted
|
|
<Li> <strong>i</strong> informal logfile entry
|
|
<Li> <strong>c</strong> cost relevant informations
|
|
<Li> <strong>s</strong> session start
|
|
<Li> <strong>e</strong> session end
|
|
<Li> <strong>p</strong> protocol specific
|
|
</Ul>
|
|
<Dt> modems <text>
|
|
<Dd> This is a list of modem entries, seperated by commas.
|
|
<Dt> final-report <text>
|
|
<Dd> If this is set, a final report is written to the given filename. If
|
|
filename is <strong>-</strong>, then it is written to stdout. This feature
|
|
is intended for use in shell scripts, so the script could proof which
|
|
message has actual send and which one has been rejected instead of simple
|
|
rely on the return code of yaps.
|
|
</Dl>
|
|
|
|
<H2>Service section</H2>
|
|
|
|
The names of these section are free to the user, but their contents describe
|
|
a paging service (or a paging company.) Following variables are allowed for
|
|
service sections:
|
|
|
|
<Dl>
|
|
<Dt> speed <num>
|
|
<Dd> The speed of the serial device.
|
|
<Dt> bits-per-byte <num>
|
|
<Dd> The number of bits per byte, supported are 5 to 8.
|
|
<Dt> parity <text>
|
|
<Dd> The used parity, this may either be <em>n</em>one, <em>e</em>ven or
|
|
<em>o</em>dd.
|
|
<Dt> stopbits <num>
|
|
<Dd> The number of stopbits, supported are 1 or 2.
|
|
<Dt> phone <text>
|
|
<Dd> The phone number of the modem gateway for this service. If the number
|
|
contains <strong>%P</strong> and <em>insert-pager-id</em> is set, then the
|
|
pagerid is inserted into the phonenumber.
|
|
<Dt> protocol <text>
|
|
<Dd> This is the communication protocol, that this service requires.
|
|
Currently are <em>ascii</em>, <em>script</em>, <em>tap</em> and <em>ucp</em>
|
|
allowed.
|
|
<Dt> max-size <num>
|
|
<Dd> The maximal length of a message for this service.
|
|
<Dt> may-split <bool>
|
|
<Dd> If this is true, then a message, which is too long will be split into
|
|
several messages.
|
|
<Dt> max-messages <num>
|
|
<Dd> The maximum number of messages per message, that can be send. If this
|
|
is zero, then an unlimited number of messages can be send.
|
|
<Dt> truncate <bool>
|
|
<Dd> If this is set a message is not split, but truncated to the length
|
|
allowed by the provider.
|
|
<Dt> use-call-id <bool>
|
|
<Dd> If this is true, then the caller-id is inserted. Where it is insert is
|
|
protocol specific.
|
|
<Dt> use-signature <bool>
|
|
<Dd> If this is true and a signature is given, this is appended to each
|
|
message.
|
|
<Dt> insert-pager-id <bool>
|
|
<Dd> If this is true, then the pagerid is inserted as part of the phone
|
|
number. This implies, that only messages to the same receipiant can be send
|
|
at one call.
|
|
<Dt> rm-invalids-cid <text>
|
|
<Dd> Remove every character in <em>text</em>, that appears in the caller id.
|
|
This is designed to make a caller id more readable, but still useable by the
|
|
desired service.
|
|
<Dt> rm-invalids-pid <text>
|
|
<Dd> Dito for pager ids.
|
|
<Dt> valid-pid <text>
|
|
<Dd> This is a regular expression to check wether a pager-id is valid for
|
|
this service. If your system does not support Posix regular expression, you
|
|
can use a simple replacement. This is just a list of strings, seperated by a
|
|
bar which must match the beginning of the pager-id.
|
|
<Dt> change-pid <text>
|
|
<Dd> If the pager-id matches the regular expression of <em>valid-pid</em>,
|
|
then this matching part is replaced with this string. If the string is just
|
|
a minus (<em>-</em>), then the match is removed from the resulting pager-id.
|
|
<Dt> valid-cid <text>
|
|
<Dd> The same like <em>valid-pid</em> for the caller id.
|
|
<Dt> change-cid <text>
|
|
<Dd> The same like <em>change-pid</em> for the caller id.
|
|
<Dt> conv-table <text>
|
|
<Dd> The value is a filename to a character conversion table. This affects
|
|
only the message (and depending on the protocol the pagerid) and allows
|
|
transforming illegal characters to valid ones.
|
|
<Dt> convert <text>
|
|
<Dd> This is comma seperated list of direct change entries of the convertion
|
|
table. If you want to include more than one pair, the block construct using
|
|
curly brackets (<em>{..}</em>) must be used. Each line contains a source and
|
|
a destination character, i.e. if the source character is encountered in a
|
|
message, the destination character is used for it. There are also some
|
|
predefined convertion rules, which all starts with an asterisk:
|
|
<Ul Compact>
|
|
<Li> <strong>*no-control</strong> control characters are suppressed
|
|
<Li> <strong>*control</strong> control characters are inserted literal
|
|
<Li> <strong>*no-8bit</strong> no characters with 8'th bit set are
|
|
included
|
|
<Li> <strong>*8bit</strong> use also characters with 8'th bit set.
|
|
<Li> <strong>*numeric</strong> only numeric characters are allowed.
|
|
</Ul>
|
|
<Dt> cost <text>
|
|
<Dd> This string is used to calculate the costs for each call. The
|
|
description is a comma seperated list of variables with equal sign seperated
|
|
optional value. These variables are currently implemented:
|
|
<Dl Compact>
|
|
<Dt> fixed
|
|
<Dd> This tells the software, that the cost are fixed per call, i.e.
|
|
no real calculation takes place according to the used entities.
|
|
<Dt> entity-length=<entity>
|
|
<Dd> This is the length of one entity. This is interpreted as a
|
|
floating point number.
|
|
<Dt> max-entities=<count>
|
|
<Dd> Some providers only charge until a maximum of entites had
|
|
been used and stop then charging.
|
|
<Dt> dial-overhead=<seconds>
|
|
<Dd> The counter starts before dialing. Typically it takes some
|
|
time from dialing to the first billed entity. This time can
|
|
be specified using this variable.
|
|
<Dt> cost=<cost>
|
|
<Dd> This is the cost per entity (or the whole cost on fixed charging
|
|
services). This is a floating point number.
|
|
<Dt> unit=<string>
|
|
<Dd> This string is appended in the logfile for the currency. This is
|
|
only of cosmetic value.
|
|
<Dt> remainder=<digits>
|
|
<Dd> This is the number of digits after the point in the cost display.
|
|
This value is typical two.
|
|
<Dt> timetable=<description>
|
|
<Dd> If a timetable entry is given, then the cost are calculated
|
|
depending on weekday and time. On fixed charging services the
|
|
value describes the complete costs for the call, in the other
|
|
case the value is the entity-length for this day/time. The
|
|
description is a semi-colon seperated list of single entries of
|
|
the form:<BR>
|
|
<strong><Weekday(s)><from>-<to>=<value></strong><BR>
|
|
Each weekday is a two letter sequence (So, Mo, Tu, We, Th, Fr, Sa)
|
|
and there are three special "weekdays": <em>Wk</em> for
|
|
working days (monday to friday), <em>Ss</em> for weekend
|
|
(saturday and sunday) and <em>al</em> for all days. A typical
|
|
example may look like:
|
|
<strong>Wk0800-1800=12;Wk1800-0800=24;Ss=24</strong>, but this
|
|
could be written shorter as:
|
|
<strong>=24;Wk0800-1800=12</strong> because the first entry is
|
|
taken as the default, if no match is found. And the construct
|
|
<em>=24</em> does not contain any weekday, so it is invalid for
|
|
any regular check.
|
|
</Dl>
|
|
<Dt> force <bool>
|
|
<Dd> If a feature is requested, but this service do not support it, the
|
|
message will still be delivered, if this variable is set to True.
|
|
<Dt> can-delay <bool>
|
|
<Dd> Set this to True, if the service provider accepts a delay for sending
|
|
the message.
|
|
<Dt> can-expire <bool>
|
|
<Dd> Set this to True, if the service provider allowes the setting of an
|
|
expiration timestamp.
|
|
<Dt> can-rds <bool>
|
|
<Dd> Set this to True, if the service provider allowes the request for a
|
|
delivery status.
|
|
<Dt> rds <bool>
|
|
<Dd> Set this to True, if <em>can-rds</em> is True and you always want to
|
|
get a delivery status.
|
|
<Dt> check-call-id <check>
|
|
<Dd> The caller id must match the <strong>check</strong> expression.
|
|
<Dt> check-pager-id <check>
|
|
<Dd> Each pager id must match the <strong>check</strong> expression.
|
|
</Dl>
|
|
|
|
<H2>Modem section</H2>
|
|
|
|
Each modem should have its own section. Following entries are currently
|
|
supported:
|
|
|
|
<Dl>
|
|
<Dt> device <text>
|
|
<Dd> The filename for the device where the modem is attached to.
|
|
If the CAPI interface should be used, the parameter <text>
|
|
must be coded as
|
|
capi/<controller>/<MSN>
|
|
Note, there must not be a '/' at the beginning, when using CAPI.
|
|
<Dt> lock-prefix <text>
|
|
<Dd> This is the pathname to prefix the basename of the modemdevice to
|
|
create lockfiles. This can be used to enable more than one application to
|
|
use the modem.
|
|
Not used by CAPI.
|
|
<Dt> lock-method <text>
|
|
<Dd> This is a comma seperated list of locking mechanism. Currently these
|
|
flags are supported:
|
|
<Ul Compact>
|
|
<Li> <em>ascii</em> PID is stored as ASCII text in lockfile.
|
|
<Li> <em>binary</em> PID is stored in machine representation in
|
|
lockfile.
|
|
<Li> <em>lower</em> converts device part of lockfile to lower case.
|
|
<Li> <em>upper</em> converts device part of lockfile to upper case.
|
|
<Li> <em>sysv4</em> append SysV4 style infos to lockfile instead of the
|
|
basename of the device.
|
|
<Li> <em>timeout=<secs></em> tries to lock the device
|
|
<strong>secs</strong> seconds.
|
|
</Ul>
|
|
Not used by CAPI.
|
|
<Dt> init <text>
|
|
<Dd> This is the init sequence to initialize the modem.
|
|
Not used by CAPI.
|
|
<Dt> dial <text>
|
|
<Dd> This is the dial sequence to dial a phone number with the modem. An
|
|
<strong>\L</strong> in the string will be replaced by the phone number.
|
|
If the CAPI interface is used, this entry just defines a
|
|
possible needed prefix to dial out, e.g. '0'.
|
|
<Dt> timeout <num>
|
|
<Dd> This is the default timeout to wait for responses of the modem.
|
|
Not used by CAPI.
|
|
<Dt> reset <text>
|
|
<Dd> This is the sequence to reset the modem.
|
|
Not used by CAPI.
|
|
<Dt> local-init <text>
|
|
<Dd> This is used to customize an existing modem entry for different purpose
|
|
(e.g. force a specific connect rate, etc.)
|
|
Not used by CAPI.
|
|
</Dl>
|
|
|
|
Beside this the section may contain protocol specific entries to adapt the
|
|
protocol for this service.
|
|
|
|
<H2>ASCII based protocol</H2>
|
|
|
|
A <strong>\C</strong> is replaced with the caller id, if available. If
|
|
request a delivery report is switched on, a <strong>\R</strong> is replaced
|
|
with <em>1</em>, else with <em>0</em>.
|
|
|
|
<Dl>
|
|
<Dt> asc-timeout <num>
|
|
<Dd> This is the default timeout for sequences when communicating with the
|
|
remote side.
|
|
<Dt> asc-login <text>
|
|
<Dd> This is the sequence to login to the remote service.
|
|
<Dt> asc-logout <text>
|
|
<Dd> This is the sequence to logout from the remote service.
|
|
<Dt> asc-pagerid <text>
|
|
<Dd> This is the sequence to embedded the pager id to be sent.
|
|
<strong>\P</strong> is replaced with the pager id.
|
|
<Dt> asc-message <text>
|
|
<Dd> Dito for the message, <strong>\M</strong> is replaced with the message.
|
|
<Dt> asc-next <text>
|
|
<Dd> This is the sequence to start the next transmission.
|
|
<Dt> asc-sync <text>
|
|
<Dd> If we get out of sync, then this sequence should bring us back to a
|
|
stage as if we had just loged in.
|
|
</Dl>
|
|
|
|
<H2>Script specific</H2>
|
|
|
|
<Dl>
|
|
<Dt> script-type <text>
|
|
<Dd> This is the scripting language to choose. Currently these are
|
|
supported: <strong>SLang</strong>, <strong>Lua</strong>.
|
|
<Dt> script-name <text>
|
|
<Dd> This is the name (e.g. the name of the variable containing) the script.
|
|
If the name starts with a slash or a plus sign, then the value is treated as
|
|
a filename from where the script should be read. The plus sign is stripped
|
|
off before opening the file.
|
|
<Dt> scr-login <text>
|
|
<Dd> This is the function/label where to start at login. If the caller id is
|
|
available (and the language supports it) the caller id is passed as an
|
|
argument.
|
|
<Dt> scr-logout <text>
|
|
<Dd> Dito for logout.
|
|
<Dt> scr-pagerid <text>
|
|
<Dd> Dito for sending the pagerid. The pagerid is passed as an argument.
|
|
<Dt> scr-message <text>
|
|
<Dd> Dito for sending the message. The message is passed as an argument.
|
|
<Dt> scr-next <text>
|
|
<Dd> Dito to go to the next message.
|
|
<Dt> scr-sync <text>
|
|
<Dd> Dito to sync to a definite state (i.e. as if we had just loged in.)
|
|
</Dl>
|
|
|
|
<H2>TAP specific</H2>
|
|
|
|
<Dl>
|
|
<Dt> tap-t1, tap-t2, tap-t3, tap-t4, tap-t5 <num>
|
|
<Dd> This is the timeout for each stage defined in the TAP specification.
|
|
See
|
|
<a href="http://www.mot.com/MIMS/MSPG/pcia_protocols/tap_v1p8/timing_retry_parameters.html#params">
|
|
there</a>
|
|
for details.
|
|
<Dt> tap-n1, tap-n2, tap-n3 <num>
|
|
<Dd> This is the retry count for each stage defined int the TAP
|
|
specification. See
|
|
<a href="http://www.mot.com/MIMS/MSPG/pcia_protocols/tap_v1p8/timing_retry_parameters.html#params">
|
|
there</a>
|
|
for details.
|
|
<Dt> tap-login-count <num>
|
|
<Dd> This is the number of tries to login to the remote service.
|
|
<Dt> tap-logout-count <num>
|
|
<Dd> This is the number of tries to logout from the remote service.
|
|
</Dl>
|
|
|
|
<H2>UCP specific</H2>
|
|
|
|
<Dl>
|
|
<Dt> ucp-timeout <num>
|
|
<Dd> This is the time to wait for an answer from the remote system. The
|
|
documentation says that this could be about 40 to 60 seconds. This depends
|
|
on the provider.
|
|
<Dt> ucp-retry <num>
|
|
<Dd> This specifies how often a message should be sent, until the program
|
|
gives up.
|
|
<Dt> ucp-extend <bool>
|
|
<Dd> If this is True then the extend UCP implementation is used, i.e. the
|
|
more complex, but more flexibel protocol (currently only possible on german
|
|
cellular phone provider Mannesmann D2.)
|
|
<Dt> ucp-ds-timeout <num>
|
|
<Dd> Wait a maximum of this value seconds for receiving of the delivery
|
|
status.
|
|
</Dl>
|
|
|
|
<H2>Alias section</H2>
|
|
|
|
The entries in this section are not able to access the global entries. Each
|
|
entry contains an alias name with its real number.
|
|
|
|
|
|
<H1 ID="cmdline">Command Line</H1>
|
|
|
|
Yaps support several command line parameter which can overwrite the possibly
|
|
used default values in the configuration files. Following options are
|
|
understood by this program (on some systems, there are is also support for
|
|
long options):
|
|
|
|
<Dl>
|
|
<Dt> -C <configfile>, --config=<configfile>
|
|
<Dd> Use <strong>cfgfile</strong> instead of the default global
|
|
configuration file <em>/etc/yaps.rc</em>.
|
|
<Dt> -s <service>, --service=<service>
|
|
<Dd> Use paging service <strong>service</strong> instead of the default of
|
|
the configuration file.
|
|
<Dt> -t, --truncate
|
|
<Dd> If this is set, then a message is truncated, if it is longer than the
|
|
allowed limit of the choosen service.
|
|
<Dt> -c <callid>, --call-id=<callid>
|
|
<Dd> Use <strong>callid</strong> as the caller id.
|
|
<Dt> -S <signature>, --signature=<signature>
|
|
<Dd> If signature appending is enabled by the service, use this string as
|
|
the signature.
|
|
<Dt> -l <logfile>, --logfile=<logfile>
|
|
<Dd> Write status of transmission to <strong>logfile</strong>.
|
|
<Dt> -L <logstr>, --logstring=<logstr>
|
|
<Dd> This is used to select the messages written to the logfile. See
|
|
<a href="#logstr">above</a> unter the configuration entry
|
|
<em>logstring</em> for a detailed description.
|
|
<Dt> -f, --force
|
|
<Dd> Force sending of messages, even if -d/-e/-r is not supported by the
|
|
service.
|
|
<Dt> -d <date>, --delay=<date>
|
|
<Dd> If the service supports it, the message is delayed and sent at
|
|
<strong>date</strong>.
|
|
<Dt> -e <date>, --expire=<date>
|
|
<Dd> If the service supports it, the message is deleted, if this date is
|
|
reached and the message had not been transmitted until then.
|
|
<Dt> -r, --request-delivery-status
|
|
<Dd> If the service supports it, a delivery status is requested.
|
|
<Dt> -R <fname>, --final-report=<fname>
|
|
<Dd> A final report is written to <em>fname</em> (or stdout, if fname is
|
|
<strong>-</strong>.) This feature is useful to check which message had been
|
|
delivered successfully or not.
|
|
<Dt> -z <fname>, --message-file=<fname>
|
|
<Dd> Reads pager-ids and messages form <em>fname</em>. Each line contains
|
|
one pair, seperated by whitespace(s).
|
|
<Dt> -v, --verbose
|
|
<Dd> Increase the verbosity of yaps, more -v's give more debug output.
|
|
<Dt> -p, --print-config
|
|
<Dd> This is used to printout configuration values for testing purpose. The
|
|
remaining paramters are variables to print out with their value.
|
|
</Dl>
|
|
|
|
Following the options the user has to give receiver/message pairs, all using
|
|
the same service. A receiver is either the pager id itself or an alias. If
|
|
the first character is a colon, then the colon is cut off and the remaining
|
|
part is taken as an alias, if the first character is a slash, it is cut off
|
|
as well and the remaining is taken as the pager id. If the first character
|
|
is a digit, it is taken as a pager id, otherwise as an alias. It is possible
|
|
to specify multiple receiver, if the receiver is a comma seperate list of
|
|
individual receivers. If the first character of the message is a plus sign,
|
|
then the remaining message is treated as a filename and the real message is
|
|
read from this file. If the message is just a minus (<strong>-</strong>),
|
|
then the message is read from stdin, if it is just a dot
|
|
(<strong>.</strong>), then the message is empty.<P>
|
|
|
|
The options <em>-d</em> and <em>-e</em> accept a date representation which
|
|
must be (according to option parsing) one argument, e.g. if it contains
|
|
spaces it must be quoted. If the first character of date is a plus
|
|
(<strong>+</strong>) sign, then the date is taken as an offset to the
|
|
current time. All further definitions are seperated by spaces:
|
|
<Ul>
|
|
<Li> <hour><strong>:</strong><min><strong>:</strong><sec>
|
|
<Li> <day><strong>.</strong><month><strong>.</strong><year>
|
|
<Li> <month><strong>/</strong><day><strong>/</strong><year>
|
|
<Li> <numeric> if less than 30 is taken as the hour
|
|
<Li> <numeric> if greater or equal than 30 is taken as minutes
|
|
</Ul>
|
|
|
|
|
|
<H1 ID="syntax">Sending/Expecting Syntax</H1>
|
|
|
|
Whenever communication over the serial line takes place the send/expect
|
|
functions are comming into play. There are three important functions, which
|
|
are called from several parts: sending of data, expecting data and a
|
|
send/expect function. Each is explained in detail here (including the
|
|
supported syntax):
|
|
|
|
<H2>Sending</H2>
|
|
|
|
Sending itself is nothing fancy, just all data will be written to the serial
|
|
line.
|
|
|
|
<H2>Expecting</H2>
|
|
|
|
Expecting means to wait for some pattern to arrive. It is possible to expect
|
|
more than one sequence and the function returns the matching entry, a
|
|
timeout or an error condition.
|
|
|
|
<H2>Send/Expect</H2>
|
|
|
|
Most communication parts call this function (which then calls the functions
|
|
above.) This function requires a string with tokens seperated by
|
|
whitespaces. A token may contain whitespaces, if the token is enclosed in
|
|
single or double quotes. These quotes (as any other quotes) are removed
|
|
during the preparse. The first character of the token is relevant for the
|
|
method to be executed. Each token is preparsed to remove/interpret special
|
|
characters. Following special characters are interpreted:
|
|
|
|
<Ul Compact>
|
|
<Li> Backslash <strong>\</strong><BR>
|
|
The backslash is used to escape any other special character (inclusive
|
|
quotes and the backslash itself) or to insert typical control characters.
|
|
These are supported:
|
|
<Ul>
|
|
<Li> \a -> Bel
|
|
<Li> \b -> Bs
|
|
<Li> \f -> Ff
|
|
<Li> \l -> Lf
|
|
<Li> \n -> Nl (system depended)
|
|
<Li> \r -> CR
|
|
<Li> \s -> Space
|
|
<Li> \t -> Tab
|
|
</Ul>
|
|
<Li> Up arrow <strong>^</strong><BR>
|
|
This is used to insert control characters, e.g. ^M means CR.
|
|
<Li> Percent <strong>%<nr></strong><BR>
|
|
This inserts optional paramter <strong>nr</strong>, if supplied.
|
|
</Ul><P>
|
|
|
|
These character initiate the behaviour of the token:
|
|
<Dl>
|
|
<Dt> <strong><</strong> Expect
|
|
<Dd> The rest of the token is for expecting. If the token contains
|
|
<strong>-</strong> then the token is split again and each subtoken is
|
|
treated as expect/send, if the expect failed. The expect token may be
|
|
seperated by <strong>|</strong> to indicate alternatives. The expect is
|
|
failed, if an error occurs, a timeout arised or not the first alternatives
|
|
matches. The <strong><</strong> may be appended by a numeric value, which
|
|
is used as the timeout in seconds.
|
|
<Dt> <strong>!</strong> Command
|
|
<Dd> To insert dynamic commands into the sequence use this construct.
|
|
Following is an optional numeric value <strong>n</strong> and a command
|
|
character. If <strong>n</strong> is not set, its default value is one.
|
|
Following characters are supported:
|
|
<Ul>
|
|
<Li> d - sleep <strong>n</strong> seconds
|
|
<Li> D - sleep <strong>n</strong> miliseconds
|
|
<Li> b - send break (length depends on <strong>n</strong> and the
|
|
implementation)
|
|
<Li> h - hangup the line (lowering DTR by <strong>n</strong> * 0,5
|
|
seconds.)
|
|
<Li> o - waits for output to drain
|
|
<Li> < - flushes the input queue
|
|
<Li> > - flushes the output queue
|
|
<Li> f - forces the sequence to fail
|
|
<Li> s - forces the sequence to succeed
|
|
</Ul>
|
|
<Dt> Any other character
|
|
<Dd> This string is just send to the remote side.
|
|
</Dl>
|
|
|
|
|
|
<H1 ID="script">Scripting</H1>
|
|
|
|
Scripting has the advantage (compared to the ASCII protocol) that one is
|
|
more flexible. As there are a lot of scripting languages around, there will
|
|
be no specific one for this package. As long as such a language is
|
|
embeddable into C programs, it should not be too complicate to integrate it
|
|
into this package.<P>
|
|
|
|
This section explains the additional function (or simular) for the available
|
|
scripting languages. The syntax itself is explained in the distribution of
|
|
each scripting package.
|
|
|
|
<H2>SLang</H2>
|
|
|
|
Beside the new functions there is an extension to the string class, so you
|
|
can use (beside others) the plus sign to concaternate strings. One time this
|
|
part should make its way into the main SLang distribution.
|
|
|
|
<H3>Variable index</H3>
|
|
|
|
<Dl>
|
|
<Dt> int NO_ERR;
|
|
<Dd> This is the return value for a function, that ended successful.
|
|
<Dt> int ERR_FAIL;
|
|
<Dd> This is the return value for a function, that encountered an error, but
|
|
which allowes the script to continue.
|
|
<Dt> int ERR_FATAL;
|
|
<Dd> Dito, but the script should not continue any more.
|
|
<Dt> int ERR_ABORT;
|
|
<Dd> Dito, but no further action should take place.
|
|
<Dt> int rds;
|
|
<Dd> Is set to <em>True</em>, if a delivery status should be requested.
|
|
<Dt> int delay_day, delay_mon, delay_year, delay_hour, delay_min, delay_sec;
|
|
<Dd> This is the time/date to delay the delivery of the message.
|
|
<Dt> int expire_day, expire_mon, expire_year, expire_hour, expire_min, expire_sec;
|
|
<Dd> This is the time/date to expire a buffered message.
|
|
<Dt> int False;
|
|
<Dd> The numeric value for False.
|
|
<Dt> int True;
|
|
<Dd> Dito for True.
|
|
</Dl>
|
|
|
|
<H3>Function index</H3>
|
|
|
|
<Dl>
|
|
<Dt> void setcb (string func, string sep);
|
|
<Dd> This enable the line callback facility and stores each line into a
|
|
local variable, which will be overwritten after each new encountered line. A
|
|
line is considered as complete, if one character in <strong>sep</strong> is
|
|
received. If <strong>func</strong> is the name of a defined function, then
|
|
this function is called on every completed new line. The line is passed as
|
|
the paramter to this function.
|
|
<Dt> void clrcb (void);
|
|
<Dd> Clears the line callback facility.
|
|
<Dt> string line (void);
|
|
<Dd> Returns the last complete read in line, if the line callback facility
|
|
is enabled.
|
|
<Dt> void hangup (void);
|
|
<Dd> Tries to hangup, if the modem is currently off-hook. This is done by
|
|
lowering the DTR line.
|
|
<Dt> int send (string str);
|
|
<Dd> Sends the string to the remote side. Returns <strong>True</strong> on
|
|
success, <strong>False</strong> otherwise.
|
|
<Dt> int csend (string str);
|
|
<Dd> Dito, but the string is converted before it is sended to the remote
|
|
side.
|
|
<Dt> int expect (int tout, string str1, ..., string strn, int cnt);
|
|
<Dd> The function waits <strong>tout</strong> seconds until one of the
|
|
strings is received. If no string is received, <strong>0</strong> is
|
|
returned, <strong>-1</strong> on error. Otherwise the number of the string
|
|
is returned (<strong>1</strong> for <strong>str1</strong>,
|
|
<strong>2</strong> for <strong>str2</strong>, etc). <strong>cnt</strong> is
|
|
the number of strings to wait for.
|
|
<Dt> int send_expect (int tout, string expr);
|
|
<Dd> This function executes the <strong>expr</strong> with its internal
|
|
send/expect evaluater and returns <strong>True</strong>, when the sequence
|
|
had been executed completely, otherwies <strong>False</strong>.
|
|
<Dt> void drain (int secs);
|
|
<Dd> This function reads and discards any character for
|
|
<strong>secs</strong> seconds.
|
|
<Dt> void cvdef (int src, int dst);
|
|
<Dd> Defines a converion rule. Every character <strong>src</strong> will be
|
|
replaced by <strong>dst</strong>. The conversion is used in <em>csend()</em>.
|
|
<Dt> void cvundef (int ch);
|
|
<Dd> Undefines the conversion rule for <strong>ch</strong>.
|
|
<Dt> void cvinval (int ch);
|
|
<Dd> Marks the character <strong>ch</strong> as invalid.
|
|
<Dt> string conv (string str);
|
|
<Dd> Converts the string <strong>str</strong> using the defined conversion
|
|
rules and returns the converted string.
|
|
</Dl>
|
|
|
|
<H2>Lua</H2>
|
|
<!-- TODO! -->
|
|
|
|
|
|
<H1 ID="sample">Examples</H1>
|
|
|
|
Here are some examples that may help you to understand the software a bit
|
|
better. First you should read the example configuration file
|
|
<a href="yaps.rc">yaps.rc</a>. This could be used as a base for your own
|
|
global configuration file.
|
|
|
|
<H2>Calling</H2>
|
|
|
|
Typically the program is called <strong>yaps <pagerid>
|
|
<message></strong>. <em>pagerid</em> is either the exact pagerid of
|
|
the receiver or an alias found in the alias section. <em>message</em> is the
|
|
message to send by itself. If a pager-id leads to more than one provider,
|
|
then the first is used. To force a special service use the <strong>-s
|
|
<service></strong> switch.
|
|
|
|
<H2>Script protocol</H2>
|
|
|
|
In the contrib directory, you can find <a href="contrib/tap.sl">tap.sl</a>,
|
|
an example on how to use the scripting facility to emulate a protocol. This
|
|
is a minimal, but working reimplemetation of TAP.
|
|
|
|
<H1 ID="chlog">Changelog</H1>
|
|
|
|
This is a list of changes:
|
|
<Ul Plain>
|
|
<Li> 9. May 1997: V 0.90 released
|
|
<Ul Compact>
|
|
<Li> Minor cleanup on calling sending routines
|
|
<Li> Added optional multiple receiver per message
|
|
<Li> Changing UCP to prepare the real implementation
|
|
<Li> Preparing the creation of a client/server solution
|
|
<Li> Compile configuration moved to seperate file
|
|
</Ul>
|
|
<Li> 13. May 1997: V 0.91 released
|
|
<Ul Compact>
|
|
<Li> Converted `char *' to `string_t *' in several places
|
|
<Li> Added max-messages configuration option
|
|
<Li> Moved some configuration stuff to config.h
|
|
<Li> Got UCP docu! Implemented it partial (as much as it makes sense)
|
|
<Li> Added option -d/-e as UCP (in extended mode) can support it
|
|
<Li> Added special date handling functions for this purpose
|
|
<Li> Changed copyright to the GPL
|
|
<Li> Use transparent data in extended UCP, if characters with
|
|
set 8th bit are found
|
|
<Li> Better message splitting
|
|
<Li> Added some sanity checks
|
|
</Ul>
|
|
<Li> 22. May 1997: V 0.92 released
|
|
<Ul Compact>
|
|
<Li> Added handling of configuration variants
|
|
<Li> Added include option in configuration files
|
|
<Li> First bugs encountered by tester fixed
|
|
<Li> Message can now be read from stdin, if message == '-'
|
|
(idea by <markus@mail.yezz.de>)
|
|
<Li> Message can now be empty, if message == '.'
|
|
<Li> Minor bugfixing/Makefilehandling (reported by Frank Käfer)
|
|
<Li> Enhanced lockfile handling, including SysV4 lockfiles (inspirated
|
|
by Frank Käfer)
|
|
<Li> Total rewrite of UCP sending
|
|
</Ul>
|
|
<Li> 26. May 1997: V 0.93 released
|
|
<Ul Compact>
|
|
<Li> UCP works again including delivery report
|
|
<Li> Added checking of pager id for a service
|
|
<Li> Added signature in configuration file
|
|
<Li> Added value start escaping with backslash
|
|
<Li> Changed checking of pager id for service
|
|
<Li> Automatic assign of a pager id to a service
|
|
<Li> Could now handle more than one service at one call
|
|
</Ul>
|
|
<Li> 30. May 1997: V 0.94 released
|
|
<Ul Compact>
|
|
<Li> Workaround for serial bug in sunos/solaris (by Frank Käfer)
|
|
<Li> If the system does not support Posix regular expression, a simple
|
|
replacement is added
|
|
<Li> More comments in yaps.rc (as wished by Frank Käfer ;-)
|
|
<Li> Change handling of control chars in TAP/pre V1.6 (hint by
|
|
<markus@mail.yezz.de>)
|
|
<Li> Added default conversion rules
|
|
<Li> Added force/-f
|
|
<Li> Added long options support
|
|
<Li> Added getopt() for systems without this function
|
|
<Li> Added valid-cid/change-cid/rm-invalids-cid/rm-invalids-pid
|
|
</Ul>
|
|
<Li> 3. June 1997: V 0.95 released
|
|
<Ul Compact>
|
|
<Li> Added final status report
|
|
<Li> Added a 2nd checking scheme
|
|
<Li> Added support for lua (another scripting language)
|
|
<Li> Removed porting approach, should be done by someone who
|
|
has access to such an OS.
|
|
<Li> Added reading of pager-id/message pairs from file
|
|
<Li> Added cost calculation
|
|
<Li> Enhanced logfile handling
|
|
</Ul>
|
|
<Li> 14. June 1997: V 0.96 released
|
|
</Ul>
|
|
|
|
</Body></HTML>
|