PMDF System Manager's Guide

28.4.1 Setting Up the Channel

There are four steps in setting up a pager channel: (1) adding the necessary channel blocks and rewrite rules to the PMDF configuration file, (2) setting up a PAGER mapping table, (3) setting up a modem script, and (4) setting up a channel option file, if necessary. A fifth and optional step is to set up a directory channel. With a directory channel, pager addressing can be simplified. For instance, rather then sending mail to /id=1234/msglen=200/@mci.pager.example.com, addresses like andy@pager.example.com can be used. This obviates, from the user's perspective, the need to remember pager numbers everytime a page is to be sent.

28.4.1.1 Before You Start

Before you begin setting up a pager channel, you should try to obtain the following information from your paging service provider:

The phone numbers, preferably local, for each dial-up paging switch you plan to use. Attempting to obtain these numbers can be quite frustrating: if you do not use the proper terminology, the customer service representatives will not know what you are talking about. Unfortunately, every service provider seems to have their own, unique terminology. You are asking for the phone number of an auto-answer, asynchronous modem. When you dial it, you should hear a modem tone. Some possible ways of inquiring after this number include:
1. Ask for the telephone number for "alpha-numeric paging".
2. Ask, "If I had a Motorola AlphaMate, what telephone number would I use?" An AlphaMate is an intelligent terminal with an internal modem that some paging companies will provide for you to send alpha-numeric pages.
3. Ask for the "paging modem telephone number".
If none of this works, ask to talk to a technician and repeat the questions.
The dialup modem characteristics (baud rate, etc.). It is very unlikely that your paging provider will be able to tell you this information, but if you like hitting your head up against a brick wall you can try asking them anyhow. We have not found any paging switches that will not accept 300 baud, even parity, with 7 data bits. We have seen paging switches which will handle 1200 and 2400 baud. We have also seen paging switches which will accept "no parity" even though they send even parity. We have also heard of paging switches which will claim to connect at, say 1200 or 2400 baud, but will nonetheless transmit at 300 baud.
The maximum number of bytes per page accepted by the switch. Do not confuse this limit with that imposed by a page receiver. The limit imposed by the switch is handled through the MAX_PAGE_SIZE channel option; the limit imposed by individual pager units is controlled on a per address basis with the PAGLEN address attribute. If the paging provider seems unsure of this, or if your longer pages don't work, you will have to determine this value experimentally. You can find that you have to limit your pages to a few bytes less than what the provider thinks the maximum is.

Note that this information can generally be determined by trial-and-error: enable master_debug for the pager channel and send some messages of varying length. Then look in the file pager_name_master.log (where name) is the specific part of the name of a pager channel in the PMDF log file directory and see if the switch rejects the page.⁴ If it does reject pages, then the values set with the MAX_PAGE_SIZE or MAX_BLOCKS_PER_PAGE channel options can need to be reduced. Many switches only accept single pages of lengths less than 200±100 bytes. The pager channel will automatically break messages which exceed MAX_PAGE_SIZE into multiple pages, each page requiring no more than MAX_BLOCKS_PER_PAGE data blocks.

28.4.1.2 Adding the Channel to the Configuration File

First choose domain names (i.e., host names) to associate with each paging switch you intend to use. These domain names will be used when addressing a message to a particular paging switch. For instance, suppose the local domain is EXAMPLE.COM and mail is to be routed to one of two paging switches operated by Pacific Telephone and MCI. Then appropriate domain names might be pactel.pager.example.com and mci.pager.example.com.

After choosing domain names, domain-name-1, domain-name-2 ..., add to the PMDF configuration file channel block entries of the form

pager_x1 domain-name-1 pager_x2 domain-name-2 . . .

Here x1, x2 ... are unique strings, each less than 26 characters in length, which serve to uniquely identify each instance of a pager channel. Be sure to leave a blank line before and after each channel block you add to your configuration file.

Continuing with our example from above, the channel blocks might appear as

pager_pactel pactel.pager.example.com pager_mci mci.pager.example.com

After adding the channel block, go to the top of the configuration file and add rewrite rules of the form:

domain-name-1 $U@domain-name-1 domain-name-2 $U@domain-name-2 . . .

For instance, in the context of our example, the following rewrite rules should be added

pactel.pager.example.com $U@pactel.pager.example.com mci.pager.example.com $U@mci.pager.example.com

Note

If you are part of a TCP/IP network, then you can want to add the pager domain names you selected to your DNS using MX records. This will allow other machines to route mail to your pager channels.

28.4.1.3 PAGER Mapping

The next step in setting up one or more pager channels is to add a mapping table named PAGER to the mapping file. This table serves three purposes: it specifies which message header lines to include in a page, how to abbreviate those header lines, and how to abbreviate the body of a message (i.e., remove superfluous spaces, abbreviate words, etc.). Some familiarity with the use of the mapping file is helpful at this point; see Chapter 5.

The name of the mapping table should either be PAGER or PAGER_x where x is the name of the pager channel (e.g., PAGER_pager_pactel or PAGER_pager_mci). Each time a pager channel runs, it will first attempt to load the mapping table PAGER_x or, if that fails, it will then attempt to load the table PAGER. If neither table can be loaded, then the entire message will be sent in its entirety.⁵

Two types of entries can be made in the mapping table. However, before explaining the format of those entries, let it be made clear that an understanding of how to use the mapping file is essential in order to understand how to construct and use these entries. A sample mapping table is given after the description of these two types of entries. This sample table, which exists as the file pager_table.sample in the PMDF table directory, will probably meet most site's initial needs and can simply be included into the mapping file as follows: (a) copy the file to pager_table.txt, (b) set this new file to be world readable, and (c) include a file reference to it in the PMDF mapping file.⁶ That is, to the PMDF mapping file add an entry such as on OpenVMS

<PMDF_TABLE:pager_table.txt

or on UNIX

</pmdf/table/pager_table.txt

or on NT

<C:\pmdf\table\pager_table.txt

Now, the two types of entries are as follows:

Message header entries. These entries specify which message header lines should be included in a page and how they should be abbreviated or otherwise mapped. Only if a header line is successfully mapped to a string of non-zero length by one of these entries will it be included in the page being generated. Each entry has the format
H|pattern replacement-text
If a message header line matches the pattern pattern then it will be replaced with the replacement text replacement-text using the mapping file's pattern matching and string substitution facilities. The final result of mapping the header line will then be included in the page provided that the metacharacter $Y was specified in the replacement text. If a header line does not match any pattern string, if it maps to a string of length zero, or if the $Y metacharacter is not specified in the replacement text, then the header line will be omitted from the page. The two entries
H|From:* F:$0$Y H|Subject:* S:$0$Y
cause the From: and Subject: header lines to be included in pages with From: and Subject: abbreviated as F: and S:. The entries:
H|Date:* H|D:$0$R$Y H|D:*,*%19%%*:*:* H|D:$0$ $5:$6$R$Y
cause the Date: header line to be accepted and mapped such that, for instance, the header line Date: Wed, 15 Dec 2012 16:13:27 -0700 (PDT) will be converted to D: Wed 16:13. Very complicated, iterative mappings can be built. Managers who want to set up custom filters will first need to understand how the mapping file works. The H| in the right-hand-side of the entry can be omitted, if desired. The H| is allowed in that side so as to cut down on the number of table entries required by sets of iterative mappings.
Message body mappings. These entries establish mappings to be applied to each line of the message body. Each line of the message body will be passed through these mappings before being incorporated into the page being built. These entries take the form:
B|pattern B|replacement-text
If a line of the message body matches a pattern pattern then it will be replaced with the replacement text replacement-text. Again, very complicated, iterative mappings can be constructed using this facility. The B| in the right-hand-side of the entry can be omitted, if desired.

The file pager_table.sample from the PMDF table directory is shown in Example 28-2. The entries in this example are explained below.

These two entries cause From: and Subject: header lines to be included in a page. From: and "Subject:" are abbreviated as, respectively, F: and S:. Some of the other entries can have further effects on From: and Subject: header lines.
This entry will reduce a From: header line containing a <...> pattern to only the text within the angle brackets. E.g., "F: "John C. Doe" (Johnny)" will be replaced with "F: jdoe@example.com".
This entry will remove, inclusively, everything inside of a (...) pattern in a From: header line. E.g., "F: "John C. Doe" (Johnny)" will be replaced with "F: "John C. Doe" ".
This entry will remove, inclusively, everything inside of a "..." pattern in a From: header line. E.g., "F: "John C. Doe" (Johnny)" will be replaced with "F: (Johnny)".
This entry will remove, inclusively, everything to the right of an at-sign, @, in a From: header line. E.g., "F: "John C. Doe" (Johnny)" will be replaced with "F: "John C. Doe" ".
These four entries remove leading and trailing spaces from lines in the message header and body.
These two entries reduce two spaces to a single space in lines of the message header and body.
These four entries reduce double dashes, periods, exclamation points, and question marks to single occurrences of the matching character. Again, this helps save bytes in a page.









  
    Example 28-2 Sample PAGER Mapping Table
  


  
    
      

      PAGER 
 
  H|From:*                         H|F:$0$R$Y  (1)
  H|Subject:*                      H|S:$0$R$Y  (1)
  H|F:*<*>*                        H|F:$1$R$Y  (2)
  H|F:*(*)*                        H|F:$0$2$R$Y  (3)
  H|F:*"*"*                        H|F:$0$2$R$Y  (4)
  H|F:*@*                          H|F:$0$R$Y  (5)
  H|%:$ *                          H|$0:$1$R$Y  (6)
  H|%:*$                           H|$0:$1$R$Y  (6)
  H|%:*$ $ *                       H|$0:$1$ $2$R$Y  (7)
  B|*--*                           B|$0-$1$R  (8)
  B|*..*                           B|$0.$1$R  (8)
  B|*!!*                           B|$0!$1$R  (8)
  B|*??*                           B|$0?$1$R  (8)
  B|*$ $ *                         B|$0$ $1$R  (7)
  B|$ *                            B|$0$R  (6)
  B|*$                             B|$0$R  (6)





In Example 28-2, the metacharacter $R is used to implement and 
control iterative application of the mappings. By iterating on these 
mappings, powerful filtering is achieved. For instance, the simple 
mappings to remove a single leading or trailing space 
((6)) or reduce two spaces to a single space 
((7)) become, when taken as a whole, a filter which strips 
all leading and trailing spaces and reduces all consecutive 
multiple spaces to a single space. Such filtering helps reduce the size 
of each page.


The order of the entries is very important. For instance, with the 
given ordering, the body of the message From: header line


From: "John C. Doe" <jdoe@example.com> (Naples) will be reduced to


jdoe The steps taken to arrive at this are as follows:


  We begin with the From: header line


From: "John C. Doe" <jdoe@example.com> (Naples) The pattern in 
the first mapping entry matches this and produces the result


F: "John C. Doe" <jdoe@example.com> (Naples) The $R metacharacter 
in the result string causes the result string to be remapped.
  
The mapping  is applied to the result string 
  of the last step. This produces:


F: jdoe@example.com The $R in the mapping causes the entire set of 
mappings to be re-applied to the result of this step.
  
Next, the mapping  is applied producing


F: jdoe The $R in the mapping causes the entire set of mappings to be 
re-applied to the result of this step.
  
Next, the mapping  is applied producing


F:jdoe The $R in the mapping causes the entire set of mappings to be 
re-applied to the result of this step.
  
Since no other entries match, the final result string


F:jdoe is incorporated into the page.



Note that the PMDF TEST/MAPPING utility (OpenVMS) or pmdf test 
-mapping utility (UNIX and NT) can be used to test the PAGER 
mapping table. For instance, on OpenVMS:




  
    
      

      $ PMDF TEST/MAPPING/NOIMAGE_FILE/MAPPING_FILE=PMDF_TABLE:pager_table.sample
Enter table name: PAGER
Input string: H|From: "John C. Doe" <jdoe@example.com> (Naples)
Output string: H|F:jdoe 
Output flags: [0,1,2,89] 
Input string: ^Z
$ 




Or on UNIX:



  
    
      

      # pmdf test -mapping -noimage_file -mapping_file=/pmdf/table/pager_table.sample
Enter table name: PAGER
Input string: H|From: "John C. Doe" <jdoe@example.com> (Naples)
Output string: H|F:jdoe 
Output flags: [0,1,2,89] 
Input string: ^D
# 




Or on NT:



  
    
      

      C:\> pmdf test -mapping -noimage_file -mapping_file=C:\pmdf\table\pager_table.sample
Enter table name: PAGER
Input string: H|From: "John C. Doe" <jdoe@example.com> (Naples)
Output string: H|F:jdoe 
Output flags: [0,1,2,89] 
Input string: ^C
C:\> 




See Chapter 31 and  Chapter 32 for information on using these utilities.







28.4.1.4 Modem Script

To handle the dialout modems used to call paging switches, the pager 
channel uses PhoneNet's modem handling facilities. Specifically, the 
pager channel uses the phone_list.dat file, described in 
Section 26.3, and modem script files, described in Section 26.5.


Before writing a modem script, you should manually dial the paging 
switch with the modem you intend to use. Record the modem commands 
required to dial the switch and the modem responses generated in the 
process. These commands and responses will then form the basis for your 
modem script.


On all platforms, the modem and serial line must be 8 bits, no parity.


For each pager channel, a separate script file is required, stored in a 
required subdirectory of the PMDF table directory. Each such script 
file must have a name of the form


pmdf_root:[table.channel]script_script. 
(OpenVMS) or


/pmdf/table/channel/script_script (UNIX) 
or


C:\pmdf\table\channel\script_script on 
NT where channel is the name of the pager channel 
and script is the script option specified in the 
phone_list.dat file.



Suppose that two pager channels, pager_pactel and pager_mci, are to be 
set up. Then a phone_list.dat file in the PMDF table 
directory and two script files need to be set up. A sample OpenVMS 
phone_list.dat file is shown in Example 28-3, and an 
analogous sample UNIX phone_list.dat file is shown in 
Example 28-4.



  
    Example 28-3 Example OpenVMS 
    phone_list.dat File for Two Pager Channels
  


  
    
      

      pager_pactel (1)   TTA3: (2)  hayes (3)
pager_pactel (1)   TTA3:     hayes 
pager_mci (4)      TTA3:     hayes 
pager_mci (4)      TTA3:     hayes 







  
    Example 28-4 Example UNIX 
    phone_list.dat File for Two Pager Channels
  


  
    
      

      pager_pactel (1)   /dev/ttyd0 (2)  hayes (3)
pager_pactel (1)   /dev/ttyd0     hayes 
pager_mci (4)      /dev/ttyd0     hayes 
pager_mci (4)      /dev/ttyd0     hayes 







In these examples, the following items should be noted:


  Two identical entries (methods) are provided 
  for the pager_pactel channel. If the first method fails, then the 
  second method will be attempted. By providing two identical methods, we 
  ensure that if, for some reason, the first call fails (busy signal, no 
  answer) a second attempt will immediately be made.
  
The same terminal line, ( TTA3: 
  on OpenVMS or /dev/ttyd0 on UNIX), is used by all methods 
  listed. The dialup modem is connected to this terminal line.
  
The same script prefix name is used by each 
  method. However, two script files, are required. Both are named 
  hayes_script, but one is stored in the 
  pager_pactel subdirectory and the other in the 
  pager_mci subdirectory of the PMDF table directory.
  
Two identical entries (methods) are provided 
  for the pager_mci channel.



The sample OpenVMS phone_list.dat file shown in 
Example 28-3 calls for two script files,


and


pmdf_root:[table.pager_mci]hayes_script.


The sample UNIX phone_list.dat file shown in 
Example 28-4 calls for two script files,


 and




When the same modem is used for each pager channel, as in 
Example 28-3 and Example 28-4, the only difference between the 
individual script files is usually just the phone number to be dialed 
for each paging switch. A sample script file intended for a Hayes 
compatible modems is shown in Example 28-5. (A sample script for 
Racal-Vadic 212a modems is given in Example 28-6.) Nearly all of the 
script commands shown are modem specific. In writing your own script 
file, a knowledge of your modem's command language as well as the 
responses to expect from the modem is essential.




  
    Example 28-5 Example Hayes-compatible Modem 
    Script
  


  
    
      

      init begin (1)
xmit "ATV1&M0&N1\r"  (2)
recv "OK" 10  (3)
init end (4)
xmit "\xATDT99500572\r"  (5)
recv "CONNECT" 30  (6)
xmit "\x\r\x"  (7)
go  (8)
xmit "\xATHZ\r"  (9)
end 
 






The following notes apply to Example 28-5.


  Begin modem initialization.
  
Issue "verbal" response codes 
  rather than numeric response codes (V1); turn off MNP negotiations 
  (&M0); and tell the modem to negotiate a 300 baud connection 
  (&N1). Your modem might not understand MNP and thus lack the 
  &M0 command. Or, it might use some command other than &M0 to 
  disable MNP negotiations.
  
Wait up to 10 seconds for the response 
  "OK".
  
End modem initialization.
  
Pause one second and then dial the paging 
  switch.
  
Wait up to 30 seconds for the response 
  "CONNECT".
  
Pause one second and then send a carriage 
  return. With some paging switches you can need to omit this xmit 
  command.
  
Connection has been made; allow the pager 
  channel to take over.
  
Pager channel is done; force the modem to 
  hangup (H) and then reset the modem (Z).



The following notes apply to Example 28-6.


  Start of the modem initialization section of 
  the script.
  
Transmit a control-E followed by a carriage 
  return.
  
Wait up to 10 seconds for the response 
  "*".
  
End of the modem initialization section of 
  the script.
  
Pause one second and then issue the modem's 
  dial command.
  
Wait up to 10 seconds for the response 
  "UMBER?".
  
Pause one second, specify that the modem 
  should establish a 300 baud connection, and then specify the number to 
  be dialed (625-6149).
  
Wait up to 10 seconds for the modem to echo 
  the phone number to be dialed.
  
Pause one second and then transmit a carriage 
  return. After the return is received by the modem, the modem will dial 
  the number.
  
Wait up to 30 seconds for the response 
  "N LINE".
  
Connection has been made; allow the pager 
  channel to take over.





  
    Example 28-6 Example Racal-Vadic 212a Modem 
    Script
  


  
    
      

      init begin (1)
xmit "\005\r" (2)
recv "*" 10 (3)
init end (4)
xmit "\xD\r" (5)
recv "UMBER?" 10 (6)
xmit "\x9k6256149\r" (7)
recv "6149" 10 (8)
xmit "\x\r"  (9)
recv "N LINE" 30 (10)
go (11)
end 
 





The following is a fine technical point --- don't worry if you don't 
understand this the first time.




Normally, when the script processing fails, (e.g., a 
recv command times out), the next method, if any, in the 
phone_list.dat file is attempted. However, this defeats 
the use of modem pools on OpenVMS:⁷ for instance, if the 
initialization of the first device in the pool fails then rather than 
try any other devices in the pool, the next method will be tried. 
However, should the script fail because of a post initialization 
problem (e.g., the dialed number was busy), then attempting 
the next method rather than the next device in the modem pool is the 
proper behavior. The init begin and init end 
script commands should be used in conjunction with modem pools: they 
mark one or more sections of the script file as being modem 
initialization steps. Should the script fail while processing a command 
in a script section delimited by init begin and init 
end , then the pager channel will first try any other devices in 
the search list. Only after that list of devices has been exhausted, 
will the next method from the phone_list.dat file be 
tried. Failures which occur in commands outside of an initialization 
section will result in the next method being tried.







28.4.1.5 Option Files

A great number of options can be set with an option file. Option files 
are used to set run-time options on a per channel basis. Option files 
are stored in the PMDF table directory and have names of the form 
x_option, where x is the 
name of the pager channel to which the option file applies, 
i.e., PMDF_TABLE:x_option. on OpenVMS, 
or /pmdf/table/x_option on UNIX, or 
C:\pmdf\table\x_option on NT.


Option files consist of several lines. Each line contains the setting 
for one option. An option setting has the form:



  
    
      

      option=value




value can be either a string or an integer, 
depending on the option's requirements. If the option accepts an 
integer value, value, a base can be specified 
using notation of the form b%v, where 
b is the base expressed in base 10 and 
v is the actual value expressed in base 
b.


Comments are allowed. Any line that begins with an exclamation point, 
!, is considered to be a comment and is ignored. Blank lines are also 
ignored in any option file.


The available options are: 

ACK_SUCCESS (0 or 1)

When the ACKNOWLEDGEMENT option specifies a value greater than zero, 
both status reports and a final delivery report (success or failure) 
will be generated. By specifying ACK_SUCCESS=0, any final success 
delivery report will be suppressed (not sent); the originator of the 
page will then only receive status reports and any final error report. 
This option is ignored when ACKNOWLEDGEMENT specifies a value less than 
unity. To suppress all status reports and success delivery reports 
(i.e., only send a message when an error occurs), simply 
specify ACKNOWLEDGEMENT=-1.
ACKNOWLEDGEMENT (integer)

By default, delivery acknowledgements are not generated 
(ACKNOWLEDGEMENT=-1). However, when this option specifies an integer 
value greater than or equal to zero, then a delivery acknowledgement 
will be sent to the message originator after a page has been 
successfully transmitted to the paging switch provided that either 
NOTARY was not used to submit or relay the message to PMDF, or, if 
NOTARY was used, that delivery reports (DSNs) were requested. 
Acknowledgements are preferentially sent to the delivery receipt 
address specified by a Delivery-receipt-to: header line. If no such 
header line is specified, then the address specified by a Reply-to: 
header line is used. Finally, if no Reply-to: header line is present, 
then the envelope From: address is used. If the originating message 
specifies a delivery receipt address of <>, then no 
acknowledgement will be generated. If USE_REPLY_TO=0 has been specified 
in the option file, then the Reply-to address will never be used. If 
set to a positive integer n >= 1 then status reports are 
sent every nth unsuccessful transmission attempt starting with 
the first attempt; i.e., on attempts 1, 1+n, 1+2n, 1+3n, .... 
For instance, if ACKNOWLEDGEMENT=1 then a status report will be sent 
every attempt until the message is successfully sent, and then, when 
the message is successfully sent, an acknowledgement will be sent. If, 
however, ACKNOWLEDGEMENT=5 then status reports will be sent on attempts 
1, 6, 11, 16, etc. until the message is successfully delivered 
or returned. When it is delivered or returned, an acknowledgement is 
sent. Set ACKNOWLEDGEMENT=0 if you only want acknowledgements sent when 
the message is successfully transmitted; set ACKNOWLEDGMENT=-1 if you 
want no acknowledgements or status reports sent. See also ACK_SUCCESS.
BACKOFF (integer >= 0)

When BACKOFF specifies an integer greater than zero, backoff retries 
will be attempted for messages which could not be delivered 
immediately. See Section 28.4.1.8 for details. By default, BACKOFF=0.
BLOCK_ACK_TIMEOUT (integer > 0)

This option specifies how long to wait after transmitting a data block 
to the paging switch for an acknowledgement. The default value is 30 
seconds. If no acknowledgement is received within BLOCK_ACK_TIMEOUT 
seconds after transmitting a block, then the page will be aborted and 
requeued for a subsequent delivery attempt. See the description of the 
BLOCK_TX_RETRIES option for further details on the use of this option.
BLOCK_TX_RETRIES (integer > 0)

After a data block is transmitted to the paging switch, the pager 
channel waits up to BLOCK_ACK_TIMEOUT seconds for an acknowledgement. 
If no acknowledgement is received within BLOCK_ACK_TIMEOUT seconds, 
then the page will be aborted and requeued for a subsequent delivery 
attempt. If a negative acknowledgement is received, then the pager 
channel will retransmit the data. Up to BLOCK_TX_RETRIES attempts will 
be made to send a data block. The page will be aborted and requeued for 
a subsequent delivery attempt when any one data block cannot be 
successfully transmitted after BLOCK_TX_RETRIES attempts (negative 
acknowledgements) or if the channel times out while waiting for an 
acknowledgement (no acknowledgement). The default value for 
BLOCK_TX_RETRIES is 7.
HEADER_STOP (character string)

This option specifies a character string to use as a delimiter between 
the message header lines and the message body. By default, the string 
"M:" is used.
ID_RX_RETRIES (integer > 0)

This option specifies the number of times the pager channel will 
attempt to obtain an "ID=" response from the paging switch. 
If an "ID=" is not received after ID_RX_TIMEOUT seconds, then 
the pager channel will transmit a carriage return to the switch and 
resume waiting for an "ID=" response. By default, the pager 
channel will try up to 4 times to obtain an "ID=" response. 
This default value can be changed with this option. If an ID= response 
is not received after ID_RX_RETRIES attempts, then the page will be 
aborted and requeued for a subsequent delivery attempt.
ID_RX_TIMEOUT (integer > 0)

This option specifies the number of seconds to wait for an 
"ID=" response from the paging switch before timing out. The 
default value is 5 seconds. See the description of the ID_RX_RETRIES 
option for further details.
LINE_STOP (character string)

This option specifies a character string to use as a delimiter between 
each line of the filtered message. By default, a single space is 
inserted between each line.
LOGIN_RETRIES (integer > 0)

This option specifies the number of times the pager channel will 
attempt to log into a paging switch. After transmitting the password in 
response to an "ID=" received from the switch, the pager 
channel will wait up to LOGIN_ACK_TIMEOUT seconds for an 
acknowledgement. If no acknowledgement is received, then the pager 
channel will resume waiting again. If a negative acknowledgement or 
"ID=" response is received, then the password will be 
retransmitted and the channel will resume waiting for a response. If 
after going through this process LOGIN_RETRIES times and a successful 
login has not been established, the page will be aborted and requeued 
for a subsequent delivery attempt. In no case will the channel ever 
wait more than an accumulated LOGIN_RETRIES * LOGIN_ACK_TIMEOUT 
seconds. By default, a value of 4 is used for LOGIN_RETRIES.
LOGIN_ACK_TIMEOUT (integer > 0)

This option specifies the number of seconds to wait for a login 
acknowledgement from the paging switch before timing out. The default 
value is 5 seconds. See the description of the LOGIN_ACK_RETRIES option 
for further details.
LOGOUT_RETRIES (integer > 0)

This option specifies the number of times the pager channel will 
attempt to log off from a paging switch. After transmitting the logout 
command, the pager channel will wait up to LOGOUT_ACK_TIMEOUT seconds 
for an acknowledgement. If no acknowledgement is received, then the 
pager channel will merely close its connection to the paging switch and 
consider the pages to not have been sent.⁹ If a negative 
acknowledgement is received, then the page was rejected. This is 
treated as a permanent error and the channel will return the message to 
the originator. If an unrecognized response is received, then the 
channel will resume waiting for a response. If, after waiting 
LOGOUT_RETRIES times only unrecognized responses have been received, 
the channel will merely close its connection and consider the pages to 
have been sent successfully. In no case will the channel ever wait more 
than an accumulated LOGOUT_RETRIES * LOGOUT_ACK_TIMEOUT seconds. By 
default, a value of 4 is used for LOGOUT_RETRIES.
LOGOUT_ACK_TIMEOUT (integer > 0)

This option specifies the number of seconds to wait for a logout 
acknowledgement from the paging switch before timing out. The default 
value is 5 seconds. See the description of the LOGOUT_ACK_RETRIES 
option for further details.
MAX_BLOCKS_PER_PAGE (integer)

Some paging switches impose a limit on the number of data blocks per 
page. The two typical cases are either no limit on the number of blocks 
per page (MAX_BLOCKS_PER_PAGE=-1) or at most one block per page 
(MAX_BLOCKS_PER_PAGE=1). When a limit is imposed, each message will be 
broken into the requisite number of pages, no one page requiring more 
than MAX_BLOCKS_PER_PAGE data blocks to transmit. No limit will be 
imposed when MAX_BLOCKS_PER_PAGE specifies a negative value. This is 
the default case, MAX_BLOCKS_PER_PAGE=-1. This option and the 
MAX_PAGE_SIZE option are the two most important options used by the 
pager channel. They are also the most likely to vary from switch to 
switch. If the proper values are not used, the paging switch will 
reject the pages presented to it.
MAX_DELIVERY_ATTEMPTS (integer > 0)

The MAX_DELIVERY_ATTEMPTS option controls the maximum number of 
delivery attempts to be made for a message. The default value is 15. If 
this option is set to 0, then no upper limit is imposed and PMDF's 
normal message return system will eventually return undeliverable 
messages. If a value is specified, then after delivery of the message 
has been tried MAX_DELIVERY_ATTEMPTS times, no further attempts will be 
made; the message will be immediately returned to the sender.
MAX_MESSAGE_SIZE (integer)

Messages which exceed, after filtering with the PAGER table mappings, a 
size of MAX_MESSAGE_SIZE bytes will be truncated to MAX_MESSAGE_SIZE 
bytes. The extra bytes are discarded. If MAX_MESSAGE_SIZE specifies a 
negative value, then no size limit will be imposed. This is the default 
setting, MAX_MESSAGE_SIZE=-1. This option can be overridden on a per 
address basis with the MSGLEN address attribute.
MAX_PAGE_SIZE (integer)

Messages which exceed, after filtering with the PAGER table mappings, a 
size of MAX_PAGE_SIZE bytes will be split into multiple pages, no one 
page exceeding a byte count of MAX_PAGE_SIZE or requiring more than 
MAX_BLOCKS_PER_PAGE data blocks. If MAX_PAGE_SIZE specifies a negative 
value, then no size limit will be imposed. This is the default setting, 
MAX_PAGE_SIZE=-1. This option can be overridden on a per address basis 
with the PAGLEN address attribute. This option and the 
MAX_BLOCKS_PER_PAGE option are the two most critical options used by 
the pager channel. If the proper values are not used, the paging switch 
will reject the pages presented to it.
MAX_PAGES_PER_MESSAGE (integer)

Messages which require, after filtering with the PAGER table mappings, 
more pages than MAX_PAGES_PER_MESSAGE to transmit will be truncated to 
MAX_PAGES_PER_MESSAGE pages. The remaining pages are discarded. If 
MAX_PAGES_PER_MESSAGE specifies a negative value, then no pages will be 
discarded. This is the default setting, MAX_PAGES_PER_MESSAGE=-1. This 
option can be overridden on a per address basis with the MAXPAG address 
attribute.
PAGES_PER_CALL (integer)

This option specifies the maximum number of pages to be sent per phone 
call (dialup session) to the paging switch. When a message is broken 
into more pages than PAGES_PER_CALL, then several calls will be placed 
so as to deliver all of the pages. In each call, no more than 
PAGES_PER_CALL pages will be sent. If PAGES_PER_CALL specifies a 
negative value, then no limit will be imposed on the number of pages 
which can be sent during any one call. This is the default setting, 
PAGES_PER_CALL=-1.
PASSWORD (character string)

Most, if not all, paging switches use the password "000000". 
If you happen to be using a switch which uses a different password, 
then that password must be specified with this option.
RETURN_HEADERS (0 or 1)

By default, the header lines for the originating message are appended 
to the bottom of acknowledgement and status reports generated by the 
pager channel. The display of these headers can be suppressed by 
specifying RETURN_HEADERS=0 in the option file. RETURN_HEADERS=1 yields 
the default behavior.
RETURN_PAGES (0 or 1)

By default, actual pages sent are not included in acknowledgement or 
status reports generated by the pager channel. To include the text of 
these pages, specify RETURN_PAGES=1. RETURN_PAGES=0 yields the default 
behavior.
REVERSE_ORDER (0 or 1)

When a message is broken into multiple pages, page 1/n, page 2/n, ..., 
page n/n, the pages are sent in reverse order: page n/n is sent first, 
followed by pages n-1/n, ..., 2/n, 1/n. This is done because many 
pagers present the most recently received page first (i.e., 
some pagers store received pages in a last in, first out buffer). By 
specifying REVERSE_ORDER=0, multiple pages will be sent in the order 
page 1/n, 2/n, ..., n/n. The default setting is REVERSE_ORDER=1.
STRIP_8BIT_CHARS (0 or 1)

By default, characters with the eighth bit high are removed from the 
message. (They are removed prior to application of the PAGER mapping.) 
To preserve these characters,specify STRIP_8BIT_CHARS=0.
STRIP_CONTROL_CHARS (0 or 1)

By default, control characters (i.e., characters with ordinal 
values 0 - 8, 10 - 31, and 127) are removed from the message. (They are 
removed prior to application of the PAGER mapping.) Each tab is 
converted to a single space prior to application of the PAGER mapping. 
To preserve these characters, specify STRIP_CONTROL_CHARS=0.
TEXT_CASE (LOWER, MIXED, NUMERIC, UPPER)

By default, the cases (upper case, lower case) of characters in a 
message are left undisturbed.^a This default setting 
corresponds to TEXT_CASE=MIXED. By specifying either TEXT_CASE=LOWER or 
TEXT_CASE=UPPER, the message, after being filtered with the PAGER 
mapping table, will be converted entirely to lower or upper case 
characters. To only pass the numerals 0 through 9 to a pager, specify 
TEXT_CASE=NUMERIC.
USE_REPLY_TO (0 or 1)

One possible address to which acknowledgement and status report 
messages are sent is the original message's Reply-To: address. Under 
some circumstances it is never appropriate to use this address for this 
purpose. The USE_REPLY_TO option controls the use of the Reply-To: 
address for acknowledgements. A value of one (the default) causes the 
Reply-To: header to be used in the normal course of events. A value of 
zero inhibits use of the Reply-To: header for acknowledgements.






28.4.1.6 Use with PET Switches


When using a pager channel with a PET switch such as those used by 
Telecom Australia, the following options must be specified in 
the channel's option file



  
    
      

      BLOCK_ACK_TIMEOUT=10 
BLOCK_TX_RETRIES=5 
LOGIN_RETRIES=2 
LOGIN_ACK_TIMEOUT=10 
LOGOUT_ACK_TIMEOUT=10 
MAX_BLOCKS_PER_PAGE=1 
MAX_PAGE_SIZE=156 
PAGES_PER_CALL=6 
PASSWORD=passwd 




Failure to specify any or all of these options will render the pager 
channel incompliant with the PET specification (Telecom Australia 
document INB 028).


If you need to report problems to Telecom Australia, in so doing 
reference the University of Melbourne certification tests.



28.4.1.7 A Word on Determining Channel Options by Trial and          Error



You can have to determine by trial and error the appropriate value for 
the MAX_PAGE_SIZE channel option.


To determine MAX_PAGE_SIZE, just try sending a long message (~500 
bytes) and see what value you need for MAX_PAGE_SIZE to get the switch 
to accept the resulting pages. Be sure to enable master_debug for the 
channel so that you can see, blow by blow, the dialogue with the paging 
switch. Be warned that the paging switch can respond by ignoring 
data sent to it and timeout (e.g., respond with a message 
like "Too Slow - Good Bye"). If this should happen, then 
decrease MAX_PAGE_SIZE and try again.


With some paging switches you can find that you need to pause a second 
or two and possibly even send a carriage return before issuing the go 
command in your modem script. (See, e.g., Example 28-5.) 
With other switches, you can find that you cannot do this and must 
issue a go immediately after getting a CONNECT response from your 
modem. You'll have to experiment.






28.4.1.8 Frequent Delivery Retries with the BACKOFF Option
Normally, if a page cannot be delivered owing to a temporary error 
condition (e.g., busy signal when dialing the paging switch), 
another delivery attempt will not be attempted until the next periodic 
delivery job runs as described in Section 1.4. However, for urgent 
pages, a retry in minutes rather than tens of minutes or hours is 
desirable. Rather than setting PMDF's periodic delivery job interval to 
a small value and then adjusting the service period for each channel 
with the period channel keyword, the BACKOFF mapping table 
and BACKOFF channel option can be used. With this mapping table and 
option, you can schedule exactly when to run jobs to attempt redelivery 
of undeliverable pages (e.g., make attempts every minute for 
the first five minutes, then every five minutes for the next thirty 
minutes, etc.). See Section 26.6 for complete details on the 
use of the BACKOFF mapping table and BACKOFF channel option.



28.4.1.9 Using a Directory Channel to Simplify Pager          Addresses



A directory channel can be used to simplify pager addresses by creating 
a pseudodomain (e.g., pager.example.com) and aliases 
(e.g., user@pager.example.com) which translate to actual pager 
addresses (e.g., 
/id=1234/paglen=100/@pactel.pager.example.com). These aliases insulate 
users from needing to know the actual pager addresses for individual 
pagers.


Directory channels are described in Section 3.2.


As an example, assume that the two channels pager_pactel and pager_mci 
and associated rewrite rules for the domains pactel.pager.example.com 
and mci.pager.example.com as shown in Section 28.4.1.2 have been added to 
the PMDF configuration file. Then a directory channel for the domain 
pager.example.com can be set up as follows:


  Add to the PMDF configuration file the rewrite rule



  
    
      

      pager.example.com        $U%pager.example.com@DIRECTORY-DAEMON 




  
Add a directory channel to the configuration file:



  
    
      

      directory 
DIRECTORY-DAEMON 




  
Create the world readable directory 
  pmdf_root:[directories] (OpenVMS) or 
  /pmdf/directories (UNIX) with the OpenVMS command



  
    
      

      $ CREATE/DIR pmdf_root:[directories]/OWNER=[SYSTEM]




or the UNIX commands



  
    
      

      # mkdir -mu=rwx,go= /pmdf/directories
# chown pmdf /pmdf/directories




On NT, the PMDF installation created this directory for you 
automatically.
  
In that directory create a directory database named 
  pager$example$com.dat on OpenVMS or 
  pager.example.com on UNIX with the PMDF CRDB (OpenVMS) or 
  pmdf crdb (UNIX and NT) utility; e.g., on OpenVMS



  
    
      

      $ PMDF CRDB pager$example$com.txt pager$example$com.dat




or on UNIX



  
    
      

      # pmdf crdb pager$example$com.txt pager.example.com




or on NT



  
    
      

      C:\> pmdf crdb pager$example$com.txt pager.example.com




Here pager$example$com.txt is an input file with the 
format:



  
    
      

      alias_1      value_1
alias_2      value_2
.            .
.            .
.            .




with alias_1, alias_2, ... 
the names of aliases and value_1, 
value_2, ... the associated translation values. A 
sample pager$example$com.txt file is shown in 
Example 28-7.



  
    Example 28-7 Sample 
    pager$example$com.txt File
  


  
    
      

      andy        /id=1234/paglen=100/@pactel.pager.example.com 
sue         /id=1122/paglen=100/@pactel.pager.example.com 
joe         /id=4321/paglen=300/@mci.pager.example.com 
spare       /id=1111/paglen=100/@mci.pager.example.com 
support     /id=0101/@pactel.pager.example.com 






Of course, steps 2 and 3 should be omitted if a directory channel has 
previously been set up.









  
    
      Note 
        
        
        ⁴  Read  Section 28.4.1.7 before beginning 
        any trials. Note especially that some switches merely time out when 
        presented with too long of a page!
        ⁵  It will, however, be truncated if 
        its length exceeds the MAX_MESSAGE_SIZE or MAX_PAGES_PER_MESSAGE 
        parameters or any sizes specified with either the MSGLEN or MAXPAG 
        address attributes.
        ⁶  The mapping file is the file pointed 
        at by the PMDF_MAPPING_FILE logical on OpenVMS, or PMDF tailor file 
        option on UNIX, or Registry entry on NT, so usually 
        PMDF_TABLE:mappings. or /pmdf/table/mappings 
        or C:\pmdf\table\mappings, respectively. If this file does 
        not already exist, then create it now. This file must be world 
        readable. If you have a compiled configuration, then you must recompile 
        and re-install your configuration so that this file, and changes to it, 
        will be seen and used by PMDF. See Chapter 5 for complete details 
        on the mapping file.
        ⁷  When a modem pool is used on 
        OpenVMS, the device name given by a method in the 
        phone_list.dat file is a logical which translates to a 
        list of device names; e.g.,    
 $ 
        DEFINE/SYSTEM MODEMS 
        LTA1:,LTA2:,TXA6:,LTA133:
 
        ⁹  It's important to note that the 
        logout response is the critical response from the paging switch which 
        tells whether or not the pages were actually accepted. As such, the 
        lack of a logout response cannot be treated as a success since to do so 
        can result in lost pages.
        ^a  Note that site supplied PAGER table 
        entries can alter the case of characters in a message.
    
    
  








  
    Previous
    Next
    Contents
    Index

PMDF System Manager's Guide

28.4.1 Setting Up the Channel

ACK_SUCCESS (0 or 1)

ACKNOWLEDGEMENT (integer)

BACKOFF (integer >= 0)

BLOCK_ACK_TIMEOUT (integer > 0)

BLOCK_TX_RETRIES (integer > 0)

HEADER_STOP (character string)

ID_RX_RETRIES (integer > 0)

ID_RX_TIMEOUT (integer > 0)

LINE_STOP (character string)

LOGIN_RETRIES (integer > 0)

LOGIN_ACK_TIMEOUT (integer > 0)

LOGOUT_RETRIES (integer > 0)

LOGOUT_ACK_TIMEOUT (integer > 0)

MAX_BLOCKS_PER_PAGE (integer)

MAX_DELIVERY_ATTEMPTS (integer > 0)

MAX_MESSAGE_SIZE (integer)

MAX_PAGE_SIZE (integer)

MAX_PAGES_PER_MESSAGE (integer)

PAGES_PER_CALL (integer)

PASSWORD (character string)

RETURN_HEADERS (0 or 1)

RETURN_PAGES (0 or 1)

REVERSE_ORDER (0 or 1)

STRIP_8BIT_CHARS (0 or 1)

STRIP_CONTROL_CHARS (0 or 1)

TEXT_CASE (LOWER, MIXED, NUMERIC, UPPER)

USE_REPLY_TO (0 or 1)

4 Read Section 28.4.1.7 before beginning any trials. Note especially that some switches merely time out when presented with too long of a page!

5 It will, however, be truncated if its length exceeds the MAX_MESSAGE_SIZE or MAX_PAGES_PER_MESSAGE parameters or any sizes specified with either the MSGLEN or MAXPAG address attributes.

7 When a modem pool is used on OpenVMS, the device name given by a method in the phone_list.dat file is a logical which translates to a list of device names; e.g., $ DEFINE/SYSTEM MODEMS LTA1:,LTA2:,TXA6:,LTA133:

9 It's important to note that the logout response is the critical response from the paging switch which tells whether or not the pages were actually accepted. As such, the lack of a logout response cannot be treated as a success since to do so can result in lost pages.

a Note that site supplied PAGER table entries can alter the case of characters in a message.

⁴ Read Section 28.4.1.7 before beginning any trials. Note especially that some switches merely time out when presented with too long of a page!

⁵ It will, however, be truncated if its length exceeds the MAX_MESSAGE_SIZE or MAX_PAGES_PER_MESSAGE parameters or any sizes specified with either the MSGLEN or MAXPAG address attributes.

⁷ When a modem pool is used on OpenVMS, the device name given by a method in the `phone_list.dat` file is a logical which translates to a list of device names; e.g.,

$ DEFINE/SYSTEM MODEMS LTA1:,LTA2:,TXA6:,LTA133:

⁹ It's important to note that the logout response is the critical response from the paging switch which tells whether or not the pages were actually accepted. As such, the lack of a logout response cannot be treated as a success since to do so can result in lost pages.

^a Note that site supplied PAGER table entries can alter the case of characters in a message.