In JVM COBOL, you pass parameters to native COBOL entry points using the standard modes: by content, by reference and by value. Note that in native interoperation with JVM COBOL, parameter passing is controlled on the CALL statement, in the USING BY clauses. JVM COBOL does not inspect the USING information in the native COBOL entry point. For example:
JVM COBOL:
call "x" using by reference y
Native COBOL:
entry "x" using by value y
In the above example, 'entry x' receives a reference to y not the value of y despite the by value clause on the entry definition. This can cause undefined results.
JVM COBOL:
call "x" using by value y
C:
int x(int* y)
{...}
In this example the C will be expecting a pointer to y and it will receive the value of y.
We recommend that you use by content and by reference when calling native COBOL from JVM COBOL. The by value functionality is intended for interoperation with other languages like C and C++.
When a parameter is passed by reference, a copy of the item in the JVM COBOL is passed to the native code. When the call to the native has finished, any changes to the information made in the native code are copied back to the JVM COBOL. However, this does mean that memory is shared between the JVM and native environments. In fact, what is actually passed to the native code is a pointer to the copied data. This is useful if you are calling non-COBOL programs.
The implications of this are very important, particularly in multi-threaded environments. Any changes to reference parameters are not visible to the JVM COBOL calling program until the call has completed.
Arbitrarily complex group items (within the memory limitations) can be passed by reference. The group definition must be identical in the native and JVM COBOL source code and it must not contain USAGE POINTER items.
Strings (java.lang.Strings) and tables (java.lang.byte arrays) can be passed by reference. All other objects (types that inherit from java.lang.Object, including valuetypes) cannot be passed by reference (or by value - see below).
Passing parameters by content is the same as passing by reference, except that the data is not copied back into the JVM COBOL memory when the call has completed.
Any item that can be passed by reference can be passed by content.
In JVM COBOL, the only items that can be passed by value are as follows:
Only 32bit types are supported for returning items. Again, the recommended type is binary-long.
For example, where the native code uses GOBACK RETURNING x, x must be a 32-bit type. x is placed in the RETURN-VALUE special register of the RETURNING item, as defined in the CALL statement.