DTIC ADA277131: The Intelligent Monitoring System: Generic Database Interface (GDI). User Manual. Revision

140 Pages·4.3 MB·English

by  Defense Technical Information Center

AD-A277 131
lE1lI1I1 hhfl
February 1094 SA1C-93/IO0 REV
7wIntelligent Monitoring System
Generic Database interface (GDI)
User Manual
DTIC_
S D _
MAR1l __199
F
SFECAL TE&CHML.RUMOR
25 February 1994
Basefime21.1l
jeanT. A~rlezso Mari Nmot4l Bonnie Macdithie, Howaid Tunwf
Geophysical Systems Operation
This docq'tnvrt hcs been appsoved
for pubh 4s, and sa*o ita
distribution is iu-nnniteci
The v1wsm aid ecorchjioew contahid in* ikd ocumet am thos of the authors aid sh&.id not be hIterputed representWngtheofficial
paid..11ei1th e 'amrkmhe~ e. of "he Ardvonce thseomh Protect Agency or the U.S. Goveromet.
Spoftmed by.
ADVANCED RESEARCH PROJEC'S AGENCY PrtcpalInseumg tor-
Nuclear Marisoring Rissarci Office Dr. ThasnC.QBache
ARPA Order Nmmbu62b6 6 PmgWn Code No. 62714E [phone]
InoWe by: DARPA)CMO
CAntrac No. MDA972-92-C-0026
3 8
05
V974
REPORT DOCUMENTATION PAGE
f0or Ap6O 7.0 -08
*t.o.4 1a 'i"..on fq,1ad-9 q twttho .4 t hensa$e .I, .n . sst ast "f.@t fOl td ,#a.e nOw o..o-e--9n Mi1 f4- .a.lIt..*o.t@ O n I. #1.Ii.q, coIf it'cO.ot nD0 o0#f, I* .n nWW in Idotd -n aIq~F m.t.n a t on,a ~ 0%r46I5iW ilt4i0 6 "ta" "w4W1ae4 rI.mowIoan,t,f. . At e-tl th'.anti , djaad tael,c. ..l o O't,f lIn's
tollfirl*of of .o ai,@..f . g qsv .~*q yAlo ns -o, vpa.c.nq lin., ow~ae- to *aitnohqto edant $a,.'"."#h u .eiaqo. O0e01 8i-w-a i~nd 4090 1~~ 14 isI tt-to
0&-1 It- or %..Iti j04 A1.91. ,q~ IN 4J1 02 and to 1-# 0-1.14 , )1 .. qcn 6-4 Idqft 'e0C'.Oi NeR u*,O nfct 4he( .01"OO.I*a).s h-nyion OC JO014
I AGENCY USE ONLY (Leave blank) 2 REPORT DATE -i REPORT TYPE AND DATES COVERED
I3-Jan-94.
Ltecial Technical 11/27/91-2/25/94
4. TITLE AND SUBTITLE -- -S. FUNDING NUMBERS
The Intelligent monitoring System
Generic Database Interface (GDI) User Manual MDA972-92-.C-0026
6.A UTHOR(S)
Jean Anderson, Mari Mortell, Bonnie MacRitchie,
Howard Turner
7. PERFORMING ORGANIZATION NAMAE(S) AND AODRISS(ES) 8. PERFORMING OR-GANIZATION
Geophysical Systems Operation REPORT NUMBER
Science Applications International Corporation
10260 Campus Pt. Drive
San Diego, CA 92121 SAIC-93-1001REV
9. SPONSORING/ MONITORING AGENCY NAME(S) AND ADORE SS(ES) 10. SPONSORING/ MONITORING
Advanced Research Project Agency
3701 N. Fairfax Drive, #717
Arlington, VA 22203-1714
11. SUPPLEMENTARY NOTES
12sa. DISTRIBUTION /A VAILABILITY STATEMENT 12b. DISTRIBUTION CODE
13. ABSTRACT (Maximum 200 word.1)
The Generic Database Interface (GDI) is a common application programmable
to multiple databases, providing two key capabilities: Database access and
data management. Database access routines allow an application to connect to
and query a database with the same GDI call whether the target database is
ORACLE, POSTGRES, or SYBASE. Data to and from the database are managed in
the native format of the application, making it possible to provide a seamless
integration of application and database.
14. SUBJECT TERMS IS.N UMBER OF PAGES
Data Management, Relational Database, Generic Interface 140
CODE
116. PRICE
17. SECURITY CLASSIFICATION 1B . SECUNtITY CLASSIFICATION I 12. SECURITY CLASSIFICATION 20. LIMIITATION OF ABSTRACT
OF REPORT OF THIS PAGE OF ABSTRACT
Unclassified Unclassified Unclassified NONE
NSN 7$40.01-260-5500 Standard Form 298 (Rev 2.89)
00 Upor Amft l TWO of Conlont
Table of Contents
Part 1: Introduction
1. O verview ........................................................................................................ 1-1
1.1 Intended Audience ............................................................................... 1-2
1.2 Docum ent O rganization ...................................................................... 1-2
1.3 User Feedback ..................................................................................... 1-3
2. A rchitecture ................................................................................................... 2-1
2.1 Basic Services ...................................................................................... 2-2
2-2 Database Connector (dbConn) .......................................................... 2-2
2.3 Database O bject (dbObj) .................................................................... 2-3
2.4 Com parison to Previous Interfaces ................................................... 2-4
2.5 Restrictions ........................................................................................... 2-5
Part I1: Generic Interface
3. Introduction ................................................................................................... 3-1
3.1 Location of G DI Com ponents ............................................................. 3-1
3.2 Sam ple Program s ................................................................................ 3-2
3.3 Database-Speci ic Notes .................................................................... 3-3
3.3.1 ORACLE ..................................................................................... 3-3
3.3.2 POSTGRES ................................................................................ 3-4
3.3.3 SYBASE ..................................................................................... 3-4
4. Database Communications (dbConn) ................................................ 4-1
4.1 Connecting to a Database ........................................................... 4-1
4.2 M anaging Q uery C hannels ................................................................. 4-5
5. Q uery Execution ......................................................................................... 5-1
-......................
6. Specialized Database Functions .......................................................... 6-1 A27,.O.'
7. D ata Ma nagem ent (dbOb j) ..................................................................... 7-1 • C
7.1 Tuple Container .............................................................................. 7-4 ty Codes
7.2 Colum n Definitions .............................................................................. 7-5 and I or
ecial
7.3 Tuple Constructor...............................7-7
L
Basolne: 21.1
aW1U rw Abnul/ TabWO of Cl'kts
8. Error Handling .............................................................................................. 8-1
8.1 User Error Functions ........................................................................... 8-2
8.2 Low-Level Error Functions .................................................................. 8-3
8.3 Known Problem s .................................................................................. 8-4
9. Transaction Ma nagem ent ....................................................................... 9-1
Part III: High-Level Interfaces
10. S-PLU S Interface ................................................................................. O-1
10.1 Starting S-PLUS ................................................................................. 10-2
10.2 Connecting to a Database ................................................................ 10-3
10.3 Executing Database Queries ........................................................... 10-4
10.4 Plotting Results .................................................................................. 10-5
10.5 Transaction M anagem ent ................................................................. 10-6
10.6 Exiting S-PLUS .................................................................................. 10-6
10.7 Sum mary of S-PLUS Com mands .................................................... 10-6
11. FO RT RA N Interface ................................................................................. 11-1
11.1 Document O rganization ..................................................................... 11-1
11.2 Subroutine and Function Calls .......................................................... 11-1
11.3 Connecting to a Database ................................................................. 11-6
11.4 Executing Queries .............................................................................. 11-8
11.4.1 Queries that Do Not Return Data .............................................. 11-8
11.4.2 Queries That Return Data ......................................................... 11-9
11.5 Handling Errors ................................................................................. 11-11
11.6 Sam ple Program s ............................................................................. 11-12
11.7 Troubleshooting Tips ........................................................................ 11-14
11.8 Current Restrictions .......................................................................... 11-15
Part IV: Reference Manual
Utilites:
gdi-gen_Astructs(1) ............................................................................... 1
GenericA PI:
gdiL abort(3) ............................................................................................ 3
gdLaddArrayStructs(3) .............. ........... 4
gdi begin tran(3) ................................................................................. 6
gdL channeL-B_open(3) ....................................................................... 7
gdi-close(3) ............................................................................................ 8
gdi close_channel(3) ............................................................................ 9
Baselne: 21.1
Go LW *Anumi Tab"e of c(cid:127)mnnts
gdLcom mit(3) .......................................................................................... 10
gdLdead(3) ............................................................................................... 11
gdi errorjlags(3) ..................................................................................... 12
gdLerrorget(3) .................................................................................. 13
gdLerror.inft(3) .................................................................................. 14
gdLexft(3) ............................................................................................ 15
gdiflush(3) .......................................................................................... 16
gdLget. account(3) ............................................................................. 17
gdi_getArrayStructs(3) ..................................................................... 18
gdiget.counter(3) ............................................................................. 21
gdi_geL database(3) .......................................................................... 24
gdi_get. dboption(3) ............................................................................. 25
gdi_geot node(3) .................................................................................. 27
gdi_get.vendors(3) ............................................................................. 28
gdLinit(3) ............................................................................................ 29
gdLinsert(3) ....................................................................................... 30
gdi obLcreate(3) ............................................................................... 31
gdi obLdestroy(3) ............................................................................. 32
gdLopen(3) .......................................................................................... 33
gdLiopen_channel(3) .......................................................................... 35
gdi_p ntnLcoldefs(3) ............................ ................................................ 36
gdi..print -conn(3) ............................................................................... 37
gdi_print.dbobj(3) ............................................................................... 38
gdi_pdnttuples(3) ............................................................................. 39
gdLrollback(3) ..................................................................................... 40
gdLsavepoint(3) .................................................................................. 41
gdi set. dboption(3) ............................................................................. 42
gdmsleep(3) ....................................................................................... 43
gdmsubmit(3) ........................................................................................... 44
gdi trace(3) .......................................................................................... 48
ORACLE-Specific Routines:
oracle_open(3) ..................................................................................... 49
ora._sqlcaerror(3) ................................................................................ 51
FORTRAN API:
gdLcdose(3Q). ...................................................................................... 52
gdmerror.get(3f) ................................................................................. 53
gdLerror init(3f) ....................................................................................... 54
gdi-nit(3f) ............................................................................................ 55
Baseine: 21.1 iii
GO U1w Ibnual Table o Cofnte
gdL m ap(M). ............................................................................................. 56
gdi-open(3f) ............................................................................................. 58
gdi subm it(3f) .......................................................................................... 59
gditrace(3f) ............................................................................................. 61
Part V: Appendices
Appendix A. Bibliography ................................................................................... A-1
Appendix B. Data Types ..................................................................................... B-1
Baselne: 21.1 iv
Part I: Introduction
0/trmw IbNmW OwMvew
1. Overview
The Generic Database Interface (GDI) Is a common Application Programming Interface (API) to
multiple databases. The GDI provides two key capabilities:
1. DatabaseA ccess
An application connects to a database and executes a database query with the same GD I
calls whether the target database Is ORACLE, POSTGRES, or SYBASE.
2. Data Management
Data to and from the database are managed in the native format of the application, mak-
ing it possible to provide a seamless Integration of application and database.
The GDI model consists of the components depicted In Figure 1. High-Level interfaces may be
added without having to modify lower level functionality.
FORTRAN or Scheme
S-PLUS ad hoc analysis Gener Int Application
specific to a database
C Application
same for all databases
FIGURE 1. Generic Database Interface (GDI) Model
Working from the bottom of Figure I to the top, the GDI consists of:
"* DatabaseI nterface
Manages Interaction with the target database.
"* Generic Interface
Provides a common API for C applications to access any database and manage data.
"* High-Level Interfaces
Support programming languages such as FORTRAN and Scheme, and third-party
products such as S-PLUS.
Baseline: 21.1 1-1
G1X I*Wr awma Oawviow
1.1 Intended Audience
The GDI targets two types of users: the end-user and the application developer. Section 10
describes S-PLUS, an end-user application.
The end-user interactively accesses the database with a program created by an application
developer or a third party tool such as S-PWS. End-users want a "hot link" between the applica-
tion and the target database so they can concentrate on research and analysis. They do not want
to be sidetracked by having to manually transfer data, not even with the aid of data migration
tools.
The application developer writes programs that require database access. Application developers
want a consistent Interface between the application and the target database so they can concen-
trate on a specific area of programming expertise, whether It be the design of sophisticated user
Interfaces or complex scientific programs. They do not want to be sidetracked by having to learn
how to access each database.
Neither user wants to become an expert for each database accessed. Both want application and
database to be transparently Integrated. The GDI achieves that transparent integration.
This manual describes what each user must know to submit queries to a database and manage
data. The user needs to know:
" The database query language, which is a topic beyond the scope of this document.
Appendix A lists a few SQL references. POSTGRES documentation Is available via
anonymous ftp from postgres.berkeley.edu.
" How to use the generic lunctions that execute queries and manage data. This is the
topic of this manual.
The user does not need to know:
"* Database vendor-specific Implementation of Embedded SQL and/or the call interface.
"* Database vendor-specific data dictionary structure.
"* Database vendor-specific error handling.
"* Application-specific and database-specific data formats.
"* Internal GDI data structures.
1.2 Document Organization
PART I Introduces a high-level view of the GDI. Section 1 (this section), describes the GDI model.
Section 2 describes the GDI architecture.
PART II Introduces GDI routines to the application developer. Section 3 discusses naming con-
ventions, sample programs, and known problems. Section 4 discusses database communica-
tions. Section 5 and Section 6 describe query execution and specialized database functions.
1. S-PLUS is a statistical and graphics program developed by StatScl that is basad on the S-Lan-
guage.
Baseline: 21.1 1-2
GO Usw *bnul Owrvipw
Section 7 describes data management. Section 8 and Section 9 discuss error handling and
transaction management, respectively.
PART III Introduces the high-level interfaces to the end-user. Section 10 contains an S-PLUS
tutorial. Section 11 describes the FORTRAN Interface.
PART IV contains UNIX Section 1 man pages for GDI tools and Section 3 man pages for GDI
routines. The most current man pages are available on-line.
PART V contains appendices. Appendix A is a bibliography of SQL language references. Appen-
dix B is a description of GDI data types.
1.3 User Feedback
The GDI development team welcomes comments. All bug reports and suggestions for improve-
ment should be sent to [e-mail]
Baseline: 21.1 1-3