# CB to IMS/OTMA Sample

# Content

#### Introduction

#### Prerequisite Software

#### Installing The Sample

#### Developing the Sample Application

#### Developing the Bottom-up Part

#### Developing the Top down Part

#### Developing the Client

#### Running the Application

# Introduction

This document describes the process of building a sample Component Broker (CB) application connecting to an IMS Installation Verification Procedure (IVP) through Open Transaction Monitor Access (OTMA). The purpose of the sample is to present a method for developing a CB application with an IMS backend using IMS TCP/IP OTMA Connection (ITOC).

This method can be followed to connect a CB application to an IMS application other than the IVP used in this sample. However, the method is limited. It demonstrates connecting a CB application to an IMS/OTMA application using IMS Web generated code and IMS Web run time. But it does not use any transaction and session support at the CB level.

The IMS/OTMA sample uses the non conversational version of the phone book IVP. This IVP is a mock phone book database, where each entry in the
phone book contains the following fields:

Last name
First name
Phone number extension
Internal zip code

The phone book IVP works on an IMS database and permits adding, inquiring, updating, and deleting of phone book entry records through the ADD, DISPLAY, UPDATE, and DELETE transactions.

For IVP install instructions for IMS, see IMS/ESA Version 6 Install Volume 1. The entire book contains information on installing and configuring the IVP sample. Chapter 11, entitled "Install/IVP Application", discusses the sample IMS application.

# Prerequisite Software

IMS Web version 2.1.1 is a prerequisite for developing and executing the IMS/OTMA sample. The sample package includes a version of IMS Web which is slightly different than the one available on the web. See the section on Installing the Sample for more details. The sample application assumes that the IMS host is running ITOC 2.1.1.

## Overview of IMS Web

IMS Web enables access to IMS applications from the World Wide Web. IMS Web consists of a development component, IMS Web Development, and a run time component, IMS Web Runtime.

IMS Web Development generates a CGI program and HTML file for IMS Web driven applications from the MFS source files. The IMS Web Development component consists of the IMS Web Studio tool and the IMS Web library. IMS Web Studio parses the MFS file(s) and generates the web-based code. The IMS Web library is a set of library and header files that are required to build the generated code into an executable that runs in the IMS Web Runtime environment.

IMS Web Runtime provides a set of functions that are called by the IMS Web Development generated code. The IMS Web Runtime component performs the following functions:

> - Communication to IMS TCP/IP OTMA Connection (IMS TOC) via TCP/IP.
> - MFS like message formatting and platform data conversion.

# Installing the Sample

The sample application is packaged in a zip file called smpimsotma.zip. The zip file includes the IMS Web Runtime and IMS Web Development, in addition to the sample code. The IMS Web components are available through the web. However, the IMS Web Runtime DLLs are not built with VAC++. Since CB C++ code links only with VAC++ DLLs, the IMS Web Runtime had to be rebuilt with VAC++. The privately built IMS Web Runtime is only compatible with the supplied version of IMS Development and ITOC 2.1.1. To install the sample, unzip the file smpimsotma.zip file in the <CBroker>\samples directory.

The top level directory IMSOTMA contains four subdirectories: Applications, BusinessObjects, pbe, and IMSWeb. Applications and BusinessObjects are the familiar directories found with any CB application. Applications contains the client code and BusinessObjects contains the server code generated by Object Builder. The pbe directory contains the modified code generated by IMS Web, the PBEPO persistent object, the imswebutil class, and the testpbe unit test driver. See sections Creating the Persistent Object Class, Creating the Error Handling Utility Class and Building the DLL and Unit Testing the Code for more information on these files. The IMSWeb directory contains the IMS Web components: Development and Runtime. Below is a description of the IMSWeb directory contents:

> - The .tbl files in the IMSWeb directory are required for language conversions. The void.tbl is an essential file used by the CGI program.
> - The directory dlls contains the IMSWeb Runtime DLLs.
> - The include and lib\win directories, contain , respectively, the header files and lib files used to build the web application.
> - The directory Studio contains all the files necessary to run the IMS Web Studio. The Web Studio can be invoked by the batch file hwsgui.bat. The com sub directory contains class files needed for the Web Studio to function.
> - The directory testno\cgi contains the non conversational version of the IVP generated code. This program can be effectively used for testing connections to IMS. The program will attempt to establish connection with an IMS system which is configured with the IVP. You will need to update the setUser(), setGroup(), setHost(), setPort(), and setIMS() method calls in CGItestno.cpp file to specify the information for the system you plan to connect to. The exe program is built by issuing the "nmake" command provided by Visual Age C++. The program can be invoked from the command line by typing CGITestno <in.dis >out.htm. The output file which is an html document can be viewed in a browser or as a simple text file. The files in.dis, in.del and in.add are text files containing name value pairs. Any of these can be redirected into the CGITestno program.

## Running the sample immediately

If you want to recreate the sample, follow the steps under Developing the Sample Application. Otherwise, you may run the sample by following the steps below.

> - Modify the file <CBroker>\samples\Imsotma\pbe\PBEPO.cpp to supply information specific to your own environment. Specifically, in the PBEPO constuctor you need to change the parameter values associated with the set methods setUser(), setGroup(); setHost(), setPort(), and setIMS(). The PBEPO class is described in Modifying the Generated Code.
> - Rebuild pbe.dll by running the "nmake" command in the <CBroker>\samples\Imsotma\pbe directory.
> - Generate the Business Objects by running the command "obgen -p<CBroker>\samples\Imsotma\BusinessObjects -aAll". This will create the <CBroker>\samples\Imsotma\BusinessObjects\Working\NT directory containing the code.
> - Follow the steps in Building the Application - Client and Server, Configuring the Application with System Management and Running the Sample Application.

# Developing the Sample Application

The process for developing the IMS/OTMA sample is similar in some aspects to that of the PAA samples. It is a meet-in-the-middle process and consists of a bottom up part and a top down part. In the bottom up part, you use the IMS Web to generate the web based code. Then you modify the web-based code to allow integration with the Component Broker code. In the top down part, you develop the CB component with Object Builder. During this part of the process, you follow a specific pattern for implementing the data object and defining the container. The two parts of the process are integrated when you implement the data object CRUD (create, retrieve, update, delete) methods.
Finally, you develop the client application to run and test your server application. Here also, the client application needs to follow a specific pattern to insure that all the CRUD method have been executed.
These steps are described in details in the following sections.

## Developing the Bottom-up Part

This part involves two main steps:

Generating the web based code
Modifying the generated code

### Generating Web Based Code Using IMS Web

1. Start the IMS Web Studio

1. Invoke Web Studio by typing hwsgui.bat ( you need to be in the IMSWeb\Studio directory when invoking this command). The file hwsgui.bat assumes that JDK is installed on C:JDK1.1.6. You may need to modify this file if your JDK is installed under different path.

2. Create a project

1. Select Choose Project from the IMS Web Studio tasks on the initial TaskGuide window or click Next.
2. Click Create new project. The Define project TaskGuide window displays.
3. Enter `pbe` under project name and `<CBroker>\samples\Imsotma\pbe` under project directory.
4. Click Next. The Gather files TaskGuide window displays.

3. Parse the MFS file

1. The path to the MFS file is `<CBroker>\samples\Imsotma\IMSWeb\testno\Dfsivf1.mfs.`
2. Click on the Find MFS file on workstation button to bring the file to the MFS files in project list.
3. Click Next and then click Parse all.
4. When you are finished, click Next.
5. The Define transaction TaskGuide window displays.

4. Define the transaction

1. Accept the default and click Next.

5. Define the classes

1. Click Next.

6. Define the host

1. Under Hostname of the machine running ITOC, enter the TCP/IP host name of the machine running the IMS TCP/IP OTMA Connection. Do not enter the TCP/IP address here. The host name might or might not have to be fully qualified, depending on how TCP/IP is configured for your web server.
2. Under Port number, enter the port number (maximum of 4 characters) assigned to the IMS TCP/IP OTMA Connection on the machine running the IMS TCP/IP OTMA Connection
3. Under Datastore ID/IMS XCF member name, enter the extended coupling facility (Emember name (maximum of 8 characters). This is the Datastore ID you specified when you installed IMS TCP/IP OTMA Connection.

7. Define the platform

1. Accept the default and click Next.

8. Generate the code

1. Click Generate to start the code generation.
2. When code generation is completed, click Close.

Two directories cgi and dtw are created. Ignore the directory dtw.

The following files are generated in the cgi directory by the tool:

1. HTMpbe.htm - defines HTML format
2. HTMParse.hpp and HTMParse.cpp - used to parse the HTML input
3. HWSLPG00.hpp, HWSLPG00.cpp - handle the output logical page.
4. HWSLPG01.hpp, HWSLPG01.cpp - handle the input logical page.
5. CGIpbe.cpp - contains the CGI BIN source code.
6. CGIpbe.mak - contains the make file to build the CGI executable.

Copy the HWS* files up one directory into <cbroker>\samples\Imsotma\pbe. This sample doesn't use the remaining files. They may be used as guidelines however, for creating the Persistent Object Class as described below.

### Modifying the Generated Code

Modifying the generated code involves

> - creating a Persistent Object class,
> - creating an error handling utility class,
> - building the DLL and unit testing the modified code

#### Creating the Persistent Object Class

The files exist containing the PBEPO object in the <cbroker>\samples\Imsotma\pbe. You may recreate these files if you want.

The PBEPO object encapsulates the steps found in the CGI program CGIPBE.cpp. The interface of PBEPO is similar to that of HWSLPG01 except that the interface of PBEPO includes also the four CRUD methods. The PBEPO.ih header file is shown below.

`#ifndef PBEPO_HPP`
`#define PBEPO_HPP`

`#include "HWSLPG00.hpp"`
`#include "HWSLPG01.hpp"`
`#include "imswebutl.h"`

`class PBEPO`
`{`
`public:`
`// LifeCycle`
`PBEPO();`
`~PBEPO();`

`// CRUD methods`
`virtual void insert();`
`virtual void retrieve();`
`virtual void update();`
`virtual void del();`

`//Get/Set methods`
`inline void setCMD(char * value) {tranInObj->setCMD(value);};`
`inline void setNAME1(char * value) {tranInObj->setNAME1(value);};`
`inline char *getNAME1() {return tranInObj->getNAME1();};`
`inline void setNAME2(char * value) {tranInObj->setNAME2(value);};`
`inline char *getNAME2() {return tranInObj->getNAME2();};`
`inline void setEXT_(char * value) {tranInObj->setEXT_(value);};`
`inline char *getEXT_() {return tranInObj->getEXT_();};`
`inline void setZIP(char * value) {tranInObj->setZIP(value);};`
`inline char *getZIP() {return tranInObj->getZIP();};`

`private:`

`HWSLPG01In * tranInObj;`
`IMSWEButl * aIMSWEButl;`

`};`
`#endif`

Each CRUD method sets the appropriate command code, invokes the execute method on the tranInObj, and then uses the error handling utility object to check for errors. If there is any error, then the error is mapped to a CB exception.

PBEPO.cpp contains the implementation of the previous interface. Here is the implementation of the insert method.

`void PBEPO::insert()`
`{`

`HWSTranOut *tranOutObj = NULL;`
`char *msg = NULL;`

`tranInObj->setCMD("ADD");`
`tranOutObj = tranInObj->execute();`
`msg = aIMSWEButl->handle_error(tranOutObj);`

`if (msg != NULL) {`
`throw IBOIMException::IDataObjectFailed("IMS/OTMA Adapter Sample",0,0,"PBEPO::insert",msg);`
`}`
`else if (tranOutObj->getMSG() != NULL)`
`{`
`if (!strncmp(tranOutObj->getMSG(), "ADDITION OF ENTRY HAS FAILED", 28) )`
`{`
`throw IBOIMException::IDataKeyAlreadyExists();`
`}`
`}`

`delete tranOutObj;`
`}`

The implementation of the following retrieve method is slightly different. Here, since we are doing a retrieve, the retrieved values are stored in the tranInObj so that the retrieve method of the DO could fetch these values.

`void PBEPO::retrieve()`
`{`
`HWSTranOut *tranOutObj = NULL;`
`char *msg = NULL;`

`tranInObj->setCMD("DISPLAY");`
`tranOutObj = tranInObj->execute();`
`msg = aIMSWEButl->handle_error(tranOutObj);`

`if (msg != NULL) {`
`throw IBOIMException::IDataObjectFailed("IMS/OTMA Adapter Sample",0,0,"PBEPO::retrieve",msg);`
`}`
`else if (tranOutObj->getMSG() != NULL)`
`{`
`if (!strncmp(tranOutObj->getAttr("MESSAGE"), "SPECIFIED PERSON WAS NOT FOUND", 30))`
`{`
`throw IBOIMException::IDataKeyNotFound();`
`}`
`}`
`}`

`tranInObj->setNAME2(tranOutObj->getNAME2());`
`tranInObj->setEXT_(tranOutObj->getEXT_());`
`tranInObj->setZIP(tranOutObj->getZIP());h`

`delete tranOutObj;`
`}`

#### Creating the Error Handling Utility Class

The error handling utility class imswebutl encapsulates handling of errors returned by IMS Web and IMS. It is implemented as a singleton. This class is independent of the application and could be used with applications other than the phone book. Note the error handling code found in the PBEPO's CRUD methods simply maps errors to CB exceptions.

#### Building the DLL and Unit Testing the Code

Once you completed the implementation of the the persistent object, you create a makefile and build the DLL which includes the binaries for the persistent, error handling utility objects, and the non web generated code. Then you create a unit test driver to test the code.

The sample provides the unit test driver testpbe. You may modify the test driver by editing the file testpbe.cpp. To rebuild the driver, type `nmake -f testpbe.mak.`

## Developing the Top-down Part

This part involves developing the phone book component in Object Builder. Since there is no application adapter support for IMS/OTMA, a specific pattern is being followed to insure proper access to the IMS/OTMA application. This pattern is summarized as follows.

> - The business object is transient
> - The data object inherits from IBOIMExtLocalToServer::IDataObjectBase. This means that the CRUD methods need to be implemented. Each CRUD method sends/receives attribute values to/from the persistent object and delegates its operation to the corresponding CRUD method of the persistent object.
> - The container is defined as a container without object services and with the Enable Persistent References checked.

This section outlines the steps required to develop the phone book component in Object Builder and to configure the phone book application in System Management. These steps are described in the following sections.

1. Defining the PhoneBookEntry Component
2. Creating Client and Server DLL Files
3. Packaging the Application
4. Building the Application - Client and Server
5. Installing the Application

### Defining the PhoneBookEntry Component

This sample assumes the following Component Broker business object interface.

> Interface PhoneBookEntry {
> attribute string lastName;
> attribute string firstName;
> attribute string extNumber;
> attribute string internalZip;
> void showAll (out string lnm, out string fnm,
> out string ext, out string zip);
> }

As you can see, this interface is based on the phone book IMS IVP. The interface consists of four attributes and one method.

#### Description of the attributes

> - lastName - the last name of the person associated with the entry. lastName is the key attribute used to uniquely identify a phone book entry instance.
> - firstName - the first name of the person.
> - extNumber - the phone number extension for the person.
> - internalZip - the mail stop or internal address for the person. This code is used by the company for internal mail delivery .

#### Description of the method

> - showAll - this method reads all the attributes and passes them out in its parameters.

The steps required to create the phone book component are described in the following sections.

1. Creating a new business object file
2. Defining the business object
3. Defining the data object
4. Defining the managed object
5. Generating the code

#### Creating the Business Object File

To create the PhoneBookEntry business object file:

1. From the Tasks and Objects pane, select the User-Defined Business Objects folder.
2. Open the pop-up menu for User-Defined Business Objects, and select Add File, which opens the Business Object File - SmartGuide to the Name and Attributes page.
3. On this page:

1. Type `PhoneBookEntry` in the Name field.
2. Accept the other defaults.

4. Click the Finish button.

The PhoneBookEntry file is now under the User-Defined Business Objects folder.

#### Defining the Business Object

After creating the new business object file, the business object needs to be defined. A fully configured business object consists of the following:

- A business object interface
- An associated key
- An associated copy helper
- A business object implementation

##### Defining the Business Object Interface

To create the PhoneBookEntry business object interface:

1. Expand the User-Defined Business Objects folder, and select PhoneBookEntry.
2. Open the pop-up menu for PhoneBookEntry, and select Add Interface, which opens the Business Object Interface - SmartGuide to the Name and Attributes page.
3. On this page:

1. Type `PhoneBookEntry` in the Name field.
2. Click the Next button to continue to the Constructs page.

4. Click the Next button to accept the defaults and to continue to the Interface Inheritance page.
5. Click the Next button to accept the defaults and to continue to the Attributes page.
6. Define the user-defined attributes.

1. Select Attributes from the tree view.
2. Open the pop-up menu for Attributes, and select Add. This displays the Add dialog.
3. In this dialog:

1. Type `lastName` in the Attribute Name field.
2. Select string as the Type. This displays the Size field.
3. Type `0` in the Size field.
4. Click the Add Another button.

4. Repeat the previous step for the remaining attributes of the PhoneBookEntry interface. The remaining attributes are:

- firstName, and click the Add Another button.
- extNumber, and click the Add Another button.
- internalZip, and click the Refresh button.

5. Click the Next button to continue to the Methods page.

7. Define the user-defined methods.

1. Right-click on Methods from the tree view.
2. From the pop-up menu for Methods, select Add, which opens the editor pane.
3. In the this pane:

1. Type `showAll` in the Method Name field.
2. Click the Refresh button.

4. Right-click on Parameters from the tree view.
5. From the pop-up menu for Parameters, select Add, which opens the editor pane.
6. In this pane:

1. Type `lnm` in the Parameter Name field.
2. Select string as the Type. This displays the Size field.
3. Type `0` in the Size field.
4. Set the Out radio button.
5. Click the Add Another button.

7. Repeat the previous step for the remaining parameters. These parameters are:

- fnm, and click the Add Another button.
- ext, and click the Add Another button.
- zip, and click the Refresh button.

8. Click the Finish button.

The PhoneBookEntry interface is now under the PhoneBookEntry file.

##### Defining the Key

To add the key:

1. From the User-Defined Business Object folder, select the PhoneBookEntry interface.
2. Open the pop-up menu for PhoneBookEntry, and select Add Key, which opens the Key - SmartGuide.
3. Select the lastName attribute from the Business Object Attributes list.
4. Click the >> button to move this attribute to the Key Attributes list.
5. Click the Finish button.

The PhoneBookEntryKey key is now under the PhoneBookEntry interface.

##### Defining the Copy Helper

To add the Copy Helper:

1. From the User-Defined Business Object folder, select the PhoneBookEntry interface.
2. Open the pop-up menu for PhoneBookEntry, and select Add Copy Helper, which opens the Copy Helper - SmartGuide.
3. Click the All>> button to move the attributes from the Business Object Attributes list to the Copy Helper Attributes list.
4. Click the Finish button.

The PhoneBookEntryCopy copy helper is now under the PhoneBookEntry interface.

##### Defining the Business Object Implementation

To add the business object implementation and data object interface:

1. From the User-Defined Business Object folder, select the PhoneBookEntry interface.
2. Open the pop-up menu for PhoneBookEntry, and select Add Implementation, which opens the Business Object Implementation - SmartGuide to the Name and Data Access Pattern page.
3. Define the implementation.

1. Select the Delegating radio button from the Pattern for Handling State Data group box.
2. Ensure that the Create a new one now radio button is selected from the Data Object Interface group box. This option allows you to define the business object attributes that need to be preserved in the data object.

4. Go to the Data Object Interface page.
5. Click the All>> button to move the attributes in the Business Object Attributes list to the State Data list.
6. Click the Finish button.

The PhoneBookEntryBO business object implementation is now under the PhoneBookEntry interface, and the PhoneBookEntryDO data object interface is now under the PhoneBookEntryBO business object implementation.

You will need to implement the showAll method. Select the PhoneBookEntryBO implementation. Select the showAll
method from the Methods pane. Add the following code in the source pane:

`lnm = iDataObject->lastName();`
`fnm = iDataObject->firstName();`
`ext = iDataObject->extNumber();`
`zip = iDataObject->internalZip();`

#### Creating the Data Object Implementation

To create the data object implementation and to connect the data object implementation to the persistent object, perform the following procedure.

1. From the User-Defined Business Object folder, select the PhoneBookEntryDO data object interface.
2. Open the pop-up menu for PhoneBookEntryDO, and select Add Implementation. This displays the Data Object Implementation - SmartGuide.
3. Set the environment on the Behavior page.

1. Set the BOIM with any key radio button from the Environment group box to indicate that the data object is part of a component installed in a business object application adaptor with instances being located by key objects.
2. Set the Transient radio button from the Form of Persistent Behavior and Implementation group box.
3. Click the Next button to continue to the Implementation Inheritance page.

4. On the Implementation Inheritance page, verify that IBOIMExtLocalToServer::IDataObjectBase is selected as parent.
5. Click the Finish button.
6. The PhoneBookEntryDOImpl data object implementation is now under the PhoneBookEntryDO interface.

##### Implementing the CRUD methods

1. With PhoneBookEntryDataObjectImpl selected, expand File Adornments in the methods pane. Then select Prolog and add "# include <PBEPO.ih>" in the source pane.
2. For each the CRUD methods (under Framework methods in the methods pane):

1. Select the method.
2. Right click and select Properties.
3. Check Use the implementation defined in the editor pane. Then Finish.
4. Add the implementation of the method in the source editor pane.

3. Implement the insert method using the following code:

`PBEPO *pbepo = new PBEPO();`
`pbepo->setNAME1(lastName());`
`pbepo->setNAME2(firstName());`
`pbepo->setEXT_(extNumber());`
`pbepo->setZIP(internalZip());`
`pbepo->insert();`
`delete pbepo;`

4. Implement the update method using the following code:

`PBEPO *pbepo = new PBEPO();`
`pbepo->setNAME1(lastName());`
`pbepo->setNAME2(firstName());`
`pbepo->setEXT_(extNumber());`
`pbepo->setZIP(internalZip());`
`pbepo->update();`
`delete pbepo;`

5. Implement the retrieve method using the following code:

`PBEPO *pbepo = new PBEPO();`
`pbepo->setNAME1(lastName());`
`pbepo->retrieve();`
`firstName(pbepo->getNAME2());`
`extNumber(pbepo->getEXT_());`
`internalZip(pbepo->getZIP());`
`delete pbepo;`

6. Implement the del method using the following code:

`PBEPO *pbepo = new PBEPO();`
`pbepo->setNAME1(lastName());`
`pbepo->del();`
`delete pbepo;`

#### Defining the Managed Object

To add the managed object:

1. From the User-Defined Business Object folder, select the PhoneBookEntryBO business object implementation.
2. Open the pop-up menu for PhoneBookEntryBO, and select Add Managed Object, which opens the Managed Object - SmartGuide to the Name and Application Adaptor page.
3. Click the Finish button.

#### Generating the Code

To generate the application code:

1. From the User-Defined Business Object folder, select PhoneBookEntry.
2. Open the pop-up menu for PhoneBookEntry, and select Generate > All.

Code generation starts. Progress is indicated in the lower-left corner of the window.

### Creating Client and Server DLL Files

The defined objects need to be built into two separate DLL files.

- One that runs on the client and provides access to the business object interface, key and copy helper.
- One that runs on the server and provides access to the managed object and the rest of the component.

The client DLL file needs to be defined before the server DLL file. When the server DLL file is defined, it needs to link to the client DLL file. After defining the objects that comprise each DLL file, these files can be built.

#### Defining the Client DLL File

To add the client DLL file:

1. Select the Build Configuration folder.
2. Open the pop-up menu for Build Configuration, and select Add client DLL. This displays the Name and Option page of the Add Client DLL - SmartGuide.
3. Type `pbeC` in the Name field.
4. Click the Next button to continue to the Client Source Files page.
5. Click the All>> button to move the client source files to the Items chosen list.
6. Click the Finish button.

The pbeC client DLL file is now under the Build Configuration folder.

#### Defining the Server DLL File

To add the server DLL.

1. Select the Build Configuration folder.
2. Open the pop-up menu for Build Configuration, and select Add Server DLL. This displays the Name and Option page of the Server DLL - SmartGuide.
3. Type `pbeS` in the Name field.
4. Type `/DHWSNT4 /I..\..\..\IMSWeb\include` in the CPP Compile Options field.
5. Type `pbe.lib hwstran.lib "..\..\..\IMSWeb\lib\win\"` in the Link Options field.
6. Click the Next button to continue to the Server Source Files page.
7. Click the All>> button to move the server source files to the Items chosen list.
8. Click the Next button to continue to the Libraries to Link With page.
9. Click the All>> button to move all the files from the Items Available list to the Items chosen list.
10. Click the Finish button.

The pbeS server DLL file is now under the Build Configuration folder.

#### Generating the makefiles

To generate the makefiles to build the configuration:

1. Select the Build Configuration folder.
2. Open the pop-up menu for Build Configuration, and select Generate > All > All Targets.

The code generation begins.

### Packaging the Application

Packaging the application consists of the following procedures:

1. Creating the application family
2. Defining the application
3. Creating the container instance
4. Configuring the managed object
5. Generating the application

#### Creating the Application Family

To add the application family:

1. Select the Application Configuration folder.
2. Open the pop-up menu for Application Configuration, and select Add Application Family. This displays the Name page of the Application Family - SmartGuide.
3. Type `pbeAppFam` in the Name field.
4. Click the Finish button.

The pbeAppFam application family is now under the Application Configuration folder.

#### Defining the Application

To add the Application:

1. Select the pbeAppFam application family.
2. Open the pop-up menu for pbeAppFam, and select Add Application, which opens the Add Application - SmartGuide to the Name and Environment page.
3. Type `pbeApp` in the Application Name field.
4. Click the Finish button.

The pbeApp application is now under the pbeAppFam application family.

#### Creating the Container Instance

To add the new container instance:

1. Select the Container Definition folder.
2. Open the pop-up menu for Container Definition, and select Add Container Instance, which opens the Container - SmartGuide.
3. Type `pbeContainer` in the Name field.
4. On the Services page select Use no Object Services radio button and check Enable persistent references.
5. Go to the Data Access Patterns page.
6. On this page, ensure that the Delegating check box is set under Business Object and check the Local Copy check box under Data Object.
7. Click the Finish button.

The pbeContainer container is now under the Container Definition folder.

#### Configuring the Managed Object

To add the managed object for the Application:

1. Select the pbeApp application.
2. Open the pop-up menu for pbeApp, and select Add Managed Object, which opens the Configure Managed Object - SmartGuide.
3. In this window:

1. Verify that PhoneBookEntryMO PhoneBookEntryMO is in the Managed Object field.
2. Click the Next button to continue to the Data Object Implementations page.

4. On this page:

1. Select Implementation.
2. Open the pop-up menu for Implementation, and select Add.
3. Select PhoneBookEntryDOImpl PhoneBookEntryDOImpl from the Data Object Implementation list.
4. Click the Next button to continue to the Container page.

5. On this page, select pbeContainer from the Name list.
6. Click the Next button to continue to the Home page.
7. On this page, select BOIMHomeOfRegHomes from the Home Name list.
8. Click the Finish button.

The PhoneBookEntryMO managed object is now under the Application Configuration folder.

#### Generating the Applications

To generate the application family:

1. Select the pbeAppFam application.
2. Open the pop-up menu for pbeAppFam, and select Generate.

Note: | If you do not have InstallShield installed on your system, Click the Yes button when the dialog concerning InstallShield is displayed.

When code generation completes, the Method Implementation pane contains the pbeApp.ddl file. You can now save and close Object Builder.

### Building the Application - Client and Server

All imported and generated files are placed in the <CBroker>\samples\Imsotma\BusinessObjects\Working\NT directory.

1. Copy the .h, .hpp, and .ih files from <CBroker>\samples\Imsotma\pbe to <CBroker>\samples\Imsotma\IMSWeb\include
2. Copy pbe.lib from <CBroker>\samples\Imsotma\pbe to <CBroker>\samples\Imsotma\IMSWeb\lib\win
3. Change directory to:

      <CBroker>\samples\Imsotma\BusinessObjects\Working\NT

4. Enter:

      nmake -f all.mak

Everything in the sample application is built.

### Installing the Application

Installing an application consists of:

1. Loading the application
2. Configuring the application

These procedures assume that you are currently logged on to DCE and that you are currently using the System Manager User Interface. If not, logon to DCE and start the System Manager User Interface.

#### Loading the Application onto System Management

To install the pbe server application:

1. Copy the dll files in `<CBroker>\samples\Imsotma\IMSWeb\dlls` to `<CBroker>\bin`
2. Copy `<CBroker>\samples\Imsotma\pbe\pbe.dll` to `<CBroker>\bin`
3. Start the System Manager User Interface, if it is not already started.
4. Become an Expert user (View > User Level > Expert).
5. Expand Host Images, and select <your host name>.
6. From the pop-up menu, select Load Application. This opens the Load Application dialog.
7. Browse for and select pbeAppFam.ddl located in <CBroker>\samples\ImsotmaA\BusinessObjects\Working\NT\pbeAppFam.

#### Configuring the Application with System Management

To configure the application:

1. Configure the pbeApp application.

1. Expand Available Applications, and select pbeApp.
2. Open the pop-up menu for pbeApp, and select Drag.
3. Expand Management Zones > Sample Cell and Work Group Zone > Configurations, and select Sample Configuration.
4. Open the pop-up menu for Sample Configuration, and select Add Application.

2. Define the server.

1. Expand Management Zones > Sample Cell and Work Group Zone > Configurations, and select Sample Configuration.
2. Open the pop-up menu of Sample Configuration, and select New > Server (free standing). This displays a new dialog box.
3. Type `pbeSrv` as the name for the server group.
4. Click the OK button. The pbeSrv is now under Server (free standing).

3. Associate the application with the server.

1. Expand Management Zones > Sample Cell and Work Group Zone > Configurations > Sample Configuration > Applications, and select pbeApp.
2. Open the pop-up menu of pbeApp, and select Drag.
3. Expand Management Zones > Sample Cell and Work Group Zone > Configurations > Sample Configuration > Server (free standing), and select pbeSrv.
4. Open the pop-up menu of pbeSrv, and select Configure Application.

4. Configure the server with the host.

1. Expand Management Zones > Sample Cell and Work Group Zone > Configurations > Server (free standing), and select pbeSrv
2. From the pop-up menu for pbeSrv, select Drag.
3. Expand Hosts, and select your server.
4. From the pop-up menu for your server, select Configure Server (free standing).

5. Activate the configuration.

1. Expand Management Zones > Sample Cell and Work Group Zone > Configurations, and select Sample Configuration.
2. Open the pop-up menu for Sample Configuration, and select Activate, which automatically starts the application server. Wait for a completion message in the Action Console window before continuing.

# Developing the client

The IMS/OTMA sample code contains a client program which exercises the CRUD methods. Note that since the business object is neither sessionable nor transactional, we need to use the checkpointToDatastore method in order to check point the object data to the data store. The checkpointToDatastore method causes the update method to be invoked on the data object. We could use also the method refreshFromDatastore to reset the state of the business object to the its previous state when the last update was invoked on the data object. Here are some fragments of the client code showing the use of these methods.

`....`
`#include <IBOIMManagedObjectFriendQOS.hh>`
`....`

`IBOIMManagedObjectFriendQOS::IMMixin_var chkPtPtr =`
`IBOIMManagedObjectFriendQOS::IMMixin::_narrow(pbePtr);`
`if( CORBA::is_nil(chkPtPtr)) {`
`cout << "*** Unable to narrow to a mixin" << endl;`
`return 1;`
`}`

`cout << ">>>> Checkpointing to datatore....." << endl;`
`chkPtPtr->checkpointToDatastore();`
`cout << ">>>> Refreshing from datastore to make sure that data has been updated"`
`<< endl;`

`chkPtPtr->refreshFromDatastore();`
`.......`

# Running the Sample Application

For IVP install instructions for IMS, see IMS/ESA Version 6 Install Volume 1. The entire book contains information on installing and configuring the IVP sample. Chapter 11, entitled "Install/IVP Application", discusses the sample IMS application.

To run the sample client application:

1. Copy the `pbeclient.mak` and `pbeclient.cpp` from `<CBroker>\samples\Imsotma\Application to <CBroker>\samples\Imsotma\BusinessObjects\Working\NT`
2. Change directory to `<CBroker>\samples\Imsotma\BusinessObjects\Working\NT`
3. Enter: `nmake -f pbeclient.mak`
4. Enter: `pbeclient`