In my shop, we have sales representatives located all over the country. Most of them work out of home offices or travel with a laptop computer. All of them need to be able to access mission-critical data on our IBM i system, and that means we need to provide them with a 5250 emulator on their desktop. This situation created a dilemma for me. Because the people weren't local, I couldn't simply go over to their computer and install an emulation program, and since many of these folks weren't very computer savvy, I couldn't ask them to set up their own 5250 emulation, much less configure a VPN.

My solution was to contribute code to the Open Source TN5250 project that lets TN5250 configure itself, automatically, to my company's network settings.

Open Source TN5250

The Open Source TN5250 (formerly known as "Linux5250") is a free 5250 emulator written in C, for Windows, Linux, and other Unixes. It was started in 1997 by Michael Madore because he could not (at the time) find a 5250 emulator for Linux. He made it an open-source project, and others (including yours truly) contributed to the project. I contributed the code that enables SSL support, FreeBSD support and Windows support to the project.

SSL was an important aspect of this solution for me because of security. I wanted an easy way to let outside users log on to my system, without the complexity of a VPN. I didn't mind using passwords to verify their identities, but if those passwords aren't encrypted, a third party might be able to "eavesdrop" and get the password. SSL gives me the same level of protection that a VPN would (albeit, only for the one 5250 connection) while requiring very little knowledge on the part of the remote user.

Likewise, I needed the ability to configure the remote user's network settings in the 5250 emulator without having to physically go to his or her location. So when I wrote the code that installs TN5250 on Windows machines, I added some extra code to let me control how TN5250 is set up. This extra code is what makes it easy to deploy TN5250 to my company's sales reps.

To learn more about this open-source project, and to download the latest version, you can visit the TN5250 website.

TN5250 Configuration

Before I explain how to control the Windows installer for TN5250, I'd like to present a quick overview of how TN5250 determines its settings at runtime. Because TN5250 was originally written for Unix-like systems, it uses a plain-text file for configuration. That text file is named tn5250rc and is located in the folder in which you install TN5250.

For example, if TN5250 is installed into its default location of C:\Program Files\TN5250, the configuration file would be C:\Program Files\TN5250\tn5250rc. Therefore, if I wanted to change the configuration file, I'd type the following at a Windows command prompt (or MS-DOS prompt.)

edit "C:\Program Files\TN5250\tn5250rc"

A typical configuration file for TN5250 might look like this:

map=37
+allow_strpccmd
colsep_style=none

profile1 {
# development system
   host=dev400.example.com
   env.DEVNAME=DSP01
   font_80=Courier New
}

profile2 {
# production system
   host=ssl:prod400.example.com
   env.DEVNAME=DSP02
   font_80=Terminal
}

printer {
    host=dev.example.com
    env.DEVNAME=PRT01
    env.IBMMFRTYPMDL=*HP4
    env.IBMMSGQNAME=DSP01
    env.IBMMSGQLIB=*LIBL
}

At the start of the configuration file are any settings that apply to all sessions of TN5250. In the above example, I've color-coded those as green. It's very similar to the file-level keywords you use in DDS--they apply to the entire configuration file, not just a specific profile.

• map=37 sets the session to use CCSID 37.
  
• +allow_strpccmd allows the Start PC Command (STRPCCMD) CL command to issue commands through this emulator.
  
• colsep_style=none disables column separators from displaying.
  

There are many other settings that you can provide. A PDF manual provided with TN5250 for Windows lists all the configuration options and explains how to use them.

The lines that contain a { or } denote profiles. This example has three profiles named "profile1" (in red), "profile2" (in blue), and "printer" (in black). When you start TN5250, you can pass a profile name as a parameter. If you do that, TN5250 will use the settings in the profile you've given, as well as any settings provided at the global-level.

The lines that begin with the # character are comments.

For example, if I ran TN5250 from the command prompt in Windows (just for the sake of a test) I could type the following:

tn5250 profile2

When I do that, TN5250 will connect to a computer named prod400.example.com using the SSL protocol. When in 80-column mode, it will use the Terminal font. It will also disable column separators, allow STRPCCMD, and use CCSID 37 because I specified those at the global level.

If I wanted to create an icon on my desktop to run using profile1, I'd do the following:

1. Right-click the Windows Desktop and choose New Shortcut.
   
2. Specify C:\Program Files\TN5250\TN5250.EXE as the location of the item.
   
3. Provide any name I like for the shortcut and click OK to create the shortcut.
   
4. Right-click my new shortcut and choose "properties."
   
5. Set the target of the shortcut to:
   "C:\Program Files\TN5250\TN5250.EXE" profile1
   
6. Click OK to save my changes.
   

In this example, I used profile1, which would connect to dev.example.com (instead of prod400.example.com). Because the host name is not prefixed with ssl:, it will not use SSL but instead will use a plain-text TN5250 connection.

The third profile is for a printer, rather than a display. TN5250 comes with a printer program called LP5250D. If you wanted to use that profile, you'd substitute LP5250D.EXE for TN5250.EXE in the above examples. It will connect to dev.example.com. If the system allows the auto-creation of virtual devices, it will create a device with Host Print Transform enabled and transform data for use with an *HP4 printer. The printer will be named PRT01, and messages for the printer will go to the DSP01 message queue.

I don't have the space here to completely describe all the configuration options and what they do, but hopefully you get the gist of it and can look in the manual that comes with TN5250 for the rest of the details.

Controlling TN5250 Setup

Now here's the bit that makes it easy for me to deploy TN5250 to my sales reps. The Windows installer that you download from Source Forge will look for a file named "options" in the same directory with the EXE for the installer. That file will suggest customizations to the way TN5250 is configured. Here's a sample "options" file:

# customizations are for:
Klement's Sausage

# format of icon: lines is
#  PROFILE \ [Desktop|Start Menu|Programs] \ [display|printer] \ Link Name

icon: profile1\Desktop\display\Devel Signon
icon: profile2\Desktop\display\Prod Signon
icon: printer\Desktop\printer\Start Printer


# anything after the tn5250rc: line will simply be added to the
# tn5250 configuration.

tn5250rc:
+allow_strpccmd
colsep_style=none
profile1 {
# development system
   host=dev400.example.com
   env.DEVNAME=DSP01
   font_80=Courier New
}
profile2 {
# production system
   host=ssl:prod400.example.com
   env.DEVNAME=DSP02
   font_80=Terminal
}
printer {
    host=dev.example.com
    env.DEVNAME=PRT01
    env.IBMMFRTYPMDL=*HP4
    env.IBMMSGQNAME=DSP01
    env.IBMMSGQLIB=*LIBL
}

The first non-comment line in the configuration file (highlighted in blue) contains a description of what the customizations are for. In this case, when you install TN5250, it will stop and say, "This setup contains customizations for Klement's Sausage. Would you like to install them?" At this point, my sales rep would click the Yes button.

The installer will then install on the user's desktop icons (highlighted in red, above) that point to the three profiles. The lines that begin with icon: tell which profiles to create icons for and whether to place those icons on the desktop or Start menu. On the desktop, these icons will have names like Devel Signon and Prod Signon, so the user knows which ones to click.

Everything after the "tn5250rc:" line (highlighted in green) will be copied, as-is, to the tn5250rc file. This is how you establish the tn5250rc file on the user's computer.

Deploying the Options

To set up a sales rep, I'll create a temporary folder on my own PC called C:\SALESREP. I'll download the tn5250-0.17.4-setup.exe file from the TN5250 home page and save it to that folder.

1. Create a folder on my own PC named C:\SALESREP
   
2. Go to tn5250.sf.net and download the Windows installer. (The current version is named tn5250-0.17.4-setup.exe.)
   
3. Rename tn5250-0.17.4-setup.exe to simply setup.exe and copy it to the c:\SALESREP folder.
   
4. Create an options file as described in the previous section and put it in the C:\SALESREP folder. (Make sure it's named "options" with no extension.)
   
5. Create a .ZIP file from my C:\SALESREP folder and e-mail it to the sales rep.
   
6. The sales rep can unzip the files, then double-click the setup.exe program. It will see the "options" file and use the settings in it to create the profiles, extra icons, and so forth.
   
7. All my sales rep has to do is double-click the Prod Signon icon, and he's connected to the production box. No need to configure anything on his end!
   

Although I used a sales rep as an example, the same technique can be used for anyone. For example, you might have a consultant who needs to log on to your system to do some development. You could create a configuration for him and send it to him the same way. I've also used this technique for software vendors from whom I've purchased software when they ask to sign on and configure their software on my system.

Automatic Sign On

When I use the preceding technique with a short-term contractor, consultant, or software vendor, I sometimes configure TN5250 to automatically sign on. That way, I don't even have to tell the contractor what the password is. I can just have him double-click the icon, and he signs on.

To do that, I create a profile in my options file that looks like this:

profile1 {
   host=ssl:dev.example.com
   env.DEVNAME=CONTRACTOR
   env.USER=CONTRACTOR
   env.IBMSUBSPW=BIGSECRET
}

This profile will automatically sign on using a user ID of CONTRACTOR and a password of BIGSECRET. Although this information will be in a configuration file on the contractor's PC, he doesn't even know it's there. It's just signing him on as if by magic!

Since he is a short-term contractor, and I plan on deleting his account after he's done, it doesn't matter that the password is in a file on his PC somewhere. He won't be able to sign on when his contract period is over, since his account will be gone. If I rehire him, I'll issue him a new password and send him a new installer with a new options file.

This automatic sign on probably isn't really necessary, but I think it's kind of neat, and if nothing else it's fun to see how people react to it automatically signing them on!

The Linux5250 Mailing List

If you need help with TN5250 or have any questions, the best place to get assistance is on the Linux5250 mailing list at Midrange.com. All the active developers of TN5250 (myself included) monitor the list and will assist you if you need help.