PBDOM_PROCESSINGINSTRUCTION

Description

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.

Methods

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:


Clone

Description

Creates and returns a clone of the current PBDOM_PROCESSINGINSTRUCTION object.

Syntax

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.


Return value

PBDOM_OBJECT. A clone of the current PBDOM_PROCESSINGINSTRUCTION object returned as a PBDOM_OBJECT.

Throws

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.

Usage

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.

Detach

Description

Detaches a PBDOM_PROCESSINGINSTRUCTION object from its parent PBDOM_OBJECT.

Syntax

pbdom_pi_name.Detach()

Argument

Description

pbdom_pi_name

The name of a PBDOM_PROCESSINGINSTRUCTION object


Return value

PBDOM_OBJECT. This PBDOM_PROCESSINGINSTRUCTION object detached from its parent object. This method does nothing if this PBDOM_PROCESSINGINSTRUCTION object has no parent.

Equals

Description

Tests for the equality of the current PBDOM_PROCESSINGINSTRUCTION object with the supplied PBDOM_OBJECT.

Syntax

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


Return value

Boolean.

Returns true if the current PBDOM_PROCESSINGINSTRUCTION object is equivalent to the input PBDOM_OBJECT, and false otherwise.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE  -- If the input PBDOM_OBJECT is not a reference to an object derived from PBDOM_OBJECT.

GetData

Description

Returns the raw data of the PBDOM_PROCESSINGINSTRUCTION object.

Syntax

pbdom_pi_name.GetData()

Argument

Description

pbdom_pi_name

The name of a PBDOM_PROCESSINGINSTRUCTION object


Return value

String.

The data of the PBDOM_PROCESSINGINSTRUCTION object.

Usage

The processing instruction data is fundamentally a string and not a set of name="value" pairs.

GetName

Description

Obtains the name of the current PBDOM_PROCESSINGINSTRUCTION object.

Syntax

pbdom_pi_name.GetName()

Argument

Description

pbdom_pi_name

The name of a PBDOM_PROCESSINGINSTRUCTION object


Return value

String.

Examples

Calling the GetName method on the following processing instruction returns works:

<?works document="hello.doc" data="hello.wks" ?>

Usage

This method is similar to the GetTarget method. To PBDOM, the processing instruction target is synonymous with its name.

GetNames

Description

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.

Syntax

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


Return value

Boolean.

Returns true if a list of names is retrieved, and false otherwise. If there are no name/value pairs, this method returns false.

Examples

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.

Usage

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.

GetObjectClass

Description

Returns a long integer code that indicates the class of the current PBDOM_PROCESSINGINSTRUCTION object.

Syntax

pbdom_pi_name.GetObjectClass()

Argument

Description

pbdom_pi_name

The name of a PBDOM_OBJECT


Return value

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.

GetObjectClassString

Description

Returns a string form of the class of the PBDOM_PROCESSINGINSTRUCTION object.

Syntax

pbdom_pi_name.GetObjectClassString()

Argument

Description

pbdom_pi_name

The name of a PBDOM_OBJECT


Return value

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

GetOwnerDocumentObject

Description

Returns the owning PBDOM_DOCUMENT of the current PBDOM_PROCESSINGINSTRUCTION object.

Syntax

pbdom_pi_name.GetOwnerDocumentObject()

Argument

Description

pbdom_pi_name

The name of a PBDOM_PROCESSINGINSTRUCTION object


Return value

PBDOM_DOCUMENT. If there is no owning PBDOM_DOCUMENT, null is returned.

GetParentObject

Description

Returns the parent PBDOM_OBJECT of the current PBDOM_PROCESSINGINSTRUCTION object.

Syntax

pbdom_pi_name.GetParentObject()

Argument

Description

pbdom_pi_name

The name of a PBDOM_PROCESSINGINSTRUCTION object


Return value

PBDOM_OBJECT. The parent of the PBDOM_PROCESSINGINSTRUCTION object. If there is no parent, null is returned.

GetTarget

Description

Returns the target of the PBDOM_PROCESSINGINSTRUCTION object.

Syntax

pbdom_pi_name.GetTarget()

Argument

Description

pbdom_pi_name

The name of a PBDOM_PROCESSINGINSTRUCTION object


Return value

String.

The target of the PBDOM_PROCESSINGINSTRUCTION object.

Examples

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.

See also

GetName

GetText

Description

Obtains text data that is contained within the current PBDOM_PROCESSINGINSTRUCTION object.

Syntax

pbdom_pi_name.GetText() 

Argument

Description

pbdom_pi_name

The name of a PBDOM_PROCESSINGINSTRUCTION object


Return value

String.

Usage

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.

See also

GetData

GetTextNormalize

GetTextTrim

SetData

GetTextNormalize

Description

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.

Syntax

pbdom_pi_name.GetTextNormalize()

Argument

Description

pbdom_pi_name

The name of a PBDOM_PROCESSINGINSTRUCTION object


Return value

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.

See also

GetData

GetText

GetTextTrim

SetData

GetTextTrim

Description

Obtains the text data that is contained within the current PBDOM_PROCESSINGINSTRUCTION object with all surrounding whitespaces removed.

Syntax

pbdom_pi_name.GetTextTrim()

Argument

Description

pbdom_pi_name

The name of a PBDOM_PROCESSINGINSTRUCTION object


Return value

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.

See also

GetData

GetText

GetTextNormalize

SetData

GetValue

Description

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.

Syntax

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


Return value

String.

String name of the name/value pair to search for value.

Examples

Given the following PBDOM_PROCESSINGINSTRUCTION object, GetValue("href") returns the string "simple-ie5.xsl":

<?xml-stylesheet href="simple-ie5.xsl" type="text/xsl" ?>

See also

GetData

GetText, SetValue

RemoveValue

Description

Removes the specified name/value pair.

Syntax

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


Return value

Boolean.

Returns true if the requested name/value pair is removed and false otherwise.

Examples

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

SetData

Description

Sets the raw data for the PBDOM_PROCESSINGINSTRUCTION object.

Syntax

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


Return value

PBDOM_PROCESSINGINSTRUCTION. The PBDOM_PROCESSINGINSTRUCTION object modified with the new data.

Throws

EXCEPTION_INVALID_STRING  -- The input data is invalid. This can happen in the following circumstances:

  1. The input data contains the sub-string "?>". This violates the requirements for the data of a processing instruction.

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

Examples

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.

Usage

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

SetName

Description

Sets the name of the current PBDOM_PROCESSINGINSTRUCTION object.

Syntax

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


Return value

Boolean.

Returns true if the name of the current PBDOM_PROCESSINGINSTRUCTION object was changed, and false otherwise.

Throws

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.

Usage

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.

SetParentObject

Description

Sets the referenced PBDOM_OBJECT to be the parent of the current PBDOM_PROCESSINGINSTRUCTION object.

Syntax

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


Return value

PBDOM_OBJECT. This PBDOM_PROCESSINGINSTRUCTION object modified.

Throws

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.

Usage

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.

SetValue

Description

Sets the value for the specified name/value pair.

Syntax

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


Return value

PBDOM_PROCESSINGINSTRUCTION.

Throws

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.

Examples

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="" ?>

Usage

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