==============================================================================
VELOCIS DATABASE SERVER 
VERSION 1.4.1 STANDALONE FOR BSDI 3.0
28th April 1997
------------------------------------------------------------------------------
The Velocis provided in this package is a complete implementation of version
1.4.1 of Velocis for standalone use (on a single computer) under BSDI 3.0.
==============================================================================

Velocis Database Server is designed for professional database application
developers who are looking for a high performance client/server database
engine.  Velocis is a scaleable SQL client/server database engine that
provides a rich set of architectural choices and APIs including ANSI SQL, 
SQL C-API, low-level C-API, C++ class libraries, and support for custom
APIs.  Unlike typical relational client/server database products, Velocis
supports both relational and pointer-based network model databases in any
combination as well as processing on either side of the client/server
equation.  The choices of multiple operating platforms, APIs, processing
locality (client or server), and database model can be mixed and combined
to satisfy the performance requirements of virtually any application.

Add-on products for Velocis include;

Raima Object Manager
--------------------
Raima Object Manager is a C++ class library that allows use of Velocis 
Database Server as an OODBMS.  ROM encapsulates object storage, retrieval,
and database navigation into C++ class definitions to provide a consistent
object-oriented interface.   Add persistence to any C++ object, object
identity, class or type hierarchies, container classes, safe type checking,
VLT, BLOB, Referential Integrity, Server Extensions, and much more.  ROM 
includes source.

Raima Report Writer
-------------------
Report Writer is designed for Raima database developers and end-users alike
who are looking for high performance data access and reporting tool for
Windows clients, with support for a multiple platform database server.  The
Report Writer represents the state-of-the-art in graphical query definition,
interactive browsing, and the production of detail (band) and frame-based
reports (or any combination).

==============================================================================
TABLE OF CONTENTS
==============================================================================

1. FEATURES AND DISTINCTIVES
2. INSTALLATION INSTRUCTIONS
3. COMPONENTS
4. BUILDING AND USING THE EXAMPLE PROGRAMS
5. CREATING A NEW SQL DATABASE
6. USE WITH ODBC-ENABLED PROGRAMS
7. RESRICTIONS AND KNOWN ISSUES
8. FOR MORE INFORMATION


==============================================================================
1. FEATURES AND DISTINCTIVES
    1.1  Designed to be embedded within mission-critical client/server 
         applications
    1.2  Ability to open multiple connections to one or more servers
    1.3  Incremental database open and close with variety of database 
         open mode
    1.4  High-Performance Transaction Processing
    1.5  Server Extensions
    1.6  Database Instancing
    1.7  Velocis SQL: Support for 1989 ANSI SQL Standards
    1.8  Velocis SQL: Transparent network-model database support
    1.9  Velocis SQL: Cost-based Query Optimizer
    1.10 Velocis SQL: Expanded Data Types
    1.11 Velocis SQL: Stored Procedures
    1.12 Velocis SQL: C-based user-defined stored procedures (UDPs)
    1.13 Velocis SQL: Scaler functions
    1.14 Velocis SQL: C-based user-defined functions (UDFs)
==============================================================================


1. FEATURES AND DISTINCTIVES
----------------------------
1.1  Designed to be embedded within mission-critical client/server 
     applications
------------------------------------------------------------------------------
Velocis is ideal for use as an embedded database engine in client/server 
applications.  Velocis has low hardware requirements (i.e., small 
"footprint") yet it can scale from standalone use on Win16 to large UNIX 
systems supporting many users.  Velocis installation and administration is
much easier than other database servers.  Its call-level administrative API
allows application programs to tailor Velocis administration to their own
environment.  Velocis management of low disk-space conditions is state-of-
the-art allowing full application management of this critical aspect. 
Velocis provides several features that allow server functionality to be 
extended resulting in close integration of the application with the 
database server.


1.2  Ability to open multiple connections to one or more servers
------------------------------------------------------------------------------
A single client application can open several independent, active connections
to that same server or any other Velocis server on the network.


1.3  Incremental database open and close with variety of database open modes
------------------------------------------------------------------------------
Velocis SQL allows any number of databases to be open and active at the same
time. Moreover, a database can be opened in one of several modes: shared,
modes: shared, exclusive, temporary, with or without transaction logging.
These modes provide different performance/recovery tradeoffs so that you can
choose the mode that best suits your application requirements.


1.4  High Performance Transaction Processing
------------------------------------------------------------------------------
Velocis SQL is built on the Velocis database engine, which has been designed
for high performance transaction-oriented applications.  Among its state-of-
the-art capabilities, the Velocis engine optimizes transaction logging and
recovery and performs asynchronous database I/O, allowing for greater
concurrency on the server computer.  The engine also piggy-backs output of
database pages and provides true row-level locking.  These provide efficient
efficient use of server memory and a large but configurable, efficient
database cache.  Moreover, four levels of transaction isolation are 
available to Velocis SQL users.


1.5  Server Extensions
------------------------------------------------------------------------------
Velocis provides an important feature that allows the server capabilities 
to be extended with application-specific functions.  Server extensions (also
known as extension modules) are C functions that execute on the database
server when called by a client program.  They improve system performance by
greatly reducing the network traffic between clients and the Velocis server.
Server extensions can be used to perform a variety of standard database
operations needed by an application.


1.6  Database Instancing
------------------------------------------------------------------------------
Database instancing allows multiple instances of a database definition 
(schema or DDL) to be created.  These separate database instances all share 
the same DDL and its associated meta-data but each instance has its own copy
of the data. 


1.7  Velocis SQL: Support for 1989 ANSI SQL Standard
------------------------------------------------------------------------------
Most of the 1989 ANSI SQL standard is supported in Velocis including the
referential integrity and column constraint check features. 


1.8  Velocis SQL: Transparent network-model database support
------------------------------------------------------------------------------
Velocis SQL DDL includes an additional statement, create join, used with 
foreign and primary key specifications to indicate that direct access 
methods are to be used in maintaining the inter-table relationship.  SQL 
DML programs are completely unaware of the presence of these "pre-defined"
joins (except for the performance benefits that result).


1.9  Velocis SQL: Cost-based Query Optimizer
------------------------------------------------------------------------------
Utilizing data distribution statistics the Velocis SQL query optimizer 
generates query execution plans .based on use of indexes, pre-defined joins 
and direct access.


1.10 Velocis SQL: Expanded data types
------------------------------------------------------------------------------
Velocis SQL allows the definition of date, time, and timestamp data 
types in addition to the standard ANSI SQL data types.  Velocis SQL also 
has the ability to define and access C struct and array columns 
manipulated using the Velocis record-level API (d_).


1.11 Velocis SQL: Stored Procedures
------------------------------------------------------------------------------
The Velocis SQL stored procedures allow SQL statements to be compiled, 
optimized, parameterized and stored in the system catalog.  Stored 
procedures are invoked through the SQL execute statement.


1.12 Velocis SQL: C-Based user-defined stored procedures
------------------------------------------------------------------------------
User-defined procedures are similar to server extensions in that they, too, 
are C functions that execute on the Velocis server.  C-based stored 
procedures can return any number of result sets.  These result sets are 
processed just as standard stored procedure result sets.  C-based stored 
procedures are also invoked the same way as are standard stored procedures. 
Unlike standard stored procedures, however, C-based stored procedures provide
the power of C.


1.13 Velocis SQL: Scalar functions
------------------------------------------------------------------------------
A full complement of scalar functions is provided including math, string, 
and date manipulation capabilities.


1.14 Velocis SQL: C-Based user-defined functions
------------------------------------------------------------------------------
User-defined functions are similar to server extensions in that they, too, 
are C functions that execute on the Velocis server.  But, instead of being 
called from the client application, they are called from Velocis SQL when 
the functions are used in an expression in an SQL statement.  User-defined
functions can be used to implement both scalar and aggregate functions.
Moreover, Velocis triggers are implemented in C using user-defined triggers.


==============================================================================
2. INSTALLATION INSTRUCTIONS
    2.1  Installation Procedures
    2.2  Directory Structure
    2.3  Testing the Installation
==============================================================================


2.  INSTALLATION INSTRUCTIONS
-----------------------------
2.1  Installation Procedures
------------------------------------------------------------------------------
Velocis 1.4.1 for BSDI comes in a single tar file, rds.tar, which includes
both server and client files.  The file is found in the \third-pa\raima
directory of CD-012.  Installation is fairly straightforward.  Please take
the following steps:

1)  Copy rds.tar onto an empty directory.  This directory is going to 
    be your Velocis HOME directory.  A typical directory name is Velocis.
 
2)  Open the tar file using the following command to install necessary 
    files on your Velocis HOME directory.

	tar -xvf rds.tar
 
3)  Run install from your Velocis HOME directory as follows.  This command
    will set up necessary permissions on the relevant directories on your
    on your BSDI.

	sh -x ./install

4)  Run one of the script files, rdshome.csh (C shell) or rdshome.sh 
    (Korn shell), in order to set up the necessary environment variables 
    for Velocis on your BSDI.

Installation is now complete.  Your Velocis is ready to start.


2.2  Directory Structure
------------------------------------------------------------------------------
The following subdirectories are created under your Velocis directory 
(e.g., /Velocis).

bin/		All object libraries and executable programs
include/	Velocis C header files
lib/		Velocis client library
catalog/	Velocis system catalog databases
syslog/		Standard Velocis log device directory
sqldb/		Example Velocis SQL database device directory
examples/	
sql/		SQL UDF, UDP and extension module examples
rsql/		RSQL utility source code and example database definitions
rdm/		Low-level database examples


2.3  Testing the Installation
------------------------------------------------------------------------------
It is necessary to start Velocis server from a terminal window.  The steps 
to accomplish this are:

1)  Start a terminal window
 
2)  Change the current directory to the Velocis bin directory, for instance:

	cd /Velocis/bin

4)  Start the server as follows.  <SERVER name> should be replaced by your
    own Velocis server name (e.g., 'velserv').  If you omit the server name,
    it will be defaulted to 'rdsbsdi'.

        rds <SERVER name>

5)  It is possible to change the default server name by changing the
    ServerName parameter in VELOCIS.INI, our initialization file found in
    your Velocis/catalog directory.  For instance, you can change the
    parameter as shown below:

        ServerName=velocis

    This will set the default server name to 'velocis'.  The next time you
    start the server without the <SERVER name> parameter, the server name
    will be 'velocis' instead of 'rdsbsdi'.  Please note that this parameter
    will always be overridden by the <SERVER name> parameter.

6)  Please note that Velocis allows you to use up to 12 characters for the
    server name.  If your server name exceeds 12 characters, neither the 
    full server name nor the name truncated to 12 characters would work.

After your Velocis server has been started, you can perform a quick test to
verify that it has been installed and configured properly by establishing
a session with Velocis utilities such as RDSADM and RSQL.  We have pre-
configured the server with two login/password identifications for this
purpose, Wayne/Father for a normal user and admin/secret for an 
administrative user.

Just like server names, Velocis has limitations to the number of characters
that you can use for your user names and passwords.  They are both limited
to 7 characters, and names longer than that would not work.

The RDSADM utility, a text-based administration program, will prompt 
you for the name of the server, login ID and password.  After 
successfully connecting to the server, another menu will offer you 
choices to administer a number of server objects, i.e. users, databases, 
devices and so on.

The RSQL utility is a simple text-based interactive SQL facility.  After 
invoking RSQL, connect to the server by entering a command of the 
form:

    .c 1 <SERVER name> admin secret

For instance, if your server name is 'bsdiserv', the connection command 
will look like:

    .c 1 bsdiserv admin secret

If RSQL successfully connects to the server, it will return with a
statement:

    Connected to Velocis, version '1.4.1 [Build 108] [10-Jan-97]'
    *** using statement handle 1 of connection 1

and will wait for further input from you.  See the help section on RSQL for
additional RSQL instructions.  Terminate RSQL with a ".q" command.


==============================================================================
3. COMPONENTS
==============================================================================

3. COMPONENTS
-------------
The following administration and utility programs are provided in the 
Velocis/bin directory.

Program		Description
------------------------------------------------------------------------------
dal		A utility that processes an interpreted language that uses 
		as its commands the low-level Velocis "d_" functions.
dbcheck		A utility that can be used to check the consistency of a 
		Velocis database.  
dbver		A utility to mark a database dictionary file (e.g., sales.dbd) 
		for use under RDM or Velocis (RDS) (e.g. "dbver/rdm sales").
		You will need to first run dbver before you attempt to access
		a Velocis database using an RDM utility, such as dbcheck.
		When you have finished using the RDM utility, you will again
		need to run dbver to reset the database for use under Velocis
		(e.g. "dbver/rds sales").
ddlgen		A utility for generating SQL and DDL specifications for 
		databases in the SQL system catalog.
ddlproc		The Database Definition Language Processor utility (ddlp) 
		that compiles a non-SQL (i.e., low-level) database schema 
		and generates the dictionary and C/C++ header files.
rdsadm		The character-mode database administration utility that 
		can be used to manage users, database devices, security, 
		and configuration. 
sddlp		The SQL Database Definition Language Processor (sddlp) 
		that compiles an SQL database schema storing the database
		definition in the system catalog as well as generating the
		database dictionary and, optionally, C header files.


==============================================================================
4. BUILDING AND USING THE EXAMPLE PROGRAMS
    4.1  Overview
    4.2  TIMS example
    4.3  Standard extension module example
    4.4  RSQL utility
    4.5  SQL extension module example
    4.6  Example user-defined SQL functions (UDF) 
    4.7  Example user-defined SQL procedures (UDP)
==============================================================================

4. BUILDING AND USING THE EXAMPLE PROGRAMS
------------------------------------------
4.1  Overview
------------------------------------------------------------------------------
The following database devices are defined with the initial system.  It is 
assumed that /Velocis is the default installation directory.  Please 
replace it with your own Velocis root directory if you specified a different 
name. The following paths can be adjusted accordingly:

Device Name	Path
------------------------------------------------------------------------------
sysdev		/Velocis/syslog
catdev		/Velocis/catalog
sqldev		/Velocis/sqldb
samples		/Velocis/examples/rdm
sqlsamp		/Velocis/examples/sql
rdsdll		/Velocis/bin

When you installed Velocis, a system catalog that was pre-loaded with three
example databases and three users was created.  The databases were sales,
invntory, and tims.  The users (with their passwords) are Wayne (Father),
guest (guest), and admin (secret).  Case is significant for user names and 
passwords.  Wayne and guest are normal users, while admin is a privileged
user.

Note:  It is a good idea to maintain a one-to-one correspondence between
actual users and account names.  Therefore, you should use the supplied
Wayne and guest accounts only until you are familiar with the system.  At
that time, you should delete the two accounts.

The tims, sales, and invntory databases are pre-loaded as well.  tims is a 
database example intended to be used only by d_  (low-level, record-oriented
API) applications.  The definition of the tims database is not included in
the SQL system catalog.  Sales and invntory are SQL databases.

Build and use the following examples to become familiar with the Velocis 
development process.  Below are the brief descriptions of each example.


4.2  TIMS example 
------------------------------------------------------------------------------
The tims example is a character-mode client application.

You can use the BSDI 'make' program to build the tims example program (found
in the examples/rdm subdirectory) from the makefile, tims.mak.  This example
has been ported to Velocis from Raima's RDM product example.  It opens the
database named tims in 'exclusive no transaction' access mode ("xn") and 
exclusively uses the d_ API to Velocis.


4.3  Standard Extension Module Example
------------------------------------------------------------------------------
The system also contains an example d_  API based (non-SQL) extension module
(called em.c) and a client program that accesses it.  These files are 
contained in the examples/rdm directory.  These files can be used as
starting points for extension module development.  You should take the time
to review the code and makefile.

To build the extension module, you can use the supplied makefile (called 
em.mak).  It may be necessary to edit the makefile to identify the location
of your compiler's directory.

Leave the target file, x_em, in the examples/rdm subdirectory.  You do 
not need to use admin to register the extension module because the system
comes with the extension module already registered.


The client program, useem, is built using the useem.mak makefile.  Execute
the resulting executable, useem.  The extension module will run and print
a set of messages indicating whether it has succeeded or failed.

When you finish with the example databases, you can remove the example
database devices if you wish.  You should not tamper with the catdev
device; this device is used internally by the system to locate the SQL
system catalog.


4.4  RSQL utility
------------------------------------------------------------------------------
Velocis comes with the source code and makefile for our rsql utility.  You 
can use the BSDI make program to build the program (found in the examples/
rsql subdirectory) from the makefile rsql.mak.  When creating your own 
makefile for your applications, you can start with rsql.mak.  The rsql
source code also provides some examples of SQL programming.


4.5  SQL Extension Module Example
------------------------------------------------------------------------------
The system contains an example SQL extension module (called emsql.c) and a
client program that accesses it.  These files are contained in the examples/
sql directory.  These files may be used as starting points for SQL extension
module development.  You should take the time to review the code.

To build the extension module, you can use the supplied makefile (called 
emsql.mak).  It may be necessary to edit the emsql.mak makefile to identify
the location of your compiler's directory.

The target file, the x_emsql module, should be left in the examples/sql 
subdirectory.  You do not need to register the extension module because the
system comes with the extension module already registered.

The client program, useemsql, is built using the useemsql.mak makefile.
Execute the useemsql executable from a terminal window.  The extension
module will run and print a set of messages indicating that it has succeeded 
or failed.  If successful, the output should include a message indicating
that 14 rows were affected.


4.6  Example User-Defined SQL Functions (UDF)
------------------------------------------------------------------------------
To build the example user-defined functions module, go to the examples/sql 
directory.  This directory contains a makefile named udf.mak, which you can
use to build the udf user-defined function module.  It may be necessary to
edit the udf.mak makefile to identify the location of your compiler
directory.

Leave the target file in the examples/sql subdirectory.

You may use the user-defined functions through the rsql example program.
For example:

    cd /Velocis/examples/rsql
    rsql
    001 rsql: .c 1 <SERVER name> admin secret
    001 rsql: create
    + 001 rsql: aggregate functions std, stds
    + 001 rsql: scalar function subquery
    + 001 rsql: in udf on sqlsamp;
    002 rsql: select sale_name, avg(amount), std(amount), stds(amount) 
    + 002 rsql: from salesperson, customer, sales_order                
    + 002 rsql: where salesperson.sale_id = customer.sale_id and       
    + 002 rsql: customer.cust_id = sales_order.cust_id group by 1;

    SALE_NAME		AVG(AMOUNT)	STD(AMOUNT)	STDS(AMOUNT)
    Flores, Bob         19233.557778 	21767.832956    23088.273442
    Jones, Walter	28170.703333	22055.396667    22829.504456
    Kennedy, Bob	61362.110000	75487.487619	78844.109392
    McGuire, Sidney    	18948.373636	16888.086829	17712.374895
    Nash, Gail		34089.695556	35751.014170	37919.676831
    Porter, Greg	87869.300000	87370.831661	97683.559422
    Robinson, Stephanie	24993.631333	28766.406110	29776.059184
    Stouffer, Bill	 3631.662500	 2731.390470 	 2919.979236
    Warren, Wayne	21263.850000	24150.207498	25456.553886
    Williams, Steve	27464.443333	16696.742874	17709.570165
    Wyman, Eliska	23617.375417	31511.044841	32188.779254

    003 rsql: select state, 
    + 003 rsql: 100*sum(amount)/subquery("select sum(amount) from 
    + 003 rsql: sales_order") pct_of_sales from customer, sales_order 
    + 003 rsql: where customer.cust_id = sales_order.cust_id group by
    + 003 rsql: state;

    STATE       	PCT_OF_SALES 
    AZ             	 6.386350 
    CA             	13.108034 
    CO             	13.422859 
    FL             	 3.591970 
    GA             	 3.057682 
    IL             	 4.310374
    IN		 	 0.781594 
    LA             	 4.993924
    MA             	 3.233216
    MI             	11.819327 
    MN              	 1.330608 
    MO              	 3.807593 
    NJ              	 0.425850 
    NY             	10.425037 
    OH              	 4.414228
    PA              	 3.911350 
    TX              	 3.259824 
    VA              	 1.695903 
    WA              	 1.634471 
    WI              	 4.389806

    004 rsql: .q               


4.7  Example User-Defined SQL Procedure (UDP)
------------------------------------------------------------------------------
C-based SQL Stored Procedures (user-defined procedures) are similar to 
extension modules except that they are invoked through SQL by preparing and
executing an execute statement.  They are more flexible than ordinary stored
procedures in that the C-based procedures can support dynamic argument
lists. 

The installation contains an example user-defined procedure (called udp.c).
This file is contained in the examples/sql directory for the server.  This
file can be used as a starting point for customized C-based stored procedure
development.  You should take the time to review the code and makefile.

To build the UDP, you can use the supplied makefile (called udp.mak).  
It may be necessary to edit the udp.mak makefile to identify the location 
of your compiler's directory.

Leave the target file, udp, in the examples/sql subdirectory.  You do not 
need to register the procedure because this is done through the SQL API. 

Once the udp module has been built, you can activate it and test it by using
the rsql utility.  Issue the following statement from rsql after logging in:

    create proc tims_data in "Udp" on sqlsamp;

Then, to execute the tims_data procedure, use the exec statement, for
example:

    exec tims_data("Kn", "Kr");

    AUTHOR     		ID_CODE	INFO_TITLE                     		...
    Knuth, D.		cs001	The Art of Computer Programming Vol 1 	...
    Knuth, D.  		cs002	The Art of Computer Programming Vol 2 	...
    Knuth, D.		cs003	The Art of Computer Programming Vol 3 	...
    Kruglinski, D.  	db020	Data Base Management Systems           	...
    Kruglinski, D.	db021	The Network-Model DBMS"                 ...

    TOTAL ROWS 
    FOUND                                                                  
               5   

This example udp also contains Login/Logout procedures that can be activated
with the following statements:

    create procedure log_login  in udp on sqlsamp;
    create procedure log_logout in udp on sqlsamp;
    set login  proc for public to log_login;
    set logout proc for public to log_logout;
    set login on;

This turns on Login/Logout logging.  Every login and logout will cause a 
row containing the action, userid, time, etc. to be inserted into a table 
called activity_log.  After a login, logout or two, you can view the table:

    select * from activity_log;


==============================================================================
5. CREATING A NEW SQL DATABASE
    5.1  Overview
    5.2  Creating the schema
    5.3  Compiling the schema using SDDLP
    5.4  Accessing the resulting SQL database 
==============================================================================


5. CREATING A NEW SQL DATABASE
-------------------------------
5.1  Overview
------------------------------------------------------------------------------
This section will lead you through creating and installing a new SQL
database called ims (or Information Management System, a program for 
managing a technical library).  The example develops the Data Definition 
Language (DDL) file, and compiles it with the SQL DDL processor called
sddlp.  To create and install the ims example, follow these steps:


5.2  Creating the schema
------------------------------------------------------------------------------
Create the SQL DDL file, called ims.sql.  We recommend using a suffix of 
.sql for the SQL DDL.  Do not use .ddl because sddlp uses that extension for
an intermediate file.  The file should contain the following text:


    create database ims;	/* Information management system */
    create table author (
        name char(16) primary key
    );
    create unique index name_key on author(name);
    create table info (
        id_code char(16) primary key,
        info_title char(30),
        publisher char(20),
        pub_date char(12),
        info_type smallint,
        name char(16) not null references author
    );
    create unique index id_code_key on info(id_code);
    create join has_published order last on info(name);


5.3  Compiling the schema using SDDLP
------------------------------------------------------------------------------
Compile the DDL and register it in the SQL catalog by running the sddlp 
utility and entering the following at the prompt:

    SDDLP>-L <SERVER name>;admin;secret ims.sql

The -L option allows you the specify the name of the server, the user name,
and the password that sddlp will use to connect to Velocis.  You can also
specify these options from the command line as shown below:

    sddlp -L <SERVER name>;admin;secret ims.sql

If you execute sddlp this way, it will not go to the prompt.  It will simply
process the schema and print out the result.  The result will also be stored
in a text file called sddlp.out, found in the directory where you executed
sddlp.


5.4  Accessing the resulting SQL database
------------------------------------------------------------------------------
Once sddlp is complete, it should be possible to use rsql to access the new 
database.  In the example below, your input is in bold face, and the server
response is displayed as regular type. 

    001 rsql: .c 1 <SERVER name> admin secret
    *** using statement handle 1 of connection 1
    002 rsql: update stats on ims;
    003 rsql: open ims;
    004 rsql: insert into author values("Bob");
 
    *** 1 rows affected
    005 rsql: insert into author values("Bill");

    *** 1 rows affected
    006 rsql: insert into info (id_code,info_title,name)
    + 006 rsql: values("bob01","Bob's first book","Bob");

    *** 1 rows affected
    007 rsql: insert into info (id_code,info_title,name)
    + 007 rsql: values("bob02","Bob's second book","Bob");

    *** 1 rows affected
    008 rsql: insert into info (id_code,info_title,name)
    + 008 rsql: values("bill01","Bill's only book","Bill");

    *** 1 rows affected
    009 rsql: commit;
    010 rsql: select * from info;

    ID_CODE	INFO_TITLE		PUBLISHER	PUB_DATE
    bill01	Bill's only book	*NULL*		*NULL*
    bob01	Bob's first book	*NULL*		*NULL*
    bob02	Bob's second book	*NULL*		*NULL*
    011 rsql: .q


==============================================================================
6. USE WITH ODBC-ENABLED PROGRAMS
    6.1  Overview
    6.2  ODBC Administration utility
    6.3  PowerBuilder users
    6.4  Compatibility with ODBC 3.0 
==============================================================================


6. USE WITH ODBC-ENABLED PROGRAMS
---------------------------------
6.1  Overview
------------------------------------------------------------------------------
The standard API for Velocis SQL is based on the Microsoft Open Database
Connectivity (ODBC) specification.  Velocis is currently based on the ODBC
version 1.0 specification and supports the level 1 functionality.

NOTE: In order to use ODBC with Velocis, you must have a version of Velocis
with a network protocol that allows Velocis client to be on a Window-based
computer.  The version of Velocis for BSDI that comes with the BSDI CD-ROM
currently does not have this capability.  This section will still be useful
if you decide to purchase a full, network-enabled version of Velocis later 
on.


6.2  ODBC Administration Utility
------------------------------------------------------------------------------
The ODBC administration utility now provides an additional field entry in 
the configuration dialog box that allows you to specify the name of the 
Velocis server.  By default, the server name is the same as the data source.
However, a given server name can be used with different data sources.  You
can now add as many data source names and servers as you like.  This utility
is automatically invoked by the ODBC installation setup.

6.3  PowerBuilder Usage
------------------------------------------------------------------------------
In order for Velocis to work correctly with PowerBuilder version 4, you will 
need to add the following sections to the PBODB040.INI file in the PB4
directory (for version 3 use PBODB030.INI file in the PB3 directory). 

    [RDS]
    PBNoCatalog='YES'
    PBSpecialDataTypes='RDS_SPECIALDATATYPES'
    PBDateTime='STANDARD_DATETIME'
    PBTrimCharColumns='YES'
    PBQualifierIsOwner='NO'
    DelimitIdentifier='NO'

    [RDS_SPECIALDATATYPES]
    SpecialDataTypes='rowid=DBI_TYPEINT=4'


Also note that since Velocis SQL does not yet support on-line processing
of SQL DDL statements, that sddlp must be used to create tables.  In other 
words, do not attempt to create/alter a database definition with 
PowerBuilder.


6.4  Compatibility with ODBC 3.0
------------------------------------------------------------------------------
The latest ODBC specification introduced by Microsoft is 3.0.  While this
specification, just like 2.0, is supposed to work with the older 1.0, some
instances have been reported that it is not the case.

One instance is the initial allocation functions; namely, SQLAllocEnv( ),
SQLAllocConnect( ) and SQLAllocStmt( ).  You are supposed to be able to use 
those level-1 APIs with ODBC 3.0, which has replaced them with a single
function, SQLAllocHandle( ).  However, it does not work correctly.

We are going to address this problem with Velocis 2.0, which will be fully
compatible with ODBC 2.0.
 

==============================================================================
7. RESTRICTIONS AND KNOWN ISSUES
==============================================================================


7. RESTRICTIONS AND KNOWN ISSUES
--------------------------------
The regular version of Velocis for UNIX is capable of using TCP/IP network 
protocol, allowing a Velocis client on a remote UNIX or Windows computer to
communicate with the server using TCP/IP.

This version of Velocis utilizes shared memory to emulate the network.  Due
to this implementation, restrictions and known issues as below apply:

(a) Both the server and client software must reside on the same BSDI 
    machine.

(b) The number of simultaneous connections to the server is limited to 2.

(c) Velocis creates one memory map file per client connection.  The memory
    map files are located in the temporary directory (typically /tmp).
    When your client logs out of the server abnormally, the corresponding
    map file will not be cleaned up.

(d) Since memory map files are based upon client process IDs, do not 
    remove those files while Velocis server is running.

(e) On some occasions, you may need to reboot your BSDI machine without
    cleanly shutting down Velocis server.  That would cause the active 
    memory map files to remain in the temporary directory.  You need not
    clean them up in order to restart Velocis, however.

(f) The Velocis client establishes the connection to the server through 
    the server name associated with the message queue.  Please do not
    attempt to start two servers with the same name on the machine.

(g) At this point of time, it is not possible to connect to Velocis Server
    from two different UNIX user accounts.  This issue is being investigated
    now.  We shall place updated information as we make progress.


==============================================================================
8. FOR MORE INFORMATION
==============================================================================

8. FOR MORE INFORMATION
-----------------------
The Velocis package contains an additional help file, README.TXT, that is
available after you have completed the installation.  The file contains 
information for the users who are upgrading from previous versions of 
Velocis as well as last minute changes that could not be included in the 
manuals or the other help files.  It also briefly discusses tips for 
performance fine-tuning for Velocis.

For information about other Raima products or how to purchase the complete 
Velocis manual set, upgrades, multi-user licenses and technical support:


    Phone:	1-800-DB-RAIMA (1-800-327-2462)
    Phone:	1-206-515-9477
    Fax:	1-206-748-5200
    Web:	http://www.raima.com
    E-mail:	sales@raima.com

