Before making any other
PI API calls, applications running on distributed nodes should connect with the PI Data Archive in order to properly initialize the connection. This is accomplished with the functions piut_connect or piut_setservernode. piut_connect attempts a connection with the default PI home node and is passed a process name.
If the connection is successful, the home node process name is set to the specified name. piut_setservernode attempts a connection with the specified node.
If the connection is successful, the process name is set either to a system generated name or to the name previously specified with piut_setprocname. A PINet version compatibility check is performed immediately after connection; if the versions are not compatible, the connection is aborted. The application identity set with the piut_setappidentity call is verified by the PI Data Arcive to ensure the application is licensed, and will abort the connection if the check fails.
For the PIAPI versions prior to PI API 2016 for Windows Integrated Security, the connection is checked against the PI Trusts configured on the PI Data Archive, and if a match is found, the connection uses the specified PI identities (users and groups). After the initial connection, the piut_login call could be to change the PI identity used for the connection. The calling program may wish to keep the login parameters for additional connections.
With PI API 2016 for Windows Integrated Security, the permissions are controlled with the PI Mappings configured on the PI Data Archive which map Windows logon or service accounts to the specified PI identities (users and groups).
Programs using PI Login services use pilg_login to both connect and determine the access level. See also PI Login Services for details.
After initial connection and login to the PI Server, the connection to the PI Server may change due to a communication/connection error. When this error is detected, the PI API has a 60 second timeout by default before another PI API connection message will be sent to the PI Server. Note that subsequent piut_setservernode calls only sets the server context. It does not check on the connection status. Instead, if needed, it is recommended that applications verify connection status by triggering a network call to the PI Server using a function such as pitm_servertime.
Finally, network information may be obtained for the local node, the current server node or a specified node by using the calls piut_netinfo, piut_netserverinfo, piut_netnodeinfo, respectively.