HP OpenVMS DCL Dictionary
CALL
Transfers control to a labeled subroutine within a command procedure.
Format
CALL label [parameter [...]]
Parameters
label
Specifies a label of 1 to 255 alphanumeric characters that appears as
the first item on a command line. A label cannot contain embedded
blanks. When the CALL command is executed, control passes to the
command following the specified label.
The label can precede or follow the CALL statement in the current
command procedure. A label in a command procedure must be terminated
with a colon (:). Labels for subroutines must be unique.
Labels declared in inner procedure levels are inaccessible from outer
levels, as in the following example:
$CALL B
$A: SUBROUTINE
$ B: SUBROUTINE
$ ENDSUBROUTINE
$ENDSUBROUTINE
|
In this example, the label B in subroutine A is inaccessible from the
outer procedure level.
parameter [...]
Specifies from one to eight optional parameters to pass to the command
procedure. Use quotation marks (" ") to specify a null
parameter. The parameters assign character string values to the symbols
named P1, P2, and so on in the order of entry, to a maximum of eight.
The symbols are local to the specified command procedure. Separate each
parameter with one or more spaces.
Setting bit 3 of DCL_CTLFLAGS to 1, specifies from one to sixteen
optional parameters to pass to the command procedure. Use quotation
marks (" ") to specify a null parameter. The parameters
assign character string values to the symbols named P1, P2, and so on
in the order of entry, to a maximum of sixteen. The symbols are local
to the specified command procedure. Separate each parameter with one or
more spaces. If you clear the bit 3 of DCL_CTLFLAGS, the default
parameters are set (that is, (P1, P2, ... P8)).
You can specify a parameter with a character string value containing
alphanumeric or special characters, with the following restrictions:
- The command interpreter converts alphabetic characters to uppercase
and uses blanks to delimit each parameter. To pass a parameter that
contains embedded blanks or lowercase letters, enclose the parameter in
quotation marks (" ").
- If the first parameter begins with a slash (/), you must enclose
the parameter in quotation marks.
- To pass a parameter that contains quotation marks and spaces,
enclose the entire string in quotation marks and use two sets of
quotation marks within the string. For example:
$ CALL SUB1 "Never say ""quit"""
|
When control transfers to SUB1, the parameter P1 is equated to the
following string:
If a string contains quotation marks and does not contain spaces,
the quotation marks are preserved in the string and the letters within
the quotation marks remain in lowercase. For example:
When control transfers to SUB2, the parameter P1 is equated to the
string:
To use a symbol as a parameter, enclose the symbol in single quotation
marks (` ') to force symbol substitution. For example:
$ NAME = "JOHNSON"
$ CALL INFO 'NAME'
|
The single quotation marks cause the value "JOHNSON" to be
substituted for the symbol `NAME'. Therefore, the parameter
"JOHNSON" is passed as P1 to the subroutine INFO.
Description
The CALL command transfers control to a labeled subroutine within a
command procedure. The CALL command is similar to the @ (execute
procedure) command in that it creates a new procedure level. The
advantage of the CALL command is that it does not require files to be
opened and closed to process the procedure. Using the CALL command also
makes managing a set of procedures easier because they can all exist in
one file rather than in several files.
When you use the CALL command to transfer control to a subroutine, a
new procedure level is created and the symbols P1 to P8 are assigned
the values of the supplied arguments. When bit 3 of DCL_CTLFLAGS is set
to 1, you can use the CALL command to transfer control to a subroutine,
a new procedure level is created and the symbols P1 to P16 are assigned
the values of the supplied arguments. Execution then proceeds until an
EXIT command is encountered. At this point, control is transferred to
the command line following the CALL command.
Procedures can be nested to a maximum of 32 levels, which includes any
combination of command procedure and subroutine calls. Local symbols
and labels defined within a nested subroutine structure are treated the
same way as if the routines had been invoked with the @ command; that
is, labels are valid only for the subroutine level in which they are
defined.
Local symbols defined in an outer subroutine level are available to any
subroutine levels at an inner nesting level; that is, the local symbols
can be read, but they cannot be written to. If you assign a value to a
symbol that is local to an outer subroutine level, a new symbol is
created at the current subroutine level. However, the symbol in the
outer procedure level is not modified.
The SUBROUTINE and ENDSUBROUTINE commands define the beginning and end
of a subroutine. The label defining the entry point to the subroutine
must appear either immediately before the SUBROUTINE command or on the
same command line.
A subroutine can have only one entry point. The subroutine must begin
with the SUBROUTINE command as the first executable statement. If an
EXIT command is not specified in the procedure, the ENDSUBROUTINE
command functions as an EXIT command.
The SUBROUTINE command performs two different functions depending on
the context in which it is executed. If executed as the result of a
CALL command, it initiates a new procedure level, defines the
parameters P1 to P8 as specified in the CALL statement, and begins
execution of the subroutine. If bit 3 of DCL_CTLFLAGS is set to 1, CALL
command allows you to define the parameters up to P16. If the
SUBROUTINE verb is encountered in the execution flow of the procedure
without having been invoked by a CALL command, all the commands
following the SUBROUTINE command are skipped until the corresponding
ENDSUBROUTINE command is encountered.
Note
The SUBROUTINE and ENDSUBROUTINE commands cannot be abbreviated to
fewer than 4 characters.
|
Qualifier
/OUTPUT=filespec
Writes all output to the file or device specified. By default, the
output is written to the current SYS$OUTPUT device and the output file
type is .LIS. System responses and error messages are written to
SYS$COMMAND as well as to the specified file. If you specify /OUTPUT,
the qualifier must immediately follow the CALL command. The asterisk
(*) and the percent sign (%) wildcard characters are not allowed in the
output file specification.
You can also redefine SYS$OUTPUT to redirect the output from a command
procedure. If you place the following command as the first line in a
command procedure, output will be directed to the file you specify:
$ DEFINE SYS$OUTPUT filespec
|
When the procedure exits, SYS$OUTPUT is restored to its original
equivalence string. This produces the same result as using the /OUTPUT
qualifier when you execute the command procedure.
Example
|
$
$! CALL.COM
$
$! Define subroutine SUB1
$!
$ SUB1: SUBROUTINE
.
.
.
$ CALL SUB2 !Invoke SUB2 from within SUB1
.
.
.
$ @FILE !Invoke another procedure command file
.
.
.
$ EXIT
$ ENDSUBROUTINE !End of SUB1 definition
$!
$! Define subroutine SUB2
$!
$ SUB2: SUBROUTINE
.
.
.
$ EXIT
$ ENDSUBROUTINE !End of SUB2 definition
$!
$! Start of main routine. At this point, both SUB1 and SUB2
$! have been defined but none of the previous commands have
$! been executed.
$!
$ START:
$ CALL/OUTPUT=NAMES.LOG SUB1 "THIS IS P1"
.
.
.
$ CALL SUB2 "THIS IS P1" "THIS IS P2"
.
.
.
$ EXIT !Exit this command procedure file
|
The command procedure in this example shows how to use the CALL command
to transfer control to labeled subroutines. The example also shows that
you can call a subroutine or another command file from within a
subroutine.
The CALL command invokes the subroutine SUB1, directing output to the
file NAMES.LOG and allowing other users write (W) access to the file.
The subroutine SUB2 is called from within SUB1. The procedure executes
SUB2 and then uses the @ (execute procedure) command to invoke the
command procedure FILE.COM.
When all the commands in SUB1 have executed, the CALL command in the
main procedure calls SUB2 a second time. The procedure continues until
SUB2 has executed.
| 
