vs
Class SystemCall

java.lang.Object
  vs.SystemCall

public class SystemCall

extends java.lang.Object

Provides the capability to call a native OpenVMS routine. This class is really a window to LIB$FIND_IMAGE_SYMBOL. So all the same restrictions are implied here. Such as, the routine needing to be present in a shareable image and that image either being present in SYS$SHARE or locatable with an appropriately defined logical.

The following is an example of calling LIB$PUT_OUTPUT using this mechanism. This is just a demonstration as the LIB$PUT_OUTPUT routine is already provided in the LibRoutines class.

 SystemCall lib$put_output = new SystemCall("LIB$PUT_OUTPUT",
                                            "LIBRTL");

 lib$put_output.call(new VMSparams[] {
                         new ByDesc("hello, world!")
                     });
 

The equivalent PL/I code looks something like this:

 declare lib$put_output entry(character(*));

 call lib$put_output(descriptor('hello, world!'));
 

For further information on the LIB$FIND_IMAGE_SYMBOL routine and its restrictions, please see the manual

See Also:

HP OpenVMS RTL Library (LIB$) Manual: LIB$FIND_IMAGE_SYMBOL

Constructor Summary

SystemCall(java.lang.String procName, java.lang.String shareableImage)
Loads a routine from a shareable image (run-time library).

Method Summary

int	call(VMSparam[] arg) Calls the routine associated with thi SystemCall object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SystemCall

public SystemCall(java.lang.String procName,
                  java.lang.String shareableImage)
           throws java.lang.UnsatisfiedLinkError

Loads a routine from a shareable image (run-time library).

The run-time library shareableImage is searched for the routine identified by procName. The work is done by the LIB$ Run-time Library function LIB$FIND_IMAGE_SYMBOL. So all appropriate rules and restrictions to the use of LIB$FIND_IMAGE_SYMBOL are implied here.

In the event that the routine can not be found the exception UnsatisfiedLinkError will be thrown.

Parameters:

procName - Symbolic name of thr routine to be loaded.

shareableImage - Name of shareable image containing procName.

Throws:

java.lang.UnsatisfiedLinkError - An error occurred when locating the symbol procName

Method Detail

call

public int call(VMSparam[] arg)

Calls the routine associated with thi SystemCall object.

The routine located in the initial instantiation of the SystemCall object can now be called. The mechanism is reminiscent of the LIB$ Run-Time Library function LIB$CALLG.

An array of arguments is constructed (specifying calling mechanism) and passed to the native routine. The results is then returned in the form of an int which can then in turn be interpreted appropriately.

Parameters:

arg - An array of VMSparam objects containing the arguments to be passed and their passing mechanisms.

Returns:

Although the return value is always int, this can be interpreted independently by the caller.