QMBasic - Assignment Statements
Variables may be assigned values by statements of the following forms
In all cases, var may be a dimensioned matrix element.
The var op expr format allows the following operators.
Additionally, many other statements set values into variables.
The substring assignment operator is
var[s,n] = expr
In the default compiler modes, substring assignment overlays an existing portion of a string. If the substring bounds extend beyond the end of the actual value stored in the string, the excess data is lost. If the value of expr is longer than the substring to be set, the trailing characters are lost. If the value of expr is shorter than the substring to be set, the remainder is filled with spaces.
Two alternative implementations are provided for compatibility with various Pick style multivalue environments. Use of the PICK.SUBSTR option of the $MODE compiler directive extends the definition above such that the original string is extended if the region to be overwritten extends beyond the end of the current string value.
Use of the PICK.SUBSTR.ASSIGN option of the $MODE compiler directive changes the behaviour of substring assignment considerably. If the value of s is negative, the new contents of var are formed by copying the value or expr, adding -s spaces, skipping n characters of the original value of var and copying the remainder. If the value of s is greater than or equal to zero, the new value of var is formed by copying s-1 characters of the original value of var, adding spaces if necessary, skipping n characters, inserting the value of expr and then copying any remaining characters from the original var.
Trailing Substring Assignment
The trailing substring assignment operator is
var[n] = expr
This overwrites the final n characters of var with the value of expr. If n is less than 1, it is treated as 1. If n exceeds the length of var it is treated as being the length of var.
If the value of expr is longer than the substring to be set, the trailing characters are lost. If the value of expr is shorter than the substring to be set, the remainder is filled with spaces.
The two $MODE compiler directive settings described above do not affect trailing substring assignment.
Delimited Substring Assignment
Delimited substring assignment replaces or inserts a portion of a string which is divided into substrings by use of a delimiter character. This character does not have to be one of the mark characters. The first character of string d is taken as the delimiter character. Starting at substring i, n substrings are replaced by the value of the assignment expression. For full details of delimited substring assignment, see the description of the FIELDSTORE statement.
Substring Assignment with Dynamic Arrays
All variants of substring assignment also allow the operation to be applied to an element of a dynamic array. For example,
VAR<FNO> = S
VAR<FNO>[1,10] = S
VAR<FNO>['*', 5, 1] = S
Field (or value, or subvalue) assignment replaces an existing field (or value, or subvalue) with the result of the expression. If the specified field, value or subvalue does not already exist within the string, mark characters are added as necessary.
Z<2,3> = expr
When adding a new field at the end of a string, the syntax
Z<-1> = expr
can be used where the field position is specified as any negative value, by convention -1. The QMBasic language will add a new field to receive the result. Similarly, the operations
Z<5,-1> = expr
Z<5,3,-1> = expr
would add a new value or subvalue to the end of existing data.
The way in which the append operation is performed depends on the setting of the COMPATIBLE.APPEND option of the $MODE compiler directive.
By default, QM prefixes the appended data with a field, value or subvalue mark unless the string, field or value in which the item is being appended is completely null.
Thus, if S = "ABCFMDEFVMFMXYZFM"
Setting the COMPATIBLE.APPEND mode modifies the behaviour such that a mark character is not inserted if the final element of the portion of the dynamic array to which data is being appended is null. This is the how other multivalue database products work and results in
Note that the S<-1> syntax should not be used when working with an association because it can lose the relation between the members of the association. Suppose we are working with an inventory in which we are associating a part number, description, and a comment. Every item has a part number and description but the comment is not always present. If we write
PART.NO<-1> = part number
DESCRIPTION<-1> = description
COMMENT<-1> = text
the COMMENT field will not be updated as expected if the text item is a null string. Next time these items are updated, the associations may get out of step.
To avoid this problem, use the field assignment or the REPLACE() function in code such as this:
PART.NO<N> = part number
DESCRIPTION<N> = description
COMMENT<N> = text
where N is the dynamic array field position to be updated. This will ensure that any null values are inserted correctly, so that the association between the values will also be correctly maintained.