Skip Headers
Oracle® Fusion Middleware WebLogic Tuxedo Connector Programmer's Guide for Oracle WebLogic Server
12c Release 1 (12.1.1)

Part Number E24979-01
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

8 Oracle WebLogic Tuxedo Connector JATMI VIEWs

This chapter describes how to use Oracle WebLogic Tuxedo Connector VIEW buffers.

This chapter includes the following sections:

Overview of Oracle WebLogic Tuxedo Connector VIEW Buffers

Note:

For more information on Oracle Tuxedo VIEW buffers, see "Using a VIEW Typed Buffer" in Programming a Tuxedo ATMI Application Using C at http://download.oracle.com/docs/cd/E13203_01/tuxedo/tux100/pgc/pgbuf.html.

Oracle WebLogic Tuxedo Connector allows you to create a Java VIEW buffer type analogous to an Oracle Tuxedo VIEW buffer type derived from an independent C structure. This allows Oracle WebLogic Server applications and Oracle Tuxedo applications to pass information using a common structure. Oracle WebLogic Tuxedo Connector VIEW buffers do not support FML VIEWs or FML VIEWs/Java conversions.

How to Create a VIEW Description File

Note:

fbname and null fields are not relevant for independent Java and C structures and are ignored by the Java and C VIEW compiler. You must include a value (for example, a dash) as a placeholder in these fields.

Your Oracle WebLogic Server application and your Oracle Tuxedo application must share the same information structure as defined by the VIEW description. The following format is used for each structure in the VIEW description file:

$ /* VIEW structure */
VIEW viewname 
type cname fbname count flag size null 

where

Table 8-1 VIEW Description File Fields

Field Description
type 

Data type of the field. Can be set to short, long, float, double, char, string, carray, or dec_t (packed decimal).

cname 

Name of the field as it appears in the information structure.

fbname 

Ignored.

count

Number of times field occurs.

flag

Specifies any of the following optional flag settings:

  • N—zero-way mapping

  • C—generate additional field for associated count member (ACM)

  • L—hold number of bytes transferred for STRING and CARRAY

size

For STRING and CARRAY buffer types, specifies the maximum length of the value. This field is ignored for all other buffer types.

null

User-specified NULL value, or minus sign (-) to indicate the default value for a field. NULL values are used in VIEW typed buffers to indicate empty C structure members.

The default NULL value for all numeric types is 0 (0.0 for dec_t). For character types, the default NULL value is `\0'. For STRING and CARRAY types, the default NULL value is " ".

Constants used, by convention, as escape characters can also be used to specify a NULL value. The VIEW compiler recognizes the following escape constants: \ddd (where d is an octal digit), \0, \n, \t, \v, \r, \f, \\, \', and \".

You may enclose STRING, CARRAY, and char NULL values in double or single quotes. The VIEW compiler does not accept unescaped quotes within a user-specified NULL value.

You can also specify the keyword NONE in the NULL field of a VIEW member description, which means that there is no NULL value for the member. The maximum size of default values for string and character array members is 2660 characters.


Example VIEW Description File

The following provides an example VIEW description which uses VIEW buffers to send information to and receive information from an Oracle Tuxedo application. The file name for this VIEW is infoenc.

Example 8-1 Example VIEW Description

VIEW infoenc
#type    cname    fbname  count flag size null
float    amount   AMOUNT  2     -    -    0.0
short    status   STATUS  2     -    -    0
int      term     TERM    2     -    -    0
char     mychar   MYCHAR  2     -    -    -
string   name     NAME    1     -    16   -
carray   carray1  CARRAY1 1     -    10   -
dec_t    decimal  DECIMAL 1     -    9    - #size ignored by viewj/viewj32
END

How to Use the viewj Compiler

To compile a VIEW typed buffer, run the viewj command, specifying the package name and the name of the VIEW description file as arguments. The output file is written to the current directory.

To use the viewj compiler, enter the following command:

java weblogic.wtc.jatmi.viewj [options] [package] viewfile

To use the viewj32 compiler, enter the following command:

java weblogic.wtc.jatmi.viewj32 [options] [package] viewfile

The arguments for this command are defined as follows:

Argument Description
options
  • -associated_fields:

    Use to set AssociatedFieldHandling to true. This allows set and get accessor methods to use the values of the associated length and count fields if they are specified in the VIEW description file. If not specified, the default value for AssociatedFieldHandling is false.

  • -bean_names:

    Use to create set and get accessor names that follow JavaBeans naming conventions. The first character of the field name is changed to upper case before the set or get prefix is added. The signature of indexed set accessors for array fields changes from the default signature of void setAfield(T value, int index) to void setAfield(int index, T value).

  • -compat_names:

    Use to create set and get accessor names that are formed by taking the field name from the VIEW description file and adding a set or get prefix. Provides compatibility with releases prior to WebLogic Server 8.1 SP2. Default value is -compat_names if -bean_names or -compat_names is not specified.

  • -modify_strings:

    Use to generate different Java code for encoding strings sent to Oracle Tuxedo and decoding strings received from Oracle Tuxedo. Encoding code adds a null character to the end of each string. Decoding code truncates each string at the first null character received.

  • -xcommon:

    Use to generate output class as extending TypedXCommon instead of TypedView.

  • -xtype:

    Use to generate output class as extending TypedXCType instead of TypedView.

Note: -compat_names and -bean_names are mutually exclusive options.

package
The package name to be included in the .java source file.

Example: examples.wtc.atmi.simpview

viewfile
Name of the VIEW description file.

Example: Infoenc


For example:

How to Pass Information to and from a VIEW Buffer

The output of the viewj and viewj32 command is a .java source file that contains set and get accessor methods for each field in the VIEW description file. Use these set and get accessor methods in your Java applications to pass information to and from a VIEW buffer.

The AssociatedFieldHandling flag is used to specify if the set and get methods use the values of the associated length and count fields if they are specified in the VIEW description file.

Use one of the following to set or get the state of the AssociatedFieldHandling flag:

How to Use VIEW Buffers in JATMI Applications

Use the following steps when incorporating VIEW buffers in your JATMI applications:

  1. Create a VIEW description file for your application as described in How to Create a VIEW Description File.

  2. Compile the VIEW description file as described in How to Use the viewj Compiler.

  3. Use the set and get accessor methods to pass information to and receive information from a VIEW buffer as described in How to Pass Information to and from a VIEW Buffer.

    See the examples/wtc/atmi/simpview/ViewClient.java file in your Oracle WebLogic Server distribution for an example of how a client uses accessors to pass information to and from a VIEW buffer.

  4. Import the output of the VIEW compiler into your source code.

  5. If necessary, compile the VIEW description file for your Oracle Tuxedo application and include the output in your C source file as described in "Using a VIEW Typed Buffer" in Programming a Tuxedo ATMI Application Using C at http://download.oracle.com/docs/cd/E13203_01/tuxedo/tux100/pgc/pgbuf.html.

  6. Configure a WTCServer MBean with a Resources Mbean that specifies the VIEW buffer type (VIEW or VIEW32) and the fully qualified class name of the compiled Java VIEW description file. The class of the compiled Java VIEW description file should be in your CLASSPATH.

  7. Build and launch your Oracle Tuxedo application.

  8. Build and launch your Oracle WebLogic Server Application.

How to Get VIEW32 Data In and Out of FML32 Buffers

A helper class is available to add and get VIEW32 data in and out of an FML32 buffer. The class name is wtc.jatmi.FViewFld. This class assists programmers in developing JATMI-based applications that use VIEW32 field type for FML32 buffers.

No change to configuration is required. You still configure the VIEW32 class path using the ViewTbl32Classes attribute in the WTCResources section of the WLS configuration file.

The following access methods are available in this helper class.

  • FViewFld(String vname, TypedView32 vdata);

  • FviewFld(FviewFld to_b_clone);

  • void setViewName(String vname)

  • String getViewName();

  • void setViewData(TypedView32 vdata)

  • void TypedView32 getViewData();

Example 8-2 How to Add and Retrieve an Embedded TypedView32 buffer in a TypedFML32 Buffer

String toConvert = new String("hello world");
TypedFML32 MyData = new TypedFML32(new MyFieldTable());
Long d1 = new Long(1234);
Float d2 = new Float(12.32);
MyView data = new myView();
FviewFld vfld;
data.setamount((float)100.96);
data.setstatus((short)3);
vfld = new FviewFld("myView", data);

try {
  myData.Fchg(MyFieldTable.FLD0, 0, toConvert);
  myData.Fchg(MyFieldTable.FLD1, 0, 1234);
  myData.Fchg(MyFieldTable.FLD2, 0, d2);
  myData.Fchg(MyFieldTable.myview, 0, vfld);
} catch (Ferror fe) {
  log("An error occurred putting data into the FML32 buffer.  The error is " + fe);
}

try {
  myRtn = myTux.tpcall("FMLVIEW", myData, 0);
} catch(TPReplyException tre) {
….
}
TypedFML32  myDataBack = (TypedFML32)myRtn.getReplyBuffer();
 Integer myNewLong;
 Float myNewFloat;
 myView View;
 String myNewString;

try {
  myNewString = (String)myDataBack.Fget(MyFieldTable.FLD0, 0);
  myNewLong = (Integer)myDataBack.Fget(MyFieldTable.FLD1, 0);
  myNewFloat = (Float)myDataBack.Fget(MyFieldTable.FLD2, 0);
  vfld = (FviewFld)myDataBack.Fget(MyFieldTable.myview, 0);
  view = (myView)vfld.getViewData();
} catch (Ferror fe) {
  ….
}

The following code listing is an example FML Description(MyFieldTable) related to the example in Example 8-2.

*base 20000 
#name    number  type   flags   comments
FLD0     10      string -       -
FLD1     20      long   -       -
FLD2     30      float  -       -
myview   50      view32 -       defined in View description file

Using the XmlViewCnv Class for XML to and From View/View(32) Translation

Use the XmlViewCnv class to perform XML to View /View(32) or View/View(32) to XML translation. The following code listing is an example that uses the XmlViewCnv class for conversion to and from XML buffer formats.

import examples.wtc.atmi.simpview.infoenc; // View class import
weblogic.wtc.gwt.XmlViewCnv; 
import weblogic.wtc.jatmi.TypedBuffer;

public class xml2view
{
   public static void main(String[] args) {
      String xmlDoc = 
      "<VIEW32><infoenc><amount>1000.0</amount><infoenc></VIEW32>";

      infoenc convertMe = new infoenc();
      convertMe = (infoenc) XmlViewCnv.XMLToView(
         xmlDoc,
         convertMe.getClass(),
         convertMe.getSubtype());

      convertMe = (infoenc) echo.Echo(convertMe);

      result = XmlViewCnv.ViewToXML(
         (TypedBuffer) convertMe, 
         convertMe.getClass(), 
         true);

      System.out.println(result);
   }
}