IBM Support

The Basics of Qshell

Troubleshooting


Problem

This document is a general overview of licensed program 57xxSS1 Option 30 - Qshell Interpreter.

Resolving The Problem


  • - What is 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.



  • - Qshell Installation



    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.

    • - Using a Qshell Interactive Session



      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:
      oAn input line for typing commands
      oAn 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 2Interrupt the currently running command by sending the SIGINT signal to all child processes.

      • - Running Qshell Commands from CL



        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.
        ocommand

        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:
        oSTDOUT

        Display the output to the C runtime terminal session. This is the default value.
        oNONE

        Throw away any output that is produced.
        oFILE=pathname

        Store the output in the file specified by pathname. The file is truncated before the output is written to the file.
        oFILEAPPEND=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:
        oQSH0005 is sent when the process running the command ends normally. The message includes the exit status of the process.
        oQSH0006 is sent when the process running the command ends by signal. The message includes the signal number.
        oQSH0007 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:
        oInput requests are ignored.
        oIf 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.



      • - Basic Qshell Commands



        The following are basic Qshell commands:

        CommandDescription
        ;Separates multiple commands to be run under the same Qshell interpreter shell
        setDisplays the names and values of all shell variables by specifying no options or arguments
        pwdDisplays the working directory on standard output
        lsLists directory contents
        cdChanges the working directory
        printWrites to standard output
        exportSets the export attribute for variables (for example, export PATH=/usr/bin: will set the PATH variable to /usr/bin:)
        catReads the specified files sequentially and writes them to standard output
        chmodChanges the operating system data authorities for an object
        cpCopies files
        grepSearches a file for a pattern
        print $JOBNAMEWrites the current Qshell Interpreter qualified job name to standard output
        getjobidWrites the child qualified job name and process ID for the specified process to standard output
        jarCombines multiple files into one Java™ Archive file
        javaRuns Java programs
        mkdirCreates directories
        mvMoves files
        paxReads, writes, and lists the members of an archive file, and copies directory hierarchies
        rmRemoves files (for example, the command rm -r removes the directory and file contents)
        sStarts a subshell of the Qshell command language interpreter
        systemRuns a CL command within Qshell interpreter
        tarReads, writes, and lists files from an archive file

        [{"Product":{"code":"SWG60","label":"IBM i"},"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Component":"Programming (Languages- compilers- tools)","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"5.4.5;6.1;6.1.1;7.1;5.1.0;5.2.0;5.3.0;5.3.5;5.4.0;5.4.5;6.1.0;6.1.1;7.1.0","Edition":"","Line of Business":{"code":"LOB08","label":"Cognitive Systems"}},{"Product":{"code":"SSC3X7","label":"IBM i 6.1"},"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Component":" ","Platform":[{"code":"","label":""}],"Version":"","Edition":"","Line of Business":{"code":"","label":""}},{"Product":{"code":"SSC52E","label":"IBM i 7.1"},"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Component":" ","Platform":[{"code":"","label":""}],"Version":"","Edition":"","Line of Business":{"code":"","label":""}}]

        Historical Number

        433528588

        Document Information

        Modified date:
        18 December 2019

        UID

        nas8N1014643