Man Linux: Main Page and Category List

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