10.1 Macro API Objects

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

Session

Session is 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

The PresentationSpace object 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

The UI object is made 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.

Other available objects

10.1.1 Attribute

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

Table 10-1 Attributes

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

10.1.2 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.

Table 10-2 AttributeSet

METHODS
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} this Arg 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.

10.1.3 Color

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

Table 10-3 Color constants

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

10.1.4 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

Table 10-4 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

Table 10-5 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
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
[print]	Print
RESET	Reset, reset terminal
RIGHT_ARROW	Cursor right, right
PAGE_UP	Page up
PAGE_DOWN	Page down
SYSTEM_REQUEST	System request
TAB	Tab
UP	Cursor up

Table 10-6 VT

Keywords	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
ENTER	Enter
END_FILE	End of field
F1 - F24	F1 - F24
HOLD	Hold
HOME	Home
INSERT	Insert
KEYPAD_COMMA	Keypad comma
KEYPAD_DOT	Keypad decimal
KEYPAD_MINUS	Keypad minus
KEYPAD_ENTER	Keypad enter
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

Table 10-7 UTS

Key word	Description
BACKSPACE	Moves the cursor to the previous tab position on the screen.
BACKTAB	Back tab <Shift> <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
DOWN	Moves the cursor down one line. Wraps at bottom.
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.
DUP_LINE	Creates a copy of the current line and overwrites the next line with the duplicate.
EURO	Inserts the Euro character
END_FIELD	Moves the cursor to the end of the current field.
END_PAGE	Moves the cursor to the end of the current page.
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.

10.1.5 DataCell

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

Table 10-8 DataCell

METHODS
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}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.

10.1.6 Dimension

Represents the size of the screen or screen area.

Table 10-9 Dimension

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

Method

Dimension(rows,cols)

Creates a new Dimension instance.

Parameters

{Number} rows screen rows dimension

{Number} cols screen columns dimension

10.1.7 Field

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

Table 10-10 Field

Method
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 of the field. Returns {Number} the foreground color for this field. These values are defined in the Color object.
getBackgroundColor()	Returns the background color of the field. Returns {Number} the 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. Parameters {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 presentation space which 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.

10.1.8 FieldList

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

Table 10-11 FieldList

Method
getPresentationSpace()	Obtains the presentation space which created this field list. Returns {PresentationSpace}Parent of this field list 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} User readable rendition of the field list.

10.1.9 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.

Table 10-12 fileTransferFactory

Method
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.

Method

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.

10.1.10 FileTransfer

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

The Reflection ZFE 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.

Table 10-13 FileTransfer

Method
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 can not be read.
sendFile(localFile, remoteName)	Sends specified file to the host. Parameters {File} Javascript file object pointing to local file to send. {String} 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 Reflection ZFE 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. Returns {Promise} fulfilled when the call completes. Rejected if an error occurred canceling the transfer.

10.1.11 HostFile

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

Table 10-14 HostFile

Method
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

10.1.12 Host File Type

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

Table 10-15 HostFileType

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.

10.1.13 File Transfer Options

File transfer option object specification.

Example: fileTransfer.setTransferOptions({ transferMethod : 'ascii' });

Table 10-16 FileTransferOptions

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

10.1.14 OIA

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

Table 10-17 OIA

Method
getStatus ()	Returns the set of enabled status flags. See StatusSet. Parameters 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.

Method

getStatus ()

Returns the set of enabled status flags. See StatusSet.

Parameters

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.

10.1.15 OIAStatus

Table 10-18 OIAStatus

OIAStatus	Description
CONTROLLER_READY	Controller ready
A_LINE	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

10.1.16 AutoSignon

Some mainframe hosts have a Digital Certificate Access Server (DCAS). You can request a temporary, one-time pass ticket from DCAS for logging into a host application. Using this object, you can write and configure a macro to run when the session starts and to automatically log you in using the credentials of the currently logged in Reflection ZFE user.

Table 10-19 AutoSignon

Method
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.

Method

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.

10.1.17 Position

Represents a row and column on the screen.

Table 10-20 Position

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

Method

Position(row,col)

Creates a new Position instance.

Parameters

{Number} row screen row coordinate

{Number} col screen column coordinate

10.1.18 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.

Table 10-21 PresentationSpace

METHODS
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 ControlKeys 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 ControlKeys 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(position,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.

10.1.19 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.

Table 10-22 Session object functions

METHODS
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 connected available device name, the configured device name, or null if no device name is configured. The connected device name is the name agreed upon during the connection negotiation process between the host and the terminal. It may be what is specified, or it could possibly be different, if for example a device name pool was specified. Returns {String}The connected device name, the configured device name, or null.
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 Operator Information Area (OIA) instance for this session. Returns {OIA} Associated with this session

10.1.20 SessionType

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

Table 10-23 SessionType

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

10.1.21 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.

Table 10-24 StatusSet

Method
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. {Object} thisArg optional pointer to a context object.
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

10.1.22 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.

Table 10-25 User Interaction

METHODS
prompt(message,[defaultAnswer], [mask])	Prompt 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.

METHODS

prompt(message,[defaultAnswer], [mask])

Prompt 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.

10.1.23 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.

Table 10-26 Waiting for the host

METHODS
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
forCursor(position, [timeout])	Waits for the cursor to arrive at the specified position. Parameters {Position} The position specifying the row and column, {Number} timeout in milliseconds Returns {Promise}Fulfilled if the cursor is already located or when it is finally located. Rejected if the wait times out.
forText(string, 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(string, 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.