Command line parameters

/BACKUPSERVER= OPC HDA Server

Optional

Default: none

Defines the OPC HDA server to be used as the backup server. Use the following format:

/BACKUPSERVER=FACT2NODE::MODBUSOPC_HDA

where FACT2NODE is the name of the computer where the OPC HDA Server runs, and MODBUSOPC_HDA is the name of the OPC HDA Server as registered on that machine. If the backup server runs on the same machine as the interface, omit the node name:

/BACKUPSERVER=MODBUSOPC_HDA

If the server name has embedded spaces, enclose the name in double quotes:

/BACKUPSERVER=”Server name with spaces”

/CS=tagname

Optional

Default: none

The string point where the interface should write the name of the currently active OPC HDA Server.

/DB=x

Optional

Default: none

Enables minimal debugging. Useful when you cannot tell what the server is returning. See the debugging parameters discussed in Configure the interface with PI ICU.

/DF=tagname

Optional

Default: none

Changes the value of the debug parameter while the interface is running. Configure an output point for the interface, Int32, and set its value to 0. Give the name of this point with the /DF parameter. For example:

/DF=OPCHDA.Debug.Parameter

When the value is changed in the PI point, the interface will capture the new value and set its debug parameter to that value. Nothing will be written to the OPC HDA Server.

/EA=#

Optional

Default: none

Adjusts the end time of the data call to the current time minus # number of seconds. This is used with the /GS (group size) parameter. Use this parameter to provide some overlap in the data call to ensure no data is missed if data goes into the OPCHDA Server after the interface made the read call.

If the /GS parameter is not passed in, the /EA parameter will have no effect.

/EC=#

Optional

Default: /EC=1

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, every interface that is running without /EC=# explicitly defined will write to the same I/O Rate point. Either explicitly define an event counter other than 1 for each instance of the interface or do not associate any I/O Rate points with event counter 1. Configuration of I/O Rate points is fully discussed in the PI Universal Interface (UniInt) Framework User Guide.

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.

/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 Hit, missed, and skipped scans in the PI Universal Interface (UniInt) User Guide for more information on skipped or missed scans.

Continuation

/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

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.

/FT=#

Optional

Default: /FT=10

Delay switching to backup server.

/FT specifies the total number of seconds during which the interface will attempt re-connection at 5 second intervals, before trying to switch to the backup OPC HDA Server.

For example: If /FT=120, then the interface will attempt to reconnect every 5 seconds for 2 minutes before trying to switch to the backup OPC HDA server.

GS=#

Optional

Default: /GS=1

The call to the OPCHDA server will be made in groups of # number of points. Within each scan class, the call to the OPCHDA server will be made in groups of # up to the number of points the scan class.

The start time of each data request will be done from the previous end time.

Without the /GS parameter, the calls to the OPCHDA server will be done one point at a time with the start time being the time stamp of the last value read from the OPCHDA server.

/HI=x

Optional

Default: /HI=2d

The maximum amount of time to go back in history at startup. For example: 1d for one day.

Default is 2d

/host=host:port

Required

The /host parameter specifies the Data Archive node.

Host is the IP address or the domain name of the Data Archive.

Port is the port number for TCP/IP communication. The port is always 5450. It is recommended that you 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 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

/HRONLY=start,end

Optional

Specify time-range-specific history recovery. Specify times using PI time string formats with a colon separating the date and the time:

/hronly=10-dec-98:10:00,10-dec-98:12:00

When configured for time-range-specific history recovery, the interface recovers data and then exits.

Note: UniInt failover cannot be configured when /HRONLY is used.

/HRPAUSE=#

Optional

Default:

/HRPAUSE=0

Milliseconds to pause between points during history recovery. Used to throttle archive data retrieval during history recovery.

/ID=x

Highly Recommended

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.

UniInt always uses the /id parameter in the fashion described above. This interface also uses the /id parameter to identify a particular interface instance 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

/IS

Optional

Tells the interface to ignore the server status returned by the OPC HDA Server. All servers should return OPCHDA_UP when they are ready to read values. Use this parameter if your OPCHDA server does not do this.

/IT

Optional

Tells the interface to discard the subsecond portion of the timestamps passed to Data Archive and only send whole integer seconds. Use for performance reasons. With this option, Data Archive will require less space, and possibly less CPU, to store the same amount of data. The interface simply truncates the fractional part of the second.

/MA

Optional

Default: none

Tells the interface to verify up to 500 items at the same time. This can speed up the startup time. By default, the interface will verify one item at a time.

/MP=#c

Optional

Default: none

The maximum amount of time to request data from the OPC HDA per call. Instead of asking for data from last value to current time, call data in chunks of time using the passed in max time period. (/MP=#c, where # is a number and c is a unit like “D: for days, “H” for hours, “M” for minutes, and “S” for seconds.

/NT

Optional

Default: none

Tells the interface to never write I/O Timeout, including when interface loses connection with the OPCHDA Server.

/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.

/PS=x

Required

The /ps parameter specifies the point source for the interface. X is not case sensitive and can be any unique single or 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 earlier than 1.6.x or the PI Data Archive version is earlier than 3.4.370.x, the PointSource is limited to a single character unless the SDK is being used.

/PW=password

Optional

Default: none

The password to use with OPC Private security. This is presumed to be case sensitive.

This parameter must be entered manually under the Additional Parameters tab of the ICU.

/Q

Optional

Tells the interface to queue snapshots and exceptions before sending to the Data Archive node.

The maximum queue size is close to 4000 bytes. The queue is flushed between scans if it is not filled.

/RP=#

Optional

Tells the interface to use the OPC HDA ReadProcessed call instead of the ReadRaw call.

The ReadProcessed call will return values at an interval based on the scan time of the point’s scan class. For example: If a point is in a scan class with a 10-second scan time, the ReadProcessed call will return values at a 10-second interval instead of all the values in the HDA server. This will reduce the traffic between the OPCHDA Server and the interface.

There are three ways to configure this parameter:

/rp=0 — The ReadProcessed call will be made with the OPCHDA_INTERPOLATIVE flag. This will cause the OPC HDA server to return interpolated values at the scan interval.

/rp=1 — The ReadProcessed will be made with the OPCHDA_START flag. This will cause the OPC HDA server to return the value and timestamp at the start time of the interval.

/rp=2 — The ReadProcessed will be made with the OPCHDA_END flag. This will cause the OPC HDA server to return the value and timestamp at the end time of interval

/SA=#

Optional

Default: none

Adjusts the start time of the data call to the previous end time minus # number of seconds. This is used with the /GS (group size) parameter. Use this parameter to provide some overlap in the data call to ensure no data is missed if data goes into the OPCHDA Server after the interface made the read call.

If the /GS parameter is not passed in, the /SA parameter will have no effect.

/SD=x

Optional

The number of seconds to wait after a connection to the OPC HDA Server and before scanning data. This is to allow time for the points on the OPC Server to load before scanning.

/SEC

/SEC=userid

Optional

Default: none

By itself, the parameter /SEC directs the interface to use the NT security option of the OPC Security standard. If the OPC Private security option is required, the userid must be given with this parameter and the password with the /PW parameter.

If the server does not support the specified security mode, or if the login fails, the interface will log the failure and attempt to reconnect.

The OPC Security settings should not be used unless the OPC server supports OPC Security, as doing so will result in no data collection.

This parameter must be entered manually under the Additional Parameters tab of the Interface Configuration Utility

/SERVER=OPCHDAServer

Required

Defines the OPC HDA Server to be used. Specify with the following format:

/SERVER=FACT1NODE::MODBUSOPC_HDA

where FACT1NODE is the name of the computer where the OPC HDA Server runs, and MODBUSOPC_HDA is the name of the OPC HDA Server as registered on that machine. If the server runs on the same machine as the interface, omit the node name:

/SERVER=MODBUSOPC_HDA

If the server name has embedded spaces, enclose the name in double quotes:

/SERVER=”Server name with spaces”

/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.

/STOPSTAT

or

/STOPSTAT=digstate

Default:

/STOPSTAT=“Intf Shut”

Optional

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 Data Archive, digstate must be in the system digital state table. The interface 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/stopstat nor /stopstat=digstate is specified on the command line, then no digital states will be written when the interface is shut down.

Note: The/stopstat parameter is disabled if the interface is running in a UniInt failover configuration as defined in the UniInt Failover Configuration chapter of this manual. Therefore, the digital state, digstate, will not be written to each PI point when the interface is stopped. This prevents the digital state being written to PI points while a redundant system is also writing data to the same PI points. The /stopstat parameter is disabled even if there is only one interface active in the failover configuration.

Examples:

• /stopstat=shutdown

• /stopstat="Intf Shut"

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

/SW=#

Optional

Default: none

The number of seconds to wait for RUNNING status, before switching to BACKUP OPCHDA Server.

/TF=format

Optional

Sets the format for timestamp strings written to the OPCHDA Server. The interface writes output timestamps using TIM= in the ExDesc field. See Sending Timestamp and Output Value to Different ItemIDs in the ExDesc (extended descriptor) section of this user guide for more information. Valid tokens are:

cc yy mn mon dd hh hr mm ss 000 XM

/TO=xx

Optional

Applies an adjustment to the time stamps (a times tamp offset), to deal with broken servers and broken installations, where the clock for the OPC HDA Server is set incorrectly (for example, the server requires the clock to match the wallclock, but the Timezone must be GMT, regardless of where the server is actually located). Do not use if the server is working properly. Specify the parameter in seconds; you may precede by a negative sign.

For example:

• Time adjusted ahead by 1 hour: /TO=3600

• Time adjusted back by 1 hour: /TO=-3600

• Time adjusted ahead by 30 minutes: /TO=1800

/TSU

Optional

If you need to use the time stamps received from the OPCHDA server without having them adjusted to the PI Data Archive clock, use:

/TSU

Note: This setting can cause your data to be lost, if your clocks are set incorrectly. Please see the section on Timestamps before using this setting.

/UHT_ID=#

Required if any type of failover other than UnInt Interface Level Failover Phase 1 or 2 is supported.

The value of this command-line parameter is used when creating UniInt health points for an interface that uses Non-UniInt interface failover. It is used for the Location3 point attribute for UniInt health points.

/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 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. 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 ICU control's 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 WARM and COLD configurations.

If an interface does not supported 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.