|
BEE Script: database dbobj [name=string] [query=string]
[action=string] [matrix=class]
[seek=[num[,num[,num]]]]
[dbid=name]
BEE Tag: <beedatabase dbobj [name=string] [query=string]
[action=string] [matrix=class]
[seek=[num[,num[,num]]]]
[dbid=name]>
In BEE, there is no initialisation or connection to the database before data access operation and no closing or disconnection from the database afterwards. The database can locate at any server as long as the BEE web server has access to the database via the Internet. Also, there are no platform-dependent database operations. All the dependent operations are handled by the system transparently and are completely concealed from the program code.
When writing database access code, you go straight into the data access operation, which is usually a one-liner, then you retrieve the results for display or further processing. This design helps to simplify your web page and reduce risk of error by eliminating the database connection process from your code. It is also more secure way of data access as BEE web sites can access only the database predefined for it at set up time.
At the moment of writing, BEE supports:
n BEE VirtualBase (flat file)
n MySQL
n mSQL
n Microsoft SQL Server
n Oracle 8
n ODBC
n InterBase
n PostgreSQL
n Sybase
In the BEE architecture, database operation is a big topic and needs to be covered in a separate section. Please see "Database Operation" for details.
Parameters
name is a global name uniquely identifying the data access result. This is used internally by the system to avoid resource allocation conflict. It is usually omitted so that the system will generate a unique name for you. If you need to access the "name" value, it is in {dbobj%name}.
Explicitly specifying the name parameter is useful when you want to access the query information stored in the "session" class. You need to use a constant name to guarantee that you get back the same "session" variable. However, BEE store a company of the query information in "session%database" anyway. So you need to define a constant name across sessions only if you have more than one database object to carry across.
Please note that this "name" parameter has nothing to do with the name of the underlying database that the operation is binding to. (The script does not contain any knowledge about the underlying database.)
query is an SQL query statement that operates on the underlying database. For data retrieval, the record set can be accessed via the "database" data type in the "var" command or in a "foreach" loop. If "query" is specified, parameters "action" and "matrix" will be ignored.
action is an advanced query method that draws input arguments from the matrix and the database object (named by dbobj in the "database" command). Besides data access, "action" can also be used to manipulate the "BEE VirtualBase" table ("create", "load", "unload", "showcreatetable" and "showinsertinto") and roll-back record retrieval ("push").
If the value of "action" is preceded by an "!", the operation will stop after deriving the SQL statement but before executing it. The resulting SQL statement will be stored in dbobj%query as usual. This is useful in debugging or testing to let the programmer to check that the SQL statement is right before applying it physically to the database.
Parameter "action" is a big topic and deserves a separate section. Please see "Database Action".
(Parameter "action" is ignored if parameter "query" is specified)
matrix specifies a class of variables each contains a data row, indexed by a key value. e.g. "matrix%12:Tel" represent the "Tel" column of row "12" (the row that is indexed by "12", not the 12th row.) The list of keys (the variable names) are held in dbobj%keys, and the list of fields (the element names) in dbobj%fields. The default value of "matrix" is "matrix".
Please note that like any object reference, the matrix class is locally referenced unless explicitly declared as "global" or "parent".
(Parameter "matrix" is ignored if parameter "query" is specified)
seek specifies the position in the retrieved record set where the record fetching will start. The default is "seek=1", which means to start fetching from the first record. "seek=last", "seek=end" and "seek=bottom" all mean that the fetching will get the last record. "seek=random" will start the fetching on a record randomly selected between the first one and the last inclusively. Subsequent fetches after "seek=random" will remain sequential following the randomly selected record.
The position in parameter "seek" can be optionally followed by two more values: "records per page" and "pages per block". This is useful for paging the display of the record set, and is described in "Paging the Data Display". (If either of these two values are specified, the "seek" position will be automatically adjusted to the first record in the page.)
dbid is an identifier to the database if there are more than one database associating with the URL of the web page where the request is originated from. This parameter is rarely used even when you have different database to access, because the URL is sufficient to identify the database to use. It is only when you want to access multiple databases from the SAME page that you need to use "dbid" to indicate which one to use. (The value of "dbid" is an identifier defined at set up time of the web site, NOT the name of the underlying database.)
After calling the function, many BEE Variables are made available. Please see "Database Variables".
|