The PBDOM_PROCESSINGINSTRUCTION class defines behavior for an XML processing instruction. Methods allow you to obtain the target of the processing instruction object as well as its data. You can always access the data as a string, and, where appropriate, as name/value pairs.
Note that the actual processing instruction of a processing instruction object is a string, even if the instruction is divided into separate name=“value” pairs. PBDOM does support such a processing instruction object format. If the processing instruction object data does contain pairs, as is commonly the case, then PBDOM_PROCESSINGINSTRUCTION parses them into an internal list of name/value pairs.
Some of the inherited methods from PBDOM_OBJECT serve no meaningful objective, and only default or trivial functionalities result. These are described in the following table:
Method |
Always returns |
|---|---|
AddContent |
Current PBDOM_PROCESSINGINSTRUCTION. Use AddValue instead. |
GetContent |
false. Use GetName and GetValue instead. |
HasChildren |
false. |
InsertContent |
Current PBDOM_PROCESSINGINSTRUCTION. |
IsAncestorObjectOf |
false. |
RemoveContent |
false. Use RemoveValue instead. |
SetContent |
Current PBDOM_PROCESSINGINSTRUCTION. Use SetData instead. |
PBDOM_PROCESSINGINSTRUCTION has the following methods:
Creates and returns a clone of the current PBDOM_PROCESSINGINSTRUCTION object.
pbdom_pi_name.Clone(boolean bDeep)
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object. |
bDeep |
A boolean specifying whether a deep or shallow clone is returned. Values are true for a deep clone and false for a shallow clone. This argument is currently ignored. |
PBDOM_OBJECT. A clone of the current PBDOM_PROCESSINGINSTRUCTION object returned as a PBDOM_OBJECT.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If the internal implementation of this PBDOM_PROCESSINGINSTRUCTION object is null. The occurrence of this exception is rare, but it can take place if severe memory corruption occurs.
The Clone method creates a new PBDOM_PROCESSINGINSTRUCTION object that is a duplicate of, and a separate object from, the original. The clone of a PBDOM_PROCESSINGINSTRUCTION object is always identical to its original whether bDeep is true or false, because a PBDOM_PROCESSINGINSTRUCTION object contains no subtree of child PBDOM_OBJECTs.
A PBDOM_PROCESSINGINSTRUCTION clone has no parent, but it resides in the same PBDOM_DOCUMENT as its original, and if the original PBDOM_PROCESSINGINSTRUCTION object is standalone, so is the clone.
Detaches a PBDOM_PROCESSINGINSTRUCTION object from its parent PBDOM_OBJECT.
pbdom_pi_name.Detach()
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
PBDOM_OBJECT. This PBDOM_PROCESSINGINSTRUCTION object detached from its parent object. This method does nothing if this PBDOM_PROCESSINGINSTRUCTION object has no parent.
Tests for the equality of the current PBDOM_PROCESSINGINSTRUCTION object with the supplied PBDOM_OBJECT.
pbdom_pi_name.Equals(pbdom_object_ref)
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
pbdom_object_ref |
A PBDOM_OBJECT for testing for equality with the current PBDOM_PROCESSINGINSTRUCTION object |
Boolean. Returns true if the current PBDOM_PROCESSINGINSTRUCTION object is equivalent to the input PBDOM_OBJECT, and false otherwise.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If the input PBDOM_OBJECT is not a reference to an object derived from PBDOM_OBJECT.
Returns the raw data of the PBDOM_PROCESSINGINSTRUCTION object.
pbdom_pi_name.GetData()
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
String. The data of the PBDOM_PROCESSINGINSTRUCTION object.
The processing instruction data is fundamentally a string and not a set of name=“value” pairs.
Obtains the name of the current PBDOM_PROCESSINGINSTRUCTION object.
pbdom_pi_name.GetName()
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
String.
Calling the GetName method on
the following processing instruction returns works:
<?works document="hello.doc" data="hello.wks" ?>
This method is similar to the GetTarget method. To PBDOM, the processing instruction target is synonymous with its name.
Retrieves a list of names taken from the part of the PBDOM_PROCESSINGINSTRUCTION object’s data that is factored into name=“value” pairs. This method can be used in conjunction with the GetValue method.
pbdom_pi_name.GetNames(string name_array[ ])
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
name_array |
An unbounded string array filled with names |
Boolean. Returns true if a list of names is retrieved, and false otherwise. If there are no name/value pairs, this method returns false.
Given the following PBDOM_PROCESSINGINSTRUCTION
object, GetNames returns three strings, a, b,
and c, even though a occurs
more than once:
<? dw-set_values a="1" b="2" c="3" a="4" ?>
When the GetValue method is called on a,
the value 4 is returned,
because it is the last value set for a.
If a name is used more than once as the name of a name/value pair in a PBDOM_PROCESSINGINSTRUCTION object, then the value set in the last occurrence of the name is used, and values declared in all previous occurrences of the name are discarded.
Returns a long integer code that indicates the class of the current PBDOM_PROCESSINGINSTRUCTION object.
pbdom_pi_name.GetObjectClass()
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_OBJECT |
Long. GetObjectClass returns a long integer code that indicates the class of the current PBDOM_OBJECT. If pbdom_pi_name is a PBDOM_PROCESSINGINSTRUCTION object, the returned value is 10.
Returns a string form of the class of the PBDOM_PROCESSINGINSTRUCTION object.
pbdom_pi_name.GetObjectClassString()
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_OBJECT |
String. GetObjectClassString returns a string that indicates the class of the current PBDOM_OBJECT. If pbdom_pi_name is a PBDOM_PROCESSINGINSTRUCTION, the returned string is “pbdom_processinginstruction”.
Returns the owning PBDOM_DOCUMENT of the current PBDOM_PROCESSINGINSTRUCTION object.
pbdom_pi_name.GetOwnerDocumentObject()
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
PBDOM_DOCUMENT. If there is no owning PBDOM_DOCUMENT, null is returned.
Returns the parent PBDOM_OBJECT of the current PBDOM_PROCESSINGINSTRUCTION object.
pbdom_pi_name.GetParentObject()
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
PBDOM_OBJECT. The parent of the PBDOM_PROCESSINGINSTRUCTION object. If there is no parent, null is returned.
Returns the target of the PBDOM_PROCESSINGINSTRUCTION object.
pbdom_pi_name.GetTarget()
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
String. The target of the PBDOM_PROCESSINGINSTRUCTION object.
Given the following PBDOM_PROCESSINGINSTRUCTION object, calling the GetTarget method returns the string “xml-stylesheet”:
<?xml-stylesheet href="simple-ie5.xsl" type="text/xsl" ?>
Calling the GetName method returns the same string.
Obtains text data that is contained within the current PBDOM_PROCESSINGINSTRUCTION object.
pbdom_pi_name.GetText()
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
String.
The GetText method returns the text data of the current PBDOM_PROCESSINGINSTRUCTION object. GetText is similar to GetData. However, the textual content of a processing instruction object is not a text node.
Obtains the text data that is contained within the current PBDOM_PROCESSINGINSTRUCTION object with all surrounding whitespace characters removed and internal whitespace characters normalized to a single space.
pbdom_pi_name.GetTextNormalize()
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
String. The normalized text content of the PBDOM_PROCESSINGINSTRUCTION object. If no textual value exists for the current PBDOM_OBJECT, or if only whitespace characters exist, an empty string is returned.
Obtains the text data that is contained within the current PBDOM_PROCESSINGINSTRUCTION object with all surrounding whitespaces removed.
pbdom_pi_name.GetTextTrim()
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
String. The trimmed text content of the PBDOM_PROCESSINGINSTRUCTION object. If no textual value exists for the current PBDOM_PROCESSINGINSTRUCTION object, or if only whitespace characters exist, an empty string is returned.
Returns the value for a specific name/value pair on the PBDOM_PROCESSINGINSTRUCTION object. If no such pair is found for the PBDOM_PROCESSINGINSTRUCTION object, an empty string is returned.
pbdom_pi_name.GetValue(string strName)
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
strName |
String name of name/value pair |
String. String name of the name/value pair to search for value.
Given the following PBDOM_PROCESSINGINSTRUCTION
object, GetValue("href") returns
the string “simple-ie5.xsl”:
<?xml-stylesheet href="simple-ie5.xsl" type="text/xsl" ?>
Removes the specified name/value pair.
pbdom_pi_name.RemoveValue(string strName)
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
strName |
String name of name/value pair to be removed |
Boolean. Returns true if the requested name/value pair is removed and false otherwise.
Suppose the following PBDOM_PROCESSINGINSTRUCTION object is given:
<?xml-stylesheet href="simple-ie5.xsl" type="text/xsl" ?>
Then, RemoveValue("href") results
in the PBDOM_PROCESSINGINSTRUCTION object being transformed
into the following:
<?xml-stylesheet type="text/xsl" ?>
Sets the raw data for the PBDOM_PROCESSINGINSTRUCTION object.
pbdom_pi_name.SetData(string strData)
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
strData |
New data for the PBDOM_PROCESSINGINSTRUCTION object |
PBDOM_PROCESSINGINSTRUCTION. The PBDOM_PROCESSINGINSTRUCTION object modified with the new data.
EXCEPTION_INVALID_STRING – The input data is invalid. This can happen in the following circumstances:
The input data contains the sub-string “?>”. This violates the requirements for the data of a processing instruction.
If the processing instruction target name is xml,
making this PBDOM_PROCESSINGINSTRUCTION object an XML declaration processing
instruction, this exception is thrown if the input data string does not
conform to the following criteria:
The data
must contain a name/value pair for the name version.
The data can contain a name/value pair
for the name encoding.
The data can contain a name/value pair
for the name standalone. If it
does, the value for standalone must
either be yes or no.
The data must not contain any other data in the form of name/value pairs or in any other form.
Lowercase
The strings xml, version, encoding, standalone, yes,
and no are all case sensitive
and must be in lowercase.
Suppose there is a PBDOM_PROCESSINGINSTRUCTION object as follows:
<?xml-stylesheet href="simple-ie5.xsl" type="text/xsl" ?>
Then, SetData("href=new.xsl") results
in the PBDOM_PROCESSINGINSTRUCTION object being transformed
into the following:
<?xml-stylesheet href=new.xsl" ?>
The entire data for the PBDOM_PROCESSINGINSTRUCTION object is now reset.
Special processing is performed when the name of the processing
instruction’s target is xml, which
indicates that it is an XML declaration. The valid instructions
allowed in the input Data as part of the name in the name/value pairs
are version, encoding,
and standalone. The version
instruction is mandatory before the processing instruction can be
added to a document.
The XML specification expects the instructions to be in the
specific order version , encoding , standalone.
This function reorders the input data to conform to the specification,
for example:
<? xml version="1.0" encoding="utf-8" standalone="yes"?>
Sets the name of the current PBDOM_PROCESSINGINSTRUCTION object.
pbdom_pi_name.SetName(string strName)
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
strName |
The new name you want to set for the current PBDOM_PROCESSINGINSTRUCTION object |
Boolean. Returns true if the name of the current PBDOM_PROCESSINGINSTRUCTION object was changed, and false otherwise.
EXCEPTION_INVALID_NAME – This
exception is thrown if the name is invalid. The name can be xml,
making this PBDOM_PROCESSINGINSTRUCTION object an XML declaration
processing instruction. However, in this case, the name xml must
be in lowercase, or the EXCEPTION_INVALID_NAME exception
will be thrown.
EXCEPTION_INVALID_STRING – This
exception is thrown if the name is xml and
the current data of this PBDOM_PROCESSINGINSTRUCTION object
is not valid. The data is valid only under the following circumstances:
It is an empty string.
If it is not an empty string, it must contain a
name/value pair for the name version.
If it is not an empty string and it contains a name/value
pair for the name version,
it can also contain a name/value pair for the name encoding.
If it is not an empty string and it contains a name/value
pair for the name version,
it can also contain a name/value pair for the name standalone. If
it does, the value for standalone must
be either yes or no (both
are case sensitive).
If it is not an empty string and it contains a name/value
pair for the name version,
it must not contain any other data (in name/value pair
format or otherwise) except for encoding and standalone.
This method is equivalent to setting the target of the processing
instruction object. See the list of exceptions for information about
the restrictions on the use of xml as
the target.
Sets the referenced PBDOM_OBJECT to be the parent of the current PBDOM_PROCESSINGINSTRUCTION object.
pbdom_pi_name.SetParentObject(pbdom_object pbdom_object_ref)
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
pbdom_object_ref |
A PBDOM_OBJECT to be set as the parent of the current PBDOM_PROCESSINGINSTRUCTION object |
PBDOM_OBJECT. This PBDOM_PROCESSINGINSTRUCTION object modified.
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE – If the input PBDOM_OBJECT is not a reference to an object derived from PBDOM_OBJECT.
EXCEPTION_HIERARCHY_ERROR – If setting the input PBDOM_OBJECT to be the parent of this PBDOM_PROCESSINGINSTRUCTION object will cause the parent PBDOM_OBJECT to be no longer well formed. For example, if this PBDOM_PROCESSINGINSTRUCTION object is an XML declaration and the parent to be set is a PBDOM_ELEMENT.
The PBDOM_OBJECT that you set as the parent and the current PBDOM_PROCESSINGINSTRUCTION object must have a legal parent-child relationship. Currently, only a PBDOM_ELEMENT and a PBDOM_DOCUMENT can be set as the parent of a PBDOM_PROCESSINGINSTRUCTION object.
Sets the value for the specified name/value pair.
pbdom_pi_name.SetValue(string strName, stringstrValue)
Argument |
Description |
|---|---|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
strName |
String name of a name/value pair |
strValue |
String value of a name/value pair |
PBDOM_PROCESSINGINSTRUCTION.
EXCEPTION_INVALID_STRING – The input strName/strValue is invalid. This can happen in the following circumstances:
The input strName/strValue data
contains the sub-string ?>.
This violates the requirements for the data of a processing instruction.
If the target name is xml,
making this PBDOM_PROCESSINGINSTRUCTION object an XML declaration processing
instruction, this exception is thrown if the input data string does not
conform to the following criterion: the data can contain a name/value pair
for the name standalone. If
it does, the value for standalone must either
be yes or no.
The strings xml, standalone, yes,
and no are case sensitive and
must be lowercase.
EXCEPTION_INVALID_NAME -
The input strName is invalid. This can happen if
the target name is xml, making
this PBDOM_PROCESSINGINSTRUCTION object an XML declaration processing
instruction, and either of the following is true:
The strName value
is other than version, standalone or encoding.
Either standalone or encoding is
set without the version first
being set.
Consider the following PBDOM_PROCESSINGINSTRUCTION object:
<?xml-stylesheet href="simple-ie5.xsl" type="text/xsl" ?>
SetValue("href","new.xsl") transforms
this processing instruction to the following, modifying the value
for href:
<?xml-stylesheet href="new.xsl" type="text/xsl"?>
SetValue("extra_info","xalan") transforms
the processing instruction to the following, adding a new name/value
pair for extra_info:
<?xml-stylesheet href=new.xsl" type="text/xsl" extra_info "xalan" ?>
Then SetValue("extra_info_2","") transforms
the processing instruction to the following, adding a new name/value
pair for extra_info_2 with
an empty string as the value:
<?xml-stylesheet href=new.xsl" type="text/xsl" extra_info="xalan" extra_info_2="" ?>
If no value is found, the supplied pair is added to the processing instruction data. The appearance of name/value pairs in a PBDOM_PROCESSINGINSTRUCTION object is not subject to any order. In this way, name/value pairs in a PBDOM_PROCESSINGINSTRUCTION object are similar to attributes in an element. Attributes are specifically not ordered.
Special processing is performed when the name of the processing
instruction’s target is xml, which
indicates that it is an XML declaration. The valid instructions
allowed in the input Data as part of the name in the name/value pairs
are version, encoding,
and standalone. The version
instruction is mandatory before the processing instruction can be
added to a document.
The XML specification expects the instructions to be in this
specific order: version , encoding , standalone.
This function reorders the input data to conform to the specification,
for example:
<? xml version="1.0" encoding="utf-8" standalone="yes"?>
