Enter the following script and save it under the name cat_here:

# Uses a here file with the cat command.

cat <<HERE
This is a notice that the official company dress code policy
has changed. All employees are required to follow the new
policy.

We don't want to make a big deal about the policy, which has
been in effect since last September, but it appears that some
people have not been following the new guidelines. Because of
this, we felt it appropriate to introduce the new guidelines
for all employees.

The new policy is available on the company InfoCENTRE. You
will need level 3 security access to view the new company dress
code  policy. All employees should view this policy TODAY. Be
careful, though, not to overload the company InfoCENTRE server.
If you have trouble logging in to the secure company InfoCENTRE
site, please call the 800 number for the internal security
hotline. This number is available on the secure company InfoCENTRE.

You won't be sent home for violating the company dress code policy,
but you will need to work out any issues with your supervisor.
HERE

# Here file has ended, so the shell expects commands.

echo "Please follow this policy immediately."

When you run the cat_here script, you see output like the following:

$ sh cat_here
This is a notice that the official company dress code policy
has changed. All employees are required to follow the new
policy.

We don't want to make a big deal about the policy, which has
been in effect since last September, but it appears that some
people have not been following the new guidelines. Because of
this, we felt it appropriate to introduce the new guidelines

for all employees.

The new policy is available on the company InfoCENTRE. You
will need level 3 security access to view the new company dress
code  policy. All employees should view this policy TODAY. Be
careful, though, not to overload the company InfoCENTRE server.
If you have trouble logging in to the secure company InfoCENTRE
site, please call the 800 number for the internal security
hotline. This number is available on the secure company InfoCENTRE.

You won't be sent home for violating the company dress code policy,
but you will need to work out any issues with your supervisor.
Please follow this policy immediately.

How It Works

The cat_here script outputs enough text to make it inconvenient to use the echo command for each line of text. Instead, the cat_here script passes a here file to the cat command, which outputs all the text. The echo command works best for single-line messages, whereas the cat command was designed to output the entire contents of a file. The script terminates the here file with the market text HERE.

After the marker HERE, the script continues. You can place any additional commands before and after the here file. In this example, the script calls the echo command after the here file ends.

Enter the following script and name the file tps_report1:

wall <<EndOfText
Please complete all TPS reports and have them
on my desk by EOB today.

Your cooperation in this matter helps the smooth
flow of our departmental structure.

-Dick
EndOfText

echo "Message sent"

When you run the tps_report1 script, you see the following output on the shell window you used to run the script:

$ sh tps_report1

Broadcast message from ericfj (Sat Oct 28 12:24:13 2006):

Please complete all TPS reports and have them
on my desk by EOB today.

Your cooperation in this matter helps the smooth
flow of our departmental structure.

-Dick
Message sent

All other users see just the message. For example:

Broadcast message from ericfj (Sat Oct 28 12:24:13 2006):

Please complete all TPS reports and have them
on my desk by EOB today.

Your cooperation in this matter helps the smooth
flow of our departmental structure.

-Dick

How It Works

The wall command, short for write (to) all (users), comes from the ancient times when users were logged in to plain ASCII terminals. In this example, wall is a handy command to call to test here files. In this more modern era, you can often use instant messaging, or IM, programs to communicate with logged-in users.

This example just sets up the here file; it does not customize the here file with variable values (the subject of the next Try It Out).

To customize a here file, you merely need to insert variables into the here file in the script. The following example shows this.

# Use of variables within a here file.

# If the user forgets to pass the command-line
# arguments, fill in defaults.

if [ $# -lt 1 ]
then
    date_required=today
else
    date_required=$1
fi

if [ $# -lt 2 ]
then
    pithy_statement="Action, urgency, excellence"
else
    pithy_statement=$2
fi




wall <<EndOfText
Please complete all TPS reports and have them
on my desk by EOB $date_required.

Your cooperation in this matter helps the smooth
flow of our departmental structure.

$pithy_statement!
-Dick
EndOfText

echo "Message sent"

Enter this script and save it under the file name tps_report2. When you run this script, you see output like the following:

$ sh tps_report2 Monday Onward

Broadcast message from ericfj (Sat Oct 28 12:45:35 2006):

Please complete all TPS reports and have them
on my desk by EOB Monday.

Your cooperation in this matter helps the smooth
flow of our departmental structure.

Onward!
-Dick
Message sent

How It Works

As before, this script passes the here file to the wall command to send a message to all users using shell windows or terminals who are logged into your system. In this case, however, the script places variables at strategic locations within the script.

To promote reuse, the date_required variable holds the day the TPS reports are due. With this, you can reuse the script for any time the reports are due. The pithy_statement variable holds a pithy statement to end the message.

Both variables set their values from the arguments passed on the command line. The first argument is used for the date_required variable and the second for the pithy_statement. Note that this script could have used the command-line positional variables $1 and $2 directly. Instead, the script checks for the existence of the positional variables. If not set, the script fills in reasonable defaults.

Enter the following script and name the file ftpget:

# Driving an interactive program, ftp.

# Validate number of arguments.
if [ $# -lt 2 ]
then
    echo "Error, usage is:"
    echo "ftpget hostname filename [directory]."
    exit −1
fi

hostname=$1
filename=$2

directory="."  # Default value

if [ $# -ge 3 ]
then
    directory=$3
fi


ftp <<EndOfSession
open $hostname




cd $directory
get $filename
quit

EndOfSession

echo "FTP session ended."

You also need to set up something called auto-login for the ftp command. See the online documentation for the ftp command for more information on this. The auto-login feature sets up the username and password for the FTP site you attempt to contact. The script needs this feature because the here document does not work well with the ftp command when the ftp command prompts the user for a username and password.

When you run this script (after setting up the ftp auto-login feature), you see minimal output like the following or an error if something goes wrong:

$ sh ftpget ftp.somehost.yow  index.html WWW
FTP session ended.

How It Works

The ftpget script is one of the trickiest scripts because of variations in the ftp command as well as how the ftp command prompts for your login to a remote system.

The basic mode of operation is that the ftpget script logs in to a remote site using the ftp command. The script then changes to a given directory and downloads the given file name. This seemingly simple task is fraught with error when using a here document because the remote server can output an error, which your script cannot handle. If the session runs well, however, you should see the file on the local system in the current directory.

The here file passes a number of ftp commands to the ftp program. The ftp program, designed for interactive use, supports a number of commands within the program itself. The ftpget script uses a here file to pass these commands to the ftp command, one at a time.

The ftpget script starts with the open command, to open an FTP session to the remote system. This is where the auto-login feature comes into play. When opening the session to the remote system, the ftp command reads in your username and password on the remote system from the .netrc file in your home directory. If the open fails, the script won't download the file.

The empty space in the here file sends new lines to the remote server because you cannot tell in advance how long it will take for the remote server to be ready for commands.

The script then issues a cd command to change directories on the remote system and the get command to download a file. The quit command ends the FTP session.

If you don't pass enough parameters to the ftpget script, you see an error message like the following:

$ sh ftpget
Error, usage is:
ftpget hostname filename [directory].

The ftpget script showed an example of how you can use here files to automate interactive programs. A more predictable interactive program is the vi text editor, introduced in Chapter 2.

The following script runs a session with the vi text editor:

filename=test.txt

vi $filename <<EndOfCommands
i
This file was created automatically from
a shell script
^[
ZZ
EndOfCommands

Save this script under the name run_vi. You can then run the script:

$ sh run_vi

If you run this script with vim acting as vi, then you will likely see output like the following:

$ sh run_vi
Vim: Warning: Input is not from a terminal

The file is still edited. The vim command includes more code for detecting whether the editor is run from a terminal. Vim can tell that it is being run from a script or program.

After running the script, you should see the following added to the file test.txt:

$ cat test.txt

This file was created automatically from
a shell script

If you run the script a second time, it appends to the file. For example:

$ sh run_vi
Vim: Warning: Input is not from a terminal
$ cat test.txt

This file was created automatically from
a shell script

This file was created automatically from
a shell script

How It Works

The run_vi script provides a file name to the vi command. It then uses a here file to pass text to the vi edit session. The i command places vi in insert mode. The next two lines of text are inserted, as is an extra newline (because the next command appears on a separate line). An Escape character pushes vi out of insert mode and back into command mode. The ZZ command saves the file and exits vi.

The ^[ text in the file must be an Escape character. Most text editors won't let you enter an Escape character into the document. One of the easiest ways to enter an Escape is to use vi. In vi, go into insert mode and then press Ctrl-V Ctrl-[, and you get an actual Escape character.

Enter the following script to see how to avoid variable substitution in here files. Save the script under the name here_no:

filename="test1"

cat <<'QuotedEndMarker'

With quotes around the here document marker,
you can include variable references such
as $HOME, $filename, and $USER.

QuotedEndMarker

When you run this script, you see output like the following:

$ sh here_no

With quotes around the here document marker,
you can include variable references such
as $HOME, $filename, and $USER.

How It Works

This script uses an ordinary here file, but it turns off the variable substitution. Otherwise, you would see the values of $HOME, $filename, and $USER in the output instead of the literal text.

All of this is done by the magic of enclosing the end marker, QuotedEndMarker, in quotes at the original reference. Do not enclose the marker in quotes at the end of the here file.