Guild Companies, Inc.  
Midrange Programmer - How-To Advice & Free Code
OS/400 Edition
Volume 1, Number 5 - March 14, 2002

Getting Started with Qshell Scripts

by Ted Holt

A Qshell script is a text file of commands that Qshell can interpret and execute. A Qshell script is to the iSeries Integrated File System what a CL program is to the OS/400 library system, except that CL programs are compiled and Qshell scripts are not. Qshell is based on POSIX and X/Open standards and has many similarities to Unix shells, especially the Korn and Bourne shells. Much of what I have learned about writing Qshell scripts has come from studying Bourne shell scripts on the Web.

There is much to learn about Qshell and Qshell scripting, far more than I can cover in a single article. So instead of trying to cover it all, Iíll try to focus on some of the more useful features. In this article you will learn to create, modify, and execute scripts by building a Qshell script. You will also learn just a little about input and output, variables, and looping and decision structures. When you finish working through this article, you will not be a Unix guru, but you'll be on your way. I will try to cover these topics and others in more detail in future articles.

Getting Started

You need a place in the Integrated File System to place scripts. The Qshell manual says that scripts should be in a directory of the root file system. If you do not have an available directory, use the Make Directory (MD) command from an AS/400 command line to create one before you go any further. I will assume that your root directory is /home/smith.

Second, you need a way to edit scripts. If you have a PC and can map a drive to your Integrated File System directory, you can use a PC editor like Windows Notepad. Or you can FTP a script to the Integrated File System from your PC or another machine. Or you can use the Edit File (EDTF) command to edit from an interactive green-screen session. I will use EDTF in the examples in this article.

Now it's time to create a script. Use the Change Directory (CD) command to change to your work directory, if necessary. Now use EDTF to create a file called myfirstscript.

edtf 'myfirstscript'

If you don't know how to use EDTF, consult the help text. Since this is a new file, there is one blank line in the file. On that line, type the following:

echo "Running script ${0}"

Note that the third character from the end is a zero, not a letter O.

Press F2, then F3 to save the script and exit the editor. You're back to the command line. Type qsh and press Enter to start the Qshell.

When Qshell starts, you'll see four blank lines at the bottom of the display. These are the lines where you enter Qshell commands. Type myfirstscript and press Enter. At the top of the display, the system should respond with the message "Running script /home/smith/myfirstscript." The system lets you know that the script has ended by displaying a dollar sign ($). (At least it's a dollar sign on my system; I'm not sure about systems that use other national languages.)

If you got some other result, you need to fix the script. Press F21 to get a window with a AS/400 command line in it. Press F9 until the EDTF reappears, and press Enter. Fix the mistake, press F2 and F3 to return to the command line, press Enter to close the command line window, type myfirstscript, and press Enter. Repeat until the script works properly.

The echo command "prints." I put the word prints in quotation marks because the output never actually hits paper. In the Unix world, printing means displaying to the screen. This should not be a hard concept to grasp if you have ever used any version of Basic.

Notice the special symbols ${0}. Qshell takes this to mean the name of the file in which the script is stored. There are more special symbols, but you'll have to look at the Qshell reference to find out what they are.

Qshell has other I/O commands. Besides echo, there are two other output commands: print and printf. For input, there's read.

Press F21 to reopen the command line window, press F9 until the EDTF command pops up, and press Enter to edit the file. (From now on, I'll just say, "Edit the script file.") If it strikes you as odd that you can't invoke the editor directly from the Qshell command entry line, try to understand that Qshell is not an interactive program but a batch program that can interact with a terminal. EDTF cannot run from a batch program.

Tab to the entry area to the left of the echo command and type I3 to insert three lines. Fill in those three lines with the following:

echo "Enter one or more non-blank characters"
read vara 
ls *${vara}* 

Save the file (F2, then F3), close the command line window (Enter), and you're back in Qshell. Type myfirstscript (or press F9 to retrieve the previous invocation), and press Enter to run the script. When Qshell asks you to enter one or more non-blank characters, enter e and press Enter. If you have files with an "e" in their names, you will see them listed on the screen. If no files have an "e" in their names, you will see error message 001-2113. If you need to, put some files into your directory.

The read command puts whatever you type into a variable I chose to call vara. The expression ${vara} retrieves that value and passes it along to the List Directory Contents (ls) command.

Keep running myfirstscript, entering different values for vara, until you're satisfied that you know how it works.

Looping and Decision-Making

Now it's time to introduce you to Qshell's looping and decision-making structures. This will not be an exhaustive treatment, but it will get you started.

Edit the script file myfirstscript. Change it so that it looks like this:

echo "Running script ${0}"                   
while true; do                          
echo "Enter one or more non-blank characters"
read vara                                    
if test "${vara}" = ""; then break; fi       
ls *${vara}*                                 

Don't leave any blanks between the third and fourth quotation marks (") in the fifth line.

Run the script and fix errors as necessary. When you get it right, it should loop, asking you for input and giving you a directory listing in return, until you press Enter without typing in any input. If your loop gets out of hand, use option 2 of the System Request menu to break it.

Notice the semicolons (;) in lines 2 and 5. A semicolon can separate two commands in the same way that placing two commands on two different lines separates them. So the if sequence could also have been written this way:

if test "${vara}" = ""   
   then break            

Notice also the equal sign (=) is used to compare two strings. To test for not-equal, use !=. To test for a numeric comparison, use the -eq, -lt, -gt, -ne, -ge, and -le operators.

How about that fi to end the if block. Qshell also has a case construct, which is terminated by esac. Isn't that cute? It was obviously designed by a propellerhead.

Your shell script includes a loop, controlled by a while command. While, of course, is a top-tested loop. Other looping structures are until (a bottom-tested loop) and for (which processes each item in a list). This script calls for a middle-tested loop, but Qshell has no such loop mechanism. (To its credit, Qshell has no go to command, either.) For that reason, I built a while loop that executes forever, and used the break command to terminate it.

I hope to cover looping and decision-making in greater detail in later articles.

Working with Data

You have seen two examples of the use of data in Qshell. The first was ${0}, which represents the name of the script. The other was a user-defined variable, which I had named vara. Let me introduce you to some other data values.

Edit myfirstscript and change the ls command so it looks like this:

ls ${1} *${vara}*

Leave at least one space before and at least one space after the ${1} expression. Run the script by typing myfirstscript and pressing Enter. It should run as it always has.

Run the script again, but this time type myfirstscript -l (that's a hyphen followed by a lowercase letter L, not a minus one) and press Enter. Be sure to leave at least one space before the hyphen. This time, you should see more information about each file that is listed. You have passed a positional parameter to your script.

The special symbol ${1} tells Qshell to substitute the first positional parameter. If you don't key a parameter when you run the script, the ls command looks like it always did:

ls *${vara}*

But if you key -l, Qshell executes the command this way:

ls -l *${vara}*

The -l causes Qshell to provide a long directory listing.

The curly braces are not always needed with positional parameters. That is, you can key $1 instead of ${1} in most cases. I always put them in because they seem to work in all cases.

Qshell also defines some variables you can use. Try these from a Qshell command line:

echo $PWD

There is a long list of these predefined variables in the Qshell reference.


I recommend you include meaningful comments in source code. In Qshell, a comment begins with what I call a pound sign (#). Others may know it as a hash mark, railroad tracks, or "an itty-bitty tic-tac-toe symbol." A comment occupies the rest of the line. A comment may occupy a line by itself, like this:

# If the file is a Java class, delete it.

Or a comment may follow executable code, like this:

cd $ORIGDIR  # return to original directory

Edit myfirstscript one more time. I want you to place a comment on the first line of the script. (If there's a way to insert a line before the first one, I haven't found it yet.) Here are two methods that might accomplish that:

1. Place an R to the left of the first line to repeat it. The first two lines will look alike. Type over the first one.

2. Type I to the left of the first line to insert a new line two. On the new line two, type the comment. Then place an M beside the first line and an A beside the second line to move the first line after the second line.

However you accomplish it, the new first line should have this on it:

# This is my first Qshell script and I'm proud of it.

Special Scripts

Before I wrap this up, let me tell you about some special script files. The first one is the global profile script. It must be named profile and reside in the /etc directory. When Qshell starts, it will run the system profile script. This file applies to all users.

Next, Qshell will look for a script called .profile in user's home directory. If it finds .profile, it executes the script. Each user should use this profile to customize for his own purposes.

Last, Qshell looks for an environment variable called ENV. Again, if it finds the environment variable, it runs the script named by the environment variable's value.

You can set the ENV environment variable in two ways. One is to use the Add Environment Variable (ADDENVVAR) CL command.


The other method is to set the environment variable in Qshell.

export ENV=/home/smith/tscript

After .profile finishes, tscript begins.

You Did It

Well, you've created and run a Qshell script. How does it feel? If you're confused, I don't blame you. This Unix stuff is weird to me, too, but I think it's worth learning. One reason I feel that way is that some of these Unix utilities come in handy when I'm working with source physical file members. The other is that Unix and Linux are getting more prevalent, and I may have to use this stuff some day.


  • IBM Qshell white paper: www-
  • IBM's Qshell Web site:
  • Bash Reference Manual: ref.html
  • Sponsored By

    Is it possible to eliminate downtime? YES!

    Can Web development be easy? YES!

    Is multi-platform development possible? YES!

    Aldon Computer Group provides the BEST programming tools to make the iSeries 400 and multiple platform development processes easier.

    Find out how by attending a FREE online seminar at

    Client Server Dev.
    Aldon Computer Group
    Profound Logic Software
    Displaying Static HTML Pages from the iSeries
    ILE Static Binding
    JSP Server-Side Error Handling, Part 2
    Getting Started with Qshell Scripts
    Introduction to Communications Console and CODE/400's Code/Editor
    Call iSeries Programs Using SQL
      Newsletters | Subscribe | Advertise | About Us | Contact | Search | Home  
      Last Updated: 2/13/02
    Copyright © 1996-2008 Guild Companies, Inc. All Rights Reserved.