IOSetRemoteReferences() Function

You can use the IOSetRemoteReferences() script function to redirect Application Server object references or remote references to tags while an InTouch application is running. IOSetRemoteReferences() finds all remote references that match specified strings and changes those references according to specified argument values. You can create a script that triggers the function to redirect references based on conditions being met or by a user action.

Category

Misc

Syntax

IOSetRemoteReferences(BaseAccess, NewAccess, MatchString, SubstituteString, Mode)

Arguments

BaseAccess

This string argument specifies the original configured Access Name to match in the references.

NewAccess

The new Access Name. The new Access Name is applied to all references in which the original Access Name matches the string provided with BaseAccess and for which the original Item Name matches the MatchString value if one is specified.

MatchString

The string to match in the original configured Item Name in the references. If the MatchString value is an empty string, it is regarded as a match for any Item Name.

SubstituteString

The string to substitute for the original Item Name. The string replaces the MatchString value to create the new active Item Name for the references. If SubstituteString is an empty string, no substitution is made.

Mode

Determines the method used to compare the original configured Item Name to the MatchString value. Matching is always from the beginning of the Item Name. A Mode value of 0 specifies the match must be for the entire Item Name or up to a period (.) within the name. A Mode value of 1 specifies that a partial match is allowed, even if the next character is not a period.

Remarks

IOSetRemoteReferences() does not check the validity of the new tag or Access Name before changing the object references.

• IOSetRemoteReferences() only changes remote references. The function redirects those references in which the original, configured Access Name matches the specified value of the BaseAccess argument, and the original Item Name matches the MatchString value.

• A single call to IOSetRemoteReferences() affects all remote references in active windows that are in memory in which the original, configured name strings match the values assigned to the BaseAccess and MatchString arguments.

• If you do not assign a value to the BaseAccess argument, IOSetRemoteReferences() does not redirect any remote references.

• If the MatchString argument is empty, IOSetRemoteReferences() redirects all remote references in which the original Access Name matches the value assigned to the BaseAccess argument.

• When the Mode argument is set to 0, replacement in the Item Name is only done for full object names (or tags), or full property names (or dotfields). The value of the MatchString argument must match the entire original Item Name or up to a character followed by a period.

• When the Mode argument is set to 1, partial replacement of the item string is allowed when the item string starts with the match item string. That is, MatchString must match some portion of the original item string, but that sub-portion must start at the beginning of the item string. The last character in the matching string does not need to be followed by a period.

• The original, configured names for a remote reference remain unchanged. Subsequent calls to IOSetRemoteReferences() do not need to recognize the current active name. Calls to IOSetRemoteReferences() can be made in any order.

• If you want two or more windows to refer to one remote reference, that remote reference acts like an I/O tag. When you redirect it, all windows see the same thing. Do not use a single name to refer to two separate targets at the same time.

  Note: Changing many references simultaneously, for example in a Window OnShow script, can take some time before all references are resolved.

Examples

The following example redirects all remote references to the pump001 item name of the Galaxy Access Name if the original item name exactly matches pumpX.

IOSetRemoteReferences("Galaxy","","pumpX", "pump001",0);

The following example matches changes the Galaxy Access Name to TagServer1 if the item name exactly matches pumpX. Also, the item name is changed to p2.

IOSetRemoteReferences("Galaxy","TagServer1", "pumpX","p2",0);

The following example changes the TagServer1 Access Name to TagServer2 when the item name is pumpX. Also, the item name is changed to backpump3.

IOSetRemoteReferences("TagServer1","TagServer2", "pumpX","backpump3",0)

The following example changes the Tank item name of the TagServer1 Access Name to Plant.

IOSetRemoteReferences("TagServer1","","Tank", "Plant",1)

The following example does not redirect any remote references because no value is assigned to the BaseAccess argument.

IOSetRemoteReferences("","Galaxy","pumpX", "pump001",0);