terminal emulators

[Brian K. White]

I've been working on our modified version of PuTTY and have it to the 
point where it's useful enough to share outside of Aljex's own 
controlled environment.

The source is here:
http://install.aljex.com/AljexClient/Aljex_Client_SRC_PUB_7.5.1.007.7z

And the compiled binaries installer is here:
http://install.aljex.com/AljexClient/Install%20Aljex%20Client%207.5.1.0007.exe



PuTTY is a completely open source terminal emulator whose major 
downfalls for our kisn of usage I have been slowly addressing, at least 
to the point where it's good enough for us.

Things PuTTY lacked that made it not a great choice for our (filepro and 
other custom application developers/supporters/resellers) kids of 
usages, which I have added to my hacked PuTTY over the last few years.

* Save session settings in local files instead of the windows registry. 
Swiped & modified from PortaPuTTY

* Recognize and auto-launch those config files the way FacetWin does for 
.fwt files, based on both mime-type and file extension (means it works 
in firefox not just internet explorer, even works in Chrome as far as 
Chrome ever works with ANY external helper app, meaning it works in 
Chrome but requires one extra click). Files are named *.at and there is 
a start-menu shortcut to where they are normally created and read, so 
you can easily find them and drag them to your desktop, usb key, email 
etc...

* Run-program escape sequence.

* Support both background/hidden and foreground show mode for 
run-program. (ie: run the included twain scan & upload util in a hidden 
window, or launch a web site in the foreground normally. In either case, 
it runs in a new thread and does not block the parent putty process.

* Passthrough print flush timer. It means you can use fp's PFPT option 
and not get a zillion pages with one record printed on each. passthrough 
print only tells Windows "ok this job's done" after 5 seconds have 
elapsed since the last Printer-Off sequence was received.

* Auto detect default windows printer for passthrough print. It's an 
option, you can specify printing disabled, auto, or any specific printer 
in the session config. It means you can put a static config file on your 
web site that works for the majority of your users out of the box, first 
click.

* NSIS installer generator script and a readme of questionable value to 
anyone but me, describing how to set up a working development and build 
environment completely for free to take this and go further with it.

* Other associated utils bundled in:

* aca.exe - basically just a renamed chp.exe, a tiny gpl app called 
Create Hidden Process. This is used to run the scan & upload app in the 
background from a registry entry, without needing any terminal emulator 
or run-program command. It means you can put a scan button right on a 
web page. It requires a special cgi on the server to interoperate with 
the scan & upload util on the pc and I haven't included that in the 
bundle yet but the scan & upload util is really just a 4-line .cmd (aka 
.bat) file that glues together the scanner util and wget.exe to do the 
upload. You can take that and make your own scheme however you want.

* wget.exe - a stripped down build of gnu wget 1.11.4. Basically it just 
lacks SSL because I wanted the binary as small and light as possible and 
WE don't happen to require ssl yet. wget binaries for windows are 
available anywhere though and you can get a fully loaded one any where & 
any time you want. Or Curl.

* ts.exe - Basically a 10 line wrapper for TwainSave.DLL from Dynarythmic.
This one is the only sticky part at the moment. The source for ts.exe is 
included, it's only a few lines, but it's just a wrapper for a dll that 
does all the work. I can't redistribute the dll except as part of my 
app, and I can't distribute my unlock key for the dll except compiled 
into an executable. So, the binary package installer includes a fully 
functional ts.exe and twainsave.dll which I may distribute all I want 
and sell for as much or as little as I want, and I choose to distribute 
it free of charge since I only paid a single one-time purchase price of 
$399.00 for it years ago. But you all may NOT RE-distribute it or sell 
it, maybe not even USE it commercially, but you may USE it yourselves 
all you want because I CAN distribute it to my users as part of my app 
without restriction or royalties.

But as with aca.exe and wget.exe, this is not particularly critical to 
the overall Terminal-emulator-with-scanning package.
Because by now there are many other more or less equivalent options you 
can find to replace this util if you don't think a one-time $399 to 
dynarythmic for life is a good deal. You don't need to use exactly what 
I use for myself. Several alternatives are cheap, some are free but only 
free as in beer, no source.

http://www.filebuzz.com/findsoftware/Twain_Scanner_Gpl/freeware-1.html

The makers of the dll I use (dynarythmic twainsave) also offer a 
twainsave.exe which is licensed individually and they have a free un 
hobbled 30 day demo to try-before-buy. (but you could just use the 
binary from my installer for that even better and no time limit)

Actually there IS even completely gpl open source twain code out there 
in the form of the TheGimp and other gnu apps that have been ported to 
windows and have "get from twain" in their file menus. But it would be a 
fair project to take the huge source for TheGimp or OpenOffice (now 
LibreOffice) and extract out just the twain and image file writing parts 
to make a nice little non-interactive util. Or better yet, this is all 
open source code, instead of using a command line util, use the library 
functions directly within putty! Same goes for the http uploading to the 
server!

But the code IS out there to do everything needed and it's freely 
available and OK to mine and use in this way. And once a completely 
unencumbered version of ts.exe or twainsave.exe or scancmd50.exe or 
about a dozen other closed source utils exists, it doesn't matter even 
if it's skeletal at first, it only gets better over time like a ratchet 
after that. Since anyone who wants can satify their own particular itch 
and fix whatever annoyance they happen to want fixed, and after a whike 
most actual useful wishes get met and mos actual problems get fixed. ust 
like I did with PuTTY itself and many others have done with countless 
other things. We are all swimming in the proof of this theory such that 
it's not a theory but an observed fact.

* tsu.cmd - Just a tiny batch file that runs ts.exe, and then runs 
wget.exe to send the scanned images to the server via http-post. (few 
firewall issues even in fairly secure businesses since no ftp, no ssh, 
just http) It's not too useful except as an example since you don't have 
the cgi I have on my server which this is uploading to.

The way I use it is I pass it two command line arguments. %1 is the host 
to send to, and %2 is a string of encrypted junk the the server created, 
and only the same server knows how to decrypt.

A cgi provides a "scan" button on a web page and constructs a special 
query string and special URL type that the installer of my package 
registers in Windows. (as:,address,encrypted_metadata) It loads this URL 
with it's own hostname in plain text and some session metadata 
encrypted. The browser sees this "as:" URL and does what the registry 
says, which is to run tsu.cmd. tsu.cmd throws away the 'as:', remembers 
the address and the encrypted junk, runs the scanner, twainsave.dll 
automatically selects the document feeder or flatbed whichever is 
available and/or has paper loaded, generates a single multi-page pdf, 
wget.exe sends it back to the same cgi on the server via http-post, the 
cgi attempts to decrypt the query string, if it succeeds decrypting, 
then it knows from the decrypted data what to do with the uploaded file, 
and does so. If it fails to decrypt, it rejects the transaction and the 
upload is never even accepted and the cgi quits without doing anything. 
The http-post is just the bare pdf file that ts.exe generated. no base64 
encoding, no mime-formatting, DEAD SIMPLE and FAST. Nothing like perl or 
php or even small special executables needed on the PC to pack up a 
normal mime formatted http-post.
The cgi gets the encrypted metadata via query_string.

Again, since it's just a batch file, and since wget.exe is open source, 
and so are even more versatile things like curl which has an actual 
all-singing all-dancing curl library, this could all be built right in 
to putty to make it real slick and efficient.

Part of the reason I keep things in stand-alone executables is so that 
the same stuff can be used the same way from FacetWin or Anzio or AniTa 
or TUNEMU or others, or directly from web pages via registry entries 
with no terminal emulator at all.

* AljexClient.nsi - SWEET NullSoft Installer script that manages windows 
registry entries for the special TwainScan URL, version and size strings 
for add/remove programs, start menu shortcuts, detecting and 
uninstalling previous versions during install, detecting and preventing 
mutiple instances of the installer from running at the same time, exept 
for allowing an uninstaller to run while the installer waits for it.. 
NSIS is again, totally free open source suff so it will essentially 
always be available for anyone. no risk of a lost serial number or a 
business going away or changing the deal. I've been improving it for the 
last year and it's pretty cool now.

* AljexClient.workspace - Code::Blocks workspace file that includes 
seperate project files for each of the *.exe's above. It's a completely 
free open source IDE for editing and compiling the source. Sine its free 
and open source It too will essentially always be available for anyone 
any time.

I currently have that workspace file configured to use MSVC++Express 
2010, which is free, but only free as in beer. Not to worry! I have 
compiled _everything_ using the completely free open source MinGW gcc 
compiler environment also! I don't generally use that, so it may not 
build 100% perfectly out of the box at any given time, but the tweaks to 
get it to build are usually no problem. So, this stuff does NOT depend 
on the Microsoft compiler or Microsoft's continued good graces. I have 
also had every thing working completely from Makefiles in MinGW, so no 
real dependency on Code::Blocks either, although that's free and open 
source so it's not a problem. But again I don't generally use those so 
at any given time they may need a little tweaking. I had everything 
working using only gcc and Makefiles from Makefiles a few versions ago 
on a different laptop. Unfortunately setting up ANY build environment, 
whether it's MinGW or Code::Blocks, using gcc or msvc or any other 
compiler is somewhat of a tedious project and comes out a little 
different every time. Currently I'm using MSVC++Express 2010 and I had 
to fix up several environment settings in Code::Blocks by hand before it 
would work. And it took a little while to get familiar with how to even 
USE code::blocks at first, but it sure is convenient to use once you've 
gotten past that. By "work" I don't just mean compile & run, but the 
resulting binaries have no ball-&-chain special dependencies. I had it 
all woring in Cygwin too, but Cygwin no longer supports a -m-no-cygwin 
compiler flag, and so most (all?) executables require cygwil.dll, which 
is a special sort of dll that you must install in a shared central way. 
You can't just include it in your package directory. It basically means 
to give someone a hello-world.exe, they'd have to install at least a 
minimal cygwin install, which is a completely unnecessary pain in the 
neck. So, no gygwin needed, no .NET needed. Just basic core windows libs 
that everyone has on at least win2K and above. Certainly XP and above. 
(Sorry all you Win95 users ;)


Ok so anywas,  After installing that binary installer, immediately 
after, no reboot or anything, just open up a start->run prompt and type:

at:hostname-or-ip-address

as in, if you have a unix box at 192.168.1.100, then do
at:192.168.1.100

Boom, immediate preconfigured scoansi ssh putty session login to that 
box assuming it's running sshd.

now login

now click the the icon in the top-left corner, change settings, go to 
terminal, put the printer on [Auto], go to ssh->data, enter a name & 
password, got to sessions, make up a name and hit save.

Go to start menu, all programs, AljexClient, sessions.
See the actual config file containing the settings you just saved.
Right-click and drag it out to your desktop.
Click on it.
Boom you're n your unix box. (assuming your /etc/ssh/sshd_config has 
"PasswordAuthentication yes" in it)

The password only works for ssh and only for that one auth type in ssh, 
but with some more work it could be added to all the other protocols. It 
means some hinky stuff to detect the login prompt from the screen 
instead of the nice neat way shh provides, but it's doable. Or, just use 
ssh. Also the ancryption for the password in the config file is kind of 
pointless at the moment. The code to decrypt it is right here perfectly 
open. And when you load a config file in this putty, you can see the 
password in the password field in the config dialog screen. That feature 
was mandated from on-high, you don't have to use it, or, you don't have 
to use it _as-is_ but can improve upon it.

Unfortunately, because of a kind of dumb internal Aljex policy, the 
built-in defaults for this putty.exe are all set for SCO ANSI emulation.
It's great if you have sco boxes running ssh because the default 
protocol is also ssh. But if you're on linux, you actually need to go 
out of your way to set various settings for linux emulation.
Then again, you only have to do them once. Once you have a 
well-configured session, you can copy it for new sessions, or you can 
even save it as "[Default Settings]" and they will be your new defaults 
on that PC from then on.

There is yet more stuff to describe to fill in some blanks but I have to 
get home for tonight. I'll post a sample saved session file that you can 
just click on, or save to your desktop and then click on, make setting 
changes mid-session and have them saved back to the cfg file that you 
clicked on wherever it is (not just to a special putty saved sessions 
folder which _also_ works) and explain some of the things that make this 
putty killer and explain that scanning process a little more.
For instance, you can generate a *.at config file dynamically from a 
.php or cgi, which reads it's data from a simple text file or even right 
from filepro, and feeds it to a web browser with the right Content-Type: 
header, So you can have a login button on a web site that accepts the 
users name, uses the entered name to look up their personal settings, 
generates a putty (or facetwin) config file using those settings, 
prefilled with the users name just to eliminate an unnecessary step for 
the user, and feeds it back to the browser, which auto launches putty or 
facetwin as directed by the Content-Type: header. That's how the login 
button on www.aljex.com works now. Users who live on many different 
servers all can just go there, punch in their username, and they get 
logged in to the server they actually live on. No thinking involved! No 
Setup! Just www.aljex.com -> login. The .php behind that login button is 
only about a dozen lines.

How about, since we have the source and this would be easy, make the 
config-file reading code expect that the config file might contain a 
blob of html at the beginning. That way, when a virgin browser clicks a 
login button, and since they don't have this putty installed, instead of 
seeing the ugly and meaningless config file text, instead of seeing even 
an ugly block of comments with a link to the installer, as good as that 
actually IS, how about they get fully browser rendered nice looking html 
including the installer already starts downloading? All without 
requiring exotic and security-blocked steps in javascript to try to read 
registry settings or something else from the PC to see if they have the 
required client installed. The installer download link is right there in 
the config file itself and we just make it so the executable knows to 
ignore this html instead of treating it as a bad config file. And of 
course it's trivial to make the browser ignore all the config file data, 
just place it all within an html comment tag. Can't get any slicker than 
that...


Ideally I'd really like to get all of this up in a public git repo that 
anyone can download from and anyone who wants to can coordinate with 
others to do further work on it. Get a public wiki going so that 
documentation and reference can start accumulating, such as nailing down 
an absolutely reproducible recipe to set up the build environment to 
compile this stuff and get everything I figured out by trial & error 
documented explicitly so it's easily reproducible. Start finding and 
testing other twainsave utils besides the one I use so there is some 
sort of working thing in there that's actually legal to not only use but 
to re-distribute, even if it's not as good or more limited than the 
dynarythmic one. Maybe some good reference config files for different 
systems.

  Maybe some correlating documentation about the server setup wrt 
termcap/terminfo/stty /etc/profile.local tricks. Like this:
   [[ "$MYTERM" ]] || read -s -t 2 -p $'\005' MYTERM
A bash-specific trick to read the terminal answer-back string (which you 
can make say whatever you want in the configurable in the session 
settings) So, if you say, telnet or ssh from one machine, to another, to 
another, or use "su" or are connecting via serial console but using 
putty to telnet or ssh to the serial console server, in all of thise 
cases you lose any special variables your direct putty session may have 
set up to tell the server that you are using "my special term" and can 
therefor use "my special term's features" (could be facetwin or anzio or 
anything not just this putty) But with this neat little thing it 
/etc/profile.local , if $MYTERM is empty at login, it well send the 
terminal query command to the terminal, and wait a max of 2 seconds for 
a respons (which it usually gets instantaneously but could be delyed due 
to mnetwork congestion or pc decrepitude) and fills MYTERM with the 
answer. If you put a trailing CR in the anwer-back field in the session 
settings, it makes this work very fast and invisibly.
So even a serial login can detect that you are using Foo-term and can 
use special Foo-term commands.

Some wiki is a better place to document that than this email ;)


It's damned useful now but it's also just the beginning.

How about special filepro support built right in? I don't know what it 
would do but since the source is open anything is possible. Maybe 
something like what ReFace or MixViews does where they recognize certain 
screen elements and react to them?

Maybe it could just be as simple as building a whole pile of more ansi 
OSC commands that you issue from filepro any time anywhere with show raw 
? (essentially like Anzio's extensive client control codes, you can do 
a_lot_ of wizbang stuff in Anzio)

How about built-in ghostscript & ghostpdl to interpret hplaser output 
and send it directly to windows GDI using code clipped from TheGimp 
again, to print on any windows supported printer? It won't be nearly as 
good or as feature rich as PrintWizard but it'll do a lot more than the 
NOTHING that most terminal emulators passthrough print does now and it's 
utterly free free free just copy it all you want, just use the hell out 
of it all you want.

There are so many things that could be done, and it's of course too much 
to contemplate all at once, but that's a dumb reason for never even 
starting on that road however small the first baby steps. This little 
package I have now is really really handy now. It took me a few years 
because I actually pretty much suck at C, and I only had little bits of 
time here & there to work on it, and much of that effort was actually 
wasted along the way where I paid guys to do some things and they never 
finished it or never gave me the source or once I saw the source I saw 
that I HATED what they did and refused to use it...
etc... But well, now it's only a couple years later and I have it, and 
it's GREAT (the download is only Dum Dum DUMMMM ONE MEG!). And, I'm 
actually finally starting to be able to make more and more fancy changes 
as the need arises.

Still TODO: well many things, a few are:
* get the Halibut stuff from the putty site and write up docmentation 
for the non-standard features. Or write them up in ANY form. I haven't 
even told you what the run-program escape sequence is so what good is 
it? In ansi/ecma-48/vtxx terminal capability nomenclature its:

"OSC ### SP string ST"

Where:

    OSC = Operating System Command, which is "esc]".
(there are 8-bit single-byte versions of many ansi codes, but PuTTY 
ignores most of these, including 0x9D, the single-byte 8-bit version of 
"esc]")

    ### = 200 for a regular window
    ### = 201 for a hidden window

    SP = a single space character
    string = string to execute on the client, can be an exe, a 
registered document type, a url, or anything else the client OS will 
execute.

    ST = string terminator, which is either a single byte 0x07 or a 
2-byte ESC+\. Technically the 0x07 is the 8-bit ST and the esc\ is the 
7-bit, and generally PuTTY ignores the 8-bit codes (I guess because it 
would complicate drawing those same characters glyphs?) but esc\ would 
be an amazing pain in the ass to have to deal with all the time since 
"\" is used by both the unix shell AND many filepro string manipulation 
commands, so it's nice that PuTTY DOES honor \007 as ST, and will 
terminate an OSC command that was started with esc].


So some examples:

OSC:
bash, using hex notation: echo -en "\x1B]"
bash, using octal notation: echo -en "\033]"
filepro, using chr("decimal"): show raw chr("27") & chr("93")

ST:
bash, using hex notation: echo -en "\x07"
bash, using octal notation: echo -en "\007"
filepro, using chr("decimal"): showraw chr("7")


Complete sample command:

You want to run "http://www.google.com"
You want it to pop up normally in the forground.

winstart:
#!/bin/bash
echo -en "\033]200 ${@}\007"

run:
winstart http://www.google.com

Or from fp (I don't actually use this method and haven't tried it any 
time recently, untested):

c = "http://www.google.com"
show raw chr("27") & "]200 " & c & chr("7")



...blah I really have to get home my gf is going to kill me but I just 
wanted to get this out finally. I'd mentioned it a couple years ago and 
never actually posted the code.

-- 
bkw