Chapter 3   Working With Data Objects


The applications programmer needs to be able to understand and know how to use the UIF API to develop a servlet, or EJB, which communicates with the EIS. The UIF API is an object oriented framework.

The iPlanet Application Server Enterprise Connector for CICS is used to execute CICS functions on a remote CICS server. The servlet or EJB uses the CICS connector to access the CICS server.

This chapter describes the procedures for acquiring UIF objects and executing function objects.

The following topics are described:

• Data Objects

• UIF API Naming Conventions

• Working with Servlet Samples

• Deploying a Connector Application

Data Objects

---

A data object is used by UIF to represent data or metadata in a generic fashion.

Data objects are used to exchange data between a servlet and UIF, and between UIF and the connector.

The iPlanet Application Server Enterprise Connector for CICS allows you to access data through the data object interface.

The data object interface:

• presents a unified representation of EIS data types

• represents complex data

• supports most common primitive data types.

The types of data objects are:

• Primitive Objects

• Structure Objects

• Array Objects

• Type Information Objects

Primitive Objects

A primitive data type object, see Figure 3-1 contains a single value of one of the following types:

• integer, float, double

• fixed length string, variable length string

Figure 3-1    Primitive Object

integer, float, double

Integer, float, and double data type objects hold a value whose type corresponds to the Java data type.

When a primitive data object is assigned to a list, array, or structure; the data object is unwrapped and its value is copied into the list, array or structure. The data object itself is not used. When a primitive value is obtained by using an untyped get method, such as getField(), getElem(), getAttr(), or getCurrent(), the returned value is wrapped in a primitive data object. In this case, the value is copied. Modifying the returned primitive data object does not change the source object.

fixed length string, variable length string

Strings correspond to the Java string data type. A fixed length string has a maximum length, whereas a variable length string has no restrictions by the connector or UIF.

The maximum length of a fixed-length string is set when the string's initial value is specified, for example four characters as shown in the following line:

list.addElemFString("abcd")

A fixed length string is truncated if it is longer than the string's initial value.

Structure Objects

Structure objects, see Figure 3-2, contain other data objects or primitive values as fields. Each object within the structure object is referred to by a string that represents the field name. Field names have a maximum length of 64 characters. A structure's fields are heterogeneous.

Figure 3-2    Structure Object

Circular references are not allowed. iPlanet Application Server Enterprise Connector for CICS prevents a data object being used as an attribute of itself. Indirect circular references are not checked

---

Caution

An error message is not generated if an indirect circular reference is defined. Unpredictable results occur if a circular reference is used at runtime.

---

.

Array Objects

An array object, see Figure 3-3, contains data objects or primitive values as elements in the object. Array elements must be homogeneous. Each element within the array object is referred to by an integer that specifies its position in the array object.

Figure 3-3    Array Object

Type Information Objects

Type information objects are structured objects that contain the type information of a data object; for example, the definition of the fields in a structure and the fields corresponding data types see Table 3-1. Instances of data objects can be created of type information objects. Each of these instances contain a reference to a type of information object. Numerous data types can share the same type information object.

Table 3-1    Type Information Objects

DataObjectInfo Type	Target Object
IBSPDataObjectPrimitiveInfo describes the type number, size of value (if type is string or binary), and the default value.	IBSPDataObjectPrimitive
IBSPDataObjectStructureInfo describes the type information of all fields of the target structure. The type information of each field is in turn described by a type information object.	IBSPDataObjectStructure
IBSPDataObjectListInfo describes the initial capacity and maximal element count of the target list.	IBSPDataObjectList
IBSPDataObjectArrayInfo describes the initial capacity, maximal element count and the type information of elements of the target array.	IBSPDataObjectArray

UIF API Naming Conventions

---

Methods in the UIF API conform to a naming convention that specifies the following:

• operation

• target

• type

The following example shows a UIF API method:

getElemString()

get is the operation, Elem is the target, and String is the type.

Operation

There are many types of operations but the two most commonly used are:

• get

• set

Target

The targets are:

• None (primitive)

• Attr (complex DataObject such as a list, array, or structure) that uses path to address attribute.

  In the API, methods of the IBSPDataObject interface do not distinguish between an element in an array and a field in a structure; an element or field is referred to as an attribute.

  The path to an element is its element number, beginning from zero. The path to a field is its field name. Element numbers and field names can be combined to create paths to attributes in complex data objects, such as a field of a structure that contains a list of elements. In this case, you specify the path as the individual attributes separated by periods (.); for example, use "field1.[01]" to identify the first element of a list at field1 in the structure.

• Elem (list/array) uses index to address element.

• Field (structure) uses name to address field.

• Current (itr) addresses object iterator is currently on.

Type

The types of operations are:

• Int

• Float

• Double

• String

• FString

• DataObject

• None

Changing Attribute Types

An attribute type can not be changed. Code Example 3-1 causes an error because it tries to change the primitive object type from integer to float.

Code Example 3-1    Changing Data Types

---

list.addElemInt (100) ; // assume 100 is added to element 1

list.setElemFloat (1, 3.14) ; // fails because the type of element is int

You can change the data type of non-primitive, as in the following example:

list.addElemDataObject (aStruct) ; // add a structure is to element 1

list.setElemDataObject (1, array) ; // change to array succeeds

Working with Servlet Samples

---

To execute an operation the servlet must be capable of the following:

• Acquiring the UIF Runtime Object

• Creating the Service Provider Object

• Creating Function Objects

• Setting Up and Executing the Function Object

The following examples show how to carry out these tasks.

Acquiring the UIF Runtime Object

The runtime object is the entry point into UIF. It is both the object factory and the access point for creating other objects.

Code Example 3-2 shows how to acquire a runtime object.

Code Example 3-2    Acquiring the UIF Runtime Object

---

private IBSPRuntime getRuntime()

{

com.kivasoft.IContext _ctx =

((com.netscape.server.servlet.platformhttp.PlatformServletContext)

getServletContext()).getContext();

IBSPRuntime ibspruntime = access_cBSPRuntime.getcBSPRuntime          (_ctx, null, null);

return ibspruntime;

}

Creating the Service Provider Object

The service provider object is the logical representation of a connection to an EIS. Typically, the service provider object is not bound to a physical connection until it is absolutely necessary. A service provider must be enabled before it can be used.

Code Example 3-3 shows how to create the service provider object.

Code Example 3-3    Creating the Service Provider Object

---

private IBSPServiceProvider getServiceProvider(IBSPRuntime runtime)

{

deb.println("Before createServiceProvider()");

if (runtime != null)

return runtime.createServiceProvider("CICS", "CICS_sp1");

else

deb.println("runtime is null");

return null;

}

.

Table 3-2 defines the function object parameters

Table 3-2    Standard Provider Object Types

Parameter	Definition
CICS	Data source name
CICS_sp1	Service provider name

Creating Function Objects

A function object is a group of related operations that share a common state. In iPlanet Application Server for CICS, a function object needs to be set up and associated with a service provider before the function object can be executed.

Function object definitions, which represent business methods available for execution on the specific enterprise systems, are derived from metadata mined from the enterprise system.

Code Example 3-4 shows how to create the function object.

Code Example 3-4    Creating the Function Object

---

IBSPFunctionObject fn = null;

...

if(   runtime != null )

{

deb.println("Before getServiceProvider()");

sp = getServiceProvider(runtime);

deb.println("After getServiceProvider()");

if( sp != null )

{

deb.println("Before createFunctionObject()");

fn = runtime.createFunctionObject("CICS", "phonebook");

}

}

Table 3-3 defines the function object parameters.

Table 3-3    Function Object Parameters

Parameter	Definition
CICS	Data source name
phonebook	Function name

Setting Up and Executing the Function Object

To Set Up and Execute the Function Object

1. Specify and enable the service provider.

2. Set the WebUserId that represents the web domain and that is mapped to the EIS domain.

   Refer to "CICS User Management", for details.

3. Prepare the function object, set up the propertySet, and set the input parameters in the function object's dataBlock.

4. Execute the function object.

5. Retrieve the output parameters from the function block.

6. Disable the service provider.

Code Example 3-5 shows how to set up and execute the function object.

Code Example 3-5    Setting Up and Executing the Function Object 

---

private dataRecord executePB(IBSPRuntime runtime, IBSPServiceProvider sp,

String requestCode, dataRecord input) throws BspException

{

int hr = 1;

IBSPFunctionObject fn = null;

IBSPDataObject data = null, prop = null;

String lastname = new String("");

String firstname = new String("");

String extension = new String("");

String zipcode = new String("");

dataRecord o_entry = null;

if( (runtime != null) && (sp != null) )

{

fn = runtime.createFunctionObject("CICS", "phonebook");

hr = sp.enable();

if( fn != null )

{

hr = fn.useServiceProvider(sp);

hr = fn.prepare(requestCode);

data = fn.getDataBlock();

if( data != null )

{

data.setAttrFString("INPUT.REQC", requestCode);

data.setAttrFString("INPUT.LNAME",input.m_lastName);

data.setAttrFString("INPUT.FNAME",input.m_firstName);

data.setAttrFString("INPUT.EXTENTION",input.m_extension);

data.setAttrFString("INPUT.ZIPC",input.m_zipcode);

prop = fn.getProperties();

if( prop != null )

{

prop.setAttrInt("CONNECTION.StubReason",0 );

}

hr = fn.execute();

if( hr == 0 )

{

data = fn.getDataBlock();

if( data != null )

{

deb.println("MSG: "+data.getAttrFString("OUTPUT.MSG"));

deb.println("REQC: "+data.getAttrFString("OUTPUT.REQC"));

lastname = data.getAttrFString("OUTPUT.LNAME");

deb.println("LNAME: "+lastname);

firstname = data.getAttrFString("OUTPUT.FNAME");

deb.println("FNAME: "+firstname);

extension = data.getAttrFString("OUTPUT.EXTENTION");

deb.println("EXTENTION: "+extension);

zipcode = data.getAttrFString("OUTPUT.ZIPC");

deb.println("ZIPC: "+zipcode);

o_entry = new dataRecord(lastname, firstname, extension, zipcode);

o_entry.m_message = new String(data.getAttrFString("OUTPUT.MSG"));

}

prop = fn.getProperties();

if(prop != null)

{

deb.println("APPLID: "+prop.getAttrFString("CONNECTION.Applid"));

deb.println("LU: "+prop.getAttrFString("CONNECTION.LU"));

...

}

} // if(hr == 0)

else

deb.println("Search Failed");

} // if(data != null)

else

deb.println("Search Failed");

} // if( fn != null )

else

deb.println("Search Failed");

hr = sp.disable();

} // if( (runtime != null) && (sp != null) )

else

deb.println("Search Failed");

return o_entry;

}

CICS User Management

The application programmer provides a WebUserId to the CICS Enterprise connector, which determines the CICS authorization context to be used to process the request. The WebUserId must be set with the configuration structure of the service provider before enabling by calling the enable() method.

Code Example 3-6 illustrates how to set WebUser test as the WebUserId before enabling the service provider.

Code Example 3-6    Setting WebUserId

---

// Create runtime

IBSPRuntime runtime = getRuntime();

if(runtime != null )

{

// Create Service Provider

sp = getServiceProvider(runtime);

if(sp != null )

{

// Get Service Provider config structure

IBSPDataObject config=sp.getConfig();

// Setting WebUser-test in the WebUserId field of the config structure

config.setAttrFString("WebUserId",WebUser-test);

fn = runtime.createFunctionObject("CICS", "BAPI_CUSTOMER_GETDETAIL");

hr = sp.enable();

}

}

........

Deploying a Connector Application

---

A developer creates an application on a development machine and then deploys the application to an application server. Deployment of an application includes installing all application files and registering all components on the destination server.

You can deploy the servlet in one of the following ways:

• Using the Deployment Tool

• Using the Command Line to Deploy

In addition to deploying the servlet you must create and import the XML files, which describe the function objects, to the repository. For more details on how to do this, see the iPlanet Application Server Enterprise Connector for CICS Administrator's Guide, Chapter 3 - Managing Data: The Data Mining Tool.

Using the Deployment Tool

The iPlanet Application Server Deployment Tool is a GUI-based tool allows you to:

• Package J2EE Application Components Into Modules

• Assemble the Module Into a Deployable Unit

• Deploy the Unit to One or More iPlanet Application Server Operating Environments

Package J2EE Application Components Into Modules

J2EE application components are archived into modules according to the container that receives them upon deployment. You can archive J2EE application components into an EJB JAR module (archived with a .jar extension) or a Web Application module (archived with a .war extension). Each module also contains a J2EE and an iPlanet Application Server specific deployment descriptors saved to XML files.

Assemble the Module Into a Deployable Unit

J2EE modules that comprise an application are assembled into a single application Enterprise Archive (.ear) file. The application .ear file also contains a J2EE deployment descriptor saved to an XML file. Depending on your requirements, the .ear file might also contain alternate deployment descriptor XML files to be used in deployment.

---

Note	.ear archives are meant to be cross platform and works no matter where you build the archive. For example, you can successfully deploy .ear files that you have built on NT to Solaris and vice versa.

---

Deploy the Unit to One or More iPlanet Application Server Operating Environments

At deployment, the .ear file is copied to the targeted iPlanet Application Server environments. Some archived application files are automatically distributed to their appropriate directories on one or more instances on the iPlanet Application Server and then registered with the iPlanet Application Server. For example, static HTML files,

Using the Command Line to Deploy

A Web Application Module can be deployed as a standalone unit or can be packaged with other modules to create an application.ear file. The .ear file contains all the modules with the application components required to run an application, along with component level and application level deployment descriptor files.

After you create an .ear file or a module that you may want to deploy, you may want to register it automatically via a batch file at a scheduled time and date. In this case, you would create the .ear file or module as you normally would using the Deployment Tool, but you would not use the tool for deployment.

For more detailed information on deployment, consult the Deployment Tool Outline Help, which installs as part of the iPlanet Application Server Deployment Tool.