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 supplied 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 terminals and,
optionally, include a text message (depending on the capability of the
receiving device). Each destination is identified by a Pager
Identification Number (PIN) specified 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
precede the pager ID specified with the -p option. For example,
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
<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 supplied, sendpage uses the SNPPSERVER
environment 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 communication
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 delivery is
obtained with level 1 (default). The SNPP specification
identifies level 0 as the highest 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(8)
-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 service provider (default). This
option is meaningful 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 specifying multiple -p options.
-q Mark pages to be queued on the server and do not wait for
their delivery. By default sendpage conforms to the SNPP
spec by synchronously waiting for each page to be
delivered. This option instructs sendpage to submit one or
pages and then terminate immediately 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 function 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 (irregardless 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 particular 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 carrier 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
/etc/hylafax/hyla.conf, /etc/hylafax/sendpage.conf, and ~/.hylarc; in
that order. Configuration files follow the conventions described in
hylafax-client(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. (Equivalent to the -a
option.)
Host The host to contact for service. (Equivalent to the -h
option.)
MailAddr The electronic mail address to direct notification
messages from the server. If this string is specified
without an ``@hostname'' 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 sending 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. (Equivalent 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
/var/spool/hylafax/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 submitted 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-client(1), faxalter(1), faxrm(1), faxstat(1), faxq(8),
hfaxd(8), hylafax-server(5)
May 12, 1996