Chapter 4 . Developing a BEA TUXEDO Application on Windows NT

Introduction

This chapter provides instructions for the following:

• Using the BuildTuxedo tool, available with BEA TUXEDO on Windows NT, for developing a BEA TUXEDO application in the Microsoft Integrated Development Environment (IDE)
• Debugging a BEA TUXEDO server application in IDE
• Developing a BEA TUXEDO application without Visual C++

With Release 6.4, BEA TUXEDO integrates the software into the Microsoft Visual C++ (msdev) environment and emulates the functionality of msdev when integration is not possible. This new feature makes it easier for you to develop BEA TUXEDO enabled applications for 16- and 32-bit Windows operating systems. BuildTuxedo operates seamlessly on Windows 95 and all currently supported Windows NT environments (Intel and Alpha).

The coding required to create BEA TUXEDO service requests, send requests, set up conversational connections, and get replies is fundamentally the same in both UNIX and NT environments.

For More Information

Refer to the following books for information on the BEA TUXEDO ATMI.

• BEA TUXEDO Programmer's Guide
• BEA TUXEDO FML Programmer's Guide
• BEA TUXEDO COBOL Guide
• BEA TUXEDO Reference Manual (Sections 3c,3cbl, 3fml on TUXEDO ATMI)

New Development Tools

• BuildTuxedo is a single tool, tightly integrated with the msdev build environment, that developers can use instead of the buildserver, buildclient, and buildclt commands. (Of course, the commands are still available for those who prefer to use them.)
• TUXDEV creates, edits, and compiles multiple 16/32-bit FML tables and multiple 16/32-bit VIEW files. It also uses Multiple Document Interface (MFC) architecture so that you can use multiple views of these file types simultaneously.

Using the buildserver and buildclient Commands in an Integrated Development Environment

Although the buildserver and buildclient commands are available on the Windows NT platform, there are differences between how the options to these commands work on NT platforms and non-NT platforms. The following table lists these differences.

To modify the build environment in an integrated development environment: (a) select Settings from the msdev Build menu, and then (b) select either the C/C++ or Link tab.

Note: CC AND CFLAGS are no longer needed.

To specify the library and include paths in an integrated development environment, select Options from the msdev Tools menu. From the Options dialog box, select the Directories tab.

Adding BuildTuxedo to the MSDEV Tools Menu

1. From within Microsoft Visual C++ (msdev) graphical user interface (GUI), Select ToolsCustomizeTools. The Customize window is displayed.
2. Click New (broken box icon with twinkle) and type &BuildTuxedo in the blank box at the end of the Menu Contents box. (Placing an ampersand (&) before any letter enables it as the hot key.)
3. In the Command field, type the entire path name of BuildTuxedo (%TUXDIR%\bin\BuildTuxedo) or select ... to search for the name. Click Open to display the name in the Command field.
4. In the Initial Directory field, click and select Current Directory.

   Note: To modify an item, highlight it and type over it. To move any item, highlight it and select the up or down arrow at the top of the Menu Contents box.

5. Click Close.

   Figure 4-1 BEA TUXEDO for Windows NT Tools Menu

   

Creating BEA TUXEDO Project Files

BuildTuxedo maintains a separate project file in the current directory for each BEA TUXEDO application using it. When BuildTuxedo begins, it searches for a valid project file in the current directory. If one is found, the various dialog controls are set to the values stored in the file and the dialog is displayed. The title bar displays the following.

BuildTuxedo <project name>

Because your BuildTuxedo project is closely associated with the msdev project in the current directory, BuildTuxedo also searches for two other files:

• A valid msdev make file (filename.mak)
• An msdev project file (filename.mdp, filename.dsw, or fielname.dsp).

If BuildTuxedo cannot find one or both of these files, it displays a warning and/or fails to activate. If the directory contains multiple BuildTuxedo project files, multiple msdev project files or make files, menu items that contain appropriate target names are added to the System menu. To save the current project file, select OK or Apply. To cancel any changes that you made to the project file or any file that BEA TUXEDO maintains, select Cancel or press Esc.

Setting Up Your Environment

Before you can build your BEA TUXEDO application in an IDE, you must set the following fundamental parameters in your environment:

• A build type
• A header file
• The name of the C or C++ file to be created and maintained by BuildTuxedo
• Function names
• Service names

To provide this information, access the BuildTuxedo Project dialog box in the msdev GUI.

How to Specify the Build Type, Header File, and File Name

1. From the BuildTuxedo dialog box, select the Build page.

   Figure 4-2 BEA TUXEDO for Windows NT Build Page

   

2. In the Build Types field, select and choose one of the following.

   Select	Then
   Server	Enter information in the Initialization, Cleanup, and Entry Point fields. Then go to Step 3.
   Native Client or Workstation Client	Go to Step 3.

   Note: Windows 95 users can select Workstation Client type only.

   Note: The Initialization and Cleanup options allow you to override the default init/exit functions by specifying valid function names. The Entry Point option allows you to specify the name of the function that BuildTuxedo generates. You can then call this function from anywhere in the application.

3. In the Header File field, enter stdafx.h (the standard msdev//MFC precompiled header file.
4. In the File Name field, enter the name of the C or C++ file to be generated and maintained by BuildTuxedo.

How BuildTuxedo Uses the Header File

In the Header File, BuildTuxedo adds the necessary pragma statements to build the current BEA TUXEDO project correctly. BuildTuxedo opens the file specified by Header File if the file is present; otherwise, it creates one. A section titled: "//Begin TUXEDO Section*****DO NOT EDIT*****" and ending with "//End TUXEDO Section" designates the area in the header file that BuildTuxedo maintains and into which pragma statements are written. If BuildTuxedo searches for and does not find this section, it appends the section to the end of the header file. Because all other text within the file remains unchanged, you can specify stdafx.h as the header file.

Note: If this is a new project and you select OK or Apply, you must select Files into Project from the msdev Insert menu. You then add the file generated by BuildTuxedo to the current project. You need to do this only for a new project or when you change the name of the C/C++ output file.

Specifying Services

Two lists are used to maintain the service dispatch table. Function Names is a user-maintained list of functions that you can associate with a service. Service Names is a user-maintained list of the associated services. Generally, the service and the function that performs the service are represented by the same name: function x performs service x. In some cases, the function may have a different name from the service it performs. For example, in one case, function abc performs services, x, y, and z. In another case, the service name is not known until runtime.

Figure 4-3 BEA TUXEDO for Windows NT Services Menu

You must specify any function associated with a service when you build the server. For any function associated with a service, you must specify the service, the appropriate prototype, a C linkage, a void return, and take a single TPSVCINFO pointer parameter. To specify a function to which a service name can be mapped, you must add the function to the Function Name list. This information is required for the service dispatch table. (If you are using the buildserver command, you can provide this information with the -s option. Refer to the BEA TUXEDO Programmer's Guide for details.)

How to Add or Edit Names on the Function Names List

1. In the Services folder, choose one of the following actions.

   To	Action
   Add an item	Click New (broken box with twinkle in the upper left corner), press Insert, or select a blank area on the list, (i.e., a dotted lined box). Type the name of the new function.
   Modify an existing name	Highlight the name and type your changes over the entry.
   Delete a name	Highlight the name on the list and click X (X icon) or press Delete.

2. When complete, press Enter to save your changes and exit. (To exit without saving your changes, press Esc or Tab.)

   Note: To scroll up and down the list, use the arrow keys.

How to Specify a Resource Manager

1. Select the Resources page from the BuildTuxedo menu.
2. In the Tuxedo Resource Manager field, type the entire pathname of the resource manager for your application.

   Note: The Tuxedo Resource Manager field contains a list of BEA TUXEDO resource managers available on the system as defined in the %TUXDIR%\udataobj\RM file. If the file is not present, a default (NONE) is displayed.

   Figure 4-4 BEA TUXEDO for Windows NT Resources Page

   

How to Debug a BEA TUXEDO Server Application

To debug a server that has not been booted, complete the following procedure. Use this procedure only if you have built the server application using the Debug configuration for your project.

1. At any Windows NT Command prompt, type tmboot -n -d 1 -s <servername> to display the command line options tmboot uses to start <servername>.
2. Run tmboot -M to boot the BBL. (If necessary, boot any additional application servers or machines as needed.
3. Select ProjectSettings in msdev.
4. In the Program Arguments field, select Debug and type the command line options used in Step 1.
5. Start the debugger and proceed as needed to debug the server application.

   Note: Because BEA TUXEDO libraries are not built with debugging information and source code is not provided, you will not be able to access the BEA TUXEDO code directly.

6. To end the debugging session, type tmshutdown at a Windows NT prompt.

   Warning: Do not select DebugStop to stop the server as BEA TUXEDO may attempt to restart it.

   Note: To debug a server that is already running, type msdev -p nnn at a Windows NT Command prompt, replacing nnn with the server's process ID (represented by a decimal number).

Developing a BEA TUXEDO Application Without Visual C++

If you need to develop a BEA TUXEDO application without Visual C++, use the buildserver and buildclient commands. To do this, specify the compiler and link options necessary to build a BEA TUXEDO application. Refer to Section 5 of the BEA TUXEDO Reference Manual Section, BEA TUXEDO Application Development Guide, and BEA TUXEDO Programmer's Guide for information on using these tools.

To build a debug version of your application using buildserver or buildclient, you must compile all source files with the /Zi and /Od options. The /Zi option enables debugging; the /Od option disables optimization. You may also need to define the _DEBUG preprocessor directive. To complete the process, indicate the link option as follows:

-l"/link/debug:full/debugtype:both"

The New Tuxdev Application

Installing Tuxdev

1. In the Microsoft Visual C++ (msdev) environment, select ToolsCustomizeTools Add.
2. In the Add Tool dialog box, type the entire path name in the Command field (TuxDev.exe is located in %TUXDIR%\bin), or select Browse to search for the name. Click OK to display the pathname in the Customize window.
3. To change the item displayed on the Tools menu, change the entry in the Menu Text field.
4. To create a hot key for a tool, position an ampersand (&) before any letter in the tool name.(now you can bring up the tool at any time by typing that letter.
5. In the Initial Directory field, click and select Current Directory to display its name ($CurDir).

BEA TUXEDO Editors

Two editors are available in this new environment: the FML Table editor and the View editor. The user interface for both editors is similar to a workbook in which you can work on multiple documents/views simultaneously. You can also edit multiple files of various types at the same time. Both editors closely resemble a Microsoft Excel spreadsheet with all of its associated functionality:

• The FML Table editor enables developers to create and/or edit an FML field table easily, and to generate user selectable 16-bit or 32-bit field header files.
• The View editor enables developers to create and/or edit a View file easily, and to generate user selectable 16-bit or 32-bit VIEWS and header files.

  Figure 4-5 New Editors

  

Using the FML Table Editor

Accessing the FML Table Editor

1. On the Command line, type the entire pathname of the Tuxdev (%TUXDIR%\bin). Type tuxdev and press Enter.
2. Choose one of the following actions.

   To	Action
   Create a file	From the BEA TUXEDO Developer's window, select File New. Go to Step 3.
   Modify an existing file	From the BEA TUXEDO Developer's window, select File Open. Select the file (fml files have a .fml extension) to edit.

3. On the New window, highlight FML Table and type in the name of the new file in the File Name field. Select OK.

   Figure 4-6 The FML Table Editor

   

Description of the FML Table Editor

The FML Table Editor illustrated in Figure 4-6 contains five columns: Name, Relative Number, Type, Flag and Comment, with an unlimited number of rows.The following chart outlines the purpose of each column in the editor.

You can open new (unnamed) FML tables in which a blank grid is created for the table named "FML Tablex", where x is a value tracked by Multiple Document Interface (MFC) and incremented by one each time a new table is created. You can specify a name if and when the table is saved. You can also open an existing text file for editing. Unless otherwise specified, files are saved in the directory in which the file was opened in tabbed delimited format, with .FML appended to the end of the filename when applicable. You can compile this file to produce either a 16- or 32-bit FML header file.

Using the View Editor

Accessing the View Editor

1. On the Command line, type the entire pathname of Tuxdev (%TUXDIR%\bin). Type tuxdev and press Enter.
2. Choose one of the following actions.

   To	Action
   Create a file	From the BEA TUXEDO Developer's window, select File New. Go to Step 3.
   Modify an existing file	From the BEA TUXEDO Developer's window, select File Open. Select the file (view files have a .vv extension) to edit.

3. On the New window, highlight View Table and type in the name of the new file in the File Name field. Select OK.

   Figure 4-7 The View Editor

   

Description of the View Editor

The View Editor illustrated in Figure 4-7 contains seven columns: CName, FBName, Type, Count, Flag, Size, and Null, with an unlimited number of rows.

You can enter comments in the CName column provided each begins with the required pound sign (#). Blank lines are also allowed. When a CName entry is not preceded by a pound sign and is not NULL, the line is assumed to be an active table entry.

Note: You must type VIEW <table name> in a row by itself in the CName column before the view information, and type END in a row by itself in the CName column to end the view information. You can enter multiple views within the same file provided that each table entry is preceded by VIEW <table name> and followed by END

You can open new (unnamed) view files in which a blank grid is created for the view, Viewx, where x is a value tracked by MFC and incremented by one each time you create a new view. You can specify a name if and when you save the view file. You can also edit an existing view file (either text or binary). Unless otherwise specified, files are saved in the directory where the file was opened in tabbed delimited format, with.v appended to the end of the filename when applicable. You can compile this file to produce either a 16- or 32-bit binary VIEW and header files.

Working in Multiple Documents Simultaneously

The Multiple Document Interface (MFC), as part of the basic framework, provides a multiple document architecture in which you can open documents and views, regardless of type, at the same time. Examples of this design are msdev, Excel and Word. In BEA TUXEDO terms, you can open x number of FML tables and y number of View files at any time, and then select to use any one of them. Documents look and feel like a workbook that contains tabs for each open document.

How the Editors Validate Entries

The following tables describe what information is validated in each column of the FML table and View editors.

The FML Table Editor

The View Editor