SENDPAGE(1)
NAME
sendpage - submit a pager job for transmission
SYNOPSIS
sendpage [ options ] [ message... ]
DESCRIPTION
sendpage submits a pager transmission request to a server
using the Simple Network Paging Protocol (SNPP) described
in RFC 1861. Pager requests specified with sendpage are
normally processed immediately, although they may also be
queued for transmission at a later time using a syntax
identical to the at(1) command. For each job that is
queued, sendpage prints a job identifier on the standard
output. A job identifier is the token by which jobs are
identified within HylaFAX. Job identifiers can be sup-
plied to the faxrm(1) command to remove the jobs or to the
faxalter(1) command to alter job parameters.
Pages may be sent to one or more destination paging termi-
nals and, optionally, include a text message (depending on
the capability of the receiving device). Each destination
is identified by a Pager Identification Number (PIN) spec-
ified with the -p option; for example, sendpage -p 12345
``Help, the fax machine is on fire!''. A PIN is typically
a numeric string though it may also be an alpha-numeric
alias depending on the capabilities of the SNPP server.
Text messages can be specified on the command line or
taken from standard input. The -n option must be used if
no text message is to be supplied with the page request--
as for a numeric-only pager. Text supplied to the paging
system is sent exactly as submitted including any newline,
carriage return, or non-ASCII data. Message preparation
including filtering and formatting must be done prior to
submitting the data to sendpage. Note that text supplied
on the command line does not include a trailing newline
character.
The order of options on the command line is significant.
Each page to be transmitted is assigned the current value
of parameters specified on the command line; e.g. whether
or not to queue the request. This means that options that
specify parameters for a particular destination must pre-
cede the pager ID specified with the -p option. For exam-
ple,
sendpage -l 2 -p sam Your network is hosed
submits a page to ``sam'' that has service level 2 while
sendpage -p sam -l 2 Your network is hosed
submits the same page but with the default service level
(1). Note also that parameter values persist across -p
options so the following
sendpage -l 0 -p sam -p 5551212 Your network is
hosed
submits two pages, both of which have service level 0.
OPTIONS
-a time Schedule transmission at the indicated time.
Times are specified using the syntax of the
at(1) command; e.g. ``now + 30 minutes'' to
schedule transmission 30 minutes in the
future. By default, sendpage schedules pages
for ``now''. (In SNPP parlance this option
specifies the ``hold time'' for the page; and
may result in the page being delivered to the
paging terminal but not delivered to the user
until the specified time.)
-D Enable notification by electronic mail when
the page has been delivered to the service
provider. This option is meaningful only when
communicating with a HylaFAX server.
-f from Use from as the identity of the message
sender. Otherwise the sender is the user that
invoked sendpage. The sender is an account
name to which the HylaFAX software should
direct email notification messages. The from
identity may be a fullblown ``From:'' line,
e.g. e.g. ``Joe Blow lt;joe@foo.com'' and
``joe@foo.com (Joe Blow)'' are acceptable. If
no host-part is specified in the from string
the local hostname is used. This option is
useful when sendpage is invoked on behalf of
another user, such as in the implementation of
an electronic mail to pager gateway.
-h [modem@]host[:port]
Force the jobs to be processed on a specific
host and, optionally, using a particular
modem. The host may be either a symbolic name
or a network address. If no -h option is sup-
plied, sendpage uses the SNPPSERVER environ-
ment variable to identify the SNPP server to
which the pages should be directed. If no
server is specified then sendpage attempts to
contact a server on the local host. If no
modem is specified, the job will be submitted
to any available modem.
-I time If a job must be requeued because of a commu-
nication failure schedule the retry according
to the specified time. Times are given in
seconds. Minutes, hours, and days can be
specified with ``min'', ``hour'', and ``day''
suffixes, respectively. By default HylaFAX
reschedules jobs using retry times that depend
on the manner in which the job failed; this
interface permits a user to override this
algorithm and specify a single fixed retry
time for all communication failures. This
option is meaningful only when communicating
with a HylaFAX server.
-l level Specify a particular service level to use in
delivering a page. A service level defines
both a scheduling priority and the time that a
client is willing to wait to find out if
delivery is successful or not. Normal deliv-
ery is obtained with level 1 (default). The
specification identifies level 0 as the high-
est priority service level with levels 1-7
lower priority and levels 8-11 vendor/server-
specific. For HylaFAX server machines the
mapping between service level and scheduling
priority is defined by the configuration of
the SNPP server process; see the PriorityMap
parameter in hfaxd(8C)
-n Send to a numeric-only paging device; i.e. do
not send a text message in the paging request.
-N Do not notify the sender by electronic mail
when the page has been delivered to the ser-
vice provider (default). This option is mean-
ingful only when communicating with a HylaFAX
server.
-p PIN The Pager Identification Number (PIN) for a
terminal that is to receive the message. A
message can be sent to multiple destinations
by specifiying multiple -p options.
-q Mark pages to be queued on the server and do
not wait for their delivery. By default send-
page conforms to the SNPP spec by syn-
chronously waiting for each page to be deliv-
ered. This option instructs sendpage to sub-
mit one or pages and then terminate immedi-
ately without waiting for their completion.
When pages are queued it is advisable to
enable email notification with the -D or -R
options. Job queueing is a non-standard func-
tion of the SNPP implementation in HylaFAX and
is not available when submitting pages to non-
HylaFAX servers.
-R Enable notification by electronic mail when
the message has been delivered and when it is
requeued for retransmission. HylaFAX will
always notify the sender by electronic mail if
there is problem delivering a page (irregard-
less of the email notification setting). This
option is meaningful only when communicating
with a HylaFAX server.
-s subject Set the ``subject'' for the specified pages
according to subject. For HylaFAX subject is
used as the identifier string returned in any
email notification messages (instead of the
usual job identifier number). This option is
useful for applications that cross reference
notification messages against job submissions.
-t tries Make no more than tries attempts to send the
page. By default, HylaFAX will terminate a
job if: 3 consecutive attempts to send a par-
ticular message fail, or it appears the
receiver is not a service provider. Otherwise
HylaFAX places no limit on the number of
attempts to send a page, instead terminating a
job if it is not completed within a fixed
period of time specified by the service level.
Note that a try is a phone call in which car-
rier is established and the IXO/TAP or UCP
protocol is commenced; this is contrasted with
a call attempt that might have failed because
the line was busy. This option is meaningful
only when communicating with a HylaFAX server.
-T dials Make no more than dials phone calls when
attempting to send a page. By default,
HylaFAX will terminate a job if: 12 attempts
to reach a service provider fail, or it
appears the receiver is not a service
provider. Otherwise HylaFAX terminates a job
if it is not completed within a fixed period
of time specified by the service level. This
option is meaningful only when communicating
with a HylaFAX server.
-v Trace the protocol between sendpage and the
SNPP server process that does the delivery
work on the remote machine. This information
is directed to the standard output.
CONFIGURATION PARAMETERS
sendpage reads configuration information from the files
/usr/local/lib/fax/hyla.conf, /usr/local/lib/fax/send-
page.conf, and ~/.hylarc; in that order. Configuration
files follow the conventions described in hylafax(1). The
following configuration parameters are recognized:
Tag Type Default Description
HoldTime string - hold time to assign to pages
Host string localhost host to contact for service
MailAddr string - mail address for notification messages
MaxDials integer 12 times to retry dialing
MaxTries integer 3 times to retry transmission
Notify string none control email notification
Port integer 444 port to use in contacting server
Protocol string tcp protocol to use in contacting server
QueueSend boolean No whether or not to queue pages
RetryTime string - delay between failed attempts to send
ServiceLevel integer SNPP service level for pages
Verbose boolean No whether or not to enable protocol tracing
The configuration parameters are explained below:
HoldTime The hold time to assign to pages. (Equiva-
lent to the -a option.)
Host The host to contact for service. (Equiva-
lent to the -h option.)
MailAddr The electronic mail address to direct noti-
fication messages from the server. If this
string is specified without an ``@host-
name'' part then the local hostname will
automatically be appended. (Equivalent to
the -f option.)
MaxDials The maximum number of times to dial the
phone for each job. (Equivalent to the -T
option.)
MaxTries The maximum number of times to retry send-
ing a job. (Equivalent to the -t option.)
Notify Control the email notification messages
from the server. This string may be one of
``done'', ``none'', ``requeued'' or
``default'' with an optionally preceding
``when '' (e.g. ``when done''). Note that
``when requeued'' implies ``when done''.
(Equivalent to the -D, -R, and -N options.)
Port The network port to contact for service.
(Eqvuialent to the -h option.)
Protocol The name of the communication protocol to
use when contacting a server. (Equivalent
to the SNPPSERVICE environment variable.)
QueueSend Control whether or not to wait for the
pages to be delivered. (Equivalent to the
-q option.)
RetryTime The time to delay between job retries due
to a communication failure. (Equivalent to
the -I option.)
ServiceLevel The SNPP service level to assign to each
page. (Equivalent to the -l option.)
Verbose Control protocol tracing. (Equivalent to
the -v option.)
ENVIRONMENT
The following environment variables are used by sendpage:
SNPPSERVER The identity of the SNPP server to contact
for service. This value is specified as
``[modem@]host[:port]'' where host is
either a host name or the Internet ``.''
(dot) address of the host; port is the TCP
port number or service name to use (default
is ``snpp'' or 444); and modem is an
optional modem name or class on the server
machine to use in processing the requests
(this is meaningful only when the server is
running HylaFAX).
SNPPSERVICE The communication service specification for
communicating with the SNPP server. This
value is specified as ``port[/protocol]'';
by default ``444/tcp''.
FILES
/usr/tmp/sndpageXXXXXX temporary files
NOTES
The phone number of the pager service provider is stored
on the server machine and is not specified by the user;
this is a departure from pager support that was supplied
with HylaFAX version 3.0.
HylaFAX version 3.0 used to recognize a null text message
and assume the destination paging device was numeric-only.
This is no longer true; if a null text message is submit-
ted then a null message will be included in the paging
request. This may cause paging requests submitted to
``real SNPP'' servers to be rejected if the paging device
is in fact numeric-only. When sending to a numeric-only
paging device the -n option should be used.
BUGS
It is not possible to page text- and non-text devices
together; sendpage must be run twice, once to send to
text-capable devices and once to send to non-text devices.
SEE ALSO
at(1) hylafax(1) faxalter(1) faxrm(1) faxstat(1)
faxq(8C) hfaxd(8C) hylafax(5F)