System i Access

Overview

Windows

Linux

Web

Wireless

	System i Access for Linux   |   Downloads    |   Documentation    |   Support    |   Installation and Usage Guide

Table of Contents:

• Introduction
• Requirements
• Installation
• ODBC Configuration
• 5250 Configuration  New ideographic (DBCS) information
• Security  New Kerberos and SSL information
• Debugging Problems
• • Technical Support
  • Forum
• FAQs
• • ODBC FAQs
  • 5250 FAQs
• Utilities
• Examples
• Reference Links

iSeries Access for Linux 32-bit provides an ODBC driver for accessing the DB2 Universal Database® (UDB) for iSeries and a 5250 emulator. The 5250 emulator includes bypass signon, keyboard mapping, macro support, workstation ID support, and many other functions.

iSeries Access for Linux 64-bit currently only provides an Extended Dynamic Remote SQL (EDRS) driver. It is supported only on SuSE SLES 9 and requires the iSeries Access for Linux 32-bit product to be installed first. For more information on ERDS, refer to the XDA Web Site and System i and i5/OS Information Center, "Extended Dynamic Remote SQL (EDRS) APIs" in the Programming -> APIs -> Database and File -> Database section.

Both iSeries Access for Linux 32-bit and iSeries Access for Linux 64-bit EDRS Driver are available as web downloads. iSeries Access for Linux 32-bit is also available as part of the iSeries Access for Web product.

 Back to top

Licenses

IBM iSeries Access for Linux (5722-XL1) is a licensed program. The 5250 Display Emulation component requires an IBM iSeries Access Family (5722-XW1) license before you can use it.

For more information about iSeries Access Family license requirements, refer to the IBM International Program License Agreement included with the iSeries Access Family (5722-XW1).

iSeries Server requirements for running iSeries Access for Linux

• Connections to System i's running OS/400 Version 5 Release 1 or OS/400 Version 5 Release 2 are supported. The product may work with earlier releases of OS/400, but is supported only with V5R1 and V5R2.
• The QUSER user profile must be enabled. From an iSeries command line type DSPUSRPRF USRPRF(QUSER) and press ENTER to display the status for QUSER. Use the CHGUSRPRF command to change the profile if necessary.
• The host servers must be started. Type STRHOSTSVR and press ENTER to start the OS/400 host servers.
• TCP/IP must be running. To run TCP/IP, you must have the TCP/IP Connectivity Utilities for AS/400 (licensed program 5722-TC1) installed on the server. For more information on host server options and TCP/IP, see the TCP/IP topic in the System i and i5/OS Information Center.

Linux requirements for running iSeries Access for Linux

• GLibc 2.2
• RPM 3.0
• OpenMotif 2.0 or later for the 5250 emulator
• unixODBC driver manager version 2.0.11 or later must be installed on the client. Go to the unixODBC Project web site for more information on the driver manager and to download the latest level of the driver manager.

Recommended iSeries LPAR (Power PC) Linux Distributions:

• Suse Linux Enterprise Server 8 and later
• Red Hat Enterprise Linux 3 and later

Note: if you recompile the unixODBC driver manager, the ./configure --prefix default is /usr/local. If you use this default, you may need to update your shared library (/etc/ld.so.conf) and executable paths to include it.

 Back to top

Installing iSeries Access for Linux

Updating iSeries Access for Linux

Uninstalling iSeries Access for Linux

• To uninstall iSeries Access for Linux, enter the following command:
     rpm -e iSeriesAccess
• Note: the /opt/ibm/iSeriesAccess/conv_tables directory might not be removed during uninstall because of downloaded conversion tables. The directory needs to be removed manually.

Manually adding iSeries Access for Linux to unixODBC Driver Manager

 Back to top

  ODBC Configuration GUI

A data source can be configured using the ODBC data source graphical user interface (GUI). The GUI contains fields to set required and frequently used options. The following instructions describe how to create or configure an ODBC Driver data source.

1. Open the Data Source Administrator that comes with the unixODBC driver manager by typing ODBCConfig at the command prompt.
2. Decide what type of data source you wish to use. User data sources (DSNs) are only accessible by the user who created them. System DSNs are accessible by any user on that machine, but you need to use root authority to create them.
3. Click Add... to create a new data source or Configure... to configure a data source that already exists. If you clicked Configure... go to step 5, otherwise continue to the next step.
4. Select an ODBC driver. Click on iSeries Access ODBC Driver and click the OK button.
5. Note:  The Add, Remove, and Configure buttons on this window apply to adding, removing, or configuring a driver.  If you accidentally click on one of these buttons, close the window and repeat this step.
6. A window similar to the following will appear.  You may have to resize the window to make it appear correctly.
7. Fill in the data source name in the Name field and your system name in the System field (required), and any other fields you wish to set.
8. Click the check mark in the upper-left corner of the window to save the configuration.

You will have to manually configure any connection options you want to set that do not have fields on the GUI. See Connection String Keywords and Values and manual configuration information before manually configuring connection options.

  Manual Data Source Configuration

 Back to top

  Starting a 5250 Emulator

 Back to top

Kerberos

iSeries Access for Linux V1.10 supports authenticating to the iSeries via Kerberos. To install and configure iSeries for Kerberos, see the System i and i5/OS Information Center, under the Security > Single signon topic. To install and configure Linux for Kerberos, see one of the many articles available on the Internet. For example, refer to the Kerberos Infrastructure HOWTO.

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 sym-link for the Kerberos shared library (Heimdal /usr/lib/libgssapi.so, MIT /usr/lib/libgssapi_krb5.so). iSeries Access for Linux dynamically loads the Kerberos shared library by that name and if a sym-link 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 iSeries Access for Linux, you must first authenticate to your Kerberos domain using the "kinit" command or setting 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.

For any iSeries Access function, you can use "*kerberos" in place of the iSeries user profile to use your Kerberos tickets. Any password will be ignored in this case. For example:
  /opt/ibm/iSeriesAccess/bin/rmtcmd CRTLIB Test /system:iSeriesSystemName /user:*kerberos

The Kerberos principle 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 do 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

Secure Sockets Layer (SSL)

SSL support using stunnel is documented in the shipped sample stunnel configuration file (/opt/ibm/iSeriesAccess/doc/iSeriesAccess.stunnel.config). Refer to this file for information on one basic way to setup SSL with iSeries Access for Linux.

Communications

Use the cwbping program to verify the connection between the Linux workstations and the iSeries 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:

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

  Technical Support

iSeries Access for Linux is IBM Licensed Program 5722-XL1.

Refer to one of these sources for known problems:

• In this Installation and Usage Guide, refer to...
  ODBC FAQs
  5250 FAQs
  Known Problems
  Forum
• System i Technical Support Web Site
• iSeries APARs and Information APARs
• Support Line Knowledge Base

If you would like to call IBM Support:

• In the U.S., call IBM iSeries Support Line at 1-800-IBM-SERV (1-800-426-7378).
• Outside the U.S., find local phone numbers in the IBM Software Support Guide.
• Or refer to IBM Electronic Services.

 Forum

As a user of iSeries Access for Linux, you are invited to participate in the iSeries Access for Linux forum, a discussion facility that puts you in touch with other users of iSeries Access for Linux.

 Back to top

 Back to top

  Error Messages

For errors that occur in the data source, the ODBC Driver in iSeries Access for Linux 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 iSeries Access for Linux returns an error message based on the message returned by the System 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 iSeries Access product is also shipped in the /opt/ibm/iSeriesAccess/doc directory.

Error message format

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

error-message

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.

  National Language considerations when using iSeries Access for Linux

Coded Character Set Identifiers (CCSID)

The ODBC Driver in iSeries Access for Linux 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 byte hex number of FROM CCSID><4 byte 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 iSeries Access ODBC Driver. Additional conversion tables will be downloaded automatically from the iSeries 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 iSeries Access for Linux and the ODBC Driver in iSeries Access for Windows

  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 iSeries Access for Linux.  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 for a list of known problems that are fixed in each release.

Applications:

 Back to top

Utilities

The following utilities are included with iSeries Access for Linux and are shipped in /opt/ibm/iSeriesAccess/bin.  RTMCMD - Run an iSeries batch/CL command Use this command from a console prompt to run a single iSeries command or a group of iSeries commands. Syntax to run a single command rmtcmd [command] Syntax to run a group of commands rmtcmd [/I:fileName] Parameters /system:systemName = iSeries system name /user:userName = iSeries user profile /password:password = iSeries user profile password /Q = no error prompts /Z = no banners Examples To run command foo on iSeries system bigblue, run:    rmtcmd foo /system:bigblue /user:UserProfile /password:UserPassword To run a groups of command listed in a file, run:    rmtcmd /i:foocmds.txt /system:bigblue /user:UserProfile /password:UserPassword  RTMODBC - Run an iSeries batch/CL command using the ODBC driver Use this command from a console prompt to run a single iSeries command or a group of iSeries commands. Syntax to run a single command rmtodbc [command] Syntax to run a group of commands rmtodbc [/I:fileName] Parameters /system:systemName = iSeries system name /dsn:dsnName = unixODBC DataSource name /user:userName = iSeries user profile /password:password = iSeries user profile password /Q = no error prompts /Z = no banners Examples To run command foo on iSeries system bigblue, run:    rmtodbc foo /system:bigblue /user:UserProfile /password:UserPassword To run a groups of command listed in a file, run:    rmtodbc /i:foocmds.txt /system:bigblue /user:UserProfile /password:UserPassword  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 iSeries system, or to help determine the cause of a connection failure. CWBPING checks of the status of the host servers on the iSeries 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 = iSeries 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 iSeries system named System1 with address 9.12.103.14: cwbping System1 or cwbping 9.12.103.14 /v  CWBTRC - Trace iSeries Access for Linux 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 = iSeries system to download the table from. Note that if a connection to the iSeries is necessary, the user ID and password must also be specified. userid = iSeries user ID password = iSeries 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 iSeries Access for Linux. See cwbcopwr.html for details  Back to top

Examples

PHP - ODBC See how the Apache Software Foundation's web server, PHP, and the ODBC Driver in iSeries Access for Linux can work together to access database data on an System 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". Additional instructions are in index.html or index.php in the download file. Requirements: a Linux machine running PHP under the Apache web server, the unixODBC driver manager, and the ODBC Driver in iSeries Access for Linux. PHP must have unixODBC driver manager support compiled in. To download the files, read and accept this agreement:   This material contains IBM copyrighted sample programming source code, DB2® UDB PHP Demo. IBM grants you a nonexclusive copyright license to use the Sample Code as an example from which you can generate similar function tailored to your own specific needs. Your license to this Sample Code provides you no right or licenses to any IBM patents. The Sample Code is provided by IBM for illustrative purposes only. The Sample Code has not been thoroughly tested under all conditions. IBM, therefore, does not guarantee or imply its reliability, serviceability, or function. IBM provides no program services for the Sample Code. All Sample Code contained herein is provided to you "AS IS" without any warranties of any kind. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGMENT ARE EXPRESSLY DISCLAIMED. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSIONS MAY NOT APPLY TO YOU. IN NO EVENT WILL IBM BE LIABLE TO ANY PARTY FOR ANY DIRECT, INDIRECT, SPECIAL OR OTHER CONSEQUENTIAL DAMAGES FOR ANY USE OF THE SAMPLE CODE INCLUDING, WITHOUT LIMITATION, ANY LOST PROFITS, BUSINESS INTERRUPTION, LOSS OF PROGRAMS OR OTHER DATA ON YOUR INFORMATION HANDLING SYSTEM OR OTHERWISE, EVEN IF WE ARE EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. I accept. Download. Once the package is downloaded to your Linux machine, unzip it.  Back to top