com.ibm.as400.access

Class 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: 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 Detail

      • CharConverter

        public CharConverter()
        Constructs a CharConverter object using a "best guess" based on the default Locale.
      • 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. If null, then this constructor behaves identically to CharConverter(ccsid).
        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 Representation 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.

        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:
        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.

        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:
        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.
      • stringToByteArray

        public byte[] stringToByteArray(String source)
        Converts the specified String into bytes.
        Parameters:
        source - The String to convert.
        Returns:
        The resultant byte array.
      • stringToByteArray

        public byte[] stringToByteArray(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(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(String source,
                             byte[] destination)
                               throws CharConversionException
        Converts the specified String into bytes.
        Parameters:
        source - The String to convert.
        destination - The destination byte array.
        Throws:
        CharConversionException - If destination is not large enough to hold the converted string.
      • stringToByteArray

        public void stringToByteArray(String source,
                             byte[] destination,
                             int offset)
                               throws 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:
        CharConversionException - If destination is not large enough to hold the converted string.
      • stringToByteArray

        public void stringToByteArray(String source,
                             byte[] destination,
                             int offset,
                             int length)
                               throws 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:
        CharConversionException - If destination is not large enough to hold the converted string.
      • stringToByteArray

        public void stringToByteArray(String source,
                             byte[] destination,
                             int offset,
                             int length,
                             int type)
                               throws 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:
        CharConversionException - If destination is not large enough to hold the converted string.
        See Also:
        BidiStringType
      • stringToByteArray

        public void stringToByteArray(String source,
                             byte[] destination,
                             int offset,
                             int length,
                             BidiConversionProperties properties)
                               throws 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:
        CharConversionException - If destination is not large enough to hold the converted string.
        See Also:
        BidiStringType
      • stringToByteArray

        public static byte[] stringToByteArray(AS400 system,
                               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,
                               String source)
                                        throws 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:
        UnsupportedEncodingException - If the ccsid is not supported.
      • stringToByteArray

        public static byte[] stringToByteArray(int ccsid,
                               String source)
                                        throws 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:
        UnsupportedEncodingException - If the ccsid is not supported.