LoadFromRecord (XmlDoc/XmlNode subroutine) - Revision history

ELowell at 16:58, 4 September 2015

2015-09-04T16:58:56Z

← Older revision		Revision as of 16:58, 4 September 2015
Line 1:		Line 1:
	{{Template:XmlDoc/XmlNode:LoadFromRecord subtitle}}		{{Template:XmlDoc/XmlNode:LoadFromRecord subtitle}}

	This subroutine adds to an <var>XmlDoc</var> object a subtree that contains the fields and		This subroutine adds to an <var>XmlDoc</var> object a subtree that contains the fields and
	fieldgroups from the current record. Among other things, the result <var>XmlDoc</var> can be used to copy a record, using the <var>[[AddToRecord (XmlDoc subroutine)\|AddToRecord]]</var> subroutine.		fieldgroups from the current record. Among other things, the result <var>XmlDoc</var> can be used to copy a record, using the <var>[[AddToRecord (XmlDoc subroutine)\|AddToRecord]]</var> subroutine.

ELowell: /* Copying from multiple source records */

2014-04-07T21:01:12Z

Copying from multiple source records

← Older revision		Revision as of 21:01, 7 April 2014
Line 211:		Line 211:

	You can also use <var>LoadFromRecord</var> to modify the fieldgroup structure		You can also use <var>LoadFromRecord</var> to modify the fieldgroup structure
	within a record (using ~~V7R2~~ of <var class="product">Model 204</var>).		within a record (using V7R5 of <var class="product">Model 204</var>).
	For example, you could take the “outer” fields of one		For example, you could take the “outer” fields of one
	record and move them to be fieldgroup members in the target		record and move them to be fieldgroup members in the target

JAL at 17:30, 12 December 2013

2013-12-12T17:30:57Z

← Older revision		Revision as of 17:30, 12 December 2013
Line 83:		Line 83:
	<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>~~, base64 encoded~~. See ~~the~~ [[#casEnc\|usage note]] ~~below~~ which describes ~~those~~ conditions ~~which~~ 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 [[ToXmlDoc (Record function)#casEnc\|this ToXmlDoc usage note]] which 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>If <var>Base64Encode</var> is <var>False</var>, field values are not base64 encoded. This means: </p>
			<ul>
	<p><var>Base64Encode</var> is available as of <var class="product">Model 204</var> version 7.5.</p> </td></tr>		<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>
Line 126:		Line 131:
	<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 base 64 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 base64 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 to disable any base64 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 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.

	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.

	<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|"Usage notes"]]~~; these~~ apply equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var>. The topics discussed there are:		<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|Usage notes]], which apply equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var>. The topics discussed there are:
	<ul>		<ul>
	<li>~~invalid~~ characters in field names;		<li>Invalid characters in field names
	<li>~~using~~ <var>AllowUnreversible</var> for lowercase or invalid field name characters;		<li>Using <var>AllowUnreversible</var> for lowercase or invalid field name characters
	<li>~~base64~~ encoding of field values;		<li>Base64 encoding of field values
	<li>~~field~~ level security;		<li>Field level security
	<li>LOB fields;		<li>LOB fields
	<li>~~record~~ locks.		<li>Record locks
	</ul>		</ul>

Line 149:		Line 151:

	==Examples==		==Examples==
	In addition to the examples in the following section, see the following examples in the <var>ToXmlDoc</var> ~~article~~, both of which apply equally to <var>LoadFromRecord</var> and <var>NewFromRecord</var>:		In addition to the examples in the following section, see the following examples in the <var>ToXmlDoc</var> description, both of which apply equally to <var>LoadFromRecord</var> and <var>NewFromRecord</var>:
	<ul>		<ul>
	<li>~~the~~ [[ToXmlDoc (Record function)#AttributeValues, AttributeNames, and NamesToLower arguments\|"AttributeValues, AttributeNames, and NamesToLower arguments"]] example		<li>The [[ToXmlDoc (Record function)#AttributeValues, AttributeNames, and NamesToLower arguments\|"AttributeValues, AttributeNames, and NamesToLower arguments"]] example
	<li>~~the~~ [[ToXmlDoc (Record function)#Getting record lock\|"Getting record lock"]] example		<li>The [[ToXmlDoc (Record function)#Getting record lock\|"Getting record lock"]] example
	</ul>		</ul>

Line 253:		Line 255:
	</nowiki></p>		</nowiki></p>
	And the corresponding output of the above <code>PAI</code> would be:		And the corresponding output of the above <code>PAI</code> would be:
	<~~pre~~>		<p class="code">\GRP = 1
	\GRP = 1		FOO = value of foo
	FOO = value of foo		/GRP = 1
	/GRP = 1		</p>
	</~~pre~~>

	{{Template:XmlDoc/XmlNode:LoadFromRecord footer}}		{{Template:XmlDoc/XmlNode:LoadFromRecord footer}}

JAL: /* Usage notes */

2013-12-12T01:56:26Z

Usage notes

← Older revision		Revision as of 01:56, 12 December 2013
Line 123:		Line 123:
	all perform the same operation and have the same arguments.		all perform the same operation and have the same arguments.
	</p>		</p>

			<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>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.

			<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 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.

	<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|"Usage notes"]]; these apply equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var>. The topics discussed there are:		<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|"Usage notes"]]; these apply equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var>. The topics discussed there are:

JAL: /* Syntax terms */

2013-12-12T01:45:43Z

Syntax terms

← Older revision		Revision as of 01:45, 12 December 2013
Line 89:		Line 89:
	<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>

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

	<td>This name required argument is a <var>[[CharacterToUnicodeMap class\|CharacterToUnicodeMap]]</var> value. If a non-null value is provided, then the specified map is used to translate non-<var>UTF8</var>/<var>16</var> field values from EBCDIC to Unicode before storing in the <var>XmlDoc</var>.		<td>This name required argument is a <var>[[CharacterToUnicodeMap class\|CharacterToUnicodeMap]]</var> value. If a non-null value is provided, then the specified map is used to translate non-<var>UTF8</var>/<var>16</var> field values from EBCDIC to Unicode before storing in the <var>XmlDoc</var>.

JAL: /* Syntax terms */

2013-12-12T01:45:11Z

Syntax terms

@@ Line 78: / Line 78: @@
 The default value is <var>False</var>, which uses the standard Unicode translation tables, including any modifications specified in <code>UNICODE Trans</code> or <code>UNICODE Map</code> [[Unicode#Update forms of UNICODE|commands]].
 The advantage of using <code>CodepageTable=False</code> is that it will allow you to readily modify the <var>XmlDoc</var> directly (that is, with the <var>[[AddElement (XmlDoc/XmlNode function)|AddElement]]</var> and <var>[[AddAttribute (XmlNode function)|AddAttribute]]</var> methods). Those operations will use the standard Unicode translation tables; there is no way to perform them using the base codepage translation tables.</td></tr>
 </table>

Dme: /* Usage notes */

2012-10-24T22:02:00Z

Usage notes

← Older revision		Revision as of 22:02, 24 October 2012
Line 106:		Line 106:
	</p>		</p>

	<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|"Usage notes"]]; these apply equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var>.		<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|"Usage notes"]]; these apply equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var>. The topics discussed there are:
			<ul>
			<li>invalid characters in field names;
			<li>using <var>AllowUnreversible</var> for lowercase or invalid field name characters;
			<li>base64 encoding of field values;
			<li>field level security;
			<li>LOB fields;
			<li>record locks.
			</ul>

	<li><var>LoadFromRecord</var> was actually introduced in version 7.6 of		<li><var>LoadFromRecord</var> was actually introduced in version 7.6 of

Dme: /* Examples */

2012-08-12T18:43:28Z

Examples

← Older revision		Revision as of 18:43, 12 August 2012
Line 114:		Line 114:

	==Examples==		==Examples==
	In addition to the examples in the following section, see the [[ToXmlDoc (Record function)#AttributeValues, AttributeNames, and NamesToLower arguments\|"AttributeValues, AttributeNames, and NamesToLower arguments"]] example ~~in the~~ <~~var~~>ToXmlDoc</~~var> article, which applies equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var~~>.		In addition to the examples in the following section, see the following examples in the <var>ToXmlDoc</var> article, both of which apply equally to <var>LoadFromRecord</var> and <var>NewFromRecord</var>:
			<ul>
			<li>the [[ToXmlDoc (Record function)#AttributeValues, AttributeNames, and NamesToLower arguments\|"AttributeValues, AttributeNames, and NamesToLower arguments"]] example
			<li>the [[ToXmlDoc (Record function)#Getting record lock\|"Getting record lock"]] example
			</ul>

	====Copying from multiple source records====		====Copying from multiple source records====
	Since <var>LoadFromRecord</var> can		Since <var>LoadFromRecord</var> can

Dme: /* Examples */

2012-08-12T18:13:07Z

Examples

← Older revision		Revision as of 18:13, 12 August 2012
Line 114:		Line 114:

	==Examples==		==Examples==
	In addition to the examples in the following section, the ~~<var>~~[[ToXmlDoc (Record function)#~~Examples~~\|~~ToXmlDoc~~]]~~</var> examples show the effect of~~ the <var>~~AttributeValues~~</var>, <var>~~AttributeNames~~</var>, and <var>~~NamesToLower~~</var> ~~method arguments~~.		In addition to the examples in the following section, see the [[ToXmlDoc (Record function)#AttributeValues, AttributeNames, and NamesToLower arguments\|"AttributeValues, AttributeNames, and NamesToLower arguments"]] example in the <var>ToXmlDoc</var> article, which applies equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var>.
	====Copying from multiple source records====		====Copying from multiple source records====
	Since <var>LoadFromRecord</var> can		Since <var>LoadFromRecord</var> can

Dme: /* Usage notes */

2012-08-12T17:51:56Z

Usage notes

← Older revision		Revision as of 17:51, 12 August 2012
Line 103:		Line 103:
	<p>		<p>
	Except for these considerations, <var>ToXmlDoc</var>, <var>NewFromRecord</var>, and <var>LoadFromRecord</var>		Except for these considerations, <var>ToXmlDoc</var>, <var>NewFromRecord</var>, and <var>LoadFromRecord</var>
	all perform the same operation and have the same arguments~~, so~~		all perform the same operation and have the same arguments.
	~~<ul>~~
	~~<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|"Usage notes"]]~~.
	~~</ul>~~
	</p>		</p>

			<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|"Usage notes"]]; these apply equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var>.

	<li><var>LoadFromRecord</var> was actually introduced in version 7.6 of		<li><var>LoadFromRecord</var> was actually introduced in version 7.6 of
	the <var class="product">Sirius Mods</var>, but the <var>XmlNode</var> class <var>LoadFromRecord</var> implementation prior to version 7.8 required that the <var>XmlDoc</var> be empty.		the <var class="product">Sirius Mods</var>, but the <var>XmlNode</var> class <var>LoadFromRecord</var> implementation prior to version 7.8 required that the <var>XmlDoc</var> be empty.