Through the MPE/iX & TurboImage extension , PHP supports the generation of web pages directly from an Image database.
The intention is to create higher level functions that shield the script writer from some of the intricacies of Image intrinsics, while hopefully enhancing performance under most conditions. I shall be interested to hear from anyone who has ideas regarding the script writer's function library. Code fragments or other suggestions for implementation will also be appreciated.
The functions created to date may be divided into several categories:
| Higher level functions: | |
| Miscellaneous functions: | |
| Information functions: | |
| Basic functions: | |
| php.ini settings: |
|
mpe_dbopen -- Connect to a TurboImage database
int mpe_dbopen(string dbname,
string password [,int dbopenmode]);
Returns an database resource_id or NULL on error.
The resource_id returned by this functions is needed by the other TurboImage functions. You can have multiple databases open at once.
dbname is in the form DBNAME[.GROUP[.ACCOUNT]].
The optional dbopenmode parameter overrides the default DBOPEN mode,
set in php.ini. If this setting, turboimage.dbopen_mode, is missing from
php.ini, the default mode is mode 5, read only, shared access.
The database connection is closed automatically when its resource
identifier goes out of scope. A
mpe_dbclose(resource_id) function is available
but is not necessary due to PHP's automatic clean up.
Example:
<?php
$db = mpe_dbopen("MUSIC.DATA","MGR");
if($db !== FALSE)
print "Opened OK";
unset($db); /* close the database */
?>
|
mpe_dbfind -- Keyed search
int mpe_dbfind(int resource_id,
string dataset, string item, searchvalue);
Searches for the first occurrence of dataset.item = searchvalue. Returns TRUE if found, FALSE if not found, or NULL on error.
If dataset.item is a compound item, searchvalue must be an array.
Uses DBFIND mode=10. Applies to detail sets only.
Example:
<?php
if(mpe_dbfind($db, "Selections", "albumcode", 2001))
print "Found";
else
print "NOT FOUND";
?>
|
mpe_dbget -- Retrieve a record from the database
int mpe_dbget(int resource_id,
string dataset, int mode [, searchvalue]);
If successful, returns the record number of the current record.
Returns zero when the condition code implies no more records to find. ie START_OF_DATA_SET, END_OF_DATA_SET, DIRECTED_START_OF_FILE, DIRECTED_END_OF_FILE, START_OF_CHAIN, END_OF_CHAIN, NO_SUCH_ENTRY.
Returns NULL on error.
Constants are defined for the various DBGET modes:
mpe_dbresult_assoc -- Returns the results of a dbget.
array mpe_dbresult_assoc(int resource_id, string dataset);
Returns an associative array containing all accessible items in the record
previously retrieved by mpe_dbget.
Returns NULL on error.
Example:
<?php
while (mpe_dbget($db, "SELECTIONS", DBGET_MODE_CHAINED_READ))
{
$r = mpe_dbresult_assoc($db, "SELECTIONS");
print("<TR>\n");
foreach($r as $x)
print " <TD>$x</TD>\n";
print("</TR>\n");
}
?>
|
mpe_dbresult_item -- Returns the results of a dbget for a single item.
mixed mpe_dbresult_item(int resource_id,
string dataset, string itemname);
Returns the value of one item in the record previously retrieved by
mpe_dbget.
Returns NULL on error.
Example:
<?php
if (mpe_dbget($db, "albums", DBGET_MODE_CALCULATED_READ, 2003))
{
$t = mpe_dbresult_item($db, "albums", "albumtitle");
print "Album title = $t";
}
?>
|
mpe_dbreset -- Reinitialize a dataset.
boolean mpe_dbreset(int resource_id,string dataset);
Reinitialize a dataset. May be required before
mpe_dbget mode DBGET_MODE_SERIAL_READ or
DBGET_MODE_BACK_SERIAL_READ if the set has previously been
accessed by the current script. Calls DBCLOSE mode 3;
Returns NULL on error.
Example:
<?php mpe_dbreset($db, "selections"); ?> |
mpe_dblock_base -- Unconditionally lock a database.
boolean mpe_dblock_base(int resource_id);
Apply an unconditional lock to an entire database. Returns TRUE if the database was locked successfully. Calls DBLOCK mode 1.
Note that PHP/iX is not linked with MR capability. Therefore only one lock can be applied at a time. This function will remove any other lock before locking the database.
Any explicit lock is applied by this function disables
automatic locking by mpe_dbget_serial,
mpe_dbget_serial_back, mpe_dbget_chain,
mpe_dbget_chain_back, mpe_dbget_dblookup,
mpe_dbput, mpe_dbdelete and
mpe_dbupdate.
Use mpe_dbunlock to remove the lock.
Returns NULL on error.
Example:
<?php
if(mpe_dblock_base($db)) {
print "Database locked\n";
}
?>
|
mpe_dblock_set -- Unconditionally lock a dataset.
boolean mpe_dblock_set(int resource_id, string dataset);
Apply an unconditional lock to an entire dataset. Returns TRUE if the set was locked successfully. Calls DBLOCK mode 3.
Note that PHP/iX is not linked with MR capability. Therefore only one lock can be applied at a time. This function will remove any other lock on the database before locking the selected set.
Any explicit lock is applied by this function disables
automatic locking by mpe_dbget_serial,
mpe_dbget_serial_back, mpe_dbget_chain,
mpe_dbget_chain_back, mpe_dbget_dblookup,
mpe_dbput, mpe_dbdelete and
mpe_dbupdate.
Use mpe_dbunlock to remove the lock.
Returns NULL on error.
Example:
<?php
if(mpe_dblock_set($db, "SELECTIONS")) {
print "SELECTIONS locked\n";
}
?>
|
mpe_dbunlock -- Unlock a database.
boolean mpe_dbunlock(int resource_id);
Relinquishes all locks on a database. Returns TRUE if the database was unlocked successfully. Calls DBUNLOCK.
Returns NULL on error.
Example:
<?php mpe_dbunlock($db); ?> |
mpe_dbinfo_list_sets -- List all sets in a database
array mpe_dbinfo_list_sets(int resource_id);
Returns an array containing the names of all sets in the database which are accessible using the current password.
Uses DBINFO modes 203 and 202.
Returns NULL on error.
Example:
<?php
$sets = mpe_dbinfo_list_sets($db);
foreach($sets as $n => $set) {
print "Set $n = $set\n";
}
?>
|
mpe_dbinfo_list_items -- List all items in a dataset
array mpe_dbinfo_list_items(int resource_id, string dataset);
Returns an associative array containing the types of all items in a dataset, indexed by item name, where these items are accessible using the current password.
Uses DBINFO modes 104 and 102.
Returns NULL on error.
Example:
<?php
$items = mpe_dbinfo_list_items($db,"SELECTIONS");
foreach($items as $item => $type) {
print "$item $type\n";
}
?>
|
mpe_dbinfo_list_paths -- List search items and associated master sets for a dataset
array mpe_dbinfo_list_paths(int resource_id, string dataset);
Returns an associative array containing the master sets associated with all search items in a dataset, indexed by search item name, where these items are accessible using the current password. If a set has no search items, then an empty array is returned.
Uses DBINFO modes 301 and 202.
Returns NULL on error.
Example:
<?php
$items = mpe_dbinfo_list_paths($db,"SELECTIONS");
foreach($items as $item => $path) {
print "$item $path\n";
}
?>
|
mpe_dbinfo_list_sorts -- List search items and associated master sets for a dataset
array mpe_dbinfo_list_sorts(int resource_id, string dataset);
Returns an associative array containing any sort items associated with search items in a dataset, indexed by search item name, where these items are accessible using the current password. If a dataset has no sorted paths, then an empty array is returned.
Uses DBINFO modes 301.
Returns NULL on error.
Example:
<?php
$items = mpe_dbinfo_list_sorts($db,"SELECTIONS");
foreach($items as $item => $sort_item) {
print "$item $sort_item\n";
}
?>
|
mpe_dbinfo_entry_count -- Retrieves a dataset's entry count
int mpe_dbinfo_entry_count(int resource_id, string dataset);
Returns the number of entries (records) in a dataset.
Uses DBINFO mode 202.
Returns NULL on error.
Example:
<?php print "Records = " . mpe_dbinfo_entry_count($db, "SELECTIONS") . "\n"; ?> |
mpe_dbget_serial -- Retrieves multiple records using a forward serial read.
array mpe_dbget_serial(int resource_id, string dataset,
string/array get_items[, int MAX_COUNT]);
Reads a set forwards, starting at the first record, until MAX_COUNT
records have been read. If MAX_COUNT is not specified, then the value
specified in turboimage.dbget_count is used.
Unconditionally locks the set (mode 3) before retrieving the records
and unlocks the set afterwards.
No lock is applied if there an explicit lock placed by
mpe_dblock_set or mpe_dblock_base,
or if the database was opened in a mode other than 1 or 5.
For detail sets, returns an array of records, indexed by record number. For master sets, returns an array of records, indexed by search item value.
If no records are found, a null length array is returned.
If get_items is an array of strings, each record will consist of an array of the items listed in get_items. If get_items is NULL, each record will consists of an array of all items in the set. If get_items is a single string, each record returned will consist of a single value.
Returns NULL on error.
Example:
<?php
$recs = mpe_dbget_serial($db, "Albums", NULL, 100);
if(count($recs) > 0) {
print "<TABLE>\n";
foreach($recs as $rec) {
print "<TR>\n";
foreach($rec as $data) {
print "<TD>$data</TD>\n";
}
print "</TR>\n";
}
print "</TABLE>\n";
}
unset($recs);
?>
|
mpe_dbget_serial_back -- Retrieves multiple records using a backwards serial read.
array mpe_dbget_serial_back(int resource_id, string dataset,
string/array get_items[, int MAX_COUNT]);
Reads a set backwards, starting at the last record, until MAX_COUNT
records have been read. If MAX_COUNT is not specified, then the value
specified in turboimage.dbget_count is used.
Unconditionally locks the set (mode 3) before retrieving the records
and unlocks the set afterwards.
No locking is done if there any lock has been explicity
applied by mpe_dblock_set or mpe_dblock_base.
For detail sets, returns an array of records, indexed by record number. For master sets, returns an array of records, indexed by search item value.
If no records are found, a null length array is returned.
If get_items is an array of strings, each record will consist of an array of the items listed in get_items. If get_items is NULL, each record will consists of an array of all items in the set. If get_items is a single string, each record returned will consist of a single value.
Returns NULL on error.
Example:
<?php
$recs = mpe_dbget_serial_back($db, "Composers", array("ComposerName","BirthPlace") ,100);
print "<TABLE>\n";
foreach($recs as $recnum => $rec) {
print "<TR>\n<TD>\n$recnum\n</TD>\n";
foreach($rec as $item) {
print "<TD>\n$item\n</TD>\n";
}
print "</TR>\n";
}
unset($recs);
print "</TABLE>\n";
?>
|
mpe_dbget_chain -- Retrieves multiple records using a chained read.
array mpe_dbget_chain(int resource_id, string dataset,
string search_item, searchvalue, string/array get_items[, int MAX_COUNT]);
Executes a find (mode=10), and then reads the chain, until MAX_COUNT
records have been read. If MAX_COUNT is not specified, then the value
specified in turboimage.dbget_count is used.
Places an unconditional item level lock (mode=5) on the set before
retrieving the records and unlocks the set afterwards.
No lock is applied if there an explicit lock placed by
mpe_dblock_set or mpe_dblock_base,
or if the database was opened in a mode other than 1 or 5.
If dataset is a master, this function executes a calculated read, returning an array of a single record.
For detail sets, returns an array of records, indexed by record number. For master sets, returns an array of records, indexed by search item value.
If no records are found, a null length array is returned.
If get_items is an array of strings, each record will consist of an array of the items listed in get_items. If get_items is NULL, each record will consists of an array of all items in the set. If get_items is a single string, each record returned will consist of a single value.
Returns NULL on error.
Example:
<?php
print "<TABLE>\n";
$recs = mpe_dbget_chain($db, "Selections", "AlbumCode", 2001, "SelectionName", 100);
foreach($recs as $recnum => $data) {
print "<TR><TD>$recnum</TD><TD>$data</TD></TR>\n";
}
unset($recs);
print "</TABLE>\n";
?>
|
mpe_dbget_chain_back -- Retrieves multiple records using a backwards chained read.
array mpe_dbget_chain_back(int resource_id, string dataset,
string search_item, searchvalue, string/array get_items[, int MAX_COUNT]);
Executes a find (mode=10), and then reads the chain backwards, until MAX_COUNT
records have been read. If MAX_COUNT is not specified, then the value
specified in turboimage.dbget_count is used.
Places an unconditional item level lock (mode 5) on the set before
retrieving the records and unlocks the set afterwards.
No lock is applied if there an explicit lock placed by
mpe_dblock_set or mpe_dblock_base,
or if the database was opened in a mode other than 1 or 5.
If dataset is a master, this function executes a calculated read, returning an array of a single record.
For detail sets, returns an array of records, indexed by record number. For master sets, returns an array of records, indexed by search item value.
If no records are found, a null length array is returned.
If get_items is an array of strings, each record will consist of an array of the items listed in get_items. If get_items is NULL, each record will consists of an array of all items in the set. If get_items is a single string, each record returned will consist of a single value.
Returns NULL on error.
Example:
<?php
$recs = mpe_dbget_chain_back($db, "Albums", "AlbumCode", 2003, "", 100);
print "<TABLE>\n";
foreach($recs as $rec) {
print "<TR>\n";
foreach($rec as $item) {
print "<TD>\n$item\n</TD>\n";
}
print "</TR>\n";
}
unset($recs);
print "</TABLE>\n";
?>
|
mpe_dbget_btree -- Retrieves multiple records using a chained read.
array mpe_dbget_btree(int resource_id, string dataset,
string search_item, string search_type, searchvalue1[ ,searchvalue2],
string/array get_items[, int MAX_COUNT]);
search_type must be one of '=','<','<=','>','>=','[]','@c','PK'. searchvalue2 is required when search_type is '[]'.
Executes a find (mode=4), and then reads the chain, until MAX_COUNT
records have been read. If MAX_COUNT is not specified, then the value
specified in turboimage.dbget_count is used.
Cuurrently places an unconditional lock on the set (mode=3) before
retrieving the records and unlocks the set afterwards. It is intended
to change this to item level locking.
No lock is applied if there an explicit lock placed by
mpe_dblock_set or mpe_dblock_base,
or if the database was opened in a mode other than 1 or 5.
A btree must be defined in the database for the specified search item.
For detail sets, returns an array of records, indexed by record number. For master sets, returns an array of records, indexed by search item value.
If no records are found, a null length array is returned.
If get_items is an array of strings, each record will consist of an array of the items listed in get_items. If get_items is NULL, each record will consists of an array of all items in the set. If get_items is a single string, each record returned will consist of a single value.
Returns NULL on error.
Example:
<?php
print "<TABLE>\n";
$recs = mpe_dbget_btree($db,'COMPOSERS','ComposerName','[]','C','J','ComposerName');
foreach($recs as $data) {
print "<TR><TD>$data</TD></TR>\n";
}
unset($recs);
print "</TABLE>\n";
?>
|
mpe_dbget_btree_back -- Retrieves multiple records using a backwards chained read.
array mpe_dbget_btree_back(int resource_id, string dataset,
string search_item, string search_type, searchvalue1[ ,searchvalue2],
string/array get_items[, int MAX_COUNT]);
search_type must be one of '=','<','<=','>','>=','[]','@c','PK'. searchvalue2 is required when search_type is '[]'.
Executes a find (mode=4), and then reads the chain, until MAX_COUNT
records have been read. If MAX_COUNT is not specified, then the value
specified in turboimage.dbget_count is used.
Cuurrently places an unconditional lock on the set (mode=3) before
retrieving the records and unlocks the set afterwards. It is intended
to change this to item level locking.
No lock is applied if there an explicit lock placed by
mpe_dblock_set or mpe_dblock_base,
or if the database was opened in a mode other than 1 or 5.
A btree must be defined in the database for the specified search item.
For detail sets, returns an array of records, indexed by record number. For master sets, returns an array of records, indexed by search item value.
If no records are found, a null length array is returned.
If get_items is an array of strings, each record will consist of an array of the items listed in get_items. If get_items is NULL, each record will consists of an array of all items in the set. If get_items is a single string, each record returned will consist of a single value.
Returns NULL on error.
Example:
<?php
print "<TABLE>\n";
$recs = mpe_dbget_btree_back($db,'COMPOSERS','ComposerName','@%','F%','ComposerName');
foreach($recs as $data) {
print "<TR><TD>$data</TD></TR>\n";
}
unset($recs);
print "</TABLE>\n";
?>
|
mpe_dblookup -- Retrieves a single record using a chained or calculated read.
array mpe_dblookup(int resource_id, string dataset,
string search_item, searchvalue, string/array get_items);
Retrieves the selected items from a single record.
If dataset is a detail set, places an unconditional item level
lock (mode 5) on the set, executes a DBFIND and a DBGET,
mode=DBGET_MODE_CHAINED_READ, before unlocking the set.
No lock is applied if there an explicit lock placed by
mpe_dblock_set or mpe_dblock_base,
or if the database was opened in a mode other than 1 or 5.
If dataset is a master, this function executes a DBGET, mode=DBGET_MODE_CALCULATED_READ.
Returns NULL if no record is found or if an error occurs.
If get_items is an array of strings, this function returns an associative array of the items listed in get_items. If get_items is NULL, an associative array of all items are returned. If get_items is a single string, a single value is returned.
Example:
<?php
$rec = mpe_dblookup($db, "Selections", "AlbumCode", 2003,
array("ComposerName","Performers","SelectionName"));
if($rec !== FALSE) {
print "<TABLE>\n";
foreach($rec as $item => $value) {
print "<TR><TD>\n$item\n</TD>\n<TD>\n$value\n</TD>\n</TR>\n";
}
print "</TABLE>\n";
}
?>
|
mpe_dblookup -- Retrieves a single record using a chained or calculated read, starting at the end of the sort chain.
array mpe_dblookup_back(int resource_id, string dataset,
string search_item, searchvalue, string/array get_items);
Retrieves the selected items from a single record, retrieving the last record in a chain rather than the first.
If dataset is a detail set, places an unconditional item level
lock (mode 5) on the set, executes a DBFIND and a DBGET,
mode=DBGET_MODE_CHAINED_READ, before unlocking the set.
No lock is applied if there an explicit lock placed by
mpe_dblock_set or mpe_dblock_base,
or if the database was opened in a mode other than 1 or 5.
If dataset is a master, this function executes a DBGET, mode=DBGET_MODE_BACK_CHAINED_READ.
Returns NULL if no record is found or if an error occurs.
If get_items is an array of strings, this function returns an associative array of the items listed in get_items. If get_items is NULL, an associative array of all items are returned. If get_items is a single string, a single value is returned.
Example:
<?php
$rec = mpe_dblookup_back($db, "Selections", "AlbumCode", 2003,
array("ComposerName","Performers","SelectionName"));
if($rec !== FALSE) {
print "<TABLE>\n";
foreach($rec as $item => $value) {
print "<TR><TD>\n$item\n</TD>\n<TD>\n$value\n</TD>\n</TR>\n";
}
print "</TABLE>\n";
}
?>
|
mpe_dblookup -- Checks for the existence of a record using a chained or calculated read.
array mpe_dbexists(int resource_id, string dataset,
string search_item, searchvalue);
Checks for the existence of the record indicated by search_item = searchvalue.
If dataset is a detail set, places an unconditional item level
lock (mode 5) on the set, executes a DBFIND and a DBGET,
mode=DBGET_MODE_CHAINED_READ, before unlocking the set.
No lock is applied if there an explicit lock placed by
mpe_dblock_set or mpe_dblock_base,
or if the database was opened in a mode other than 1 or 5.
If dataset is a master, this function executes a DBGET, mode=DBGET_MODE_CALCULATED_READ.
Returns TRUE a record exists. Returns FALSE if no record is found. Returns NULL on error.
Example:
<?php
$composer = "Edvard Grieg";
$rec = mpe_dbexists($db, "Composers", "ComposerName", $composer);
if($rec) {
print "We have \"$composer\"";
} else {
print "Sorry, no \"$composer\"";
}
?>
|
mpe_dbput -- Add a record to a dataset.
boolean mpe_dbput(int resource_id, string dataset,
assoc array of item values);
The third argument is an associative array containing the data, indexed by item name
If dataset is a detail set, this function unconditionally locks the
entire database before executing the DBPUT. If dataset is a master set,
this function unconditionally locks the set. The lock is removed
afterwards. No lock is applied if an explicit lock has already been
applied by mpe_dblock_set or mpe_dblock_base.
Items not explicity initialized by the array of item values are set to a default value of zero for numeric items, or space for character items.
Returns TRUE on success.
mpe_dbdelete -- Deletes a record from dataset.
array mpe_dbdelete(int resource_id, string dataset,
record number | search item value);
If dataset is a detail set, the third argument must be the record number
of the record to be deleted. The record number is the value returned by
mpe_dbget, or the index value of the array returned by any
of mpe_dbget_serial, mpe_dbget_serial_back,
mpe_dbget_chain or mpe_dbget_chain_back.
If dataset is a master set, the third argument must be the value of the
search item of the record to be deleted. This is the value returned by
mpe_dbget, or the index value of the array returned by any
of mpe_dbget_serial, mpe_dbget_serial_back,
mpe_dbget_chain or mpe_dbget_chain_back.
If dataset is a detail set, this function unconditionally locks the
entire database before executing the DBDELETE. If dataset is a master set,
this function unconditionally locks the set. The lock is removed
afterwards. No lock is applied if an explicit lock has already been
applied by mpe_dblock_set or mpe_dblock_base.
Returns TRUE on success.
mpe_dbupdate -- Modifies a record
array mpe_dbupdate(int resource_id, string dataset,
record number | search item value, assoc array of item values);
mpe_dbget, or the index value of the array returned by any
of mpe_dbget_serial, mpe_dbget_serial_back,
mpe_dbget_chain or mpe_dbget_chain_back.
If dataset is a master set, the third argument must be the value of the
search item of the record to be updated. This is the value returned by
mpe_dbget, or the index value of the array returned by any
of mpe_dbget_serial, mpe_dbget_serial_back,
mpe_dbget_chain or mpe_dbget_chain_back.
The fourth argument is an associative array containing the data, indexed by item name
If dataset is a detail set, this function unconditionally locks the
entire database before executing the DBUPDATE. If dataset is a master set,
this function unconditionally locks the set. The lock is removed
afterwards. No lock is applied if an explicit lock has already been
applied by mpe_dblock_set or mpe_dblock_base.
Returns TRUE on success.
mpe_nlmatch -- Checks if string matches a pattern
array mpe_nlmatch(string s, string pattern);
Returns TRUE if s matches pattern.
Calls NLMATCHINIT and NLMATCH. The results of calls to NLMATCHINIT are cached.
Mode for DBOPEN.
May be overridden by the optional parameter in mpe_dbopen.
The default value for turboimage.dbopen_mode is 5.
The maximum number of records that may be returned by a single call to
the various functions that read multiple records, return them in arrays.
This may be overriden by the optional parameter of each of
mpe_dbget_serial, mpe_dbget_serial_back,
mpe_dbget_chain and mpe_dbget_chain_back.
The default value for turboimage.dbget_count is 1024.
Whether to transparently apply locks during
mpe_dbget_serial, mpe_dbget_serial_back,
mpe_dbget_chain, mpe_dbget_chain_back
and mpe_dblookup.
The default value for turboimage.dbread_auto_lock is 1.
This setting may be changed during the execution of the script by PHP
variable turboimage_dbread_auto_lock.
Disables mpe_dblock_set and mpe_dblock_set.
You may not want your script writers using these explicit locking functions.
The default value for turboimage.disable_explicit_lock is 0.