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 ------------------------------------------------------------------------------