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

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