Previous     Contents     Index     DocHome     Next     
iPlanet Application Server 6.0 Programmer's Guide (C++)



Chapter 11   Running and Debugging Applications


This chapter describes how to set up a test version of your application, as well as how to use the debugging tools in your C++ development toolkit.

The following topics are included in this chapter:



Getting Ready to Run an Application

Before you can execute the AppLogic objects in your application, you must set up a test version of your application. This involves copying your application files to the appropriate locations and registering the AppLogics, other code modules, and security information needed in the application. For the purposes of testing, you will probably set up the application on a single iPlanet Application Server.

This manual does not describe application deployment in detail. In general, the procedure for setting up an application for testing is similar to that for deploying production applications. This section describes only those procedures that are specific to setting up an application for testing.

Alternatively, if you are using iPlanet Application Builder, you can deploy applications using its deployment feature. This procedure is described in User's Guide.


Compiling Applications

This section assumes that you are already familiar with creating makefiles and compiling source files on your development platform. It also assumes that you have already installed the entire Calhoops sample application on your development system using the iPlanet Application Server installation procedure described on the product CD.

This section lists relevant libraries to link to and describes creating a makefile for your AppLogic, using examples of makefiles from the Calhoops sample application for the Sun Solaris, Hewlett-Packard HP-UX, and Microsoft Windows NT platforms.


Setting the GX_ROOTDIR Environment Variable

Before compiling, you need to set the $GX_ROOTDIR environment variable to point to the root directory for the iPlanet Application Builder. For instructions on how to do this, see the system documentation for your particular development platform.


Creating a Makefile

Use your C++ application development tools to generate the makefile for your project. The following examples show the makefile for the Calhoops sample application on the Sun Solaris, Hewlett-Packard HP-UX, and Microsoft Windows NT platforms.


Sun Solaris
#

# Sample makefile for C, C++ applogics

# Run 'make debuggable' or simply 'make'

# to build shared library with debug info.

# Run 'make release' to build optimized shared library

#

OBJS = calhoops.o # list of all object files to be generated

SHO = libcalhoops.so # name of shared object file to generate

DEBUG = -g

debuggable := TARGET = debuggable

release := TARGET = release

release := DEBUG = -O

debuggable: all

release: all

PLATFORM = SOLARIS

CC = cc

CPP = CC

GX_ROOT = $$GX_ROOTDIR

LIBDIR = $(GX_ROOT)/gxlib

INCDIR = $(GX_ROOT)/include

INCLUDES = -I. -I$(INCDIR)

CPPFLAGS = -KPIC -mt -DUNIX -DGXPUBLIC_BUILD -D$(PLATFORM) $(DEBUG) $(INCLUDES)

CFLAGS = -KPIC -mt -DUNIX -DGXPUBLIC_BUILD -D$(PLATFORM) $(DEBUG) $(INCLUDES)

SHOFLAGS = -G -Bsymbolic -mt -z text -L $(LIBDIR)

.SUFFIXES :

.SUFFIXES : .c .h .cpp .s .o

.cpp.o:

   $(CPP) $(CPPFLAGS) -c $<

.c.o:

   $(CC) $(CFLAGS) -c $<

.s.o:

   $(CPP) $(CPPFLAGS) -c $<

all : install

install: $(SHO)

   [ -d $(LIBDIR) ] && cp $(SHO) $(LIBDIR)

$(SHO): $(OBJS)

   $(CPP) $(SHOFLAGS) -o $(SHO) $(OBJS) -lgxagent -lgxidl -lgxutil

clean :

   @rm -f $(OBJS)

clobber : clean

   @rm -f $(SHO) $(LIBDIR)/$(SHO)


Hewlett-Packard HP-UX
#

# Sample makefile for C, C++ applogics

# Run 'make debuggable' or simply 'make'

# to build shared library with debug info.

# Run 'make release' to build optimized shared library

#

OBJS = calhoops.o # list of all object files to be generated

SHO = libcalhoops.sl # name of shared object file to generate

DEBUG = -g

debuggable := TARGET = debuggable

release := TARGET = release

release := DEBUG = -O

debuggable: all

release: all

PLATFORM = HPUX

CC = cc

CPP = CC

GX_ROOT = $$GX_ROOTDIR

LIBDIR = $(GX_ROOT)/gxlib

INCDIR = $(GX_ROOT)/include

INCLUDES = -I. -I$(INCDIR)

CPPFLAGS = +Z +a1 -DUNIX -D$(PLATFORM) -DGXPUBLIC_BUILD $(DEBUG) $(INCLUDES)

CFLAGS = +Z -Ae -DUNIX -D$(PLATFORM) -DGXPUBLIC_BUILD $(DEBUG) $(INCLUDES)

SHOFLAGS = -b -q -Wl,+s,+b:,+vshlibunsats $(CPPFLAGS) -L $(LIBDIR)

.SUFFIXES :

.SUFFIXES : .c .h .cpp .s .o

.cpp.o:

$(CPP) $(CPPFLAGS) -c $<

.c.o:

   $(CC) $(CFLAGS) -c $<

.s.o:

   $(CPP) $(CPPFLAGS) -c $<

all : install

install: $(SHO)

   [ -d $(LIBDIR) ] && cp $(SHO) $(LIBDIR)

$(SHO): $(OBJS)

   $(CPP) $(SHOFLAGS) -o $(SHO) $(OBJS) -lgxagent -lgxidl -lgxutil

clean :

   @rm -f $(OBJS)

clobber : clean

   @rm -f $(SHO) $(LIBDIR)/$(SHO)


Microsoft Windows NT
PROJECT=calhoops.dll

PROJECT_OBJS=calhoops.obj

##############################################################

KIVA_ROOT=C:\KIVA\KDS

MYCFLAGS=

MYLFLAGS=

CC_FLAGS =$(MYCFLAGS) /c /nologo /MTd /W3 /GX -DWIN32 -DWINDOWS

-D_WINDOWS $(MYCFLAGS)

CC_FLAGS_REL=/Ox

CC_FLAGS_DBG=/Od /Zi /Gm -DDEBUG -D_DEBUG

LINK_FLAGS =$(MYLFLAGS) /MAP /subsystem:windows /dll /incremental:no

LINK_FLAGS_REL=

LINK_FLAGS_DBG=/DEBUG:FULL /DEBUGTYPE:BOTH

INCLUDE=$(KIVA_ROOT)\include;$(INCLUDE)

LIB =$(KIVA_ROOT)\lib\c;$(LIB)

LIBS=gxagent.lib gxutil.lib gxidl.lib kernel32.lib user32.lib uuid.lib

!if "$(DEBUG)" == "YES"

CC_FLAGS=$(CC_FLAGS) $(CC_FLAGS_DBG)

LINK_FLAGS=$(LINK_FLAGS) $(LINK_FLAGS_DBG)

!else

CC_FLAGS=$(CC_FLAGS) $(CC_FLAGS_REL)

LINK_FLAGS=$(LINK_FLAGS) $(LINK_FLAGS_REL)

!endif

CC=CL

LINK=LINK

.SUFFIXES: .cpp

.cpp.obj:

   $(CC) $(CC_FLAGS) $<

all: project

project: $(PROJECT_OBJS)

   $(LINK) $(LINK_FLAGS) $(PROJECT_OBJS) /OUT:$(PROJECT) $(LIBS)

clean:

   del *.obj

   del *.map

   del *.dll

   del *.pdb


Placing Files on the iPlanet Application Server

This section uses the following abbreviations to refer to directories on your file system:

  • $GX_ROOTDIR is the root directory where you installed the iPlanet Application Builder.

  • $APP_ROOTDIR is the root directory where you store AppLogic files for a specific application or project. We recommend that you make this a subdirectory under the GXApp directory:

    • Unix: $GX_ROOTDIR/APPS/GXApp/<Italic>AppName

    • Windows: $GX_ROOTDIR\APPS\GXApp\<Italic>AppName


Caution

If you reinstall or uninstall the iPlanet Application Builder, this directory might be overwritten by the installation program. Be sure to move or copy these files to a different location before reinstalling or uninstalling your software.


When placing shared libraries and HTML template files (for HTML-based clients) on your iPlanet Application Server, consider storing them in the following locations, where $GX_ROOTDIR is the Netscape Application Server root installation directory:




Component

Suggested Location

Sun Solaris  

 

shared library files  

$GX_ROOTDIR/gxlib/*.so.  

html templates (.html)  

$APP_ROOTDIR/templates  

Hewlett-Packard HP-UX  

 

shared library files  

$GX_ROOTDIR/gxlib/*.sl  

html templates (.html)  

$APP_ROOTDIR/templates  

Microsoft Windows NT  

 

shared library files  

$GX_ROOTDIR\bin\*.dll  

html templates (.html)  

$APP_ROOTDIR\templates  

For example, the Calhoops sample application shared library files might be stored in the following locations:




Platform

Shared Library File

Sun Solaris  

$GX_ROOTDIR/gxlib/libcalhoops.so  

Hewlett-Packard HP-UX  

$GX_ROOTDIR/gxlib/libcalhoops.sl  

Microsoft Windows NT  

$GX_ROOTDIR\bin\calhoops.dll  


Placing Files on the Web Server (HTML Client)

When placing web pages and graphics files on your Web server, consider storing them in the following locations, where <Code>$WS_DOCROOTDIR is the document root directory of the web server:




Component  

Sample Location  

html pages (.html)  

<Code>$WS_DOCROOTDIR/GXApp/<Italic>AppName  

html graphics (.gif, .jpeg)  

<Code>$WS_DOCROOTDIR/GXApp/<Italic>AppName  

For example, the query selection form for the Calhoops sample application (index.html) might be in the following path:

<Code>$WS_DOCROOTDIR/GXApp/CCalhoops/index.html


Registering Code And Security Information

Before you can execute your application, you must set up a test version. As one of the steps in this procedure, you must register certain application items with the iPlanet Application Server. When setting up an application for testing, you might need to register any of the following types of items with the iPlanet Application Server:

  • AppLogic objects

  • Other code modules

  • Users

  • User groups

  • Access control lists (ACLs)

By registering users, user groups, and ACLs, you can set up security for the application. During testing and initial deployment, you must define these items yourself if your application includes security features, such as calls to LoginSession( ). During production deployment, the system administrator can also manage the security information, using the iPlanet Application Server Administrator tools.


Using Utilities to Register Application Information

The iPlanet Application Server maintains a record of registered application items in local registry storage. You can use the kreg utility to populate the registry. To do so, edit one or more files with a .gxr extension. These files are the input to kreg.

To register code or security information using utilities

  1. For an AppLogic object or other code module, you must generate a unique GUID. To do so, run the kguidgen utility from a command line or window by typing the following command:

       kguidgen

    This utility returns a random, unique GUID which you can copy and paste.

  2. Add lines to the .gxr file for the items you want to register. The syntax for each type of item is given later in this section. Each item uses four lines.

    • Make sure you assign a unique name to the item. Unlike the GUIDs, which are sure to be unique since they are generated automatically, there is a possibility for duplicates when you assign names yourself. For example, prefix the names of your AppLogics with the application name to reduce the possibility of name collisions.

    • For an AppLogic object or other code module, paste in the GUID that was generated by kguidgen.

  3. Run the kreg utility from a command line or window using the following syntax:

       kreg fileName.gxr

    For example:

       kreg OnlineBank.gxr


AppLogic .gxr Syntax

The entry in a .gxr file to register an AppLogic object uses the following syntax (the portion from AppLogic to group is all on one line):

AppLogic name [:type=c][:enable=y|n][:encrypt=y|n]

              [:lb=y|n][:descr[:AppName;group;...]]

GUID [:server;...[acl=user,[!]EXECUTE;...]]

Blank line

Path to AppLogic

The items in the syntax are as follows:

  • name: Name of the AppLogic object.

  • :type=c: Optional letter c to indicate that the AppLogic object is written in C++.

  • :enable=y|n: Optional flag to indicate whether the AppLogic is enabled.

  • :encrypt=y|n: Optional flag to indicate whether the communications to the AppLogic are encrypted.

  • :lb=y|n : Optional flag to indicate whether sticky load balancing is set.

  • :descr: Optional description of the AppLogic, which will appear in the Application Administrator.

  • :AppName;group;...: Optional semicolon-separated list of groups to which the AppLogic belongs. The first group should be the name of the application.

  • Globally unique identifier (GUID) that was generated by kguidgen.

  • :server;...: Optional semicolon-separated list of server descriptions. Each server description uses the following syntax:

       <SERVER_IP_ADDR>:<SERVER_IP_PORT>[=<SERVER_FLAGS>]

    SERVER_IP_ADDR is a decimal-dotted IP address, such as 192.23.43.15. SERVER_IP_PORT is the Executive Server port number, in decimal. SERVER_FLAGS is an optional decimal number. The flags, in hexadecimal, are 0x8000000 to set sticky load balancing and 0x00000001 to set the enable flag. Note that you can turn these on using the lb and enable flags on the first line.

  • acl=user,[!]EXECUTE;...: Optional semicolon-separated list of access control list (ACL) entries, to specify which users can execute the AppLogic. Each ACL entry uses the following syntax:

       user,[!]permission

    User is the name of a User or UserGroup, as specified by the system administrator. Permission is an operation name. For AppLogics, EXECUTE is the only operation that is checked automatically by the system. An exclamation point in front of EXECUTE means the user or user group can not run the AppLogic.

  • Path to AppLogic object. For cross-platform compatibility, you can omit the extension of the file (such as .dll or .so) and, on UNIX platforms, you can also omit the lib prefix of the file. For increased portability, it is advisable to use relative paths in the .gxr file.

  • (Optional) Comments. Each line can end with a comment preceded by the vertical bar character |.


Example
The following lines show the .gxr file entry for an AppLogic object (the portion from AppLogic to digibanker is all on one line):

AppLogic CalculateBalancesLogic:Updates account balance

   :lb=y:type=c::digibanker

{e248ecd0-9bfd-bc32-00a024d1709f}

|Blank

libbanking


Code Module .gxr Syntax

The entry in a .gxr file to register a code module (that is not an AppLogic object or an iPlanet Extension) uses the following syntax:

Module name [:type=c][:descr[:AppName;group;...]]

GUID

Blank line

Path to code module

The items in the syntax are as follows:

  • name: Name of the module.

  • :type=c: Optional letter c to indicate that the module is written in C++.

  • :descr: Optional description which will appear in the Application Administrator.

  • :AppName;group;...: Optional semicolon-separated list of groups to which the module belongs. The first group should be the name of the application.

  • Globally unique identifier (GUID) that was generated by kguidgen.

  • Relative path to the code module. For cross-platform compatibility, you can omit the extension of the file (such as .dll or .so). For increased portability, it is advisable to use relative paths in the .gxr file.

  • (Optional) Comments. Each line can end with a comment preceded by the vertical bar character |.


Example
The following lines show the .gxr file entry for a code module:

Module DigiBank CICS Integration:type = c

{e248ecd0-9bfd-bc32-00a024d1709f}

|Blank

digicics


User .gxr Syntax

The entry in a .gxr file to register a user has the following syntax:

User name

Password

[group;...]

Blank line

The items in the syntax are as follows:

  • name: Name of the user.

  • Password: The user's password.

  • group;...: Optional semicolon-separated list of groups to which the user belongs. These groups are defined elsewhere in the .gxr file, using the syntax described later in this section.

  • (Optional) Comments. Each line can end with a comment preceded by the vertical bar character |.


Example
The following lines show the .gxr file entry for a user:

User DigiBankAdmin

tiger

DigiBankUsers;DigiBankAdministrators

| Blank


User Group .gxr Syntax

The entry in a .gxr file to register a user group has the following syntax:

UserGroup name

Blank line

Blank line

Blank line

The items in the syntax are as follows:

  • name: Name of the user group.

  • (Optional) Comments. Each line can end with a comment preceded by the vertical bar character |.


Example
The following lines show the .gxr file entry for a user group:

UserGroup DigiBank Users

| Blank

| Blank

| Blank


ACL .gxr Syntax

The entry in a .gxr file to register a named access control list (ACL) uses the following syntax:

ACL name

[user,[!]permission;...]

Blank line

Blank line

The items in the syntax are as follows:

  • name: Name of the ACL.

  • user,[!]permission;...: Optional semicolon-separated list of ACL entries, to specify which users can perform operations. Each ACL entry uses the following syntax:

       user,[!]permission

    User is the name of a user or user group, as specified by the system administrator. Permission is an operation name, such as EXECUTE, READ, or WRITE . An exclamation point in front of the permission means the user or user group can not perform that operation.

  • (Optional) Comments. Each line can end with a comment preceded by the vertical bar character |.


Example
The following lines show the .gxr file entry for an ACL:

ACL DigiBank.monthlyforecast

DigiBankAdmin,ADMIN;DigiBankPartner,!READ

| Blank

| Blank


Saving and Restoring Registry Configurations

As described in the previous section, the iPlanet Application Server maintains a record of registered application items in local registry storage. You can save and restore snapshots of the registry by using the kreg utility. You might want to do this for the following reasons:

  • Back up registry settings.

  • More easily bring up secondary, replicated servers.

  • More easily bring up replicated engines or control sets.

  • Save, replicate, and manually synchronize registry information about users, user groups, ACLs, AppLogics, and iPlanet Extensions across multiple machines.

  • Debug administration settings.

  • Remotely view and debug a configuration.

  • Allow various groups in your organization to swap between saved configurations, especially if certain registry configurations are required for certain tests, such as load balancing, partitioning, and stress testing.

  • Replicate AppLogic information to the Web server tier. This supports better AppLogic load balancing from the Web server. It also allows encryption of AppLogic requests on a per-AppLogic basis between a Web server and Executive Server.


To Save the Registry

To save a snapshot of the current registry settings, run the kreg utility from a command line or window using the following syntax:

kreg -save fileName key1 [key2...]

The fileName is the file in which the registry settings are saved. The key is the path to a registry key, starting from the root key. For example:

kreg -save mytest.data SOFTWARE\KIVA\Enterprise\2.0\CCS0\DAE


To Restore the Registry

To save a snapshot of the current registry settings, run the kreg utility from a command line or window using the following syntax:

kreg -load fileName [fileName2...]

The fileName is the file in which the registry settings were saved. For example:

kreg -load mytest.data



Debugging with Third-Party Tools


You can test and debug AppLogic objects using the debugging tools in your C++ development toolkit. The tools available vary depending on the machine and operating system you are using. iPlanet Application Builder integrates with several debugging tools.

The following steps give a general outline of the debugging process. Specific procedures for each debugging tool follow.


General steps to debug AppLogic

  1. Compile the AppLogic using the debug option.

    For example, in many compilers, the -g flag enables the debug option.

  2. Start your debugging tool.

    For example, on Microsoft Windows NT, you might use msdev. On UNIX, you might use dbx.

  3. Determine the process ID of the C++ Server process you want to debug.

    For example, on Microsoft Windows NT, use the Task Manager. On UNIX, use the ps command.

  4. Using this process ID, attach to the C++ Server process from within your debugging tool.

    For example, if you are using msdev on Microsoft Windows NT, use the menus. If you are using dbx on UNIX, use the command attach PID.

    Note: The AppLogic you are trying to debug may not yet be loaded into the C++ Server. Most debugging tools will still allow you to set the breakpoint in the AppLogic before it has been loaded. If not, execute the AppLogic once so that it is loaded.

  5. Set a breakpoint in your AppLogic.

    For example, the beginning of the Execute( ) method is often a logical place for a breakpoint.

  6. Execute your AppLogic.

  7. At the breakpoint, begin stepping through your AppLogic code.


Debugging with MSVC (Version 4.2 or Higher)

To debug code using Microsoft Visual C++, in addition to any projects that you use to build your AppLogic code, you must create a project of type "Console Application" that contains no code files at all, but simply specifies the C++ Server .EXE file of your Netscape Application Server installation as its executable. After invoking your AppLogic once, you will be able to open its source files in the MSVC's editor and set breakpoints in these files.


Create the Project

  1. File - New- Project Workspace.

  2. Console Application; any name you like; Location can be any directory, but it will be convenient to use the root directory of your AppLogic tree.


Set Up the Project

  1. Build - Settings (Alt-F7)

  2. Select the "Win32 Debug" configuration.

  3. Go to the Debug tab.

  4. In "Category", select General.

  5. As "Executable for debug session" supply the path to the C++ Server .EXE file in your Runtime Environment.

  6. "Program arguments": -debug (may not be necessary).

  7. In "Category", select Additional DLLs.

  8. In the Modules list, add one or more DLLs from your AppLogic and check the boxes to the left of their names.


Run the Project

  1. Start the Netscape Application Builder Runtime Environment and shut down the C engine once initialization is complete.

  2. Build - Debug - Go or F5 key.

  3. "One or more files are out of date ...?": choose No.

  4. "One or more breakpoints cannot be set ....": choose OK.

  5. "First-chance exception ....": choose OK.

  6. Debug - Go or F5.

  7. "Pass exception on to the program being debugged?": choose Yes.

  8. Repeat steps 5-7 once more.

  9. File - Open and open one or more source files from the additional DLLs you specified in "Set up" above.

  10. Set breakpoints in these files, as needed.

  11. Bring up a suitable form in a Web browser or somehow cause your AppLogic to execute, and debug normally.


Previous     Contents     Index     DocHome     Next     
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated April 26, 2000