PMDF System Manager's Guide
Previous Contents Index

26.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.

26.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:
  1. 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.
  2. 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.
  3. 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.4 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.

26.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.

26.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.5

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. 6 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:

  1. 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.

  2. 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 26-2. The entries in this example are explained below.

  1. 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.
  2. 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 ".
  3. 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" ".
  4. 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) ".
  5. 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" ".
  6. These four entries remove leading and trailing spaces from lines in the message header and body.
  7. These two entries reduce two spaces to a single space in lines of the message header and body.
  8. 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 26-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 26-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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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 29 and Chapter 30 for information on using these utilities.

26.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 24.3, and modem script files, described in Section 24.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 26-3, and an analogous sample UNIX phone_list.dat file is shown in Example 26-4.

Example 26-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 26-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:

  1. 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.
  2. 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.
  3. 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.
  4. Two identical entries (methods) are provided for the pager_mci channel.

The sample OpenVMS phone_list.dat file shown in Example 26-3 calls for two script files,
and
pmdf_root:[table.pager_mci]hayes_script.

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

When the same modem is used for each pager channel, as in Example 26-3 and Example 26-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 26-5. (A sample script for Racal-Vadic 212a modems is given in Example 26-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 26-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 26-5.

  1. Begin modem initialization.
  2. 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.
  3. Wait up to 10 seconds for the response "OK".
  4. End modem initialization.
  5. Pause one second and then dial the paging switch.
  6. Wait up to 30 seconds for the response "CONNECT".
  7. Pause one second and then send a carriage return. With some paging switches you can need to omit this xmit command.
  8. Connection has been made; allow the pager channel to take over.
  9. Pager channel is done; force the modem to hangup (H) and then reset the modem (Z).

The following notes apply to Example 26-6.

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

Example 26-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:7 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.

26.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 26.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.9 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.

26.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.

26.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 26-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.

26.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 24.6 for complete details on the use of the BACKOFF mapping table and BACKOFF channel option.

26.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 26.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:

  1. Add to the PMDF configuration file the rewrite rule 


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

  2. Add a directory channel to the configuration file: 


    directory 
DIRECTORY-DAEMON

  3. 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.

  4. 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 26-7.

    Example 26-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

4 Read Section 26.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.

6 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.

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.

Previous Next Contents Index