NewFromRecord (XmlDoc function)
Create a new XmlDoc from the current record (XmlDoc class)
[Requires Janus SOAP]
This shared function creates a new XmlDoc object that contains the fields and fieldgroups from the current record. This record extraction is the same operation that is performed by the LoadFromRecord subroutine and by the ToXmlDoc function in the Record class.
Syntax
%doc = [%(XmlDoc):]NewFromRecord[( [AttributeValues= boolean], - [AttributeNames= boolean], - [NamesToLower= boolean], - [AllowUnreversible= boolean], - [CodepageTable= boolean], - [Base64Encode= boolean], - [CharacterMap= characterToUnicodeMap], - [Allownull= boolean], - [Recordnumber= number], [File= string])] Throws CharacterTranslationException
Syntax terms
| %doc | NewFromRecord returns a new XmlDoc object. |
|---|---|
| %(XmlDoc) | The class name in parentheses denotes a shared method and is one way to invoke NewFromRecord. You can also use an object expression whose type is XmlDoc (even if the value of the expression is null). |
| AttributeValues | Boolean object |
| AttributeNames | Boolean object |
| NamesToLower | Boolean object |
| AllowUnreversible | Boolean object |
| CodepageTable | Boolean object |
| AllowNull | The value of this Boolean argument, which defaults to False, is copied to the AllowNull property of the XmlDoc created by NewFromRecord. 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). |
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
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 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. 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
A False value prevents null characters from being stored in the XmlDoc, so it will conform to the XML Recommendation, which does not allow null characters in an XML document.
The following fragment:
%s = 'Field with null/' With '00':X With '/' Store Record FOO = %s End Store %r = $CurRec FRN %r %doc = %doc:NewFromRecord End For PrintText {~} = {%doc:AllowNull} %doc:Print
produces this output:
%doc:AllowNull = False <Record version="1" file="QAWORK" number="1"> <field name="FOO" encoding="base64"> xomFk4RApomjiECVpJOTYQBh </field> </Record>
In the above output, notice that FOO is base64 encoded,
because it contains a null character, and
null characters are not allowed in an XmlDoc whose AllowNull
property is False.
The following fragment:
%s = 'Field with null/' With '00':X With '/' Store Record FOO = %s End Store %r = $CurRec FRN %r %doc = %doc:NewFromRecord(AllowNull=True) End For PrintText {~} = {%doc:AllowNull} %doc:Print
produces the following output:
%doc:AllowNull = True <Record version="1" file="QAWORK" number="1"> <field name="FOO"> Field with null/�/ </field> </Record>
In the above output, FOO is not base64 encoded; the XmlDoc contains
a null character, which is displayed by the Print method using a
character reference (�).
This may be useful for visually inspecting the contents of the
XmlDoc, again noting that such a document is not, strictly speaking,
conformant to the XML Recommendation.
See the description of the AttributeValue argument of the LoadFromRecord subroutine for a list of all conditions which force base64 encoding of the "field" element.
See also
- See the LoadFromRecord method for a discussion of extracting the contents of the current record into an XmlDoc.