SET assigns values to variables or to a selected portion of a variable.
The format of the SET command is:
S[ET][:tvexpr] setleft=expr | (setleft[,...])=expr | *lvn=lname | aliascontainer[,...]
where
setleft == glvn | $EXTRACT(glvn,[,intexpr1[,intexpr2]]) | $PIECE(glvn,expr1[,intexpr1[,intexpr2]]) | isv
and
aliascontainer == lvn | exfunc | exvar
The optional truth-valued expression immediately following the command is a command postconditional that controls whether or not GT.M executes the command.
A subscripted or unsubscripted local or global variable name on the left of the equal-sign (=) specifies a variable in which to store the expression found on the right side of the equal-sign; the variable need not exist prior to the SET; if the variable exists prior to the SET, the SET replaces its old value.
During a SET, GT.M evaluates the right side of the equal sign before the left; this is an exception to the left-to-right order of evaluation in GT.M and means that GT.M maintains the naked indicator using the expression on the right-hand side of the equal sign (=) before setting the variable.
When the portion of the argument to the left of the equal sign is in the form of a $PIECE function, SET replaces the specified piece or pieces of the variable (specified as the first argument to the $PIECE() form) with the value of the expression on the right side of the equal-sign; if the variable did not exist prior to the SET or does not currently contain the pieces identified by the optional third and fourth arguments to the $PIECE() form, SET adds sufficient leading delimiters, as specified by the second argument to the $PIECE form, to make the assignment fit the $PIECE() form. Note that if the fourth argument exceeds the third argument, SET does not modify the target glvn or change the naked indicator.
When the portion of the argument to the left of the equal sign is in the form of a $EXTRACT function, SET replaces the specified character or characters of the variable (specified as the first argument to the $EXTRACT() form) with the value of the expression on the right side of the equal-sign; if the variable did not exist prior to the SET or does not contain the characters identified by the optional second and third arguments to the $EXTRACT() form, SET adds sufficient leading spaces to make the assignment fit the $EXTRACT() form. Note that if the third argument exceeds the second argument, SET does not modify the target glvn or change the naked indicator .
isv on the left-hand side of the equal-sign specifies an Intrinsic Special Variable. Not all ISVs permit SET updates by the application - see the description of the individual ISV.
When the portion of the argument to the left of the equal-sign is in the form of a list of setlefts enclosed in parentheses, SET assigns the value of the expression on the right of the equal sign to all the destinations.
If a SET updates a global node matching a trigger definition, GT.M executes the trigger code after the node has been updated in the process address space, but before it is applied to the database. When the trigger execution completes, the trigger logic commits the value of a node from the process address space only if $ZTVALUE is not set. if $ZTVALUE is set during trigger execution, the trigger logic commits the value of a node from the value of $ZTVALUE. For more information on using SET in Triggers, refer to “Set” section in the Triggers chapter.
A SET * command explicitly makes the lvn on the left-hand side of the equal-sign an alias if it is an unsubscripted lvn (the root of an array) or an alias container if it is a subscripted lvn. If the portion of the argument on the right-hand side of the equal-sign is other than an lname (the root of an array), it must evaluate to an alias or alias container. Extrinsic functions and extrinsic special variables return an alias container if they terminate with a QUIT *. For more information on Alias Variables, refer to “Alias Variables Extensions”.
In a SET * command, any previous array associated with the lvn on the left-hand side of the equal-sign ceases to be associated with it, and if lvn was the only lvn associated with that (old) array in any scope, GT.M may reclaim the space it occupied. Alias assignment does not require that any data set exist for a name on the right-hand side of the equal-sign - the assignment simply creates an association.
SET * left-hand side arguments cannot be parenthetically enclosed lists such as SET (a,*b)=c or SET (*a,*b)=c.
SET and SET * assignments can be combined into one command in a comma separated list, for example, SET *a=b,^c(3)=d(4).
SET * only accepts argument indirection, that is, while SET accepts x="*a=b",@x, SET does not permit x="*a",@x=b or SET x="b",*a=@x.
An indirection operator and an expression atom evaluating to a list of one or more SET arguments form a legal argument for a SET.
A SET with proper syntax always succeeds regardless of the prior state or value of the variable, as long as GT.M can evaluate the expression to the right of the equal sign (=).
For the syntax of $PIECE() or $EXTRACT(), refer to Chapter 7: “Functions”.
Example:
GTM>Kill Set a="x",(b,c)=1,@a="hello" ZWRite a=x b=1 c=1 x="hello" GTM>
The KILL command deletes any previously defined local variables. The SET command has three arguments. The first shows a simple direct assignment. The second shows the form that assigns the same value to multiple variables. The third shows atomic indirection on the left of the equal sign. The ZWRITE command displays the results of the assignments.
Example:
GTM>Set ^(3,4)=^X(1,2)
As GT.M evaluates the right-hand side of the equal sign before the left-hand side within a SET argument, the right-hand expression determines the naked reference indicator prior to evaluation of the left-hand side. Therefore, this example assigns ^X(1,3,4) the value of ^X(1,2).
Example:
GTM>Kill x Set $Piece(x,"^",2)="piece 3" ZWRite x x="^^piece 3" GTM>
This SET demonstrates a "set piece" and shows how SET generates missing delimiters when required. For more information on $PIECE(), refer to Chapter 7: “Functions”.
Example:
GTM>Set x="I love hotdogs"
GTM>Set $Extract(x,3,6)="want"
GTM>Write x
I want hotdogs
GTM>Set $Extract(x,7)=" many "
GTM>Write x
I want many hotdogs
GTM>
The SET $EXTRACT command replaces and extracts the specified characters with the value of the expression on the right hand side of the equal-sign (=). For more information on $EXTRACT(), refer to Chapter 7: “Functions”.
Example:
GTM>kill A,B
GTM>set A=1,A(1)=1,A(2)=2
GTM>set *B=A ; A & B are aliases.
GTM>zwrite B
B=1 ;*
B(1)=1
B(2)=2
GTM>
This SET * command creates an alias associated between A and B. It associates the entire tree of nodes of A including its root and all descendants with B.
Example:
GTM>kill A,B,C
GTM>set A=1,*C(2)=A ; C(2) is a container
GTM>zwrite
A=1 ;*
*C(2)=A
GTM>set *B=C(2) ; B is now an alias
GTM>write B,":",$length(C(2)),":" ; An alias variable provides access but a container doesn't
1:0:
GTM>
This SET * command creates an alias by dereferencing an alias container.