This time, we are going to use VFP 8 and its new XmlAdapter class together with the new structured error handling, called Try/Catch...

Using Try-Catch-Finally

A new command have being incorporated to the already existing ones on Visual FoxPro's control structure: the brand-new Try/Catch. This instruction set allows for a structured error handling style and offers great simmilarity with .NET and even with Visual C++. Though I have already shown similarities and differences between both platforms' control structures, I will explain just the Visual FoxPro implementation of this structure, as this and its .NET sibling are simmilar enough to understand one by knowing the other.

Just like every Visual FoxPro instruction, Try has its corresponding EndTry, which indicates the end of the error trapping, but before this happens, there are two elements to deal with: Catch and Finally.

Let’s consider each point in order to understand them:

1. Try: Starts the error trapping. Since there, any error will be redirected to the CATCH block, and the lines following the one that produced the error will not be executed, of course.
2. Catch [ To loError ]: Here is where the error itself is handled. The instruction is able to create an Exception object, which has properties like ErrorNo or Message to know more details about the error.
3. Throw [ eUserExpression ]: When this clause is included with eUserExpression, Visual FoxPro forces the Exception object's ErrorNo property to 2071 and shows "User Thrown Error(Error 2071)". If eUserExpression is omitted, Visual FoxPro looks for the original object Exception if it exists, else, it creates a new Exception object and assigns the value 2071 to ErrorNo property.
4. Exit: This instruction immediately stops the execution of the current block. If Exit is in the Try or Catch blocks, the program executes the Finally block if any, otherwise, the first line after EndTry is executed.
5. Finally: The code included in this block will be executed whether or not an error happens, provided all your code is written in TRY-CATCH blocks. The Finally block may be used to clean things up, i.e. to release not required variables or cursors.
6. EndTry: This is the end of the instruction.

The first contact with Try-Catch

Function Print_Report_CR9( tcReportName as string ) as Boolean
   Local loCR as CrystalRuntime.Application, llOk as Boolean
   llOk = .t.
   if empty(tcReportName )
      tcReportName = "C:\MiReporte.rpt"
   endif
   
   Try
      loCR = CreateObject( "Crystal Runtime.Application" )
      MessageBox( "The object has been property created." )
   Catch
      llOk = .f.   
      MessageBox( "An error has occurred." )
   EndTry

   Return ( llOk )
EndFunc

In this example, since Crystal Report's runtime library is misspelled, an error will occur and Catch will trap it. Nevertheless, the error trapping is still quite primitive, as you do not know what the message or the error number are.

To trap the error object

Function Print_Report_CR9( tcReportName as string ) as Boolean

   Local loCR as CrystalRuntime.Application, llOk as Boolean
   llOk = .t.
   if empty( tcReportName )
      tcReportName = "C:\MiReporte.rpt"
   endif
   Try
      loCR = CreateObject( "CrystalRuntime.Application" )
      loRP = loCR.OpendReport( tcReportName )
      MessageBox( "The report has been property opened." )

   Catch to loError
      llOk = .f.
      MessageBox( "Error Nro: " + alltrim( str( loError.ErrorNo ) );
      + chr( 13 ) + "Message: " + loError.Message )
   EndTry

   Return ( llOk )
EndFunc

Now we can see that trapping the error number and message is very easy, and it gives us the chance to handle any other property of the loError object.

Obviously, you can write your own routine to save and/or to format the error according to your needs. Instead of the MessageBox() function, just call your routine.

NOTE: Making some tests, I tried to save the last error within an object i.e. goApp.oError, and I got an error, as it seems that you can store the error in a variable, but not in an object property.

Multiple Catch blocks

Function Print_Report_CR9( tcReportName as string ) as Boolean

   Local loCR as CrystalRuntime.Application, llOk as Boolean
   llOk = .t.
   if empty( tcReportName )
      tcReportName = "C:\MiReporte.rpt"
   endif
   Try
      loCR = CreateObject( "CrystalRuntime.Application" )
      loRP = loCR.OpendReport( tcReportName )
      MessageBox( "The report has been property opened." )

   Catch to loError When loError.ErrorNo = 1733
      llOk = .f.
      MessageBox( "Cannot find the Crystal Report Runtime Library" )

   Catch to loError When loError.ErrorNo <> 1733
      llOk = .f.
      MessageBox( "Error No: " + alltrim( str( loError.ErrorNo ) );
      + chr( 13 ) + "Message: " + loError.Message )
   EndTry

   Return ( llOk )
EndFunc

Within the catch block, we are able to set different actions according to the error number returned by the exception object. This may be done in two different ways: the first one is to write several catch blocks that execute different actions; the second one is to write a Do Case in the Catch block and handle the errors therein.

Nesting blocks

This new command allows to nest Try/Catches just like we can nest an If or any other command belonging to Visual FoxPro's control structure. Though I am sure that what nesting is and how to nest instructions do not need to be explained, I found interesting to show how Try-Catch performs when nested, even when its behavior is what you should expect.

Function Print_Report_CR9( tcReportName as string ) as Boolean

   Local loCR as CrystalRuntime.Application, llOk as Boolean

   llOk = .t.
   if empty( tcReportName )
      tcReportName = "C:\MiReporte.rpt"
   endif

   Try
      loCR = CreateObject( "CrystalRuntime.Application" )
      loRP = loCR.OpendReport( tcReportName )
      MessageBox( "The report has been property opened." )

      Try
         loRP.Print( 1234567890 )
         MessageBox( "The report was printed successful" )
      Catch to loError
         MessageBox( "Nested Error: " + loError.Message )
      EndTry
      MessageBox( "This is always shown." )
   Catch to loError
      MessageBox( "Error No: " + alltrim( str( loError.ErrorNo ) );
      + chr( 13 ) + "Message: " + loError.Message )
   EndTry

   llOk = ( vartype( loError ) <> "O" )
   Return ( llOk )
EndFunc

According to this example, once the object is created and the report is opened, another Try block starts, when we intend to print, but we entered a wrong parameter, so that an error occurs. Then, the error is trapped by the Catch in this Try block and the message "Nested Error" is shown. Exiting this block, the program executes the following code line and exits the next Try level. This way, as expected, we see that each Catch traps the errors from its own Try instead passing the errors to the next level.

On the other hand, you can pass the error from one block to the higher level, using the Throw instruction. This command "sends" the error occurred to the next Catch level, and so you can pass the error through different tiers.

Passing an error to the next higher level

Function Print_Report_CR9( tcReportName as string ) as Boolean

   Local loCR as CrystalRuntime.Application, llOk as Boolean
   llOk = .t.

   if empty( tcReportName )
      tcReportName = "C:\MiReporte.rpt"
   endif
   Try
      loCR = CreateObject( "CrystalRuntime.Application" )
      loRP = loCR.OpendReport( tcReportName )
      MessageBox( "The report has been property opened." )

      Try
         loRP.Print( 1234567890 )
         MessageBox( "The report was printed successful" )
      Catch
         Throw
      EndTry
      MessageBox( "If there is an error, this will never be shown." )

   Catch to loError
      MessageBox( "Error No: " + alltrim( str( loError.ErrorNo ) );
      + chr( 13 ) + "Message: " + loError.Message )
   EndTry
   llOk = ( vartype( loError ) <> "O" )
   Return ( llOk )
EndFunc

In the lines above, if an error occurs in the nested Try-Catch, it is passed to the higher level by the Throw instruction. Without any parameters, this instruction hands the Exception object over to the next level, so it can handle the error. You may need to create a custom error; in that case you can create your own exception an assign it the required values as follows:

Function Print_Report_CR9( tcReportName as string ) as Boolean

   Local loCR as CrystalRuntime.Application, llOk as Boolean
   llOk = .t.
   if empty( tcReportName )
      tcReportName = "C:\MiReporte.rpt"
   endif
   Try
      loCR = CreateObject( "CrystalRuntime.Application" )
      loRP = loCR.OpendReport( tcReportName )
      MessageBox( "The report has been property opened." )

      Try
         loRP.Print(1234567890)
         MessageBox( "The report was printed successful." )
      Catch
         loExc = createobject( "Exception" )
         loExc.ErrorNo = -1
         loExc.Message = "Printing error."
         Throw loExc
      EndTry
      MessageBox( "If there is an error, this will never be shown." )
   Catch to loError
      MessageBox( "Error No: " + alltrim( str( loError.ErrorNo ) );
      + chr( 13 ) + "Message: " + loError.Message )
   EndTry
   llOk = ( vartype( loError ) <> "O" )
   Return ( llOk )
EndFunc

What is Finally useful for?

Function Print_Report_CR9( tcReportName as string ) as Boolean
   Local loCR as CrystalRuntime.Application, llOk as Boolean
   llOk = .t.
   if empty( tcReportName )
      tcReportName = "C:\MiReporte.rpt"
   endif
   Try
      loCR = CreateObject( "CrystalRuntime.Application" )
      loRP = loCR.OpendReport( tcReportName )
      MessageBox( "The report has been property opened." )

      Try
         loRP.Print( 1234567890 )
         MessageBox( "The report was printed successful" )
      Catch
         Throw
      Finally
         MessageBox( "This is always shown." )
      EndTry
      MessageBox( "If there is an error, this will never be shown." )
   Catch to loError
      MessageBox( "Error No: " + alltrim( str( loError.ErrorNo ) );
      + chr( 13 ) + "Message: " + loError.Message )
   EndTry

   llOk = ( vartype( loError ) <> "O" )
   Return ( llOk )
EndFunc

From CursorToXml to XmlAdapter

The XmlAdapter class is among the most interesting new features on the 8th version of Visual FoxPro as it allows us to interact with .NET by supporting multi-table XML documents, resembling a .NET DataSet. This is why Visual FoxPro 8 is the most advisable choice when facing a three-tier project, not only because it is a very powerful tool, but also because it is totally compatible with .NET.

Though the XmlAdapter object holds several properties, methods and events, I will focus in showing its functionality rather than enumerate them. To see the complete list of methods and properties of this class you can always read the Visual FoxPro help.

Although we have already seen how to pass an XML document to C#, we are going to see a couple of simple examples about passing multiple results, thus loading several screen elements in a single call, i.e. heading data, a grid and a combobox.

Generating the XML from Visual FoxPro

Let's create a class that contains a method which returns an XML with 3 tables.

Define Class Customers as Session OLEPUBLIC

   Function Init
         set talk     off
         set safety   off
         set delete    on

         set exact     on
         set near      off
         set exclusive off
         set multilock on
         set century   on
         set century   to 19 ROLLOVER 50
         set date      to DMY
         set reprocess to 10 seconds
   EndFunc

   Function GetOrders( tcCustomerID as string ) as String
      Local lcXml as string      ,;
            loXA as XmlAdapter   ,;
            loError as Exception
      lcXml = ""
      Try
         Open DataBase home( 2 ) + "\Northwind\NorthWind" Shared

         Select * From Customers   ;
            Where CustomerID = tcCustomerID into cursor cur_Customers
         Select * from Orders ;
            where CustomerID = tcCustomerID Into Cursor cur_Orders

         loXA = CreateObject( "XmlAdapter" )
         loXA.XMLSchemaLocation = "1"
         loXA.AddTableSchema( "cur_Customers" )
         loXA.AddTableSchema( "cur_Orders" )
         loXA.ToXML( "lcXml", "", .F. )
      Catch to loError
         if version( 2 ) = 0
            comreturnerror( str( loError.ErrorNo ), loError.Message )
         else
            messagebox( loError.Message )
         endif
      Finally
         Close Tables All
      EndTry
      Return lcXml
   EndFunc
EndDefine

In this example we create several cursors from a Visual FoxPro database. As we intend to generate a multi-table Xml, we use the AddTableSchema() method to store the different cursors -one at a time- into the object. Once the cursors are loaded, we can check the Count property of the Tables collection to know how many Tables the Xml object carries.

Getting the data from C#

You should remember that it is important to add a reference to the component written in Visual FoxPro to your C# Project, so that you are able to access its public methods.

To see more details about how to add a reference to a COM component in a .NET project, you can see the article www.utmag.com/spanish/october2003/page8.asp.

public void cmdGetData_Click()
{
   DataSet dsCustomers = new DataSet();
   try()

   {
      myproject.customers oCustomer = new myproject.CustomersClass();
      string xml = oCustomer.GetOrders( "ALFKI" );
      dsCustomers.ReadXml( new System.IO.StringReader( xml ) );
      dsCustomers.AcceptChanges();
      grdOrders.DataSource = dsCustomers.Tables[1];
   }
   catch(Exception exp)
   {
      MessageBox.Show( exp.Message.Trim() );
   }
}

Updating data from C#

In order to complete the integration between Visual FoxPro and C#, let's create an updating routine in the customers class, whose only function is to update records in the table orders. This routine uses the XmlAdapter and CursorAdapter objects to achieve the updating from an Xml Diffgram originated from an ADO.NET DataSet.

Function UpdateOrders( tcXml as String, tcCustomerID as string ) as VOID ;
   helpstring "Update de orders related to a Customer id." 

   Local loXA as XmlAdapter, loCA as CursorAdapter
   Try
      Open DataBase home( 2 ) + "\Northwind\NorthWind" Shared
      loXA = CreateObject( "XmlAdapter" )
      loCA = CreateObject( "CursorAdapter" )
       with loCA
          .Alias = "cur_orders"
          .SelectCmd = "Select * From Orders Where CustomerId = '" + alltrim( tcCustomerID ) + "'"
          .DataSourceType = "NATIVE"
          .DataSource = "FOX"
          .CursorFill()
          .KeyFieldList = "CustomerId, OrderId"
          .UpdatableFieldList = CursorGetProp("UpdatableFieldList")
          .UpdateNameList = CursorGetProp("UpdateNameList")
      endwith
      CursorSetProp( "Buffering", 5 )
      with loXA
         .AddTableSchema( Alias() )
         .IsDiffgram = .T.
         .LoadXML( tcXml )
         for niCount = 1 to loXA.Tables.Count
            if lower( loXA.Tables[ niCount ].Alias ) = "cur_orders"
               select ( loXA.Tables[ niCount ].Alias )
               loXA.Tables[ niCount ].ApplyDiffGram()
               TableUpdate( .t., .t., "cur_orders" )
            endif
         next
      endwith
   Catch to loError
      if version( 2 ) = 0
         comreturnerror( str( loError.ErrorNo ), loError.Message )
      else
         messagebox( loError.Message )
      endif
   Finally
      Close Tables All
   EndTry
EndFunc

1. Create XmlAdapter and CursorAdapter objects
2. Query original data back from CursorAdapter object
3. Relate the alias got with CursorAdapter to XmlAdapter
4. Load the Xml with its DiffGram
5. Issue the ApplyDiffGram on the alias
6. Issue the TableUpdate to confirm changes.

Though this routine is a simple example on how to update a single table, with a small effort and a bit of imagination, you can write a generic routine with the required intelligence to perform all the updating associated to an Xml DiffGram.

We need to introduce a small adjustment to our data gathering routine. To make easier to handle the form’s info, we will create a property of the type DataSet and use it to store all needed data, thus, when associating a grid to a table of that property, it becomes easier to extract the xml with the changes to pass it through the tiers.

Conclusion

As you can see, each new step makes stronger the existing tie between Visual FoxPro and C#, their interaction and coexistence in a common project is pretty intense because both are compatible in many aspects.

In the next issue, I will discuss in deeper detail some features and similarities between the creation of a business tier with Visual FoxPro and with C#, what issues you should keep in mind, and how difficult can be to face the migration of a class.
 

Overload

In Visual FoxPro we often use optional parameters, since the language allows this. In case we do not set some parameter, this is initialized as a logical variable with its value in false, by default. Nevertheless, it is not so simple in C#, for this language does not accept optional parameters, and variables are strong typed, meaning that every variable must have its type defined and you can’t pass –let’s say- a numeric value to a date type parameter or a Boolean value to a string parameter.

This is of course a hard shock for the developer who never had the chance to use a language that compels him to set the exact quantity of parameters or explicitly declare the data type for each variable.

While in Visual FoxPro you just can omit a parameter, in C# is needed define several times the same method with different quantity and even type of parameters in order to depending upon the quantity and type of the parameters passed, the corresponding block of code be executed. This combination of method name and quantity and type of parameters is known in .Net as signature.

A simple example for this is the collection fields of a table within a DataSet, where you can reference a field by its position in the array or by its name. This means that there are two internal methods, the first one has as parameter, a numeric value, and the second one takes as parameter a string value.

Declaring a function

Declaration of methods in C# has some differences relating to Visual FoxPro, as is shown bellow.

Visual FoxPro	C#
function GetEmployee() as string *Get an employee by id Endfunc	public string GetEmployee() { //Get an employee by id }

As to C#, you need to indicate the return data value before the name of the method, just like when you declare a variable.

Visual FoxPro
function GetEmployee( tnEmployeeId as integer ) as string *Get an employee by id Endfunc
C#
public string GetEmployee( int tnEmployeeId ) { //Get an employee by id }

Similarly to the function, you must indicate the data type for the parameters before their names, since these are also strong typed, meaning they must be explicitly declared in order to avoid a compilation error.

Declaring an overload for a parameter

In order to get the concept clear, a method can be written several times with the same name, but each time it receives different parameters. In the example, we declare the function GetEmployee() setting as parameter a numeric variable called tnEmployeeID..

public string GetEmployee( int tnEmployeeId)
{
   // Get an employee by id
}

What follows is the overloaded method, same name but the function expects a string parameter instead a numeric one, called tcLastName.

public string GetEmployee( string tcLastName)
{
   // Get an employee by last name
}

Declaring an overloaded function with several parameters

We will assume that the GetEmployeeOrders() method may receive 2 parameters, where the first one indicates the employee code and the second one the list of fields by which you desire to sort the query. This example differs from the previous one for we add an optional parameter instead of change the type of the existing one, so that we get a function that may receive one parameter in order to seek just by the key of the employee or may receive two parameters and perform a query seeking by key and sorted by a field set according to the second parameter.

Visual FoxPro.

Function GetEmployeeOrders( tnEmployeeId, tcOrderBy ) as string
   If Pcount() > 1 And VarType( tcOrderBy ) == "C"
      tcOrderBy = " Order By " + tcOrderBy
   Endif
   * Get the employee orders by id and in some specific order
EndFunc

Keep in mind that in C# you need to declare the overloaded methods, then we start declaring the firs method as follows:

public string GetEmployeeOrders( int tnEmployeeId )
{
   // Get the employee orders by the id
}

On the other hand, this second method has one more string type parameter that the former one called tcOrderBy.

public string GetEmployeeOrders( int tnEmployeeId, string tcOrderBy )
{
// Get the employee orders by id and in some specific order
}

So we implement in C# what in VFP would be a simple routine with an optional parameter. Nonetheless, once you compile in C#, intellisense finds for you two sets of parameters, meaning that (according to C#) there is one method with two overloads, enabling the calling method to send one or two parameters depending on the desired result. If the method receives one parameter, the firs version will be executed, while if two parameters are passed, it will trigger the second version.

Intellisense shows a text that starts with “1 of 2” before the parameters ennumeration, and if you use the up-down cursor keys you can see the different parameter sets for the different overloads overloads.

Let us see how to us an overloaded method in C#.

string xml = "";
try
{
   if (this.OrderBy.Trim() == "")
      //Si no hay un orden especifico, no pasar el parámetro.
      xml = GetEmployeeOrders( "ALFKI" );
   else
      //if the OrderBy property is filled.
      xml = GetEmployeeOrders( "ALFKI", this.OrderBy.Trim() );

   //Do something with the xml document.
   DataSet ds = new DataSet();
   ds.ReadXml( new System.IO.StringReader( xml ) );
   Datagrid1.DataSource( ds );
}
catch (exception exc)
{
   MessageBox.Show( exc.Message )
}

The range of this is –no doubts- pretty wide, what makes apparent that we face a develop scheme that allows quite thoroughly to handle routines.

Override

In Visual FoxPro we can clearly override code from an inherited class and this results in the replacement of the behavior of the method for the new code, as is shown below:

Let us define a simple class as custom, and write in it a method to be overwritten later.

Define class Employee as Custom OLEPUBLIC
   Function GetEmployee() as String
      Return "Original"
   EndFunc
EndDefine

Then, let us define a class that inherits the former one and override the method changing the return message.

Define class OverEmployee as Employee OLEPUBLIC
   Function GetEmployee() as String
      Return "Override"
   EndFunc
EndDefine

But C# does not allow so easily override a function, it is required to set the function in order that it can be overridden, declaring it as follows:

public virtual string GetEmployee( int tnEmployeeId )
{
// Get the employee by the id and by some specific order
}

In order to override an inherited routine you need to declare it as virtual and public. This allows at the proper time to use the clause override and write code that will supersede the original one.

public override string GetEmployee( int tnEmployeeId )
{
// Get the employee by the id and by some specific order (override)
}

Please keep in mind that you can’t override a function with a different signature (name and quantity or type of parameters), for as it was explained before, there is no such a thing as optional parameters and hence it appears as physically different functions, shown as just one by IntelliSense.

Conclusion

As you can see, some similarities between Visual Foxpro and C# are really strong, besides, for a developer with some experience in Visual Foxpro, C# gets quite simple and even intuitive, thanks to the impeccable IDE of .NET.