Using the Editors

For COM and EJB components and three-tier applications, you must create and deploy service components in addition to your screens. Even though all distributed application architectures use service components, each technology needs product-specific settings and defines services differently. For developers, this means that a service component created for one product will need modifications before it can work with another technology.

This chapter lists general instructions for creating and defining service components. Additional information can be found in the Application Development Guide as well as the manuals for each of the different products.

Creating and Saving Service Components

When you create a new service component in the editor, it displays a window in which you define the widgets participating in the service and add programming code.

Figure 7-1 In all environments, a service component has characteristics to distinguish it from a screen. Note the icon in the upper left corner of the window and the different wallpaper.

How to Create a Service Component

1. Choose FileNewService Component. An untitled service component opens.
2. Create the data members by placing widgets from the Create menu or Create tool bar onto the component.
3. Add code to the component. JPL procedures can be added by choosing ProceduresJPL Procedures.
4. For COM and EJB, the component interface must be defined. From the menu, choose ViewComponent Interface. This brings up a window where you can define methods and properties and specify product-specific settings.

In JetNet and Tuxedo applications, the screen wizard can generate service components at the same time that it is creating client screens. Each service component is identical to the client screen except that it has no push buttons and no menu/toolbar controls since there is no direct interaction between a user and a service component.

Services for the service component are defined for the root table view of the service component. For more information on wizard-generated output, refer to page 4-25, "Output for JetNet and Oracle Tuxedo Applications."

Identifying Service Components

Since you can have different types of windows open in the editor at the same time, you can identify service components in the following ways:

• The Screen Type property. Under Identity, the Screen Type property is set to Component.

• The Type field in the Properties window. If a component has focus, the Type field displays Component.

• The service component's icon and wallpaper.

Opening and Saving Service Components

Additional information is available:

• For information about opening service components in a Panther library, refer to "Opening Application Components."

• For information about saving service components to a library, refer to "Saving an Application Component." Information specific to COM components is in "Saving COM Components" and to EJBs is in "Saving Service Components and Generating EJBs".

Defining the Component Interface

Part of creating the service component is defining the component interface, which is the set of methods and properties the component will support. From the menu, choose ViewComponent Interface. This brings up a window containing settings for methods and properties as well as the necessary settings for the specific technology.

Note: JetNet and Tuxedo applications do not use the Component Interface window.

Defining Methods

Methods are functions or procedures available to the component. These procedures define actions to be performed when the methods are invoked, and they usually receive and/or return values.

The Methods section displays the methods defined for a particular component. Each row in the grid corresponds to a method. The first column shows the method's return type. The second column shows the method's name. The third column shows the method's parameters (in order, and prefixed by their kind and type).

A method can be implemented by a JPL procedure that is in scope when the form is opened at runtime or by a C function (the name of the JPL procedure or C function, however, does have to be the same as the component method's name).

Java processing is associated with the component by specifying the Java class in the service component's Java Tag property.

How to Add or Change a Method

1. Choose Change.

   The Change Methods dialog opens.

2. To add a method:

   • In the New Method column, select the name of any existing component-level JPL procedure and use the arrow buttons to move items between the columns.

   • In the New Method field at the bottom, type the name of a new method and press Enter.

     The Add Parameters for Method dialog opens.

3. To change a method:

   • Select an existing method and choose Copy or Modify or double-click.

     The Copy Parameters for Method or the Change Parameters for Method dialog opens.

You set the return type on the Add, Change, or Copy Parameters for Method dialogs by selecting one of the following: Void, String, Integer, Boolean, Double, or Object.

Parameters

Parameters are arguments that are passed between the client application and the service component. They may be passed only in one direction, or they may be passed back and forth.

How to Add a Parameter to the Method

1. Enter the name of a new parameter in the New Parameter field and press Enter, or select a parameter from the Service Widgets column. You can also select an existing parameter and choose Modify or double-click it.

   The Add Parameter or Change Parameter dialog opens.

2. Define the following:

   • Type—Set to String, Integer, Boolean, Double, or Object.

   • Array—Select the Array check box if applicable. Parameters may be arrays of data.

   • Kind—Set to In/Out, In, or Out, depending on whether the parameter is to be provided by the client, returned to the client, or if a value is to be sent and another returned in its place.

3. Choose OK.

The Template button on the Add Parameters for the Method dialog writes template JPL for the method to the clipboard; it can then be pasted to another file.

Defining Properties

Properties are variables that provide state information about the application.

The Properties section displays all the properties supported by the component. Each row in the grid corresponds to a Panther variable, either a widget on the component or a JPL variable. The order in which the properties appear does not affect the component's functionality.

The first column shows the property's type. The second column shows whether or not the property is read-only. The third column shows the property's name.

Figure 7-2 The Properties tab card displays type, name and read-only information for the properties of a component.

How to Add or Modify a Property

1. Choose Change.

   The Change Properties dialog opens.

   

   Figure 7-3 The Change Properties dialog allows you to add, insert or modify the property settings.

2. To add new properties:

   • In the New Property column, select an existing item and use the arrow buttons to move items between columns.

   • In the New Property field at the bottom, type the name of a new property and press Enter.

     The new property name appears in the grid.

3. To change the settings for a property, select the property in the grid and choose Modify or double-click on the property.

   The Change Properties dialog opens.

4. Define the following:

   • Type—Set to String, Integer, Boolean, Double, or Object.

     The value in the field or JPL variable that implements the property will be converted to this type and handed to the client when a client requests the value of the property.

   • Array—Select the Array check box if applicable.

   • Read-only—Select the Read-only option. Check the box if applicable.

     If the property is marked Read-only, clients can get its value but not set it.

---

COM Applications

A Panther COM component consists of an implementation file (.dll) and a DCOM installation file (.inf). These all have the same base name as the service component. The DLL is generated from a template called PrlServer.dll (in the config directory of the Panther installation directory). It is copied to the application directory and renamed to the name of the component. The application directory and template DLL can be changed in the COM section of the component interface screen.

• When you save service components for COM, they all must be saved in the same directory. The Directory field allows you to specify the directory in which the .dll file will be stored.

• You have the option of specifying a version number. If you change the version number, the resulting component can be registered on a system along with the previous version. Client applications can call a specific version; if no version number is specified, the latest version will be accessed.

• Under Advanced Options, the PrlServer.dll field allows you to use a .dll other than the default PrlServer.dll. This allows you to add custom code by installing your own C functions. The source to PrlServer.dll can be found in the comlink directory.

• Under Advanced Options, you have the option of changing the component's Class ID (CLSID). This identifier is automatically generated when the component is first created. You should change it only if you are generating a new component from an existing one and they must have distinct identities. For example, the CLSID should be changed when changing the version.

How to Generate a New CLSID

Press the New button on the COM tab card. You need to do this if:

• You modify an existing method or property of a distributed COM component. An interface is a contract between the component and the other software components that access it. If you modify the interface of a distributed component being used by other programs, you must generate a new Class ID. Adding a new method or property does not require generating a new Class ID, though updating the version number is recommended.

• You use one component as a template for another, and wish to save the component in the editor under a new name. Note that merely changing the name is not enough to define a new component. The Class ID is the unique identifier that COM uses to distinguish one component from another.

• If you change the version and want the old version to remain available, you should use a new CLSID for the new version.
  

  Figure 7-4 The COM tab card allows you to set DLL directories and to change the CLSID.

Saving COM Components

To save a service component, choose FileSave AsLibrary Member, enter a name, and choose the library to save it in, generally server.lib. When you save a service component, you are asked whether to generate a new type library (.tlb) for it. If you are saving the component for the first time, or you have changed the interface definition for the component since the last time the component was saved, you should choose Yes. Otherwise, you can choose No.

You can view the contents of a type library using Microsoft tools such as COM/OLE Object Viewer (oleview.exe, part of Microsoft's Visual C++ compiler).

Deploying COM Components

For more information on instantiating a COM component in a client screen, refer to Chapter 4, "Building Client Screens," in COM/MTS Guide.

For more information on deploying COM components, refer to Chapter 5, "Deploying COM Components," in COM/MTS Guide.

Enterprise JavaBeans

A Panther Enterprise JavaBean consists of a series of Java classes, home and remote interfaces, a deployment descriptor and any environment settings needed for deployment. The Java classes are compiled and packaged in a JAR and then the EJB is installed with the WebSphere middleware so that it can be located in response to client requests.

The corresponding Panther service component must be located in one of the libraries specified in an application's SMFLIBS directory, or, by default, in server.lib in the server's base directory, if it is to be found at runtime.

The EJB's methods will be implemented either by JPL, Java or C code accessed from that form. To use C or C++ functions to implement an EJB's methods, the functions must be built into a shared library and that library must be loaded, and the relevant functions installed, using the functions sm_slib_load and sm_slib_install.

For more information on Panther EJBs, refer to Panther for IBM WebSphere Developer's Studio.

The Panther EJB Tab Card

The Panther EJB card has three sections.

• General—Specify the directory into which the files for the component should be generated. Optionally, you can also specify a package name and a JNDI home name. Panther uses the service component name as the default JNDI home name.

• Transaction—Specify the transaction attributes for the bean. Optionally, you can also specify transactions for specific methods.

• Environment—Optionally, specify environment variables for the bean.

General

1. Specify the directory name for component file generation.
2. Optionally, specify the Java package name for the EJB's bean class, home interface, and remote interface if you wish the files to be compiled into a specific package.
3. Optionally, specify the Java Naming and Directory Interface (JNDI) name by which clients will invoke the EJB at runtime. Panther uses the service component name by default.

1. Choose the Transaction Attribute from the drop down menu.

   • TX_BEAN_MANAGED

   • TX_MANDATORY

   • TX_NOT_SUPPORTED

   • TX_REQUIRES_NEW

   • TX_REQUIRED

   • TX_SUPPORTS

     For descriptions of the attributes, refer to "Transaction Attribute Settings" in Panther for IBM WebSphere Developer's Studio.

2. Choose the Isolation Level from the drop down menu.

   • SERIALIZABLE

   • REPEATABLE_READ

   • READ_COMMITTED

   • READ_UNCOMMITTED

     For descriptions of the isolation levels, refer to "Isolation Level Settings" in Panther for IBM WebSphere Developer's Studio.

3. Optionally, double click on a specific method name to specify values other than the default for the transaction attribute and isolation level.

1. Specify Name and Value.
2. Choose Set.

To save a service component, choose FileSave AsLibrary Member, enter a name, and choose the library to save it in, generally server.lib.

When you save a service component, you are asked if you wish to generate the files needed to deploy the component. You can choose to generate the EJB's Java files, and, in addition, to compile and package the EJB, depending on whether IBM WebSphere Application Server is installed locally or remotely.

You can also select ToolsGenerate Component to generate the EJB.

For more information on building and generating EJBs, including a description of the files generated, refer to Chapter 5, "Building Enterprise JavaBeans," in Panther for IBM WebSphere Developer's Studio.

Deploying EJBs on IBM WebSphere Application Server

The specifics of deployment depend on whether or not IBM WebSphere Application Server is installed locally. Panther installs the EJB if the application server is available; if not, additional steps are necessary.

To call EJBs built with Panther, the deployed JAR file, built or added to when the EJB is packaged and compiled, needs to be on the CLASSPATH for the client. Users deploying applications must copy these JAR files to every machine that they wish to act as EJB clients.

For more information on deploying Panther EJBs, refer to Chapter 6, "Deploying Enterprise JavaBeans in WebSphere," in Panther for IBM WebSphere Developer's Studio.

JetNet and Oracle Tuxedo Applications

Services in JetNet and Oracle Tuxedo applications are the subroutines necessary for an application to access a resource manager, such as a database. Service components for JetNet and Tuxedo are visual representations of these services. For more information, refer to Chapter 5, "Defining Services in JetNet and Oracle Tuxedo Applications," in JetNet/Oracle Tuxedo Guide.

Using Wizard-Generated Service Components

When you generate a client screen and a service component, they are identical because a service component interacts with its client screen counterpart to transfer data to and from the appropriate services. The client screen and service component pair must be kept parallel. Thus, if you modify your client screen, you must also modify its corresponding service component in a similar fashion. This is true of selection screens and their corresponding selection service components.

Note: Visual modifications (such as color, fonts, and pixmaps) on the client screen need not be duplicated on the service component.

Testing Service Components

You can test a service component to see if the appropriate data is passed from the database to the service component. This requires a direct database connection rather than connecting to the database by way of the application server.

For more information on testing service components, particularly in JetNet and Oracle Tuxedo applications, refer to "Testing Screens and Service Components" in Application Development Guide.