NewFromRecord (XmlDoc function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(23 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:XmlDoc:NewFromRecord subtitle}}
{{Template:XmlDoc:NewFromRecord subtitle}}
This shared function creates a new <var>XmlDoc</var> object that contains the fields and
This shared function creates a new <var>XmlDoc</var> object that contains the fields and fieldgroups from the current record. Among other things, the result <var>XmlDoc</var> can be used to copy a record, using the <var>[[AddToRecord (XmlDoc subroutine)|AddToRecord]]</var> subroutine.
fieldgroups from the current record.
 
This record extraction is the
The field and fieldgroup extraction performed by <var>NewFromRecord</var> is the
same operation that is performed by the <var>[[LoadFromRecord (XmlDoc/XmlNode subroutine)|LoadFromRecord]]</var> subroutine and by the <var>[[ToXmlDoc (Record function)|ToXmlDoc]]</var> function in the <var>[[Record class|Record]]</var> class.
same operation that is performed by the <var>[[LoadFromRecord (XmlDoc/XmlNode subroutine)|LoadFromRecord]]</var> subroutine and by the <var>[[ToXmlDoc (Record function)|ToXmlDoc]]</var> function in the <var>[[Record class|Record]]</var> class, as is further described below in [[#Usage notes|"Usage notes"]].


==Syntax==
==Syntax==
Line 11: Line 11:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%doc</th><td><var>NewFromRecord</var> returns a new <var>XmlDoc</var> object.</td></tr>
<tr><th>%doc</th><td><var>NewFromRecord</var> returns a new <var>XmlDoc</var> object.</td></tr>
<tr><th><var>%(XmlDoc)</var></th>
 
<td>The class name in parentheses denotes a shared method and is one way to invoke <var>NewFromRecord</var>. You can also use an object expression whose type is <var>XmlDoc</var> (even if the value of the expression is null).</td></tr>
<tr><th><var>[%(XmlDoc):]</var></th>
<td>The optional class name in parentheses denotes a [[Notation conventions for methods#Shared methods|virtual constructor]] method. See [[#Usage notes|"Usage notes"]], below, for more information about invoking an <var>XmlDoc</var> virtual constructor.</td></tr>
 
<tr><th><var>AttributeValues</var></th>
<tr><th><var>AttributeValues</var></th>
<td>This [[Methods#Named parameters|name required]] argument is a <var>[[Enumerations#Using Boolean enumerations|Boolean]]</var> value that indicates whether a field value will be stored as &ldquo;XML text&rdquo; or as an XML attribute (belonging to its field, which is an <var>XmlDoc</var> element).
<td>This [[Methods#Named parameters|name required]] argument is a <var>[[Enumerations#Using Boolean enumerations|Boolean]]</var> 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 <var>XmlDoc</var> element).
   
   
For example, <code><APSUBUND>COMM</APSUBUND></code> is text format, and <code><APSUBUND value="COMM"/></code> is attribute value format.
For example, <code><APSUBUND>COMM</APSUBUND></code> is text format, and <code><APSUBUND value="COMM"/></code> is attribute value format.
Line 27: Line 29:
</ul>
</ul>
   
   
This argument must be <var>False</var> if the <var>XmlDoc</var> is to be used as the method object of the <var>[[#AddToRecord subroutine in XmlDoc class|AddToRecord]]</var> subroutine.</td></tr>
This argument must be <var>False</var> if the <var>XmlDoc</var> is to be used as the method object of the <var>[[AddToRecord (XmlDoc subroutine)|AddToRecord]]</var> subroutine.</td></tr>


<tr><th><var>AttributeNames</var></th>
<tr><th><var>AttributeNames</var></th>
Line 66: Line 68:
The default value is <var>False</var>, which uses the standard Unicode translation tables, including any modifications specified in <code>UNICODE Trans</code> or <code>UNICODE Map</code> [[Unicode#Update forms of UNICODE|commands]].
The default value is <var>False</var>, which uses the standard Unicode translation tables, including any modifications specified in <code>UNICODE Trans</code> or <code>UNICODE Map</code> [[Unicode#Update forms of UNICODE|commands]].
The advantage of using <code>CodepageTable=False</code> is that it will allow you to readily modify the <var>XmlDoc</var> directly (that is, with the <var>[[AddElement (XmlDoc/XmlNode function)|AddElement]]</var> and <var>[[AddAttribute (XmlNode function)|AddAttribute]]</var> methods). Those operations will use the standard Unicode translation tables; there is no way to perform them using the base codepage translation tables.</td></tr>
The advantage of using <code>CodepageTable=False</code> is that it will allow you to readily modify the <var>XmlDoc</var> directly (that is, with the <var>[[AddElement (XmlDoc/XmlNode function)|AddElement]]</var> and <var>[[AddAttribute (XmlNode function)|AddAttribute]]</var> methods). Those operations will use the standard Unicode translation tables; there is no way to perform them using the base codepage translation tables.</td></tr>
<tr><th><var>Base64Encode</var></th>
<td>This name required argument is a <var>Boolean</var> value.
<p>The default is <var>True</var>, which indicates that before storing a field's value in the <var>XmlDoc</var>, the value is base64 encoded <b>if needed</b>. See [[ToXmlDoc (Record function)#casEnc|this ToXmlDoc usage note]] which describes the conditions that would require base64 encoding.</p>
<p>
If <var>Base64Encode</var> value is <var>False</var>, field values are not base64 encoded. This means: </p>
<ul>
<li>Control and uninvertible characters are translated to their Unicode counterparts.
<li>X'00' (if the <var>AllowNull</var> argument is not <var>True</var>) and untranslatable characters can cause request cancellation, unless they are mapped by the <var>CharacterMap</var> argument. (An unmapped untranslatable character actually throws a <var>[[CharacterTranslationException class|CharacterTranslationException]]</var> exception, which results in cancellation if not caught.)
</ul>
<p>
<var>Base64Encode</var> is available as of <var class="product">Model 204</var> version 7.5.</p> </td></tr>
<tr><th><var>CharacterMap</var></th>
<td>This name required argument is a <var>[[CharacterToUnicodeMap class|CharacterToUnicodeMap]]</var> value. If a non-null value is provided, then the specified map is used to translate non-<var>UTF8</var>/<var>16</var> field values from EBCDIC to Unicode before storing in the <var>XmlDoc</var>.
<p>Also, if a non-null value is provided, then the <var>Base64Encode</var> argument is forced to the value <var>True</var>, and the processing indicated by that is performed.</p>
<p><var>CharacterMap</var> is available as of <var class="product">Model 204</var> version 7.5.</p> </td></tr>


<tr><th><var>AllowNull</var></th>
<tr><th><var>AllowNull</var></th>
Line 76: Line 95:
==Usage notes==
==Usage notes==
<ul>
<ul>
<li><var>NewFromRecord</var> is a [[Object variables#Virtual Constructor methods|virtual constructor]] and as such can be called with no method object, with an explicit class name, or with an object variable, even if that object is <var>Null</var>:
<p class="code">%doc = NewFromRecord
%doc = %(XmlDoc):NewFromRecord
%doc = %doc:NewFromRecord
</p>
<li>Whether to use <var>ToXmlDoc</var>, <var>LoadFromRecord</var>, or <var>NewFromRecord</var> depends on what is
<li>Whether to use <var>ToXmlDoc</var>, <var>LoadFromRecord</var>, or <var>NewFromRecord</var> depends on what is
most convenient for your application.
most convenient for your application.
If you are already using a <var>Record</var> object which references the desired record,
If you are already using a <var>Record</var> object that references the desired record,
using <var>ToXmlDoc</var> may be more convenient; if not, then either
using <var>ToXmlDoc</var> may be more convenient; if not, then either
<var>NewFromRecord</var> or <var>LoadFromRecord</var> (both of which require that the method be
<var>NewFromRecord</var> or <var>LoadFromRecord</var> (both of which require that the method be
contained in a &ldquo;record loop&rdquo;) may be more convenient.
contained in a record loop, for example, <var>For Each Record</var>) may be more convenient.
You must use <var>LoadFromRecord</var> if you want to add the record's content as a
You must use <var>LoadFromRecord</var> if you want to add the record's content as a
subtree to a non-empty <var>XmlDoc</var>;
subtree to a non-empty <var>XmlDoc</var>;
in other cases the <var>NewFromRecord</var> &ldquo;factory method&rdquo; may be your choice.
in other cases the <var>NewFromRecord</var> virtual constructor may be your choice.
<p>  
<p>  
Since <var>NewFromRecord</var> and <var>ToXmlDoc</var> create new <var>XmlDoc</var> objects, they have the
Since <var>NewFromRecord</var> and <var>ToXmlDoc</var> create new <var>XmlDoc</var> objects, they have the
Line 92: Line 119:
As stated, both
As stated, both
<var>NewFromRecord</var> and <var>LoadFromRecord</var> must be
<var>NewFromRecord</var> and <var>LoadFromRecord</var> must be
contained in a &ldquo;record loop&rdquo;, for example, an <var>FRN</var> block, and they may not be
contained in a record loop, for example, an <var>FRN</var> block, and they may not be
invoked within a fieldgroup context.</p>
invoked within a fieldgroup context.</p>
<p>  
<p>  
Except for these considerations, <var>ToXmlDoc</var>, <var>NewFromRecord</var>, and <var>LoadFromRecord</var>
Except for these considerations, <var>ToXmlDoc</var>, <var>NewFromRecord</var>, and <var>LoadFromRecord</var>
all perform the same operation and have the same arguments.
all perform the same operation and have the same arguments, so.
</p>
</p>
<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage|Usage notes]], which apply equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var>. The topics discussed there are:
<ul>
<li>Invalid characters in field names
<li>Using <var>AllowUnreversible</var> for lowercase or invalid field name characters
<li>Base64 encoding of field values
<li>Field level security
<li>LOB fields
<li>Record locks
</ul>
</ul>
</ul>


==Examples==
==Examples==
In addition to the examples in the following section, see the following examples in the <var>ToXmlDoc</var> article, both of which apply equally to <var>LoadFromRecord</var> and <var>NewFromRecord</var>:
<ul>
<li>The [[ToXmlDoc (Record function)#AttributeValues, AttributeNames, and NamesToLower arguments|"AttributeValues, AttributeNames, and NamesToLower arguments"]] example
<li>The [[ToXmlDoc (Record function)#Getting record lock|"Getting record lock"]] example
</ul>
====Handling records with null characters====
====Handling records with null characters====
In the following example, <var>NewFromRecord</var> adds record content which includes a null character to an <var>XmlDoc</var>. The default <var>False</var> value of the <var>AllowNull</var> parameter is passed to the <var>XmlDoc</var> and causes the null character to be base64 encoded. This conforms to the XML Recommendation, which does not allow null characters in an XML document.
<!--This example is test XML.DME.003.QA in file QASHR-->
In the following example, <var>NewFromRecord</var> adds record content that includes a null character to an <var>XmlDoc</var>. The default <var>False</var> value of the <var>AllowNull</var> parameter is passed to the <var>XmlDoc</var> and causes the null character to be base64 encoded. This conforms to the XML Recommendation, which does not allow null characters in an XML document.
   
   
The following fragment:
The following fragment:
Line 160: Line 205:
<p>  
<p>  
The description [[#Syntax terms|above]] of the <var>AttributeValues</var> argument lists all conditions which force base64 encoding of the "field" element.</p>
The description [[#Syntax terms|above]] of the <var>AttributeValues</var> argument lists all conditions which force base64 encoding of the "field" element.</p>
==See also==
==See also==
<ul>
<ul>
<li>Among other things, the result <var>XmlDoc</var> can be used to copy a record, using the <var>[[AddToRecord (XmlDoc subroutine)|AddToRecord]]</var> subroutine.
<li>See the <var>[[LoadFromRecord (XmlDoc/XmlNode subroutine)|LoadFromRecord]]</var> method for a discussion of extracting the contents of the current record into an <var>XmlDoc</var>.
<li>See the <var>[[LoadFromRecord (XmlDoc/XmlNode subroutine)|LoadFromRecord]]</var> method for a discussion of extracting the contents of the current record into an <var>XmlDoc</var>.
</ul>
</ul>
{{Template:XmlDoc:NewFromRecord footer}}
{{Template:XmlDoc:NewFromRecord footer}}

Latest revision as of 22:04, 20 August 2019

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. Among other things, the result XmlDoc can be used to copy a record, using the AddToRecord subroutine.

The field and fieldgroup extraction performed by NewFromRecord is the same operation that is performed by the LoadFromRecord subroutine and by the ToXmlDoc function in the Record class, as is further described below in "Usage notes".

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

%docNewFromRecord returns a new XmlDoc object.
[%(XmlDoc):] The optional class name in parentheses denotes a virtual constructor method. See "Usage notes", below, for more information about invoking an XmlDoc virtual constructor.
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 NewFromRecord.
  • 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 value 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.

AllowNull The value of this name required 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). For an example, see "Handling records with null characters", below.

Usage notes

  • NewFromRecord is a virtual constructor and as such can be called with no method object, with an explicit class name, or with an object variable, even if that object is Null:

    %doc = NewFromRecord %doc = %(XmlDoc):NewFromRecord %doc = %doc:NewFromRecord

  • Whether to use ToXmlDoc, LoadFromRecord, or NewFromRecord 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, 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, so.

  • 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

Examples

In addition to the examples in the following section, see the following examples in the ToXmlDoc article, both of which apply equally to LoadFromRecord and NewFromRecord:

Handling records with null characters

In the following example, NewFromRecord adds record content that includes a null character to an XmlDoc. The default False value of the AllowNull parameter is passed to the XmlDoc and causes the null character to be base64 encoded. This conforms 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/&#x0;/ </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 (&#x0;). 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.

The description above of the AttributeValues argument lists all conditions which force base64 encoding of the "field" element.

See also

  • Among other things, the result XmlDoc can be used to copy a record, using the AddToRecord subroutine.
  • See the LoadFromRecord method for a discussion of extracting the contents of the current record into an XmlDoc.