SetString (System function) - Revision history

Tbullock: Oops lost the newline.

2015-10-23T22:32:40Z

Oops lost the newline.

← Older revision		Revision as of 22:32, 23 October 2015
Line 35:		Line 35:

	<li>The <var class="term">oldValue</var> argument makes it possible to use <var>System</var> strings as structures that can be safely updated by multiple users. For example, one might want to maintain a system-wide counter. This can be accomplished as follows:		<li>The <var class="term">oldValue</var> argument makes it possible to use <var>System</var> strings as structures that can be safely updated by multiple users. For example, one might want to maintain a system-wide counter. This can be accomplished as follows:
	<p class="code">%value is float%newValue is float		<p class="code">%value is float
			%newValue is float

	%value = %(system):string('Counter')		%value = %(system):string('Counter')

Tbullock: Align, and make the data types agree.

2015-10-23T22:31:30Z

Align, and make the data types agree.

← Older revision		Revision as of 22:31, 23 October 2015
Line 35:		Line 35:

	<li>The <var class="term">oldValue</var> argument makes it possible to use <var>System</var> strings as structures that can be safely updated by multiple users. For example, one might want to maintain a system-wide counter. This can be accomplished as follows:		<li>The <var class="term">oldValue</var> argument makes it possible to use <var>System</var> strings as structures that can be safely updated by multiple users. For example, one might want to maintain a system-wide counter. This can be accomplished as follows:
	<p class="code">%value is ~~longString~~		<p class="code">%value is float%newValue is float
	%newValue is float

	%value = %(system):string('Counter')		%value = %(system):string('Counter')
Line 43:		Line 42:
	</p>		</p>
	Unfortunately, another thread might update the value of the counter between the time the above code retrieves the value (with <var>[[String_(System_function)\|String]]</var>) and the time it updates it (with <var>SetString</var>). In such a case, an increment of the counter might be missed. This is more likely, of course, in an <var class="product">MP/204</var> environment, but you should not count on it being impossible in a non-<var class="product">MP/204</var> environment. To safely update a counter, you can do the following:		Unfortunately, another thread might update the value of the counter between the time the above code retrieves the value (with <var>[[String_(System_function)\|String]]</var>) and the time it updates it (with <var>SetString</var>). In such a case, an increment of the counter might be missed. This is more likely, of course, in an <var class="product">MP/204</var> environment, but you should not count on it being impossible in a non-<var class="product">MP/204</var> environment. To safely update a counter, you can do the following:
	<p class="code">%value is ~~longString~~		<p class="code">%value is float
	%newValue is float		%newValue is float
	%success is float		%success is float

	repeat while not %success		repeat while not %success
Line 58:		Line 57:

	<li>This technique can be used with considerably more complex data-structures. For example, one can actually store a serialized <var>[[XmlDoc_API#The_XmlDoc_class\|XmlDoc]]</var> in a <var>system</var> string. A request can retrieve the current structure, manipulate it, and then replace the updated structure:		<li>This technique can be used with considerably more complex data-structures. For example, one can actually store a serialized <var>[[XmlDoc_API#The_XmlDoc_class\|XmlDoc]]</var> in a <var>system</var> string. A request can retrieve the current structure, manipulate it, and then replace the updated structure:
	<p class="code">%value is longString		<p class="code">%value is longString
	%newValue is longString		%newValue is longString
	%myDoc is object xmlDoc		%myDoc is object xmlDoc
	%success is float		%success is float

JALWiccan: Automatically generated page update

2014-02-16T00:26:59Z

Automatically generated page update

← Older revision		Revision as of 00:26, 16 February 2014
Line 9:		Line 9:
	<tr><th>%number</th><td>A numeric result that indicates whether the string update succeeded. <var class="term">%number</var> is set to 1 upon success. If <var class="term">oldValue</var> is specified and does not match the current setting of the string, the update is not performed and a 0 is returned.</td></tr>		<tr><th>%number</th><td>A numeric result that indicates whether the string update succeeded. <var class="term">%number</var> is set to 1 upon success. If <var class="term">oldValue</var> is specified and does not match the current setting of the string, the update is not performed and a 0 is returned.</td></tr>

	<tr><th><var>%(System)</var></th>		<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>SetString</var> can also be invoked via a <var>System</var> object variable, which may be <var>null</var>.</td></tr>		<td>The class name in parentheses denotes a [[Notation conventions for methods#Shared methods\|shared]] method. <var>SetString</var> can also be invoked via a <var>System</var> object variable, which may be <var>null</var>.</td></tr>

JAL at 20:36, 16 November 2012

2012-11-16T20:36:58Z

← Older revision		Revision as of 20:36, 16 November 2012
Line 50:		Line 50:
	%value = %(system):string('Counter')		%value = %(system):string('Counter')
	%newValue = %value + 1		%newValue = %value + 1
	%success = %(system):setString('Counter', %newValue, -		%success = %(system):setString('Counter', %newValue, %value)
	%value)
	end repeat		end repeat
	</p>		</p>
	If no user has updated Counter between the <var>[[String_(System_function)\|String]]</var> and the <var>SetString</var> methods, the update would succeed. If some other user has updated it, the update would not be performed, <var>SetString</var> would return a 0, and the repeat loop would be repeated.		If no user has updated <code>Counter</code> between the <var>[[String_(System_function)\|String]]</var> and the <var>SetString</var> methods, the update would succeed. If some other user has updated it, the update would not be performed, <var>SetString</var> would return a 0, and the repeat loop would be repeated.
	<p>While this looks nasty — it seems the code could loop forever — it's not that bad. Since the only thing that causes the <var>SetString</var> to fail is another user updating the same string at the same time; even if a hundred users were in this loop, at least one of them would succeed on each iteration. So unless the system is doing almost nothing else, all the updates would be performed in fairly short order.</p>		<p>
			While this looks nasty — it seems the code could loop forever — it's not that bad. Since the only thing that causes the <var>SetString</var> to fail is another user updating the same string at the same time; even if a hundred users were in this loop, at least one of them would succeed on each iteration. So unless the system is doing almost nothing else, all the updates would be performed in fairly short order.</p>

	<li>This technique can be used with considerably more complex data-structures. For example, one can actually store a serialized <var>[[XmlDoc_API#The_XmlDoc_class\|XmlDoc]]</var> in a <var>system</var> string. A request can retrieve the current structure, manipulate it, and then replace the updated structure:		<li>This technique can be used with considerably more complex data-structures. For example, one can actually store a serialized <var>[[XmlDoc_API#The_XmlDoc_class\|XmlDoc]]</var> in a <var>system</var> string. A request can retrieve the current structure, manipulate it, and then replace the updated structure:

JAL: /* Examples */

2012-11-16T20:34:33Z

Examples

← Older revision		Revision as of 20:34, 16 November 2012
Line 31:		Line 31:
	==Examples==		==Examples==
	<ol>		<ol>
	<li>The following statement sets the system string called DIAMONDS:		<li>The following statement sets the system string called <code>DIAMONDS</code>:
	<p class="code">%(system):setString('DIAMONDS', 'CLEAR')</p>		<p class="code">%(system):setString('DIAMONDS', 'CLEAR')</p>

JAL: /* Examples */

2012-11-06T18:20:53Z

Examples

← Older revision		Revision as of 18:20, 6 November 2012
Line 55:		Line 55:
	</p>		</p>
	If no user has updated Counter between the <var>[[String_(System_function)\|String]]</var> and the <var>SetString</var> methods, the update would succeed. If some other user has updated it, the update would not be performed, <var>SetString</var> would return a 0, and the repeat loop would be repeated.		If no user has updated Counter between the <var>[[String_(System_function)\|String]]</var> and the <var>SetString</var> methods, the update would succeed. If some other user has updated it, the update would not be performed, <var>SetString</var> would return a 0, and the repeat loop would be repeated.
	<p>While this looks nasty &~~amp;amp;#x2014~~; it seems the code could loop forever &~~amp;amp;#x2014~~; it's not that bad. Since the only thing that causes the <var>SetString</var> to fail is another user updating the same string at the same time; even if a hundred users were in this loop, at least one of them would succeed on each iteration. So unless the system is doing almost nothing else, all the updates would be performed in fairly short order.</p>		<p>While this looks nasty — it seems the code could loop forever — it's not that bad. Since the only thing that causes the <var>SetString</var> to fail is another user updating the same string at the same time; even if a hundred users were in this loop, at least one of them would succeed on each iteration. So unless the system is doing almost nothing else, all the updates would be performed in fairly short order.</p>

	<li>This technique can be used with considerably more complex data-structures. For example, one can actually store a serialized <var>[[XmlDoc_API#The_XmlDoc_class\|XmlDoc]]</var> in a <var>system</var> string. A request can retrieve the current structure, manipulate it, and then replace the updated structure:		<li>This technique can be used with considerably more complex data-structures. For example, one can actually store a serialized <var>[[XmlDoc_API#The_XmlDoc_class\|XmlDoc]]</var> in a <var>system</var> string. A request can retrieve the current structure, manipulate it, and then replace the updated structure:

JAL: /* Examples */

2012-11-06T18:19:13Z

Examples

← Older revision		Revision as of 18:19, 6 November 2012
Line 33:		Line 33:
	<li>The following statement sets the system string called DIAMONDS:		<li>The following statement sets the system string called DIAMONDS:
	<p class="code">%(system):setString('DIAMONDS', 'CLEAR')</p>		<p class="code">%(system):setString('DIAMONDS', 'CLEAR')</p>

	<li>The <var class="term">oldValue</var> argument makes it possible to use <var>System</var> strings as structures that can be safely updated by multiple users. For example, one might want to maintain a system-wide counter. This can be accomplished as follows:		<li>The <var class="term">oldValue</var> argument makes it possible to use <var>System</var> strings as structures that can be safely updated by multiple users. For example, one might want to maintain a system-wide counter. This can be accomplished as follows:
	<p class="code">%value is longString		<p class="code">%value is longString
Line 73:		Line 74:
	</p>		</p>
	Note that the above code assumes that the <code>Complicated</code> system string is already set. If the application cannot guarantee that <code>Complicated</code> has been set, there should be a test for the null string, bypassing the <var>[[LoadXml_(XmlDoc/XmlNode_function)\|loadXml]]</var> operation and instead populating the <var>XmlDoc</var> with some initial nodes.		Note that the above code assumes that the <code>Complicated</code> system string is already set. If the application cannot guarantee that <code>Complicated</code> has been set, there should be a test for the null string, bypassing the <var>[[LoadXml_(XmlDoc/XmlNode_function)\|loadXml]]</var> operation and instead populating the <var>XmlDoc</var> with some initial nodes.
	<p>The document is stored in the system string in EBCDIC. This is not necessary &~~amp;amp;#x2014~~; the document could be stored in UTF-8 encoding &~~amp;amp;#x2014~~; it is just easier to debug this code if it is saved in EBCDIC.</p>		<p>
			The document is stored in the system string in EBCDIC. This is not necessary — the document could be stored in UTF-8 encoding — it is just easier to debug this code if it is saved in EBCDIC.</p>
	</ol>		</ol>

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

JALWiccan: 1 revision

2012-11-06T17:46:14Z

1 revision

← Older revision	Revision as of 17:46, 6 November 2012
(No difference)

JAL at 17:46, 6 November 2012

2012-11-06T17:46:03Z

← Older revision		Revision as of 17:46, 6 November 2012
Line 54:		Line 54:
	</p>		</p>
	If no user has updated Counter between the <var>[[String_(System_function)\|String]]</var> and the <var>SetString</var> methods, the update would succeed. If some other user has updated it, the update would not be performed, <var>SetString</var> would return a 0, and the repeat loop would be repeated.		If no user has updated Counter between the <var>[[String_(System_function)\|String]]</var> and the <var>SetString</var> methods, the update would succeed. If some other user has updated it, the update would not be performed, <var>SetString</var> would return a 0, and the repeat loop would be repeated.
	<p>While this looks nasty &~~amp;amp;amp;~~amp;amp;#x2014; it seems the code could loop forever &~~amp;amp;amp;~~amp;amp;#x2014; it's not that bad. Since the only thing that causes the <var>SetString</var> to fail is another user updating the same string at the same time; even if a hundred users were in this loop, at least one of them would succeed on each iteration. So unless the system is doing almost nothing else, all the updates would be performed in fairly short order.</p>		<p>While this looks nasty &amp;#x2014; it seems the code could loop forever &amp;#x2014; it's not that bad. Since the only thing that causes the <var>SetString</var> to fail is another user updating the same string at the same time; even if a hundred users were in this loop, at least one of them would succeed on each iteration. So unless the system is doing almost nothing else, all the updates would be performed in fairly short order.</p>

	<li>This technique can be used with considerably more complex data-structures. For example, one can actually store a serialized <var>[[XmlDoc_API#The_XmlDoc_class\|XmlDoc]]</var> in a <var>system</var> string. A request can retrieve the current structure, manipulate it, and then replace the updated structure:		<li>This technique can be used with considerably more complex data-structures. For example, one can actually store a serialized <var>[[XmlDoc_API#The_XmlDoc_class\|XmlDoc]]</var> in a <var>system</var> string. A request can retrieve the current structure, manipulate it, and then replace the updated structure:
Line 73:		Line 73:
	</p>		</p>
	Note that the above code assumes that the <code>Complicated</code> system string is already set. If the application cannot guarantee that <code>Complicated</code> has been set, there should be a test for the null string, bypassing the <var>[[LoadXml_(XmlDoc/XmlNode_function)\|loadXml]]</var> operation and instead populating the <var>XmlDoc</var> with some initial nodes.		Note that the above code assumes that the <code>Complicated</code> system string is already set. If the application cannot guarantee that <code>Complicated</code> has been set, there should be a test for the null string, bypassing the <var>[[LoadXml_(XmlDoc/XmlNode_function)\|loadXml]]</var> operation and instead populating the <var>XmlDoc</var> with some initial nodes.
	<p>The document is stored in the system string in EBCDIC. This is not necessary &~~amp;amp;amp;~~amp;amp;#x2014; the document could be stored in UTF-8 encoding &~~amp;amp;amp;~~amp;amp;#x2014; it is just easier to debug this code if it is saved in EBCDIC.</p>		<p>The document is stored in the system string in EBCDIC. This is not necessary &amp;#x2014; the document could be stored in UTF-8 encoding &amp;#x2014; it is just easier to debug this code if it is saved in EBCDIC.</p>
	</ol>		</ol>

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

JAL at 00:30, 1 November 2012

2012-11-01T00:30:03Z

← Older revision		Revision as of 00:30, 1 November 2012
Line 1:		Line 1:
	{{Template:System:SetString subtitle}}		{{Template:System:SetString subtitle}}
	The <var>SetString</var> shared callable function sets a [[System class#System and subsystem globals and strings\|system-wide string]].		The <var>SetString</var> shared [[Notation conventions for methods#Callable functions\|callable]] function sets a [[System class#System and subsystem globals and strings\|system-wide string]].

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

	===Syntax terms===		===Syntax terms===
	<table class="syntaxTable">		<table class="syntaxTable">
	<tr><th>%number</th><td>A numeric result that indicates whether the string update succeeded. <var class="term">%number</var> is set to 1 upon success. If <var class="term">oldValue</var> is specified and does not match the current setting of the string, the update is not performed and a 0 is returned.</td></tr>		<tr><th>%number</th><td>A numeric result that indicates whether the string update succeeded. <var class="term">%number</var> is set to 1 upon success. If <var class="term">oldValue</var> is specified and does not match the current setting of the string, the update is not performed and a 0 is returned.</td></tr>

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

	<tr><th>name</th>		<tr><th>name</th>
	<td>A string that identifies the global string to be set.</td></tr>		<td>A string that identifies the global string to be set.</td></tr>

	<tr><th>value</th>		<tr><th>value</th>
	<td>A string that identifies the new value for the global string.</td></tr>		<td>A string that identifies the new value for the global string.</td></tr>

	<tr><th>oldValue</th>		<tr><th>oldValue</th>
	<td>A string that identifies a value to be compared against the current value of the <var>System</var> string before doing the update. This is an optional argument.</td></tr>		<td>A string that identifies a value to be compared against the current value of the <var>System</var> string before doing the update. This is an optional argument.</td></tr>
Line 18:		Line 23:

	==Usage notes==		==Usage notes==
	<ul><li>All errors result in request cancellation.		<ul>
			<li>All errors result in request cancellation.
	<li>It is not an error to set a string that is not set.		<li>It is not an error to set a string that is not set.
	<li>Unlike <var>[[SetGlobal_(System_subroutine)#Usage_notes\|SetGlobal]]</var>, <var>SetString</var> does not turn off multiprocessing, and it is designed for fairly high levels of updating.		<li>Unlike <var>[[SetGlobal_(System_subroutine)#Usage_notes\|SetGlobal]]</var>, <var>SetString</var> does not turn off multiprocessing, and it is designed for fairly high levels of updating.
Line 24:		Line 30:

	==Examples==		==Examples==
	<ol><li>The following statement sets the system string called DIAMONDS:		<ol>
			<li>The following statement sets the system string called DIAMONDS:
	<p class="code">%(system):setString('DIAMONDS', 'CLEAR')</p>		<p class="code">%(system):setString('DIAMONDS', 'CLEAR')</p>
	<li>The <var class="term">oldValue</var> argument makes it possible to use <var>System</var> strings as structures that can be safely updated by multiple users. For example, one might want to maintain a system-wide counter. This can be accomplished as follows:		<li>The <var class="term">oldValue</var> argument makes it possible to use <var>System</var> strings as structures that can be safely updated by multiple users. For example, one might want to maintain a system-wide counter. This can be accomplished as follows:
Line 48:		Line 55:
	If no user has updated Counter between the <var>[[String_(System_function)\|String]]</var> and the <var>SetString</var> methods, the update would succeed. If some other user has updated it, the update would not be performed, <var>SetString</var> would return a 0, and the repeat loop would be repeated.		If no user has updated Counter between the <var>[[String_(System_function)\|String]]</var> and the <var>SetString</var> methods, the update would succeed. If some other user has updated it, the update would not be performed, <var>SetString</var> would return a 0, and the repeat loop would be repeated.
	<p>While this looks nasty &amp;amp;amp;amp;#x2014; it seems the code could loop forever &amp;amp;amp;amp;#x2014; it's not that bad. Since the only thing that causes the <var>SetString</var> to fail is another user updating the same string at the same time; even if a hundred users were in this loop, at least one of them would succeed on each iteration. So unless the system is doing almost nothing else, all the updates would be performed in fairly short order.</p>		<p>While this looks nasty &amp;amp;amp;amp;#x2014; it seems the code could loop forever &amp;amp;amp;amp;#x2014; it's not that bad. Since the only thing that causes the <var>SetString</var> to fail is another user updating the same string at the same time; even if a hundred users were in this loop, at least one of them would succeed on each iteration. So unless the system is doing almost nothing else, all the updates would be performed in fairly short order.</p>

	<li>This technique can be used with considerably more complex data-structures. For example, one can actually store a serialized <var>[[XmlDoc_API#The_XmlDoc_class\|XmlDoc]]</var> in a <var>system</var> string. A request can retrieve the current structure, manipulate it, and then replace the updated structure:		<li>This technique can be used with considerably more complex data-structures. For example, one can actually store a serialized <var>[[XmlDoc_API#The_XmlDoc_class\|XmlDoc]]</var> in a <var>system</var> string. A request can retrieve the current structure, manipulate it, and then replace the updated structure:
	<p class="code">%value is longString		<p class="code">%value is longString