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 other best practices. The Remote Connection Emulator integrates traditional 3270 practices and tools into the Eclipse integrated development environment (IDE). It provides basic access to the mainframe for viewing unique information and other mainframe 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.

Limitation: The Remote Connection Emulator is not available on the Linux® client.
For a quick introduction to the capabilities of the Remote Connection Emulator, click these links. For a more detailed explanation of the functions, settings, and properties, see the links in each section.
Migration notes:
  • The default session type is telnet 3279. If you open a workspace that was created in an earlier version of the 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 Session Properties Session Properties.

Before you start

Create a connection 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

Back to top

Starting a host session

  1. In the Remote Systems view, select a z/OS system connection.
  2. Right-click and select Remote Connection Emulator.
  3. If this is your first time starting a session, the product prompts you to name it, such as rce-session-1. The product saves session settings in a file with extension .rces3270 in the RemoteConnectionEmulatorProjectFiles folder of the Eclipse workspace folder. You can also navigate to any location to save emulator session files.
  4. If you already have multiple session files, the product prompts you to choose a session to open.
  5. Log on to the remote system using your user ID and password.
Tip:
  • To maximize the session window size, double-click the top session tab or press Ctrl+M. To detach the session window from the editor area of the perspective, right-click the top session tab and select Detach.
  • To open help for the main Remote Connection Emulator window and for the Session Properties, Keyboard Remap, and Terminal Styling slider windows, click the ? icon at the top or bottom of the window. The corresponding help topic opens in IBM® Documentation.
Opening the Remote Connection Emulator

Back to top

Cloning and splitting sessions

You can create and save multiple sessions by cloning and splitting active sessions.

  • To clone a session, click the top tab of a session, and then select Window > Editor > Clone. The product prompts you to name the session file, for example, rce-session-2.
  • To split a session, click the top tab of a session, and then select Window > Editor > Toggle Split Editor (Horizontal) or Toggle Split Editor (Vertical). The product prompts you to name the session file.

The new sessions are independent of each other. Any changes you make to session settings, such as changing font colors, are saved in the session file. If you make changes to the settings of a session that you want to clone, save the session, then close and reopen it before cloning it. The saved settings are cloned to the new session.

Cloning and splitting the Remote Connection Emulator

Back to top

Changing session settings

Use the toolbar icons to modify the connection or terminal emulator settings:

Connect/Disconnect: Connect or disconnect from the remote system.

Secondary keyboard: Open the PF keyboard.

Crosshairs: Open a crosshair to track the cursor location.

Session Status Updates: Open session status updates. Most recent status messages are displayed at the top of the status sliding window. Scroll this window to see older status messages. TCP/IP communication error codes are platform-specific. To capture detailed communication error information, enable tracing as described in Setting trace options for the Remote Connection Emulator. For information about TCP/IP error codes, see these topics:

Session Properties: Set connection and security options for the session. You can also click the Host Properties tab to set session connection and security options. To learn more about these options, see Setting session properties.

Keyboard Remap: Change keyboard mappings for the session. To learn more about keyboard mappings, see Customizing the keyboard

Terminal Styling: Change colors and fonts in the emulator. To learn more about these options, see Setting colors and fonts.

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

Changing session settings

Back to top

Copying, cutting, and pasting text

You can copy, cut, and paste text in the emulator:
  1. Select an area of text.
  2. Press Ctrl+C or ⌘_C to copy, or Ctrl+X or ⌘+X to cut.
  3. Press Ctrl+V or ⌘+V to paste.
Copying, pasting, and printing text

Back to top

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.
  4. In the emulator, open the session settings and select Enable trace.
For more information about setting trace options, see Tracing. For more information about the Preferences window, see Preferences.

Back to top

Limitations and troubleshooting

If the emulator hangs and disconnecting and reconnecting does not solve the problem, close the Remote Connection Emulator session and restart it.
macOS: If you move focus away from the Remote Connection Emulator session and then return to it, focus is not regained.
If the logon screen appears garbled, you might need to enable JavaScript in your browser or override the default browser that the Eclipse workbench uses. Do these steps:
  1. To determine which browser the workbench is using, click Window > Show View > Other.
  2. Expand the General folder, select Internal Web Browser, and then click Open.
  3. In the internal web browser address field, type https://www.whatismybrowser.com/, and then click Go to the selected URL.
  4. If the internal browser is Internet Explorer 11, do one of these options:

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.
  • If you cannot maximize the session window by double-clicking the top session tab, try pressing Ctrl+M.
  • macOS:
    When connecting to the host over a secure connection, you might see these issues on macOS:
    • An exception might be written to the error log.
    • If you configure the TLS session with a client certificate and password for the client certificate, and then close and reopen the session, the connection fails. This failure to connect occurs because the client certificate password is not retained in the Host Properties tab.
      To work around this issue:
      1. In the product Preferences window, navigate to General > Security > Secure Storage.
      2. On the Password tab, clear the OS X Keystore Integration checkbox and click Save and Close.
      3. When prompted, enter a password and click Save.
    • If you change settings in Session Properties, Keyboard Remap, or Terminal Styling, the certificate password is cleared and must be entered again.
    Note: You must create and enter a master password for each secure session. If you shut down and restart a workspace that contains a secure Remote Connection Emulator connection, you are prompted to enter the master password again.
Cloning and splitting sessions
  • If you click Cancel during a cloning operation, the clone is created, but it is not named and saved.
Changing session settings
  • If you cannot see all of the fields in the sliding windows for Secondary Keyboard, Session Properties, Keyboard Remap, and Terminal Styling, maximize the Remote Connection Emulator window.
  • macOS Keyboard Remap:
    • Remapping a key to eraseField, eraseInput, or insert might cause unexpected characters to be inserted in the entry field. To work around this limitation, remap these commands to the left ⌘ Command key or to any key on the Secondary keyboard secondary keyboard and use the secondary keyboard rather than the physical keyboard. Because the eraseInput and eraseField commands are already mapped to the secondary keyboard, you use secondary keys that are already defined for them.
    • If you click the Clear key, enter text in the Remote Connection Emulator window, and then press Enter, the emulator session is disconnected.
Copying, cutting, and pasting text
On macOS, you can copy, cut, and paste text only within the Remote Connection Emulator window. You cannot paste text into the Remote Connection Emulator that was copied or cut from an external window or application, such as a text editor.
ISPF sessions
While using ISPF in the Remote Connection Emulator, you might experience these issues. This list is not comprehensive.
  • If the host sends an update to the client, the current input might be cleared.
  • Resizing the Remote Connection Emulator session window can cause the lines that represent text entry fields to disappear or become disjointed. You can type into the entry fields even if the line is broken or not visible.
  • When you type text in a command line, or press the space bar or backspace key to delete text from a command line, the text and fields might shift to the left or right.
  • When you type text in a command line, the cursor does not always move to the correct location.
  • Windows: In a multi-line input field, such as the ISPF Command Shell, if you press Backspace to delete the last character of a line, the cursor is not set to the correct position.
Other issues and limitations
  • 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.
  • macOS: On macOS, entering a CICS command might disconnect your Remote Connection Emulator session. For some CICS commands, you can work around this issue by selecting New Line from the Secondary Keyboard Secondary Keyboard.

Back to top