5.2 Commands

This section contains the following information:

5.2.1 Regular Expressions

5.2.2 AAVerify

Table 5-3 Command Description

Use With

Startup, Terminal Launcher, Web and/or Windows

SecureLogin Version

All (Arguments added in version 3.0)

Type

Action

Usage

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

Arguments

  • Method

    The name of the NMAS method you wish to use. If not specified AAVerify uses the method that was chosen during initial authentica-tion to the directory.

    NOTE:You can specify multiple methods.

  • User

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

  • Tree

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

  • [?Result]

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

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

This provides application reauthentication using a strong log on method. For example, a user might be forced to enter their smartcard and PIN before the application logs on using single sign-on, even though the application natively knows nothing about smartcards and PINs. If the verification succeeds, the [?Result] is set to true, otherwise it is set to false.

NMAS Specific: If AAVerify is called with no arguments, then the currently logged on user is reauthenticated using the log on method that they used for their current log on.

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
  • Smartcard
  • 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 using a fingerprint device or a smartcard.

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 8 "BSmith" - Tree "Production" ?Result

Example

Windows Application Definition

This example detects the login dialog box, but before SecureLogin Single Sign-On enters the user's credentials, it prompts the user to provide their Advanced Authentication credentials such as smartcard and 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

5.2.3 ADD

Table 5-4 Description of Add Command

Used With

Startup, Terminal Launcher, Web and/or Windows

SecureLogin Version

3.0

Type

Variable Manipulator

Usage

Add <Variable1> <Variable2> [?Result]

Arguments

<Variable1>

The first argument, the number to which the second argument is added. This argument contains the result of the addition equa-tion 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 vari-able 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 out-put 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 3Add ?LoginAttempts 3 ?Result

Example

Windows Application Definition

This example reads the values of Control IDs 103 and 104 into vari-ables. 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.4 Attribute

Table 5-5 Description of Attribute

Use With

Advanced Web Application Definition

SecureLogin Version

3.5

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 com-mand to specify which HTML attributes and attribute values must exist for that particular HTML tag.

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

Example

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

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

5.2.5 AuditEvent

Table 5-6 Description of AuditEvent

Use With

Startup, Terminal Launcher, Web and Windows applications definitions for those enterprises that have Novell Audit as part of their infrastructure

SecureLogin Version

6.0 SP1

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 will then trigger a log event to the Novell Audit server.

Example

If the Audit platform agent is not present on the workstation, no event 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.6 BeginSplashScreen/EndSplashScreen

Table 5-7 BeginSplashScreen/EndSplashScreen Description

Use with

Terminal Launcher (Generic and Advanced Generic Only)

SecureLogin Version

3.0.4

Type

Action

Usage

BeginSplashScreen

EndSplashScreen

Arguments

None

Description

Use to display a Novell splash screen across the whole Terminal Emula-tor window. This is used to mask any flashing and so on that is produced by SecureLogin scraping the screen for text. A Delay command at the start of the Application Definition ensures the emulator window is in place before the splash screen is displayed.

Example

Terminal Launcher Application Definition

This example launches the emulator and the SecureLogin Single Sign-On waits 2 sec-onds for it to connect. The splash screen is dis-played to cover the flashing, the log on is detected, the username is entered, then the splash screen disappears.

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

5.2.7 Break

Table 5-8 Description of Break

Use With

Startup, Terminal Launcher, Web and Windows

SecureLogin Version

3.5.1

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 Appli-cation Definition continues. If log on is not found, the Application Definition will check again.

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

Example 2

Terminal Application Definition

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

# Initial System Login
WaitForText "ogin:"
Type $Username
Type @E
WaitForText "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

Example 2 (Contd)

#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
EndAccount is locked for some reason, possibly inac-tive.   If -Text "Account Locked"If#
Mes-sageBox "Your account has been locked, possi-bly 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 BooleanInput

Table 5-9 Description of Boolean Input

Use With

Advanced Application Definitions created using the Web Wizard.

SecureLogin Version

3.5.1

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

Table 5-10 Description of Call

Use With

Startup, Terminal Launcher, Web and/or Windows

SecureLogin Version

3.5.1

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 sub-routine 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 immedi-ately following the Call command.

Example

Terminal Application Definition

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

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

Repeat
If -Text "Username"
Call "Log on"   
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 Log on
EndSub

5.2.10 ChangePassword

Table 5-11 Description of ChangePassword

Use With

Startup, Terminal Launcher, Web and Windows

SecureLogin Version

All

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 vari-able and is used in scenarios where password expiry is an issue. Set the <Variable> to the new password.

The flag for this command is Random.

If Random is:

  • Set, the new pass-word 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. For more information see Section 5.2.64, Run.

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 pass-word and confirmation of the new password. The Application Def-inition 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 $PasswordBackupMessageBox "The change password process failed. Please retry the pass-word change at your next log on. IT x453."

5.2.11 Class

Table 5-12 Description of Class

Use With

Startup, Windows

SecureLogin Version

All

Type

Dialog Specifier

Usage

Class <-Class>

Arguments

<Window-Class>

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

Description

When a window is created, it is based on a template known as a win-dow 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 SecureLogin Window Finder tool to determine the win-dow class.

Example

Windows Application Definition

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

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

5.2.12 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 log on 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.

Resolving Issue of Reentering User ID Details

If the log on fails due to incorrect credentials, SecureLogin prompts the user to change the credentials. SecureLogin does not retain User ID details and prompts the user to enter them again. However, this could result in changing the wrong credentials if the user selects the incorrect User ID.

To resolve this issue, you can use the SetPlat, ReLoadPlat and ClearPlat commands. ReloadPlat sets the current User ID to the one which was chosen last 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.

For more information see Section 5.2.61, ReLoadPlat and Section 5.2.12, ClearPlat.

Table 5-13 Description of ClearPlat

Use With

Startup, Terminal Launcher, Web and/or Windows

SecureLogin Version

V.3.6.0 SP1

Type

Action

Usage

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

Application Startup

When an application first starts up, use ClearPlat to clear the previ-ously chosen platform. You can do this in a Windows application by add-ing an extra dialog statement for the main window.

Change Credentials Canceled

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

Successful Log on

Call ClearPlat to allow the user to relog on with a different platform at a later stage

Arguments

None

Description

Use to reset the last chosen platform, causing subsequent calls to ReLoad-Plat 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.13 ClearSite

Table 5-14 Description of ClearSite

Use with

Startup, Terminal Launcher, Web and/or Windows and Advanced Application Definitions created using the Web Wizard.

SecureLogin Version

3.6.10

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

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

Example 2

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

Table 5-15 Description of Click

Use With

Java, Web, Windows

SecureLogin Version

All

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, will send a right mouse click.

  • <X Co-ordinate>

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

  • <Y Co-ordinate>

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

  • <#Number>

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

  • Web specific

    The number of the button is determined by the Web page layout. See Section 5.2.24, EndScript.

  • Windows specific

    This is the control ID. Use the Windows Finder tool to discover the con-trol 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 Single Sign-On 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 win-dow on which the Application Definition is running.

If -Raw is specified, then you can set the X coordinate and the Y coor-dinates. 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 will click the third button on the page. Keep in mind that due to Web page layout and design, the sequential order of the buttons may not be obvious, and that you may have to use the DumpPage command to discover the field layout. For more information see Section 5.2.24, EndScript.

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, enters the username and pass-word, and clicks the button number 1.

# 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 clicks the login button.

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

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

5.2.15 ConvertTime

Table 5-16 Description of ConvertTime

Use With

Startup, Terminal Launcher, Web and Windows

SecureLogin Version

3.0.4

Type

Variable Manipulator

Usage

ConvertTime <time> <String Time>

Arguments

<String Time>

The output variable.

Description

Use to convert a numeric time value, for example,?CurrTime(system), into a legible format and 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) ?TimeMessageBox ?Time

5.2.16 Ctrl

Table 5-17 Description of Ctrl

Use With

Startup, Windows, Java

SecureLogin Version

All

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 con-stant that is established at the time a program is compiled.

Third party software control ID numbers may not be consis-tent 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 Applica-tion Definition will skip to the next dialog statement as though the <#Ctrl-ID> did not exist.

Syntax Examples

Ctrl #1

Ctrl #1 "OK"

Example

Windows Application Definition

This example tests the dialog box to see if it contains the correct Con-trol ID's with the correct values. If any of the Control IDs are miss-ing, 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.17 DebugPrint

Table 5-18 Description of DebugPrint

Use With

All

SecureLogin Version

6.0

Type

Action

Usage

DebugPrint <data>

Arguments

<data> The text displayed to the user.

<Data> can be serveral strings, variables, or a combination of both.

Description

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

Syntax Examples

DebugPrint Caught the login dialog

DebugPrint Setting Platform to ?Platform

Example

Windows Application Definition

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

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

5.2.18 Decrement

Table 5-19 Description of Decrement

Use with

All

SecureLogin Version

3.5.1 to 6.0

Type

Variable Manipulator

Usage

Decrement <variable>

Arguments

<variable>

The name of the variablle 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 particularApplication Definition has made.

Once the number of instances is equal to the specified number, you can instruct the Application Definition to run another task or end the Application Definition. This is useful when configuring an application whose logon 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.

For more information, see Section 5.2.41, Increment/Decrement.

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 log on 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.19 Delay

Table 5-20 Description of Delay

Use with

All

SecureLogin Version

3.5.1 to 6.0

Type

Action

Usage

Delay <Time Period>

Arguments

<Time Period>

A period of time, expressed in milliseconds (1/1000 of a second), dur-ing which the Application Definition execution is paused.

Description

Use the Delay command to delay the execution of the Application Defi-nition for the time specified in the <Time Period> argument

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

Example

Windows Application Definition

This example detects the logon box, but the Application Definition waits half a second before acting upon it to make sure that the box is com-plete.

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

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

5.2.20 Dialog/EndDialog

Table 5-21 Description of Dialog/EndDialog

Use With

Java, Windows

SecureLogin Version

All

Type

Dialog Specifier

Usage

DialogEndDialog

Arguments

None

Description

Use the Dialog/EndDialog command to identify the beginning and end of a dialog specification block respectively. You can use these com-mands to con-struct 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 state-ments 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, Log on, Change Password, and so on) unique.

The portion of the Application Definition that follows the EndDialog command is called the Application Definition body. Another dialog block, or the end of the Application Definition, terminates the Applica-tion Definition body.

Example

Windows Application Definition

This example tests the dialog box in order to determine its identity. If it is deter-mined to be the login dialog 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.21 DisplayVariables

Table 5-22 Description of Display Variables

Use With

All

SecureLogin Version

All

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 on is unsuccessful due to an incorrect username or password, the DisplayVariables command prompts the user to edit the stored username or password values. The log on 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 Dis-playVariables 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 will not be customized.

Once there are variables stored for the user, the prompt is custom-ized when the Application Definition is run.The SetPrompt com-mand can also be used to customize the prompt text in the dialog box.

NOTE:You can use the OnException EnterVariablesCancelled com-mand to prevent a user from canceling the DisplayVari-ables 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 box, and SecureLogin prompts the user to enter a new username and pass-word. Once spec-ified, 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 pass-word"?$Username $Password
Type $Username #1001
Type $Password #1002
Click #1

5.2.22 Divide

Table 5-23 Description of Divide

Use With

Startup, Terminal Launcher, Web and/or Windows

SecureLogin Version

3.0

Type

Variable Manipulator

Usage

Divide <Variable1> <Variable2> [?Result]

Arguments

<Variable1>

The dividend, the first argument, the number that is divided by the sec-ond argument. Also this argument contains the result if the optional [?Result] argument is not passed in. If used without the [?Result] argu-ment, <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 argu-ment 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 ?Login Attempts ?LoginFailures

Divide ?LoginAttempts ?LoginFailures ?Result

Divide ?LoginAttempts "3"

Divide ?LoginAttempts "3" ?Result

Example

Windows Application Definition

This example read the values of Control IDs 103 and 104 into vari-ables. 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.23 DumpPage

Table 5-24 Description of Dump Page

Use With

Advanced Web Application Definition

SecureLogin Version

3.5

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

Table 5-25 Description of EndScript

Use With

Startup, Terminal Launcher, Web and/or Windows

SecureLogin Version

All

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 dialog 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 Defini-tion.

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

Table 5-26 Description of Event

Use With

Windows

SecureLogin Version

3.5

Type

Dialog Specifier

Usage

Event <Event>

Arguments

<Event>

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

Description

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

You can only apply the Event specifier within a Dialog and EndDialog statement block. Only one Event may be specified per Dialog block. If there is a requirement to monitor for multiple events, each must be specified within their own Dialog block.

Syntax Examples

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

5.2.26 Event Specifiers

For details on Windows Event commands, see the Microsoft* MSDN Web site located at http://msdn.microsoft.com. Microsoft's 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.

5.2.27 FocusInput

Table 5-27 Description of FocusInput

Use With

Startup, Terminal Launcher, Web and/or Windows and Advanced Application Definitions created using the Web Wizard.

SecureLogin Version

3.5.1

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

Table 5-28 Description of GenerateOTP

Use With

Startup, Terminal Launcher, Web and Windows

SecureLogin Version

3.5.0 and higher

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 (OTP) 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 OTP based on the user’s smartcard.

-challenge

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

Description

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

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

GenerateOTP was an undocumented command initially developed in SecureLogin version 3.5.1 to meet a specific client requirement and was for use with the Vasco Digipass hard token generator. For information regarding this configuration please contact Novell Technical Support about Mainframe OTP solutions.

In SecureLogin version 6 the GenerateOTP command was enhanced to incorporate OTP soft token generation functionality embedded in Smartcard 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 can even sent to cell phones as SMS text messages.

Synchronous Mode: Synchronous authentication replaces static alpha/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 alpha/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.

The application definition example 1 shows a typical command structure to enable OTP for use with a Vasco Digipass hard token generator.

The application definition example 2 shows a typical command structure to enable OTP for use with the Smartcard technology.

Example

In SecureLogin version 6, the GenerateOTP command has been enhanced to integrate with smartcards.

In Synchronous mode the GenerateOTP command will require the administrator to pass the -mode variable, AISC-SKI to the command.

In this instance AISC-SKI is the Smartcard and SKI is the name of the applet used on the smartcard.

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

Dialog
Title "Test App"
EndDialog
ReadText #12 ?tmp
GenerateOTP -mode "AISC-SKI" -challenge ?tmp ?Otp
Type ?OtpResult #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 over rides 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 may be required to specify the location this library file.

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

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

5.2.29 GetCheckBoxState

Table 5-29 Description of GetCheckBoxState

Use with

Advanced Web Application Definition

SecureLogin Version

3.5

Type

Action

Usage

GetCheckBoxState <#Item Number> <Variable>

Arguments

<Item Number>

The ID of the checkbox.

<Variable>

The target variable for the status of the specified check box. 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 checkbooks.

Example

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

5.2.30 GetCommandLine

Table 5-30 Description of GetCommandLine

Use with

Startup, Windows

SecureLogin Version

3.0.4

Type

Action

Usage

GetCommandLine <Variable>

Arguments

<Variable>

This variable defines where to store the captured command line.

Description

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

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

Example

Windows Application Definition

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

GetCommandLine ?Text 
If ?Text Eq "C:\Winnt\Notepad.exe"  KillApp Notepad.exe
EndIf

5.2.31 GetEnv

Table 5-31 Description of GetEnv

Use with

All

SecureLogin version

3.5

Type

Action

Usage

GetEnv <envvar> <variable>

Arguments

<EnvVar>

This is the environment variable name you wish to retrieve.

<variable>

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

Description

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

Example

Windows Application Definition

GetEnv "SESSIONNAME" ?SessionName
If ?SessionName eq "console"  MessageBox "Run-ning from Citrix Server Console"
EndIf

5.2.32 GetIni

Table 5-32 Description of GetIni

Use With

Windows, Web, Terminal, Java*

SecureLogin Version

3.5

Type

Action

Usage

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

Arguments

<Ini File>

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

<Section>

Name of the section that contains the key name.

<Key>

Name of the key to read.

<variable>

This variable defines where to store the retrieved environment variable data

Description

Use the GetIni command to read data from INI file.

Example

Windows Application Definition

GetIni "c:\program files\lotus\notes\notes.ini" "Notes"? "KeyFileName ?NotesDefaultIDFileSetPlat ?NotesDefaultIDFile

5.2.33 GetMD5

Table 5-33 Description of GetMD5

Use With

All

SecureLogin Version

3.5

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

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 which is then passed in as the argument to the command, which could be a ?tmp or $hash_value type variable.

GetMD5 ?tmp

or

GetMD5 $hash_value

The MD5 hash value would normally be obtained from the windows finder tool on a window from the applicaiton, then copy the MD5 hash from WindowFinder. This MD 5 value would then be put in a script then the GetMD5 command used to compare the two MD5 hash values. If the MD5 hash values do not match, then the excutable file may have been changed.

5.2.34 GetReg

Table 5-34 Description of GetReg

Use With

All

SecureLogin Version

3.5

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""_
?ProductIDIf ?ProductID noteq "xxxxxxxxxx"_
#Not corporate desktop
EndScript
EndIf

5.2.35 GetSessionName

Table 5-35 Description of GetSessionName

Use With

Terminal Emulator

SecureLogin Version

3.5

Type

Action

Usage

GetSessionName <?variable>

Arguments

<Variable>

The target variable that the session name is copied into.

Description

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

Example

Windows Application Definition

GetSessionName ?Session_name

5.2.36 GetText

Table 5-36 Description of GetText

Use With

Web, Terminal Launcher

SecureLogin Version

3.0

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 Defini-tion that might contain several If -Text statements.

Under Netscape, each If -Text statement scans the screen to find the speci-fied text, 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 word Log on. If Log on exists, SecureLogin enters the credentials and sub-mits them automatically.

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

5.2.37 GetURL

Table 5-37 Description of GetURL

Use With

Web

SecureLogin Version

3.0

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

Table 5-38 Description of GoToURL

Use with

Web

SecureLogin version

3.5.1

Type

Action

Usage

GoToURL <URL> [<-frame>]

Arguments

<URL>

The URL to which the browser will navigate.

<-frame>

Opens the URL in the frame which started the Application Definition.

Description

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

When using the -frame option on a framed Web page, the URL redi-rect occurs only in the current frame rather than the parent win-dow.

You must specify http:// before the URL.

Example

Web Application Definition

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

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

5.2.39 If/Else/Endif

Table 5-39 Description of If/Else/Endif

Use with

Startup, Terminal Launcher and/or Windows

SecureLogin version

All

Type

Flow Control

Usage 1

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

Usage 2

If <Value1> <Eq|NEq > <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 <Variable>   #
Do This
[Else]   #
Do This
EndIf

Arguments

<Value1>

The left hand side of the expression for evaluation.

<Value2>

The right hand 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: Evaluates to true if the left hand side is equal to the right hand side.

  • NEq: Evaluates to true if the left hand side is not equal to the right hand side.

  • -In: Evaluates to true if the left hand side is a substring of the right hand side.

  • -NotIn: Evaluates to true if the left hand side is not a substring of the right hand side.

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 NEq operators are not case sensitive, while the -In and -NotIn operators are case sensitive.

Numerical Comparison Operators Supported

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

An operator is supplied to check for the existence of a stored variable:- Exists: Evaluates to true if the specified variable exists.

Finally, an operator is 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.

Syntax Examples

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

# Log on 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
# Log on 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, SecureLogin performs the log on 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 SecureLogin loading, to see if SecureLogin has been run by the user. If it has not, 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 SecureLogin.

If –Exists $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.company.com/SecureLogin
Details.htm”
EndIf
EndIf

5.2.40 Include

Table 5-40 Description of Include

Use With

All

SecureLogin Version

3.0

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 Defini-tion commands by multiple applications. The Application Defini-tion 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 sup-ported by the calling application.

Example

Windows Application Definition

This example detects the logon dialog, 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/Decrement

Table 5-41 Description of Increment/Decrement

Use With

All

SecureLogin Version

All

Type

Variable Manipulator

Usage

Increment <Variable>

Decrement <Variable>

Arguments

<Variable>

The name of the variable to increase or decrease in value.

Description

Use the Increment/Decrement command to add or subtract from a specified variable. For example, you can use the increment and decre-ment to count the number of passes a particular Application Defi-nition has made.

Once the number of instances is equal to the specified number, you can instruct the Application Definition to run another task or end the Application Definition. This is useful when configuring an application whose logon 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.

Syntax examples

Increment ?RunCount

Decrement ?RunCount

Example

Windows Application Definition

Each time the Application Definition is run, a variable is incremented. This example counts the number of times the dialog box is dis-played. If the dialog box is displayed more than three times, the application is closed. If the log on 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

Table 5-42 Description of KillApp

Use With

All

SecureLogin Version

All

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 log on 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

Table 5-43 Description of Local

Use with

All

SecureLogin Version

All

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 vari-ables are used in the same way as normal runtime vari-ables 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 vari-able local at any time in an Application Definition.

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

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 dis-played 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

Table 5-44 Description of MatchDomain

Use With

Advanced Application Definitions created using the Web Wizard.

SecureLogin Version

3.5.1

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 MatchForm

Table 5-45 Description of MatchForm

Use With

Advanced Application Definitions created using the Web Wizard.

SecureLogin Version

3.5.1

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

-name "name"

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

-action "action"

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

-method "method"

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

-target "target"

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

Description

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

Example

In this example the form name “log on” within the web site www.google.com .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 may be a “null”
MatchForm #1 -name “”

5.2.46 MatchField

Table 5-46 Description of MatchField

Use With

Advanced Application Definitions created using the Web Wizard.

SecureLogin Version

3.5.1

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

In this example the web site fields Email, Password and Cookie within the web site www.google.com .com are 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”
MatchField #1:4 -name “SAVEOPTION” -type “checkbox”
-value “YES”
MatchField #1:5 -name “Submit2” -type “submit”
EndSite
SetPrompt “Enter your user credentials”
TextInput #1:1 -value “$Username”
TextInput #1:2 -value “$Password”
FocusInput#1:2 -focus “true”
BooleanInput #1:3 -check “false”
BooleanInput #1:4 -check “false”
PressInput
Endscript

5.2.47 MatchForm

Table 5-47 Description of MatchForm

Use With

Advanced Application Definitions created using the Web Wizard.

SecureLogin Version

3.5.1

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

-name "name"

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

-action "action"

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

-method "method"

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

-target "target"

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

Description

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

Example

In this example the form name “log on” within the web site www.google.com .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 may be a “null”
MatchForm #1 -name “”

5.2.48 MatchOption

Table 5-48 Description of MatchOption

Use With

Advanced Web Application Definitions created using the Web Wizard.

SecureLogin Version

3.5.1 to 6.0

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

Example

This example the form name “log on” within the secure web site www.lotto.com .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.49 MatchReferer

Table 5-49 Description of MatchReferer

Use With

Advanced Web Application Definitions created using the Web Wizard.

SecureLogin Version

3.5.1 to 6.0

Type

Action

Usage

MatchReferer "Referer"

Arguments

MatchReferer

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

"Referer"

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

Description

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

Example

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

Table 5-50 Description of MatchURL

Use With

Advanced Web Application Definitions created using the Web Wizard.

SecureLogin Version

3.5.1

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 which is to be matched. This need not be the URL listed in the navigation field of the web browser as the given page may not have been loaded from there.

Description

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

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

Table 5-51 Description of Message Box

Use With

Startup, Terminal Launcher, Web and Windows

SecureLogin Version

All

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 mes-sage box, rather than being limited to an OK button only.

<-YesNoCancel>

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

<?Variable>

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

<-Background>

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

<-DefaultNo>

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

<Data>

The text displayed to the user. <Data> can be several strings, vari-ables, 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 sus-pended until the user reacts to this message. The MessageBox can take any number of text arguments, including variables, for exam-ple MessageBox "The user " $Username " has just been logged onto the system".

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

Use a runtime <?Variable> to capture the MessageBox result immedi-ately after the flag. The variable value is set to Yes, No, or Can-cel.

Syntax examples

MessageBox "Application Definition completed suc-cessfully"

MessageBox "Do you wish to continue?" -YesNo ?Result

MessageBox "Do you wish to continue?" -YesNoCan-cel ?Result -Background -

DefaultNo

Example 1

Windows Application Definition

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

# Change Password Dialog Box 
Dialog   
Class #32770   
Title "Change Password"
EndDialog
MessageBox -YesNo ?Result "Your password has expired, would you like to change it now?"
If ?Result Eq "Yes"   
Type $Username #1015   
Type $Password #1004   
ChangePassword $Password Random   
Type $Password #1005   
Type $Password #1006   
Click #1   
MessageBox "Password changed successfully"
Else   
Click #2   
MessageBox "You 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 Applica-tion Definition to allow the writer to see where the Application Definition execution if failing.

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

MessageBox "Beginning wait for Log on prompt"
WaitForText "ogin:"
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

Table 5-52 Description of Multiply

Use With

All

SecureLogin Version

3.0

Type

Variable Manipulator

Usage

Multiply <Variable1> <Variable2> [?Result]

NOTE:You must use integer arithmetic.

Arguments

<Variable1>

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

<Variable2>

The multiplier, the second argument, is the number by which the first number is multiplied. <Variable2> can be a 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 num-bers into the Application Definition, or you can use variables. The results can be out-put to another variable, or to one of the original num-bers.

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

Table 5-53 Description of OnException/ClearException

Use With

All

SecureLogin Version

3.0.4

Type

Flow Control

Usage

OnException <Exception Name> Call <SubRoutine>

ClearException <Exception Name>

Arguments

<Exception Name>

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

  1. ChangePasswordCancelled. When a user clicks Cancel on the Change Password dialog box.
  2. EnterVariablesCancelled. When a user clicks Cancel on the automatic variable prompt dialog box.

<SubRoutine>

The name of the subroutine you want to run when the exception condi-tion is true.

Description

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

Syntax examples

OnException ChangePasswordCancelled Call Display

ErrorClearException ChangePasswordCancelled

Example 1

Windows Application Definition

In this example the log on failed because the user has invalid creden-tials stored. This pro-vides the user with an opportunity to verify their user-name and pass-word, but what happens if the user clicks Cancel? If the user clicks Cancel, the exception is executed and forces the user to enter their credentials.

# Log on Failed Dialog Box 
Dialog   
Class #32770 
Title "Log on Failed"
EndDialog
OnException EnterVariablesCancelled Call Vari-ables 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 ver-ification 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 their 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 their user object.

# Change Password Dialog Box 
Dialog
Class #32770
Title “Change Password”
EndDialog
Type $Username #1005
Type $Password #1006
OnException ChangePasswordCancelled Call ForceChangePwd
ChangePassword $Password “Please enter a new password for the Human Resources? application. IT 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

5.2.54 Parent/EndParent

Table 5-54 Description of Parent/EndParent

Use With

Windows

SecureLogin Version

All

Type

Dialog Specifier

Usage

ParentEndParent

Arguments

None

Description

Use the Parent command to begin a Parent block in which the state-ments act upon a window's Parent. The commands that follow the Parent command function identically to commands used in a dialog block; if they equate to false then the Application Definition ends.

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

The Parent command is particularly useful in applications where the dialog box (for example Logon dialog box) is the child of an open win-dow, 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 spec-ify Parent blocks.

You can also use the Parent command to execute commands on a dia-logs parent. For example, it is possible to get a Application Defini-tion 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 sub-ject 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 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 log on. In this case, the parent of the logon 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 Logon windows 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

Table 5-55 Description of PickListAdd

Use With

All

SecureLogin Version

All

Type

Action

Usage

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

Arguments

<Display-Text>

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

<Return-Value>

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

Description

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

You can also use the PickList command to choose from multiple ses-sions on one mainframe account. In fact, 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.

Example

Windows Application Definition

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

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

5.2.56 PickListDisplay

Table 5-56 Description of PickListDisplay

Use With

Startup, Terminal Launcher, Web and/or Windows

SecureLogin Version

All

Type

Action

Usage

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

Arguments

<?Variable>

The output variable for the selected option.

<Display-Text>

The description text for the pick list box.

-NoEdit

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

Description

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

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

Syntax examples

PickListDisplay ?Choice

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

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

Example

Windows Example

In this example, the user has three accounts to this application, and wants to pick which one to use. They pick which account they want to use, and 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

Table 5-57 Description of Position Character

Use With

Password Policy Application Definitions

SecureLogin Version

All

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, upper-case, lowercase, or a punctuation character.

You can specify multiple positions.

Example

The password is not valid unless the first, sixth, and seventh charac-ters are uppercase.

POSITIONCHARACTER UPPERCASE 1,6,7

5.2.58 PressInput

Table 5-58 Description of PressInput

Use With

Advanced Web Application Definitions created using the Web Wizard.

SecureLogin Version

3.5.1

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

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

Table 5-59 Description of ReadText

Use With

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

SecureLogin Version

All

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 exam-ple, row).

<Column-Number>

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

Description

Use the ReadText command to run in both Windows and Terminal Launcher Application Definitions. While the usage and arguments for the use of ReadText with Windows and Terminal Launcher are differ-ent, 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-Num-ber>, and sends those characters to the specified <Variable>. The ReadText command will not work with Generic or Advanced Generic emulators, it only works with HLLAPI and some DDE emulators. For Generic or Advanced Generic emulators use the If -Text or Gettext commands.

For more information, see Section 5.2.39, If/Else/Endif and Section 5.2.36, 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 on.

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

# Log on Failed Message 
Dialog   
Class #32770 
Title "Log on Failed"
EndDialog
ReadText #65535 ?ErrorMsg
Click #1
If "Invalid Username" -In ?ErrorMsg   Display-Variables "Please verify your Username and try again." $Username   
Type $Username #1001   
Type $Password #1002   
Click #1
EndIf
If "Invalid Password" -In ?ErrorMsg   Display-Variables "Please verify your Password and try again." $Password   
Type $Username #1001   
Type $Password #1002 
Click #1
EndIf
If "Account Locked" -In ?ErrorMsg   MessageBox "Your account is locked. Please contact the Help-desk 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

Table 5-60 Description of RegSplit

Use With

All

SecureLogin Version

All

Type

Action

Usage

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

Arguments

<RegEx>

The regular expression.

<Input-String>

The string that to split.

<Output-String1>

The first sub expression.

<Output-String2>

The second sub expression.

Description

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

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 logon screen, SecureLogin displays a message box prompting the user to select an appropriate platform from a list. Once selected, SecureLogin enters the chosen platform's credentials into the application and submits them.

Resolving the Issue of Reentering User ID Details

If log on fails due to incorrect credentials, SecureLogin prompts the user to change their 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 which was last chosen (for the given application), or if a platform not previously selected, the command leaves it unset.

For more information see Section 5.2.61, ReLoadPlat and Section 5.2.12, ClearPlat.

Table 5-61 Description of ReLoadPlat

Use With

Startup, Terminal Launcher, Web and/or Windows

SecureLogin Version

All

Type

Action

Usage

Use the ReLoadPlat command at:

  • Log on. Before the user first logs onto the application, call ReLoadPlat. This prevents the user from having to reselect a platform after a failed log on.
  • Failed Log on. Call ReLoadPlat to reselect the platform that contained the incorrect credentials. This gives the user an opportunity to change the credentials using a ChangePassword or a DisplayVariables command.

Arguments

None

Description

Use to set the current platform to the last one chosen by the Applica-tion Def-inition, 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 Change-Cancelled
ChangePassword $password
ClearException ChangePasswordCancelled 
Type -raw \Alt+F
Type -raw L
# ==== EndSection: Log on Failure ====
# ==== BeginSection: Change Credentials Cancelled
====
Sub ChangeCancelled 
ClearPlat 
EndScriptEndSub
# ==== EndSection: Change Credentials 
Cancelled ===

5.2.62 Repeat/EndRepeat

Table 5-62 Description of Repeat/EndRepeat

Use With

All

SecureLogin Version

All

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 bro-ken 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 End-Script com-mands 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 com-mand to jump to the next repeat loop in the Application Definition.

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

Example (Cont.)

Type $Username 
Type @E     
Delay 500      
WaitForText "password:"      
Type $Password 
Type @E      
Delay 500   
EndIf
# Account is locked for some reason, possibly inactive. 
If -Text "Account Locked" 
MessageBox "Your account has been locked, possibly due to inactivity for 40 days. Please contact the administrator on x453."   
EndIf
# Main Menu, user has logged on successfully.  
If -Text "Application Selection"      
Break   
EndIf
Delay 100
EndRepeat

5.2.63 RestrictVariable

Table 5-63 Description of RestrictVariable

Use With

All

SecureLogin Version

All

Type

Action

Usage

RestrictVariable <Variable-Name>

<Password-Policy>

Arguments

<Variable-Name>

The name of the variable to restrict.

<Password-Policy>

The name of the policy to enforce on the variable.

Description

Use the RestrictVariable command to monitor a <Variable> and enforce a specified <Password-Policy> on the <Variable>. Any vari-able speci-fied must match the policy or it is not saved.

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

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

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

Example 1

Windows Application Definition

This example uses the Application Definition to restrict the $Password variable to the Finance password policy. The user's password must match the policy when they first save their credentials. When the pass-word 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 restricts the ?NewPwd variable to the Finance password policy. When the application starts for the first time and prompts the user to enter their credentials, then their current password ($Password) is saved and used.

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

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

Table 5-64 Description of Run

Use With

Startup, Terminal Launcher, Web and/or Windows

SecureLogin Version

All

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 <Com-mand> with the specified optional [<Arg1> [<Arg2>] …] argu-ments.

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

5.2.65 SelectListBoxItem

Table 5-65 Description of SelectListBoxItem

Use With

Advanced Web Application Definitions

SecureLogin Version

All

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.24, EndScript.

Example

SelectListBoxItem "Remember Defects" #2 -multise-lect

SelectListBoxItem "Remember Enhancements" #2 -multiselect

5.2.66 SendKey

Table 5-66 Description of SendKey

Use With

Terminal Launcher

SecureLogin Version

All

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 clip-board, and then pastes it into the emulator screen. The Send-Key command enters the text directly into the emulator screen.

About using the Type Command

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

The Type command has many special functions, and some you can use with the SendKey command. For more information, see Section 5.2.85, Sending Keyboard Commands Using Type and Section 5.2.84, Type. For more information on these func-tions, see Section 7.0, Reference Commands and Keys.

Example

Terminal Launcher Application Definition

The example sends the username and password to the terminal emu-lator.

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

5.2.67 Set

Table 5-67 Description of Set

Use With

All

SecureLogin Version

All

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.

Descriptions

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

Example 1

Windows Application Definition

This example uses the Application Definition to set a ?RunCount vari-able 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 have 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.68 SetCheckBox

Table 5-68 Description of SetCheckBox

Use With

Advanced Web Application Definition

SecureLogin Version

3.5

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 mes-sagebox"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 lan-guages 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.69 SetCursor

Table 5-69 Description of SetCursor

Use With

Terminal Launcher (Only available in HLLAPI and some DDE emula-tors)

SecureLogin Version

All

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 conver-sion is carried out before the cursor is set to the position.

<Y Co-ordinate>

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

Description

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

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

Syntax examples

SetCursor 200

SetCursor 100 500

Example

Terminal Launcher Application Definition

This example sets the cursor to the correct position, and then you enter cre-dentials.

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

5.2.70 SetFocus

Table 5-70 Description of SetFocus

Use With

Java, Web, Windows

SecureLogin Version

All

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 user-name 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.71 SetPlat

Table 5-71 Description of SetPlat

Use With

All

SecureLogin Version

All

Type

Action

Usage 1

SetPlat <Application-Name>

Usage 2

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

Arguments

<Application-Name>

Application name from which to read the variables.

<RegEx>

Regular expression to use as application name.

<Variable>

Use a previously set ?Variable, for example using a PickList (For more information see Section 5.2.61, ReLoadPlat)

<#Ctrl-ID>

The control ID number of the regular expression.

Description

By default, variables are stored directly against the platform or applica-tion 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 log on and an admin log on) accessing the same platform or application.
  • Multiple platforms or applications using a common set of credentials?

Other uses of SetPlat include:

  • Configuring application1 to read it's $Username and $Password from application2. This saves a user from entering the credentials twice and having to remember to update them in both locations when they change, and so on.
  • Configuring application1, application2, and application3 to read the users credentials from Platform Common. This results in a single store of common credentials which you only need to update once.

Example 1

Web Application Definition

A dialog box appears when you try to access a password‐pro-tected site 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 com-mand, the same Username and Password for www.serversys-tems.com is entered to log on to any site (and are obvi-ously invalid for any other site).

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

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

Example 1 (Contd)

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

When the user has run the Application Definition, they will see 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 uncondi-tionally changed to the application specified in <RegEx>. An unconditional SetPlat command is only valid if specified before Dialog/EndDialog statements.

Example 2

Windows Application Definition

This example displays a pick list and sets a new platform so multiple users can log on to the application. In this case, SetPlat creates a new platform called Default User, Global Administrator, or Regional Admin-istrator, 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.72 SetPrompt

Table 5-72 Description of SetPrompt

Use with

All

SecureLogin Version

All

Type

Action

Usage

SetPrompt <Prompt-Text>

Arguments

<Prompt-Text>

The customized text prompt displayed in the Enter SecureLogin Vari-ables 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 DisplayVari-ables command to customize the prompt text in the dialog box (for previously stored variables).

For more information, see Section 5.2.21, 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 bot-tom 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 Pass-word for accessing the Human Resources sys-tem. 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 com-mand 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 Pass-word for accessing the Human Resources sys-tem. These credentials will be remembered by SecureLogin and you will be automatically logged on in future. IT Helpdesk x4564"

5.2.73 Site/EndSite

Table 5-73 Description of Site/EndSite

Use With

Advanced Web Application Definitions created using the Web Wizard.

SecureLogin Version

3.6.1

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/End-Dialog commands found in the windows scripting commands.

"Name"

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

-userid "userid"

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

NOTE:"userid" must be a static string.

-initial

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

-subsequent

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

-recent timeout

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

Timeout is given in milliseconds.

-nonexclusive

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

Description

SIte/EndSite begins and ends an Application Defintion, 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 SecueLogin would expect to find on a web page to run the applicxation 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 log on to the users account using the users email 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.74 StrCat

Table 5-74 Description of StrCat

Use With

All

SecureLogin Version

All

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 " "$User-name".

In this case "$Username" is "Tim", and the variable "?Result" now con-tains 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 onto the password. The result is a LogonID, which SecureLogin uses to log on 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.75 StrLength

Table 5-75 Description of StrLength

Use With

All

SecureLogin Version

3.0.4

Type

Variable Manipulator

Usage

StrLength <Destination> <String>

Arguments

<Destination>

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

<String>

The string whose length you want to measure.

Description

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

Example

Windows Application Definition

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

# 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.76 StrLower

Table 5-76 Description of StrLower

Use with

All

SecureLogin Version

3.0.4

Type

Variable Manipulator

Usage

StrLower <Destination> [<Source>]

Arguments

<Destination>

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

[<Source>]

The input variable. If not specified, 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 charac-ters are lower case.

If only a:

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

Example

Windows Application Definition

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

# Log on Dialog Box 
Dialog
Class #32770
Title "Log on"
EndDialog
ReadText #1001 ?Username
StrLower ?LowerCaseUsername ?Username 
Type ?LowerCaseUsername #1002
Click #1

5.2.77 StrUpper

Table 5-77 Description of StrUpper

Use With

All

SecureLogin Version

3.0.4

Type

Variable Manipulator

Arguments

<Destination>

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

[<Source>]

The input variable. If 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 charac-ters are upper case.

If only a:

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

Example

Windows Application Definition

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

# Log on Dialog Box
Dialog
Class #32770
Title "Log on"
EndDialog
ReadText #1001 ?Username
StrUpper ?UpperCaseUsername ?Username 
Type ?UpperCaseUsername #1002
Click #1

5.2.78 Sub/EndSub

Table 5-78 Description of Sub/EndSub

Use With

Startup, Terminal Launcher, Web and/or Windows

SecureLogin Version

3.5.1

Type

Flow Control

Usage

Sub <Name> EndSub

Arguments

<Name>

Any name entered to identify the subroutine.

Description

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

You can also call a subroutine using the Call command. For more infor-mation, see Section 5.2.10, ChangePassword.

Example

Terminal Launcher Application Definition

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

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

5.2.79 Submit

Table 5-79 Description of Submit

Use With

Web

SecureLogin Version

All

Type

Action

Usage

Submit

Arguments

None

Description

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

The function performed by the Submit command is automatically per-formed 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.

When Submits Do Not Occur Automatically

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

Furthermore, an automatic submit does not occur if you type text into a specific text entry field. For example, in the Application Definition seg-ment 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.80 Subtract

Table 5-80 Description of Subtract

Use With

Startup, Terminal Launcher, Web and/or Windows

SecureLogin Version

3.0

Type

Variable Manipulator

Usage

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

Arguments

<Start-Value>

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

If used:

  • Without the [?Result] argument, then <Start-Value> must be a SecureLogin variable, for example, ?StartValue or $StartValue.
  • 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 SecureLo-gin 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 Section 5.2.4, Attribute and Section 5.2.22, Divide.

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

Syntax Examples

Subtract "1" "2" ?Result

Subtract ?LoginAttempts ?LoginFailures

Subtract ?LoginAttempts ?LoginFailures ?Result

Subtract ?LoginAttempts "3"

Subtract ?LoginAttempts "3" ?Result

Example

Windows Application Definition

This example reads the values of Control IDs 103 and 104 into vari-ables. 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.81 Tag/EndTag

Table 5-81 Description of Tag/End Tag

Use With

Advanced Web Application Definition

SecureLogin Version

All

Type

Tag Specifier

Usage

TagEndTag

Arguments

None

Description

Use the Tag/EndTag commands to find HTML tags.

Example

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

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

5.2.82 TextInput

Table 5-82 Description of TextInput

Use With

Advanced Web Application Definitions created using the Web Wizard.

SecureLogin Version

3.5.1

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 specied 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.83 Title

Table 5-83 Description of Title

Use With

Java, Windows

SecureLogin Version

All

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 may not be enough - if there is more than one window in a platform (application) with the specified title, the SecureLogin Application Definition will run every time that window is detected.

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

Uniquely Identifying a Window

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

NOTE:Use the SecureLogin Window Finder tool to determine the win-dow 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 Dia-log block.

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

5.2.84 Type

Table 5-84 Description of Type

Use With

Java, Terminal Launcher, Web and/or Windows

SecureLogin version

All

Type

Action

Terminal Usage

Type [-Raw] <Text>

Windows Usage

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

Type [-Raw] <Text>

Web Usage

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

Type <Text> ["password"]

Arguments

[-Raw]

By default, when typing into a Terminal Emulator or Windows applica-tion, 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.

<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 on page 151.

[<#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 on page 151.

[password]

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

Description

Use the Type command to enter data, such as usernames and pass-words 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. For more information see Section 5.2.66, SendKey.

Windows Specific

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

  • Provided, it must be a num-ber that refers to a control ID as identified by the Windows Finder Tool. SecureLogin Single Sign‐On will then send the contents of the <Text> argument directly to the window and to the specific control that matches the <#Ctrl-ID> argument.
  • Not specified, SecureLogin will send keystrokes to whichever control has focus. In the Windows environment, the -Raw option is often useful when the Window Finder Tool is unable to determine control IDs for the text entry areas of an application, or these control IDs are changing. If using the -Raw option, then you cannot use the <#Ctrl-ID> argument.

Web Specific

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

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

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

Web Application Definition

This example uses the SecureLogin agent to automati-cally generate this Application Definition for the mail.yahoo.com site. This example shows the use of Password as the [<Field Name>] argument.

Type $Username 
Type $Password Password

In the Application Definition above, the SecureL-ogin 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.85 Sending Keyboard Commands Using Type

SecureLogin can send special keyboard 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 working. These special commands include the ability to select Menu items, send ALT, and send other keyboard combinations.

Special Key Commands

Table 5-85 Description of 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. For more information on available keyboard sequences you can use with the Type command see Section 7.1, Windows Keyboard Functions.

Table 5-86 Description of Raw Key Commands

Type

Simulates

\|<xxx>

The format for sending a raw key command, where <xxx> repre-sents 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 list are the @ commands 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

For more information on the available terminal emulator commands that you can use within a terminal emulator Application Definition see Section 7.0, Reference Commands and Keys.

5.2.86 WaitForFocus

Table 5-87 Description of WaitForFocus

Use With

Windows

SecureLogin Version

All

Type

Flow Control

Usage

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

Arguments

<#Ctrl-ID>

The ID number of the control with the focus.

[<Repeat-Loops>]

The number of repeat-loops that will run.

Description

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

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

NOTE:Do not place WaitForFocus commands within Dialog / EndDi-alog statements.

Syntax Examples

WaitForFocus #301

WaitForFocus #301 "2000"

WaitForFocus #301 "0"

WaitForFocus #301 "-1"

Example

Windows Application Definition

This example has the SecureLogin waiting indefinitely for window #301 to get focus. Once the Logon 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

5.2.87 WaitForText

Table 5-88 Description for WaitForText

Use With

Terminal Launcher

SecureLogin Version

All

Type

Flow Control

Usage

WaitForText <Text>

Arguments

<Text>

The text for which the Application Definition is waiting.

Description

Use the WaitForText command so the Terminal Launcher waits for the specified <Text> to display before continuing. This command allows the user to wait for particular text to dis-play before continuing. For example, waiting for a username field to display before attempting to type a user-name.

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

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

Also, some terminal emulators will not correctly match text that is hard against the left margin of the window. Again, if you encounter this situ-ation 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 user-name. It will then wait for assword: to display before entering the password.

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