The IBM AS/400 SDK for ActiveX and OLE DB is an excellent tool for developing mainstream client/server applications with the AS/400. With the wide range of access methods available, you can create a reliable business-caliber application and obtain satisfactory performance. The SDK is well designed, full featured, and free—and it interfaces easily with PC programming languages like Visual Basic.

Once it was called Project Lightning. Then, it became the Lightning Software Development Kit (SDK). Finally, its official name is the IBM AS/400 SDK for ActiveX and OLE DB. Are you still confused about what it is and what it does? Do you feel like you need a Ph.D. in client/serverology to understand it? Well, don’t worry. This article removes some of the mystery from IBM’s newest PC server package and explains how it works with Client Access and PC programming languages (such as Visual Basic, Delphi, and PowerBuilder) to provide seamless Microsoft OLE DB-to-AS/400 connectivity for your PC-based applications.

With the SDK, your PC applications can access DB2/400 files and AS/400 data queues, call AS/400 programs, and execute OS/400 commands, SQL statements, and stored procedures. I’ll introduce SDK, explaining what it is; how it interfaces with Microsoft’s OLE DB and ActiveX; and how you order, install, and get technical support for the product. It even provides sample code so you can program your first Visual Basic- to-AS/400 application. (Editor’s note: All sample code printed here is available for download on the Web at www.midrangecomputing.com/mc/98/10). You’ll also explore some of the not-so-insignificant problems involved in using the new SDK. You’ll be accessing AS/400 data from your PC programming languages in no time after you read this article.

What About the Name?

First, there’s that name—the IBM AS/400 SDK for ActiveX and OLE DB. Although accurate, it’s not exactly catchy. It’s way too long and carries more letters than a

mailman. Is it any wonder, then, that many programmers still call it the Lightning SDK or, more properly, the AS/400 ActiveX SDK?

Perhaps you’ll get a better idea of what the OLE DB Provider and the SDK are after you examine the conditions that spawned their existence from IBM’s point of view.

As you well know, IBM intends to place the AS/400 in the center of the server market fray. To this end, IBM has endeavored to address criticisms of the AS/400’s role as a server through a policy of “embrace and extend.” In other words, IBM has eliminated or will eliminate the grounds for each well-founded knock on the AS/400 by “making the AS/400 do that,” whatever that is.

In the face of this policy, IBM also realizes that Microsoft’s Windows programming technology (called OLE Automation or just Automation) has an indefatigable presence in the real world (i.e., Microsoft claims an amazing 3 million Visual Basic programmers are out there). To quiet any criticism that AS/400 data and processing are inaccessible to Windows programmers, IBM created a Microsoft OLE Automation- compatible gateway to AS/400 data and programs. This gateway, called the Client Access OLE DB Provider, is designed to work with Microsoft’s latest universal data access technology: OLE DB and ADO. Microsoft also provides an OLE DB Provider with SNA Server 4.0. However, SNA Server will cost you, and it might be overkill to buy SNA Server just to get the OLE DB Provider. (For more information about Microsoft’s OLE DB Provider, see the “OLE DB Provider for AS/400 and VSAM” sidebar.)

The Client Access OLE DB Provider is somewhat misunderstood because it gives you nothing to look at. It includes no user interface screens or dialog boxes. You don’t have a menu option that starts the DB Provider, nor do you set DB Provider properties as you do for Client Access connections.

The OLE DB/ADO object is an OLE Automation Server. In this case, that means it is a wrapper (a consolidation of functions fitted with a more convenient interface) for low- level communications processes with a server. When used with the Client Access OLE DB Provider, the OLE DB/ADO object has access to the AS/400 that Windows invokes under the covers whenever needed. OLE Automation technology makes an object’s processes (called methods) and data (called properties) available to other programs. The set of externally available properties and methods is said to be the object’s exposed or public interface. The manner in which an object’s public interface is laid out is called its object model.

For example, consider the PC programming code in Figure 1 to declare an object variable named MyConnectionObject as type AD400.Connection. (A connection object is part of OLE DB/ADO support or, as in this instance, IBM’s additional support for record- level access to indexed files. A connection object provides physical communication with the AS/400.) In each code example, the DB Provider supplies the information needed to create an object representing a connection to the AS/400.

Windows programming languages take advantage of underlying support within Windows for making external processes and data available to Automation-enabled programs. How you use this Microsoft technology is determined by rules called the Component Object Model (COM).

Microsoft’s OLE DB/ADO Support

The IBM Client Access OLE DB Provider takes advantage of a recent Microsoft technology called OLE DB (pronounced o-lay dee-bee). This technology provides the underlying support for access to a variety of databases in an OLE Automation format. Although you can code directly to the OLE DB interface, a more friendly access is gained through use of yet another layer—the ActiveX Data Object (ADO).

The ADO is a wrapper for complex interactions with OLE DB. It provides a more workable interface to OLE DB and is employed by the Client Access OLE DB Provider to supply AS/400 data and processes.

The base support for OLE DB and ADO is part of Microsoft’s Universal Data Access technology (see http://www.microsoft.com/ data for more information). The support programs you need to install on your PC to use OLE DB/ADO may come from a variety of sources, including IBM ActiveX SDK and Microsoft Visual Studio 6.0. You can also download it from Microsoft. This base support, however, is only half of the picture. The base OLE DB/ADO support needs specific processing information and connectivity capability for each database to which it is to connect. This is where the Client Access OLE DB Provider comes in. It works together with base OLE DB support, through the ADO layer, to provide access to a specific database: the AS/400.

Feeling a Bit Orphaned

The IBM SDK for ActiveX has suffered from a high level of anticipation prior to its release and a low profile for the actual product since. Although the SDK development team is dedicated to the package, one gets the feeling that IBM management merely tolerates its existence and is annoyed by having to embrace a Microsoft technology. (Links to the SDK team’s Web site remain conspicuously absent from other IBM sites.) Nevertheless, the AS/400 SDK is included in Client Access/400 base support (V3R1M3 and higher or by PTF to prior releases).

Regardless of IBM’s low regard for its own product, the IBM SDK for ActiveX and OLE DB is a valuable yet possibly unappreciated set of tools that an AS/400 applications programmer can use almost immediately to create business-caliber client/server applications. The product’s connection stability is acceptable, as is its communications performance.

IBM Support for the SDK

IBM handles support for the SDK differently than for other products. According to IBM, the SDK is provided more or less on an as is basis. If you call the support line, you probably will not obtain formal help-desk support for your problem. However, this doesn’t signify a total lack of support for the SDK. The development team provides SDK support informally through email; you can send questions to the team at This email address is being protected from spambots. You need JavaScript enabled to view it..

The programmers who use the SDK might actually benefit from this arrangement, at least for now. Considering how much it costs to get even one formal development question answered by IBM Partners in Development, it might be considered even a bargain to get email answers.

The IBM team also offers SDK service packs through the Web, so they are updating the product and providing fixes. The first service pack is currently available at the AS/400 SDK for ActiveX and OLE DB Web site at http://www.as400.ibm.com/clientaccess/oledb. Once you reach the site, the option to download the service pack is contained in the page text, not in the download options on the left-hand side of the screen.

What Can You Do with the ActiveX SDK?

The Client Access OLE DB Provider object is a set of specially constructed Windows routines that work with Client Access/400 to communicate with corresponding support programs on the AS/400. These programs come with Client Access and allow access to the following AS/400 data and processes:

• Files (tables)—Access DB2/400 files at the record level for insert, update, or delete operations.

• Data queues—Create, clear, or delete AS/400 data queues; read or write data queue entries.

• Programs—Call a user-written AS/400 application program from the client program and pass both input and output parameters.

• Commands—Execute AS/400 commands from the client.
• SQL statements—Interact with AS/400 files directly with SQL statements.
• SQL stored procedures—Manage and execute AS/400 stored procedures; return result sets.

This is not to suggest, however, that you need to know how to use all of these features in order to use any of them. They can function independently and don’t necessarily go together. Most applications will use, at most, two of these access types. For example, you might build a client/server application that uses data queues to pass data back and forth. In this same application, you’ll need a means of starting your AS/400 data queue partner program. The AS/400 command feature of the SDK will fill this need nicely by allowing you to issue the AS/400 Submit Job (SBMJOB) command to start the partner program.

How Do You Use the SDK?

When properly installed (see the “Installing the IBM AS/400 SDK for ActiveX and OLE DB” sidebar), the SDK makes itself known to Automation support through the Windows registry. Your client programming language can then access the SDK’s object library by reference. Therefore, prerequisite to the use of the SDK is a knowledge of your client language’s mechanism for establishing a reference to an OLE Automation server.

For example, in Visual Basic 5.0, references to support for record-level access to DB2/400 files and Microsoft’s OLE DB ADO support are set by taking the References... option from the Project menu within the Integrated Development Environment (IDE). Place a check mark next to the entry for AS/400 SDK Runtime Tables Index Reads Type Library (it may be listed as cwbzzidx 1.0 Type Library) to set a reference to record-level access support. Once added, the reference text will become AS/400 SDK Runtime Tables Index Reads Type Library. Also place a check next to the entry for Microsoft’s support for OLE DB/ADO—Microsoft OLE DB ActiveX Data Objects 1.0 Library. After selecting both these items, click OK, and your application will support the SDK (see Figure 2). Also, for Visual Basic 5.0, you must reference these Automation servers for every program you write that uses the SDK. They are not carried over from application to application.

Once a reference is set, the public methods and properties provided by the Client Access OLE DB Provider and ADO are available to your Visual Basic program.

You should understand that Microsoft OLE DB/ADO technology uses the Client Access OLE DB Provider to get at AS/400 data and processing. You don’t declare a reference to Client Access OLE DB Provider to use it; you pass its name to the OLE DB/ADO object. You then use methods and properties of the OLE DB/ADO objects to get to the AS/400 data and processing. Microsoft’s OLE DB/ADO, however, does not support record-level access to indexed files at this time. To remedy this shortcoming, the IBM SDK development team has provided an additional library of objects: the AS/400 SDK Runtime Tables Index Reads Type Library. The set of objects contained in this library will retrieve a pointer (called a bookmark) to a given record by key. The bookmark may then be used by OLE DB/ADO to actually retrieve the record (see program examples in Figures 5 and 6 on the Web at http://www.midrangecomputing.com/mc/98/10).

Learning the OLE DB Provider and ADO Object Models

Each access type available within the Client Access OLE DB Provider has exposed methods and properties appropriate for it, collectively called a public interface. Once you decide which type to use, your next step involves studying the public interface and learning how to use it.

You have several tools available to help you with this. You can (and should) read the ADO and Technical Reference help documentation installed as part of the SDK. These documents provide overviews and technical reference information essential to use ADO and the OLE DB Provider.

You must become familiar with the basics of the ADO layer of OLE DB. Once a connection is made through the Client Access OLE DB Provider, standard ADO methods and properties are used to actually read and write data.

For another source, you can consult the sample programs provided as part of the SDK. Sample programs are included for Visual Basic 4.0 and 5.0, Delphi 2.0 and 3.0, PowerBuilder 5.0, and Visual C++ 5.0. Further, if you’re using Visual Basic, you can employ the add-in wizard for Visual Basic that comes with the SDK to generate skeletal

Visual Basic program code (Figure 3). The code can then be fleshed out to form a real application (see the “Installing the the IBM AS/400 SDK for ActiveX and OLE DB” sidebar for notes about installing the wizard.)

Sequential and Record-level Access to an AS/400 File with Visual Basic

Perhaps the most valuable tool in the SDK is the ability to access AS/400 file data at the record level. This type of access, presented in the following example, most closely aligns with standard AS/400 programming practices. The example described here shows how to read an AS/400 file sequentially.

This section of the article also presents a second example on how to retrieve a record by key, but the code for that example resides on Midrange Computing’s Web site at http://www.midrangecomputing.com/mc/98/10. The code for the sequential read program is also available for download from MC’s Web site.

Accessing an AS/400 File Sequentially

This Visual Basic 5.0 program simply reads an unknown number of AS/400 source file records into a list box using the familiar coding technique of reading a record and entering a DO loop that contains another read at the bottom. In RPG IV, this technique would look like the code listing in Figure 4.

This humble application of the SDK can get by with only the functionality that comes with ADO (with an internal assist from the IBMDA400 data provider), so you’ll only need to set a reference to Microsoft OLE DB ActiveX Data Objects 1.0 Library (see Figure 2). Once you’ve done this, you may define objects needed to access the AS/400 and to read data, as the code in Figure 5 illustrates.

The connection object is used to tell ADO support to use the IBMDA400 access provider and to connect to the AS/400. The command object tells ADO support which file to open and which access method to use. The recordset object is needed to accept the results of the execution of the command object. You normally declare these objects as public so they can be used throughout a form or program.

The code listing in Figure 6 creates the objects defined in Figure 5 and uses the recordset object to fill a list box for display. The sample data comes from file QDDSSRC in library QGPL, member *FIRST. (On most systems, the QDSIGNON source code will be present.)

Figures 5 and 6 contain all the code required to read through an AS/400 file sequentially—in this case, to fill a list box at program startup time. You must also create a Visual Basic form named Form1 that contains one list box called List1 to display the output from your QDDSSRC source file. For information on creating Visual Basic forms, see your Visual Basic programming documentation.

In the sample code, the first reference point, denoted by (1), shows the necessary objects being created with the Set statements. In reference point (2), the Open method of the connection object defines and establishes a connection. Notice that the name of the ADO connection provider (IBMDA400) is supplied, as is the name of the AS/400 (Sxxxxxxx, where Sxxxxxxx is your system name). You use the remaining two arguments to specify a user ID and password. If none are specified, your current user ID is used or a sign-on panel is displayed. The Set statement at reference point (3) then associates the command object’s ActiveConnection property with the new connection.

At reference point (4), the CommandText property of the command object is set to the desired AS/400 file, using the following syntax:

LIBRARY/FILE(MEMBER, RECORD FORMAT, COMMITMENT CONTROL)

Don’t confuse the term command as used here with AS/400 CL command. Here, it means query command—a request for data from a file.

The line at (5) creates a parameter object to be sent to the IBMDA400 access provider. The parameter’s name will be P1, of type character. This line further specifies P1 as an input type of parameter of length 1. The parameter is not given an initial value. (Note:

If the P1 parameter is not created and appended to the command object, the open table will not work correctly when you use ADO 1.0. This problem has been fixed in ADO 1.5. For more information, see the Installing ADO 1.5 topic in the SDK Technical Reference.)

In the next line (6), the rubber meets the road. The query command is executed and the results are obtained in a recordset object. The first two arguments are varRcds, or records affected by an update (not applicable in this case), and varParms, or parameter values passed with an SQL statement (also not applicable). These two optional arguments are in place only to allow the third argument adCmdTable—a value that tells ADO to interpret the command string to be the name of a file rather than a literal command.

The With structure at (7) is just shorthand. The .MoveFirst statement sets the file pointer to the first record and reads it. The DO loop at (8) loads a record into the list box and reads the next record until an EOF condition is met. Once the file has been read, the connection, command, and recordset objects are no longer needed, so they are destroyed with the Set statements at (9). The list box is then displayed (Figure 7).

Accessing an AS/400 Record by Key

A second Visual Basic program to retrieve AS/400 records by key is available for download on MC’s Web site. This program uses the same objects as the sequential read program, but retrieving records by key requires the help of the Client Access OLE DB Provider. Currently, OLE DB does not support a Seek or FindFirst method, so the Client Access OLE DB Provider comes with an index object to determine the file’s cursor position for a given key value. The cursor position (called a bookmark) is then passed to the recordset object to retrieve the record in question. For further discussion and an example of how this is accomplished, please refer to the code on the Web site.

Recommendations for Using the SDK

The IBM AS/400 SDK for ActiveX and OLE DB is an excellent tool for developing mainstream client/server applications with the AS/400. With the wide range of access methods available, you can create a reliable business-caliber application and obtain satisfactory performance. The package is well designed, full featured, and free.

The SDK, however, relies on the proper support software being present on the AS/400. Until this level of OS/400 is widespread, applications built with the SDK and intended for general distribution may be difficult to deploy and support. But for everyone else...what are you waiting for?!

OLE DB Provider for AS/400 and VSAM

If desktop connectivity to the AS/400 is involved, you can be sure that Microsoft is involved as well, even if it’s a simple single connection to a desktop Windows PC. For years, Microsoft has offered communication products; and, for AS/400 users, its BackOffice product known as SNA Server is particularly interesting. SNA Server’s primary purpose is to provide a gateway between a Windows NT LAN and the AS/400.

Undoubtedly, gateways can reduce the resources required on a single AS/400 server by distributing services to other systems. Gateways can also open the door to additional features you might not be able to get from a single-server environment.

Universal Data Access and OLE DB

Over the past several years, Microsoft has also developed core technologies meant to provide access to data whether it resides on a desktop system or on the enterprise. Microsoft calls this technology platform Universal Data Access. Universal Data Access consists of a collection of software components that interact with each other, such as ActiveX Data Objects (ADO), OLE DB, Remote Data Service (RDS), and even Component Object Model (COM).

Of these technologies, the OLE DB component is very useful in AS/400 shops. It comes included as a component of Microsoft’s SNA Server 4.0 gateway, so it’s virtually free if you already use SNA Server. The

official name of the component is Microsoft’s OLE DB Provider for AS/400 and VSAM, but most people refer to it as OLE DB. To obtain more information on SNA Server and OLE DB as whole, see the Microsoft SNA Server home page at http://www.microsoft.com/sna/default.asp.

The history of Microsoft’s OLE DB goes as follows. While IBM was developing Project Lightning to produce the AS/400 SDK for ActiveX and OLE DB, Microsoft was developing a competing technology called Thor that also aimed to provide record-level access to the AS/400 from PCs. Thor evolved into the OLE DB component of SNA Server, so the two terms are sometimes used interchangeably.

One of the biggest benefits of OLE DB to an AS/400 developer—that it provides record-level access to AS/400 files—is only the beginning. Developers also gain the advantage of using OLE DB as a common interface to dissimilar databases in the enterprise. And OLE DB offers both PC-to-host and Web-to-host data access. See Figure A for an illustration of how OLE DB fits into this type environment.

As for the AS/400, OLE DB includes the following:
• Support for keyed and nonkeyed physical files and logical files
• Reading from and writing to AS/400 files without first transferring the information to the PC platform
• Because of its record-level access features, integration of PC applications with nonstructured data (flat files, such as S/36 files or Integrated File System [IFS] files) with desktop and server-based databases and tools, and Web applications
• Client/server development using high-level interfaces, such as ADO, supported in Visual Basic, Visual C++, Visual J++, Visual Basic for Applications, and ActiveX Scripting.

In order for OLE DB to gain access to your AS/400 files, you define data sources much as you would in ODBC. OLE DB (or ADO) accesses AS/400 files through OS/400’s Distributed Data Management (DDM) architecture and through the native AS/400 SNA environment. For the ODBC programmer who wants to learn OLE DB, Microsoft offers a white paper on the Web called OLE DB for the ODBC Programmer that explains OLE DB concepts in terms of ODBC. That paper is available at http://www.microsoft.com/data/oledb/ prodinfo/wpapers/oledb4odbc.htm.

A Microsoft-only Solution

As is often the case with Microsoft products, OLE DB is feature rich, but be aware that it makes many of its benefits possible only through other Microsoft products such as SNA Server and Internet Information Server. If you buy into Microsoft’s Universal Data Access platform, you’ve probably already bought into other Microsoft products, or chances are good that you soon will.

Ñ Richard Shaler

Windows NT

SNA Server OLE DB

Internet Information Server

DB2/400

LAN

Record-level Access

Browser

Internet

Figure A: The OLE DB environment

Installing the IBM AS/400 SDK for ActiveX and OLE DB

To install the new SDK, do the following:

• Install Client Access/400 V3R1M3 or above on the AS/400. (Note that the version number for Client Access does not correspond to your OS/400 version number.)

• Check the AS/400 ActiveX SDK Web site at http://www.as400.ibm.com/clientaccess/oledb for recent AS/400 PTF information.

• Install the most current cumulative PTFs for your version of OS/400 if you want to use record-level access over native TCP/IP connections (WinSock).

• Install the most recent Client Access service pack on the PC (SF48155 for V3R1M3 at this writing, but another V3R1M3 service pack is scheduled to be released on October 7, 1998. V3R2, being a new product, may also have a service pack available by the time you read this). Service packs are available at IBM’s Client Access Web site at http://as400.rochester.ibm.com/clientaccess/.

• If you’re not running Client Access V3R2, download the SDK installation package from the IBM development team’s Web site (it’s free). This file, named SETUPEX.EXE, is a 3.8 Mb self-extracting zip file. For Client Access/400 V3R2, the SDK setup program is available on your Client Access/400 CD.

• Install the SDK, taking all of the defaults presented.

A development PC or a PC running applications built with the SDK relies on corresponding partner programs to be present on the AS/400. While OS/400 V4R2 and above includes all AS/400 support for the SDK within Client Access, users of prior versions and release levels of OS/400 must apply appropriate PTFs to load the AS/400 support code for record-level access over TCP/IP. (Other forms of SDK access to the AS/400 do not require PTFs.) You can obtain further details at the SDK team’s Web site.

Check the team’s support Web site for late-breaking information. For example, presently, if you plan to use the Add-Ins wizard for Visual Basic 4.0/5.0, you should download the replacement wizard library file cwbzzvbw.dll, now available at the AS/400 SDK Web site. Be sure to follow the installation directions provided.

Note: Particular applications may have additional requirements. For instance, to have record-level access to AS/400 files over a pure TCP/IP connection, you must start the TCP/IP server for DDM on the AS/400. To do so, you use the Start TCP/IP Server (STRTCPSVR) command as follows:

STRTCPSVR SERVER(*DDM)

— Chris Peters

Delphi example
MyConnectionObject : Variant;
MyConnectionObject := CreateOleObject('ad400.connection');

PowerBuilder example
oleobject MyConnectionObject
MyConnectionObject = CREATE OLEObject
MyConnectionObject.ConnectToNewObject ("ad400.connection")

Visual Basic example
Public MyConnectionObject As AD400.Connection

Set MyConnectionObject = New AD400.Connection

Figure 1: Various examples of PC code declare an object variable as type AD400.Connection

Figure 2: Set the references to Client Access OLE DB Provider and Microsoft’s OLE DB ADO to make Visual Basic support the SDK

Figure 3: SDK’s Visual Basic Add-Ins wizard allows you to generate skeletal Visual Basic code

C *LoVal SetLL MyFile
C Read MyFile 20
C DoW *In20 = *Off
C ...write to subfile...

C Read MyFile 20
C EndDo

Figure 4: RPG IV technique reads an unknown number of AS/400 source file records

Option Explicit
Public objADOConnection As ADODB.Connection
Public objADOCommand As ADODB.Command
Public objADORecordSet As ADODB.Recordset

Figure 5: Visual Basic 5.0 code to create objects for the program listed in Figure 6

Private Sub Form_Load()

Dim varRcds As Variant

Dim varParms As Variant

(1) Set objADOConnection = New ADODB.Connection
Set objADOCommand = New ADODB.Command
Set objADORecordSet = New ADODB.Recordset

(2) objADOConnection.Open “Provider=IBMDA400;Data Source=Sxxxxxxx;”, “”, “”
(3) Set objADOCommand.ActiveConnection = objADOConnection

(4) objADOCommand.CommandText = “QGPL/QDDSSRC(*FIRST, *FIRST, *NONE)”
(5) objADOCommand.Parameters.Append _
objADOCommand.CreateParameter(“P1”, adChar, adParamInput, 1)
(6) Set objADORecordSet = objADOCommand.Execute(varRcds, varParms, _
adCmdTable)

(7) With objADORecordSet

.MoveFirst
(8) Do While Not .EOF

List1.AddItem .Fields(“SRCDAT”) & “ “ & .Fields(“SRCDTA”)

.MoveNext

Loop
End With

(9) Set objADORecordSet = Nothing
Set objADOCommand = Nothing
Set objADOConnection = Nothing

End Sub

Figure 6: Visual Basic 5.0 code to read and display the first member of the QGPL/QDDSSRC file

Figure 7: This list box is displayed when you run the VB program to sequentially read and display the first member of a QGPL/QDDSSRC file