Click or drag to resize
OSIsoft, LLC

Path Syntax Overview

This topic describes the syntax used when parsing paths to an AFObject within the AF SDK.

This topic contains the following sections:

A path to an object is created by the one of the AFObjectGetPath methods and is restored from a string by one of the Find methods that accept a path (e.g. AFObjectFindObject, AFObjectFindObjects, AFAttributeFindAttribute(String, AFObject)). A path, such as "\\MySystem\MyDatabase\MyElement|Attribute1", can be used to reference any object derived from AFObject.

The AFObjectGetPath method is similar to using the IPIPersistPersist method to save an object, but has options that can produce a more human readable format, as well as options for shortening the string by using a relative base object which can decrease the length of the string. If the string is encoded with either the AFEncodeTypeShortName or AFEncodeTypeFriendlyName option, it cannot always be restored using one of the Find methods.

Syntax

Path syntax described in Extended Backus-Naur Form (EBNF)
Path              = [ PathStart ] PathPart { ("\" | "|") PathPart }
                  | DynamicAttrPath     (* Only for FindAttribute methods *)
                  ;

PathStart         = "\\"                (* Starting at system-level (Systems or PIServers) *)
                  | "\"                 (* Starting at AFDatabase or UOMDatabase *)
                  | ".\DataReference"   (* Starting at DataReference if relative to AFAttribute
                                           or AFAttributeTemplate *)
                  | ".\DeliveryChannel" (* Starting at DeliveryChannel if relative to AFNotificationContact *)
                  | ".\"                (* Starting at AFBaseElement if relative to AFAttribute
                                           or AFElementTemplate if relative to AFAttributeTemplate *)
                  | "..\"               (* Starting with parent AFElement if relative to AFAttribute
                                           or AFElementTemplate if relative to AFAttributeTemplate *)
                  ;

PathPart          = "|"                 (* Root AFAttribute or AFAttributeTemplate *)
                  | NameId
                  | "[" NameIdOrFilters "]"
                  | AFIDENTITY "[" NameIdOrFilters "]"
                  ;

NameIdOrFilters   = NameId
                  | Filter { "][" Filter }
                  ;

NameId            = Name [ ";" Guid ]   (* Name has higher precedence *)
                  | Guid [ ";" Name ]   (* ID has higher precedence *)
                  ;

Name              = StringValue
                  | "EnumerationSets[]" (* System State Set, not allowed within brackets *)
                  ;

Filter            = "@Name=" StringValue
                  | "@Category=" StringValue
                  | "@Description=" StringValue
                  | "@ReferenceType=" StringValue
                  | "@Template=" StringValue
                  | "@Trait=" StringValue (* Name of Trait or group of Traits *)
                  | "@Type=" StringValue
                  | "@UOM=" StringValue
                  | "@Index=" IntValue    (* Index is 1-based, negative to index from end *)
                  | Integer               (* Only valid with previous filter specified, Index is 1-based, negative to index from end *)
                  ;

DynamicAttrPath   = String "." String                                   (* DataReferenceName.ConfigString *)
                  | "\\" PIServerPart "\" PIPointPart [ ";" String ] ;  (* \\PIServer\PIPoint;ConfigString *)
                  | PIPointPart [ ";" String ] ;                        (* PIPoint;ConfigString when relative to a PIServer *)
                  ;

PIServerPart      = PIServerNameId
                  | "PIServer[" PIServerNameId "]"
                  | "PIServers[" PIServerNameId "]"
                  ;

PIPointPart       = PIPointNameId
                  | "PIPoint[" PIPointNameId "]"
                  ;

PIServerNameId    = StringValue [ ";" Guid ]             (* Name has higher precedence *)
                  | StringValue [ "?" GuidString ]       (* Name has higher precedence *)
                  | Guid [ ";" StringValue ]             (* ID has higher precedence *)
                  ;

PIPointNameId     = StringValue [[ ";" ] "?" Integer ]   (* Name has higher precedence *)
                  | "?" Integer [ ";" StringValue ]      (* ID has higher precedence *)
                  ;

StringValue       = "'" { QuotedEscapedChar | "''" } "'"
                  | """ { QuotedEscapedChar | """" } """
                  | String
                  ;

QuotedEscapedChar = Char
                  | "\""      (* Escaped " character *)
                  | "\'"      (* Escaped ' character *)
                  | "\*"      (* Escaped * character *)
                  | "\?"      (* Escaped ? character *)
                  ;

EscapedChar       = NoWhiteSpaceChar
                  | "\" Char  (* The character is escaped *)
                  ;

IntValue          = "'" Integer "'"
                  | """ Integer """
                  | Integer
                  ;

Guid              = "{" GuidString "}" ;

Integer           = Digit { Digit } ;

Digit             = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

GuidString        = ? Hex Digits in following format: HHHHHHHH-HHHH-HHHH-HHHHHHHHHHHH ?

String            = ? Any sequence of printable characters ?

NoWhiteSpaceChar  = ? Any printable character except whitespace characters ?

Char              = ? Any printable character ?

Description

The path is segmented into parts, and each part represents an object or list of objects derived from the AFObject base class. Parts are typically separated with a single backslash (\), with the exception of either an AFAttribute or an AFAttributeTemplate, which use the pipe character (|). Additionally, the PISystem or PIServer portion begins with two backslashes (\\). Depending on the encoding option chosen, each part of the path will contain information on the specific object(s) in that part of the path. That information may consist of the type of collection the object is in, as well either the Name and/or UniqueID of the object or one or more collection filters. There is a default object type for each parent object, therefore the type of collection for the object is only required if it is not the default or a filter is specified. The default collection types are specified in the Default Collection Types table below.

If the collection is specified, then the collection filter or Name and/or UniqueID are enclosed in square brackets ([ and ]). If both the Name and UniqueID are specified, then they are separated by a semicolon (;), and their relative order defines the precedence when used when finding the object (the first one specified has higher precedence). UniqueIDs must include the surrounding curly brackets ({ and }). A single period enclosed in square brackets (i.e. "[.]") represents the default collection member of the parent object.

A collection filter starts with the at sign (@) followed by the filter name. Multiple filters may be specified and are evaluated in the specified order. The index filter "[@Index=int]" or "[int]" is used to specify the index of the matched object to return and should be the last filter specified. If the index filter is not specified, then the first match is returned if returning a single object. When using the index filter, the first item is at index 1. A negative index value starts from the end of the collection (e.g. -1 is last item in collection). The Path Filter table below specifies the supported filters. If a filter does not apply to the type of object in the collection, then an object will not be found.

The PISystem starts a fully qualified path and is preceded by two backslashes (\\). The collection name "Systems" is not needed since its location within the path is well known. A relative path starting with "\\." indicates to begin using the same system as the relative object. For example, "\\.\Database2" can be used to reference a database in the same system as the relative object. If the relative object is not specified or the PISystem is not specified as part of the path, then the PISystemsDefaultPISystem will be used. The path for a PIServer must specify the "PIServers" collection in the following format: \\PIServers[MyPIServerName].

The AFDatabase is the default object which follows a PISystem. To access other non-database objects off of the system, the collection must be identified (e.g. "\\MySystem\Contacts[JSmith]"). A relative path starting with a single backslash (\), indicates to begin using the same database as the relative object. For example, paths "\Element2" and "\Tables[MyTable]" can be used to reference objects in the same database as the relative object. If the relative object is not specified or the AFDatabase is not specified as part of the path, then the AFDatabasesDefaultDatabase will be used.

When using the relative parameter, the AFObjectGetPath method will only create a parent relative path that is one level higher than the relative object. The parent is indicated by a double period (..). An example parent path is "..\Element2|Attribute1". The single period (.) represents the current relative object and can be used to create a relative path from itself. When the relative object is an AFAttribute, then the single period followed by a backslash (.\) represents the owning AFBaseElement while the single period followed by a vertical bar (.|) will reference a child AFAttribute. Examples of a self relative path are ".\|Attribute1" and ".|Attribute1|Attribute2" where the specified relative object was an AFAttribute. All other Element reference types will create a relative path from the database: "\Element1\Element2|Attribute1".

An AFElement may have multiple paths. To find all of an element's paths, use the AFElementGetPaths method. The AFObjectGetPath method will return the 'strongest' path for an element, as well as child objects such as AFAttributes. The strongest path is typically created by the first reference to the element. An element is the default collection from a database, so the element collection name does not need to be specified in the path.

Paths to dynamic objects are also supported for the FindAttribute methods. The path for a dynamic AFAttribute contains the AFPlugIn name of the AFDataReference and its ConfigString separated by a single period (.) (e.g. "DataReferenceName.ConfigString"). For example, "PI Point Array.\\piserver2\sinusoid|sinusoidu" would create a PIPoint Array dynamic attribute with two values: Sinusoid and Sinusoidu. If the path indicates a path to a PIPoint, then a dynamic attribute will be created using the PI Point data reference with the ConfigString indicated by the path. For example, "\\pisever2\sinusoid" would create a dynamic attribute with the DataReference configured to read values from the PIPoint Sinusoid.

Default Collection Types

The following table lists the default type of collection for each parent object type. The default type of collection will be used when an AFIDENTITY is not specified in the PathPart.

Parent Type

Default Collection Type

PISystem

Databases

PIServer

PIPoints

AFCollective

CollectiveMembers

UOMDatabase

UOMs

UOMClass

UOMs

AFDatabase

Elements

AFElementTemplate

AttributeTemplates (2)

AFNotificationTemplate

AttributeTemplates or NotificationContacts (1)

AFElement

Attributes or Elements (1)

AFModel

Attributes or Elements (1)

AFCase

Attributes or Elements (1)

AFAttribute

Attributes

AFAttributeTemplate

AttributeTemplates

AFLayer

Elements

AFAnalysis

Cases

AFAnalysiRule

AnalysisRules

AFEnumerationSet

EnumerationValues

AFEventFrame

Attributes or EventFrames (1)

AFNotification

Attributes or NotificationContacts (1)

AFNotificationContact

NotificationContacts

AFNotificationContent

NotificationContacts

AFNotificationContactTemplate

NotificationContactTemplates

AFResult

Adjustments

AFTransfer

Attributes

  • (1) The default type of collection is Attributes unless the path starts at an AFBaseElement indicated with ".\" or starts at with a parent AFElement or AFElementTemplate indicated with "..\".

  • (2) Specifying Attributes as the collection name will also result in the default collection of AttributeTemplates.

Path Filters

Path filters can be used to restrict the objects that are returned for a collection in the path. For example, on an Elements collection you could specify a Template filter to only return elements that have the specified template or a Name filter of "Tank*" to return the elements whose name start with the specified string. The Name filter value can contain wildcard characters and are described in the Wildcard Characters section below. The following table lists the supported path filters.

Filter

Description

Example

@Category

Return the object(s) that matches the specified AFCategory in the collection.

\Element#1\Elements[@Category=MyCategory]

@Description

Return the object(s) that matches the specified description in the collection.

\Element#1\Elements[@Description=My Description]

@Index

Specify an index into the collection. First item in the collection is at index 1 (one based). Use a negative number for an index from the end of the collection (e.g. -1 is last item, -2 is next-to-last item). The '@Index' filter name is optional if another filter is specified before the index filter.

\Element#1\Elements[@Index=4] or \Element#1\Elements[@Name=Tank*][@Index=-3] or \Element#1\Elements[@Name=Tank*][-3]

@Name

Return the object(s) whose Name matches the specified query string in the collection.

\Element#1\Elements[@Name=Tank*]

@ReferenceType

Return the object(s) that matches the specified AFReferenceType in the collection.

\Element#1\Elements[@ReferenceType=Composition]

@Template

Return the object(s) that matches the specified template in the collection.

\Element#1\Elements[@Template=MyTemplate]

@Trait

Return the object(s) that matches the specified trait in the collection.

\Element#1|Pressure|Attributes[@Trait=HiHi]

@Type

Return the object(s) that matches the specified type in the collection.

\Element#1\Elements[@Type=Flow] or \Element#1|Attributes[@Type=System.Int32]

@UOM

Return the object(s) that matches the specified UOM in the collection.

\Element#1|Attributes[@UOM=meter]

Wildcard Characters

The string value of a filter can be enclosed in single quotes ('), double quotes ("), or without quotes. The filter string value can include regular characters and wildcard characters. Regular characters must match exactly the characters specified in the filter value. Wildcard characters can be matched with arbitrary fragments of the filter value. Wildcard characters can be escaped using the single backslash (\) character.

When the filter value is specified within either single or double quotes, the single backslash (\) character is treated as a literal character unless followed by a wildcard character, a single quote ('), or a double quote ("). When specified within quotes, two quote characters that match the starting quote character are treated as a single quote character (e.g. '' is treated as a one single quote character ' if the filter value starts with a single quote). When the filter value is specified without quotes, all characters are treated as a literal character (there are no escaped characters).

The wildcard characters used in the string value of a filter have the following rules:

  • If an empty string is specified as part of the Name filter, then everything will be matched. Otherwise, an exact match on empty string or default value for the filter is performed if an empty string is specified.

  • If no wildcards, then an exact match on the filter string is performed.

  • Wildcard * can be placed anywhere in the filter string and matches zero or more characters.

  • Wildcard ? can be placed anywhere in the filter string and matches exactly one character.

Examples

Below are some example paths:

  • \\MySystem\MyDatabase

  • \\Systems[MySystem]\Databases[MyDatabase]

  • \\.\Databases[.]

  • \\.\.

  • \\{5c64c379-c182-4f35-8d30-78d8c2f84502};MySystem\{5c64c379-c182-4f35-8d30-78d8c2f84503};MyDatabase

  • \\{5c64c379-c182-4f35-8d30-78d8c2f84502}\{5c64c379-c182-4f35-8d30-78d8c2f84503}

  • \\Systems[MySystem]\Databases[@Index=3]

  • \\MySystem\MyDatabase\Elements[@Template=Tank]|Attributes[Pressure]|[@Trait=HiHi]

  • \\MySystem\MyDatabase\Elements[@Template=Tank]|Attributes[Pressure]|[@Trait=AllLimits]

  • \\MySystem\MyDatabase\Elements[@Template=Tank][@Category=Tutorial]|Attributes[@Category=Tutorial]

  • \\MySystem\MyDatabase\[@Template=Tank][@Category=Tutorial]|[@Category=Tutorial]

  • \\MySystem\Databases[MyDatabase]\Elements[@Category=Tutorial]|Volume

  • \\MySystem\Databases[{5c64c379-c182-4f35-8d30-78d8c2f84503}]\[@Category=Tutorial]|Volume

  • \\PIServer[MyPIServer]\PIPoint[PointName?123]

  • \\PIServer[MyPIServer]\PointName?123

  • \\PIServer[.]\StateSets[System]\No Data

  • \\PIServer[.]\StateSets['State ''Special'' Set']\No Data

See Also

Reference

Other Resources

Enabling Operational Intelligence