Screen Object
From SecureCRT
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.
A data path or circuit between two computers over a phone line, network cable, or other means.
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.
Telnet is a protocol that provides an interface for communications between clients and servers.
Screen
Object
Description
The Screen object provides access to SecureCRT's terminal 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.
Syntax
[ varname = ] object.CurrentColumn
Remarks
Read-only numeric property. The first column is 1. An error will be returned if there is no connection open.
Description
Returns the current row of the cursor.
Syntax
[ varname = ] object.CurrentRow
Remarks
Read-only numeric property. The first row is 1. An error will be returned if there is no connection open.
Description
Returns the current number of columns.
Syntax
[ varname = ] object.Columns
Remarks
Read-only numeric property.
Description
Allows the script to control whether escape sequences are ignored or not for WaitForString(s) and ReadString methods.
Syntax
object.IgnoreEscape [ = True | False ]
Remarks
The IgnoreEscape property toggles whether ReadString() or WaitForString() recognizes escape sequences. By default, Readstring will capture and look for escape sequences.
Example:
crt.screen.IgnoreEscape = False
' The following call will return after we recieve 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)
Description
Determines which index within your list of strings was found by the ReadString method.
Syntax
[ varname = ] object.MatchIndex
Remarks
Is only useful in combination with the ReadString 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.
Eample:
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
Description
Returns the current number of rows.
Syntax
[ varname = ] object.Rows
Remarks
Read-only numeric property.
Description
Returns or sets the Synchronous setting of the screen.
Syntax
object.Synchronous [ = True | False ]
Remarks
If Synchronous is False then under certain circumstances a script can miss data sent by the server that it is expecting to see. Synchronous is set to False by default.
For 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:
Description
Returns the current selection.
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
Description
Clears the screen.
Syntax
object.Clear
Remarks
None.
Description
Returns a string of characters read for a portion of the screen.
Syntax
object.Get(row1, col1, row2, col2)
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).
Description
Returns the characters on each row requested.
Syntax
object.Get2(row1, col1, row2, col2)
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.
Description
Prints the screen.
Syntax
object.Print
Remarks
If no printer is defined on your machine, an error will be returned.
Description
Captures data as it is received from the remote.
Syntax
[ varname = ] object.ReadString([string1[,string2 ... , stringn]] [, timeoutSeconds])
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.
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)
Note: To retrieve a 1-based index of which string ReadString encountered, check the Screen.MatchIndex property.
Description
Sends a string of characters.
Syntax
object.Send string
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.
Description
Sends key strokes to the active window.
Syntax
object.SendKeys string
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.
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.
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
Description
Sends a built-in SecureCRT command. SendSpecial can send any of the Menu, Telnet, 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).
Syntax
object.SendSpecial string
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.
Examples:
Description
Wait for the cursor to change position.
Syntax
[ result = ] object.WaitForCursor [ timeout ]
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.
Description
Wait for a keypress event.
Syntax
[ result = ] object.WaitForKey [ timeout ]
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.
Description
Wait for a string.
Syntax
[ result = ] object.WaitForString string [, timeout]
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.
Example:
Description
Wait for one of several strings to appear in the input.
Syntax
[ result = ] object.WaitForStrings string1, [string2, ..., stringn] [, timeout]
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.
Example:
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.