Using the Visual C++.Net IDE To Develop Oracle Tuxedo ATMI Applications

The following sections describe how to develop ATMI application clients and/or servers in the Microsoft Visual C++ Integrated Development Environment (msdev) on a Windows XP, or Windows Server 2003 system:

•	Before You Start

•	Using Development Tools

•	Using the buildserver and buildclient Commands

•	Adding BuildTuxedo to the MSDEV Tools Menu

•	Creating Oracle Tuxedo ATMI Project Files

•	Setting Up Your Environment

•	Debugging an Oracle Tuxedo ATMI Server Application

•	Developing an ATMI Application Using the Command Line Instead of the Visual C++.Net IDE GUI

•	Using the Tuxdev Application

•	Using the Oracle Tuxedo ATMI Editors

Before You Start

Because Oracle Tuxedo ATMI client but not server components can be installed on Windows XP, you can use the Microsoft Visual C++ IDE on these platforms to develop only ATMI application clients. In contrast, because both Oracle Tuxedo ATMI client and server components can be installed on Windows Server 2003, you can use the Microsoft Visual C++.Net IDE on the Windows Server 2003 platform to develop both ATMI application clients and servers.

Using Development Tools

Oracle Tuxedo ATMI integrates into the Microsoft Visual C++.Net IDE (msdev) and emulates the functionality of msdev when integration is not possible. This integration makes it easier for you to develop Oracle Tuxedo ATMI applications for 16-bit and 32-bit Windows operating systems.

The coding required to create Oracle Tuxedo ATMI service requests, send requests, set up conversational connections, and get replies is fundamentally the same in both UNIX and Windows Server 2003 environments. BuildTuxedo and TUXDEV are tools that help you in your development environment.

•

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, these commands are still available for those who prefer to use them.) The BuildTuxedo system operates seamlessly on all currently supported Windows environments.

•	TUXDEV allows you to create, edit, and compile multiple 16/32-bit FML tables and multiple 16/32-bit VIEW files. It also uses Multiple Document Interface (MDI) architecture so that you can use multiple views of these file types simultaneously.

Using the buildserver and buildclient Commands

Both the buildclient() and buildserver() commands are available to Windows Server 2003 but not to Windows XP. Only the buildclient() command is available to Windows XP, meaning that only Tuxedo application clients can be built on a Windows XP system. For more information about the build commands, see buildclient(1)and buildserver(1)in Oracle Tuxedo Command Reference.

There are differences between how the options to the buildclient() and buildserver() commands work on non-integrated development environments and on integrated development environments, as indicated in the following table.

 

Table 3‑1 Using the buildserver and buildclient Commands 

To . . .	In a Non-Integrated Development Environment, Use This Option . . .	In an Integrated Development Environment . . .
Turn on verbose mode	-v	All options are displayed on tabs by default. (The -v option is unnecessary and unsupported.)
Specify an output file	-o (output_filename)	1. Select Settings from the msdev Build menu. 2. Select the Link tab in the Project Settings dialog box. 3. Specify the name of your output file by using the edit control.
Specify the first file to be linked	-f	1. Select Settings from the msdev Build menu. 2. Select the Link tab in the Project Settings dialog box. 3. Specify the first file to be linked by using the edit control.
Specify the last file to be linked	-l	1. Select Project from the msdev menu. 2. Select the Link tab in the Project Settings dialog box. 3. Specify the last file to be linked by using the edit control.
Specify a resource manager	-r	1. Access the BuildTuxedo GUI. 2. Access the BuildTuxedo Test window and select the Resources tab. 3. In the Tuxedo Resource Manager field, enter the name of the resource manager.
Specify services that will be available on a server	-s	1. Access the BuildTuxedo GUI. 2. Access the BuildTuxedo Test window and select the Services tab. 3. In the Service Names field, enter the name of each service on a separate line.
Use the COBOL compiler	-c	COBOL is unavailable.

To modify the build environment in an integrated development environment, follow these steps:

1.	Choose Settings from the msdev Project menu.

2.	Select 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, follow these steps:

1.	From the MSDEV Tools menu, choose Options to display the Options dialog box.

2.	In the Options dialog box, select the Directories tab.

Adding BuildTuxedo to the MSDEV Tools Menu

To add BuildTuxedo to the MSDEV Tools menu, follow these steps:

1.	In the Microsoft Visual C++.Net IDE (msdev) graphical user interface (GUI), choose Tools → External Tools. The External Tools window displays.

2.	In the External Tools window, click Add to clear the Title field.

Figure 3‑1 External Tools Window

3.	In the Title field of the External Tools page, type &BuildTuxedo in the empty field.

Note:

To enable a letter key as a hot key, put an ampersand (&) before the appropriate letter.

4.	In the Command field of the External Tools page, provide a pathname by doing one of the following:

•	Type the full pathname of BuildTuxedo (%TUXDIR%\bin\BuildTuxedo).

•	To the right of the Command field, click the ellipsis button , browse to the desired directory, select buildtuxedo.exe, and click Open. The selected pathname appears in the External Tools window.

5.	In the Initial directory field of the External Tools page, click the right arrow button to display a pop-up menu. In the pop-up menu, choose Project Directory ($(ProjectDir)).

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.

6.	Click Apply to save the changes and click OK to close the External Tools window.

BuildTuxedo is now part of the MSDEV Tools menu.

Creating Oracle Tuxedo ATMI Project Files

BuildTuxedo maintains a separate project file in the current directory for each Oracle Tuxedo ATMI 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 information:

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 makefile (filename.mak)

•	An msdev project file (filename.mdp, filename.dsw, or filename.dsp)

If BuildTuxedo cannot find either of these files, it displays a warning and/or fails to activate. If the directory contains multiple BuildTuxedo project files, or 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 make to the project file or any file maintained by the Oracle Tuxedo system, click Cancel or Esc.

Setting Up Your Environment

Before you can build your Oracle Tuxedo ATMI application in an IDE, you must set the following fundamental parameters in your environment:

•	Build type

•	Header file

•	Filename 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_name dialog box in the msdev GUI.

Specifying the Build Type, Header File, and Filename

To specify the build type, header file, and filename, follow these steps:

1.	In the project_name dialog box, click the Build tab to display the Build page.

Figure 3‑2 Build Page

2.	In the Build Types field of the Build page, click the down arrow and choose one of the following:

•

Server

•	Native client or Workstation client

Note:

Windows XP users can select only Workstation Client type.

 

If You Select . . .	Then, After Making Your Selection . . .
Server	Enter information in the Initialization, Cleanup, and Entry Point fields. Proceed to step 3.
Native Client or Workstation Client	Proceed to step 3.

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 generated by BuildTuxedo. After specifying its name, you can call the function from anywhere in the application.

3.	In the Header File field of the Build page, enter stdafx.h.

4.	In the File Name field of the Build page, 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 Oracle Tuxedo ATMI project correctly. BuildTuxedo opens the file specified in the Header File field of the Build page, if the file is present; otherwise, it creates a new one. A section starting with:

//Begin Tuxedo Section*****DO NOT EDIT*****

and ending with:

//End Tuxedo Section

designates the area in the header file in which pragma statements are written. This area is maintained by BuildTuxedo. If BuildTuxedo does not locate this section in the file, it appends it 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 your project is new, 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 Function and Service Names

Select the Services tab to display the Services page, in which you specify function and service names.

Figure 3‑3 Services Page

In the Services page, 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.

Note:

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

Generally, the service and the function that performs the service are represented by the same name. For example, 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 may not be known until run time.

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 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.

Note:

If you are using the buildserver(1)command, you can provide this information with the -s option. For more information about the -s option, see Programming an Oracle Tuxedo ATMI Application Using C or Programming an Oracle Tuxedo ATMI Application Using COBOL.

To add or edit names on the Function Names list, follow these steps:

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

 

To	Action
Add an item	1. Click the New icon (broken box with twinkle in the upper left corner). 2. Click Insert, or select a blank area on the list (that is, a dotted lined box). 3. Type the name of the new function.
Modify an existing name	Highlight the name and type over it.
Delete a name	Highlight the name on the list and click the X icon or click Delete.

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

Specifying a Resource Manager

To specify a resource manager, follow these steps:

1.	Select the Resources tab in the BuildTuxedo window to display the Resources page.

Figure 3‑4 Resources Page

\

2.	In the Tuxedo Resource Manager field of the Resources page, type the full pathname of the resource manager for your application.

Note:

The Tuxedo Resource Manager field contains a list of Oracle 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.

Debugging an Oracle Tuxedo ATMI Server Application

You should use the following procedure only if you have built the ATMI server application using the Debug configuration for your project.

To debug a server that has not been booted, follow these steps.

1.	At any Windows command prompt, type tmboot -n -d 1 -s servername to display the command-line options used by tmboot(1)to start servername.

2.	Execute the tmboot -M command to boot the BBL. (If necessary, boot additional application servers or machines.)

3.	In msdev, select Project → Settings.

4.	In the Program Arguments field of the Debug page, type the command-line options used in step 1.

5.	Start the debugger and start debugging the server application.

Note:

Because Oracle Tuxedo libraries are not built with debugging information and source code is not provided, you cannot access the Oracle Tuxedo code directly.

6.	To end the debugging session, type tmshutdown at any Windows command prompt.

WARNING:

Do not stop the server by selecting Debug → Stop; the Oracle Tuxedo system may subsequently attempt to restart the server.

Note:

To debug a server that is already running, type msdev -p nnn at any Windows command prompt, replacing nnn with the server’s process ID (represented by a decimal number).

Developing an ATMI Application Using the Command Line Instead of the Visual C++.Net IDE GUI

If you must develop an Oracle Tuxedo ATMI application using the command line instead of the Microsoft Visual C++ IDE GUI, use the buildserver(1)and buildclient(1)commands. To do this, specify the compiler and link options necessary to build an Oracle Tuxedo ATMI application. For information about using these tools, see the following documents:

•	Oracle Tuxedo Command Reference

•	Tutorials for Developing Oracle Tuxedo ATMI Applications

•	One of the following language-specific guides:

•	Programming an Oracle Tuxedo ATMI Application Using C

•	Programming an Oracle Tuxedo ATMI Application Using COBOL

To build a debug version of your ATMI 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. In addition, you may need to define the _DEBUG preprocessor directive. To complete the process, indicate the link option as follows:

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

Using the Tuxdev Application

To install the Tuxdev application, follow these steps:

1.	In the Microsoft Visual C++.Net IDE (msdev) graphical user interface (GUI), choose Tools → External Tools. The External Tools window displays.

2.	In the External Tools window, click Add to clear the Title field.

3.	In the Title field of the External Tools page, type &Tuxdev in the empty field.

Note:

To enable a letter key as a hot key, put an ampersand (&) before the appropriate letter.

4.	In the Command field of the External Tools page, provide a pathname by doing one of the following:

•	Type the full pathname of BuildTuxedo (%TUXDIR%\bin\tuxdev.exe).

•	To the right of the Command field, click the ellipsis button , browse to the desired directory, select tuxdev.exe, and click Open. The selected pathname appears in the External Tools window.

5.	To change the item displayed on the External Tools menu, change the entry in the Menu Contents field.

Note:

To create a hot key for a tool, put an ampersand (&) before any letter in the tool name. This enables you to invoke the tool at any time simply by typing that letter.

6.	In the Initial directory field of the External Tools page, click the right arrow button to display a pop-up menu. In the pop-up menu, choose Project Directory ($(ProjectDir)).

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.

7.	Click Apply to save the changes and click OK to close the External Tools window.

Tuxdev is now part of the MSDEV Tools menu.

Using the Oracle Tuxedo ATMI Editors

Two editors are available in this environment: the FML Table Editor and the VIEW Table Editor. The user interface for both editors is similar to a workbook in which you can work on multiple views (that is, documents) simultaneously. You can also edit multiple files of various types at the same time. Both editors are similar to a Microsoft Excel spreadsheet:

•	FML Table Editor enables you to create and/or edit an FML field table easily, and to generate user-selectable 16- or 32-bit field header files.

•	VIEW Table Editor enables you to create and/or edit a VIEW Table file easily, and to generate user-selectable 16- or 32-bit VIEWS and header files.

Using the FML Table Editor

To invoke the FML Table Editor, follow these steps:

1.	On the Windows command line, type the full pathname of tuxdev (%TUXDIR%\bin) and press Enter.

2.	Type tuxdev and press Enter to display the Oracle Tuxedo Developer window.

3.	Choose one of the actions described in the following table.

 

To . . .	Complete These Steps . . .
Create a file	1. In the Oracle Tuxedo Developer window, choose File→New. The New window appears, as shown in the figure titled “New Window” on page 3‑15. 2. Proceed to step 4.
Modify an existing file	1. In the Oracle Tuxedo Developer window, choose File→Open. 2. Select the file (FML filenames include a .fml extension) to edit. 3. Skip the remaining steps.

Figure 3‑5 New Window

4.	In the New window, select FML Table and type the name of the new file in the File Name field.

5.	Click OK to invoke the FML Table Editor.

Figure 3‑6 FML Table Editor

As shown in the preceding figure, the FML Table Editor contains five columns—Name, Number, Type, Flag, and Comment—and an unlimited number of rows.

Table 3‑2 describes the purpose of each column in the FML Table Editor.

 

Table 3‑2 FML Table Editor Column Description

This Column . . .	Enables You to . . .
Name	Enter comment and/or base numbers. Each comment or number must be preceded by a pound sign (#) or an asterisk (*); otherwise, the line is assumed to be an active table entry. Data entered in an empty cell is assumed to be a new entry. (Blank lines are allowed.)
Number	Specify the relative number of the field.
Type	Select from a list of all valid values for this field.
Flag	Select flag settings (when the column is active).
Comment	Expand or clarify any entry designated in the Name column.

You can open new (unnamed) FML tables. A blank grid is created for the table named FML Tablex, where x is a value tracked by the MDI 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-bit or 32-bit FML header file.

Using the VIEW Table Editor

To invoke the VIEW Table Editor, follow these steps:

1.	On the Windows command line, type the full pathname of tuxdev (%TUXDIR%\bin) and press Enter.

2.	Type tuxdev and press Enter to display the Oracle Tuxedo Developer window.

3.	Choose one of the actions described in the following table.

 

Table 3‑3 Using the View Table Editor Actions

To . . .	Complete These Steps . . .
Create a file	1. In the Oracle Tuxedo Developer window select File→New to display the New window, as shown in the figure titled “New Window” on page 3‑15. 2. Proceed to step 4.
Modify an existing file	1. In the Oracle Tuxedo Developer window, choose File→Open. 2. Select the file (FML filenames include a .fml extension) to edit. 3. Skip the remaining steps.

 

4.	In the New window, select VIEW Table and type the name of the new file in the File Name field.

5.	Click OK to invoke the VIEW Table Editor.

Figure 3‑7 VIEW Table Editor

As shown in the preceding figure, the VIEW Table Editor contains seven columns— CName, FBName, Type, Count, Flag, Size, and Null—and an unlimited number of rows.

You can enter comments in the CName column, as long as the required pound sign (#) is shown at the beginning of each comment. 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.

Table 3‑4 describes the purpose of each column in the VIEW Table Editor.

 

Table 3‑4 VIEW Table Editor Column Description

This Column . . .	Enables You to . . .
CName	Enter comment and/or base numbers. Each comment or number must be preceded by a pound sign (#) or an asterisk (*); otherwise, the line is assumed to be an active table entry. (Blank lines are allowed.)
FBName	Specify the [field in the] fielded buffer; this name is displayed in the field table file.
Type	Select from a list of all valid values for this field.
Count	Specify the number of elements to allocate (that is, the maximum number of occurrences to be stored for this member).
Flag	Select flag settings (when the column is active).
Size	Indicate the size of the member if the type is string, carray, or dec_t. Otherwise, you can specify ‘-’, and the view compiler computes the size.
Null	Specify a null value or ‘-’ (default null value) for that field.

Note:

You must specify the following information to denote the start and end of the view information:

VIEW table_name
.
.
.
END

The information must appear in the CName column in a row by itself. 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 the MDI 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 in which the file was opened in tabbed delimited format, with .v appended to the filename when applicable. You can compile this file to produce either 16- or 32-bit binary VIEW and header files.

Working in Multiple Documents Simultaneously

The MDI, 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 Oracle Tuxedo terms, you can open x number of FML tables and y number of VIEW Table files at any time, and then use any one of them. Each document looks and feels like a workbook that contains tabs for each open document.

How the Editors Validate Entries

Table 3‑5 describes the information that is validated in each column of the FML Table Editor.

 

Table 3‑5 Information Validated in the FML Table Editor

In This Column . . .	This Information Is Validated . . .
Name	Comments, base numbers, and valid text strings
Number	Numbers only. (The range is determined by a 16/32-bit user mode.)
Type	Valid FML types.
Flag	Valid FML flags. Extra checking is done for mutually exclusive flags.
Comment	Entries are not validated.

Table 3‑6 describes the information that is validated in each column of the VIEW Table Editor.

 

Table 3‑6 Information Validated in the VIEW Table Editor

In This Column . . .	This Information Is Validated . . .
CName	Entries are not validated.
FBName	Entries are not validated.
Type	Valid Oracle Tuxedo types.
Count	Numbers only. (The range is determined by a 16/32-bit user mode.)
Flag	Valid FML flags. Extra checking is done for mutually exclusive flags.
Size	Numbers only. (The range is determined by a 16/32-bit user mode.)
Null	Entries are not validated.

See Also

For information about the Oracle Tuxedo ATMI, see the following documents:

•	Programming an Oracle Tuxedo ATMI Application Using C

•	Programming an Oracle Tuxedo ATMI Application Using COBOL

•	Programming an Oracle Tuxedo ATMI Application Using FML

•	Oracle Tuxedo Command Reference

•	Oracle Tuxedo ATMI C Function Reference

•	Oracle Tuxedo ATMI COBOL Function Reference

•	Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference