Lesson 5\using Parameters

Introduction

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

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 6-7 Parameters in a UDC

Command File Example:

Figure 6-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 6-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 6-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 6-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 6-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.