This function logs the user into a PI Server. A login is required to gain access to protected PI data.

Note: pilg_login() is NOT supported with PIAPI 2016 for Windows Integrated Security.

C format

PIINT32 pilg_login(

HWND hWndParent,

LPCSTR lpszUserName,

LPCSTR lpszServerName,

LPCSTR lpszPassword,

int32 PIPTR * valid)



System error




Connection to server failed


Specified server does not exist


Allocation of memory unsuccessful


The handle of the parent window is invalid


The login was canceled


Application is not registered


Login unsuccessful


No servers configured (pilogin.ini not found)


Invalid login


hWndParent (passed)

handle of the parent window,


user name - pointer to null terminated string,


server name - pointer to null terminated string,


password - pointer to null terminated string,


pointer to authorization parameter which specifies the access rights:

 0 - no access rights,

 1 - read access rights,

 2 - read/write access rights.

Usage Notes

If a NULL pointer is passed for the server name or the user name, the defaults will be used. If a valid string pointer is passed for the password, pilg_login will attempt to login once using that password and return the result. Otherwise, if the pointer for the password is NULL an attempt to login is made using the default password. The default password is a blank string on the first login and all subsequent server logins use the previous password. If the default password login fails and the window handle argument is not NULL, the login dialog is displayed for the user to provide the user and password for a final attempt. The final result is returned.

Passing NULL pointers in Visual Basic requires modification of the supplied function declaration and use of special keywords. See Passing a Null Pointer for a complete discussion.


Trust login is supported by entering the appropriate settings into the PILogin.INI file.

PI API 2016 for Windows Integrated Security

pilg_login() does not work with PI API 2016 as explicit logons are no longer supported. Instead of using pilg_login() and explicit logins to control the permissions associated with a connection to the PI Data Archive, PI API 2016 uses the Windows credentials of the PI API client application and its associated PI Mappings configured on the PI Data Archive.

If pilg_login() is called, the function will return success (0) but no changes will be made to the permissions for the PI Data Archive connection. The passed arguments lpszUserName and lpszPassword will not used.

Success (0) is returned for backward compatibility with existing applications that call pilg_login().

Enabling Operational Intelligence