Skip to content

Macro API Objects

You can create macros using the Macro API. By default for use in macros, there are four primary objects available:

  • Session - the main entry point for access to the host. You use the Session object to connect, disconnect and provide access to the PresentationSpace object.

  • PresentationSpace - represents the screen and provides many common capabilities such as getting and setting the cursor location, sending data to the host and reading from the screen. It is obtained by calling session.getPresentationSpace().

  • Wait - provides a simple way to wait for various host states to occur before continuing to send more data or read from the screen. For example, you can wait for the cursor to be located at a certain position, text to be present in a position on the screen or simply wait for a fixed amount of time. All ‘Wait' function calls require the yield keyword, which is explained below.

  • User Interface - automatically available in your macro as the “ui” variable. It provides basic user interface capabilities. You can use this object to display data to the user or prompt them for information. All ‘UI' function calls require the yield keyword.

All available objects

See the list of available objects in the right navigation, "On this page." (You may need to expand your browser.)


Attribute

Use the Attribute, along with the AttributeSet, to decode the formatting information present on the data cell.

Attribute Indicates...
PROTECTED a protected data cell
MODIFIED a modified data cell
NUMERIC_ONLY the beginning of a numeric only data cell
ALPHA_NUMERIC an alpha numeric data cell.
HIGH_INTENSITY whether the data cell contains high intensity text
HIDDEN whether the data cell contains hidden text
PEN_DETECTABLE whether the data cell is pen detectable
ALPHA_ONLY an alpha only data cell
NUMERIC_SHIFT the beginning of a numeric shift field
NUMERIC_SPECIAL the data cell marks the beginning of a numeric special field
KATAKANA_SHIFT a section of Katakana text
MAGNETIC_STRIPE the data cell marks the beginning of a magnetic strip field
SIGNED_NUMERIC_ONLY the data cell is a signed numeric field
TRANSMIT_ONLY the data cell is a transmit only field
FIELD_END_MARKER the data cell marks the end of a modified field
FIELD_START_MARKER the data cell marks the start of a modified field
SPECIAL_EMPHASIS_PROTECTED a special emphasis protected field
TAB_STOP that the data cell contains a tab stop
REVERSE the data cell displays in reverse video mode
BLINKING the data cell contains blinking text
RIGHT_JUSTIFIED the data cell marks the beginning of a right justified field
LEFT_JUSTIFIED the data cell marks the beginning of a left justified field
LOW_INTENSITY the data cell contains low intensity text
UNDERLINE the data cell contains underlined text
DOUBLE_BYTE the data cell contains double byte text
COLUMN_SEPARATOR the data cell contains a column separator
BOLD the data cell contains bold text
DOUBLE_WIDTH the data cell marks a double width field
DOUBLE_HEIGHT_TOP a double height top data cell
DOUBLE_HEIGHT_BOTTOM a double height bottom data cell
CONTROL_PAGE_DATA the data cell contains control page data
RIGHT_COLUMN_SEPARATOR the data cell contains a right column separator
LEFT_COLUMN_SEPARATOR a data cell containing a left column separator
UPPERSCORE the data cell contains an upperscore
STRIKE_THROUGH the data cell contains strike through text

AttributeSet

The AttributeSet object allows the user to decode the attributes that are present on the data cell. The AttributeSet object returns values defined in the Attribute object and when used together, you can get formatting information from the data cell.

Method Description
contains(attribute) Determines if the set contains the specified Attribute.
Parameters
{Number} attribute to check
Returns
{Boolean} True if the attribute is in the set
isEmpty() Determines if the attribute set is empty.
Returns
{Boolean}True if the set is empty.
size() Indicates the number of attributes in a set.
Returns
{Number} The attribute count.
toArray() Converts the internal attribute set to an array.
Returns
{Number[]}Array of values of attributes in the set.
toString() Converts the internal attribute set to a string.
Returns
{String} Space-delimited names of attributes in the set.
forEach(callback, thisArg) Function to iterate over each element in the attribute set.
Parameters
{forEachCallback} Callback to perform the specific operation. Called with the name of each attribute in the set.
{Object} thisArg optional pointer to a context object.
forEachCallback(string, object) A user provided callback function where you provide the behavior, to be used as the callback parameter to forEach.
Parameters
{String} String name of an attribute in the attribute set.
{Object} thisArg optional pointer to a context object.

AutoSignOn

Method Description
getPassTicket() Obtains a pass ticket to be used for signing onto a mainframe application. Multiple pass tickets may be requested using different application IDs.
Parameters
{String} application ID tells the host which application the sign on is for
Returns
{Promise} fulfilled with the pass ticket key or rejected if the operation fails. The pass ticket obtained from DCAS only works with the current host session and is valid for ten minutes.
sendUserName() Applies the user name contained in the pass ticket to the field at the current cursor location on the current host screen. The user name must be sent before the password. Sending the password first will invalidate the pass ticket, and you will need to get another one.
Parameters
{String} passTicketKey opbtained from getPassTicket
Returns
{Promise} fulfilled if the user name is successfully sent. Rejected if the operation fails.
sendPassword() Applies the password contained in the pass ticket to the field at the current cursor location on the current host screen. The user name must be sent before the password. Sending the password first will invalidate the pass ticket, and you will need to get another one.
Parameters
{String} passTicketKey obtained from getPassTicket
Returns
{Promise} fulfilled if the password is successfully sent. Rejected if the operation fails.

Color

Color constants to use for the DataCell object foreground and background colors.

Color Description Numeric Value
BLANK_UNSPECIFIED No color specified 0
BLUE Blue 1
GREEN Green 2
CYAN Cyan 3
RED Red 4
MAGENTA Magenta 5
YELLOW Yellow 6
WHITE_NORMAL_INTENSITY Normal intensity white 7
GRAY Gray 8
LIGHT_BLUE Light blue 9
LIGHT_GREEN Light green 10
LIGHT_CYAN Light cyan 11
LIGHT_RED Light red 12
LIGHT_MAGENTA Light magenta 13
BLACK Black 14
WHITE_HIGH_INTENSITY High intensity white 15
BROWN Brown 16
PINK Pink 17
TURQUOISE Turquoise 18

ControlKey

The ControlKey object defines constants for sending cursor control keys and host commands using the sendKeys method. Constants are available for these host types:


IBM 3270

Key word Description
ALTVIEW Alternate view
ATTN Attention
BACKSPACE Back space
BACKTAB Back tab
CLEAR Clear or clear display
CURSOR_SELECT Cursor select
DELETE_CHAR Delete, delete character
DELETE_WORD Delete word
DEST_BACK Destructive backspace
DEV_CANCEL Device cancel
DOWN Cursor down
DSPSOSI Display SO/SI
DUP Duplicate field
END_FILE End of field
ENTER Enter
ERASE_EOF Erase end of field
ERASE_FIELD Erase field
ERASE_INPUT Erase input
FIELD_MARK Field mark
HOME Cursor home
IDENT Ident
INSERT Insert
LEFT_ARROW Cursor left
LEFT2 Left two positions
NEW_LINE New line
PA1 - PA3 PA1 - PA3
PF1 - PF24 PF1 - PF24
PAGE_DOWN Page down
PAGE_UP Page up
RESET Reset, reset terminal
RIGHT2 Right 2 positions
RIGHT_ARROW Cursor right, right
SYSTEM_REQUEST System request
TAB Tab key
UP Cursor up

IBM 5250

Key word Description
ALTVIEW Alternate view
ATTN Attention
AU1 - AU16 AU1 - AU16
BACKSPACE Back space
BACKTAB Back tab
BEGIN_FIELD Begin field
CLEAR Clear or clear display
DELETE_CHAR Delete, delete character
DEST_BACK Destructive backspace
DOWN Cursor down
DSPSOSI Display SO/SI
DUP Duplicate field
END_FILE End of field
ENTER Enter
ERASE_EOF Erase end of field
ERASE_FIELD Erase field
ERASE_INPUT Erase input
FIELD_EXT Field exit
FIELD_MINUS Field minus
FIELD_PLUS Field plus
FIELD_MARK Field mark
HELP Help request
HEXMODE Hex mode
HOME Cursor home
INSERT Insert
LEFT_ARROW Cursor left
NEW_LINE New line
PA1 - PA3 PA1 - PA3
PF1 - PF24 PF1 - PF24
PAGE_DOWN Page down
PAGE_UP Page up
[print] Print
RESET Reset, reset terminal
RIGHT_ARROW Cursor right, right
SYSTEM_REQUEST System request
TAB Tab key
UP Cursor up

VT

Key word Description
BACKSPACE Back space
BREAK Break
CLEAR Clear or clear display
CURSOR_SELECT Cursor select
DELETE_CHAR Delete, delete character
DOWN Cursor down
EK_FIND Edit keypad find
EK_INSERT Edit keypad insert
EK_NEXT Edit keypad next
EK_PREV Edit keypad previous
EK_REMOVE Edit keypad remove
EK_SELECT Edit keypad select
END_FILE End of field
ENTER Enter
F1 - F24 F1 - F24
HOLD Hold
HOME Home
INSERT Insert
KEYPAD_COMMA Keypad comma
KEYPAD_DOT Keypad decimal
KEYPAD_ENTER Keypad enter
KEYPAD_MINUS Keypad minus
KEYPAD0 - KEYPAD9 Keypad 0 - Keypad 9
LEFT_ARROW Cursor left
PF1 - PF20 PF1 - PF20
PAGE_DOWN Page down
PAGE_UP Page up
RESET Reset, reset terminal
RETURN Return, carriage return
RIGHT_ARROW Cursor right, right
TAB Tab key
UDK16 - UDK20 User defined key 6 - User defined key 20
UP Cursor up

UTS

Key word Description
BACKSPACE Back space
BACKTAB Back tab
CHAR_ERASE Erases character at the cursor and advances the cursor.
CLEAR_DISPLAY Clear display
CLEAR_EOD Clear to end of display
CLEAR_EOF Clear to end of field
CLEAR_EOL Clear to end of line
CLEAR_FCC Clear Field Control Character
CLEAR_HOME Clear display and cursor home
CONTROL_PAGE Toggles the control page
DELETE_LINE Deletes the line containing the cursor and shifts remaining lines up one row
DELIN_LINE Deletes character under cursor and shifts remaining characters on line to the left.
DELIN_PAGE Deletes character under cursor and shifts remaining characters on page to the left.
DOWN Moves the cursor down one line. Wraps at bottom.
DUP_LINE Creates a copy of the current line and overwrites the next line with the duplicate.
END_FIELD Moves the cursor to the end of the current field.
END_PAGE Moves the cursor to the end of the current page.
EURO Inserts the Euro character
F1 - F22 Function keys F1-F22
HOME Moves the cursor to beginning of current page (row 1, col 1)
INSERT Toggles insert/overwrite mode.
INSERT_IN_LINE Inserts space at cursor position and shifts the remaining characters on the line to the right. The character in the far right column on the line is discarded.
INSERT_IN_PAGE Inserts space at cursor position and shifts the remaining characters on the page to the right. The character in the far right column on each line is discarded.
INSERT_LINE Inserts a new line at the cursor row and shifts the remaining lines down. The last row on the page is discarded.
LEFT_ARROW Moves the cursor one position to the left wrapping if necessary.
LOCATE_FCC Finds the next field control character on the screen.
MSG_WAIT Retrieves messages queued to the terminal.
RETURN Carriage return
RIGHT_ARROW Moves the cursor one position to the right, wrapping if necessary.
SOE Inserts the Start of Entry character
START_OF_FIELD Moves the cursor to the beginning of the field.
START_OF_LINE Moves the cursor to column 1 of current line.
TAB Moves the cursor to the next tab position of the screen.
TOGGLE_COL_SEP Toggles the column separator attribute.
TOGGLE_STRIKE_THRU Toggles the strike-through attribute on the current data cell.
TOGGLE_UNDERLINE Toggles the underline attribute on the current data cell.
TRANSMIT Transmits changed field data to the host.
UNLOCK Sends the UNLOCK key to the host.
UP Moves the cursor up one row, wrapping if necessary.

DataCell

The DataCell object provides information about a particular position on a terminal screen.

Method Description
getPosition() Returns the position of this data cell on the screen.
Returns
{Position} the position of the data cell on the screen
getChar() Obtains the character associated with the cell.
Returns
{String}The character associated with the cell.
getAttributes() Returns the set of attributes specified for this data cell instance. See AttributeSet.
Returns
{AttributeSet} The set of attributes for this data cell instance.
getForegroundColor() Returns the foreground color, as defined in the Color object, for this data cell.
Returns
{Number} Foreground color for this data cell. The color is defined in the Color object.
getBackgroundColor() Returns the background color, as defined in the Color object, for this data cell.
Returns
{Number} Background color for this data cell. The color is defined in the Color object.
toString Converts the internal data cell to a string.
Returns
{String}The string representation of a data cell.
isFieldDelimiter() Tests if this cell represents a field delimiter.
Returns
{Boolean} True if this cell is a field delimiter, false if otherwise.

Dimension

Represents the size of the screen or screen area.

Method Description
Dimension(rows,cols) Creates a new Dimension instance.
Parameters
{Number} rows screen rows dimension
{Number} cols screen columns dimension

Field

Use the Field object, along with FieldList, to obtain the information present in a field on the screen.

Method Description
getAttributes() Returns the set of attributes specified for this field instance. See AttributeSet.
Returns
{AttributeSet} The set of attributes for this field.
getForegroundColor() Returns the foreground color for the field.
Returns
{Number} Foreground color for this field. These values are defined in the Color object.
getBackgroundColor() Returns the background color of the field.
Returns
{Number} Background color for this field. These values are defined in the Color object.
getStart() Returns the starting position of the field. The starting position is the position of the first character of the field. Some host types use a character position to store field level attributes. In this case, the attribute position is not considered the start position.
Returns
{Position} Starting position of the field.
Throws
{RangeError} For zero length fields.
getEnd() Returns the ending position of the field. The ending position is the position in the presentation space containing the last character of the field.
Returns
{Position} Ending position of the field.
Throws
{RangeError} For zero length fields.
getLength() Returns the length of the field. For host types that use a character position to store the field attributes, the field length does not include the field attribute position
Returns
{Number} Length of the field.
getDataCells() Obtains the data cells that comprise this field. See DataCell.
Returns
{DataCell[]} Data cells that comprise this field.
getText() Obtains the text from the field.
Returns
{String} field text.
setText() Sets the field text. For certain host types, like VT, the text is transmitted to the host right away, but in other host types, the text is not transmitted to the host until an Aid key is invoked. If the text is shorter than the field, the text is placed in the host field, and the remainder of the field is cleared. If the text is longer than the host field, then as much text as will fit is placed in the field.
Parameter
{String} Text to set on the field.
Throws
{Error} If the field is protected.
clearField() Clears the current field in an emulation-specific manner.
Throws
{Error} If the field is protected or clear is not supported.
getPresentationSpace() Obtains the PresentationSpace that created this field.
Returns
{PresentationSpace} Parent of this field instance.
toString() Creates a user-friendly description of the field.
Returns
{String} A user readable rendition of the field.

FieldList

Use the FieldList object, along with Field object, to obtain field list information.

Method Description
getPresentationSpace() Obtains the PresentationSpace that created this field.
Returns
{PresentationSpace} Parent of this field instance.
findField(position, text, direction) Returns the field containing the specified text. The search starts from the specified position and proceeds either forward or backward. If the string spans multiple fields, the field containing the starting position is returned. When searching forward the search will not wrap to the top of the screen. When searching backward the search will not wrap to the bottom of the screen.
Parameters
{Position} Position from which to start the search. See Position object.
{String} The text to search for (optional). If not provided, returns the next field to the right of or below the specified position.
{Number} direction of the search (optional). Use PresentationSpace. SearchDirection constants for this parameter. For example, PresentationSpace.SearchDirection.FORWARD or PresentationSpace.SearchDirection.BACKWARD. If not provided, searches forward.
Returns
{Field} containing the string or null if a field meeting the given criteria is not found.
Throws
{RangeError} If the position is out of range.
get(index) Obtains the field at the given index.
Parameters
{Number} index into the field list.
Returns
{Field} located at the specified index.
Throws
{RangeError} If the index is out of range.
isEmpty() Determines if the field list is empty.
Returns
{Boolean} True if the list is empty.
size() Indicates the number of fields in the list.
Returns
{Number} The field count.
toString() Creates a user-friendly description of the field list.
Returns
{String} A user readable rendition of the field list.

FileTransfer

Use the FileTransfer object to list and transfer files between the host system and the client.

The Host Access for the Cloud file transfer API abstracts the file path conventions used by different host file implementations. Follow URL or Linux file system path formats when formatting file paths used by the API. For example, /root/directory/file.

It is important to observe any rules specific to host systems, such as allowable characters or name lengths.

Note

Browsers place significant security restrictions around the ability of Javascript to interact with client file systems.

Method Description
getHostFileListing(remotePath)() Request a listing of host files. If RemotePath is omitted, a file listing for the current remote working directory is shown.
Parameters
{String} (optional) If specified will get file listing for specified remote path. If not specified, will get file listing for current remote working directory.
Returns
{Promise} Resolves to an array of HostFile objects contained at remoteName. Rejected if the remote path cannot be read.
sendFile(localFile, remoteName) Sends specified file to the host.
Parameters
{File} Javascript file object pointing to local file to send.
{String} (optional) Fully-qualified remote file name as allowed by remote system (Unix, Windows, MVS, VAX).
Returns
{Promise} fulfilled with a HostFile object representing the sent file on success. Rejected if an error occurred sending the file.
getDownloadURL(remoteName) Constructs a link to download a file from a host system.
Parameters
{String} Fully-qualified remote file name as allowed by remote system (Unix, Windows, MVS, VAX).
Returns
{URL} that can be used to retrieve the file from the Host Access for the Cloud session server.
setTransferOptions(options) Set transfer options for current FileTransfer session. The transfer options are applied to all future transfers until the session is either exited or overridden by another call to setTransferOptions.
Parameters
{JSON} see FileTransferOptions for allowed names and values.
Returns
{Promise} fulfilled when the call completes. Rejected if an error occurred setting the options.
cancel() Cancels the current transfer in progress.
Parameters
{String} Fully-qualified remote file name as allowed by remote system (Unix, Windows, MVS, VAX).
Returns
{Promise} fulfilled when the call completes. Rejected if an error occurred canceling the transfer.

FileTransferFactory

A fileTransferFactory object is available to all macros. If file transfers are configured for the session, you can use it to get a reference to a FileTransfer object.

Method Description
getIND$File() Returns a FileTransfer object for interacting with the configured Ind$File type for the session.
Returns
{FileTransfer}
Throws
{Error} If the session hasn’t been configured to allow IND$File transfers.

FileTransferOptions

File transfer option object specification. Example:
`fileTransfer.setTransferOptions({ transferMethod : 'ascii' });```

Method Description
transferMethod {String}Allowed values:
  • ‘ascii’
  • ‘binary’

HostFile

A HostFile object represents a file on the host file system.

Method Description
getName() Gets the file name.
Returns
{String} the file name.
getParent() Gets the parent of this host file.
Returns
{String} the parent of this host file. This means different things on different host types. For example on TSO this is the name of the catalog in which the file resides.
getSize() The byte size of the file.
Returns
{Number} the size of the file in bytes.
getType() The type of file represented.
Returns

HostFileType

The HostFileType object defines constants for determining the type of a HostFile object.

Value Description
FILE Represents a file on the host system.
DIR Represents a directory on the host system.
UNKNOWN Represents a host file of unknown origin.

OIA

Operator Information Area (OIA) interface. The OIA object returns values that are defined in the OIAStatus object.

Method Description
getStatus () Returns the set of enabled status flags. See StatusSet.
Returns
{StatusSet} Containing the status information.
getCommErrorCode() Returns the current communication error code.
Returns
{Number} the current communication error code. If one doesn’t exist, it will be 0.
getProgErrorCode() Returns the current program error code.
Returns
{Number} the current program error code. If one doesn’t exist, it will be 0.

OIAStatus

OIAStatus Description
CONTROLLER_READY Controller ready
A_ONLINE Online with a non-SNA connection
MY_JOB Connected to a host application
OP_SYS Connected to a SSCP (SNA)
UNOWNED Not connected
TIME Keyboard inhibited
SYS_LOCK System lock following AID key
COMM_CHECK Communication check
PROG_CHECK Program check
ELSEWHERE Keystroke invalid at cursor location
FN_MINUS Function not available
WHAT_KEY Keystroke invalid
MORE_THAN Too many characters entered in the field
SYM_MINUS Symbol entered not available
INPUT_ERROR Operator input error (5250 only)
DO_NOT_ENTER Do not enter
INSERT Cursor in insert mode
GR_CURSOR Cursor in graphics mode
COMM_ERR_REM Communications error reminder
MSG_WAITING Message waiting indicator
ENCRYPT Session is encrypted
NUM_FIELD Invalid character in numeric only field

Position

Method Description
Position(row,col) Creates a new Position instance.
Parameters
{Number} row screen row coordinate
{Number} col screen column coordinate

PresentationSpace

Use the PresentationSpace object to interact with the terminal screen. Setting and getting the cursor position, sending keys, and reading text are some of the interactions available.

Method Description
getCursorPosition() Returns a Position instance representing the current cursor position. An unconnected session has a cursor position of 0,0.
Returns
{Position} current cursor location
setCursorPosition(position) Moves the host cursor to the specified row and column position. For some hosts, such as VT, the host may constrain the movements of the cursor.
Parameters
{Position} Position new cursor position.
Returns
None
Throws
{RangeError} If the position is not valid on the current screen.
isCursorVisible() Tests that the cursor is currently visible in the presentation space. The cursor is considered not visible if the session is not connected.
Returns
{Boolean} True if the cursor is visible. False if the cursor is not visible.
sendKeys(keys) Transmits a text string or ControlKey to the host at the current cursor position in the presentation space. If the cursor is not in the desired position, then use setCursorPosition function first.
The text string can contain any number of characters and ControlKey objects.
For example: "myname" + ControlKey.TAB + "mypass" + ControlKey.ENTER will transmit a user ID, tab to the next field, transmit a password, and then transmit the Enter key.
If you need to transmit a square bracket, double the brackets ([[ or ]]).
Parameters
{String} keys text and/or control keys to transmit
getText(start,length) Returns a string representing a linear area of the presentation space. No new line characters are inserted if row boundaries are encountered.
Parameters
{Position} start position from which to retrieve text
{Number}length the maximum number of characters to return. If the length parameter causes the last position of the presentation space to be exceeded then only those characters up to the last position will be returned.
Returns
{String) representing a linear area of the presentation space which may be empty if the session is not connected.
Throws
{RangeError} If the position or length are not valid on the current screen.
getSize() Gets the dimensions of the screen as a Dimension object.
Returns
{Dimension} Containing the number of rows and columns. The screen size is [row:0, col:0] if the session is not connected.
getDataCells(start, length) Returns DataCell instances where the first member will be for the position specified by the start parameter. The maximum number of DataCell instances in the list is specified by the length parameter.
Parameters
{Position} start the first position on the host screen in which to retrieve DataCell instances. See Position.
{Number} length of the maximum number of DataCell instance to be retrieved. If not specified, returns DataCells from the start position to the end of the screen.
Returns
{DataCell[]} Instances which may be empty if the session is not connected. If position is not specified, returns all DataCells. If length is not specified, returns DataCells from the start position to the end of the screen.
Throws
{RangeError}if start or length are out of range.
getFields() Returns a list of the fields in the presentation space. If the host type does not support fields or the current screen is not formatted then the return value will always be an empty list. See FieldList.
Returns
{FieldList} of host defined fields in the presentation space.

Session

The session object is the main entry point for interacting with the host. It contains functions for connecting, disconnecting, and obtaining the PresentationSpace object.

Method Description
connect() Connects to the configured host. If needed, use ,wait.forConnect() to block macro execution until the session is connected.
Returns
None
disconnect() Disconnects from the configured host. If needed, use wait.forDisconnect() to block macro execution until the session is connected.
Returns
None
isConnected() Determines whether the connection to the host is connected.
Returns
{Boolean} true if host connection is established; false if not.
getPresentationSpace() Provides access to the PresentationSpace instance for this session.
Returns
{PresentationSpace} instance associated with this session.
getDeviceName() Returns the device name for a connected session or an empty string if the session is disconnected or doesn't have device name.
Returns
{String} The connected device name.
getType() Returns the type of host session. See SessionType.
Returns
{String} The type of host session.
setDeviceName() Provides a means to modify the device name on a session instance.
Parameters
{String} name Device name to use when connecting to a host.
Throws
{Error}If an attempt is made to set the device name while the session is connected.
getOIA() Provides access to the OIA instance for this session.
Returns
{OIA} Associated with this session

SessionType

Constants used to identity the type of host to which the connection is being made. See Session object.

Host Type Description
IBM_3270 Indicates an IBM 3270 terminal session
IBM_5250 Indicates an IBM 5250 terminal session
VT Indicates a VT session

StatusSet

You can use the StatusSet object to decode the OIA status. The StatusSet object returns values defined in the OIAStatus object and when used together, you can get status information from the OIA.

Method Description
contains(statusFlag) Determines if the set contains the specified status flag from OIAStatus constants.
Parameters
{Number} statusFlag status to check
Returns
{Boolean}True if the status flag is present in the set.
isEmpty() Determines if the status set is empty.
Returns
{Boolean} True if the set is empty.
size() Indicates the number of status flags in the set.
Returns
{Number} The status count
toArray() Converts the internal status set to an array.
Returns
{Object []} Array of status flags in the set.
toString() Converts the internal status set to a string.
Returns
{String} Space delimited names of status flags in the set.
forEach(callback, thisArg) Function to iterate over each element in the status set.
Parameters
{forEachCallback} Callback to perform the specific operation. Called with the name of each status in the set.
forEachCallback(string, thisArg) A user-provided callback function where you provide the behavior, to be used as the callback parameter to forEach.
Parameters
{String} String The name of a status in the status set.
{Object} thisArg Optional pointer to a context object.

User Interface

The user interface object provides functions for interacting with the user, prompting for and displaying basic information. The UI object is made automatically available in your macro as the “ui” variable”.

Note

Important: All UI functions require the ‘yield’ keyword in front of them. This allows the macro to block execution until the conditions of the UI function have been met.
[parameter] denotes an optional parameter.

Method Description
prompt(message,[defaultAnswer], [mask]) Prompts the user for information in the user interface.
Parameters
{String} message title to display to the user. Default: blank String.
{String} defaultAnswer to use if user leaves it blank. Default: blank String
{Boolean} mask indicates whether to hide the prompt (as with a password)
Returns
{Promise} Fulfilled when the user closes the dialog window. Returns the users input on “OK” or null on “Cancel”.
message([message]) Display a message in the user interface.
Parameters
{String} message to display to the user. Default: blank String.
Returns
{Promise} Fulfilled when the user closes the message window.

Wait

Use the wait object to wait for a particular session or screen state. For example, you can wait until the cursor is found at a particular location or text is present at a certain location before continuing with the macro execution.

Wait functions are often used in conjunction with asynchronous functions such as connect() and sendKeys().

Note

All functions take timeouts as an optional parameter and have a default time out value of 10 seconds (10000ms).
Important: All wait functions require the ‘yield’ keyword in front of them. This allows the macro to block execution until the conditions of the wait function are met.
[parameter] denotes an optional parameter.

Method Description
setDefaultTimeout(timeout) Sets the default timeout value for all functions.
Parameters
{Number} default timeout to use for all wait functions in milliseconds.
Returns
{None}
Throws
{RangeError} If the specified timeout is less than zero.
forConnect([timeout]) Waits for a connect request to complete.
Parameters
{Number} in milliseconds.
Returns
{Promise} Fulfilled if the session is already connected or when connection occurs. Rejected if the wait times out.
forDisconnect([timeout]) Waits for a disconnect request to complete.
Parameters
{Number} timeout in milliseconds.
Returns
{Promise} Fulfilled if the session is already disconnected or when it finally disconnects. Rejected if the wait times out.
forFixedTime([timeout]) Waits unconditionally for fixed time. Time is in milliseconds (ms).
Parameters
{Number} timeout in milliseconds.
Returns
{Promise} Fulfilled after time elapses.
forScreenChange([timeout]) Waits for the host screen to change. This function returns when a screen update is detected. It makes no guarantees about the number of subsequent updates that may arrive before the screen is complete. Waiting repeatedly until the screen contents match some known stopping criteria is advisable.)
Parameters
{Number} timeout in milliseconds.
Returns
{Promise} Resolved if the screen change. Rejected if the wait times out.
forCursor(position, [timeout]) Waits for the cursor to arrive at the specified position.
Parameters
{Position} The position specifying the row and column
Returns
{Promise} Fulfilled if the cursor is already located or when it is finally located. Rejected if the wait times out.
forText(text, position, [timeout]) Wait for text located at a specific position on the screen
Parameters
{String} text to expect
{Position} position specifying the row and column
{Number} timeout in milliseconds
Returns
{Promise} Fulfilled if the text is already at the specified position or whenever it is located. Rejected if the wait times out.
Throws
{RangeError} if the position is not valid.
forHostPrompt(text, column,[timeout]) Waits for a command prompt located at a particular column on the screen.
Parameters
{String} text prompt to expect
{Position} column where cursor is expected
{Number} timeout in milliseconds.
Returns
{Promise} Fulfilled if the conditions are already met or when the conditions are finally met. Rejected if the wait times out.
Throws
{RangeError} if the column is out of range.
forHostSettle([settleTime],[timeout]) NOTE: wait.forHostSettle should only be used when other more targeted wait functions are insufficient.
Monitors incoming screen data and resolves settleTime ms after the last update and the keyboard is unlocked. This function is useful when data arrives in multiple packets and you want to be sure the whole screen has been received before carrying on.
Parameters
{Number} time to wait after the last update to make sure more data doesn’t arrive unexpectedly. The default is 200 milliseconds.
{Number} timeout in milliseconds.
Returns
{Promise}Fulfilled when the settle time has elapsed after receipt of the last screen update and the keyboard is unlocked.