ToXmlDoc (Record function) - Revision history

JAL: /* Examples */

2014-07-31T20:48:37Z

Examples

← Older revision		Revision as of 20:48, 31 July 2014
Line 253:		Line 253:

	==Examples==		==Examples==
	In addition to the example in the following section, see the [[NewFromRecord (XmlDoc function)#Handling records with null characters\|"Handling records with null characters"]] example in the <var>NewFromRecord</var> article, which applies equally to <var>ToXmlDoc</var>.		In addition to the example in the following section, see the [[NewFromRecord (XmlDoc function)#Handling records with null characters\|Handling records with null characters]] example in the <var>NewFromRecord</var> article, which applies equally to <var>ToXmlDoc</var>.

	====AttributeValues, AttributeNames, and NamesToLower arguments====		====AttributeValues, AttributeNames, and NamesToLower arguments====
Line 314:		Line 314:

	====Getting record lock====		====Getting record lock====
	As stated in the [[#othusage\|"Usage notes"]] above, a record lock of at least <var>Share</var> strength is required for the record processed by <var>ToXmlDoc</var>. If you are processing an unlocked record set, you can use the <var>[[LoopLockStrength (Recordset property)\|LoopLockStrength]]</var> property so that for each iteration of a <var>For Each Record</var> loop using the recordset, the current record is locked, as shown in the following example:		As stated in the [[#othusage\|Usage notes]] above, a record lock of at least <var>Share</var> strength is required for the record processed by <var>ToXmlDoc</var>. If you are processing an unlocked record set, you can use the <var>[[LoopLockStrength (Recordset property)\|LoopLockStrength]]</var> property so that for each iteration of a <var>For Each Record</var> loop using the recordset, the current record is locked, as shown in the following example:
	<p class="code">%recSet is object recordset in QAWORK		<p class="code">%recSet is object recordset in QAWORK
	* In this fragment, %rec is null, only used to qualify the currentRecord constructor		* In this fragment, %rec is null, only used to qualify the currentRecord constructor

JAL: /* Usage notes */

2014-07-31T20:47:00Z

Usage notes

← Older revision		Revision as of 20:47, 31 July 2014
Line 249:		Line 249:
	No locks are required for a sorted record or in single-user mode.		No locks are required for a sorted record or in single-user mode.

	See [[#Getting record lock\|"Getting record lock"]] below for an example of obtaining a share record lock when processing an unlocked found set.		See [[#Getting record lock\|Getting record lock]] below for an example of obtaining a share record lock when processing an unlocked found set.
	</ul>		</ul>

JAL: /* Syntax terms */

2014-07-31T20:44:47Z

Syntax terms

← Older revision		Revision as of 20:44, 31 July 2014
Line 41:		Line 41:
	<tr><th><var>AllowUnreversible</var></th>		<tr><th><var>AllowUnreversible</var></th>
	<td>This name required argument is a <var>Boolean</var> value that indicates whether a request is cancelled if a field name would be changed irreversibly by lowercasing or by replacing with a period the characters that would be invalid in an XML document.		<td>This name required argument is a <var>Boolean</var> value that indicates whether a request is cancelled if a field name would be changed irreversibly by lowercasing or by replacing with a period the characters that would be invalid in an XML document.
	For example, as described below in "Usage Notes," fields <code>FOO BAR</code> and <code>FOO%BAR</code> would both produce the element name <code>FOO.BAR</code> if <var>AttributeNames<var> is set to <code>False</code>. This will cause request cancellation unless <var>AllowUnreversible<var> is set to <code>True</code>.		For example, as described below in "Usage Notes," fields <code>FOO BAR</code> and <code>FOO%BAR</code> would both produce the element name <code>FOO.BAR</code> if <var>AttributeNames</var> is set to <code>False</code>. This will cause request cancellation unless <var>AllowUnreversible</var> is set to <code>True</code>.
	The default value is <var>False</var>, which allows request cancellation to alert you about unreversible field names.</td></tr>		The default value is <var>False</var>, which allows request cancellation to alert you about unreversible field names.</td></tr>

JAL at 20:40, 31 July 2014

2014-07-31T20:40:45Z

← Older revision		Revision as of 20:40, 31 July 2014
Line 5:		Line 5:

	The record extraction performed by <var>ToXmlDoc</var> is the		The record extraction performed by <var>ToXmlDoc</var> is the
	same operation that is performed by the [[XmlDoc API]] methods <var>[[LoadFromRecord (XmlDoc/XmlNode subroutine)\|LoadFromRecord]]</var> and <var>[[NewFromRecord (XmlDoc function)\|NewFromRecord]]</var>, as is further described below in [[#Usage notes\|"Usage notes"]].		same operation that is performed by the [[XmlDoc API]] methods <var>[[LoadFromRecord (XmlDoc/XmlNode subroutine)\|LoadFromRecord]]</var> and <var>[[NewFromRecord (XmlDoc function)\|NewFromRecord]]</var>, as is further described below in [[#Usage notes\|Usage notes]].

	<var>ToXmlDoc</var> is available in <var class="product">Sirius Mods</var> version 7.3 and later.		<var>ToXmlDoc</var> is available in <var class="product">Sirius Mods</var> version 7.3 and later.

JAL: /* Syntax terms */

2013-12-12T17:25:30Z

Syntax terms

← Older revision		Revision as of 17:25, 12 December 2013
Line 55:		Line 55:
	<tr><th><var>Base64Encode</var></th>		<tr><th><var>Base64Encode</var></th>
	<td>This name required argument is a <var>Boolean</var> value.		<td>This name required argument is a <var>Boolean</var> value.
	<p>The default is <var>True</var>, which indicates that before storing a field's value in the <var>XmlDoc</var>, the value is base64 encoded <b>if needed</b>. See the [[#casEnc\|usage note]] below ~~which~~ describes the conditions that would require base64 encoding.</p>		<p>The default is <var>True</var>, which indicates that before storing a field's value in the <var>XmlDoc</var>, the value is base64 encoded <b>if needed</b>. See the [[#casEnc\|usage note]] below that describes the conditions that would require base64 encoding.</p>
	<p>If ~~its~~ value is <var>False</var>, ~~then~~ field values are not base64 encoded~~; that is, control~~ and uninvertible characters are translated to their Unicode counterparts~~, and it also means that~~ X'00' (if the <var>AllowNull</var> argument is not <var>True</var>) and untranslatable characters can cause request cancellation, unless they are mapped by the <var>CharacterMap</var> argument. (An unmapped untranslatable character actually throws a <var>[[CharacterTranslationException class\|CharacterTranslationException]]</var> exception, which results in cancellation if not caught.)</p>		<p>
	<p><var>Base64Encode</var> is available as of <var class="product">Model 204</var> version 7.5.</p> </td></tr>		If <var>Base64Encode</var> value is <var>False</var>, field values are not base64 encoded. This means: </p>
			<ul>
			<li>Control and uninvertible characters are translated to their Unicode counterparts.
			<li>X'00' (if the <var>AllowNull</var> argument is not <var>True</var>) and untranslatable characters can cause request cancellation, unless they are mapped by the <var>CharacterMap</var> argument. (An unmapped untranslatable character actually throws a <var>[[CharacterTranslationException class\|CharacterTranslationException]]</var> exception, which results in cancellation if not caught.)
			</ul>
			<p>
			<var>Base64Encode</var> is available as of <var class="product">Model 204</var> version 7.5.</p> </td></tr>

	<tr><th><var>CharacterMap</var></th>		<tr><th><var>CharacterMap</var></th>

JAL at 16:50, 12 December 2013

2013-12-12T16:50:31Z

← Older revision		Revision as of 16:50, 12 December 2013
Line 114:		Line 114:
	the <var>AllowUnreversible</var> parameter.		the <var>AllowUnreversible</var> parameter.

	<li>In versions of <var class="product">Model 204</var> prior to 7.5, the effect of the <var>Base64Encoding</var>=<var>False</var> argument can be accomplished by post-processing the <var>XmlDoc</var> and replacing values which have an <code>encoding="base64"</code> attribute with the ~~base 64~~ decoded value translated to Unicode.		<li>In versions of <var class="product">Model 204</var> prior to 7.5, the effect of the <var>Base64Encoding</var>=<var>False</var> argument can be accomplished by post-processing the <var>XmlDoc</var> and replacing values which have an <code>encoding="base64"</code> attribute with the base64 decoded value translated to Unicode.

	<li>UTF8 and UTF16 fields are copied directly to the <var>XmlDoc</var>; there is no translation (either automatic or using		<li>UTF8 and UTF16 fields are copied directly to the <var>XmlDoc</var>; there is no translation (either automatic or using
	the <var>CharacterMap</var> argument) nor ~~base 64~~ encoding involved for them.		the <var>CharacterMap</var> argument) nor base64 encoding involved for them.

	<li>The <var>Base64Encode</var>=<var>False</var> argument can be used to disable any ~~base 64~~ encoding of field values.		<li>The <var>Base64Encode</var>=<var>False</var> argument can be used to disable any base64 encoding of field values.

	Alternatively, the <var>CharacterMap</var> argument (with a non-null value) can be used to disable any ~~base 64~~ encoding of field values, and to specify translations, which can avoid request cancellation due to X'00' and/or untranslatable characters in field values.		Alternatively, the <var>CharacterMap</var> argument (with a non-null value) can be used to disable any base64 encoding of field values, and to specify translations, which can avoid request cancellation due to X'00' and/or untranslatable characters in field values.

	<div id="casEnc"></div>		<div id="casEnc"></div>

JAL: /* Syntax terms */

2013-12-12T16:45:54Z

Syntax terms

← Older revision		Revision as of 16:45, 12 December 2013
Line 56:		Line 56:
	<td>This name required argument is a <var>Boolean</var> value.		<td>This name required argument is a <var>Boolean</var> value.
	<p>The default is <var>True</var>, which indicates that before storing a field's value in the <var>XmlDoc</var>, the value is base64 encoded <b>if needed</b>. See the [[#casEnc\|usage note]] below which describes the conditions that would require base64 encoding.</p>		<p>The default is <var>True</var>, which indicates that before storing a field's value in the <var>XmlDoc</var>, the value is base64 encoded <b>if needed</b>. See the [[#casEnc\|usage note]] below which describes the conditions that would require base64 encoding.</p>
	<p>If its value is <var>False</var>, then field values are not ~~base 64~~ encoded; that is, control and uninvertible characters are translated to their Unicode counterparts, and it also means that X'00' (if the <var>AllowNull</var> argument is not <var>True</var>) and untranslatable characters can cause request cancellation, unless they are mapped by the <var>CharacterMap</var> argument. (An unmapped untranslatable character actually throws a <var>[[CharacterTranslationException class\|CharacterTranslationException]]</var> exception, which results in cancellation if not caught.)</p>		<p>If its value is <var>False</var>, then field values are not base64 encoded; that is, control and uninvertible characters are translated to their Unicode counterparts, and it also means that X'00' (if the <var>AllowNull</var> argument is not <var>True</var>) and untranslatable characters can cause request cancellation, unless they are mapped by the <var>CharacterMap</var> argument. (An unmapped untranslatable character actually throws a <var>[[CharacterTranslationException class\|CharacterTranslationException]]</var> exception, which results in cancellation if not caught.)</p>
	<p><var>Base64Encode</var> is available as of <var class="product">Model 204</var> version 7.5.</p> </td></tr>		<p><var>Base64Encode</var> is available as of <var class="product">Model 204</var> version 7.5.</p> </td></tr>

Line 65:		Line 65:

	<tr><th><var>AllowNull</var></th>		<tr><th><var>AllowNull</var></th>
	<td>The value of this name required <var>Boolean</var> argument, which defaults to <var>False</var>, is copied to the <var>[[AllowNull (XmlDoc property)\|AllowNull]]</var> property of the <var>XmlDoc</var> created by <var>ToXmlDoc</var>. The <var>XmlDoc</var>'s <var>AllowNull</var> property, in turn, determines whether field values that contain the X'00' character are stored in the <var>XmlDoc</var> with base64 encoding. Such values are base64 encoded if the <var>AllowNull</var> property is <var>False</var> (the default). For an example, see [[#Handling records with null characters\|"Handling records with null characters"]] in the <var>[[NewFromRecord (XmlDoc function)\|NewFromRecord]]</var> method description.		<td>The value of this name required <var>Boolean</var> argument, which defaults to <var>False</var>, is copied to the <var>[[AllowNull (XmlDoc property)\|AllowNull]]</var> property of the <var>XmlDoc</var> created by <var>ToXmlDoc</var>. The <var>XmlDoc</var>'s <var>AllowNull</var> property, in turn, determines whether field values that contain the X'00' character are stored in the <var>XmlDoc</var> with base64 encoding. Such values are base64 encoded if the <var>AllowNull</var> property is <var>False</var> (the default). For an example, see [[#Handling records with null characters\|Handling records with null characters]] in the <var>[[NewFromRecord (XmlDoc function)\|NewFromRecord]]</var> method description.
	<p><var>AllowNull</var> is available as of <var class="product">Sirius Mods</var> version 7.7.</p>		<p><var>AllowNull</var> is available as of <var class="product">Sirius Mods</var> version 7.7.</p>
	</td></tr>		</td></tr>

JAL: /* Syntax terms */

2013-12-12T16:41:24Z

Syntax terms

← Older revision		Revision as of 16:41, 12 December 2013
Line 55:		Line 55:
	<tr><th><var>Base64Encode</var></th>		<tr><th><var>Base64Encode</var></th>
	<td>This name required argument is a <var>Boolean</var> value.		<td>This name required argument is a <var>Boolean</var> value.
	<p>The default is <var>True</var>, which indicates that before storing a field's value in the <var>XmlDoc</var> it is, <b>if needed</b>~~, base 64 encoded~~. See the [[#casEnc\|usage note]] below which describes ~~those~~ conditions ~~which~~ would require ~~base 64~~ encoding.</p>		<p>The default is <var>True</var>, which indicates that before storing a field's value in the <var>XmlDoc</var>, the value is base64 encoded <b>if needed</b>. See the [[#casEnc\|usage note]] below which describes the conditions that would require base64 encoding.</p>
	<p>If its value is <var>False</var>, then field values are not base 64 encoded; that is, control and uninvertible characters are translated to their Unicode counterparts, and it also means that X'00' (if the <var>AllowNull</var> argument is not <var>True</var>) and untranslatable characters can cause request cancellation, unless they are mapped by the <var>CharacterMap</var> argument. (An unmapped untranslatable character actually throws a <var>[[CharacterTranslationException class\|CharacterTranslationException]]</var> exception, which results in cancellation if not caught.)</p>		<p>If its value is <var>False</var>, then field values are not base 64 encoded; that is, control and uninvertible characters are translated to their Unicode counterparts, and it also means that X'00' (if the <var>AllowNull</var> argument is not <var>True</var>) and untranslatable characters can cause request cancellation, unless they are mapped by the <var>CharacterMap</var> argument. (An unmapped untranslatable character actually throws a <var>[[CharacterTranslationException class\|CharacterTranslationException]]</var> exception, which results in cancellation if not caught.)</p>
	<p><var>Base64Encode</var> is available as of <var class="product">Model 204</var> version 7.5.</p> </td></tr>		<p><var>Base64Encode</var> is available as of <var class="product">Model 204</var> version 7.5.</p> </td></tr>

Dme: /* Usage notes */

2013-11-15T18:45:42Z

Usage notes

← Older revision		Revision as of 18:45, 15 November 2013
Line 119:		Line 119:
	the <var>CharacterMap</var> argument) nor base 64 encoding involved for them.		the <var>CharacterMap</var> argument) nor base 64 encoding involved for them.

	<li>The <var>Base64Encode</var>=<var>False</var> argument can be used ~~with the <var>[[LoadFromRecord (XmlDoc method)\|LoadFromRecord]]</var> method~~ to disable any base 64 encoding of field values.		<li>The <var>Base64Encode</var>=<var>False</var> argument can be used to disable any base 64 encoding of field values.

	Alternatively, the <var>CharacterMap</var> argument (with a non-null value) can be used to disable any base 64 encoding of field values, and to specify translations, which can avoid request ~~translation~~ due to X'00' and/or untranslatable characters in field values.		Alternatively, the <var>CharacterMap</var> argument (with a non-null value) can be used to disable any base 64 encoding of field values, and to specify translations, which can avoid request cancellation due to X'00' and/or untranslatable characters in field values.

	<div id="casEnc"></div>		<div id="casEnc"></div>

Dme: /* Usage notes */

2013-11-15T18:42:53Z

Usage notes

← Older revision		Revision as of 18:42, 15 November 2013
Line 118:		Line 118:
	<li>UTF8 and UTF16 fields are copied directly to the <var>XmlDoc</var>; there is no translation (either automatic or using		<li>UTF8 and UTF16 fields are copied directly to the <var>XmlDoc</var>; there is no translation (either automatic or using
	the <var>CharacterMap</var> argument) nor base 64 encoding involved for them.		the <var>CharacterMap</var> argument) nor base 64 encoding involved for them.

			<li>The <var>Base64Encode</var>=<var>False</var> argument can be used with the <var>[[LoadFromRecord (XmlDoc method)\|LoadFromRecord]]</var> method to disable any base 64 encoding of field values.

			Alternatively, the <var>CharacterMap</var> argument (with a non-null value) can be used to disable any base 64 encoding of field values, and to specify translations, which can avoid request translation due to X'00' and/or untranslatable characters in field values.

	<div id="casEnc"></div>		<div id="casEnc"></div>
	<li>If the <var>Base64Encode</var> argument is <var>False</var> (the default), and		<li>If the <var>Base64Encode</var> argument is <var>False</var> (the default), and