The Basics of Qshell

Qshell is a command environment based on POSIX 1003.2, X/Open Command, and Utilities Issue 4, Version 2 standards. It is upwardly-compatible with Bourne shell scripts and supports many of the features used by Korn shell and Bourne Again shell scripts. It consists of the following parts:

o The shell interpreter (or qsh) is a program that reads commands from an input source, interprets each command, and then runs the command using the services of the operating system.
o The utilities (or commands) are external programs that provide additional functions and can be quite simple or very complex.

Together, the shell interpreter and utilities provide a powerful, standards-based scripting environment. As you use the new programming models offered by IBM i5/OS, Qshell provides an extensible command environment that allows you to:

o Manage files in any file system supported by the Integrated File System.
o Run threaded programs that do thread-safe I/O to and from an interactive session.
o Write shell scripts that can be run without modification on other systems using a cross-platform command language.
o Write your own utilities to extend the functions provided by Qshell.

The Qshell Interpreter is an optional licensed program (57xxSS1 Option 30) that is provided with the IBM i.

To determine if you already have the Qshell Interpreter licensed program installed, from the operating system command line type GO LICPGM and press the Enter key. Select Option 10, and press the Enter key again. To toggle through the Installed Status, Installed Release, and Product Option column views, press F11.

Installed Status

This column indicates whether or not each licensed program or optional part is installed. If no value is shown, the licensed program or optional part is not installed. Some of the status values are:

o	*COMPATIBLE The product is installed and its version, release, modification, and level is compatible with the installed level of the operating system.
o	*ERROR The product has not been installed successfully or it is only partially installed. Use the Check Product Option (CHKPRDOPT) command to determine the cause of the failure. The publication about installing, upgrading, or deleting i5/OS and related software (SC41-5120) has more information on recovery procedures for licensed programs and optional parts that have not been installed successfully. Note: Program temporary fixes (PTFs) can be applied to licensed programs that display as *ERROR.
o	*INSTALLED The product is installed; however it may or may not be compatible with the installed operating system.

If the Installed Status of the Qshell Interpreter shows as *ERROR, the license program is currently not functioning properly and must be re-installed.

Installing or Re-Installing the Qshell Interpreter Licensed Program

If the Qshell Interpreter is not listed as an installed program or if re-installation is required, load the system installation media (refer to the Installation Media List below) and use GO LICPGM Option 11 to install Qshell.

Installation Media List

The following Standard Set CD numbers contain the 57xxSS1 Option 30 - Qshell Interpreter:

o V7R1: B_GROUPx_02 Standard Set

o V6R1: B29xx_01 Standard Set

o V5R4 and V5R3: D29xx_02 Standard Set

o V5R2: B29xx_05 Standard Set

o V5R1: B29xx_04 Standard Set

After you have inserted the media into the CD drive, typed GO LICPGM, and selected Option 11, scroll through the list of licensed programs until you see product Option 30 (Qshell). Type 1 in the Option column next to Qshell in the Description column and press the Enter key. The system will ask you to confirm the installation of the licensed program 57xxSS1 Option 30 - Qshell. Press the Enter key to proceed to the Install Options page. The listed Install Options should be set with the following values:

Installation Device... OPT01
Objects to install... 1 1=Programs and language objects
Nonaccepted agreement.. 2 2=Display software agreement
Automatic IPL... N N=No

Press the Enter key to start the installation, and the system will begin installing Qshell. You will know you are finished when you get the confirmation message Work with license programs function complete.

The Start QSH (STRQSH) command, also known as QSH, is a CL (control language) command that starts a Qshell interactive session or runs a Qshell command.

If running in an interactive job with no parameters, STRQSH starts an interactive Qshell session. If a Qshell session is not already active in the job, then the following events occur:

1.	A new Qshell session is started and a terminal window is displayed. The operating system starts a batch-immediate job that runs the Qshell interpreter, which is a program named QZSHSH. At this point the user is running two jobs: the interactive job and the batch-immediate job. If you start a subshell or run a utility, Qshell will start additional jobs as needed. These jobs have the name QP0ZSPWP (if single-threaded) or QP0ZSPWT (if multithreaded). Thus, three jobs are required to start a subshell or to run a utility.
2.	QSH runs the commands from the file /etc/profile if it exists.
3.	QSH runs the commands from the file .profile in the user's home directory if it exists.
4.	QSH runs the commands from the file specified by the expansion of the ENV variable if it exists.

If a Qshell session is already active in an interactive job, you are reconnected to the existing session. From the terminal window, you can type Qshell commands and view output from the commands. The terminal window has the following parts:

o	An input line for typing commands
o	An output area that contains an echo of the commands you typed and any output generated by the commands

You can use the following function keys:

Function key	Description
F3 (Exit)	Close the terminal window and end the Qshell session.
F5 (Refresh)	Refresh the output area.
F6 (Print)	Print the output area to a spooled file.
F7 (Up)	Roll output area up one page. If a number is on the command line, the output area is rolled up by that number of lines.
F8 (Down)	Roll output area down one page. If a number is on the command line, the output area is rolled down by that number of lines.
F9 (Retrieve)	Retrieve a previous command. You can press this key multiple times to retrieve any previous command. For example, to retrieve the second to last command you typed, press this key two times. You can also select a specific command to be run again by placing the cursor on that command and pressing this key. When the interactive job is running in a double-byte CCSID, this key is not available.
F11 (Toggle line wrap)	Toggle the line wrap/truncate mode in the output area. In line wrap mode, lines longer than the width of the terminal window are wrapped to the next line. In truncate mode, the portion of a line beyond the width of the terminal window is not shown.
F12 (Disconnect)	Disconnect from the Qshell session. This key closes only the terminal window and does not end the Qshell session. You can redisplay the disconnected Qshell session by running STRQSH again.
F13 (Clear)	Clear the output area.
F14 (Adjust command line length)	Adjust the command line length to four lines. If a number is on the command line, the command line length is adjusted to that number of lines.
F17 (Top)	Display the top of the output area.
F18 (Bottom)	Display the bottom of the output area.
F19 (Left)	Shift the output area to the left. If a number is on the command line, the output area is shifted by that number of columns.
F20 (Right)	Shift the output area to the right. If a number is on the command line, the output area is shifted by that number of columns.
F21 (Command entry)	Display a command entry window where you can type CL commands.
SysReq 2	Interrupt the currently running command by sending the SIGINT signal to all child processes.

Note: The subsystem the CL program is running in must be configured to allow at least 2 additional jobs to be created. This can be verified through the MAXJOBS parameter on the subsystem description. MAXJOBS - CURRENT NUMBER OF JOB >= 2. This allows for the Qshell Interpreter job and a child job to run the utility.

The Start QSH (STRQSH) command, also known as QSH, is a CL (control language) command that starts a Qshell interactive session or runs a Qshell command. If called with the CMD parameter, STRQSH runs the specified Qshell command. The possible values of the CMD parameter are:

o	*NONE No command is provided and an interactive session is started. If CMD(*NONE) is specified and STRQSH is run in a batch job, STRQSH does nothing.
o	command A Qshell command is specified. The command can be a maximum of 5000 bytes in length. If a blank or other special characters are used, the command must be enclosed in apostrophes. If an apostrophe is intended, two apostrophes must be used.

When running a command, STRQSH starts qsh, runs the specified Qshell command, displays any output generated by the command to the C runtime terminal session, and ends qsh. Note that qsh does not run any profile files when started to run a command.

You can control what happens to the output by setting the QIBM_QSH_CMD_OUTPUT environment variable. The environment variable can have the following values:

o	STDOUT Display the output to the C runtime terminal session. This is the default value.
o	NONE Throw away any output that is produced.
o	FILE=pathname Store the output in the file specified by pathname. The file is truncated before the output is written to the file.
o	FILEAPPEND=pathname Store the output in the file specified by pathname. The output is appended to end of the file.

When the command ends, STRQSH sends one of the following messages:

o	QSH0005 is sent when the process running the command ends normally. The message includes the exit status of the process.
o	QSH0006 is sent when the process running the command ends by signal. The message includes the signal number.
o	QSH0007 is sent when the process running the command ends by exception.

By default, the messages are sent as completion messages. You can have the messages sent as escape messages by setting the environment variable QIBM_QSH_CMD_ESCAPE_MSG. When the value of the environment variable is Y, the QSH0006 and QSH0007 messages are always sent as escape messages and the QSH0005 message is sent as an escape message if the exit status is greater than zero.

Qshell in Batch Jobs

You can also run Qshell in a batch job. Unfortunately, there are certain limitations:

o	Input requests are ignored.
o	If the command produces any output, it will be spooled by Qshell.

Note: The subsystem the command is submitted to must be configured to allow at least 3 additional jobs to be created. This can be verified through the MAXJOBS parameter on the subsystem description. MAXJOBS - CURRENT NUMBER OF JOB >= 3. This allows for the submitted job, the Qshell Interpreter job, and a child job to run the utility.

The following is an example of how to submit a Qshell command to run in batch mode:

SBMJOB CMD(QSH CMD('cd /home;ls -l')) JOB(CdAndListFiles)

Note: A semicolon (;) was used in the above command to allow the cd /home and the ls -l commands to be run under the same Qshell interpreter shell.

The following are basic Qshell commands:

Command	Description
;	Separates multiple commands to be run under the same Qshell interpreter shell
set	Displays the names and values of all shell variables by specifying no options or arguments
pwd	Displays the working directory on standard output
ls	Lists directory contents
cd	Changes the working directory
print	Writes to standard output
export	Sets the export attribute for variables (for example, export PATH=/usr/bin: will set the PATH variable to /usr/bin:)
cat	Reads the specified files sequentially and writes them to standard output
chmod	Changes the operating system data authorities for an object
cp	Copies files
grep	Searches a file for a pattern
print $JOBNAME	Writes the current Qshell Interpreter qualified job name to standard output
getjobid	Writes the child qualified job name and process ID for the specified process to standard output
jar	Combines multiple files into one Java™ Archive file
java	Runs Java programs
mkdir	Creates directories
mv	Moves files
pax	Reads, writes, and lists the members of an archive file, and copies directory hierarchies
rm	Removes files (for example, the command rm -r removes the directory and file contents)
s	Starts a subshell of the Qshell command language interpreter
system	Runs a CL command within Qshell interpreter
tar	Reads, writes, and lists files from an archive file

Refer to the following Web sites for additional information:

IBM i Information Center - Qshell
http://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/index.jsp?topic=/rzahz/rzahzintro.htm

System i Programming Qshell (V6R1 and V7R1) Publication
http://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/topic/rzahz/rzahz.pdf

Qshell Utilities
http://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/index.jsp?topic=/rzahz/rzahzutility.htm

Qshell for iSeries Publication
www.amazon.com/gp/product/1583470468/102-9065628-4741741

Public Qshell Rochester Support Center Knowledgebase Documents
http://www-912.ibm.com/s_dir/slkbase.NSF/wos?OpenView&Start=1&Count=30&Expand=12.11#12.11

PTF Cover Letters Search
http://www-912.ibm.com/a_dir/as4ptf.nsf/9939a36675eadb978625710200584cbd/$searchForm?SearchView
Search for the word Qshell.