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)