IBM U2 MultiValue Add-ins for Visual Studio

LINQ Tutorial

Version 1.1.2 November 2008

IBM Corporation 555 Bailey Avenue

San Jose, CA 95141

Licensed Materials – Property of IBM

© Copyright International Business Machines Corporation 2008. All rights reserved.

AIX, DB2, DB2 Universal Database, Distributed Relational Database Architecture, NUMA-Q, OS/2, OS/390, and OS/400, IBM Informix®, C-ISAM®, Foundation.2000 ™, IBM Informix® 4GL, IBM Informix® DataBlade® module, Client SDK™, Cloudscape™, Cloudsync™, IBM Informix® Connect, IBM Informix® Driver for JDBC, Dynamic Connect™, IBM Informix® Dynamic Scalable Architecture™ (DSA), IBM Informix® Dynamic Server™, IBM Informix® Enterprise Gateway Manager (Enterprise Gateway Manager), IBM Informix® Extended Parallel Server™, i.Financial Services™, J/Foundation™, MaxConnect™, Object Translator™, Red Brick® Decision Server™, IBM Informix® SE, IBM Informix® SQL, InformiXML™, RedBack®, SystemBuilder™, U2™, UniData®, ®, wIntegrate® are trademarks or registered trademarks of International Business Machines Corporation.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

Portions Copyright © ComponentOne, LLC 1991-2006. All Rights Reserved.

Microsoft .NET, Windows, Windows NT, and Excel are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited.

Other company, product, and service names used in this publication may be trademarks or service marks of others.

Information Development Team: Claire Gustafson, Shelley Thompson, Anne Waite

US GOVERNMENT USERS RESTRICTED RIGHTS

Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

ii

iii

Table of Contents Unit 1 1 

Product Overview 1 

Feature Overview ........................................................................................... 2 The U2.NET Suite ...................................................................................... 2 

Unit 2 3 

LINQ Tutorial 3 

Building an Application Using Core Objects ................................................... 4 

Unit 3 5 

Creating Profiles 5 

Creating a Server Profile ................................................................................ 6 Creating an Account Profile ........................................................................... 8 Creating a Login Profile ............................................................................... 11 

Unit 4 14 

Data Binding Single-Value Attributes Using LINQ 14 Creating a Windows Form Application .......................................................... 15 

Setting the Form Properties ..................................................................... 15 Adding New Controls .............................................................................. 19 Building the Application .......................................................................... 21 

Unit 5 22 

Data Binding Multivalue Attributes Using LINQ 22 

Accessing U2 Nested Data in a LINQ Application .......................................... 23 Adding Event Handlers ............................................................................ 24 Building the Application .......................................................................... 26 

Creating a Console Application .................................................................... 30 The Solution File .......................................................................................... 31 

Further Reading 32 

Unit 1 Product Overview

This unit outlines the components of IBM U2 MultiValue Add-ins for Visual Studio (U2.NET).

Page 1

Page 2

Feature Overview Core Objects is a component of U2.NET. The classes of the Core Objects component are used to create .NET-based application interfaces to U2 database systems. Core Objects provides the underlying framework upon which all other U2.NET components are based, and allows the developer to rapidly create feature-rich, high-performance applications using the tools provided by the Microsoft .NET Framework environment. The design goal of U2.NET is to enable the U2 developer to combine the power and flexibility of U2 technology with the feature-rich .NET environment.

The U2.NET Suite Core Objects is one of three components within the U2.NET suite:

• Core Objects: Object-oriented native .NET access to U2 data servers.

• Binding Objects: High-performance data binding

technology that enables standard .NET controls to become fully U2 aware. Binding Objects links with Core Objects to provide its functionality.

• Adapter Objects: A complete implementation of an

ADO.NET managed data provider for U2 data servers, offering a standardized interface to access data servers.

Unit 2 LINQ Tutorial

This unit briefly describes how the Core Objects component of U2.NET supports the Language Integrated Query (LINQ) component of the .NET Framework when building an application in .NET supported languages.

As of version 1.1.2, U2.NET supports LINQ to DataSet functionality for querying and data binding single-value, multivalue, and multi-subvalue data in UniData and UniVerse databases. U2.NET version 1.1.2 ships with three example programs that demonstrate the new LINQ capabilities in U2.NET.

For more information about LINQ, please refer to the following:

• The LINQ Project at Microsoft

http://msdn.microsoft.com/en-us/netframework/aa904594.aspx

• LINQ to DataSet Samples

http://msdn.microsoft.com/en-us/vbasic/bb688086.aspx

Page 3

Page 4

Building an Application Using Core Objects Beginning with version 1.1.2, U2.NET supports creating DataSets that can be consumed by LINQ-based applications. To use LINQ to DataSets in your applications, you will first need to create an mvItemList that contains the results of a query. All of the following Select statements can be used to create an mvItemList:

• mvAccount.Select() • mvAccount.IndexSelect() • mvAccount.ProgSelect() • mvFile.Select() • mvFile.IndexSelect()

After you create an mvItemList object, you can then use mvItemList’s DataTable methods to create single-value, multivalue and multi-subvalue data tables. The DataTable instances thus created can be used by LINQ directly, or can be bound to windows or web controls. The mvListItem class and its DataSet methods are documented in the Core Objects Developer’s Guide. This tutorial assumes that you have already installed U2.NET Developer on your workstation, and that the server components and the U2NETEMO account are installed and configured from the U2.NET Data Manager tool to your U2 data server. If you are not sure how to do this, refer to the U2.NET Getting Started Guide or the U2.NET User Guide. In addition, you also need Microsoft Visual Studio 2008 installed on your workstation. Note: U2.NET Developer ships with several third-party controls that provide enhanced funtionality above standard Windows forms controls. These are available to the user for a 30-day evaluation period. After the evaluation period, you must purchase licenses for these third-party controls directly from their respective companies.

Unit 3 Creating Profiles

In this unit, you will create a server profile, an account profile, and a login profile.

• A server profile represents the location you want to install the server components.

• An account profile provides the means to define two main areas of information: account-specific logon settings and account specific-session pooling, and housekeeping settings.

• A login profile allows you to assign a logical name to a server and account profile pair. Use login profiles to identify the data server to which you want to connect whenever possible.

Page 5

Creating a Server Profile To use the U2NETDEMO account, you first need to create a server profile. To create a server profile: 1. Open the U2.NET Data Manager. Choose Start > All Programs > IBM U2 > U2.NET >

Version 1.x > U2.NET Data Manager. 2. In the tree view, right-click the Servers context menu and select the Add Server

Profile option, as shown below:

Page 6

3. A pop-up window prompts you for a profile name. Enter your profile name and click the Accept button. The Server Profile dialog box appears.

4. In the Server Profile dialog box, enter the details of the server profile.

In the Database type text box, select UniData or UniVerse. In the Server OS text box, select Windows or UNIX. In the Server address text box, enter the server address. This can be an IP address or a resolvable system name. In the Service text box, enter the UDCS or UVCS service to which UniObjects will connect. If you want the Connection Monitor to display when a new connection is established, select the Display connection monitor on startup check box. In the Send keep-alive… text box, enter how often, in seconds, that you want U2.NET to automatically send traffic between the client and the server to avoid session inactivity timeout. In the U2 Telnet port text box, enter the correct Telnet port on which UniData or UniVerse will run.

5. Click the Save Update icon on the Data Manager toolbar. Close the dialog box.

Page 7

Creating an Account Profile Each server profile defines how U2.NET clients locate and connect to the U2 data server. The data server does not, however, hold the details of a particular account on the server so that an account-specific connection can be established. The Account Profile is the entity that holds this extra information. There may be a number of account profile definitions within a single Server Profile, each representing a different account or application on the server. To create an account profile: 1. In the server profile tree view, click the + button next to the profile name, and then

right-click the Accounts context menu. Select the Add Account Profile option.

2. A pop-up window prompts you for a profile name. Enter your profile name and

click the Accept button. The Account Profile dialog box appears.

Page 8

3. In the Account Profile dialog box, enter the details of the account profile.

In the U2 account (full path) text box, enter the name of the full path of the U2 account for which you are defining this profile.

In the User name text box, enter the login name used to access the U2 account. In the Password text box, enter the password for the U2 account. Check the Enable U2 connection pooling box if you want to enable connection pooling.

In the Minimum pool size text box, enter the minimum number of sessions that may be contained within the pool.

In the Maximum pool size text box, enter the maximum number of sessions that may be contained within the pool.

Page 9

In the Free pooled sessions after text box, enter the maximum number of seconds that a pooled session may remain inactive within the session pool before it is freed up. A value of zero here indicates that sessions are to be kept open indefinitely.

If you want to specify that a process will wait for a session to become available when all current sessions are allocated and the maximum concurrent session limit of the session pool has been reached, check the Queue for free session text box. If this check box is not selected, an exception will be raised in these circumstances.

In the Queuing poll interval text box, enter the number of milliseconds to wait before the next Queue attempt.

In the Maximum number of poll attempt text box, enter the maximum number of unsuccessful queuing poll attempts that can be made before an exception occurs.

4. Click the Save Update icon on the Data Manager toolbar. Close the dialog box.

Page 10

Creating a Login Profile You must create a login profile named U2NETDEMO and associate it to a server profile and the U2NETDEMO account profile in order to use the U2NETDEMO sample files and the examples in this tutorial. To create a login profile: 1. In the Data Manager tree view, right-click the Logins option, and then select the

Add Login Profile, as shown below.

For more information about the Data Manager, refer to the U2.NET User Guide.

Page 11

2. The Add New Login Profile window opens. In the New login profile ID text box, type U2NETDEMO. Click the Accept button. The Login Profile dialog box opens.

3. In the Login Profile dialog box, enter the details of the account profile. From the Server name list, select the name of the server you are connecting to. From the Account name list, select the name of the account you want to open.

If you choose not to use the server/account pairing option described above, select the Use gateway profile option, and then select the Gateway name from the list.

5. Click the Save Update icon on the Data Manager toolbar. Close the dialog box.

Page 12

After you define all of the U2NETDEMO profiles, you are ready to create a .NET application using Core Objects.

Page 13

Unit 4 Data Binding Single-Value Attributes Using LINQ

In this unit, we use LINQ to data bind a standard DataGridView control to the SALESORDER file in the U2NETDEMO account.

Page 14

Creating a Windows Form Application To open a new Windows Form project in Visual Studio 2008: 1. Click the New Projects icon at the upper-left corner of the Visual Studio window.

The New Project dialog box opens, as shown below.

2. In the Name text box, enter the project name. For this exercise, name the project frmOrders. Click the OK button. The Visual Studio New Form dialog box opens.

Setting the Form Properties The Visual Studio Forms window has six main panes: the Toolbox, Output, Solution Explorer, U2.NET Data Manager, and Properties panes, plus the Form Designer pane in the middle of the window. These panes are identified by arrows in the image below.

Page 15

When U2.NET Developer is installed, it creates a U2.NET tab in the Visual Studio Toolbox pane. This installs several new icons in the toolbox, including one for the PrimaryDataSource control. Note: If the icons are not visible in the Visual Studio Toolbox, choose View > IBMU2.U2.NET Data Manager from the Visual Studio toolbar.

The Properties pane allows you to set the properties of the page itself and set the properties of individual objects on the page.

Page 16

To set the form properties: 1. Visual Studio automatically creates a new form when the project opens. Click the

border of this form to select it, as shown below.

2. In the Properties pane, set the properties as follows:

o Set the (Name) property to frmSalesOrder o Set the Text property to Sales Orders

Click in the Form Designer pane to apply the changes. The Solution Explorer pane allows you to explore all the files related to the current project. At this point, you must use the Solution Explorer to add a reference to the Core Objects DLL. To set the page properties: 1. In the Solution Explorer pane, right-click the Form1.cs file and select the Rename

option. Rename the file frmSalesOrder.cs.

2. In the Solution Explorer pane, right-click the References option and select Add Reference from the context menu.

Page 17

3. Select the Browse tab and navigate to the following location: C:\Program Files\IBM\U2.NET\Version1.x\bin 4. Select the IBMU2NET.CoreObjects.dll and click OK. Focus returns to the form.

Page 18

Adding New Controls The next step is to add new controls to the form. To add controls: 1. Drag a Data GridView control and two Button controls onto the form. Position the

controls as shown below.

o Set the Button1 Name property to btnLoad o Set the Button1 Text property to Load

o Set the Button 2 Name property to btnSave o Set the Button 2 Text property to Save

o Set the Data GridView Name property to dgvSALESORDER_SV o Set the AutoSizeColumnsMode property to Fill

After you add the new controls to the frmSalesOrder form, you must create an event handler for the Load button. To create the btnLoad event handler: 1. Double-click the btnLoad button you just created. The Code Designer tab opens.

2. Add a reference to the U2.NET Core Objects namespace. To do this, add the

following code to the top of the file:

using IBMU2.U2NET.CoreObjects;

3. Add members to the form. To do this, add the following code to the form:

Page 19

public partial class FrmSalesOrders : Form {

mvAccount mvAccount = null; mvItemList ilist = null; mvDataTable dt_SV = null; }

4. Next, you must add code to the event handler as follows:

private void btnLoad_Click(object sender, EventArgs e)

{ mvAccount = new mvAccount("U2NETDEMO"); mvFile file = mvAccount.FileOpen("SALESORDER"); ilist = file.Select("WITH @ID < \"10\"", "");

dt_SV = ilist.DataTable("@ID CUSTOMER DATEPLACED BUYTOTALCOST");

var query_SV = from r in dt_SV.AsEnumerable() select r; DataView dv_SV = query_SV.AsDataView(); dgvSALESORDER_SV.DataSource = dv_SV;

} In this event handler code, the LINQ and DataTable functionality are used to perform several actions, listed below in the order in which they occur in the above code snippet:

• Open a connection to the U2NETDEMO login profile. • Open the SALESORDER file. • Execute a Select command on the SALESORDER file. • Create a DataTable of single-valued attributes using the mvItemList DataTable

member [dt_SV]. • Use a LINQ query over the DataSet. • Use the AsDataView property on the LINQ query to return a DataView object

that can be databound. • Assign the DataView object to the grid’s DataSource.

For more information about the mvItemList class, please refer to the Core Objects Developer’s Guide. After you have created the btnLoad event handler, you must create a second event handler for the btnSave button. To create the btnSave event handler:

1. Double-click the btnSave button. The Code Designer tab opens.

2. Add the following event handler code:

private void btnSave_Click(object sender, EventArgs e)

Page 20

{ ilist.WriteModifiedItems();

}

In this event handler code, we call the mvItemList’s WriteModifiedItems method to write all modified items to the database. After you added this code, return to Designer mode by clicking the Design button at the bottom of the form.

Building the Application When you have created all of the controls and added the event handlers for the buttons, you are ready to build the application. To build the application: 1. Click the Build button on the Visual Studio toolbar, and then select Build Solution. 2. Run the application.

To do this, click the Debug button on the Visual Studio toolbar, and then select the Start WithoutDebugging option. This opens a working version of the Sales Order application you just created, shown in the image below.

3. Click the Load button to load the information from the SALESORDER file into the

application. You can now modify any item in the grid. After you make a change to the information, click the Save button. The modified data is saved to the U2 database. You can verify this change using either U2 database commands or the U2.NET Data Manager.

Page 21

Unit 5 Data Binding Multivalue Attributes Using LINQ

In this unit, we add two new grid controls to the application, and bind the controls to multivalue and multi-subvalue attributes of the SALESORDER file. The result is a three-level hierarchy of nested data from the SALESORDER file in the U2NETDEMO account.

Page 22

Accessing U2 Nested Data in a LINQ Application

In the previous unit, we built an application that combined LINQ with U2 DataTable support to bind the single-valued attributes to a grid control. We are now going to expand that application to build a hierarchically connected application. We begin by adding two DataGridView controls to the form. To add new controls: 1. If it is not already opened, open the design view of the frmSalesOrder.cs form in

Visual Studio 2008.

2. Drag two DataGridView controls onto the form. Position the DataGridView1 control under the dgvSALESORDER_SV control. Position the DataGridView2 control under the dataGridView2 control. Set the grid properties as follows:

o Set the DataGridView1 Name property to dgvSALESORDER_MV o Set the AutoSizeColumnsMode property to Fill

o Set the DataGridView2 Name property to dgvSALESORDER_MS o Set the AutoSizeColumnsMode property to Fill

The Sales Order form should now look like the one below:

Page 23

Adding Event Handlers In this exercise, you need to add an event handler to the dgvSALESORDER_SV control. To create the dgvSALESORDER_SV event handler: 1. Select the dgvSALESORDER_SV control. While the grid is highlighted, click the

Events icon on the Properties pane toolbar. The Events menu items appear in the Properties pane.

2. Double-click the SelectionChanged option to create an event handler. The Sales Order.cs code view opens in the form pane. You must now add two new Form members to the code. Add the following code to the member list:

mvDataTable dt_MV = null, dt_MS = null;

3. Now add the following code for the event handler: …

if (dgvSALESORDER_SV.SelectedRows.Count > 0) {

Page 24

mvItem curItem = ilist[dgvSALESORDER_SV.SelectedRows[0].Index + 1]; dt_MV = ilist.DataTable(curItem, "PRODUCT PRODUCTDESC QTY BUYUNITCOST"); var query_MV = from r in dt_MV.AsEnumerable() select r; DataView dv_MV = query_MV.AsDataView(); dgvSALESORDER_MV.DataSource = dv_MV; }

… In this event handler code, the LINQ and DataTable functionality are used to perform several actions, listed below in the order in which they occur in the above code snippet:

• Locate the currently selected mvItem. • Create a DataTable of multivalue attributes by using the mvItemList.DataTable()

method of the mvItemList class. • Use a LINQ query over the DataSet. • Use the AsDataView property on the LINQ query to return a DataView object

that can be databound. • Assign the DataView object to the grid’s DataSource.

For more information about using the mvItemList class, refer to the Core Objects Developer’s Guide. In the next exercise, you will add an event handler to the dgvSALESORDER_MV control. To create the dgvSALESORDER_MV event handler:

1. Select the dgvSALESORDER_MV control. While the grid is highlighted, click the

Events button on the Properties pane toolbar. The Events menu items appear in the Properties pane.

2. Double-click the SelectionChanged option to create an event handler. The Sales Order.cs code view opens in the form pane.

3. Add the following code to the dgvSALESORDER_MV event handler:

… if (dgvSALESORDER_SV.SelectedRows.Count > 0 && dgvSALESORDER_MV.SelectedRows.Count > 0) { mvItem curItem = ilist[dgvSALESORDER_SV.SelectedRows[0].Index + 1]; int mvSel = dgvSALESORDER_MV.SelectedRows[0].Index;

Page 25

dt_MS = ilist.DataTable(curItem, mvSel, "DELIVERYQTY DELIVERYDATE DELIVERYDESC"); var query_MS = from r in dt_MS.AsEnumerable() select r; DataView dv_MS = query_MS.AsDataView(); dgvSALESORDER_MS.DataSource = dv_MS; }

…

In this event handler code, the LINQ and DataTable functionality are used to perform several actions, listed below in the order in which they occur in the above code snippet:

• Locate the currently selected mvItem. • Locate the MV position selected in the dgvSALESORDER_MV grid. • Use Core Objects to create a DataTable of multivalue attributes. • Use a LINQ query over the DataSet. • Use the AsDataView property on the LINQ query to return a DataView object

that can be databound. • Assign the DataView object to the grid’s DataSource.

Building the Application When you have created all of the controls and added the event handlers for the buttons and grids, you are ready to build the application. To build the application: 1. Click the Build button on the Visual Studio toolbar, and then select Build Solution.

2. Run the application. To do this, click the Debug button on the Visual Studio

toolbar, and then select the Start WithoutDebugging option. This opens a working version of the Sales Order application you just created, as shown in the image below.

Page 26

3. Click the Load button to load the information from the SALESORDER file into the application. After the information loads, use the row pointer to select a row. This populates a list in the middle grid that displays the multivalue information for the selected item.

Page 27

4. Select an item from the second grid to populate a list in the third grid that displays

the multi-subvalue information for each selected item, as shown below.

Page 28

5. You can make changes to the grid information at any level, single-value,

multivalue, or multi-subvalue, and save those changes to the database. After you make a change to the information, click the Save button. The modified data is saved to the U2 database. You can verify this change using either U2 database commands or the U2.NET Data Manager.

Page 29

Creating a Console Application The LINQ_Examples1 example file takes you through the steps necessary to create a C# console application using LINQ to directly manipulate U2 nested data. The default location o f the LINQ_Examples1 file is: C:\Program Files\IBM\U2.NET\Version1.x\Examples.VS2008\LINQ The LINQ_Examples1 file runs a program that calls two main functions:

• PrintNestedData()

• Nested_MS_Update

In this example, the PrintNestedData() function is used to show data from the SALESORDER file both before and after the Nested_MS_Update function runs. The PrintNestedData() function uses the new Core Objects DataSet functions to print the single-value, multivalued, and sub-multivalued data from the SALESORDER file. The Nested_MS_Update function demonstrates how you can use LINQ to query and update single-valued, multivalued, and multi-subvalued data from the SALESORDER file. In the code snippet below, you can see that the DELIVERYQTY value is 1 before the Nested_MS_Update update runs, and that it has changed to 19 after the update.

Nested_MS_Update: Before update, DELIVERYQTY: 1 DELIVERYDATE: 3/13/2008 DELIVERYDESC: Setting DELIVERYQTY to random value: 19 for MS attribute with DELIVERYDATE = 3/13/2008 After update, DELIVERYQTY: 19 DELIVERYDATE: 3/13/2008 DELIVERYDESC:

Note: The source code comments in the Program.cs file explain the LINQ to DataSet functionality and usage in this example.

Page 30

The Solution File The LINQ completed Tutorial solution files can be found in the following default location: C:\Program Files\IBM\U2.NET\Version1.x\Examples.VS200x\LINQ After you have navigated to the Example file, select the LINQDataBinding_Tutorial1 file, and then click the LINQDataBinding_Tutorial1.sln option. Build the application and run it from the Windows Command Prompt window. For a Debug build, the executable is created in: C:\Program Files \IBM\U2.NET\Version1.1\Examples.VS2008\LINQ\LINQ_Examples1\bin\Debug To run the application, open the Windows Command Prompt window, navigate to the above directory, and then run the “LINQ_Examples1.exe” application.

Page 31

Further Reading

For more information about U2.NET or any of its components, refer to the following documents:

U2.NET User Guide This guide provides an overview of the U2.NET product. It discusses information about topics such as product installation, licensing, the Data Manager, and extended dictionary definitions. U2.NET Adapter Objects Developer's Guide This guide provides an overview of U2.NET's Adapter Objects component. Information about topics such as ADO.NET, the mvConnection class, the mvCommand class, dynamic normalization, and that Data Adapter wizard are all included in this guide. U2.NET Adapter Objects Tutorial This tutorial takes you through all the steps necessary to create a working application using Adapter Objects and the Data Manager. U2.NET Binding Objects Developer's Guide This guide provides an overview of U2.NET's Binding Objects component. Topics such as databinding, the PrimaryDataSource control, the SecondaryDataSource control, the mvNavigate control, the mvQuery control, and the Control Assistant are covered in this guide. U2.NET Binding Objects Tutorial This tutorial takes you through the steps necessary to create a working application using Binding Objects in the Microsoft Visual Studio environment. U2.NET Binding Objects Web Tutorial This tutorial helps you learn all the steps necessary to create a working AJAX-enabled Web application using Binding Objects in the Microsoft Visual Studio environment. U2.NET Core Objects Developer's Guide This guide provides an overview of U2.NET's Core Objects component. It includes information about using Core Objects, the class library, using file schema, and optimizing application performance.

Page 32

Page 33

U2.NET LINQ Tutorial This tutorial takes you through the steps involved in using Core Objects and the Language Integrated Query (LINQ) component of the .NET Framework to build a U2.NET application in Visual Studio. U2.NET Getting Started Guide This guide provides a quick overview of the steps needed to begin using U2.NET, including installing and licensing the product.