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 alphanumeric or national (Unicode) data from the object.

About this task

Services for Unicode: Use the following standard services to convert between jstring object references and COBOL USAGE NATIONAL data items. Use these services for applications that you intend to be portable between the workstation and the mainframe. 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
NewString¹	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
GetStringChars¹	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.
This service throws an exception if the system runs out of memory.

Services for EBCDIC: Use the following z/OS® services, an extension of the JNI, to convert between jstring object references and COBOL alphanumeric data (PIC X(n)).

Table 2. **Services that convert between jstring references and alphanumeric data**
Service	Input arguments	Return value
NewStringPlatform	The JNI environment pointer Pointer to the null-terminated EBCDIC character string that you want to convert to a jstring object Pointer to the jstring object reference in which you want the result Pointer to the Java encoding name for the string, represented as a null-terminated EBCDIC character string¹	Return code as a binary fullword integer: 0 Success. -1 Malformed input or illegal input character. -2 Unsupported encoding; the jstring object reference pointer is set to `NULL`.
GetStringPlatformLength	The JNI environment pointer jstring object reference for which you want the length Pointer to a binary fullword integer for the result Pointer to the Java encoding name for the string, represented as a null-terminated EBCDIC character string¹	Return code as a binary fullword integer: 0 Success. -1 Malformed input or illegal input character. -2 Unsupported encoding; the jstring object reference pointer is set to `NULL`. Returns, in the third argument, the needed length in bytes of the output buffer to hold the converted Java string, including the terminating null byte referenced by the second argument.
GetStringPlatform	The JNI environment pointer jstring object reference that you want to convert to a null-terminated string Pointer to the output buffer in which you want the converted string Length of the output buffer as a binary fullword integer Pointer to the Java encoding name for the string, represented as a null-terminated EBCDIC character string¹	Return code as a binary fullword integer: 0 Success. -1 Malformed input or illegal input character. -2 Unsupported encoding; the output string is set to a null string. -3 Conversion buffer is full.
If the pointer is `NULL`, the encoding from the Java file.encoding property is used.

These EBCDIC services are packaged as a DLL that is part of your IBM® Java Software Development Kit. For details about the services, see jni_convert.h in the IBM Java Software Development Kit.

Use CALL literal statements to call the services. The calls are resolved through the libjvm.x DLL side file, which you must include in the link step of any COBOL program that uses object-oriented language.

For example, the following code creates a Java String object from the EBCDIC string 'MyConverter'. (This code fragment is from the J2EE client program, which is shown in full in Example: J2EE client written in COBOL.)


Move z"MyConverter" to stringBuf
Call "NewStringPlatform" 
  using by value JNIEnvPtr 
                 address of stringBuf
                 address of jstring1
                 0
  returning rc

If the EBCDIC services are the only JNI services that you call from a COBOL program, you do not need to copy the JNI.cpy copybook. You also do not need to establish addressability with the JNI environment pointer.

Services for UTF-8: The Java Native Interface also provides services for conversion between jstring object references and UTF-8 strings. These services are not recommended for use in COBOL programs due to the difficulty in handling UTF-8 character strings on the z/OS platform.