WebLogic Tuxedo Connector Programmer's Guide
WebLogic Tuxedo Connector JATMI VIEWs
The following sections provide information about how to use WebLogic Tuxedo Connector VIEW buffers:
Overview of WebLogic Tuxedo Connector VIEW Buffers
Note: For more information on Tuxedo VIEW buffers, see Using a VIEW Typed Buffer.
WebLogic Tuxedo Connector allows you to create a Java VIEW buffer type analogous to a Tuxedo VIEW buffer type derived from an independent C structure. This allows WebLogic Server applications and Tuxedo applications to pass information using a common structure. 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 WebLogic Server application and your 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
- The file name is the same as the VIEW name.
- You can have only one VIEW description per file.
- The VIEW description file is the same file used for both the WebLogic Tuxedo Connector
viewj
compiler and the Tuxedo viewc
compiler.
- viewname is the name of the information structure.
- You can include a comment line by prefixing it with the # or $ character.
- The following table describes the fields that must be specified in the VIEW description file for each structure.
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:
|
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 \Q\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 a Tuxedo application. The file name for this VIEW is infoenc
.
Listing 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
init 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
|
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.
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).
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.
Use to generate different Java code for encoding strings sent to
Tuxedo and decoding strings received from Tuxedo. Encoding
code adds a null character to the end of each string. Decoding
code truncates each string at the first null character recieved.
Use to generate output class as extending TypedXCommon
instead of TypedView.
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:
- A VIEW buffer is compiled as follows:
java weblogic.wtc.jatmi.viewj -compat_names
examples.wtc.atmi.simpview infoenc
- A VIEW32 buffer is compiled as follows:
java weblogic.wtc.jatmi.viewj32 -compat_names -modify_strings
examples.wtc.atmi.simpview infoenc
How to Pass Information to and from a VIEW Buffer
The output of the viewj
and view
j32
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.
set
methods set the count for an array field and set the length for a string or carray field.
- Array
get
methods return an array that is at most the size of the associated count field.
- String and carray
get
methods return data that is at most the length of the associated length field.
Use one of the following to set or get the state of the AssociatedFieldHandling
flag:
- Use the -
associated_fields
option for the viewj
and viewj32
compiler to set the AssociatedFieldHandling
flag to true..
- Invoke the
void setAssociatedFieldHandling(boolean state)
method in your Java application to set the state of the AssociatedFieldHandling
flag.
- If false, the
set
and get
methods ignore the length and count fields.
- If true, the
set
and get
methods use the values of the associated length and count fields if they are specified in the VIEW description file.
- The default state is false.
- Invoke the
boolean getAssociatedFieldHandling()
method in your Java application to return the current state of AssociatedFieldHandling
.
How to Use VIEW Buffers in JATMI Applications
Use the following steps when incorporating VIEW buffers in your JATMI applications:
See the examples/wtc/atmi/simpview/ViewClient.java
file in your WebLogic Server distribution for an example of how a client uses accessors to pass information to and from a VIEW buffer.
- Import the output of the VIEW compiler into your source code.
- If necessary, compile the VIEW description file for your Tuxedo application and include the output in your C source file as described in Using a VIEW Typed Buffer.
- 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.
- Build and launch your Tuxedo application.
- Build and launch your WebLogic Server Application.