Using the Fortran COM Server Wizard

This section shows how to create a project, specify the COM server characteristics, generate code for, and implement an example Fortran COM server project called Adder. It contains the following topics:

• Specifying the Fortran COM Server as a Developer Studio Add-in
• Creating a Fortran COM Server Project
• Using the Fortran COM Server Wizard to Define Your COM Server
• Adding a Property
• Working with the Hierarchy Pane
• Description of Property Pages
• Modifying the Generated Code
• Build Notes
• Visual C++ ClassView
• Using Example Clients
• Modifying Your COM Servers

Specifying the Fortran COM Server as a Developer Studio Add-in

The Fortran COM Server Wizard is implemented as a Developer Studio Add-in. After you install Visual Fortran, you need to register and load the Fortran COM Server Wizard on your system. If you have not already done so, do the following:

1. In the Tools menu, click Customize
2. Click the Add-in and Macros tab
3. Enable the check box for the Fortran COM Server Wizard if it is displayed in the list
4. If it is not displayed, click the Browse button and find the CSAddin.dll file, in the ...\Microsoft Visual Studio\Common\MSDev98\Addins\Df98\ directory.
5. Click the Close button

You only need to perform this procedure once on your system.

Creating a Fortran COM Server Project

The first step in creating a Fortran COM Server is to create a new project. Start Developer Studio. In File menu, click New.

In the New Projects dialog box, select (click) the Fortran COM Server project type, as shown below (if Microsoft Visual C++ is installed on your system, additional project types will appear):

The Fortran COM Server Wizard is implemented as a Developer Studio Add-in and must be registered and loaded on your system. If you receive a message that begins with "The Fortran COM Server Wizard Add-in is not loaded into Developer Studio ...", follow the instructions in Initializing the Fortran COM Server as a Developer Studio Add-in.

In this case:

1. Enter "Adder" as the name of the project.
2. Accept or modify the project folder location.
3. Click the OK button. (If you click <Back, the previous screen appears, allowing you to change the name, location, or project type of the project being created.)

To define the initial attributes of the Fortran COM server project being created, additional information is requested. The following screen shows the Fortran COM Server AppWizard. You use the project AppWizard once per project to create the project files and skeleton template (as with other project types). The Fortran COM Server AppWizard requests the type of server (DLL or EXE), the class name, interface name, and the class derived type name:

In this case:

1. Accept the default server type (DLL).
2. Type the class name AddingMachine. Default text appears for the default interface name and class derived type name.
3. Shorten the default interface name to IAdd.
4. Accept the default class derived type name.
5. Click the Finish button. (If you click Cancel, project creation is terminated.)

A summary screen appears that summarizes the location and template information created for this project:

After you click OK, the project is created and the Fortran COM Server Wizard appears.

Using the Fortran COM Server Wizard to Define your COM Server

The Fortran COM Server Wizard lets you interactively define the attributes of your COM server. It lets you define and name classes, interfaces, methods, and so on. The user interface contains two panes:

• The left pane is a tree control that displays your classes, interfaces, methods, and so on in a hierarchy.
• The right pane is a property page that displays the properties of the selected element in the hierarchy.

The Fortran COM Server Wizard is automatically invoked by the Fortran COM Server AppWizard, so you can enter the initial definition of your server. You can, but you are not required to, fully define the server at this point. You can partially define your project and close your project workspace. Later, after you start Developer Studio and open the project workspace again, you can start the Fortran COM Server Wizard by clicking the Fortran COM Server Wizard menu item in the View menu.

With our example COM server, the initial screen of the Fortran COM Server Wizard now appears, displaying the type library GUID and the type library version:

In this case, you need to expand the hierarchy to select the IAdd interface name:

1. Click the plus sign (+) to open the COM server name (and project name) Adder.
2. Click the plus sign (+) to open the class name AddingMachine.
3. Click the IAdd interface name.

The screen appears as follows:

If the Dual Interface check box is checked, click the Dual Interface check box to uncheck it. The Adder sample only supports a COM server interface.

The hierarchy is as follows:

• The root is the COM server itself, Adder. This is also the project name.
• The immediate children of the COM server are classes. Our hierarchy initially contains a single class, AddingMachine. You can add additional classes to the COM server.
• The immediate children of a class are interfaces and the class derived-type. Our hierarchy contains the interface IAdd and the class derived-type AddingMachine_InstanceData. Each class contains one, and only one, class derived-type. You can add additional interfaces to the class.
• The immediate children of an interface are methods (one or more).
• The immediate children of a method are the method arguments (one or more).

You can use the Fortran COM Server Wizard's graphical user interface to add a class, interface, method, property, or argument:

1. Select the parent item.
2. Click the Add button.
3. Type the requested name (and other requested text).
4. Click OK.

To delete an item:

1. Select the item to be deleted.
2. Click the Delete button.

For our example Adder COM server, add the methods to the IAdd interface:

1. Verify that the IAdd interface is selected (highlighted).
2. Click the New button.

The following screen appears:

The active buttons displayed depend on the selected (highlighted) item (COM server, class, interface, method, or argument) in the hierarchy. The active buttons represent the types that are valid in the current context. For example, the Argument button is inactive since an interface was selected and an Argument must be added to a method.

In this case:

1. Select the Method type.
2. Type Clear as the name of the first method of the IAdd interface.
3. Click OK.

Because the Clear method takes no arguments, you can now add a second method, named Add:

1. Click (select) the IAdd interface.
2. Click the New button.
3. Type the second method name, Add.
4. Click OK.

The Add method requires an argument, which we will name Operand. To add the Operand argument:

1. Click (select) the Add method.
2. Click the New button.
3. Type the argument name, Operand.
4. Click OK.

Before you click OK, the screen appears as follows:

After you click OK, the Fortran COM Server Wizard screen adds the Operand argument and displays its properties.

The default data type of an argument is INTEGER(4).

In our example:

1. Use the Fortran data type combo box to change the data type to REAL(4) (as follows):
   
2. Leave the default values for Interface data and Intent.

We need to add the last method:

1. Click (select) the IAdd interface.
2. Click the New button.
3. Type the method name, GetValue.
4. Click OK.

The GetValue method requires an argument, which we will name CurrentValue. To add the CurrentValue argument:

1. Select the GetValue method.
2. Click the New button.
3. Type the argument name, CurrentValue.
4. Click OK.

For the CurrentValue argument:

1. Use the Fortran data type combo box to change the data type to REAL(4)
2. Leave the default values for Interface data.
3. Change the Intent to Out.
4. Click the Return value check box.

The screen appears as follows:

In our example, the server definition is now complete. Click the Save button to dismiss the Fortran COM Server Wizard. The project is now displayed, including the TODO.TXT file, allowing you to modify the generated code.

For detailed information about the property pages (right pane) for server, class, interface, method, argument, or instance properties, see Description of Property Pages.

To change the definition of your server later, select the Fortran COM Server Wizard menu item in the View menu.

Adding a Property

In addition to methods, an interface can contain properties. Properties are method pairs that set or return information about the state of an object. Typically, a property corresponds to a field in the object's derived type. For example, in the AddingMachine example, we could have used a CurrentValue property rather than a GetValue (and SetValue) methods.

A property is primarily an Automation concept. In a COM interface, a property is implemented as one or two methods:

• A get_property-name method
• A put_property-name method

A property can be defined as read-only or write-only. In this case, there will be a single get_ or put_ method.

Defining an interface member as a property, rather than a method, can affect the syntax used by the client of your server. For example, Visual Basic uses a different syntax for getting or putting a property than for invoking a method. If the client language has a specific property syntax, it typically looks similar to setting a field in a record, rather than making a call.

To add a property to your interface:

1. Click (select) the interface in the hierarchy pane.
2. Click the New button. The New dialog appears. Do the following:
   • Select the Property type.
   • Type a name for the property. The completed screen appears as follows:
     
   • Click OK. The following screen appears:
     
3. In the New Property dialog box, define the attributes of the property. This includes:
   • Whether the property has both get_ and put_ methods.
   • The integer Automation identifier of this property.
   • The data type of this property.
4. Click OK.

One or two methods are added to your interface. Two methods are added if you select both the get_ and put_ methods. One method is added if it is read-only or write-only. The properties methods and the argument that identifies the property value are fully defined and do not need to be modified.

A property method typically only has the single argument that represents the property value. You can add additional arguments if it makes sense. For example, additional arguments might be added if the property is an array of values, where an integer index argument is added to the property method.

When adding additional arguments to a property method, make sure that they are added before the property value argument. That is, the property value argument must always be the last argument to the property method. You can use drag-and-drop in the hierarchy pane to change the order of arguments. The order in the method is always the order that appears in the hierarchy pane.

Working with the Hierarchy Pane

As you have seen in the AddingMachine example, the hierarchy pane represents the definition of your server; that is, the classes, interfaces, methods, and so on. The hierarchy pane's user interface supports the following functionality:

The hierarchy pane supports drag-and-drop to allow you to change the order of items. To move an item, click and drag the item and drop it on the item that you want to precede it in the hierarchy.

Description of Property Pages

Property pages appear in the right pane of the Fortran COM Server Wizard window. Different property pages apply to:

• Server Properties
• Class Properties
• Interface Properties
• Method Properties
• Argument Properties
• Instance Type Properties

Server Properties:

Class Properties:

Interface Properties:

Method Properties:

Argument Properties:

Instance Type Properties:

Modifying the Generated Code

After you either click the Save button to dismiss the Fortran COM Server Wizard or open the project workspace, the project is displayed, including the TODO.TXT file.

The TODO.TXT file informs you of changes made to your project by the Wizard, and lets you know when you need to make changes. After the initial invocation of the Wizard, TODO.TXT lists the files that were added to the project. The source files are added to two folders in your FileView pane:

• Source files that you will need to modify are placed in the Source Files folder.
• Files that are totally generated by the Wizard are placed in the Do Not Edit folder. It is futile to modify the files in the Do Not Edit folder, since these files are regenerated each time you invoke the Wizard and change the definition of the server (edits you make to these files will be lost).

Click:

1. The plus sign (+) at the Adder files line
2. The plus sign (+) at the Source Files folder

The project screen appears as follows:

The two files that you need to modify with a text editor are in the Source Files folder:

• UAddingMachineTY.f90 contains a module that defines your class derived-type.
• UIAdd.f90 contains the implementation of the IAdd methods.

We will first modify the file UAddingMachineTY.f90. To edit the file UAddingMachineTY.f90, either double-click its file name in the FileView pane or use the Open menu item in the File menu. The original file UAddingMachineTY.f90 contains the following code:

A file named Uclass-nameTY.f90 is created for each class defined by the server. The file contains a module named AddingMachine_USE (in the form classname_USE). There are three places in this module where you may need to add code specific to your class:

• The first entry in the module is your class derived-type. Initially it contains an "integer dummy" field to allow the module to be compiled without error. If your class has per-object data, remove the "integer dummy" field line and add your data to the derived-type. For the AddingMachine class, we add the following where the object stores the current value:

   real(4) CurrentValue
  

  The module also contains two module procedures by the names AddingMachine_CONSTRUCTOR and AddingMachine_DESTRUCTOR (referred to as classname_CONSTRUCTOR and classname_DESTRUCTOR below).
  
  
• The classname_CONSTRUCTOR procedure is called immediately after an instance of the class derived-type is created because of the creation of a new object. This function is where you initialize the fields of the class derived-type, if necessary. The new derived-type is passed as an argument to the function. For the AddingMachine class, we initialize the current value to 0 by adding the following statement:

    ObjectData%CurrentValue = 0
  

• The classname_DESTRUCTOR procedure is called immediately before an instance of the class derived-type is destroyed because an object is being destroyed. This function is where you release any resources used by the fields of the class derived-type, if necessary. The derived-type is passed as an argument to the function. For the AddingMachine class, there is nothing that needs to be added.

We will now modify the other source file UIAdd.f90. Either double-click its file name in the FileView pane or use the File menu, Open item. The original file UIAdd.f90 contains the following code:

A file by the name Uinterfacename.f90 (for example UIadd.f90) is created for each interface defined by the class. The file contains the methods of the class. Each method is named interfacename_methodname, for example: "IAdd_Clear". Each method is a function that is passed the class derived-type as the first argument. This gives the function access to the per-object data. Each function returns a 32-bit COM status code called an HRESULT. S_OK is a parameter that defines a success status. For additional information on COM status codes, see COM Status Codes: HRESULT.

You replace the "! TODO: Add implementation" line in each method with the code for the method. For the IAdd interface, below is the implementation of its three methods:

 IAdd_Clear:	ObjectData%CurrentValue = 0

 IAdd_Add:	ObjectData%CurrentValue = ObjectData%CurrentValue + Operand

 IAdd_GetValue:	CurrentValue = ObjectData%CurrentValue

Save the file and from the Build menu, click Build Adder.dll to build the server. The COM server is now complete.

Build Notes

The Developer Studio project created by the Fortran AppWizard performs two additional steps not done in a typical Fortran project:

• The build uses the MIDL compiler to compile the IDL file that describes the server. The MIDL compiler creates the server's Type library and generates C files that can be used in MIDL-based Marshalling (see Marshalling, Proxies and Stubs).

  The MIDL compiler uses the Visual C++ preprocessor by default during compilation. If the AppWizard determined that Visual C++ was not installed, it sets the MIDL options to use the Fortran preprocessor FPP instead. The options added are:

    /cpp_cmdfpp /cpp_opt  "/a /m/extend_source 132"
  

• A custom build step is added to register the COM server on your system. For a DLL COM server, registration is done using the REGSVR32 program. REGSVR32 could fail if the Window system directory is not on the Developer Studio's Executables Files list. On Windows NT and Windows 2000 systems, this is the \Winnt\System32 directory. On Windows 9x systems, this is typically the \Windows\System directory. If the registration step fails, do the following:
  
  
  1. In the Tools menu, click Options.
  2. Scroll to the Directories tab.
  3. Select the Executable files from the list.
  4. Add the windows system directory at the bottom of the list of directories.
  5. Click OK

For an EXE COM server, the COM server itself is run with the /REGSERVER command-line option.

Visual C++ ClassView

If you also have Microsoft Visual C++ Version 6 installed on your system, you will notice that your server definition also appears in the Visual C++ ClassView pane. This occurs because the Visual C++ ClassView software can read and understand the IDL file created by the Fortran COM Server wizard.

---

Note: Do not attempt to use the Visual C++ ClassView pane to modify the your server's definition. Always use the Fortran COM Server wizard to modify classes created by the Fortran COM Server wizard.

---

Using Example Clients

The server is now ready to be called by any COM client. The completed Adder sample is provided in the ...Df98\Samples\Advanced\COM\Adder directory. This directory also contains three clients written in Visual Fortran, Visual Basic, and Visual C++.

To build the sample clients, first build the Adder sample. The GUIDs used by the sample COM clients work with the Adder Sample (not the GUIDs created in the example).

If you followed the example COM server AddingMachine in earlier sections (starting with Creating a Fortran COM Server Project), the AddingMachine server that you created is identical to the Adder sample except for the GUID's assigned to the AddingMachine object. The Fortran COM Server AppWizard always generates new GUIDs for a new project.

Each client displays a dialog box that provides the user interface to the Adding Machine. Below are notes on each of the clients:

• VFAdder, the Visual Fortran client

  The VFAdder client is created using the Fortran Windows Application AppWizard. VFAdder is a simple Dialog Based Application. The main dialog box is defined to have Clear and Add buttons, an edit box to enter the addend, and a static text field that displays the current value:

  

  The Fortran Module Wizard creates the module (AddingMachine.f90) that defines the IAdd interface methods for use from Fortran. Code is added to the beginning of the WinMain routine to initialize COM and create an AddingMachine object:

    call COMINITIALIZE(ret)
    call COMCREATEOBJECTBYGUID (CLSID_AddingMachine, CLSCTX_ALL, IID_IAdd, &
    & gAddingMachine, status)
    call Check_Status(status,  " Unable to create AddingMachine object")
  

  The subroutine added as the handler of the Add button (VFAdderAdd) calls the $IAdd_Add routine and the $IAdd_GetValue routine:

  !  Call the AddingMachine Add method
      lret = DlgGet(dlg, IDC_EDIT_ADDEND, text)
      read(text, *) addend
      status = $IAdd_Add(gAddingMachine, addend)
     call Check_Status(status,  " Add method returned failure status")
  
  !  Set the Current Value text field
      status = $IAdd_GetValue(gAddingMachine, value)
      write(text, *) value
      call Check_Status(status,  " GetValue method returned failure status")
      lret = DlgSet(dlg, IDC_CURRENTVALUE, text)
  

  The subroutine added as the handler of the Clear button (VFAdderClear) calls the $IAdd_Clear routine in a similar way. Code is added at the end of the WinMain routine to uninitialize COM and release the AddingMachine object:

     if (gAddingMachine /= NULL) then
             ret = COMReleaseObject(gAddingMachine)
     endif
     call COMUNINITIALIZE()
  

• VBAdder, the Visual Basic V6 client

  VBAdder is created from a new Standard EXE project. The form is modified to be similar to the VFAdder dialog box above. The first step in using the AddingMachine object from Visual Basic is to select the References menu item from the Project menu. Find AddingMachine 1.0 Type Library in the list and select it. Visual Basic reads the information from the type library and becomes aware of the AddingMachine object, the IAdd interface, and its methods. These will appear in the choices that the Visual Basic editor makes available to you as you enter code for the project.

  The following code is added to the VBAdder project:

  • An instance of the AddingMachine object is created by adding the following line to the General Declarations area:

    Dim Adder As New AddingMachine

  • The code for the Add button Click method is:

     Private Sub Add_Click()
        Dim Value As Single
        Adder.Add (Addend.Text)
        CurrentValue.Caption = Adder.GetValue
        Addend.Text = ""
     End Sub
    

  • The code for the Clear button Click method is:

     Private Sub Clear_Click()
        Adder.Clear
        CurrentValue.Caption = Adder.GetValue
     End Sub
    

  • The code for the Exit button Click method is:

     Private Sub Exit_Click()
        End
     End Sub

• VCAdder, the Visual C++ V6 client

  VCAdder is created using the MFC AppWizard (exe). The Dialog based option is selected in the wizard. The dialog box controls are copied from the VFAdder dialog box and pasted into the VCAdder dialog box.

  The following statement is added to VCAdder.h in order to give the source files access to the AddingMachine object, the IAdd interface and its methods:

   #import "..\Adder.dll"

  A member variable is added to the CVCAdderApp application class to hold the pointer to the AddingMachine object:

   AddingMachineLib::IAddPtr m_pIAdd;

  Code is added to the beginning of the CVCAdderApp::InitInstance method to initialize COM and create an AddingMachine object:

      CoInitialize(NULL);
      m_pIAdd.CreateInstance(__uuidof(AddingMachineLib::AddingMachine));

  The MFC Class Wizard is used to add:

  • A member variable for the Addend edit field, m_Addend
  • A member variable for the CurrentValue static text field, m_CurrentValue
  • Member functions for the clicked message on the Add, Clear, and Exit buttons - OnAdd, OnClear, and OnExit

  OnAdd calls the Add method and the GetValue method.

   void CVCAdderDlg::OnAdd()
   {
      HRESULT hr;
      UpdateData();
      double addend = atof(m_Addend);
      hr = theApp.m_pIAdd->Add((float)addend);
      float value = theApp.m_pIAdd->GetValue();
      char buffer[32];
      sprintf(buffer, "%10.10G", value);
      m_CurrentValue = buffer;
      m_Addend = "";
      UpdateData(FALSE);
   }
  

  OnClear calls the Clear method and the GetValue method in a similar way.

  Code is added at the end of the CVCAdderApp::InitInstance method to release the AddingMachine object and uninitialize COM:

     m_pIAdd.Release();
      CoUninitialize();

For design considerations and notes on using Visual Basic and Visual C++ clients, see Visual Basic and Visual C++ Client Notes.

Modifying Your COM Servers

You can modify the server to change the properties of any entry in the hierarchy, add new entries to the hierarchy, move entries in the hierarchy, or remove entries from the hierarchy.

You use the same user interface of the Fortran COM Server Wizard that you used to create the COM server, simplifying any additions, deletions, or changes to your COM server definition. However, you need to pay careful attention to the following files when you modify the COM server definition:

• View the TODO.TXT file. The TODO.TXT serves as a log of the changes you have made to the server definition. You may delete entries from TODO.TXT that are no longer useful to you. TODO.TXT is simply a text file that the wizard appends messages to.
• New versions of the source files in the Source files folder generated by the Fortran COM Server Wizard do not overwrite existing source files, since you may have modified existing source files. New source files are in the form of the original file name with a plus sign (+) appended, such as UIADD+.f90. Use the text editor to copy-and-paste the newly generated definitions into your previously modified source code (described below), as instructed by text in the TODO.TXT file.

The Fortran COM Server Wizard regenerates the files in the Do Not Edit folder whenever the server definition changes.

To display the Fortran COM Server Wizard:

1. Start Developer Studio
2. Open a COM server project created by the Fortran COM Server AppWizard
3. Click the Fortran COM Server Wizard menu item in the View menu (see Using the Fortran COM Server Wizard to Define your COM Server)

Once you have published an interface and clients are using it, COM rules state that you must not change the interface. Instead, you should create a new interface, in addition to the original one, and change the name. A common practice is to append a 2 to the name, for the second version of the interface. For example, IAdd would become IAdd2. The second version of your class should support both the original and new interfaces. Old clients continue to work using the original interface. New clients can use the new interface with the new functionality.

The new interface has a different interface ID (IID) than the original interface. The text name is for the convenience of programmers. The IID uniquely identifies the interface.

The Fortran COM Server Wizard adds messages to TODO.TXT anytime the Wizard makes a change to the project and anytime that you make a change to the server definition that requires you to manually edit one or more of the source files. For example, if you add a new method to the IAdd interface, SetValue, that sets the current value to a specific number, the Wizard generates new code to implement the new method in your server. Some of the new code is in the files in the Do Not Edit folder. The Wizard automatically changes these files.

However, a new method skeleton needs to be added to the UIADD.f90 file in the Source Files folder. The wizard never creates a new file with the same name as a file in the Source Files folder, because that would cause the edits that you have made to the files to be lost. Instead, the wizard generates a file with a plus sign (+) appended to the end of the name, for example: UIADD+.f90. The file UIADD+.f90 contains the skeleton of the new method, IAdd_SetValue. In this case, the following message is added to TODO.TXT, and TODO.TXT is opened in the Developer Studio text editor:

The file UIAdd+.f90 has been generated with the following changes.
You must merge these changes with the existing file UIAdd.f90.
The method IAdd_SetValue has been added.

You must use a text editor to copy the new method skeleton from the UIADD+.f90 file and paste it into the UIADD.f90 file.

Whenever a change is made to your server definition, "+" versions of the files in the Source Files folder are generated. You can ignore these files except when TODO.TXT informs you of an action you need to take.

Other changes that would require you to manually merge changes into your source files include:

• Adding a new property.
• Changing the arguments of an existing method.
• Renaming a class, interface or method.
• Deleting a class, interface or method.