LoadFromRecord (XmlDoc/XmlNode subroutine): Difference between revisions

Revision as of 23:10, 2 June 2011

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.

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. This record extraction is the same operation that is performed by the NewFromRecord shared function and by the the Record class ToXmlDoc function.

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.

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 that references the desired record, using ToXmlDoc may be more convenient; if not, then either NewFromRecord or LoadFromRecord (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 property. 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. The discussion of the “extract from record to XmlDoc” operation generally uses LoadFromRecord, except where one of these considerations is relevant to the discussion.

Examples

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

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

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.