Community articleSetLiteralByRefEx function
Added by IBM contributorIBM on July 26, 2013
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars


This function finds a particular IFormNodeP as specified by a reference string. Once the IFormNodeP is found, its literal will be set as specified. If the IFormNodeP does not exist, this function will create it, but only if the IFormNodeP would be an option or argument node.
If necessary, this function can create several nodes at once. For example, if you set the literal for the second argument of an itemlocation, this function will create the itemlocation option node and the two argument nodes and then set the literal for the second argument node.
This function cannot create a IFormNodeP at the form, page, or item level; to do so, use Create.
The node that you call this function on is used as the starting point for the search.
Note: It is not necessary to call this function when you are using XForms. Use the UpdateXFormsInstance function instead.


   Sub SetLiteralByRefEx(
      theScheme As String,
      theReference As String,
      theReferenceCode As Long,
      theCharSet As String,
      theNSNode As IFormNodeP,
      theLiteral As String)


Table 1. Function parameters
theSchemeStringReserved. This must be null.
theReferenceStringA string that contains the reference.
theReferenceCodeLongReserved. Must be 0.
theCharSetStringThe character set in which theLiteral parameter is written. Use null for ANSI/Unicode. Use Symbol for Symbol.
theNSNodeIFormNodePA node that is used to resolve the namespaces in theReference parameter (see “Determining Namespace” in the Notes® section). Use null if the node that you are calling this function on has inherited the necessary namespaces.
theLiteralStringThe string that will be assigned to the literal. If null, any existing literal is removed.


Nothing if the call is successful or throws an exception if an error occurs.

Usage details

Before you decide which IFormNodeP to use this function on, be sure you understand the following:
  1. The IFormNodeP you supply can never be more than one level in the hierarchy above the level at which your reference string starts. For example, if the reference string begins with an option, then the IFormNodeP can be no higher in the hierarchy than an item.
  2. If the IFormNodeP is at the same level or lower in the hierarchy than the starting point of the reference string, the function will attempt to locate a common ancestor. The function will locate the ancestor of the IFormNodeP that is one level in the hierarchy above the starting point of the reference string. The function will then attempt to follow the reference string back down through the hierarchy. If the reference string cannot be followed from the located ancestor (for example, if the ancestor is not common to both the IFormNodeP and the reference string), the function will fail. For example, given a IFormNodeP that represents "field_1" and a reference of "field_2", the function will access the "page" node above "field_1", and will then try to locate "field_2" below that node. If the two fields are not on the same page, the function will fail.
Creating a reference string:
For more information about creating a reference, see About references API 801 COMCreate New Article.
Digital signatures:
Do not set a node that is digitally signed. Doing so will break the digital signature and produce an error.
Determining namespace:
In some cases, you may want to use the SetLiteralByRefEx function to set the value for a node that does not have a globally defined namespace. For example, consider the following form:
   <label sid="Label1">
   <field sid="Field1" xmlns:processing="URI">

In this form, the processing namespace is declared in the Field1 node. Any elements within Field1 will understand that namespace; however, elements outside of the scope of Field1 will not.
In cases like this, you will often start your search at a node that does not understand the namespace of the node you are trying to locate. For example, you might want to locate the node referenced in the value of Label1. In this case, you would first locate the Label1 value node and get its literal. Then, from the Label1 value node, you would attempt to locate the processing:myValue node as shown:
   Label1Node.SetLiteralByRefEx(vbNullString, "Field1.processing:myValue",
      0, vbNullString, vbNullString, "20")

In this example, the setLiteralByRef function would fail. The function cannot properly resolve the processing namespace because this namespace is not defined for the Label1 value node. To correct this, you must also provide a node that understands the processing namespace (in this case, any node in the scope of Field1) as a parameter in the function:
   Label1Node.SetLiteralByRefEx(vbNullString, "Field1.processing:myValue",
      0, vbNullString, Field1Node, "20")


The following example adds a label to a form. A node is passed into the function, which then uses GetLiteralByRefEx to read the value of a field. The function then uses DereferenceEx to locate the field node, and creates a label node as a sibling using Create. Finally, the function creates a value for the new label node using SetLiteralByRef.
   Sub AddLabel(Form)
      Dim TempNode, XFDL ' objects
      Dim Name ' strings
      Set TempNode = Form
      ' Get the value of the NameField.value option node
      Name = TempNode.GetLiteralByRefEx(vbNullString, _
         "PAGE1.NameField.value", 0, vbNullString, Nothing)
      ' Locate the NameField item node in the first page of the form
      Set TempNode = TempNode.DereferenceEx(vbNullString, _
      "PAGE1.NameField", 0, UFL_ITEM_REFERENCE, Nothing)
      ' Get an XFDL object
      Set XFDL = CreateObject("PureEdge.xfdl_XFDL")
      ' Create a label.  This label is created as a sibling of the NameField,
      ' and is named NameLabel.
      Set TempNode = XFDL.Create(TempNode, UFL_AFTER_SIBLING, "label", _
         vbNullString, vbNullString, "NameLabel")
      ' Create a value option for the label.  This option is assigned the
      ' value of Name (as read from the field)
      TempNode.SetLiteralByRefEx vbNullString, "value", 0, vbNullString, _
         Nothing, Name
   End Sub

Parent topic:
FormNodeP functions