Lesson 4\using UDC Options

Introduction

Lesson 4 presents the following options associated with UDCs:

LOGON/NOLOGON
LIST/NOLIST
HELP/NOHELP
RECURSION/NORECURSION
PROGRAM/NOPROGRAM''
BREAK/NOBREAK

These options affect the way that the UDC is used and the way that it acts. Typically, the option must be specified in the line directly after the UDC header (name). Several of these options can also appear within the body of the UDC. (This is discussed later in this lesson.)




	NOTE: Most of the options discussed appear in `MYUDC1` and `MYUDC2`.

LOGON option

As you recall, the LOGON option causes a UDC to execute immediately upon logon. You need not invoke it by name.

MYUDC1 contains a UDC called STARTUP that uses this option. Notice how you automatically get a SHOWJOB display when you logon. OPTION LOGON is good for any UDCs that you want automatically executed at the beginning of your session.

Example:

   STARTUP

   OPTION LOGON

   SHOWJOB

   SETEQ

   ***

The default is OPTION NOLOGON.




	NOTE: The `LOGON/NOLOGON` option must appear immediately after the UDC header on a separate line.

LIST/NOLIST option

This option specifies whether or not the MPE/iX commands that make up a specific UDC are displayed when the UDC is executed. If OPTION LIST is specified, each line of the UDC will be displayed, as well as the results of that line.

With the LIST option, the UDC command lines are displayed.

There are two UDCs in MYUDC2: ST1 and ST2. Both do the same thing, with only one minor difference - the LIST/NOLIST option:

   ST1

   OPTION LIST

   SHOWTIME

   ***



   ST2

   OPTION NOLIST

   SHOWTIME

   ***

erify that MYUDC2 is still cataloged. If it is not, please use SETCATALOG to do so.

Execute ST1 and ST2. What happens? Notice that with ST1, both the MPE/iX command (SHOWTIME) and its results are displayed on the screen. With ST2, only the results of SHOWTIME are displayed. ST1 has the LIST option, and ST2 does not.

Normally, you don't need a listing of the actual commands in the UDC. However, if you have a particularly complex UDC and wish to be reminded of the commands that compose it, use OPTION LIST.

The default is OPTION NOLIST.




	NOTE: The `LIST/NOLIST` option can appear in the body of the UDC, as well as immediately after the header. This is unlike `LOGON/NOLOGON`, which can only appear immediately after the header.

HELP/NOHELP option

As you recall, you can use the HELP command to look at the description of a particular UDC in a UDC file. By using HELP, you do not have to PRINT the entire UDC file to view only selected UDCs. Type:

   HELP SETCAT

You should see a description of the SETCAT UDC. Now type:

   HELP SETCATA

Why don't you see a description? HELP only works with UDCs that are defined with the HELP option. To examine SETCATA, then, you must print the entire MYUDC2 file.

   PRINT MYUDC2

Find the SETCATA UDC and notice that it is defined with the NOHELP option.

Unless security restrictions prevent you from allowing others to examine a UDC, you should avoid the use of the NOHELP option.

The default is OPTION HELP.




	NOTE: The `HELP/NOHELP` option must appear immediately after the UDC header.

RECURSION/\NORECURSION option

Normally, in your UDC file you can use a UDC within the definition of another UDC, only if the one you are referencing appears after the one you are currently using. For example, this is a valid UDC sequence within a UDC file:

UDCFILE1:

   LOGON

     command

     command

     command

   **********

   UDC1

     command

     UDC2

     command

   **********

   UDC2

     command

     command

     command

   ***********

UDC2 is called within UDC1, and that is acceptable because UDC2 is defined after UDC1 in UDCFILE1. What if you wanted to call UDC1 within UDC2? That would not be possible unless you used the RECURSION option.

Not only must you be concerned with the order in which UDCs are defined within one UDC file, you must be concerned with the order in which the UDC files themselves are cataloged. When you catalog your UDC files, UDCs are cataloged in the order in which the UDC file names were entered on the SETCATALOG command line.

For example, suppose you cataloged your UDC files in this order:

   SETCATALOG UDCFILE1,UDCFILE2

By specifying the RECURSION option after the UDC header, you can reference any UDC in the UDC directory, even if it was defined in a UDC file that was cataloged prior to the current one. In the next example, you can see the RECURSION option used properly for UDC2 and UDC3: UDCFILE1: UDCFILE2:

   UDC0                          LOGON

     command                       command

     command                       command

     command                       command

   ***********                   ************

                                 UDC1

                                   command

                                   command

                                   UDC2

                                   command

                                 ************

                                 UDC2

                                 OPTION RECURSION

                                   command

                                   command

                                   UDC1

                                   command

                                 ************

                                 UDC3

                                 OPTION RECURSION

                                   command

                                   UDC0

                                 *************

The RECURSION option, as illustrated, ensures that UDC2 is properly executed, even though UDC1 precedes it in the file. The option also ensures that UDC3 is properly executed, even though UDC0 precedes it in the directory.




	NOTE: `UDC0` is in `UDCFILE1`. `UDCFILE1` was cataloged before `UDCFILE2`. The `RECURSION` option is only effective for the UDC in which it is specified.

The RECURSION option on a UDC eliminates the need to put a UDC file in any specific order in the catalog. When RECURSION is used, the recursive UDC finds the other UDCs it calls, regardless of the order of the UDC file. Therefore, the order in which the UDC files are cataloged is not important.




	NOTE: It is good practice to put a comment in a UDC file to indicate whether or not it must be cataloged in a certain order with other UDC files because of recursion dependencies.

Exercise 5-3: RECURSION option

Study the following UDC file and indicate how you should change this file to have the UDC SO call upon and execute UDC ST without changing the order of the UDCs in the file:

   ST

   SHOWTIME

   ***

   SM

   SHOWME

   ***

   SO

   SHOWOUT

   ***

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

Because recursion allows two UDCs to call each other and enables a UDC to call itself, limitations have been put in place to prevent endless loops.

The maximum number of times that a UDC can call itself, or that two user commands can call each other is 30 total times. When that maximum is reached, the system interrupts the process with an error message. This is a system-imposed restriction.

Example:

Suppose you add the following UDC to MYUDC2, recatalog MYUDC2, and then execute MYTIME.

   MYTIME

   OPTION RECURSION

   SHOWTIME

   MYTIME

Notice that MYTIME executed 30 times!

The default is OPTION NORECURSION.




	NOTE: The `RECURSION` option can appear anywhere in the body of the UDC, as well as immediately after the header.

PROGRAM/\NOPROGRAM option

This option lets you specify whether or not a UDC can be executed from within a program. If you specify NOPROGRAM, the UDC cannot be executed from within a program.

Consider the following UDC in the MYUDC2 file:

   TIME

   OPTION NOPROGRAM

   SHOWTIME

   ***

This means that if you called TIME from within a program or utility, such as VOLUTIL (a volume management utility), the following would happen:

   volutil:  :TIME

   UNKNOWN COMMAND NAME.  (CIERROR 975)

Notice that from the utility, you must enter the system prompt (:) before the UDC. You must do this so that the command interpreter can respond, even though you are in a subsystem.

Then exit VOLUTIL as follows:

   volutil:  EXIT

The default is OPTION PROGRAM. However, even with OPTION PROGRAM, some subsystems and utilities won't recognize UDCs, depending on how they were programmed.




	NOTE: The `PROGRAM/NOPROGRAM` option must appear after the UDC header and the `PARM` line.

Q5-5

Study the following UDC and indicate what you would do to this file to have the UDC LF not be executable from within a program:

   LF

   LISTFILE

   ***

BREAK/NOBREAK option

This option lets you specify whether or not the execution of a UDC will be "breakable". With the BREAK option specified, when you press BREAK, execution of a command stops and cannot be resumed. However, if the command happens to invoke a subsystem such as the editor or FCOPY, you may use the RESUME command after pressing BREAK to continue execution.

For example, LISTFILE is a "regular" command. If you press BREAK while LISTFILE is executing, all output stops. You cannot use the RESUME command to continue its execution. On the other hand, if you are executing VOLUTIL commands (VOLUTIL is a subsystem) and press BREAK, you will be put in "break mode."

This means that you can then execute other MPE/iX commands or RESUME or ABORT the subsystem.

If you specify the NOBREAK option, pressing BREAK will have no effect on either regular MPE/iX commands or subsystem commands.

To illustrate this option, create the following two command files, BREAK1 and BREAK2.

BREAK1 command file:

   OPTION BREAK

   LISTFILE @.CLASS.ACCTx,2

BREAK2 command file:

   OPTION NOBREAK

   LISTFILE @.CLASS.ACCTx,2

Now, execute BREAK1 and immediately press BREAK. The listing should stop. Notice also that you cannot resume the listing by typing RESUME. BREAK effectively terminates the execution of BREAK1.

Do the same with BREAK2. What happens? The BREAK key should have no effect, and the files in the account should continue listing.




	NOTE: The `BREAK/NOBREAK` option must appear immediately after the UDC header.

Position of options

By now you've probably noticed that most options appear on the lines following a UDC header, or on the first lines of a command file. There are two options that can appear both after the UDC header and in the UDC body. What are they?

   OPTION RECURSION/NORECURSION

   OPTION LIST/NOLIST

When an option appears within the body, it takes precedence over the option in the header.

Study the DOFILE example when answering the following question. It illustrates what happens when OPTION LIST appears in the header, and OPTION NOLIST appears in the body:

DOFILE UDC File:

   DOIT1

   OPTION LIST

   SHOWTIME

   OPTION NOLIST

   LISTFILE

   ***

   DOIT2

   SHOWME

   ***

   DOIT3

   LISTFILE

   OPTION RECURSION

   DOIT2

   ***

Q5-6	DOFILE.`CLASS` is on your system. Add it to the user directory by cataloging it. Execute `DOIT1`. What MPE/iX commands are displayed? Execute `DOIT2`. What MPE/iX commands are displayed? Why? Execute `DOIT3`. What MPE/iX commands are displayed? Why?

In DOIT1, OPTION LIST is "activated" in the UDC header and then "deactivated" in the UDC body when OPTION NOLIST is specified. This means that when you enter DOIT1, you will see the MPE/iX command, SHOWTIME, but you will not see the command, LISTFILE.

Figure 6-6 Default Options

Exercise 5-4: UDC options

Add a single UDC called SLS to the MYUDC2 file. Have the UDC do the following in the order given:
1. Execute the SHOWTIME command without listing the SHOWTIME command on the screen.
2. Execute the LISTFILE command without listing the LISTFILE command on the screen.
3. Execute the SHOWME command and list the SHOWME command on the screen.
  NOTE: Make sure that you uncatalog MYUDC2 before adding SLS to it.

What is wrong with the following UDC?


    LISTER
    OPTION NOLIST
    FILE OUT;DEV=LP
    PRINT MYFILE;OUT=*OUT
    OPTION LIST
    OPTION NOHELP
    LISTFILE MYFILE,2
    ***

Put an X next to the correct default value assumed by the system when no option is specified in a UDC:


   LIST                  NOLIST         

   HELP                  NOHELP         

   RECURSION             NORECURSION    

   PROGRAM               NOPROGRAM

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

Lesson summary

The following options control what you can do with your UDCs and command files (only LOGON/NOLOGON and RECURSION are valid only for UDCs):
1. LOGON/NOLOGON - determines whether or not the UDC goes into effect automatically upon logon (default = NOLOGON).
2. LIST/NOLIST - determines whether or not the commands making up the UDC, as well as its results, are listed when the UDC is executed (default = NOLIST).
3. HELP/NOHELP - determines whether or not you can display the commands making up the UDC by using the HELP command (default = HELP).
4. RECURSION/NORECURSION - determines whether or not you can reference a UDC within the definition of another, when the referenced UDC was defined before the other, either in the same file or elsewhere in the directory (default = NORECURSION).
  NOTE: Command files can always be invoked recursively. The RECURSION option has no meaning, except for UDCs.
5. PROGRAM/NOPROGRAM - determines whether or not you can execute a UDC within a program (default = PROGRAM).
6. BREAK/NOBREAK - determines whether or not the execution of a UDC is be "breakable" (default = BREAK).