4. SQLkit_JLT functions.

Contents of this section

4.1 open_jlt() : non-socket version

Connect to a Just Logic database. This function must be called before any other SQLkit_JLT function. The non-socket version should be linked with fs_sql.o.

PARAMETERS     : one required, the name of the database.

RETURN VALUE   : integer SQLCODE : zero means success, a negative  
                 number is an error : a positive number is a warning : 
                 see the Just Logic documentation for the exact meaning 
                 of the SQLCODE.
EXAMPLE  :   

LOCAL nRetVal := open_jlt( "abc" )

4.2 open_jlt() : socket version

Connect to a Just Logic database. This function must be called before any other SQLkit_JLT function. The socket version should be linked with fs_sqlnet.o.

PARAMETERS   : three required.

   db_name   :  name of the database

   user_name :  user's login name

   passwd    :  user's password

RETURN VALUE   : integer SQLCODE : zero means success, a negative  
                 number is an error : a positive number is a warning : 
                 see the Just Logic documentation for the exact meaning 
                 of the SQLCODE.
EXAMPLE  :   

LOCAL nRetVal := open_jlt( "abc", "griffin", "MakeMyDay" )

4.3 close_jlt()

Disconnect from a Just Logic database.

PARAMETERS     : none.

RETURN VALUE   : integer SQLCODE : zero means success, a negative  
                 number is an error : a positive number is a warning : 
                 see the Just Logic documentation for the exact meaning 
                 of the SQLCODE.
EXAMPLE  :   

LOCAL nRetVal := close_jlt()

4.4 sql_unlock()

Permit program to retrieve (select) locked records without locking them to other users. Equivalent to the command: set no_read_lock

PARAMETERS     : none.

RETURN VALUE   : integer SQLCODE : zero means success, a negative  
                 number is an error : a positive number is a warning : 
                 see the Just Logic documentation for the exact meaning 
                 of the SQLCODE.
EXAMPLE  :   

LOCAL nRetVal := sql_unlock()

4.5 sql_lock()

Enforce record locking of all retrieved (selected) records and deny this program access to records locked by other users. This is the default behavior of the Just Logic database. This function reverses the effect of sql_unlock(). It is equivalent to the command: set read_lock

PARAMETERS     : none.

RETURN VALUE   : integer SQLCODE : zero means success, a negative  
                 number is an error : a positive number is a warning : 
                 see the Just Logic documentation for the exact
                 meaning of the SQLCODE.
EXAMPLE  :   

LOCAL nRetVal := sql_lock()

4.6 sql_ret()

Retrieve (select) records from a Just Logic database. Equivalent to the command: select * from relname where wclause

PARAMETERS     :  four required.

   relname     :  name of the relation (table) to retrieve from

   wclause     :  the where clause from the select statement, but
                  without the word "where ".  Set wclause to NIL if
                  you wish to retrieve the entire table.

   @tfilename  :  a pointer to a variable that will contain the
                  temporary file name where the retrieved records
                  are stored.

   @fieldcount :  a pointer to a variable that will contain the
                  number of fields making up each retrieved record.

RETURN VALUE   :  A positive integer or zero indicating the number
                  of records retrieved; or a negative number 
                  indicating an error (SQLCODE).  See the Just
                  Logic documentation for the exact meaning of the
                  SQLCODE. For example, -179 indicates you are trying
                  to retrieve locked records. 
                  If zero or a negative number is returned,
                  no temporary file is created.
EXAMPLE  :  

LOCAL relname := "part"
LOCAL wclause := "name like '%' order by name"
LOCAL tfilename := ""
LOCAL fieldcount := 0
LOCAL nRowCount := sql_ret(relname, wclause, @tfilename, @fieldcount)
This will retrieve into a temporary file all records in the part table (``name like '%' '') in ascending ASCII order of the name field. If wclause is set to NIL the same set of records will be returned, but in a different order. Please note that parameters three and four are pointers and must have ``@'' in front of them. Their values are available after sql_ret() returns.

4.7 sql_aret()

Check for the existence of one or more records in a Just Logic database. Although this function does not retrieve data (other than the number of qualifying records), all records selected by it will be locked unless sql_unlock() is called first. It can be used to quickly lock a record, etc.

PARAMETERS     :  two required.

   relname     :  name of the relation (table) to query

   wclause     :  the where clause from the select statement, but
                  without the word "where ".  Set wclause to NIL to
                  to find the number of all records in a table.

RETURN VALUE   :  A positive integer or zero indicating the number
                  of records retrieved; or a negative number 
                  indicating an error (SQLCODE).  See the Just
                  Logic documentation for the exact meaning of the
                  SQLCODE. For example, -179 indicates you are trying
                  to retrieve locked records. 
EXAMPLE  :  

LOCAL nCustCount := sql_aret("customer", NIL)
This example establishes how many records are in the customer table and locks it to other users.

4.8 sql_commit()

Commit to disc any pending updates and unlock all locked records.

PARAMETERS     : none.

RETURN VALUE   : integer SQLCODE : zero means success, a negative  
                 number is an error : a positive number is a warning : 
                 see the Just Logic documentation for the exact
                 meaning of the SQLCODE.
EXAMPLE  :   

LOCAL nRetVal := sql_commit()

4.9 sql_rback()

Rollback any pending updates.

PARAMETERS     : none.

RETURN VALUE   : integer SQLCODE : zero means success, a negative  
                 number is an error : a positive number is a warning : 
                 see the Just Logic documentation for the exact
                 meaning of the SQLCODE.
EXAMPLE  :   

LOCAL nRetVal := sql_rback()

4.10 sql_repl()

Update one or more existing records in a Just Logic database.

PARAMETERS   : three required.

   relname   : name of relation or table to update.

   AtValStr  : attribute value string.

   wclause   : where clause of SQL update statement, but without
               the word "where ".


RETURN VALUE   : integer SQLCODE : zero means success, a negative  
                 number is an error : a positive number is a warning : 
                 see the Just Logic documentation for the exact meaning 
                 of the SQLCODE.
EXAMPLE  :   

LOCAL relname := "employee"
LOCAL AtValStr := "name = 'GRIFFIN', type = 'D', salary = 800000"
LOCAL wclause := "employeetid = 78467"
LOCAL nRetVal := sql_repl( relname, AtValStr, wclause )
The attribute value string consists of one or more attribute value pairs, i.e., a field name followed by `` = '' followed by a value. Attribute value pairs are separated by commas and string values must be surrounded by single quotes. All records matching the where clause will be updated. Updates are not committed to disc until sql_commit() is called. This example is equivalent to the SQL command: update employee set name = 'GRIFFIN', type = 'D', salary = 800000 where employeetid = 78467

4.11 sql_append()

Append (insert) a new record into a Just Logic database table.

PARAMETERS   : three required.

   relname   : name of relation or table to update.

   fields    : a comma delimited list of fields enclosed in 
               brackets.

   values    : a comma delimited list of values enclosed in
               brackets and parallel to the fields above.
               String values must be surrounded by single 
               quotes.

RETURN VALUE  : integer SQLCODE : zero means success, a negative  
                number is an error : a positive number is a warning : 
                see the Just Logic documentation for the exact
                meaning of the SQLCODE.
EXAMPLE  :   

LOCAL cTable := "payor"
LOCAL cFields := "(payortid, name)"
LOCAL cValues := "(29783, 'GRIFFIN')"
LOCAL nRetVal := sql_append( cTable, cFields, cValues )
Appended records are not committed to disc until sql_commit() is called. This example is equivalent to the the SQL command: insert into payor (payortid, name) values (29783, 'GRIFFIN')

4.12 sql_delete()

Delete a record from a Just Logic database.

PARAMETERS    : two required.

   relname    : relation or table in which to find record(s).

   wclause    : where clause of an SQL delete statement,
                but without the word "where ".

RETURN VALUE  : integer SQLCODE : zero means success, a negative  
                number is an error : a positive number is a warning : 
                see the Just Logic documentation for the exact meaning 
                of the SQLCODE.
EXAMPLE  :   

LOCAL nRetVal := sql_delete("part", "name like 'b%'")
This is equivalent to the SQL command: delete from part where name like 'b%'

Deletions are not committed until sql_commit() is called. Until then they may be rolled back by calling sql_rback().


Previous Chapter

Table of contents of this chapter, General table of contents

Top of the document, Beginning of this Chapter