Ubuntu Manpage: sendpage - submit a pager job for transmission

Provided by: hylafax-client_6.0.6-5_amd64

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.