Connecting to z/OS by using the Remote Connection Emulator

Many enterprises engaged in long-term mainframe application development have numerous tools, utilities, jobs, processes, and best practices that rely on a traditional 3270 development environment. The Remote Connection Emulator integrates traditional 3270 tools and practices into the Eclipse integrated development environment (IDE). It provides basic access to the mainframe for viewing unique information and mainframe tools and processes that are not available in the workbench. By using Remote Connection Emulator, you can connect to the remote system and open a full-screen emulator.

Migration notes

The Remote Connection Emulator can migrate emulator sessions in workspaces that were created by prior versions of the client, but you might notice these differences or limitations:
  • The session profile names might be changed. The Remote Connection Emulator creates profiles with a default name that matches the connection name, but you can rename the profile:
    1. To open the profile, click Edit profile Edit profile.
    2. Expand the Connection information section and update the Profile name field.
    3. Save your changes and close the session.
    4. In the Remote Systems view, right-click the connection name and select Remote Connection Emulator. The new name is displayed in the list of profiles.
  • If session profile includes a key mapping to the paste command, that key mapping is not migrated. Keys can no longer be mapped to the paste command.
  • For workspaces created on a macOS client, the certificate file for secure connection is not migrated. For more information about certificate files for secure connections on macOS, see Preparing a certificate file for secure connections from macOS.

The default session type is telnet 3279. If you use the 16.0.x or 17.0.x client to open a workspace that was created by a 15.0.x client, and that workspace has an active Remote Connection Emulator session, the Session type setting retains the value that was set in the workspace. To change the session type, click Edit profile Edit profile, and expand the Connection information section.

Limitation: Migrating from version 16 to version 17 does not migrate Remote Connection Emulator profiles. You must create Remote Connection emulator profiles for z/OS connections in your version 17 workspace.

Before you start

Create a connection to a remote system. For instructions, see Creating a connection to a z/OS® system or watch the following demonstration.

Creating a connection to a remote system

Starting a host session

  1. In the Remote Systems view, select a z/OS system connection.
  2. If this is your first time starting a session and you have no profile, right-click and select Remote Connection Emulator > Create Profile. The product creates a profile for the host connection, saves it in a file with extension .json in the RemoteConnectionEmulatorProjectFiles folder of the Eclipse workspace folder, and opens the emulator window.
    Remote Connection Emulator menu with no connection profile
  3. If you already have at least one profile, you can either select it from the Remote Connection Emulator menu or create another profile. If you select a profile, the product opens the emulator window with the selected profile.
    Remote Connection Emulator menu with one profile
    Important: Because Remote Connection Emulator profiles are associated with specific connection names, renaming a remote system connection results in loss of the associated profiles. To reclaim lost profiles, restore the connection name.
  4. To connect to the remote system, click Connect Connect, and then log on to the remote system using your user ID and password.
Tip:
  • To maximize the session window size, double-click the session tab or click Maximize Maximize. To detach the session window from the editor area of the perspective, right-click the emulator tab and select Detach. For more information about working with detached views, see Detaching views and editors.
  • To open help for the Remote Connection Emulator window click Help in the toolbar
Opening the Remote Connection Emulator

Quick guide to emulator tools

Use the toolbar icons to interact with the terminal emulator, modify connection settings, and get help:

Connect Disconnect: Connect or disconnect from the remote system.

Toggle Crosshairs: Open a crosshair to track the cursor location.

Keypad: Open the secondary keyboard. By default, the keypad is opened on the left side of the emulator window. To move it to the bottom of the window, edit the Display section of the session profile. For more information about editing the profile, see Display properties.

Edit profile: Set connection, security, key mapping, terminal colors, and screen type, size, font, and code page options for the session. To learn more about these options, see Setting session properties.

Help: Open the IBM Documentation for Remote Connection Emulator in an external browser window.

Changing session settings

Accessibility

You can use keyboard shortcuts to quickly move focus between different areas of the Remote Connection Emulator window.
Table 1.
Shortcut Description
Alt+H Moves focus to the header section, which includes RCE actions such as Toggle Secondary Keyboard, Show Ruler, Help, Record Macro, and Play Macro.
Alt+F Moves focus to the footer section, which displays details such as the host name, insert or replace mode, and cursor position.
Alt+M Returns focus to the main RCE screen, allowing you to continue working in the emulator session.

Macro Support

Macro support in the Remote Connection Emulator, allowing you to record, play back, and manage repetitive actions in the emulator window. Macros can capture keystrokes, cursor moves, and defined actions to automate common workflows.

Recording a macro
  1. Click the Record Macro option in the emulator toolbar.
  2. While recording, perform the actions you want to capture, this can include typing, moving the cursor, or pressing defined keys such as Tab, function keys, Attn, PA1, or Reset.
  3. While recording:
    • The Play Macro option is disabled.
    • A flashing Record icon appears in the bottom-left corner of the emulator window.
  4. To stop recording, click the Stop icon (replaces the Record option).
Tip: Make sure host responses are consistent; mismatched timing may affect playback.
Playing back a macro
  1. Click the Play Macro option in the toolbar.
  2. In the playback dialog, select a macro to run.
  3. Actions in the macro are performed sequentially.
  4. While playing back:
    • The Record Macro option is disabled.
    • A flashing Playback icon appears in the corner.
    • To stop playback at any time, click the Stop icon.
Note: Keystroke actions during playback are ignored.
Macro management in settings
The Macro section in the settings page displays all recorded macros in a table and provides these actions:
  • View macro content: Inspects the recorded actions.
  • Rename macro: Each macro initially has a timestamp-based name; validation ensures new names are valid.
  • Delete macro: Removes unwanted macros.
  • Export macro: Downloads macro contents to a local machine, useful for VS Code environments.
  • Import macro: Allows you to upload macros from your local machine.
    Note: The import functionality is not part of the macros table.
  • Map key combinations: Assigns macros to keyboard shortcuts, including combination and control keys.
    Note: Key mappings for macros are performed in the Key Mapping section, not in the Macro section.
Macro file format
Macros are stored as text files. Each line can contain:
  • Text: User-typed text in double quotes.
    • Passwords: When the emulator detects password input, it records the word Prompt in the macro file. During playback, you will be prompted to manually enter the password.
  • CursorMoveAction: Followed by row and column integers (1-based). Values outside valid ranges are automatically adjusted.
  • Defined Actions: Predefined commands like LeftAction, TabAction, UpAction. Invalid actions trigger validation errors.
Limitation:
  • Macro support assumes the host responds consistently, unexpected prompts or timing changes may affect execution.
  • Very long macros may take longer to play back or export.
  • Recording and playback option are mutually exclusive, both are disabled when in the settings page.
Note: Editing macros manually is optional, the system validates syntax and semantics.

Copying, cutting, and pasting text

You can copy, cut, and paste text in the emulator:
  1. Use the mouse or the Shift+arrow keys to select an area of text. Use the drag points to expand or contract the selection box. To move the selection box, place the cursor inside it, left-click, and drag the box to a new location.
  2. Press Ctrl+C or ⌘+C to copy, or Ctrl+X or ⌘+X to cut.
  3. Press Ctrl+V or ⌘+V to paste.
Copying and pasting text

Splitting and cloning emulator sessions

You can split an active emulator session either vertically or horizontally, or clone a session to generate a copy of it. Both splitting a session and cloning a session result in creating a copy of the session profile, which you can edit as needed.
  • To split an emulator session window, click Window > Editor > Toggle Split Editor (Horizontal) or Window > Editor > Toggle Split Editor (Vertical). These actions open a new emulator session in the same editor tab as the original session. The new session opens on the Edit profile page so that you can alter and save profile settings.
  • To clone an emulator session, click Window > Editor > Clone. This action opens an emulator session in a new editor tab. The new session opens on the Edit profile page so that you can alter and save profile settings.
Splitting and cloning emulator sessions

Setting trace options for the Remote Connection Emulator

If you need to gather trace data for the emulator, use the Preferences window to set trace options:
  1. In the Preferences window, click Tracing (Window->Preferences->Tracing).
  2. In the Tracer Name list, select com.ibm.remote.connection.emulator.
  3. Set the tracing level to FINE or FINER. The FINEST level of tracing might generate too much data and is intended for use only in rare cases when extended traces are needed. During tracing, trace entries are produced and placed in the workspace\.metadata\.trace file.
For more information about setting trace options, see Tracing. For more information about the Preferences window, see Preferences.

Limitations and troubleshooting

If the emulator hangs, try these steps:
  • Click Disconnect and Connect to disconnect and reconnect.
  • Close the Remote Connection Emulator session and restart it.
If the Remote Connection Emulator session loses focus, click Remote Connection Emulator in the upper left corner of the session.
Remote Connection Emulator session window with cursor positioned on "Remote Connection Emulator"
macOS: If you move focus away from the Remote Connection Emulator session and then return to it, focus is not regained.

You might also see these issues and limitations with the emulator. This list is not comprehensive.

Starting a host session
If Remote Connection Emulator fails to start, you might need to configure a working directory for the S3270 executable file. Use the Remote Connection Emulator Preferences page to specify a working directory. For instructions, see Configuring a working directory.
Creating and editing profiles
  • If a profile is created and then the host connection name is changed, the profile might disappear.
  • If a message window stating No more handles ... opens when you create a Remote Connection Emulator profile, restart your workspace and retry the operation.
  • If you configured the z/OS connection to use client certificates, and the profile page displays the message No certificate alias was found. when you try to select a client certificate, do these steps:
    1. Open the workbench Preferences window, and select Client Certificates.
    2. Clear the entry in the hostIdMappings object identifier (OID) field, and then click Apply and Close.
Other issues and limitations
  • A profile might become unusable if you change your network connection. This issue occurs in these scenarios, and might occur in others as well:
    • Connect to a profile over a wireless network connection. Disconnect. Try to reconnect through a VPN over a different wireless network connection.
    • Connect through a VPN. Disconnect. Try to reconnect over a wireless hotspot.
    • Connect through a VPN over one wireless network connection. Disconnect. Attempt to connect through the same VPN, but over a different wireless network connection.
  • You might notice differences in terminal styling between Remote Connection Emulator and IBM® Personal Communications:
    • The command line is yellow instead of red.
    • In JCL the following characters are green instead of yellow: = ( )&
    • In the ISPF editor, block selections are not highlighted.