Chapter 42. Building Application Executables

Comment out the JDB include statement.

To link JDB and your database engine:

Leave the JDB database specification uncommented and uncomment the appropriate include statement for your database.

Include C Modules in the Executable

If your application uses user-written C modules, you'll want to link them into the application's executable.

To link your own C modules to the executable:

1. Copy the modules to the application directory.
2. Add the filenames to the SRCMODS macro of the makefile.

For example, if your application's C source code modules are mymod1.c and mymod2.c, change the SRCMODS line of the makefile to list the modules. For example:

UNIX: SRCMODS = mymod1.o mymod2.o funclist.o

Windows: SRCMODS = mymod1.obj mymod3.obj funclist.obj

When you include files within the executable, you don't have to include them in the deployed distribution.

Identify the Database Version

When you build an executable to include your database, once you edit the makefile, you must also ensure that the uncommented makevars file includes the appropriate information.

Refer to Database Drivers for your specific engine before changing these values.

To verify (or update) database-specific information:

Access the makevars.dbs, and ensure that the following settings are correct for your database engine:

• Case handling—Set the flag dbs_INIT to one of the following: d (default case conversion set), l (lowercase), u (uppercase), p (preserve case). The default is d. This specification deals primarily with the case conversion of database column names. Some database engines only create column names in a specific case or allow mixed cases. This case setting specification allows you to create all Panther variables in a particular case and Panther handles the conversion for you.

  Refer to the online Database Drivers for find out what the Panther default is for your database engine.

• Engine name—Set the flag dbs_ENGNAME to specify the default engine name. Refer to the online Database Drivers for your specific engine.

• Version—In the databaseName PARAMETERS section of the makevars, verify your database engine's version. Uncomment the appropriate block of parameters based upon this version. Also, verify and correct path names if necessary.

Compile the Changes

Once you have copy all required files to your application directory, and make the appropriate edits to the makefile (and optionally, to makevars and jmain.c), from the application directory, run the appropriate compiler utility at the command line: make under UNIX; nmake under Windows.

A compiling message and then the linking message are displayed. When the operating system returns you to the command prompt (with no errors), the executables have been built.

For more about makefiles, refer to your compiler's documentation on make or nmake.

If you are building executables for distribution, you can package them with the other required files for application release. Refer to page 43-1 for details.

Rename the Executables

The result of running the make or nmake utility is compiled executables ready for distribution. You can rename executables to reflect your application's name; there are no naming restrictions, except perhaps those imposed by your specific operating system.

---

Customizing Source Code for an Application

You can edit the source, jmain.c, for the Panther executable to change the default behavior of your application. jmain.c is located in the link directory and you should copy it to your application directory. Edit the source file prior to creating the executable if you want to do any of the following:

• Specify a startup screen for your application, such as, a welcome or login screen.

• Specify an icon for your application.

• Make Panther binary files memory-resident: screens, JPL modules, menus.

• Make configuration files used by Panther memory-resident.

• Rename the Panther library.

Whenever you edit jmain.c you must remember to rebuild your runtime executable (prorun) in order for changes to take effect.

Source Code Structure

jmain.c has three functions defined in it:

• main, initialize and clean_up which you can modify: main is defined globally and is the entry point to the entire application program. main calls the statically defined functions

• initialize and clean_up. Code necessary to your application can be inserted into the main routine. Any code inserted before initialize is executed before any Panther functions have been executed. initialize allocates internal data structures and sets the terminal characteristics. Code inserted after initialize is executed after Panther allocates internal data structures and sets the terminal characteristics, but before there are any screens and before there is a local data block.

• clean_up exits back to the operating system and restores the terminal's display state. Code called after clean_up is executed after all Panther functions have been executed.

If a finer granularity is needed, you can edit initialize and clean_up themselves. Do so only if you understand Panther thoroughly.

Notes: In general, you should not modify jmain.c to install event functions. You can declare most event functions in funclist.c. A few event function types, however, must be installed before or during initialization in jmain.c. For more information on event function installation, refer to page 44-4.

Specifying an Application Startup Screen

To identify a startup screen that will display when your application is first initialized, you must edit the jmain.c file you copied to your application directory.

Change the start_screen_name setting from 0 to the name of your top screen; for example, start_screen_name = "login.scr"; Include the specification after the comment for TOPSCREEN:

/* to hard code the name of the first screen, for */
/* example, "TOPSCREEN", replace the following line */
/* with start_screen_name = "TOPSCREEN"; */

start_screen_name = "login.scr";
start_up (argc, argv);

Rebuild your runtime executable to have the change in jmain.c take effect.

Specifying an Application Icon

To ensure that an icon that will display when your application is installed on a Windows client machine, specify the name of the application icon in the prorun.rc resource file that you copied to your application directory.

In jmain.c, change the ICONFILE specification from prolific.ico to the name of your icon image.

Rebuild your runtime executable to have the change in jmain.c take effect.

Including Memory-Resident Components

All Panther components can be made memory resident: screens, menus, configuration files, and JPL modules. When a component is made memory resident, it means it is compiled as part of the executable. This can enhance application performance by minimizing its need to access the disk. It can also reduce the number of files in the distribution. Once these components are compiled into the executable, the individual components can then be eliminated from the distribution.

In function, memory residency means the component is loaded into memory when your application starts up. However, it's also important to recognize that your application would consume more memory at startup.

In general, the process of making a component memory-resident involves:

• Copying or extracting the desired component in its binary format from its library using formlib.

• Converting the component from binary format to a C data structure with the bin2c utility.

• Editing the source file, jmain.c, to include the desired C structure.

• Compiling the application to build the components into the application's executable.

Panther creates binary files that are stored in Panther libraries. These include your screens and service components, JPL modules, menus, and any file created with and used by Panther (such as an application setup file named in SMSETUP). Memory-resident files are installed by way of a memory-resident list. The list is maintained by Panther and specifies the components you indicate in the source file.

To make screens, menus, or JPL modules memory-resident:

1. Extract the desired binary component from its library using formlib. Or run jpl2bin against the ASCII version of the component to get a binary file.
2. Convert the binary file to a C structure with bin2c, for example:

   bin2c filename.h filename.bin

3. In jmain.c, after the lines:

   #include "smdef.h"
   #include "smerror.h"
   #include "smuprdb.h"

   add the filename.h specification

   #include filename.h

4. In jmain.c, before the line:

   /* THE FOLLOWING FUNCTIONS ARE IN THIS MODULE */

   include the C structure:

   struct form_list mrforms[] =
   {
   	"source_filename.ext", filename
         "",             (char *)0
   };

   All memory-resident files, modules, etc. should be listed, one per line, immediately before the line:

    "",             (char *)0

   This last entry in the list indicates the end of the list and is required.

5. In jmain.c, after the line:

   /* Place code...any Panther initializations here */

   add the following line:

   sm_formlist(mrforms);

   The call to sm_formlist dynamically adds the specified components in the form_list structure to Panther's internal memory-resident list.

6. Make sure the edited jmain.c source is in your application directory and create your application executable (refer to "Steps for Creating an Executable").

   Notes: Because the screen editor can only operate on library files, altering memory-resident screens and JPL during program development requires a cycle of test—edit—extract from library—reconvert with bin2c—recompile. Therefore you should make components memory-resident only at the very end of your development process.

At runtime, when Panther attempts to open a screen, it first looks in the memory-resident screen list for the requested screen; if found there, it's displayed from memory, while screens not in the list are sought in open libraries. In this way, you can open screens irrespective of their actual location—for example, with sm_r_form. You can later change the location of the screen without changing the calls to open them, simply by changing the memory-resident list.

If you have specified the setup variable SMFEXTENSION, Panther appends its value to screen names that do not already contain an extension; take this into account when creating the screen list. For UNIX systems, Panther can also convert the name to uppercase before searching the screen list, as determined by the FCASE variable.

Alternatively, if you are using a custom executive, sm_d_form and related library functions can be used to display memory-resident screens; each takes as one of its parameters the address of the global array containing the screen data, which usually have the same name as the file in which the original screen was originally stored.

Any or all of the required configuration files as well as optional configuration files used by Panther can be made memory-resident. These files include:

• Message files (msgfile.bin)

• Video file (*vid.bin)

• Configuration map file (*cmap.bin)

• Key translation file (*keys.bin)

To make configuration files memory-resident:

1. Copy the desired binary files from the config directory or extract (using formlib) them from the common library (if they are already associated with your application).
2. Convert the binary file to C structure with bin2c, for example:

   bin2c filename.h filename.bin

3. In jmain.c, after the lines:

   #include "smdef.h"
   #include "smerror.h"
   #include "smuprdb.h"

   add the filename.h specification:

   #include "filename.h"

4. In jmain.c, after the line:

   /* Place code to...any Panther initializations here */

   add the following line or lines, specific to each configuration file type:

   sm_n_msg_read ("SM", SM_MSGS, MSG_MEMORY|MSG_INIT,
   msgfile);
   sm_vinit (videofile);
   sm_load_colormap (cmapfile);
   sm_keyinit (keyfile);

If a configuration file is memory-resident, the corresponding environment variable or SMVARS entry is unnecessary and the binary files needn't be included in the common library of your distribution.

Rename the Distributed Panther Library

The distributed library, prorun5.lib, contains the support routines and screens used by Panther. It is required in your application's distribution as well. In addition to renaming executables, you can also rename this library to conform to your application's name.

To rename the Panther library:

1. Copy prorun5.lib from the config directory to your application directory and rename the copied file.
2. In jmain.c, replace the line:

   if ((lib = sm_l_open (p = RUNTIME_LIBRARY)) < 0)

   with:

   if ((lib = sm_l_open (p = "myapp.lib")) < 0)

Subsystem Installation

After the definition of the main function, there is a JTERM_COMPRESSION subsystem macro definition. This subsystem increases the communication efficiency and execution speed for applications when they are accessed by the Panther terminal emulator. It increases the application's memory requirements. By default, it is set to 0. To turn the subsystem on, set the macro to 1.

Oracle Tuxedo Executables

You need to update the Oracle Tuxedo XA RM file before you can use the provided makefile to relink executables. This is done by appending the contents of $SMBASE/samples/Oracle Tuxedo/RM to $TUXDIR/udataobj/RM and confirming the appropriate section for your database and version.

---

---