Command line parameters

Save PDF

Last UpdatedJan 29, 2024
16 minute read

Note: The PI Universal Interface (UniInt) User Guide includes details about other command-line parameters, which may be useful.

Parameter	Description
/CacheMode Required Default: Not Defined	Required for disconnected startup operation. If defined, the /CacheMode startup parameter indicates that the interface will be configured to utilize the disconnected startup feature.
/CachePath=path Optional Default: Not Defined	Used to specify a directory in which to create the point caching files. The directory specified must already exist on the target machine. By default, the files are created in the same location as the interface executable. If the path contains any spaces, enclose the path in quotes. Examples: /CachePath=D:\PIPC\Interfaces\CacheFiles /CachePath=D:/PIPC/Interfaces/CacheFiles / CachePath=D:/PIPC/Interfaces/CacheFiles/ Examples with space in path name: /CachePath="D:\Program Files\PIPC\MyFiles" /CachePath="D:/Program Files/PIPC/MyFiles" /CachePath="D:/Program Files/PIPC/MyFiles/"
/CacheSynch=# Optional Default: 250 ms	Care must be taken when modifying this parameter. This value must be less than the smallest scan class period defined with the /f parameter. If the value of the /CacheSynch parameter is greater than the scan class value, input scans will be missed while the point cache file is being synchronized. The optional /CacheSynch=# startup parameter specifies the time slice period in milliseconds (ms) allocated by UniInt for synchronizing the interface point cache file with the PI Data Archive. By default, the interface will synchronize the point cache if running in the disconnected startup mode. UniInt allocates a maximum of # ms each pass through the control loop synchronizing the interface point cache until the file is completely synchronized. Synchronization of the point cache file can be disabled by setting the value /CacheSynch=0 . The minimum synchronization period when cache synchronization is enabled is 50ms Whereas, the maximum synchronization period is 3000ms (3s). Period values of 1 to 49 will be changed by the interface to the minimum of 50ms and values greater than 3000 will be set to the maximum interval value of 3000ms. Default: 250 ms Range: {0, 50 - 3000} time in milliseconds Example: /CacheSynch=50 (use a 50ms interval) /CacheSynch=3000 (use a 3s interval) /CacheSynch=0 (do not synchronize the cache)
/dnpdbg=level Optional	Specifies the level of debugging messages to be written to the log files and to the console window if running interactively. The level is a 16-bit number that can be expressed as a hexadecimal number if preceded with a 0x. Each bit of the debug parameter turns on and off debugging in a different section of the interface. The following list shows example debug parameters and the section of code affected by that bit. For each bit, setting the bit to 1 will turn on that section's debugging messages and setting the bit to 0 will turn them off. To combine different parameters, add the value of the parameters together. For example, to send the raw DNP messages to both the RTU log file and to the console, and to log the Data Link, Transport, and Application Layer message explanations to the log file, set the parameter to /dnpdbg=0x001F . Basically, this turns on bits 1 through 5 starting from the right. For a more detailed explanation, See the DNP and other debugging messages section. Examples /dnpdbg=0x0001 Raw DNP messages written to the RTU log file /dnpdbg=0x0002 Data Link Layer Descriptions to Log File /dnpdbg=0x0004 Transport Layer Descriptions to Log File /dnpdbg=0x0008 Application Layer Descriptions to Log File /dnpdbg=0x0010 Raw DNP messages written to the Console /dnpdbg=0x0020 Data Link Layer Descriptions to Console /dnpdbg=0x0040 Transport Layer Descriptions to Console /dnpdbg=0x0080 Application Layer Descriptions to Console /dnpdbg=0x0100 Start-UP procedures /dnpdbg=0x0200 Load PI point Procedures /dnpdbg=0x0400 Data Sent to PI (not including Heartbeat points) /dnpdbg=0x0800 Scanning for Current Values /dnpdbg=0x1000 Communication Medium /dnpdbg=0x2000 Value Scaling
/ec=# Optional	The first instance of the /ec parameter on the command-line is used to specify a counter number, # , for an I/O Rate point. If the # is not specified, then the default event counter is 1. Also, if the /ec parameter is not specified at all, there is still a default event counter of 1 associated with the interface. If there is an I/O Rate point that is associated with an event counter of 1, each copy of the interface that is running without /ec=# explicitly defined will write to the same I/O Rate point. This means either explicitly defining an event counter other than 1 for each copy of the interface or not associating any I/O Rate points with event counter 1. For interfaces that run on Windows nodes, subsequent instances of the /ec parameter may be used by specific interfaces to keep track of various input or output operations. Subsequent instances of the /ec parameter can be of the form /ec, where is any ASCII character sequence. For example, /ecinput=10 , /ecoutput=11, and /ec=12 are legitimate choices for the second, third, and fourth event counter strings.
/event=ScanClass Optional	Specifies a scan class as an event class which polls the RTU for all DNP3 class 1,2, and 3 events. All of the points assigned to this scan class will be treated as event type points. The ScanClass defines a scan class that corresponds to a /f= flag from the start-up file and the Location4 of the PI points. Example: If this is found in the start-up file. /f=10 /f=120 /f=00:10:00 /event=2 The interface will make a request for event data (class 1,2,3 data) every 2 minutes. All PI points with Location4 equal to 2 will be considered event type points and no requests for static data will be made for these points except during the integrity scan if configured.
/f=SS.## or /f=SS.##,SS.## or /f=HH:MM:SS.## or /f=HH:MM:SS.##, hh:mm:ss.## Required for reading scan-based inputs	The /f parameter defines the time period between scans in terms of hours (HH), minutes (MM), seconds (SS) and sub-seconds (##). The scans can be scheduled to occur at discrete moments in time with an optional time offset specified in terms of hours (hh), minutes (mm), seconds (ss) and sub-seconds (##). If HH and MM are omitted, then the time period that is specified is assumed to be in seconds. Each instance of the /f parameter on the command-line defines a scan class for the interface. There is no limit to the number of scan classes that can be defined. The first occurrence of the /f parameter on the command-line defines the first scan class of the interface; the second occurrence defines the second scan class, and so on. PI Points are associated with a particular scan class via the Location4 PI Point attribute. For example, all PI Points that have Location4 set to 1 will receive input values at the frequency defined by the first scan class. Similarly, all points that have Location4 set to 2 will receive input values at the frequency specified by the second scan class, and so on. Two scan classes are defined in the following example: /f=00:01:00,00:00:05 /f=00:00:07 or, equivalently: /f=60,5 /f=7 The first scan class has a scanning frequency of 1 minute with an offset of 5 seconds, and the second scan class has a scanning frequency of 7 seconds. When an offset is specified, the scans occur at discrete moments in time according to the formula: scan times = (reference time) + n(frequency) + offset where n is an integer and the reference time is midnight on the day that the interface was started. In the above example, frequency is 60 seconds and offset is 5 seconds for the first scan class. This means that if the interface was started at 05:06:06, the first scan would be at 05:07:05, the second scan would be at 05:08:05, and so on. Since no offset is specified for the second scan class, the absolute scan times are undefined. The definition of a scan class does not guarantee that the associated points will be scanned at the given frequency. If the interface is under a large load, then some scans may occur late or be skipped entirely. See the section "Performance Summaries" in the PI Universal Interface (UniInt) User Guide for more information on skipped or missed scans. Sub-second Scan Classes Sub-second scan classes can be defined on the command-line, such as /f=0.5 /f=00:00:00.1 where the scanning frequency associated with the first scan class is 0.5 seconds and the scanning frequency associated with the second scan class is 0.1 of a second. Similarly, sub-second scan classes with sub-second offsets can be defined, such as /f=0.5,0.2 /f=1,0 Wall Clock Scheduling Scan classes that strictly adhere to wall clock scheduling are now possible. This feature is available for interfaces that run on Windows and/or UNIX. Previously, wall clock scheduling was possible, but not across daylight saving time. For example: /f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8 AM. However, after a Daylight Saving Time change, the scan would occur either at 7 AM or 9 AM, depending upon the direction of the time shift. To schedule a scan once a day at 8 AM (even across daylight saving time), use /f=24:00:00,00:08:00,L. The ,L at the end of the scan class tells UniInt to use the new wall clock scheduling algorithm.
/host=host:port Required	The /host parameter specifies the PI Data Archive node. Host is the IP address or the domain name of the PI Data Archive node. Port is the port number for TCP/IP communication. The port is always 5450. It is recommended to explicitly define the host and port on the command-line with the /host parameter. Nevertheless, if either the host or port is not specified, the interface will attempt to use defaults. Examples: The interface is running on an interface node, the domain name of the PI Data Archive node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host parameters would be: /host=marvin /host=marvin:5450 /host=206.79.198.30 /host=206.79.198.30:5450
/id=x Required	The /id parameter is used to specify the interface identifier. The interface identifier is a string that is no longer than 9 characters in length. UniInt concatenates this string to the header that is used to identify error messages as belonging to a particular interface. See the Error and informational messages for PI Interface for DNP3 for more information. UniInt always uses the /id parameter in the fashion described above. This interface also uses the /id parameter to identify a particular interface copy number that corresponds to an integer value that is assigned to one of the Location code point attributes, most frequently Location1. For this interface, use only numeric characters in the identifier. For example, /id=1
/IOPool=# Optional	Where # is the number of threads to be used for the IO completion port pool. If this parameter is not defined, the default is used. Default = 2 x Number of logical processors Minimum = 1 Maximum = 1024
/IOSleep=# Optional	Where # is the number of milliseconds to allow the IOCP threads to sleep between executions. By default, the IOCP routine does not sleep between executions. This parameter should not be altered unless the interface process appears to be utilizing a high percentage of the cpu. In this case, set the /IOSleep parameter to one and restart the interface. Default = 0 Minimum = 0 Maximum = 100
/IOTimeOut=# Optional	Specifies the length of time, in minutes, allowed to elapse without a good communication session with an RTU before the system digital state "IO TimeOut" will be written to all points belonging to the RTU. A value of 0 or the absence of the parameter in the start-up file means "IO TimeOut" will never be written to the PI points. A communications session is defined as receiving a good response to a request or receiving an unsolicited message from the RTU. The value # is in minutes and care must be taken when assigning this value. By default, the default check for an I/O timeout is not performed. If the I/O timeout value is less or roughly equal to the shortest scan class frequency and the Integrity Scan frequency, "IO TimeOut" may be written to the points shortly before every scan. Therefore, the value of # must be at least 1.5 times longer than the shortest scan class frequency or the Integrity Scan frequency whichever is shorter. Note: If the interface is configured to receive unsolicited responses from the RTU, "IO TimeOut" may be written to points if values on the RTU do not change frequently enough to send an unsolicited message to the interface. Therefore, consideration must be taken whether or not to perform integrity scans at periodic intervals when assigning a value to this parameter. Default = 0 Minimum = 0 (Timeout not written) Maximum = 1440 (1 day in minutes)
/NoDevStatLog Optional	When this parameter is defined, the interface does not log the list of RTUs that have no connection to the interface in the device status log. However, the number of RTUs in error will still be listed in the Device Status point. By default, the RTU(s) that are in error are logged to a device status log file for the interface. The maximum size of the log file is 100KB and once reached the file will then be cleared for new data.
/NoLogRTUParams Optional	When this parameter is defined, the interface does not log the startup parameters for RTUs assigned to the interface. This is useful to prevent the pipc.log file from becoming difficult to read when many RTUs are defined for a given instance of the interface. By default, the startup parameters for each RTU are listed in the pipc.log file.
/omf_clear	Clears the entries in the Windows Credential Manager for the corresponding service name and the Run-As account. To activate it, perform the following actions: Stop the interface. Add the /omf_clear command line option through the Additional Parameters input in ICU. Start the interface. Update the service-name.config file that is in the same directory as the interface executable, providing the desired username/password, or clientid/clientsecret, and restart the interface. Note: This parameter is only recognized when the interface is started as a service. After it finishes clearing the entries in the Windows Credential Manager, the interface service stops.
/PISDK= # Optional Default = 0	The /pisdk parameter can be used to enable or disable the PI SDK in some situations. Use /pisdk=1 to enable the PI SDK. Use /pisdk=0 to disable the PI SDK. If a particular interface requires the PI SDK, then the PI SDK will always be enabled and the /pisdk parameter will be ignored. Note: If the interface is running on an interface node with the PI API version 1.6.x or later and the version of the PI Data Archive is 3.4.370.x or later, the interface will ignore the /pisdk parameter and the SDK will not be used to retrieve point attributes .
/ps=x Required	The /ps parameter specifies the point source for the interface. X is not case sensitive and can be any <single/multiple> character string. For example, /ps=P and /ps=p are equivalent. The length of X is limited to 100 characters by UniInt. X can contain any character except '*' and '?'. The point source that is assigned with the /ps parameter corresponds to the PointSource attribute of individual PI Points. The interface will attempt to load only those PI points with the appropriate point source. If the PI API version being used is prior to 1.6.x or the PI Data Archive version is prior to 3.4.370.x, the PointSource is limited to a single character unless the SDK is being used.
/retry=# Optional Default: /retry=30	Specifies the interval (in seconds) that the interface will make subsequent attempts to connect to a specific RTU device. Example: /retry=20 Retry every 20 seconds
/RTULogSize=# Optional	Where # specifies the maximum size of the RTU log file before the file is cleared for new data. Size in kilobytes (KB). If the interface debug level as defined by the /dnpdbg does not specify logging to the RTU log file (level=0x0001), then the log file is not created by the interface. Default = 100 (100KB) Minimum = 10 (10KB) Maximum = 10000 (10MB)
/sio Optional	The /sio parameter stands for "suppress initial outputs." The parameter applies only for interfaces that support outputs. If the /sio parameter is not specified, the interface will behave in the following manner. When the interface is started, the interface determines the current Snapshot value of each output point. Next, the interface writes this value to each output point. In addition, whenever an individual output point is edited while the interface is running, the interface will write the current Snapshot value to the edited output point. This behavior is suppressed if the /sio parameter is specified on the command-line. That is, outputs will not be written when the interface starts or when an output point is edited. In other words, when the /sio parameter is specified, outputs will only be written when they are explicitly triggered.
/StatusInterval=# Optional	Where # specifies interface device status update interval in seconds. Consider the /retry rate as well as the time it takes to establish connections with configured devices in determining the /StatusInterval value. Use an interval that allows enough time to establish connection with enough devices to allow the /StatusPercentUp value to be reached. Note : When the interface is configured to use UniInt failover, the setting of the /StatusInterval to an interval that does not allow enough time to attempt a reconnection to a device in error could result in the interface setting the device status to an error condition prematurely and result in the backup copy of the interface assuming control. Default = 1 (1 second) Minimum = 1 (1 second) Maximum = 3600 (1 hour)
/StatusKeepState Optional	This parameter is only applicable when UniInt Interface Failover is being used. The /StatusKeepState parameter when defined prevents the backup copy of the interface from assuming the primary state at an interval specified by the location5 attribute of the ActiveID point when the value of both failover copies of the interface have equal device status values and neither interface is able to collect data while in the primary state. The interface does this by writing a value of 30 to the device status. The UniInt device status health point accepts values in the range of 0-100; whereby a value of 0 represents a good status value. Any value less than 50 prevents the backup copy of the interface instance from assuming control if the device status values of the failover instances are equal in error value. A value of 50 -70 allows the backup copy of the interface to assume control, at an interval specified by the location5 attribute of the ActiveID point, if the device status values of the failover instances are equal. Default = not defined
/StatusPercentUp=# Optional	Where # specifies the minimum percent of connected devices for reporting a good device status. All configurations: The interface will write a value of good to the UniInt device status health point if the percent of connected devices is equal to or greater than the /StatusPercentUp value. If the /StatusPercentUp=0, the interface will always report a status of good. UniInt failover: The interface will report a status value of 50 if the percent of connected devices is less than the /StatusPercentUp value. If the /StatusKeepState parameter is defined, the interface will report a status value of 30 if the percent of connected devices is less than the /StatusPercentUp value. The /StatusPercentUp=0 is useful during a UniInt failover configuration if the user wants the other interface to assume the role as primary only if the heartbeat of this copy of the interface fails to update (i.e. this copy is shutdown, crashes, or enters a locked state). Default = 100 (100%) Minimum = 0 (0%) Maximum = 100 (100%)
/StatusUpdateDelay=# Optional	Where # specifies the time in seconds before the interface will set the device status upon initial startup or upon assuming the role as primary if running in a UniInt failover configuration. Default = 0 (no delay) Minimum = 0 Maximum = 600 (10 minutes)
/stopstat=digstate or /stopstat /stopstat only is equivalent to /stopstat="Intf Shut" Optional Default = no digital state written at shutdown.	If /stopstat=digstate is present on the command line, then the digital state, digstate , will be written to each PI Point when the interface is stopped. For a PI Data Archive, digstate must be in the system digital state table. UniInt will use the first occurrence of digstate found in the table. If the /stopstat parameter is present on the startup command line, then the digital state " Intf Shut" will be written to each PI Point when the interface is stopped. If neither /stopstatnor /stopstat=digstateis specified on the command line, then no digital states will be written when the interface is shut down. Examples: /stopstat=shutdown /stopstat="Intf Shut" The entire digstate value should be enclosed within double quotes when there is a space in digstate .
/UFO_ID= # Required for UniInt Failover Phase 1 or 2	Failover ID. This value must be different from the Failover ID of the other interface in the failover pair. It can be any positive, non-zero integer.
/UFO_Interval= # Optional Default: 1000 for Phase 1 Failover Default: 5000 for Phase 2 Failover Valid values are 50‑20000.	Failover Update Interval Specifies the heartbeat Update Interval in milliseconds and must be the same on both interface computers. This is the rate at which UniInt updates the Failover Heartbeat points as well as how often UniInt checks on the status of the other copy of the interface.
/UFO_OtherID= # Required for UniInt Failover Phase 1 or 2	Other Failover ID. This value must be equal to the Failover ID configured for the other interface in the failover pair.
/UFO_Sync= path/[filename] Required for UniInt Failover Phase 2 synchronization. Any valid pathname / any valid filename The default filename is generated as executablename_pointsource_interfaceID.dat	The Failover File Synchronization file path and optional filename specify the path to the shared file used for failover synchronization and an optional filename used to specify a user defined filename in lieu of the default filename. The path to the shared file directory can be a fully qualified machine name and directory, a mapped drive letter, or a local path if the shared file is on one of the interface nodes. The path must be terminated by a slash ( / ) or backslash ( \ ) character. If no terminating slash is found, in the /UFO_Sync parameter, the interface interprets the final character string as an optional filename. The optional filename can be any valid filename. If the file does not exist, the first interface to start attempts to create the file. Note: If using the optional filename, do not supply a terminating slash or backslash character. If there are any spaces in the path or filename, the entire path and filename must be enclosed in quotes. Note: If you use the backslash and path separators and enclose the path in double quotes, the final backslash must be a double backslash ( \\ ). Otherwise the closing double quote becomes part of the parameter instead of a parameter separator. Each node in the failover configuration must specify the same path and filename and must have read, write, and file creation rights to the shared directory specified by the path parameter. The service that the interface runs against must specify a valid logon user account under the "Log On" tab for the service properties.
/UFO_Type= type Required for UniInt Failover Phase 2.	The Failover Type indicates which type of failover configuration the interface will run. The valid types for failover are HOT, WARM, and COLD configurations. If an interface does not support the requested type of failover, the interface will shut down and log an error to the log file stating the requested failover type is not supported.
/WorkerPool=# Optional	Where # is the number of threads to be used for the worker pool. If this parameter is not defined, no worker pool is created. Default = 0 Minimum = 0 Maximum = 1024
/xml=<UNCPath> Required	Specifies the name and path of the XML configuration file to be used by the interface. If there are spaces in the name or path, then the name and path must be enclosed in quotation marks. Example: /xml=C:\pipc\interfaces\pidnp3\PIDNP3.xml Example: /xml="C:\Program Files\interfaces\pidnp3\PIDNP3.xml"

Parameter

Description

/CacheMode

Required Default: Not Defined

Required for disconnected startup operation. If defined, the /CacheMode startup parameter indicates that the interface will be configured to utilize the disconnected startup feature.

/CachePath=path

Optional Default: Not Defined

Used to specify a directory in which to create the point caching files. The directory specified must already exist on the target machine. By default, the files are created in the same location as the interface executable. If the path contains any spaces, enclose the path in quotes. Examples:

/CachePath=D:\PIPC\Interfaces\CacheFiles

/CachePath=D:/PIPC/Interfaces/CacheFiles /

CachePath=D:/PIPC/Interfaces/CacheFiles/

Examples with space in path name:

/CachePath="D:\Program Files\PIPC\MyFiles"

/CachePath="D:/Program Files/PIPC/MyFiles"

/CachePath="D:/Program Files/PIPC/MyFiles/"

/CacheSynch=#

Optional Default: 250 ms

Care must be taken when modifying this parameter. This value must be less than the smallest scan class period defined with the /f parameter. If the value of the /CacheSynch parameter is greater than the scan class value, input scans will be missed while the point cache file is being synchronized.

The optional /CacheSynch=# startup parameter specifies the time slice period in milliseconds (ms) allocated by UniInt for synchronizing the interface point cache file with the PI Data Archive. By default, the interface will synchronize the point cache if running in the disconnected startup mode. UniInt allocates a maximum of # ms each pass through the control loop synchronizing the interface point cache until the file is completely synchronized.

Synchronization of the point cache file can be disabled by setting the value /CacheSynch=0 . The minimum synchronization period when cache synchronization is enabled is 50ms Whereas, the maximum synchronization period is 3000ms (3s). Period values of 1 to 49 will be changed by the interface to the minimum of 50ms and values greater than 3000 will be set to the maximum interval value of 3000ms.

Default: 250 ms

Range: {0, 50 - 3000} time in milliseconds

Example: /CacheSynch=50 (use a 50ms interval)

/CacheSynch=3000 (use a 3s interval)

/CacheSynch=0 (do not synchronize the cache)

/dnpdbg=level

Optional

Specifies the level of debugging messages to be written to the log files and to the console window if running interactively. The level is a 16-bit number that can be expressed as a hexadecimal number if preceded with a 0x. Each bit of the debug parameter turns on and off debugging in a different section of the interface. The following list shows example debug parameters and the section of code affected by that bit. For each bit, setting the bit to 1 will turn on that section's debugging messages and setting the bit to 0 will turn them off. To combine different parameters, add the value of the parameters together. For example, to send the raw DNP messages to both the RTU log file and to the console, and to log the Data Link, Transport, and Application Layer message explanations to the log file, set the parameter to /dnpdbg=0x001F . Basically, this turns on bits 1 through 5 starting from the right. For a more detailed explanation, See the DNP and other debugging messages section.

Examples

/dnpdbg=0x0001 Raw DNP messages written to the RTU log file

/dnpdbg=0x0002 Data Link Layer Descriptions to Log File

/dnpdbg=0x0004 Transport Layer Descriptions to Log File

/dnpdbg=0x0008 Application Layer Descriptions to Log File

/dnpdbg=0x0010 Raw DNP messages written to the Console

/dnpdbg=0x0020 Data Link Layer Descriptions to Console

/dnpdbg=0x0040 Transport Layer Descriptions to Console

/dnpdbg=0x0080 Application Layer Descriptions to Console

/dnpdbg=0x0100 Start-UP procedures

/dnpdbg=0x0200 Load PI point Procedures

/dnpdbg=0x0400 Data Sent to PI (not including Heartbeat points)

/dnpdbg=0x0800 Scanning for Current Values

/dnpdbg=0x1000 Communication Medium

/dnpdbg=0x2000 Value Scaling

/ec=#

Optional

The first instance of the /ec parameter on the command-line is used to specify a counter number, # , for an I/O Rate point. If the # is not specified, then the default event counter is 1. Also, if the /ec parameter is not specified at all, there is still a default event counter of 1 associated with the interface. If there is an I/O Rate point that is associated with an event counter of 1, each copy of the interface that is running without /ec=# explicitly defined will write to the same I/O Rate point. This means either explicitly defining an event counter other than 1 for each copy of the interface or not associating any I/O Rate points with event counter 1. For interfaces that run on Windows nodes, subsequent instances of the /ec parameter may be used by specific interfaces to keep track of various input or output operations. Subsequent instances of the /ec parameter can be of the form /ec*, where * is any ASCII character sequence. For example, /ecinput=10 , /ecoutput=11, and /ec=12 are legitimate choices for the second, third, and fourth event counter strings.

/event=ScanClass

Optional

Specifies a scan class as an event class which polls the RTU for all DNP3 class 1,2, and 3 events. All of the points assigned to this scan class will be treated as event type points. The ScanClass defines a scan class that corresponds to a /f= flag from the start-up file and the Location4 of the PI points.

Example: If this is found in the start-up file.

/f=10 /f=120 /f=00:10:00 /event=2

The interface will make a request for event data (class 1,2,3 data) every 2 minutes. All PI points with Location4 equal to 2 will be considered event type points and no requests for static data will be made for these points except during the integrity scan if configured.

/f=SS.##

/f=SS.##,SS.##

/f=HH:MM:SS.##

/f=HH:MM:SS.##, hh:mm:ss.##

Required for reading scan-based inputs

The /f parameter defines the time period between scans in terms of hours (HH), minutes (MM), seconds (SS) and sub-seconds (##). The scans can be scheduled to occur at discrete moments in time with an optional time offset specified in terms of hours (hh), minutes (mm), seconds (ss) and sub-seconds (##). If HH and MM are omitted, then the time period that is specified is assumed to be in seconds.

Each instance of the /f parameter on the command-line defines a scan class for the interface. There is no limit to the number of scan classes that can be defined. The first occurrence of the /f parameter on the command-line defines the first scan class of the interface; the second occurrence defines the second scan class, and so on. PI Points are associated with a particular scan class via the Location4 PI Point attribute. For example, all PI Points that have Location4 set to 1 will receive input values at the frequency defined by the first scan class. Similarly, all points that have Location4 set to 2 will receive input values at the frequency specified by the second scan class, and so on. Two scan classes are defined in the following example: /f=00:01:00,00:00:05 /f=00:00:07 or, equivalently: /f=60,5 /f=7

The first scan class has a scanning frequency of 1 minute with an offset of 5 seconds, and the second scan class has a scanning frequency of 7 seconds. When an offset is specified, the scans occur at discrete moments in time according to the formula:

scan times = (reference time) + n(frequency) + offset

where n is an integer and the reference time is midnight on the day that the interface was started. In the above example, frequency is 60 seconds and offset is 5 seconds for the first scan class. This means that if the interface was started at 05:06:06, the first scan would be at 05:07:05, the second scan would be at 05:08:05, and so on.

Since no offset is specified for the second scan class, the absolute scan times are undefined. The definition of a scan class does not guarantee that the associated points will be scanned at the given frequency. If the interface is under a large load, then some scans may occur late or be skipped entirely. See the section "Performance Summaries" in the PI Universal Interface (UniInt) User Guide for more information on skipped or missed scans.

Sub-second Scan Classes

Sub-second scan classes can be defined on the command-line, such as /f=0.5 /f=00:00:00.1 where the scanning frequency associated with the first scan class is 0.5 seconds and the scanning frequency associated with the second scan class is 0.1 of a second. Similarly, sub-second scan classes with sub-second offsets can be defined, such as /f=0.5,0.2 /f=1,0

Wall Clock Scheduling

Scan classes that strictly adhere to wall clock scheduling are now possible. This feature is available for interfaces that run on Windows and/or UNIX. Previously, wall clock scheduling was possible, but not across daylight saving time. For example: /f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8 AM. However, after a Daylight Saving Time change, the scan would occur either at 7 AM or 9 AM, depending upon the direction of the time shift. To schedule a scan once a day at 8 AM (even across daylight saving time), use /f=24:00:00,00:08:00,L. The ,L at the end of the scan class tells UniInt to use the new wall clock scheduling algorithm.

/host=host:port

Required

The /host parameter specifies the PI Data Archive node. Host is the IP address or the domain name of the PI Data Archive node. Port is the port number for TCP/IP communication. The port is always 5450. It is recommended to explicitly define the host and port on the command-line with the /host parameter. Nevertheless, if either the host or port is not specified, the interface will attempt to use defaults. Examples:

The interface is running on an interface node, the domain name of the PI Data Archive node is Marvin, and the IP address of Marvin is 206.79.198.30.

Valid /host parameters would be:

/host=marvin

/host=marvin:5450

/host=206.79.198.30

/host=206.79.198.30:5450

/id=x

Required

The /id parameter is used to specify the interface identifier.

The interface identifier is a string that is no longer than 9 characters in length.

UniInt concatenates this string to the header that is used to identify error messages as belonging to a particular interface. See the Error and informational messages for PI Interface for DNP3 for more information.

UniInt always uses the /id parameter in the fashion described above. This interface also uses the /id parameter to identify a particular interface copy number that corresponds to an integer value that is assigned to one of the Location code point attributes, most frequently Location1. For this interface, use only numeric characters in the identifier. For example, /id=1

/IOPool=#

Optional

Where # is the number of threads to be used for the IO completion port pool. If this parameter is not defined, the default is used.

Default = 2 x Number of logical processors

Minimum = 1

Maximum = 1024

/IOSleep=#

Optional

Where # is the number of milliseconds to allow the IOCP threads to sleep between executions. By default, the IOCP routine does not sleep between executions. This parameter should not be altered unless the interface process appears to be utilizing a high percentage of the cpu. In this case, set the /IOSleep parameter to one and restart the interface. Default = 0

Minimum = 0

Maximum = 100

/IOTimeOut=#

Optional

Specifies the length of time, in minutes, allowed to elapse without a good communication session with an RTU before the system digital state "IO TimeOut" will be written to all points belonging to the RTU. A value of 0 or the absence of the parameter in the start-up file means "IO TimeOut" will never be written to the PI points. A communications session is defined as receiving a good response to a request or receiving an unsolicited message from the RTU. The value # is in minutes and care must be taken when assigning this value. By default, the default check for an I/O timeout is not performed. If the I/O timeout value is less or roughly equal to the shortest scan class frequency and the Integrity Scan frequency, "IO TimeOut" may be written to the points shortly before every scan. Therefore, the value of # must be at least 1.5 times longer than the shortest scan class frequency or the Integrity Scan frequency whichever is shorter.

Note: If the interface is configured to receive unsolicited responses from the RTU, "IO TimeOut" may be written to points if values on the RTU do not change frequently enough to send an unsolicited message to the interface. Therefore, consideration must be taken whether or not to perform integrity scans at periodic intervals when assigning a value to this parameter.

Default = 0

Minimum = 0 (Timeout not written)

Maximum = 1440 (1 day in minutes)

/NoDevStatLog

Optional

When this parameter is defined, the interface does not log the list of RTUs that have no connection to the interface in the device status log. However, the number of RTUs in error will still be listed in the Device Status point. By default, the RTU(s) that are in error are logged to a device status log file for the interface. The maximum size of the log file is 100KB and once reached the file will then be cleared for new data.

/NoLogRTUParams

Optional

When this parameter is defined, the interface does not log the startup parameters for RTUs assigned to the interface. This is useful to prevent the pipc.log file from becoming difficult to read when many RTUs are defined for a given instance of the interface. By default, the startup parameters for each RTU are listed in the pipc.log file.

/omf_clear

Clears the entries in the Windows Credential Manager for the corresponding service name and the Run-As account. To activate it, perform the following actions:

Stop the interface.
Add the /omf_clear command line option through the Additional Parameters input in ICU.
Start the interface.
Update the service-name.config file that is in the same directory as the interface executable, providing the desired username/password, or clientid/clientsecret, and restart the interface.

Note: This parameter is only recognized when the interface is started as a service. After it finishes clearing the entries in the Windows Credential Manager, the interface service stops.

/PISDK= #

Optional

Default = 0

The /pisdk parameter can be used to enable or disable the PI SDK in some situations. Use /pisdk=1 to enable the PI SDK. Use /pisdk=0 to disable the PI SDK. If a particular interface requires the PI SDK, then the PI SDK will always be enabled and the /pisdk parameter will be ignored. Note: If the interface is running on an interface node with the PI API version 1.6.x or later and the version of the PI Data Archive is 3.4.370.x or later, the interface will ignore the /pisdk parameter and the SDK will not be used to retrieve point attributes .

/ps=x

Required

The /ps parameter specifies the point source for the interface. X is not case sensitive and can be any <single/multiple> character string. For example, /ps=P and /ps=p are equivalent. The length of X is limited to 100 characters by UniInt. X can contain any character except '*' and '?'. The point source that is assigned with the /ps parameter corresponds to the PointSource attribute of individual PI Points. The interface will attempt to load only those PI points with the appropriate point source. If the PI API version being used is prior to 1.6.x or the PI Data Archive version is prior to 3.4.370.x, the PointSource is limited to a single character unless the SDK is being used.

/retry=#

Optional Default:

/retry=30

Specifies the interval (in seconds) that the interface will make subsequent attempts to connect to a specific RTU device. Example: /retry=20 Retry every 20 seconds

/RTULogSize=#

Optional

Where # specifies the maximum size of the RTU log file before the file is cleared for new data. Size in kilobytes (KB). If the interface debug level as defined by the /dnpdbg does not specify logging to the RTU log file (level=0x0001), then the log file is not created by the interface. Default = 100 (100KB) Minimum = 10 (10KB) Maximum = 10000 (10MB)

/sio

Optional

The /sio parameter stands for "suppress initial outputs." The parameter applies only for interfaces that support outputs. If the /sio parameter is not specified, the interface will behave in the following manner. When the interface is started, the interface determines the current Snapshot value of each output point. Next, the interface writes this value to each output point. In addition, whenever an individual output point is edited while the interface is running, the interface will write the current Snapshot value to the edited output point. This behavior is suppressed if the /sio parameter is specified on the command-line. That is, outputs will not be written when the interface starts or when an output point is edited. In other words, when the /sio parameter is specified, outputs will only be written when they are explicitly triggered.

/StatusInterval=#

Optional

Where # specifies interface device status update interval in seconds. Consider the /retry rate as well as the time it takes to establish connections with configured devices in determining the /StatusInterval value. Use an interval that allows enough time to establish connection with enough devices to allow the /StatusPercentUp value to be reached. Note : When the interface is configured to use UniInt failover, the setting of the /StatusInterval to an interval that does not allow enough time to attempt a reconnection to a device in error could result in the interface setting the device status to an error condition prematurely and result in the backup copy of the interface assuming control. Default = 1 (1 second) Minimum = 1 (1 second) Maximum = 3600 (1 hour)

/StatusKeepState

Optional

This parameter is only applicable when UniInt Interface Failover is being used.

The /StatusKeepState parameter when defined prevents the backup copy of the interface from assuming the primary state at an interval specified by the location5 attribute of the ActiveID point when the value of both failover copies of the interface have equal device status values and neither interface is able to collect data while in the primary state. The interface does this by writing a value of 30 to the device status.

The UniInt device status health point accepts values in the range of 0-100; whereby a value of 0 represents a good status value. Any value less than 50 prevents the backup copy of the interface instance from assuming control if the device status values of the failover instances are equal in error value. A value of 50 -70 allows the backup copy of the interface to assume control, at an interval specified by the location5 attribute of the ActiveID point, if the device status values of the failover instances are equal.

Default = not defined

/StatusPercentUp=#

Optional

Where # specifies the minimum percent of connected devices for reporting a good device status.

All configurations:

The interface will write a value of good to the UniInt device status health point if the percent of connected devices is equal to or greater than the /StatusPercentUp value. If the /StatusPercentUp=0, the interface will always report a status of good.

UniInt failover:

The interface will report a status value of 50 if the percent of connected devices is less than the /StatusPercentUp value. If the /StatusKeepState parameter is defined, the interface will report a status value of 30 if the percent of connected devices is less than the /StatusPercentUp value.

The /StatusPercentUp=0 is useful during a UniInt failover configuration if the user wants the other interface to assume the role as primary only if the heartbeat of this copy of the interface fails to update (i.e. this copy is shutdown, crashes, or enters a locked state).

Default = 100 (100%)

Minimum = 0 (0%)

Maximum = 100 (100%)

/StatusUpdateDelay=#

Optional

Where # specifies the time in seconds before the interface will set the device status upon initial startup or upon assuming the role as primary if running in a UniInt failover configuration.

Default = 0 (no delay)

Minimum = 0

Maximum = 600 (10 minutes)

/stopstat=digstate

/stopstat

/stopstat only is equivalent to /stopstat="Intf Shut"

Optional

Default = no digital state written at shutdown.

If /stopstat=digstate is present on the command line, then the digital state, digstate , will be written to each PI Point when the interface is stopped. For a PI Data Archive, digstate must be in the system digital state table.

UniInt will use the first occurrence of digstate found in the table. If the /stopstat parameter is present on the startup command line, then the digital state " Intf Shut" will be written to each PI Point when the interface is stopped.

If neither /stopstatnor /stopstat=digstateis specified on the command line, then no digital states will be written when the interface is shut down.

Examples:

/stopstat=shutdown

/stopstat="Intf Shut"

The entire digstate value should be enclosed within double quotes when there is a space in digstate .

/UFO_ID= #

Required for UniInt Failover Phase 1 or 2

Failover ID. This value must be different from the Failover ID of the other interface in the failover pair. It can be any positive, non-zero integer.

/UFO_Interval= #

Optional

Default: 1000 for Phase 1 Failover

Default: 5000 for Phase 2 Failover

Valid values are 50‑20000.

Failover Update Interval

Specifies the heartbeat Update Interval in milliseconds and must be the same on both interface computers.

This is the rate at which UniInt updates the Failover Heartbeat points as well as how often UniInt checks on the status of the other copy of the interface.

/UFO_OtherID= #

Required for UniInt Failover Phase 1 or 2

Other Failover ID. This value must be equal to the Failover ID configured for the other interface in the failover pair.

/UFO_Sync= path/[filename]

Required for UniInt Failover Phase 2 synchronization.

Any valid pathname / any valid filename

The default filename is generated as executablename_pointsource_interfaceID.dat

The Failover File Synchronization file path and optional filename specify the path to the shared file used for failover synchronization and an optional filename used to specify a user defined filename in lieu of the default filename.

The path to the shared file directory can be a fully qualified machine name and directory, a mapped drive letter, or a local path if the shared file is on one of the interface nodes. The path must be terminated by a slash ( / ) or backslash ( \ ) character. If no terminating slash is found, in the /UFO_Sync parameter, the interface interprets the final character string as an optional filename.

The optional filename can be any valid filename. If the file does not exist, the first interface to start attempts to create the file. Note: If using the optional filename, do not supply a terminating slash or backslash character. If there are any spaces in the path or filename, the entire path and filename must be enclosed in quotes. Note: If you use the backslash and path separators and enclose the path in double quotes, the final backslash must be a double backslash ( \\ ).

Otherwise the closing double quote becomes part of the parameter instead of a parameter separator. Each node in the failover configuration must specify the same path and filename and must have read, write, and file creation rights to the shared directory specified by the path parameter. The service that the interface runs against must specify a valid logon user account under the "Log On" tab for the service properties.

/UFO_Type= type

Required for UniInt Failover Phase 2.

The Failover Type indicates which type of failover configuration the interface will run. The valid types for failover are HOT, WARM, and COLD configurations.

If an interface does not support the requested type of failover, the interface will shut down and log an error to the log file stating the requested failover type is not supported.

/WorkerPool=#

Optional

Where # is the number of threads to be used for the worker pool. If this parameter is not defined, no worker pool is created.

Default = 0

Minimum = 0

Maximum = 1024

/xml=<UNCPath>

Required

Specifies the name and path of the XML configuration file to be used by the interface. If there are spaces in the name or path, then the name and path must be enclosed in quotation marks.

Example: /xml=C:\pipc\interfaces\pidnp3\PIDNP3.xml

Example: /xml="C:\Program Files\interfaces\pidnp3\PIDNP3.xml"

PI Interface for DNP3

Command line parameters

Table of Contents

Command line parameters

Related Links