LoadFromRecord (XmlDoc/XmlNode subroutine)
[Requires Janus SOAP]
This subroutine adds to an XmlDoc object a subtree that contains the fields and fieldgroups from the current record. Among other things, the result XmlDoc can be used to copy a record, using the AddToRecord subroutine.
nr:LoadFromRecord[( [AttributeValues= boolean], [AttributeNames= boolean], - [NamesToLower= boolean], [AllowUnreversible= boolean], - [CodepageTable= boolean], [Base64Encode= boolean], - [CharacterMap= characterToUnicodeMap])] Throws CharacterTranslationException
|nr||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: |
When the method object is an XmlNode not referring to the Root node of an XmlDoc:
|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).
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.
<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
|Base64Encode||This name required argument is a Boolean value.
The default is True, which indicates that before storing a field's value in the XmlDoc, the value is base64 encoded if needed. See this ToXmlDoc usage note which describes the conditions that would require base64 encoding.
If Base64Encode is False, field values are not base64 encoded. This means:
Base64Encode is available as of Model 204 version 7.5.
|CharacterMap||This name required argument is a CharacterToUnicodeMap value. If a non-null value is provided, then the specified map is used to translate non-UTF8/16 field values from EBCDIC to Unicode before storing in the XmlDoc.
Also, if a non-null value is provided, then the Base64Encode argument is forced to the value True, and the processing indicated by that is performed.
CharacterMap is available as of Model 204 version 7.5.
- 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, for example, For Each Record) 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 virtual constructor 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.
- In versions of Model 204 prior to 7.5, the effect of the Base64Encoding=False argument can be accomplished by post-processing the XmlDoc and replacing values which have an
encoding="base64"attribute with the base 64 decoded value translated to Unicode.
- UTF8 and UTF16 fields are copied directly to the XmlDoc; there is no translation (either automatic or using the CharacterMap argument) nor base64 encoding involved for them.
- The Base64Encode=False argument can be used to disable any base64 encoding of field values. Alternatively, the CharacterMap 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.
- See the additional comments in the ToXmlDoc Usage notes, which apply equally to NewFromRecord and LoadFromRecord. The topics discussed there are:
- Invalid characters in field names
- Using AllowUnreversible for lowercase or invalid field name characters
- Base64 encoding of field values
- Field level security
- LOB fields
- Record locks
- 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.
In addition to the examples in the following section, see the following examples in the ToXmlDoc description, both of which apply equally to LoadFromRecord and NewFromRecord:
- The "AttributeValues, AttributeNames, and NamesToLower arguments" example
- The "Getting record lock" example
Copying from multiple source records
Since LoadFromRecord 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 V7R5 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
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