UserLogin

Logs a user into the Plant SCADA system, using either Windows integrated security or Plant SCADA security and gives users access to the areas and privileges assigned to them in the Users database, and uses the locale language defined for that user. Only one user can be logged into a computer at any one time. If a user is already logged in when a second user logs in, the first user is replaced by the newly logged on user. When a newly logged in user does not have access to view the current page (as defined by the page's area), the system returns to the home page as specified by the parameter[Page]HomePage, and if unsuccessful that returns to the startup page. When multiple pages are currently displayed, this occurs for each open window.

To call this function at user login, the password argument passed needs to be in secure string format.

At startup, or when the user logs out, a default user is active, with access to area 0 (zero) and privilege 0 (zero) only. Use the LoginForm() function to display a form for logging in to the system.

This function is a blocking function. It blocks the calling Cicode task until the operation is complete.

Syntax

UserLogin(sUserName, sPassword, [sLanguage])

sUserName:

The user's name as defined in the Users database, or the Windows User account name, in plain text.

sPassword:

The user's password, as defined in the Users database or Windows account formatted as a secure string.

To improve the user credentials protection provides a system built-in user login function that takes the user name and secure password as the arguments. This reduces the chance that the user's password can be exposed in plaint text from the runtime system

sLanguage:

The specified language needs to be one of the languages defined in the Languages view in Plant SCADA Studio's Setup activity. If the specified language is undefined, the default language is used by the login user, and a message "Undefined language" is shown in the prompt line.

An empty string (i.e. "") can be specified to indicate that the default language is used by the login user. The default language defined by [Language]LocalLanguage INI parameter.

The default value of this parameter is "".

Return Value

0 (zero) if successful.

Related Functions

LoginForm, Logout, LogoutIdle, Message, Input

Example

/*

** FUNCTION NAME:LoginForm

**

** This function displays the login form, get the user name, password and

** the language of the user session and then trys to log the user in.

** If the login does not succeed it will retry until login is ok or user

** presses the cancel button.

**

*/

INT

FUNCTION

LoginForm(STRING sName="", STRING sPassword="", STRING sLanguage="English")

INT bDone;

INT nStatus;

INT hForm;

bDone = FALSE;

WHILE bDone = FALSE DO

FormNew("@(Login Form)", 35, 5, 5);

FormPrompt(1, 0, "@(Name)");

FormInput(16, 0, "", sName, 16);

FormPrompt(1, 2, "@(Password)");

FormSecurePassword(18, 2, "", sPassword, 16);

FormPrompt(1, 4, "@(Language)");

FormInput(16, 4, sLanguage, 16);

FormButton(6, 6, " " + "@(OK)" + " ", 0, 1);

FormButton(20, 6, "@(Cancel)", 0, 2);

IF FormRead(0) = 0 THEN

hForm = FormNew("@(User Login)", 36, 1, 8 + 16 + 128 + 256);

FormPrompt(1, 0, "@(Authentication in progress ...)");

FormRead(1);

SleepMs(200);

IF UserLogin(sName, sPassword, sLanguage) = 0 THEN

bDone = TRUE

nStatus = 0;

ELSE

sPassword = "";

END

IF FormActive(hForm) THEN

FormDestroy(hForm);

END

ELSE

bDone = TRUE;

nStatus = 298;

END

END

RETURN nStatus;

END

See Also

Security Functions