CharConverter

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

All Implemented Interfaces:

java.io.Serializable
```
public class CharConverter
extends java.lang.Object
implements java.io.Serializable
```
A character set converter between Java String objects and IBM i native code pages.
Note: Some methods of this class accept an array-valued argument in addition to arguments that specify an array offset and possibly also a length. All such methods will throw an ArrayIndexOutOfBoundsException if the offset and/or length are not valid for the array.

See Also:
AS400Text, Serialized Form

Constructor Summary

Constructors
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(java.lang.String encoding)` Constructs a CharConverter object using the specified character encoding.

Method Summary

Methods
Modifier and Type	Method and Description
`static java.lang.String`	`byteArrayToString(AS400 system, byte[] source)` Converts the specified bytes into a String.
`java.lang.String`	`byteArrayToString(byte[] source)` Converts the specified bytes into a String.
`java.lang.String`	`byteArrayToString(byte[] source, int offset)` Converts the specified bytes into a String.
`java.lang.String`	`byteArrayToString(byte[] source, int offset, int length)` Converts the specified bytes into a String.
`java.lang.String`	`byteArrayToString(byte[] source, int offset, int length, BidiConversionProperties properties)` Converts the specified bytes into a String.
`java.lang.String`	`byteArrayToString(byte[] source, int offset, int length, int type)` Converts the specified bytes into a String.
`static java.lang.String`	`byteArrayToString(int ccsid, AS400 system, byte[] source)` Converts the specified bytes into a String.
`static java.lang.String`	`byteArrayToString(int ccsid, byte[] source)` Converts the specified bytes into a String.
`static java.lang.String`	`convertIFSQSYSPathnameToJobPathname(java.lang.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 java.lang.String`	`convertJobPathnameToIFSQSYSPathname(java.lang.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.
`java.lang.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, java.lang.String source)` Converts the specified String into bytes.
`static byte[]`	`stringToByteArray(int ccsid, AS400 system, java.lang.String source)` Converts the specified String into bytes.
`static byte[]`	`stringToByteArray(int ccsid, java.lang.String source)` Converts the specified String into bytes.
`byte[]`	`stringToByteArray(java.lang.String source)` Converts the specified String into bytes.
`byte[]`	`stringToByteArray(java.lang.String source, BidiConversionProperties properties)` Converts the specified String into bytes.
`void`	`stringToByteArray(java.lang.String source, byte[] destination)` Converts the specified String into bytes.
`void`	`stringToByteArray(java.lang.String source, byte[] destination, int offset)` Converts the specified String into bytes.
`void`	`stringToByteArray(java.lang.String source, byte[] destination, int offset, int length)` Converts the specified String into bytes.
`void`	`stringToByteArray(java.lang.String source, byte[] destination, int offset, int length, BidiConversionProperties properties)` Converts the specified String into bytes.
`void`	`stringToByteArray(java.lang.String source, byte[] destination, int offset, int length, int type)` Converts the specified String into bytes.
`byte[]`	`stringToByteArray(java.lang.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(java.lang.String encoding)
              throws java.io.UnsupportedEncodingException
```
    Constructs a CharConverter object using the specified character encoding.
    
    Parameters:
    encoding - The name of a character encoding.
    
    Throws:
    
    java.io.UnsupportedEncodingException - If the encoding is not supported.
  - CharConverter
```
public CharConverter(int ccsid)
              throws java.io.UnsupportedEncodingException
```
    Constructs a CharConverter object using the specified CCSID.
    
    Parameters:
    ccsid - The CCSID of the IBM i text.
    
    Throws:
    
    java.io.UnsupportedEncodingException - If the ccsid is not supported.
  - CharConverter
```
public CharConverter(int ccsid,
             AS400 system)
              throws java.io.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. If null, then this constructor behaves identically to CharConverter(ccsid).
    
    Throws:
    
    java.io.UnsupportedEncodingException - If the ccsid is not supported.
- Method Detail
  - byteArrayToString
```
public java.lang.String byteArrayToString(byte[] source)
```
    Converts the specified bytes into a String.
    
    Parameters:
    source - The bytes to convert.
    
    Returns:
    The resultant String.
  - byteArrayToString
```
public java.lang.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 java.lang.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 java.lang.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 Representation Architecture). See BidiStringType for more information and valid values.
    
    Returns:
    The resultant String.
    See Also:
    BidiStringType
  - byteArrayToString
```
public java.lang.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 java.lang.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 java.lang.String byteArrayToString(int ccsid,
                                 AS400 system,
                                 byte[] source)
                                          throws java.io.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:
    
    java.io.UnsupportedEncodingException - If the ccsid is not supported.
  - byteArrayToString
```
public static java.lang.String byteArrayToString(int ccsid,
                                 byte[] source)
                                          throws java.io.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:
    
    java.io.UnsupportedEncodingException - If the ccsid is not supported.
  - convertIFSQSYSPathnameToJobPathname
```
public static java.lang.String convertIFSQSYSPathnameToJobPathname(java.lang.String qsysData,
                                                   int jobCCSID)
                                                            throws java.io.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.
    Note: This method is intended for use only with QSYS object pathnames; that is, pathnames containing "/QSYS.LIB/".
    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:
    
    java.io.UnsupportedEncodingException - If the specified CCSID is not supported.
    See Also:
    convertJobPathnameToIFSQSYSPathname(java.lang.String, int)
  - convertJobPathnameToIFSQSYSPathname
```
public static java.lang.String convertJobPathnameToIFSQSYSPathname(java.lang.String jobData,
                                                   int jobCCSID)
                                                            throws java.io.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.
    Note: This method is intended for use only with QSYS object pathnames; that is, pathnames containing "/QSYS.LIB/".
    
    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:
    
    java.io.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 java.lang.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.
  - stringToByteArray
```
public byte[] stringToByteArray(java.lang.String source)
```
    Converts the specified String into bytes.
    
    Parameters:
    source - The String to convert.
    
    Returns:
    The resultant byte array.
  - stringToByteArray
```
public byte[] stringToByteArray(java.lang.String source,
                       int type)
```
    Converts the specified String into bytes.
    
    Parameters:
    source - The String to convert.
    type - The bidi string type, as defined by the CDRA (Character Data Representation Architecture). See BidiStringType for more information and valid values.
    
    Returns:
    The resultant byte array.
    See Also:
    BidiStringType
  - stringToByteArray
```
public byte[] stringToByteArray(java.lang.String source,
                       BidiConversionProperties properties)
```
    Converts the specified String into bytes.
    
    Parameters:
    source - The String to convert.
    properties - The bidi conversion properties.
    
    Returns:
    The resultant byte array.
  - stringToByteArray
```
public void stringToByteArray(java.lang.String source,
                     byte[] destination)
                       throws java.io.CharConversionException
```
    Converts the specified String into bytes.
    
    Parameters:
    source - The String to convert.
    destination - The destination byte array.
    
    Throws:
    
    java.io.CharConversionException - If destination is not large enough to hold the converted string.
  - stringToByteArray
```
public void stringToByteArray(java.lang.String source,
                     byte[] destination,
                     int offset)
                       throws java.io.CharConversionException
```
    Converts the specified String into bytes.
    
    Parameters:
    source - The String to convert.
    destination - The destination byte array.
    offset - The offset into the destination array for the start of the data.
    
    Throws:
    
    java.io.CharConversionException - If destination is not large enough to hold the converted string.
  - stringToByteArray
```
public void stringToByteArray(java.lang.String source,
                     byte[] destination,
                     int offset,
                     int length)
                       throws java.io.CharConversionException
```
    Converts the specified String into bytes.
    
    Parameters:
    source - The String to convert.
    destination - The destination byte array.
    offset - The offset into the destination array for the start of the data.
    length - The number of bytes of data to write into the array.
    
    Throws:
    
    java.io.CharConversionException - If destination is not large enough to hold the converted string.
  - stringToByteArray
```
public void stringToByteArray(java.lang.String source,
                     byte[] destination,
                     int offset,
                     int length,
                     int type)
                       throws java.io.CharConversionException
```
    Converts the specified String into bytes.
    
    Parameters:
    source - The String to convert.
    destination - The destination byte array.
    offset - The offset into the destination array for the start of the data.
    length - The number of bytes of data to write into the array.
    type - The bidi string type, as defined by the CDRA (Character Data Representation Architecture). See BidiStringType for more information and valid values.
    
    Throws:
    
    java.io.CharConversionException - If destination is not large enough to hold the converted string.
    See Also:
    BidiStringType
  - stringToByteArray
```
public void stringToByteArray(java.lang.String source,
                     byte[] destination,
                     int offset,
                     int length,
                     BidiConversionProperties properties)
                       throws java.io.CharConversionException
```
    Converts the specified String into bytes.
    
    Parameters:
    source - The String to convert.
    destination - The destination byte array.
    offset - The offset into the destination array for the start of the data.
    length - The number of bytes of data to write into the array.
    properties - The bidi conversion properties.
    
    Throws:
    
    java.io.CharConversionException - If destination is not large enough to hold the converted string.
    See Also:
    BidiStringType
  - stringToByteArray
```
public static byte[] stringToByteArray(AS400 system,
                       java.lang.String source)
```
    Converts the specified String into bytes.
    
    Parameters:
    system - The system object representing the system with which to connect.
    source - The String to convert.
    
    Returns:
    The destination byte array.
  - stringToByteArray
```
public static byte[] stringToByteArray(int ccsid,
                       AS400 system,
                       java.lang.String source)
                                throws java.io.UnsupportedEncodingException
```
    Converts the specified String into bytes.
    
    Parameters:
    ccsid - The CCSID of the IBM i text.
    system - The system object representing the system with which to connect.
    source - The String to convert.
    
    Returns:
    The destination byte array.
    
    Throws:
    
    java.io.UnsupportedEncodingException - If the ccsid is not supported.
  - stringToByteArray
```
public static byte[] stringToByteArray(int ccsid,
                       java.lang.String source)
                                throws java.io.UnsupportedEncodingException
```
    Converts the specified String into bytes. 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 String to convert.
    
    Returns:
    The destination byte array.
    
    Throws:
    
    java.io.UnsupportedEncodingException - If the ccsid is not supported.

Methods inherited from class java.lang.Object

CharConverter

CharConverter

CharConverter

CharConverter

byteArrayToString

byteArrayToString

byteArrayToString

byteArrayToString

byteArrayToString

byteArrayToString

byteArrayToString

byteArrayToString

convertIFSQSYSPathnameToJobPathname

convertJobPathnameToIFSQSYSPathname

getCcsid

getEncoding

isFaultTolerantConversion

setFaultTolerantConversion

stringToByteArray

stringToByteArray

stringToByteArray

stringToByteArray

stringToByteArray

stringToByteArray

stringToByteArray

stringToByteArray

stringToByteArray

stringToByteArray

stringToByteArray