HP 3000 Manuals HP 3000 Manuals
CALL
Transfers execution to another Transact program or to a Report/V or
Inform/V program.
Syntax
CALL file-name[([password,][mode])][,option-list];
CALL passes control to another Transact program or to a Report/V or
Inform/V program. The called program operates as if it were the main
program, but it shares all or part of the calling program's data register
space. The called program returns to the calling program with an EXIT
statement. The calling program then resumes execution of the statement
following the CALL statement.
When a CALL from a main program is executed, any open files or data sets
remain open across the call. However, when the called program is an
Inform/V or Report/V program, the database passwords must be specified
again. The passwords can be specified programmatically from the terminal
or in the stream file.
When a CALL from a called system is executed, files opened by the system
that made the call do not remain open for use by the system it calls.
While a called Transact program is executing, both the calling program
and the called program are in the memory stack and share the data
register. Called Inform/V or Report/V programs do not share the same
memory stack or data register.
If a called Report/V or Inform/V program uses any database or data file
named in the SYSTEM statement of the calling Transact program, that
database or file must be opened in a non-exclusive mode. Furthermore,
the open mode must be compatible with the open mode used by Report/V or
Inform/V (default mode 5), or the open mode used by Report/V or Inform/V
must be altered to be compatible with the mode used by Transact. Any
database locks should be released before the CALL statement.
The Transact/iX compiler can generate code for two different types of
calls, referred to as "static" and "dynamic" calls.
Static calls are direct procedure calls to the called program. Static
calls must meet the following requirements:
* The name of the called program must be available at load time.
* Either the object code for the called program must be in an RL or
in an RSOM file at link time or the executable code for the called
program must be in an XL at load time.
* a literal program name must be used in the CALL statement.
* The DYNAMIC_CALLS option must be off.
Dynamic calls use the MPE/iX HPGETPROCPLABEL intrinsic to load the called
program at run time. Dynamic calls must meet the following requirements:
* The object code for the called program must be in an XL. However,
only those programs that are actually called at run time need to
be present in the XL.
* Either a variable program name must be used in the CALL statement
or the DYNAMIC_CALLS option must be on.
The name of the called program does not need to be available until run
time.
There are advantages and disadvantages to both types of call. The
primary advantage of static calls over dynamic calls is superior run-time
performance. Dynamic calls must use HPGETPROCPLABEL whenever a CALL
statement is executed, and this intrinsic must search the various
libraries and load the requested program. With static calls, the called
programs are loaded when the main program is loaded and the run-time
overhead is negligible for most applications.
However, dynamic calls have the advantage that the name does not need to
be known at compile time. Therefore, CALL statements that use a variable
for the called program name are always compiled as dynamic calls.
A further advantage is that dynamic calls do not require the object code
for the called programs to be available until the CALL statement is
actually executed. Therefore, dynamic calls allow a main program to be
executed even if some of the called programs it references have not yet
been compiled (or even written), as long as the main program does not
attempt to actually call any of the missing programs.
Statement Parts
file-name The name of one of the following:
* Another Transact program (as specified in a
SYSTEM statement).
* A Report/V program (as specified in a REPORT
statement).
* An Inform/V program (as specified in the
report name of the catalog).
If file-name names an Inform/V file or Report/V
file, the "Report" or "Inform" option must be
specified in the option-list. file-name can also
be specified as (item-name[(subscript)]), where
item-name is the name of an item that contains the
name of the program or report to be executed. A
subscript is allowed if the referenced item is an
array. (See "Array Subscripting" in Chapter 3.)
file-name can be fully qualified as
file-name.group.account
If (item-name[(subscript)]) is specified, the call
is generated dynamically at run time. If file-name
is specified, then the call can be either static or
dynamic, depending on the compile options
specified. (See the discussion of compiler options
in Chapter 9.)
password A password for access to the database used by the
called program. This parameter is optional,
required only if the called program does not
specify a database password in its SYSTEM statement
or if the database is not already opened by the
called program. Transact prompts for a password at
run time if it is not specified here. If the
password is in both places, the password specified
in the SYSTEM statement of the called program takes
precedence.
password can be specified as:
"text-string" The database password.
item-name The name of an item
[(subscript)] containing the database
password. A subscript is
allowed if the item being
referenced is an array item.
It is possible to supply the called program with
more than one password. This can be accomplished
by defining a compound item of type X or U, where
the size of each element in the compound is 8
characters.
If a list of passwords is passed to the called
program, the first password on the list is used to
open the first database specified in the SYSTEM
statement, the second password on the list is used
to open the second database specified, and so on.
If only one password is passed, it opens the first
database specified in the SYSTEM statement with
that password as well as subsequent specified
databases that have no password.
mode The mode in which the database used by the called
program is to be opened. This parameter is
optional, and can be specified here if the SYSTEM
statement in the called program does not specify
it; if mode is specified both places, the mode
specified in the called program takes precedence.
Mode can be specified as:
digit Number 1 to 8. Default=1. A
digit is only valid when
calling another Transact
program.
item-name Name of item containing mode
[(subscript)] value. A subscript is
allowed if the item being
referenced is an array item.
It is possible to specify a list of modes to be
passed to the called program. It is done by
passing a compound item of type I(2). The mode
list can be passed only if a password list is also
passed. Like the password list, the mode list is
used to open each of the databases specified in the
SYSTEM statement with a different mode.
option-list One or more of the following options separated by
commas:
DATA=item-name The location in the data register
[(subscript)] of the calling program where a
called Transact program can begin
using space. This space includes
the location of the specified
item. If item-name is an "*",
the called program cannot use any
space already used by the calling
program. A subscript is allowed
if the item being referenced is
an array item. (See "Array
Subscripting" in Chapter 3.)
Although the contents of the data
register can be passed via a CALL
statement, the list register
contents are not. Therefore, the
called program must set up its
own list register before
execution.
If no DATA= is specified, the
called system will start
overlaying the calling program's
data register with its own
list/data registers. The item
must start on a 16-bit boundary.
SIZE=number The number of 16-bit words of
data register space that a called
Transact program can use. If
DATA=item-name is also specified,
space starts at the location
assigned to item-name. This
space cannot be larger than the
number of unused 16-bit words in
the data register and must start
on a 16-bit word boundary.
________________________________
NOTE When Transact CALLs a
Transact subprogram, the
data register space
allocated to the subprogram
is determined by the DATA=
and SIZE= parameters of the
CALL statement, not the
DATA= option of the SYSTEM
statement in the called
program. The maximum size
of the data register,
however, is determined by
the DATA= option of the
main program's SYSTEM
statement.
________________________________
SWAP A request to write part of the
caller's stack space out to a
temporary MPE file before the
CALL is made. When control is
transferred back to the calling
program, the MPE file is read
back and the stack is restored.
Use of the SWAP option increases
the number of nested calls that
can be made before stack space is
exhausted. There is some
overhead, however, associated
with using the SWAP option.
Therefore it should be used only
if available stack space is very
limited.
INFORM A request to run the Inform/V
report specified by file-name.
None of the Inform/V menus are
displayed. If needed, a database
password is prompted for. After
the Inform/V report is complete,
control returns to the statement
following the call.
REPORT A request to run the Report/V
report specified by file-name.
If needed, a database password is
prompted for. After the report
is complete, control returns to
the statement following the call.
STATUS When the STATUS option is used,
the success of a CALLed Transact
program is described by the value
in the 32-bit status register.
After a called program completes,
Transact sets the calling
program's 32-bit status register
to one of the values in the table
below.
[REV BEG]
Status Meaning
Register
Value
0 No errors were detected by
Transact within the called
program.
-2 An error was detected by
Transact within the called
program.
A 0 will be returned in the
status register in cases where
the error is handled by the
programmer or end user. A 0 will
be returned in the following
cases:
* Data errors or command
errors for interactive
programs occur.
* Error messages are
suppressed by the
subprogram using the
STATUS option or the NOMSG
option.
* Error messages are
suppressed by the ERROR=
option on the LET verb.
[REV END]
When the STATUS option is not
used on the CALL verb, Transact
does not alter the calling
program's status register.
The STATUS option can be used
only with called Transact
programs. The Transact compiler
returns an INVALID OPTION error
message when used with called
Report/V and Inform/V programs.
Limitations on the CALL Statement
The following limitations apply to the CALL statement when you use the
Transact/iX compiler:
* Calls from a Transact/iX program can only be made to Transact
programs that have been compiled with the Transact/iX compiler.
The called program must be linked to the calling program in one of
the ways described above.
* The SWAP option is not supported by Transact/iX and is ignored if
it appears on a CALL statement. Since MPE/iX systems have far
more data space than MPE V systems, this option is not needed.
The Transact/iX compiler issues an informational message if the SWAP
option is encountered:
*INFO: THE 'SWAP' OPTION FOR THE CALL VERB IS NOT NECESSARY ON AN MPE/iX SYSTEM
Floating Point Format
When passing parameters or data that access real numbers, the called
program must be compiled with the same real-number format as the main
program.
Examples
The first example calls the INVMGT program, provides a password for
opening any databases used by INVMGT, and allows the database to be
opened in mode 7 for exclusive read access. INVMGT can use data register
space beginning at the item named ORDER, and it can use 1000 16-bit words
of space.
CALL INVMGT ("X43",7),
DATA = ORDER,
SIZE = 1000;
In the next example, the user is prompted for the name of the application
to run. Then the password needed to access the database is retrieved
from the PASSWORD-DSET detail set.
DATA(MATCH) SYSNAME("Enter name of application to run :");
SET(KEY) LIST(USER);
GET(CHAIN) PASSWORD-DSET, LIST(SYSNAME, PASSWORD);
CALL (SYSNAME) (PASSWORD, 5),
DATA=*;
The next example shows how multiple passwords and multiple modes can be
passed to a called program.
DEFINE(ITEM) PASSWORD-LIST 2 X(8) :
MODE-LIST 2 I(2) :
MODE-ITEM I(2) = MODE-LIST(1);
MOVE (PASSWORD-LIST) = "PASS1 PASS2 ";
LET (MODE-ITEM) = 1;
LET OFFSET(MODE-ITEM) = 2;
LET (MODE-ITEM) = 5;
CALL ORDPROC (PASSWORD-LIST,MODE-LIST), DATA=*;
This example shows the programs MAIN and CALC. MAIN uses a CALL verb with
and without the STATUS option. The status register is initialized to the
value "111" and tested after each CALL verb for the expected status
register value. Without a STATUS option on the CALL verb, MAIN's status
register will not be changed. When a STATUS option is used, the status
register will be set to -2 because of the arithmetic error in the caller
program CALC.
In the called program CALC, the arithmetic operation fails. Although the
LET verb results in an error, the status register for CALC is unchanged.
SYSTEM MAIN;
DEFINE(ITEM) ZEROS I(5,,2):
PSTATUS I(5,,4);
LIST ZEROS,INIT:PSTATUS,INIT;
LET STATUS = 111;
<<Example of CALL verb without the STATUS option.>>
CALL CALC, DATA=ZEROS;
IF STATUS = 111 then display "MAIN's STATUS IS STILL 111.";
<<Example of CALL verb with the STATUS option.>>
CALL CALC, DATA=ZEROS,STATUS;
IF STATUS = -2 THEN DISPLAY "MAIN's STATUS IS NOW -2.";
EXIT;
END;
SYSTEM CALC;
DEFINE(ITEM) ZEROS I(5,,2):
PSTATUS I(5,,4);
LIST ZEROS:PSTATUS;
LET STATUS = 222;
LET (ZEROS) = (ZEROS) / (ZEROS);
<<Causes an arithmetic error.>>
LET (PSTATUS) = STATUS;
DISPLAY "CALC's STATUS REGISTER AFTER ERROR>>",LINE=2:PSTATUS,NOHEAD;
EXIT;
END;
************************** RESULTS *****************************
ERROR: INTEGER DIVIDE BY ZERO (PROG 54,6) [CALC]
CALC's STATUS REGISTER AFTER ERROR>> 222
MAIN's STATUS IS STILL 111.
*ERROR: INTEGER DIVIDED BY ZERO (PROG 54,6) [CALC]
CALC's STATUS REGISTER AFTER ERROR>> 222
MAIN's STATUS IS NOW -2.
This example shows modifications to the programs MAIN and CALC. The
program MAIN uses the CALL verb with and without the STATUS option. The
status register is still set to the value "111" and tested after each
CALL verb for the expected status. Without a STATUS option on the CALL
verb, MAIN's status register will not be changed. When a STATUS option
is used, MAIN's status register will be set to 0 because the error in the
called program is handled by the called program.
In the called program CALC, we still perform an arithmetic operation
which causes an error. The ERROR= option which has been added causes the
status register to be set to a value of 3 when the arithmetic operation
fails. The status register is not shared between programs, but the
program MAIN displays or checks the value stored in shared item PSTATUS.
SYSTEM MAIN;
DEFINE(ITEM) ZEROS I(5,,2):
PSTATUS I(5,,4);
LIST ZEROS,INIT:PSTATUS,INIT;
LET STATUS = 111;
<<Example of CALL verb without the STATUS option.>>
CALL CALC, DATA=ZEROS;
IF STATUS = 111 then display "MAIN's STATUS IS STILL 111.";
<<Example of CALL verb with the STATUS option.>>
CALL CALC, DATA=ZEROS,STATUS;
IF STATUS = 0 THEN DISPLAY "MAIN's STATUS IS NOW 0.";
DISPLAY "PSTATUS has a value of: ":PSTATUS,NOHEAD;
EXIT;
END;
SYSTEM CALC;
DEFINE(ITEM) ZEROS I(5,,2):
PSTATUS I(5,,4);
LIST ZEROS:PSTATUS;
LET (ZEROS) = (ZEROS) / (ZEROS), ERROR= NEXT-LINE(*);
<<Causes an error>>
NEXT-LINE;
LET (PSTATUS) = STATUS;
<<See LET verb for table of STATUS values. >>
DISPLAY "CALC's STATUS REGISTER AFTER ERROR>> ",LINE=2:PSTATUS,NOHEAD;
EXIT;
END;
************************** RESULTS *****************************
CALC's STATUS REGISTER AFTER ERROR>> 3
MAIN's STATUS IS STILL 111.
CALC's STATUS REGISTER AFTER ERROR>> 3
MAIN's STATUS IS NOW 0.
PSTATUS has a value of: 3
END OF PROGRAM