TN5250 for Windows

Scott Klement

TN5250 is an Open-Source emulator that emulates an IBM 5250 compatible terminal over a TCP/IP network.

This document is intended to explain the configuration and day-to-day use of the TN5250 emulator in a Windows environment


Table of Contents
1. The Quick-Connect dialog
1.1. A quick-start with Quick-Connect
1.2. Giving your terminal a name
1.3. Options available on the Quick-Connect dialog
1.3.1. Host to connect to
1.3.2. Device Name
1.3.3. Use SSL Encryption
1.3.4. Verify Server's SSL certificate
1.3.5. Auto-copy, Right-click paste
1.3.6. Char Map
1.3.7. Terminal Size
2. Configuring TN5250 with command-line switches
3. Creating TN5250 profiles
4. Printer Support (LP5250D)
4.1. What a funny name!
4.2. A quick example of running lp5250d
4.3. A more sophisticated example
4.3.1. Creating the profile for our printer settings
4.3.2. Creating a Windows Shortcut for our lp5250d session
5. Using SSL with TN5250
5.1. Setting up your server
5.2. Telling TN5250 to use SSL for encryption
5.3. Telling TN5250 to verify the authenticity of your server
5.4. Configuring TN5250 for client certificates
6. TN5250 Options
6.1. Options processed by the server (Telnet Environment Options)
6.1.1. The DEVNAME (Device Name) option
6.1.2. The TERM (Terminal Type) option
6.1.3. The KBDTYPE, CODEPAGE and CHARSET (Language) options
6.1.4. The USER, IBMSUBSPW, IBMCURLIB, IBMIMENU, IBMPROGRAM (Auto Sign-on) options
6.2. Options processed by the TN5250 client
6.2.1. The HOST (host name of server) option
6.2.2. The MAP (Character translation map) option
6.2.3. The RULER (Draw lines to my cursor) option
6.2.4. The VERSION (Display Version and Exit) option
6.2.5. The PCSPEAKER (Use PC Speaker) option
6.2.6. The BEEPFILE (Special Beep Sound File) option
6.2.7. The COPYMODE (Copy To Clipboard Mode) option
6.2.8. The UNIX_LIKE_COPY (Copy/Paste like a Unix xterm) option
6.2.9. The UNIX_SYSREQ (Use Ctrl-C for SysReq) option
6.2.10. The TRACE (create trace file) option
6.2.11. The FONT_80 and FONT_132 (Font) options
6.2.12. RESIZE_FONTS (Re-size fonts to match window size) option
6.2.13. BLACK, WHITE, RED, BLUE, ETC (Color) options
6.2.14. BLACK_ON_WHITE and WHITE_ON_BLACK (Color Style) options
6.2.15. RULER_COLOR (Rule Line Color) option
6.2.16. COLSEP_STYLE (Column Separator Style) option
6.2.17. CARET_STYLE (Text Cursor Style) option
7. LP5250D Options
7.1. Options processed by the server (Telnet Environment Options)
7.1.1. The DEVNAME (Device Name) option
7.1.2. The IBMMFRTYPMDL (Manufacturer Type & Model) option
7.1.3. The IBMWSCSTNAME & IBMWSCSTLIB (Workstation Customization) option
7.1.4. The IBMMSGQNAME & IBMMSGQLIB (Message Queue) options
7.2. Options processed by the LP5250D client
7.2.1. The VERSION (Display Version and Exit) option
7.2.2. The HOST (host name of server) option
7.2.3. The MAP (Character translation map) option
7.2.4. The TRACE (create trace file) option
7.2.5. The OUTPUTCOMMAND (direct printer output) option
8. Troubleshooting & Reporting Bugs
8.1. The bug fixing process, and how to get help
8.2. Creating a trace file
9. Running TN5250 from a network share or floppy disk
9.1. Which files are needed for TN5250 to run?
9.2. Where do I have to put the files?
9.3. Utilizing the $loginname$ feature

Chapter 1. The Quick-Connect dialog

1.1. A quick-start with Quick-Connect

It is assumed that your iSeries/400 or AS/400 server has already been configured for TCP/IP and that the telnet server is running on your AS/400. If it is not, please contact your system administrator about setting up your AS/400 before continuing.

Follow these steps to get started:

  1. Double-click the TN5250 icon on your desktop or start menu

  2. A window opens up that says "TN5250 Quick-Connect" and asks you a number of questions. To keep things simple, just type the name of your AS/400 in the "Host to connect to" box, and click Ok.

  3. You should now have an AS/400 sign-on screen. Congratulations!

  4. You can exit the emulator by pressing Control-Q or by clicking on "Exit" from the File menu


1.2. Giving your terminal a name

To specify a device name:

  1. Double-click TN5250 again. Note that if you hadn't closed the previous window, this would start up a second TN5250 session. (This is useful, because it's sometimes nice to have two or more 5250 sessions open at once.)

  2. This time, after filling in the host name, type a device name in the next box. For example, if you want your device to be called DSP51, type that into the Device Name box.

  3. Now, when you click OK the AS/400 gives you the device name that you selected.


1.3. Options available on the Quick-Connect dialog

Only some of TN5250's options can be set using the Quick-Connect dialog. Most of the options are set using the a "command-line" or "profile" option, which is explained later in this document.

Here is a list of the options you can set on the Quick-Connect screen, and what they do:


1.3.1. Host to connect to

This is the host name of the iSeries or AS/400 that you want to log on to. It can be a "domain name" such as AS400.EXAMPLE.COM or it can be an IP address such as 192.168.110.4.

If you need to use a "non-standard" port number to connect to your AS/400, it is also specified here. Just separate the host name from the port number with a colon. For example, to connect using port 1025, I might specify:

            AS400.EXAMPLE.COM:1025
         

You can also add a "stream type" identifier to the beginning of the host name. For example, if I wanted to play back a debugging trace file, I could specify:

            debug:C:\tn5250\tracefile.txt
         

1.3.2. Device Name

This is the device name that you'd like the AS/400 to assign to you. Depending on how your AS/400 is set up, it may or may not honor this request.


1.3.3. Use SSL Encryption

This option tells TN5250 to encrypt all of the data sent to and from your AS/400 using the SSL protocol. Your AS/400 must be configured to receive SSL telnet requests, or an error will occur when it tries to connect.

See the section on SSL for details


1.3.4. Verify Server's SSL certificate

With this option enabled, the SSL connection won't be allowed unless the AS/400's SSL certificate is valid, and has been signed by a trusted certificate authority.

Many companies will generate their own certificates, instead of paying for the services of an official certificate authority. If the "Verify Server" option is checked, these certificates won't be allowed, and the connection will fail.

You can specify your own certificate authorities as being trusted by TN5250, if you wish to use this option in that scenario. See the section entitled "SSL Options" for more information.


1.3.5. Auto-copy, Right-click paste

When this option is set, text is copied to the Windows clipboard immediately when you highlight it with the mouse. The text can be pasted to the 5250 window by right-clicking in it. This is similar to the way text is copied/pasted in Unix.

If this option is not enabled, you'll need to click the Copy option from the Edit menu, (or press Ctrl-C) to copy text to the clipboard, and click the Paste option from the Edit menu (or press Ctrl-V) to paste the text


1.3.6. Char Map

This is the CCSID of the character map which tells TN5250 how to display the characters on your screen. Here is a list of some of the common character maps:

CCSID Windows encoding Description
37 windows-1252 US, Canada, Netherlands, Portugal, Brazil, Australia, New Zealand
256 windows-1252 Netherlands
273 windows-1252 Austria, Germany
277 windows-1252 Denmark, Norway
278 windows-1252 Finland, Sweden
280 windows-1252 Italy
284 windows-1252 Spain, Latin America
285 windows-1252 United Kingdom
290 JIS_X0201 Katakana Extended
297 windows-1252 France
420 windows-1256 Arabic
424 windows-1255 Hebrew
500 windows-1252 Belgium, Canada, Switzerland
870 windows-1250 Eastern Europe
871 windows-1252 Iceland
875 windows-1253 Greece
880 windows-1251 Cyrillic
905 windows-1254 Turkey - Latin3
1026 windows-1254 Turkey - Latin5

1.3.7. Terminal Size

Here you can select whether you want a terminal that's capable of only 24x80 mode (24 rows by 80 columns) or if it's capable of both 24x80 and 27x132.

If you select 24x80, tn5250 will emulate an IBM 3179-2 terminal. If you select 27x132, tn5250 will emulate an IBM 3477-FC terminal


Chapter 2. Configuring TN5250 with command-line switches

One of the most useful features of TN5250 is that you can set all of your options using the command-line. Unlike the Quick-Connect dialog, this allows you to specify any of TN5250's options.

To try it out:

  1. Open up an MS-DOS prompt.

  2. Switch to the directory where you installed TN5250. For example, you might type:

         
                 C:\WINDOWS>cd \"Program Files"\TN5250
             
    
  3. Launch TN5250 by typing the tn5250 command, followed by the name of the host you want to connect to. For example:

                 C:\Program Files\TN5250>tn5250 AS400.EXAMPLE.COM
             
    
  4. Notice that when you do it this way, you don't get the Quick-Connect dialog. So how do you specify a device name? Well, the device name is sent to the AS/400 using the DEVNAME environment option, which we can specify with the "env.DEVNAME" option.

    So, for example, to connect as DSP51 you might type:

                 C:\Program Files\TN5250>tn5250 env.DEVNAME=DSP51 AS400.EXAMPLE.COM
              
    
  5. You can specify different stream types and ports in your hostname here, too. For example, to connect to port 8992 using an SSL-encrypted stream, you can type:

                 C:\Program Files\TN5250>tn5250 env.DEVNAME=DSP51 ssl:AS400.EXAMPLE.COM:8992
              
    

    Its very important that there be no spaces in the middle of a command-line argument. So, typing env.DEVNAME=DSP51 is okay, but typing env.DEVNAME = DSP51 will cause problems.

    If you do need to put spaces in your options, you should wrap the entire option in quotes. For example, this is perfectly legal:

                 C:\Program Files\TN5250>tn5250 "font_80=Courier New" as400.example.com
              
    
  6. You can use command-line mode in conjunction with the Quick-Connect dialog if you want to specify some options that cannot be given with Quick-Connect. For example, you might type:

                 C:\Program Files\TN5250>tn5250 +ruler "font_80=Courier New"
              
    

    Because I did not give a host, above, the Quick-Connect dialog will appear to ask me which host to connect to. In addition to that, however, it will use the Courier New font, and it will draw rule lines to indicate where my cursor is.

There are many more options available from the command-line in tn5250. See the chapter on OPTIONS for more information.

Now, lets suppose that you've gotten tired of typing all of the options that you want to use each time that you start a new session.

You can set all of your command-line options in a Windows Shortcut. When you run the short cut, they'll be used automatically.

  1. Open up your My Computer icon, and navigate to the directory where you installed TN5250. For example, if you installed TN5250 in C:\Program Files\TN5250, you'd first click My Computer, then C:, then Program Files, and finally TN5250.

  2. Right-click the Tn5250.exe icon and select "Copy".

  3. Close the My Computer window, and right-click your desktop. Choose "Paste Shortcut"

  4. Right click the new shortcut, and select "Rename". Rename it to something easy to remember. I called mine "DSP51".

  5. Right click the new shortcut again, and choose "Properties"

  6. On the line that says "Target:", add the options that you'd like to use. For example, I'm setting my Target to look like this:

                "c:\Program Files\TN5250\TN5250.EXE" env.DEVNAME=DSP51 ssl:as400.example.com
             
    
  7. Click OK to save your changes

  8. Now when I double click my DSP51 shortcut on my desktop, it connects to my AS/400 as device DSP51, and gives me a sign-on screen. No more typing all of those options!


Chapter 3. Creating TN5250 profiles

Sometimes its useful, especially when you have a lot of settings to manage, to keep your tn5250 settings in a file, instead of typing them all into a command-line or shortcut.

The way that you do this is by defining a "tn5250rc" file.

  1. Open up an MS-DOS prompt.

  2. Just like you did when you tried out the command-line options, Switch to the directory where you installed the TN5250 software.

  3. Use the MS-DOS editor to create a new file called tn5250rc by typing:

    edit tn5250rc

  4. Set all of your TN5250 options in this file. For example, if you wanted to create a display called FRED1 which connects to an as400 called iseries.sample.com, you'd type this:

                profile1 {
                   host = iseries.sample.com
                   env.DEVNAME=FRED1
                }
              
    
  5. Now that you've created this, you can utilize those settings just by typing: tn5250 profile1

    Be careful of capitalization. "profile1" is not the same as "Profile1", and that's different from "PROFILE1".

  6. You can set any of tn5250's settings in the tn5250rc file. Here's a more sophisticated example:

                profile1 {
                   host = ssl:iseries.sample.com
                   env.DEVNAME=FRED1
                   env.TERM=IBM-3477-FC
                   font_80=System
                   font_132=Terminal
                   +ssl_verify_server
                   ssl_ca_file=c:\certs\ca\as400_ca.pem
                   trace=c:\windows\temp\profile1-trace.txt
                }
         
                profile2 {
                   host = ssl:as400.example.com
                   env.DEVNAME=DSP51
                   +ruler
                   env.TERM=IBM-3179-2
                   map=285
                   ssl_cert_file=c:\certs\client\fredclient.pem
                   ssl_pem_pass=wilma
                }
          
                printer {
                   host = ssl:as400.example.com
                   env.DEVNAME=PRT01
                   env.IBMMFRTYPMDL = *HP4
                   env.IBMMSGQNAME = QSYSOPR
                   env.IBMMSGQLIB = *LIBL
                }
              
    

    See, I wasn't kidding when I said that would be more sophisticated! This copy of tn5250rc contains 3 different profiles called profile1, profile2 and printer respectively.

  7. Now, you can run those profiles by typing:

                 C:\Program Files\TN5250>tn5250 profile1
                 C:\Program Files\TN5250>tn5250 profile2
                 C:\Program Files\TN5250>lp5250d printer
              
    

    Tip: You can use profiles as arguments when you create a Windows shortcut as well! For example, set the "Target:" in the shortcut properties to:

                   "C:\Program Files\TN5250\TN5250.EXE" profile1
                
    

Just a reminder, you'll want to check out the sections containing TN5250 OPTIONS and LP5250D, which show all of the options that you can use.


Chapter 4. Printer Support (LP5250D)

4.1. What a funny name!

First, a quick explanation, since Windows users are probably wondering what the name "lp5250d" means. On Unix systems, the print spooler is called "lpd", which stands for "Line Printer Daemon". When 5250 printer support was added to TN5250, they cleverly decided to call the printer program "lp5250d" (line printer 5250 daemon.) When I converted the code so that lp5250d would run on Windows systems, I kept the name.

The lp5250d program is intended to be a "background process" that just receives printer output from the AS/400. There is very little reason to interact with lp5250d while it's running.

In order to use lp5250d, your AS/400 must support the enhanced TN5250e servers. This was first available in V3R2, but required a PTF to activate it. If you're running an older release of OS/400, please read APAR II10918 to see if this option is available at your release.


4.2. A quick example of running lp5250d

As I'm writing this document, lp5250d does not have a "Quick-Connect" dialog like tn5250 does. You have to configure it using profiles or command-line arguments.

Here's an example of running lp5250d to help get you started:

  1. Open up an MS-DOS prompt.

  2. Switch to the directory where you installed TN5250. For example, you might type:

         
                   C:\WINDOWS>cd \"Program Files"\TN5250
               
    
  3. Run the lp5250d program giving it some command line arguments.

                   C:\Program Files\TN5250>lp5250d env.DEVNAME=PRT01 ssl:as400.example.com
               
    

What should happen when you run that is that lp5250d will connect with your AS/400, and become printer PRT01. When the AS/400 sends a report to PRT01, it will receive the report and send it to whatever printer is your Windows default.

With this simple of a set up, every document will just be a plain text representation. It will lose any formatting that your AS/400 might include (such as fonts & graphics) and may not even be sophisticated enough to work with some printers.


4.3. A more sophisticated example

In this example, we will do a more real-world configuration of lp5250d. We will specify a number of telnet environment options that the AS/400 will use to create the device description for our printer. We will place all of these settings in a profile in our tn5250rc file, and create a shortcut for the printer.

Are you ready? (why do I ask these things?)


4.3.1. Creating the profile for our printer settings

  1. Once again, go to an MS-DOS prompt, and switch to the directory where you installed TN5250. (If you don't know how to do this, see the previous section in this document.)

  2. At the MS-DOS prompt, edit your tn5250rc file. (If you don't already have one, create it now)

                    C:\Program Files\TN5250>edit tn5250rc
                 
    
  3. Add a new profile onto the end. For our example, we'll create an entry for Hewlett Packard LaserJet 4 printer. So, I'm going to call the profile "hp"

                     hp {
                        host = as400.example.com  (1)
                        env.DEVNAME = PRT04       (2)
                        env.IBMMFRTYPMDL = *HP4   (3)
                        env.IBMMSGQNAME = DSP51   (4)
                        env.IBMMSGQLIB = *LIBL    (5)
                        map = 37                  (6)
                     }
                 
    
    (1)
    This is the hostname that lp5250d will connect to. You can prefix this with "ssl:" if you wish to encrypt your session, or suffix it with a ":123" to select an alternate port number, just as you can in tn5250!
    (2)
    This is the name that the AS/400 will use when creating it's device description and it's output queue.

    It should be noted that this is just a suggestion to the AS/400. It could decide to reject this name, or ignore it, or assign you a different name, depending on how your AS/400 is configured.

    (3)
    This asks the AS/400 to use it's "Host Print Transform" function to convert the spooled files to our printer's native language.

    For our example, we've used the *HP4 option to tell the AS/400 to put the document in the language used by Hewlett Packard LaserJet 4 printers

    For a list of possible values for this parameter, you should log on your your AS/400, and prompt the CRTDEVPRT command. Any value allowed for the MFRTYPMDL parm of the CRTDEVPRT command can be specified here.

    (4)
    This is the message queue that messages for this printer will be sent to. In our example, we are sending the printer messages to the workstation message queue for the DSP51 display
    (5)
    This is where you specify the library of the message queue. In our example, we are using the library list to locate the message queue.
    (6)
    This is equivalent to the "Char Map" option that was described in the "Quick-Connect" options for TN5250. It specifies the CCSID that you need to use.

    In our example, we are using a CCSID of 37. This is the correct value for the United States, as well as several other countries.

  4. Save your changes to the tn5250rc file, and exit back to the MS-DOS prompt.

  5. You can now run lp5250d from the MS-DOS prompt like this:

                    C:\Program Files\TN5250>lp5250d hp
                 
    

4.3.2. Creating a Windows Shortcut for our lp5250d session

So that we don't need to open up an MS-DOS prompt each time we want to start lp5250d, we'll create a shortcut on our desktop which will start it when we double-click it.

  1. Double click the "My Computer" icon and navigate to the directory where you installed TN5250

  2. Right-click the "lp5250d" executable, and choose "copy".

  3. Close the My Computer window and right-click your desktop.

  4. Choose "Paste Shortcut." Windows will create a "Shortcut to LP5250D" on your desktop.

  5. Right-click the new shortcut and choose "rename". Change the name of the short cut to "PRT04" (or another name that appeals to you)

  6. Right-click the new shortcut again, and this time choose "Properties"

  7. Switch to the "Shortcut" tab, and at the end of the text in the "Target:" box, add profile name of "hp".

    My "Target" now looks like this:

                      "C:\Program Files\TN5250\LP5250D.EXE" hp
                   
    
  8. Click the OK button to save your changes.

  9. To test it out, double-click on the PRT04 icon!


Chapter 5. Using SSL with TN5250

Using the Secure Sockets Layer (SSL) protocol, it is possible to configure your AS/400 and tn5250 to encrypt and protect it's communication. This is particularly helpful if you are connecting to your AS/400 over an untrusted network, such as the Internet

In addition to providing data encryption, SSL also provides authentication. By authentication, I mean that one computer is able to tell that the other computer is actually who it claims to be, and not an imposter.


5.1. Setting up your server

Setting up TN5250 to communicate with an SSL-aware AS/400 is very easy. However, setting up the AS/400 itself isn't as easy. This section will attempt to walk you through a basic setup of your AS/400's secure telnet server.

There are many wonderful things you can do with SSL and with the OS/400 Digital Certificate Manager. For more details, I recommend looking at the documentation that came with your server.

This section assumes that your AS/400 and TELNET server have never been set up to use SSL, and that you wish you create & sign your own SSL certificates (as opposed to buying them from VeriSign or a similar company)

If your system is already set up for SSL, please skip to step 7, where we will configure the TELNET server to use the SSL.

  1. You must install the following software on your AS/400:

    • Digital Certificate Manager, option 34 of OS/400 (5769-SS1)

    • IBM HTTP Server for AS/400 (5769-DG1)

    • IBM Cryptographic Access Provider (5769-ACx or 5649-ACx)

    The first two options are included on your OS/400 CDs. The Cryptographic Access Provider must be ordered from IBM, and you may get a different option, depending on the laws in your country regarding encryption, and the model of AS/400 you have. At the time of this writing, IBM supplies the C.A.P. at no charge.

    If you're given a choice, you'll want to install 5769-AC3, as it has the best cryptography.

  2. Start the HTTP *ADMIN server in order to configure your Digital Certificate Manager. From the AS/400, type:

                     STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)
                 
    
  3. With a web browser, connect to your AS/400's admin server: http://as400.example.com:2001

  4. Click "Digital Certificate Manager", then "Certificate Authority (CA)" then "Create a Certificate Authority." Fill out the forms, etc.

  5. Click "System Certificates". IF you haven't done so already, click "Create new certificate store" and follow the prompts for creating the *SYSTEM certificate store.

  6. Select "Work With Secure Applications". Select "QIBM_QTV_TELNET_SERVER", then click the "Work with system certificate" button. It should tell you that your telnet server has your system certificate assigned to it. IF not, you can assign it here.

  7. Now you have to start your telnet server on the AS/400. If it is already running, you'll have to end it, and start it again.

    On the AS/400, type:

                    ENDTCPSVR SERVER(*TELNET)
                    STRTCPSVR SERVER(*TELNET)
                 
    
  8. Now, verify that your SSL-enabled Telnet server is running. on the AS/400, type NETSTAT *CNN. Press F14 to display the port numbers. Look for a server that's in "Listen" state on port 992. This is the SSL telnet server.

If you have problems, or need more detailed information on how to set up the TELNET-SSL server on the AS/400, see the TCP/IP configuration area of the iSeries Information Center.

Here's a link to the TELNET section of the Information Center online: http://publib.boulder.ibm.com/pubs/html/as400/v4r5/ic2924/info/RZAIWGETSTART.HTM

Click "Telnet server and SSL" to get started.


5.2. Telling TN5250 to use SSL for encryption

  1. To tell TN5250 to use SSL when you connect to your AS/400, prefix the hostname with ssl: in your configuration. For example, type:

                    C:\Program Files\TN5250>tn5250 ssl:as400.example.com
                 
    

    Or, if you're using the "Quick-Connect" dialog when you start tn5250, check the "Use SSL Encryption" box.

At this point, the data that you exchange with the AS/400 is being done using an encrypted channel. However, no authentication is being done!


5.3. Telling TN5250 to verify the authenticity of your server

It is a good idea when using SSL to verify the certificate that your telnet-ssl server is sending to tn5250. This ensures that you are communicating with the server that you think you are, and that your connection is not being "hijacked" by a 3rd party.

In order to do this, you'll need to download a copy of your AS/400's "Certificate Authority" (CA) certificate, which you will store on your hard drive. Then, when TN5250 starts, it can verify that each session has been "signed" by your AS/400's Certificate Authority

  1. If it's not already running, start the AS/400's HTTP *ADMIN server by typing:

                    STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)
                 
    
  2. Connect to the Admin server with a web browser: http://as400.example.com:2001

  3. Click "Digital Certificate Manager", then "Certificate Authority (CA)" then "Install CA certificate on your PC", then click "Copy and paste certificate"

  4. Highlight the certificate that is displayed with your mouse. Make sure that you include the "----BEGIN CERTIFICATE-----" and the "----END CERTIFICATE-----" in the selection. Then choose "Copy" from your web browser's Edit menu.

  5. Open a utility such as Notepad and paste the certificate into it. Then save the document as C:\Program Files\TN5250\as400_ca.txt (or, if you like, some other name)

  6. Add the "ssl_ca_file" option to your tn5250rc file, so that TN5250 knows where the AS/400's certificate is. Here's an example profile:

                    ssltest {
                       host = ssl:as400.example.com
                       env.DEVNAME = SSL1
                       +ssl_verify_server                                 (1)
                       ssl_ca_file = C:\Program Files\TN5250\as400_ca.txt (2)
                    }
                 
    
    (1)
    The +ssl_verify_server keyword tells TN5250 that you want it to verify the authenticity of your AS/400.
    (2)
    The ssl_ca_file keyword must point to the certificate that you just downloaded from the AS/400.
  7. Now you can envoke tn5250:

                    C:\Program Files\TN5250>tn5250 ssltest
                 
    

5.4. Configuring TN5250 for client certificates

Some versions of OS/400 allow you to require client authentication in the Telnet server. This means that when you connect, the AS/400 will actually verify the authenticity of the client.

This can be a great security tool because you can configure your AS/400 to only allow connections from people using the AS/400's private certificate authority. If you set this up correctly, you can restrict your system to people who you've specifically given certificates to.

Explaining how to configure the server for this is beyond the scope of this document. However, once the server has been configured this way, you'll need to know how to tell TN5250 to use a certificate assigned by your server.

In order to follow these steps, you'll need the openssl.exe program that comes with the OpenSSL toolkit. If you built tn5250 from source, you built it when you compiled OpenSSL. If not, you'll need to get it from http://www.openssl.org

  1. If it's not already running, start the AS/400's HTTP *ADMIN server by typing:

                    STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)
                 
    
  2. Connect to the Admin server with a web browser (I used Netscape Navigator 4.77 in my tests and I do not know exactly how you'd do it with a different browser, so good luck...) http://as400.example.com:2001

  3. Click "Digital Certificate Manager", then "Certificate Authority (CA)" then "Install CA certificate on your PC", then click "Receive certificate"

  4. Netscape brings up the "New Certificate Authority" wizard. Follow the prompts, until you can finally click "Finish".

  5. Click "User Certificates", then "Request a new user certificate", Fill out the form and click OK.

  6. Netscape brings up the "Generate A Private Key" wizard. Follow the prompts. The password you assign it is only temporary, but you should assign it one. Maybe "tn5250" is a good password.

  7. After filling out your password, and waiting a second or two, you should come to a screen that says "User Certificate Created Successfully". Click "Receive Certificate".

  8. The certificate should be downloaded into your web browser. It may not tell you that it did anything, so don't be surprised if nothing seems to happen.

  9. On the Netscape "Navigation Toolbar" click the "Security" button. (This is the button that looks like a padlock). Then under "Certificates", click on "Yours".

  10. The certificate that you just generated should appear, along with any other private-key certficates that you have in your browser. Highlight the cert that you just generated, and click "Export".

  11. It asks for a password. Type the password that you used in step 6.

  12. It asks for a new password. Type the same password again. Then type it one more time to verify it. :)

  13. Save the exported certificate to a file called "tn5250.p12" It will tell you that the certificate has been successfully exported. Good work!

  14. Unfortunately, Netscape likes to save the certificate in pkcs12 format, which doesn't do us much good. We need it in PEM format! Back at your MS-DOS prompt type:

                    C:\Program Files\TN5250>openssl pkcs12 -clcerts -in tn5250.p12 -out tn5250.pem
                 
    
  15. It asks for the "Import Password". This is the same password that you assigned it in Step 12.

  16. It says "Enter PEM pass phrase". This is, yet another, password. However, this is the important one that you will be using from this point on. You might want to write it down.

  17. Now, finally, to tell tn5250 to use this certificate that you just received, use the ssl_cert_file keyword. You'll also need a PEM passphrase, (this is the password that you typed in Step 16) which you can specify with the ssl_pem_pass keyword.

    Here's an example:

                    ssltest {
                       host = ssl:as400.example.com
                       env.DEVNAME = SSL1
                       +ssl_verify_server
                       ssl_ca_file = C:\Program Files\TN5250\as400_ca.txt
                       ssl_cert_file=C:\Program Files\TN5250\tn5250.pem
                       ssl_pem_pass=tn5250
                    }
                 
    
  18. Now you can run tn5250, and give it a try:

                    C:\Program Files\TN5250>tn5250 ssltest
                 
    

Chapter 6. TN5250 Options

This section explains the configuration keywords that are available in TN5250. For information on how to specify these keywords, see Chapters XXX and YYY.

Tip: Some of the examples below illustrate calling TN5250 from an MS-DOS prompt, and others illustrate the use of a profile in the tn5250rc file. However, any of the options should work from either of these scenarios, as well as from a Windows Shortcut.


6.1. Options processed by the server (Telnet Environment Options)

The TN5250e (Enhanced TN5250) protocol makes it possible to send user-defined variables to the AS/400. The AS/400, in turn, uses these variables in order to control some of the aspects of your session.

In older versions of OS/400, you may need to apply PTFs in order to enable TN5250e support. If you are running an older release of OS/400, please see APAR II10918 in IBM's AS/400 service database.

Environment options are specified to TN5250 in the following format:

               env.OPTION-NAME = Value
           

Whenever TN5250 is given an option that begins with 'env.', it will send it to the AS/400 without interpreting it's value. So, if IBM ever adds more options, you can specify them without needing to upgrade your copy of TN5250


6.1.1. The DEVNAME (Device Name) option

This option tells the AS/400 the name of the device that you'd like to use for this session. The device name must be a valid AS/400 system object name, and can be up to 10 characters long.

Example:

                 C:\Program Files\TN5250>tn5250 env.DEVNAME=DSP01 as400.example.com
             

Note: A special feature of TN5250 allows you to place your Windows login name into the device name of your session. Here's an example:

                   C:\Program Files\TN5250>tn5250 env.DEVNAME=$loginname$S1 as400.example.com
               

If you signed on to your Windows session as "MATT", the name sent to the AS/400 would be "MATTS1", but if JANE were signed on to the Windows machine, it would instead send "JANES1".


6.1.2. The TERM (Terminal Type) option

This option is sent to the AS/400 to indicate which type of terminal you would prefer to use. The terminal types, are listed below. The ones marked as "Default" are the ones that TN5250 will use if no terminal type is specified.

Tip: This is the keyword that specifies whether 27x132 mode is allowed for your session, or not.

Terminal Type Description Default
IBM-3477-FC 27x132-capable color Yes
IBM-3477-FG 27x132-capable mono  
IBM-3180-2 27x132-capable mono  
IBM-3179-2 24x80-capable color Yes
IBM-3196-A1 24x80-capable mono  
IBM-5292-2 24x80-capable color  
IBM-5291-1 24x80-capable mono  
IBM-5251-11 24x80-capable mono  

Example:

                 C:\Program Files\TN5250>tn5250 env.TERM=IBM-3179-2 as400.example.com
             

6.1.3. The KBDTYPE, CODEPAGE and CHARSET (Language) options

The AS/400 will use these options when creating the device description for your session. For a description of these options, and their values, see the OS/400 Communications Configuration manual (SC41-5401-00) , chapter 8.

Note: The CODEPAGE and CHARSET options will not work if you do not specify a KBDTYPE. A special value of *SYSVAL can be given for KBDTYPE if you do not wish to explcitly set one.

Example:

                profile1 {
                   host = as400.example.com
                   env.DEVNAME = DSP07
                   map = 273
                   env.KBDTYPE = AGB
                   env.CHARSET = 697
                   env.CODEPAGE = 273
                }
             

6.1.4. The USER, IBMSUBSPW, IBMCURLIB, IBMIMENU, IBMPROGRAM (Auto Sign-on) options

These options can be used to specify your User-ID and Password, and optionally your Current Library, Initial Menu and Program/Procedure (respectively) so that you can bypass the initial sign-on screen.

Note: TN5250 does not currently support using IBMSUBSPW (substitution password) with the IBM substitution password encryption scheme. (You can only use it for unencrypted passwords) If you wish your password to be protected from spying by 3rd parties, we recommend using SSL.

Example:

                 autosignon {
                     host = as400.example.com
                     env.DEVNAME = DSP01
                     env.USER = my-user-id
                     env.IBMSUBSPW = my-password
                 }
    
                 automenu {
                     host = as400.example.com
                     env.DEVNAME = DSP01
                     env.USER = my-user-id
                     env.IBMSUBSPW = my-password
                     env.IBMCURLIB = QSYS
                     env.IBMIMENU = CMDDSP
                     env.IBMPROGRAM = *NONE
                 }
             

Important: There are some security risks involved in placing your password in a text file on your PC. Anyone who can get access to your hard drive can then proceed to use your AS/400 account.

If you decide to use this option, make sure that it does not violate your company's security policies


6.2. Options processed by the TN5250 client

The options in this section are processed by the TN5250 client itself. (Just so you know who to blame if something doesn't work!)


6.2.1. The HOST (host name of server) option

The host option indicates the name or IP address of the system that you are connecting to. It also can be used to designate the type of communications stream that you wish to use, and/or a non-standard TCP/IP port number.

Note: When given on a command-line, the host name is not prefixed by a keyword, and must be the last option given.

This is the only keyword that is not the same when given at a command-line as it is in a tn5250rc profile.

Note: The host keyword is the only manditory option when running TN5250. All other keywords are optional. Therefore, if the host keyword is not specified, TN5250 will open up the "Quick-Connect" dialog to find out which host you wanted.

The value of the host keyword takes this format:

                  (1)host = (2)STREAM-TYPE:(3)hostname(4):PORT
              
(1)
The host= keyword is only specified when you are creating a tn5250rc profile. When you are specifying the host at the command-line, you omit the "host=" part, and always put the hostname at the end of the command line.
(2)
The STREAM-TYPE is optional. If not given, the default value is "telnet:"

The possible values for STREAM-TYPE are:

Stream-Type Description
telnet: The 5250 data is sent over the standard TCP/IP telnet protocol.
tn5250: This is an alias for "telnet"
ssl: The 5250 data is sent over an SSL-encrypted TCP/IP telnet session.
telnets: This is an alias for "ssl"
debug: Stream data is read from a trace file.

Note: For more information on the debug: stream, see the "The TRACE (create trace file) option" and the section on "Troubleshooting"

(3)
This is the name or IP address of the AS/400 you're connecting to. If you are using the "debug:" stream type, this is where you specify the name of the trace file.
(4)
This is the TCP/IP port number that TN5250 will attempt to use to connect to the AS/400's telnet server. If this option is not specified, TN5250 will use port 23 for the telnet: stream type, or 992 for the ssl: stream type

Command-line Examples:

                  C:\Program Files\TN5250>tn5250 as400.example.com
                  C:\Program Files\TN5250>tn5250 telnet:devel.example.com
                  C:\Program Files\TN5250>tn5250 ssl:iseries.sample.org
                  C:\Program Files\TN5250>tn5250 telnet:donut.tasty.net:8023
                  C:\Program Files\TN5250>tn5250 trace=C:\debug.txt ssl:iseries.example.org:1234
              

Profile Examples:

                 example1 {
                    host = as400.example.com
                 }
    
                 example2 {
                 # for security reasons, ACME uses port 3021
                    host = proxy.acme.com:3021
                 }
    
                 example3 {
                    host = debug:C:\debug.txt
                 }
    
                 # Note: Carl says: "It's safe to put my password in a 
                 #       file on my PC.  Who'll ever see it?"
                 example4 {
                    env.DEVNAME=DSP01
                    env.USER=carl
                    env.IBMSUBSPW=chelsea
                    host = ssl:series5.carlsinc.com
                    env.IBMCURLIB=QGPL
                    env.IBMIMENU=MAIN
                 }
    
                 # Note: I was kidding.  That's not really Carl's password.
                 example5 {
                    host = telnet:acrossthepond.example.uk
                    trace=c:\debug.txt
                    map = 285
                 }
                     
              

6.2.2. The MAP (Character translation map) option

Sets the translation table which translates between ASCII and EBCDIC. This should match the CCSID of the interactive job. The default value is 37.

Here are a list of common maps:

CCSID Windows encoding Description
37 windows-1252 US, Canada, Netherlands, Portugal, Brazil, Australia, New Zealand
256 windows-1252 Netherlands
273 windows-1252 Austria, Germany
277 windows-1252 Denmark, Norway
278 windows-1252 Finland, Sweden
280 windows-1252 Italy
284 windows-1252 Spain, Latin America
285 windows-1252 United Kingdom
290 JIS_X0201 Katakana Extended
297 windows-1252 France
420 windows-1256 Arabic
424 windows-1255 Hebrew
500 windows-1252 Belgium, Canada, Switzerland
870 windows-1250 Eastern Europe
871 windows-1252 Iceland
875 windows-1253 Greece
880 windows-1251 Cyrillic
905 windows-1254 Turkey - Latin3
1026 windows-1254 Turkey - Latin5

Example:

                 C:\Program Files\TN5250>tn5250 map=880 as400.moscow.ru
              

6.2.3. The RULER (Draw lines to my cursor) option

The ruler option is a "boolean option". You can turn it on by preceding the keyword with a '+' character, and turn it off by preceding the keyword with a '-' character.

When enabled, the RULER option draws lines across your screen which intersect wherever your cursor is.

Example:

                 C:\Program Files\TN5250>tn5250 +ruler as400.example.com
             

6.2.4. The VERSION (Display Version and Exit) option

This just tells you the version of tn5250 that you have installed.

Example:

                 C:\Program Files\TN5250>tn5250 +version
             

6.2.5. The PCSPEAKER (Use PC Speaker) option

Unless this option is specified, any time a "beep" sound needs to be played on your PC, it is played through your sound card.

If this option is given, and preceeding by a '+' (enable) sign, the beeps will be played through your PC speaker.

Example:

                C:\Program Files\TN5250>tn5250 +pcspeaker as400.fool.org
             

6.2.6. The BEEPFILE (Special Beep Sound File) option

This is used to make TN5250 play a special wave (.wav) file, instead of beeping, when a beep occurs.

Example:

                tada {
                   host = as400.example.com
                   env.DEVNAME=EXCITED
                   beepfile=C:\WINDOWS\MEDIA\TADA.WAV
                }
             

6.2.7. The COPYMODE (Copy To Clipboard Mode) option

When copying text from your TN5250 session to the clipboard, it can be copied as either a bitmap (image) or as plain text, or as both. Both is the default.

Example:

                 C:\Program Files\TN5250>tn5250 copymode=bitmap as400.example.com
             

Tip: This mode can be useful when you're writing documenation. Try setting the copymode to bitmap (as shown above) and logging on to your AS/400. Then, highlight the screen and copy it to the clipboard.

Now, open up Microsoft Word in another window. In Word, press Ctrl-V to paste the clipboard. Presto! A perfect image of the screen in your Word document.


6.2.8. The UNIX_LIKE_COPY (Copy/Paste like a Unix xterm) option

This is a boolean option. When you specify it, you need to either place a '+' in front of it to specify that it is enabled, or a '-' in front of it to specify that it's disabled.

When this is enabled, data is copied to the clipboard automatically after you highlight it. (You don't need to press Ctrl-C, or Click EDIT/COPY to make it go to the clipboard)

In addition, you can paste text into the emulator by right-clicking in the TN5250 window, instead of pressing Ctrl-V or clicking EDIT/PASTE

This is similar to the way text is copied/pasted on Unix systems. One difference, however, is that Unix uses the middle mouse button to paste, instead of the right mouse button. Unfortunately, it's harder to access the middle button in Windows, so I used the right-button.

Example:

                 C:\Program Files\TN5250>tn5250 +unix_like_copy as400.example.com
             

6.2.9. The UNIX_SYSREQ (Use Ctrl-C for SysReq) option

When this option is enabled, Ctrl-C will perform a System Request instead of copying text to the clipboard.

This is a boolean option. When you specify it, you need to either place a '+' in front of it to specify that it is enabled, or a '-' in front of it to specify that it's disabled.

Note: In the Unix version of TN5250, the Ctrl-C button is used to activate the OS/400 System Request function. This is intuitive for Unix people, since Ctrl-C is usually used to mean "interrupt the process" in Unix software.

In Windows, however, our users found this confusing, so we made it an option that isn't enabled by default.

Example:

                 C:\Program Files\TN5250>tn5250 +unix_sysreq as400.example.com
             

6.2.10. The TRACE (create trace file) option

When this option is given, the 5250 data stream is written to a "trace file", along with every key press that you make, and a lot of useful debugging information. This information can be used by a TN5250 developer to track down elusive bugs in the software.

When you send a trace file to a developer, he can use it to "re-play" your TN5250 session, showing him the exact screens that you saw, and the data that you typed. He can then see exactly what code the TN5250 program was running at the time that you encountered a problem, and can use this information to try to fix the problem.

Important: When you create a trace file, it logs everything that you type, and everything that gets sent to & received from the AS/400 including passwords! If you need to make a trace file, we recommend that you change your password after creating it.

Example:

                C:\Program Files\TN5250>tn5250 trace=C:\debug.txt as400.here.net
             

See the section entitled "Troubleshooting & Reporting Bugs" for more information on trace files and getting support.


6.2.11. The FONT_80 and FONT_132 (Font) options

These options are used to tell TN5250 which fonts you wish to use for displaying text.

The "font_80" keyword is the font to use when your session is in 24x80 mode, and the "font_132" keyword is the font to use when your session is in 27x132 mode.

The value that you assign to these keywords is the font name, followed by (optionally) the height and width of the font. This is specified in the following format:

                  font_80 = (1)Font Name-(2)Wx(3)H
              

Note: The font_132 keyword has the exact same syntax.

(1)
This is the name of the font to use. It's important to use a font that has a fixed-width. A proportionally spaced font (which are very popular with Windows currently) will yield strange-looking results.
(2)
Here (instead of the letter W) you type the width of the font. If you specify a width that does not exist, Windows will pick the closest width that it can find. You do not have to specify a width.
(3)
Here (instead of the letter H) you type the height of the font. If you specify a height that does not exist, Windows will pick the closest height that it can find. You do not have to specify a height.

Examples:

                 C:\Program Files\TN5250>tn5250 font_80=System as400.example.com
                 C:\Program Files\TN5250>tn5250 font_80=Terminal-10x6 as400.example.com
    
                 fonttest {
                    host = as400.example.com
                    env.TERM=IBM-3477-FC
                    font_80=Terminal-10x6
                    font_132=System
                    env.DEVNAME=DSP01
                 }
              

6.2.12. RESIZE_FONTS (Re-size fonts to match window size) option

This is a boolean option. When you specify it, you need to either place a '+' in front of it to specify that it is enabled, or a '-' in front of it to specify that it's disabled.

When this option is turned on, TN5250 will attempt to change the size of each font to the best possible value when you change the size of your screen.

                C:\Program Files\TN5250>tn5250 +resize_fonts as400.example.com
             

Note: Most fonts can only be displayed at specific sizes. If your screen is set to a size that doesn't exist, TN5250 will let Windows pick the next closest size. If this doesn't give you satisfactory results, try setting a different font with the font_80 and font_132 keywords.


6.2.13. BLACK, WHITE, RED, BLUE, ETC (Color) options

These options are used to tell TN5250 how to display the 5250 colors sent by the AS/400. Each color can be set to be displayed as any other color.

Here is a list of the colors that are sent by the AS/400, along with the values that TN5250 will display them as by default:

5250 Color Default Color Hex Color Code
green lightgreen #00FF00
white white #FFFFFF
red lightred #FF0000
turquoise cyan #008080
yellow yellow #FFFF00
pink lightmagenta #FF00FF
blue lightcyan #00FFFF
black black #000000

Each color can be re-mapped by setting the corresponding 5250 color keyword to a new color. To specify a color, you give a hexidecimal color code in this format:

                 (1)5250 color name = #(2)rr(3)gg(4)bb
            
(1)
The 5250 color name to re-map. (The color sent by the AS/400)
(2)
The red component of the color to display. This must be a 2-digit hexidecimal number from 00 - FF
(3)
The green component of the color to display. This must be a 2-digit hexidecimal number from 00 - FF
(4)
The blue component of the color to display. This must be a 2-digit hexidecimal number from 00 - FF

In addition to specifying the color as a hexidecimal Red Green Blue (RGB) number, TN5250 will also accept the following symbolic names:

Color Name Hex Color Code  
white #FFFFF0  
yellow #00FF00  
lightmagenta #FF00FF  
lightred #FF0000  
lightcyan #00FFFF  
lightgreen #00FF00  
lightblue #0000FF  
lightgray #808080  
gray #C0C0C0  
brown #808000  
red #800000  
cyan #008080  
green #008000  
blue #000080  
black #000080  

For example, perhaps most of your TN5250 session normally displays as green. Now you're tired of green, and would like a nice bright magenta instead, you'd specify:

               C:\Program Files\TN5250>tn5250 green=#FF0000 as400.example.com
            

or:

               C:\Program Files\TN5250>tn5250 green=lightmagenta as400.example.com
            

6.2.14. BLACK_ON_WHITE and WHITE_ON_BLACK (Color Style) options

This are boolean options. When you specify them, you need to either place a '+' in front of each to specify that they are enabled, or a '-' in front of each to specify that they're disabled.

These are used to force TN5250 to display all data in a monochrome (2-color) mode. The "black_on_white" option displays the words in black, and the background in white. The "white_on_black" option displays the words in white and the background in black

For example:

                 C:\Program Files\TN5250>tn5250 +white_on_black as400.example.com
             

Note: The +black_on_white setting is equivalent to setting the black 5250 color to be displayed as white in TN5250, and setting all of the other 5250 colors to be displayed as black.

Note: The +white_on_black setting is equivalent to setting the black 5250 color to be displayed normally in TN5250, and setting all of the other 5250 colors to be displayed as white.

Tip: The +black_on_white setting is very useful when you plan to make screen captures that you want to insert into your documentation. It works especially well when combined with the copymode=bitmap option!


6.2.15. RULER_COLOR (Rule Line Color) option

This sets the color of the rule lines displayed when the +ruler option is turned on (See "RULER" above.)

This color can be set to any of the hex codes for color display, or to one of the color names. For a list of color names, and more info about color codes, see the section called "BLACK, WHITE, RED, BLUE, ETC (Color) options", above.

Example:

                 C:\Program Files\TN5250>tn5250 +ruler ruler_color=#000080 as400.example.com
             

6.2.16. COLSEP_STYLE (Column Separator Style) option

This option lets you pick a style of column separator to display in TN5250. The options are:

Value Description
full (default) A vertical line is drawn between each character
dots dots are drawn to the left and below each character
none No column separators are drawn

Example:

                C:\Program Files\TN5250>tn5250 colsep_style=none as400.example.com
            

6.2.17. CARET_STYLE (Text Cursor Style) option

In Windows terminology, a "caret" is the cursor where text will appear when you type, and a "cursor" is the icon showing where the mouse is currently pointing.

This option lets you pick a caret style to use while in TN5250. The options are:

Value Description
block (default) A solid rectangular block
blink A block cursor that blinks (flashes)
line An underscore that flashes

Example:

                C:\Program Files\TN5250>tn5250 caret_style=line as400.example.com
            

Chapter 7. LP5250D Options

This section explains the configuration keywords that are available in LP5250D. For information on how to specify these keywords, see Chapters XXX and YYY.

Tip: Some of the examples below illustrate calling LP5250D from an MS-DOS prompt, and others illustrate the use of a profile in the tn5250rc file. However, any of the options should work from either of these scenarios, as well as from a Windows Shortcut.


7.1. Options processed by the server (Telnet Environment Options)

The TN5250e (Enhanced TN5250) protocol makes it possible to send user-defined variables to the AS/400. The AS/400, in turn, uses these variables in order to control some of the aspects of your printer session.

In older versions of OS/400, you may need to apply PTFs in order to enable TN5250e support. If you are running an older release of OS/400, please see APAR II10918 in IBM's AS/400 service database.

Environment options are specified to LP5250D in the following format:

               env.OPTION-NAME = Value
           

Whenever LP5250D is given an option that begins with 'env.', it will send it to the AS/400 without interpreting it's value. So, if IBM ever adds more options, you can specify them without needing to upgrade your copy of TN5250


7.1.1. The DEVNAME (Device Name) option

The DEVNAME option works the same way in lp5250d as it does in tn5250. For details on how specify a device name, see the "DEVNAME (Device Name)" topic in the TN5250 options section.

Example:

                 C:\Program Files\TN5250>lp5250d env.DEVNAME=PRT01 as400.example.com
              

7.1.2. The IBMMFRTYPMDL (Manufacturer Type & Model) option

This option tells the AS/400 to enable it's Host Print Transform function, and specifies the printer model that the AS/400 should transform it's data for.

For a list of values for this keyword, check out the MFRTYPMDL parameter to the CRTDEVPRT command on the AS/400.

Note: If you specify the special value of *WSCST for the IBMMFRTYPMDL option, then you'll also want to use the IBMWSCSTNAME and IBMWSCSTLIB options.

Examples:

                 printtest {
                    host = as400.example.com
                    env.DEVNAME=PRT02
                    env.IBMMFRTYPMDL = *HP4
                 }
    
                 plaintext {
                    host = as400.example.com
                    env.DEVNAME=PRT02
                    env.IBMMFRTYPMDL = *WSCST
                    env.IBMWSCSTNAME = QWPDEFAULT
                    env.IBMWSCSTLIB = *LIBL
                 }
             

7.1.3. The IBMWSCSTNAME & IBMWSCSTLIB (Workstation Customization) option

When you set the IBMMFRTYPMDL keyword to the value "*WSCST", then this parameter is used by the AS/400 to locate the name of a custom printer driver.

The IBMWSCSTNAME keyword is the name of the object on your AS/400, and the IBMWSCSTLIB keyword is used to specify which library that object is in.

Example:

                 plaintext {
                    host = as400.example.com
                    env.DEVNAME=PRT02
                    env.IBMMFRTYPMDL = *WSCST
                    env.IBMWSCSTNAME = QWPDEFAULT
                    env.IBMWSCSTLIB = *LIBL
                 }
             

7.1.4. The IBMMSGQNAME & IBMMSGQLIB (Message Queue) options

These keywords can be used to specify the name of the message queue to which operational messages for this printer device will be sent.

The IBMMSGQNAME option specifies the name of the message queue, and the IBMMSGQLIB option contains the name of the library that it is found in.

Example:

                 sample {
                    host = as400.sample.tv
                    env.DEVNAME=PRT02
                    env.IBMMFRTYPMDL = *HP4
                    env.IBMMSGQNAME=QSYSOPR
                    env.IBMMSGQLIB=*LIBL
                 }
             

7.2. Options processed by the LP5250D client

The options in this section are processed by the LP5250D client itself, and are not passed on to the AS/400.


7.2.1. The VERSION (Display Version and Exit) option

This just tells you the version of lp5250d that you have installed.

Example:

                 C:\Program Files\TN5250>lp5250d +version
             

7.2.2. The HOST (host name of server) option

The HOST option is used the same way in lp5250d as it is in TN5250. See the section entitled "HOST (host name of server)" under TN5250 Options for details on how to specify a host name.

Note: The debug: stream type is currently unimplemented in lp5250d, however SSL and Telnet both work.

Example:

                 C:\Program Files\TN5250>lp5250d env.DEVNAME=PRT01 ssl:as400.example.com
              

7.2.3. The MAP (Character translation map) option

Sets the translation table which translates between ASCII and EBCDIC. This should match the CCSID of the interactive job. The default value is 37.

The MAP option works the same way in lp5250d as it does in tn5250. For details on how specify a map, see the "MAP (Character translation map)" topic in the TN5250 options section.

Example:

                 C:\Program Files\TN5250>lp5250d map=273 env.DEVNAME=PRT01 as400.example.de
              

7.2.4. The TRACE (create trace file) option

The TRACE option works the same way in lp5250d as it does in tn5250. For details on how specify a trace file, see the "TRACE (create trace file)" topic in the TN5250 options section.

Note: The ability to play-back a tracefile is currently unimplemented in lp5250d. However, the debugging information contained in the file itself may still be useful to a developer who is trying to find a printer problem

Example:

                C:\Program Files\TN5250>lp5250d trace=C:\debug.txt as400.here.net
             

See the section entitled "Troubleshooting & Reporting Bugs" for more information on trace files and getting support.


7.2.5. The OUTPUTCOMMAND (direct printer output) option

This lp5250d option is used to tell lp5250d where you'd like to send the printer output. This keyword is optional, and if it is not specified, lp5250d will send the printer output to your default Windows printer.

The outputcommand is specified using the following syntax:

                outputcommand = (1)output-type:(2)device or file name
             
(1)
The output type specifies the type of device that the data from the AS/400 will be written to.

The possible output types are "file:" and "printer:"

(2)
This signifies either the filename that you wish to write the output to, or the printer name that you wish to print the output on.

Examples:

                 printer {
                    host = ssl:as400.somewhere.net
                    env.DEVNAME = PRT11
                    outputcommand = file:C:\printouts\report.txt
                 }
                 
                 printer2 {
                    host = ssl:as400.example.com
                    env.DEVNAME = P1
                    outputcommand = printer:Canon BJC-620
                 }
    
                 printer3 {
                    host = ssl:as400.example.com
                    env.DEVNAME = PRT01
                    env.IBMMFRTYPMDL = *HP4
                    outputcommand = printer:HP LaserJet 4L
                 }
             

Tip: The printer name must exactly match the name that Windows knows your printer by. If you open up the My Computer icon, and then select "Printers", you can get a list of which printers are configured.

Important: This option may change, as some of the developers are not completely satisfied by the way that it works.


Chapter 8. Troubleshooting & Reporting Bugs

8.1. The bug fixing process, and how to get help

For the most part, development and support of this project is done by people in their spare time. We do our best to find the bugs in the software, and fix them, but inevitably there will be some that fall through the cracks.

When bugs are fixed, we discuss them on our mailing list, fix them, and submit the fixes to our CVS repository. (The CVS repository is a software package that keeps track of all of the changes we make to the program, and allows us to see what has been done, and back up to older revisions if needed.) This means that, frequently, something will be fixed in CVS a few months before it will be made available in a general release.

Due to this model of development and support, we ask that you take the following steps when you find an error, and need help:

  1. Go to our web page, http://tn5250.sourceforge.net and see if there's anything posted there that might help you.

  2. If nothing was found on our web site, search the archives of our mailing list. Almost everything that's worked on for the whole project is reported to the mailing list.

    You can find the archives here: http://archive.midrange.com Click on "Linux5250" and then do your search.

  3. If neither of those steps has proven helpful, then your best bet is to subscribe to the mailing list and ask for help.

    There is a link on our home page that will help you sign up for the mailing list.

  4. Finally, after some discussion on the mailing list, you may be asked to submit some diagnostic information to one or more of the developers.

Currently, all support for this project is handled by E-mail. Keep in mind that all of the developers have full time jobs that are not related to maintaining this emulator. We simply can't provide you with a phone number to call for support.

Having said that, however, most of the bugs reported to the mailing list are fixed promptly. (Usually within one week.) and questions are answered even more promptly. (Usually within one day.)


8.2. Creating a trace file

The best diagnostic tool in TN5250 is it's "trace" capability. When this option is enabled, everything that the emulator does is written to a file on your hard disk. Every keystroke is logged. Every byte sent or received from the AS/400 is logged. Key information about how the emulator is processing certain things are logged.

The trace function of TN5250 is enabled when you specify a filename using the trace keyword. For example, if you wanted to trace your session, logging the information to a file called "tracefile.txt", you might type the following command:

            C:\Program Files\TN5250>tn5250 trace=tracefile.txt as400.example.com
         

Then, you'll want to use the emulator to reproduce the bug that is causing problems for you. Just do whatever it takes to make the bug manifest itself, and then sign off and exit the emulator.

Now that your session has been logged to the trace file, you can re-play that session by typing:

            C:\Program Files\TN5250>tn5250 debug:tracefile.txt
         

When you do this, the emulator will start up again, but this time you won't actually be connected to your AS/400. Instead, you will be re-playing the trace file.

While the trace file is playing, each time you press a key, the emulator will do the next "event" that happened during the session that you traced. If you keep pressing a key, the session will play back, much like you're watching a movie.

Note: FIXME: Is that clear?

When you send the trace file to the developer, he will also be able to step through your session, and see exactly what you saw when things went wrong.

The trace file is just an ordinary ASCII text file. You can view it on your system in any text editor. For example, if you wanted to look at it in the MS-DOS editor, you might type:

            C:\Program Files\TN5250>edit tracefile.txt
         

However, unless you're a developer, the contents of this file probably won't be very helpful to you. (Still, it might be worth looking at!)

Important: Please don't ever send a trace file to the Linux5250 mailing list. Trace files can be large, and the mailing list is read by a lot of people. When a developer needs you to send him a tracefile, please send it to the developer directly!

Important: Trace files log everything that happens during your session, including your user name and password. For this reason, it is a good idea to change your password after you've created a trace file.


Chapter 9. Running TN5250 from a network share or floppy disk

If you like, you can copy the Windows version of TN5250 to a floppy disk and/or network share, instead of installing it individually on each PC you wish to use it on. Here are some guidelines for doing that.


9.1. Which files are needed for TN5250 to run?

Here are the files that TN5250 must have:

  • lib5250.dll is the core of TN5250, and must be available for anything to work.

  • tn5250.exe is necessary if you want to do terminal emulation.

  • lp5250d.exe is necessary if you want to have printer support.

The following files aren't required, but might be useful:

  • tn5250rc the configuration file.

  • This documentation.


9.2. Where do I have to put the files?

TN5250 was designed so that an "Install" and "Uninstall" software would not be needed. TN5250 does not modify the Windows Registry, and it does not require it's DLL to be registered with the operating system.

What all of that means is that you can run it off of any directory on any disk. It can be a floppy, a CD-ROM, a network share, or a hard drive.

There are just a few simple restrictions:

  • When Windows loads tn5250.exe or lp5250d.exe, it has to be able to find the lib5250.dll file. It does this by first looking in your "current directory", and then if it's not found, it searches your PATH

    Therefore, you can copy everything to a floppy, and run it from the floppy, just as long as you switch your current directory to the floppy drive before starting tn5250.exe

  • When you run tn5250 or lp5250d and try to use a configuration profile, tn5250 will look for the tn5250rc in the same directory that tn5250.exe is in.


9.3. Utilizing the $loginname$ feature

Any time TN5250 encounters the word $loginname$ (spelled exactly that way, in all lowercase) it will be replaced by the name of the user who is currently logged on to the Windows Desktop

This is particularly useful when running TN5250 from a network share because you can use it to set a different device name for each user, while still having only one tn5250rc file.

For example, you might use this profile:

             userdisplay {
                env.DEVNAME = $loginname$S1
                host = as400.example.com
             }
         

This way, each user gets their own device ID when they connect.