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
IBM 5250
VT
UTS

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.

Available host types:

IBM_3270
IBM_5250
VT
ALC
UTS
T27

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 `{Number}` 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.