5.2 Commands

This section contains information on the following commands:

5.2.1 AAVerify

Use With

Startup, Terminal Launcher, Web, or Windows

SecureLogin Version

3.5 to 6.1 SP1

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 want to use. If a method is 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 want to use for the AAVerify command. If a method is, AAVerify reauthenticates the currently logged-in 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 AAVerify. Set this variable to true for success or false for failure.

?AAVerifyReturnCode

A variable that is set with the error code that is generated from the AAVerify reauthentication process (if any).

Description

Use AAVerify with SecureLogin Advanced Authentication or Novell NMAS to verify the user. It is typically used before the application username and password are retrieved and entered into the login box.

This provides application reauthentication using a strong login method. For example, a user might be forced to enter his or her smart card and PIN before the application login by using single sign-on, even though the application natively knows nothing about smart cards 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.

NMAS Specific

If AAVerify is called with no arguments, then the currently logged-in user is reauthenticated by using the login method that he or she used for the current login.

AA Specific

When AAVerify is called in an AA environment, the method parameter must be present. The method must be one of the following:

  • Any

  • Biometric

  • Smart card

  • Token

  • Password

  • Passphrase

  • Directory

  • Password

  • SecureID

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

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 ACLs 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 SecureLogin enters the user's credentials, it prompts the user to provide the Advanced Authentication credentials (smart card, PIN, biometric, and token)

# Log on Dialog Box
Dialog
Ctrl #32770
Title “Log on”
EndDialog
AAVerify –Method “Enhanced Password” ?Result
If ?Result Eq “True”
Type “$Username” #1001
Type “$Password” #1002
Click #1
Else
MessageBox “Authentication failed! Please verify
your smart card is inserted and your PIN is correct.
IT x453”
EndIf

Example 2

Windows Application Definition

The following example shows the usage of the OnExceptions command as well as the ?AAVerifyReturnedCode.

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

#=============================
# 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. Error "
?AAVerifyReturnCode ". Login cancelled"
EndScript
EndSubg

5.2.2 ADD

Used With

Startup, Terminal Launcher, Web, or Windows

SecureLogin Version

3.0 to 6.1 SP1

Type

Variable Manipulator

Usage

Add <Variable1> <Variable2> [?Result]

Arguments

<Variable1>

The first argument; the number to which the second argument is added. This argument also contains 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 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 SecureLogin variable or numeric value.

[?Result]

Optional. The sum, or the result of the equation.

Description

Adds one number to another. The numbers can be hard-coded 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

SecureLogin Version

3.5 to 6.1 SP1

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.84, Tag/EndTag.

Example

This example finds the form that has an attribute of name with a value of login.

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

5.2.4 AuditEvent

Use With

Startup, Terminal Launcher, Web, or Windows application definitions for those enterprises that have Novell Audit as part of their infrastructure.

SecureLogin Version

6.0

Type

Specifier

Usage

AuditEvent [<message>]

Arguments

<message> The variable or text string passed to the Novell Audit server.

Description

Use AuditEvent to log SecureLogin events to the Novell Audit server.

If the Type command is used with ChangePassword command to generate a $password variable this triggers a log event to the Novell Audit server.

Example

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

AuditEvent “message”

The parameter “message” is the string passed to the Novell Audit server.

AuditEvent $message

The parameter $message is the variable passed to the Novell Audit server.

5.2.5 BeginSplashScreen/EndSplashScreen

Use With

Terminal Launcher (Generic and Advanced Generic Only)

SecureLogin Version

3.0.4 to 6.1 SP1

Type

Action

Usage

BeginSplashScreen

EndSplashScreen

Arguments

None

Description

Use to display a splash screen across the whole Terminal Emulator window. This is used to mask any flashing or other effects that are produced by SecureLogin scraping the screen for text. A Delay command at the start of the application definition ensures that the emulator window is in place before the splash screen is displayed.

Example

Terminal Launcher Application Definition

This example launches the emulator and SecureLogin waits two seconds for it to connect. The splash screen is displayed to cover the flashing, the login is detected, the username 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 by using the Web Wizard.

SecureLogin Version

3.6.1.0 to 6.1 SP1

Type

Action

Usage

BooleanInput #FormID:FieldID -check "check"

Arguments

#FormID

The ID to be given to the matched form. The ID must be a static unsigned integer.

#FieldID

The ID to be given to the matched field. The ID must be a static unsigned integer.

-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 checkbox or radio button).

Example

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

# === Login Application Definition #2 ==
# === Google Initial Login ====
#========================================
Site Login -userid “Google Log On” -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, and Windows

SecureLogin Version

3.5 to 6.1 SP1

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 word 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 checks 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 login (in this case the application main menu appears). After the user has logged in, the Repeat loop is broken and the application definition continues. If the login is not successful, the application definition checks again. Terminal Emulators uses 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

SecureLogin Version

3.5 to 6.1 SP1

Type

Flow control

Usage

Call <SubRoutine>

Arguments

<SubRoutine>

The name of the subroutine called. This name must be identical to the name specified 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 the subroutine completes, the application definition resumes executing from the command immediately following the Call command.

Example

Terminal Application Definition

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

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

Repeat
If -Text "Username"
Call "Login"
EndIf
If -Text "Wrong Password"
Call "WrongPassword"
EndIf
Delay 100
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 verify your password and click OK to retry log
on. IT x453." $Password
Call Login
EndSub

5.2.9 ChangePassword

Use With

Startup, Terminal Launcher, Web, and Windows

SecureLogin Version

3.5 to 6.1 SP1

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 invokes the random password generator.

Description

Use ChangePassword to change a single variable. It is also used 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.63, 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 username and password, and then the 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 failedSet
$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

SecureLogin Version

3.5 to 6.1 SP1

Type

Dialog Specifier

Usage

Class <Window-Class>

Arguments

<Window-Class>

A string specifying the window class that this statement matches.

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 execution of 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 Window Finder tool to determine the window class.

Example 1

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 executes. If false, the application definition checks the next dialog block.

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

Example 2

Java Application Definition

You can now use the dialog statements in Java definitions to specify the class of the window, similar to Windows definitions.

Dialog
Title "Login"
Class "PswFrame"
EndDialog
Messagebox test

The Class information is listed in the definition created by the Add Java Application wizard.

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, SecureLogin directs the user to select an appropriate User ID from a list. SecureLogin enters the selected User ID's credentials into the application and submits them.

If the login fails because incorrect credentials, SecureLogin prompts the user to change the credentials. SecureLogin does not retain User ID details and prompts the user to reenter 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.61, ReLoadPlat and Section 5.2.11, ClearPlat.

Use With

Startup, Terminal Launcher, Web, or Windows

SecureLogin Version

V.3.6.0 to 6.1 SP1

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 him or her a chance to choose a different platform next time.

Successful Login

Call ClearPlat to allow the user to login 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 (Cont.)

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

Startup, Terminal Launcher, Web, Windows, and Advanced application definitions created by using the Web Wizard.

SecureLogin Version

3.6.1.0 to 6.1 SP1

Type

Action

Usage

ClearSite "SiteName"

Arguments

"SiteName"

The name of the site to clear.

Description

Used inside a site block 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.

Example 1

Example 2

In this example, the user is redirected to the main Google portal 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.

MessageBox "Would you like to login again?" -yesno
?Continue
If ?Continue eq "Yes"
TextInput #1:1 -value "$Username"
TextInput #1:2 -value "$Password"
FocusInput #1:2 -focus "true"
BooleanInput #1:3 -check "false"
PressInput
Else
ClearSite Login
EndIf

5.2.13 Click

Use With

Java, Web, Windows

SecureLogin Version

3.5 to 6.1 SP1

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 >]]

Web Usage

Click <#Number>

Arguments

<#Ctrl-ID>

The ID number of the control to be pressed.

[-Raw]

-Raw eliminates the mouse and sends a direct click.

[-Right]

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

<X Co-ordinate>

X represents the horizontal coordinate 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 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 often clicks 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 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.

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 clicks the third button on the page. Keep in mind that due to Web page layout and design, the sequential order of the buttons might not be obvious, and that you might have to use the DumpPage (see Section 5.2.22, DumpPage) command to discover the field layout.

Syntax Examples

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

Example 1

Windows Application Definition

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

# Log on 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 username and password, and then the login 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.

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

5.2.14 ConvertTime

Use With

Startup, Terminal Launcher, Web, and Windows

SecureLogin VersionSecureLogin Version

3.0.4 to 6.1 SP1

Type

Variable Manipulator

Usage

ConvertTime <time> <String Time>

Arguments

<String Time>

The output variable.

Description

Convert a numeric time value, for example, ?CurrTime(system), into a legible format and stores it in <String Time>.

Example

Windows Application Definition

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

# Log on 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

SecureLogin Version

3.5 to 6.1 SP1

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 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.

NOTE:Third-party software control ID numbers might not be consistent from one version to the next. Use the 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 skips 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.

# Log on 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

SecureLogin Version

6.0

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 been logged in to the system").

Syntax Examples

DebugPrint "Caught the login dialog”

DebugPrint "Setting platform to " ?Platform

Example

Windows Application Definition

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

# Login 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

SecureLogin Version

3.5 to 6.1 SP1

Type

Variable Manipulator

Usage

Decrement <Variable>

Arguments

<Variable>

The name of the variable to decrease in value.

Description

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

After 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.41, 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 displayed. If the dialog box is displayed more than three times, the application is closed. If the login is successful, the count is reset.

#Log on 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
# Log on Successful Message
Dialog
Ctrl #1
Title “Log on Successful”
EndDialog
Set ?RunCount “0”

5.2.18 Delay

Use with

All

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Usage

Delay <Time Period>

Arguments

<Time Period>

A period of time, expressed in milliseconds (1/1000 of a second), during which the 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 millisecnsonds (for example, Delay 5000 creates a five 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, but the application definition waits half a second before acting upon it to make sure that the box is complete.

# Log on 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

SecureLogin Version

3.5 to 6.1 SP1

Type

Dialog Specifier

Usage

DialogEndDialog

Arguments

None

Description

Use the Dialog/EndDialog command to identify the beginning and end of a dialog specification block. 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 then 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, Login, 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 parses the Type and Click commands to complete the login process.

# Log on 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

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Usage

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

Arguments

[<User Prompt>]

Optional, customized text displayed in the Enter SecureLogin Variables dialog box.

[<Variables>]

The name of the variables for which you want the user prompted. If not specified, SecureLogin prompts 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 log in is unsuccessful because of an incorrect username or password, the DisplayVariables command prompts the user to edit the stored username or password values. The login process proceeds as normal from that point. You can 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 SecureLogin Variables dialog box.

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

After there are variables stored for the user, the prompt is 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

Windows Application Definition

This example detects the Wrong Password dialog, and SecureLogin prompts the user to enter a new username and password. After they are specified, 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

5.2.21 Divide

Use With

Startup, Terminal Launcher, Web, or Windows

SecureLogin Version

3.0 to 6.1 SP1

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 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 SecureLogin variable or a numeric value.

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

Description

Use to divide one number by another. The numbers can be hard-coded 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 reads 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

SecureLogin Version

3.5 to 6.1 SP1

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

SecureLogin Version

3.5 to 6.1 SP1

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, and SecureLogin enters the username and password, and the user clicks OK. If the Incorrect Password message is detected, SecureLogin displays a message that the password was incorrect, and terminates the application definition.

Dialog   
   Title "Log on 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

SecureLogin Version

3.5 to 6.1 SP1

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 MSDN Web site.

Microsoft Spy++, or similar Windows message spy tools, are also useful for trapping event names in specific windows. Information regarding 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 startup. By adding the Event specifier to a dialog block, you can override this behavior, so 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 can be specified per Dialog block. If there is a requirement to monitor for multiple events, each must be specified within its own dialog block.

For more information, see the MSDN Web site 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, Windows, and Advanced application definitions created by using the Web Wizard.

SecureLogin Version

3.6.1.0 to 6.1 SP1

Type

Action

Usage

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

Arguments

#FormID

The ID to be given to the matched form. The ID must be a static unsigned integer.

#FieldID

The ID to be given to the matched field. The ID must be a static unsigned integer.

-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.

# === Login Application Definition #2 ==
# === Google Initial Login ====
#========================================
Site Login -userid “Google Log On” -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

Use With

Startup, Terminal Launcher, Web and Windows

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Usage

GenerateOTP -mode <string>-challenge <string>

Arguments

<result>

A variable that receives the value of the one time password that is generated.

-mode

Specifies the type one-time password that is dynamically generated. The default value for mode is set to "soft" for the Vasco soft token. Setting this to "AISC-SKI" makes SecureLogin use the algorithm to generate an one-time password based on the user’s smart card.

-challenge

When the one-time password 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

A one-time password is an authentication method specifically designed to avoid the security exposures inherit with traditional fixed and static password usage.

One-time passwords 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 login. If the codes match, the user is authenticated.

GenerateOTP was an undocumented command initially developed in SecureLogin Version 3.5.x to meet a specific client requirement and was for use with the Vasco Digipass hard token generator.

In SecureLogin Version 6, the GenerateOTP command was enhanced to incorporate one-time password soft token generation functionality embedded in smart card functionality.

Soft tokens can be generated in synchronous and asynchronous mode, which now allows soft tokens to be loaded onto mobile devices such PDAs and even be sent to cell phones as SMS text messages.

Synchronous Mode: Synchronous authentication or patented time-plus event authentication replaces static alphabetic and numeric passwords with a pseudo-random code that is dynamically generated at configured time intervals generally around each 60 seconds. 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 alphabetic and numeric 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 needs to be passed to the GenerateOTP command as an argument.

The application definition synchronous example shows a typical command structure to enable one-time password for use with a Vasco Digipass hard token generator.

The application definition asynchronous example shows a typical command structure to enable one-time password for use with Smart Card technology.

Example

In SecureLogin Version 6, the GenerateOTP command has been 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 smart card and SKI is the name of the applet used on the smart card.

An example application definition enabling synchronous one-time password 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 needs to 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 one-time password encryption key distribution for use with smart cards 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 SecureLogin checks for a variable named mode before assuming the default which is to generate a Vasco Token. Values passed into the command via the script override values defined as variables. This is for future integration with 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 might be required to specify the location this library file.

The smart card is assumed to be in the card reader at one-time password generation time and a single card reader is also assumed.

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

5.2.27 GetCheckBoxState

Use with

Advanced Web Application Definition

SecureLogin Version

3.5 to 6.1 SP1

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. The value returned is Checked or 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 box.

Example

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

5.2.28 GetCommandLine

Use with

Startup, Windows

SecureLogin Version

3.0.4 to 6.1 SP1

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:Use the GetCommandLine to detect and differentiate back-end systems and database for use with multiple logins in the SAP* application.

This command is not supported under Windows 95 and Windows 98.

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:\Winnt\Notepad.exe"   KillApp Notepad.exe
EndIf

5.2.29 GetEnv

Use with

All

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Usage

GetEnv <envvar> <variable>

Arguments

<EnvVar>

This is the environment variable name you want 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

SecureLogin Version

Introduced with Novell SecureLogin 6.1

Type

Action

Usage

GetHandle <variable>

Arguments

<Variable>

This variable defines where to store the capture handle.

Description

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

Example 1

Windows Application Definition

GetHandle ?winHandleMessageBox ?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

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Usage

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

Arguments

<Ini File>

This is the filename from which you want 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 ?NotesDefaultIDFile

5.2.32 GetMD5

Use With

Windows

SecureLogin Version

6.0

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 works only with Win32 scripts.

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

The MD5 hash is 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 that 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 is normally obtained from the Windows Finder tool on a window from the application, then the MD5 hash is copied from the Window Finder. This MD5 value is then be put in a script and the GetMD5 command is used to compare the two MD5 hash values. If the MD5 hash values do not match, then the executable file might have been changed.

5.2.33 GetReg

Use With

All

SecureLogin Version

3.5 to 6.1 SP1

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

Description

To get the default value of a Registry key, use two backward slashes (\\) on the command.

This returns the default value.

Example

GetReg HKLM\XYZ\\

This returns the default value set at XYZ.

5.2.34 GetSessionName

Use With

Terminal Emulator

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Usage

GetSessionName <?variable>

Arguments

<Variable>

The target variable that the session name is copied into.

Description

Used to find the current HLLAPI session name that is used to connect and return it to the specified variable.

Example

Windows Application Definition

GetSessionName ?Session_name

5.2.35 GetText

Use With

Web, Terminal Launcher

SecureLogin Version

3.0 to 6.1 SP1

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 a large Web application definition that might contain several If -Text statements.

Under Netscape, each If -Text statement scans the screen to find the specified text, and each scan of the screen results in the screen flashing. However, by 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. SecureLogin tests for the presence of the words “Log on”. If Log on exists, SecureLogin enters the credentials and submits them automatically.

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

5.2.36 GetURL

Use With

Web

SecureLogin Version

3.0 to 6.1 SP1

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, 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 applications. You will now be redirected to the Intranet home page."
   GoToURL "http://Intranet"
EndIf

5.2.37 GoToURL

Use with

Web

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Usage

GoToURL <URL> [<-frame>]

Arguments

<URL>

The URL to which the browser navigates.

<-frame>

Opens the URL in the frame that 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 specify http:// before the URL.

Example

Web Application Definition

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

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

5.2.38 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.39 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 -Exists|-NotExists <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 logon 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.40 Include

Use With

All

SecureLogin Version

3.0 to 6.1 SP1

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 box, the notepad.exe application definition is executed, and then the user's credentials are entered.

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

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

5.2.41 Increment

Use With

All

SecureLogin Version

3.5 to 6.1 SP1

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.

After 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 in is successful, the count is reset.

#Log on 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
 
# Log on Successful Message
Dialog
  Ctrl #1
  Title “Log on Successful”
EndDialog
Set ?RunCount “0”

5.2.42 KillApp

Use With

All

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Usage

KillApp <Process-Name>

Arguments

<Process-Name>

The name of the process to terminate.

Description

Use to terminate an application.

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 login is successful, the count is reset.

#Log on 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

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

Set ?RunCount “0”

5.2.43 Local

Use with

All

SecureLogin Version

3.5 to 6.1 SP1

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 only exists 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.

Description

Using local runtime variables increases the performance of SecureLogin, although only slightly. Local runtime variables are used to run application definitions multiple times and not store 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, SecureLogin alerts the user, then closes the application.

# Invalid Log on Message
Dialog   
   Class #32770   
   Title "Log on Failure"
EndDialog

Local ?RunCount
Increment ?RunCount
If ?RunCount Gt "5"   
   MessageBox "Closing Application"   
   KillApp "PasswordText.exe"
EndIf
Type $Username
Type $Password

5.2.44 MatchDomain

Use With

Advanced application definitions created by using the Web Wizard.

SecureLogin Version

3.6.1.0 to 6.1 SP1

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 http://www.yahoo.com/mymail/login.

Example

This example the Web site www.google.com is being matched by the Application Definition.

# === Login Application Definition #2 ==
# === Google Initial Login ====
#========================================
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.45 MatchField

Use With

Advanced application definitions created by using the Web Wizard.

SecureLogin Version

3.6.1.0 to 6.1 SP1

Type

Action

Usage

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

Arguments

FieldID

The ID to be given to the matched field. The ID must be a static unsigned integer.

-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

  • 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 fails to match.

Example

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

# === Login Application Definition #2 ==
# === Google Initial Login ====
#========================================
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.46 MatchForm

Use With

Advanced application definitions created by using the Web Wizard.

SecureLogin Version

3.6.1.0 to 6.1 SP1

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 a static unsigned integer.

-optional

Specifies that matching this form is not required to successfully match the 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 (MDSN definition).

-method "method"

Specifies the form method to match against. The method or how to send the form data to the server (MDSN definition."

-target "target"

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

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 fails to match.

Example

This example the form name log on within the Web site www.google.com and .com is being matched by the application definition.

# === Login Application Definition #2 ==
# === Google Initial Login ====
#========================================
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 can be a “null”

MatchForm #1 -name “”

5.2.47 MatchOption

Use With

Advanced Web application definitions created by using the Web Wizard.

SecureLogin Version

3.6.1.0 to 6.1 SP1

Type

Action

Usage

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

Arguments

OptionID

The ID to be given to the specific option within the given field. The ID is a static, unsigned integer.

-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 also fails to match.

Example

This example uses the form name “log on” within the secure Web site www.lotto.com and .com is being matched by the application definition.

# === Login Application Definition #4 ==
# === Lotto User Initial Login ====
#========================================
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.48 MatchReferer

Use With

Advanced Web application definitions created by using the Web Wizard.

SecureLogin Version

3.6.1.0 to 6.1 SP1

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 referrer.

Example

In this example, the referring html page “www.lotteries/index.html” is being matched by the application definition.

# === Login Application Definition #5 ==
# === Lotto User Initial Login ====
#========================================
Site Login -userid “Member Log In” -initial
MatchForm #1 -name “log in”
MatchReferer “www.Lotteries.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.49 MatchTitle

Use With

Advanced Web application definitions created by using the Web Wizard.

SecureLogin Version

3.6.1.0 to 6.1 SP1

Type

Action

Usage

MatchTitle "Title"

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 that is to be matched.

Description

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

Example

This example the html page with the title “” within the Web site www.nytimes.com .com is being 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

5.2.50 MatchURL

Use With

Advanced Web application definitions created by using the Web Wizard

SecureLogin Version

3.6.1.0 to 6.1 SP1

Type

Action

Usage

MatchURL "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 that is to be matched. This need not be the URL listed in the navigation field of the Web browser because the given page might not have been loaded from there.

Description

Use Match URL inside a site block to match or filter an HTML page within a Site based on its URL. The URL can be a complex Web address or a secure Web site such as:

https://mymail.com/home/login.php?Home=eb9127d7df248d0e63d92

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

5.2.51 MessageBox

Use With

Startup, Terminal Launcher, Web, or Windows

SecureLogin Version

3.5 to 6.1 SP1

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 responding to the MessageBox. If this parameter is not used, the MessageBox remains the topmost 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 -YesNoCancel 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 been logged in to 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 want 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 elected 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 Log on prompt"
WaitForText "login:"
MessageBox "Log on detected, now entering Username"
Type $Username
MessageBox "Username entered, now simulating Enter"
Type @E
MessageBox "Enter has been simulated. Now waiting for? 
Password"WaitForText "password:"
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.52 Multiply

Use With

All

SecureLogin Version

3.0 to 6.1 SP1

Type

Variable Manipulator

Usage

Multiply <Variable1> <Variable2> [?Result]

NOTE:You must use integer arithmetic.

Arguments

<Variable1>

The Multiply command, which is 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 SecureLogin variable, either ?Variable1 or $Variable1. Otherwise <Variable1> can be any numeric value.

<Variable2>

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

[?Result]

Optional. The product, or result of the equation.

Description

Use to multiply one number by another. You can hard code the numbers into the application definition, or you can 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.53 OnException/ClearException

Use With

All

SecureLogin Version

3.0.4 to 6.1 SP1

Type

Flow Control

Usage

OnException <Exception Name> Call <SubRoutine>

ClearException <Exception Name>

Arguments

<Exception Name>

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

  • AAVerifyCancelled. When a user cancels the reauthentication process (support depends on the Advanced Authentication product being used).

  • AAVerifyFailed. When the AAVerify reauthentication command fails.

  • ChangePasswordCancelled. When a user cancels in the Change Password dialog box.

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

  • GenerateOTPCancelled. When a user cancels the one-time password generation dialog.

  • GenerateOTPFailed. When the GenerateOTP command fails.

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

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

<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 in 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 his or her username and password, but if the user clicks Cancel, the exception is executed and forces the user to enter the credentials.

# Log on Failed Dialog Box
Dialog   
   Class #32770   
   Title "Log on Failed"
EndDialog
OnException EnterVariablesCancelled Call Variables Cancelled
DisplayVariables "Please verify your Username and Password and try again. Helpdesk x5555."
ClearException EnterVariablesCancelled

Type $Username #1001
Type $Password #1002
Click #1
Sub VariablesCancelled   
   OnException EnterVariablesCancelled Call Variables Cancelled 
   Display Variables "You cannot cancel this verification dialog box. Please verify your Username and Password when prompted and click OK to retry log on."   
   ClearException EnterVariablesCancelled
EndSub

Example 2

Windows Application Definition

This example prompts the user to change his or her password. 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 the 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 x5555”
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 x5555”
   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 cancelled"
   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

5.2.54 Parent/EndParent

Use With

Windows

SecureLogin Version

3.5 to 6.1 SP1

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 exist.

The Parent command is particularly useful in applications where the dialog box (for example 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 box’s parent. For example, it is possible to get a application definition to click a button on the parent window. An example of this use is shown in Example 2.

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 work, try by using the Parent command. It is able to handle windows that are within windows, and so on.

Example 1

Windows Application Definition

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

#Log on Dialog BoxDialog   
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.

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

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

5.2.55 PickListAdd

Use With

All

SecureLogin Version

3.5 to 6.1 SP1

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 a value is 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 login.

You can also use the PickListAdd command to choose from multiple sessions on one mainframe account. In fact, you can use the PickList to build a list of databases, phone numbers, or any list from which your 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:This command changed in usage from Novell SecureLogin 6.0 to 6.1. 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 ...

displays the value <not set>

Example 1

Windows Application Definition

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

###Login 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 ?Account
Type $Username #1001
Type $Password #1002
Click #1
###End Login Dialog Box

Example 2

Any Application Definition

In this example, the application should execute when Novell SecureLogin runs. It should display the numbers 1 - 10.

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

Example 3

Windows Application Definition

In this example, SecureLogin SSO reads the Control ID for #1001. (Use Windows Finder to find the Control ID.) SecureLogin should then display everything that is listed in that Control ID.

###Start Login
Dialog
Title "Login"
EndDialog
PickListAdd #1003
PickListDisplay ?Result "Select Database or Server"
SetPlat ?Result
Type $Username #1001
Type $Password #1002
Select ?result #1003
###End Login

Example 4

Java Application Definition

In this example, when SecureLogin SSO runs it reads the Control ID for #1001. (Use Windows Finder to find the Control ID.) SecureLogin SSO should then Display everything that is listed in that Control ID.

In this example, when SecureLogin runs it must display

Create the Java Application Login_User_Pass_Other_List.exe with the following code:

PickListAdd #3
PickListDisplay ?Database "Select your Database" -
noedit
SetPlat ?Database
Type #1 $Username
Type #2 $Password
Select ?Database #3
###End Login##

Example 5

Windows Application Definition

In this example, when SecureLogin runs it displays what you select.

If you Select #Fred, then the message box should display one thing, and if you select #1 then the message box should display other thing. Create the Windows Application ListComboTest.exe with the following code:

###Start ListComboTest
dialog
title "ListTest"
enddialog
PickListAdd #Fred something
PickListAdd #1 otherthing
PickListDisplay ?Result "my message"
Messagebox ?Result
###End ListComboTest##

5.2.56 PickListDisplay

Use With

Startup, Terminal Launcher, Web, and or, or Windows

SecureLogin Version

3.5 to 6.1 SP1

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 his or her 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 for this application, and wants to pick which one to use. After he or she picks which account they want to use, and SecureLogin uses the SetPlat command to switch to that set of credentials.

# Log on 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.57 PositionCharacter

Use With

Password Policy application definitions

SecureLogin Version

3.5 to 6.1 SP1

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.58 PressInput

Use With

Advanced Web application definitions created by using the Web Wizard.

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Usage

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

Arguments

PressInput

Simulates a keyboard enter event, optionally focusing a given field beforehand.

-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 On button on the www.google.com Web site.

# === Login Application Definition #2 ==
# === Google Initial Login ====
#========================================
# === Login Application Definition #2 ==
# === Google Initial Login ====
#========================================
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.59 ReadText

Use With

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

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Windows Usage

Terminal Launcher Usage

ReadText <#Ctrl-ID> <?Variable>

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

Arguments

<#Ctrl-ID>

The control ID number of the text to read.

<?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. Although 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 does 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.39, If/Else/EndIf and Section 5.2.35, GetText.

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

Syntax examples

ReadText #301 ?Text
ReadText ?Text 4 6

Example 1

Windows Application Definition

The same Title and Class appear in the error message dialog box when a user fails to log in.

This example distinguishes between errors and provides users with more specific information, rather than a general message stating that 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.

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

ReadText #65535 ?ErrorMsg
Click #1
If "Invalid Username" -In ?ErrorMsg   DisplayVariables "Please verify your Username and try again." $Username   
   Type $Username #1001   
   Type $Password #1002   
   Click #1
EndIf
If "Invalid Password" -In ?ErrorMsg   DisplayVariables "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 Helpdesk on x3849."   
Endscript
EndIf

Example 2

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.

# Log on 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 3

Terminal Launcher Application Definition

This example reads a message in a Terminal Emulator and displays the message in a user-friendly format.

ReadText ?Message 30 24 2
MessageBox ?Message

5.2.60 RegSplit

Use With

All

SecureLogin Version

3.5 to 6.1 SP1

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 subexpression.

<Output-String2>

The second subexpression.

Description

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

For more information on regular expression, see the Electronic Text Center or search the Microsoft MSDN library.

Example

Windows Application Definition

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

# Log on 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

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.61 ReLoadPlat

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

If login fails because of incorrect credentials, SecureLogin prompts the user to change his or her credentials. SecureLogin does not retain the platform details and prompts the user to reenter 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 that was last chosen (for the given application), or if a platform not previously selected, the command leaves it unset.

See also Section 5.2.61, ReLoadPlat and Section 5.2.11, ClearPlat.

Use With

Startup, Terminal Launcher, Web, or Windows

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Usage

Use the ReLoadPlat command at:

  • Login: Before the user first logs onto the application, call ReLoadPlat. This prevents the user from having to reselect a platform after a failed login.

  • Failer Login: Call ReLoadPlat to reselect the platform that contained the incorrect credentials. This gives the user an opportunity to change the credentials by using a ChangePassword or a DisplayVariables command.

Arguments

None

Description

Use this command 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 (Cont.)

# ==== 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 
   EndScriptEndSub
# ==== EndSection: Change Credentials 
Cancelled ===

5.2.62 Repeat/EndRepeat

Use With

All

SecureLogin Version

3.5 to 6.1 SP1

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. 

Example (Cont.)

   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.63 RestrictVariable

Use With

All

SecureLogin Version

3.5 to 6.1 SP1

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 for 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 by using policies, if you are using a more restrictive policy than is already in place, and you restrict a variable that does not match the policy now in effect, then the user cannot save it the first time. This is because when SecureLogin detects that there is no saved credential, a user who has a password of six characters, cannot save it if the policy restricts the $Password variable to eight characters and two numbers.

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

You can restrict any variable by 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 he or she first saves the 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

#Log on 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 restrict the ?NewPwd variable to the Finance password policy. When the application starts for the first time and prompts the user to enter his or her credentials, then the 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 more restrictive password policies than are currently in place when you cannot guarantee that all existing passwords meet the new policy.

# Set the Password to use the Finance Password Policy
RestrictVariable ?NewPwd FinancePwdPolicy
# Log on 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.64 Run

Use With

Startup, Terminal Launcher, Web, or Windows

SecureLogin Version

3.5 to 6.1 SP1

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

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 FinanceSystem. Please do so manually."   
EndScript
EndIf

5.2.65 Select

Use With

Java and Advanced Web application definitions.

SecureLogin Version

Introduced in version 6.1.000

Type

Action

Usage

Select <Text of Item to select> [<#Item Number>]

Arguments

<Text of Item to select>

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

<#Item Number>

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

Description

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

Examples

This example picks an item from the session list/comb :

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.66 SelectListBoxItem

Use With

Advanced Web application definitions

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Usage

SelectListBoxItem <Text of Item to set to> [<#Item Number>] [<-multiselect>]

Arguments

<Text of Item to set to>

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

<#Item Number>

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

<-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 instruction on determining item numbers, see Section 5.2.22, DumpPage.

Example

SelectListBoxItem "Remember Defects" #2 -multiselect
SelectListBoxItem "Remember Enhancements" #2 -multiselect

5.2.67 SelectOption

Use With

Advanced Web application definitions created by using the Web Wizard.

SecureLogin Version

3.6.1.0 to 6.1 SP1

Type

Action

Usage

SelectOption <#FormID:FieldID:OptionID -select "select" | #FormID:FieldID -clear>

Arguments

SelectOption

Used to select or deselect options within a list box or combo box.

-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 selects the Default User and sets a new platform so that only the default user can log in to the application. In this case, SetPlat creates a new platform called Default and the respective $Username and $Password are saved there.

# log on Dialog Box
Dialog
Class #32770   
Title "Log on"
EndDialog
SelectOption "Default User" 
SetPlat ?Default
Type $Username #1001
Type $Password #1002
Click #3

5.2.68 SendKey

Use With

Terminal Launcher

SecureLogin Version

3.5 to 6.1 SP1

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.

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.87, Type, and for more details on these functions, see Section 7.0, Reference Commands and Keys.

Example

Terminal Launcher Application Definition

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

#Send Username
SendKey "writer"
SendKey "\N"
#Send Password
SendKey "Hu7%f"
SendKey "\N"

5.2.69 Set

Use With

All

SecureLogin Version

3.5 to 6.1 SP1

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.

Description

Use the Set command to copy the value of <Data> into <Variable>. The <Data> can be any text, or another variable, but 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.

# Log on 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.

# Log on 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 Ctrl #15, and sets the $Database variable so the user does not need to set the variable.

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

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

5.2.70 SetCheckBox

Use With

Advanced Web Application Definition

SecureLogin Version

3.5 to 6.1 SP1

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 so you can see the 'Search Language' section and all the Languages with the check boxes then click OK on this messagebox"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 the languages except Norwegian" -yesno ?
advweb2
if ?advweb2 eq yes 
set ?cmd38 "setcheckbox command worked"
else      
set ?cmd38 "setcheckbox failed"
endif

5.2.71 SetCursor

Use With

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

SecureLogin Version

3.5 to 6.1 SP1

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 <ScreenPosition> 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.72 SetFocus

Use With

Java, Web, Windows

SecureLogin Version

3.5 to 6.5

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 <#Ctrl-ID>.

A valid <#Ctrl-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.

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

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

5.2.73 SetPlat

Use With

All

SecureLogin Version

3.5 to 6.1 SP1

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, such aa PickList (see Section 5.2.55, PickListAdd).

<#Ctrl-ID>

The control ID number of the regular expression.

NOTE:For information regarding regular expressions, see Electronic Text Center.

Description

By default, variables are stored directly against the platform or application on which you have 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 login and an admin login) 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 its $Username and $Password from application2. This saves a user from entering the credentials twice and needing to remember to update them in both locations when they change, and so on.

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

Example 1

Web Application Definition

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

When you specify the Title, Class, Username, and Password fields for this dialog box, they are always the same. If you stored the Username and Password against this platform without using the SetPlat command, the same Username and Password for www.serversystems.com are entered to log in 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 in. You can use this name as the unique identifier in order to set a new platform and to save the login 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 username for Control Panel at www.serversystems.comNext, 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 Electronic Text Center.

When the user runs the application definition, he or she sees the username 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 in 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.

# log on 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.74 SetPrompt

Use with

All

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Usage

SetPrompt <Prompt-Text>

Arguments

<Prompt-Text>

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

Description

Use the SetPrompt command to customize the text in the Enter 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 SecureLogin Variables dialog box, and places the SetPrompt command at the bottom of the application definition.

# Log on Dialog Box
Dialog
Class #32770
Title "Log on"
EndDialog
Type $Username #1001
Type $Password #1002
Click #1
SetPrompt "Please enter your Username 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 Helpdesk x4564"

Example 2

Windows Application Definition

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

# Log on 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 Username 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 Helpdesk x4564"

5.2.75 -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.76 Site/Endsite

Use With

Advanced Web application definitions created by using the Web Wizard

SecureLogin Version

3.6.1 to 6.1 SP1

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 only matches the first time.

-subsequent

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

-recent timeout

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

The timeout is given in milliseconds.

-nonexclusive

Specifies that even if this site block matches, other scripts and wizards are not 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 SecureLogin expects 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 Login ===
Site “www.mybank.com” -userid “My Login Credentials”
-initial
EndSite

Example 2:

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

# === Login Application Definition #2 ==
# === Google Initial Login ====
#========================================
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.77 StrCat

Use With

All

SecureLogin Version

3.5 to 6.1 SP1

Type

Action

Usage

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

Arguments

<Variable>

The variable to which you want to 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 username from #1001 into ?Username and uses the StrCat command to join the username to the password. The result is a LogonID, which SecureLogin uses to log in to the system.

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

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

5.2.78 StrLength

Use With

All

SecureLogin Version

3.0.4 to 6.1 SP1

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 than 4, an error message is displayed.

# Log on 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.79 StrLower

Use with

All

SecureLogin Version

3.0.4 to 6.1 SP1

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 a variable is not specified, 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 lowercase.

If only a:

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

  • If only a 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 username from #1001 and copies it into ?Username. The StrLower command is then used to make sure the username is all lowercase.

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

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

5.2.80 StrUpper

Use With

All

SecureLogin Version

3.0.4 to 6.1 SP1

Type

Variable Manipulator

Arguments

<Destination>

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

[<Source>]

The input variable. If a variable is not specified, 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 uppercase.

If only a:

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

  • If only a 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 username from #1001 and copies it into ?Username. The StrUpper command is then used to make sure the username is all uppercase.

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

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

5.2.81 Sub/EndSub

Use With

Startup, Terminal Launcher, Web, or Windows

SecureLogin Version

3.5 to 6.1 SP1

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 by 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 login 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.82 Submit

Use With

Web

SecureLogin Version

3.5 to 6.1 SP1

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 it is used with Netscape.

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

Type $Username 
Type $Password Password

Types the username and password and submits the form.

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 segment 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 username and password and then executes a manual Submit.

Type $Username #1

Type $Password #2

Submit

5.2.83 Subtract

Use With

Startup, Terminal Launcher, Web, or Windows

SecureLogin Version

3.0 to 6.1 SP1

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:

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

  • If used with the [?Result] argument, then <Start-Value> can be a 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 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 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 <StartValue>, <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.84 Tag/EndTag

Use With

Advanced Web Application Definition

SecureLogin Version

3.5 to 6.1 SP1

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 in.

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

5.2.85 TextInput

Use With

Advanced Web application definitions created by using the Web Wizard.

SecureLogin Version

3.6.1.0 to 6.1 SP1

Type

Action

Usage

TextInput #FormID:FieldID -value "value"

Arguments

#FormID

The ID to be given to the matched form. The ID must be a static unsigned integer.

#FieldID

The ID to be given to the matched field. The ID must be a static unsigned integer.

-value "value"

The text value to be input.

Description

Used inside a site block to input text into a specified field.

Example

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

# === Login Application Definition #2 ==
# === Google Initial Login ====
#========================================
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.86 Title

Use With

Java, Windows

SecureLogin Version

3.5 to 6.1 SP1

Type

Dialog Specifier

Usage

Title <Window-Title>

Arguments

<Window-Title>

The text to test against the window title.

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 might not be enough. If there is more than one window in a platform (application) with the specified title, the SecureLogin application definition runs every time that window is detected.

Always place the Title command after all other commands in the Dialog block.

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 Window Finder tool to determine the window title.

Example

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.

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

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

5.2.87 Type

Use With

Java, Terminal Launcher, Web, or Windows

SecureLogin Version

3.5 to 6.1 SP1

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"]

Arguments

[-Raw]

By default, when typing into a Terminal Emulator or Windows application, SecureLogin verifies that the window exists before continuing. This verification process is disabled when the -Raw argument is provided. Further, instead of trying to set the text in the field directly, this option simulates actual keystrokes, causing SecureLogin to type into whichever window has focus.

[-order]

If the control IDs are not constant, utilize the -order switch to type into a control based on the creation order and not the tab order.

[-msg]

This option can be used when a Type command is sending the data correctly, but the application is not successfully reading the data. The -msg modifier 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 older versions of Lotus* Notes*.

<Text>

The text to type into this area. This text can be static text, such as ABC, or any 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 Windows Finder tool to extract these control IDs. For more information, see Windows-Specific:.

[<#Order-ID>]

For Windows application definitions, this parameter specifies the control (based on the creation order) into 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 this 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 usernames 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:

  • If the <#Ctrl-ID> argument is provided, it must be a number that refers to a control ID as identified by the Windows Finder tool. SecureLogin then sends the contents of the <Text> argument directly to the window and to the specific control that matches the <#Ctrl-ID> argument.

  • f the <#Ctrl-ID> argument is not specified, SecureLogin sends 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 you are 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 <#FieldID> 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 position using the password argument. In this method the 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 is a typical use of the Type command in a Windows application definition.

# Log on 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 there 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 shown 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"

Types type text into control with ID of 1

type #1 "text" -order

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


type #1 "text" -msg

Types 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 SecureLogin agent to automatically generate this application definition for the mail.yahoo.com Web site. This example shows the use of Password as the [<Field Name>] argument.

Type $Username
Type $Password Password
In the Application Definition above, the 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

5.2.88 Using the Type Command to Send Keyboard Commands

SecureLogin can send special keystrokes to Windows and Internet based applications to emulate the user's keyboard entry. The Type command can pass keystrokes through to the window that the application definition is using. These special commands include the ability to select menu items, send Alt key combinations, 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. The Section 7.2, 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. The commands are the ones that you can use in the SecureLogin application definition Type command. These commands perform specific emulator and mainframe functions. For example, you can send an Enter, Tab, or cursor key or 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

Section 7.2, Windows Keyboard Functions details the available terminal emulator commands that you can use within a terminal emulator application definition.

5.2.89 WaitForFocus

Use With

Windows

SecureLogin Version

3.5 to 6.1 SP1

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 runs.

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. After 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 the SecureLogin waiting indefinitely for window #301 to get focus. After the login dialog box is detected, it enters the user credentials.

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

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

Example 2

This second example uses the WaitForFocus command to suspend the running of the application definition until <#Ctrl-ID> #15 is reached and a message box with “love” appears.

## BeginSection: "Global Script Configuration"
## EndSection: "Global Script Configuration"
## BeginSection: "Login 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: "Login Window"

5.2.90 WaitForText

Use With

Terminal Launcher

SecureLogin Version

3.5 to 6.1 SP1

Type

Flow Control

Usage

WaitForText <Text>

Arguments

<Text>

The text for which the application definition is waiting.

Description

Use the WaitForText command to have the Terminal Launcher wait for the specified <text> to display before continuing. This command allows the user to wait for particular text to display before continuing. For example, waiting for a username field to display before attempting to type a username.

The <Text> can 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 pauses and tries 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 login works regardless of whether the word log on is presented on the terminal screen as Log on or log on. However, WaitForText "Log on" only works if the phrase log on is presented on the screen as "Log on".

Also, some terminal emulators do not correctly match the 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 uses the SecureLogin to wait for the text “ogin” to appear on the emulator screen before entering the username. It then waits for “assword:” to display before entering the password.

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