SetPassword

SetPassword is called on a client station to set a new password for a specified user in the project security system.

Syntax

SetPassword(optStrUserName,optStrNewPassword,optStrConfirmPassword,optStrCurrentPassword)

optStrUserName

The name of the user.

This parameter is optional; if no value is specified, a Set Password dialog box will be displayed on the client station so that the current user can select the name.

optStrNewPassword

The new password for the specified user.

This parameter is optional; if no value is specified, a Set Password dialog box will be displayed on the client station so that the current user can enter their new password.

optStrConfirmPassword

The new password again, to confirm that it has been entered correctly.

This parameter is optional; if no value is specified, a Set Password dialog box will be displayed on the client station so that the current user can enter their new password.

optStrCurrentPassword

The current password for the specified user, to authorize the change.

This parameter is optional; if no value is specified and the function has been called by the current user in order to set their own password, a Set Password dialog box will be displayed on the client station so that they can enter their current password.

The current password is not required at all if this function has been called by an administrative user in order to set the password of another user.

Return value

This function returns one of the following possible values:

Notes

Even though the function parameters are all optional, the information is still necessary, and a dialog will be opened to enter the information that is not provided. If you do not want the Set Password dialog to be displayed on the client station, provide valid arguments to all of the function parameters.

In order to successfully execute this function, the current user must have sufficient privileges to set passwords, regardless of whether they are setting their own password or another user's password. If they do not have sufficient privileges, this function returns a value of 10 as described in Return value above. For more information, see Creating and configuring groups.

If your project's security mode is set to Local Plus Domain (LDAP), changing passwords is subject to LDAP server criteria and detailed error messages will be included in the project's runtime log (the Output window). For more information about security modes, see About security modes. For more information about LDAP server criteria and error messages, see the documentation for your specific LDAP server.

You should avoid calling this function too frequently during project run time — for example, as part of a For loop that repeats in a matter of milliseconds. By default, the security settings are saved synchronously (that is, after each change is made), and too frequent saves can decrease runtime performance and/or cause the project development environment to freeze.

As a workaround, you can change the default behavior and configure your project to save the security settings asynchronously, at a specified interval. To do this, manually edit your project file (<project name>.app) to add the following settings:

[SecuritySystem]

EnableAsyncSavingForBuiltInFunctions=1

[Options]

SecuritySystemAutoSaveInterval=<in minutes, default is 5, minimum is 1>

Asynchronous saving applies to the following built-in functions:

• BlockUser

• CreateUser

• RemoveUser

• SetPassword

• SetUserGroup

• UnblockUser

If you enable asynchronous saving as described above and then call any of these functions to make changes to the security settings during project run time, those changes will be applied immediately but they might not be saved when the project is stopped.

In contrast, if you use the project development environment to make changes to the security settings during project run time, those changes are always saved synchronously regardless of whether asynchronous saving is enabled.

Examples

Display the Set Password dialog on the client, to get the information from the current user:

SetPassword()

Change the password for user "Admin", but display the dialog in order to get the new password and authorization:

SetPassword("Admin")

Change the password for user "admin" to the value of the tag newPassword, but display the dialog in order to get authorization:

SetPassword("Admin",newPassword,newPassword)

Change the password for user "admin" to the value of the tag newPassword, without displaying the dialog:

SetPassword("Admin",newPassword,newPassword,"DLfVU89Y")