vAddField

vAddRecord

vCountFields

vCountMatching

vCountRecords

vGetDatabases

vGetFieldInfo

vGetFields

vGetRecord

vGetRecordID

vIsFieldIndexed

vLoadDatabase

vLookup

vMakeDatabase

vMakeFieldIndex

vRemoveDatabase

vRemoveField

vRemoveFieldIndex

vRemoveRecord

vRetrieve

vSetFieldInfo

vSetRecord

vUnloadDatabase

Parameter	Description
database	name of database
field-info-list	structured list (see below)
[index-it]	index this field? (true/false) [optional]

Adds a new field to database whose structure is defined using the field-info-list parameter in the format specified below. If you wish the field to be indexed for searching, set the optional parameter index-it to true, otherwise the field will not be indexed.

The field-info-list parameter should use the structure:

Examples:

vAddField("Customers", ["id" "Customer ID" "unsigned"], true);
vAddField("Customers", ["fnam" "First Name" "text" 50]);
vAddField("Customers", ["lnam" "Last Name" "text" 50]);

See Also:

• vRemoveField
• vSetFieldInfo

Parameter	Description
database	name of database
[field-values]	list of field/value pairs [optional]

Adds a new record to database and returns the new record's ID number as an integer. The optional field-values parameter may be used to set the field contents of the new record, rather than using an additional function call.

Both of the examples below perform the same action, one demonstrating the use of the field-values parameter rather than having to use vSetRecord().

Examples:

1. new_id = vAddRecord("Customers");
   vSetRecord("Customers", new_id, 
              [["id" 1] ["fnam" "Nathan"] ["lnam" "Nunn"]]);

2. vAddRecord("Customers", 
              [["id" 1] ["fnam" "Nathan"] ["lnam" "Nunn"]]);

See Also:

• vRemoveRecord
• vSetRecord

Parameter	Description
database	name of database

Counts the number of defined fields in database and returns the count as an integer.

Example:

num_fields = vCountFields("Customers");   // num_fields will be equal to 3

Parameter	Description
database	name of database
search-field	four-character field reference
compare-op	comparison operator (see below)
compare-value	value to compare to

Returns the total number of records that match the query specified using search-field, compare-op, and compare-value. This function is helpful when used in conjunction with the start-with and max-hits parameters in vLookup() or vRetrieve() allowing you to retrieve matching records in smaller chunks.

The database name to search is specified by the database parameter. The search-field parameter specifies which field in the database is being searched. The compare-op specifies how to search for matching records, and compare-value is the value to compare each field with. All text comparisons in Verona are non case-sensitive.

If the compare-value parameter is not the same type as the field being searched, Verona will attempt to coerce the value as appropriate. For example, an "=" lookup on the unsigned field "id" with a compare value of "12" will return expected results because the text string "12" can be coerced to the integer 12.

Valid values for compare-op are:

Example:

num_hits = vCountMatching("Customers", "fnam", "starts with", "John");
print "There are " & num_hits & " customers whose name starts with John.";

See Also:

• vLookup
• vRetrieve

Parameter	Description
database	name of database

Returns the total number of records in database.

Example:

num_customers = vCountRecords("Customers");
print "We have served " & num_customers & " customers!";

Returns a list of all the databases currently available.

Example:

db_list = vGetDatabases();
num_databases = sizeOf(db_list);
print num_databases & " databases available: " & db_list;

>> 3 databases available: Catalog Customers Orders

Parameter	Description
database	name of database
field	field reference or index number

Returns a structured list containing the definition of the field specifed by field in database. The field parameter may be the field's four-character reference string or its sequential index number in the database.

To get field definitions for all defined fields in a database, refer to vGetFields().

The returned list has the following structure:

Example:

field_info = vGetFieldInfo("Customers", "fnam");
printList(field_info);

>> ["fnam" "First Name" "text" 50]

See Also:

• vGetFields
• vSetFieldInfo

Parameter	Description
database	name of database

Returns a structured list describing all the defined fields in database.

Each item in the returned list is a sub-list with the following structure:

Example:

field_structure = vGetFields("Customers");
repeat with the_field in field_structure
  printList(the_field) & "\r";
end repeat;

>> ["id" "Customer ID" "unsigned"]
   ["fnam" "First Name" "text" 50]
   ["lnam" "Last Name" "text" 50]

See Also:

• vGetFieldInfo
• vSetFieldInfo

Parameter	Description
database	name of database
record-id	record ID
[return-fields]	list of field references to return [optional]

Given a record ID in record-id and database, this function will return the contents of the record specified. If you do not want all the fields in a record returned, use the optional return-fields parameter to specify which fields to return, and in what order. Additionally, including the special field reference "----" in return-fields will return the record's ID number in the results.

Examples:

1. record_id = vGetRecordID("Customers", 1);
   printList(vGetRecord("Customers", record_id));
   
   >> [1 "Nathan" "Nunn"]

2. record_id = vGetRecordID("Customers", 1);
   printList(vGetRecord("Customers", record_id, ["lnam" "fnam"]));
   
   >> ["Nunn" "Nathan"]

See Also:

• vGetRecordID
• vSetRecord

Parameter	Description
database	name of database
record-number	sequential record number

Given a record's sequential number in record-number, the record's internal ID is returned. The name of the database is specified by the database parameter.

Example:

// get the 50th record in "Customers" database
record_id = vGetRecordID("Customers", 50);
the_customer = vGetRecord("Customers", record_id);

Parameter	Description
database	name of database
field	four-character field reference

Returns true if the field specified by field is currently indexed. The name of the database is specified by the database parameter.

Note: Unindexed fields are searchable in Verona, but the results return much more slowly than with an indexed field.

Examples:

1. is_indexed = vIsFieldIndexed("Customers", "id");
   if (is_indexed = true) then
     print "true";
   else
     print "false";
   end if;
   
   >> true

2. // "fnam" is the second field in the "Customers" database
   is_indexed = vIsFieldIndexed("Customers", "fnam");
   if (is_indexed = true) then
     print "true";
   else
     print "false";
   end if;
   
   >> false

See Also:

• vMakeFieldIndex
• vRemoveFieldIndex

Parameter	Description
database	name of database to load

Only for those who want absolute control over their databases, this function will load the database whose name is database.

However, since Verona handles loading of databases automatically when they are used it is not necessary for general use and is only provided for completeness.

Example:

vLoadDatabase("Customers");

See Also:

• vUnloadDatabase

Parameter	Description
database	name of database
search-field	four-character field reference
compare-op	comparison operator (see below)
compare-value	value to compare to
[sort-field]	sort by field reference/index [optional]
[start-with]	start with hit number [optional]
[max-hits]	maximum hits to return [optional]

This function is used to search for records in a database that match a given query. A list containing the record IDs of all records matching the query is returned. To receive actual field values for any returned record, you must use vGetRecord.

The database name to search is specified by the database parameter. The search-field parameter specifies which field in the database is being searched. The compare-op specifies how to search for matching records, and compare-value is the value to compare each field with. All text comparisons in Verona are non case-sensitive.

If the compare-value parameter is not the same type as the field being searched, Verona will attempt to coerce the value as appropriate. For example, an "=" lookup on the unsigned field "id" with a compare value of "12" will return expected results because the text string "12" can be coerced to the integer 12.

If you want the returned results sorted by a field other than search-field, the optional sort-field parameter may be used to designate an alternate field to sort by.

The start-with and max-hits parameters are used to return a subset of the total matching records. For example, if there are 125 matching records (this can be determined using the vCountMatching() function) and you only want blocks of 25 at a time, set max-hits to 25 and start-with to 25 * the number of the results block to be shown (0 for the first block of 25, 1 for the second block of 25, and so forth). This functionality is very useful when returning the results of large queries in an organized and quick fashion. See the third example below for further reference.

Valid values for compare-op are:

Examples:

1. // All customers whose last name starts with "a", as in a 
   // directory listing.
   hits = vLookup("Customers", "lnam", "starts with", "A");

2. // Same as above, with results sorted by the customer's 
   // first name.
   hits = vLookup("Customers", "lnam", "starts with", "A", "fnam");

3. // As above, returned in blocks of 25 at a time.
   page_num = 1;
   max_hits = 25;
   start_with = (page_num - 1) * max_hits;
   hits = vLookup("Customers", "lnam", "starts with", "A", "fnam", 
                  start_with, max_hits);
   
   // In this example, setting page_num to 2 will return the 
   // second page of results, 3 the third page, and so forth.

See Also:

• vCountMatching
• vGetRecord
• vRetrieve

Parameter	Description
database	name of database to make

Creates a new, empty database with no field definitions. The name of the new database is specified by the database parameter.

Example:

customers_db = "Customers";
vMakeDatabase(customers_db);

See Also:

• vRemoveDatabase

Parameter	Description
database	name of database
field	four-character field reference

Creates an index for the field specified in field by its four-character reference. The name of the database is specified by the database parameter.

Note: Unindexed fields are searchable in Verona, but the results are much slower than a field that is indexed.

Example:

// Indexes the "Last Name" field of the "Customers" database.
vMakeFieldIndex("Customers", "lnam");

See Also:

• vIsFieldIndexed
• vRemoveFieldIndex

Parameter	Description
database	name of database

Permanently removes a database from the disk. The name of the database to be deleted is specified by the database parameter.

Warning: This operation is not reversible!

Example:

// Permanently deletes the "Users" database.
vRemoveDatabase("Users");

See Also:

• vMakeDatabase

Parameter	Description
database	name of database
field	four-character field reference

Permanently removes a field from a database. The field to delete is specified by its four character reference in the field parameter. The name of the database is specified by the database parameter.

Warning: This operation is not reversible!

Example:

// Permanently deletes the "id" field and its contents from the 
// "Customers" database.
vRemoveField("Customers", "id");

See Also:

• vAddField

Parameter	Description
database	name of database
field	four-character field reference

Removes the index for the field specified in field by its four character reference thus freeing up disk space occupied by the index. The name of the database is specified by the database parameter.

Note: Unindexed fields are searchable in Verona, but the results return much more slowly as compared to an indexed search.

Example:

// Remove the field index for "lnam" in the "Customers"
// database.
vRemoveFieldIndex("Customers", "lnam");

See Also:

• vIsFieldIndexed
• vMakeFieldIndex

Parameter	Description
database	name of database
record-id	ID of record to remove

Permanently removes the record whose ID is record-id from the database. The name of the database is specified by the database parameter.

Warning: This operation is not reversible!

Example:

// Remove all customers in the database whose last name starts with "a"
repeat with delete_id in vLookup("Customers", "lnam", "starts with", "A");
  vRemoveRecord("Customers", delete_id);
end repeat;

See Also:

• vAddRecord
• vGetRecordID

Parameter	Description
database	name of database
search-field	four-character field reference
compare-op	comparison operator (see below)
compare-value	value to compare to
[return-fields]	list of field references to return [optional]
[sort-field]	sort by field reference/index [optional]
[start-with]	start with hit number [optional]
[max-hits]	maximum hits to return [optional]

This versatile function performs a query much like vLookup(), but rather than returning record ID numbers, it returns the actual record data. This removes the need to repeatedly get each record to access data returned based on a query.

The database name to search is specified by the database parameter. The search-field parameter specifies which field in the database is being searched. The compare-op specifies how to search for matching records, and compare-value is the value to compare each field with. All text comparisons in Verona are non case-sensitive.

If the compare-value parameter is not the same type as the field being searched, Verona will attempt to coerce the value as appropriate. For example, an "=" lookup on the unsigned field "id" with a compare value of "12" will return expected results because the text string "12" can be coerced to the integer 12.

Using the optional return-fields parameter specifies which fields will be retrieved from all records matching the query. This is particularly useful for large databases where you are only interested in a few of the fields. The returned list will contain each field requested, in the order specified. Additionally, including the special field reference "----" in return-fields will return the record's ID number in the results.

If you want the returned results sorted by a field other than search-field, the optional sort-field parameter may be used to designate an alternate field to sort by.

The start-with and max-hits parameters are used to return a subset of the total matching records. For example, if there are 125 matching records (this can be determined using the vCountMatching() function) and you only want blocks of 25 at a time, set max-hits to 25 and start-with to 25 * the number of the results block to be shown (0 for the first block of 25, 1 for the second block of 25, and so forth). This functionality is very useful when returning the results of large queries in an organized and quick fashion. See the third example below for further reference.

Valid values for compare-op are:

Each of the examples below demonstrate various levels of query complexity and return actual record data.

Examples:

1. // All customers whose last name starts with "a", as in a 
   // directory listing, returning the customer's first and last name.
   results = vRetrieve("Customers", "lnam", "starts with", "A",
                       ["fnam" "lnam"]);

2. // Same as above, with results sorted by the customer's 
   // first name.
   results = vRetrieve("Customers", "lnam", "starts with", "A",
                       ["fnam" "lnam"], "fnam");

3. // As above, returned in blocks of 25 at a time.
   page_num = 1;
   max_hits = 25;
   start_with = (page_num - 1) * max_hits;
   results = vRetrieve("Customers", "lnam", "starts with", "A",
                       ["fnam" "lnam"], "fnam", start_with, max_hits);
   
   // In this example, setting page_num to 2 will return the 
   // second page of results, 3 the third page, and so forth.

See Also:

• vCountMatching

Parameter	Description
database	name of database
field	reference or field index number
field-info-list	structured list (see below)

Modifies the field specified by its four character reference or index number in field to match the structure defined in field-info-list. The name of the database is specified in the database parameter.

Note that this function can only modify a field's reference or name, not its type or length. Any additional items in field-info-list will be ignored.

The field-info-list parameter should use the structure:

Example:

vSetFieldInfo("Customers", "fnam", ["f_nm" "First Name"]);
vSetFieldInfo("Customers", "lnam", ["l_nm" "Last Name"]);

See Also:

• vGetFieldInfo
• vGetFields

Parameter	Description
database	name of database
record-id	record ID
field-values	list of field/value pairs

Modifies the value of one or more fields in the record whose ID is record-id. The field-values parameter is a list of field reference and value pairs which are to be modified in the record. The name of the database is specified by the database parameter.

Example:

vSetRecord("Users", rec_id, [["pass" new_password]]);

See Also:

• vAddRecord

Parameter	Description
database	name of database

Only for those who want absolute control over their databases, this function will unload the database whose name is database.

However, since Verona handles unloading of databases automatically when needed, it is not necessary for general use and is only proved for completeness.

Example:

vUnloadDatabase("Customers");

See Also:

• vLoadDatabase