Welcome!

ColdFusion Authors: Yakov Fain, Maureen O'Gara, Nancy Y. Nee, Tad Anderson, Daniel Kaar

Related Topics: ColdFusion

ColdFusion: Article

Macromedia ColdFusion - MX to iSeries Demystified

A world-class database platform paired up with a world-class Web application server

In this article, I'll show you how to connect ColdFusion MX to an IBM iSeries (formerly AS/400) DB2 database. I'll describe your connectivity options and give you configuration examples.

While attending an iSeries conference a couple of years ago, I had the opportunity to talk with an IBM DB2 engineer. I still remember the blank look on his face when I explained that I use ColdFusion to access his database. In his defense, I've enlightened more than a few Macromedians as to what an iSeries is and what it does. Thank heaven for standards and thank the heavens again for Macromedia's and IBM's adherence to them.

There are several ways to get to DB2 data on the iSeries. We'll concentrate on ODBC and JDBC. Platform examples will include ColdFusion MX 6.1 on Windows 2000 Server and JRun/ColdFusion MX 6.1 on Apple OSX 10.1.5.

Windows 2000 Server
ODBC Configuration Step by Step Installation

To make ODBC work, you need Client Access for iSeries installed on the ColdFusion Server. Client Access for iSeries is a licensed program and is available on the media distributed with the operating system. ODBC is an option provided with the Client Access tools suite. For security reasons it's best to perform a selective setup and choose only the options you will need (see Figure 1).

 

In the iSeries world, a software patch is known as a PTF or Program Temporary Fix. I cannot stress enough how important these are. Make sure that you download and apply the latest iSeries Client Access PTFs.

Creating a System DSN for ODBC
Create a system DSN with the Windows ODBC Administrator using the iSeries Access ODBC driver. I won't cover all the settings, but I'll point out a few that will make it work better with MX Studio and Server.

Server Tab
Naming convention differences: It's best to use SQL naming instead of system or *SYS. SQL naming uses dotted notation when separating libraries and files. *SYS uses the less-common forward slash mark.

Library list: This is where you set the libraries that this ODBC connection will use to find data. While explicit paths will work in your SQL statements, the libraries will not show up in the Studio MX available libraries list for the data source.

Performance Tab
Use blocking with fetch of one row: Use this option when your application iterates through small blocks of sequential records.

Enable lazy close support: This option prevents unnecessary opening and closing of connections.

Create a ColdFusion Data Source
Open your ColdFusion server administration screen and create a new data source. The type will be ODBC Socket and the name will be the name you gave to the System DSN. Supply a profile and password, verify the data source, and you should be ready to go.

Diagnostics/Troubleshooting
This is where ODBC has bragging rights over JDBC on the iSeries. The ODBC facilities for troubleshooting application performance and connectivity are as comprehensive as they are easy to use. You can access these tools from the Windows 2000 ODBC configuration panel.

Windows 2000 Server
JDBC Configuration Step by Step

IBM provides three JDBC drivers for the iSeries: the Native JDBC driver, the JT400 or IBM Java Toolbox driver, and JTOpen, the open source driver. The native driver, while faster than the others, will only run on the iSeries JVM.

What is the IBM Toolbox for Java? What is JTOpen? What are the differences? The answer is very little. The IBM Toolbox for Java is the polished, refined older brother of JTOpen.

JTOpen is the bleeding-edge open source version of the toolbox. It includes contributions from the open source community along with the newest fixes and enhancements from IBM. JTOpen is covered by the IBM Public License. Perhaps the most significant difference between the two is how the products are supported. JTOpen's support is provided through an online forum whereas the Toolbox is supported through traditional IBM software support channels.

The Toolbox formally known as the "IBM Toolbox for Java" is the licensed version of JTOpen. It's shipped with the iSeries as part of the base operating system and can be referenced by its licensed program code 5722JC1 or 5769JC1 for OS/400 versions prior to V5R1.

IBM Toolbox for Java and JTOpen Installation

  • See www-1.ibm.com/servers/eserver/ iseries/toolbox/faq.htm#faqG and http://publib.boulder.ibm.com/iseries/v5r1/ic2924/ index.htm?info/rzahh/rzahnm04.htm for system requirements.
  • Use iSeries Operations Navigator to locate the Java Toolkit folder on the iSeries. You can find it in the QIBM/ProdData/HTTP/Public/jt400/ IFS folder. If it's not installed, have your system administrator install the licensed program 5722JC1 (V5Rx) or 5769JC1 (V4Rx).

    or

  • Download the latest JTOpen from www-1.ibm.com/servers/eserver/iseries/toolbox/downloads.htm.
  • Create a folder on your ColdFusion MX Server. To minimize the classpath length I put one in the root and called it C:JT400 or C:JTOpen.
  • Copy the contents of QIBM/ProdData/HTTP/Public/jt400/ or extract the JTOpen zip file into your new folder.
  • Using the ColdFusion administrator, navigate to Java and JVM Settings and put C:/JT400/lib/jt400.jar or C:/JTOpen/lib/ jt400.jar into the classpath box. If you have multiple classpaths, separate them with a comma (see Figure 2).

  • Stop and restart the ColdFusion MX Application Server service.
  • Under "Data & Services" on the left navigation bar, click Data Sources. In the "Add Data Source" area, give your data source a name, then choose the other driver type and click Add (see Figure 3).

     

  • CF Data Source Name = My_iSeries
  • JDBC URL = as jdbc:as400://[iSeries server name or address]/[Database Name];prompt=false; You can verify the name by entering the WRKRDBDIRE command on the iSeries. Don't forget the prompt=false. This prevents the iSeries from sending a profile/password dialog box to the ColdFusion server in the event of an invalid profile/password. Without it, the ColdFusion server could hang.
  • Driver Class = com.ibm.as400.access.AS400JDBCDriver
  • Driver Name = Optional
  • Username = Optional. You can always append this information later in your application. I use a username and password during setup and remove it when I know it works.
  • Password=Optional
  • Description=Optional

    ColdFusion is now connected to the iSeries (see Figure 4).

     

    Apple OSX
    JDBC Configuration Step by Step

    The most intriguing capability for Web developers may be OS X's built-in support for Java. OS X ships with Java2 Standard Edition (J2SE), allowing developers a native environment to deploy their Java applications.

    Connecting to the AS400 from JRun and ColdFusion

  • Open the JRun Management Console (JMC) from your browser. Click on the default server link in the "Welcome to Macromedia JRun 4" window.
  • Add a classpath to the JTOpen.jar file you installed into the root level of the hard drive. Click on Settings, then JVM Settings. In the Java VM Settings window, go to the Classpaths for Java VM area, and click the Browse button next to the New Classpath text field. Navigate to the /JTOpen4/lib/jt400.jar file and click Open. The classpath will appear in the "New Classpath" text field. Click Add, then Update at the bottom of the window.
  • Open the ColdFusion MX Administrator.
  • Under Data & Services on the left navigation bar, click Data Sources. In the Add Data Source area, give your data source a name, then choose the other driver type and click Add.
  • In the Add window, enter the JDBC URL as jdbc:as400://[iSeries server name or address]/[Database Name];prompt=false
  • The Driver Class is com.ibm.as400.access.AS400JDBCDriver. The Driver Name field is optional. Enter your AS400 username and password, and a brief description of the data source. Click Submit. You can verify that the data source is connected to the database in the Data Sources window by clicking the checkmark icon next to the data source name.
  • ColdFusion is now connected to the AS400.

    Performance Tips & Additional Settings
    Now that you have a basic connection to the iSeries, it's time to do some performance tuning. While researching this article I performed countless query tests against various driver and server settings. I quickly realized that comprehensive performance tuning was well beyond the scope of this article. I've included links to IBM documentation at the end of the article.

  • Avoid using "Select *": ODBC and JDBC will perform unnecessary field-level processing if you use only a few fields.
  • Use connection pooling: The instantiation of a new connection will result in a noticeable performance hit even on the fastest of systems. New connections to a fast iSeries took an average of 350ms to establish without connection pooling turned on.
  • Install the latest patches from IBM and Macromedia: Not only do they fix problems, they add functionality and performance. Both companies have a good track record when it comes to fixes.
  • Take advantage of DB2's stored procedures: You can call them directly from SQL.

    <cfquery name="myQuery" datasource="my_iSeries">
    { library.program('parm') }
    </cfquery>

    I'm not a DBA and I don't know all that much about packaging in DB2, but if you do and want to use it here's how to set it up:

    jdbc:as400://[iSeries server name or address]/[Database
    Name];prompt=false;libraries=*libl,mylib;extended dynamic=true;
    package=mypackage;package library=mylib;package cache=true;

    Modifying the block size and enabling data compression may also improve performance depending on your workload.

    as jdbc:as400://[iSeries server name or address]/[Database
    Name];prompt=false;libraries=*libl,mylib;block size=512;
    data compression=true;

    Conclusion
    The Java Toolkit comes with literally hundreds of Java classes that you can access using the <cfobject> tag. The simple call in Listing 1 gets disk space information.

    What a combination! A world-class database platform paired up with a world-class Web application server. Thanks to standards, ODBC and JDBC are just the tip of the iceberg when it comes to integrating ColdFusion with the iSeries.

    Acknowledgment
    I'd like to thank my coworker and Apple guru Robert Haddan. He configured, tested, and documented the configuration process on OS X.

    Additional iSeries Resources

  • Troubleshooting ODBC: http://publib.boulder.ibm.com/iseries/v5r2/ic2924/ index.htm?info/rzaii/rzaiiodbc22.HTM
  • Performance Tuning ODBC: http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/ rzaik/rzaikodbcperfconsd.htm
  • JDBC Properties: http://publib.boulder.ibm.com/iseries/v5r2/ic2924/ index.htm?info/rzahh/javadoc/JDBCProperties.html
  • Troubleshooting JDBC: www-1.ibm.com/servers/eserver/iseries/toolbox/ troubleshooting.htm#RecordLevelAccess
  • Performance Tuning JDBC: http://publib.boulder.ibm.com/iseries/v5r2/ic2924/ info/rzaha/jdbcperf.htm
  • More Stories By Jeremy Lyon Lyon

    Jeremy Lyon is the eGovernment Coordinator for the Oregon Department of Revenue. Jeremy has over 15 years of administration and programming experience utilizing systems ranging from the Timex Sinclair 1000 to the Cray XMP supercomputer.

    Comments (14) View Comments

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


    Most Recent Comments
    Jeremy Lyon 04/13/06 02:33:25 AM EDT

    Daron,

    "No suitable driver" usually means that the JVM did not load the JTOpen jt400.jar file

    Is it in the class path?

    Jeremy

    Jeremy Lyon 04/13/06 02:26:16 AM EDT

    geebee,

    If you use CF5 yes. You can do all the configuration in the cfquery tag. If you use CF7 read:

    http://www.macromedia.com/cfusion/webforums/forum/messageview.cfm?catid=...

    It's for Microsoft sql server but I don't see any reason why it would not work with the iSeries.

    SYS-CON Brazil News Desk 04/12/06 01:38:27 PM EDT

    In this article, I'll show you how to connect ColdFusion MX to an IBM iSeries (formerly AS/400) DB2 database. I'll describe your connectivity options and give you configuration examples.

    geebee 04/12/06 01:23:47 PM EDT

    Jeremy,

    Very good article. impressive. We have an AS400 system here from which we retrieve data using Shocase and then put the data into Excel, csv files and MS Access. Very cumbersom though. What we need is an integrated solution from which users can look at data from the AS400 legacy system using some sort of web application, preferrably something built using coldfusion since I am relatively familiar with that. However, I do not have the CF administrator on my machine, due to LAN. It will be probably tough to getr them to load it for me. So, what is a workaround using notepad to link CF and AS400. Any other ideas?

    Thanks in advance,
    -geebee

    Daron 03/03/06 05:13:52 PM EST

    I've tried the instructions for connecting to the 400. I get the following error: java.sql.SQLException: No suitable driver available for PSEAN, please check the driver setting in resources file, error: null
    The root cause was that: java.sql.SQLException: No suitable driver available for PSEAN, please check the driver setting in resources file, error: null

    SYS-CON Germany News Desk 10/15/05 02:48:56 PM EDT

    Macromedia ColdFusion - MX to iSeries Demystified. In this article, I'll show you how to connect ColdFusion MX to an IBM iSeries (formerly AS/400) DB2 database. I'll describe your connectivity options and give you configuration examples.

    ColdFusion Developer's Journal News Desk 10/15/05 01:50:18 PM EDT

    MX to iSeries Demystified. In this article, I'll show you how to connect ColdFusion MX to an IBM iSeries (formerly AS/400) DB2 database. I'll describe your connectivity options and give you configuration examples.

    Tom McHugh 10/15/05 01:22:04 PM EDT

    Jeremy:

    Will the steps outlined in your article "MX to iSeries Demystified" be the same under Windows 2003 Server? Thanks!

    Uwe Raddatz 01/15/04 10:05:07 AM EST

    Hi,

    I am using the JTOpen 4.1 JDBC driver to access an iSeries server. Sometimes it happens, a stored procedure call hangs in reason of problems during execution on the database server. The JDBC driver does not throw an exception, so the page request will not be answered.

    I set the "Timeout Requests after ..." setting to 60 seconds but this only works for pure ColdFusion tags such as . It does not work for stored procedure calls. Also there's no timeout parameter for the JDBC driver. :(

    So these non-responding requests accumulate up to the number defined in the "Maximum number of simultaneous requests" setting in ColdFusion Administrator. Further requests will be queued - finally no request will be answered until ColdFusion server will be restarted.

    It's a dissatisfying situation. ;) Any suggestions to find a solution?

    Bye.

    Jeremy Lyon 12/11/03 11:25:50 PM EST

    Hi,

    DB2/400 CHAR pads the field to the field length. VARCHAR does not. To strip the spaces I would:

    Trim it at the SQL level i.e.,

    SELECT trim(fieldname) as field

    OR create a db2 view of the file i.e.,

    Create view qgpl.table_view as Select Trim(charfield) trimed_char From qgpl.table

    Jeremy

    Uwe Raddatz 12/11/03 06:49:01 AM EST

    Can anyone tell me how to prevent that query result fields will be filled up with blanks up to the maximum length of the column?

    And what could be the reason of sporadic and unreproducible exceptions when calling queries or stored procedures (see stack trace below)?

    java.lang.NumberFormatException: 266
    at com.ibm.as400.access.AS400ZonedDecimal.toObject(AS400ZonedDecimal.java:421)
    at com.ibm.as400.access.SQLNumeric.convertFromRawBytes(SQLNumeric.java:89)
    at com.ibm.as400.access.JDServerRow.getSQLData(JDServerRow.java:400)
    at com.ibm.as400.access.AS400JDBCResultSet.getValue(AS400JDBCResultSet.java:3612)
    at com.ibm.as400.access.AS400JDBCResultSet.getObject(AS400JDBCResultSet.java:3023)
    at coldfusion.sql.QueryTable.populate(QueryTable.java:272)
    at coldfusion.sql.Executive.getRowSets(Executive.java:559)
    at coldfusion.sql.Executive.executeCall(Executive.java:814)
    at coldfusion.sql.Executive.executeCall(Executive.java:749)
    at coldfusion.sql.SqlImpl.executeCall(SqlImpl.java:313)
    at coldfusion.tagext.sql.StoredProcTag.doEndTag(StoredProcTag.java:192)

    Thanx for help.

    Jeremy Lyon 12/10/03 11:09:11 PM EST

    Other than setting up the JTOpen toolbox, the OSX setup was run of the mill. I had the JRun stuff in the draft but it really didn't add anything to Macromedia's instructions so I cut it.

    If you have specific questions I would be happy to help.

    Rob Brooks-Bilson 12/10/03 04:45:04 PM EST

    If you are running CF MX for J2EE, you can drop the jt400.jar file in {jrun.home}/servers/lib/. This keeps you from having to specify it's location in you Java CLASSPATH.

    Andy Karas 12/09/03 05:08:01 PM EST

    I couldn't find any reference to JRun/ColdFusion MX 6.1 on Apple OSX 10.1.5 in this article.

    Is there a similar article which outlines how to use ColdFusion on Mac OSX?

    @ThingsExpo Stories
    One of the biggest challenges when developing connected devices is identifying user value and delivering it through successful user experiences. In his session at Internet of @ThingsExpo, Mike Kuniavsky, Principal Scientist, Innovation Services at PARC, described an IoT-specific approach to user experience design that combines approaches from interaction design, industrial design and service design to create experiences that go beyond simple connected gadgets to create lasting, multi-device experiences grounded in people's real needs and desires.
    Enthusiasm for the Internet of Things has reached an all-time high. In 2013 alone, venture capitalists spent more than $1 billion dollars investing in the IoT space. With "smart" appliances and devices, IoT covers wearable smart devices, cloud services to hardware companies. Nest, a Google company, detects temperatures inside homes and automatically adjusts it by tracking its user's habit. These technologies are quickly developing and with it come challenges such as bridging infrastructure gaps, abiding by privacy concerns and making the concept a reality. These challenges can't be addressed w...
    The Domain Name Service (DNS) is one of the most important components in networking infrastructure, enabling users and services to access applications by translating URLs (names) into IP addresses (numbers). Because every icon and URL and all embedded content on a website requires a DNS lookup loading complex sites necessitates hundreds of DNS queries. In addition, as more internet-enabled ‘Things' get connected, people will rely on DNS to name and find their fridges, toasters and toilets. According to a recent IDG Research Services Survey this rate of traffic will only grow. What's driving t...
    Connected devices and the Internet of Things are getting significant momentum in 2014. In his session at Internet of @ThingsExpo, Jim Hunter, Chief Scientist & Technology Evangelist at Greenwave Systems, examined three key elements that together will drive mass adoption of the IoT before the end of 2015. The first element is the recent advent of robust open source protocols (like AllJoyn and WebRTC) that facilitate M2M communication. The second is broad availability of flexible, cost-effective storage designed to handle the massive surge in back-end data in a world where timely analytics is e...
    Scott Jenson leads a project called The Physical Web within the Chrome team at Google. Project members are working to take the scalability and openness of the web and use it to talk to the exponentially exploding range of smart devices. Nearly every company today working on the IoT comes up with the same basic solution: use my server and you'll be fine. But if we really believe there will be trillions of these devices, that just can't scale. We need a system that is open a scalable and by using the URL as a basic building block, we open this up and get the same resilience that the web enjoys.
    We are reaching the end of the beginning with WebRTC, and real systems using this technology have begun to appear. One challenge that faces every WebRTC deployment (in some form or another) is identity management. For example, if you have an existing service – possibly built on a variety of different PaaS/SaaS offerings – and you want to add real-time communications you are faced with a challenge relating to user management, authentication, authorization, and validation. Service providers will want to use their existing identities, but these will have credentials already that are (hopefully) i...
    "Matrix is an ambitious open standard and implementation that's set up to break down the fragmentation problems that exist in IP messaging and VoIP communication," explained John Woolf, Technical Evangelist at Matrix, in this SYS-CON.tv interview at @ThingsExpo, held Nov 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA.
    How do APIs and IoT relate? The answer is not as simple as merely adding an API on top of a dumb device, but rather about understanding the architectural patterns for implementing an IoT fabric. There are typically two or three trends: Exposing the device to a management framework Exposing that management framework to a business centric logic Exposing that business layer and data to end users. This last trend is the IoT stack, which involves a new shift in the separation of what stuff happens, where data lives and where the interface lies. For instance, it's a mix of architectural styles ...
    The Internet of Things will put IT to its ultimate test by creating infinite new opportunities to digitize products and services, generate and analyze new data to improve customer satisfaction, and discover new ways to gain a competitive advantage across nearly every industry. In order to help corporate business units to capitalize on the rapidly evolving IoT opportunities, IT must stand up to a new set of challenges. In his session at @ThingsExpo, Jeff Kaplan, Managing Director of THINKstrategies, will examine why IT must finally fulfill its role in support of its SBUs or face a new round of...
    Cultural, regulatory, environmental, political and economic (CREPE) conditions over the past decade are creating cross-industry solution spaces that require processes and technologies from both the Internet of Things (IoT), and Data Management and Analytics (DMA). These solution spaces are evolving into Sensor Analytics Ecosystems (SAE) that represent significant new opportunities for organizations of all types. Public Utilities throughout the world, providing electricity, natural gas and water, are pursuing SmartGrid initiatives that represent one of the more mature examples of SAE. We have s...
    The Internet of Things will greatly expand the opportunities for data collection and new business models driven off of that data. In her session at @ThingsExpo, Esmeralda Swartz, CMO of MetraTech, discussed how for this to be effective you not only need to have infrastructure and operational models capable of utilizing this new phenomenon, but increasingly service providers will need to convince a skeptical public to participate. Get ready to show them the money!
    P2P RTC will impact the landscape of communications, shifting from traditional telephony style communications models to OTT (Over-The-Top) cloud assisted & PaaS (Platform as a Service) communication services. The P2P shift will impact many areas of our lives, from mobile communication, human interactive web services, RTC and telephony infrastructure, user federation, security and privacy implications, business costs, and scalability. In his session at @ThingsExpo, Robin Raymond, Chief Architect at Hookflash, will walk through the shifting landscape of traditional telephone and voice services ...
    The Internet of Things is tied together with a thin strand that is known as time. Coincidentally, at the core of nearly all data analytics is a timestamp. When working with time series data there are a few core principles that everyone should consider, especially across datasets where time is the common boundary. In his session at Internet of @ThingsExpo, Jim Scott, Director of Enterprise Strategy & Architecture at MapR Technologies, discussed single-value, geo-spatial, and log time series data. By focusing on enterprise applications and the data center, he will use OpenTSDB as an example t...
    Explosive growth in connected devices. Enormous amounts of data for collection and analysis. Critical use of data for split-second decision making and actionable information. All three are factors in making the Internet of Things a reality. Yet, any one factor would have an IT organization pondering its infrastructure strategy. How should your organization enhance its IT framework to enable an Internet of Things implementation? In his session at Internet of @ThingsExpo, James Kirkland, Chief Architect for the Internet of Things and Intelligent Systems at Red Hat, described how to revolutioniz...
    Bit6 today issued a challenge to the technology community implementing Web Real Time Communication (WebRTC). To leap beyond WebRTC’s significant limitations and fully leverage its underlying value to accelerate innovation, application developers need to consider the entire communications ecosystem.
    The definition of IoT is not new, in fact it’s been around for over a decade. What has changed is the public's awareness that the technology we use on a daily basis has caught up on the vision of an always on, always connected world. If you look into the details of what comprises the IoT, you’ll see that it includes everything from cloud computing, Big Data analytics, “Things,” Web communication, applications, network, storage, etc. It is essentially including everything connected online from hardware to software, or as we like to say, it’s an Internet of many different things. The difference ...
    Cloud Expo 2014 TV commercials will feature @ThingsExpo, which was launched in June, 2014 at New York City's Javits Center as the largest 'Internet of Things' event in the world.
    SYS-CON Events announced today that Windstream, a leading provider of advanced network and cloud communications, has been named “Silver Sponsor” of SYS-CON's 16th International Cloud Expo®, which will take place on June 9–11, 2015, at the Javits Center in New York, NY. Windstream (Nasdaq: WIN), a FORTUNE 500 and S&P 500 company, is a leading provider of advanced network communications, including cloud computing and managed services, to businesses nationwide. The company also offers broadband, phone and digital TV services to consumers primarily in rural areas.
    "There is a natural synchronization between the business models, the IoT is there to support ,” explained Brendan O'Brien, Co-founder and Chief Architect of Aria Systems, in this SYS-CON.tv interview at the 15th International Cloud Expo®, held Nov 4–6, 2014, at the Santa Clara Convention Center in Santa Clara, CA.
    The major cloud platforms defy a simple, side-by-side analysis. Each of the major IaaS public-cloud platforms offers their own unique strengths and functionality. Options for on-site private cloud are diverse as well, and must be designed and deployed while taking existing legacy architecture and infrastructure into account. Then the reality is that most enterprises are embarking on a hybrid cloud strategy and programs. In this Power Panel at 15th Cloud Expo (http://www.CloudComputingExpo.com), moderated by Ashar Baig, Research Director, Cloud, at Gigaom Research, Nate Gordon, Director of T...