TN5250 for Windows

Scott Klement

TN5250 for Windows by 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 conguration and day-to-day use of the TN5250 emulator in a Windows environment

Table of Contents
1. The Quick-Connect dialog .......................................................................................................................................1 1.1. A quick-start with Quick-Connect .................................................................................................................1 1.2. Giving your terminal a name..........................................................................................................................1 1.3. Options available on the Quick-Connect dialog.............................................................................................1 1.3.1. Host to connect to ..............................................................................................................................1 1.3.2. Device Name......................................................................................................................................2 1.3.3. Use SSL Encryption ..........................................................................................................................2 1.3.4. Verify Servers SSL certicate...........................................................................................................2 1.3.5. Auto-copy, Right-click paste .............................................................................................................2 1.3.6. Char Map ...........................................................................................................................................2 1.3.7. Terminal Size .....................................................................................................................................3 2. Conguring TN5250 with command-line switches ................................................................................................4 3. Creating TN5250 proles .........................................................................................................................................6 4. Printer Support (LP5250D) .....................................................................................................................................8 4.1. What a funny name! .......................................................................................................................................8 4.2. A quick example of running lp5250d.............................................................................................................8 4.3. A more sophisticated example .......................................................................................................................8 4.3.1. Creating the prole for our printer settings .......................................................................................9 4.3.2. Creating a Windows Shortcut for our lp5250d session ...................................................................10 5. Using SSL with TN5250 .........................................................................................................................................11 5.1. Setting up your server...................................................................................................................................11 5.2. Telling TN5250 to use SSL for encryption ..................................................................................................12 5.3. Telling TN5250 to verify the authenticity of your server.............................................................................12 5.4. Conguring TN5250 for client certicates ..................................................................................................13 6. TN5250 Options ......................................................................................................................................................15 6.1. Options processed by the server (Telnet Environment Options)..................................................................15 6.1.1. The DEVNAME (Device Name) option..........................................................................................15 6.1.2. The TERM (Terminal Type) option.................................................................................................15 6.1.3. The KBDTYPE, CODEPAGE and CHARSET (Language) options...............................................16 6.1.4. The USER, IBMSUBSPW, IBMCURLIB, IBMIMENU, IBMPROGRAM (Auto Sign-on) options 16 6.2. Options processed by the TN5250 client .....................................................................................................17 6.2.1. The HOST (host name of server) option .........................................................................................17 6.2.2. The MAP (Character translation map) option .................................................................................19 6.2.3. The RULER (Draw lines to my cursor) option................................................................................20 6.2.4. The VERSION (Display Version and Exit) option..........................................................................20 6.2.5. The PCSPEAKER (Use PC Speaker) option...................................................................................20 6.2.6. The BEEPFILE (Special Beep Sound File) option..........................................................................21 6.2.7. The COPYMODE (Copy To Clipboard Mode) option....................................................................21 6.2.8. The UNIX_LIKE_COPY (Copy/Paste like a Unix xterm) option ..................................................21 6.2.9. The UNIX_SYSREQ (Use Ctrl-C for SysReq) option....................................................................22

iii

6.2.10. The TRACE (create trace le) option............................................................................................22 6.2.11. The FONT_80 and FONT_132 (Font) options..............................................................................23 6.2.12. RESIZE_FONTS (Re-size fonts to match window size) option ...................................................23 6.2.13. BLACK, WHITE, RED, BLUE, ETC (Color) options .................................................................24 6.2.14. BLACK_ON_WHITE and WHITE_ON_BLACK (Color Style) options.....................................25 6.2.15. RULER_COLOR (Rule Line Color) option ..................................................................................26 6.2.16. COLSEP_STYLE (Column Separator Style) option.....................................................................26 6.2.17. CARET_STYLE (Text Cursor Style) option.................................................................................26 7. LP5250D Options ....................................................................................................................................................28 7.1. Options processed by the server (Telnet Environment Options)..................................................................28 7.1.1. The DEVNAME (Device Name) option..........................................................................................28 7.1.2. The IBMMFRTYPMDL (Manufacturer Type & Model) option.....................................................28 7.1.3. The IBMWSCSTNAME & IBMWSCSTLIB (Workstation Customization) option ......................29 7.1.4. The IBMMSGQNAME & IBMMSGQLIB (Message Queue) options...........................................29 7.2. Options processed by the LP5250D client ...................................................................................................30 7.2.1. The VERSION (Display Version and Exit) option..........................................................................30 7.2.2. The HOST (host name of server) option .........................................................................................30 7.2.3. The MAP (Character translation map) option .................................................................................30 7.2.4. The TRACE (create trace le) option..............................................................................................31 7.2.5. The OUTPUTCOMMAND (direct printer output) option ..............................................................31 8. Troubleshooting & Reporting Bugs.......................................................................................................................33 8.1. The bug xing process, and how to get help ................................................................................................33 8.2. Creating a trace le ......................................................................................................................................33 9. Running TN5250 from a network share or oppy disk.......................................................................................35 9.1. Which les are needed for TN5250 to run? .................................................................................................35 9.2. Where do I have to put the les? ..................................................................................................................35 9.3. Utilizing the $loginname$ feature................................................................................................................35

iv

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 congured 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. 2. 3. 4. Double-click the TN5250 icon on your desktop or start menu 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. You should now have an AS/400 sign-on screen. Congratulations! 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. 2. 3. Double-click TN5250 again. Note that if you hadnt closed the previous window, this would start up a second TN5250 session. (This is useful, because its sometimes nice to have two or more 5250 sessions open at once.) This time, after lling 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. 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 TN5250s options can be set using the Quick-Connect dialog. Most of the options are set using the a "command-line" or "prole" 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 specied here. Just separate the host name from the port number with a colon. For example, to connect using port 1025, I might specify:

Chapter 1. The Quick-Connect dialog

AS400.EXAMPLE.COM:1025

You can also add a "stream type" identier to the beginning of the host name. For example, if I wanted to play back a debugging trace le, I could specify:
debug:C:\tn5250\tracefile.txt

1.3.2. Device Name

This is the device name that youd 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 congured 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 Servers SSL certicate

With this option enabled, the SSL connection wont be allowed unless the AS/400s SSL certicate is valid, and has been signed by a trusted certicate authority. Many companies will generate their own certicates, instead of paying for the services of an ofcial certicate authority. If the "Verify Server" option is checked, these certicates wont be allowed, and the connection will fail. You can specify your own certicate 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, youll 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:

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

1.3.7. Terminal Size

Here you can select whether you want a terminal thats capable of only 24x80 mode (24 rows by 80 columns) or if its 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. Conguring 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 TN5250s options. To try it out: 1. 2. Open up an MS-DOS prompt. 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 dont 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.

Chapter 2. Conguring TN5250 with command-line switches There are many more options available from the command-line in tn5250. See the chapter on OPTIONS for more information. Now, lets suppose that youve 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, theyll 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, youd rst click My Computer, then C:, then Program Files, and nally TN5250. Right-click the Tn5250.exe icon and select "Copy". Close the My Computer window, and right-click your desktop. Choose "Paste Shortcut" Right click the new shortcut, and select "Rename". Rename it to something easy to remember. I called mine "DSP51". Right click the new shortcut again, and choose "Properties" On the line that says "Target:", add the options that youd like to use. For example, Im setting my Target to look like this:
"c:\Program Files\TN5250\TN5250.EXE" env.DEVNAME=DSP51 ssl:as400.example.com

2. 3. 4. 5. 6.

7. 8.

Click OK to save your changes 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 proles

Sometimes its useful, especially when you have a lot of settings to manage, to keep your tn5250 settings in a le, instead of typing them all into a command-line or shortcut. The way that you do this is by dening a "tn5250rc" le. 1. 2. 3. Open up an MS-DOS prompt. Just like you did when you tried out the command-line options, Switch to the directory where you installed the TN5250 software. Use the MS-DOS editor to create a new le called tn5250rc by typing: edit tn5250rc 4. Set all of your TN5250 options in this le. For example, if you wanted to create a display called FRED1 which connects to an as400 called iseries.sample.com, youd type this:
profile1 { host = iseries.sample.com env.DEVNAME=FRED1 }

5.

Now that youve created this, you can utilize those settings just by typing: tn5250 profile1 Be careful of capitalization. "prole1" is not the same as "Prole1", and thats different from "PROFILE1".

6.

You can set any of tn5250s settings in the tn5250rc le. Heres 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

Chapter 3. Creating TN5250 proles

env.IBMMSGQNAME = QSYSOPR env.IBMMSGQLIB = *LIBL }

See, I wasnt kidding when I said that would be more sophisticated! This copy of tn5250rc contains 3 different proles called prole1, prole2 and printer respectively. 7. Now, you can run those proles by typing:
C:\Program Files\TN5250>tn5250 profile1 C:\Program Files\TN5250>tn5250 profile2 C:\Program Files\TN5250>lp5250d printer

Tip: You can use proles 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, youll 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 its running. In order to use lp5250d, your AS/400 must support the enhanced TN5250e servers. This was rst available in V3R2, but required a PTF to activate it. If youre 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 Im writing this document, lp5250d does not have a "Quick-Connect" dialog like tn5250 does. You have to congure it using proles or command-line arguments. Heres an example of running lp5250d to help get you started: 1. 2. Open up an MS-DOS prompt. 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 conguration 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

Chapter 4. Printer Support (LP5250D) these settings in a prole in our tn5250rc le, and create a shortcut for the printer. Are you ready? (why do I ask these things?)

4.3.1. Creating the prole for our printer settings

1. 2. Once again, go to an MS-DOS prompt, and switch to the directory where you installed TN5250. (If you dont know how to do this, see the previous section in this document.) At the MS-DOS prompt, edit your tn5250rc le. (If you dont already have one, create it now)
C:\Program Files\TN5250>edit tn5250rc

3.

Add a new prole onto the end. For our example, well create an entry for Hewlett Packard LaserJet 4 printer. So, Im going to call the prole "hp"
hp { host = as400.example.com env.DEVNAME = PRT04 env.IBMMFRTYPMDL = *HP4 env.IBMMSGQNAME = DSP51 env.IBMMSGQLIB = *LIBL map = 37 }

This is the hostname that lp5250d will connect to. You can prex this with "ssl:" if you wish to encrypt your session, or sufx it with a ":123" to select an alternate port number, just as you can in tn5250! This is the name that the AS/400 will use when creating its device description and its 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 congured.

This asks the AS/400 to use its "Host Print Transform" function to convert the spooled les to our printers native language. For our example, weve 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 specied here.

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 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. This is equivalent to the "Char Map" option that was described in the "Quick-Connect" options for TN5250. It species 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.

Chapter 4. Printer Support (LP5250D) 4. 5. Save your changes to the tn5250rc le, and exit back to the MS-DOS prompt. 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 dont need to open up an MS-DOS prompt each time we want to start lp5250d, well create a shortcut on our desktop which will start it when we double-click it. 1. 2. 3. 4. 5. 6. 7. Double click the "My Computer" icon and navigate to the directory where you installed TN5250 Right-click the "lp5250d" executable, and choose "copy". Close the My Computer window and right-click your desktop. Choose "Paste Shortcut." Windows will create a "Shortcut to LP5250D" on your desktop. Right-click the new shortcut and choose "rename". Change the name of the short cut to "PRT04" (or another name that appeals to you) Right-click the new shortcut again, and this time choose "Properties" Switch to the "Shortcut" tab, and at the end of the text in the "Target:" box, add prole name of "hp". My "Target" now looks like this:
"C:\Program Files\TN5250\LP5250D.EXE" hp

8. 9.

Click the OK button to save your changes. To test it out, double-click on the PRT04 icon!

10

Chapter 5. Using SSL with TN5250

Using the Secure Sockets Layer (SSL) protocol, it is possible to congure your AS/400 and tn5250 to encrypt and protect its 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 isnt as easy. This section will attempt to walk you through a basic setup of your AS/400s secure telnet server. There are many wonderful things you can do with SSL and with the OS/400 Digital Certicate 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 certicates (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 congure the TELNET server to use the SSL. 1. You must install the following software on your AS/400:

Digital Certicate 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 rst 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 youre given a choice, youll want to install 5769-AC3, as it has the best cryptography. 2. Start the HTTP *ADMIN server in order to congure your Digital Certicate Manager. From the AS/400, type:
STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

3. 4. 5. 6.

With a web browser, connect to your AS/400s admin server: http://as400.example.com:2001 Click "Digital Certicate Manager", then "Certicate Authority (CA)" then "Create a Certicate Authority." Fill out the forms, etc. Click "System Certicates". IF you havent done so already, click "Create new certicate store" and follow the prompts for creating the *SYSTEM certicate store. Select "Work With Secure Applications". Select "QIBM_QTV_TELNET_SERVER", then click the "Work with system certicate" button. It should tell you that your telnet server has your system certicate assigned to it. IF not, you can assign it here. Now you have to start your telnet server on the AS/400. If it is already running, youll have to end it, and start it again.

7.

11

Chapter 5. Using SSL with TN5250 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 thats 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 conguration area of the iSeries Information Center. Heres 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, prex the hostname with ssl: in your conguration. For example, type:
C:\Program Files\TN5250>tn5250 ssl:as400.example.com

Or, if youre 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 certicate 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, youll need to download a copy of your AS/400s "Certicate Authority" (CA) certicate, which you will store on your hard drive. Then, when TN5250 starts, it can verify that each session has been "signed" by your AS/400s Certicate Authority 1. If its not already running, start the AS/400s HTTP *ADMIN server by typing:
STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

2. 3.

Connect to the Admin server with a web browser: http://as400.example.com:2001 Click "Digital Certicate Manager", then "Certicate Authority (CA)" then "Install CA certicate on your PC", then click "Copy and paste certicate"

12

Chapter 5. Using SSL with TN5250 4. Highlight the certicate 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 browsers Edit menu. Open a utility such as Notepad and paste the certicate into it. Then save the document as C:\Program Files\TN5250\as400_ca.txt (or, if you like, some other name) Add the "ssl_ca_le" option to your tn5250rc le, so that TN5250 knows where the AS/400s certicate is. Heres an example prole:
ssltest { host = ssl:as400.example.com env.DEVNAME = SSL1 +ssl_verify_server ssl_ca_file = C:\Program Files\TN5250\as400_ca.txt }

5. 6.

7.

The +ssl_verify_server keyword tells TN5250 that you want it to verify the authenticity of your AS/400. The ssl_ca_le keyword must point to the certicate that you just downloaded from the AS/400.

Now you can envoke tn5250:

C:\Program Files\TN5250>tn5250 ssltest

5.4. Conguring TN5250 for client certicates

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 congure your AS/400 to only allow connections from people using the AS/400s private certicate authority. If you set this up correctly, you can restrict your system to people who youve specically given certicates to. Explaining how to congure the server for this is beyond the scope of this document. However, once the server has been congured this way, youll need to know how to tell TN5250 to use a certicate assigned by your server. In order to follow these steps, youll 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, youll need to get it from http://www.openssl.org 1. If its not already running, start the AS/400s HTTP *ADMIN server by typing:
STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

2. 3.

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 youd do it with a different browser, so good luck...) http://as400.example.com:2001 Click "Digital Certicate Manager", then "Certicate Authority (CA)" then "Install CA certicate on your PC", then click "Receive certicate"

13

Chapter 5. Using SSL with TN5250 4. 5. 6. 7. 8. 9. Netscape brings up the "New Certicate Authority" wizard. Follow the prompts, until you can nally click "Finish". Click "User Certicates", then "Request a new user certicate", Fill out the form and click OK. 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. After lling out your password, and waiting a second or two, you should come to a screen that says "User Certicate Created Successfully". Click "Receive Certicate". The certicate should be downloaded into your web browser. It may not tell you that it did anything, so dont be surprised if nothing seems to happen. On the Netscape "Navigation Toolbar" click the "Security" button. (This is the button that looks like a padlock). Then under "Certicates", click on "Yours".

10. The certicate that you just generated should appear, along with any other private-key certcates 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 certicate to a le called "tn5250.p12" It will tell you that the certicate has been successfully exported. Good work! 14. Unfortunately, Netscape likes to save the certicate in pkcs12 format, which doesnt 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, nally, to tell tn5250 to use this certicate that you just received, use the ssl_cert_le keyword. Youll 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. Heres 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

14

Chapter 6. TN5250 Options

This section explains the conguration 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 prole in the tn5250rc le. 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-dened 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 IBMs AS/400 service database. Environment options are specied 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 its 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 youd 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. Heres 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".

15

Chapter 6. TN5250 Options

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 specied.
Tip: This is the keyword that species whether 27x132 mode is allowed for your session, or not.

Terminal Type IBM-3477-FC IBM-3477-FG IBM-3180-2 IBM-3179-2 IBM-3196-A1 IBM-5292-2 IBM-5291-1 IBM-5251-11 Example:

Description 27x132-capable color 27x132-capable mono 27x132-capable mono 24x80-capable color 24x80-capable mono 24x80-capable color 24x80-capable mono 24x80-capable mono

Default Yes

Yes

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 Conguration 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 }

16

Chapter 6. TN5250 Options

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 le 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 companys 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 doesnt 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.

17

Chapter 6. TN5250 Options

Note: When given on a command-line, the host name is not prexed 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 prole.

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

The value of the host keyword takes this format:

host = STREAM-TYPE:hostname:PORT

The host= keyword is only specied when you are creating a tn5250rc prole. 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. The STREAM-TYPE is optional. If not given, the default value is "telnet:" The possible values for STREAM-TYPE are: Stream-Type telnet: tn5250: ssl: telnets: debug: Description The 5250 data is sent over the standard TCP/IP telnet protocol. This is an alias for "telnet" The 5250 data is sent over an SSL-encrypted TCP/IP telnet session. This is an alias for "ssl" Stream data is read from a trace le.

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

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

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

18

Chapter 6. TN5250 Options Prole 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: "Its safe to put my password in a # file on my PC. Wholl 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. Thats not really Carls 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 37 256 273 277 278 Windows encoding windows-1252 windows-1252 windows-1252 windows-1252 windows-1252 Description US, Canada, Netherlands, Portugal, Brazil, Australia, New Zealand Netherlands Austria, Germany Denmark, Norway Finland, Sweden

19

Chapter 6. TN5250 Options CCSID 280 284 285 290 297 420 424 500 870 871 875 880 905 1026 Example:
C:\Program Files\TN5250>tn5250 map=880 as400.moscow.ru

Windows encoding windows-1252 windows-1252 windows-1252 JIS_X0201 windows-1252 windows-1256 windows-1255 windows-1252 windows-1250 windows-1252 windows-1253 windows-1251 windows-1254 windows-1254

Description Italy Spain, Latin America United Kingdom Katakana Extended France Arabic Hebrew Belgium, Canada, Switzerland Eastern Europe Iceland Greece Cyrillic Turkey - Latin3 Turkey - Latin5

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

20

Chapter 6. TN5250 Options

6.2.5. The PCSPEAKER (Use PC Speaker) option

Unless this option is specied, 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) le, 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 youre 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 its disabled. When this is enabled, data is copied to the clipboard automatically after you highlight it. (You dont need to press Ctrl-C, or Click EDIT/COPY to make it go to the clipboard)

21

Chapter 6. TN5250 Options 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, its 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 its 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 isnt enabled by default.

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

6.2.10. The TRACE (create trace le) option

When this option is given, the 5250 data stream is written to a "trace le", 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 le 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 x the problem.
Important: When you create a trace le, 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 le, we recommend that you change your password after creating it.

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

22

Chapter 6. TN5250 Options See the section entitled "Troubleshooting & Reporting Bugs" for more information on trace les 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 specied in the following format:
font_80 = Font Name-W xH

Note: The font_132 keyword has the exact same syntax.

This is the name of the font to use. Its important to use a font that has a xed-width. A proportionally spaced font (which are very popular with Windows currently) will yield strange-looking results. 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 nd. You do not have to specify a width. 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 nd. 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 its 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

23

Chapter 6. TN5250 Options

Note: Most fonts can only be displayed at specic sizes. If your screen is set to a size that doesnt exist, TN5250 will let Windows pick the next closest size. If this doesnt 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 green white red turquoise yellow pink blue black Default Color lightgreen white lightred cyan yellow lightmagenta lightcyan black Hex Color Code #00FF00 #FFFFFF #FF0000 #008080 #FFFF00 #FF00FF #00FFFF #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:
5250 color name = #rr gg bb

The 5250 color name to re-map. (The color sent by the AS/400) The red component of the color to display. This must be a 2-digit hexidecimal number from 00 - FF The green component of the color to display. This must be a 2-digit hexidecimal number from 00 - FF 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 white yellow lightmagenta Hex Color Code #FFFFF0 #00FF00 #FF00FF

24

Chapter 6. TN5250 Options Color Name lightred lightcyan lightgreen lightblue lightgray gray brown red cyan green blue black Hex Color Code #FF0000 #00FFFF #00FF00 #0000FF #808080 #C0C0C0 #808000 #800000 #008080 #008000 #000080 #000080

For example, perhaps most of your TN5250 session normally displays as green. Now youre tired of green, and would like a nice bright magenta instead, youd 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 theyre 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.

25

Chapter 6. TN5250 Options

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 full dots none Example:
C:\Program Files\TN5250>tn5250 colsep_style=none as400.example.com

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

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 block blink line Description (default) A solid rectangular block A block cursor that blinks (ashes) An underscore that ashes

26

Chapter 6. TN5250 Options Example:

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

27

Chapter 7. LP5250D Options

This section explains the conguration 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 prole in the tn5250rc le. 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-dened 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 IBMs AS/400 service database. Environment options are specied 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 its 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 its Host Print Transform function, and species the printer model that the AS/400 should transform its 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 youll also want to use the IBMWSCSTNAME and IBMWSCSTLIB options.

28

Chapter 7. LP5250D 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 species the name of the message queue, and the IBMMSGQLIB option contains the name of the library that it is found in. Example:

29

Chapter 7. LP5250D Options

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:

30

Chapter 7. LP5250D Options

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

7.2.4. The TRACE (create trace le) option

The TRACE option works the same way in lp5250d as it does in tn5250. For details on how specify a trace le, see the "TRACE (create trace le)" topic in the TN5250 options section.
Note: The ability to play-back a tracele is currently unimplemented in lp5250d. However, the debugging information contained in the le itself may still be useful to a developer who is trying to nd 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 les and getting support.

7.2.5. The OUTPUTCOMMAND (direct printer output) option

This lp5250d option is used to tell lp5250d where youd like to send the printer output. This keyword is optional, and if it is not specied, lp5250d will send the printer output to your default Windows printer. The outputcommand is specied using the following syntax:
outputcommand = output-type:device or file name

The output type species the type of device that the data from the AS/400 will be written to. The possible output types are "le:" and "printer:"

This signies either the lename 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 }

31

Chapter 7. LP5250D Options

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

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

32

Chapter 8. Troubleshooting & Reporting Bugs

8.1. The bug xing 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 nd the bugs in the software, and x them, but inevitably there will be some that fall through the cracks. When bugs are xed, we discuss them on our mailing list, x them, and submit the xes 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 xed 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 nd an error, and need help: 1. 2. Go to our web page, http://tn5250.sourceforge.net and see if theres anything posted there that might help you. If nothing was found on our web site, search the archives of our mailing list. Almost everything thats worked on for the whole project is reported to the mailing list. You can nd 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 cant provide you with a phone number to call for support. Having said that, however, most of the bugs reported to the mailing list are xed promptly. (Usually within one week.) and questions are answered even more promptly. (Usually within one day.)

8.2. Creating a trace le

The best diagnostic tool in TN5250 is its "trace" capability. When this option is enabled, everything that the emulator does is written to a le 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 lename using the trace keyword. For example, if you wanted to trace your session, logging the information to a le called "tracele.txt", you might type the following command:
C:\Program Files\TN5250>tn5250 trace=tracefile.txt as400.example.com

33

Chapter 8. Troubleshooting & Reporting Bugs Then, youll 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 le, 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 wont actually be connected to your AS/400. Instead, you will be re-playing the trace le. While the trace le 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 youre watching a movie.
Note: FIXME: Is that clear?

When you send the trace le 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 le is just an ordinary ASCII text le. 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 youre a developer, the contents of this le probably wont be very helpful to you. (Still, it might be worth looking at!)
Important: Please dont ever send a trace le to the Linux5250 mailing list. Trace les can be large, and the mailing list is read by a lot of people. When a developer needs you to send him a tracele, please send it to the developer directly!

Important: Trace les 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 youve created a trace le.

34

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

If you like, you can copy the Windows version of TN5250 to a oppy 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 les are needed for TN5250 to run?

Here are the les that TN5250 must have:
lib5250.dll tn5250.exe

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

is necessary if you want to do terminal emulation. is necessary if you want to have printer support.

lp5250d.exe

The following les arent required, but might be useful:

tn5250rc

the conguration le.

This documentation.

9.2. Where do I have to put the les?

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 its 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 oppy, 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 nd the lib5250.dll le. It does this by rst looking in your "current directory", and then if its not found, it searches your PATH Therefore, you can copy everything to a oppy, and run it from the oppy, just as long as you switch your current directory to the oppy drive before starting tn5250.exe

When you run tn5250 or lp5250d and try to use a conguration prole, 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

35

Chapter 9. Running TN5250 from a network share or oppy disk 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 le. For example, you might use this prole:
userdisplay { env.DEVNAME = $loginname$S1 host = as400.example.com }

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

36