Screen Object
Description
The Screen object provides access to SecureCRT's terminal A device usually consisting of a keyboard, a display unit such as a cathode ray tube, and a serial port used for entering and sending data to a computer and displaying any data received from the computer. Terminals are usually connected to a computer with a serial line or some other type of connection. There are many terminal types including VT100, VT102, VT220, and others. screen.
Syntax
Remarks
SecureCRT's
Screen object is accessed through the top-level object’s Screen
property.
Screen Object Properties and Methods
|
|
|
|
|
|
|
|
|
Description
Returns the current column of the cursor.
Remarks
Read-only numeric property. The first column is 1. An error will be returned if there is no connection A data path or circuit between two computers over a phone line, network cable, or other means. open.
VBScript
Syntax
[ varname = ] object.CurrentColumn
Python
Syntax
[ varname = ] object.CurrentColumn
Description
Returns the current row of the cursor.
Remarks
Read-only numeric property. The first row is 1. An error will be returned if there is no connection open.
VBScript
Syntax
[ varname = ] object.CurrentRow
Python
Syntax
[ varname = ] object.CurrentRow
Description
Returns the current number of columns.
Remarks
Read-only numeric property.
VBScript
Syntax
[ varname = ] object.Columns
Python
Syntax
[ varname = ] object.Columns
Description
Allows the script to control whether escape sequences are ignored or not for WaitForString(s) and ReadString methods.
Remarks
The IgnoreEscape property toggles whether ReadString() or WaitForString() recognizes escape sequences. By default, Readstring will capture and look for escape sequences.
VBScript
Syntax
object.IgnoreEscape [ = True | False ]
Example
crt.screen.IgnoreEscape = False
' The following call will return after we receive either an
' 'Escape' or 'BEL' character from the remote
MsgBox crt.screen.Readstring(chr(27), chr(7))
crt.screen.IgnoreEscape = True
' Now that IgnoreEscape is set to true, the following call
' will always time out after 5 seconds because ReadString is
' ignoring non-printable characters
MsgBox crt.screen.Readstring(chr(27), chr(7), 5)
Python
Syntax
object.IgnoreEscape [ = True | False ]
Example
crt.Screen.IgnoreEscape = False
# The following call will return after we receive either an
# 'Escape' or 'BEL' character from the remote
crt.Dialog.MessageBox(crt.Screen.ReadString([chr(27), chr(7)]))
crt.Screen.IgnoreEscape = True
# Now that IgnoreEscape is set to true, the following call
# will always time out after 5 seconds because ReadString is
# ignoring non-printable characters
crt.Dialog.MessageBox(crt.Screen.ReadString([chr(27), chr(7)], 5))
Description
Determines which index within your list of strings was found by the ReadString or WaitForStrings method.
Remarks
Is only useful in combination with either the ReadString or WaitForStrings method.
The crt.Screen.MatchIndex property is used in conjunction with the ReadString method when ReadString is passed multiple strings to wait for. When used, MatchIndex will indicate which string was found by ReadString (1=first_string, 2=second_string, etc.). A MatchIndex value of 0 indicates that a timeout occurred before a match was found.
VBScript
Syntax
[ varname = ] object.MatchIndex
Example
szOutput = crt.Screen.ReadString("error", "warning", "#", 10)
Select Case crt.Screen.MatchIndex
Case 0
MsgBox "Timed out!"
Case 1
MsgBox "Found 'error'"
Case 2
MsgBox "Found 'warning'"
Case 3
MsgBox "Found '#'"
End Select
Python
Syntax
[ varname = ] object.MatchIndex
Example
szOutput = crt.Screen.ReadString(["error", "warning", "#"], 10)
index = crt.Screen.MatchIndex
if (index == 0):
crt.Dialog.MessageBox("Timed out!")
elif (index == 1):
crt.Dialog.MessageBox("Found 'error'")
elif (index == 2):
crt.Dialog.MessageBox("Found 'warning'")
elif (index == 3):
crt.Dialog.MessageBox("Found '#'")
Description
Returns the current number of rows.
Remarks
Read-only numeric property.
VBScript
Syntax
[ varname = ] object.Rows
Python
Syntax
[ varname = ] object.Rows
Description
Returns the current selection.
VBScript
Syntax
[ varname = ] object.Selection
Example
# $language = "VBScript"
# $interface = "1.0"
' GoogleSelectedText.vbs
' send the selected text to the clipboard
crt.Clipboard.Text = crt.Screen.Selection
' Extract the selected text from the clipboard into a variable as "Text"
szSelection = crt.Clipboard.Text
' Now search on Google for the information.
g_szSearchBase = "http://www.google.com/search?hl=en&q="
Set g_shell = CreateObject("WScript.Shell")
g_shell.Run "iexplore " & g_szSearchBase & szSelection
Python
Syntax
[ varname = ] object.Selection
Example
#$language = "Python"
#$interface = "1.0"
import SecureCRT
import webbrowser
# send the selected text to the clipboard
crt.Clipboard.Text = crt.Screen.Selection
# Extract the selected text from the clipboard into a variable as "Text"
szSelection = crt.Clipboard.Text
# Now search on Google for the information.
g_szURL = "http://www.google.com/search?q=" + szSelection
webbrowser.open(g_szURL)
Description
Returns or sets the Synchronous setting of the screen.
Remarks
If Synchronous is False then under certain circumstances a script can miss data sent by the server A computer program that provides services to other computer programs (called clients). Often the computer on which a server program runs is also called a server. The term host is often used as a synonym for server. that it is expecting to see. Synchronous is set to False by default.
VBScript
Syntax
object.Synchronous [ = True | False ]
Example
The following code that waits for two different strings, could potentially miss the second string while it is performing some operation after receiving the first string. In order to prevent this kind of condition, it temporarily sets Synchronous to True:
Syntax
object.Synchronous [ = True | False ]
Example
The following code that waits for two different strings, could potentially miss the second string while it is performing some operation after receiving the first string. In order to prevent this kind of condition, it temporarily sets Synchronous to True:
crt.Screen.Send("someCommand")
crt.Screen.WaitForString("thisString")
... do something else
crt.Screen.WaitForString("thatString")
Description
Clears the screen.
Remarks
None.
VBScript
Syntax
object.Clear
Python
Syntax
object.Clear()
Description
Returns a string of characters read for a portion of the screen.
Remarks
Returns a string containing the characters on the screen rectangle defined by the numeric values row1,col1 (upper-left) and row2,col2 (lower-right).
VBScript
Syntax
object.Get(row1, col1, row2, col2)
Python
Syntax
object.Get(row1, col1, row2, col2)
Description
Returns the characters on each row requested.
Remarks
Returns the characters on each row requested with a \r\n, so the rows can be split by looking for the \r\n sequence. This allows the rows to be different lengths as required by the contents of the rows.
Notes
If your scripts need to work with MBCS languages, you should use the Get2 interface.
VBScript
Syntax
object.Get2(row1, col1, row2, col2)
Python
Syntax
object.Get2(row1, col1, row2, col2)
Description
Provides a global method to set case insensitivity. In addition, case insensitivity can be set per-function as described below in the WaitForStrings, WaitForString, and ReadString methods.
Remarks
If this method is true, the WaitForStrings, WaitForString, and ReadString methods are not case sensitive, otherwise, they are case sensitive (default).
VBScript
Syntax
object.IgnoreCase
Python
Syntax
object.IgnoreCase()
Description
Prints the screen.
Remarks
If no printer is defined on your machine, an error will be returned.
VBScript
Syntax
object.Print
Python
Syntax
object.Print()
Description
Captures data as it is received from the remote.
Remarks
ReadString is similar to the WaitForStrings function except in that ReadString captures data. By default, ReadString will capture all data received from the remote, including escape sequences. To enable or disable the inclusion of escape sequences in the data captured by ReadString, set the Screen.IgnoreEscape property to false/true, respectively. If the remote side is sending escape sequences and Screen.IgnoreEscape is set to true, ReadString will return the string "plug" when "p" was drawn in the upper left corner, "l" in the upper right corner, "u" in the bottom left corner, and "g" in the bottom right corner.
If a timeout parameter is provided, and ReadString reaches the timeout period without receiving the specified string(s) from the remote, ReadString will return an empty string.
Notes
This method takes an optional bCaseInsensitive parameter that defaults to false (case-sensitive wait string matching). It also takes an optional lWaitTimeout parameter, which defaults to "0" if not specified. To specify the bCaseInsensitive parameter, you must also explicitly specify the lWaitTimeout parameter when using this function in a script.
To retrieve a 1-based index of which string ReadString encountered, check the Screen.MatchIndex property.
VBScript
Syntax
[ varname = ] object.ReadString([string1[,string2 ... , stringn]] [, timeoutSeconds] [bCaseInsensitive])
Example
ReadString has the following three usage scenarios:
1. Returns data as soon as it is available from the remote, one character at a time. The syntax for this scenario is:
varname = crt.Screen.ReadString
Example:
char = crt.Screen.ReadString
2. Capture data until a specific string is detected from the remote (similar to how WaitForStrings() is used, except that it captures data). The syntax for this scenario is:
varname = crt.Screen.ReadString(StringToWaitFor [, TimeOutSeconds])
Example:
str = crt.Screen.ReadString("home", 10)
3. Capture data until one of a list of multiple strings is detected from the remote (similar to how WaitForStrings is used, except that it captures data). The syntax for this scenario is:
varname = crt.Screen.ReadString(StringToWaitFor [, StringToWaitFor [, ...]] [, TimeOutSeconds])
or
varname = crt.Screen.ReadString(StringsArray [, TimeOutSeconds])
Examples:
str = crt.Screen.ReadString("home", "work", ... , 10)
or
str = crt.Screen.ReadString(arrayOfStrings, 10)
Python
Syntax
[ varname = ] object.ReadString([stringarray] [, timeoutSeconds] [, bcaseInsensitive])
Example
ReadString has the following three usage scenarios:
1. Returns data as soon as it is available from the remote, one character at a time. The syntax for this scenario is:
varname = crt.Screen.ReadString()
Example:
char = crt.Screen.ReadString()
2. Capture data until a specific string is detected from the remote (similar to how WaitForStrings() is used, except that it captures data). The syntax for this scenario is:
varname = crt.Screen.ReadString(StringToWaitFor [, TimeOutSeconds])
Example:
str = crt.Screen.ReadString("home", 10)
3. Capture data until one of a list of multiple strings is detected from the remote (similar to how WaitForStrings is used, except that it captures data). The syntax for this scenario is:
varname = crt.Screen.ReadString(StringsArray [, TimeOutSeconds])
Example:
str = crt.Screen.ReadString(["home", "work"], 10)
Description
Sends a string of characters.
Remarks
Attempting to send a string while no connection is open returns an error.
Notes
The Send interface works with MBCS languages, and works correctly regardless of whether the display font can represent the characters or not, as long as the select "Character Encoding" for the session can represent the characters.
VBScript
Syntax
object.Send string
Python
Syntax
object.Send(string)
Description
Sends key strokes to the active window.
Remarks
The SendKeys method can send more than one keystroke at a time by using compound string arguments. For example, to send the keystrokes a, b, and c, you would send the string argument "abc". The SendKeys method also uses some characters as modifiers of characters. This set of special characters consists of the plus sign (+), caret (^), percent sign (%), tilde (~), parentheses, brackets, and braces. The characters "+", "^", and "%" perform the functions of SHIFT, CTRL, and ALT, respectively. These can be combined to affect one key as in "^%c" which is the equivalent of the CTRL+ALT+C key combination. Parenthesis characters are used to group characters for modifiers, for example, "+(ec)" will send "EC". SendKeys can use up to three nested parenthesis.
To send bracket characters, send the string argument "{[}" for the left bracket and "{]}" for the right one. To send brace characters, send the string argument "{{}" for the left brace and "{}}" for the right one.
Some keystrokes do not generate characters (such as ENTER and TAB). Some keystrokes represent actions (such as BACKSPACE and BREAK). To send these kinds of keystrokes, send the arguments shown in the SendKeys keystroke table.
VBScript
Syntax
object.SendKeys string
Example
#$language = "VBScript"
#$interface = "1.0"
Sub Main()
crt.Screen.Clear
crt.screen.sendkeys("mc~")
crt.Sleep 2000
crt.screen.sendkeys("{f1}")
crt.Sleep 2000
crt.screen.sendkeys("{esc}0")
crt.Sleep 2000
crt.screen.sendkeys("{esc}0")
crt.Sleep 2000
crt.screen.sendkeys("y")
End Sub
Python
Syntax
SendKeys is not currently supported for Python.
Description
Sends a built-in SecureCRT command. SendSpecial can send any of the Menu, Telnet Telnet is a protocol that provides an interface for communications between clients and servers. , and VT functions listed on the Map Selected Key dialog (accessed by selecting a key in the Keymap Editor and clicking on the Map Selected Key... button).
Remarks
The string parameter to SendSpecial should describe one of the special SecureCRT or protocol functions. Attempting to use SendSpecial while no connection is opened will result in an error.
VBScript
Syntax
object.SendSpecial string
Example
Syntax
object.SendSpecial(string)
Example
crt.Screen.SendSpecial("MENU_PASTE")
crt.Screen.SendSpecial("TN_BREAK")
crt.Screen.SendSpecial("VT_PF1")
Description
Wait for the cursor to change position.
Remarks
The optional timeout parameter specifies the number of seconds to wait for the change. If a change of cursor position is detected WaitForCursor() returns True. If a timeout occurs the function returns False. If no timeout is specified then WaitForCursor() will not time out. An error will be returned if there is no connection open.
VBScript
Syntax
[ result = ] object.WaitForCursor [ timeout ]
Python
Syntax
[ result = ] object.WaitForCursor([timeout])
Description
Wait for a keypress event.
Remarks
The optional timeout parameter specifies the number of seconds to wait for a key event. If key event is detected WaitForKey() returns True. If a timeout occurs the function returns False. If no timeout is specified then WaitForKey() will not time out. An error will be returned if there is no connection open.
VBScript
Syntax
[ result = ] object.WaitForKey [ timeout ]
Python
Syntax
[ result = ] object.WaitForKey([timeout])
Description
Wait for a string.
Remarks
Wait for the string to appear in the input. The timeout (seconds) parameter is optional. When the string is detected in the input WaitForString() returns True. If a timeout occurs the function returns False. An error will be returned if there is no connection open.
Note
This method takes an optional bCaseInsensitive parameter that defaults to false (case-sensitive wait string matching). It also takes an optional lWaitTimeout parameter, which defaults to "0" if not specified. To specify the bCaseInsensitive parameter, you must also explicitly specify the lWaitTimeout parameter when using this function in a script.
VBScript
Syntax
[ result = ] object.WaitForString string [, timeout] [bCaseInsensitive]
Example
Syntax
[ result = ] object.WaitForString(string [, timeout] [, bCaseInsensitive])
Example
if (crt.Screen.WaitForString("ogin:", 10) != True):
crt.Dialog.MessageBox("Failed to detect login!")
Description
Wait for one of several strings to appear in the input.
Remarks
Waits for one of the strings given as arguments to appear in the input. When one of the argument strings is matched in the input, WaitForStrings() returns the argument index of the string that was found (the index of the first string given as an argument to WaitForStrings() is 1). If the optional timeout parameter is specified and a timeout occurs before any of the strings are found, WaitForStrings() returns 0. In the absence of a timeout parameter WaitForStrings() will block without timing out and will not return 0. An error will be returned if there is no connection open.
Notes
If you are using VBScript, WaitForStrings() will accept an array of strings as its first argument followed by an optional timeout. The value returned by WaitForStrings() will be the index of the string found in the array (1st element in the array = 1). A value of 0 will be returned if no strings were found within the timeout period if specified.
The WaitForString(s) interface works with MBCS languages, and depends only on the "Character Encoding" for the session being able to represent the characters being waited for, not on the characters being displayed correctly on the screen.
This method takes an optional bCaseInsensitive parameter that defaults to false (case-sensitive wait string matching). It also takes an optional lWaitTimeout parameter, which defaults to "0" if not specified. To specify the bCaseInsensitive parameter, you must also explicitly specify the lWaitTimeout parameter when using this function in a script.
VBScript
Syntax
[ result = ] object.WaitForStrings string1, [string2, ..., stringn] [, timeout] [bCaseInsensitive]
Example
Syntax
[ varname = ] object.WaitForStrings(StringsArray [, timeout] [, bcaseInsensitive])
Example
result = crt.Screen.WaitForStrings(["foo", "bar", "quux", "gee"], 10)
crt.Dialog.MessageBox(str(result))
if (result == 3):
crt.Dialog.MessageBox("Got quux!")
if (result == 0):
crt.Dialog.MessageBox("Timed out!")