LoadFromRecord (XmlDoc/XmlNode subroutine)

This subroutine adds to an XmlDoc object a subtree that contains the fields and fieldgroups from the current record. This record extraction is the same operation that is performed by the NewFromRecord shared function and by the Record class ToXmlDoc function.

Syntax

Syntax terms

doc	LoadFromRecord is in both the XmlDoc and XmlNode classes. When the method object is an XmlDoc, or refers to the Root node of an XmlDoc: The XmlDoc must not contain any nodes except the Root node. A "Record" element is added as the top level element of the XmlDoc. Children are added to the Record element, representing the outer fields and fieldgroups of the record. When the method object is an XmlNode not referring to the Root node of an XmlDoc: The node must be an Element node. Children are added to that element, representing the outer fields and fieldgroups of the record. See the AddToRecord subroutine description for some examples of extracting multiple records into a single XmlDoc. See the AddToRecord section "Structure of XmlDoc for AddToRecord" for a description of the XmlDoc created by LoadFromRecord.
%(XmlDoc)	The class name in parentheses denotes a shared method and is one way to invoke LoadFromRecord. You can also use an object expression whose type is XmlDoc (even if the value of the expression is null).
AttributeValues	This name required argument is a Boolean value that indicates whether a field value will be stored as “XML text” or as an XML attribute (belonging to its field, which is an XmlDoc element). For example, <APSUBUND>COMM</APSUBUND> is text format, and <APSUBUND value="COMM"/> is attribute value format. The default value is False, which produces text format. In this format, the value of a field will be converted to base64 in the XmlDoc if the field contains a byte that is: Equal to X'00', if the AllowNull property of the XmlDoc is False. Between X'00' and X'3F'. Not translatable from EBCDIC to Unicode, using either the standard Unicode translation table or the base codepage translation table, as determined by the CodepageTable argument of LoadFromRecord. Not invertible when translating from EBCDIC to Unicode and back to EBCDIC using the standard Unicode translation table, if the CodepageTable argument is False. This argument must be False if the XmlDoc is to be used as the method object of the AddToRecord subroutine.
AttributeNames	This name required argument is a Boolean value that indicates whether each field name is to be stored in the XmlDoc as an element name or as the value of a "name" attribute. For example, <APSUBUND>COMM</APSUBUND> is element-name format, and the following is name-as-attribute format: <field name="APSUBUND"> COMM </field> The default value as of Sirius Mods version 7.6 (and maintenance back to version 7.3) is True, which produces name-as-attribute format. Formerly, the default value was False. The name-as-attribute format from the True option is better suited to operations on the XmlDoc, particularly a record copying operation. The element-name format from the False option produces more compact output when the XmlDoc is serialized. This argument must be True if the XmlDoc is to be used as the method object of the AddToRecord subroutine.
NamesToLower	This name required argument is a Boolean value that indicates whether field names are stored in all lowercase characters. The default value is False, which does not translate uppercase name characters to lowercase. If the XmlDoc is to be used for record copying, this argument should probably be False.
AllowUnreversible	This name required argument is a Boolean 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 False, which allows request cancellation to alert you about unreversible field names. If the XmlDoc is to be used for record copying, this argument should probably be False.
CodepageTable	This name required argument is a Boolean value; if True, the translations defined by the base Unicode codepage are used when translating from EBCDIC to Unicode for storing in the XmlDoc. This argument is for the unusual case where you anticipate that the XML document is to be used later by AddToRecord, and the standard Unicode translation tables in place when AddToRecord is invoked may differ from those in place when the record was copied to the XmlDoc. The default value is False, which uses the standard Unicode translation tables, including any modifications specified in UNICODE Trans or UNICODE Map commands. The advantage of using CodepageTable=False is that it will allow you to readily modify the XmlDoc directly (that is, with the AddElement and AddAttribute methods). Those operations will use the standard Unicode translation tables; there is no way to perform them using the base codepage translation tables.
AllowNull	The value of this name required Boolean argument, which defaults to False, is copied to the AllowNull property of the XmlDoc created by LoadFromRecord. The XmlDoc's AllowNull property, in turn, determines whether field values that contain the X'00' character are stored in the XmlDoc with base64 encoding. Such values are base64 encoded if the AllowNull property is False (the default). For an example, see the NewFromRecord "Handling records with null characters" section.

Usage notes

• Whether to use ToXmlDoc, NewFromRecord, or LoadFromRecord depends on what is most convenient for your application. If you are already using a Record object which references the desired record, using ToXmlDoc may be more convenient; if not, then either LoadFromRecord or NewFromRecord (both of which require that the method be contained in a “record loop”) may be more convenient. You must use LoadFromRecord if you want to add the record's content as a subtree to a non-empty XmlDoc; in other cases the NewFromRecord “factory method” may be your choice.

  Since NewFromRecord and ToXmlDoc create new XmlDoc objects, they have the AllowNull argument for setting the created XmlDoc's AllowNull poperty; LoadFromRecord does not have the AllowNull argument.

  As stated, both NewFromRecord and LoadFromRecord must be contained in a “record loop”, for example, an FRN block, and they may not be invoked within a fieldgroup context.

  Except for these considerations, ToXmlDoc, NewFromRecord, and LoadFromRecord all perform the same operation and have the same arguments.

• All fields are copied to the XmlDoc by LoadFromRecord.
• See the AddToRecord subroutine description for an example of extracting a record to an XmlDoc for record copying, and see the ToXmlDoc function for other examples using the method arguments.
• LoadFromRecord was actually introduced in version 7.6 of the Sirius Mods, but the XmlNode class LoadFromRecord implementation prior to version 7.8 required that the XmlDoc be empty.

Examples

Copying from multiple source records

Since LoadFromRecord subroutine can extract from a record into a subtree of an Element node in an XmlDoc, you can use it, together with AddToRecord, to combine multiple source records into one target record.

As a simple example, you can put the fields from two records “side by side” into a target record:

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

The XmlDoc that is input to AddToRecord would have a structure similar to the following:

<Record ...> <field ...> ... first field from record %x </field> ... <field ...> ... first field from record %y </field> ... </Record>

Of course, you could also accomplish this particular objective by using two XmlDoc objects:

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

You can also use LoadFromRecord to modify the fieldgroup structure within a record (using V7R2 of Model 204). For example, you could take the “outer” fields of one record and move them to be fieldgroup members in the target record:

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

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 SRCFILE are defined as outer fields, but in TARGFILE they are defined as members of fieldgroup GRP (or they would need to be “FIELDGROUP *” fields). So, for example, definitions for SRCFILE might include:

DEFINE FIELD FOO DEFINE FIELDGROUP GRP

and definitions for TARGFILE might include:

DEFINE FIELDGROUP GRP DEFINE FIELD FOO WITH FIELDGROUP GRP

And the XmlDoc that is input to the above AddToRecord subroutine may look like:

<Record ...> <fieldgroup name="GRP" ...> <field name="FOO"> value of foo </field> </fieldgroup> </Record>

And the corresponding output of the above PAI would be:

    \GRP = 1
     FOO = value of foo
    /GRP = 1

Template:XmlDoc:LoadFromRecord footer