Opens a database connection.
Arguments: |
The arguments are:
dbFileName [required] |
The file name of the database to open. The special string:memory:can be
used to open an in memory database. ThedbFileNameargument can also be an
URI. Refer to the SQLite documentation for details.
|
dbConn [required] |
The stringnameof a variable in the Rexx program that will be set to the
Handle to the database connection. Note that this is the string name of the
variable, not the variable itself. The variable may, but does not need to, already exist in the program.
|
openFlags [optional] |
One or more of the file File Open Constants constants. This flag controls how the database
is opened. Do not use any constant marked asVFS only. Use ooSQLiteMerge to merge two or more of the constant values to together, if
needed.
The 3 common flags are OPEN_READWRITE, OPEN_READONLY, and OPEN_CREATE. If this argument is omitted, the
OPEN_READWRITE merged with OPEN_CREATE flags are used.
|
reserved [optional] |
This argument is reserved for future enhancement. It is completely ignored in the current implementation.
|
|
Return value: |
Returns one of the SQLite Result Code Constants codes. OK on success, otherwise an error
code.
When the function returns, the variable named by thedbConnargument will always
be set to a handle to the database connection. This is true even if the return code indicates and error.
|
Remarks: |
On success, the database connection handle can be used as an argument in any other function that requires a
database connection handle. To prevent resource leaks, oosqlClose must be
called on each database connection returned byoosqlOpen. This is true even if
oosqlOpenreturns an error. Never use the database connection afteroosqlClosehas been called. This many crash the SQLite database engine.
On error, the handle can be used in the oosqlErrMsg function to obtain a
description of the error. It can also be used in the oosqlErrCode function,
although at this point the return fromoosqlErrCodewill be the same as the
return code fromoosqlOpen. There is one exception to this. If the error return
is NOMEM the handle will be null. Do not use a null handle in any other function.
The oosqlIsHandleNull function can be used to test for a null
handle. However testing for a return of NOMEM is sufficient. The handle will always be null when the return is
NOMEM and not null for any other return.
TheopenFlagsargument is the binaryorvalue
of the individual open constants. If the programmer is comfortable with the binaryoroperation, that can be used instead of theooSQLiteMerge()function.
|
Details |
The functionality of theoosqlOpen()routine is similar to that of the sqlite3_open_v2 SQLite API
|
Example: |
This example opens theooFoods.rdbxdatabase and checks for any errors:
ret = oosqlOpen('ooFoods.rdbx', 'db') |
if ret == .ooSQLite~NOMEM then do |
say 'Unrecoverable error, quitting.' |
return 99 |
end |
|
if oosqlErrCode(db) >.<. .ooSQLite~OK then do |
-- handle the error .. |
oosqlClose(db) |
... |
end |
|
-- We have a good connection, use the database. |
...
|
|