Using tags or functions in ECMAScript

ECMAScript follows its own string parsing rules and hence, you must be aware of the methods you must use when you want to use tags or functions in ECMAScript.

You can find the guidelines to be followed when you use the tags or functions under different scenarios:
  • All strings must be enclosed in quotation marks, with appropriate escape sequences:
    • Quotation marks within the value of the string must be preceded by a backslash (\")
    • Backslashes must be preceded by another backslash (\\)
      Example legacy function:
      setTag(testFileName, C:\myfile.txt)
      After conversion to ECMAScript:
      setTag("testFileName", "C:\\myfile.txt")
      or
      testFileName = "C:\\myfile.txt"
  • Replace the null() function with the null keyword.
    Example legacy function:
    setTag(testTag, null())
    After conversion to ECMAScript:
    setTag("testTag", null)
    or
    testTag = null
  • Although the setTag() function is still valid in ECMAScript, you can assign values directly instead:
    Example legacy function:
    setTag(testTag, newValue)
    After conversion to ECMAScript:
    testTag = "newValue"
    or
    tags["testTag"] = "newValue"
    Note: A direct reference to a tag named id must be qualified with tags. In ECMAScript you can reference a tag with:
    
    tags["myTagName"]
    tags.get("myTagName")
    tags.myTagName
    myTagName
    
    When the tag name is id, tags.id resolves correctly during execution.
  • Similarly, you can replace the legacy add() function with an operator:
    Example legacy function:
    add(%%testTag%%, 1)
    After conversion to ECMAScript:
    testTag + 1
  • ECMAScript functions do not recognize double percent signs (%%). Therefore, when you write a function, do not enclose the tags in double percent signs as you would in a legacy function. Test Integrations and APIs tags are automatically exposed as ECMAScript local variables.
    • In most cases, you can treat the tag name as a local variable:
      Example legacy function:
      resetTags(%%variable%%)
      After conversion to ECMAScript:
      resetTags(variable)
      Example legacy function:
      xpath(%%xml%%, %%xpathString%%)
      After conversion to ECMAScript:
      xpath(xml, xpathString)
    • Tag names that include symbols or reserved words can cause problems; in those cases use the tags["tagname"] style of notation.
      Same example, after conversion to ECMAScript:
      xpath(tags["xml"], tags["xpathString"])
Note: When you assign tags that contain binary data to another tag, a reference to the underlying data is created and any changes to the data is reflected in both tags. You can avoid duplication in the tags by making a copy of the actual data. For example,
tags["b"] = java.lang.reflect.Array.newInstance(java.lang.Byte.TYPE, tags["a"].length);
java.lang.System.arraycopy(tags["a"], 0, tags["b"], 0, tags["a"].length);