AspenTech IP.21

.NET AGENT

Item Type Support

SIGNALS

Overview

The IP.21 connector enables Seeq to access data from AspenTech IP.21 via AspenTech’s SQLplus query language.

Prerequisites

The Windows installation where the connector resides must have its regional format set to English (US).

Configuration

This is an example configuration template that is displayed in the Additional Configuration box that appears when you click Configure for an existing datasource (or if a new datasource is being created, in the Create new datasource connection modal that appears after clicking Add Datasource) on the Datasources administration page.

{
    "HostName": "localhost",
    "Port": 10014,
    "Username": null,
    "Password": null,
    "HistorianQualityFilter": null,
}

IP.21 Additional Configuration

Known Issues

There are no known issues for the IP.21 connector. Please report any issues you find to our support portal.

Troubleshooting

“Memory Full” Exceptions

“Memory Full” exception may occur either during indexing or during data requests, and the solution may differ depending on which operation triggers the exception.

For any “Memory Full” exception

Check the values of the SETCIMSQLMAX and SETCIMSQLMEM settings on each IP.21 server for any connections that are exhibiting this exception. A setting of 200,000,000 for both of these parameters has been observed to allow queries to succeed that had previously failed when the parameters were set to 25,000,000. You should contact AspenTech support for assistance setting these parameters for each IP21 server exhibiting the issue if you are not familiar with the settings.

“Memory Full” Exceptions During Indexing

During indexing, an adaptive algorithm adjusts the MAX_ROWS for SELECT queries to IP21 to try to maintain a 10-second response time for each request. On occasion, this causes the batch size to be too large for IP21 to process. In such a case, the MaxIndexingPageSize may be changed from null (meaning no hard limit) to a positive integer, so that the MAX_ROWS for the indexing queries will never exceed MaxIndexingPageSize . If not encountering “Memory Full” exceptions during indexing, this parameter should be left null.

“Memory Full” Exceptions Resulting From Data Requests

On occasion, very large queries can exceed the per-query memory allocation that the IP.21 server can support. In this case, you will see a Memory Full Exception error being raised both in the log/net-link/net-link.log file and in Seeq Workbench for a particular signal:

It is possible to limit the MAX_ROWS for data requests by specifying the Max Results per Request parameter. Please note that this parameter does not have any effect for the ado QueryMethod. See Performance Considerations below for an explanation of why it is preferred to avoid use of the ado query method when possible. Note that setting Max Results Per Request too low can cause excessive queries to the connector, so the highest value that avoids “Memory Full” exceptions should be preferred. A value in the 200000 to 500000 range is a good first choice, since the default set by the Seeq server configuration is ~1M.

Troubleshooting Other Issues

It is very helpful to have the AspenTech IP21 SQLplus utility installed on the machine that is hosting the Seeq agent making the connection to IP21 (in most cases, that’s the Remote Agent machine). This allows you to test the connection from the machine to the IP21 server and troubleshoot any queries that appear to be slow. You can see what queries the Seeq IP21 connector is using by viewing the logs for the NET Agent that is hosting the connection (see Getting Support for instructions on accessing the logs).

You can emulate the exact method that Seeq is using by invoking the sqlplusx utility on the Windows Command Prompt. Here’s an example – you’ll need to replace the hostname and query appropriately:

"C:\Program Files (x86)\AspenTech\InfoPlus.21\db21\code\sqlplusx.exe" /h=myip21server "SELECT PE_DESCRIPTION FROM IP_TagsBranch"

Note that you may need to launch the Windows Command Prompt as a particular Windows user account that has access to IP21.

If the sqlplusx utility is having trouble executing queries, then the Seeq IP21 Connector will likely also have similar problems.

After installing the AspenTech SQLplus utility, make sure to reboot the machine to ensure installation finishes successfully.

If you are running into other issues with connecting to or access data from IP.21, view our guide for troubleshooting datasource issues.

Performance considerations

By default, the IP.21 Connector uses the AspenTech Web Page ADO.NET interface library to retrieve data. The ADO.NET library's data transfer performance is significantly affected by network latency between the Seeq Server and IP.21 server(s). Any latency over 1ms may result in unacceptable data retrieval performance. A "ping" test from the Seeq Server to an IP.21 server will report the latency in milliseconds.

If you experience poor data retrieval performance, it is recommended that you take the following steps:

• Install AspenTech SQLplus wherever the Seeq IP.21 Connector is running (either on the Seeq Server itself or Remote Agents).

• In the AspenTech IP.21 Connector.json configuration file, change the QueryMethod parameter like so:

  CODE

  "QueryMethod": "sqlplusx"

When using the sqlplusx QueryMethod, you must use Windows Authentication (ActiveDirectory) as the authentication method. (Username and Password in the configuration file will be ignored.) In other words, you must configure the Windows Service account that is running Seeq with appropriate credentials that allow access to your IP.21 server.

Make sure TCP is allowed on port 10014 from the Remote Agent to the IP.21 server since this is the port and protocol SQLplus will use (It can be changed when you launch Aspen SQLplus, but it’s recommended to use the default port 10014).

Performance Issues with SQLPlus

If performance troubles persist after switching to querying with SQLPlus, it can be helpful to determine if the performance problem lies with Seeq or the IP.21 installation. On the machine that has the IP.21 connector enabled, find Seeq’s data directory and open the log/net-link/net-link.log file. Search for IP.21 and note any SQLplus queries that look to be particularly slow (e.g. returning only a few rows in several seconds). You can then copy the query statement that was slow into the clipboard, open the SQLplus client on the same machine, and execute it. If the query is still slow then the problem lies with IP.21 and can be investigated directly.

View our guide on optimizing datasource performance for general guidance.