View source for SetObject (System function)

{{Template:System:SetObject subtitle}}
<var>SetObject</var> sets a [[System_class#System-wide_objects|"system-wide object"]].

==Syntax==
{{Template:System:SetObject syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>%gen</th><td>The new generation number associated with name. This is a positive integer (set to 1 the first time the method succeeds) that increases by one each time the name object is updated. <var class="term">gen</var> is set to 0 if the method encounters a problem or if <var class="term">testGen</var> differs from the current generation number of name.
<p>
All other errors result in request cancellation.</p></td></tr>

<tr><th><var class="nobr">%(System)</var></th>
<td>The class name in parentheses denotes a [[Notation conventions for methods#Shared methods|shared]] method. <var>SetObject</var> can also be invoked via a <var>[[System_class|System]]</var> object variable, which may be <var>null</var>.</td></tr>

<tr><th>name</th>
<td>The string name by which the system-wide object is identified.</td></tr>

<tr><th>object</th>
<td>The object variable that becomes the current system-wide object. The object referenced by <var class="term">object</var> must be [[Copying objects|"deep copyable"]]).</td></tr>

<tr><th>testGen</th>
<td>An optional argument, this is an integer that is compared to the current generation number of name. If the values differ, <var>SetObject</var> fails to replace <var class="term">object</var>, and it returns a 0 value.</td></tr>
</table>

==Examples==
The following example shows how the generation number can be used to make sure that you do not update an object that someone else updated after you got your copy.
<p class="code"><nowiki>%myObj is object myClass
  ...
retry:
%gen = %(system):</nowiki>[[GetObject_(System_function)|getObject]]<nowiki>('FOO', %myObj)
  ... fiddle with the object
* Now try to update it
if not %(system):setObject('FOO', %myObj, %gen) then
   * Someone else changed it, let's see what they did
   jump to retry
end if
</nowiki></p>
In this case, when you try to update <code>FOO</code>, <code>FOO</code>'s generation is compared with <code>%gen</code>. If the generation number changed, the <var>SetObject</var> call does not succeed, and 0 is returned.

==See also==
{{Template:System:SetObject footer}}