Quick Tutorial - Automated operation

Pretty much anything that you can do in Heavy Metal with a mouse and keyboard can also be done via the command line.  For example, to start up Heavy Metal, fetch and display a stock quote for IBM and then exit, you'd type:

perl heavymetal.pl --stocksym IBM --quote --batchmode 1

In the above command line, there are three distinct commands:

1. "--stocksym IBM" - set current stock symbol to IBM
2. "--quote" - fetch quote for current stock symbol
3. "--batchmode 1" - Turn batch_mode on, which means the program exits when all commands have completed.

The command-line syntax in general has you first set up variables (such as the current stock symbol), and then execute commands that operate on them.  This is admittedly a bit awkward, but I'm lazy and it was easy to do it this way.  Besides, you're not really going to be typing this stuff directly on the command line.  The real purpose of this mode is to set up batch files with lists of commands to perform at specific times or intervals.  To support this, we add a new command-line option:

--file <fname>

To duplicate the previous example, create a normal text file with the following lines, and call it "batch.txt":

	--stocksym IBM
	--quote
	--batchmode 1

Then, do:

perl heavymetal.pl --file batch.txt

This will result in exactly the same actions as the first version.

Now, in this example, we used "--batchmode 1" to signal Heavy Metal to exit when the commands have been carried out.  For Linux users, this will be the typical usage.  For example, suppose you wanted to print out daily weather reports.  You'd create a batch file, "dailyweather.txt",  that looked something like:

	--ftpfile ftp://weather.noaa.gov/data/forecasts/ca/sanjose.txt
	--ftp
	--batchmode 1

and then create a crontab entry to have "perl heavymetal.pl --file dailyweather.txt" executed each morning at 7:00.

Windows, unfortunately, doesn't come standard with a nice scheduling agent like cron - though you can easily find similar utilities on the net.  If you don't want to do that, Heavy Metal comes with a simple repeat feature that may get you by.

Instead of using "--batchmode 1", instead you'll use "--repeat".  This option collects all of the command-line options prior to it and repeats them indefinately - with an optional sleep period in between.

For example, suppose you wanted to print out a stock quote every 5 minutes and 30 seconds.  Create a file named "ticker.txt" composed of the following lines:

	--stocksym TMTA
	--quote
	--sleepminutes 5
	--sleepseconds 30

Then, invoke Heavy Metal as follows:

perl heavymetal.pl --file ticker.txt --repeat

Heavy Metal will fetch the TMTA quote, sleep for 5 minutes and 30 seconds, and then start all over again.  Note that when Heavy Metal goes to sleep it will automatically minimize it's window and then restore it upon rewakening.

There is an important restriction on the use of "--repeat".  It must appear on the command line, and must be the last thing on the command line.  Don't put it into the file.

To get a full and current list, do:

perl heavymetal.pl --usage

Note that the options are generally broken down into two groups - variables to set, and actions to perform.

Variable-setting options      --name <value>

	--port - Set serial port.  Example, --port COM1:
	--divisor - Set UART baud rate divisor.
	--code - Set code to use (USTTY, ITA2, M20TTS, ASCII) for loop device
	--wordsize - Set UART word size
	--stopbits - Set UART stop bits
	--batchmode - If set to 1, exit when all commands complete.
	--remotemode - If set to 1, don't use modal dialog boxes on error and warning messages.  This is useful when operating the program from a TTY keyboard.
	--localecho - If set to 1, echo keyboard input to computer display.
	--unshift - If set to 1, HeavyMetal will automatically shift to <ltrs> on space.
	--lclock - Lowercase lock.
	--escapes - If set to 0, this will disable the .,.NAME escapes
	--upshift - When converting from ASCII to Baudot, convert lowercase ASCII to upper-case Baudot.
	--popserver - The name of your incoming mail server.
	--emailacct - The name of your email account
	--emailpasswd - Your email password
	--smtpserver - The name of your outgoing mail server
	--emailto - Who's going to get your email message
	--emailfrom - Your email address
	--emailsubject - Subject line for your email
	--emailmessage - Body of your email
	--sleepminutes - How many minutes to sleep on --sleep or --repeat
	--sleepseconds - How many seconds to sleep on --sleep or --repeat
	--hostcmd - Command to execute on host computer
	--ftpfile - Full path of file to fetch using --ftp
	--telnethost - Name to computer to telnet to
	--telnetuser - User account to login to via telnet
	--telnetpasswd - Password for telnet user
	--telnetcmd - Command to execute on telnet target computer
	--stocksym - Stock symbol to use for --quote and --fullquote
	--x10_house - House code for your X10 tty controller
	--x10_device - Device code for your X10 tty controller

Command options

	--telnet - Expects --telnethost, --telnetuser, --telnetpasswd & --telnetcmd to have previously been set.  Will telnet to another computer, execute one command and display the output.
	--albany - Displays a weather report for Albany, NY.  This, and --sanjose, are there as examples and you can edit heavymetal.pl to change them to your favorite locations.
	--sanjose - See above.
	--greenkeys - Fetch and print out Greenkeys messages.  Expects --popserver, --emailacct and --emailpasswd to have been previously set.
	--headers - Similar to --greenkeys, only prints out all email headers.
	--allmail - Similar to --headers, but prints out email bodies as well as headers.
	--quote - Print stock quote.  Expect --stocksym to have prevsiously been set.
	--fullquote - Similar to --quote, but gives more info.
	--portfolio - Displays a sample stock portfolio.  To change to your own portfolio, open heavymetal.pl in a text editor, search for "my @portfolio" and add/replace your own ticker symbols.
	--ftp - Fetch file using FTP.  Expects --ftpfile to have been previously set.
	--sleep - Go to sleep for --sleepminutes plus --sleepseconds.
	--qbf - Do the "Quick Brown Fox" test message.
	--ryry - Do the "RYRYRY" test message.
	--raw5 - Do a test printout of all 5-bit codes.
	--raw6 - Do a test printout of all 6-bit codes.
	--hostexec - Execute command on host computer.  Expects --hostcmd to have been previously set.
	--x10_on - Send "on" message to X10 device defined by --x10_house & --x10_device.
	--x10_off - Send "off" message to X10 device defined by --x10_house & --x10_device.
	--newswire_summary - Print out most recent AP top stories summary
	--check_newswire - Print all new AP stories and summaries since last time you checked.
	--repeat - Repeat all command-line commands up to the --repeat command.
	--usage - Display usage message.