Top

HowToModifyTerminfoFilesForSAS

This information is specifically for the BioEpi people over in Centerra?, although if you're trying to modify term files for another purpose, this document will probably give you enough information to make it work.

RobinsonTryon

Big Idea

we want to make command-line sas612 work on windows machines with function keys, etc... so we're going to use the ssh client PuTTY + a modified terminfo file to give us the same functionality on Polaris/Cascade as we had on (the retiring) Belknap.

Some useful information

I got a really useful reference from the http://www.sas.com website -- a plaintext file that talked about modifying term files using 'tic' and 'untic'.

here's the link for that file:

• http://ftp.sas.com/techsup/download/technote/ts263.txt

Useful stuff about the term files is available if you look at the man page for terminfo (type man terminfo on the remote machine running sas612).

Wherever the SAS612 folder is on your disk, you'll want to be familiar with two subdirectories, utilities/ and terminfo/.

on cascade, we have:

/appls1/sas612/utilities /appls1/sas612/terminfo

1. So the first thing that we want to do is get a file that describes our terminal and 'untic?' it -- i.e. put it in a plaintext format that we can read and modify.

Actually, in the bigger picture we're going to make a new 'home' for terminfo files. Then, when we run sas612 we're going to tell it to look in OUR terminfo directory (rather than the system's terminfo folder, which on cascade is found in /usr/share/lib/terminfo). Good idea, eh?

So I created a folder in my afs home directory called terminfo/. And then, after much trial and error, I realized that I just wanted to have a terminfo file for the vt220 terminal.

Note that files are (generally) stored in folders a through z in the terminfo folder. Therefore, I created a folder called 'v/' inside that terminfo directory.

2. The next thing I did was to grab a copy of the vt220-nam file from the sas612/terminfo/v/ directory. (Note: I could have just as well gotten that file from the system terminfo directory; in some cases, this might be preferred because if I run sas612 with a vt220 terminal, I'm using the file from the system directory, not from the sas612 directory... it's a minor point)

I copied the file to ~/terminfo/v/vt220-nam,

3. A few more things I needed to setup before decompiling the terminfo file:

Set the terminal type to vt220, so if we're using tcsh, type

cascade~> setenv TERM vt220

Set the TERMINFO environment variable so that untic knows where to get term files. Again, using tcsh we can type:

cascade~> setenv TERMINFO sas612/terminfo

where sas612/ is our sas system directory as above...

4. Okay, ready to go. So then I used the 'untic' tool that is found in sas612/utilities/bin/untic to create a plaintext version of the file:

cascade~> /appls1/sas612/utilities/bin/untic -t vt220-nam > vt220-nam.term

(so we're taking input from the vt220-nam (binary) terminfo file, and redirecting the output into the vt220-nam.term (human-readable, ascii) file.

NOTE: So in truth I don't need a copy of the vt220-nam file in my home directory, but it's nice to have all of the pieces together so that if you move to a different system or if things get reinstalled, you still have a copy of the original that you used to generate the plaintext.

NOTE: sorry about all these notes, but I just realized that you could set your TERMINFO variable to be ~/terminfo instead of sas612/terminfo, and then run the untic command as above. That might come in handy sometime.

MORE INFORMATION: Here's the usage info for 'untic':

Usage: untic [-t term] [-f filename]

untic prints to standard output (hence the reason why I redirected the output into the vt220-nam.term file. The '.term' extension on the end of that file is not required, but was a convention of the docs that I read.

The '-t' flag can be used to specify a specific term type to pass to untic; by default, the value in the TERM env variable is used.

Note that I put all of the plaintext versions of the terminfo files in the folder ~/terminfo/. I'm not sure if there could be bad effects from putting them in ~/terminfo/v/....

5. Okay, time to edit the terminfo description. The contents of these files look confusing and strange, but just hang in there and trust your intuition (or mine, I guess :) and it'll all come together in the end.

The vt220-nam.term file looks like this:

#
vt220-nam,
   xon, 
   cols#80, it#8, lines#24, vt#3, 
   bel=^G, cr=^M, csr=\E[%i%p1%d;%p2%dr, tbc=\E[3g, 
   clear=\E[H\E[2J, el=\E[K, ed=\E[J, 
   cup=\E[%i%p1%d;%p2%dH, cud1=\E[B, home=\E[H, 
   civis=\E[?25l, cub1=\E[D, cnorm=\E[?25h, cuf1=\E[C, 
   cuu1=\E[A, dch1=\E[P, dl1=\E[M, smacs=^N, blink=\E[5m, 
   smir=\E[4h, rev=\E[7m, smso=\E[7m, smul=\E[4m, 
   rmacs=^O, sgr0=\E[m, rmir=\E[4l, rmso=\E[m, rmul=\E[m, 
   is2=\E[H\E[2J, il1=\E[L, kbs=^H, kcud1=\EOB, kf1=\EOP, 
   kf2=\EOQ, kf3=\EOR, kf4=\EOS, kcub1=\EOD, kcuf1=\EOC, 
   kcuu1=\EOA, rmkx=\E>, smkx=\E=, lf1=PF1, lf2=PF2, 
   lf3=PF3, lf4=PF4, nel=^J, dl=\E[%p1%dM, 
   cud=\E[%p1%dB, il=\E[%p1%dL, cub=\E[%p1%dD, 
   cuf=\E[%p1%dC, cuu=\E[%p1%dA, 
   rs2=\E>\E[?3l\E[?4l\E[?5l\E[?7h\E[?8h, rc=\E8, sc=\E7, 
   ind=^J, ri=\EM, 
   sgr=\E[%?%p1%t;7%;%?%p2%t;4%;%?%p3%t;7%;%?%p4%t;5%;%?%p6%t;1%;m%?%p9%t^N%e^O%;, 
   hts=\EH, 

My "laundry list" said that I needed to make the Function, Home, PageUp*/*PageDown, and Tab keys work properly. Oh, and the NumericKeypad too.

Okay. So the NumericKeypad, Tab and PageUp / PageDown keys I solved by configuring PuTTY,. There might be a way to do it with the terminfo file, and if someone wants to add that here that would be great!

The function keys

Take a look at this excerpt from the terminfo file:

   kf1=\EOP, 
   kf2=\EOQ, kf3=\EOR, kf4=\EOS, kcub1=\EOD, kcuf1=\EOC, 
   kcuu1=\EOA, rmkx=\E>, smkx=\E=, lf1=PF1, lf2=PF2, 

basically all of the kf1, kf2, etc... are mapping key presses to the function keys.

But then lf1, lf2, etc... are mapping what key event the i^th function key is sending. In the original terminfo file, (as above), F1 sends PF1, F2 sends PF2, F3 sends PF3, and F4 sends PF4.

(NOTE: that's 'Lf-one', Lf-two (just wanted to make sure that people didn't get confused by fonts that make 'l' look the same as '1'.)

Because F1 sends PF1, F2 sends PF2, etc... that's why the first 4 function keys didn't seem to work -- because whenever we pressed one, sas612 didn't get a "Function key #i was pressed" key event.

As it turns out, you only have to specify lf1, lf2,... if you want to change the value of F1, etc... I put them in down below, but they're really unnecessary.

What's my keypress sending?

So you press a key on your keyboard (say F1), which sends a code "XXXXXX" to your computer, which then sends the keycode to the remote server that interprets it with the vt220 terminfo file.

We need to make sure that they keycode in the terminfo file for F1 matches what keycode is generated when we press 'F1' on our keyboard.

How?

Connect to your server (say, cascade), and run keypad, an application that sas has for grabbing keypress events. Keypad is located here: sas612/utilities/bin/keypad

Here's an example:

qubit-cascade:~/terminfo> /appls1/sas612/utilities/bin/keypad

WARNING: addendum file not found for this terminal.

TERM=vt220   TERMINFO=/appls1/sas612/terminfo/  TERMINFOADD=/usr/lib/terminfo

This program displays the characters the terminal sends to the host 
computer when a key is depressed.

Please press a key (q to exit) ....
\EOP
\EOQ
\EOR
\EOS
\E[15~
\E[17~
\E[18~
\E[19~
\E[20~
\E[21~

Those characters are the first 10 function keys, from a vt220 terminal, sshing to cascade from a sunray thin client.

If we do the same test on a windows machine, we get a similar result, but interestingly enough the keycodes we get from the 'keypad' program are not necessarily right for sas612. (anyone want to chime in and explain why?)

Basically the way we fix this is to run sas612, and actually press F1, F2, etc... and see what is displayed on the screen. If I remember correctly, I got something close to E[11~, E[~12, ...

I realized (through trial and error) that we need to escape the whole character, because it's really sending an 'escape sequence', so the final values for the function keys are:

  kf1=\E[11~, kf2=\E[12~, kf3=\E[13~, kf4=\E[14~, kf5=\E[15~,
   kf6=\E[17~, kf7=\E[18~, kf8=\E[19~, kf9=\E[20~, kf10=\E[21~,

The Home key

Okay, so we have to deal with the Home key. I was a little confused at first, because there's both the khome and home key presses in vt220-nam, but I figured out with the keypad program and sas612 that we wanted:

    home=\E[H
  

Compile the terminfo file

After our changes to the terminfo file, we need to compile the file using tic (so it's back in the binary form that we had before we used untic on it).

Move to the directory containing vt220-nam, and make sure that the TERMINFO environment variable is set to your local terminfo directory (probably _~/terminfo).

Run the command tic vt220-nam.term, and you should find that a file 'vt220-nam' in a directory 'v' has appeared inside your local terminfo directory.

Finally! running sas612!

Okay, we have just one last thing to do: run sas612 and tell it to use the vt220 terminfo file that we hacked to work on a windows machine with PuTTY.

Here's the command:

 sas612 -fsdevice ascii.vt220-nam

And that should be that! Enjoy sas612!

A few little caveats:

• Make sure that all of the environment variables are set properly. TERMINFO must point to your local TERMINFO folder or you'll be really mystified why the function keys are still broken.. :)
• other environment variables are TERMINFOADD and TERM. TERM should be 'vt220' here and TERMINFOADD can be (optionally) set to be !SASROOT/terminfo. I don't think that you need to set TERMINFOADD (please correct me if this is false!)
• make sure that your DISPLAY variable is not set, or you'll have a dickens of a time trying to get command-line sas612. If you're using tcsh as your shell, you can use the command unsetenv DISPLAY

What does your terminfo file look like?

Here's the full terminfo file, complete with comments and some unnecessary junk about the numeric keypad. It's not in the smallest form possible, but hopefully it is easier to understand the different parts when it is laid out like this.

#
vt200-nam|vt220-nam|vt230-nam|vt240-nam|vt200 series in VT200 mode/7 bit control with no am or am2,
   xon, 
   cols#80, it#8, lines#24, vt#3, 
   bel=^G, cr=^M, csr=\E[%i%p1%d;%p2%dr, tbc=\E[3g, 
   clear=\E[H\E[2J, el=\E[K, ed=\E[J, 
   cup=\E[%i%p1%d;%p2%dH, cud1=\E[B, home=\E[H, 
   civis=\E[?25l, cub1=\E[D, cnorm=\E[?25h, cuf1=\E[C, 
   cuu1=\E[A, dch1=\E[P, dl1=\E[M, smacs=^N, blink=\E[5m, 
   smir=\E[4h, invis=\E[7m, smso=\E[7m, smul=\E[4m, 
   rmacs=^O, sgr0=\E[m, rmir=\E[4l, rmso=\E[m, rmul=\E[m, 
   is2=\E[H\E[2J, il1=\E[L, kbs=^H, kcud1=\EOB,

# trying to get 'home' key to work
   khome=\E[H,

# trying to get NumLock to work
# kb2=5, ka3=\E[5~,

# put in the correct values to send for keypress events (~qubit)
# (kf value determines the escape sequence to be generated)
   kf1=\E[11~, kf2=\E[12~, kf3=\E[13~, kf4=\E[14~, kf5=\E[15~,
   kf6=\E[17~, kf7=\E[18~, kf8=\E[19~, kf9=\E[20~, kf10=\E[21~,
   kcub1=\EOD, kcuf1=\EOC, 
   kcuu1=\EOA, rmkx=\E>, smkx=\E=,

# make sure that we have a mapping defined for all 10 function keys (~qubit)
# (actually, we could just leave these out)
# (lf value sets what will show up in the KEYS menu in sas program)
   lf1=F1, lf2=F2, lf3=F3, lf4=F4, lf5=F5, lf6=F6, 
   lf7=F7, lf8=F8, lf9=F9, lf10=F10, 

# Testing the numeric keypad values:

   nel=^J, dl=\E[%p1%dM, 
   cud=\E[%p1%dB, il=\E[%p1%dL, cub=\E[%p1%dD, 
   cuf=\E[%p1%dC, cuu=\E[%p1%dA, 
   rs2=\E>\E[?3l\E[?4l\E[?5l\E[?7h\E[?8h, rc=\E8, sc=\E7, 
   ind=^J, ri=\EM, 
   sgr=\E[%?%p1%t;7%;%?%p2%t;4%;%?%p3%t;7%;%?%p4%t;5%;%?%p6%t;1%;m%?%p9%t^N%e^O%;, 
   hts=\EH, 

PuTTY...

Here's how to modify PuTTY for command-line SAS.

RobinsonTryon - 25 Oct 2002