Emulator functions

The emulator built-in functions perform actions related to the navigation and display of data in the terminal session. The session must be connected to a host in order for these functions to execute. If the session is not connected, the function will return with a default value of zero for numeric return values or a null string for string values. If the function fails, a negative one (-1) will be returned.

Locations on the screen are referenced by Row/Column or by buffer offset (relative 0). Thus, the top left position would be Row 1, Column 1 or Location 0. Functions that take a screen position accept either form. Screen locations (buffer offsets) yield different Row/Column values depending on the screen size. For example, if the terminal has 24 rows and 80 bytes, location 80 will be row 2, col 1. However, if it is a model 5, location 80 will be row 1, col 81.

Disconnect

Disconnects the current session from the host. The script terminates when the session disconnects.

Parms: None
Return: Returns 0 if success; -1 if an error

Example:

disconnect a ( ); // disconnects the current session

FindString

Use FindSring to find the string specified anywhere on the screen.

Parms: Arg1 - string to search for
Return: Returns the location of the string, or -1 if the string was not found or the session gets disconnected

Example:

user = findString("Userid"); // find the string "Userid" and return its 
location if ((findString("OMEGAVIEW") > 0) // is this the correct screen?

GetCursor

GetCursor returns the current location of the cursor. This is the buffer offset.

Parms: None
Return: Returns the relative location of the cursor, or -1 if an error occurs or the terminal gets disconnected

Example:

Pos = getCursor(); // returns the cursor position

GetCursorCol

GetCursorCol returns the current column number of the cursor.

Parms: None
Return: Returns the integer value of the cursor column number, or -1 if an error occurs or the terminal is disconnected

Example:

Col = getCursorCol(); // get cursor column number

GetCursorRow

GetCursorRow returns the current row number of the cursor.

Parms: None
Return: Returns the integer value of the cursor row number, or -1 if an error occurs or the terminal is disconnected

Example:

Row = getCursorRow(); // get cursor row number

GetDefaultTimeout

GetDefaultTimeout returns the value of the WaitForScreen default Timeout.

Parms: None
Return: Returns the value of the WaitForScreen default Timeout in milliseconds

Example:

TimeoutValue = getDefaultTimeout(); 
// returns the cursor wait for screen timeout value

GetField

GetField retrieves the string from the field pointed to by location. The number of characters is determined by the length of the field.

Parms: Position - the position of the field on the screen. This can be a ROW,COL or the relative location on the screen.
Return: Returns the string of characters from the field, or a null string if it is an invalid field position

Example:

Applid = getField(5,1); // get the data in the field at Row 5, column 1 
Applid = getField(80); // get the data from the field at 
location 80 - offset 80 (row 2 col 1 on a model 2)

Note: The location can be any valid location on the screen. The field containing that address is referenced. Protected or unprotected data can be retrieved. If the location is invalid, an error is generated and a null string is returned.

GetFontSize

GetFontSize gets the current Emulator screen font size.

Parms: None
Return: Returns an integer value of the Font point size

Example:

FontSize = getFontSize();// return the current Font size (in points)

GetProperty

GetProperty retrieves the value of a System Property.

Parms: PropertyName - the name of the system property to retrieve, enclosed in quotes
Return: Returns the value of the property, or null if not found

Example:

Applid = getProperty("APPLID") // get the data from the APPLID variable

GetString

GetString retrieves the string from the location on the screen. The number of characters is determined by the length parm.

Parms: Position - the position on the screen. This can be a ROW,COL or the relative location on the screen.
Length - number of characters to retrieve
Return: Returns the string of characters from the location

Example:

Applid = getString(5,1,16); // get 16 characters from screen 
location Row 5, column 1  Applid = getString(80,15); 
// get 15 characters from location 80 - offset 80 (row 2 col 1 on a model 2)

Note: The location can be any valid location on the screen, protected or unprotected. If the location is invalid, an error is generated and a null string is returned.

Hide

Hides the terminal screen. This sets the terminal frame to not visible. It is used when it is not desirable to show the actual screens that are being navigated. When the script ends, or the session is disconnected, the screen will be shown.

Parms: None
Return: Returns 0 if successful, or -1 if there is an error or the terminal gets disconnected

Example:

Hide(); // set the terminal window to not visible

Screencols

Screencols returns the number of columns on the screen. For a 3270 model 2 this would be 80.

Parms: None
Return: Returns the number of columns on the screen, or -1 if there is an error or the terminal gets disconnected

Example:

Cols = screenCols(); // returns the number of columns

Screenrows

Screenrows returns the number of rows on the screen. For a 3270 model 2 this would be 24.

Parms: None
Return: Returns the number of rows on the screen, or -1 if there is an error or the terminal gets disconnected

Example:

Rows = ScreenRows(); // returns the number of rows

SendKey

SendKey simulates pressing the corresponding AID key.

Parms: String representation of the key to send
Return: Returns 0 if successful, or -1 if there is an error or the terminal gets disconnected

Example:

SendKey ("Enter"); // sends the Enter key. Any modified 
data on the screen will be sent as part of the data stream.

The following values can be specified:

ENTER: Enter key. Sends the modified data, cursor location and the AID key.
RESET: Resets and unlocks the keyboard. No data is sent to the host.
CLEAR: Sends the CLEAR Aid key. Only the Aid key is sent.
SYS_REQ: Sends the System Request Aid.
ERASE_EOF: Clears the Unprotected fields from the current cursor location to the end of screen. No data is transmitted to the host.The fields are set to nulls.
ERASE_INPUT: Clears the current field to nulls.
FIELD_MARK: Transmits the FieldMark aid key.
HOME: Puts the cursor at the first unprotected field on the screen.
TAB: Places the cursor at the next unprotected field.
PA1, PA2, PA3
F1 through F24

The following special keys position the cursor:

HOME: Puts the cursor at the first unprotected field on the screen.
TAB: Places the cursor at the next unprotected field.

Note: The behavior and data that gets transmitted to the host are dependent on the actual key being sent. The Enter and the Function keys send any modified data fields, as well as the cursor location and the AID key. The other AID keys send only the AID key.

Sendstring

Sendstring sets the string at the current cursor location and sends the data with the Enter key.

Parms: String to be sent
Return: Returns 0 if successful, or -1 if there is an error or the terminal gets disconnected

Example:

Sendstring ("ctsoa"); // enters the string ctsoa at the 
current cursor location and sends the data with the Enter key

Setcursor

Setcursor positions the cursor on the terminal.

Parms: Screen position can be either of the following:
ROW,COL - the Row and Column to position the cursor Location - the relative location on the screen
Return: Returns the relative location of the cursor, or -1 if there is an error or the terminal gets disconnected

Example:

SetCursor(1,1); // sets the cursor to the top left position of the screen 
SetCursor(80); // sets the cursor to offset 80 (This would be row 2, 
col 1 on a 24x80 terminal)

SetDefaultTimeout

SetDefaultTimeout sets the default timeout.

Parms: New wait time, in milliseconds. For example, 1000 is a one second wait.
Return: Returns the previous value of the WaitForScreen Timeout valued

Example:

oldTimeoutValue = setDefaultTimeout(10000); 
// override the timeout to 10 seconds

SetField

SetField places a string in the field containing the designated location The number of characters is determined by the length of the string.

Parms: String value - the string to be placed in the field
Position - a position on the screen that is part of a field.The position must be in an Unprotected field.This can be a ROW,COL or relative location on the screen.
Return: Returns 0 if successful, or -1 if there is an error.

Example:

SetField(applid,5,1); // put the string pointed to by applid 
at the field containing row 5,col 1 
SetField("ctsoa",80); // put the string ctsoa at the field 
containing offset 80 (row 2 col 1 on a model 2)

Note: If the location on the screen is not an Unprotected field, or if the length exceeds the size of the field, an error will be generated; no data will be placed.

SetFontSize

Sets a new font size.

Parms: The new font size, in points
Return: Returns the previous value of the font size

Example:

oldFontSize = setFontSize(16); // set the new Font size to 16 pt

Setstring

Setstring places a string at the designated location on the screen. The number of characters is determined by the length of the string.

Parms: String value - the string to be placed on the screen:
Position - the position on the screen. This can be a ROW,COL or relative location on the screen.
Return: Returns 0 if successful, or -1 if there is an error

Example:

SetString(applid,5,1); // put the string pointed to 
by the variable applid at row 5,col 1
SetString("ctsoa",80); // put the string ctsoa at 
offset 80 (row 2 col 1 on a model 2)

Note: If the location on the screen is not an Unprotected field, or if the length exceeds the size of the field, an error will be generated and no data will be placed.

Show

Shows the terminal screen. This sets the terminal frame to visible.

Parms: None
Return: Returns the relative location of the cursor, or -1 if there is an error or the terminal gets disconnected

Example:

Show(); // set the terminal window to visible

WaitforScreen

WaitForScreen waits for a screen of data to be received from the host.

Parms

arg 1 = Timeout value. This is the length of time to wait, in milliseconds.

If no data is received by this time, processing continues If no value is specified, a default of 15 minutes is assume

Return

Returns a numeric value specifying the result of the function:

0 = data was received

-1 = timeout. No data was received within the time specified

Example:

waitforscreen(); // wait until a screen is received 
(or 15 minutes has elapsed)
waitforscreen(15*1000) // wait for up to 15 seconds

Note: Because the WaitforScreen is waiting for input, it could take a long time before a screen is received. If a stall has occurred and the system is not responding, the script will stall. For this reason, there is a timeout value associated with this function. If no data is received for 10 minutes, the wait is cancelled automatically and a value of -1 is returned.

WaitForString

WaitForString waits for a screen containing the specified data at the specified location to be received.

Parms

arg 1 = The string to wait for

arg2 = The row,column position of the data

arg3 = Timeout value. This is the length of time to wait, in milliseconds.

If no data is received by this time, processing will continue.

If no value is specified, a default of 15 minutes is assumed

Return

Returns a numeric value specifying the result of the function:

0 = data was received

-1 = timeout. No data was received within the time specified

Example:

Waitforstring("Userid",5,1); // wait until a screen is received 
that has the string "Userid" at row 5 col 1
Waitforstring ("Userid",5,1 1000*15) // wait for up to 15 seconds

Note: Because the waitforstring is waiting for input, it could take a long time before a screen is received. If a stall has occurred and the system is not responding, the script will stall. For this reason, there is a timeout value associated with this function. If no data is received within 10 minutes, the wait will be cancelled automatically and a value of -1 will be returned.