Assigns a value to a variable.
Synopsis
SET:pc setargument,...
S:pc setargument,...
where setargument can be:
variable=value
(variable-list)=value
The
SET command assigns a value to a variable. It can set a single variable, or set multiple variables using any combination of two syntactic forms. It can assign values to variables by specifying a comma-separated list of
variable=value pairs. For example:
It can assign the same value to multiple variables by specifying a comma-separated list of variables enclosed in parentheses. For example:
You can combine these two syntactic forms in any combination. For example:
SET (a,b)=1,c=2,(d,e,f)=3
The maximum number of assignments you can perform with a single invocation of
SET is 128.
If a specified variable does not exist,
SET creates it and assigns the value. If a specified variable exists,
SET replaces the previous value with the specified value.
A value can be a literal or an expression that evaluates to a value.
An optional postconditional expression. Caché executes the command if the postconditional expression is true (evaluates to a non-zero numeric value). Caché does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to
Command Postconditional Expressions in
Using Caché ObjectScript.
The variable to receive the value resulting from the evaluation of
value. It can be a local variable, a process-private global, a global variable, or a special variable. A local variable, process-private global, or global variable can be either subscripted or unsubscripted. A global variable can be specified with extended global reference (see
Global Structure in
Using Caché Multi-Dimensional Storage).
Local variables, process-private globals, and special variables are specific to the current process; they are mapped to be accessible from all namespaces. A global variable persists after the process that created it terminates. A global is specific to the namespace in which it was created. By default, a
SET assigns a global in the current namespace. You can use
SET to define a global (^myglobal) in another namespace (samples) by using syntax such as the following:
SET ^[“samples”]myglobal="Ansel Adams”.
A variable can be a piece or segment of a variable as specified in the argument of a
$PIECE or
$EXTRACT function.
Note that you can assign values to only certain special variables. See the reference pages for individual special variables for further details.
A literal value or any valid Caché ObjectScript expression. Usually a
value is a numeric or string expression.
-
A numeric value is converted to canonical form before assignment: leading and trailing zeros, a plus sign or a trailing decimal point are removed. Any exponentiation or specified arithmetic operations are performed.
-
A string value is enclosed in quotation marks. A string is assigned unchanged, except that doubled quotation marks within the string are converted to a single quotation mark. The null string ("") is a valid
value.
-
A numeric value enclosed in quotation marks is not converted to canonical form and no arithmetic operations are performed before assignment.
-
If a relational or logical expression is used, Caché assigns the truth value (0 or 1) resulting from the expression.
-
Object properties and object methods that return a value are valid expressions. Use the
.. syntax for assigning a property or method value to a variable.
The following example illustrates how you can specify multiple arguments for the same
SET command. Specifically, the command assigns values to three variables. note that arguments are evaluated in left-to-right order.
SET var1=12,var2=var1*3,var3=var1+var2
WRITE "var1=",var1,!,"var2=",var2,!,"var3=",var3
The following example shows the
(variable-list)=value form of the
SET command. It shows how to assign the same value to multiple variables. Specifically, the command assigns the value 0 to three variables.
SET (sum,count,average)=0
WRITE "sum=",sum,!,"count=",count,!,"average=",average
The following example shows setting a subscripted global variable in a different namespace using extended global reference.
ZNSPACE "user"
SET ^["samples"]name(1)="fred"
ZNSPACE "samples"
WRITE ^name(1)
The following example sets
x to the value of an object property:
where
person is the object reference, and
LastName is the object property name. Note that dot syntax is used in object expressions; a dot is placed between the object reference and the object property name or object method name.
To set a variable with an object property or object method value for the current object, use the double-dot syntax:
When using
SET with objects, do not perform multiple assignments. For example, avoid statements such as:
// Avoid this syntax:
SET (a.Name,b.Name)=z
Instead, issue a separate
SET command for each assignment, as shown in the following example:
SET a.Name=z
SET b.Name=z
The following command sets
x to the value returned by the object method TotalLines():
SET x=invoice.TotalLines()
A
SET command for objects can take an expression with cascading dot syntax, as shown in the following examples:
SET x=patient.Doctor.Hospital.Name
In this example, the patient.Doctor object property references the Hospital object, which contains the Name property. Thus, this command sets
x to the name of the hospital affiliated with the doctor of the specified patient. The same cascading dot syntax can be used with object methods.
A
SET command for objects can be used with system-level methods, such as the following data type property method:
SET x=patient.NameIsValid(name)
In this example, the NameIsValid() property method returns its result for the current patient object. NameIsValid() is a boolean method generated for data type validation of the Name property. Thus, this command sets
x to 1 if the specified name is a valid name, and sets
x to 0 if the specified name is not a valid name.
Each variable assignment can be a local variable, a process-private global, or a global, the
$PIECE function, the
$EXTRACT function, and certain special variables, including
$DEVICE,
$X,
$Y,
$KEY,
$ECODE, and
$ETRAP.
If the target variable does not already exist,
SET creates it and then assigns the value. If it does exist,
SET replaces the existing value with the assigned value.
You can set individual subscripted values (array nodes) for a local variable, process-private global, or a global. You can set subscripts in any order. If the variable subscript level does not already exist,
SET creates it and then assigns the value. Each subscript level is treated as an independent variable; only those subscript levels set are defined. For example:
KILL myarray
SET myarray(1,1,1)="Cambridge"
WRITE !,myarray(1,1,1)
SET myarray(1)="address"
WRITE !,myarray(1)
In this example, the variables myarray(1,1,1) and myarray(1) are defined and contain values. However, the variables myarray and myarray(1,1) are not defined, and return an <UNDEFINED> error when invoked. For further information on subscripted variables, refer to
Global Structure in
Using Caché Multi-Dimensional Storage.
Caché evaluates the arguments of the
SET command in strict left-to-right order. For each argument, it perform evaluation in the following sequence:
-
Evaluates occurrences of indirection or subscripts to the left of the equal sign in a left-to-right order to determine the variable name(s). For more information, refer to
Indirection in
Using Caché ObjectScript.
-
Evaluates the expression to the right of the equal sign.
-
Assigns the expression to the right of the equal sign to the variable name or references to the left of the equal sign.
Defined and Undefined Variables
Most Caché commands and functions require that a variable be defined before it is referenced. Attempting to reference an undefined variable generates an <UNDEFINED> error. Attempting to reference an undefined object generates a <PROPERTY DOES NOT EXIST> or <METHOD DOES NOT EXIST> error. Refer to
$ZERROR for further details on these error codes.
The
READ command and the
$INCREMENT function can reference an undefined variable and assign a value to it. The
$DATA function can take an undefined or defined variable and return its status. The
$GET function returns the value of a defined variable; optionally, it can also assign a value to an undefined variable.
SET with $PIECE and $EXTRACT
When used on the right side of the equals sign,
$PIECE and
$EXTRACT extract a substring from a variable and assign its value to the specified variable(s) on the left side of the equals sign.
$PIECE extracts a substring using a specified delimiter, and
$EXTRACT extracts a substring using a character count.
For example, assume that variable
x contains the string "HELLO WORLD". The following commands extract the substring "HELLO" and assign it to variables
y and
z, respectively:
SET x="HELLO WORLD"
SET y=$PIECE(x," ",1)
SET z=$EXTRACT(x,1,5)
WRITE "x=",x,!,"y=",y,!,"z=",z
When used on the left side of the equals sign,
$PIECE and
$EXTRACT insert the value from the expression on the right side of the equals sign into the specified portion of the target variable. Any existing value in the specified portion of the target variable is replaced by the inserted value.
For example, assume that variable
x contains the string "HELLO WORLD" and that variable
y contains the string "HI THERE". In the command:
SET x="HELLO WORLD"
SET y="HI THERE"
SET $PIECE(x," ",2)=$EXTRACT(y,4,9)
WRITE "x=",x
The
$EXTRACT function extracts the string "THERE" from variable
y and the
$PIECE function inserts it into variable
x at the second field position, replacing the existing string "WORLD". Variable
x now contains the string "HELLO THERE".
If the target variable does not exist, Caché creates it and pads it with delimiters (in the case of
$PIECE) or with spaces (in the case of
$EXTRACT) as needed.
For example, assume that
x contains the string "HELLO WORLD" and that
y contains the string "THERE". The following command inserts the value of
y in positions 7 through 11 of x:
SET x="HELLO WORLD"
SET y="THERE"
SET $EXTRACT(x,7,11)=y
WRITE "x=",x
Variable
x now contains the string "HELLO THERE".
In the following example, assume that the global array ^client is structured so that the root node contains the client's name, with subordinate nodes containing the street address and city. For example, ^client(2,1,1) would contain the city address for the second client stored in the array.
Assume further that the city node (x,1,1) contains field values identifying the city, state abbreviation, and ZIP code (postal code), with the comma as the field separator. For example, a typical city node value might be "Cambridge,MA,02142". The three
SET commands in the following code each use the
$PIECE function to assign a specific portion of the array node value to the appropriate local variable. Note that in each case
$PIECE references the comma (",") as the string separator.
ADDRESSPIECE
SET ^client(2,1,1)="Cambridge,MA,02142"
SET city=$PIECE(^client(2,1,1),",",1)
SET state=$PIECE(^client(2,1,1),",",2)
SET zip=$PIECE(^client(2,1,1),",",3)
WRITE "City is ",city,!,
"State or Province is ",state,!
,"Postal code is ",zip
QUIT
The
$EXTRACT function could be used to perform the same operation, but only if the fields were fixed length and the lengths were known. For example, if the city field was known to contain only up to 9 characters and the state and ZIP fields were known to contain only 2 and 5 characters, respectively, the
SET commands could be coded with the
$EXTRACT function as follows:
ADDRESSEXTRACT
SET ^client(2,1,1)="Cambridge,MA,02142"
SET city=$EXTRACT(^client(2,1,1),1,9)
SET state=$EXTRACT(^client(2,1,1),11,12)
SET zip=$EXTRACT(^client(2,1,1),14,18)
WRITE "City is ",city,!,
"State or Province is ",state,!,
"Postal code is ",zip
QUIT
Notice the gaps between 9 and 11 and 12 and 14 to accommodate the comma field separators.
The following example replaces the first substring in
A (originally set to 1) with the string "abc".
StringPiece
SET A="1^2^3^4^5^6^7^8^9"
SET $PIECE(A,"^")="abc"
WRITE !,"A=",A
QUIT
The following example uses
$EXTRACT to replace the first character in
A (again, a 1) with the string "abc".
StringExtract
SET A="123456789"
SET $EXTRACT(A)="abc"
WRITE !,"A=",A
QUIT
The following example replaces the third through sixth pieces of
A with the string "abc" and replaces the first character in the variable
B with the string "abc".
StringInsert
SET A="1^2^3^4^5^6^7^8^9"
SET B="123"
SET ($PIECE(A,"^",3,6),$EXTRACT(B))="abc"
WRITE !,"A=",A,!,"B=",B
QUIT
The following example sets
$X,
$Y,
$KEY, and the fourth piece of a previously undefined local variable,
A, to the value of 20. It also sets the local variable
K to the current value of
$KEY.
A includes the previous three pieces and their caret delimiter (^).
SetVars
SET ($X,$Y,$KEY,$PIECE(A,"^",4))=20,X=$X,Y=$Y,K=$KEY
WRITE !,"A=",A,!,"K=",K,!,"X=",X,!,"Y=",Y
QUIT
The following example sets
$ECODE and
$ETRAP to the null string. Then, the example sets the local variables
EC and
ET to the values of
$ECODE and
$ETRAP.
SetEvars
SET ($ECODE,$ETRAP)="",EC=$ECODE,ET=$ETRAP
WRITE "EC=",EC,!,"ET=",ET
QUIT
SET with $LIST and $LISTBUILD
Caché includes several functions that allow you to manipulate lists more quickly and easily than you can with
$PIECE or
$EXTRACT. These functions are:
These functions do not use delimiters when they create or manipulate lists. Instead, they encode the length (and type) of each element within the list itself. They then use the encoded length specifications to extract specified list elements during list manipulation. Because the $LIST functions do not use delimiter characters, the lists created using these functions should not be input to
$PIECE or other character-delimiter functions.
$LIST returns the specified element of the specified list.
$LISTBUILD returns a list containing one element for each argument given.
Replaces the specified element with the value given on the right side of the equal sign.
Extracts several elements of a list in a single operation. The arguments of
$LISTBUILD are variables, each of which receives an element of the list corresponding to their position in the
$LISTBUILD parameter list. Variable names may be omitted for positions that are not of interest.
In the following example,
$LISTBUILD (on the right side of the equal sign) is first used to return a list. Then
$LISTBUILD (on the left side of the equal sign) is used to extract two items from that list and set the appropriate variables.
SetListBuild
SET J=$LISTBUILD("red","blue","green","white")
SET $LISTBUILD(A,,B)=J
WRITE "A=",A,!,"B=",B
In this example, A="red" and B="green".
