LoadFromRecord (XmlDoc/XmlNode subroutine)
Template:XmlDoc:LoadFromRecord subtitle
Syntax
Template:XmlDoc:LoadFromRecord syntax
Syntax terms
| %doc | LoadFromRecord returns a new XmlDoc object. |
|---|---|
| %(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, 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:
|
| 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, <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 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 "Handling records with null characters", below. |
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.