This function establishes a user's access to PI System data based on a login to a configured user database (PI User Database or VMS UAF) The login call may be made in one of two ways: by passing a NULL string for the username argument and a NULL string for the password argument, the server will return the default level of access, or by passing a username and password and attempting to qualify a valid login. Note that a null string is a valid pointer to an array of chars whose first element is set to 0. This requirement is distinctly different from pilg_login which accepts NULL pointers.
If piut_login is called after a valid login was performed, the request is ignored and the existing authorization level is returned in valid. See the Usage Notes for interpretation of the valid parameter.
Note: piut_login() is NOT supported with PIAPI 2016 for Windows Integrated Security.
char PIPTR * username,
char PIPTR * passwrd,
int32 PIPTR * valid );
Null terminated character string
Null terminated password string
Level of access available
Regarding the return values, if a return of -999 (Invalid Login) is obtained, the valid parameter will contain a system error status. If the return is zero (successful) the valid parameter will contain the authorization information.
The following defines are provided in piapi.h for evaluating the valid parameter:
#define PINO 0
#define PIREAD 1
#define PIREADWRITE 2
Logins will be checked against the PI user database on the platform of the server and proxy information if the user is not found (UNIX and NT). On VMS, the piserver.dat piserver authentication list and the VMS UAF are checked for valid logins. The database being tested against should be provided by the application to the user when logging in.
piut_login() does not work with PI API 2016 as explicit logons are no longer supported. Instead of using piut_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 piut_login() is called, the function will return success (0) but no changes will be made to the permissions for the PI Data Archive connection. Success is returned to retain backward compatibility with existing applications that call piut_login().