CharConverter

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.ibm.as400.access
Class CharConverter

java.lang.Object
  com.ibm.as400.access.CharConverter

All Implemented Interfaces:: Serializable

public class CharConverter
extends Object
implements Serializable

A character set converter between Java String objects and IBM i native code pages.

Note that in the past few releases, several constructors were deprecated because they did not accept a system object as an argument. Due to recent changes in the behavior of the character conversion routines, this system object is no longer necessary.

See Also:: AS400Text, Serialized Form

Constructor Summary
Constructor and Description
`CharConverter()` Constructs a CharConverter object using a "best guess" based on the default Locale.
`CharConverter(int ccsid)` Constructs a CharConverter object using the specified CCSID.
`CharConverter(int ccsid, AS400 system)` Constructs a CharConverter object using the specified CCSID and system.
`CharConverter(String encoding)` Constructs a CharConverter object using the specified character encoding.

Method Summary
Modifier and Type	Method and Description
`static String`	`byteArrayToString(AS400 system, byte[] source)` Converts the specified bytes into a String.
`String`	`byteArrayToString(byte[] source)` Converts the specified bytes into a String.
`String`	`byteArrayToString(byte[] source, int offset)` Converts the specified bytes into a String.
`String`	`byteArrayToString(byte[] source, int offset, int length)` Converts the specified bytes into a String.
`String`	`byteArrayToString(byte[] source, int offset, int length, BidiConversionProperties properties)` Converts the specified bytes into a String.
`String`	`byteArrayToString(byte[] source, int offset, int length, int type)` Converts the specified bytes into a String.
`static String`	`byteArrayToString(int ccsid, AS400 system, byte[] source)` Converts the specified bytes into a String.
`static String`	`byteArrayToString(int ccsid, byte[] source)` Converts the specified bytes into a String.
`static String`	`convertIFSQSYSPathnameToJobPathname(String qsysData, int jobCCSID)` Converts a QSYS pathname String obtained from the IFS classes into a String suitable for use with other Toolbox services such as CommandCall and DataQueues.
`static String`	`convertJobPathnameToIFSQSYSPathname(String jobData, int jobCCSID)` Converts a pathname String obtained from a Toolbox host server (such as CommandCall or DataQueue) to a QSYS pathname suitable for use with the IFS classes.
`int`	`getCcsid()` Returns the CCSID of this conversion object.
`String`	`getEncoding()` Returns the encoding of this conversion object.
`static boolean`	`isFaultTolerantConversion()` Indicates if conversion is fault tolerant.
`static void`	`setFaultTolerantConversion(boolean faultTolerantConversion)` Enables fault tolerant conversion.
`static byte[]`	`stringToByteArray(AS400 system, String source)` Converts the specified String into bytes.
`static byte[]`	`stringToByteArray(int ccsid, AS400 system, String source)` Converts the specified String into bytes.
`static byte[]`	`stringToByteArray(int ccsid, String source)` Converts the specified String into bytes.
`byte[]`	`stringToByteArray(String source)` Converts the specified String into bytes.
`byte[]`	`stringToByteArray(String source, BidiConversionProperties properties)` Converts the specified String into bytes.
`void`	`stringToByteArray(String source, byte[] destination)` Converts the specified String into bytes.
`void`	`stringToByteArray(String source, byte[] destination, int offset)` Converts the specified String into bytes.
`void`	`stringToByteArray(String source, byte[] destination, int offset, int length)` Converts the specified String into bytes.
`void`	`stringToByteArray(String source, byte[] destination, int offset, int length, BidiConversionProperties properties)` Converts the specified String into bytes.
`void`	`stringToByteArray(String source, byte[] destination, int offset, int length, int type)` Converts the specified String into bytes.
`byte[]`	`stringToByteArray(String source, int type)` Converts the specified String into bytes.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

CharConverter

public CharConverter()

: Constructs a CharConverter object using a "best guess" based on the default Locale.

CharConverter

public CharConverter(String encoding)
              throws UnsupportedEncodingException

Constructs a CharConverter object using the specified character encoding.

Parameters:: encoding - The name of a character encoding.
Throws:: UnsupportedEncodingException - If the encoding is not supported.

CharConverter

public CharConverter(int ccsid)
              throws UnsupportedEncodingException

Constructs a CharConverter object using the specified CCSID.

Parameters:: ccsid - The CCSID of the IBM i text.
Throws:: UnsupportedEncodingException - If the ccsid is not supported.

CharConverter

public CharConverter(int ccsid,
                     AS400 system)
              throws UnsupportedEncodingException

Constructs a CharConverter object using the specified CCSID and system.

Parameters:: ccsid - The CCSID of the IBM i text.; system - The system object representing the system with which to connect.
Throws:: UnsupportedEncodingException - If the ccsid is not supported.

Method Detail

byteArrayToString

public String byteArrayToString(byte[] source)

Converts the specified bytes into a String.

Parameters:: source - The bytes to convert.
Returns:: The resultant String.

byteArrayToString

public String byteArrayToString(byte[] source,
                                int offset)

Converts the specified bytes into a String.

Parameters:: source - The bytes to convert.; offset - The offset into the source array for the start of the data.
Returns:: The resultant String.

byteArrayToString

public String byteArrayToString(byte[] source,
                                int offset,
                                int length)

Converts the specified bytes into a String.

Parameters:: source - The bytes to convert.; offset - The offset into the source array for the start of the data.; length - The number of bytes of data to read from the array.
Returns:: The resultant String.

byteArrayToString

public String byteArrayToString(byte[] source,
                                int offset,
                                int length,
                                int type)

Converts the specified bytes into a String.

Parameters:: source - The bytes to convert.; offset - The offset into the source array for the start of the data.; length - The number of bytes of data to read from the array.; type - The bidi string type, as defined by the CDRA (Character Data Representataion Architecture). See BidiStringType for more information and valid values.
Returns:: The resultant String.
See Also:: BidiStringType

byteArrayToString

public String byteArrayToString(byte[] source,
                                int offset,
                                int length,
                                BidiConversionProperties properties)

Converts the specified bytes into a String.

Parameters:: source - The bytes to convert.; offset - The offset into the source array for the start of the data.; length - The number of bytes of data to read from the array.; properties - The bidi conversion properties.
Returns:: The resultant String.

byteArrayToString

public static String byteArrayToString(AS400 system,
                                       byte[] source)

Converts the specified bytes into a String.

Parameters:: system - The system object representing the system with which to connect.; source - The bytes to convert.
Returns:: The resultant String.

byteArrayToString

public static String byteArrayToString(int ccsid,
                                       AS400 system,
                                       byte[] source)
                                throws UnsupportedEncodingException

Converts the specified bytes into a String.

Parameters:: ccsid - The CCSID of the IBM i text.; system - The system object representing the system with which to connect.; source - The bytes to convert.
Returns:: The resultant String.
Throws:: UnsupportedEncodingException - If the ccsid is not supported.

byteArrayToString

public static String byteArrayToString(int ccsid,
                                       byte[] source)
                                throws UnsupportedEncodingException

Converts the specified bytes into a String. If the Toolbox does not possess a table for the given CCSID, nor does the JVM, an UnsupportedEncodingException is thrown.

Parameters:: ccsid - The CCSID of the IBM i text.; source - The bytes to convert.
Returns:: The resultant String.
Throws:: UnsupportedEncodingException - If the ccsid is not supported.

convertIFSQSYSPathnameToJobPathname

public static String convertIFSQSYSPathnameToJobPathname(String qsysData,
                                                         int jobCCSID)
                                                  throws UnsupportedEncodingException

Converts a QSYS pathname String obtained from the IFS classes into a String suitable for use with other Toolbox services such as CommandCall and DataQueues.

This method is meant to handle QSYS pathnames and other string data that was retrieved using the IFS classes. Object names in QSYS are stored in EBCDIC. The file server always returns names to the Toolbox IFS classes in Unicode, so the system must convert the name from EBCDIC to Unicode before returning it to the client. The system does this conversion using CCSID 37, not the file server job CCSID; however, the name may contain variant (but legal) codepoints. Specifically, the three legal variant EBCDIC codepoints for QSYS object names are 0x5B, 0x7B, and 0x7C. If the name retrieved using the Toolbox IFS classes is given to another Toolbox component such as CommandCall, the name will be converted to EBCDIC using the job CCSID for that particular component. If variant characters exist in the name, the resulting name used by the host server job may not be the same as the original name.

Here is a typical scenario in which this method will be needed. The user profile name CASH$FLOW exists on the system. In EBCDIC CCSID 37, it is comprised of the codepoints:

     0xC3 0xC1 0xE2 0xC8  0x5B  0xC6 0xD3 0xD6 0xE6

Note that the dollar sign '$' is codepoint 0x5B so it is one of the legal codepoints for a QSYS object pathname. Now, if this pathname is used in a CommandCall, such as "DLTUSRPRF CASH$FLOW", that command string will get converted to the CCSID of the host server job. If the host server job isn't running under CCSID 37, the resulting command string may not contain the dollar sign. For example, in CCSID 285 (United Kingdom) the codepoint 0x5B is actually an English pound sterling ('�' or Unicode 0x00A3). The dollar sign '$' is found at codepoint 0x4A instead. Hence, the "CASH$FLOW" in the command string will get converted to the following EBCDIC CCSID 285 codepoints:

     0xC3 0xC1 0xE2 0xC8  0x4A  0xC6 0xD3 0xD6 0xE6

That is not how the user profile name is stored in QSYS. The 0x4A codepoint should really be a 0x5B codepoint. So in this case, the command server will return an error message indicating the user profile was not found.

The solution is to use this method to replace the variant codepoints with codepoints that will correctly convert given the host server job CCSID. When given the string "CASH$FLOW" and the CCSID 285, this method will return the string "CASH�FLOW". If the CommandCall is issued with the string "DLTUSRPRF CASH�FLOW" and the job CCSID of the remote command host server is 285, it will correctly convert the pound sterling '�' into codepoint 0x5B, which is how the user profile name "CASH$FLOW" is actually stored in QSYS.

For more information, please see IBM i Information Center: CL and APIs: Control Language (CL): Naming within commands.

Parameters:: qsysData - The String in which to substitute variant QSYS characters.; jobCCSID - The CCSID of the job in which to convert the variant characters.
Returns:: The Unicode String with correctly substituted variant characters for use with host servers that convert based upon job CCSID.
Throws:: UnsupportedEncodingException - If the specified CCSID is not supported.
See Also:: convertJobPathnameToIFSQSYSPathname(java.lang.String, int)

convertJobPathnameToIFSQSYSPathname

public static String convertJobPathnameToIFSQSYSPathname(String jobData,
                                                         int jobCCSID)
                                                  throws UnsupportedEncodingException

Converts a pathname String obtained from a Toolbox host server (such as CommandCall or DataQueue) to a QSYS pathname suitable for use with the IFS classes.

See the javadoc for convertIFSQSYSPathnameToJobPathname for more information. This method essentially does the opposite of what convertIFSQSYSPathnameToJobPathname does. The specified jobData string has its variant characters substituted so that it can be used with the IFS classes. If given the String returned by this method, the file server will correctly convert the codepoints into the real QSYS object pathname using CCSID 37.

Parameters:: jobData - The String in which to substitute variant QSYS characters.; jobCCSID - The CCSID of the job in which to convert the variant characters.
Returns:: The Unicode String with correctly substituted variant characters for use with the IFS server that converts based upon CCSID 37.
Throws:: UnsupportedEncodingException - If the specified CCSID is not supported.
See Also:: convertIFSQSYSPathnameToJobPathname(java.lang.String, int)

getCcsid

public int getCcsid()

Returns the CCSID of this conversion object.

Returns:: The CCSID.

getEncoding

public String getEncoding()

Returns the encoding of this conversion object.

Returns:: The encoding.

isFaultTolerantConversion

public static boolean isFaultTolerantConversion()

Indicates if conversion is fault tolerant.

Returns:: true if conversion is fault tolerant, false otherwise.

setFaultTolerantConversion

public static void setFaultTolerantConversion(boolean faultTolerantConversion)

Enables fault tolerant conversion. Fault tolerant conversion allows incomplete EBCDIC character data to be converted without throwing an exception. This is a static setting and affects all subsequent character conversion. Fault tolerant conversion may adversly affect performance and memory usage during character conversion. The default is false.

Parameters:: faultTolerantConversion - true to enable fault tolerant conversion, false otherwise.