HP 3000 Manuals HP 3000 Manuals
Help with Commands
If you look at the PURGE command in the book Command Reference - HP 3000
Series 9X8LX (B3820-90007), you will find, under the heading Syntax, a
curious-looking entry:
PURGE filereference[,TEMP]
This method of showing a command and its parameters is called a syntax
diagram.
Filereference looks unfamiliar. It is simply the formal name of the
(required) parameter for specifying a file to erase.
________________________________________________________________________
|A formal name is not a parameter. Formal names such as filereference |
|appear in syntax diagrams to help you understand what kind of |
|information belongs to a particular parameter. |
| |
|The information that you give to PURGE, or any other command, when you|
|execute it, is the actual parameter. |
________________________________________________________________________
On the command line, you would enter a suitable value (a name, a word, a
number) to achieve the results that you want, just as you enter PURGE
ACCTRPTReturn to remove a file called ACCTRPT. In this case, the
information ACCTRPT is the actual parameter.
-------------------------------------------------------------------------------------------------
| | | |
| Command | Formal Parameter | Actual Parameter |
| | A Name To Help You | A Real File to Erase |
| | | |
-------------------------------------------------------------------------------------------------
| | | |
| PURGE | filereference | ACCTRPT |
| | | |
-------------------------------------------------------------------------------------------------
| | |
| Syntax Diagram | PURGE filereference |
| | |
-------------------------------------------------------------------------------------------------
| | |
| Command Entered | PURGE ACCTRPT |
| | |
-------------------------------------------------------------------------------------------------
Filereference is a required parameter. It follows the name of the
command, and there are no square brackets around it. Filereference
suggests that some reference to a file is called for. In this case, it
calls for the name of a file.
You may find ,TEMP unfamiliar, too. It is an optional parameter. It is
also a keyword. There is more on information on keywords in "Variables
and keywords" and in "Syntax diagrams" .
In the syntax diagram, the square brackets ( [ ] ) surrounding ,TEMP
signify that using ,TEMP is optional. You may use it or omit it
according to your need. If you choose to use it, you must include the
comma that precedes TEMP, as in this example:
PURGE K0356774,TEMP
This command line removes a temporary file named K0356774 from the disk.
If no such temporary file exists, the operating system displays an
warning message telling you that it could not find that (temporary) file.
Syntax diagrams
Syntax diagrams help in understanding the parts of a command--its
parameters--their use, and their relationship to each other. When the
command is a simple one, its syntax diagram is relatively easy to follow.
But when the command is complex, when it has many parameters, its syntax
diagram does appear formidable.
But, despite any potential complexity, all syntax diagrams follow simple
rules.
What follows is not a complete lesson in reading syntax diagrams.
Instead, it is an introduction intended to make syntax diagrams look a
little less formidable.
Variables and keywords
The syntax diagram for the PURGE command is simple.
PURGE filereference[,TEMP]
The parameter filereference is in italic lettering to indicate that it is
a variable. Entering PURGE filereferenceReturn would produce an error.
Because filereference is in italics, you must use the name of a file in
its place when you execute the PURGE command:
PURGE ACCTRPTReturn
Variable--required parameter.
What is a variable? You might think of it as an empty box. Until you
put something inside it, the box is just an empty box. When you put
something inside it, it becomes a box of....What did you put inside the
box?
For a computer, a variable is much like an empty box. It is an area of
memory waiting for something to fill it. In a syntax diagram, a formal
name such as filereference represents just such an empty box. But
filereference is also a parameter of the command PURGE.
For PURGE, the parameter filereference is a variable. That means that
when you execute PURGE, it will look for something in a memory box called
filereference.
If it finds the name of an existing file, it erases that file.
You put the name of a file into that memory box when you execute PURGE
this way:
PURGE ACCTRPT
Since filereference is a required parameter of PURGE, the command expects
to find something in the filereference memory box. If it finds nothing
(because you left out the name of a file), it reports an error to the
computer and the computer puts an error message on your video screen.
PURGE 6Return
will not work. 6 is not the name of a file, but a number.
PURGE X6
will work, if X6 is the name of a file in your current group and if the
file is not protected in some way.
________________________________________________________________________
| |
|Worth Knowing |
| |
|In the Help Facility, variables appear not in italic lettering, but in|
|plain lowercase letters. |
________________________________________________________________________
Variable--optional parameter.
Optional parameters are variables, too, but with a difference. The
LISTFILE command serves as an example. Its syntax diagram includes this
parameter:
LISTFILE [filename]
Here, filename is an optional parameter.
There is a memory box called filename, too. But for LISTFILE that box
always has something in it. What is there is a value that says: all
files in the group. And that is what LISTFILE displays if you do not
specify a file name. Unlike PURGE with its required parameter, LISTFILE
can be quite happy even if you do not specify a file name (because there
is always something for it to find in the memory box called filename).
LISTFILE ACCTRPT
When you specify a file name in this fashion, the file ACCTRPT goes into
the memory box called filename. When LISTFILE peeks into that memory
box, it finds--not "all files in the group," but the name of one
particular file, ACCTRPT.
* A required parameter (variable) is a memory box that that starts
out empty. It must have something put into it. And you must put
that something in it.
* An optional parameter (variable) is a memory box that starts out
with a default value already in it. You can choose to put
something else into the memory box, or you can choose to accept
what is already there. If you choose to accept what is already
there, the computer will take some default action. By default,
the command will act on whatever it finds in the memory box (or
boxes) that belong to it.
Under the Parameters heading of the PURGE command in the Command
Reference - HP 3000 Series 9X8LX (B3820-90007), you will find a
description of each parameter of the PURGE command. That description
tells you what is appropriate to use.
Keyword--not variable.
Look again at the syntax diagram for PURGE.
PURGE filereference[,TEMP]
,TEMP is also a parameter. It happens to be optional, too, because it is
surrounded by brackets. But it is not a variable. It is a keyword. It
appears in uppercase letters. It instructs PURGE to remove a temporary
file, rather than a permanent one.
A keyword is not a variable. It is not an empty box into which you can
put what you like. In order to use a keyword, you must enter the keyword
exactly as it appears in the syntax diagram. You may enter the word in
uppercase letters or in lowercase letters. Entering this:
PURGE ACCTRPT,TIMEReturn
will produce an error. In fact, entering anything other than ,TEMP after
the name of a file will produce an error.
Because TEMP is optional, you do not have to use it when you enter the
command. But if you do decide to use it (in order to erase a temporary
file), TEMP is the only value that PURGE can accept.
The elements of syntax
There are valuable "clues" in any syntax diagram:
Syntax Elements
-------------------------------------------------------------------------------------------
| |
| Element Name Meaning |
| |
-------------------------------------------------------------------------------------------
| |
| [ ] Brackets What is inside is optional. |
| |
| Pay attention to the punctuation, the comma or the |
| semicolon if there is one. |
| |
-------------------------------------------------------------------------------------------
| |
| { } Braces What is inside is required. |
| |
| Pay attention to any square brackets that may |
| surround the braces, as in this construction: |
| |
| |
| [ { beta }] |
| SOMECOMMAND alpha[ ;{ gamma}] |
| [ { delta}] |
| In the MPE/iX Help Facility, it might look like |
| this: |
| |
| |
| [ { beta} ] |
| SOMECOMMAND ;alpha[ ;{ gamma}] |
| [ { delta}] |
| This construction shows up to alert you that |
| choices are available. But it tells you that your |
| choices are restricted. |
| |
| Here, you may choose whether to use beta, gamma, or |
| delta or simply ignore them all. But, if you |
| choose to use one of them, you must use beta or |
| gamma or delta--but only one of them, not two or |
| three. |
| |
-------------------------------------------------------------------------------------------
Table 7-0. Syntax Elements (cont.)
-------------------------------------------------------------------------------------------
| |
| Element Name Meaning |
| |
-------------------------------------------------------------------------------------------
| |
| lowercase Lowercase Letters What is shown in lowercase letters is a variable. |
| lowercase In your documents, variables appear in italic |
| lowercase lettering. In the Help Facility, |
| variables appear in plain lowercase lettering. |
| |
| If it is an optional parameter, you may give the |
| command some information in place of that variable |
| when you type the command line. If it is a |
| required parameter, you must give the command some |
| information in place of that variable when you type |
| the command line. |
| |
| For PURGE, a file name is required. For LISTFILE, |
| a file name is optional. |
| |
-------------------------------------------------------------------------------------------
| |
| UPPER- Uppercase Letters What is shown in uppercase letters is a keyword. |
| CASE |
| If you are going to use a keyword (or something |
| "attached" to a keyword by an equal sign =), you |
| must enter the keyword exactly as it is spelled. |
| |
| What is attached to a keyword by an equal sign is |
| usually a variable. |
| |
-------------------------------------------------------------------------------------------
| |
| , and ; Comma, Semicolon Separators or place-holders. |
| |
| Commas and semicolons tell the computer where one |
| parameter ends and another begins. If you omit an |
| optional parameter that has punctuation, be sure to |
| enter the comma or semicolon on the command line; |
| otherwise, the computer is likely to become lost or |
| confused. If it becomes lost or confused, it will |
| show you an error message or--worse--do something |
| unexpected. |
| |
-------------------------------------------------------------------------------------------