Application Writer’s Guide to the Earthworm Database Project

Lucky Vidmar

March 2, 2001

Source Tree Organization

EW_HOME /

EW_VERSION /

include

lib

bin

src /

archiving /

display /

libsrc /

util

winnt

solaris

[ . . . ]

oracle /

schema-VERSION /

sql_scripts

lib

src /

include

core_schema

strong_motion

[ . . . ]

apps /

lib

src /

include

archive /

orareport /

[ . . . ]

libsrc

API Overview

The oracle subtree in the src directory consists of two independent branches: schema and apps. The schema directory contains the source code (C and SQL) which actually touches the database. We think of this as the Earthworm DBMS Application Programmer’s Interface (API). The schema/src directory is comprised of several subdirectories roughly corresponding to the parts of the schema (core, external, alarms, etc.). Each of those directories contains the actual API C routines, as well as the SQL scripts necessary to support them.

Each API call lives within its own object file which has the same name as the API call itself. For example, the API call to retrieve an origin is ewdb_api_GetOrigin(), the source code for it is in ewdb_api_GetOrigin.c which compiles to ewdb_api_GetOrigin.o. This object file is automatically copied into the schema/lib directory from where it can be linked into the applications.

The function prototypes for each API function should be listed in ewdb_ora_api.h under schema/src/include.

Applications Overview

Each application lives in its own directory under schema/apps/src. The convention is that the source file which contains the main() function has the same name as the application. For example, the directory for the archive application might be:

apps/src/archive/

archive.c

archive.h

another_source_file.c

archive.d

makefile.sol

makefile.nt

RCS /

RCS. The RCS directory supports the Revision Control System which is used to ensure exclusive write-access to files, as well as to provide simple revision history of each file. There are several things to keep in mind while working with RCS:

1. In order for RCS to automatically update each file with the revision comments (a useful feature, we think), the following should be added to the top of each source file:

/*

* THIS FILE IS UNDER RCS - DO NOT MODIFY UNLESS YOU HAVE

* CHECKED IT OUT USING THE COMMAND CHECKOUT.

*

* $Id: ewdb_app_guide2.htm,v 1.2 2006/06/15 15:49:32 stefan Exp $

*

* Revision history:

* $Log: ewdb_app_guide2.htm,v $

* Revision 1.2 2006/06/15 15:49:32 stefan

* contact

*

* Revision 1.1 2006/05/19 15:49:52 paulf

* first inclusion

*

*

*/

2. Before modifying any source file which is under RCS, make sure to check it out first:

# checkout archive.c

3. Once finished modifying a source file, check it back in immediately to so that others can access it:

# checkin archive.c

Makefiles. Each application directory should have two makefiles: makefile.sol and makefile.nt used to compile the application under Solaris and NT respectively. Even if an application only runs on one platform, there should be a makefile for the other one containing only the clean-up directives. This ensures a smooth cross-platform compilation.

Below are the template makefiles for both Solaris and NT, with some explanations given in different color:

makefile.sol

#

# THIS FILE IS UNDER RCS - DO NOT MODIFY UNLESS YOU HAVE

# CHECKED IT OUT USING THE COMMAND CHECKOUT.

#

###############################

# Set APP to your program name.

###############################

APP = program_name In our example above, this would be archive

###############################

# Set directories

###############################

These directories are defined in the ew_sol_sparc.cmd file

B = $(WEB_DIR)/bin/

L = $(EW_HOME)/$(EW_VERSION)/lib/

A = $(SCHEMA_DIR)/lib/

APPS_LIB = $(APPS_DIR)/lib/

###############################

#OBJECT FILES EXTENSION

###############################

OBJ = .o

#########################################################

# Set APP_OBJECTS to the object files in this directory

#

# Set APP_OTHER to bind options or libraries needed by

# this application.

#########################################################

APP_OBJECTS = $(APP).o another_source_file.o

APP_OTHER = -lm

#########################################################

# Set EARTHWORM_API_O to all utility objects needed

# by this application.

#########################################################

EARTHWORM_API_O = $(L)ew_utility1.o \

$(L)ew_utility2.o \

$(APPS_LIB)ewdb_apps_util1.o \

$(APPS_LIB)ewdb_apps_util2.o \

$(APPS_LIB)ewdb_apps_util3.o

############################################################

# Include the makefile which links in all of the EWDB_API

# libraries. This makefile also enters the scary world of

# Oracle compilation options. No self-respecting application

# writer would want to know anything about what happens

# past this point.

############################################################

The make_ora_api.sol file contains the list of all API objects which are to be linked in. Those objects are in schema/lib directory. The make_ora_api.sol file also contains a series of directives needed to properly set up the Oracle compilation environment on Solaris. Changing any of the Oracle directives is done at one’s peril.

include $(APPS_DIR)/src/make_ora_api.sol

Below are the typical lint and clean-up directives. They allow for easy removal of object files and binaries.

# lint directive

lint:

lint $(APP).c another_source_file.c $(GLOBALFLAGS)

# cleanup directives

clean:

/bin/rm -f a.out core *.o *.obj

clean_bin:

/bin/rm -f $(B)/$(APP)*

install:

makefile.nt

#

# THIS FILE IS UNDER RCS - DO NOT MODIFY UNLESS YOU HAVE

# CHECKED IT OUT USING THE COMMAND CHECKOUT.

#

###############################

# Set APP to your program name.

###############################

APP = program_name

###############################

# NT System Makefile

###############################

!include <ntwin32.mak>

###############################

# Set directories

###############################

B = $(EW_HOME)\$(EW_VERSION)\bin

L = $(EW_HOME)\$(EW_VERSION)\lib

A = $(SCHEMA_DIR)\lib

APPS_LIB = $(APPS_DIR)\lib

API_INC_DIR = $(SCHEMA_DIR)\src\include

###############################

# OBJECT FILES EXTENSION

###############################

OBJ = .obj

#########################################################

# Set APP_OBJECTS to the object files in this directory

#

# Set APP_OTHER to bind options or libraries needed by

# this application.

#########################################################

APP_OBJECTS = $(APP).obj another_source_file.obj

APP_OTHER = -lm

############################################################

# Include the makefile which links in all of the EWDB_API

# libraries. EW_LIB is also set in this makefile -- it

# includes all of the typical earthworm libraries.

############################################################

make_ora_api.nt is less complicated than its Solaris cousin. It only contains the list of all API objects from schema/lib to be included. All of the necessary Oracle compilation directive are below in this file.

include ..\make_ora_api.nt

#########################################################

# Set EARTHWORM to all utility objects needed

# by this application.

#########################################################

EARTHWORM = $(EW_LIB) \

$(L)\ew_utility1.obj \

$(L)\ew_utility2.obj \

$(APPS_LIB)\ewdb_apps_util1.obj \

$(APPS_LIB)\ewdb_apps_util2.obj

##################################

# All object files for this app.

##################################

ALL_APP_OBJECTS = $(API_LIB) $(API_SQL_LIB) $(APP_OBJECTS) $(EARTHWORM)

Here is where the scary Oracle stuff begins. It is not contemplated that the application writer should have to change any of this.

##########################################################

# This is where the scary Oracle compilation stuff begins.

# No self-respecting application writer would want to know

# anything about what happens past this point.

##########################################################

# libraries for linking oci programs

OCILDLIBS= ociw32.lib oci.lib

LDFLAGS= /LIBPATH:$(ORACLE_HOME)\oci$(ORACLE_OCI_VER)\lib\msvc $(OCILDLIBS)

# Switch \lib\msvc to \lib\borland for borland compiler

# directory that contain oratypes.h and other oci demo program header files

ORA_INCLUDE= -I$(ORACLE_INC)

API_INCLUDE= -I$(API_INC_DIR)

ALL_INCLUDE= $(API_INCLUDE) $(ORA_INCLUDE)

###############################

# Build Your Application

###############################

$(B)\$(APP).exe: $(ALL_APP_OBJECTS)

$(link) $(conlflags) $(ldebug) $(conlibsmt) $(LDFLAGS) $(ALL_APP_OBJECTS) -out:$(B)\$(APP).exe

##################################

# To build objects from .c files

##################################

.c$(OBJ):

$(cc) $(cflags) $(cdebug) $(cvarsmt) $(tflags) $(ALL_INCLUDE) /Od $<

# Clean-up directives

clean:

del a.out core *.o *.obj *% *~

clean_bin:

del $(B)\$(APP)*

Application Utilities. Under apps/src, there is a libsrc directory containing utility routines which are potentially helpful to the application writer. The object files compiled from the source in libsrc are copied into apps/lib directory from where they can be linked into applications. The examples of such utilities include various web routines such as html_header(), as well as the routines providing a higher level interface to the database, e.g., GetDBEventInfo().

The function prototypes of the utility routines in apps/src/libsrc are in ewdb_apps_utils.h under apps/src/include.

While application writers are not expected to modify the code under the schema subtree, they are welcome to add to or modify the utility routines under apps/src/libsrc. It should be kept in mind, however, that other applications potentially rely on these utility routines. Therefore, care should be taken that such modifications do not break other applications.