Winsock Database Request System Documentation[1]
Table of Contents
Table of Contents......
Overview......
Introduction......
Document Use......
System Design......
Description......
System Design Diagram......
Directory Structure......
Database Request Server......
Description/Overview......
Important Procedures......
skServer_ConnectionRequest......
skServer_DataArrival......
FindServerName......
Appearance......
Sample Topic Server......
Description/Overview......
Important Procedures......
GetRecordset......
ParseSearchString......
Appearance......
Client ActiveX Control......
Description/Overview......
Important Procedures......
GetRecordset......
ResultsArrival......
Appearance......
Sample Database Request Client......
Description/Overview......
Important Procedures......
mnuFileSendData_Click......
Appearance......
Messaging......
Description/Overview......
Language Specifications......
Preliminary Implementation......
XML as a Standard......
Overview
Introduction
The Winsock Database Request System is a prototype system that is used to demonstrate the concept of distributed communication. The communication, in this context, is used to handle client requests for data on a remote server. The role of the server is to determine which database system the client is requesting the data from, and based upon this, to route the request and resulting output to and from the correct database server.
It is to be noted that the primary concept of interest in this system is not the data being requested, processed, or sent; rather, this data transfer is used as a pretext for demonstrating the communication system itself. The communication system utilizes a component called the “Winsock Control”. This control enables the programmer to communicate via TCP/IP protocols, through “ports”, with internet-ready computers. In any communication, two Winsock Controls are needed: one in the requesting application, or “client”, and one in the responding application, or “server”. In a nutshell, the client submits a connection request, and the server either obliges with an “Accept” message or refuses with a “Deny” message. Once the “Accept” message has been received by the client, the applications have established a working connection. This connection utilizes the typical TCP/IP standards and is therefore relatively robust.
The advantages of this communication method are that (1) thousands of connections can be simultaneously sustained by the server (provided that ample bandwidth and processing power are available), and (2) that any Windows 95 or Windows NT 3.5/4.0 computer on the internet can use the software as soon as it is installed. The primary disadvantage is that the only method of communication between applications is text-based messaging, so additional processing is required on either end to accomplish the tasks that the communication intends.
Document Use
This documentation was created both as a programmer’s guide to the system, and as a guide to understanding the concepts being demonstrated by the system. As such, this document should be kept up-to-date when changes to either the system itself or the setup/installation program have occurred.
System Design
Description
The Winsock Database Request System, as previously mentioned, is a prototype system that is used to demonstrate the power of Winsock TCP/IP communication. In order to do so, however, it is necessary to use the communication system to facilitate another task; preferably, one which requires or would benefit from such a distributed communication system. The task chosen for the purposes of this prototype was the following: allowing client applications to send a data request (à la search engines) to the system server, which would then process the request and return a corresponding result set[2].
The figure on the following page gives a graphical interpretation of the system. The important figures in the graph are: (1) the Client Application, (2) the Server Application, and (3) the Topic Servers. The method by which the system executes is as follows.
First, the Client Application is manipulated by the end user, in some fashion, to generate a request for a set of records in a remote database. (For example, the user may be using the Client Application as a search engine for the documents categorized in the remote database). The Client Application submits a request to the Server Application of the following form:
“<Topic>!<RequestInfo>”
Where “<Topic>” is the name of the topic in question (more on this later), and “<RequestInfo>” is the information relevant to the request (i.e., the search phrase used to mine the document set in the database).
Once the server receives the request, it searches in the Server Database for the name of the ActiveX EXE object (Topic Server) which can process that topic. (In the case of this prototype, the Topic is called “Sample”; this Topic will be discussed in more detail in the Section titled “Sample Topic Server.”) Once the server has found the correct object, it loads that object (as an out-of-process server) and sends the relevant information to the object. The object then executes its algorithm against the Topic Database, and returns the results to the Server Application. These results are then sent to the Client Application.
Once the result set has been sent to the Client Application, the Client Application terminates its connection with the Server Application.
Winsock Database Request System
System Design Diagram
1
Directory Structure
Figure 2
Directory Structure of WDRS Development Files
The following diagram displays the directory structure of the files used in the Winsock Database Request System. Currently, these files reside in P:\Users\Tate\. Each directory is documented:
Winsock: This is the main directory for the development files used in the Winsock Database Request System. The project files for the Database Request Server are stored in the directory (Project file: Server.vbp).
Winsock\Documentation: This directory contains the documentation files used for the system (including, and primarily, this document).
Winsock\Drc_OCX: This directory contains the development files used to create DBReqClient.OCX, the ActiveX component used in the client application to manage and encapsulate communication with the Database Request Server.
Winsock\Install: This directory contains the subdirectories \Client, \OCX, and \Server. Each subdirectory contains the files needed to install the client application, DBReqClient.OCX (for development, not just run-time, use), and the server application on new machines (respectively). Each directory contains a file named Setup.exe which, when executed, will install the files in the directory on the local machine.
Winsock\Sample: This directory contains the development files for the Sample Client Application discussed below.
Winsock\Sample\Database: This directory contains the database used by the Sample Topic Server (discussed below). The Sample Topic Server responds to requests for the “Sample” Topic by querying the database found at Winsock\Sample\Database\books.mdb.
Winsock\Servdb: This directory contains the Server Database, which the Database Request Server uses to locate information on Topic Servers.
Winsock\Server: This directory contains the development files for the Sample Topic Server, as discussed below.
Database Request Server
Description/Overview
The Database Request Server acts as a relay channel in the system; it manages both the communication with the client applications and the launching and execution of the topic servers.
The Database Request Server contains a Winsock Control (actually, a Winsock Control Array), named skServer, whose base control (skServer(0)) listens on port 1001 of the server computer[3]. The base control then creates a new instance n in the control array (i.e., skServer(n)) which is used to manage the nth client connection. skServer(n) then accepts the request from the client, and the connection is established.
Once client n sends its data request (again, in the form “<Topic>!<RequestInfo>”), the server locates the proper ActiveX EXE (Topic Server) to manage <Topic>. It sends the data in <RequestInfo> to the Topic Server. Once the Topic Server has completed processing the request, the Database Request Server receives the output (result set) from the Topic Server and transmits that output to client n via its socket connection through skServer(n). While the task of communication is completed at this point, the Database Request Server does not yet close the connection. As of the time of this writing, the client application manages closing the socket connection upon receipt of the output.
Important Procedures
- Private Sub skServer_ConnectionRequest(Index As Integer, ByVal requestID As Long)
- Private Sub skServer_DataArrival(Index As Integer, ByVal bytesTotal As Long)
- Function FindServerName(ByVal strTopic$, strServerName$, strDBLoc$) As Boolean
skServer_ConnectionRequest
Arguments:
Index: The item in the skServer control array that is receiving the Connection Request (always 0 in this procedure)
requestID: A long integer which uniquely identifies the request instance.
Description:
This procedure manages the acceptance of a connection request from a TCP/IP client. It increments the global variable g_lNum, and uses g_lNum to load a new instance within the skServer control array (this allows the single skServer control to handle multiple connections at a time; each instance skServer(x) manages the xth client connection.
skServer_DataArrival
Arguments:
Index: The item in the skServer control array that is receiving the DataArrival event.
bytesTotal: A long integer which represents the total number of bytes received.
Description:
This procedure manages the process of (1) receiving a client data request, (2) finding the appropriate Topic Server, (3) generating that Topic Server object and communicating with it, and (4) sending the results from the Topic Server back to the client.
FindServerName
Arguments:
strTopic: The name of the Topic requested by the client application that FindServerName is trying to find in the Server Database.
strServerName: The name of the Topic Server as called through the Windows API with CreateObject (e.g., “SampleDLL.BookList” for the Sample Topic Server). This string will be filled by FindServerName
strDBLoc: The file location of the database that the Topic Server will be querying. This string will be filled by FindServerName
Description:
This procedure manages the process of locating the two aforementioned pieces of information for the requested Topic. FindServerName returns “False” if it cannot locate the requested Topic in the “DLL_List” table of the Server Database.
Appearance
The Database Request Server is not meant to be attractive; it is merely functional. The primary items in the interface to note are (1) the lstCommInfo ListBox (at the top) and (2) the txtSentData TextBox at the bottom of the form. The lstCommInfo ListBox lists all client connections, data receipts, and client closing connections. txtSentData merely lists the last data request received by the server from a client application.
Figure 3
Database Request Server
Sample Topic Server
Description/Overview
The Sample Topic Server is included as a component in the Winsock Database Request System for strictly illustrative purposes. The idea behind the Topic Server is simple: send the Topic Server a search string, and have it return a series of records in a given database that correspond to that search string.
In this application, the Sample Topic Server queries a database which contains a list of technical book titles. It supports multiple term searches (of the form “A and B” or “A or B or C”, but not “A and B or C”). This application was chosen for two reasons. First, it illustrates at least somewhat nontrivial use of this messaging system: the Database Request Server calls upon a resource to perform a nontrivial task, the output of which will be returned to the client. Second, it is similar to other research work being done involving information search and Information Retrieval, and the hope is that at least some of the work can be reused in that project.
The Sample Topic Server is an ActiveX EXE object that can be loaded through the Windows API in Visual Basic. The built-in method, called “CreateObject”, allows the programmer to create and load a Windows component (either an in-process DLL or out-of-process EXE) by simply passing a string argument corresponding to that object. The Sample Topic Server is included in the “SampleDLL” development project; the specific name of its class in that project is called “BookList”. Therefore, the relevant string to use in “CreateObject” for this object is “SampleDLL.Booklist”. The Topic Server was chosen to be an ActiveX EXE instead of an ActiveX DLL so that it could be loaded out-of-process for multithreading purposes. (NB: You can envision a Database Request Server, when fully active, managing fifty connections with Topic Servers at one time.) However, due to time limitations, the system is not multithreading; doing so would require implementing callback procedures which seemed, initially, to be out of the scope of this project.
Important Procedures
- Function GetRecordset(strDatabase$, strTopicInfo$, strCreateText$) As Boolean
- Function ParseSearchString(strSearchString As String) As Boolean
GetRecordset
Arguments:
strDatabase: This string tells the Topic Server the file location of the database to query.
strTopicInfo: This is the actual search string, e.g., “Apple OR Banana”.
strCreateText: The results of the Topic Server query. This string will be filled by GetRecordset.
Description:
This procedure manages the entire task of the Topic Server; it is the Database Request Server’s “entry point”. The Database Request Server invokes the GetRecordset method in order to get the results from the Topic Server to be returned to the client application.
GetRecordset begins by calling ParseSearchString (described below), which manages the process of parsing the search string into search terms. It then generates an SQL query to return the records that fit the search string. After the database enginge executes the query and returns the results, GetRecordset reads the records in the set into strCreateText, the string which will be passed back to the client. GetRecordset lists the field names first, then each of the records, in the string. All fields within a record are separated by a Tab character (ASCII character 9), and all records are separated by a Carriage Return/Line Feed sequence.
GetRecordset returns a “False” if and only if an error occurs in the process of generating the results set.
ParseSearchString
Arguments:
strSearchString: The string that ParseSearchString will parse into individual search terms.
Description:
This procedure simply parses the search string passed through the Database Request Server from the client application. ParseSearchString fills the module-level array m_strarySearchTerms() with the individual search terms in the string. It also sets the module-level Boolean variable m_blnAndQuery to “True” if the query is disjunctive (e.g., “A and B”, and to false if it is conjunctive (e.g., “A or B”.) While ParseSearchString can manage as many as ten search terms, it cannot handle complex Boolean search phrases, such as “A and (B or C)”.
Appearance
Because the Sample Topic Server is an ActiveX EXE, it has no visual component. Therefore, when the Database Request Client loads it, the Topic Server simply spawns a new process during its execution.
Client ActiveX Control
Description/Overview
The Client ActiveX Control is an ActiveX component that is to be incorporated into any client application built for the Winsock Database Request System. It encapsulates most of the work necessary to (1) carry out a Winsock TCP/IP connection with the Database Request Server and (2) in generating messages that the server can understand.
In this system, therefore, the ActiveX Control plays an important role. It facilitates the creation of new, different client applications while encouraging reuse. In this system, the Sample Database Request Client, which utilizes this ActiveX control, is very simple to manipulate. In addition, this component can be used in new Visual Basic development projects, as well as C++ projects.
Most of the important code and features of the control are related to setting, receiving, and sending property values – i.e., in communicating with the client application. Therefore, for a full understanding of all of the functions the control performs, it is necessary to consult the development project itself. However, this documentation will serve to highlight its important functions.
Important Procedures
- Public Sub SendRequest(strTopicInfo$)
- Public Event ResultsArrival(strResults$)
GetRecordset
Arguments:
strTopicInfo: This is the search string that the client application is transmitting, e.g., “Apple OR Banana”.
Description:
This procedure serves as the main Public procedure for the control. The client application calls this procedure when it is prepared to send a data request.
The control then manages the process of (1) checking the host information (in order to locate the Database Request Server), (2) connecting to the server, and (3) sending the data request. The procedure does this by calling the private procedures CheckHostInformation, CheckConnectionStatus, and SendTopicData, respectively.
ResultsArrival
Arguments:
strResults: The string corresponding to the result set sent by the Database Request Server.
Description:
This event is raised in the ActiveX control when the control has finished receiving the result set from the Database Request Server. This event can be captured by the client application, which is in charge of determining what to do with the results when they arrive.
Appearance
The Client ActiveX Control’s appearance can be divided into two separate modes: run-time and design-time. At run-time, the control has no visual component, as it is not necessary for the control to interact with the end user directly. However, during design time, the control should appear as a non-sizeable bitmap on the development form, as shown below.
Figure 4
OCX Bitmap in design time
Sample Database Request Client
Description/Overview
The Sample Database Request Client is an extremely simple application used for illustrative purposes. For the most part, the code in the application is used either for controlling the user interface of the application or for interacting with the Client ActiveX Control.