Database Variables
zMUD variables that contain database records have a special format. They are similar to a string list (which has several items separated by the | character), but each item has both a Name and a Value. You can use the format "Name1=Value1|Name2=Value2|etc..." in most database scripting commands, although the data is stored with different delimiters internally. You should never have to access a database variable directly and will always use zMUD functions and command to manipulate them.
You can have a database variable that is not necessarily associated with a database record. In this case, the variable contains the field Names and Values in the format shown above, but are not actually stored on disk in the database. This is similar to a Record or Class in Pascal, or a struc in C. It allows a single variable to have named fields and values.
To create a database variable, you can use several different methods. The #VAR command accepts the above format:
#VAR VarName {Name1=Value1|Name2=Value2|Name3=Value3|etc...}
You can also add fields to a variable one at a time using the #ADDKEY command or the %addkey function:
#VAR VarName ""
#ADDKEY VarName Name1 Value1
#ADDKEY VarName Name2 Value2
etc
The #ADDKEY command also accepts the Name=Value syntax:
#ADDKEY VarName {Name3=Value3|Name4=Value4|etc...}
Warning: Do NOT attempt to create a database variable using the concat function. Doing
#VAR VarName %concat("Name1=Value1","|","Name2=Value2")
WILL NOT WORK! The = and | delimiters are not used by the internal database storage and the resulting variable will not be considered a database variable.
You can delete a field from a database variable using the #DELKEY command:
#DELKEY VarName Name1
would delete the Name1 field and the Value1 value assigned to it.
To display the database variable to the screen in a nice format, use the #SHOWDB command:
#SHOWDB @VarName
will display each field Name and Value on a separate line on the screen.
To access a field Value from a database variable, you can use one of two methods. The most general method is to use the %db function, where the first argument is the database variable, and the second argument is the Name of the field you wish to retrieve. For example %db(@VarName,"Name1") would return Value1 in the above examples. This method of retrieving values is preferred in complex situations since the name of the field can itself be a variable. For example:
#VAR FieldName Name1
#SHOW %db(@VarName,@FieldName)
will display Value1 to the screen.
The second way to access database variables is using standard C and Pascal "dot notation" where you specify the VarName.FieldName. For example @VarName.Name1 will return Value1. However, this shortcut notation does not allow a variable field name. @VarName.@FieldName WILL NOT WORK! So, while it is useful most of the time, sometimes you will still need the %db function. The dot notation can also be used to set database values, either with the #VAR command or the zMUD assignment statement:
#VAR VarName.Name1 Value1
VarName.Name1=Value1
will both set the Name1 field in the VarName database variable to Value1.
To access database fields of the current database record (%rec) you can use an additional shorthand: &FieldName. The & character is the Database Character and can be changed in the Special Character preferences. The &FieldName syntax is most commonly used in query and sort formulas to refer to fields in the current database record. Do not confuse the &FieldName syntax with the &VarName syntax for Trigger Patterns. Trigger Patterns have a completely different syntax from the normal scripting parser. So, all of the following are equivalent and return the value of the Name field for the current record:
#SHOW %db(%rec,Name)
#SHOW %db(,Name)
#SHOW %rec.Name
#SHOW &Name
Here is a complete list of commands and functions that operate on general database variables: %addkey(db,key,value) adds the key=value to the database variable db and returns the new database variable.
%delkey(db,key) deletes the key from the database variable db and returns the new database variable
%db(db,key) returns the value of field key in the database variable db
%iskey(db,key) returns the position of the key in the database variable db. Returns 0 (false) if the key does not exist
%numkeys(db) returns the number of fields (keys) in the database variable db
#ADDKEY db key value adds the key=value to the database variable db. Supports the Name=Value syntax.
#DELKEY db key deletes the key from the database variable db
#SHOWDB db displays the database variable db on the screen
#LOOPDB db commands loops through each field in the database variable, assigns the field name to %key and the value of the field to %val, and executes the given commands.
Database Names