Scripting

Overview

As discussed in chapter 3, a Qshell script is a text file that contains commands that Qshell can interpret and execute. Because scripts are not compiled, but interpreted at run time, they might be compared to the OCL and REXX procedures that run on the iSeries.

You are probably accustomed to storing source code in source physical files. Qshell scripts may also be stored in source physical files, but they run faster and demand less system resources if they are stored in stream files in the root file system of the IFS.

In a production environment, Unix programmers and administrators typically store shell scripts in a /bin directory underneath a user 's home directory. You can follow that convention while learning to use Qshell and working through this book, but it's not necessary. All that matters is that you have a directory of your own.

A directory is like a source physical file, in that the directory can contain more than one instance of source code. A source physical file has members , while a directory has stream files . If you don't have your own directory and are not sure how to get one, see "Introducing the Stream-File Exercises" in chapter 3.

Naming a Script File

Although you can name a script file anything you want, it is probably a good idea to follow the conventions used in the Unix world. Unix script programmers typically begin with a base name . This may be followed by a period and a suffix to indicate the type of script. For example, a suffix of ksh indicates a Korn shell script.

The rules for naming files in the root system are very liberal . You may include blanks and punctuation marks in file names , but it is probably best not to do so. A good suffix for Qshell scripts is qsh, but that is by no means required.

The example scripts in this book often use the fictitious file name myscript.qsh . If you key some of the examples, you will probably want to use other names so you can keep more than one script on disk.

Running a Script File

To run a Qshell script, enter its name on the command line of an interactive shell session and press the Enter key. Qshell may might respond with error 001-0019:

Error found searching for command myscript.qsh. No such path or
 directory.

If you know that the file exists, the problem is likely that you do not have Execute permission or the PATH environment variable is not set correctly.

The PATH variable contains a list of directories that are to be searched for commands. To view the current setting of PATH, use the following command:

echo $PATH

Be sure to type the word PATH in uppercase letters , because Qshell variable names are case-sensitive.

Look for the name of the directory that contains your script. If your script is in the current directory, look for a leading colon, a trailing colon , two adjacent colons, or the current directory's name. Any of these indicates the presence of the current directory in the search path.

Every file has a set of permissions associated with it that tell who is allowed to read, write, and execute the file. Permissions are defined for the owner of the file, the group to which the owner belongs, and everybody else. Qshell scripts require Read and Execute permissions. (Permissions are discussed in detail in chapter 9.)

When you create an IFS file, you will probably have Read permission, but you may not have Execute permission. If not, you will have to grant yourself Execute permission in order to run the script.

Figure 4.1 shows how to determine and enable Execute permission within an interactive Qshell session. The - l option of the ls command displays a ten-character string that indicates the permissions. This string is in the first column of the output. The owner permissions are described by the second through fourth characters , which read rw - in this example. These characters indicate that the Read and Write attributes are enabled, but the Execute attribute is disabled. Notice the permissions after executing the chmod command. The hyphen in the fourth position has been replaced with an x . Now you can execute your script.

ls -l myscript.qsh


-rw------- 1 JSMITH 0 25 Sep 3 09:05 myscript.qsh


/home/JSMITH $


chmod u+x myscript.qsh


/home/JSMITH $


ls -l myscript.qsh


-rwx------ 1 JSMITH 0 25 Sep 3 09:05 myscript.qsh

Figure 4.1: Use this code as a pattern for enabling Execute permission for a script.

Comments

At this point, you should know how to create and revise stream files in your directory. You have only one thing left to learn: what to put in those stream files. That is what the rest of this book is all about.

Since every good program requires documentation, one of the first things you should learn is how to include comments in Qshell source code.

Comments begin with the # symbol and span the remainder of the line. The # symbol is referred to by various names , including " pound ," "hash," "sharp," and "number." Comments are ignored in Qshell scripts, as are blank lines.

A comment may occupy the entire line or the trailing portion only. Here are examples of both types of comments:

# If the -p option was specified, print the output.
shift $OPTIND-1 # shift out the options

The Magic Number

If you look at scripts developed for Unix systems, you will frequently see a special comment on the first line. This comment begins with the symbols # and ! (often pronounced " pound bang"), and is called the magic number . The purpose of the magic number is to tell Unix which interpreter to load to process the script.

The magic number is discussed in detail in chapter 12. For now, you can ignore it.

Executable Commands

You are probably aware that some CL commands are permitted in CL programs only, other CL commands are permitted to run interactively only, and still others may run in either environment. For example, the IF command is only allowed in CL programs, the GO command runs in interactive jobs only, and SBMJOB works in either environment.

Qshell commands are not restricted in that way. All Qshell commands may run in an interactive session or in a script (although it may not always make sense to enter a certain command in a certain environment).

If you enter a syntactically incomplete command in an interactive session, Qshell responds with the secondary prompt. You can continue to enter line after line of commands, until Qshell determines that execution is possible.

Special Scripts

When you begin a Qshell session, it automatically executes the following three script files, if they exist:

• The global profile file, /etc/profileThe system administrator uses this file to set system-wide options for all users.
• A file named .profileAfter running /etc/profile, Qshell looks in the user 's home directory for this profile, which is used for personal customization. (Yes, it begins with a period, and is pronounced "dot profile.") The .profile file is a good place to define environment variables , including the ENV environment variable. Use the DSPUSRPRF command to display your HOME directory. For example, DSPUSRPRF JSMITH.
• The file named in the ENV environment variableQshell looks to see if the ENV environment variable has a value. If so, and if that value is the name of an existing file, Qshell executes the file. One of the most common uses of ENV is to define aliases , which are short names for a command. (Aliases are discussed in detail in chapter 12.)

Qshell runs these script files in the order given here, and in the current process.

Your First Script

Before you proceed, be sure you know how to edit and run Qshell scripts. Figure 4.2 is a script you can enter and run for practice.

# Getting acquainted
print "Please enter your name."
read name
print "Hi, $name. Qshell rulz!"

print "What's your favorite programming language?"
read lang
if [ -z "$lang" ]
 then print "Maybe we can talk at a more convenient time."
 exit 1
fi

lang=$(print $lang tr '[:lower:]' '[:upper:]') # convert to caps
case $lang in
 *RPG*) print "Me too!";;
 COBOL*) print "How quaint!";;
 JAVA) print "At least you didn't say "C"";;
 C) print "You're a glutton for punishment!";;
 *) print "To each his own."
esac

Figure 4.2: Use this script for practice.

To enter and run the script, use the following process:

1. Sign on to an iSeries machine through a terminal or a 5250 emulation session.
2. If necessary, change to the directory where you are going to place the Qshell script.
3. At a CL command line, type qsh and press Enter to begin a Qshell session.
4. Since you cannot edit a file directly from Qshell, press the F21 key to get a CL command line.
5. Use EDTF to enter the Qshell script. If you are not sure how to use EDTF, see chapter 3.
6. After editing, press Enter from a blank line (or press F12) to close the command-line window and return to Qshell.
7. If necessary, use chmod to make the script executable.
8. Type the name of your script on the Qshell command line and press Enter to run it.

If you must edit the script, press F21 to get back to the CL command line. From there, you can use the F9 key to retrieve the previous EDTF command.

Continue running and editing the script in Figure 4.2 as needed, until you have no syntax errors and understand how the script works. Don't worry if you don't understand the syntax of the Qshell commands at this point. That's the purpose of the rest of the book.

Summary

A script is a text file that contains Qshell commands. Typing the file's name and pressing Enter runs all the commands in the script file. To execute a script, you must have Execute permission to the file.

A script may include comments, including the special comment known as the magic number , and executable commands. Unlike CL, Qshell does not restrict the execution of Qshell commands to either batch or interactive environments. Therefore, any Qshell command may be used in a script.

Three special scripts run when Qshell starts: /etc/profile, .profile, and the file named in the ENV environment variable.