iSeries Access for Linux 5250 Emulator

September 2003

Contents 1

PURPOSE OF THIS DOCUMENT AND ASSUMPTIONS ...................................................1

2

MAIN EMULATOR FUNCTIONS ......................................................................................1 2.1 EMULATOR LANGUAGES ...............................................................................................1 2.2 EMULATOR MODULES /F ILENAMES ..................................................................................2 2.2.1 Emulator modules (object code)...........................................................................2 2.2.2 Emulator MRI Text Files ......................................................................................2 2.2.3 Emulator Read/Write Files ...................................................................................3 2.3 EMULATOR F UNCTIONS /F EATURES .................................................................................3 2.3.1 Emulator Functions .............................................................................................3 2.3.2 5250 Emulator Resources ...................................................................................4 2.3.3 5250 Keyboard Remapping .................................................................................6 2.3.4 5250 Color Mapping............................................................................................7 2.3.5 Miscellaneous Preferences ..................................................................................9 2.3.6 Record/Playback .............................................................................................. 10 2.3.7 5250 Pop-up/Pull down Keypads ....................................................................... 11 2.3.8 5250 Help Viewer ............................................................................................. 13 2.3.9 5250 Screen Print ............................................................................................. 13 2.3.10 5250 Image/Fax (3849 Emulation) ..................................................................... 14 2.3.11 5250 Session ID ............................................................................................... 14 2.3.12 5250 Copy/Cut/Paste........................................................................................ 14 2.3.13 5250 Hot Spots................................................................................................. 15 2.4 5250 START - UP/COMMAND L INE O PTIONS .................................................................... 15 2.5 EMULATOR LAYOUT AND A PPEARANCE.......................................................................... 18 2.5.1 5250 Emulator Status Line ................................................................................ 18 2.6 ISERIES ACCESS LICENSE ................................................................................... 19

1 Purpose of this document and assumptions This document is a description of current 5250 Emulator functionality. iSeries Access: The 5250 Emulator is designed to be Linux distribution independent. The dependencies on the Linux distribution are glibc 2.2 and openmotif 2.*. The distribution must also support installing an rpm created with rpm 3.0. The iSeries Access for Linux 5250 emulator is a client implementation. It is intended to be used on a Linux client, defined as a system with a single Linux user, using 1 Linux userid. The emulator may be run on a Linux server but only 1 user id should attempt to execute the 5250 code at one time. While one userid is using a 5250 session, other sessions started with another userid, other then root, will not start. Scalable 75 and 100 DPI fonts MUST be available on the Linux OS. This means the fonts need to be on the system and X configured to use scalable 75 and 100 DPI fonts.

2 Main Emulator Functions The primary method to configure the Emulator is with preferences. There is command line parameter support for a subset of the preferences. Values passed in on the command line take precedence over values set as a preference.

2.1 Emulator Languages The main emulator window labels and helper applications are translated and will display based on the $LANG system environment variable. The command line value –LANGID may also be used to set the language. The setup5250 program and help display English text until translated text is made available. OS400 language 2922 2924 2925

Locale pt_PT en_US fi_FI

Description Portuguese in Portuguel English Finnish

2926

da_DK

Danish

2928

fr_FR

French

2929

de_DE

German

2931

es_ES

Spanish

2932

it_IT

Italian

2933

no_NO

Norwegian

2937

sv_SE

Swedish

2939

de_CH

German Swiss

2940

fr_CH

French Swiss

2942

it_CH

Italian Swiss

2963

nl_BE

Belgium

2966

fr_BE

French in Belgium

2980

pt_BR

Portuguese in Brazil

2981

fr_CA

French Canadian

2.2 Emulator Modules/Filenames 2.2.1 Emulator modules (object code) The iSeries Access for Linux binaries are installed in /opt/ibm/iSeriesAccess/bin, with links from /usr/bin/ibm5250 and /usr/bin/setup5250 to the corresponding binary in the /opt/ibm/iSeriesAccess/bin directory. These binaries are part of the emulator package: ibm5250 miscpref5250 helpviewer colormapper keymapper keypad playedit printapp setup5250 2.2.2 Emulator MRI Text Files The iSeries Access for Linux text is stored in /opt/ibm/iSeriesAccess/mri/%locale% The entire locale, as specified by the system environment variable $LANG or the emulator command line value –LANGID is used to determine the locale to use for emulator window labels and help text. If a directory matching the entire locale is not found, then a directory that matches the first 2 chars of the locale is searched for. If no match is still found, text from the en_US directory is used. This is an example of the directories searched for a de_DE locale: de_DEàdeàen_US These files contain text used by emulator labels and messages: File ColrMpTx.rc KeymapTx.rc N3MscPTx.rc HelpVwTx.rc

Description Color map resource Key map resource Misc. preferences resource Help viewer resource

LocPrtTx.rc

Screen print resource

NS3270Tx.rc

3270/5250 main resource

SetupMRI.rc

Setup tool resource

These files contain the help text displayed by the emulator:

2

File N3ClHelp.hlp N3HelpTx.hlp N3KPHelp.hlp

Description Color map help text Help viewer help text Key pad help text

N3KyHelp.hlp

Key map help text

N3PEHelp.hlp

Playback/Edit help text

SetupHTx.hlp

Setup tool help text

2.2.3 Emulator Read/Write Files The emulator reads/writes files in the user’s home directory. iSeries Access for Linux reads/writes the files from $HOME/.iSeriesAccess/ibm_5250/. Description for 5250

Location

Keyboard remapping Color mapping Record/playback sequences

$HOME/.iSeriesAccess/ibm_5250/K/* $HOME/.iSeriesAccess/ibm_5250/C/* $HOME/.iSeriesAccess/ibm_5250/P/*

Miscellaneous preferences

$HOME/.iSeriesAccess/ibm_5250/Miscellaneous

Keypad data

$HOME/.iSeriesAccess/ibm_5250/W/*

Global preferences

$HOME/IBM5250

Server connections defined with setup5250 Printer preferences

$HOME/.iSeriesAccess/ibm_5250/EmulConnections

Userid/password configured as part of connection with setup5250 Userid/password configured as global preference with setup5250 Application location/font information, specific to a screen resolution

$HOME/.iSeriesAccess/ibm_5250/EmulConnections5250.auth

$HOME/.iSeriesAccess/ibm_5250/LocalPrint

$HOME/.iSeriesAccess/ibm _5250/IBM5250.auth $HOME/.iSeriesAccess/ibm_5250/Desktop example Desktop1024x768

2.3 Emulator Functions/Features 2.3.1

Emulator Functions

The 5250 emulator provides function equivalent to an IBM 5250 terminal. The emulator also provides extended 5250 terminal functions similar to those provided by PC/5250 and IBM RUMBA/400 emulators. The emulator supports the following functions: • Customizable multi-session support (up to 99) • Customizable menu bar/pull downs • Scalable fonts: user selects from a few listed fonts which scale when the window border is dragged. • Maximize window support • Remember initial window placement and font • Saving a desktop file for window placement and font if initial geometry is not defined. • On-line help • Keyboard remapping • Session level color mapping • Record/playback • User-customizable pop-up and pull down keypads • Auto-start of playback file • Auto-logon • Copy/cut/paste • 24x80 and 27x132 screen size support • Dynamic window management for screen size changes (27x132) • Settable 5250 display names • Secure Sockets Layer (SSL) support—not available in the September 2003 release • Screen print to PostScript printers (parallel, serial, remote) • Monochrome, grey scale, and color image/fax viewing and printing; 3489 emulation • DP mode (normal 5250 mode) support of primary and foreground color extended attributes • Easily changed Enter/Field Exit key locations

3

• • • • • • • • • • • • • 2.3.2

Customizable automatic Help key on operator error Fixed hot spots: menu, function key, More..., Enter key emulation (customizable: off, single click, or double click; also URL hot spots are recognized) Hot spot highlighting option Cursor style options: block/underscore and blink/no blink Rule line Row/column indicator Shift and Caps Lock indicators Customizable window title Column separator customization Type-ahead customization Session ID to identify a session (similar to PCOMM session short name) Automatic, customizable, communication error recovery Auto-disconnect option after specified inactivity time

5250 Emulator Resources Resource NS5250*27x132: enable or disable NS5250*ColumnSeperator: enable or disable NS5250*ImageView: enable or disable

Function 27x132 enable/disable Column separators enable/disable Image/fax viewing enable/disable

NS5250*Keymap: enable, disable, or disable_and_hide

Is user allowed to remap keyboard

NS5250*Keymap101Path

Default 101 key map file

NS5250*Keymap102Path

Default 102 key map file

NS5250*KeymapPath

Default key map file

NS5250*ColorMap: advanced, basic, disable, or disable_and_hide NS5250*DefaultColorMapPath:

Is user allowed to change colors

NS5250*ColorMapPath:

Default color schemes

NS5250*KeyPad: enable, disable, or disable_and_hide

Is the keypad function available

NS5250*KeyPadPath

Default keypad files

NS5250*PlayBack: enable, disable, or disable_and_hide

Are record and playback available

NS5250*PlayBackPath

Default playback files

NS5250*MiscPref: enable, disable, or disable_and_hide

Is Miscellaneous preferences available Is screen print available

NS5250*LocalPrint: enable, disable, or keyboard_only_local_print NS5250*Control: enable or disable

4

Default color map file

Is control menu displayed

NS5250*Edit: enable or disable

Is edit menu displayed

NS5250*Command: enable or disable

Is command menu displayed

NS5250*Option: enable or disable

Is option menu displayed

NS5250*Help: enable or disable

Is help menu displayed

NS5250*FontMenu: enable, disable, or disable_no_resize_or_move NS5250*ChangeIPAddress: enable or disable

Is font menu list displayed Can user change IP address for New 5250 session

Resource NS5250*BrowserStart: enable or disable

Function Hot spot browser start allowed

NS5250*CURSOR_BLINK: ENABLE or DISABLE

Cursor blink

NS5250*CURSOR_STYLE: BLOCK_INSERT_UNDERSCORE_REPLACE, UNDERSCORE_INSERT_BLOCK_REPLACE, BLOCK, or UNDERSCORE NS5250*DESTRUCTIVE_BACKSPACE: ENABLE or DISABLE NS5250*ENTER_KEY: USE_DEFAULT, ENTER_ENTER_AND_RIGHT_CTRL_NEWLINE, ENTER_NEWLINE_AND_RIGHT_CTRL_ENTER, ENTER_ENTER_AND_RIGHT_CTRL_FIELD_EXIT, or ENTER_FIELD_EXIT_AND_RIGHT_CTRL_ENTER NS5250*ERROR_RESET_KEYS: RESET, CURSOR_MOVEMENT_ALSO,or MOST_KEYS NS5250*KEYBOARD_BUFFERING: ENABLE, DISABLE, or USE_AS400_SETTING NS5250*HOTSPOTS: DISABLE, ENABLE, SINGLE_CLICK, or DOUBLE_CLICK NS5250*HOTSPOT_HIGHLIGHTING: ENABLE or DISABLE NS5250*INPUT_ONLY_CURSOR_MOVEMENT: ENABLE or DISABLE NS5250*INSERT_MODE: DEFAULT_OFF_AUTOMATIC RESET, DEFAULT_OFF_NO_AUTOMATIC RESET, or DEFAULT_ON_NO_AUTOMATIC_RESET NS5250*PASTE_LOCATION: AT_CURSOR or AT_MOUSE_POINTER NS5250*PRINT_KEY: USE_DEFAULT, PRINT_IS_SCREEN_PRINT, or SHIFTED_PRINT_IS_SCREEN_PRINT NS5250*ROW_COLUMN_INDICATOR: ENABLE or DISABLE NS5250*RULE_LINE: ENABLE_KEY_FOLLOW_CURSOR, ENABLE_KEY_FIXED, ENABLE_FOLLOW_CURSOR, or DISABLE NS5250*RULE_LINE_STYLE: BOTH or VERITCAL

Cursor style

NS5250*AUTOMATIC_HELP: ENABLE or DISABLE

Automatic help on operator error

NS5250*BLUE_UNDERSCORE: ENABLE or DISABLE

Blue underscore

NS5250*LARGE_SCREEN_BEHAVIOR: USE_LAST_FONT, MOVE_WINDOW_AND_REDUCE_FONT_IF_NEEDED, REDUCE_FONT_ONLY, or REDUCE_FONT_AND_MOVE_WINDOW_IF_NEEDED NS5250*COPY_PASTE_ACCESS: ENABLE or DISABLE

Large screen (27x132) behavior

NS5250*DEFAULT_COPY_TYPE: LINEAR or BLOCK

Default copy type

NS5250*DESKTOP_FUNCTION: ENABLE or DISABLE

Desktop file write allowed

NS5250*SESSION_ID: 20 characters within double quotes, or 18 or 19 characters in double quotes with +n

Session ID

Destructive backspace Enter/New Line/Field Exit

Error reset keys Keyboard buffering Hotspots Hot spot highlighting Input only cursor movement Insert mode

Paste location Print key

Row column indicator Rule Line

Rule line style

Copy paste access

5

2.3.3

Resource where n is a number 1-99

Function

NS5250*DISPLAY_NAME: 20 characters in double quotes

Display name

NS5250*MAX_SESSIONS: 1-99

maximum number of sessions

NS5250*EMULATOR_GEOMETRY: ww x hh + xx + yy

emulator geometry

NS5250*EURO: ENABLE, DISABLE, or NOT_SPECIFIED

Euro

NS5250*INACTIVITY_TIMEOUT: 0 to 9999 in minutes

Inactivity timer

NS5250*RETRY_COUNT: Number of retries, default is 144 NS5250*RETRY_INTERVAL: time between retries in seconds, default in 300 nd NS5250*QUICK_RETRY_INTERVAL: time before 2 and rd 3 quick retries in seconds NS5250*CONNECT_TIMEOUT: Time allow for initial telnet connect in seconds, default is 15 NS5250*BLINKING_TEXT: ENABLE or DISABLE

Communication error retry count

NS5250*TITLE: title text with double quotes

Title text

NS5250*TITLE_OPTION: TEXT_ONLY, SESSION_ID_ONLY, TEXT_AND_SESSION_ID, TEXT_HOST_AND_SESSION_ID, or TEXT_AND_HOST NS5250*STARTUP_PLAYBACK: File name of playback file NS5250*LARGEST_IMAGE: Largest image/fax in thousands of bytes, default is 400 NS5250*DEBUG: TRUE or FALSE

Title options

NS5250*TRACE: TRUE or FALSE

Trace mode

NS5250*PORT: port from 1 to 99999

5250 port

Communication error retry interval Communication quick retry interval Communication connect time-out should attribute text blink

Startup playback file Largest 5250 image Debug mode

5250 Keyboard Remapping

The 5250 emulator includes a GUI keyboard remapping program for 5250 sessions. Access to the keyboard remapping program is controlled with a resource value. Valid values for the resource are: • “enable”: The user is allowed to modify their keyboard mapping for 5250 sessions. The keyboard mapping menu item is displayed in the Option menu. • “disable”: The user is not allowed to modify their keyboard mapping. The default resource value is disable. The result is the menu option being grayed out and cannot be selected by the user from the Option pull down menu. • “disable_and_hide”: The user is not allowed to modify their keyboard mapping and the menu item for the keyboard mapping file is not displayed in the Option pull down menu. Each 5250 session has a session name determined at 5250 session startup time. The session name contains the name of the iSeries partition the session is connecting to and a 5250 session number (1-99). The session name enables the user to use multiple keyboard maps for multiple 5250 emulation sessions. A keyboard map file contains all the keystroke mapping information. A keyboard map file applies to only one type of keyboard: for example a 101 key PC keyboard or 102 key PC keyboard. At session startup, a keyboard mapping table is built using the following process: 1. Checks if a -KEYFILE command line option was specified.

6

2. 3. 4.

5.

Check for a keyboard file matching the name of the 5250 session. Check for a default keyboard mapping file (ex. Default.101) If a file does not exist, check if a resource is set. For example, a resource NS5250*Keymap101Path: is typically followed by a full path name (directory and file name) of a default keyboard remapping file for a 101 key keyboard. The resource could be followed by “0” indicating a default keyboard mapping does not exist. Valid resources and file extensions are: NS5250*Keymap101Path “path/filename”.101 NS5250*Keymap102Path “path/filename”.102 If none of the above exists, the internal defaults are used for the session.

If a user modifies their 5250 keyboard mapping, the user can apply the changes to the current session without saving the changes to their user directory. If the user wishes to save the changes, the user can select to save the modified keyboard map as: • The default keyboard map file (used by all 5250 sessions) • A session specific keyboard map file • A personal keyboard map file The maximum file name length for a keyboard map file is 32 characters. Blanks are allowed in the name. The saved keyboard map immediately applies to the 5250 session that was used to start the keyboard mapping program. Other emulator sessions must be exited and restarted to pick up the new keyboard map. The keyboard map may be printed. 2.3.4

5250 Color Mapping

The emulator supports a GUI color mapping program for emulation sessions. The color mapping program supports 8, 16, and 24 bit color systems. The basic color mapping program defines up to 10 different colors for each of the five default basic color schemes; all but two of the basic scheme colors (wheat background and light blue background) come from the WEB color palette. The advanced color mapping program can define up to 22 unique colors for each session. Access to the color mapping program is controlled with a resource. The valid resource values are: • “advanced”: The user is allowed to remap their colors for 5250 emulation sessions. The user can use either basic color mapping or use advanced color mapping. • “basic”: The user is allowed to use the basic portion of the colormapper program. Basic is the default resource setting. Basic color mapping allows the user to choose between five basic background and foreground color schemes. • “disable”: The user is not allowed to change the colors of the emulation sessions. The color map menu item in the Option menu is grayed out and can not be selected. • “disable_and_hide”: The user is not allowed to change the colors of their emulation sessions. The pull down menu is not displayed in the Option menu. Each emulation session has a session name, determined at 5250 session initialization. The session name contains the name of the AS/400 that the session connected to and a session number into that AS/400 (1-99). The session name enables the user to use multiple color maps for multiple 5250 emulation sessions. At session initialization, the emulator determines if a color map file exists following these steps: 1. 2.

Check if there is a session specific color map file in the user’s home directory, where the name of the file matches the name of the session and the file extension is .session. Check if there is a user default color map in the user’s home directory where the name of the file is default.default.

7

3. 4.

5.

Check to see if a color map file is specified in a resource. The default color map resource NS5250*DefaultColorMapPath: can be followed by a full path (directory and filename) to the default color mapping file or a “0” if there is no default color map for the user. A default color map has the extension .advanced. No color map is used and the default black background is used.

When a user selects color mapping from the Option pull down menu, a new window is presented with two choices at the top of the window: Basic and Advanced. The advanced option is grayed out unless the resource value is set to advanced. Basic color mapping allows a user to choose from a list of color schemes: • List of advanced color schemes created by the user via advanced color mapping read from user’s color map directory • List of advanced color schemes defined as default advanced color mapping schemes. The list comes from the NS5250*ColorMapPath resource. • Default color schemes: Ø black background Ø light grey background Ø dark grey background Ø light background Ø light blue background Advanced color mapping allows the user to control the color of the following individual components of an emulator session (defaults listed also): • 5250 menu bar foreground: black • 5250 menu bar background: grey • 5250 window background: black • 5250 pushbutton background: dark grey • 5250 blue text: blue • 5250 green text: green • 5250 pink text: pink • 5250 red text: red • 5250 turquoise text: turquoise • 5250 white text: white • 5250 yellow text: yellow • 5250 cursor color: white • 5250 mouse color: white • 5250 rule line color: blue • 5250 status line foreground: turquoise • 5250 status line background: black • 5250 monochrome image foreground: black • 5250 monochrome image background: white • Assist programs window background: grey • Assist programs group box background: light grey • Assist programs scrollable list/entry field background: off white • Assist programs foreground: black If a user modifies their 5250 color mappings, they can apply the changes to their current session without saving the changes in their user directory. An example 5250 window and example assist program window with all the colors configured is displayed on the right side of the basic and advanced window. This allows a user to verify that all foreground text colors are readable. If the user exits from the 5250 session that launched the color mapping, a dialogue box is presented asking if the user wishes to save color mapping changes or exit without saving the changes.

8

If a user chooses a new basic color scheme and wishes to save the changes, the user can select saving the modified color map as a: • Default color map used for all 5250 sessions. • Session specific color map. If a user creates a new advanced color scheme and wishes to save the changes, the user is prompted for a name of the color scheme. The color scheme name will be displayed when using basic color mapping. Blanks are allowed in the color map name. The maximum file name length is 32 characters. Basic color mapping is used to select an advanced color scheme for the specific session or as a default for all sessions. A saved color map file immediately applies to the 5250 session the color mapping program was started from. Other emulator sessions must be exited and restarted to pick up the new colors. 2.3.5 Miscellaneous Preferences The emulator has a miscellaneous preferences program that allows the user to fine tune their 5250 sessions. The program is launched via a pull down menu item under the Option menu. A resource entry controls the availability or unavailability of the miscellaneous preferences menu item. Valid values for the reference are: • “enable”: The user is allowed to use 5250 miscellaneous preferences. Enable is the default value. • “disable_and_hide”: The user is not allowed to use the 5250 miscellaneous preferences program and the menu item is not displayed. At 5250 session initialization, the emulator checks to see if there is a Miscellaneous file in the user’s directory (/home/user/ibm_5250). If the file is not found, the internal defaults are used. The 5250 miscellaneous preferences are (defaults listed also): • Cursor Style (underscore or block; default is block in insert mode and underscore in replace mode) • Cursor Blink (disable or enable; default is disable) • Enter/Field Exit key locations (default is Enter and Right Control key; four other options are available) • Print key location (default is normal location of Print and Screen Print) • Destructive Backspace key (enable or disable; default is enable) • Hot spots (disabled, primary button press, or primary button double click; default is primary button press) • Hot spots highlighting (disable or enable; default is disable) • Paste start location (cursor or mouse pointer; default is cursor) • Auto Help for operator error (enable or disable; default is enable) • Operator error reset (reset key, reset key plus cursor movement keys, or most keys; default is reset key) • Keyboard buffering (use OS/400 setting, enable, or disable; default is use OS/400 setting) • Large screen behavior (default is move the window and change font; four other options are available) • Row column indicator (display or do not display; default is display) • Rule line key (enable the rule line key following the cursor is the default; three other options are available) • Rule line style (horizontal and vertical is default) • Blue underscore (disable or enable; disable is default)

9

The miscellaneous preferences user interface lists the preferences on the left and the selected preference on the right. A set defaults button allows the user to set all preference settings to the original defaults. When a preference is modified, the change is temporarily applied to all 5250 sessions. There is an overlap between keyboard mapping files and Enter/Field Exit Key location, Print Key location, and Destructive Backspace. If the user has modified Enter/Field Exit Key location via miscellaneous preferences, the user’s miscellaneous preference takes priority. The same is true for Print Key. 2.3.6

Record/Playback

The emulator supports record/playback capability (sometimes called keyboard macros) for 5250 sessions. The user can record and later playback keystrokes (and mouse) events; any recorded sequences are stored in a file in the user’s directory. A resource entry controls the availability or unavailability of the record playback program; the resource values are: • “enable”: The user is allowed to record and playback keystroke sequences. The default value is enable. • “playback_only”: The user is allowed to playback keystroke sequences, which are probably default playback files. The Record pull down option is not displayed. The Record key is also disabled. • “disable_and_hide”: The user is not allowed to record or playback keystroke sequences. The pull down options Record and Playback are not displayed and the Record and Playback keys are disabled. The user can start recording two ways: 1. Select the Record choice from the pull down menu. 2. Press the Record key A recording may be played five ways: 1.

Select the Playback choice from the pull down menu. A list of files is presented.

2.

Press the Playback key followed by the specified accelerator key. (function key)

3.

Auto-logon playback files will play when the session starts.

4.

Press a user-mapped key to play the desired playback file. Keyboard mapping allows a key, or key sequence, to be mapped to a specific playback file.

5.

Select a keypad button associated with the desired playback file. Pop-up and pull down keypads are supported. A specific playback file can be played when the user selects a specific keypad button. The user creates a keypad, defines the keypad button text and keyboard action or playback file associated with each keypad button.

Playback sequences are the same for all 5250 emulation sessions for a given user: • Default playback files: Each playback sequence is stored in a separate file. The default playback resource NS5250*PlayBackPath: is typically followed by one full path (directory and file name) or more to default playback files. Multiple paths are separated by a comma. If the resource is followed by a “0”, there is no default playback file. • When the user requests a playback, check if the playback file is in the user’s playback directory: iSeriesAccess: $HOME/.iSeriesAccess/IBM_5250/P/ User accelerator keys take priority over default accelerator keys (if a match occurs). An auto-logon playback file is specified on the startup file (-playback). The playback file is automatically started as soon as the first 5250 screen is received.

10

Recording: The user may pause a recording in progress. The 5250 emulator automatically pauses when the user presses a data key in a non-display entry field. The user may pause the recording to specify the user’s Userid or Password should be inserted during playback, for an auto-logon playback file. The maximum playback file size is 8K bytes. When the user completes the record sequence, the user enters a name for the playback file. The name may contain blanks. Defining an accelerator key is optional. If an accelerator key is specified, the accelerator key becomes an extension on the file name. For example is F4 is configured as an accelerator key the playback file name could be “playback file name”.F4. If no accelerator key is specified, the playback file name does not have an extension. An existing playback file can not be edited. To make changes to an existing file, a new recording needs to be done and then saved as the existing file name. The new recording will replace the previous recording. A playback window is normally presented when playback is started. If the user selected Playback from the pull down menu or pressed the Playback key, the user selects a playback file to play. The playback window has two scrollable lists of playback files: the user’s playback files and default playback files. The user can control the speed of the playback by adjusting a playback speed slider bar in the playback window. The record and playback program detects the following: • Matching name found in the user’s directory; user is asked to verify that this recording should overwrite the previous playback file. • Playback requested but the default playback file not longer exists • Accelerator key playback attempted, but no matching playback file 2.3.7

5250 Pop-up/Pull down Keypads

Emulator users may create keypads. Each keypad has keypad buttons; each button has a userdefined keyboard action or a playback file associated with it. When a user selects a keypad button, the keyboard action/playback is processed in the 5250 session. Each keypad is available in one of two user interface options: 1. A separate pop-up keypad window. When a user selects a keypad button, the keyboard action/playback is processed in the 5250 session that launched the keypad window. Pop-up keypads are dynamic, the user decides when a pop-up keypad window is or is not displayed. 2. A keypad pull down with keypad buttons available through the main emulator menu bar (Keypad option is added to the emulator menu bar). Valid resource values for the keypad resource entry are: •

“enable”: The use is allowed to create, change, and user keypads. The default resource value is enable.

•

“keypad_only”: The user is allowed to use keypads, but is not allowed to create or change keypads. The keypad customization pull down choice is not displayed.

•

“disable_and_hide”: The user is not allowed to use keypads. The two pull down keypad choices are not displayed for the user.

The Keypad pull down choice is used to display one or more pop-up keypad windows. If the user has exactly on pop-up keypad file that pop-up keypad window is displayed. If the user has

11

multiple pop-up keypad files, the user selects one or more pop-up keypad windows to be displayed from a multiple choice selection dialogue box. The default keypad resource NS5250*KeyPadPath: is typically followed by one or more full paths (directory and file name) to default keypad files. Multiple paths are separated by a comma. If the resource is followed by the character “0”, there is no default keypad file for the user. Each pop-up window has: • A title that is a portion of the 5250 session title: the OS400 partition name or IP address and the session number. The window title is useful to tie the pop-up keypad window to the launching 5250 session window. • User-customized buttons that perform a keyboard action or playback file. The user controls the layout of the keypad buttons: for example, 1x4, 6x1, or 4x4. All keypad buttons are the same size. The size of the keypad buttons is controlled by the user. The Customize Keypad program allows the user to specify that the keypad functions should be available though a keypad pull down instead of a pop-up keypad window. If the user selects this choice, a Keypad menu bar choice is included in the main 5250 window if the user has any pull down keypads: • If the user has one pull down keypad file, selecting Keypad lists the buttons text as pull down choices. • If the user has multiple pull down keypad files, selecting Keypad lists the pull down keypad files; select a keypad file displays a drop-down list with the button text as dropdown list choices. • If the user has no pull down keypad files, the Keypad menu bar choice is not displayed. A user can have both pop-up keypads and pull down keypads. The user can easily change from one type of keypad to the other. The Customize Keypad pull down choice allows the user to create or change a keypad. The customize keypad code is in a separate module that is loaded only when the user selects this pull down choice. If the user has a keypad file, a dialogue box asks the user to select an existing keypad to change or create a new keypad. The customize keypad window allows the user to: • Define keypad buttons: including button text and keypad actions or a playback file associated with the button. The user can edit the keypad action areas. A list of keyboard actions and playback files are available for the user to select. • Change an Existing keypad button. • Delete an existing keypad button. • Move keypad buttons. • Specify if the keypad is a pop-up keypad or pull down keypad. • Set the row/column dimensions of a pop-up keypad window. • Set the size of each button in a pop-up keypad window. • A save pushbutton that allows the user to save this pop-up keypad. The user gives the keypad a file name. The maximum length of the file name is 32 characters and can contain blanks. • A cancel pushbutton that cancels the customize window. If the user has unsaved changes, should probably present a dialogue asking if the user wishes to exit with or without saving changes • A help pushbutton that launches pop-up keypad help text. • Also, a separate keypad window shows the keypad under construction. For a pull down keypad, the keypad window is shown as one column wide. The -KEYPAD startup command line option causes a pop-up keypad window to be created at the same time that the 5250 session window is created. A pop-up keypad file name should follow -

12

KEYPAD. The keypad may come from the user’s keypad directory or from a list of system default keypads made available to the user. Pop-up keypad windows will use the same foreground/background colors as the 5250 emulator menu bar of the session that launched the keypad window. 2.3.8 5250 Help Viewer The help viewer program is used to view 5250 emulator on-line help text files: • Main 5250 on-line help • Keyboard remapping help • Color mapping help • Keypad help A separate window pops up with a scrollable index of topics on the left side of the window and scrollable topic help text on the right side of the window. The help viewer supports searching forward and backward. Next/previous topic navigation is supported. Help text may be printed by topic or completely. 2.3.9 5250 Screen Print Screen print prints the contents of the 5250 session to a locally attached printer or a network printer. Screen print uses the default printer environment variable. If a printer other then the default printer is desired, that printers name needs to by typed into the displayed lpr command. A resource controls the availability of screen print. Valid resource values are: • “enable”: The user is allowed to screen print. The Print menu bar choice is displayed on the menu bar. The default value is enable. • “keyboard_only_local_print”: The user is allowed to screen print using the Screen Print key on the keyboard. The Printer menu bar choice is not displayed to the user. • “disable_and_hide”: The user is not allowed to screen print. The Print menu bar choice is not displayed to the user and the Print Screen key is disabled. The emulator creates a PostScript level 2 printer data stream User preference items include: • Target printer will be the configured default system printer or the user may type another printer name. • Portrait or landscape • Image/fax or text print if image/ fax is on the screen • Printer page size for image/fax printing When the user selects the screen print, the following text formatting is done: • Non-display date changes to blanks • Attributes change to blanks • Text assist characters (OV/editor) change to blanks • ENPTUI characters change to their character equivalents • DUP character is changed to an asterisk • Underscore is printed: Ø Underscore is used for ASCII for underscored nulls Ø Begin/end underscore commands are used for PostScript. • Color, intensify (bold), reverse image, and column separators are not printed.

13

2.3.10 5250 Image/Fax (3849 Emulation) 5250 monochrome image/fax viewing and printing to PostScript printers is supported. 5250 color and grey scale JPEG and TIFF image viewing and printing is supported. Color PCX is supported. A resource entry controls 5250 image/fax; the resource values are: • “enable”: The user is allowed to display image/fax. Enable is the default resource value. • “disable”: The user is not allowed to display image and fax. 5250 emulator image/fax support: • Viewing support equivalent to or better than the 3489: image/fax formats, scrolling, scaling, rotation, reverse, trim magnify scaling, etc. • The maximum image/fax size is dynamic based on: Ø The default size is 400,000 bytes of source (compressed) image/fax. The command line parameter LARGEST_IMAGE can increase or decrease the size of the maximum image/fax. Ø The available memory of the system Ø The largest image/fax that the 3489 can display is 128K bytes. Applications may not send more than that to the emulator. • Image/fax printing is supported to PostScript printers. 2.3.11 5250 Session ID The session ID can be defined by a command line option or a resource. The session ID can be a single value; for example “Smith”. A set of session Ids can be defined; for example, Smith+n where n is 3 would make 3 session Ids available, “Smith1”, “Smith2”, and “Smith3”. Each 5250 session has a unique session ID. If a session ID is defined, it is used. If a session ID is not defined, default session IDs are defined, “A”, “B”, ….“Z”, “AA”, “AB”,... If a user has one or more session IDs defined and already has 5250 sessions active using those session Ids, default session Ids are defined for subsequent 5250 sessions, starting with “A”. The 5250 session ID will be used by the following: • 5250 window title: the default window title is the window title text, a colon, and the defined session ID. If a 5250 session has a default session ID, the target AS/400 and session number continue to be used in the 5250 window title. • The DeskTop file stores the user’s last 5250 window locations and font size. If a 5250 session has a defined session ID, this is used in the DeskTop file. If a 5250 session has a default session ID, the target AS/400 and session number are used in the DeskTop file instead. • The 5250 jump key can jump between all 5250 windows. The jump action can also have a session number as a parameter; for example, if jump(3) is defined as the action for a key sequence, this key sequence jumps to the third 5250 window. The jump action also allows a session ID as a parameter, for example, jump(“Smith”). • Color mapping allows a color map file to be stored for a specific 5250 session. If a 5250 session has a defined session ID, the session specific color mapping file applies to that session ID. • Keyboard mapping allows a keyboard map file to be stored for a specific 5250 session. If a 5250 session has a defined session ID, the session specific keyboard map file applies to that session ID. 2.3.12 5250 Copy/Cut/Paste The 5250 emulator supports copy, cut, and paste within an emulator session, and between different emulator sessions. Linear and rectangular copy and paste are supported.

14

Copy, cut, and paste are available through the Edit menu bar choice. Keyboard-driven copy and paste is supported. 2.3.13 5250 Hot Spots The emulator supports fixed hot sports. Hot spot text must be in an output area (not within an entry field). Hot spot click customization is supported: single click, double click, or disabled. Hot spot highlighting is available.

2.4 5250 Start-up/Command Line Options The format of the command line to invoke a 5250 emulator session is: ibm5250 AS/400Name -title “my session title” -wide disable -image enable -geometry WWxWH+Xoffset+Yoffset -DISPLAY_NAME SMITH+3 –iconic • •

•

• • • •

•

•

•

ibm5250 is the application name and is case sensitive AS/400Name is typically specified and defines the AS/400 to which the 5250 emulation session will communicate. The name could be a host name or an IP address. If the AS/400Name is not specified, the emulator will prompt the user for the name or IP address. -title is optional and case sensitive. Title text follows that is case sensitive. If the title text contains a space, the title text must be within double quotes. The title text is displayed in the 5250 session window overriding the 5250 window title text resource value. Title text is truncated if longer than thirty characters. When the 5250 session dialogue (menu pull down) is used to start another 5250 session, the same title is used. -TITLE_OPTION is option and case sensitive, followed by one the following: TEXT_AND_SESSION_ID (default), TEXT_ONLY, SESSION_ID_ONLY, TEXT_HOST_AND_SESSIONID, or TEXT_AND_HOST. -wide is optional and is case sensitive. Either “enable” or “disable” should follow and are case sensitive. This parameter enables or disables 27x132 support. -image is optional and is case sensitive. Either “enable” or “disable” should follow and are case sensitive. This parameter enables or disables image/fax viewing. The default is “enable”. -LARGEST_IMAGE is optional and case sensitive. A 3 or 4 digit numeric parameter follows which indicates the maximum source image/fax size which will be displayed. The parameter indicates the number of thousands of bytes to be accepted. The 5250 emulator has a default value of 400; displaying an image or fax up to 400,000 bytes in size. This parameter is undocumented in help text. -LANGID is optional and case sensitive. A 5 digit parameter follows which contains the locale to be used. The –LANGID will override the Linux environment variable $LANG and determine the conversions to be used on the OS400 data stream. The emulator window decorations will be determined by the $LANG or –LANGID value of the first emulator session started. -geometry is optional and case sensitive. Window width, window height, x offset, and y offset follow (WWxWH+Xoffset+Yoffset). The 5250 window will be placed according to the values. The window size parameters are adjusted as necessary to fit the font that fills the window. If a maximized window is desired using the largest font that will fit for the particular monitor resolution, use -geometry 9999x9999+0+0. -playback or -PLAYBACK is optional and case sensitive. A case sensitive file name of a 5250 playback file follows. This function enables “auto-logon” so users do not need to again type in their userid and password. This function also enables automatically starting

15

•

• •

a playback file, which allows users to get to a specific AS/400 screen. The playback file can be from the user’s playback directory or a default playback file. -keypad or -KEYPAD is option, case sensitive, and used to automatically start a pop-up keypad window when the 5250 emulator session starts. A case sensitive pop-up keypad file name follows. Multiple -keypad command line options can be specified; to start multiple pop-up keypad windows (each with a different keypad file). The keypad file can be from the user’s keypad directory or be a default keypad file. -KEYFILE is optional, case sensitive, and used to specify a user named keyboard remapping file to be used for the 5250 emulator session. A case sensitive keyboard remapping file name follows including a keyboard type file extension. -DISPLAY_NAME is optional, case sensitive, and followed by one parameter. The following rules apply to AS/400 5250 session names: Ø Each active 5250 session must have a unique session name Ø The first character must be an alpha character Ø All characters must be alpha, numeric, a period, or an underscore Ø All alpha characters must be upper case Ø Session names must be 2 to 10 characters in length One of the following types of parameters may be used for the display name: 1. XXXXXX where XXXXXX is a 2 to 10 character name of one 5250 session. 2. XXXXXX+n where XXXXXX is the 1 to 9 character base portion of the 5250 session names on the target AS/400 and n is the number digit from 1 to 9 and determines the number of sessions this user can start to target OS400 using this command line. 3. “XXXXXX YYY ZZZZ” is a list of possible display names separated by a space. The starting and ending quotes are required. Each name can be 2 to 10 characters in length. The names are attempted in order. The maximum number of names in the list is limited to 256 characters. 4. USE_USER_ID allows the user to start one 5250 session where the session name will be the user’s userid (2 to 10 characters). 5. USE_USER_ID+n allows the user to start n 5250 sessions where the session name will be the user’s userid (2 to 10 characters) USE_USER_ID+99 is also supported. Ninety-nine 5250 sessions are allowed using the user’s userid. USE_USER_ID+999 is also supported. Up to 999 5250 sessions are allowed. 6.

Text+USE_USER_ID is another variation of USE_USER_ID. A text string between 1 and 8 characters can be defined as a leading text string to the userid. The userid will be truncated to fit the session name to 10 characters.

7.

Text+USE_USER_ID+n is also supported and allows up to 9 sessions to be started. Text+USE_USER_ID+99 and text+USE_USER_ID+999 are also supported.

8.

USE_USER_ID+text is another variation of USE_USER_ID. Text between 1 and 8 characters can be appended to the user id. The userid will be truncated to fit the session name to 10 characters.

9.

USE_USER_ID+text+n is supported where n is a numeric digit between 1 and 9 and specifies the number of sessions that can be started from this command line. The text cannot start with a digit. USE_USER_ID+text+99 and USE_USER_ID+text+999 are also supported.

10. USE_HOST_NAME uses the workstation hostname as the session name. Th e hostname will be converted to upper case for the session name. The host name cannot exceed 10 characters.

16

11. USE_HOST_NAME+n is also supported where n is a numeric digit between 1 and 9 specifying how many 5250 sessions can be started from this command line. •

• •

• • •

•

• • • •

•

• • •

-SESSION_ID is optional, case sensitive, and followed by an ID for the 5250 session. The session ID text can be upper or lower case and up to 20 characters in length. If there is a space in the session ID text, the session ID text must be contained within double quotes. Ø +n is also supported where n is a numeric digit between 1 and 99. No spaces are allowed between the text and “+n”. -EURO, -Euro, -euro, and -NOEURO are optional, case sensitive, and specify if the European monetary symbol should or should not be used. The command line option is ignored for languages that do not support the Euro symbol. -SSL or -ssl is optional, case sensitive, and followed by a case sensitive file name or directory and file name. The emulator automatically adds a “.kyr” extension and “.sth” extension before reading the SSL files. The default port is 992 if SSL is specified. SSL is not supported in the September 2003 iSeries Access release. -NO_SSL or -no_ssl disables SSL if activated from a preference. SSL is not supported in the September 2003 iSeries Access release. -port or -PORT is case sensitive and allows a 5250 session to use a port number other than the default. For non-SSL telnet, the default port number is 23. A 1 to 4 digit port number follows the command line option. -INACTIVITY is optional, case sensitive, and followed by a numeric parameter from 0 to 9999 that specifies if a 5250 session should be ‘signed off’ (telnet disconnect/reconnect) after the specified inactivity time has expired. The default value is 0 indicating no inactivity timer. -BLOCK_COPY is optional, case sensitive, and specifies that the 5250 emulator should default to block copy (vs. Linear copy) when marking an area for copy or cut. Normally, linear copy is the default (pressing and dragging the primary mouse button marks the linear area) and block copy is available through a double click. -NO_COPY_PASTE is optional, case sensitive, and specifies that the emulator should not allow copy, cut, or paste into or out of the emulator session. -SESSION_COPY_PASTE_ONLY is optional, case sensitive, and specifies that the 5250 emulator should only allow copy, cut, and paste within the emulator session. -COPY_PASTE is optional, case sensitive, and specifies the emulator should allow copy, cut, and paste into and out of the emulator session. -BROWSER_START is optional, case sensitive, and specifies the emulator code recognize a URL hot spot. This option defaults to unavailable because not all users have browser access. If this option is specified and the user clicks on a valid URL hot spot, the command specified in the system environment variable $BROWSER is called with the URL passed as an option. The user will need to define the system variable $BROWSER to be the browser name that is to be used. A fully qualified name or a name found in the system path may be specified. If the environment variable is not found or is not valid, a browser will not start. -RETRY_COUNT is optional and case sensitive. The option specifies if automatic retry should be done if a communication error occurs. A numeric parameter follows with a value between 0 and 9999. Zero indicates manual retry. One to 9999 to indicate the number of automatic retries to attempt. The default is 144. -RETRY_INTERVAL is optional and case sensitive. This option specifies the automatic retry count in seconds. A numeric parameter follows with a value from 1 to 9999; the default value is 300 (5 minutes). -NO_DESKTOP_FILE is optional and case sensitive. The emulator supports reading and writing a desktop file to remember the user’s last window location and font size. This option disables the ability to read and write the desktop file. -debug or -DEBUG can be used to display verbose messaging while the emulator runs.

17

•

-trace or -TRACE can be used to trace telnet activity between the emulator and host OS/400.

2.5 Emulator Layout and Appearance Each 5250 emulator session window has the following layout: • Window title: The default title is “5250” followed by a “:” a session ID. Title text can be different for different sessions. A command line option and resource allow the title contents to be customized. If the system name is specified and greater than 20 characters, the name is truncated from the right. • A menu bar is generally under the window title. The menu bar by default has the following menu options: Command, Edit, Option, Control, Print, and Help. Ø Command allows the user to start new 5250 sessions and exit the 5250 session. Ø Edit enables cut, copy, paste via the 5250 emulator menu bar/pull down. Keyboard hot keys can be used for copy and paste (shift + left for copy and shift + right for paste). Ø Option enables font changes and customization programs like keyboard mapping, miscellaneous preferences, and record. Ø Control enables various 5250 keys which may be hard to locate on a PC keyboard: Reset key, System request, Attention, etc. Ø Print enables 5250 screen print. Ø Help starts an on-line help window. • The 5250 session data is under the menu bar; managed by the AS/400. • A status line is at the bottom of the 5250 session window. 2.5.1

5250 Emulator Status Line

The emulator status line contains the following: sn AS/400Name Message Waiting

Other indicators

The high-level description of the status line is: • sn is the 5250 session number to the target AS/400: 1-99 • The AS/400 name is the same name as presented in the window title described above. The name is truncated to 20 characters if necessary. The name can be the AS/400 system name or the IP address of the AS/400. • “Message Waiting” is displayed when the message waiting indicator is to be displayed. • Other indicators: • 27/132 is an example of row and column text cursor position. The user can turn on and off the display of row/column text cursor position in 5250 miscellaneous preferences. Status line details

Column position(s) 80 column 1 2-3 6-25

Column position(s) 128 column 1 2-3 7-26

Message Waiting Zap startup indicator (up to 8 characters) -655: Waiting for telnet negotiation -656: Initializing TCP/IP socket interface -657: Resolving host name of telnet server -658: Initializing TCP connection for telnet -659: TCP attachment has been lost Input inhibited (large X if locked keyboard)

27-48

30-51

50

56

Type ahead (double angle brackets if on)

52

59

Reserved for system Session number OS/400 name (20 character max)

18

Status line details

Upper shift (up arrow if on)

Column position(s) 80 column 56

Column position(s) 128 column 65

Caps lock (capital A if on)

58

68

Insert (upside down V if on)

63

75

Diacritic (like a small d if on)

65

78

Playback indicator

67

81

Cursor direction (left pointing arrow)

69

84

Screen direction (reverse background/empty arrow)

71

87

Image/fax indicator (bar chart symbol)

74

92

Text cursor row/column position

76-80

127-132

2.6 iSeries Access License Using the 5250 emulator in iSeries Access for Linux requires the iSeries Access Family (5722XW1) license on the iSeries server. One 5722-XW1 user license is used for each unique client or userid that is connecting to the iSeries server. One userid may start multiple emulator sessions to the same iSeries server and only one 5722-XW1 license will be used on the server. Setup5250 may be used to configure the userid and password. If a global preference for userid and password is configured, those values will be used to obtain the 5722-XW1 license. If the userid and password are specified on a connection configured with setup5250, those values will be used. If global values and connection (command line) values are configured, command line values take precedence.

19