Description
Sets the value for the specified name/value pair.
Note
Starting from Version 2022, the PBDOM_PROCESSINGINSTRUCTION object is no longer supported to add and modify the XML declarations. Use the PBDOM_DOCUMENT SetXMLDeclaration method to set the XML declaration instead of using SetValue.
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"?>
