View source for LoadFromRecord (XmlDoc/XmlNode subroutine)

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

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.

This record extraction is the
same operation that is performed by the <var>[[NewFromRecord (XmlDoc function)|NewFromRecord]]</var> shared function and by the <var>[[Record class|Record]]</var> class <var>[[ToXmlDoc (Record function)|ToXmlDoc]]</var> function, as is further described below in [[#Usage notes|"Usage notes"]].

==Syntax==
{{Template:XmlDoc/XmlNode:LoadFromRecord syntax}}


===Syntax terms===
<table class="syntaxTable">
<tr><th>nr</th><td><var>LoadFromRecord</var> is in both the <var>XmlDoc</var> and <var>XmlNode</var> classes.
 
When the method object is an <var>XmlDoc</var>, or refers to the <var>Root</var> node of an <var>XmlDoc</var>: <ul> <li>The <var>XmlDoc</var> must not contain any nodes except the <var>Root</var> node. <li>A "Record" element is added as the top level element of the <var>XmlDoc</var>. Children are added to the Record element, representing the outer fields and fieldgroups of the record. </ul>
 
When the method object is an <var>XmlNode</var> not referring to the <var>Root</var> node of an <var>XmlDoc</var>:
<ul>
<li>The node must be an <var>Element</var> node.
<li>Children are added to that element, representing the outer fields and fieldgroups of the record.
</ul>
[[AddToRecord (XmlDoc subroutine)#Structure of XmlDoc for AddToRecord|"Structure of XmlDoc for AddToRecord"]] in the <var>[[AddToRecord (XmlDoc subroutine)|AddToRecord]]</var> method page describes in detail the <var>XmlDoc</var> created by <var>LoadFromRecord</var>.
</td></tr>

<tr><th><var>AttributeValues</var></th>
<td>This [[Methods#Named parameters|name required]] argument is a <var>[[Enumerations#Using Boolean enumerations|Boolean]]</var> value that indicates whether a field value will be stored as &ldquo;XML text&rdquo; or as an XML attribute (belonging to its field, which is an <var>XmlDoc</var> element).
 
For example, <code><APSUBUND>COMM</APSUBUND></code> is text format, and <code><APSUBUND value="COMM"/></code> is attribute value format.
 
The default value is <var>False</var>, which produces text format. In this format, the value of a field will be converted to base64 in the <var>XmlDoc</var> if the field contains a byte that is:
<ul>
<li>Equal to X'00', if the <var>[[AllowNull (XmlDoc property)|AllowNull]]</var> property of the <var>XmlDoc</var>
is <var>False</var>.
<li>Between X'00' and X'3F'.
<li>Not translatable from EBCDIC to Unicode, using either the standard [[Unicode#Support for the ASCII subset of Unicode|Unicode translation table]] or the base codepage translation table, as determined by the <var>CodepageTable</var> argument of <var>LoadFromRecord</var>.
<li>Not invertible when translating from EBCDIC to Unicode and back to EBCDIC using the standard Unicode translation table, if the <var>CodepageTable</var> argument is <var>False</var>.
</ul>
 
This argument must be <var>False</var> if the <var>XmlDoc</var> is to be used as the method object of the <var>AddToRecord</var> subroutine.</td></tr>

<tr><th><var>AttributeNames</var></th>

<td>This name required argument is a <var>Boolean</var> value that indicates whether each field name is to be stored in the <var>XmlDoc</var> as an element name or as the value of a "name" attribute.
 
For example, <code><APSUBUND>COMM</APSUBUND></code> is element-name format, and the following is name-as-attribute format:
<p class="code"><nowiki><field name="APSUBUND">
   COMM
</field>
</nowiki></p>
 
The default value as of <var class="product">Sirius Mods</var> version 7.6 (and maintenance back to version 7.3) is <var>True</var>, which produces name-as-attribute format. Formerly, the default value was <var>False</var>.
 
The name-as-attribute format from the <var>True</var> option is better suited to operations on the <var>XmlDoc</var>, particularly a record copying operation. The element-name format from the <var>False</var> option produces more compact output when the <var>XmlDoc</var> is serialized.
 
This argument must be <var>True</var> if the <var>XmlDoc</var> is to be used as the method object of the <var>AddToRecord</var> subroutine.</td></tr>
<tr><th><var>NamesToLower</var></th>
<td>This name required argument is a <var>Boolean</var> value that indicates whether field names are stored in all lowercase characters. The default value is <var>False</var>, which does not translate uppercase name characters to lowercase.
 
If the <var>XmlDoc</var> is to be used for record copying, this argument should probably be <var>False</var>.
</td></tr>

<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.
 
The default value is <var>False</var>, which allows request cancellation to alert you about unreversible field names.
 
If the <var>XmlDoc</var> is to be used for record copying, this argument should probably be <var>False</var>.</td></tr>

<tr><th><var>CodepageTable</var></th>

<td>This name required argument is a <var>Boolean</var> value; if <var>True</var>, the translations defined by the '''base''' Unicode codepage are used when translating from EBCDIC to Unicode for storing in the <var>XmlDoc</var>.
 
This argument is for the unusual case where you anticipate that the XML document is to be used later by <var>AddToRecord</var>, and the standard [[Unicode#Support for the ASCII subset of Unicode|Unicode translation tables]] in place when <var>AddToRecord</var> is invoked may differ from those in place when the record was copied to the <var>XmlDoc</var>.
 
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>

<tr><th><var>Base64Encode</var></th>
 		
<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>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>

<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>.
 		
<p>Also, if a non-null value is provided, then the <var>Base64Encode</var> argument is forced to the value <var>True</var>, and the processing indicated by that is performed.</p>
 		
<p><var>CharacterMap</var> is available as of <var class="product">Model 204</var> version 7.5.</p> </td></tr>

</table>

==Usage notes==
<ul>
<li>Whether to use <var>[[ToXmlDoc (Record function)|ToXmlDoc]]</var>, <var>[[NewFromRecord (XmlDoc function)|NewFromRecord]]</var>, or <var>LoadFromRecord</var> depends on what is
most convenient for your application.
If you are already using a <var>Record</var> object which references the desired record,
using <var>ToXmlDoc</var> may be more convenient; if not, then either
<var>LoadFromRecord</var> or <var>NewFromRecord</var> (both of which require that the method be
contained in a record loop, for example, <var>For Each Record</var>) may be more convenient.
You must use <var>LoadFromRecord</var> if you want to add the record's content as a
subtree to a non-empty <var>XmlDoc</var>;
in other cases the <var>NewFromRecord</var> virtual constructor may be your choice.
<p> 
Since <var>NewFromRecord</var> and <var>ToXmlDoc</var> create new <var>XmlDoc</var> objects, they have the
<var>AllowNull</var> argument for setting the created <var>XmlDoc</var>'s <var>[[allowNull (XmlDoc property)|AllowNull]]</var>
poperty; <var>LoadFromRecord</var> does not have the <var>AllowNull</var> argument.</p>
<p> 
As stated, both
<var>NewFromRecord</var> and <var>LoadFromRecord</var> must be
contained in a record loop, for example, an <var>FRN</var> block, and they may not be
invoked within a fieldgroup context.</p>
<p> 
Except for these considerations, <var>ToXmlDoc</var>, <var>NewFromRecord</var>, and <var>LoadFromRecord</var>
all perform the same operation and have the same arguments.
</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:
<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
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.

</ul>

==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>:
<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====
Since <var>LoadFromRecord</var> can
extract from a record into a subtree of an <var>Element</var> node in an <var>XmlDoc</var>,
you can use it, together with <var>AddToRecord</var>, to combine multiple
source records into one target record.
 
As a simple example, you can put the fields from two records
&ldquo;side by side&rdquo; into a target record:
<p class="code">FRN %x
   %doc = %doc:NewFromRecord
End For
%top = %doc:SelectSingleNode('*')
FRN %y
   %top:LoadFromRecord
End For
Store Record
End Store
%rn = $CurRec
FRN %rn
   %doc:AddToRecord
End For
</p>
 
The <var>XmlDoc</var> that is input to <var>AddToRecord</var> would have a structure
similar to the following:
<p class="code"><nowiki><Record ...>
   <field ...>
   ... first field from record %x
   </field>
   ...
   <field ...>
   ... first field from record %y
   </field>
   ...
</Record>
</nowiki></p>
Of course, you could also accomplish this particular objective by
using two <var>XmlDoc</var> objects:
<p class="code"><nowiki>FRN %x
   %doc1 = %doc1:NewFromRecord
End For
FRN %y
   %doc2 = %doc2:NewFromRecord
End For
Store Record
End Store
%targ = $CurRec
FRN %targ
   %doc1:AddToRecord
   %doc2:AddToRecord
End For
</nowiki></p>
 
You can also use <var>LoadFromRecord</var> to modify the fieldgroup structure
within a record (using V7R2 of <var class="product">Model 204</var>).
For example, you could take the &ldquo;outer&rdquo; fields of one
record and move them to be fieldgroup members in the target
record:
<p class="code"><nowiki>In SRCFILE FRN %x
   %doc = %doc:NewFromRecord
End For
%fg = %doc:SelectSingleNode('*/fieldgroup[@name="GRP"]')
In SRCFILE FRN %y
   %fg:LoadFromRecord
End For
In TARGFILE Store Record
End Store
%rn = $CurRec
In TARGFILE FRN %rn
   %doc:AddToRecord
   PAI
End For
</nowiki></p>
 
The use of a separate source and target file above (which in
general is a typical usage of the record copying methods) is
more or less required here, because the fields in <code>SRCFILE</code> are
defined as outer fields, but in <code>TARGFILE</code> they are defined as members of fieldgroup
<code>GRP</code> (or they would need to be &ldquo;FIELDGROUP *&rdquo; fields).
So, for example, definitions for <code>SRCFILE</code> might include:
<p class="code"><nowiki>DEFINE FIELD FOO
DEFINE FIELDGROUP GRP
</nowiki></p>
and definitions for <code>TARGFILE</code> might include:
<p class="code"><nowiki>DEFINE FIELDGROUP GRP
DEFINE FIELD FOO WITH FIELDGROUP GRP
</nowiki></p>
And the <var>XmlDoc</var> that is input to the above <var>AddToRecord</var> subroutine
may look like:
<p class="code"><nowiki><Record ...>
   <fieldgroup name="GRP" ...>
      <field name="FOO">
         value of foo
      </field>
   </fieldgroup>
</Record>
</nowiki></p>
And the corresponding output of the above <code>PAI</code> would be:
<pre>
    \GRP = 1
     FOO = value of foo
    /GRP = 1
</pre>

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