Compiling High-level Access Interfaces for Multi-site Software (CHAIMS) |
This is the most current version of the CHAIMS API for the main CHAIMS calls, as reflected in the BNF used by the compiler and the CHAIMS programs we have created and run. This is specified with reference to the the CORBA runtime. (It is possible that during the creation of the DCE runtime we may need to make a few changes to this API, but we'll try to avoid this situation.)
The SETUP call establishes communication with a designated megamodule.
setup_identifier
= SETUP ("megamodulename
", "hostname
", input_arg1 = "arg1", input_arg2 = "arg2")
setup_identifier
is an identifier for the connection. Future
invocations to the megamodule designated by megamodulename
are
specified using setup_identifier
.
See other CHAIMS calls below.
"megamodulename
" refers to the name of the megamodule as
it is registered at the server side. In CORBA terminology, this is
the server name as registered in the Implementation Repository. This
is required in the SETUP call and must be first in the argument list.
"hostname
" refers to the name of the machine that the
server is located on (or is the gateway server for the service; it's
possible the service consists of multiple servers). An
example of a hostname
used might be sole.stanford.edu.
This is required in the SETUP call and must be second in the argument
list.
input_arg1, input_arg2
are input arguments to the
megamodule. These are used to specify default arguments to the
megamodule.
There can be as many arguments declared as the megamodule
wrapper (or native CHAIMS megamodules) will support. The value of
the input argument is specified within quotations. Currently, only
input types that can be represented as strings are used or supported.
Order of the input arguments is irrelvant as long as they follow
megamodulename
and hostname
. No input
arguments are required.
For the CORBA runtime, the SETUP call produces the binding call necessary
to bind to a CORBA object. While there is a matching SETUP API in the
CHAIMS compliant RR server, we aren't currently using it as there isn't
any need to set default arguments like input_arg1
in the example above.
The SETUP call also creates, in the CORBA client code, an instantiation
of the megamodule
object (CORBA server name) which corresponds
to the unique
setup_identifier
specified by the megaprogrammer. The actual
name used in the CORBA client code is not the same, but the correspondence
is there.
The identifier setup_identifier
is not a return value
in the traditional sense; that is, the SETUP call does not return a
value from the megamodule which is assigned to the variable
setup_identifier
. I realize that it does look like a
traditional
return value since it is on the left hand side of an
equality. However, this is to provide a simple means for the
megaprogrammer to identify the connection.
The identifier assignment is required by
the CHAIMS compiler. The compiler will exit with an error if
the SETUP call does not have an assignment.
The INVOKE call starts the execution of a specified method.
invoke_identifier
= setup_identifier.INVOKE ("methodname
", input_arg1 = "arg1")
invoke_identifier
is an identifier for the invocation.
Since control is returned to the CHAIMS program, this is used when doing
EXTRACT and EXAMINE calls so that
the correct process is identified for those calls.
setup_identifier
is the SETUP identifier
created by the SETUP call. See SETUP
description above.
"methodname"
is the name of the method in the megamodule
that the megaprogrammer wishes to use. In the case of megamodules that
only offer one service, this may be the name of the megamodule itself.
This argument is required in the INVOKE call, and
must be first in the argument list.
input_arg1
is an input argument to the
megamodule. These are defined in the exact same manner as the
arguments to SETUP shown above.
Again, there can be as many arguments declared as the megamodule
wrapper (or native CHAIMS megamodules) will support. The value of
the input argument is specified within quotations. Currently, only
input types that can be represented as strings are used or supported.
Order of the input arguments is irrelvant as long as they follow
methodname
. No input arguments are required, but the
megamodule may indicate an error if input arguments are needed to
perform any useful calculations or services. The error would be
seen by the megaprogrammer when EXTRACT
is performed (or possibly EXAMINE).
Right now, the CORBA code that is created is not asychronous. I'm
working to fix this. Currently, a CHAIMS INVOKE call results in a
CORBA method invocation by the megamodule instansiation which was created
by the SETUP call above. The method invoked is methodname
.
The EXAMINE call is used to determine the state of the invocation
referred to by invoke_identifier
.
examine_output
= invoke_identifier
.EXAMINE ()
examine_output
is the data structure that holds the
result of the examine call.
invoke_identifier
is the invocation identifier assigned
in the INVOKE call above.
This call works like a traditional assignment. The variable
examine_output
is assigned the results of the call
to EXAMINE.
The compiler currently recognizes the result of the EXAMINE to be a character string. In other words, in the CORBA client code, the code is written such that the result of the call is assigned to a character string.
We do not have a megamodule that does anything approaching the concept for which the EXAMINE call was created. We have been able to test that the CORBA client code created is correct by returning a string from the megamodule, but our megamodules don't examine their own processes and return a descriptive result.
The EXTRACT call collects the results of an invocation within a data structure.
extract_output
= invoke_identifier
.EXTRACT ()
extract_output
is the data structure that holds the
results of the invocation.
invoke_identifier
is the invocation identifier assigned
in the INVOKE call above.
The assignment works like a traditional assignment in this case as well. The variable at the left hand side of the equality gets the value returned by the call on the right hand side of the equality.
Currently, extract_output is string based; the data structure expected is in the form of a series of chars. This is not working exactly right. While the call is being done correctly, the assignment is not right. This is a bug in the compiler and something else I'm trying to fix.
Prasanna wrote an input/output extraction that will take the
extract_output
and dump it to a screen, either local
or remote. This is TCP/IP based. If we assign it directly, this
routine works, but, as I said, there are problems in the assignment
from the EXTRACT call.
The TERMINATE call kills either a running invocation or a connection to the megamodule.
setup_identifier
.TERMINATE ()
invoke_identifier
.TERMINATE ()
setup_identifier
is the identifer for the connection
established by a call to SETUP. See above.
invoke_identifier
is the identifer for an invocation
established by a call to INVOKE. See above.
The TERMINATE call which is done using setup_identifier
produces the CORBA client code necessary to release the binding
created during the initial SETUP.
The call to TERMINATE using the invoke_identifer
does the same thing, for now. This is obviously wrong, but I am
undecided as to what code to generate that would stop a running
CORBA process (i.e., do I kill it from the client end, or do
I sent the request to a CHAIMS wrapper or megamodule that will
process the request to terminate the method as it sees fit).
I'm leaning towards the latter; opinions are welcome.