Change Timeout

Change the timeout for connection in seconds.

Arguments

Argument	Type	Default value
seconds	timedelta	null

Usage

Change Timeout

3 seconds

Change Wait Time

To give time for the mainframe screen to be "drawn" and receive the next commands, a "wait time" has been created, which by default is set to 0.5 seconds. This is a sleep applied AFTER the following keywords:

Arguments

Argument	Type	Default value
wait_time	timedelta	null

If you want to change this value, just use this keyword passing the time in seconds.

Usage

Change Wait Time	0.5
Change Wait Time	200 milliseconds
Change Wait Time	0:00:01.500

Change Wait Time After Write

To give the user time to see what is happening inside the mainframe, a "wait time after write" has been created, which by default is set to 0 seconds. This is a sleep applied AFTER sending a string in these keywords:

Arguments

Argument	Type	Default value
wait_time_after_write	timedelta	null

If you want to change this value, just use this keyword passing the time in seconds.

Note: This keyword is useful for debug purpose

Usage

Change Wait Time After Write	1
Change Wait Time After Write	0.5 seconds
Change Wait Time After Write	0:00:02

Close All Connections

Close all currently opened connections and reset the index counter to 1.

Close Connection

Close the current connection.

Delete Char

Delete the character under the cursor. If you want to delete a character that is in another position, simply pass the coordinates ypos / xpos.

Arguments

Argument	Type	Default value
ypos	int, None	None
xpos	int, None	None

Coordinates are 1 based, as listed in the status area of the terminal.

Usage

Delete Char
Delete Char	ypos=9	xpos=25

Delete Field

Delete the entire content of a field at the current cursor location and positions the cursor at beginning of field. If you want to delete a field that is in another position, simply pass the coordinates ypos / xpos of any part in the field.

Arguments

Argument	Type	Default value
ypos	int, None	None
xpos	int, None	None

Coordinates are 1 based, as listed in the status area of the terminal.

Usage

Delete Field
Delete Field	ypos=12	xpos=6

Execute Command

Execute a x3270 command.

Arguments

Argument	Type	Default value
cmd	str	null

Usage

Execute Command	Enter
Execute Command	Home
Execute Command	Tab
Execute Command	PF(1)
Execute Command	Scroll(backward)	# To send Page Up
Execute Command	Scroll(forward)	# To send Page Down

Get Current Position

Returns the current cursor position. The coordinates are 1 based.

Arguments

Argument	Type	Default value
mode	ResultMode	As_Tuple

By default, this keyword returns a tuple of integers. However, if you specify the mode with the value "As Dict" (case-insensitive), a dictionary in the form of {"xpos": int, "ypos": int} is returned.

Usage

Get Cursor Position		# Returns a position like (1, 1)
Get Cursor Position	As Dict	# Returns a position like {"xpos": 1, "ypos": 1}

Get String Positions

Returns a list of tuples of ypos and xpos for the position where the string was found, or an empty list if it was not found.

Arguments

Argument	Type	Default value
string	str	null
mode	ResultMode	As_Tuple
ignore_case	bool	False

If you specify the mode with the value "As Dict" (case-insensitive), a list of dictionaries in the form of [{"xpos": int, "ypos": int}] is returned.

If ignore_case is set to True, then the search is done case-insensitively.

Usage

${positions}	Get String Positions	Abc		# Returns a list like [(1, 8)]
${positions}	Get String Positions	Abc	As Dict	# Returns a list like [{"ypos": 1, "xpos": 8}]

Get String Positions Only After

Returns a list of tuples of ypos and xpos for the position where the string was found, but only after the specified ypos/xpos coordinates. If it is not found an empty list is returned.

Arguments

Argument	Type	Default value
ypos	int	null
xpos	int	null
string	str	null
mode	ResultMode	As_Tuple
ignore_case	bool	False

If you specify the mode with the value "As Dict" (case-insensitive), a list of dictionaries in the form of [{"xpos": int, "ypos": int}] is returned.

If ignore_case is set to True, then the search is done case-insensitively.

Usage

${positions}	Get String Positions Only After	5	4	Abc		# Returns a list like [(5, 5)]
${positions}	Get String Positions Only After	5	4	Abc	As Dict	# Returns a list like [{"ypos": 5, "xpos": 5}]

Get String Positions Only Before

Returns a list of tuples of ypos and xpos for the position where the string was found, but only before the specified ypos/xpos coordinates. If it is not found an empty list is returned.

Arguments

Argument	Type	Default value
ypos	int	null
xpos	int	null
string	str	null
mode	ResultMode	As_Tuple
ignore_case	bool	False

If you specify the mode with the value "As Dict" (case-insensitive), a list of dictionaries in the form of [{"xpos": int, "ypos": int}] is returned.

If ignore_case is set to True, then the search is done case-insensitively.

Usage

${positions}	Get String Positions Only Before	11	20	Abc		# Returns a list like [(11, 19)]
${positions}	Get String Positions Only Before	11	20	Abc	As Dict	# Returns a list like [{"ypos": 11, "xpos": 19}]

Move Cursor To

Moves the cursor to the specified ypos/xpos position. The coordinates are 1 based. This keyword raises an error if the specified values exceed the Mainframe screen dimensions.

Arguments

Argument	Type	Default value
string	str	null
mode	ResultMode	As_Tuple
ignore_case	bool	False

Usage

Move Cursor To

1

5

Move Next Field

Move the cursor to the next input field. Equivalent to pressing the Tab key.

Move Previous Field

Move the cursor to the previous input field. Equivalent to pressing the Shift+Tab keys.

Open Connection

Create a connection to an IBM3270 mainframe with the default port 23. To establish a connection, only the hostname is required. Optional parameters include logical unit name (LU) and port.

Arguments

Argument	Type	Default value
host	str	null
LU	str, None	None
port	int	23
extra_args	List[str], PathLike, None	None
alias	str, None	None

Additional configuration data can be provided through the extra_args parameter. extra_args accepts either a list or a path to a file containing x3270 command line options.

Entries in the argfile can be on one line or multiple lines. Lines starting with "/libraries/3rd-party-libraries/mainframe3270#" are considered comments. Arguments containing whitespace must be enclosed in single or double quotes.


-accepthostname myhost.com


-xrm "wc3270.acceptHostname: myhost.com"

-charset french
-port 992

Please ensure that the arguments provided are available for your specific x3270 application and version. Refer to the wc3270 command line options for a subset of available options.

Note: If you specify the port with the -port command-line option in extra_args (or use the -xrm resource command for it), it will take precedence over the port argument provided in the Open Connection keyword.

This keyword returns the index of the opened connection, which can be used to reference the connection when switching between connections using the Switch Connection keyword. For more information on opening and switching between multiple connections, please refer to the Concurrent Connections section.

Usage

Open Connection	Hostname
Open Connection	Hostname	LU=LUname
Open Connection	Hostname	port=992
@{extra_args}	Create List	-accepthostname	myhost.com	-cafile	${CURDIR}/cafile.crt
Append To List	${extra_args}	-port	992
Open Connection	Hostname	extra_args=${extra_args}
Open Connection	Hostname	extra_args=${CURDIR}/argfile.txt
Open Connection	Hostname	alias=my_first_connection

Open Connection From Session File

Create a connection to an IBM3270 mainframe using a session file.

Arguments

Argument	Type	Default value
session_file	PathLike	null
alias	str, None	None

The session file contains resources (settings) for a specific host session.

The only mandatory setting required to establish the connection is the hostname resource.

This keyword is an alternative to Open Connection. Please note that the Robot-Framework-Mainframe-3270-Library currently only supports model "2". Specifying any other model will result in a failure.

For more information on session file syntax and detailed examples, please consult the x3270 wiki.

This keyword returns the index of the opened connection, which can be used to reference the connection when switching between connections using the Switch Connection keyword. For more information on opening and switching between multiple connections, please refer to the Concurrent Connections section.

Usage

Open Connection From Session File

${CURDIR}/session.wc3270

where the content of session.wc3270 is:

wc3270.hostname: myhost.com:23
wc3270.model: 2

Page Should Contain All Strings

Assert that all the strings in a given list exist on the mainframe screen.

Arguments

Argument	Type	Default value
list_string	List[str]	null
ignore_case	bool	False
error_message	str, None	None

The assertion is case-sensitive. If you want it to be case-insensitive, you can pass the argument ignore_case=True.

You can change the exception message by setting a custom string to error_message.

Usage

Page Should Contain All Strings	${list_of_string}
Page Should Contain All Strings	${list_of_string}	ignore_case=True
Page Should Contain All Strings	${list_of_string}	error_message=New error message

Page Should Contain Any String

Assert that one of the strings in a given list exists on the mainframe screen.

Arguments

Argument	Type	Default value
list_string	List[str]	null
ignore_case	bool	False
error_message	str, None	None

The assertion is case-sensitive. If you want it to be case-insensitive, you can pass the argument ignore_case=True.

You can change the exception message by setting a custom string to error_message.

Usage

Page Should Contain Any String	${list_of_string}
Page Should Contain Any String	${list_of_string}	ignore_case=True
Page Should Contain Any String	${list_of_string}	error_message=New error message

Page Should Contain Match

Assert that the text displayed on the mainframe screen matches the given pattern.

Arguments

Argument	Type	Default value
txt	str	null
ignore_case	bool	False
error_message	str, None	None

Pattern matching is similar to matching files in a shell, and it is always case-sensitive. In the pattern, * matches anything and ? matches any single character.

Note that for this keyword the entire screen is considered a string. So if you want to search for the string "something" and it is somewhere other than at the beginning or end of the screen, it should be reported as follows: *something*

The assertion is case-sensitive. If you want it to be case-insensitive, you can pass the argument ignore_case=True.

You can change the exception message by setting a custom string to error_message.

Usage

Page Should Contain Match	*something*
Page Should Contain Match	*so???hing*
Page Should Contain Match	*someTHING*	ignore_case=True
Page Should Contain Match	*something*	error_message=New error message

Page Should Contain String

Assert that a given string exists on the mainframe screen.

Arguments

Argument	Type	Default value
txt	str	null
ignore_case	bool	False
error_message	str, None	None

The assertion is case-sensitive. If you want it to be case-insensitive, you can pass the argument ignore_case=True.

You can change the exception message by setting a custom string to error_message.

Usage

Page Should Contain String	something
Page Should Contain String	someTHING	ignore_case=True
Page Should Contain String	something	error_message=New error message

Page Should Contain String X Times

Asserts that the entered string appears the desired number of times on the mainframe screen.

Arguments

Argument	Type	Default value
txt	str	null
number	int	null
ignore_case	bool	False
error_message	str, None	None

The assertion is case-sensitive. If you want it to be case-insensitive, you can pass the argument ignore_case=True.

You can change the exception message by setting a custom string to error_message.

Usage

Page Should Contain String X Times	something	3
Page Should Contain String X Times	someTHING	3	ignore_case=True
Page Should Contain String X Times	something	3	error_message=New error message

Page Should Match Regex

Fails if string does not match pattern as a regular expression. Regular expression check is implemented using the Python re module. Python's regular expression syntax is derived from Perl, and it is thus also very similar to the syntax used, for example, in Java, Ruby and .NET.

Arguments

Argument	Type	Default value
regex_pattern	str	null

Backslash is an escape character in the test data, and possible backslashes in the pattern must thus be escaped with another backslash (e.g. \\d\\w+).

Page Should Not Contain All Strings

Fails if one of the strings in a given list exists on the mainframe screen. If one of the string are found, the keyword will raise an exception.

Arguments

Argument	Type	Default value
list_string	List[str]	null
ignore_case	bool	False
error_message	str, None	None

The assertion is case-sensitive. If you want it to be case-insensitive, you can pass the argument ignore_case=True.

You can change the exception message by setting a custom string to error_message.

Usage

Page Should Not Contain All Strings	${list_of_string}
Page Should Not Contain All Strings	${list_of_string}	ignore_case=True
Page Should Not Contain All Strings	${list_of_string}	error_message=New error message

Page Should Not Contain Any String

Assert that none of the strings in a given list exists on the mainframe screen. If one or more of the string are found, the keyword will raise an exception.

Arguments

Argument	Type	Default value
list_string	List[str]	null
ignore_case	bool	False
error_message	str, None	None

The assertion is case-sensitive. If you want it to be case-insensitive, you can pass the argument ignore_case=True.

You can change the exception message by setting a custom string to error_message.

Usage

Page Should Not Contain Any Strings	${list_of_string}
Page Should Not Contain Any Strings	${list_of_string}	ignore_case=True
Page Should Not Contain Any Strings	${list_of_string}	error_message=New error message

Page Should Not Contain Match

Assert that the text displayed on the mainframe screen does NOT match the given pattern.

Arguments

Argument	Type	Default value
txt	str	null
ignore_case	bool	False
error_message	str, None	None

Pattern matching is similar to matching files in a shell, and it is always case-sensitive. In the pattern, * matches anything and ? matches any single character.

Note that for this keyword the entire screen is considered a string. So if you want to search for the string "something" and it is somewhere other than at the beginning or end of the screen, it should be reported as follows: *something*

The assertion is case-sensitive. If you want it to be case-insensitive, you can pass the argument ignore_case=True.

You can change the exception message by setting a custom string to error_message.

Usage

Page Should Not Contain Match	*something*
Page Should Not Contain Match	*so???hing*
Page Should Not Contain Match	*someTHING*	ignore_case=True
Page Should Not Contain Match	*something*	error_message=New error message

Page Should Not Contain String

Assert that a given string does NOT exist on the mainframe screen.

Arguments

Argument	Type	Default value
txt	str	null
ignore_case	bool	False
error_message	str, None	None

The assertion is case-sensitive. If you want it to be case-insensitive, you can pass the argument ignore_case=True.

You can change the exception message by setting a custom string to error_message.

Usage

Page Should Not Contain String	something
Page Should Not Contain String	someTHING	ignore_case=True
Page Should Not Contain String	something	error_message=New error message

Page Should Not Match Regex

Fails if string does match pattern as a regular expression. Regular expression check is implemented using the Python re module. Python's regular expression syntax is derived from Perl, and it is thus also very similar to the syntax used, for example, in Java, Ruby and .NET.

Arguments

Argument	Type	Default value
regex_pattern	str	null

Backslash is an escape character in the test data, and possible backslashes in the pattern must thus be escaped with another backslash (e.g. \\d\\w+).

Read

Get a string of length at screen coordinates ypos / xpos.

Arguments

Argument	Type	Default value
ypos	int	null
xpos	int	null
length	int	null

Coordinates are 1 based, as listed in the status area of the terminal.

Example for read a string in the position y=8 / x=10 of a length 15:

${value}

Read

8

10

15

Read All Screen

Read the current screen and returns all content in one string.

This is useful if your automation scripts should take different routes depending on a message shown on the screen.

Usage

${screen}	Read All Screen
IF	'certain text' in '''${screen}'''
	Do Something
ELSE
	Do Something Else
END

Read From Current Position

Similar to Read, however this keyword only takes length as an argument to get a string of length from the current cursor position.

Arguments

Argument	Type	Default value
length	int	null

Register Run On Failure Keyword

This keyword lets you change the keyword that runs on failure during test execution. The default is Take Screenshot, which is set on library import.

Arguments

Page Should Not Contain String	something
Page Should Not Contain String	someTHING	ignore_case=True
Page Should Not Contain String	something	error_message=New error message

You can set None to this keyword, if you do not want to run any keyword on failure.

Usage

Register Run On Failure Keyword	None	# no keyword is run on failure
Register Run On Failure Keyword	Custom Keyword	# Custom Keyword is run on failure

Send Enter

Send an Enter to the screen.

Send PF

Send a Program Function to the screen.

Arguments

Argument	Type	Default value
pf	str	null

Usage

Send PF

3

Set Screenshot Folder

Set a folder to keep the html files generated by the Take Screenshot keyword.

Arguments

Argument	Type	Default value
path	str	null

Note that the folder needs to exist before running your automation scripts. Else the images will be stored in the ${OUTPUT DIR} set by robotframework.

Usage

Set Screenshot Folder

C:\\Temp\\Images

Switch Connection

Switch the current connection to the one identified by index or alias. Indices are returned from and aliases can be optionally provided to the Open Connection and Open Connection From Session File keywords.

Arguments

Argument	Type	Default value
alias_or_index	str, int	null

For more information on opening and switching between multiple connections, please refer to the Concurrent Connections section.

Examples:

Open Connection	Hostname	alias=first
Open Connection	Hostname	alias=second	# second is now the current connection
Switch Connection	first		# first is now the current connection

Take Screenshot

Generate a screenshot of the IBM 3270 Mainframe in a html format. The default folder is the log folder of RobotFramework, if you want change see the Set Screenshot Folder.

Arguments

Argument	Type	Default value
keyword	str	null

The Screenshot is printed in an iframe log, with the values of height=410 and width=670, you can change these values by passing them to the keyword.

The file name prefix can be set, the default is "screenshot".

The full file path is returned.

Usage

${filepath}	Take Screenshot
${filepath}	Take Screenshot	height=500	width=700
Take Screenshot	height=500	width=700
Take Screenshot	filename_prefix=MyScreenshot

Wait Field Detected

Wait until the screen is ready, the cursor has been positioned on a modifiable field, and the keyboard is unlocked.

Sometimes the server will "unlock" the keyboard but the screen will not yet be ready. In that case, an attempt to read or write to the screen will result in a 'E' keyboard status because we tried to read from a screen that is not ready yet.

Using this method tells the client to wait until a field is detected and the cursor has been positioned on it.

Wait Until String

Wait until a string exists on the mainframe screen to perform the next step. If the string does not appear in 5 seconds, the keyword will raise an exception. You can define a different timeout.

Arguments

Argument	Type	Default value
txt	str	null
timeout	timedelta	0:00:05

Usage

Wait Until String	something
Wait Until String	something	10
Wait Until String	something	15 s
Wait Until String	something	0:00:15

Write

Send a string and Enter to the screen at the current cursor location.

Arguments

Argument	Type	Default value
txt	str	null

Usage

Write

something

Write Bare

Send only the string to the screen at the current cursor location.

Arguments

Argument	Type	Default value
txt	str	null

Usage

Write Bare

something

Write Bare In Position

Send only the string to the screen at screen coordinates ypos / xpos.

Arguments

Argument	Type	Default value
txt	str	null
ypos	int	null
xpos	int	null

Coordinates are 1 based, as listed in the status area of the terminal.

Usage

Write Bare in Position

something

9

11

Write In Position

Send a string and Enter to the screen at screen coordinates ypos / xpos.

Arguments

Argument	Type	Default value
txt	str	null
ypos	int	null
xpos	int	null

Coordinates are 1 based, as listed in the status area of the terminal.

Usage

Wait Until String	something
Wait Until String	something	10
Wait Until String	something	15 s
Wait Until String	something	0:00:15