IBM i Access for Linux

Installation and usage guide

Table of contents:

Introduction

IBM i Access Client Solutions is the newest member of the IBM i Access family. The Linux Application Package is an optional download that provides an ODBC driver for accessing the DB2 for i database from a Linux client.

ODBC features for the IBM i Access Linux Application Package include:

For additional functions for the Linux platform like 5250 emulation, Data Transfer, 5250 Console, and displaying spool files, see IBM i Access Client Solutions.

  • - Requirements

    Recommended Linux Distributions:

    Linux requirements:

    IBM i requirements:


  • - Installation

    Installing the Linux Application Package

    1. Download the Linux Application Package: IBMiAccess_v1r1_LinuxAP.zip

    2. Unzip the file. This can be accomplished using the unzip command or one of the many GUI tools available.

    3. Choose the package to install based on your platform.
    32-bit and 64-bit packages are available for i386, x86, and PowerPC architectures
    Both rpm and deb packages are provided for i386 and x86.
    Also available are 32-bit compatibility packages for 64-bit architectures.

    4. On rpm-based distributions, use:
    rpm -ivh       (e.g. rpm -ivh ibm-iaccess-1.1.0-1.0.i386.rpm)
    Note: Due to changes in unixODBC package on some distributions, you may need to force install the rpm with the --nodeps option

    On Debian-based distributions, use:
    dpkg -i       (e.g. dpkg -i ibm-iaccess-1.1.0-1.0.amd64.deb)
    Note: During the installation, the ODBC driver will automatically be registered with the unixODBC driver manager.


    Updating the Linux Application Package

    1. Download the updated Linux Application Package: IBMiAccess_v1r1_LinuxAP.zip
    Note: The updates will be available in the same location as your original download with updated version numbers.

    2. Unzip the file. This can be accomplished using the unzip command or one of the many GUI tools available.

    3. Choose the package to install based on your platform.
    32-bit and 64-bit packages are available for i386, x86, and PowerPC architectures
    Both rpm and deb packages are provided for i386 and x86.
    Also available are 32-bit compatibility packages for 64-bit architectures.

    4. On rpm-based distributions, use:
    rpm -Uvh       (e.g. rpm -Uvh ibm-iaccess-1.1.0-1.0.i386.rpm)
    Note: Due to changes in unixODBC package on some distributions, you may need to force install the rpm with the --nodeps option

    On Debian-based distributions, use:
    dpkg -i       (e.g. dpkg -i ibm-iaccess-1.1.0-1.0.amd64.deb)

    Note: During the upgrade, the ODBC driver will automatically be re-registered with the unixODBC driver manager.


    Uninstalling the Linux Application Package

    For rpm-based distributions, use:
    rpm -e       (e.g. rpm -e ibm-iaccess-1.1.0-1.0.i386.rpm)

    For Debian-based distributions, use:
    dpkg -r       (e.g. dpkg -r ibm-iaccess-1.1.0-1.0.amd64.deb)
    Note: the /opt/ibm/iSeriesAccess/conv_tables directory might not be removed during uninstall because of downloaded conversion tables. The directory will then need to be removed manually.


  • - Security

    Kerberos

    IBM i Access Client Solutions - Linux Application Package supports authenticating to IBM i via Kerberos. To install and configure IBM i for Kerberos, see the IBM i Information Center, under the Security > Single sign-on topic. To install and configure Kerberos for Linux, consult information appropriate for your distribution (often readily available online)

    Note: Most Linux distributions have at least one (Heimdal and MIT) version of the Kerberos 5 included with them. However, some distributions do not create a symlink for the Kerberos shared library (Heimdal /usr/lib/libgssapi.so, MIT /usr/lib/libgssapi_krb5.so). Linux Application Package dynamically loads the Kerberos shared library by that name and if a symlink to that name is not available, you will get the following error: CWBSY1015 - Kerberos not available on this version of the operating system.

    To use Kerberos with Linux Application Package, you must first authenticate to your Kerberos domain using the "kinit" command or set up your initial Linux login to do it with PAM (Pluggable Authentication Module) Kerberos plug-in. After a successful "kinit", you should be able to do a "klist -f" to see the status of your Kerberos tickets.

    To configure the ODBC driver to use kerberos, simply specify "*KERBEROS" as the user name when configuring your data source or calling the connection API.

    The Kerberos principal name will be based upon the fully qualified TCP/IP name received from the reverse look-up of the TCP/IP address. If you use hosts file to resolve TCP/IP addresses, be sure to include the fully qualified TCP/IP system name. For example: 1.2.3.4 MyiSseries.MyDomain.com MyiSeries

    Other Security Solutions

    For other security solutions including OpenSSH and stunnel, see Securing Communications with OpenSSH on IBM i5/OS (PDF, 1.54MB)


  • - Debugging problems

    Communications

    Use the cwbping program to verify the connection between the Linux workstations and the IBM i server, and to verify the host servers are started.

    Tracing and logging

    Once you verify your connection to the server, there are four basic trace files for problem determination:

    • SQL log - The unixODBC sql.log will show the input and output parameters for ODBC API calls made. The sql.log is activated using the unixODBC ODBCConfig program. From the Advanced tab, you can enable sql tracing and configure the location of the log file.
    • History log - The history log will show high-level communication, security and data conversion error messages. The History log is activated using the cwbtrc program.
    • Detail trace - The detail trace will show low-level driver information and is intended for use in reporting problems to IBM. Detail trace is activated using the cwbtrc program.

    For additional help on error messages, refer to the "Error Message" sections in the ODBC FAQs.

    Technical support

    IBM i Access Client Solutions - Linux Application Package is Licensed Program 5733-XJ1.

    Refer to one of these sources for known problems:


  • - FAQs

    ODBC frequently asked questions

    Error messages

    When an error occurs, the ODBC Driver in IBM i Access returns the SQLSTATE (an ODBC error code) and an error message. The driver obtains this information both from errors that are detected by the driver and from errors that are returned by the IBM i.

    For errors that occur in the data source, the ODBC Driver in IBM i Access maps the returned native error to the appropriate SQLSTATE. When both the driver and the driver manager detect an error, they generate the appropriate SQLSTATE. The ODBC Driver in IBM i Access returns an error message based on the message returned by the IBM i.

    For errors that are detected within the ODBC Driver, the driver returns an error message based on the text associated with the SQLSTATE. These error messages are translated messages. Help text for error messages found in the underlying components of the IBM i Access product is also shipped in the /opt/ibm/iSeriesAccess/doc directory.

    Error message format

    Error messages have the following format:

    [vendor][ODBC-component][data-source]
    error-message

    The prefixes in brackets ([ ]) identify the source of the error. The following table shows the values of these prefixes returned by the IBM i Access ODBC Driver.

    When the error occurs in the data source, the [vendor] and [ODBC-component] prefixes identify the vendor and name of the ODBC component that received the error from the data source.

    Error Source Value
    Driver Manager [unixODBC]
    [Driver Manager]
    ODBC Driver in IBM i Access [unixODBC]
    [IBM]
    [IBM i Access ODBC Driver]
    NLS messages [unixODBC]
    [IBM]
    [IBM i Access ODBC Driver]
    Column #:
    NLS error message number
    NLS error message text

    See the message prefix table below to find second level help text.
    Communication and security [unixODBC]
    [IBM]
    [IBM i Access ODBC Driver]
    Communications link failure. comm rc=xxxx - (message text)

    xxxx is the error number in decimal, not hexadecimal, format. Message text describing the nature of your error appears with the error number. See the message prefix table below to find second level help text.
    DB2 for i [unixODBC]
    [IBM]
    [IBM i Access ODBC Driver]
    [DB2 UDB]
    Server error message

    To view error message text for DB2 for i errors:

    For errors that begin with: Use this OS/400 command
    SQL DSPMSGD RANGE(SQLxxxx) MSGF(QSQLMSG)
    IWS or PWS DSPMSGD RANGE(ZZZxxxx) MSGF(QIWS/QIWSMSG)
    ZZZ is either IWS or PWS
     
    Some other prefixes that may be seen through the ODBC Driver in IBM i Access include:
    Message Prefix
    Message Prefix Message File Description
    CWB#### cwber.html Base error messages
    CWBCO#### cwbcoer.html Communication error messages
    CWBNL#### cwbnler.html Conversion error messages
    CWBSY#### cwbsyer.html Security error messages
    CWBRC#### cwbrcer.html Remote Command error messages 
    CWBLM#### cwblmer.html License error messages

    National language considerations when using IBM i Access Linux Application Package

    The ODBC Driver in IBM i Access handles many types of data conversions. The character code page conversions involve using conversion tables and the iconv interfaces. Some of the conversion tables are shipped with the driver, others will be automatically downloaded from the IBM i when needed. Iconv is a library shipped with Linux that also handles character data conversions.

    Coded Character Set Identifiers (CCSID)

    The ODBC Driver in IBM i Access uses a pair (to and from) of Coded Character Set Identifiers (CCSID) to convert character data. The conversion will either use a conversion table or the iconv interfaces.

    Conversion tables

    Conversion tables are stored in /opt/ibm/iSeriesAccess/conv_tables and use the following naming convention:
    <4 digit hex number of FROM CCSID><4 digit hex number of TO CCSID>.tbl

    For example, the conversation table for 819 to 500 would be 033301f4.tbl.

    Many conversion tables are shipped with the IBM i Access ODBC Driver. Additional conversion tables will be downloaded automatically from the IBM i when they are needed. You can also download conversion tables using the CWBNLTBL utility.

    ODBC application character set

    The ODBC application character set is defined by the current locale's character set.

    To find out the current locale, use the following command:
    locale

    To find out the current mapping between the current locale's character set and the CCSID that will be used, use the following command:
    /opt/ibm/iSeriesAccess/bin/cwbnltbl

    Overriding the character set to/from CCSID mappings

    If you wish to change or add character set to/from CCSID mapping, add the following lines to the $HOME/.iSeriesAccess/cwb_userprefs.ini configuration file.

    [CWB_CURRUSER\Software\IBM\Client Access Express\CurrentVersion\NLS]
    CCSID-CODESET=attr_str:939,IBM939,819,IBM819

    The above lines will create mappings for CCSID 939 to character set "IBM939" and for CCSID 819 to character set "IBM819".

    List of available locales

    To list the available locales, use the following command:
    locale -a

    List of available Iconv character sets

    To list the available iconv character sets, use the following command:
    iconv -l

    How to investigate conversion problems

    Most conversion problems are logged in the History Log. To turn on history logging, use the following command:
    /opt/ibm/iSeriesAccess/bin/cwbtrc /hl:1
    (Refer to CWBTRC for more about the trace utility.)

     The history log output will be in $HOME/.iSeriesAccess/cwbhistory--.csv. Use either a text editor or a spread sheet to view the contents of the history log.

    Differences between the ODBC Driver in IBM i Access Linux Application Package and the ODBC Driver in IBM i Access for Windows

    Linux ODBC Windows ODBC
    The driver is an ODBC 3.5 ANSI driver with the ability to store and process Unicode data. An ANSI driver does not support Unicode strings passed as arguments to the APIs. Applications passing Unicode strings on APIs will work because the unixODBC driver manager maps calls these calls to the ANSI driver's narrow interfaces. The driver is an ODBC 3.5 Unicode driver. A Unicode driver accepts Unicode strings as arguments to the APIs.
    To sign on you must specify a user ID and password (or specify *KERBEROS as the user ID) when calling the connection API or have the user ID and password entered into the DSN. The ODBC driver will not prompt for iSeries user IDs or passwords. User ID and password updates must be done through a telnet session with the iSeries. The user has sign on options that control which user ID and password to use when connecting. When connecting, cached passwords might be used. If a user's password has expired a dialog is displayed to allow a user to change it.
    When binding a parameter or a column with SQL_C_WCHAR as the C type, wchar_t buffers should not be passed in. The driver manager and driver both handle the SQL_C_WCHAR data type as a 2 byte UCS-2 string. When binding a parameter or a column with SQL_C_WCHAR as the C type, wchar_t buffers should be passed in. The driver manager and driver both handle the SQL_C_WCHAR  data type as a 2 byte UCS-2 string.
    Restrictions when using the ODBC Driver in IBM i Access Linux Application Package
    Restriction Reason
    MTS is not supported. This depends on Microsoft Windows-specific components which are not available on Linux.
    APIs that display a graphical user interface are not supported. The API call will still complete but will behave as if displaying the GUI failed.
    Translation DLLs Translation DLLs are not currently supported. Any attempt to use them will be ignored.
    DSN connection option for user ID /password prompting via a sign-on dialog is not supported. Graphical user interfaces are not being ported to Linux.
    DSN option for customizing package settings for an application is not supported. Only the simple implementation of package settings is being ported to Linux.
    See Unsupported Connection String Keywords for other DSN options that are not supported in Linux. These keywords correspond with options we aren't supporting.
    Secure Sockets Layer (SSL) component The SSL component is not needed or shipped with the Linux driver. Use a common SSL tunnel or Socks server instead.
    Connection Timeout  The connection timeout option is not supported with the Linux driver.

    Known problems

    There are several known problems that have been discovered with the unixODBC Driver Manager and with applications that use the ODBC Driver in IBM i Access. This list is by no means a complete list, but contains a list of problems that we've noticed

    unixODBC Driver Manager:

    Refer to the unixODBC web site (link resides outside of ibm.com) for a list of known problems that are fixed in each release.

     

  • - Utilities

    The following utilities are included with IBM i Access Client Solutions - Linux Application Package and are shipped in /opt/ibm/iSeriesAccess/bin.

    CWBPING - Test the connection to the server

    Use this command from a console prompt to determine if a connection can be successfully made to an IBM i system, or to help determine the cause of a connection failure.

    CWBPING checks of the status of the host servers on the IBM i system. The name of the communications provider is shown, as well as the result of connecting to each of the host socket servers. To see detailed messages, use the (/v) verbose option.

    Syntax

    cwbping system [/v] [/pl:#] [/al:#] [/serv:name] [/port:#] [/user:userid] [/password:password] [/all]

    Parameters

    • system = name of the server
    • /v = verbose output
    • /pl:# = port mode (0 = Server services file, 1 = Local services file, 2 = Standard port )
      Note: If the /port:# is specified, the port mode is ignored.
    • /al:# = address mode
      0 = Always use gethostbyname
      1 = Lookup after 1 hour
      2 = Lookup after 1 day
      3 = Lookup after 1 week
      4 = Never use gethostbyname, use configured IP address
      5 = Lookup once after each PC restart
      Note: If the system name is specified in IP Address form (x.x.x.x) the address mode will be ignored.
    • /serv:name = name of the service to connect to (i.e. /serv:telnet or /serv:ftp)
      Note: Any TCP/IP service name can be used. For example, see CWBCO1003 or you local services file.
    • /port:# = port number to connect to in decimal (i.e. /port:23 or /port:21)
      Note: Any TCP/IP port number can be used. For example, see CWBCO1003 or your local services file.
    • /user:userid = IBM i user ID to use only if the server requires security on startup
    • /password:password = iSeries password to use only if the server requires security on startup
    • /all = verify all possible servers, by default only common servers are verified.

    Examples

    To check the status of the host servers on the IBM i system named System1 with address 9.12.103.14:

    cwbping System1

    or 

    cwbping 9.12.103.14 /v

    CWBTRC - Trace IBM i Access Linux Application Package

    Use this command from a console prompt to configure tracing.

    Syntax

    cwbtrc [/DT:0-1] [/DPATH:path] [/DWRAP:0-4000] [/DFLTR:0-1] [/DTICK:0-1] [/DFRMT:0-1] [/HL:0-1] [/HPATH:path] [/HWRAP:0-4000] [/HFLTR:0-1] [/HTICK:0-1]

    Parameters

    Note: Defaults shown in bold.

    • /DT:0-1 = turn detail trace off/on
    • /DPATH:path = detail trace path, default is $HOME/.iSeriesODBC
    • /DWRAP:0-4000 = detail trace wrap size (MB), default is 1. An " " symbol will be placed after the last record.
    • /DFLTR:0-1 = detail trace filter off/on
    • /DTICK:0-1 = timestamp or tick count in trace entries
    • /DFRMT:0-1 = limit tcp hex data off/on
    • /HL:0-1 = turn history log off/on
    • /HPATH:path = history log path, default is $HOME/.iSeriesODBC
    • /HWRAP:0-4000 = history log wrap size (MB), default is 1. An " " symbol will be placed after the last record.
    • /HFLTR:0-1 = history log filter off/on
    • /HTICK:0-1 = timestamp or tick count in traces entries

    Running CWBTRC without any parameters will show the command syntax and the current status of each parameter.

    The output from CWBTRC will have the following naming convention:

    cwbdetail--pid.csv

    cwbhistory--pid.csv

    The output files will be in semi-colon separated record format, suitable for input into spreadsheets for viewing.

    Examples

    The following command will turn on detail trace and allow it to grow to a 10 meg file before wrapping. It will also turn on history logging.

    cwbtrc /dt:1 /dwrap:10 /hl:1

    The following command will turn on history log and change the path to /usr/traces 

    cwbtrc /hl:1 /hpath:/usr/traces

    CWBNLTBL - Download conversion tables

    Use this command from a console prompt to download conversion tables.

    Syntax

    cwbnltbl [source-code-page] [target-code-page] [system] [userid] [password]

    Parameters

    • source-code-page = source code page for the table
    • target-code-page = target code page for the table
    • system = IBM i system to download the table from. Note that if a connection to the IBM i is necessary, the user ID and password must also be specified.
    • userid = IBM i user ID
    • password = IBM i password

    The tables share a common location on the workstation /opt/ibm/iSeriesODBC/conv_tables. Many conversions tables are already shipped with the product. The product also uses iconv conversion where necessary. Use the History Log to look for conversion information.

    Examples 

    • To download the 819 to 13488 conversion table from the iSeries if necessary, run
      cwbnltbl 819 13488 myiSeriesSystem myiSeriesuserid myiSeriesPwd
    • To show the current locale charset and its code-page mapping, run
      cwbnltbl

    CWBCOPWR - Change advanced communications settings

    Use this command to change the advanced communications settings of IBM i Access Linux Application Package.


  • - Examples

    PHP - ODBC

    See how the Apache Software Foundation's web server, PHP, and the ODBC Driver in IBM i Access Linux Application Package can work together to access database data on an IBM i.

    Instructions for setting up PHP and Apache are in the Redbook Linux Integration with IBM i5/OS, (SG24-6551).

    Read section 3.4.2, "PHP for three-tier applications".


  • - Reference links

Contact IBM

Browse Power Systems

Next generation applications for big data and analytics and cognitive computing are providing unprecedented insights into opportunities, threats and efficiencies. IBM Power Systems is at the forefront of delivering solutions to gain faster insights from analyzing both structured information and unstructured big data. With the secure, flexible and open platform of IBM Power Systems plus solutions and software, organizations can outpace their competitors by delivering faster services, providing differentiated offerings and turning operational cost into investment opportunity.

To draw insights and make better decisions, businesses rely on the secure, flexible and open platform of IBM Power Systems. Built with the first processor designed for big data workloads, the design of Power Systems combines the computing power, memory bandwidth and I/O in ways that are easier to consume and manage, building on strong resiliency, availability and security.

IBM Power Systems deliver flexibility and choice of operating systems to enable your business to support the next generation applications for big data and analytics and cognitive computing that are transforming how organizations work today. Whether running 1, 2, or all 3 - coupled with PowerVM, they maximize the benefit of Power Systems in your business.

Transform your business with Systems Software that enables virtualization, high availability, flexibility, security and compliance on Power Systems™. IBM’s integrated approach to developing Systems and Systems Software together delivers optimized results with Power Systems.

As an open innovation platform, Power Systems is optimized for big data and analytics performance and to deliver scale-out economics and security for the cloud. IBM and IBM Business Partner solutions exploit key capabilities in IBM Power Systems.

Over the last five years thousands of clients have migrated to IBM Power Systems. Learn how Power Systems has helped them support next generation applications for big data and analytics and cognitive computing on an open platform for choice while improving business performance, reducing risk, and establishing a platform for growth.