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 global variable, or a special variable. If a
local variable or global variable is specified, it 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).
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 an arithmetic or string expression. The null
string (“”) is a valid
value. 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.
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.
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 or global variable,
the
$PIECE function, the
$EXTRACT function,
and certain special variables, including
$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 or a global variable. 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.
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 up-arrow (^) 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".