However, I was a little surprised that they didn’t include the source code for the Windows program that communicates with the board. Sending a “hello world” message to the LCD is fine for verifying that the kit works, but an LCD connecting to a PC could be used for so much more.

When Googling for some .Net code that I could use as a starting point for writing my own interface, I was delighted to find that somebody had already done most of the work for me. An article on The Code Project site describes the construction of a homebrew parallel port LCD connection, and includes the C# .Net code that the creator used to send data to the LCD. Out of curiosity I downloaded the code and ran the .exe to see what happened, and I was astounded to see it successfully writing The Code Project’s RSS feed to the kitsrus LCD, under Vista no less. “Hello World”, indeed.

The Code Project article’s creator wasn’t using the kitrsrus kit, but because his LCD is based on a similar controller chip, and by a lucky coincidence in the selection of parallel port pins, the code mostly worked. The only problem was that the data wasn’t scrolling across the LCD as intended, but was stuck in the last column of the display, writing only to that one position. The data was getting across, it just wasn’t being positioned correctly. This is a pretty common and easily solved problem when writing data to an LCD, as I’ll explain below.

(In order to preserve your sanity and mine, I’ll refrain some referring to “the Code Project project” and the “kitsrus kit”, and call them the “CP project” and “the kit”. Apologies to their respective trademark owners.)

Although there is no “standard interface” for connecting an LCD to a parallel port, there is a fairly close correspondence between the parallel port’s pins and the pins used by all LCDs that use an HD44780-compatible controller chip. (Most LCDs intended for use by hobbyists are compatible with this standard, dating back to the late 90s. The Wikipedia entry for HD44780 links to an Everyday Practical Electronics article from 1997.)

The CP project used an LCD based on an old Samsung KS0066 chip, and the kit contains an LCD based on the KS0070 and manufactured in 1999, and both of those are HD44780-compatible.

The Code Project author wrote 2 articles that contain all the technical information you need to know in order to understand his .Net source code: this article covers the parallel port’s pins, and this one covers the LCD’s. The illustration below is linked to his second article.

Both the parallel port and the LCD use 8 data pins, D0 through D7. Not surprisingly, both the CP project and the kit wire the 2 sets of pins in a one-to-one correspondence, D0 to D0, D1 to D1, etc. The data sent by the .Net code arrives just fine at the LCD, then.

LCDs based on the HD44780 interface also have 3 control pins: RS (register select), R/W (read/write) and E (enable). Since LCDs don’t have much to say, both the CP project and the kit do the same thing with the R/W pin – wire it to ground, putting it in a permanent write state.

By a happy coincidence, both the CP project and the kit happened to wire parallel port pin C0 to the E pin of the LCD – without pin C0 turning things off and on, nothing would have made it to the LCD. There is a non-intuitive pattern of setting the enable pin low then high then low again that is necessary to write data to the LCDs — this seems to be the thing that trips up most novice LCD programmers, but the CP project’s source code does a nice job of commenting this code so that you can understand what’s going on.

The only area where the 2 approaches differ is in the selection of the RS pin: the CodeProject board uses pin C2 while the kitsrus board uses C1. (See the CP project’s pinout diagram below). Since this pin is used to tell the LCD whether it is receiving data or instructions, and the pin needs to be high for data, this difference should have caused everything being sent to the LCD to the treated as instructions, resulting in a jumpy cursor but no characters on the screen. However, by another lucky coincidence, the parallel port pin used by the kit, C1, is reversed – it is normally high and is set to low by sending it a “1″. This results in everything sent to the LCD being treated as data — characters with no cursor control, exactly what we got.

Parallel port connections to the LCD, by Levent Saltuklaroglu, courtesy of The Code Project

To adapt the CP project’s code to the kit, the only change required is to redirect all signals intended for C2 to C1, and flip the bit from allow for the fact that kit’s pin is reversed.

I decided to implement this change by adding a go-between method that would convert the instructions sent by the CodeProject code to the ones required by the kitsrus board:

        private void writeToControl(int intValue)
        {
            int intModifiedValue = intValue;
            if ((intValue & 4) > 0)
				// if C2 is being set  high, set C1 high by sending it a 0
                intModifiedValue = intModifiedValue & 253;
            else
				// else, if C2 is being set low, set C1 low by sending it a 1
                intModifiedValue = intModifiedValue | 2;

            PortAccess.Output(intControl, intModifiedValue);
        }

And that’s it — the kit can now be fully controlled by the CP project’s code.

This is quite cool, since it breathes new life into a 10-year old kit. When originally introduced the kit had only a command line interface that would only run in DOS – real DOS, not the command line in Windows XP. However, the .Net code works just fine under Vista and Windows 7. By tinkering with the code you can now use the LCD as a remote display for whatever you like: RSS feeds, e-mail, twitter. A poor geek’s Chumby!

The first and more serious bug is that the driver always returns numbers with a decimal point as a zero when using French “regional settings” in Windows.

For example, when using these Regional Settings…

Zut alors, c'est un comma!

…the sample .Net application that IBM provides in its QuickStart tutorial displays this:

French toast

We ran into this bug because many of our product’s users have the “French (Canada)” setting on their PCs. I assume that the root cause of the bug is that a comma, rather than a period, is used as the decimal point, as marked in yellow above. IBM support has confirmed that this is a bug are internally testing a fix in the Runtime Client, so the fix will likely be available in Fix Pack 3c or the one after that.

I’m surprised that nobody (including us) ran into this bug earlier, but that’s probably because most developers (including us) have got into the habit of reading data from UniVerse as strings, then converting the data into its proper format in their code. As I’ve mentioned in past articles, UniVerse has a “multivalue” heritage where all data is stored internally as strings. Developers should go against this grain at their own peril.

For example, rather than defining a currency field in the Universe dictionary like this…

COMMISSION
001 A
002 34
005 S
007 MD3
009 R
010 7

… define it as….

COMMISSION.STR
001 A
002 34
005 S
006 CHAR,7
009 R
010 7

… and read the value into a String. Then, you can convert it to a Decimal variable using code like…

Decimal.TryParse(strValue, System.Globalization.NumberStyles.Number,
System.Globalization.CultureInfo.InvariantCulture, out decValue);

The “InvariantCulture” thing is needed because, when defined as a CHAR, UniVerse will return a decimal value using — surprise, surprise — a period as the decimal point.

The second bug that we tripped over was a little more obscure. The bug was found by one of our developers, who was double-checking the configuration of our clients’ databases to make sure that all of our latest patches had been applied. He found that one particular SQL statement used in our application was failing with the following error:

Error  occurred: ERROR [Command_ExecuteDirect]  [IBM  U2][UCINET][UNIVERSE]:UniVerse/SQL: syntax error.  Unexpected verb.  Token was  "LIST". Scanned command was FROM VENDORS SELECT LIST  :  IBM.Data.DB2: -2147467259

This type of error usually indicates a mismatch between our dictionary entries and our application, which was the type of configuration issue that he was checking for. It wasn’t a big surprise, since the problem was found in a database that is only used for in-house training. Surprisingly, though, after reapplying the latest dictionary entries the bug remained.

Like most database systems that I’ve worked with, UniVerse’s SQL parser tends to return some pretty vague error messages. The particular SQL statement that was failing was quite long, containing about 20 columns, none of which were named “LIST”. By trial-and-error, I found that the culprit was a field named DEMO.LIST. The DICT definition of this field was fine – it exactly matched the dictionary entry used in the other databases at this client site, none of which were experiencing this error. While scratching my head over this, our developer told me that he found the same error in the same SELECT statement in a database at a different client. This database was also one used for in-house training.

This made me suspect that the error was caused by bad data. The databases used for in-house training are more likely to contain weird characters like embedded tabs or carriage-returns.

The dictionary definition of DEMO.LIST was a 100-character string:

DEMO.LIST
001 A
002 5
005 S
006 CHAR,100
009 L
010 100

As mentioned earlier, strings are usually a safe choice for data in UniVerse. I’m not aware of any type of data that can cause a SELECT of a a string to fail in UniVerse’s ADO.NET driver, but there’s a first time for everything. However, a bit of trial-and-error testing made it clear that this SELECT statement was failing on the plainest of records: vanilla text that couldn’t possibly cause a problem. It was a real whodunnit.

Back to the not-very-helpful error message, It was complaining about a “token” named LIST. If I simplified the variable name to something like FIELD1, did that affect the error message? Well, yeah: it made the error go away completely. The SELECT statement worked fine if the column name was changed to FIELD1, or DEMO or even DEMOLIST. Weird. We have periods in lots of our column names, and a lot of them are named LIST. DEMO, not so much.

At this point, things finally fell into place. The name that we give our databases that are used for in-house training is DEMO. And, of course, in standard SQL syntax, a period in a column name is used to identify the table, such as “SELECT TABLE1.FIELD1″. Sure enough, I ran some tests in our development database, named DEV, and found that naming a column “DEV.LIST” or “DEV.FIELD” or “DEV.WHATEVER” caused SELECT statements that use that field to fail.

The moral of the story, I suppose, is don’t use periods in your column names. That was IBM support’s suggestion, though I’m hoping that they will fix this bug as well.

I suppose that both of these bugs are indicative of what happens when you drag a 40-something year-old non-relational database kicking and screaming into the .Net world. Oops, better make that “dotNet” to be safe!

select USER.ID from "CSUSER-FILE"

is valid, but not

select USER.ID from [CSUSER-FILE]

or

select user.id from "csuser-file"

Oddly, names that contain a period do not have to be quoted – unlike its SQL database brethren, UniVerse is smart enough to figure out when the period delimits the table ID from the column name.

3) A "SELECT *" query will return the key fields along with whatever fields are defined in a special dictionary entry named "@".  For example, if you want SELECT * FROM USERS to return the FIRST-NAME and LAST-NAME fields, you’ll need to edit the dictionary as follows:

ED DICT USERS
Record name = @
2 lines long.

----: 2
0002: 1 2
Bottom at line 2.
----: R FIRST-NAME LAST-NAME
0002: FIRST-NAME LAST-NAME
Bottom at line 2.
----: FI
"@" filed in file "DICT USER".

If you don’t have a record named "@" in your file’s dictionary, then "SELECT *" will return the column named "@ID" if you have one (which you probably do, since the primary key is automatically added to all dictionaries under this name when you first create them).  If you happen to have deleted the "@ID" column, then SELECT * will fail with a "No column rows" error.

What if you have a 200 column table and you want SELECT * to return all 200 columns?  Sorry, but you’ll have to enter all 200 column names in that "@" record.  And if you add, delete or rename a column, you’ll have to remember to edit that "@" record. I feel your pain!  This cumbersome approach dates back to UniVerse’s ODBC driver, and I suppose they can’t change it now without breaking a lot of applications.  You can find the details described in inscrutable IBM-ese in the UniVerse ODBC Guide.

4) Errors encountered when executing your SQL statement are reported in a pretty obscure manner.  You’ll see a message box with the "Error in SQL.  Check the SQL and try again.  For error detail information refer to the IBM Output Message Pane".  It took me awhile to figure out where the "IBM Output Message Pane" was hidden.  It’s in the Output window (Ctrl-W O), but you’ll need to change the "Show output from" combo to "IBM Output Message Pane" as shown below. 


5) If you have subvalued fields, only the first subvalue in the field will appear in the Results grid.  (Subvalues are ASCII 252 delimiters which are used to fit multiple fields into the same column).  This is presumably a side effect of a bug in IBM’s ADO.NET driver which replaces subvalue delimiters with CR/LF.

6) There are a couple of bugs in the ADO.NET driver for which, as far as I know, there is no good workaround.  The first is that the SQL processor can’t handle hard-coded values which contain the "at sign", such as:

SELECT * FROM MY.TABLE WHERE THE.KEY = "DAN@WORK"

Depending on the structure of your data you may be able to get at the data by using a wildcard instead

SELECT * FROM MY.TABLE WHERE THE.KEY LIKE "DAN%WORK"

The other bug is that zero-length numeric fields such as the one in attribute 5 below will result in an “Input string was not in a correct format” error (that funny little accented character is ASCII 253, the multivalue delimiter):

0001: SMITH
0002: 1414 W. 8TH
0003: DENVER
0004: CO
0005: V2001ýýC8181
0006: 200ý3599ý1050

This latter bug was fixed by IBM in the recently released Fix Pack 3, but if you have users on earlier releases there is a workaround you can implement in your code, as explained later in the article.

7) Last, but not least, multivalues.  As described in my previous article there are a few different ways to configure your dictionary to return multivalues, but the method that IBM recommends is to list the multivalued fields in a special "association" dictionary entry that looks like this:

    DETAILS
001 PH ASSOCIATION OF ORDER DETAIL FIELDS
002 ORDER.IDS ORDER.AMOUNTS

The advantage of this approach is that you can return the items within the multivalued field as if they were separate columns, which makes the data a lot easier to work with.  The disadvantage is that you’ll have to puzzle out the syntax for a join with a "virtual table".   If the above field DETAILS was defined in the dictionary of a table named CUSTOMERS, then a SQL statement to return a list of order IDs and amounts would be:

SELECT a.KEY.FULL, ORDER.IDS, ORDER.AMOUNTS FROM CUSTOMERS a JOIN CUSTOMERS_DETAILS b ON a.KEY.FULL = b.KEY.FULL

Since the dictionary field that is automatically added for the primary key, "@ID", can’t be used in SQL statements, you’ll have to add one yourself in order to use it in the JOIN — in the above example I added a field named KEY.FULL to CUSTOMERS.

If by this point you’re fully freaked out by the UniVerse way of implementing SQL, then I’ve got some good news for you: the code itself is pretty much plain vanilla and won’t require much explanation. 

Before you start coding, you’ll need to add a reference to the IBM.Data.DB2 DLL to your project References list, as shown at the right.  You’ll also need to add "IBM.Data.DB2" to your list of namespaces:

using IBM.Data.DB2;

The process of building a connection string is quite similar to other databases like SQL Server.  You’ll need to set the Server, User, Password and Database (which is the UniVerse account name).   In addition, you need to set two less familiar properties — ServerType and Pooling:

private string providerName = "IBM.Data.DB2";
private DbConnectionStringBuilder builder;
private DbConnection conUniVerse;

builder = new DbConnectionStringBuilder();
builder["Server"] = txtServer.Text.Trim();
builder["User ID"] = txtUserID.Text.Trim();
builder["Password"] = txtPassword.Text.Trim();
builder["ServerType"] = "universe";
builder["Pooling"] = "false";
builder["Database"] = txtAccount.Text.Trim();
string strConnectionString = builder.ConnectionString;

DbProviderFactory m_provider = DbProviderFactories.GetFactory(providerName);
conUniVerse= m_provider.CreateConnection();

conUniVerse.ConnectionString = strConnectionString;
conUniVerse.Open();

You’ll then need to create an ADO Data Adapter and feed it the SQL statement.

DbProviderFactory factory = DbProviderFactories.GetFactory(providerName);
DbDataAdapter adapter = factory.CreateDataAdapter();
adapter.FillError += new FillErrorEventHandler(adapter_FillError);
adapter.SelectCommand = DB_GetCommand(strSQL);

Lastly, you create an ADO Dataset to hold the results of the query, then bind that Dataset to a grid on your form to display the data:

DataSet dsData = new DataSet();
adapter.Fill(dsData , "MyData");

bindingSource1.DataSource = dsData ; // bindingSource1 is a BindingSource object that I dragged from the Toolbox onto my form
bindingSource1.DataMember = "MyData";
gridData.DataSource = bindingSource1; // gridData is a DataGridView object on my form
conUniVerse.Close();

You may have noticed that I added a FillError event handler to my adapter.  This is a workaround for the zero-length multivalue problem that I mentioned earlier in the article.  In the error handler, you can examine the Exception’s properties and, if it appears to be the zero-length multivalue error, set the e parm’s Continue property to true.

void adapter_FillError(object sender, FillErrorEventArgs e)
{
    if (e.Errors.Message.Contains("Input string was not in a correct format"))
        e.Continue = true;
}

This will result in the dataset being filled, but without the multivalued " virtual record" that contained the zero-length value. If the zero-length value is just bad data then that’s probably what you want — otherwise, you’ll need Fix Pack 3.

Whew!   That might seem like a lot of work to read some data into a grid, but it’s stable, it’s pretty fast, and it’s still a lot less coding than the only other stable and fast UniVerse API out there, UniVerse Objects.  Once you’ve learned the ropes, UniVerse is now a viable database option for .Net development. 

public static TimeSpan TimeSpan_FromUniverseString(string strUniverseTime)
{
    int intUniverseTime = 0;
    // if the string contains milliseconds, discard them
    int intIndex = strUniverseTime.IndexOf('.');
    if (intIndex >= 0)
    {
        strUniverseTime = strUniverseTime.Substring(0, intIndex);
    }

    if (!Int32.TryParse(strUniverseTime, out intUniverseTime))
    {
        // if not a numeric, then return 00:00:00
        return new TimeSpan(0);
    }
    int intDays = intUniverseTime / 86400;
    int intRemainder = intUniverseTime % 86400;
    int intHours = intRemainder / 3600;
    intRemainder = intRemainder % 3600;
    int intMinutes = intRemainder / 60;
    int intSeconds = intRemainder % 60;
    return new TimeSpan(intDays, intHours, intMinutes, intSeconds);
}

However, an easier workaround (which I stumbled across after using the above approach for months) is to take advantage of the "correlative" code. 

This code only exists in A- and S-type dictionary entries, in attribute 8.  Ordinarily, time fields are defined in UniVerse dictionaries by specifying a "conversion code", such as "MTS" in attribute 7.

    ACCESS.TIME
001 A
002 3
005 S
007 MTS
009 R
010 5

This tells ADO.Net (or UniVerse Basic) that the value in this field can be regarded as a time.  However, by specifying the same conversion code in attribute 8, the conversion to a time value is handled internally by the UniVerse database before ADO.Net sees it.

    ACCESS.TIME.SQL
001 A
002 3
005 S
008 MTS
009 R
010 5

Therefore, a value such as "3600.5" will be seen by the ADO.Net driver as 1:30 am, without that nasty millisecond value that it so dislikes.

3) Multivalues

Ah yes, multivalues.  This is a method for storing multiple values into the same field, separated by a special delimiter.  For example, attribute 1 might contain a list of order numbers, and attribute 2 the amount (in cents) of each of order:

001 C2000ýM3000ýS3000
002 600782ý700422ý101456

Multivalued strings are the primary feature that distingishes UniVerse and its brethern databases from all the others, but .Net doesn’t really understand the concept (nor do many .Net programmers, actually).  UniVerse provides some tools which allow you to dress up the multivalued data to resemble columns in a normalized SQL database — it is up to you whether you want to play dress-up, or just process the multivalued fields in their underlying form: delimited strings.

There are 3 different approaches to definining multivalued strings in the dictionary so that they are safe for consumption by .Net:

i) The documented approach is to use a D-type dictionary entry which contains an "M" in attribute 6 and an "association" name in attribute 7.  For example, the definition of the Order ID and Order Amount fields might look like:

    ORDER.IDS
001 D Order IDs
002 1
004 Order IDs
005 10L
006 M
007 DETAILS

    ORDER.AMOUNTS
001 D Order Amounts
002 2
003 MD0,$
004 Order Amount
005 7R
006 M
007 DETAILS

And the dictionary entry which defines the virtual "DETAILS" table would be:

    DETAILS
001 PH ASSOCIATION OF ORDER DETAIL FIELDS
002 ORDER.IDS ORDER.AMOUNTS

If the main table which contained the multivalued fields was named SALES, then there would now be a virtual table named SALES_DETAILS containing three fields: ORDER.IDS, ORDER.AMOUNTS, and a foreign key field that points back to the primary key of the SALES table. 

For details, see chapter 5 of the UniVerse System Description manual, and for a thorough example see the sample code which is included with Part 2 of IBM’s tutorial on the ADO.Net driver.  In the third part of this series, I will show an example of how you would use a JOIN clause in a SELECT statement to return the fields in the virtual table in the same record as the fields in the main table.

The advantage of this approach is that the resulting SQL statements will closely resemble those that would be used for a relational database, and this should make it easier to port your application from UniVerse to a relational database should you wish to.  The downside is that it can become quite cumbersome to code when your records contain multivalued attributes that aren’t related on one another. For example, if a customer record contains a list of order numbers in attribute 1, and a list of customer contacts in attribute 2, you’ll have to specify a different association name for these 2 entries, and retrieve them using either a very complicated 3-way JOIN, or using 2 different SELECT statements. Also, since UniVerse does not offer any constraints or other mechanisms for enforcing the integrity of your data, you are likely to find that bad data fouls up your application, resulting in missing rows or runtime Exceptions.  In our application, we use this approach only for small and simple tables.

ii) You can return the multivalued strings in their "native" form — strings with delimiters separating the values.  You do this by using an I-type dictionary entry that converts the multivalue delimiter (ASCII 253) to whatever character you want.  For example, to return attribute 1 with the multivalued fields delimited by commas:

   FIELD.LIST
001 I
002 CONVERT(@VM,',',@RECORD<1>)
004 FIELD.LIST
005 50L
006 S
008 VARCHAR,32767

You might be wondering why you can’t just return the strings using the original delimiter, ASCII 253.  For reasons known only to IBM, this results in a runtime exception.  Incidentally, there is is a second type of delimiter which is also common in UniVerse, the subvalue delimiter (ASCII 252).  UniVerse subvalues  occur when the parts of a multivalued fields are, in turn, delimited into smaller fields.  For reasons also known only to IBM, these are automatically converted by the ADO.NET driver to a carriage return and line feed (i.e. "\r\n").   IBM support has indicated that this delimiter conversion is actually a bug and will be changed back to ASCII 252 to a future Fix Pack.

Once you have the delimited string, you’ll need to use .Net’s string parsing capabilities to separate it into individual fields and convert the fields to their correct data type.  You’ll find that .Net isn’t ideally suited for this type of string processing.  UniVerse, on the other hand, is very much suited to it, and IBM provides a library named UniVerse Objects.Net that contains a variety of methods for extracting data from delimited strings.  Frustratingly, your ability to use UniVerse Objects to parse your data is hampered by the fact that ADO.NET has forced you to replace all the multivalue and subvalue delimiters with other delimiters that UniVerse Objects doesn’t support.

If you decide to read UniVerse multivalued data in its native form, you might want to consider bypassing ADO.NET altogether and reading the data using UniVerse Objects.  This is what our application does when dealing with tables that contain data that is mostly multivalued.  It is much faster, and will likely require less code.

iii)  While "official" UniVerse multivalued fields are delimited using ASCII 253 and 252, many UniVerse Basic programmers grow so fond of multivalues that they use them all over the place, with whatever delimiter character tickles their fancy.  I’ve seen multivalued strings used as the primary key, and I’ve seen multivalued strings that contain embedded dates and time fields.  While that kind of data structure would make SQL programmer cringe and a SQL database crawl, UniVerse is tuned to handle these strings efficiently and provides functions that you can insert in your dictionary to extract these fields relatively easily.

The trick is to place a correlative in attribute 8.  Appendix C of the UniVerse Basic manual documents these correlatives, but be forewarned: they are cryptic enough to make a Perl programmer weep with frustration.  Here are a couple of examples to get you started.

Say you had a key that was delimited with "@" signs.  Just to make things interesting, say that one of the fields was a UniVerse Julian date, and another was a UniVerse Julian time.  A typical key would be: FIRSTPART@14927@49055.75.

If you wanted to return the 1st part of the key ("FIRSTPART") as a separate field in the SELECT statement, you could define it as follows in the UniVerse dictionary:

    THE.STRING
001 S
002 0
005 S
008 F;0;(G0@1)
009 L
010 20

The correlative in attribute 8 means "take attribute 0 (the key), then split it into sections with ‘@’ as the delimiter and return part 0".  If you want all the gory details of what the "F code" can do, see Appendix C of the UniVerse Basic manual. 

To return the date string as a date, you would use a similar "F code" string in attribute 8, along with a conversion code in attribute 7:

    THE.DATE
001 S
002 0
005 S
007 D2
008 F;0;(G1@1)
009 R
010 9

The time field is trickier – as mentioned above, the ADO.NET driver doesn’t like time fields with milliseconds.  The best way to handle these fields is by putting the conversion code in attribute 8, but that’s where we need to put the correlative, and (as far as I know) you can’t put both a conversion code and a correlative in the same dictionary attribute.  You can, however, combine 2 extract commands in a correlative:

	THE.TIME
001 S
002 0
005 S
007 MTS
008 F;0;(G2@1);(G0.1)
009 R
010 12

This correlative tells the database to extract the time field from the key and then, having done that, extract the part before the decimal point.  The conversion code in attribute 7 then converts that value to a .Net TimeSpan.  (The Universe Basic manual refers to this as "reverse Polish format (Lukasiewicz)" — how geeky is that?)

So, there you have it: an overview of the tricks that I’ve used to whip our UniVerse data into a form suitable for consumption by .Net. 

If you are new to UniVerse, you are likely thinking at this point: "um, so how do I edit a dictionary".  As a crash course on UniVerse for Windows programmers, I would strongly recommend the "Learner Pack" put together by the U2 User Group.  The UniVerse manuals are a well written, exhaustive reference when you are ready to dive deeper, but as a crash couse you can’t do better than the U2UG Learner Pack.

In third and final part of this series, I’ll show you the (relatively simple) coding required to load UniVerse data into a DataGridView using ADO.Net.

1. Stability.  UniOLEDB’s intermittent "memory is corrupt" errors were driving me nuts.  Upgrading the database server from UniVerse 10.1 to 10.2 improved UniOLEDB’s stability significantly, but switching to the ADO.NET driver has made things better still.  Stability is no longer a concern — we’ve had no problems with dropped connections or failed queries.




2. Deployment.  UniOLEDB’s archaic install program was driving our clients’ IT guys nuts.  The fact that UniOLEDB had to be installed by manually on each desktop was a dealbreaker for the larger sites.  The DB2 Client’s installation program has its own quirks, as I wrote about here, but once we figured out the trick our clients have had no problems rolling it out with automated tools like Microsoft Systems Management Server.




3. Productivity.  The ability to have Visual Studio treat UniVerse like a full-fledged database would make it a lot easier to developer new forms.  With UniOLEDB we had to laboriously handcraft the DataAdapters for each table: write the SELECT, INSERT, UPDATE and DELETE statements, set their parameters, use them to construct the DataAdapter, then write the code to populate and manage the DataSet tables.  That was a lot of code, and we have a lot of tables!  Wouldn’t it be nice to replace all of that with a simple drag-and-drop?

Well, 2 out of 3 ain’t bad.

We haven’t quite reached that third goal yet.  We’ve got a relatively messy UniVerse database: our master dictionary and most of our data dictionaries are littered with references to things that don’t exist or aren’t correctly defined.  UniVerse itself ignores these obsolete entries, but it seems that the DB2 Client dutifully tries to make sense of them, each and every time that we connect.

As a result, any attempt to access a table through the Visual Studio IDE, be it from the Server Explorer or the Data Sources window, is painfully slooooooow.   I have an idea for doing an end-run around this problem, and when I have time to pursue it I’ll write a blog post describing what I did and how it turned out.

But, for now, drag and drop isn’t an option.

Our internal developers are still accessing UniVerse data through a labour-intensive code-based approach, without using the Server Explorer or Data Sources IDE at all.  That’s fine for us, since we’ve built a framework to support it, but when I was recently asked to help a client’s .Net developers get to our data, I knew I had to give them something easier.

My boss assured them that once they had the UniVerse 10.2 and its new IBM ADO.NET driver, UniVerse would be as easy to use as SQL Server.  Heck, we’d even create Views for the data they want.

Well, not so fast.  Even with an ADO.NET driver, UniVerse doesn’t support Views. There’s a node called "Views" sitting under the UniVerse data connection in Visual Studio’s Server Explorer, but it will always remain forlornly barren.  There is simply no equivalent entity in the world of UniVerse.

When I asked IBM about this, they recommended using UniVerse subroutines instead.  These are regarded by the ADO.NET driver as stored procedures, meaning that they can be viewed and invoked from the Server Explorer under the Procedures node.   You can use them with Visual Studio’s Data Source Configuration Wizard to create DataSets and DataAdapters without having to write any code.

Pretty nifty, and that’s something you couldn’t do with UniOLEDB.  (Predictably, it would throw up a "memory is corrupted" error if you tried).  But the subroutines are written in dowdy old UniVerse Basic, and our clients’ developers didn’t want to go there.  They opted for SQL.

Running SQL SELECT statements against a UniVerse database is a lot easier with the new ADO.NET driver, but it’s still tricky, with quite a few pitfalls that aren’t mentioned in IBM’s tutorials or (as far as I know) anywhere else.

So, having just played matchmaker between UniVerse and some .Net developers, I thought it might be useful to describe the quickest path to getting your UniVerse data into a .Net grid.

My next post will describe what needs to be done to prepare the UniVerse dictionaries for .Net, and the following post will show how to create UniVerse-friendly SELECT statements and feed the results into a DataGridView.

In NetAdvantage, there aren’t separate "menu bar" and "toolbar" controls — everything is a toolbar.  A menu bar is just a toolbar with lots of text and not many icons.  Fair enough.  But not all NetAdvantage toolbars are equal – you can set the IsMainMenuBar property on one (and only one) toolbar.  In the version of NetAdvantage that we were previously using, 2007 Volume 1, this property seemed to have only one effect: it forced that toolbar to be on a separate row from all of the others.  This seemed like an odd feature, so we never used it.

At some point between 2007 Volume 1 and 2008 Volume 2, the IsMainMenuBar property became a lot more important: if none of your toolbars have it, then you lose your accelerator keys.  (By "accelerator keys", I mean the underlined letters in menus that can be used with the Alt key as a shortcut.  Some of the young folk today call them "access keys", go figure.)

I didn’t notice until one of our internal testers diplomatically asked "um, didn’t those used to be underlined"?  It took me awhile to figure out that the IsMainMenuBar property was at the root of the problem – this behaviour isn’t documented and, oddly, I couldn’t find any reference to the problem on the Infragistics forums.   I submitted the problem to Infragistics, and so far they are handling it as a bug, not a feature. 

The workaround is easy enough: use the IsMainMenuBar property.  Since this forces other toolbars onto separate rows of the screen, we also merged everything into one toolbar: I figure the loss of screen real estate would be more annoying to users than losing the ability to position the toolbars on the screen.

We finally took the plunge a few weeks ago, upgrading from 2007 Volume 1 to the latest and greatest, 2008 Volume 2. I was relieved to find that it was an almost pain-free transition.

The only bump that we hit wasn’t even a bug in the current version: it might have been a bug in 2007 Vol 1 that they fixed, or just an undocumented syntax change. The problem occurred in code which identified an UltraGrid band by key rather than index number:

// by key:
UltraGridColumn colCode = grid.DisplayLayout.Bands["clsOurObject"].Columns[“code”];

// by index:
UltraGridColumn colName = grid.DisplayLayout.Bands[0].Columns[“name”];

Our coding standard was to identify bands by key rather than index number in multi-band grids, in case the grid was reorganized and a band was added or removed.

The UltraGrid band key is read-only, being automatically set by the Infragistics code.  When we first started using NetAdvantage in 2006, I noticed that the key for the first-level band was set to the name of the underlying class, but the keys for the child bands were set to the name of the list variable which contained the band’s rows.  Strange, but not something that ruined my day.  Life went on.

However, after the upgrade to 2008 Volume 2, this eccentricity became a problem.  The key names were now all based on the list variable name.  After fruitlessly poking around the UltraGrid’s properties and methods for an option that would change things back to the way they were, I gave up and went with the low tech approach of changing all the band key references in our code:

//UltraGridColumn colCode = grid.DisplayLayout.Bands["clsOurObject"].Columns[“code”];
// new key name:
UltraGridColumn colCode = grid.DisplayLayout.Bands["lstOurStuff"].Columns[“code”];

We posted the problem to Infragistics’ support forum, and their support team was surprised that our original code had ever worked when using the class name as the key.  So, the problem remains unexplained: strange, but still not something that ruined my day.

I haven’t taken advantage of the new functionality yet, but one clear and unexpected advantage from the upgrade is a marked performance improvement in large grids. We have a window which loads massive amounts of data into a two-level grid: sometimes over a million rows.  A grid of 200,000 rows which used to take about 30 seconds to load on my development PC (measured from the point that the underlying list was populated until the grid was up and responsive to user input) now takes just 6 seconds.  Navigating through this type of large grid and applying sorts and filters is also noticeably faster – sorting the 200,000 row grid takes less than a second, filtering takes about 3.  The Release Notes mention some tweaking that Infragistics did to the grid back in Version 2007 Volume 3, but I didn’t expect an improvement on this scale.

A major update with just 1 bug and a huge performance boost: that’s what I call a upgrade!

Having made the leap over to IBM’s new "DB2 Client" ADO.Net driver for the U2 UniVerse database, we recently spent some time figuring out how to get it onto users’ PCs.  This turned out to be harder than I expected, and harder than it should be.

The new Data Client’s installer was actually a big selling point for us.  The previous database driver, UniOLEDB, used a proprietary install program that didn’t support automated, silent installs.  This means that someone from the user’s IT department had to visit each user’s desktop and 1) launch the install program, 2) click Next a bunch of times, 3) phone us and complain about how annoying this is.  Every install program that we’ve created or incorporated into our product for the last 10 years has supported silent installs, except this one.  

I was so giddy at the prospect of moving on to a proper installer that I assured our clients that we would now fully support silent installs without (ahem) actually trying to do one.  My optimism was based on the fact that 1) the new database client uses the same installer as IBM’s flagship database, DB2, 2) this installer was created using one of the industry standard tools, InstallShield, which has supported silent installs for ages, and 3) the DB2 Information Center’s extensive documentation includes a section entitled "Silent Installation".  It sure looks easy when you read about it.

Unfortunately, it doesn’t quite work the way it’s described, and finding the specifics required quite a lot of Googling as well as some trial and error. 

Here’s what doesn’t work:

1) Installing without a response file.  This will launch the installer, but it will quickly abort, and the error message written to the log is enigmatic:

Action ended 20:06:46: DB2SetDB2INSTANCECA.2BC48F01_561E_4906_8321_946A9F5A90AA. Return value 3.
Action ended 20:06:46: INSTALL. Return value 3.
MSI (s) (E4:68) [20:06:46:607]: Product: IBM Data Server Runtime Client – DB2COPY1 — Configuration failed.

Presumably, the response file is mandatory.

2) The standard InstallShield command line switch for generating a response file in the Windows folder (-r).  I never thought that the Windows folder was a great place to put it — apparently IBM agrees.

3) The Response File Generator utility (db2rspgn).  Although this utility does, indeed, generate a response file, we had absolutely no luck when trying to use this response file to do an install.  Googling the problem suggested that many others had the same result, but I still have no idea what the solution is, if any.

4) Manually editing one of the sample response files, as suggested by the Information Center, might have worked if we actually had a sample response file.  The sample response files are apparently located on the "Information Integration Product DVD", but I’ve never seen such a beast.

Here’s what does work:

1) Run the installer normally (with no command line switches), then look in your %TEMP% folder.  Sure, enough, there’s a .rsp file left behind in there. 

2) This response file works just fine with the standard InstallShield parameters for a silent install.  For the current version of the DB2 runtime client, this is :

v9.5fp2_nt32_rtcl_en.exe /v"/qn RSP_FILE_PATH=<path of the .rsp file>.

The contents of the elusive response file are somewhat of a letdown.  Unless you need to install 2 different versions of the database drivers, you’re unlikely to ever want to change a thing.   Should you not have an Information Integration Product DVD at hand, feel free to use our response file as a sample:

PROD=RUNTIME_CLIENT
INSTALL_TYPE=TYPICAL
DB2_COPY_NAME=DB2COPY1
DEFAULT_COPY=YES
DEFAULT_CLIENT_INTERFACE_COPY=YES
DEFAULT_INSTANCE=DB2
INSTANCE=DB2
DB2.NAME=DB2
LIC_AGREEMENT=ACCEPT

string strConn = @"User ID=JoeUser;Password=HisPassword;Database=c:\account\path;Server=ourserver;ServerType=universe;pooling=false";

Incidentally, you can now do away with the cryptic "uci.config" initialization file used by UniOLEDB.  The ADO.Net driver does not require any configuration beyond what is in the code.  Welcome to the 21st century!

5. Certain OleDB database objects need to be replaced with their ADO equivalents.  Note that the syntax for DataReaders, Commands and Parameters is quite similar, with the main difference being that the ADO objects don’t have their own constructors.  The DataAdapter, on the other hand, requires considerably more code to create using the ADO.Net driver:

• OleDbCommand is now DbCommand

// UniOLEDB
public static OleDbCommand DB_GetCommand(string strSQL)
{
    OleDbCommand cmd = new OleDbCommand(strSQL, conn);
    return cmd;
}

// ADO.Net
public static DbCommand DB_GetCommand(string strSQL)
{
    DbCommand cmd = conn.CreateCommand();
    cmd.CommandText = strSQL;
    cmd.CommandType = CommandType.Text;
    return cmd;
}

• OleDbDataReader is now DbDataReader

// UniOLEDB:
public static DbDataReader DB_GetReader(string strSQL)
{
    OleDbCommand cmd = new OleDbCommand(strSQL, conn);
    DbDataReader rdr = cmd.ExecuteReader();
    return rdr;
}

// ADO.Net:
public static DbDataReader DB_GetReader(string strSQL)
{
    DbCommand cmdSQL = conn.CreateCommand();
    cmdSQL.CommandText = strSQL;
    cmdSQL.CommandType = CommandType.Text;
    DbDataReader rdr = cmdSQL.ExecuteReader();
    return rdr;
}

• OleDbDataAdapter is now DbDataAdapter

// UniOLEDB:
public static OleDbDataAdapter DB_GetAdapter()
{
    return new OleDbDataAdapter();
}

// ADO.Net:
public static DbDataAdapter DB_GetAdapter()
{
    DbProviderFactory factory = DbProviderFactories.GetFactory("IBM.Data.DB2");
    DbDataAdapter adapter = factory.CreateDataAdapter();
    return adapter;
}

• OleDbType is now Db2Type (since we needed to support both UniOLEDB and ADO.Net, I changed our code to use the generic DbType enum and added conversion methods for the types that we use):

// UniOLEDB:
public static OleDbType DB_GetOleDbType(DbType type)
{
    switch (type)
    {
        case DbType.Date:
            return OleDbType.DBDate;
        case DbType.Decimal:
            return OleDbType.Decimal;
        case DbType.String:
            return OleDbType.VarChar;
        case DbType.Int32:
            return OleDbType.Integer;
    }
}       

// ADO.Net:
private static DB2Type DB_GetDB2Type(DbType type)
{
    switch (type)
    {
        case DbType.Date:
            return DB2Type.Date;
        case DbType.Decimal:
            return DB2Type.Decimal;
        case DbType.String:
            return DB2Type.VarChar;
        case DbType.Int32:
            return DB2Type.Integer;
    }
}

• OleDbParameter is now DbParameter

// UniOLEDB:
public static void DB_AddParameter(OleDbCommand cmd, string strName, DbType type, int intSize, string strSourceColumn)
{
    OleDbType oleDbType = DB_GetOleDbType(type);
    cmd.Parameters.Add(strName, oleDbType, intSize, strSourceColumn);
}       

// ADO.Net:
public static void DB_AddParameter(DbCommand cmd, string strName, DbType type, int intSize, string strSourceColumn)
{
    DB2Type db2Type = DB_GetDB2Type(type);
    DbParameter param = new DB2Parameter(strName, db2Type, intSize, strSourceColumn);
    cmd.Parameters.Add(param);
}

6. Once all of the tedious but straight-forward "a Quarter Pounder with Cheese is now a Royale with Cheese" stuff is out of the way, you should find that the two drivers speak pretty much the same language and not many other code changes are required. When we fired up the app and tried out our SQL statements, we only found two cases where the same statement didn’t return the same data:

a. Subvalue markers (ASCII 252) are returned by the ADO.Net driver as carriage-return/line-feed ("/r/n").  Subvalues are a method used by UniVerse to stuff 3 levels of data into a single field: if a multivalued field can be thought of as representing a parent-child table relationship, then subvalues can be thought of as parent-child-grandchild.  We don’t use them much, and it seems that most other developers don’t either, since IBM support wasn’t aware of this when I reported it to them.  However, IBM intends to resolve this problem in Fix Pack 3.

b. The ADO.Net driver doesn’t support use of the virtual "@ASSOC_ROW" field in SQL statements.  The UniOLEDB driver stored a row number in this field when converting a multivalued field into multiple virtual rows.  SQL statements that rely on row numbers are almost certainly not a good idea in any database — you should be able to rewrite the SQL to avoid using them.


And there you have it — with a relatively small and straightforward set of code changes, you’re now accessing your UniVerse data with a true-blue ADO.Net driver. 

As for the set of problems listed at the top of this article, I can report that the new driver solves problems #2 and #4.  I haven’t tried doing database updates with ADO.Net yet, so I can’t say if problem #1 is solved.  I noticed that IBM’s series of tutorials for the new driver recommends that database subroutines (written in UniVerse Basic) be used to handle updates, so I plan to stick to using UniObjects for the time being. 

We haven’t completely cracked problem #3 yet, partly because of the unavoidable "multivalued database with lipstick" issue.  The Visual Studio add-in works great with the sample HS.SALES account, and every crusty old UniVerse Basic programmer that I’ve showed it too is quite surprised to see a graphical database design tool that works with UniVerse.  Unfortunately, when we tried accessing our real world database we ran into a serious performance problem.  HS.SALES has 749 entries in its master dictionary — our database has over 5 thousand.  As a result, it took Visual Studio a few minutes to enumerate all of our schema objects.  A few minutes might not seem so bad, but this enumeration is done not only when the database’s object tree is first displayed, but each and every time a new query is created from the Data Connection.  It’s really cramping our style!

However, there is hope that Visual Studio and UniVerse can now get along.  IBM provides a few different ways to filter the number of schema objects that are available to Visual Studio, and we’ll be trying out those methods in the future.  I’ll write about that in a future article.

if (grid.ActiveRow.IsDataRow)
{
	grid.ActiveRow.Band.Columns["columnkeyname"].TabStop = false;
	grid.ActiveRow.Band.Columns["columnkeyname"].CellActivation = Activation.NoEdit
}

There are a number of things in this short piece of code that require some explanation for those not accustomed to the ways of the UltraGrid:

• The IsDataRow property is necessary to make sure that you’re not trying to set the edit state of a row that isn’t displaying your data, such as the header rows that the UltraGrid automatically inserts when using its Group By feature.
• The Band property is used to identify which drill-down level the row belongs to.  An example is the screenshot at the right, from Infragistics’ website, showing a grid with 3 bands.  And if you’re working with a plain vanilla grid with just 1 set of rows?  Tough, you’ve still got a band, like it or not, so get used to coding a Band reference for rows, columns and cells.
• The only .CellActivation setting that allows users to Tab past a non-editable cell is "disabled", which also prevents the user from selecting the cell for copying into the clipboard.  So, you’ll generally want to use Activation.NoEdit and set the TabStop separately.

Changing the editable state of a row

You might spend hours looking in vain for the setting to make a row non-editable.  You can set the edit state for columns and cells, but not rows.  Here’s some code to do it the hard way:

public static void Infragistics_SetAllColumnsEditState(UltraGrid grid, bool blnEditable,
	bool blnAllowTab)
{
	UltraGridBand band = grid.ActiveRow.Band;

	for (int i = 0; i < band.Columns.Count; i++)  // columns belong to a band, not a row
	{
		if (!band.Columns[i].Hidden) // don't mess with hidden columns!
		{
			if (blnEditable)
			{
				column.TabStop = true;
				column.CellActivation = Activation.AllowEdit;
			}
			else
			{
				column.TabStop = blnAllowTab;
				column.CellActivation = Activation.NoEdit;
			}
		}
	}
}

Notice that Columns belong to a Band, not a Row.  Cells belong to a Row, but the CellActivation property doesn’t exist for Cells, just Columns.  Go figure.

Translating Grid Text

The UltraGrid is unusually verbose for a screen component: there’s text in the filter settings (as shown in the screenshot), text in the column chooser, text in the Group By interface, and so on.  All those prompts and instructions are better than Ikea-like pictograms, I suppose, but it’s all in English. 


If you need to support other languages, you’ll need to provide your own translations.   To do so, you’ll need a reference to the Infragistics ResourceCustomizer class, and a list of the keys used to identify each piece of text.

            Infragistics.Shared.ResourceCustomizer rc = Infragistics.Win.UltraWinGrid.Resources.Customizer;
            rc.SetCustomizedString("GroupByBoxDefaultPrompt", NLS.TxDragaColumnHeadr);
            rc.SetCustomizedString("ColumnChooserButtonToolTip", NLS.TxFieldChooser);
            rc.SetCustomizedString("ColumnChooserDialogCaption", NLS.TxFieldChooser);
            rc.SetCustomizedString("FilterClearButtonToolTip_RowSelector", NLS.TxClearAllFilterCriteria);
            // and so on...

The "NLS" in the above code is a reference to the project’s resource class where we store all our text translations.

Selecting All Rows in the Grid

This is another common task that seems more convoluted than necessary.  Rather than just tell the UltraGrid "Select All", you need to tell it "Add to the collection of selected rows all the data rows that are currently visible in the grid":

grid.Selected.Rows.AddRange(grid.Rows.GetFilteredInNonGroupByRows());

Make Enter Work Like Tab

A grid looks like a spreadsheet, so UltraGrid should work like Excel, right?  Your users will probably think so, but UltraGrid’s designers don’t entirely agree.  By default, pressing Enter in a grid cell won’t do anything.  The solution is extremely non-obvious, but fortunately it’s covered in the Infragistics KnowledgeBase article KB2028:

Infragistics.Win.UltraWinGrid.GridKeyActionMapping newKam;

foreach (Infragistics.Win.UltraWinGrid.GridKeyActionMapping ugKam in Grid.KeyActionMappings)
{
	if (ugKam.KeyCode == Keys.Tab)
	{
		newKam = new Infragistics.Win.UltraWinGrid.GridKeyActionMapping(Keys.Enter, ugKam.ActionCode, ugKam.StateDisallowed, ugKam.StateRequired, ugKam.SpecialKeysDisallowed, ugKam.SpecialKeysRequired);
		Grid.KeyActionMappings.Add(newKam);
	}
}

Select A Range of Cells

By default, when the user drags the mouse down a column of cells the grid will select cells row-by-row, similar to a Word document.  Most users will expect cell selection to work like Excel, not Word, and allow a rectangular region of cells to be selected.   Fortunately, turning on this support is a one-liner, but the trick is that you’ll need to put that 1 line in the InitializeLayout event:

private void grid_InitializeLayout(object sender, InitializeLayoutEventArgs e)
{

		// allow drag select like in Excel
		e.Layout.Override.SelectTypeCell = SelectType.Extended;

}

Paste Into A Range of Cells

This is another case where users will expect your grid to emulate Excel.  If you a copy a cell into the clipboard then select a rectangular set of cells and click Paste, they’ll want the contents of the clipboard to be pasted into the full range of selected cells, repeating the value(s) as often as necessary.  Unfortunately, to UltraGrid paste means "paste once", so you’ll have to do the work yourself:

int intNumRows;
int intNumCols;
UltraGridCell startingCell = GetSelectedCells(grid, out intNumRows, out intNumCols);
if (startingCell != null)
{
	string[,] strClipboardCells = Array_FromClipboard(strHeaderValues);
	int intClipboardRows = strClipboardCells.GetUpperBound(0) + 1;
	int intClipboardCols = strClipboardCells.GetUpperBound(1) + 1;
	// if only 1 cell is selected, assume that the user wants to paste the entire clipboard (Excel's behaviour)
	if ((intNumRows == 1) & (intNumCols == 1))
	{
		intNumRows = intClipboardRows;
		intNumCols = intClipboardCols;
	}
	if ((intClipboardRows > 0) &
		(intClipboardCols > 0))
	{
		int intClipboardRow = 0;
		int intClipboardCol = 0;
		int intCurrentRow = 0; // row index within the selection
		int intCurrentCol = 0; // col index within the selection
		int intStartingColOfClipboardBlock = 0; // col index within selection of start of current paste block
		int intStartingRowOfClipboardBlock = 0; // row index within selection of start of current paste block
		UltraGridCell currentCell = startingCell;
		UltraGridRow currentRow = currentCell.Row;
		UltraGridCell startingCellOfClipboardBlock = startingCell;
		UltraGridColumn col; // current column to be pasted in the grid
		UltraGridRow row; //current row to be pasted in the grid

		while (intCurrentRow < intNumRows)
		{
			// paste the value
			currentCell.Value = strClipboardCells[intClipboardRow, intClipboardCol];

			// advance to next cell in clipboard
			intClipboardCol += 1;
			// advance to next cell in selection block
			intCurrentCol += 1;
			// advance to the next cell in the grid
			col = currentCell.Column.GetRelatedVisibleColumn(VisibleRelation.Next);
			// if we've reached the last cell of the clipboard, or last cell of the selection block, or last cell of
			//   the grid, need to wrap around
			if ((intClipboardCol >= intClipboardCols) | (intCurrentCol >= intNumCols) | (col == null))
			{
				intClipboardRow += 1;
				intClipboardCol = 0;
				row = currentCell.Row.GetSibling(SiblingRow.Next);
				intCurrentRow += 1;
				intCurrentCol = intStartingColOfClipboardBlock;

				// if we've reached the last row of the clipboard, or last row of the selection block, or last row of
				//   the grid, need to advance to next set of columns to be pasted
				if ((intClipboardRow >= intClipboardRows) | (intCurrentRow >= intNumRows) | (row == null))
				{
					// start pasting a new clipboard block, unless we've reached the end of the selection
					intCurrentRow = intStartingRowOfClipboardBlock;
					intClipboardCol = 0;
					intClipboardRow = 0;
					intCurrentCol = intStartingColOfClipboardBlock + intClipboardCols;
					intStartingColOfClipboardBlock = intCurrentCol;
					col = currentCell.Column.GetRelatedVisibleColumn(VisibleRelation.Next);
					if ((intCurrentCol >= intNumCols) | (col == null))
					{
						// reached last column of paste selection, advance to next set of rows to be pasted into
						intCurrentRow += intClipboardRows;
						intCurrentCol = 0;
						intStartingColOfClipboardBlock = 0;
						intStartingRowOfClipboardBlock = intCurrentRow;
						if (row != null)
						{
							currentCell = row.Cells[startingCell.Column.Key];
							startingCellOfClipboardBlock = currentCell;
						}
						// else, we've reached the end of the grid, so presumably intRow is > intNumRows and the
						//   while loop will end
					}
					else
					{
						// start pasting a new block in the same row as the previous block
						currentCell = startingCellOfClipboardBlock.Row.Cells[col.Key];
						startingCellOfClipboardBlock = currentCell;
					}
				}
				else
				{
					// wrap around to next cell
					currentCell = row.Cells[startingCellOfClipboardBlock.Column.Key];

				}
			}
			else
			{
				currentCell = currentCell.Row.Cells[col.Key];

			}
		}
	}
}

Much of this code is pretty mundane stuff that I’m including to complete the solution, but a couple of odd methods stand out. The call to currentCell.Column.GetRelatedVisibleColumn(VisibleRelation.Next) is a complicated solution to a seemingly easy requirement: get the next column to the right.  Columns in UltraGrid are indexed according to their position in the data source, not on the screen. Similarly, to move to the next row you can’t just increment the row index: that won’t skip past filtered-out rows and hidden row.  If you’re using drill-down rows then row navigation becomes even more complicated, so the approach I use is currentCell.Row.GetSibling(SiblingRow.Next).   Surprisingly, there is no collection in the UltraGrid that presents the grid cells in the same order that the user sees them — your code will have to figure that out on the fly in order to navigate through the grid cell by cell.

Notice that the instruction that does the actual pasting is a one-liner that is overshadowed by all the grid navigation code — picking that line out of the pile is sort of like playing "Where’s Waldo".

The Array_FromClipboard method called by this code is pretty self-explanatory, but the GetSelectedCells method qualifies as non-obvious because of the same navigation problems described above.  It’s easy to get the collection of selected cells — grid.Selected.Cells — but that collection of cells isn’t nicely organized into rows and columns for you.  To figure out how many rows and columns are selected, and which of the cells is the upper left corner of the selection, you’ll need to do a bit of work:

// initialize
int intFirstSelectedRow = Int32.MaxValue;
int intFirstSelectedCol = Int32.MaxValue;

int intLastSelectedRow = -1;
int intLastSelectedCol = -1;
UltraGridCell upperLeftCell = null;

foreach (UltraGridCell cell in grid.Selected.Cells)
{
	bool blnFirstCol = false;
	bool blnFirstRow = false;
	if (cell.Row.VisibleIndex < intFirstSelectedRow)
	{
		// use visible row -- otherwise, hidden network babies cause problems
		intFirstSelectedRow = cell.Row.VisibleIndex;
		blnFirstRow = true;
	}
	if (cell.Row.VisibleIndex > intLastSelectedRow)

		intLastSelectedRow = cell.Row.VisibleIndex;
	if (cell.Column.Header.VisiblePosition < intFirstSelectedCol)
	{
		intFirstSelectedCol = cell.Column.Header.VisiblePosition;
		blnFirstCol = true;
	}
	if (cell.Column.Header.VisiblePosition > intLastSelectedCol)
		intLastSelectedCol = cell.Column.Header.VisiblePosition;
	if (blnFirstCol & blnFirstRow)
		upperLeftCell = cell;
}

intNumSelectedCols = intLastSelectedCol - intFirstSelectedCol + 1;
intNumSelectedRows = intLastSelectedRow - intFirstSelectedRow + 1;

Notice that the VisibleIndex and VisiblePosition properties are used instead of Index and Position.  The rows’ Index property includes filtered-out rows, while the columns’ Position property includes hidden columns and does not account for the fact that UltraGrid allows users to drag columns to a new position.

Tabbing Into the Grid

OK, for my last trick of the day, I’d like to cover yet another scenario that should "just work", but doesn’t.  If a user tabs into a grid, they’ll expect focus to be on the first editable cell so that they can just start typing.  By default, when you tab into UltraGrid it gives the focus to… nothing. As far as I can tell, it isn’t possible for users to start editing a grid without using the mouse.  After much trial and error, I ended up adding the following code to the grid’s Enter event:

if (grid.ActiveCell == null)
{
	if (grid.ActiveRow == null)
	{
		if (grid.Rows.Count == 0)
			return; // empty grid, so no way to give a cell focus
		grid.ActiveRow = grid.Rows[0];
	}
	// make the leftmost cell the active cell -- will find the first editable cell below
	grid.ActiveCell = grid.ActiveRow.Cells["theKey"];
}
UltraGridCell cell = grid.ActiveCell;
if (!cell.CanEnterEditMode)
	// find the next editable cell
	grdRatings.PerformAction(UltraGridAction.NextCell);
if (grdRatings.ActiveCell != null)
{
	while (!grid.ActiveCell.CanEnterEditMode)
	{
		// have we reached the end?
		grid.PerformAction(UltraGridAction.NextCell);
		if (grid.ActiveCell == null)
			return; // give up
		if (grid.ActiveCell == cell)
			return; // we aren't going anywhere, give up
		if ((grid.ActiveCell.Row.Index == 0) & (grid.ActiveCell.Column.Key == "theKey"))
			return; // looped around, so give up
		cell = grid.ActiveCell;

	}
	if (cell.CanEnterEditMode)
		grid.PerformAction(UltraGridAction.EnterEditMode);

	grid.ActiveRowScrollRegion.ScrollCellIntoView(grid.ActiveCell, grid.DisplayLayout.ColScrollRegions[0]);
}

Ye gods, that’s a lot of work for such a simple and commonplace task!  I guess that’s why they pay us coders the big bucks. 

Notice that the list line of the above code sample contains a reference to something called a column scroll region.  Oooh, what’s that?  It’s a method of divided up your grid rows into sections that scroll independently, similar to Excel’s Split feature.  It’s also filled with more pitfalls than the Temple of Doom.  Sounds like a good topic for a future article!


Update on November 26, 2008:

In response to the question in the comments section about overriding the default UltraGrid error messages… 

In general the best way to prevent the Infragistics grid from displaying its error messages to the user is to handle the grid’s Error event.  Just set the e.Cancel parm to true.  This Infragistics help page includes a good example of the things you can do in the Error event.

In the case of null values, you can set the column’s Nullable property  to tell the grid that null values are allowed. If your grid’s data source is a database table then UltraGrid will automatically set this property to an appropriate value for the column — otherwise you’ll need to set this property yourself. The property is set to whatever value you want to display in the column when it is empty, which is usually a zero length string: e.g. col.Nullable = Infragistics.Win.UltraWinGrid.Nullable.EmptyString;