NewFromRecord (XmlDoc function) - Revision history

Dme: /* Handling records with null characters */

2019-08-20T22:04:48Z

Handling records with null characters

← Older revision		Revision as of 22:04, 20 August 2019
Line 146:		Line 146:

	====Handling records with null characters====		====Handling records with null characters====
			<!--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.		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.

ELowell: /* Syntax */

2015-09-01T16:53:46Z

Syntax

← Older revision		Revision as of 16:53, 1 September 2015
Line 12:		Line 12:
	<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>		<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>		<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>

JAL at 20:27, 12 December 2013

2013-12-12T20:27:19Z

← Older revision		Revision as of 20:27, 12 December 2013
Line 68:		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 88:		Line 105:
	<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
Line 109:		Line 126:
	</p>		</p>

	<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|"Usage notes"]]~~; these~~ apply equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var>. The topics discussed there are:		<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>		<ul>
	<li>~~invalid~~ characters in field names;		<li>Invalid characters in field names
	<li>~~using~~ <var>AllowUnreversible</var> for lowercase or invalid field name characters;		<li>Using <var>AllowUnreversible</var> for lowercase or invalid field name characters
	<li>~~base64~~ encoding of field values;		<li>Base64 encoding of field values
	<li>~~field~~ level security;		<li>Field level security
	<li>LOB fields;		<li>LOB fields
	<li>~~record~~ locks.		<li>Record locks
	</ul>		</ul>

Line 124:		Line 141:
	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>:		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>		<ul>
	<li>~~the~~ [[ToXmlDoc (Record function)#AttributeValues, AttributeNames, and NamesToLower arguments\|"AttributeValues, AttributeNames, and NamesToLower arguments"]] example		<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		<li>The [[ToXmlDoc (Record function)#Getting record lock\|"Getting record lock"]] example
	</ul>		</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.		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:

Dme: /* Usage notes */

2012-10-24T22:02:34Z

Usage notes

← Older revision		Revision as of 22:02, 24 October 2012
Line 109:		Line 109:
	</p>		</p>

	<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|"Usage notes"]]; these apply equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var>.		<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|"Usage notes"]]; these 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>

Dme: /* Examples */

2012-08-12T18:42:51Z

Examples

← Older revision		Revision as of 18:42, 12 August 2012
Line 114:		Line 114:

	==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>:		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>		<ul>
	<li>the [[ToXmlDoc (Record function)#AttributeValues, AttributeNames, and NamesToLower arguments\|"AttributeValues, AttributeNames, and NamesToLower arguments"]] example		<li>the [[ToXmlDoc (Record function)#AttributeValues, AttributeNames, and NamesToLower arguments\|"AttributeValues, AttributeNames, and NamesToLower arguments"]] example

Dme: /* Examples */

2012-08-12T18:42:10Z

Examples

← Older revision		Revision as of 18:42, 12 August 2012
Line 114:		Line 114:

	==Examples==		==Examples==
	In addition to the examples in the following section, see the [[ToXmlDoc (Record function)#AttributeValues, AttributeNames, and NamesToLower arguments\|"AttributeValues, AttributeNames, and NamesToLower arguments"]] example ~~in the~~ <~~var~~>ToXmlDoc</~~var> article, which applies equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var~~>.		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.		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.

Dme: /* Examples */

2012-08-12T18:12:23Z

Examples

← Older revision		Revision as of 18:12, 12 August 2012
Line 114:		Line 114:

	==Examples==		==Examples==
	In addition to the examples in the following section, the ~~<var>~~[[ToXmlDoc (Record function)#~~Examples~~\|~~ToXmlDoc~~]]~~</var> examples show the effect of~~ the <var>~~AttributeValues~~</var>, <var>~~AttributeNames~~</var>, and <var>~~NamesToLower~~</var> ~~method arguments~~.		In addition to the examples in the following section, see the [[ToXmlDoc (Record function)#AttributeValues, AttributeNames, and NamesToLower arguments\|"AttributeValues, AttributeNames, and NamesToLower arguments"]] example in the <var>ToXmlDoc</var> article, which applies equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var>.
	====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.		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.

Dme: /* Examples */

2012-08-12T18:00:21Z

Examples

← Older revision		Revision as of 18:00, 12 August 2012
Line 114:		Line 114:

	==Examples==		==Examples==
			In addition to the examples in the following section, the <var>[[ToXmlDoc (Record function)#Examples\|ToXmlDoc]]</var> examples show the effect of the <var>AttributeValues</var>, <var>AttributeNames</var>, and <var>NamesToLower</var> method arguments.
	====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.		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.
Line 173:		Line 174:
	<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>

Dme: /* Usage notes */

2012-08-12T17:50:31Z

Usage notes

← Older revision		Revision as of 17:50, 12 August 2012
Line 106:		Line 106:
	<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, so		all perform the same operation and have the same arguments, so.
	~~<ul>~~
	~~<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|"Usage notes"]]~~.
	~~</ul>~~
	</p>		</p>

			<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|"Usage notes"]]; these apply equally to <var>NewFromRecord</var> and <var>LoadFromRecord</var>.

	</ul>		</ul>

Dme: /* Usage notes */

2012-08-12T17:48:28Z

Usage notes

← Older revision		Revision as of 17:48, 12 August 2012
Line 106:		Line 106:
	<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
			<ul>
			<li>See the additional comments in the <var>ToXmlDoc</var> [[ToXmlDoc (Record function)#othusage\|"Usage notes"]].
			</ul>
	</p>		</p>
	</ul>		</ul>