User Defined Commands and Command Files



Overview

You can execute MPE User Defined Commands, also known as UDCs, inside Qedit. You must first do a Set Udc command to tell Qedit which UDCs to recognize. To check on your UDCs, use Verify Udc, :Setcatalog and :Help udc.

The wider concept, User Commands, includes both UDCs and command files. A command file is a file that contains a set of commands which will be executed when you type the name of the file (like a DOS batch file). Command files are similar to UDCs except that you do not need to catalog them. Like UDCs, command files can have parameters. Many users are switching from UDCs to command files, because the maintenance is easier.

A command file can start with the optional header lines: PARM, ANYPARM and OPTION. These define the parameters and options of the command file. The command file terminates at the end of file or the first * line. If you need to pass an exclamation mark as parameter, use !! (for example, use !!xx if you want to pass in the string !xx).

You can use UDCs and command files as a "command language" to write customized functions in Qedit. They may contain MPE commands like :Listf. Qedit commands preceded with a slash, conditional logic commands such as :If and :Else, :While loops, Qedit-simulated MPE commands such as :Editerror, other command files, UDCs, external commands (%purge t@), and calculator commands (=5*80). You can include Qedit commands in a command file by preceding them with a slash "/". Qedit commands in command files and UDCs will set the CIERROR JCW so that you can test the result of the command. See the /Qedit Command section below for more details.

Qedit accepts command file names and UDC commands with or without the leading colon (":"). You must precede them with a colon if the name is the same as a Qedit command (e.g., :R, :L). Beware of some unobvious Qedit commands composed of abbreviations and options. For example, PRT is interpreted as a Qedit command (Proc with the template option) so you must put a colon in front of it to have Qedit execute it as a User Command.

In Qedit, an asterisk (*) as a parameter to a User Command substitutes the name of your current workfile or the last one you Shut. As well, $ as parameter substitutes the name of the last external filename mentioned (Verify Lastfile).

Back to table of contents

Sample UDCs

UDCs allow you to abbreviate the MPE commands that you use frequently and to create complex new commands. We provide a sample UDC file in the Robelle account that you may find useful:

        /set udc udc.catalog.robelle
        /:showcatalog
        UDC.CATALOG.ROBELLE
           PROSE               USER
           PDISC               USER
           SEG                 USER
           TIME                USER
           SPOOK               USER
           DUP                 USER
        /:help time
        USER DEFINED COMMAND:
        time
        ##  show the date and time
        showtime
        /:time
        FRI, OCT 14, 1995,  9:24 PM
        /:SPOOK     {runs spook on any CM system}

Back to table of contents

Restriction on Qedit UDCs

There are three restrictions on the User Commands that Qedit can handle: no more than 32 parameters or more than 256 bytes of parameters, no expanded line greater than 279 characters, and no I/O redirection on MPE V.

Qedit supports If/Else commands and the While-Endwhile loop of MPE/iX, but the CIERROR JCW is not updated exactly the same as MPE for all errors.

Back to table of contents

UDC Security

Some users have altered the security of Command.Pub.Sys to be (X,L:ANY; R,A,W:CR). If you do this, the Set Udc On command will not be able to search Command.Pub.Sys. Use Set Udc with filenames instead.

Back to table of contents

UDCs with Parameter Substitution

Here are two UDCs with parameters, :Compare and :Seg.

        /set udc compudc.catalog.robelle
        /:help compare
        USER DEFINED COMMAND:

        COMPARE filea, fileb, outfile="$STDLIST", info=""
        ##
        ##  Compare two files using the Compare program.
        ##
        file filea=!filea
        file fileb=!fileb
        file outfile=!outfile
        run compare.pub.robelle;info="!info"
        reset filea
        reset fileb
        reset outfile
        ****
You invoke the Compare UDC by entering:
        /:compare *,origfile  {* means current workfile}
The Seg UDC gives you the ability to execute a file of :Segmenter commands without typing them interactively and without streaming a batch job.
        /setcatalog udc.catalog.robelle
        /:help seg
        USER DEFINED COMMAND:

        seg parm1
        ##  execute segmenter commands from a file.
        run segdvr.pub.sys;stdin=!parm1
        *
To invoke Seg, specify the file name that contains Segmenter commands:
        /:seg seg055

Back to table of contents

Command File Example

Here is a command file to print the spool files for a job number:

        SSP.BOB.GREEN

        parm jobnum="0"
        if !jobnum > 0 then
           showout job=#j!jobnum
        endif
To invoke SSP.Bob.Green within Qedit, you just type
        /ssp 67
Qedit follows the Hppath variable in searching for a command file named "ssp". The default is to look in your logon group, then your Pub group then Pub.Sys. You can override the default path by doing :Setvar Hppath on MPE/iX or Set Hppath on MPE V (simulated).
        /:setvar hppath "!hpgroup,cmd,pub,pub.sys" {MPE/iX}
        /set hppath "!hpgroup,cmd,pub,pub.sys"     {MPE V}
Warning: When you convert a UDC into a command file, don't forget to replace the UDC name in the first line by the literal "PARM". If you forget, you can easily create a recursive loop, since the PARM line is optional in command files. A command file can invoke itself recursively, but only up to 10 levels deep.

Restriction: Command files must be permanent files on MPE V, but they can be either temporary or permanent files on MPE/iX.

Back to table of contents

I/O Redirection

On MPE/iX, you can have I/O redirection in command files. The "<" and ">" characters are used to specify I/O redirection, so there are some restrictions in using them in a command file's Qedit commands.

Any occurrence of "<" or ">" means I/O redirection, unless these character are part of a string. However, the string can only be delimited by a single quote (') or a double quote ("). The other string delimiters usually accepted by Qedit do not work. For example,

        /find \<comment>\
works as a Qedit command on-line, but does not work in a command file because the "<" and ">" are interpreted as I/O redirection.

Back to table of contents

Variables

On MPE/iX, commands in UDCs and command files may reference variables by preceding them with an exclamation mark, just as you do for parameters (e.g. display !hpgroup). Variables are also allowed in MPE commands which you enter through $stdin or a usefile. On MPE V, Qedit allows you to refer to the value of a JCW in the same way (e.g., display !cierror).

Here is a command file that updates a record with today's date in YY/MM/DD format. The date is derived from the pre-defined HP JCWs hpyear, hpmonth, and hpdate:

        TODAY.CMD.SYS

        /t file                  {replace columns 1/8 with date}
        /set win (1/8)
        /c 1/8 "!hpyear/!hpmonth/!hpdate"
        /l "/" (5/5) *           {check for "/" in column 5}
        if qeditcount = 1
           /c 4 "0"              {insert leading 0 before month}
        endif
        /l " " (8/8) *           {check for " " in column 8}
        if qeditcount = 1
           /c 7 "0"              {insert leading 0 before day}
        endif
        /set win ( )
The value of the JCWs hpmonth and hpdate may be single digits (for example on January 1, 1996) so we may need to insert leading zeros (96/1/1 becomes 96/01/01). We do this by testing for the existence of a "/" and a " " in specific columns. If there is a "/" in column 5, we know that the month value is a single digit.

Qeditcount

Qedit has a JCW (like a variable) that keeps track of how many lines were processed by the last command: QEDITCOUNT. This JCW is updated after those commands that can print a total: List, Delete, Add-file, Add-move, Add-copy, Append, Change, Divide, Glue, Justify, Keep, Merge, Proc, and Text. The line count is truncated at 32,000.

     /deleteq "$page"
     29 lines DELETED!
     /showjcw qeditcount
     QEDITCOUNT = 29

InsideQedit JCW

Since UDCs and command files are not exactly the same when executed inside Qedit, as they are when executed by MPE, we provide a JCW that tells you where you are. InsideQedit is set to 0 the first time you run Qedit. You should also set it to 0 in your logon UDC. If you do a ShowJCW, InsideQedi will always show a value of 0. When you refer to InsideQedit from within Qedit (in an If or While command), Qedit does not look at the real JCW. Instead, it inserts a constant value of 1. Nor does Qedit set the real JCW to 1; it is still 0. Thus, you have a JCW that acts differently withi Qedit, giving you a way to find out where you are. Since /Qedit commands can only be executed when the command file is executed by Qedit, the InsideQedit jcw gives you a way to test this.

        if insideqedit=1 then
           run spook5.pub.sys;hold
        else
           run spook5.pub.sys
        endif

Back to table of contents

Current Workfile (*)

The :Prose command is even more useful than it appears, due to an extension to the UDC-concept that Qedit provides: * as a parameter is replaced by the name of the current workfile, or the workfile just closed if none is Open. Thus, you can easily edit and print a Prose document from within Qedit:

        /open rpt003.doc      {open file for changes}
        /modify ...           {edit the document}
        /set udc udc.catalog.robelle
        /:prose *             {print final-stop with control-y}
                              {Prose may take a while}
        /modify ...           {more changes...}
        /add .001             {select pages to print}
          0.001 .sel (1:4)
          0.002 //
        /:prose *,*lp         {print copy on line printer}
When you specify * as a UDC parameter and the current file is in your logon group, Qedit passes the unqualified filename as the UDC parameter instead of the fully qualified filename. This allows you to append group names to it in the UDC body.

Back to table of contents

Options for UDCs

Qedit supports the MPE options for List, Nohelp, and Nobreak, plus:

        OPTION NOERROR        {suppress all MPE error messages}
        OPTION NOWARN         {suppress all warning messages}

Back to table of contents

/Qedit Commands

When you execute a command file or a UDC from within Qedit, you can also include Qedit commands in the command file by preceding the Qedit commands with a slash (for example,/find "text").

        /command line

Back to table of contents

Checking Results

Qedit allows you to include Qedit command lines within UDCs and command files. You can check the result of the /Qedit command by testing CIERROR or QEDITCOUNT:

        setjcw CIERROR = 0
        continue
        /open abc.source
        /find "def"
        if CIERROR=0 then
           /delete *
        else
           if CIERROR=860 then
              display Invalid syntax in Qedit command!
           else
              if CIERROR=900 then
                 display End of file - string not found!
              else
                 if CIERROR=907 then
                    display Non-existent file!
                 endif
              endif
           endif
        endif
As this example shows, the /Qedit command returns one of three CIERROR values:
         860 = Illegal Keyword
         907 = Non-Existent File
         900 = End Of File  (returned by Find and Findup)
Note that these CIERROR values are only set when the commands are being executed from a User Command, not from $stdin or a usefile.

Back to table of contents


(Thanks to Tim Ericson for this article)

....Back to the Qedit Q&A Page