Manipulating Java strings

COBOL represents Java String data in Unicode. To represent a Java String in a COBOL program, declare the string as an object reference of the jstring class. Then use JNI services to set or extract COBOL national (Unicode) or UTF-8 data from the object.

Services for Unicode: Use the following standard services to convert between jstring object references and COBOL USAGE NATIONAL data items. Access these services by using function pointers in the JNINativeInterface environment structure.

Table 1. Services that convert between jstring references and national data
Service Input arguments Return value
NewString1
  • The JNI environment pointer
  • A pointer to a Unicode string, such as a COBOL national data item
  • The number of characters in the string; binary fullword
jstring object reference
GetStringLength
  • The JNI environment pointer
  • A jstring object reference
The number of Unicode characters in the jstring object reference; binary fullword
GetStringChars1
  • The JNI environment pointer
  • A jstring object reference
  • A pointer to a boolean data item, or NULL
  • A pointer to the array of Unicode characters extracted from the jstring object, or NULL if the operation fails. The pointer is valid until it is released with ReleaseStringChars.
  • If the pointer to the boolean data item is not null, the boolean value is set to true if a copy is made of the string and to false if no copy is made.
ReleaseStringChars
  • The JNI environment pointer
  • A jstring object reference
  • A pointer to the array of Unicode characters that was returned from GetStringChars
None; the storage for the array is released.
  1. This service throws an exception if the system runs out of memory.

Services for UTF-8: You can use the following services, an extension of the JNI, to convert between jstring object references and UTF-8 strings. Use these services in programs that do not need to be portable to the mainframe. Access these services by using function pointers in the JNI environment structure JNINativeInterface.

Table 2. Services that convert between jstring references and UTF-8 data
Service Input arguments Return value
NewStringUTF1
  • The JNI environment pointer
  • A pointer to a null-terminated UTF-8 string
jstring object reference, or NULL if the string cannot be constructed
GetStringUTFLength
  • The JNI environment pointer
  • A jstring object reference
The number of bytes needed to represent the string in UTF-8 format; binary fullword
GetStringUTFChars1
  • The JNI environment pointer
  • A jstring object reference
  • A pointer to a boolean data item, or NULL
  • Pointer to an array of UTF-8 characters extracted from the jstring object, or NULL if the operation fails. The pointer is valid until it is released with ReleaseStringUTFChars.
  • If the pointer to the boolean data item is not null, the boolean value is set to true if a copy is made of the string and to false if no copy is made.
ReleaseStringUTFChars
  • The JNI environment pointer
  • A jstring object reference
  • A pointer to the UTF-8 string that was derived from the jstring argument by using GetStringUTFChars
None; the storage for the UTF-8 string is released.
  1. This service throws an exception if the system runs out of memory.