HP 3000 Manuals

Using the 900 Series HP 3000: Advanced Skills Module 5: User Commands

Lesson 5 Using Parameters 

Introduction 

Lesson 5 presents the following information about UDC and command file
parameters:

   *   parameter definition.

   *   correctly using required and optional parameters. 

   *   correctly specifying parameters in UDCs and command files.

Passing values by parameters 

You may have noticed, when examining the MYUDC2 file, that some UDCs have
more than just a command name in the header.  Some also have parameters.
Up to now you've read about user commands (both UDCs and command files),
which are composed solely of simple MPE/iX commands.  To invoke such a
user command, you simply enter one command name.

It is also possible for a user command to contain parameters, so that
when you execute the command, you can enter the name of the UDC or
command file, followed by one or more values.  The values are passed to
the parameters.  Parameters act as placeholders in the command syntax and
are replaced by user-supplied values upon execution.  In a UDC, the
parameters appear in either the command header, or on the PARM line
directly preceding any options, but not in both places.  In a command
file, the parameters appear only in the PARM line, which is the first
line of the file, directly preceding any options.

UDC:                             Command File:

     Header                 Parameters
     Parameters             Options
     Options
     Body

UDC Example: 


          Figure 5-7.  Parameters in a UDC 

Command File Example: 


          Figure 5-8.  Parameters in a Command File 

In these examples, FILE is the parameter.  The user command name is PR.
The syntax of this user command indicates that PR must always be followed
by a value.  This value will be some file name supplied by the user.  The
system knows that FILE is a parameter because of the PARM line.  The
system also knows that FILE is to be replaced with a user-supplied value,
since there is an exclamation point (!)  in front of the parameter name
(!FILE).

The system command, PRINT, is executed when you supply a file name along
with the PR user command:

     PR JOB1

This actually executes the following system command:

     PRINT JOB1


          Figure 5-9.  PR Command File 

Try it and see!

What happens if you just type:

     PR 

You get an error because, according to the UDC definition, the system
expects a value after the PRINT command.  In this lesson you will learn
how to avoid such errors by defining default parameter 
values.

What if you wanted to print several files?  What happens if you type:

     PR JOB1,JOB2 

Once again, you get an error because, according to the UDC definition,
only one parameter value is expected.  You may write UDCs that allow more
than one parameter.  You will be examining their use later in this
lesson.

Optional and required parameters 

Parameters are either required or optional.  If required, the user must 
specify values for the parameters when executing the user command.

Required parameters are those for which no default value is specified.
Required parameters are specified by listing the parameter name without a
default value in the UDC. This means that when the UDC is invoked, some
value must follow the command name, if a required parameter is specified
in the definition.  You can now examine two different examples, the PR
command file (which you've already seen), and the SETCAT UDC.

PR Command File Example 

     PARM FILE1
     PRINT !FILE1

Explanation 

The purpose of this command file is to print one file (FILE1.)

The exclamation point (!)  tells the system that the file name that you
specify when you execute the PR user command is be passed to the
parameter, FILE1.

FILE1 is a required parameter.  You
cannot enter PR without specifying a value after it.  What happens if you
enter only PR? The system tells you:
________________________________________________________________________
|                                                                      |
| FILE1 PARAMETER IS REQUIRED.                                         |
| PARAMETERS DO NOT MATCH USER COMMAND DEFINITION.                     |
|                                                                      |
________________________________________________________________________

            

SETCAT UDC Example: 

     SETCAT UDCFILE="MYUDC1"
     SETCATALOG !UDCFILE
     ***

Explanation: 

The purpose of this UDC is to catalog a specified UDC file.

The exclamation point (!)  tells the system that when you execute the
SETCAT user command, the file name that you specify is to be passed to
the parameter, UDCFILE.

UDCFILE is an optional parameter.  If you enter SETCAT without specifying
a value after it, MYUDC1 is assumed to be the value, by default.


NOTE  Required parameters have no values assigned them in the UDC or
      command file.  Optional parameters do.


First, use SHOWCATALOG to verify that both MYUDC1 and MYUDC2 are
cataloged.  If they are not, catalog them.

To test the default value of SETCAT, first uncatalog MYUDC1 so that only
MYUDC2 is in effect:

     SETCAT MYUDC2'' 

Now enter SETCAT without any file name after it and see what happens.
When you do a SHOWCAT, MYUDC1 should be in effect again, not MYUDC2.
Indeed, the system did execute this command:

     SETCATALOG MYUDC1 

Now, add MYUDC2 to the UDC directory and verify that both MYUDC1 and
MYUDC2 are cataloged:

     SETCATALOG MYUDC2;APPEND 
     SHOWCAT 

Here you cannot use SETCATA because it is a UDC defined in the MYUDC2 UDC
file.  Once MYUDC2 is cataloged, however, you can use SETCATA again.

Optional parameters with sensible default values are useful if the user
doesn't specify a value.

Multiple parameters 

What if you want to use the PR command file to print multiple files?  It
is also possible to specify more than one parameter in a UDC or command
file.  This lets you enter additional values after the UDC name when
executing the command.  By doing so, you pass values to multiple
parameters in one command.

Consider the following command file, PRX, and the UDC, SETCATX. Each is
modified version of the PR command file and the SETCAT UDC.


          Figure 5-10.  PRX Command File 

PRX Command File: 

     PARM FILE1=$NULL,FILE2=$NULL,FILE3=$NULL
     PRINT !FILE1
     PRINT !FILE2
     PRINT !FILE3

Explanation: 

The command in the previous figure lets you print up to three files.  All
three parameters default to $NULL (the system designator for an empty
file), so that only a $NULL value with no data is passed to them.  In
this example, assigning a parameter value of $NULL, no error message
results if you forget to specify a value for that parameter.  Without the
$NULL default, you would get the message THE xxx PARAMETER IS REQUIRED.

To test how the PRX user command works with one or more values, enter the
following:

     PRX JOB1,JOB2 

You should see a listing of each file and no error message.

What happens if you type only PRX? You shouldn't get an error message.
Instead, nothing is printed (since $NULL is an empty file).


          Figure 5-11.  SETCATX UDC 

SETCATX UDC (in MYUDC2 file): 

     SETCATX UDCFILE1="MYUDC1",UDCFILE2=$NULL,UDCFILE3=$NULL
     SETCATALOG !UDCFILE1,!UDCFILE2,!UDCFILE3
     ***

Explanation: 

The UDC in the figure above lets you catalog up to three files.  The
first parameter defaults to MYUDC1.  The second and third parameters
default to $NULL (empty file).

To test how the SETCATX UDC works with one or more values, start by
cataloging only MYUDC2:

     SETCATX MYUDC2 

Do a SHOWCAT to verify that only MYUDC2 is cataloged.  So, SETCATX works
with only one value.  How about three values?

Enter the following:

     SETCATX MYUDC1,MYUDC2,MYUDC3 

Do a SHOWCAT to verify that all three UDC files are now cataloged.

What happens if you type only SETCATX? Try it and see.  You should not
get an error message, since the first parameter (UDCFILE1) defaults to
MYUDC1.  Instead, MYUDC1 should get cataloged, since it is the default
value.  Notice also that all the other UDC files were "uncataloged."

Do a SHOWCAT to verify that only MYUDC1 is in effect.

Now recatalog MYUDC2 and MYUDC3, and then verify that all three UDC files
are once again in effect:

     SETCATALOG MYUDC2,MYUDC3;APPEND 
     SHOWCATALOG 

Using multiple parameters and $NULL default parameter values 
in place of file names gives you flexibility in a user command.  By doing
so, you can enter less than the total number of parameters specified in
the command without receiving an error message.

$NULL must not be used as a default value if you are supposed to pass a
numeric value to a parameter.  Use a number instead.  In the example
below, $NULL is the default value for a file name, whereas 2 is the
default value for the numeric option.

Example: 

     LS FILE1="$NULL",OPTION="2"
     LISTFILE !FILE1,!OPTION


NOTE  The quotation marks are not required.


Benefits of parameters 

Putting parameters in your UDCs can provide a short-cut method for
entering lengthy commands that change frequently.  For example, suppose
that you run a program that writes its results to *OUT. You must change
the OUT file equation each time you run the program so that the output
goes to one of three different files:  OUTFILE1, OUTFILE2, and OUTFILE3.
Consider the typing effort:

     FILE OUT=OUTFILE1;REC=-80,,F,ASCII
     FILE OUT=OUTFILE2;REC=-80,,F,ASCII
     FILE OUT=OUTFILE3;REC=-80,,F,ASCII

Wouldn't it be nice to have a UDC that would let you change the
destination easily?  Here is how it's done.


          Figure 5-12.  NEWOUT UDC 

     NEWOUT FILE
     FILE OUT=!FILE;REC=-80,,F,ASCII
     ***

To change the output destination to OUTFILE1, you only have to type

     NEWOUT OUTFILE1

Then, when you run the program, and it writes its output to *OUT, the
output is directed to OUTFILE1.

Exercise 5-5:  using parameters.   

   1.  Create a command file or UDC called LS that has the following
       characteristics:

          a.  performs a LISTFILE,1 or LISTFILE,2 or LISTFILE,3 on a
              user-specified file

          b.  the user must specify a file name; however, LISTFILE,1 will
              always be assumed unless otherwise specified Hint:  Use the
              PARM keyword as the first line of the file, and make sure
              to specify a default value for the numeric LISTFILE option.

              __________________________________________________________ 

              NOTE  When using parameters in a UDC, it's a good idea to
                    create a command file first and test it, and then
                    convert it to a UDC.

              __________________________________________________________ 

   2.  Test and execute LS on file JOB1 as follows:

          a.  Enter

                   LS 

              without any numeric option value.  What happens?

          b.  Enter

                   LS 

              with parameter value 1; then with parameter value 2; then
              with parameter value 3.

   3.  When the LS command file is working, convert it to a UDC and add
       it to MYUDC3.  This time, do not use the PARM line.

       HINT: Make sure to use SETCATALOG first so that MYUDC3 is not in
       the user directory; otherwise, you will be unable to modify it.

   4.  Recatalog MYUDC3 in the user directory.  Then test and execute LS.
       Even though the command file and the UDC are the same, the UDC is
       executed because the system searches the user directory first.

********** End of Exercise 5-5 *********** 

Lesson summary 

   1.  Optional (default) parameters should be used in a UDC or command
       file when it seems sensible that a user might not enter values for
       all the parameters.

   2.  Required parameters should be used in command files and UDCs when
       values must be specified with the UDC. Typically, required
       parameters come before optional ones.

   3.  In command files, parameters must be specified in the PARM line
       only (before options and before the body of the file).

   4.  In UDCs, parameters can be specified in the command header or the
       PARM line, but not in both.

MPE/iX 5.0 Documentation