Paging – A Case Study (part 1)

Introduction

The purpose of this paper is to show how you can use a web site as a front end with Visual Objects behind the scenes to interface with Alpha pagers. We will cover some of the design decisions and the implementation details that went into the project. We will also cover the Visual Objects COM components and how they were set up.

We’ll do so in a serie of 2 articles, this being the first one.

In the Beginning

In the beginning there was alpha paging programs but with the advent of the internet, people were no longer happy with just an alpha paging program. They wanted to be able to use their paging software from anywhere in the company. Not just those machines that had the alpha software installed.

The Software

The software used for the project was as follows:

• Microsoft IIS 5.0 with ASP
• CA Visual Objects 2.7b
• PowerPage
• VO2ADO

The first two bullets are pretty self-explanatory. IIS is Microsoft’s web server . Visual Objects was used to write the middle layer of the system. PowerPage provided the TAP (pager protocol). Visual Objects also provided the COM layer that could be called from the ASP scripts running on the Web Server. VO2ADO was used for data access inside of the Visual Objects COM Components. Figure 1 shows the various components to the paging system in their final format. It also shows that the design allows other COM enabled languages to leverage the middle layer.

Fig. 1: Components of the paging system

Design

Web Pager was designed from the beginning as a web page using standard HTML with ASP extensions. The ASP added the capabilities of using the custom written components (in Visual Objects).

The PagerClient COM object was written in Visual Objects. It was the primary interface for the data, as well as the low level pager logic. It’s responsibilities included formatting the pager object and finally submitting the pager object to the queue for processing.

CLASS Pager INHERIT autoserver
  PROTECT access_number      AS STRING
  PROTECT pager_id           AS STRING
  PROTECT max_chars_per_blk  AS STRING
  PROTECT msg                AS STRING
  PROTECT cDataSource        AS STRING
  PROTECT aRecipient         AS ARRAY
  PROTECT oConn              AS ADOConnection
 
  DECLARE METHOD Access_Number
  DECLARE METHOD AddPagerId
  DECLARE METHOD addRecipient
  DECLARE METHOD formatDigits
  DECLARE METHOD getgroups
  DECLARE METHOD getusers
  DECLARE METHOD getGroupsandUsers
  DECLARE METHOD Max_Char
  DECLARE METHOD Message
  DECLARE METHOD PlaceOnpagerQue
  DECLARE METHOD quit
  DECLARE METHOD Send_Page
  DECLARE METHOD SQLSelect

The PagerQue COM object is also written in Visual Objects. It has the responsibility of keeping track on all pager objects that have been submitted. It is slightly different than the pagerClient as it compiled as an EXE instead of a DLL. It is an “out of proc” OLE server.

CLASS PagerQ INHERIT AutoServer
  // msg that gets sent to the PagerDial
  EXPORT aMessageSave  AS ARRAY
  // dialing return Code from PagerDial
  EXPORT nRetVal    AS LONG
  // return message from PagerDial
  EXPORT pszRetMsg    AS PSZ
  // message loop object
  EXPORT oAPPAbstract  AS ASPAPPABSTRACT
  // flag to terminate loop upon request
  EXPORT lKillNow    AS LOGIC

  DECLARE ACCESS empty
  DECLARE ACCESS QueueLength
 
  DECLARE METHOD finishedDial
  DECLARE METHOD GetNextPage
  DECLARE METHOD PostMessageOnqueue
  DECLARE METHOD quit
  DECLARE METHOD setup

Goals

The primary goal for the Web Pager was to create a simple system for the user.

1. It was to allow the user to select multiple people at the same time
2. Handle different paging systems.
3. Allow multiple people to be in the system at the same time.
4. Fast response time.
5. Accessible over the internet.

The phone book from our existing paging system handled goals 1 and 2. The web server approach handled goals 3 and 5. Goal number 4 was the problem.

Problems

Fast response time was a problem. When the user clicked Submit, I wanted a message to come back saying that the page had been submitted to the queue but I could not get a message back if someone else was already dialing out. The initial design had only 2 COM components; the PagerClient and the PagerQue. The speed problem resided in PagerQue. PagerQue could not process any incoming pager objects as long as it was dialing. This could represent a significant delay depending on how many users were included in a pager object. The end result was that pagerque was redesigned to be multi threaded.

Prototypes

Now it is time to talk prototypes. Sometimes it is easier to purchase technology than to develop it yourself. This has caused there to be a booming 3^rd party market for most programming languages. Powerpage is a 3^rd party DLL that can be integrated into most languages. It provides the low-level support for the TAP protocol. TAP is required for interfacing with Alpha Pagers. Powerpage is written in C++ and comes with prototypes for VB, Visual FoxPro, C, Delphi but not Visual Objects. However, writing the prototypes was pretty painless. Below are the functions that were used in the pager system:

_DLL FUNC PowerPage(pszPort AS PSZ, ;
  pszBaud AS PSZ, ;
  pszModemInit AS PSZ, pszModemdialStr AS PSZ, ;
  pszAccessNo AS PSZ, pszPagerNo AS PSZ, ;
  pszMaxChar AS PSZ, pszMsg AS PSZ, ;
  pszDebugFile AS PSZ, pszRetMsg AS PSZ, ;
  pszLine1 AS PSZ, pszLine2 AS PSZ, pszLine3 AS PSZ, ;
  pszMinimize AS PSZ) ;
  AS INT PASCAL:powerp32.PowerPage

_DLL FUNC Send_Alpha_Page(pszPort AS PSZ, ;
  pszBaud AS PSZ, ;
  pszModemInit AS PSZ, pszModemdialStr AS PSZ, ;
  pszAccessNo AS PSZ, pszPagerNo AS PSZ, ;
  pszMaxChar AS PSZ, pszMsg AS PSZ, ;
  pszDebugFile AS PSZ, pszRetMsg AS PSZ) ;
  AS INT PASCAL:powerp32.send_alpha_page

The difference between the 2 DLL calls is that Send_Alpha_Page does not let you control the 3 line message that is displayed while the page is being sent and PowerPage allows the programmer full control. It should also be mentioned that PowerPage is “Shareware”. The unregistered version only allows the Send_Alpha_Page call. But, if you want to create and run a guiless service on NT, it is advisable to register your copy where you can suppress the 3 line display.

How Does it Work?

Now that we have discussed the COM objects involved, the next logical step is to discuss how the system actually works. It will be broken down into the web page, the different COM objects, how they interact with each other, and the queing system.

Web Page

The web page is pretty basic HTML with a couple of functions. Below is a picture of the actual web screen.

Beep.asp

As you can see, the design is simple but functional. You have 2 listboxes, the first containing a list of available people or groups to select. The second contains a list of the people that you have selected. You use the middle buttons to move people from one list to another. There is a box to type your message into and finally a button to send the page.

The functions to move in and out of the listboxes are written in JScript. They also require Netscape 4.0 or higher or Internet Explorer 3.0 or higher as they are using both a caption and a return value (much like the CA-Visual Objects listbox control). Here is the source for the script section of beep.asp. It contains the in, out, and send functions.

To fill the listboxes, we call our custom component.

Referencing  the component

Before we can fill our listbox, we must first reference the component.

<%
dim oBeepClient
dim aList
set oBeepClient =
  Server.CreateObject( "PagerClient.Server")
%>

The “<% and %>” denote the beginning and ending of asp scripts. With this snippet, we first dim our variables, them the set is the line actually creates the reference.

Note: Once we have created the reference to the COM component, Visual Studio will use the type library from the COM component to enable IntelliSense. so it is easier to know the methods that the component contains.

Filling the Listbox

Now that we have a reference to our COM component, we can fill the listbox.

<%
aList = oBeepClient.getGroupsandUsers         
for i = 1 to ubound(aList)
%>
<%=aList(i,1)%>
<%
next
set oBeepClient = nothing
%>

The data from 2 tables are being combined into the available listbox, the Groups table and the Users table. Once the listbox is filled, both the COM component is set to nothing as we no longer need it.

The Send Button

The Send button onclick method invokes the send function. The purpose of the send function is to mark the selected property of each listbox item that was selected. Once all listbox items have been checked, it invokes the forms submit method, which links the beep.asp to beepsub.asp. Beepsub.asp is where all the hard work takes place.

Beepsub.asp

Beepsub is where all the real work takes place. Once again we must create a reference to the COM component. We must also figure out how many recipients were selected. This is where marking the recipient listbox selected property with true. Once the form is posted we can access another property called count to pick up the information needed.

RepCount = Request("Recipient").count

Sending the Page

The COM component does all of the hard work for use. There are only a few methods that we have to remember. They are

• AddRecipient: add a recipient from the recipient collection
• Message: message to send
• Send_Page: method that causes pager client to submit the request to the queue.

<%
dim RepCount   
dim oBeepClient
dim cMessage
dim S_OK
dim S_FALSE
S_OK = 0
S_FALSE = 1
set oBeepClient =
  Server.CreateObject( "PagerClient.Server")
if request("message") > "" then
  RepCount = Request("Recipient").count
  for i = 1 to RepCount
    Response.Write "Adding recipient "  &
      request("recipient") (i) & "
"
    oBeepClient.AddRecipient
      cint(Request("recipient") (i))
  next
  cMessage = request("message")
  Response.Write cMessage & "
"
  oBeepClient.Message cMessage
  response.write("Sending Page(s)
")
  hResult = oBeepClient.Send_Page
  if hResult = S_OK then
    response.write("Page placed in the Queue"&"
")
  else
    response.write("ERROR placing page in the queue")
  end if
else
  Response.Write("Error
Message cannot be blank")
end if
set oBeepClient = nothing
%>

You will notice that all access to the oBeepclient object are done with the “.” operator. If I were using  Visual Objects, the syntax would be “:” operator (i.e. oBeepClient:Send_Page instead of oBeepClient.Send_Page() ).

Moving Forward

The design of pagerclient makes it very easy to call from other languages. The sample code (included on the conference CD) contains the Visual Objects, Visubl Basic dotNet, ASP, and ASP.Net source. With each different GUI, the only thing that changes is the GUI and the exception handling. The calls to the COM object remain consistant throughout.

2B Continued …