SetObject (System function): Difference between revisions
Jump to navigation
Jump to search
m (Automatically generated page update) |
m (copied content from PDF and updated to be system only) |
||
| Line 1: | Line 1: | ||
{{Template:System:SetObject subtitle}} | {{Template:System:SetObject subtitle}} | ||
The <var>SetObject</var> method makes a given object available with a specified name to the Online or <var>[[Subsystem_class|Subsystem]]</var>. An object made thus available is known as a [[System_class#System-wide_objects|"system-wide object"]]. | |||
==Syntax== | ==Syntax== | ||
| Line 5: | Line 6: | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>% | <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. | ||
<tr><th>(System)</th> | <p>All other errors result in request cancellation.</p></td></tr> | ||
<td>The class name in parentheses denotes a shared method. SetObject can also be invoked via a System object variable, which may be null.</td></tr> | <tr><th>%(System)</th> | ||
<tr><th> | <td>The class name in parentheses denotes a 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> | ||
<td> | <tr><th>name</th> | ||
<tr><th> | <td>The string name by which the system-wide object is identified.</td></tr> | ||
<td><var> | <tr><th>object</th> | ||
<tr><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> | ||
<td><var> | <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">%obj</var>, and it returns a 0 value.</td></tr> | |||
</table> | </table> | ||
==Examples== | ==Examples== | ||
<ol><li>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 FOO, FOO's generation is compared with %gen. If the generation number changed, the <var>SetObject</var> call does not succeed, and 0 is returned. | |||
</ol> | |||
==See also== | ==See also== | ||
{{Template:System:SetObject footer}} | {{Template:System:SetObject footer}} | ||
Revision as of 05:28, 25 March 2011
Set a system-wide object (System class)
The SetObject method makes a given object available with a specified name to the Online or Subsystem. An object made thus available is known as a "system-wide object".
Syntax
[%gen =] %(System):SetObject( name, object, [testGen])
Syntax terms
| %gen | 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. gen is set to 0 if the method encounters a problem or if testGen differs from the current generation number of name.
All other errors result in request cancellation. |
|---|---|
| %(System) | The class name in parentheses denotes a shared method. SetObject can also be invoked via a System object variable, which may be null. |
| name | The string name by which the system-wide object is identified. |
| object | The object variable that becomes the current system-wide object. The object referenced by object must be "deep copyable"). |
| testGen | An optional argument, this is an integer that is compared to the current generation number of name. If the values differ, SetObject fails to replace %obj, and it returns a 0 value. |
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.
%myObj is object myClass ... retry: %gen = %(system):getObject('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
In this case, when you try to update FOO, FOO's generation is compared with %gen. If the generation number changed, the SetObject call does not succeed, and 0 is returned.