5.2 Commands

5.2.1 AAVerify

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5 or later (arguments added in version 3.0)

Type

Action

Usage

AAVerify [-Method <Defined method to use>] [-User <Username>] [-Tree <Tree name>] [?Result]

Arguments

Method

The name of the advanced authentication method you wish to use. If not specified, AAVerify uses the method that was chosen during initial authentication to the directory.

NOTE:You can specify multiple methods.

User

The name of the user you wish to use for the AAVerify command. If not specified, AAVerify reauthenticates the currently logged on user.

Tree

The name of the tree the user is in. You must use this with the User argument.

[?Result]

A variable name (preferably a temporary variable) that receives the result of the AAVerify. Set this variable to true for success or false for failure.

?AAVerifyReturnCode

A variable that will get set with the error code that is generated from the AAVerify re-authentication process (if any).

Description

Use AAVerify with Novell SecureLogin re-authentication, Novell Modular Authentication Service (NMAS), or Novell Lightweight Directory Access Protocol (LDAP) to verify the user. It is typically used before the application user name and password are retrieved and entered into the login box.

This provides application re-authentication using a strong login method. For example, a user might be forced to enter their smart card and PIN before the application will log on using single sign-on, even though the application natively knows nothing about smartcards and PINs. If the verification succeeds, the [?Result] is set to true, otherwise it is set to false. These additions are for Novell SecureLogin and NMAS.

Novell SecureLogin re-authentication may use one of the following methods:

  • Password – your directory password.

  • Smart card – if the smart card option has been selected during installation.

  • Logon method – Novell SecureLogin prompts for the same credentials as were used to log on for the current session.

You can specify more than one method argument. In this case the user is allowed to re‑authenticate with any of the specified methods. For example, you could use the command to request authentication using a fingerprint reader or smart card.

NMAS or Novell LDAP-specific

The method should be the name of the sequence as defined in the Novell environment.

If AAVerify is called with no arguments, then the currently logged on user is re‑authenticated using the login method that they used for their current session.

NOTE:When the AAVerify command is added to an application definition, it only increases the security of the target application if it is not possible to alter the application definition. If the application definition could be modified or overridden, then the AAVerify command could be removed and there would be no additional security. For this reason it is imperative that application definition access be restricted through directory access controls and SecureLogin’s preferences, so that only a small, trusted group of administrators can modify, add and override application definitions.

Syntax examples

AAVerify

AAVerify -Method "Enhanced Password" ?Result

AAVerify -Method "Enhanced Password"-User "BSmith" - Tree "Production" ?Result

Example 1

Windows application definition

This example detects the login dialog box, but before Novell SecureLogin enters the user's credentials, it prompts the user to provide their re-authentication credentials. The credentials are not submited until the re-authentication has succeeded.

# Logon Dialog Box
Dialog
   Title "Log on"
EndDialog
AAVerify -Method "Enhanced Password" ?Result
If ?Result Eq "True"
   Type $Username #1001
   Click #1
Else
   Click #2
   MessageBox "Authentication failed. Please verify your smart card is inserted and your PIN is correct."
EndIf

Example 2

Windows application definition

The following example shows the use of exception handling with the OnExceptions command.

Refer to Section 5.2.55, OnException/ClearException for further details and examples of OnException usage.

Dialog
   Title "Log on"
EndDialog

OnException AAVerifyCancelled Call CancelSimpleLoginDialogCancelled
OnException AAVerifyFailed Call CancelSimpleLoginDialogFailed

AAVerify -method "smartcard"
Type $Username #1001
Click #1

Sub CancelSimpleLoginDialogCancelled
   Click #2
   EndScript
EndSub

Sub CancelSimpleLoginDialogFailed
   Click #2
   MessageBox "Your re-authentication failed. Log on cancelled"
   EndScript
EndSub

Example 3

Windows application definition

The following example shows how to re-authenticate against the user's login method.

Dialog
   Title "Log on"
EndDialog

OnException AAVerifyFailed Call AAVerifyFailed
OnException AAVerifyCancelled Call AAVerifyCancelled

If ?isPin Eq “true”
   AAVerify -method "smartcard" ?result
Else
   AAVerify -method "password" ?result
EndIf

ClearException AAVerifyFailed
ClearException AAVerifyCancelled

Type $username
Type \n
Type $password
Type \n

Sub AAVerifyFailed
   Click #2
   MessageBox "Re-authentication failed."
   EndScript
EndSub

Sub AAVerifyCancelled
   Click #2
   EndScript
EndSub

5.2.2 Add

Used with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.0 or later

Type

Variable manipulator

Usage

Add <Variable1> <Variable2> [?Result]

Arguments

<Variable1>

The first argument, the number to which the second argument will be added. This argument will also contain the result of the addition equation if the optional [?Result] argument is not passed in. If used without the [?Result] argument, <Variable1> must be a Novell SecureLogin variable. Otherwise, <Variable1> can be any numeric value.

<Variable2>

The second argument, the number added to the first argument in the equation. <Variable2> can be a Novell SecureLogin variable or numeric value.

[?Result]

Optional, the sum or result of the equation.

Description

Adds one number to another. The numbers can be written into the application definition or they can be variables. The result can be output to another variable or to one of the original numbers.

Syntax examples

Add 1 2 ?Result
Add ?LoginAttempts ?LoginFailures
Add ?LoginAttempts ?LoginFailures ?Result
Add ?LoginAttempts 3
Add ?LoginAttempts 3 ?Result

Example

Windows application definition

This example reads the values of control IDs 103 and 104 into variables. From there they are added, and the result is typed into control ID 1

ReadText #103 ?Number1
ReadText #104 ?Number2
Add ?Number1 ?Number2 ?Result
Type ?Result #1

5.2.3 Attribute

Use with

Advanced Web application definition

Novell SecureLogin version

3.5 or later

Type

Specifier

Usage

Attribute <Attribute Name> <Attribute Name>

Arguments

< Attribute Name>

Name of the HTML attribute to discover.

< Attribute Value>

The value the above HTML attribute must contain for the condition to be true.

Description

Use the Attribute specifier in conjunction with the Tag/EndTag command to specify which HTML attributes and attribute values must exist for that particular HTML tag.

For more information, see Section 5.2.89, Tag/EndTag.

Example

This example finds the form that has an attribute of Name with a value of Logon.

Tag "Form"   
Attribute "Name" "Logon"
EndTag

5.2.4 AuditEvent

Use with

Startup, Terminal Launcher, Java, Web, or Windows application definitions to send an audit event to the Windows Event Log.

Novell SecureLogin version

6.0 or later

Type

Specifier

Usage

AuditEvent [<message>]

Arguments

<message>

The variable or text string passed to the Windows Event Log.

NOTE:The functionality to send the contents of $variable or ?variable to the Windows Event Log is only supported in Novell SecureLogin 6.1SP1 or later

Description

Use AuditEvent to log Novell SecureLogin events to the Windows Event Log.

If the ChangePassword command is used to generate a $password variable, then a log entry is sent to the Windows Event Log.

Example

If the Audit platform agent is not present on the workstation nothing will be logged.

AuditEvent “message”

The parameter “message” is passed to the Windows Event Log.

AuditEvent $message

The parameter $message variable is passed to the Windows Event Log.

5.2.5 BeginSplashScreen/EndSplashScreen

Use with

Terminal Launcher (Generic and Advanced Generic only)

Novell SecureLogin version

3.0.4 or later

Type

Action

Usage

BeginSplashScreen

EndSplashScreen

Arguments

None

Description

Use to display Novell splash screen across the whole Terminal Emulator window. This is used to mask any flickering caused by Novell SecureLogin scraping the screen for text.

A Delay command at the start of the application definition ensures the emulator window is in place before the splash screen is displayed.

Example

Terminal Launcher application definition

This example launches the emulator and the Novell SecureLogin waits 2 seconds for it to connect. The splash screen is displayed to cover the flickering, the login field is detected, the user name is entered, then the splash screen disappears.

Delay 2000
BeginSplashScreen
WaitForText "Login:"
Type $Username
EndSplashScreen
Type @E

5.2.6 BooleanInput

Use with

Advanced application definitions created using the Web Wizard.

Novell SecureLogin version

3.5.x or later

Type

Action

Usage

BooleanInput #FormID:FieldID check "check"

Arguments

#FormID:FieldID

The ID that was given to the matched field in the Site block using MatchField command. The FormID and FieldID must be unsigned integers.

check "check"

"check" is a Boolean value indicating a set or unset state for the specified field.

Description

Used inside a Site block to set the state of a Boolean field (either a check box or radio button).

Example

In this example the value of field #1:3 is being checked by the application definition.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site Login -userid “Google Logon” -initial
MatchDoimain “www.google.com”
MatchField #1:1 -name “Email” -type “text”
MatchField #1:2 -name “Passwd” -type “password”
MatchField #1:3 -name “Cookie” -type “check”
EndSite
SetPrompt “Enter your user credentials”
TextInput #1:1 -value “$Username”
TextInput #1:2 -value “$Password”
FocusInput#1:2 -focus “true”
BooleanInput #1:3 -check “false”
PressInput
Endscript

5.2.7 Break

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5 or later

Type

Action

Usage

Break

Arguments

None

Description

Use Break within the Repeat/EndRepeat commands to break out of a repeat loop.

Example 1

Windows application definition

This example reads the screen and the content is searched for the words ‘log on’. If log on is found, the Repeat loop is broken and the application definition continues. If log on is not found, the application definition will check again.

Dialog   
   Class #32770   
   Title "Log on"
EndDialog
Repeat   
   ReadText  #301 "?Text"   
   If ?Text Eq "Log on" 
   Break   
   EndIf
Delay 100
EndRepeat

Example 2

Terminal application definition

This example reads the terminal emulator screen and the content is searched for a successful log on (in this case the application main menu appears). Once the user has logged on, the Repeat loop is broken and the application definition continues. If the log on is not successful, the application definition will check again. Terminal emulators use repeat loops for error handling and to break out of the loop as appropriate.

# Initial System Login
WaitForText "ogin:"
Type $Username
Type @E
WaitForText "assword:
"Type $Password
Type @E
Delay 500
# Repeat loop for error handling
Repeat
Check to see if password has expired
If -Text "EMS: The password has expired."      
   ChangePassword $Password      
   Type $Password      
   Type @E      
   Type $Password      
   Type @E   
EndIf
#User has an invalid Username and / or Password stored. 
   If -Text "Log on Failed"      DisplayVariables "The username and / or password stored by SecureLogin is invalid. Please verify your credentials and try again. IT x453."
   Type $Username
   Type @E
   Delay 500
   WaitForText "assword:"
   Type $Password 
   Type @E 
   Delay 500   
   EndIf# 

Account is locked for some reason, possibly inactive.   
If -Text "Account Locked" MessageBox "Your account has been locked, possibly due to inactivity for 40 days. Please contact the administrator on x453." EndIf # Main Menu, user has logged on #successfully. If -Text "Application Selection" Break   
EndIf
Delay100
EndRepeat

5.2.8 Call

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5 or later

Type

Flow control

Usage

Call <SubRoutine>

Arguments

<SubRoutine>

The name of the subroutine called. This must be identical to the name given in the Sub command.

Description

Use the Call command to call and run a subroutine. When a subroutine is called, the application definition begins executing from the first line of the subroutine. When it is completed, the application definition resumes executing from the command immediately following the Call command.

Subroutines are useful when you would otherwise have to repeat the same lines of application definition over again.

Example

Terminal application definition

This example looks for the word Username, if it is found on the screen the subroutine Log on is launched. If Wrong Password is found, the subroutine WrongPassword is launched.

Repeat   
If -Text "Username"      
   Call "Login"   
EndIf   
If -Text "Wrong Password"      
   Call "WrongPassword"   
EndIf
EndRepeat 
#==Login Subroutine==
Sub Login   
   Type $Username
   Type @E 
   Type $Password
   Type @E
EndSub
#==Wrong Password Subroutine==
Sub WrongPassword
   DisplayVariables "The password entered is incorrect. Please check your password and click OK to try again. IT x4532." 
   $Password  
   Call Login
EndSub

5.2.9 ChangePassword

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5 or later

Type

Action

Usage

ChangePassword <Variable> [<Text>] "Random"

Arguments

<Variable>

A normal or runtime variable in which the password is stored.

[Text]

The text you want displayed in the change password dialog box.

[Random]

Random will invoke the random password generator.

Description

Use ChangePassword to change a single variable in scenarios where password expiry is an issue. Set the <Variable> to the new password.

The flag for this command is Random.

If Random is:

  • Set, the new password is generated automatically in compliance with the variable's password policy.

  • Not set, a dialog box prompts the user to enter a new password. The new password is tried against any variable password policies that are in place. See also Section 5.2.65, RestrictVariable.

Syntax examples

ChangePassword $NewPassword
ChangePassword ?NewPassword "Please enter a new password"
ChangePassword ?NewPassword Random

Example

Windows application definition

This example detects the change password event. The application requires the current user name and password, and then a new password and confirmation of the new password. The application definition creates a backup of the old password in case the password change fails (which is detected by the message that is displayed), and then generates and enters a new password.

# Change Password Dialog
BoxDialog  
Class #32770   
Title "Change Password"
EndDialog
Set $PasswordBackup $Password
Type $Password #1015
ChangePassword $Password Random
Type $Password #1005
Type $Password #1006
Click #1# 
Change Password Failed Dialog Box
Dialog   
Class #32770   
Title "Change Password Failed"
EndDialog
# Set the password back as the password change failed 
$Password $PasswordBackup
MessageBox "The change password process failed. Please retry the password change at your next log on. IT x453."

5.2.10 Class

Use with

Startup, Windows

Novell SecureLogin version

3.5 or later

Type

Dialog specifier

Usage

Class <Window-Class>

Arguments

<Window-Class>

A string specifying the window class that this statement will match.

Description

When a window is created, it is based on a template known as a window class. The Class command checks to see if the class of the newly created window matches its <Window-Class> argument.

If the window:

  • Matches the <Window-Class> argument, the application definition continues to the next line.

  • Does not match the <Window-Class> argument, execution continues at the next dialog statement.

NOTE:Use the Novell Window Finder tool to determine the window class.

Example

Windows application definition

This example checks the dialog box generated by the application to determine if the Window Class is #32770. If true and its title is log on, that section of the application definition will execute. If false, the application definition will check the next Dialog block.

# Logon Dialog Box
Dialog   
Class "#32770"    
Title "Log on"
EndDialog
Type $Username #1001
Type $Password #1002
Click #1

5.2.11 ClearPlat

For each dialog block in an application definition, the chosen user ID is reset and you must select it again. Select it again by using a SetPlat command or by having the user select again from a list.

When an application first presents a login screen, Novell SecureLogin directs the user to select an appropriate user ID from a list. Novell SecureLogin enters the selected user ID's credentials into the application and submits them.

Resolving issue of re-entering user ID details

If the login fails due to incorrect credentials, Novell SecureLogin prompts the user to change the credentials. Novell SecureLogin does not retain user ID details and prompts the user to re-enter them. However, this could result in changing the wrong credentials if the user selects the incorrect user ID.

To resolve this issue, use the SetPlat, ReLoadPlat and ClearPlat commands. ReloadPlat sets the current user ID to the one which was last chosen (for the given application) or leaves the user ID unset if a user ID has not been selected previously. ClearPlat resets the last chosen user ID.

See also Section 5.2.63, ReLoadPlat and Section 5.2.77, SetPlat.

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.6.0 or later

Type

Action

Usage

There are three main places where code needs to be added to use the ClearPlat command:

Application startup When an application first starts up, use ClearPlat to clear the previously chosen platform. (Do this in a Windows application by adding an extra dialog statement for the main window.)

Change Credentials Canceled Call ClearPlat if the user decides not to modify the chosen platform's credentials, thus giving them a chance to choose a different platform next time.

Successful Logon Call ClearPlat to allow the user to log on again with a different platform at a later stage.

Arguments

None

Description

Use to reset the last chosen platform, causing subsequent calls to ReLoadPlat to do nothing.

Example

Windows application definition

#== BeginSection: Application startup ====
Dialog 
Class "#32770" 
Title "Password Test Application"
EndDialog
ClearPlat
# == EndSection: Application startup====
# ==== BeginSection: Log on ====
Dialog 
Class "#32770" 
Ctrl #1001 
Title "Log on"
EndDialog
ReLoadPlat
SetPrompt "Username =====>"
Type $Username #1001
SetPrompt "Password =====>"
Type $Password #1002
SetPrompt "Domain =====>
"Type $Domain #1003
Click #1
# ==== EndSection: Log on ====

## ====BeginSection: Log on successful ====
Dialog 
Class "#32770" 
Title "Log on successful"
EndDialog
ClearPlat

Example (continued)

Click #2
# ==== EndSection: Log on successful ====

# ==== BeginSection: Log on failure ====
Dialog 
Class "#32770" 
Title "Log on failure"
EndDialog
Click #2
ReLoadPlat
OnException ChangePasswordCancelled Call 
ChangeCancelled 
ChangePassword $password
ClearException ChangePasswordCancelled 
Type -raw \Alt+F
Type -raw L
# ==== EndSection: Log on Failure ====
# ==== BeginSection: Change Credentials Cancelled ====
Sub ChangeCancelled 
ClearPlat 
EndScript
EndSub
# ==== EndSection: Change Credentials 
Canceled ===

5.2.12 ClearSite

Use with

Web Wizard

Novell SecureLogin version

6.0 or later

Type

Action

Usage

ClearSite "SiteName"

Arguments

"SiteName"

The name of the site to clear, as specified in the matching Site/EndSite block that will be reset to initial.

Description

Used to clear the 'matched' status for a given site. This allows initial sites to match again and causes recent and subsequent sites to fail to match.

The ClearSite command needs to have the complete URL specified in the line before the ClearSite command.

Examples

In this example? the user is redirected to the Google home page and any previous user information is cleared.

GotoURL “http://www.google.com”
ClearSite Login

In this example, the ClearSite command is used with as part of conditional statement and if a particular condition is true the user information is cleared.

Site “Login” –subsequent

MatchURL “here.now.com”

endsite

MessageBox "Would you like to login again?" -yesno ?Continue

If ?Continue eq "Yes"

  Call LoginSub

Else

  ClearSite Login

EndIf

5.2.13 Click

Use with

Java, Web, or Windows

Novell SecureLogin version

3.5 or later

Type

Action

Windows usage

Usage One: Click <#Ctrl-ID> [-Raw] [-Right] Usage Two: Click <# Ctrl-ID > [-Raw [-x < X Co-ordinate > -y <Y Co-ordinate >]] Usage Three: Click [-order] <#Order-ID>

Web usage

Click <#Number>

Arguments

<#Ctrl-ID>

The ID number of the control to be pressed.

[-order]

If the control ID's are not constant, utilize the -order argument to instruct Novell SecureLogin to type into a control based on the creation order and not the tab order. For more information on the -order argument usage, see Example 4.

<#Order-ID>

For Windows application definitions, this parameter specifies which control based on the creation order in which to type the text.

[-Raw]

-Raw eliminates the mouse and sends a direct click.

[-Right]

-Right, used only with the -Raw flag, will send a right mouse click.

<X Co-ordinate>

X represents the horizontal co-ordinate relative to the client area of the application (not the screen).

<Y Co-ordinate>

Y represents the vertical coordinate relative to the client area of the application (not the screen).

<#Number>

The pound/hash symbol followed by the sequential number/control ID of the button to be pressed.

Web specific

The number of the button is determined by the Web page layout. See the Section 5.2.22, DumpPage.

Windows specific

This is the control ID. Use the Windows Finder tool to discover the control ID.

Java specific

The index to use is put in an example application definition created by the Java wizard.

Description

When used with Windows applications, the Click command sends a click instruction to the specified <#Ctrl-ID>.

NOTE:If the button to be clicked does not have a control ID, the Type "\N" command will often click the default button in a Windows application.

You can set the –Raw flag if the button or control does not respond to the Click command. The –Raw flag causes Novell SecureLogin to emulate the mouse and send a direct click message to the control. Using the -Right flag with the -Raw flag sends a right-click to the control.

Setting the <#Ctrl-ID> to 0 (zero) sends the click instruction to the window on which the application definition is running.

If -Raw is specified, then you can set the X coordinate and the Y coordinates. These coordinates are relative to the client area of the application, not the screen.

NOTE:The borders of Windows Vista windows are substantially wider than those of Windows XP windows. Consequently, if your application definition will be used on both operating systems, you should use coordinates towards the top left of a Vista button or the bottom right of an XP button to ensure the same button is clicked in both operating systems.

When used with Web application definitions, the Click command takes a single argument, which is the sequential number on the page of the button to be pressed. Click #3 will click the third button on the page. Keep in mind that, due to Web page layout and design, the sequential order of the buttons may not be obvious, and that you may have to use the DumpPage command to discover the field layout (see Section 5.2.22, DumpPage).

Syntax examples

Click #1
Click #1 -Raw -Right
Click -X 12 -Y 24
Click -order #1

Example 1

Windows application definition

This example detects the login dialog box, the user name and password are entered, and button number 1 (in this case the logon button) is clicked.

# Logon Dialog Box
Dialog   
Class #32770  
Title "Log on"
EndDialog
Type $Username #1001
Type $Password #1002
Click #1

Example 2

Web application definition

This example enters the user name and password, and then the logon button is clicked.

Type $Username
Type $Password Password
Click #1

Example 3

Windows application definition

This example uses the Java application, so there is no control ID. Instead, the Click command is told to click a particular place on the window.

# Logon Dialog Box
Dialog   
Class #32770
Title "Log on"
End Dialog
Type $Username
Type $Password
Click -X 12 -Y 24

Example 4

Windows application definition

This example shows the use of the -order switch and demonstrates a possible ‘order’ of the parameter.

# Logon Dialog Box
Dialog
Class #32770
Title “Log on”
EndDialog
Type $Username #1001
Type #Password #1002
Click -order #1

5.2.14 ConvertTime

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.0.4 or later

Type

Variable manipulator

Usage

ConvertTime <Time> <String Time>

Arguments

<String Time>

The output variable.

Description

Use to convert a numeric time value, for example, ?CurrTime(system), into a legible format and store it in <String Time>.

Example

Windows application definition

This example converts the time to a readable format and displays it in a dialog box.

# Logon Dialog Box
Dialog
Class #32770
Title "Log on"
End Dialog
ConvertTime ?CurrTime(system) ?Time
MessageBox ?Time

5.2.15 Ctrl

Use with

Startup, Windows, Java

Novell SecureLogin version

3.5 or later

Type

Dialog specifier

Usage

Ctrl <#Ctrl-ID> [<Regular Expression>]

Arguments

<#Ctrl-ID>

The ID number of the control to check.

[<RegEx>]

The regular expression.

Description

Use the Ctrl command to determine if a window or its children (any descendants) contains the control expressed in the <#Ctrl‑ID> argument. The control ID number is a constant that is established at the time a program is compiled.

Third party software control ID numbers may not be consistent from one version to the next. Use the Novell Window Finder tool to determine the control ID.

Using the [<RegEx>] argument adds a further check that allows the application definition to skip to the next command. If the text on the specified <#Ctrl-ID> does not conform to the [<RegEx>], the application definition will skip to the next dialog statement as though the <#Ctrl-ID> did not exist.

Syntax examples

Ctrl #1
Ctrl #1 "OK"

Example

Windows application definition

This example tests the dialog box to see if it contains the correct control IDs with the correct values. If any of the control IDs are missing, or the text does not match, the application definition passes on to the next dialog block.

# Logon Dialog Box
Dialog   
Ctrl #1 "OK"   
Ctrl #2 "Cancel"   
Ctrl #3 "Help"    
Title "Log on"
EndDialog

Type $Username 
Type "\T"
Click #1

5.2.16 DebugPrint

Use with

All

Novell SecureLogin version

6.0 or later

Type

Action

Usage

DebugPrint <Data>

Arguments

<Data>

The text displayed to the user.

Data can be several strings, variables, or a combination of both..

Description

Use the DebugPrint command to display the text specified in the <Data> variable on a Debug console. The command can take any number of text arguments, including variables (for example, DebugPrint "The user " $Username " has just logged onto the system").

Syntax examples

DebugPrint "Caught the login dialog”
DebugPrint "Setting platform to " ?Platform

Example

Windows application definition

This example displays the the text specified in the ?ServerName variable on the Debug console.

# Logon Dialog
Dialog
Class "#32770"
Title "Log on"
EndDialog
ReadText #1003 ?ServerText
RegSplit "Server: (.*)" ?ServerText ?ServerName
DebugPrint "Setting the platform to " ?ServerName
SetPlat ?ServerName
Type $Username #1001
Type $Password #1002
Click #1

5.2.17 Decrement

Use with

All

Novell SecureLogin version

3.5 or later

Type

Variable manipulator

Usage

Decrement <Variable>

Arguments

<Variable>

The name of the variable to decrease in value.

Description

Use the Decrement command to from a specified variable. For example, you can use decrement to count the number of passes a particular application definition has made.

Once the number of instances is equal to the specified number, you can instruct the application definition to run another task or end the application definition. This is useful when configuring an application whose login panel is similar to other windows within the application, or to easily control the number of attempts a user can have to access an application.

Also see Section 5.2.42, Increment

Syntax examples

Decrement ?RunCount

Example

Windows application definition

Each time the application definition is run, a variable is incremented. This example counts the number of times the dialog box is dis-played. If the dialog box is displayed more than three times, the application is closed. If the login is successful, the count is reset.

# Logon Dialog Box
Dialog
Class #32770
Title “Log on”
EndDialog

Decrement ?RunCount
If ?RunCount Gt “3”
MessageBox “Log on has been attempted too many times.  The application will be closed.”
KillApp “app.exe”
Else
Type $Username #1001
Type $Password #1002
Click #1
EndIf

# Logon Successful Message
Dialog
Ctrl #1
Title “Logon Successful”
EndDialog

Set ?RunCount “0”

5.2.18 Delay

Use with

All

Novell SecureLogin version

3.5 or later

Type

Action

Usage

Delay <Time Period>

Arguments

<Time Period>

A period of time, expressed in milliseconds (1/1000 of a second), during which application definition execution is paused.

Description

Use the Delay command to delay the execution of the application definition for the time specified in the <Time Period> argument.

The time specified in the <Time Period> argument is noted in milliseconds (for example, Delay 5000 creates a 5-second pause). You can use the Delay command to accommodate an introduction screen or another custom feature.

Example

Windows application definition

This example detects the login box, then the application definition waits half a second before acting upon it to make sure that the box is complete.

# Logon Dialog Box
Dialog   
Class #32770   
Title "Log on"
EndDialog

Delay 500
Type $Username #1001
Type $Password #1002
Click #1

5.2.19 Dialog/EndDialog

Use with

Java, Windows

Novell SecureLogin version

3.5 or later

Type

Dialog specifier

Usage

Dialog/EndDialog

Arguments

None

Description

Use the Dialog/EndDialog command to identify the beginning and end of a dialog specification block respectively. You can use these commands to construct a dialog specification block, which consists of a series of dialog specification statements (for example Ctrl, Title, and so on).

When a dialog block is executed, each of the dialog specification statements is executed in sequence. If any statement within the dialog block is not found, the entire dialog block is considered false, and the application definition execution proceeds to the next dialog block, if any. You need to specify as much information in the dialog block to make the dialog box (for example, Log on, Change Password, and so on) unique.

The portion of the application definition that follows the EndDialog command is called the application definition body. Another dialog block, or the end of the application definition, terminates the application definition body.

Example

Windows application definition

This example tests the dialog box in order to determine its identity. If it is determined to be the login box, the application definition will parse the Type and Click commands to complete the login process.

# Logon Dialog Box
Dialog 
Ctrl #1 "OK"    
Title "Log on"   
Parent      
Title "Application 1"   
EndParent
EndDialog

Type $Username #1001
Type $Password #1002

Click #1

5.2.20 DisplayVariables

Use with

All

Novell SecureLogin version

3.5 or later

Type

Action

Usage

DisplayVariables [<User Prompt>] [<Variable> [<Variable>] …]

Arguments

[<User Prompt>]

Optional, customized text displayed in the Enter Novell SecureLogin Variables dialog box. This message can be defined in a runtime variable (see example 2).

[<Variables>]

The name of the variables for which you want the user prompted. If not specified, Novell SecureLogin will prompt for all variables that are used by the application definition.

Description

Use the DisplayVariables command to display a dialog box that lists the user's stored variables (for example, $Username and $Password) for the current application.

About editing variables The user can edit the variables from this dialog box. For example, if the login process is unsuccessful due to an incorrect user name or password, the DisplayVariables command prompts the user to edit the stored user name or password values. The login process proceeds as normal from that point. You can also specify a particular variable to display.

If the <Variables> parameter is specified, DisplayVariables prompts only for the variables specified. Enter the replacement text in quotation marks after the DisplayVariables command. This replaces the default prompt text in the Enter Novell SecureLogin Variables dialog box.

If there are no variables stored for the user, the first time Novell SecureLogin attempts to single sign-on to the application, the prompt will not be customized.

Once there are variables stored for the user, the prompt will be customized when the application definition is run.The SetPrompt command can also be used to customize the prompt text in the dialog box.

NOTE:You can use the OnException EnterVariablesCancelled command to prevent a user from canceling the DisplayVariables prompt.

Syntax examples

DisplayVariables
DisplayVariables "Please enter your details"
DisplayVariables "Please enter a new password" $Password
DisplayVariables "Please enter your username and password" $Username $Password
DisplayVariables "" $Username $Password

Example 1

Windows application definition

This example detects the Wrong Password dialog box, and Novell SecureLogin prompts the user to enter a new user name and password. Once specified, Novell SecureLogin enters them into the dialog box, and the user clicks OK.

# Wrong Password 
Dialog Box
Dialog 
Class #32770   
Title "Wrong Password"
EndDialog
DisplayVariables "Enter a new username and password"?$Username $Password
Type $Username #1001
Type $Password #1002
Click #1

Example 2

Windows application definition

This examples passes the message in as a variable.

Dialog
Class "Notepad"
Title "Untitled - Notepad"
EndDialog
Set ?Vars "\$Username"
Set ?Msg "This is a DisplayVariables message"
DisplayVariables ?Vars
DisplayVariables ?Msg $Password
DisplayVariables "testing" ?Vars
DisplayVariables "testing" $Password $Username

5.2.21 Divide

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.0 or later

Type

Variable manipulator

Usage

Divide <Variable1> <Variable2> [?Result]

Arguments

<Variable1>

The dividend, the first argument, the number that is divided by the second argument. Also this argument contains the result if the optional [?Result] argument is not passed in. If used without the [?Result] argument, <Variable1> must be a Novell SecureLogin variable, either?Variable1 or $Variable1. Otherwise <Variable1> can be any numeric value.

<Variable2>

The divisor, the second argument, the number by which the first argument is divided. <Variable2> can be a Novell SecureLogin variable or a numeric value.

[?Result]Optional, the quotient, the result of the equation.

Description

Use to divide one number by another. The numbers can be written into the application definition or they can be variables. The result can be output to another variable or to one of the original numbers.

NOTE:This is an integer arithmetic that is 5/2, not 2.5.

Syntax examples

Divide "1" "2" ?Result
Divide ?LoginAttempts ?LoginFailures
Divide ?LoginAttempts ?LoginFailures ?Result
Divide ?LoginAttempts "3"
Divide ?LoginAttempts "3" ?Result

Example

Windows application definition

This example read the values of control IDs 103 and 104 into variables. From there they are divided,and typed into control ID 1.

ReadText #103 ?Number1
ReadText #104 ?Number2
Divide ?Number1 ?Number2 ?Result
Type ?Result #1

5.2.22 DumpPage

Use with

Advanced Web application definition

Novell SecureLogin version

3.5 or later

Type

Action

Usage

DumpPage <Variable>

Arguments

<Variable>

The string variable to receive the page information.

Description

Use the DumpPage command to provide information about the current Web page. Use for debugging Web page application definitions.

Example

DumpPage ?dump
MessageBox ?dump 

5.2.23 EndScript

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5 or later

Type

Action

Usage

EndScript

Arguments

None

Description

Use the EndScript command to immediately terminate execution of the application definition.

Example

Windows application definition

This example detects the login box, then Novell SecureLogin enters the user name and password, and the user clicks OK. If the Incorrect Password message is detected, Novell SecureLogin displays a message that the password was incorrect, and terminates the application definition.

Dialog   
Title "Logon Failure"   
Ctrl #1
EndDialog

ReadText #65535 ?ErrorMsg
If "Incorrect Password" -In ?ErrorMsg MessageBox "You have entered an incorrect password"   
EndScript
EndIf

5.2.24 Event/Event Specifiers

Use with

Windows

Novell SecureLogin version

3.5 or later

Type

Dialog specifier

Usage

Event <Event Specifier>

Arguments

<Event Specifier>

The application event to monitor. This corresponds to a Windows event, which usually begins with WM_.

For example, WM_COPYDATA, WM_GETOBJECT, WM_GETTEXT

For detailed information on Windows events, see the Microsoft Developer network Web site..

Microsoft's Spy++, or similar Windows message spy tools, are also useful for trapping event names in specific windows. Information on Spy ++ is also available on the MSDN Web site.

Description

Application definitions generally execute at the point when an application window is created. This corresponds to the WM_CREATE message that is received from an application window at start up. By adding the Event specifier to a dialog block, you can override this behavior, such that an application definition only executes when (and only when) the specified message is generated. If no Event specifier is given, it is equivalent to Event WM_CREATE.

You can only apply the Event specifier within a Dialog and EndDialog statement block. Only one Event may be specified per Dialog block. If there is a requirement to monitor for multiple events, each must be specified within their own Dialog block. For more information, see MSDN or other documentation on the Win32 messaging system.

Syntax examples

Dialog    
Class "someclass"    
Event WM_ACTIVATE
EndDialog
MessageBox "Caught the WM_ACTIVATE message"

5.2.25 FocusInput

Use with

Startup, Terminal Launcher, Web or Windows and advanced application definitions created using the Web Wizard.

Novell SecureLogin version

3.5.x or later

Type

Action

Usage

FocusInput #FormID:FieldID [-focus "focus"]

Arguments

#FormID:FieldID

The ID that was given to the matched field in the Site block using MatchField command. The FormID and FieldID must be unsigned integers.

-focus "focus"

Focuses the input field based upon the Boolean value of "focus". The Boolean value can be either "true" or "false.

Description

Used to focus on an input field based upon the Boolean value of "focus".

Example

In this example the value of field #1:2 is being checked by the application definition.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site Login -userid “Google Logon” -initial
MatchDoimain “www.google.com”
MatchField #1:1 -name “Email” -type “text”
MatchField #1:2 -name “Passwd” -type “password”
MatchField #1:3 -name “Cookie” -type “check”
EndSite
SetPrompt “Enter your user credentials”
TextInput #1:1 -value “$Username”
TextInput #1:2 -value “$Password”
FocusInput #1:2 -focus “true”
BooleanInput #1:3 -check “false”
PressInput
Endscript

5.2.26 GenerateOTP

GenerateOTP command supports two types of usage:

AISC Usage

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5.0 or later

Type

Action

Usage

GenerateOTP -mode <string>-challenge <string>

Arguments

<result>

A variable that receives the value of the one-time password (OTP) that is generated.

-mode

Specifies the type of OTP that is dynamically generated. The default value for mode is set to AISC-SKI for smartcard OTP. Setting this to AISC-SKI makes SecureLogin use the Novell algorithm to generate an OTP based on the user’s smart card. This setting is deprecated and can be removed.

-challenge

When the OTP generated is based on a challenge/response or asynchronous mode, the challenge needs to be passed to the GenerateOTP command as an argument, normally by means of a script that reads the challenge from the screen.

Description

OTP is an authentication method specifically designed to avoid the security exposures inherit in traditional fixed and static passwords.

OTPs rely upon a predefined relationship between the user and the authenticating server. The encryption key is shared between the user's token generator and the server, with each performing the pseudo-random code calculation at user logon. If the codes match, the user is authenticated.

The GenerateOTP command incorporates OTP token generation functionality embedded in Novell’s smartcard technology.

Novell’s soft tokens can be generated in synchronous and asynchronous modes which now allows soft tokens to be loaded onto mobile devices such as PDAs or be sent to cell phones as SMS text messages.

Synchronous mode: Synchronous authentication of ’Novell’s timeplus-event authentication replaces static alphanumeric passwords with a pseudo-random code that is dynamically generated at configured time intervals, generally around once a minute. The pseudo-random code is based on a shared encryption key and the current time.

Asynchronous mode: Asynchronous authentication or challenge response authorization replaces static alphanumeric passwords with a pseudo-random code that is dynamically generated based on a shared encryption key, the current time and a challenge/response combination. In Asynchronous mode the challenge must be passed to the GenerateOTP command as an argument.

The application definition asynchronous example shows a typical command structure to enable OTP for use with Novell’s smart card technology.

The application definition asynchronous example shows a typical command structure to enable OTP for use with Novell’s smart card technology.

Example

In Novell SecureLogin version 6.0, the GenerateOTP command was enhanced to integrate with smart cards.

In Synchronous mode the GenerateOTP command requires the administrator to pass the ‑mode variable, AISC-SKI, to the command.

In this instance AISC-SKI is the Novell smart card and SKI is the name of the applet used on the smart card.

An example application definition enabling synchronous OTP encryption key distribution for use with smart cards is as follows:

Dialog
Title "Test App"
EndDialog
GenerateOTP -mode "AISC-SKI" ?OtpResult
Type ?OtpResult #14

In Asynchronous mode the challenge must be passed to the GenerateOTP command as an argument. This requires a script that reads the challenge variable from the screen.

An example application definition enabling asynchronous OTP encryption key distribution for use with smartcards is as follows:

Dialog
Title "Test App"
EndDialog
ReadText #12 ?tmp
GenerateOTP -mode "AISC-SKI" -challenge ?tmp ?Otp
Type ?Otp #14

It is assumed that a call without a challenge passed in is synchronous. The -mode parameter, instead of being passed in via the script, can also be created as a single sign-on variable in the script platform.

If the -mode parameter is not passed in as a parameter to the GenerateOTP command, Novell SecureLogin will check for a variable named mode. Values passed into the command via the script will override values defined as variables. This is for future integration with Novell SecureLogin for Mobiles.

NOTE:It is assumed that the acomx.dll is present on the machine and in the path. If not, then additional code may be required to specify the location of this library file.

The smartcard is assumed to be in the card reader at OTP generation time and a single card reader is also assumed.

If the user's smart card has not been authenticated the user will be prompted to enter a PIN to unlock the card. This is required only once as the PIN is normally cached.

HOTP Usage

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

7.0 SP2 or later

Type

Action

Usage

GenerateOTP -METHOD=<XMethod> -MODE=<XMode> ?OTPResult

Arguments

-METHOD

Defines the method or algorithm to generate the OTP. You can use the following value:

  • OATH-HOTP

-MODE

Defines the mode of OTP generation and usage - software, hardware or smart token. You can use any one of the following values:

  • SOFT

  • HARD

  • AI-SC(Smart Card)

?OTPResult

A variable that receives the value of the one-time password (OTP) that is generated.

Description

SecureLogin will enable using wizards to configure applications supporting OTP based authentication. Using wizards, users can configure OTP algorithm specific parameters with the options available to choose from using the wizard.

Example

# place your application definition here. 
Set ?OTPCredential "<NOTSET>"
GenerateOTP -method "OATH_HOTP" -mode "SOFT" ?OTPCredential
If ?OTPCredential Eq "<NOTSET>"
DisplayVariables "Please specify all information." $OTPSecretKey $OTPCounter $OTPDigit 
GenerateOTP -method "OATH_HOTP" -mode "SOFT" ?OTPCredential 
EndIf
MessageBox "OTP Generation Success" 
MessageBox ?OTPCredential

5.2.27 GetCheckBoxState

Use with

Advanced Web, Windows

Novell SecureLogin version

3.5 or later

Type

Action

Usage

GetCheckBoxState <#Item Number> <Variable>

Arguments

<Item Number>

The ID of the check box.

<Variable>

The target variable for the status of the specified check box. Value returned is Checked or Unchecked. Partially selected tristate check boxes will be returned as Unchecked. The variable can be a question mark (?) or a dollar sign ($) variable.

Description

Use the GetCheckBoxState command to return the current state of the specified check boxes.

Example

GetCheckBoxState #25 ?state1
GetCheckBoxState #26 ?state2
MessageBox ?state1
MessageBox ?state2

5.2.28 GetCommandLine

Use with

Startup, Windows

Novell SecureLogin version

3.0.4 or later

Type

Action

Usage

GetCommandLine<Variable>

Arguments

<Variable>

This variable defines where to store the captured command line.

Description

Use the GetCommandLine command to capture the full command line of the program that is loaded and save it to the specified variable.

NOTE:You can use the GetCommandLine to detect and differentiate backend systems and databases for use with multiple logons in the SAP application.

Example

Windows application definition

This example reads the command line of the application, and then tests the line to see if it is Notepad.exe. If it is, Notepad is closed. If it is not, the application definition ends.

GetCommandLine ?Text
If ?Text Eq "\"C:\Windows\System32\notepad.exe\""
   KillApp Notepad.exe
EndIf

5.2.29 GetEnv

Use with

All

Novell SecureLogin version

3.5 or later

Type

Action

Usage

GetEnv <EnvVar> <Variable>

Arguments

<EnvVar>

This is the environment variable name you wish to retrieve.

<Variable>

This variable defines where to store the retrieved environment variable data.

Description

Use the GetEnv command to read the value of an environment variable and saves it in the specified variable.

Example

Windows application definition

GetEnv "SESSIONNAME" ?SessionName
If ?SessionName eq "console"
MessageBox "Running from Citrix Server Console"
EndIf

5.2.30 GetHandle

Use with

Windows

Novell SecureLogin version

6.1.0 or later

Type

Action

Usage

GetHandle <Variable>

Arguments

<Variable>

This variable defines where to store the captured handle.

Description

Use GetHandle to capture the unique handle of the window that the Windows application definition script is activated on.

GetHandle is used to retrieve the handle so that the value is passed to TLaunch.exe to inform the terminal launcher what window to interact with, or to pass the value to any other application.

Example 1

Windows application definition

GetHandle ?winHandle
MessageBox ?winHandle

Example 2

Windows application definition

GetReg "HKLM\Software\Microsoft\Windows\CurrentVersion\App Paths\SLProto.exe\Path" ?SLLocation
If ?SLLocation eq "<NOTSET>"
EndScript
EndIf

GetHandle ?PuttyHWND
Strcat ?TLaunch ?SLLocation "tlaunch.exe"
Strcat ?TLaunchHWND "/hwnd" ?PuttyHWND
Run ?TLaunch "/auto" "/ePutty" "/l" "/pPutty - Detection and
Login" "/t" "/q" "/s" ?TLaunchHWND

5.2.31 GetIni

Use with

Windows, Web, Terminal, Java

Novell SecureLogin version

3.5 or later

Type

Action

Usage

GetIni <ini file> <section> <key> <variable>

Arguments

<Ini File>

This is the file name from which you wish to read the section or key.

<Section>

Name of the section that contains the key name.

<Key>

Name of the key to read.

<Variable>

This variable defines where to store the retrieved environment variable data.

Description

Use the GetIni command to read data from INI file.

Example

Windows application definition

GetIni "C:\Program Files\Lotus\Notes\Notes.ini" "Notes" "KeyFileName" ?NotesDefaultIDFileSetPlat

5.2.32 GetMD5

Use with

Windows

Novell SecureLogin version

6.0 or later

Type

Action

Usage

GetMD5<Value>

Arguments

<Value>

Returns the MD5 hash value.

Description

Use the GetMD5 command to generate an MD5 hash value of the current process the script is running for. GetMD5 will only work with Win32 scripts.

Message-Digest algorithm 5 (MD5) is employed in Novell SecureLogin and can be used to check the integrity of files against a known hash value.

MD5 hash values are widely used in software to provide assurance that a particular file has not been altered. The administrator can compare a published MD5 sum with the checksum of another file to recognize corrupt or incomplete files, particularly for large executable files.

Example

In a Windows application definition the MD5 hash value is stored as a variable which is then passed in as the argument to the command, which could be a ?tmp or $hash_value type variable.

GetMD5 ?tmp

or

GetMD5 $hash_value

The MD5 hash value would normally be obtained with the Window Finder tool on a window from the application, and also the MD5 hash from Window Finder. This MD5 value would then be put in a script and the GetMD5 command would be used to compare the two MD5 hash values. If the MD5 hash values do not match, the executable file may have been altered.

5.2.33 GetReg

Use with

All

Novell SecureLogin version

3.5 or later

Type

Action

Usage

GetReg <RegEntry> <Variable>

Arguments

<RegEntry>

This is the registry entry to read.

<Variable>

This variable defines where to store the retrieved environment variable data.

Description

Use the GetReg command to read data from the registry and save it in the specified variable.

The following is format for the registry entry input: HIVE\KEY\Value

ValueValid hives are:

"HKCR "HKEY_CLASSES_ROOT "HKCC "HKEY_CURRENT_CONFIG "HKCU  "HKEY_CURRENT_USER "HKLM "HKEY_LOCAL_MACHINE "HKU "HKEY_USERS

Example

Windows application definition

GetReg "HKLM\Software\ABCCorp\ProductID"?ProductID
If ?ProductID noteq "xxxxxxxxxx"
#Not corporate desktop
EndScript
EndIf

5.2.34 GetDirectoryStatus

Use with

All

Novell SecureLogin version

7.0 or later

Type

Variable manipulators

Usage

GetDirectoryStatus <?StatusVariable>

Arguments

<?StatusVariable>

The target variable to which the value of the primary status is copied.

The value returned is either online or offline.

Description

Use the GetDirectoryStatus command to find out whether Novell SecureLogin can connect to the directory or not.

The status is online if the network is up, Novell SecureLogin connects to the directory, and the user is working in online mode.

The status is online if either the network is down, the network is up but the directory is unavailable, or the user chooses to work offline mode.

Example

GetDirectoryStatus ?status
If ?status eq “online”
#online instructions
EndIf
If ?status eq “offline”
#offline instructions
EndIf

5.2.35 GetSessionName

Use with

Terminal Emulator

Novell SecureLogin version

3.5 or later

Type

Action

Usage

GetSessionName <?Variable>

Arguments

<Variable>

The target variable that the session name is copied into.

Description

Use the GetSessionName command to find the current HLLAPI session name that is used to connect and returns it to the specified variable.

Example

Windows application definition

GetSessionName ?Session_name

5.2.36 GetText

Use with

Web, Terminal Launcher

Novell SecureLogin version

3.0 or later

Type

Action

Usage

GetText <Variable>

Arguments

<Variable>

This variable defines where to store the captured text.

Description

Use the GetText command to get all of the text from the screen and save it to the specified variable. It is used in large Web application definitions that contain several If -Text statements.

In Netscape, each If -Text statement screen scan to find the specified text caused the screen to flicker. However, using GetText (for example If ?Text -in ?FromGetText), the application definition can contain multiple If -Text commands with only one scan of the screen.

Example

Web application definition

This example copies the text content of the Web page to the ?Text variable. Novell SecureLogin tests for the presence of the word ‘Logon’. If Logon exists, Novell SecureLogin enters the credentials and submits them automatically.

GetText ?Text
If "Log on" -In ?Text   
Type $Username
Type $Password Password
EndIf

5.2.37 GetURL

Use with

Web

Novell SecureLogin version

3.0 or later

Type

Action

Usage

GetURL <Variable>

Arguments

<Variable>

This variable defines where to store the captured URL.

Description

Use the GetURL command to capture the URL of the site that is loaded and save it to the specified variable.

Example

Web application definition

This example copies the URL of the Web site to the ?URL variable and tests the URL to see if it matches text being searched for. If it does, Novell SecureLogin pops up a message box and redirects the user to the intranet.

GetURL ?URL
If "Log off" -In ?URL
MessageBox "You have chosen to log off the application. You will now be redirected to the intranet home page."
GoToURL "http://Intranet"
EndIf

5.2.38 GoToURL

Use with

Web

Novell SecureLogin version

3.5 or later

Type

Action

Usage

GoToURL <URL> [<-frame>]

Arguments

<URL>

The URL to which the browser will navigate.

<-frame>

Opens the URL in the frame which started the application definition.

Description

Use the GoToURL command to make the browser navigate to the specified URL. By default the command opens the new Web page in the main window, rather than the frame that started the application definition.

When using the -frame option on a framed Web page, the URL redirect occurs only in the current frame rather than the parent window.

You must include http://.

Example

Web application definition

This example detects an incorrect password message, displays a message box informing the user, and then browses the Novell Web site.

If -Text "Incorrect Password"   
MessageBox "You have entered an incorrect password"   
GoToURL "http://www.Novell.com"
EndIf

5.2.39 Highlight

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5 or later

Type

Action

Description

Use the Highlight command to set the focus of the Web page on a field.

The command is useful for pages that do not have any control selected after loading or for any fields that change the behavior after gaining focus.

It functions similar to the SetFocus command in Windows scripts.

Example

Web application definition

If –Text "Logon"
Highlight #1
Type $Username #1
Highlight #2
Type $Password #2
Type “\N”
EndIf

5.2.40 If/Else/EndIf

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5 or later

Type

Flow control

Usage 1

If <Value1> <Gt|Lt> <Value2>
#Do This
[Else]
#Do This
EndIf

Usage 2

If <Value1> <Eq|NotEQ > <Value2> [-I|-S]
#Do This
[Else] 
#Do This
EndIf

Usage 3

If <Value1> <-In|-NotIn> <Value2> [-I|-S]
#Do This
[Else]
#Do This
EndIf

Usage 4

If -Text [-Frame] <Text> 
#Do This
[Else]
#Do This
EndIf

Usage 5

If -Exist|-NotExist <Variable>
#Do This
[Else]
#Do This
EndIf

Arguments

<Value1>

The left side of the expression for evaluation.

<Value2>

The right side of the expression for evaluation.

<Text>

The text for which you are searching.

Description

Use the If command to establish a block to execute if the expression supplied is true. The Else command works inside an If block. The Else command is executed if the operator in the If block is false. Use the EndIf command to terminate the If block.

Text comparison operators supported The text comparison operators supported by the If command are:

  • Eq: True if the left side is equal to the right side.

  • NotEQ: True if the left side is not equal to the right side.

  • -In: True if the left side is a substring of the right side.

  • -NotIn: True if the left side is not a substring of the right side.

  • -SiteDeparted: Checks if the current document is still active or not.

When using these text comparison operators, you may optionally specify whether the comparison is to take into account the case of the strings being compared. If -I is specified, the comparison is case insensitive. If -S is specified, then the comparison is case sensitive. By default the Eq and NotEQ operators are not case sensitive, while the -In and -NotIn operators are case sensitive.

An operator is also supplied to directly query the application for a particular string:-Text: Evaluates to true if the specified text is found in the application windows of the application. For Internet Explorer application definitions, you can supply an optional -Frame argument, which restricts the command to look for the specified text in the current frame.

Numerical comparison operators supported Two numerical comparison operators are supported by the If command, Gt and Lt. The command evaluates to true if the left side is greater than or less than (respectively) the right side. This is a numerical comparison, so the left and right sides must be numbers.

An operator is supplied to check for the existence of a stored variable:

  • -Exists: True if the specified variable exists.

  • -NotExist: True if the specified variable does not exist.

Syntax examples

If $Number NotEQ "1"
MessageBox "NotEQ 1"
Else
MessageBox "Eq 1"
EndScript
EndIf

If ?Value1 Gt ?Value2
If -Text "Log on"
If -Exists $RunBefore
If "Log on" -In ?Text

Example 1

Web application definition

This example tests for an incorrect password. If it is found, an incorrect password message box is displayed. If the error message is not found, Novell SecureLogin logs in as normal.

If -Text "Incorrect Password"   
DisplayVariables "You have an incorrect password. Please verify it and retry log on."   
EndScript
Else   
Type $Username   
Type $Password Password
EndIf

Example 2

Windows application definition

Each time the application definition is run, a variable is incremented. This example counts the number of times the dialog box is displayed. If it is displayed more than three times, the application is closed. If the log on is successful, the count is reset.

# Logon Dialog Box
Dialog
   Class #32770
   Title “Log on”
EndDialog

ReadText #1001 ?Username

If –Exists $Username
Else
   Set $Username ?Username
EndIf
Increment ?RunCount
If ?RunCount Gt “3”
MessageBox “Log on has been attempted too many times.  The application will be closed.”
KillApp “app.exe”
Else
   Type $Username #1001
   Type $Password #1002
   Click #1
EndIf

# Logon Successful Dialog Box
Dialog
   Ctrl #1
   Title “Log on successful”
EndDialog

Set ?RunCount “0”

Example 3

Web application definition

This example copies the text content of the Web page to ?WebText. The variable is then tested to see if ‘Log on’ is present. If it is, Novell SecureLogin performs the login process. If it is not present, the application definition is terminated.

GetText ?WebText
If “Log on” –In ?WebText
   Type $Username
   Type $Password Password
Else
   EndScript
EndIf

Example 4

Startup

This example tests, upon Novell SecureLogin loading, to see if Novell SecureLogin has been run by the user. If it has not, Novell SecureLogin sets the variable so that the message is only displayed once, and then displays a welcome message along with the option for further details on Novell SecureLogin.

If –NotExist $LoadedBefore
   EndScript
Else
MessageBox –YesNo ?Result “Welcome to SecureLogin Single Sign‑On, a new password management tool that will save you the hassle of remembering your passwords. Would you like more details on how to use SecureLogin and what it can do for you?”
Set $LoadedBefore “Yes”
If ?Result Eq “Yes”
GoToURL “http://www.Novell.com/securelogin.htm”
EndIf
EndIf

5.2.41 Include

Use with

All

Novell SecureLogin version

3.0 or later

Type

Flow control

Usage

Include <Platform-Name>

Arguments

<Platform-Name>

The name of the application definition to include.

Description

Use the Include command to share commonly-used application definition commands by multiple applications. The application definition identified by <Platform-Name> is included at execution time into the calling application definition. The application definition included with the Include command must comprise commands supported by the calling application.

Example

Windows application definition

This example detects the login dialog, the Notepad.exe application definition is executed, and then the user's credentials are entered.

# Logon Dialog Box
Dialog
Class #32770
Title “Log on”
EndDialog

Include “Notepad.exe”
Type $Username #1001
Type $Password #1002
Click #1

5.2.42 Increment

Use with

All

Novell SecureLogin version

3.5 or later

Type

Variable manipulator

Usage

Increment <Variable>

Arguments

<Variable>

The name of the variable to increase in value.

Description

Use the Increment command to add to a specified variable. For example, you can use increment to count the number of passes a particular application definition has made.

Once the number of instances is equal to the specified number, you can instruct the application definition to run another task or end the application definition. This is useful when configuring an application whose login panel is similar to other windows within the application, or to easily control the number of attempts a user can have to access an application.

Also see Section 5.2.17, Decrement

Syntax examples

Increment ?RunCount

Example

Windows application definition

Each time the application definition is run, a variable is incremented. This example counts the number of times the dialog box is displayed. If the dialog box is displayed more than three times, the application is closed. If the log on is successful, the count is reset.

# Logon Dialog Box
Dialog
   Class #32770
   Title “Log on”
EndDialog

Increment ?RunCount
If ?RunCount Gt “3”
   MessageBox “Log on has been attempted too many times.  The application will be closed.”
   KillApp “app.exe”
Else
   Type $Username #1001
   Type $Password #1002
   Click #1
EndIf

# Logon Successful Message
Dialog
   Ctrl #1
   Title “Log on successful”
EndDialog

Set ?RunCount “0”

5.2.43 KillApp

Use with

All

Novell SecureLogin version

3.5 or later

Type

Action

Usage

KillApp <Process-Name>

KillApp <-Title>

Arguments

<Process-Name>

The name of the process to terminate.

-title “Application title”

The title of the process to terminate.

Description

Use the KillApp command to terminate an application.

Example 1

Windows application definition

Each time the application definition is run, a variable is incremented. This example counts the number of times the dialog box is displayed. If the dialog box is displayed more than three times, the application is closed. If the log on is successful, the count is reset.

# Logon Dialog Box
Dialog
   Title “Log on”
   Class #32770
EndDialog
Increment ?RunCount
If ?RunCount Gt “3”
   MessageBox “Log on has been attempted too many times.  The application will be closed.”
KillApp “app.exe”

Else
   Type $Username #1001
   Type $Password #1002
   Click #1
EndIf
# Logon Successful Message
Dialog
   Title “Log on successful”
   Ctrl #1
EndDialog
Set ?RunCount “0”

Example 2

Windows application definition

Same application definition as used in Example 1, however, the KillApp process is specified by title.

Dialog
   Title “Login Simple”
   Class #32770
EndDialog
Increment ?RunCount

If ?RunCount Gt “3”
   MessageBox “Log on has been attempted too many times.  The application will be closed.”
   KillApp -title “Login Simple”
Else
   Type $Username #1001
   Type $Password #1002
   Click #1
EndIf

# Logon Successful Message
Dialog
   Title “Login - Simple Successful”
   Ctrl #1
EndDialog
Set ?RunCount “0”

5.2.44 Local

Use with

All

Novell SecureLogin version

3.5 or later

Type

Variable manipulator

Usage

Local <?Variable>

Arguments

<?Variable>

The runtime variable to declare as local.

Description

Use the Local command to declare that a runtime variable will only exist for the lifetime of the application definition. Local runtime variables are used in the same way as normal runtime variables and are still written as ?Variable.

Declare local runtime variables as local by using the Local command, followed by the variable name. When runtime variables are declared local, you cannot set them back again. You can declare a runtime variable local at any time in an application definition.

Using local runtime variables increases the performance of Novell SecureLogin, although only slightly. Local runtime variables are used to run application definitions multiple times without storing the runtime variables between each run of the application definition.

Local runtime variables are also used to prevent runtime variables from overwriting each other, which could happen if two instances of an application definition are running at the same time. For example, use the Local command if two instances of Terminal Launcher are running, each instance running the same application definition but attached to different emulator sessions.

Example

Windows application definition

This example declares a variable as local, and then uses it to count the number of times a dialog box is displayed. If the dialog box is displayed too many times, Novell SecureLogin will alert the user, then close the application.

# Invalid Logon Message
Dialog   
Class #32770   
Title "Logon Failure"
EndDialog
Local ?RunCount
Increment ?RunCount
If ?RunCount Gt "5"   
MessageBox "Closing application"   
KillApp "PasswordText.exe"
EndIf
Type $Username
Type $Password

5.2.45 MatchDomain

Use with

Advanced application definitions created using the Web Wizard.

Novell SecureLogin version

3.5.x or later

Type

Action

Usage

MatchDomain "Domain"

Arguments

Domain

The domain name or address to be matched.

Description

Use MatchDomain inside a Site block to filter a site based on its domain. If the domain doesn't match, the Site block fails to match.

The domain matched is a normally a low level domain name such as www.yahoo.com and not www.yahoo.com/mymail/login

Example

In this example the site www.google.com is being matched by the application definition.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site Login -userid “Google Log On” -initial
MatchDomain “www.google.com”
MatchField #1:1 -name “Email” -type “text”
MatchField #1:2 -name “Passwd” -type “password”
MatchField #1:3 -name “Cookie” -type “check”
EndSite
SetPrompt “Enter your user credentials”
TextInput #1:1 -value “$Username”
TextInput #1:2 -value “$Password”
FocusInput#1:2 -focus “true”
BooleanInput #1:3 -check “false”
PressInput
Endscript

5.2.46 MatchField

Use with

Advanced application definitions created using the Web Wizard.

Novell SecureLogin version

3.5.x or later

Type

Action

Usage

MatchField #FormID:FieldID [-optional] [-name "name"] [-type "type"] [-value "value"] [‑defaultValue "defaultValue"]

Arguments

#FormID:FieldID

The ID to be given to the matched option within the field, building from the #FormID of the associated form. The FormID and FieldID must be unsigned integers. The combined #FormID:FieldID must be unique within the site block.

-optional

Specifies that matching this field is not required to successfully match the parent form.

-name "name"

Match against the field name.

-type "type"

Match against the field type. Type can be one of the following:

  • Button

  • Checkbox

  • File

  • Image

  • Hidden

  • Password

  • Radio

  • Reset

  • Submit

  • Text

  • TextArea

  • Select-multiple

  • Select-one

-value "value"

Match against the field value.

-defaultValue "defaultValue"

Match against the field’s default value.

Description

Use MatchField to filter a form based on the presence of a particular field. If the field fails to match and it is not specified as optional, then the parent form will fail to match.

Example

This example would locate the Web page fields Email, Password and Cookie within the Web site www.google.com .com matched by the application definition.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site Login -userid “Google Log On” -initial
MatchForm #1 -name “log on”
MatchDomain “www.google.com”
MatchField #1:1 -name “Email” -type “text”
MatchField #1:2 -name “Passwd” -type “password”
MatchField #1:3 -name “Cookie” -type “check”
MatchField #1:4 -name “SAVEOPTION” -type “checkbox” -value “YES”
MatchField #1:5 -name “Submit2” -type “submit”

EndSite
SetPrompt “Enter your user credentials”
TextInput #1:1 -value “$Username”
TextInput #1:2 -value “$Password”
FocusInput#1:2 -focus “true”
BooleanInput #1:3 -check “false”
BooleanInput #1:4 -check “false”

PressInput
Endscript

5.2.47 MatchForm

Use with

Advanced application definitions created using the Web Wizard.

Novell SecureLogin version

3.5.x or later

Type

Action

Usage

MatchForm #FormID [-optional] [-name "name"] [-action "action"] [-method "method"] [-target "target"]

Arguments

#FormID

The ID to be given to a matching form. The ID must be an unsigned integer prefixed with # and unique within the site block.

-optional

Specifies that matching this form is not required to successfully match site.

-name "name"

Specifies the form name to match against. The form name is an optional value given to a form by the creator of the Web site.

-action "action"

Specifies the form action to match against. The URL to which the form content is sent for processing.

-method "method"

Specifies the form method to match against. The method or how to send the form data to the server.

-target "target"

Specifies the form target to match against. The window or frame at which to the form targets its contents.

Description

Use MatchForm to filter a site based on the presence of a particular form. If the form fails to match and it is not specified as optional, then the site will fail to match.

Example

In this example the form named ‘log on’ within the Web site www.google.com .com is being matched by the application definition.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site Login -userid “Google Log On” -initial
MatchForm #1 -name “log on”
MatchDomain “www.google.com”
MatchField #1:1 -name “Email” -type “text”
MatchField #1:2 -name “Passwd” -type “password”
MatchField #1:3 -name “Cookie” -type “check”
EndSite
SetPrompt “Enter your user credentials”
TextInput #1:1 -value “$Username”
TextInput #1:2 -value “$Password”
FocusInput#1:2 -focus “true”
BooleanInput #1:3 -check “false”
PressInput
Endscript

The form name may be a “null”

MatchForm #1 -name “”

5.2.48 MatchOption

Use with

Advanced Web application definitions created using the Web Wizard.

Novell SecureLogin version

3.5.x or later

Type

Action

Usage

MatchOption #FormID:FieldID:OptionID [-optional] [-text "text"] [-value "value"]

Arguments

#FormID:FieldID:OptionID

The ID to be given to the matched option within the field, building from the #FormID:FieldID of the associated selection field. The FormID, FieldID and OptionIDs must be unsigned integers. The combined #FormID:FieldID:OptionID must be unique within the site block.

-optional

Specifies that matching this option is not required to successfully match the parent field.

-text "text"

Specifies the text string for this particular option.

NOTE:The text is what is displayed to the user.

-value "value"

Specifies the value for this particular option.

NOTE:The value is what is passed to the server when a form is submitted.

Description

Use the MatchOption command to filter a field based on the presence of a particular option.

An option is an item within a specific combo box or list box. If the option is not found, and it is not specified as optional, then the parent field will also fail to match.

Example

In this example the form named ‘log on’ within the secure Web site www.lotto.com is being matched by the application definition.

# === Logon Application Definition #4 ==
# === Lotto User Initial Logon ====
#========================================
Site Login -userid “Member Log In” -initial
MatchForm #1 -name “log in”
MatchDomain “https://site10.Lotto.com”
MatchField #1:1 -name “Member ID” -type “text”
MatchField #1:2 -name “Passwd” -type “password”
MatchOption #1:3 -name “Secure” -type “text”
EndSite
SetPrompt “Enter your user credentials”
TextInput #1:1 -value “$Username”
TextInput #1:2 -value “$Password”
FocusInput #1:2 -focus “true”
BooleanInput #1:3 -check “true”
PressInput
Endscript

5.2.49 MatchReferer

Use with

Advanced Web application definitions created using the Web Wizard.

Novell SecureLogin version

3.5.x or later

Type

Action

Usage

MatchReferer "Referer"

Arguments

MatchReferer

Used inside a site block, MatchReferer is used to filter a site based on a referer. If the site referer does not match, the site block fails to match.

"Referer"

The site referer which is to be matched. If PageA.htm includes a link to PageB.htm, then the referer is "PageA.htm".

Description

Use MatchReferer inside a Site/EndSite block to match or filter a site based on a referer.

Example

In this example the refering HTML page www.lotto.com/index.html is being matched by the application definition.

# === Logon Application Definition #5 ==
# === Lotto User Initial Logon ====
#========================================
Site Login -userid “Member Log On” -initial
MatchForm #1 -name “log on”
MatchReferer “www.lotto.com/index.html”
MatchDomain “https://site10.lotto.com”
MatchField #1:1 -name “Member ID” -type “text”
MatchField #1:2 -name “Passwd” -type “password”
MatchOption #1:3 -name “Secure” -type “text”
EndSite
SetPrompt “Enter your user credentials”
TextInput #1:1 -value “$Username”
TextInput #1:2 -value “$Password”
FocusInput #1:2 -focus “true”
BooleanInput #1:3 -check “true”
PressInput
Endscript

5.2.50 MatchRegex

Use with

All

Novell SecureLogin version

7.0 or later

Type

Action

Usage

MatchRegex <RegEx> <Input-String>

Arguments

<RegEx>

The regular expression

<Input-String>

The string to match against.

Description

Use the MatchRegex command to test whether a regular expression matches against the specified string or not. Can be used inside a Site–EndSite or Dialog–EndDialog block for example.

For more information regarding regular expressions see the Boost C++ Libraries Web site

Example

This example matches against any Web page on the www.google.com domain that has a text box, a password box and text somewhere on the page that matches against the “Welcome \w+ to Gmail” regular expression (“Welcome Nick to Gmail” for example).

Site “Gmail: Email from Google”
MatchForm #1
MatchDomain "www.google.com"
MatchField #1:10 -type “text”
MatchField #1:11 -type “password”
GetText ?PageText
MatchRegex “Welcome \w+ to Gmail” ?PageText
EndSite
MessageBox “Matched”

5.2.51 MatchTitle

Use with

Advanced Web application definitions created using the Web Wizard.

NOTE:-regex parameter is not supported in SecureLogin versions prior to 7.0.

Novell SecureLogin version

3.5 or later

Type

Action

Usage

MatchTitle [-regex] "URL"

Arguments

MatchTitle

Used inside a site block, MatchTitle is used to filter a site based on its title. If the site title does not match, the site block fails to match.

"Title"

The site title which is to be matched.

-regex

You may also use regular expressions to match part of a Title.

For more information regarding regular expressions see the Boost C++ Libraries Web site

Description

Use MatchTitle inside a Site block to match or filter a site based on a HTML page title.

Example

In this example the HTML page with the title ‘The New York Times > Log In’ within the Web site www.nytimes.com is matched by the application definition.

# =============================================
# Login Script #1 - The New York Times > Log In
# =============================================
# === Initial Login ===
Site Login -userid "nytimes.com #1" -initial
MatchURL "http://www.nytimes.com/auth/login"
MatchDomain "www.nytimes.com"
MatchTitle "The New York Times > Log In"
MatchForm #1 -name "login"
MatchField #1:1 -name "USERID" -type "text"
MatchField #1:2 -name "PASSWORD" -type "password"
MatchField #1:3 -name "SAVEOPTION" -type "checkbox" -value "YES"
MatchField #1:4 -name "Submit2" -type "submit"
EndSite

If the title to match is The New York Times > Log In, then

MatchTitle -regex "Times > Log In"

5.2.52 MatchURL

Use with

Advanced Web application definitions created using the Web Wizard.

NOTE:-regex parameter is not supported in SecureLogin versions prior to 7.0.

Novell SecureLogin version

3.5 or later

Type

Action

Usage

MatchURL [-regex] "URL"

Arguments

MatchURL

Used inside a Site block, MatchURL is used to filter a site based on its URL. If the URL doesn't match, the Site block fails to match.

"URL"

The site URL which is to be matched. This need not be the URL listed in the navigation field of the Web browser as the given page may not have been loaded from there.

-regex

You may also use regular expressions to match part of a URL, such as the domain only.

For more information regarding regular expressions see the Boost C++ Libraries Web site. :

Description

Use MatchURL inside a Site block to match or filter a HTML page within a site based on its URL.

The URL can be a complex Web address or a secure Web site.

Example

In this example the URL “https://www.nytimes.com/auth/login” is matched.

# === Initial Login ===
Site Login -userid "nytimes.com #1" -initial
MatchURL "https://www.nytimes.com/auth/login"
MatchDomain "www.nytimes.com"
MatchTitle "The New York Times > Log In"
MatchForm #1 -name "login"
MatchField #1:1 -name "USERID" -type "text"
MatchField #1:2 -name "PASSWORD" -type "password"
MatchField #1:3 -name "SAVEOPTION" -type "checkbox" -value "YES"
MatchField #1:4 -name "Submit2" -type "submit"
EndSite

If the URL to match is “http://www.nytimes.com/auth/login?URI=http://”, then:

MatchURL -regex "nytimes.com"

5.2.53 MessageBox

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5 or later

Type

Action

Usage

MessageBox<Data> [-Background] [-DefaultNo] [-YesNo <?Variable>] [-YesNoCancel <?Variable>]

Arguments

<-YesNo>

The -YesNo flag allows the user to select Yes or No within the message box, rather than being limited to an OK button only.

<-YesNoCancel>

The -YesNoCancel flag allows the user to select Yes, No, or Cancel when a message box is displayed.

<?Variable>

This runtime variable is required with the -YesNo / -YesNoCancel flag to store the result of the user action.

<-Background>

When specified, this parameter allows the user to open an application and work in that application, without having to respond to the MessageBox. If this parameter is not used, the MessageBox remains the active window. In Web applications, you must respond to the MessageBox before you can continue with any other work.

<-DefaultNo>

This optional parameter is used only with the -YesNo and -YesNoCan-cel flags. When the ‑DefaultNo parameter is set, the No button has the default focus rather than the Yes button.

<Data>

The text displayed to the user. <Data> can be several strings, variables, or a combination of both.

Description

Use the MessageBox command to display a dialog box that contains the text specified in the <Data> variable. The application definition is suspended until the user reacts to this message. The MessageBox can take any number of text arguments, including variables (for example, MessageBox "The user " $Username " has just logged onto the system").

You can set the -YesNo flag when calling a MessageBox. If the -YesNo flag is set, the MessageBox prompts the user with a box that has a Yes and a No button, rather than an OK button.

Use a runtime <?Variable> to capture the MessageBox result immediately after the flag. The variable value is set to Yes, No, or Cancel.

Syntax examples

MessageBox "Application definition completed successfully"
MessageBox "Do you wish to continue?"  -YesNo ?Result
MessageBox "Do you wish to continue?" -YesNoCancel ?Result ‑Background -DefaultNo

Example 1

Windows application definition

This example detects the change password dialog box. A message box is displayed prompting the user whether or not they would like to change their password, and to inform them it was successful.

# Change Password Dialog Box
Dialog   
Class #32770   
Title "Change Password"
EndDialog

MessageBox -YesNo ?Result "Your password has expired, would you like to change it now?"

If ?Result Eq "Yes"   
Type $Username #1015   
Type $Password #1004   
ChangePassword $Password Random   
Type $Password #1005   
Type $Password #1006   
Click #1   
MessageBox "Password changed successfully"
Else   
Click #2   
MessageBox "You chose not to change your password"
EndIf

Example 2

Terminal Launcher test application definition

Use message boxes when troubleshooting application definitions. This example displays a message box before each step in the application definition to allow the writer to see where the application definition execution is failing.

The WaitForText cuts off the first character because it finds both Password and password, and responds to all password entry points.

MessageBox "Beginning wait for logon prompt"
WaitForText "ogin:"
MessageBox "Logon detected, now entering user name"
Type $Username
MessageBox "User name entered, now simulating Enter"
Type @E
MessageBox "Enter has been simulated, now waiting for password”
Password"WaitForText "assword:"
MessageBox "Password detected, now entering password"
Type $Password
MessageBox "Password entered, now simulating Enter"
Type @E
MessageBox "Sequence completed, the user should now be logged on"

5.2.54 Multiply

Use with

All

Novell SecureLogin version

3.0 or later

Type

Variable manipulator

Usage

Multiply <Variable1> <Variable2> [?Result]

NOTE:You must use integer arithmetic.

Arguments

<Variable1>

The multiplicand, the first argument, is the number multiplied by the second argument. Also this argument contains the result if the optional [?Result] argument is not passed in. If used without the [?Result] argument, <Variable1> must be a Novell SecureLogin variable, either ?Variable1 or $Variable1. Otherwise <Variable1> can be any numeric value.

<Variable2>

The multiplier, the second argument, is the number by which the first number is multiplied. <Variable2> can be a Novell SecureLogin variable or numeric value.

[?Result]

Optional, the product, or result of the equation.

Description

Use to multiply one number by another. You can write the numbers into the application definition or use variables. The results can be output to another variable or to one of the original numbers.

Syntax examples

Multiply "1" "2" ?Result

Multiply ?LoginAttempts ?LoginFailures

Multiply ?LoginAttempts ?LoginFailures

?Result

Multiply ?LoginAttempts "3"

Multiply ?LoginAttempts "3" ?Result

Example

Windows application definition

This example reads the values of control IDs 103 and 104 into variables. From there they are multiplied, and typed into control ID 1.

ReadText #103 ?Number1
ReadText #104 ?Number2
Multiply ?Number1 ?Number2 ?Result
Type ?Result #1

5.2.55 OnException/ClearException

Use with

All

Novell SecureLogin version

3.0.4 or later

Type

Flow control

Usage

OnException <Exception Name> Call <SubRoutine>

ClearException <Exception Name>

Arguments

<Exception Name>

The name of the exception on which you wish to act. The following exceptions are supported:

  • AAVerifyCancelled: When a user cancels the re-authentication process (support will depend on the Advanced Authentication product being used).

  • AAVerifyFailed: When the AAVerify re-authentication command fails.

  • ChangePasswordCancelled: When a user cancels on the Change Password dialog.

  • EnterVariablesCancelled: When a user cancels the automatic variable prompt box or the display variables prompt box.

  • GenerateOTPCancelled: When a user cancels the GenerateOTP dialog.

  • GenerateOTPFailed: When the GenerateOTP command fails.

  • PickListCancelled: When a user cancels the pick list choice dialog.

  • RunFailed: When the program specified by the Run command fails to launch.

  • SelectLoginCancelled: When a user cancels the dialog box listing the login credential set.

<SubRoutine>

The name of the subroutine you want to run when the exception condition is true.

Description

Use the OnException command to detect when certain conditions are met. Currently, this is when Cancel is clicked on either of two dialog boxes. When the condition is met, a subroutine is run. Use the ClearException command to reset the exceptions value.

Syntax examples

OnException ChangePasswordCancelled Call Display Error
ClearException ChangePasswordCancelled

Example 1

Windows application definition

In this example the login failed because the user has invalid credentials stored. This provides the user with an opportunity to verify their user name and password, but what happens if the user clicks Cancel? If the user clicks Cancel, the exception is executed and forces the user to enter their credentials.

# Logon Failed Dialog Box
Dialog   
   Class #32770   
   Title "Log on failed"
EndDialog
OnException Enter VariablesCancelled Call VariablesCancelled
DisplayVariables "Please verify your user name and password and try again.  IT x4532"
ClearException EnterVariablesCancelled

Type $Username #1001
Type $Password #1002
Click #1
Sub VariablesCancelled   
   OnException EnterVariablesCancelled 
Call VariablesCancelled  
DisplayVariables "You cannot cancel this verification dialog box.  Please verify your user name and password when prompted and click OK to try again."   
   ClearException EnterVariablesCancelled
EndSub

Example 2

Windows application definition

This example prompts the user to change their password. Novell SecureLogin must handle password changes so the password is updated both in the application and in the user's 3DES encrypted store (in the directory against their user object).

# Change Password Dialog Box
Dialog
   Class #32770
   Title “Change Password”
EndDialog

Type $Username #1005
Type $Password #1006
OnException ChangePasswordCancelled Call ForceChangePwd
ChangePassword $Password “Please enter a new password for the Human Resources? application.  IT x4532”
Type $Password #1007
Type $Password #1008
ClearException ChangePasswordCancelled

Sub ForceChangePwd
   OnException ChangePasswordCancelled Call ForceChangePwd
   ChangePassword $Password “You must enter a new password and cannot Cancel.?
IT x432”
   Type $Password #1007
   Type $Password #1008
   ClearException ChangePasswordCancelled
EndSub

Example 3

Windows application definition

This example demonstrates the OnException usage of AAVerifyCancelled and AAVerifyFailed.

#
# Login - Simple
#
Dialog
   Title "Login - Simple"
   Class "#32770"
   Ctrl #1001
   Ctrl #1002
   Ctrl #1 "&Login"
   Ctrl #2 "Cancel"
   Ctrl #1027 "Username:"
   Ctrl #1028 "Password:"
   Ctrl #1009
EndDialog
   OnException AAVerifyCancelled Call CancelSimpleLoginDialogCancelled
   OnException AAVerifyFailed Call CancelSimpleLoginDialogFailed
   AAVerify -method "smartcard"
   Type $Username #1001
   Type $Password #1002
   Click #1
#
# Cancel the Simple Login Window - AAVerify cancelled
#
Sub CancelSimpleLoginDialogCancelled
   Click #2
   EndScript
EndSub
#
# Cancel the Simple Login Window - AAVerify failed
#
Sub CancelSimpleLoginDialogFailed
   Click #2
   MessageBox "Your re-authentication failed.  Login canceled"
   EndScript
EndSub

Example 4

Windows application definition

This example demonstrates the OnException usage of GenerateOTPCancelled and GenerateOTPFailed.

#
# Login - Simple
#
Dialog
   Title "Login - Simple"
   Class "#32770"
   Ctrl #1001
   Ctrl #1002
   Ctrl #1 "&Login"
   Ctrl #2 "Cancel"
   Ctrl #1027 "Username:"
   Ctrl #1028 "Password:"
   Ctrl #1009
EndDialog
   OnException GenerateOTPCancelled Call CancelSimpleLoginDialogCancelled
   OnException GenerateOTPFailed Call CancelSimpleLoginDialogFailed
   GenerateOTP -mode "AISC-SKI" ?OtpResult
   Type $Username #1001
   Type ?OtpResult #1002
   Click #1
#
# Cancel the Simple Login Window - GenerateOTP cancelled
#
Sub CancelSimpleLoginDialogCancelled
   Click #2
   EndScript
EndSub
#
# Cancel the Simple Login Window - GenerateOTP failed
#
Sub CancelSimpleLoginDialogFailed
   Click #2
   MessageBox "Your generation of your password failed.  Login cancelled"
   EndScript
EndSub

Example 5

Windows application definition

This example demonstrates the OnException usage of SelectLoginCancelled. In the following example, we create another credential set of Gmail and later create al linked credential set.

  1. Enable the first account for single sign-on. In this example, Gmail.

  2. In the notification area, right-click the Novell SecureLogin icon, then select New Login. The Add New Login Wizard Welcome page is displayed.

  3. Select the application for which you want to add another login. In this example, Gmail.

  4. Click Next.

  5. In the Description field, specify a descriptive name for the login. For example, Talk.

  6. Click Finish.

  7. Start the application.The <name of the application; in this example, www.google.com> login selection dialog box is displayed.

  8. Select the required login credential set, then click OK.

    SecureLogin enters the credentials, and you are automatically logged on to the application.

Dialog
  Title "Login - Simple"
EndDialog
 
OnException SelectLoginCancelled Call CannotCancel
SetPlat Login1
Type $username #1001
Type $password #1002
 
Sub CannotCancel
   Messagebox "You cannot cancel selecting to use a credential set, closing application."
   #Send ALT+F4 to close application
   type \ALT+\|115
   EndScript
EndSub

5.2.56 Parent/EndParent

Use with

Windows

Novell SecureLogin version

3.5 or later

Type

Dialog specifier

Usage

ParentEnd

Parent

Arguments

None

Description

Use the Parent command to begin a parent block in which the statements act upon a window's parent. The commands that follow the Parent command function identically to commands used in a dialog block; if they equate to false, then the application definition ends.

For example, the command Title in a parent block returns false if the title of the parent does not match the one specified in the command. However, if a command in a parent block returns a false result, the execution does not skip to the next parent block, as it would in a dialog block. Instead, the parent block proceeds to the next dialog block or the application definition terminates if no further dialog blocks exists.

The Parent command is particularly useful in applications where the dialog box (for example, a login dialog box) is the child of an open window, typically in the background. If you are unable to single sign-on to an application after enabling it with the wizard, you typically need to specify parent blocks.

You can also use the Parent command to execute commands on a dialog’s parent. For example, it is possible to get an application definition to click a button on the parent window. An example is shown below.

EndParent command Use the EndParent command to terminate a parent block and set the subject of the application definition back to the original window. You can nest the Parent command, thereby allowing the parent block to act on the parent of the parent.

NOTE:If you use the wizard or try to enable an application and it does not seem to work, try using the Parent command. It is able to handle windows that are within windows.

Example 1

Windows application definition

This example specifies the dialog box that is used for log on. In this case, the parent of the login box has a class of "Centura:MDIFrame".

# Logon Dialog Box 
Class "Centura:Dialog"
   Ctrl #4098   
   Ctrl #4100   
   Title "Log on"   
   Parent      
Class "Centura:MDIFrame"   
   EndParent

EndDialog

Type $Username #4098
Type $Password #4100
Click #4101

Example 2

Windows application definition

This example is used to click a button on the login window’s parent.

# Logon Dialog Box
Dialog   
   Class #32770 
   Title "Log on"
EndDialog

Type $Username #1001
Type $Password #1002
Parent 
Click #1
EndParent

5.2.57 PickListAdd

Use with

All

Novell SecureLogin version

3.5 or later (see note under Description below)

Type

Action

Usage

PickListAdd <Display-Text> [<Return-Value>]

Arguments

<Display-Text>

The text displayed in the pick list for the specified option.

<Return-Value>

The value returned from the pick list. If not specified, the return value is the display text.

Description

Use the PickListAdd command to allow users with multiple accounts for a particular system to choose the account to which they will log on.

You can also use PickListAdd command to choose from multiple sessions on one mainframe account. Use the PickList to build a list of databases, phone numbers, or any list from which a user can choose. You can then set variables or take action accordingly.

PickListAdd is always used with the PickListDisplay and is typically also used in conjunction with the SetPlat command.

NOTE:Change in usage from Novell SecureLogin 6.1 on. Setting variables after adding them to the list no longer results in the new value appearing in the list. For example:

PickListAdd ?Y
Set ?Y “Text”
PickListDisplay ...

will display the value <not set>

Example 1

Java or Windows application definition

In this example, the user has to pick which of three accounts to use. They pick which account they want to use, and Novell SecureLogin switches to that set of credentials using the SetPlat command.

## Logon Dialog Box ##
Dialog 
   Title "Log on"
EndDialog
PickListAdd "Account One" "One"
PickListAdd "Account Two" "Two"
PickListAdd "Account Three" "Three"
PickListDisplay ?Account "Please select the account you wish to use"-NoEdit
SetPlat ?Account
Type $Username #1001
Type $Password #1002
Click #1
## End Logon Dialog Box ##

Example 2

Any application definition

In this example, the application should execute and when Novell SecureLogin runs it should display the numbers 0 - 9.

Set ?Count "0"
Repeat 10
   PickListAdd ?Count
   Increment ?Count
EndRepeat
PickListDisplay ?Count "Please select your option " -NoEdit

Example 3

Java or Windows application definition

In this example, Novell SecureLogin reads the following window and prompts the user with the items in the Other list:

###Logon
PickListAdd #3
PickListDisplay ?Database "Select your database" -NoEdit
SetPlat ?Database
Type #1 $Username
Type #2 $Password
Select ?Database #3
###End logon##

5.2.58 PickListDisplay

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5 or later

Type

Action

Usage

PickListDisplay <?Variable> <Display-Text> [-NoEdit]

Arguments

<?Variable>

The output variable for the selected option.

<Display-Text>

The description text for the pick list box.

-NoEdit

The -NoEdit flag disables the addition of extra variables by the user.

Description

Use the PickListDisplay command to display the pick list entries built by previous calls to PickListAdd. The PickListDisplay command returns the result in a <?Variable> sent to the command.

If the desired entry is not among the displayed entries, the user can enter their own data into an edit field at the bottom of the pick list. Set the -NoEdit flag to turn this feature off.

Syntax examples

PickListDisplay ?Choice "Please select the account you wish to use"
PickListDisplay ?Choice "Please select the account you wish to use" -NoEdit 

Example

Windows example

In this example, the user has three accounts to this application and wants to pick which one to use. They pick which account they want to use and Novell SecureLogin uses the SetPlat command to switch to that set of credentials.

# Logon dialog box
Dialog   
   Class #32770   
   Title "Log on"
EndDialog
PickListAdd "Account one" "One"
PickListAdd "Account two" "Two"
PickListAdd "Account three" "Three"
PickListDisplay ?Account "Please select the account you wish to use" -NoEdit
SetPlat ?AccountType $Username #1001
Type $Password #1002
Click #1

5.2.59 PositionCharacter

Use with

Password Policy application definitions

Novell SecureLogin version

3.5 or later

Type

Action

Usage

POSITIONCHARACTER [NUMERAL] [UPPERCASE] [LOWERCASE] [PUNCTUATION] <Position>, [<Position>].

Arguments

[NUMERAL]

The character at <Position> must be a numeral.

[UPPERCASE]

The character at <Position> must be an uppercase character.

[LOWERCASE]

The character at <Position> must be a lowercase character.

[PUNCTUATION]

The character at <Position> must be a punctuation character.

<Position>

The character position in the password.

Description

Use this command in a password policy application definition to enforce that a certain character in the password is a numeral, uppercase, lowercase, or a punctuation character.

You can specify multiple positions.

Example

The password is not valid unless the first, sixth, and seventh characters are uppercase.

POSITIONCHARACTER UPPERCASE 1,6,7

5.2.60 PressInput

Use with

Advanced Web application definitions created using the Web Wizard.

Novell SecureLogin Version

3.5.x or later

Type

Action

Usage

PressInput [#FormID:FieldID [-press "press"]]

Arguments

PressInput

Simulates a keyboard enter event. Optionally focusing a given field beforehand.

#FormID:FieldID

The ID that was given to the matched field in the Site block using MatchField command. The FormID and FieldID must be unsigned integers.

-press "press"

Description

Simulates pressing the keyboard Enter key.

Example

This example the PressInput command within the application definition is the equivalent of clicking the Sign In button on the www.google.com Web site.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site Login -userid “Google Log On” -initial
MatchForm #1 -name “log on”
MatchDomain “www.google.com”
MatchField #1:1 -name “Email” -type “text”
MatchField #1:2 -name “Passwd” -type “password”
MatchField #1:3 -name “Cookie” -type “check”
EndSite
SetPrompt “Enter your user credentials”
TextInput #1:1 -value “$Username”
TextInput #1:2 -value “$Password”
FocusInput#1:2 -focus “true”
BooleanInput #1:3 -check “false”
PressInput
Endscript

5.2.61 ReadText

Use with

Terminal Launcher, Windows. This command applies specifically to HLLAPI, WinHLLAPI and HLLAPI 16 terminal emulators.

Novell SecureLogin version

3.5 or later

Type

Action

Windows Usage

Terminal Launcher Usage

ReadText <#Ctrl-ID> <?Variable> ReadText [-order] <#Order-ID>

ReadText <?Variable> <Character-Number> <Row-Number> <Column-Number>

Arguments

[-order]

If the control ID's are not constant, utilize the -order argument to instruct Novell SecureLogin to type into a control based on the creation order and not the tab order. For more information on the -order argument usage, see Example 4.

<#Ctrl-ID>

The control ID number of the text to read.

<#Order-ID>

For Windows application definitions, this parameter specifies which control based on the creation order in which to type the text.

<?Variable>

The variable that receives the text that is read.

<Character-Number>

The number of characters to read.

<Row-Number>

The horizontal position number of the first character to read (for example, row).

<Column-Number>

The vertical position number of the first character to read (for example, column).

Description

Use the ReadText command to run in both Windows and Terminal Launcher application definitions. While the usage and arguments for the use of ReadText with Windows and Terminal Launcher are different, the results of each command are the same.

Windows application definition In a Windows application definition, the ReadText command reads the text from any given <#Ctrl-ID>, and sends it to the specified variable. For this command to function correctly, the <#Ctrl-ID> must be valid.

Terminal Launcher application definition In a Terminal Launcher application definition, the ReadText command reads a specified number of characters, starting at the <Row-Number>, and sends those characters to the specified <Variable>. The ReadText command will not work with Generic or Advanced Generic emulators, it only works with HLLAPI and some DDE emulators. For Generic or Advanced Generic emulators, use the If -Text or Gettext commands.

For more information, see Section 5.2.40, If/Else/EndIf and Section 5.2.36, GetText.

Syntax examples

ReadText #301 ?Text
ReadText ?Text 4 6

Example 1

HLLAPI emulator

Readtext ?result "X" "Y" "Z"

X = The number of characters to read.

Y= The row from which the characters are read.

Z= The column from which the characters are read.

Example 2

Windows script

ReadText #1004 ?result 

Example 3

Windows application definition

The same title and class appear in the error message dialog box when a user fails to log on.

This example distinguishes between errors and provides users with more specific information, rather than a general message stating their username and password is incorrect, or the account is locked. In this case, the example reads the error message, clicks OK, and prompts the user with a customized message.

# Logon Failed Message
Dialog   
   Class #32770 
   Title "Log on failed"
EndDialog

ReadText #65535 ?ErrorMsg
Click #1
If "Invalid Username" -In ?ErrorMsg   Display-Variables "Please verify your Username and try again." $Username   
   Type $Username #1001   
   Type $Password #1002   
   Click #1
EndIf
If "Invalid Password" -In ?ErrorMsg   Display-Variables "Please verify your Password and try again." $Password   
   Type $Username #1001   
   Type $Password #1002 
   Click #1
EndIf
If "Account locked" -In ?ErrorMsg   MessageBox "Your account is locked. Please contact the IT help- desk on x4532."   
   EndScript
EndIf

Example 4

Windows application definition

This example reads the text from a control ID and sets the database variable so the user is not prompted to set the variable.

# Logon Dialog Box
Dialog   
   Class #32770   
   Title "Log on"
EndDialog
ReadText #15 ?Database
If -Exists $Database
Else   
   Set $Database ?Database
EndIf
Type $Username #1001
Type $Password #1002
Type $Database #1003
Click #1

Example 5

Terminal Launcher application definition

This example reads a message in a trminal emulator and displays the message in a user friendly format.

ReadText ?Message 30 24 2
MessageBox ?Message

Example 6

Windows application definition

This example reads the text from a control defined by its creation order and sets the database variable so the user is not prompted to set the variable.

# Logon Dialog Box
Dialog   
   Class #32770   
   Title "Log on"
EndDialog
ReadText -order #5 ?Database
If -Exists $Database
Else   
   Set $Database ?Database
EndIf
Type $Username #1001
Type $Password #1002
Type $Database #1003
Click #1

5.2.62 RegSplit

When using regular expressions with the RegSplit command, ensure that any regular expressions comply with the syntax rules detailed under Section 4.3.8, Regular Expressions.

Use with

All

Novell SecureLogin version

3.5 or later

Type

Action

Usage

RegSplit <RegEx> <Input-String> [<Output-String1> [<Output-String2>]...]

Arguments

<RegEx>

The regular expression.

<Input-String>

The string that to split.

<Output-String1>

The first sub-expression.

<Output-String2>

The second sub-expression.

Description

Use the RegSplit command to split a string using a regular expression. <Output-String1> and <Output-String2> contain the first and second sub-expressions respectively.

For more information regarding regular expressions see:

www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html

For information regarding Microsoft regular expression usage, search the Microsoft MSDN Library at:

http://msdn2.microsoft.com/en-us/library/default.aspx

Example 1

Windows application definition

This example copies text from control ID 301 to the ?Text variable. The RegSplit command is then used to strip the user name details out of the text that was read. The platform is set to that user name, and the correct password is entered by Novell SecureLogin.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog
ReadText #65535 ?Text
RegSplit "Please enter the password for (.*) account" ?Text ?UserSetPlat ?User
Type $Username #1001
Type $Password #1002
Click #1

Example 2

How to handle regsplit exception with OnException

# Logon Dialog Box
Dialog
   Title "Untitled - Notepad"
EndDialog
Set ?Url "Oneabc"
Type ?Url
Type \n
# Create exception handler
OnException RegSplitFailed Call RegSplitError
# Provide suspicious regular expression, note the "\)" below RegSplit "(.*\)abc(.*)" ?Url ?Lhs ?Rhs
StrCat ?Url ?Lhs ", " ?Rhs
MessageBox ?Url
ClearException RegSplitFailed
Sub RegSplitError
   # print out RegSplitReturnCode
   Type "RegSplitError: "
   Type ?RegSplitReturnCode
   Type \n
   EndScript
EndSub

Open text example

#?InputString: "This is a long string with a few components in it"

Command

RegSplit "This(.*)a long(.*)with(.*)components(.*)" ?InputString ?First ?Second ?Third ?Fourth

Result

?First = "is", ?Second = "string", ?Third = "a few", ?Fourth = "in it"

5.2.63 ReLoadPlat

When an application first presents a login screen, Novell SecureLogin displays a message prompting the user to select an appropriate platform from a list. Once selected, Novell SecureLogin enters the chosen platform's credentials into the application and submits them.

Resolving the issue of re-entering user ID details

If log on fails due to incorrect credentials, Novell SecureLogin prompts the user to change their credentials. Novell SecureLogin does not retain the platform details and prompts the user to re-enter the information. This could result in the user changing the wrong credentials if they select the incorrect platform.

The SetPlat, ReLoadPlat and ClearPlat commands resolve this issue. ReloadPlat sets the current platform to the one which was last chosen (for the given application) or, if a platform was not previously selected, the command will leave it unset.

See also Section 5.2.77, SetPlat and Section 5.2.11, ClearPlat.

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5 or later

Type

Action

Usage

Use the ReLoadPlat command at:

  • Log on. Before the user first logs onto the application, call ReLoadPlat. This prevents the user from having to reselect a platform after a failed log on.

  • Failed log on. Call ReLoadPlat to reselect the platform that contained the incorrect credentials. This gives the user an opportunity to change the credentials using a ChangePassword or a DisplayVariables command.

Arguments

None

Description

Use to set the current platform to the last one chosen by the application definition or, if a platform is not chosen, leaves the platform unset.

Example

Windows application definition

# ==== BeginSection: Application startup ====
Dialog 
   Class "#32770" 
   Title "Password Test Application"
EndDialog
ClearPlat
# ==== EndSection: Application startup ====

# ==== BeginSection: Log on ====
Dialog 
   Class "#32770" 
   Title "Log on"
   Ctrl #1001
EndDialog
ReLoadPlat
SetPrompt "Username =====>
"Type $Username #1001
SetPrompt "Password =====>
"Type $Password #1002
SetPrompt "Domain =====>
"Type $Domain #1003
Click #1
# ==== EndSection: Log on ====

## ==== BeginSection: Log on successful ====
Dialog 
   Class "#32770
   "Title "Log on successful"
EndDialog
ClearPlat
Click #2
# ==== EndSection: Log on successful ====

Example (continued)

# ==== BeginSection: Log on failure ====
Dialog 
   Class "#32770" 
   Title "Log on failure"
EndDialog
Click #2

ReLoadPlatOnException ChangePasswordCancelled Call Change-Cancelled 
ChangePassword $password
ClearException ChangePasswordCancelled 
Type -raw \Alt+F
Type -raw L
# ==== EndSection: Log on failure ====

# ==== BeginSection: Change credentials cancelled ====
Sub ChangeCancelled 
   ClearPlat 
   EndScriptEndSub
# ==== EndSection: Change credentials 
Cancelled ===

5.2.64 Repeat/EndRepeat

Use with

All

Novell SecureLogin version

3.5 or later

Type

Action

Usage

Repeat [Loop#] EndRepeat

Arguments

[Loop#]

The number of times the repeat application definition block is repeated. If not specified, the repeat continues indefinitely unless broken by other commands.

Description

Use the Repeat command to establish an application definition block similar to the If command. The repeat block is terminated by an EndRepeat command. Alternatively, you can use the Break or EndScript commands to break out of the loop.

Syntax examples

Repeat
Repeat 3

Example

Terminal application definition

This example uses the Repeat command to watch the screen for the messages and responds accordingly. You can use the Break command to jump to the next repeat loop in the application definition.

# Initial System Log on
WaitForText "login:"
Type $Username
Type @E
WaitForText "password:"
Type $Password
Type @E
Delay 500
#Repeat loop for error handling
Repeat
#Check to see if password has expired   
   If -Text "EMS: The password has expired."     
ChangePassword
#Password 
Type $Password      
Type @E 
Type $Password 
Type @E   
   EndIf
#User has an invalid Username and / or # Password stored.  
   If -Text "Log on Failed"      
DisplayVariables "The username and / or password stored by SecureLogin is invalid. Please verify your credentials and try again.  IT x453."     
Type $Username      
Type @E     
Delay 500      
WaitForText "password:"      
Type $Password 
Type @E      
Delay 500   
   EndIf
# Account is locked for some reason, possibly inactive. 
   If -Text "Account Locked" 
MessageBox "Your account has been locked, possibly due to inactivity for 40 days. Please contact the administrator on x453."   
   EndIf
# Main Menu, user has logged on successfully.  
   If -Text "Application Selection"      
Break   
   EndIf
Delay 100
EndRepeat

5.2.65 RestrictVariable

Use with

All

Novell SecureLogin version

3.5 or later

Type

Action

Usage

RestrictVariable <Variable-Name>

<Password-Policy>

Arguments

<Variable-Name>

The name of the variable to restrict.

<Password-Policy>

The name of the policy to enforce on the variable.

Description

Use the RestrictVariable command to monitor a variable and enforce a specified password policy on the variable. Any variable specified must match the policy or it is not saved.

When restricting variables to policies, if you are making a tighter policy than is already in place, and you restrict a variable that does not match the policy today, then the user cannot save it the first time. This is because when Novell SecureLogin detects there is no saved credential, a user who has a password of 6 characters today cannot save it if the policy restricts the $Password variable to 8 characters and 2 numbers.

Example 2 works around this by restricting a new password variable (?NewPwd), instead of restricting the $Password variable. The user can store their existing password when Novell SecureLogin prompts for the credentials first time, and enforces the stronger password policy when the password expires in x days.

You can restrict any variable using a password policy, not just a $Password. You can also use RestrictVariable to make sure other variables are entered in the correct format. For example, you can enforce that $Username is always lowercase or $Database is 6 characters and no numbers.

Example 1

Windows application definition

This example uses the application definition to restrict the $Password variable to the Finance password policy. The user's password must match the policy when they first save their credentials. When the password requires changing, the application definition generates a new password randomly based on that policy (no user intervention is required).

# Set the password to use the Finance password policy
RestrictVariable $Password FinancePwdPolicy

#Logon Dialog Box
Dialog 
   Class #32770 
   Title "Log on"
EndDialog

   Type $Username #1001
   Type $Password #1002

#Change Password Dialog Box

Dialog
   Class #32770   
   Title "Change Password”
EndDialog
   Type $Username #1015
   Type $Password #1004
   ChangePassword $Password Random
   Type $Password #1005
   Type $Password #1006
Click #1

Example 2

Windows application definition

This example uses the application definition to restricts the ?NewPwd variable to the Finance password policy. When the application starts for the first time and prompts the user to enter their credentials, then their current password ($Password) is saved and used.

When the password expires, the password policy is enforced on any new password. This is a way to enforce tougher password policies (than are currently in place) when you cannot guarantee all existing passwords meet the new policy.

# Set the password to use the Finance password policy
RestrictVariable ?NewPwd FinancePwdPolicy
# Logon Dialog Box
Dialog   
   Class #32770   
   Title "Log on"
EndDialog
   Type $Username #1001
   Type $Password #1002
Click #1
# Change Password 
Dialog Box
Dialog   
   Class #32770   
   Title "Change Password"
EndDialog 
   Type $Username #1015
   Type $Password #1004
   ChangePassword ?NewPwd Random
   Type ?NewPwd #1005
   Type ?NewPwd #1006
   Set $Password ?NewPwd
Click #1

5.2.66 Run

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5 or later

Type

Action

Usage

Run <Command> [<Arg1> [<Arg2>] ...]

Arguments

<Command>

The full path of the program to execute.

<Arg1>, <Arg2>

An optional list of arguments and switches for the command.

Description

Use the Run command to launch the program specified in <Command> with the specified optional [<Arg1> [<Arg2>] …] arguments.

The application definition does not wait for the launched program to complete.

Example

Startup application definition

This example prompts the user to start the Finance System.

If they click:

  • Yes, the Run command is used to start the application with the necessary switches.

  • No, a message box is displayed, and the application is not started.

MessageBox "Would you like to connect to the Finance System?" -YesNo ?Result
If ?Result Eq "Yes"   
   Run "C:\Program Files\HRS\Finance.exe"  "/DB:HRS" "/Debug" 
Else   
   MessageBox "You have chosen not to run the Finance System.  Please do so manually."   
   EndScript
EndIf

5.2.67 RunEX

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

7.0.3 or later

Type

Action

Usage

RunEx [-show <state>] [-position <coord>] [-size <dimensions>] -cmd "executablepath" [arg1[ argN]]

Arguments

-show <state>

state is a variable or value that represents a window state. For more information about the values, see ShowWindow function.

NOTE:If the state cannot be evaluated to a valid state, then the default value is NORMAL.

-position <coord>

coord is a variable or value that represents screen position in pixels from the top left of the window.

-size <dimensions>

dimensions is a variable or value that represents width in pixels.

<Arg1>, ....<ArgN>

An optional list of arguments and switches for the command

Description

RunEX executes a function in the hidden mode based on the options the user provides.

Example

For Example:

  • RunEx -show maximize -cmd cmd.exe

  • RunEx -position 50,50 -cmd cmd.exe

  • RunEx -size 800,900 -cmd cmd.exe

  • RunEx -show hide -cmd <application> <arg1> <arg2>

5.2.68 Select

Use with

Java, Advanced Web, Windows

Novell SecureLogin version

6.1 or later

Type

Action

Usage

Select <Text of Item to select> [<#Ctrl-ID>]

Arguments

<Text of Item to select>

The text item that you want Novell SecureLogin to select in the list box.

<#Ctrl-ID>

When multiple list boxes are found, this specifies which list box to address.

Description

Use the Select command to select entries from a combo or list style control.

Examples

This example picks an item from the session combo or list control:

Select ?session #1

This example selects a tab within another tab control. When one tab control is contained within another, the tab selection order is irrelevant.

Select “Quick Connect” #70
Select “Connection” #69

This example selects a cell from within a table

Select “[0,0]” #1
If –text “User” #1
   Select “[0,1]” #1
   Type $Username #1
Endif

5.2.69 SelectListBoxItem

Use with

Advanced Web application definitions

Novell SecureLogin version

3.5 or later

Type

Action

Usage

SelectListBoxItem :<Item text of selection> <#Ctrl-ID> [-multiselect]

Arguments

<Item text of selection>

The text item that you want SecureLogin to select in the list box. it can be a variable or a string.

<#Ctrl-ID>

Must be provided.

<-multiselect>

Used to select multiple list box entries by using a subsequent SelectListBoxItem command.

Description

Use the SelectListBoxItem command to select entries from a list box.

For instructions on determining <#Ctrl-IDs>, see Section 5.2.22, DumpPage.

Example

If "ERROR: The credentials supplied were invalid. Please try again." -In ?Text
SelectListBoxItem "Find Context" #1
Type ?SysUser #1
Type $Password #2
MessageBox "If logon continues to fail, please logout of the computer and back
in, retry, and report it to your SecureLogin administrator."
EndScript
EndIf

5.2.70 SelectOption

Use with

Advanced Web application definitions.

Novell SecureLogin version

3.5.x or later

Type

Action

Usage

SelectOption #FormID:FieldID:OptionID -select <true|false>

or

SelectOption #FormID:FieldID –clear

Arguments

#FormID:FieldID:OptionID

The ID that was given to the matched option in the Site block using the MatchOption command. The FormID, FieldID, and OptionID must be unsigned integers.

-select "select"

Selects or deselects a specific option.

"select" is a Boolean value, either "true" or "false".

-clear

Deselects all options for the given control.

Description

Use the SelectOption command to select or deselect options within a list box or combo dialog box.

Example

This example clears the selection in the option list and selects option 2 only.

SelectOption #1:3 -clear
SelectOption #1:3:2 –select true 

5.2.71 SendEvent

Use with

All

Novell SecureLogin Version

7.0

Type

Action

Usage

SendEvent <Windows Handle> <Event Specifier>

Arguments

<Windows Handle>

A valid windows handle. This should be a local variable with the handle initialised via a call to GetHandle. Alternatively, it is possible to broadcast the event by using the Windows constant HWND_BROADCAST.

<Event Specifier>

See Section 5.2.24, Event/Event Specifiers for the applicable conditions. In addition, a new custom single sign-on event can be used, SSO_NOTIFY.

Description

Use the SendEvent command with constants:

  • HWND_BROADCAST to send an event to all windows

  • SSO_NOTIFY to send a custom single sign-on event

Example 1

Send WM_SETFOCUS using a captured handle

Event WM_SETFOCUS
....
GetHandle ?handle
SendEvent ?handle WM_SETFOCUS

Example 2

Broadcast the custom SSO_NOTIFY event

Event SSO_NOTIFY
....
SendEvent HWND_BROADCAST SSO_NOTIFY

5.2.72 SendKey

Use with

Terminal Launcher

Novell SecureLogin Version

3.5 or later

Type

Action

Usage

SendKey <Text>

Arguments

<Text>

The text typed into the emulator screen.

Description

Use the SendKey command to work only with Generic and Advanced Generic emulators. You can use the SendKey command in the same manner as the Type command. Generally, the Type command is the preferred command to use. The Type command places the text into the clipboard, and then pastes it into the emulator screen. The SendKey command enters the text directly into the emulator screen.

Using the Type Command: Variables do not work with the SendKey command. If you want to use variables, use the Type command.

The Type command has many special functions, and some you can use with the SendKey command. For more information, see Section 5.2.92, Type and Section 7.0, Reference Commands and Keys.

Example

Terminal Launcher application definition

The example sends the username and password to the terminal emulator.

#Send User Name
SendKey "DJones"
SendKey "\N"
#Send Password
SendKey "Hu7%f"
SendKey "\N"

5.2.73 Set

Use with

All

Novell SecureLogin version

3.5 or later

Type

Action

Usage

Set <Variable> <Data>

Arguments

<Variable>

The variable to which the data is being assigned.

<Data>

The text or variable read from and assigned to the variable. If the data argument contains a ? then it must be escaped (\?), for example:

Set ?Message “\?Username”

Descriptions

Use the Set command to copy the value of <Data> into <Variable>. The <Data> can be any text or another variable, whereas the <Variable> must be either a ?Variable or $Variable.

Example 1

Windows application definition

This example uses the application definition to set a ?RunCount variable to count the number of times the application is run.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

If ?RunCount Eq <NOTSET>   
   Set ?RunCount "1"
Else 
   Increment ?RunCount
EndIf

   Type $Username #1001
   Type $Password #1002
Click #1

Example 2

Windows application definition

This example uses the application definition to set the ?NewPwd to the stored $Password variable.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

   Type $Username #1001
   Type $Password #1002
Click #1

# Change Password Dialog Box
Dialog 
   Class #32770
   Title "Change Password"
EndDialog

   Type $Username #1015
   Type $Password #1004
   ChangePassword ?NewPwd Random
   Type ?NewPwd #1005
   Type ?NewPwd #1006
   Set $Password ?NewPwd
Click #1

Example 3

Windows application definition

This example uses the application definition to read the value of control ID 15 and sets the $Database variable so the user does not have to set the variable.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

ReadText #15 ?Database
If -Exists $Database   
Else   
   Set $Database ?Database
EndIf

5.2.74 SetCheckBox

Use with

Advanced Web, Windows

Novell SecureLogin version

3.5 or later

Type

Action

Usage

SetCheckBox <Item Number> <Option>

Arguments

<Item Number>

The check box in reference to the number of check boxes found.

<Option>

Specifies the status of the check box as Checked or Unchecked.

Description

Use the SetCheckBox command to select or clear a check box.

Example

MessageBox "Scroll down to see the 'Search Language' section with the check boxes then click OK"setcheckbox #1 "checked"
setcheckbox #2 "checked"
setcheckbox #3 "checked"
setcheckbox #4 "checked"
setcheckbox #25 "checked"
setcheckbox #26 "checked"
setcheckbox #27 "checked"
MessageBox "Did it select the first four languages and Norwegian, Polish and Portuguese languages" -yesno ?advweb
if ?advweb eq yes
set ?cmd37 "SetCheckBox command worked" elseset ?cmd37 "SetCheckBox failed"
endifset
checkbox #1 "unchecked"
setcheckbox #2 "unchecked"
setcheckbox #3 "unchecked"
setcheckbox #4 "unchecked"
setcheckbox #26 "unchecked"
setcheckbox #27 "unchecked"
MessageBox "Did it clear all languages except Norwegian" -yesno ?
advweb2
if ?advweb2 eq yes 
   set ?cmd38 "SetCheckBox command worked"
else      
   set ?cmd38 "SetCheckBox failed"
endif

5.2.75 SetCursor

Use with

Terminal Launcher (only available in HLLAPI and some DDE emulators)

Novell SecureLogin version

3.5 or later

Type

Action

Usage 1

SetCursor <Screen-Position>

Usage 2

SetCursor <X Co-ordinate> <Y Co-ordinate>

Arguments

<Screen-Position>

The position on the screen to move the cursor.

<X Co-ordinate>

The horizontal coordinate. When specified, a row or column conversion is carried out before the cursor is set to the position.

<Y Co-ordinate>

The vertical coordinates. When specified, a row or column conversion is carried out before the cursor is set to the position.

Description

Use the SetCursor command to set the cursor to a specified <Screen-Position> or <X Co‑ordinate> <Y Co-ordinate>.

The position is noted by a number greater than 0 (zero), for example, SetCursor 200. Terminal Launcher displays an error message if the screen position is invalid.

Syntax examples

SetCursor 200
SetCursor 100 500

Example

Terminal Launcher application definition

This example sets the cursor to the correct position, and then you enter credentials.

SetCursor 200
Type $Username
Type @E
Type $Password
Type @E

5.2.76 SetFocus

Use with

Java and Windows

Novell SecureLogin version

3.5 or later

Type

Action

Arguments

<#Ctrl-ID>

The ID number of the control to which the keyboard focus is directed.

Description

Use the SetFocus command to set the keyboard focus to a specified control ID.

A valid control ID is required for the SetFocus command to function correctly.

Example

Windows application definition

This example sets the focus to the username field (#1001). The username is typed and a tab stop is simulated, and then the password is typed and pressing Enter is simulated.

# Logon Dialog Box
Dialog 
   Class #32770 
   Title "Log on"
EndDialog

SetFocus #1001
Type $Username
Type \T
Type $Password
Type \N

5.2.77 SetPlat

Use with

All

Novell SecureLogin version

3.5 or later

Type

Action

Usage 1

SetPlat <Application-Name>

Usage 2

SetPlat <RegEx> <Variable> <#Ctrl-ID>

Arguments

<Application-Name>

Application name from which to read the variables.

<RegEx>

Regular expression to use as application name.

<Variable>

Use a previously set ?Variable, for example, using a PickList (see Section 5.2.57, PickListAdd).

<#Ctrl-ID>

The control ID number of the regular expression. For information regarding regular expressions see:

www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html

Description

By default, variables are stored directly against the platform or application on which you have Novell SecureLogin enabled. For example, if you enable Groupwise.exe, the Groupwise credentials are stored against the Groupwise.exe platform.

SetPlat sets the platform or application from which variables are read and saved if you have:

  • Multiple accounts (for example, your own log on and an admin log on) accessing the same platform or application.

  • Multiple platforms or applications using a common set of credentials?

Other uses of SetPlat include:

  • Configuring application1 to read it's $Username and $Password from application2. This saves a user from entering the credentials twice and having to remember to update them in both locations when they change, and so on.

  • Configuring application1, application2, and application3 to read the users credentials from Platform Common. This results in a single store of common credentials which you only need to update once.

Example 1

Web application definition

The following is a standard dialog box for accessing a password‑protected site using Netscape Navigator.

When you specify the Title, Class, User Name, and Password fields for this dialog box they are always the same. If you stored the user name and password against this platform without using the SetPlat command, the same user name and password for www.serversystems.com is entered to log on to any site (and are obviously invalid for any other site).

However, the previous dialog box always contains the name of the Web site to which to log on. You can use this name as the unique identifier in order to set a new platform and to save the log on credentials.

Using a dialog block with a SetPlat statement The solution is to use a dialog block with a SetPlat statement such as:

Dialog 
   Ctrl #330
   Ctrl #214
   Ctrl #331
   Ctrl #1
   Ctrl #2   
   Title "Username and Password Required"   
   SetPlat #331 "Enter username for (.*) at (.*):"
EndDialog
Type $Username #214
Type $Password #330
Click #1

The power of this application definition is the line:

SetPlat #331 "Enter username for (.*) at (.*):"

This reads the line from dialog control ID 331, enters the user name for Control Panel at www.serversystems.com, and applies the regular expression to this text. Regular expressions are a way of manipulating text strings, however, for most purposes a few very basic commands work.

For information regarding regular expressions see:

www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html

When the user has run the application definition, they will see the user name and password saved as www.serversystems.com. The text matched inside the brackets then becomes the symbol application. If a dialog <#Ctrl-ID> is not specified, the symbol application is unconditionally changed to the application specified in <RegEx>. An unconditional SetPlat command is only valid if specified before Dialog/EndDialog statements.

Example 2

Windows application definition

This example displays a pick list and sets a new platform so multiple users can log on to the application. In this case, SetPlat creates a new platform called Default User, Global Administrator, or Regional Administrator, and the respective $Username and $Password is saved there.

# Logon Dialog Box
Dialog
   Class #32770   
   Title "Log on"
EndDialog

PickListAdd "Default User"  
PickListAdd "Global Administrator" 
PickListAdd "Regional Administrator" 
PickListDisplay ?Choice "Please select the account you wish to use"-NoEdit 
SetPlat ?Choice
Type $Username #1001
Type $Password #1002
Click #3

5.2.78 SetPrompt

Use with

All

Novell SecureLogin version

3.5 or later

Type

Action

Usage

SetPrompt <Prompt-Text>

Arguments

<Prompt-Text>

The customized text prompt displayed in the Enter Novell SecureLogin Variables dialog box.

Description

Use the SetPrompt command to customize the text in the Enter Novell SecureLogin Variables dialog boxes. These dialog boxes are used to prompt the user for new variables. You can also use the DisplayVariables command to customize the prompt text in the dialog box (for previously stored variables).

For more information, see Section 5.2.20, DisplayVariables.

NOTE:Positioning of the SetPrompt command is crucial. Position it before the first usage of each variable to name that variable, and apply the final Setprompt to the text displayed at the top of the prompt screen.

Example 1

Windows application definition

This example replaces the default text prompt in the Enter Novell SecureLogin Variables dialog box, and places the SetPrompt command at the bottom of the application definition.

# Logon Dialog Box
Dialog
   Class #32770   
   Title "Log on"
EndDialog
   Type $Username #1001
   Type $Password #1002
   Click #1
SetPrompt "Please enter your user name and password for accessing the Human Resources system.  These credentials will be remembered by SecureLogin and you will be automatically logged on in future. IT Help Desk x4532"

Example 2

Windows application definition

This example replaces the text prompt next to any variable entry field in the Enter Novell SecureLogin Variables box and places the SetPrompt command immediately before the variable in the application definition.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog
SetPrompt "Enter Username==>"
Type $Username #1001
SetPrompt "Enter Password==>
"Type $Password #1002
Click #1
SetPrompt "Please enter your user name and password for accessing the Human Resources system.  These credentials will be remembered by SecureLogin and you will be automatically logged on in future. IT Help Desk x4532"

5.2.79 -SiteDeparted

Use With

Web

Novell SecureLogin version

3.5 or later

Type

Action

Argument

SiteDeparted is a conditional variable.

Description

Use the SiteDeparted variable in Web scripts to see if the current document is still active when used as part of an If statement.

Example

The following example checks if the user has navigated away from the current Web site or not.

If the users have navigated away from the Website, it informs the users and exists the script.

If -SiteDeparted
    MessageBox "Script terminated, we have left the web-site"
    EndScript
EndIf

5.2.80 Site/Endsite

Use with

Advanced Web application definitions created using the Web Wizard.

Novell SecureLogin Version

3.5.x or later

Type

Action

Usage

Site ["Name" [-userid "userid"] [-initial|-subsequent|-recent timeout] [-nonexclusive]]

Arguments

Site

The Site/EndSite commands are used to match a particular site given a set of filters. Site/EndSite usage is much the same as the Dialog/EndDialog commands found in the windows scripting commands.

"Name"

Name is a static string used to denote the site being matched. The Name cannot be a variable and the same value can be used by multiple Site commands to specify a match for the same site under differing conditions.

-userid "userid"

Specifies the default set of credentials to be used for this site block.

NOTE:"userid" must be a static string.

-initial

Specifies that this site block will only match the first time.

-subsequent

Specifies that this site block will only match after an initial match has already been made.

-recent timeout

Specifies that this site block will only match if a previous match was made within the given timeout period.

Timeout is given in milliseconds.

-nonexclusive

Specifies that even if this site block matches, other scripts and wizards will not be prevented from running.

Description

SIte/EndSite begins and ends an application definition, in place of Dialog/EndDialog.

The Site/EndSite commands have been added to allow for much finer control of Web site matching. No longer is a URL all that can be matched on. Detailed information of the loaded Web site can now be matched upon and used to execute blocks of scripting commands.

Site/EndSite blocks are used to define all the parameters Novell SecureLogin would expect to find on a Web page to run the application definition.

'Match' commands can be used to filter a given site. If one of the contained match commands fails to match, then the site block fails to match as a whole.

Example 1

This simple example would locate the Web site www.mybank.com.

# === My Bank Initial Logon ===
Site “www.mybank.com” -userid “My Logon Credentials”
-initial
EndSite

Example 2

This simple example would locate the Web site www.google.com, locate the login form and log on to the user’s account using the user’s e-mail address, account number and password.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site Login -userid “Google Log On” -initial
MatchDomain “www.google.com”
MatchField #1:1 -name “Email” -type “text”
MatchField #1:2 -name “Passwd” -type “password”
MatchField #1:3 -name “Cookie” -type “check”
EndSite
SetPrompt “Enter your user credentials”
TextInput #1:1 -value “$Username”
TextInput #1:2 -value “$Password”
FocusInput#1:2 -focus “true”
BooleanInput #1:3 -check “false”
PressInput
Endscript

5.2.81 StrCat

Use with

All

Novell SecureLogin Version

3.5 or later

Type

Action

Usage

StrCat <Variable> <Input-String1> <Input-String2>

Arguments

<Variable>

The variable to which you want a result saved.

<Input-String1>

First data string or variable.

<Input-String2>

Second data string or variable.

Description

Use the StrCat command to append the second data string to the first data string. For example, StrCat ?Result "SecureRemote " "$Username".

In this case "$Username" is "Tim", and the variable "?Result" now contains the value "SecureRemote Tim".

Example

Windows application definition

This example reads the user name from #1001 into ?Username and uses the StrCat command to join the user name onto the password. The result is a LoginID, which Novell SecureLogin uses to log on to the system.

# Logon Dialog Box
Dialog
   Class #32770 
   Title "Log on"
EndDialog

ReadText #1001 ?Username
StrCat ?LoginID $Username $Password
Type ?LoginID #1002
Click #1

5.2.82 StrLength

Use with

All

Novell SecureLogin version

3.0.4 or later

Type

Variable manipulator

Usage

StrLength <Destination> <String>

Arguments

<Destination>

The output variable. Also the input variable if no source is specified.

<String>

The string whose length you want to measure.

Description

Use the StrLength command to count the number of characters in a variable and output that value to the destination variable.

Example

Windows application definition

This example reads the password from #301 and then uses StrLength to count the number of characters. If it is less that 4, an error message is displayed.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

ReadText #301 ?Password
StrLength ?Length $Password 
If ?Length Lt "4"   
   MessageBox "Password is too short"
EndIf

5.2.83 StrLower

Use with

All

Novell SecureLogin Version

3.0.4 or later

Type

Variable manipulator

Usage

StrLower <Destination> [<Source>]

Arguments

<Destination>

The output variable. Also the input variable if no source is specified.

[<Source>]

The input variable. If not specified, Novell SecureLogin reads the destination variable, makes the necessary changes, and writes over the variable.

Description

Use the StrLower command to modify a variable so that all the characters are lower case.

If only a:

  • Destination variable is specified, the string is read from the destination, then is stored back to it.

  • Source variable is specified, the string is read from the source, and the modified value is stored in the destination variable. In this case, the source variable remains unchanged.

Example

Windows application definition

The example reads the user name from #1001 and copies it into ?Username. The StrLower command is then used to make sure the user name is all lower case.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

ReadText #1001 ?Username
StrLower ?LowerCaseUsername $Username 
Type ?LowerCaseUsername #1002
Click #1

5.2.84 StrUpper

Use with

All

Novell SecureLogin version

3.0.4 or later

Type

Variable manipulator

Arguments

<Destination>

The output variable. Also the input variable if no source is specified.

[<Source>]

The input variable. If not specified, Novell SecureLogin reads the destination variable, makes the necessary changes, and writes over the variable.

Description

Use the StrUpper command to modify a variable so that all the characters are upper case.

If only a:

  • Destination variable is specified, the string is read from the destination and is then stored back to it.

  • Source variable is specified, the string is read from the source, and the modified value is stored in the destination variable. In this case, the source variable remains unchanged.

Example

Windows application definition

This example reads the user name from #1001 and copies it into ?Username. The StrUpper command is then used to make sure the user name is all upper case.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

ReadText #1001 ?Username
StrUpper ?UpperCaseUsername $Username 
Type ?UpperCaseUsername #1002
Click #1

5.2.85 Sub/EndSub

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5 or later

Type

Flow control

Usage

Sub <Name> EndSub

Arguments

<Name>

Any name entered to identify the subroutine.

Description

Use the Sub/EndSub commands around a block of lines within an application definition to denote a subroutine.

You can also call a subroutine using the Call command. For more information, see Section 5.2.8, Call.

Example

Terminal Launcher application definition

This example checks the emulator screen for the text Log On or Wrong Password. If either is found, the appropriate subroutine is called and run before the next part of the application definition.

If -Text "Log On"   
   Call "Log On"
EndIf
If -Text "Wrong Password"   
   Call "WrongPassword"
EndIf
Sub Login
   Type $Username
   Type @E
   Type $Password
   Type @E
EndSub
Sub WrongPassword   
   DisplayVariables "Enter correct password" 
   $Password
   Call Login
EndSub

5.2.86 Submit

Use with

Web

Novell SecureLogin version

3.5 or later

Type

Action

Usage

Submit

Arguments

None

Description

Use the Submit command only in Web application definitions and only with Internet Explorer to allow for enhanced control of how and when a form is submitted. The Submit command performs a Submit on the form in which the first password field is found. The Submit command is ignored if used with Netscape.

The function performed by the Submit command is automatically performed by Web application definitions by default. For example, the application definition:

Type $Username

Type $Password Password

Types the user name and password and submits the form.

When submits do not occur automatically However, submits do not occur automatically if any of the following commands are in the application definition: Type \N, Type \T, Submit, or Click. If any of these commands are used, you must use the Submit command or some other means to submit the form.

Furthermore, an automatic submit does not occur if you type text into a specific text entry field. For example, in the application definition snippet below, the Submit command must follow the Type command for the application definition to work properly:

Type $Username #1001

Submit

Example

Web application definition

This example enters the user name and password and then executes a manual Submit.

Type $Username #1

Type $Password #2

Submit

5.2.87 Substr

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

7.0.3 or later

Type

Action

Usage

SubStr [<var result>] [<var source>] [<var start>] [<var count>]

Arguments

<var result>

The <var result> argument is the variable where the sub text is stored.

<var source>

The <var source> argument is the actual string.

<var start>

The <var start> argument is the index number of the sub text.

<var count>

The <var count> argument is the number of characters from the index number.

Example

Windows application definition

This example displays a subtext from the given string.

Substr ?result abc123ABC!@# 3 6
?result 123ABC

5.2.88 Subtract

Use with

Startup, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.0 or later

Type

Variable manipulator

Usage

Subtract <Start-Value> <Subtract-Value> [?Result]

Arguments

<Start-Value>

The <Start-Value> argument is the start number from which the second argument is subtracted. This argument contains the result if the optional [?Result] argument is not passed in. If used:

  • Without the [?Result] argument, then <Start-Value> must be a Novell SecureLogin variable, for example, ?StartValue or $StartValue.

  • With the [?Result] argument, then <Start-Value> can be a Novell SecureLogin variable or a numeric value.

<Subtract-Value>

The <Subtract-Value> argument is the number subtracted from the first argument. <Subtract-Value> can be a Novell SecureLogin variable or a numeric value.

[?Result]

The result of the equation. This argument is optional but, if used, set to <Start-Value> - <Subtract-Value>. The [?Result] must be a Novell SecureLogin variable, for example, $Result or ?Result.

Description

Use the Subtract command to subtract one value from another.

This is useful if you are implementing periodic password change functionality for an application. You can use the Subtract command (in conjunction with the Divide function and the Slina DLL) to determine the number of days that have elapsed since the last password change. Other numeric commands include the Add, Divide, and Multiply.

For more information see:

NOTE:The Subtract command correctly subtracts when <Start-Value>, <Subtract-Value> and <Result-Value> are between -2147483648 and +2147483647.

Syntax examples:

Subtract "1" "2" ?Result
Subtract ?LoginAttempts ?LoginFailures
Subtract ?LoginAttempts ?LoginFailures ?Result
Subtract ?LoginAttempts "3"
Subtract ?LoginAttempts "3" ?Result

Example

Windows application definition

This example reads the values of control IDs 103 and 104 into variables. From there they are subtracted and typed into control ID 1.

ReadText #103 ?Number1
ReadText #104 ?Number2
Subtract ?Number1 ?Number2 ?Result
Type ?Result

5.2.89 Tag/EndTag

Use with

Advanced Web application definitions

Novell SecureLogin version

3.5 or later

Type

Tag specifier

Usage

Tag

EndTag

Arguments

None

Description

Use the Tag/EndTag commands to find HTML tags.

Example

This example finds the form that has an attribute of Name with a value of Log on.

Tag "Form"   
   Attribute "Name" 
"Log on"EndTag

5.2.90 TextInput

Use with

Advanced Web application definitions created using the Web Wizard.

Novell SecureLogin version

3.5.x or later

Type

Action

Usage

TextInput #FormID:FieldID -value "value"

Arguments

#FormID:FieldID

The ID that was given to the matched field in the Site block using MatchField command. The FormID and FieldID must be unsigned integers.

-value "value"

The text value to be input.

Description

Use the TextInput command after a Site block to input text into a specified field.

You can enter text into fields of type password/text/textarea/file.

Example

In this example the text value of the system user name and password are passed to the application definition.

# === Logon Application Definition #2 ==
# === Google Initial Logon ====
#========================================
Site Login -userid “Google Log On” -initial
MatchDomain “www.google.com”
MatchField #1:1 -name “Email” -type “text”
MatchField #1:2 -name “Passwd” -type “password”
MatchField #1:3 -name “Cookie” -type “check”
EndSite
SetPrompt “Enter your user credentials”
TextInput #1:1 -value “$Username”
TextInput #1:2 -value “$Password”
FocusInput#1:2 -focus “true”
BooleanInput #1:3 -check “false”
PressInput
Endscript

5.2.91 Title

Use with

Java, Windows

Novell SecureLogin version

3.5 or later

Type

Dialog specifier

Usage

Title <Window-Title> [-regex “regular expression”]

Arguments

<Window-Title>

The text to test against the window title.

-regex

You may also use regular expressions to match part of a URL, such as the domain only.

For more information regarding regular expressions see:

www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html

Description

Use the Title command to retrieve the title of a window and compare it against the string specified in the <Window-Title> argument. For this block of the application definition to run, the retrieved window title and the <Window-Title> argument must match the text supplied to the Title command in the dialog block.

Title is one of the main commands to identify a window. However, the Title command alone may not be enough – if there is more than one window in a platform (application) with the specified title, the Novell SecureLogin application definition will run every time that window is detected.

Make Title the first command in the Dialog block to speed the matching process and ensure that all detected controls are also created. However, with some applications, if the text to match is too long, this will slow the detection and creation process. Consequently, if your application definition is unusually slow to execute, try placing the Title command after all other commands in the Dialog block.

For Windows applications, either Title or Class should be defined in a Dialog block at least once.

Uniquely identifying a window To uniquely identify a window, the Title command is typically used with the Class or Ctrl commands. For more information, see Section 5.2.10, Class and Section 5.2.15, Ctrl.

NOTE:Use the Novell Window Finder tool to determine the window title.

Example 1

Windows application definition

This example tests the dialog box to see if it has the correct title. If the title is not correct, the application definition passes on to the next Dialog block.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Logon"
EndDialog

Type $Username #1001
Type $Password #1002
Click #1

Example 2

Windows application definition

This example uses a regular expression to identify the window title.

Dialog
   Title "Logon - Simple"
   Class "#32770"
Parent 
Class "#32770"
Title -regex "training"
EndParent 
Ctrl #1001
Ctrl #1002
Ctrl #1
EndDialog

5.2.92 Type

Use with

Java, Terminal Launcher, Web, or Windows

Novell SecureLogin version

3.5 or later

Type

Action

Terminal usage

Type [-Raw] <Text>

Windows usage

Type <Text> [<#Ctrl-ID>]

Type [-Raw] <Text>

Type [-order] <Text> [<#Order-ID>]

Type [-msg] <Text> [<#Ctrl-ID>]

Web usage

Type <Text> [<#Field-ID>]

Type <Text> ["password"]

Type [-Raw] <Text>

Arguments

[-Raw]

By default, when typing into a terminal emulator or Windows application, Novell SecureLogin verifies that the window exists before continuing. This verification process is disabled when the -Raw argument is provided. Furthermore, instead of setting the text in the field directly, the -Raw argument simulates actual keystrokes, causing Novell SecureLogin to type into whichever window has focus.The ‑Raw argument can also be used in a Web application. The -Raw argument attempts to type the text into the window that owns the Web page (Internet Explorer or Firefox) and works the same as -Raw on Windows applications.

[-order]

If the control ID's are not constant, utilize the -order argument to instruct Novell SecureLogin to type into a control based on the creation order and not the tab order. For more information on the -order argument usage, see Example 5.

[-msg]

The -msg argument can be used when a Type command is sending the data correctly, but the application is not successfully reading the data. The -msg argument will only work in Windows applications as the argument simulates the keys being pressed (that is, key down, character, key up). For Web applications use the ‑Raw argument to get the JavaScript to trigger. The -msg argument sends the data character by character versus sending the text string all at once. This -msg option is often useful for older Windows applications, particularly old versions of Lotus Notes.

<Text>

The text to type into this area. This text can be static text, such as ABC, or any Novell SecureLogin variable, such as $Username.

[<#Ctrl-ID>]

For Windows application definitions, this optional argument specifies the control into which to type the text. Use the Novell Window Finder to extract these control IDs. For more information, see Windows specific.

[<#Order-ID>]

For Windows application definitions, this parameter specifies which control based on the creation order in which to type the text.

[<#Field-ID>]

For Web application definitions, this optional argument specifies the text field into which to type the text. For more information, see Web specific.

[password]

For Web application definitions, this optional argument specifies to perform this type into the password field on this form. If [password] is used, that application's application definition cannot use a <#Ctrl-ID> argument. For more information, see Web specific.

Description

Use the Type command to enter data such as user names and passwords into applications. There are reserved character sequences that are used to type special characters, for example Tab and Enter. If it is not possible to determine control IDs in a Windows application, and the Type command is not working, use the SendKey command instead.

Windows specific In Windows, if the <#Ctrl-ID> argument is:

  • Provided, it must be a number that refers to a control ID as identified by the Window Finder Tool. Novell SecureLogin will then send the contents of the <Text> argument directly to the window and to the specific control that matches the <#Ctrl-ID> argument.

  • Not specified, Novell SecureLogin will send keystrokes to whichever control has focus. In the Windows environment, the -Raw option is often useful when the Window Finder Tool is unable to determine control IDs for the text entry areas of an application, or these control IDs are changing. If using the -Raw option, then you cannot use the <#Ctrl-ID> argument.

Web specific For Web pages, there are two ways to specify which field receives <Text>.

  • The first method uses absolute positioning by means of the <#Field-ID> argument. The <#Field-ID> is a number that refers to the location of the field within the HTML form. For example, #1 refers to the first text entry field in the Web form; #2 refers to the second text entry field, and so on.

  • The second method uses relative positioning using the password argument. In this method the Novell SecureLogin agent first locates the text field within the HTML form that is a password field, and types <Text> into that field. Other type commands send their <Text> parameters to fields that are relative to the first password field.

    For example, the Type command immediately preceding the Type command that has the [Password] argument is sent to the text field immediately preceding the first password field.

Example 1

Windows application definition

This example typifies the use of the Type command in a Windows application definition.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

Type $Username #1001
Type $Password #1002
Type "DB2" #1003
Click #1

Example 2

Windows application definition

This example shows the use of the -Raw switch. This switch is not actually required in this instance, and is only used as an example.

# Calculator Is Active
Dialog
   Class #SciCalc
   Title "Calculator"
EndDialog
Type -Raw "15"
Type -Raw "+"
Type -Raw "20"
Type -Raw "="

Example 3

Windows application definition

This example shows the use of the -msg switch. In this instance the switch is not actually required and is only used as an example of the use of Password as the -msg argument.

# Calculator Is Active
Dialog
   Class #SciCalc
   Title "Calculator"
EndDialog
Type -msg $Password #480".

Example 4

Windows application definition

The following syntax examples compare and contrast the use of the various Type command arguments.

Type #1 "text"

Will type text into control with ID of 1

Type #1 "text" -order

Will type text into the first control found in the dialog when enumerating the children.

Type #1 "text" -msg

Will type text into the first control with an ID of 1 it finds within the set of windows allowing some time for the control to be created.

Type #1 "text" -raw
Type #1 "text" -focus

Ignores the unused parameter #1

Example 5

Windows application definition

This example shows the use of the -order switch and demonstrates the possible “order” of the parameter.

Type -order #1 "some text"
Type #2 "some text" -order
Type "some text" -order #3

Example 6

Web application definition

This example uses the Novell SecureLogin agent to automatically generate this application definition for the mail.yahoo.com site. This example shows the use of password as the [<Field Name>] argument.

Type $Username
Type $Password Password

In the application definition above, the Novell SecureLogin agent locates the first password field. The first Type command sends $Username to the field immediately before the password field. The second Type command sends $Password to the password field. The same application definition could be rewritten using absolute placement as shown below. In the following example, the Submit command is also used to automatically submit the page.

Type $Username #1
Type $Password #2
Submit

Sending keyboard commands using Type

Novell SecureLogin can send special keyboard keystrokes to Windows and Web-based applications to emulate the user's keyboard entry. The Type command can pass keystrokes through to the window that the application definition is working. These special commands include the ability to select menu items, send Alt, and send other keyboard combinations.

Special key commands

Type

Simulates

\Alt+<key>

Pressing the ALT key plus the desired <key>.

\Shift+<key>

Pressing the SHIFT key plus the desired <key>.

\Ctrl+<key>

Pressing the CTRL key plus the desired <key>.

\LWin+<key>

Pressing the left Windows key plus the desired <key>.

\RWin+<key>

Pressing the right Windows key plus the desired <key>.

\Apps+<key>

Pressing the Application key plus the desired <key>.

Raw key commands

You can also use the Type command to send a combination of raw key commands. Section 7.1, Windows Keyboard Functions details the available keyboard sequences you can use with the Type command.

Type

Simulates

\|<xxx>

The format for sending a raw key command, where <xxx> represents the keyboard code.

\|18+65

Pressing the ALT-A keys in sequence.

Type commands used with Terminal Launcher

Terminal Launcher uses the High Level Language Application Programming Interface (HLLAPI) to interface with a wide range of mainframe emulators that implement this programming standard. Listed below are the @ commands that you can use in the Type command. These commands perform specific emulator and mainframe functions. For example, you can send an Enter, Tab, cursor key, issue a mainframe emulator print screen, or reset function.

The @ commands are used in application definition language in the following format:

  • TYPE @ command

  • WAITFORTEXT "Log on:"

  • Type $username

  • Type @T

  • Type $password

  • Type @E

The Section 7.1, Windows Keyboard Functions details the commands that you can use within a Terminal Emulator application definition.

5.2.93 WaitForFocus

Use with

Windows

Novell SecureLogin version

3.5 or later

Type

Flow control

Usage

WaitForFocus <#Ctrl-ID> [<Repeat-Loops>]

Arguments

<#Ctrl-ID>

The ID number of the control with the focus.

[<Repeat-Loops>]

The number of repeat-loops that will run.

Description

Use the WaitForFocus command to suspend the running of the application definition until the <#Ctrl-ID> has received keyboard focus, or the <Repeat-Loops> expire. The <Repeat-Loops> is an optional value that defines the number of loop cycles to run. The <Repeat-Loops> value defaults to 3000 loops if nothing is set. Once focus is received, the application definition continues.

Set the figure to a negative number (for example, WaitForFocus "#1065" "-1") for the <Repeat-Loops> never to expire. If the <Repeat-Loops> is set to 0 (zero), it loops until the window defined in the Dialog/ EndDialog statement is given keyboard focus.

NOTE:Do not place WaitForFocus commands within Dialog / EndDialog statements.

Syntax examples

WaitForFocus #301
WaitForFocus #301 "2000"
WaitForFocus #301 "0"
WaitForFocus #301 "-1"

Example 1

Windows application definition

This example has Novell SecureLogin waiting indefinitely for window 301 to get focus. Once the login dialog box is detected, it enters the user credentials.

# Logon Dialog Box
Dialog
   Class #32770
   Title "Log on"
EndDialog

WaitForFocus #301 "-1"
Type $Username
Type \T
Type $Password
Type \N

Example 2

This example has the WaitForFocus command suspend the running of the appli-cation definition until control ID #15 is reached and a message box with “love” should appear.

## BeginSection: "Logon Window"
Dialog
Class "Notepad"
Title "Untitled - Notepad"
EndDialog
Setprompt "Optional:"
# Here the correct ID with the loops set to 0
WaitForFocus #15 0
Set ?thu "love\me"
RegSplit "(.*)\\(.*)" ?thu ?Domain ?User
MessageBox ?Domain
## EndSection: "Logon Window"

5.2.94 WaitForText

Use with

Terminal Launcher

Novell SecureLogin version

3.5 or later

Type

Flow control

Usage

WaitForText <Text>

Arguments

<Text>

The text for which the application definition is waiting.

Description

Use the WaitForText command to make the Terminal Launcher wait for the specified text to display before continuing. For example, you may make Novell SecureLogin wait for a user name field to display before attempting to type a user name.

The text may appear anywhere on the terminal screen and is usually case sensitive (this depends on the Terminal Emulator itself). If the text is written in the wrong case, the terminal launcher will pause and try to find the correct text in the correct case, until the terminal screen times out.

If WaitForText is not working, try leaving the initial letter off the <Text> to avoid any conflict with case sensitivity. For example, WaitForText logon will work regardless of whether the text ‘log on’ is presented on the terminal screen as Log on or log on. However, WaitForText "Log on" will only work if the word log on is presented on the screen as ‘Log on’.

Also, some terminal emulators will not correctly match text that is hard against the left margin of the window. Again, if you encounter this situation, try to match text without the leading character.

Example

Terminal Launcher application definition

This command instructs Novell SecureLogin to wait for the text ogin: to appear on the emulator screen before entering the user name. It will then wait for assword: to display before entering the password.

WaitForText "ogin:"
Type $Username
Type @E
WaitForText "assword:"
Type $Password
Type @E