LoadFromRecord (XmlDoc/XmlNode subroutine)

Load fields and fieldgroups from current record (XmlDoc and XmlNode classes)

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

This record extraction is the same operation that is performed by the NewFromRecord shared function and by the Record class ToXmlDoc function, as is further described below in "Usage notes".

Syntax

nr:LoadFromRecord[( [AttributeValues= boolean], [AttributeNames= boolean], - [NamesToLower= boolean], [AllowUnreversible= boolean], - [CodepageTable= boolean], [Base64Encode= boolean], - [CharacterMap= characterToUnicodeMap])] Throws CharacterTranslationException

Syntax terms

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: 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. "Structure of XmlDoc for AddToRecord" in the AddToRecord method page describes in detail the XmlDoc created by LoadFromRecord.
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.
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: Control and uninvertible characters are translated to their Unicode counterparts. X'00' (if the AllowNull argument is not True) and untranslatable characters can cause request cancellation, unless they are mapped by the CharacterMap argument. (An unmapped untranslatable character actually throws a CharacterTranslationException exception, which results in cancellation if not caught.) 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.

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

Examples

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

XmlDoc class XmlNode class XmlNodelist class	List of XmlDoc methods List of XmlNode methods List of XmlNodelist methods List of XmlDoc API methods	XmlDoc methods syntax XmlNode methods syntax XmlNodelist methods syntax
Notation conventions for methods