DataBlade Developers Kit User's Guide Creating DataBlade Objects Using BladeSmith

When you generate files, BladeSmith creates files that describe the objects you defined in your project. The files include:

• SQL scripts that BladeManager executes to register the DataBlade module in databases and SQL scripts that create the DataBlade module objects in user databases.
• source files that contain basic code for the routines defined in your project.
• unit and functional test files.
• setup files that you use with BladePack to create an installation package.

Generate SQL files, source files, functional test files, and installation files at any time. See Regenerating Files for more information on when to regenerate. If you change any of the output directories, regenerate all files.

To generate files or change the properties of generated files, choose Generate DataBlade to display the Generate DataBlade dialog box, as shown in Figure 4-2.

Figure 4-2 Generate DataBlade Dialog Box

The Generate DataBlade dialog box contains a file tree that shows categories of generated files. Each category is represented by a node in the tree. When you click a node, the Generate button changes to reflect the name of the category.

The directory structure of the generated files is illustrated by Figure 4-3.

Figure 4-3 Generated File Directory Structure

Programming language subdirectories are created during generation only if you have defined objects in those languages.

This section includes the following subsections that describe the tasks you can perform using the Generate DataBlade dialog box:

• Setting Generated File Properties
• Generating All Files
• Generating SQL Scripts
• Generating Source Files
• Generating Test Files
• Generating Installation Package Files
• Regenerating Files
• Opening the Project File in Visual C++

Most categories of generated files have properties that you can change. The properties appear in the Generate DataBlade dialog box Properties grid when you select a category in the file tree.

The following table lists the properties of the generated file categories, their default values, categories to which they belong, and a brief description of each.

1. Click the node of the category whose properties you want to change.
2. Click the name of the property whose value you want to edit in the Property column of the Properties grid.
3. Edit the value by typing a new value or selecting a new value from the popup list in the Value column.
4. Click Apply.

The top-level node in the Generate DataBlade dialog box file tree is Generate DataBlade (see Figure 4-2 on page 4-66).

1. In the Generate DataBlade dialog box, click the Generate DataBlade node.
2. Edit the properties of the generated file categories, if necessary. See Setting Generated File Properties for instructions.
3. Click Generate DataBlade.

The Generate DataBlade node has the following properties:

• Format. Use the Format property to specify how text lines end in the generated files:
• DOS. Text lines end with a carriage return/linefeed pair.
• UNIX. Text lines end with a linefeed character.
• Merge. The default value is True. To merge custom changes from previous source code and unit test files into the new files, select True. To overwrite existing files, select False. See Merging Changes in Source Code and Unit Test Files for more information.

The default value for the Format property is DOS.

To generate only the SQL scripts, click the SQL node in the Generate DataBlade dialog box; then click Generate Scripts.

The property associated with the SQL node is Directory. The default directory is scripts. You can change the name of the directory the SQL scripts are saved in, but the path must be relative to the project directory.

The following table describes the generated SQL scripts.

BladeSmith generates separate files for locale-specific objects such as error messages. For example, the files for the default U.S. English locale are prepare.en_us.sql and errors.en_us.1252. Only one error message file is necessary per language. The database server automatically translates between languages. For example, the errors.en_us.1252 file is sufficient for all en_us encodings; you do not need additional encodings like error.en_us.8859-1.

You can add SQL statements to the generated SQL scripts by adding an SQL file object to your project. See Adding SQL Files for more information about adding SQL statements to a DataBlade module.

Warning: Do not edit generated SQL scripts. Use BladeSmith to make changes; then regenerate the scripts.

Generating Source Files

To generate only the source files for objects defined in your project, click the Source node or one of its subordinate nodes in the Generate DataBlade dialog box (see Figure 4-2 on page 4-66); then click Generate Source. The following table lists the source code file generation options.

The Source node has these properties:

• Directory. The default directory is src. To change the name of the top-level directory the source code files are saved in, specify a new directory or path. The path must be relative to the project directory.
• Logging. The default value is False. To add logging information to your source code files, select True.
• Tracing. The default value is False. To add tracing to your generated source code, select True. See Tracing and Error Handling for more information.

The property associated with the C node under the Server node is MMX. The MMX default value is False. You can choose whether to allow Intel MMX media enhancement technology in your DataBlade module. To generate the Gen_IsMMXMachine function to check for an Intel MMX processor, specify True. See The Gen_IsMMXMachine() Utility Function for more information.

BladeSmith writes a header file, source files, and makefiles for Windows NT and UNIX platforms. It also generates other necessary files, depending on the coding language. For information on the source files BladeSmith generates, see Source Files Generated by BladeSmith and Appendix A, Source Files Generated for DataBlade Modules.

After you generate source files, edit the source files to add your code to the routine declarations BladeSmith generated. For a description of the contents of the generated files and how to modify and compile the generated code, see Chapter 5, Programming DataBlade Module Routines in C, Chapter 6, Creating ActiveX Value Objects, or Chapter 8, Programming DataBlade Modules in Java.

To generate only the test files, click the Tests node in the Generate DataBlade dialog box (see Figure 4-2 on page 4-66); then click Generate Tests. You can also choose to generate only functional tests or only unit tests.

The property associated with the Tests node is Directory. The default directory is functest. You can change the name of the directory the test files are saved in, but the path must be relative to the project directory. The functest directory only applies to functional tests; unit tests are generated in the src directory.

See Chapter 9, Debugging and Testing DataBlade Modules on UNIX, for information about executing functional tests.

To generate only the installation packaging files that BladePack uses to build installation packages, click the Packaging node in the Generate DataBlade dialog box (see Figure 4-2 on page 4-66); then click Generate Packaging.

The property associated with the Packaging node is Directory. The default directory is install. You can change the name of the directory where the installation files are saved, but the path must be relative to the project directory.

When you generate installation package files, BladeSmith creates a set of files that you use with BladePack to generate installation scripts for your DataBlade module:

• project.bom. A bill of materials file.
• project.cmp. A components file.
• project.prd. A product file.
• project.str. A string file.

Important: Do not edit the generated installation package files. Instead, use BladeSmith to regenerate the installation package files after you have added or removed DataBlade module objects in the project file. For details about adding files to your installation package and generating installation packages, see Chapter 11, Using BladePack.

After you make changes in a BladeSmith project, regenerate the appropriate files. For example, if you add a cast to a DataBlade module, you must regenerate SQL scripts. If the cast has a support routine, you must also regenerate source files. When a node in the generated file category tree on the Generate DataBlade dialog box needs to be generated, it is followed by an asterisk.

BladeSmith uses two processes to regenerate files, depending on the file:

• Source code and unit test files. If merging is enabled, BladeSmith merges user changes into the newly generated code.
• Visual C++ project, SQL, functional test, and installation files. BladeSmith replaces existing files.

When BladeSmith finds existing source code and unit test files, it copies them to backup files before regenerating them.

If you add SQL statements to unit test files and then regenerate them, BladeSmith merges your code automatically.

If the Merge property of the DataBlade node in the Generate DataBlade dialog box is True, BladeSmith copies the changes you made to your source and unit test files into the newly generated source files. In this way, you can update your objects in BladeSmith without losing the code you added.

In source code files, BladeSmith does not remove code for routines that no longer exist in the project; you must manually remove such code. For example, suppose you create an opaque data type with an Assign() function specified and generate code; then you alter the opaque data type to no longer have an Assign() function. When you regenerate the source code, the Assign() function code remains.

If the Merge property of the DataBlade node in the Generate DataBlade dialog box is False, BladeSmith does not merge your previous changes into the new source files, but existing files are backed up. You can copy changes from the backup files into the newly generated files using a text editor.

If BladeSmith encounters problems while generating files, it displays the Generate Code Problem dialog box. For help in resolving merging problems, click Help on this dialog box and read the on-line help.

For information on how to use merging to upgrade projects created with a previous version of the DataBlade Developers Kit, see the release notes.

BladeSmith does not merge changes to Visual C++ project, SQL files, functional test files, or installation files. When you regenerate SQL files and functional test files, BladeSmith regenerates the previous files as well as the Visual C++ project file. When you regenerate installation files, BladeSmith deletes relevant entries in the bill of materials file and adds them again. If you use BladePack to add files to the package, regenerating installation files does not affect your additions.

After you generate your C or C++ source code, you can launch Microsoft Visual C++ and open the project workspace file for your DataBlade module by clicking MSDev on the Generate DataBlade dialog box.

You can also open the DataBlade module project in Visual C++ from BladeSmith at any time by choosing Tools MSDev or clicking the MSDev button in the toolbar.

1. With the project open in BladeSmith, choose Tools MSDev.

If the DBDK Visual C++ Add-In toolbar does not appear, you must add it manually. For instructions, see Manually Loading the Add-In.

A dialog box asks if you want to select a local database server.

2. Click Yes.

The add-in Properties dialog box appears. See Specifying Properties for a Project for more instructions on assigning a database server and database to your project.