Power Page v1.05
Copyright by Ron Tanner, 1995 / All rights reserved.
Compuserve# 75170,776
Internet:   75170.776@compuserve.com

What is Power Page?
-------------------

Power Page is a Windows DLL that allows you to send Alpha-numeric
(full text) messages to pagers.  You can integrate the power of paging
into your application easily with a single function call from virtually
any language including:

     PowerBuilder
     Microsoft Access
     FoxPro 
     Dbase for Windows
     C / C++
     Paradox for Windows
     Visual Basic
     or any language that supports calling DLL functions.

The DLL function is defined as follows:
  send_alpha_page(port, baud, modem_init_str, modem_dial_str,
                  access_number, pager_id, max_chars_per_blk,
                  msg, debug_file, retmsg)


By making this simple call, you can send a message to anyone anywhere.

NOTE:  THE UNREGISTERED VERSION OF THIS SOFTWARE LIMITS THE MESSAGE
       TO 40 CHARACTERS.  THE REGISTERED VERSION ALLOWS FOR AN UNLIMITED
       MESSAGE SIZE.

You could use Power Page to:
     Send Time-critical information.
     Notify support technicians of an error or warning.
     Integrate messaging into your application.
     Send alerts or reminder notes. (Wake up calls)
     Send scheduling or meeting notices.
     Provide customers an easy way to ask technical support questions.
     Integrate with dispatch applications.

Power Page makes paging integration a cinch!


What is required?
-----------------

  Microsoft Windows 

  POWERPG.DLL installed in a directory on your path or the 
  \WINDOWS\SYSTEM directory.

  A modem and phone line connected to the computer (COM1 - COM9)

  In addition, you will need to know some information about the
  paging company and pager of the person you wish to send a message to.
  This is described later.


What does it cost?
------------------

This is not free software. The license allows you to use this software 
for evaluation purposes without charge for a period of 20 days.  If you 
use this  software after the 20 day evaluation period a registration fee 
is required. 

The cost of the software is $25 per license.  A license is for a single
computer per the licensing terms stated below.  Quantity discounts,
site licenses, or royalty free distribution licenses are also available
by contacting the author:

     Ron Tanner
     4955 E. Preserve Court
     Greenwood Village, CO  80121
     Phone: 303-689-0720
     Fax: 303-689-0730
     Compuserve# 75170,776

Source code and/or custom modifications are also available for an
additional fee.

To order, please see the file ORDER.TXT.


What is the difference between the registered and unregistered version?
-----------------------------------------------------------------------

The registered version offers the following enhancements:

1.  The 40 character message limitation has been lifted.  You can send
    a message up to 1000 characters long.  If the message is bigger
    than the maximum characters per block limit of your paging company, then
    Power Page will split the message up into multiple pages.

2.  You may send multiple messages per call.  For example, if you want
    to send a message to all the salesmen, this is possible now with
    one phone call.  You do this by passing several pager id's and several
    messages separated by the ^ (shift-6) character.  Please refer to 
    the registered version documentation for more information.

3.  There is another function call in the DLL called PowerPage() that
    has enhancements that allow you to control the pop up display.  You
    have 4 more parameters.  The first three, you may pass text to be
    displayed in the window (Rather than my annoying copyright).  The 
    last parameter lets you run the power page window minimized to an
    icon.  Please see the description of the PowerPage() in the registered
    documentation for more information.


How do I Install Power Page?
----------------------------

To install Power Page, simply copy the POWERPG.DLL file to the 
\WINDOWS\SYSTEM directory.  When you register, I will send you a 
new copy of the POWERPG.DLL file.


What do I need to know about the Pager?
---------------------------------------

The only thing you need to know about the pager is the pager phone
number or the Pager ID.  For example, I have a Motorola Advisor on
Interlink Communications of Colorado.  The phone number to my pager
is 8260590. (Do not pass a dash in the phone number when you call the 
function)

You will need to know the following about the paging company of the
pager. (In my case, the paging company is Interlink Communications):

1.  Access Number.  You will need to know the paging terminals 
    alphanumeric paging access telephone number.  This is the phone
    number of the modem at the paging company that will receive the
    message using the TAP protocol.  This number is the same for
    everybody that has a pager from that company.  In my case, Interlink's
    access phone number is 303-799-0055.  Many carriers will offer
    800 numbers - especially the nationwide guys like SkyPage or Mobilcomm.

2.  The baud rate.  You need to know the paging company's modem baud
    rate associated with the access number.  Believe it or not, most
    access modems still receive alphanumeric messages at 300 baud.
    Many have "upgraded" to 2400 baud.  It doesn't really matter that
    much what rate they have - pager messages tend to be relatively short
    so the speed of transfer is not really that important.

3.  Characters per message block.  Most paging carriers limit how many
    characters can be sent in one message.  A lot of carriers limit the
    message size to 80 characters.  Many others have expanded their 
    service to 230 characters per message.  The size of message really
    becomes a factor of the carrier.  You will need to find out this
    information or learn this through trial and error.

4.  Password?  Does your paging carrier require a password.  Most US 
    companies DO NOT.  In this case, Power Page sends six zeros as the
    password.  This is the standard way of doing it.  If do require a
    special password, see the note under "access number" below.

    REGISTERED USERS NOTE:
    You can send any size of message to Power Page.  Power Page
    will automatically split them up into several messages to fit the
    characters per message block.  Unregistered user's messages are
    chopped off at 40 characters.


What else do I need to know?
----------------------------

You will also need to know what port your modem is connected to.  You
may need to know what kind of modem is attached and perhaps custom
configure it by passing Power Page a modem initialization string.


What is the format of the call?
-------------------------------

The following describes the "send_alpha_page" function call:

int send_alpha_page(port,baud,modem_init_str,modem_dial_str,access_number,
                    pager_id,max_chars_per_blk,msg,debug_file,retmsg)

char *port;              /* Port that modem is connected              */
char *baud;              /* Baud rate of the paging company           */
char *modem_init_str;    /* Any special setup string your modem needs */
char *modem_dial_str;    /* Any special dial string your modem needs  */
char *access_number;     /* The paging company's alpha access phone # */
char *pager_id;          /* The pager phone number                    */
char *max_chars_per_blk; /* The paging company's character limit / msg*/
char *msg                /* The message to send to the pager          */
char *debug_file;        /* If you have problems give this a file name*/
char *retmsg;            /* The return message of how it went         */

Parameter                Description
-------------------------------------------------------------------------
port                     Specifies the port that your modem is connected 
                         to.  This can be "COM1" through "COM9"

baud                     Specifies the baud rate that the paging company's
                         alpha access port communicates at.  This can
                         be any of the following: "300", "1200", "2400",
                         "4800", "9600", "19200".  In very rare cases,
                         I have seen the paging terminal require N,8,1
                         rather than E,7,1. (Parity, data bits, stop bits)
                         If this is the case, preceed the baud rate
                         with an N. (ie "N300")

modem_init_str           Start off by leaving this string NULL.  If the 
                         value is NULL, Power Page will send your modem
                         an AT + a return.  The modem must then
                         respond with an "OK".  If the default doesn't
                         work, you will need to find the modem's manual
                         and figure out a string that will work.  Any
                         time you need a <cr> replace it with the tilde
                         character (~) (ie. AT&F~)  If you need to pause,
                         the hat character (^) will give you a 1 second
                         pause. (ie. AT&F~^^AT~)  The maximum length of
                         the modem initialization string is 80 characters.

modem_dial_str           Start off by leaving this string NULL.  If the
                         value is NULL, Power Page will send your modem 
                         an ATDT when it is ready to dial.  If only pulse
                         dialtone is available, you will have to pass
                         "ATDP" in this parameter.


access_number            This is the telephone number for the paging
                         company's modem that receives alphanumeric
                         messages.  THIS IS DIFFERENT FROM THE PAGER
                         TELEPHONE NUMBER.  You may include dashes and
                         comma's like any other modem phone number. 
                         (A comma usually pauses 2 seconds - ie 9,444-4444)
                         (See above for more information)

                         Note: For those paging carriers that require
                         a specific password, this is where you put it.
                         After the access phone number place the ^ hat
                         character (shift 6) and then place the password.
                         For example, if the paging carrier required the
                         password of L23456, then the access_number string
                         would be: access_number$="9,444-4444^L23456"

pager_id                 This is usually the pager's phone number or 
                         PIN number.  DO NOT INCLUDE ANY DASHES in this
                         number.

max_chars_per_blk        This is the number of characters the paging 
                         company allows per message block.  This number
                         varies widely from company to company.  Some
                         are as small as 60 characters and some are as
                         big as 1000 characters.  The norms seem to be
                         80 and 230 characters per block.  If the message
                         you pass is bigger than the character per block
                         limitation, Power Page automatically splits your
                         message up into multiple blocks, so the recipient 
                         gets the entire message. (Registered version only)
                         However, he/she does get a different page for 
                         each block. (See above for more information)

msg                      This is the message that goes to the pager.  The
                         un-registered version truncates this message to
                         40 characters.

debug_file               Normally, this parameter is NULL.  In the event
                         you are having trouble successfully completing 
                         a page, specify a valid file name for this
                         parameter.  Power Page will append to the end
                         of the file some information on where the 
                         problem is.  This file will also help me to
                         determine where the problem is if you want to 
                         E-Mail me the file.

retmsg                   This is a string returned by Power Page telling 
                         you what happened during the call.  See below
                         for a complete description of the possible values
                         in this string.  Make sure you pre-allocate 100
                         bytes for this string BEFORE you make the function
                         call.


RETURNS: 0 = Successful
         1 = Failure

The possible values for the retmsg parameters are as follows:

With Return Code of 0: (Success)
     Successful.
     Operator interrupted session.

With Return Code of 1: (Failure)
     Could not create window.
     Could not create windows timer.
     OpenComm Error - The device identifier is invalid or unsupported.
     OpenComm Error - The devices baud rate is unsupported.
     OpenComm Error - Byte size error.
     OpenComm Error - The default parameters are in error.
     OpenComm Error - The hardware is not available
          (is locked by another device).
     OpenComm Error - The function cannot allocate memory for the COM queues.
     OpenComm Error - The device is not open.
     OpenComm Error - The COM port is already open.
     OpenComm Error - Unknown error.
     OpenComm Error - Error on BuildCommDCB command.
     OpenComm Error - Error on SetCommState command.
     CloseComm Error.
     Your modem on COMx did not respond to the following
          init string: <passed init string>
     Timeout waiting for CONNECTion.
     Lost Connection during call.
     Timeout waiting for ID=.
     Timeout waiting for goahead string.
     Lost Connection during call.
     Block was NAK'd five times.
     Invalid or Inactive Pager ID sent to paging company.



Example calls
-------------

  The setup and call from your favorite language would be similar to
  how you would make a call to a Windows API (SDK) function.  Some
  specific examples follow:


  PowerBuilder Example
  --------------------
  
  Declare a Global External function as follows:
      FUNCTION int send_alpha_page(ref string port, ref string baud, &
               ref string modem_init_str, ref string modem_dial_str, &
               ref string access_number, ref string pager_id, &
               ref string max_chars_per_blk, ref string msg, &
               ref string debug_file, ref char retmsg[100]) &
               LIBRARY "POWERPG.DLL"

  A sample script to setup and send a page:
     int rc
     char retmsg[100]
     string port,baud,modem_init_str,modem_dial_str
     string access_number,pager_id,max_chars_per_blk,msg,debug_file

     port="COM1"
     baud="300"
     modem_init_str=""
     modem_dial_str=""
     access_number="799-0055"
     pager_id="8260590"
     max_chars_per_blk="80"
     msg="Hello, This is a test page."
     debug_file=""

     rc=send_alpha_page(port,baud,modem_init_str,modem_dial_str, &
          access_number,pager_id,max_chars_per_blk,msg,debug_file,retmsg)

     MessageBox("Power Page Results",retmsg)

  
  VISUAL BASIC or Microsoft Access Example
  ----------------------------------------

  In the declarations area add the following line (put on one line):

Declare Function send_alpha_page Lib "POWERPG.DLL" (ByVal port$, ByVal baud$,
        ByVal modem_init_str$, ByVal modem_dial_str$, ByVal access_number$, ByVal pager_id$,
        ByVal max_chars_per_blk$, ByVal msg$, ByVal debug_file$, ByVal retmsg$) As Integer


  A Sample script to setup and send a page:

port$ = "COM1"
baud$ = "300"
modem_init_str$ = ""
modem_dial_str$ = ""
access_number$ = "7990055"
pager_id$ = "8260590"
max_chars_per_blk$ = "80"
msg$ = "Howdy partner."
debug_file$ = ""
retmsg$ = String$(100, 0)

Rem -- Put the following on one line:
ret% = send_alpha_page(port$, baud$, modem_init_str$, modem_dial_str$, access_number$,
        pager_id$, max_chars_per_blk$, msg$, debug_file$, retmsg$)

MsgBox retmsg$


  FoxPro for Windows Examples
  ---------------------------

  FoxPro does not allow the 10 required parameters to be passed to a DLL.  
  Therefore, an alternative function has been provided in the DLL to 
  combine 9 of the parameters into one separated by the verticle bar (|).
  The function is called PowerPageCombined(char *parms, char *retmsg)

  The following example may explain:

* For testing purposes, make sure you don't reload FOXTOOLS a million times.
SET LIBRARY TO
* Now load it back in.
SET LIBRARY TO d:\vfp\fOXTOOLS.FLL

* Register the PowerPage function via FOXTOOLS
RN = RegFn("PowerPageCombined","@C@C","I","POWERPG.DLL")

* Initialize the variables
retmsg=SPACE(100)
parms="COM1|300|AT&F~||7990055|8260590|80|Sample Page|test.txt|"

*port|baud|initstring|dialstring|accessnumber|pagerId|maxchars|msg|debugfile

result = CallFn(RN,@parms, @retmsg)
?retmsg


  C or C++ Example
  ----------------

int sample_function(void)
{
   char retmsg[100];
   HINSTANCE lh;
   int ret;
   BOOL (FAR pascal *lpfn) (char far *,char far *,char far *,char far *,
                            char far *,char far *,char far *,char far *,
                            char far *, char far *);

   lh=LoadLibrary("POWERPG.DLL");
   if(lh <= HINSTANCE_ERROR) {
      MessageBox(0,"Could Not Load library","Return Status",MB_OK);
      return(0);
   }
   lpfn=(BOOL (FAR pascal *)
        (char far *,char far *,char far *,char far *, char far *,
         char far *,char far *,char far *,char far *, char far *))
        (GetProcAddress(lh,"send_alpha_page"));

   if(lpfn == 0) {
      MessageBox(0,"Could Not Load address","Return Status",MB_OK);
      return(0);
   }

   ret=(*lpfn)("COM1","300","","","7990055","8260590","80",
               "Hello, Test Page","",retmsg);

   FreeLibrary(lh);
   MessageBox(0,retmsg,"Return Status",MB_OK);
   return(0);
}


  Paradox for Windows Example
  ---------------------------

  Declare the following in the Uses() method of the form object
  and place the following code in it:

Uses POWERPG
   send_alpha_page(CPTR port, CPTR baud, CPTR modem_init_str, 
                   CPTR modem_dial_str, CPTR access_number, CPTR pager_id,
                   CPTR max_chars_per_blk, CPTR msg CPTR debug_file, 
                   CPTR retmsg) CWORD
EndUses

var
   port String
   baud String
   modem_init_str String
   modem_dial_str String
   access_number String
   pager_id String
   max_chars_per_blk String
   msg String
   debug_file String
   retmsg String
   retVal SmallInt
endvar

port = "COM1"
baud = "300"
modem_init_str = ""
modem_dial_str = ""
access_number = "7990055"
pager_id = "8260590"
max_chars_per_blk = "80"
msg = "Howdy partner."
debug_file = ""
retmsg = Space(100)

retval=send_alpha_page(port, baud, modem_init_str, modem_dial_str,
        access_number,pager_id, max_chars_per_blk, msg, debug_file, retmsg)

MsgInfo("Results",retmsg)


  Objectview Example
  ------------------

DECLARE FUNCTION send_alpha_page%(@port$,@baud$,@modem_init_str$, 
                 @modem_dial_str$,@access_number$,@pager_id$,
                 @max_chars_per_blk$,@msg$,@debug_file$, 
                 @retmsg$) LIB "POWERPG.DLL send_alpha_page"

port$ = "COM1"
baud$ = "300"
modem_init_str$ = ""
modem_dial_str$ = ""
access_number$ = "7990055"
pager_id$ = "8260590"
max_chars_per_blk$ = "80"
msg$ = "Howdy partner."
debug_file$ = ""
FOR I% = 1 to 100
   retmsg$=retmsg$ + " "
NEXT I

ret% = send_alpha_page(port$, baud$, modem_init_str$, modem_dial_str$, access_number$,
        pager_id$, max_chars_per_blk$, msg$, debug_file$, retmsg$)

MESSAGEBOX(retmsg$,"Result",MB_OK)

  
  Dbase for Windows Example
  -------------------------

  EXTERN CINT send_alpha_page(CPTR *,CPTR *,CPTR *,CPTR *,CPTR *,
                              CPTR *,CPTR *,CPTR *,CPTR *,CPTR *)
  

* Initialize variables
port="COM1"
baud="300"
modem_init_str=""
modem_dial_str=""
access_number="7990055"
pager_id="8260590"
max_chars_per_blk="80"
msg="Howdy partner."
debug_file=""
retmsg=SPACE(100)

retval=send_alpha_page(port, baud, modem_init_str, modem_dial_str,
        access_number,pager_id, max_chars_per_blk, msg, debug_file, retmsg)

?retmsg



LEGAL MATTERS
-------------

 Of course the usual disclaimers still apply.  We are not 
 responsible for anything at all.  Nothing.  Even if we are held
 responsible, the limit of our liability is the licensing fees
 you paid. 


SHAREWARE LICENSE - END USER
----------------------------

 The Power Page software is not and has never been public
 domain software, nor is it free software. 

 Non-licensed users are granted a limited license to use our
 software on a 20-day trial basis for the purpose of determining
 whether the software is suitable for their needs.  Any use
 of our software, except for the initial 20-day trial, requires
 registration.  The use of unlicensed copies of our software,
 outside of the initial 20-day trial, by any person, business,
 corporation, government agency or any other entity is
 strictly prohibited. 


 SHAREWARE LICENSE - FOR DISTRIBUTION OF SHAREWARE FILES,
 USER GROUPS, BBS's, ONLINE SERVICES, SHAREWARE VENDORS, and
 OTHERS

 A limited license is granted to copy and distribute our
 shareware software only for the trial use of others, subject to
 the following limitations:

  1)    The software must be copied in unmodified form, complete
        with the file containing this license information.

  2)    The full machine-readable documentation must be included
        with each copy.

  3)    Our software may not be distributed in conjunction with
        any other product with out a specific license to do so
        from Ron Tanner.

  4)    Vending of our software products in retail stores (by
        "shareware rack vendors") is specifically prohibited
        without prior written authorization.

  5)    No fee, charge, or other compensation may be requested
        or accepted, except as authorized below:

     A) Non-profit user groups may distribute copies of the our
        products to their members, subject to the above
        conditions, without specific permission.  Non-profit
        groups may collect a disk duplication fee not to exceed
        five dollars.

     B) Operators of electronic bulletin board systems (sysops)
        may make our products available for downloading only as
        long as the above conditions are met.  An overall or
        time-dependent charge for the use of the bulletin board
        system is permitted as long as there is not a specific
        charge for the download of our software.

     C) Mail-order vendors of shareware software
        may distribute our products, subject to the
        above conditions, without specific permission.
        Vendors may charge a disk duplication and handling
        fee, which, when pro-rated to each individual product,
        may not exceed eight dollars.


 LICENSED COPIES OF OUR SOFTWARE ARE GOVERNED BY THE FOLLOWING:
---------------------------------------------------------------

 THIS SOFTWARE IS NOT FOR SALE: The software  is 
 subject to the following license terms and conditions.  

 SOFTWARE LICENSE granted, when required fees paid,
 by Ron Tanner, with its mailing address at 4955 E. Preserve Court,
 Greenwood Village, CO  80121.  The software contained in this 
 package is licensed to you as the end user.  It is not sold.

 LICENSE:
         1.0  The software contained in this package 
 (hereafter referred to as "the Software") is copyrighted 
 material owned by Ron Tanner.  Payment of the single copy
 license fee authorizes one named person to use the Software
 on one computer provided this copyright is not violated and
 provided the rules outlined herein are observed.

         1.1  One person may use the Software on any 
 single computer. This license can be transferred only once 
 in any twenty-four hour period. You must pay for additional 
 copies of the Software if more than one person uses it at 
 one time, or if the Software is used on two or more 
 computers. Neither concurrent use on two or more 
 computers, nor use by more than a single individual on a 
 network is permitted without authorization and payment of 
 other license fees.

         1.2  You may make copies of the software for 
 backup purposes, as long as all such copies, along with 
 the original, are kept in your possession or control.

         1.3  You may not make any changes or modifications to
 the Software, including, but not limited to, decompiling,
 disassembling, or otherwise reverse engineering it.  You may
 not rent or lease it to others.  You may not use it on a
 computer network if more than one user can use it on more than
 one computer during any one twenty-four hour span of time.


  LIMITED WARRANTY
------------------

  Ron Tanner guarantees your satisfaction with this
  product for a period of 90 days from the date of original
  purchase.  If you are unsatisfied with the product
  within that time period, return the package in salable
  condition to the place of purchase for a full refund.

  Ron Tanner warrants that all disks provided are
  free from defects in material and workmanship, assuming
  normal use, for a period of 90 days from the date of
  purchase.

  Ron Tanner warrants that the program will perform
  in substantial compliance with the documentation supplied
  with the software product.  If a significant defect in
  the product is found, the purchaser may return the
  product for a refund.  In no event will such a refund
  exceed the purchase price of the product.


  EXCEPT AS PROVIDED ABOVE, RON TANNER DISCLAIMS ALL
  WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT
  LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY AND
  FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE
  PRODUCT.  SHOULD THE PROGRAM PROVE DEFECTIVE, THE
  PURCHASER ASSUMES THE RISK OF PAYING THE ENTIRE COST OF
  ALL NECESSARY SERVICING, REPAIR, OR CORRECTION AND ANY
  INCIDENTAL OR CONSEQUENTIAL DAMAGES.  IN NO EVENT WILL
  RON TANNER BE LIABLE FOR ANY DAMAGES WHATSOEVER
  (INCLUDING WITHOUT LIMITATION DAMAGES FOR LOSS OF
  BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
  INFORMATION AND THE LIKE) ARISING OUT OF THE USE OR THE
  INABILITY TO USE THIS PRODUCT EVEN IF RON TANNER
  HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

  Use of this product for any period of time constitutes
  your acceptance of this agreement and subjects you to its
  contents.


  TRADEMARKS
------------

  Microsoft and MS-DOS are registered trademarks of
  Microsoft Corporation.
  Windows is a trademark of Microsoft Corporation.

