HP 3000 Manuals HP 3000 Manuals
HP ALLBASE/SQL PC API
by Anjali P. Mulgaonkar
Commercial Systems Division
An overview of HP ALLBASE/SQL PC API is discussed in the related article
in the "Database Tools" section in this ^fsCommunicator. This article
provides more technical details about the HP ALLBASE/SQL PC environment,
PC client environment, HP 3000 server environment, error handling, and
support tools.
HP ALLBASE/SQL PC API ENVIRONMENT
The figure on the following page shows the detailed client and server
environment.
PC CLIENT ENVIRONMENT
The supported client platforms are Intel-based 80286, 80386 or 80486 PCs
with graphics capability. Other requirements on the PC are a LAN card, a
mouse and at least 4MB of memory. The HP ALLBASE/SQL PC API software
resides entirely on the PC and requires 1 MB of disk storage. Additional
software required for the client PC is as follows:
* MS-DOS 3.3 or later
* MW Windows 3.00a or later (standard or enhanced mode)
* Networking software depending on the protocol chosen
* TCP/IP protocol:
HP NS 2.1/MS-DOS or later
or
HP ARPA Services 2.1/MS-DOS or later
NOTE: Either HP LAN Manager 1.1 or later, or NetWare client
maybe installed with either of the above. Be sure to order the
appropriate versions of HP NS / HP ARPA Services for the networking
platform (HP LAN Manager or Netware) being chosen.
* SPX/IPX protocol:
NetWare client
NOTE: Can support TCP/IP concurrently. See the note above.
Besides this software, the 4GL query and application development tools,
and their generated applications reside on the client PC. The 4GL tools
and applications use two types of function calls:
* PC based function calls:
These functions, relating to building a user interface, data
editing, window management and so on, are handled entirely by the
client PC. These require no translation by HP ALLBASE/SQL PC API.
CLIENT PC
+--+-------------------------------------------------+
| | |
| | +--------------------------------------+ |
| | | 4GL tool or application or scriptor | |
| | +--------------------------------------+ |
| | | Function Call |
Filter <------------------------| Interface |
Capture | | V |
Point | | +- +---------------------------+ |
| | | | Gupta C/API | sqlapiw.dll |
| | | +----+------------------+---+ |
| | | | ALLBASE switch | sqlawin.dll |
| | | +------------------+ |
| | | | MLI via Window's |
HP <-------| | Messages |
ALLBASE/ | | | V |
SQL | | | +------------------+ |
PC API | | | | ALLBASE router | dballbas.exe |
| | | +----+------------------+---+ |
| | | | Translator/Packetizer | trlt.dll |
| | | | Translation to SQLX | |
| | +- +---------------------------+ |
| | MS Windows | |
| | 3.0 or later | |
| +-------------------|-----------------------------|
Data <------------------------| |
Com | MS-DOS 3.3 | SQLX Packets |
Log | or later | |
Point | V |
| +-----------------------------------------------|
| | PC Networking code |
+----+---------------------------------+-------------+
Local Area |
Network --------------+-----------------------+---------------
| HP 3000 DATABASE SERVER
+--+-----------+---------------------------------+---+
HP 3000 | | SPX/IPX | TCP/IP | |
Network | |.....................|.......................| |
Code <----| HP NetWare/XL with | HP ThinLan 3000/XL | |
| | HP ThinLan 3000/XL | | |
| +---------------------|-----------------------+ |
ALLBASE/ | | Listener | DEA - | Listener | DEA - | |
NET <----| | 1 per | | 1 per | |
| | | process | | process | |
| +---------------------------------------------+ |
| | ALLBASE/SQL | |
| +---------------------------------------------+ |
| MPE-iX 3.0 or later |
+----------------------------------------------------+
* Database function calls:
These function calls, relating to data definition and data
manipulation (SQL), database connection and so on, are handled at
the HP 3000 at the DBMS level. HP ALLBASE/SQL PC API provides the
link between the client PC environment and the server. HP
ALLBASE/SQL PC API functions in three ways to provide this link:
a. Translates client (PC) database requests into ALLBASE/SQL
requests.
b. Directs these ALLBASE/SQL requests to the ALLBASE/SQL DBMS
on the server, and returns database replies to the client
PC applications.
c. Translates ALLBASE/SQL replies into client (PC) replies.
All of the function calls are first processed by the Gupta C/API. The
Gupta C/API routes database function calls to the ALLBASE router, via the
ALLBASE switch, when appropriate. The ALLBASE router communicates with
the Gupta C/API by Windows messages using message level interface (MLI).
MLI is Gupta's proprietary interface, which is a request reply protocol
in which each request sent by a requester (for example, the client PC)
requires a reply from the server. The router converts the MLI
into the Translator function calls and passes them over to the
translator/packetizer. The Translator external interface is a subset of
the Gupta C/API and some additional routines. The translator/packetizer
performs many jobs. The first job translates the SQLBase syntax of the
SQL commands into ALLBASE/SQL syntax, where possible, and performs
datatype conversions where necessary. The second job translates the
database requests into SQLX. SQLX is both a function call interface to
the HP ALLBASE/SQL database and a protocol for communication of ALLBASE
distributed execution agents (DEAs) developed by HP. The third job
packetizes and de-packetizes the SQLX messages between the client PC and
the HP 3000 server.
HP 3000 SERVER ENVIRONMENT
The HP 3000 must be a series 900 with a LANIC card. The software
requirements are as follows:
* MPE XL 3.0 or later
* ALLBASE/SQL A.E1.16 or later
* ALLBASE/NET A.E1.16 or later
* Networking software depending on the protocol chosen.
TCP/IP protocol:
HP ThinLAN 3000/XL
SPX/IPX protocol:
NetWare/XL and HP ThinLAN 3000/XL
The ALLBASE/SQL and ALLBASE/NET provide the relational database
environment on the server. The HP 3000 server provides database security
through the MPE/iX logon system. All of the database management
capabilities of ALLBASE/SQL are also utilized.
The listener process, part of ALLBASE/NET, establishes the connection
between the client PC application process and the target database process
on the server. The listener, working through HP ThinLAN 3000/XL or
NetWare/XL data communications software, monitors a specified data
communications port for any incoming connection requests. Upon receiving
the connection request, the listener process creates a second process
that validates the incoming connection string against the MPE/iX logon
file. After that, the listener is free to listen to more connection
requests. This second process streams a server job for the specified
user and waits for the job to be initiated. The streamed job sets up a
direct communication link between the user and the database process
through the data communications software on the server. This direct link
is used from then on for all the communication between this user and the
DBMS.
ERROR HANDLING
An error code is returned to the client PC 4GL tool or application each
time it issues a function call. A zero error code indicates successful
completion of the call. If the error code is non-zero, the application's
error handling routine references the error.sql file, part of the HP
ALLBASE/SQL PC API product, to retrieve the error message text associated
with the returned code.
THE TOOLS OVERVIEW
There are troubleshooting and verification tools available for this
product. The troubleshooting tools consist of logging utilities as well
as a tool for problem duplication. All the tools are provided with the
product, thus the tools are on the customer's system for remote support.
All the tools are unsupported at this release. The tools are:
* Filter - filtr410.dll
This is a logging tool that is activated by two renames of
files on the client PC. When activated, the filter logs in
a file each Gupta C/API function call made by the 4GL tool
or application on the client PC. An analysis of this file
may show an invalid Gupta C/API function call that the 4GL
tool or application is making. This file can be used as
input to the scriptor tool described below for problem
duplication.
* Scriptor - scriptor.exe
The scriptor runs on the client PC in place of the 4GL tool
or application. It takes as input the Gupta C/API calls
(either individual calls or a series of calls in an ASCII
file). The output is printed on the screen and you have
the option of logging it to a file. The output file
produced by turning the filter on for a 4GL tool or
application can be used as an input file for the scriptor.
This is very useful in isolating the 4GL or application
specific problems, because now you are trying to duplicate
the problem using only the relevant set of Gupta C/API
function calls.
* DCLOG
This logging tool logs all the client requests and the
server replies that go over the network. This log allows
for verification of the data that is sent or received at
the client PC end. This tool is turned on by setting the
HPDCRECORD variable to 1 outside of the Windows.
* Displog - displog.exe
This is a support tool used to format in ASCII the binary
data communications trace logs produced by the DCCOM tool.
* Install - install.exe
This program gracefully installs the entire product and the
associated tools. There is some additional file
manipulation that is required besides installing the
product.
* Scripts - verify.scp and views.scp
Two scripts are included with the product. Both these
scripts are used as input to the Scriptor tool described
above. The verify.scp script verifies that a connection
can be established between the client PC and the
ALLBASE/SQL DBE on the server. Views.scp, installs the
system catalog views in each DBE, so that the ALLBASE/SQL
tables can be accessed by client PC 4GL tools or
applications.
* What - what.exe
This is a support tool used to display version information
for most of the files of the product.
Refer to the related article in the "Database Tools" section in this
Communicator for details on the supported 4GL query and application
development tools as well as the documentation for this product.