VIPER Database Engine (TM) (PREVIEW RELEASE 0.9.2)


REXX Language API  
Copyright (c) - 1995 by Douglas A. Bebber



This document provides a brief function reference for the VIPER Database Engine - REXX API.
Detailed information will be provided in the VIPER Database Engine (version 1.0.0) Technical
Reference Manual. 

NOTE:  The complete VIPER Database Engine source code will be made freely available in a 
subsequent release.

This PREVIEW RELEASE of the VIPER Database Engine for OS/2 is being made available in
an effort to accelerate the version 1.0.0 general release. Consider this PREVIEW RELEASE to
be similar to a beta test period. I would like to obtain as much feedback as possible concerning
bug reports and general usage in an effort to make any necessary changes prior to the version
1.0.0 general release.

Technical information for this PREVIEW RELEASE 0.9.2 concerns only the REXX API. Similar
information concerning the C-Language API will be made in the PREVIEW RELEASE 0.9.5 .

Library Registration of all VIPER functions can be performed by calling the SysLoadViperFuncs
call in the VIPER.DLL. Previous releases used SysLoadFuncs call. The SysLoadViperFuncs replaces
the older SysLoadFuncs.

Please send any suggested additions or corrections to:

Douglas A. Bebber

CompuServe: 72123,3661
Internet: 72123.3661@compuserve.com

-----------------------------------------------------------------------------
             VIPER Database Engine for OS/2 REXX API Function Reference
-----------------------------------------------------------------------------
NOTE: All functions return 1 if successfull, 0 if an error resulted. Search functions are the
exception. See the Search function descriptions for the details.

RxViperAddRecord

Description:

This function adds a record to a database. All database indexes are updated.

Syntax:

rc = RxViperAddRecord(DatabaseName, IndexName, FieldValues.)

where:
        DatabaseName is a string containing the filename for the new database.
        IndexName specifies a database index.
        FieldValues. is a REXX stem variable containing the record information.
        Each element of the REXX stem variable constitues a field. The first
        element (FieldValues.0) contains the number of fields in the record.

Example:
                CREATEDB.CMD

-----------------------------------------------------------------------------

RxViperCloseDatabase

Description:

This function closes an open database.

Syntax:

rc = RxViperCloseDatabase(DatabaseName)

where:
                DatabaseName is a string containing the filename of the open database.
        
Example:
                CREATEDB.CMD

-----------------------------------------------------------------------------


RxViperCopyDatabase

Description:

This function copies a database and its associated indexes.

Syntax:

rc = RxViperCopyDatabase(CurrentName, NewName, RefIndex, BlockSize)

where:
                CurrentName is a string containing the filename of the source database.
                NewName is a string containing the filename of the new database.
                RefIndex is the source index to reference during the copy process.
                BlockSize (specifying 0 uses the default block size).
        
Example:
                COPYDB.CMD

-----------------------------------------------------------------------------


RxViperCreateDatabase

Description:

This function creates and opens a database for use.

Syntax:

rc = RxViperCreateDatabase(DatabaseName, FieldDefinition.)

where:
        DatabaseName is a string containing the filename for the new database.
        FieldDefinition is a REXX stem variable containing the database field definition.
        FieldDefinition.0 contains the number of fields. FieldDefinition.1 - FieldDefinition.X
        contain the field names.

Example:
                CREATEDB.CMD

-----------------------------------------------------------------------------


RxViperCreateIndex

Description:

This function creates an index for the specified database.

Syntax:

rc = RxViperCreateIndex(DatabaseName, IndexName, KeyFields.)

where:
        DatabaseName is a string containing the filename of the database.
      
        IndexName specifies the name of the new index.
        
        KeyFields. is a REXX stem variable containing the index key fields.
        KeyFields.0 contains the number of key fields in the index. KeyFields.1 - KeyFields.X
        contain the key field names.

Example:
                CREATEDB.CMD


-------------------------------------------------------------------------------


RxViperCreateNewIndexFile

Description:

This function creates a new index file for the specified database.

Syntax:

rc = RxViperCreateNewIndexFile(DatabaseName, BlockSize, OverWriteFlag)

where:
        DatabaseName is a string containing the filename of the database.
      
        Block size for the new index file (0 uses default).
        
        OverWriteFlag specifies whether or not to overwrite an existing index file
        if it exists. 0 = no overwrite, 1 = yes overwrite.



-------------------------------------------------------------------------------


RxViperDeleteRecord

Description:

This function deletes the current database record using the specified index for the
specified database.

Syntax:

rc = RxViperDeleteRecord(DatabaseName, IndexName )

where:
                DatabaseName is a string containing the filename of the open database.
        
                IndexName is the name of the index to position realitive to.

                
Example:
                DELREC.CMD


-------------------------------------------------------------------------------


RxViperDestroyDatabase

Description:

This function deletes the current database and index files.

Syntax:

rc = RxViperDestroyDatabase(DatabaseName )

where:
                DatabaseName is a string containing the filename of the open database.
        
                

                
Example:
                DESTRYDB.CMD


-------------------------------------------------------------------------------


RxViperDestroyIndex

Description:

This function deletes the specified index.

Syntax:

rc = RxViperDestroyIndex(DatabaseName, IndexName )

where:
                DatabaseName is a string containing the filename of the open database.
        
                IndexName is a string containing the name of the index to destroy.
                

                


-------------------------------------------------------------------------------


RxViperFlushDatabaseBuffers

Description:

This function writes buffered database changes to disk. The info is written to disk during the call.

Syntax:

rc = RxViperFlushDatabaseBuffers(DatabaseName)

where:
                DatabaseName is a string containing the filename of the open database.
        

-----------------------------------------------------------------------------


RxViperGetFieldNames

Description:

This function gets the names of the fields present in the specified database.

Syntax:

rc = RxViperGetFieldNames(DatabaseName, FieldNames. )

where:
                DatabaseName is a string containing the filename of the open database.

                FieldNames. is a REXX stem variable that will contain the name of every
                database field upon return.

Note:           FieldNames.0 will contain the number of fields in the database. If you need
                to know the names of the fields as well as the number of fields in a database,
                you can use this single call to get the desired info. You do not need to make a
                separate call to GetNFields in this case.
        
Example:
                DBINFO.CMD


-------------------------------------------------------------------------------



RxViperGetIndexDescription

Description:

This function gets the description of the the specified index for the specified database.

Syntax:

rc = RxViperGetIndexDescription(DatabaseName, IndexName, IndexDescription. )

where:
                DatabaseName is a string containing the filename of the open database.

                IndexName is the name of the index to be described.

                IndexDescription. is a REXX stem variable that will contain the name of every
                database field which makes up the index. IndexNames.0 will contain the total 
                number of fields which make up the index. The ordering of the stem variable is
                the same as the index field order.

        
Example:
                DBINFO.CMD


-------------------------------------------------------------------------------


RxViperGetIndexNames

Description:

This function gets the names of the indexes available for the specified database.

Syntax:

rc = RxViperGetIndexNames(DatabaseName, IndexNames. )

where:
                DatabaseName is a string containing the filename of the open database.

                IndexNames. is a REXX stem variable that will contain the name of every
                database index upon return. IndexNames.0 will contain the total number of
                indexes defined for the database.

        
Example:
                DBINFO.CMD


-------------------------------------------------------------------------------



RxViperGetNFields

Description:

This function gets the number of fields present in the specified database.

Syntax:

rc = RxViperGetNFields(DatabaseName )

where:
                DatabaseName is a string containing the filename of the open database.
        
Example:
                GETNFLDS.CMD


-------------------------------------------------------------------------------


RxViperGetRecord

Description:

This function gets the current database record using the specified index for the
specified database.

Syntax:

rc = RxViperGetRecord(DatabaseName, IndexName, Fields.)

where:
                DatabaseName is a string containing the filename of the open database.
        
                IndexName is the name of the index to position realitive to.

                Fields. is the REXX stem variable to contain the returned database record.
Example:
                GETREC.CMD


-------------------------------------------------------------------------------


RxViperMarkRecord

Description:

This function marks the current record in the database using the specified index. This function
used in conjunction with the MoveToMarkedRecord is for implementing place holders.

Syntax:

rc = RxViperMarkRecord(DatabaseName, IndexName)

where:
                DatabaseName is a string containing the filename of the open database.
        
                IndexName is the name of the index to position realitive to.
Example:
                MARKREC.CMD


------------------------------------------------------------------------------


RxViperMatchKey

Description:

This function determines if the current record in the database (using specified index) matches
the key specified in the Key. function argument.

Syntax:

rc = RxViperMatchKey(DatabaseName, IndexName, Key.)

where:
                DatabaseName is a string containing the filename of the open database.
        
                IndexName is the name of the index to position realitive to.

                Key. is the REXX stem variable to contain the key for matching.


-------------------------------------------------------------------------------



RxViperMoveToFirstRecord

Description:

This function moves the database cursor to the first record of the specified index for the
specified database.

Syntax:

rc = RxViperMoveToFirstRecord(DatabaseName, IndexName)

where:
                DatabaseName is a string containing the filename of the open database.
        
                IndexName is the name of the index to position realitive to.
Example:
                GETREC.CMD


------------------------------------------------------------------------------


RxViperMoveToLastRecord

Description:

This function moves the database cursor to the last record of the specified index for the
specified database.

Syntax:

rc = RxViperMoveToLastRecord(DatabaseName, IndexName)

where:
                DatabaseName is a string containing the filename of the open database.
        
                IndexName is the name of the index to position realitive to.
Example:
                GETREC.CMD


------------------------------------------------------------------------------


RxViperMoveToMarkedRecord

Description:

This function moves the database cursor to a previously marked record. The specified index 
is referenced for the specified database.

Syntax:

rc = RxViperMoveToMarkedRecord(DatabaseName, IndexName)

where:
                DatabaseName is a string containing the filename of the open database.
        
                IndexName is the name of the index to position realitive to.
Example:
                MARKREC.CMD


------------------------------------------------------------------------------


RxViperMoveToNextRecord

Description:

This function moves the database cursor to the next record of the specified index for the
specified database.

Syntax:

rc = RxViperMoveToNextRecord(DatabaseName, IndexName)

where:
                DatabaseName is a string containing the filename of the open database.
        
                IndexName is the name of the index to position realitive to.
Example:
                GETREC.CMD

------------------------------------------------------------------------------

RxViperMoveToPreviousRecord

Description:

This function moves the database cursor to the previous record of the specified index for the
specified database.

Syntax:

rc = RxViperMoveToPreviousRecord(DatabaseName, IndexName)

where:
                DatabaseName is a string containing the filename of the open database.
        
                IndexName is the name of the index to position realitive to.
Example:
                GETREC.CMD


------------------------------------------------------------------------------



RxViperOpenDatabase

Description:

This function opens a database and the associated index for use.

Syntax:

rc = RxViperOpenDatabase(DatabaseName, IndexName)

where:
                DatabaseName is a string containing the filename of the database.
                IndexName is a string containing the name of the index to use.
        
Example:
                GETREC.CMD

-----------------------------------------------------------------------------


RxViperRenameDatabase

Description:

This function renames a database and its associated index file.

Syntax:

rc = RxViperRenameDatabase(CurrentName, NewName)

where:
                CurrentName is a string containing the filename of the source database.

                NewName is a string containing the new filename of the database.
        

-----------------------------------------------------------------------------


RxViperSearchKey

Description:

This function searches the database for a specific record using specified index. The search
criteria is placed in the functions KeyFields. parameter.

Syntax:

rc = RxViperSearchKey(DatabaseName, IndexName, KeyFields. )

where:
                DatabaseName is a string containing the filename of the open database.
        
                IndexName is the name of the index to search on.

                KeyFields. is a REXX stem variable containing the index key search criteria.

Returns:        0 on error.
                1 if found.
                2 if not found (moved to the closest matching record).
Example:
                SEARCHKY.CMD


------------------------------------------------------------------------------

RxViperSearchRecord

Description:

This function searches the database on the specified index for the record contained in the
RecordInfo. REXX stem variable argument. 

Syntax:

rc = RxViperSearchRecord(DatabaseName, IndexName, RecordInfo. )

where:
                DatabaseName is a string containing the filename of the open database.
        
                IndexName is the name of the index to search on.

                RecordInfo. is a REXX stem variable containing the record search criteria.

Returns:        0 if error.
                1 if found.
                2 if not found.


------------------------------------------------------------------------------




RxViperUpdateRecord

Description:

This function is used to change an existing record in the database.

Syntax:

rc = RxViperUpdateRecord(DatabaseName, IndexName, FieldValues.)

where:
                DatabaseName is a string containing the filename of the open database.
        
                IndexName is the name of the index to position realitive to.

                FieldValues. is a REXX stem variable containing the new record information.
Example:
                UPDATREC.CMD


------------------------------------------------------------------------------

