When using the Sqlite() function the recommended way to retrieve the data is via the SqlGet() function. The two main benefits are:
1. Speed - this is the most efficient and quickest way to read the data.
2. Accuracy - the data from the database is returned verbatim, so you don't have to worry about field and record delimiters (which can be confusing when you get the data without using SqlGet().
However, the biggest problem with SqlGet() is that it only supports one "level" of use. That is, it can't be nested. For example, you can't start reading the caches table and then inside the same loop start reading the logs table.
Build 83 removes this limitation and you can now have up to 5 levels of nesting. We have introduced the concept of a "handle" and each instance of SqlGet has an associated handle (0..4). All related SqlGet commands and options must use the same Handle as the original instance.
For backwards compatibility, existing code should work "as is" without any need to change. Existing code will default to handle "0", which doesn't need to be explicity coded (when left out all SqlGet related commands/functions default to handle "0")
There are 5 associated "parts" to SqlGet and each now support the use of a "handle". If no handle is given then the default "0" is used.
1. Sqlite() - As before, this is the function that initializes your Sqlite query and to put your query into SqlGet mode you add the option "SqlGet=Yes". The only change now is that you can (optionally) add the "handle" to the end of "Yes". For example:
As we haven't explicitly added a handle number, the default of "0" is used. So this line of code is exactly the same as:
Similarly, other handles are accessed by appending the required handle number to "yes". For example, to start a query using handle 2 the code would be:
2. SqlGet() - This is the function that actually retrieves the data from the query. It now supports and additional parameter which is the "handle" (a number from 0..4) that correlates to the initial sqlite query that was opened. If you leave out the additional parameter, then internally the handle is set to 0
3. SqlNext - This is the command that enables you to move to the next record in the query. We have now added the Handle= paramater to enable it to be tied to the corresponding query. If omitted the SqlNext will operate on Handle 0
4. $_SqlEol - this is the system variable that you usually test in a loop to see if there are any more records to process. Just add the associated handle number to the end of this variable (if none is added, then 0 is assumed)
5. SqlGetClose - This command allows you to close a SqlGet query. All SqlGet queries *must* be closed (otherwise it leaves a dangling handle which will cause strange error messages when trying to use Sqlite). In reality you problably don't need to use this function often as the SqlGet query is automatically closed when you reach the end of the list via the SqlNext command. That is, most times you use SqlGet you will iterate over the entire result set, so the SqlGet query will automatically be closed for you. However there are times when you might "Break" out of a read loop before reaching the end of the list and hence you must then use this command to make sure the SqlGet query is closed. Similar to the SqlNext command we have added the optional Handle= parameter and it operates in a similar fashion.
Probably the best way to get a "handle" (sorry for the pun) on this is to see some example code. The following macro doesn't really do too much that would be called "useful" but it should give a good idea how to "nest" SqlGet queries. The following code will just loop through 5 random caches in your database and show a message for each that lists the name and date of 5 associated logs
Note: As per the comments for the SqlGetClose command, both in this macro are not *needed* (we read all the records so an automatic close is done for us) However, it is a good habit to get into as it might save you some serious debugging time when an automatic close has not been done.
1. Speed - this is the most efficient and quickest way to read the data.
2. Accuracy - the data from the database is returned verbatim, so you don't have to worry about field and record delimiters (which can be confusing when you get the data without using SqlGet().
However, the biggest problem with SqlGet() is that it only supports one "level" of use. That is, it can't be nested. For example, you can't start reading the caches table and then inside the same loop start reading the logs table.
Build 83 removes this limitation and you can now have up to 5 levels of nesting. We have introduced the concept of a "handle" and each instance of SqlGet has an associated handle (0..4). All related SqlGet commands and options must use the same Handle as the original instance.
For backwards compatibility, existing code should work "as is" without any need to change. Existing code will default to handle "0", which doesn't need to be explicity coded (when left out all SqlGet related commands/functions default to handle "0")
There are 5 associated "parts" to SqlGet and each now support the use of a "handle". If no handle is given then the default "0" is used.
1. Sqlite() - As before, this is the function that initializes your Sqlite query and to put your query into SqlGet mode you add the option "SqlGet=Yes". The only change now is that you can (optionally) add the "handle" to the end of "Yes". For example:
| GSK |
$status = Sqlite("sql","select * from caches","SqlGet=yes") |
As we haven't explicitly added a handle number, the default of "0" is used. So this line of code is exactly the same as:
| GSK |
$status = Sqlite("sql","select * from caches","SqlGet=Yes0") |
Similarly, other handles are accessed by appending the required handle number to "yes". For example, to start a query using handle 2 the code would be:
| GSK |
$status = Sqlite("sql","select * from caches","SqlGet=Yes2") |
2. SqlGet() - This is the function that actually retrieves the data from the query. It now supports and additional parameter which is the "handle" (a number from 0..4) that correlates to the initial sqlite query that was opened. If you leave out the additional parameter, then internally the handle is set to 0
3. SqlNext - This is the command that enables you to move to the next record in the query. We have now added the Handle= paramater to enable it to be tied to the corresponding query. If omitted the SqlNext will operate on Handle 0
4. $_SqlEol - this is the system variable that you usually test in a loop to see if there are any more records to process. Just add the associated handle number to the end of this variable (if none is added, then 0 is assumed)
5. SqlGetClose - This command allows you to close a SqlGet query. All SqlGet queries *must* be closed (otherwise it leaves a dangling handle which will cause strange error messages when trying to use Sqlite). In reality you problably don't need to use this function often as the SqlGet query is automatically closed when you reach the end of the list via the SqlNext command. That is, most times you use SqlGet you will iterate over the entire result set, so the SqlGet query will automatically be closed for you. However there are times when you might "Break" out of a read loop before reaching the end of the list and hence you must then use this command to make sure the SqlGet query is closed. Similar to the SqlNext command we have added the optional Handle= parameter and it operates in a similar fashion.
Probably the best way to get a "handle" (sorry for the pun) on this is to see some example code. The following macro doesn't really do too much that would be called "useful" but it should give a good idea how to "nest" SqlGet queries. The following code will just loop through 5 random caches in your database and show a message for each that lists the name and date of 5 associated logs
| GSK |
$Status = sqlite("sql","select * from caches limit 5","sqlget=yes") While not($_SqlEol) $code = SqlGet("Code") $data = $Code + ": " + SqlGet("Name") + $_CrLf $Status = sqlite("sql","select * from logs where lparent = '$code' limit 5","sqlget=yes1") While not($_SqlEol1) $data = $data + " " + SqlGet("lby",1) + ": " + SqlGet("ldate",1) + $_CrLf SqlNext Handle=1 Endwhile SqlGetClose Handle=1 MsgOk Msg=$data SqlNext EndWhile SqlGetClose |
Note: As per the comments for the SqlGetClose command, both in this macro are not *needed* (we read all the records so an automatic close is done for us) However, it is a good habit to get into as it might save you some serious debugging time when an automatic close has not been done.