|
Oracle® Application Server Integration InterConnect User's Guide
10g Release 2 (10.1.2) B14069-02 |
|
 Previous |
 Next |
|
Oracle® Application Server Integration InterConnect User's Guide
10g Release 2 (10.1.2) B14069-02 |
|
|
Previous |
Next |
This appendix describes how to use the Data Definition Description Language (D3L) in its native format message to application view translations. It contains the following topics:
This section contains these topics:
D3L is an XML-based message description language. It describes the structure that an application's native, non-XML format message (also called the native view of the application) must follow to communicate with OracleAS Integration InterConnect. Oracle provides the following OracleAS Integration InterConnect transport adapters that interact with the D3L message description language:
FTP
HTTP
MQ Series
SMTP
OracleAS Integration InterConnect Adapters perform the following tasks:
Validate the D3L message description files during run-time initialization.
Use the D3L translation engine (subcomponent of the bridge) to translate messages from:
Native format message to application view
Application view to native format message
Transport message payload data between an application and OracleAS Integration InterConnect.
Some applications do not use XML as native message payload format. These applications use native formats, such as structured records of bytes and characters. For these native formats to be successfully translated into a format understood by other applications, the messages content must follow a predefined, structured set of rules. This structured format can then be translated into an application view, transformed into a common view, and understood by other applications.
D3L provides both a predefined, structured set of rules and translation capabilities for native format messages. D3L provides:
An XML-based message description language that describes the contents of native format messages
A translation engine that uses the instructions defined in the D3L file to translate the native format message contents to and from an application view
The D3L descriptions must comply with a syntax defined by the D3L document type definition (DTD). D3L enables you to describe the record layout of binary, string, structured, and sequence data. Use D3L only when the number of fields in the underlying native format message is fixed and known. D3L is not suitable for the following:
Descriptions of arbitrarily structured data like regular XML
Name-value pair data
Conditional data structures, which require token look-aheads to parse
This section describes data definition description language enhancements. It includes the following topics:
This enhancement enables the Data Definition Description Language (D3L) author to add a new type of member, property. Syntax, to a D3L structure, in addition to fields and pads. For example:
<struct ... ... <property name="prop_name" /> ... </struct>
|
Note: There is no type definition associated with this structure element. |
The modified D3L Data Type Definition (DTD) for this new structure element is:
<!ENTITY % StructElements "field | property | pad" > <!ELEMENT property EMPTY > <!ATTLIST property %FieldAttributes; >
The semantics of this new structure element is to link data in a transport protocol header with the message payload. In other words, when a D3L containing a structure with one, or more, property member(s) is imported in iStudio, it will create a String OAI attribute with the name specified in the property name attribute.
At runtime, this OAI attribute will be populated with the value of a transport protocol header, inbound–to-hub, which name matches the name attribute of the property member. Simlarly, for outbound messages, the OracleAS Integration InterConnect message payload property value will define the value of the corresponding protocol header.
For example, if using OracleAS Integration InterConnect Adapter for FTP, the file structure would be:
<struct ..> <property name="filename" /> <field ...
In this case, the OracleAS Integration InterConnect Application View attribute filename, that is derived from the D3L definition, would be assigned the name of the actual file being passed to D3L. For outbound message, the value will determine the physical filename being used to store the file.
If using OracleAS Integration InterConnect Adapter for HTTP, an example file structure would be:
<struct ..> <property name="Host" /> <property name="Referer" /> <field name="...> < ...
|
Note: This is a dynamic payload dependent feature, which will override settings in theadapter.ini file and Application View Meta Data Modify Fields. As a result, the property ota.send.endpoint could be overridden by a corresponding message attribute defined through the D3L.
|
The D3L syntax enables you to create multiple nested imparrays for outbound translations (app-to-native or hub-to-spoke).
Multiple nested imparrays can be created to match multiple nested arrays in XML as XML does not have the need to declare the length of an array. For example:
<array1> <array2>..</array2> <array2>..</array2> </array1> <array1> <array2>..</array2> <array2>..</array2> <array2>..</array2>
If this XML message was published by OracleAS Integration InterConnect Adapter for AQ, and consumed by OracleAS Integration InterConnect Adapter for FTP that is running in D3L mode, the preceding structure would then be matched by the following D3L structure:
<imparray id="array1"> <imparray id="array2"> ..
As D3L does not perform parsing for app-to-native translation, also known as production, the preceding D3L is entirely possible. However, for native-to-app translations, the preceding D3L would be invalid as a single imparray by itself would consume the rest of the native message.
|
Note: This new imparray semantics depart from the design principle that D3L is a fully bidiretional symmetric translator and can perform bothnative-to-app and app-to-native translation using just one the same D3L definition.
|
Finally, the D3L translator will determine, at runtime, whether multiple nested imparrays exist in a D3L. If multiple nested imparrays are detected, the translator will prevent the D3L from being used for parsing purposes (native-to-app translations). If not detected, the D3L translator will flag an error condition.
This section provides an example of how the contents of a native format message are:
Described in a D3L file
Configured with the required D3L file
To successfully translate the native format message, you need to satisfy both the preceding conditions.
This section contains the following topics:
This section describes an application's native format message (named price) that contains data for updating the price of personal computer model number 2468 to 199.99. The native message uses the following format to describe the data:
message ::=actionmodelprice
| Where... | Is... |
|---|---|
action
|
UPDATE_PRICE
|
model
|
2468
|
price
|
199.99
|
The data must strictly follow the structure defined in a D3L file, for this example, price.xml. This D3L translation engine translates the data into an application view. shows how a D3L file defines the structure that the native format message price must follow to successfully define the data elements.
Figure C-1 Native Format Message Payload Data and D3L File Syntax
All three data elements are defined as strings with different delimiters for separating their data.
When the D3L translation engine receives a native format message, such as price, it must determine the exact D3L file to verify the native format message contents, such as, price.xml.
This section describes the methods for configuring the correct D3L file with the native format message. It contains the following topics:
The ota.d3ls parameter in the %ORACLE_HOME%\integration\interconnect\adapters\application\adapter.ini file enables you to define the D3L file to use with the native format message. For example:
ota.d3ls=price.xml
When the D3L translation engine receives the native format message from the bridge, it retrieves the correct D3L file based on this parameter setting. Multiple D3L files can also be defined using the ota.d3ls parameter. For example:
ota.d3ls=price.xml,emp.xml,booking.xml
Unless one of the methods described in "Message Header Attributes" is used, the D3L translation engine compares the data structure in the native format message to each D3L file until it finds the correct one to use for translation.
The D3L file includes message header attributes work with the D3L engine to choose the correct D3L file for translating a native format message to an application view. The values for these message header attributes match the settings in the native format message.
Message header attribute values override the approach of comparing each D3L file defined with the ota.d3ls parameter in the adapter.ini file with a native format message.
Two methods to set the message header attribute values are available:
Both methods enable the D3L translation engine to use the correct D3L file for translation after receiving the native format message.
|
Note: When the correct D3L file is selected and a successful translation has taken place, themessage element attributes name and object in the D3L file define the OracleAS Integration InterConnect event name and business object, respectively.
|
OracleAS Integration InterConnect Adapters, such as the HTTP adapter, make their protocol level transport properties available to the D3L translation engine, including custom properties added by a sender application, such as an HTTP client. The D3L file message element enables the user to specify two attributes, header and value, which match the protocol level headers in a received native format message.
For example, a third-party application uses the custom transport header D3L-Header to communicate with the D3L translation engine which D3L file to use to translate an incoming native format message. The following steps must be performed to set custom values in the transport header:
Set the D3L-Header parameter in the transport message header to a value that matches the value attribute setting of the <message> element in the D3L file.
Set the header attribute of the <message> element in the D3L file to D3L-Header to match the D3L-Header parameter name in the transport message header.
illustrates using the HTTP adapter where D3L-Header and price are the header name and header value, respectively. The header name and value are used to match a native format message with the correct D3L file. The D3L translation engine retrieves the correct D3L file based on these settings.
Figure C-2 Name/Value Pair Message Header Attributes
The D3L engine supports a rudimentary pattern matching capability in the value attribute of the D3L message element.
A D3L author can create a D3L definition, such as:
<message type="CrtCust" header="filename" value="cust_create%" ...
This definition is for the FTP adapter, which provides a header property called filename that holds the name of a received file.
The preceding D3L destination will be selected to parse incoming files whose filenames match the name pattern in the value attribute, such as,
cust_create01 cust_create02 po_int_ext01 cust_create03 po_int_ext02
The "wildcard" character in the pattern ("%") can only appear at two places in the attribute string-value, as either the first or the last character, or both the first and last characters.
For example, the following patterns are acceptable:
%endstring : such as %.csv
startstring%: such as po_int%
%substring%: such as %create%
You can set the magic attribute of the message element in the D3L file to match the first n bytes of data in a native format message. This feature enables you to define the D3L file to use with the native format message. When a native format message is received by the D3L translation engine, the magic values of all D3L files are compared with the first n bytes of the native format message. The magic values must be long enough to be unique across all registered D3Ls for a given adapter instance.
provides an example where *UPDATE_PRICE is the value that configures the native format message with the correct D3L file.
Figure C-3 Magic Value Message Header Attribute
The D3L translation engine retrieves the correct D3L file based on these settings.
The D3L attribute startsat of the message element enables the D3L author to specify the byte location to start the magic matching.
Having this attribute allows the D3L definition:
<?xml version="1.0" encoding="US-ASCII"?> <!DOCTYPE message SYSTEM "d3l.dtd"> <message name="newBook" type="BookType" object="BookObj" magic="ISBN#" startsat="12">
This D3L definition will trigger if a native message contains the byte character sequence ISBN# in byte positions 12 to 16.
This section describes the contents of a sample D3L file named book_reply.xml.
1 <?xml version="1.0" encoding="US-ASCII"?> 2 <!DOCTYPE message SYSTEM "d3l.dtd"> 3 <message name="replyFlight" type="BookingReplyType" object="Booking" 4 header="D3L-Header" value="replyOptions"> 5 <unsigned4 id="u4" /> 6 <unsigned2 id="u2" /> 7 <struct id="DateTimeRecord"> 8 <field name="DateInfo"> 9 <date format="MMDDYY"> 10 <pfxstring id="datstr" length="u4" /> 11 </date> 12 </field> 13 <field name="TimeHour"><limstring delimiter="*" /></field> 14 <field name="TimeMinute"><limstring delimiter="*" /></field> 15 </struct> 16 <struct id="ItinRecord"> 17 <field name="DepartureTime"><typeref type="DateTimeRecord" /></field> 18 <field name="ArrivalTime"><typeref type="DateTimeRecord" /></field> 19 </struct> 20 <pfxarray id="ItinArray" length="u2"> 21 <typeref type="ItinRecord" /> 22 </pfxarray> 23 <struct id="BookingReplyType"> 24 <field name="AirportCodeFrom"><limstring delimiter="*" /></field> 25 <field name="AirportCodeTo"><limstring delimiter="*" /></field> 26 <field name="Itineraries"><typeref type="ItinArray" /></field> 27 </struct> 28 </message>
Lines 1 and 2
These lines define standard information, such as the Prolog and Document Type Declaration (DTD) that must have the specified values (for example, specifying d3l.dtd as the DTD).
These lines define the following message element attributes:
name: It must correspond to the associated Oracle Application Server Integration InterConnect application view event name defined in iStudio. The D3L file can also be imported in iStudio when defining the message attributes of an event (the name of which must match the name attribute of the D3L message element).
type: It names a structure that is defined in subsequent lines of this D3L file.
object: It must match the Oracle Application Server Integration InterConnect business object defined in iStudio.
header: It is identified in the set of protocol level transport message headers associated with a native format message.
value: It must match the actual value of the corresponding protocol level transport message header defined through the header attribute.
Lines 5 and 6
These lines define an unsigned, four-byte integer and unsigned, two-byte integer. These data type declarations are named u4 and u2, respectively, so they can be referred to later.
Lines 7 Through 15
These lines define the following fields of a structure named DateTimeRecord:
DateInfo defines a date format of MMDDYY and a length prefixed by an unsigned four-byte integer.
TimeHour defines a string delimited by the character *.
TimeMinute defines a string delimited by the character *.
Lines 16 Through 19
These lines define the fields of the structure named ItinRecord. The fields DepartureTime and ArrivalTime both consist of the DataTimeRecord structure.
Lines 20 Through 22
These lines define a length-prefixed array named InitArray, where each array element is of type ItinRecord.
Lines 23 Through 28
These lines define the following fields of the message structure BookingReplyType, which satisfies the BookingReplyType type declaration in the message document element:
AirportCodeFrom is a string delimited by the character *.
AirportCodeTo is a string delimited by the character *.
Itineraries is a field of type ItinArray, which is an array of ItinRecord.
D3L supports use of the following data types and declarations in a D3L file:
D3L supports signed or unsigned integers that can be one, two, four, or eights octets in size, and in big or little endian octet ordering.
Example C-1 Quantity Field
<field name="quantity"> <unsigned4 endian="big" align="6"/> </field>
The quantity field defines a four byte unsigned binary integer, using big (default) endian, and at an alignment of 6 bytes. For example, D3L will ensure that the reading or writing of this integer will start at a position in the buffer, so that <position> modulus <alignment> = 0.
|
Note: Little Endian means that the low-order byte of the number is stored in memory at the lowest address, and the high-order byte at the highest address. whereas Big Endian means that the high-order byte of the number is stored in memory at the lowest address, and the low-order byte at the highest address.
|
Data example
Byte addresses (hex):
00 01 02 03 04 05 06 07 08 09 0A 0B
Byte (hex):
00 00 00 00 00 00 80 FF FF FF 00 00
Parsed value (dec):
quantity = 128x2563 + 255x2562 + 255x2561 + 255x2560 = 2164260863
Example C-2 Weight and Length Field
<field name="weight"> <unsigned2 align="3"/> </field> <field name="length"> <unsigned2 align="3"/> </field>
The weight and length fields define two 2-byte unsigned binary integers, using big endian, and an alignment of 3 bytes.
Data example
Byte addresses (hex):
.. 07 08 09 0A 0B 0C 0D 0E ..
Byte (hex):
.. 00 00 EE 88 00 22 F0 00 ..
Parsed value (dec):
weight = 238x2561 + 136x2560 = 61064 length = 34x2561 + 240x2560 = 8944
Example C-3 Temperature and Pressure Field
<field name="temperature"> <signed2 endian="little" /> </field> <field name="pressure"> <unsigned4 endian="big" /> </field> <field name="wind"> <unsigned2 endian="little" align="4" /> </field>
The temperature field defines a 2-byte signed binary integer, using little endian, and no alignment.
The pressure field defines a 4-byte unsigned binary integer, using big endian, and no alignment.
The wind field defines a 2-byte unsigned binary integer, using little endian, and a 4-byte alignment.
Data example
Byte addresses (hex):
.. 60 61 62 63 64 65 66 67 68 69 ..
Byte (hex):
.. EF FE 00 00 04 0A 00 00 3C 00 .. ^ ^ ^ little end big end alignment
Parsed value (dec):
temperature = 256x256 - (239x2560 + 254x2561) = -273 pressure = 4x2561 + 10x2560 = 1034 wind = 60x2560 + 0x2561 = 60
D3L supports single- and double-precision, IEEE format, floating-point data. Single-precision floating point numbers (floats) take up four bytes or octets. Double-precision floating point numbers (doubles) take up eight bytes or octets.
Example C-4 Distance and Age Field
<field name="distance"> <double align="6"/> </field> <field name="age"> <float /> </field>
The distance field defines an 8-byte double-float (floating-point value according to the IEEE 754 floating-point double precision bit layout), at an alignment of 6 bytes.
The age field defines a 4-byte single-float (floating-point value according to the IEEE 754 floating-point single precision bit layout).
|
Note: The IEEE 754 floating-point format is parsed and produced by the following Java class methods:
|
Data example
Byte addresses (hex):
.. 77 78 03 04 05 06 07 08 09 0A 0B xx xx ..
Byte (hex):
00 00 D2 47 D3 CE 16 2A B1 A1 5E 5D 6B 0B ..
^ double ^ float
Parsed value (dec):
distance = 1 x 1038 age = 1 x 1018
D3L supports the following string types:
Constant length strings without delimiters, with optional padding to fill out empty spaces.
Delimited strings can be delimited by an arbitrary delimiter character.
Length-prefixed strings where the length prefix is a numeric type. Numeric types are binary integer types described in "Signed or Unsigned Integers" or are a number stored as a string.
Strings terminated by a specified character.
Strings terminated by a delimiter defined by an enclosing limarry structure.
Four date formats: MMDDYY, DDMMYY, MMDDYYYY, DDMMYYYY, where the information is stored as a string in one of these formats with any separator character between month, date, and year, such as 12!24=01).
Numbers not defined as binary data, but as strings. Any string format can define a number (either an integer or a floating-point entity). In iStudio, a D3L field of type number is handled as a double.
Example C-5 Constant length strings
<field name="CURRENCY_CODE"> <padstring length="4" padchar=" " padstyle="tail"/> </field> <field name="COUNTRY_CODE"> <padstring length="2" padchar="" padstyle="none"/> </field> <field name="TO_USD_RATE"> <padstring length="12" padchar="0" padstyle="head"/> </field>
The CURRENCY_CODE field defines a fixed length string of four characters. Any blank (" ") characters (pads) near the end (padstyle="tail") of the string are not considered part of the data value.
The COUNTRY_CODE field defines a fixed length string of two characters. All characters in this field are part of the data value because padstyle is "none".
The TO_USD_RATE field defines a fixed length string of 12 characters. Any zeros at the beginning (padstyle="head") of the string are not considered part of the data value.
Data example
Native byte (character) stream:
GBP UK000012550.00
Parsed value s:
CURRENCY_CODE = 'GBP' COUNTRY_CODE = 'UK' TO_USD_RATE = '12550.00'
Example C-6 Delimited strings
<field name="State"> <limstring delimiter="." /> </field> <field name="Region"> <limstring delimiter="." /> </field> <field name="City"> <limstring delimiter="|" /> </field> <field name="Landmark"> <limstring delimiter="|" /> </field> <field name="Street"> <limstring delimiter="+" /> </field>
The "State", "Region", "City", "Landmark", and "Street" fields are delimited strings enclosed by ".", ".", "|", "|", and "+", respectively .
Data example
Native byte (character) stream:
.FL..Florida Keys.|Key West||Ernest Hemingway Museum|+Whitehead St.+
Parsed value s:
State = 'FL' Region = 'Florida Keys' City = 'Key West' Landmark = 'Ernest Hemingway Museum' Street = 'Whitehead St.'
Example C-7 Length prefixed strings
<unsigned1 id="ubyte1" /> <unsigned2 id="ubyte2" endian="little" /> <struct> <field name="user"> <pfxstring length="ubyte1" /> </field> <field name="encr_user"> <pfxstring length="ubyte2" /> </field>
The user field defines a string the length of which is defined by a 1-byte binary integer preceeding the string contents.
The encr_user field defines a string the length of which is defined by a 2-byte binary integer preceeding the string contents.
Data example
Byte addresses (hex):
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12
Characters:
03 j o e 0D 00 D U Z a c . 1 H K V m I Y
Parsed values:
user = 'joe' encr_user = 'DUZac.1HKVmIY'
Example C-8 Terminated strings
<field name="product"> <termstring endchar=","/ > </field>
<field name="ordered"> <termstring endchar=","/ > </field>
<field name="inventory"> <termstring endchar=","/ > </field>
<field name="backlog"> <termstring endchar=","/ > </field>
<field name="listprice"> <termstring endchar="\n"/> </field>
Each of the first four fields is populated with input characters until the terminating/ending character (endchar) is encountered (","). The last field ends with a linefeed.
Data example
Native byte (character) stream:
1020,16,18,,1580.00<LF>
Parsed values:
product = '1020' ordered = '16' inventory = '18' backlog = '' listprice = '1580.00'
|
Note: The backlog field is empty. |
Example C-9 Simple strings - simplestring
<limarray id="CSV_Type" contchar="," endchar="\n"> <simplestring/> </limarray> <struct> <field name="CSV"> <typeref type="CSV_Type"/> </field>
The CSV field references a type declaration "CSV_Type" to a delimited array. The array members are separated by comma (contchar=",") and end with linefeed (endchar="\n").
Data example
Native byte (character) stream:
5,18,2.5,255,78.75,9
Parsed values:
CSV[] = { '5', '18', '2.5', '255', '78.75', '9' }
Example C-10 Dates - date
<field name="StartDate"> <date format="MMDDYY"> <termstring endchar="\n"/> </date> </field> <field name="EndDate"> <date format="DDMMYY"> <termstring endchar="\n"/> </date> </field> <field name="Milestone"> <date format="MMDDYYYY"> <termstring endchar="\n"/> </date> </field> <field name="DueDate"> <date format="DDMMYYYY"> <termstring endchar="\n"/> </date> </field>
The fields contain dates representing the four date formats.
Data example
Byte stream (characters):
11/16/02<LF> 24/11/02<LF> 11/20-2002<LF> 23*11*2002<LF>
Parsed values:
StartDate = Sat Nov 16 00:00:00 PST 2002 EndDate = Sun Nov 24 00:00:00 PST 2002 Milestone = Wed Nov 20 00:00:00 PST 2002 DueDate = Sat Nov 23 00:00:00 PST 2002
|
Note: The D3L parser will accept any character between theDD, MM and YY(YY) characters in the native format, but will always produce the "/" separator when translating from application message format to native message format. Hours, minutes, and seconds are not parseable.
|
Example C-11 String based numbers
<unsigned1 id="u1" /> <pfxstring id="HueType" length="u1" /> <struct id="ColorDefinition"> <field name="Red"> <number> <padstring length="4" padstyle="head" padchar="0"/> </number> </field> <field name="Green"> <number> <pfxstring length="u1" /> </number> </field> <field name="Blue"> <number> <limstring delimiter="."/> </number> </field> <field name="Brightness"> <number> <termstring endchar="|"/> </number> </field> <field name="Hue"> <number> <typeref type="HueType"/> </number> </field> </struct>
The declared type u1 is an unsigned 1-byte integer (0-255). The second type declaration "HueType" is a length prefixed string, where the string length will be defined in a one-byte binary integer preceding the string contents.
The Red field is a number defined as a fixed length string of 4 characters, which can be padded with zeros at the beginning.
The Green field is a number defined as a length prefixed string, where the string length will be defined in a one-byte binary integer preceeding the string contents.
The Blue field is a number defined as a "." delimited string. The string beginning and end is demarcated by ".".
The Brightness field is a number defined as a string which is read from the current point until the ending character ("|") is encountered.
The Hue field is a number defined as a string of type "HueType".
Data example
Byte addresses (hex) and characters (hex values shown in italics):
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 0 1 2 8 03 1 2 8 . 2 5 5 . 0 . 7 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 5 3 3 3 3 | 08 0 . 6 6 6 6 6 6
Parsed values:
Red = 128.0 Green = 128.0 Blue = 255.0 Brightness= 0.753333 Hue = 0.666666
|
Note: The parsed numbers always internally become doubles. |
D3L supports structured types, such as ordered records containing other data types (predefined or user defined). Types can be nested to arbitrary depth. This means you can use structures of sequences of structures of sequences to any finite depth. Recursive, self referencing, and data structures are not supported in D3L.
All data fields in a message format description must be named. These names are used as Oracle Application Server Integration InterConnect message attribute names. All names within the same structure must be mutually unique.
Within a D3L file the first element should be message. The message element must refer to a struct (using the IDREF type attribute), which then becomes the top-level data structure of the message.
Example C-12 ColorDefinition Field
<message type="ColorDefinition" name="myEV" object="myBO"> <unsigned1 id="u1" /> <pfxstring id="HueType" length="u1" /> <struct id="ColorDefinition"> <field name="Red"> ... <field name="Green"> ...
|
Note: The top-level structure can be placed anywhere in the D3L file within the scope of themessage element.
|
D3L supports sequences, such as arrays of various types. These include:
Delimited arrays (with arbitrary separator and terminator characters)
Length-prefixed arrays (where the length is one of the numeric types)
Fixed-length arrays
Implicit-length arrays (which use all remaining data in the native format message to the end of the buffer)
The data being sequenced can be any other D3L type (predefined or user defined).
Example C-13 Delimited arrays
<field name="members"> <limarray contchar=";" endchar="."> <limstring delimiter="." /> </limarray> </field>
The members field becomes an array of data elements separated by semicolons (contchar=";"). The end of the array is marked by a period (endchar="."). Each data element in the array is a string delimited by a set of periods (delimiter=".").
Data example
Native byte (character) stream:
.John.;.Steve.;.Paul.;.Todd..
Parsed values:
members[] = { 'John', 'Steve', 'Paul', 'Todd' }
Example C-14 Length prefixed arrays
<unsigned2 id="u2" endian="little" align="4" />
<struct>
<field name="measurements">
<pfxarray length="u2" > <signed1 /> </pfxarray>
</field>
The measurements field becomes an array of signed 1-byte binary integers (signed1). The number of elements in the array is determined by the unsigned two-byte binary integer at the beginning of the array.
Data example
Byte addresses (hex):
.. 08 09 0A 0B 0C 0D 0E 0F 10 ..
Bytes (hex):
.. 06 00 FF A2 6C 24 0E 77 ..
Values (dec):
measurements[] = { -1, -94, 108, 36, 14, 119 }
Example C-15 Fixed length arrays
<field name="digits">
<fixarray length="10">
<number>
<termstring endchar="-">
</number
</fixarray>
The digits field becomes an array of numbers (doubles). Each number element in the native byte format is represented as a string which is terminated by a dash (endchar="-"). The number of elements in the array must always be 10 (length="10").
Data example
Native byte (character) stream:
1-2-3-4-5-6-7-8-9-0-
Parsed values:
digits[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 0.0 }
Example C-16 Implicit length arrays
<message name="addOrders" object="Order" type="OrdersType"> <number id="Number"> <termstring endchar="," /> </number> <number id="Price"> <termstring endchar=";" /> </number> <number id="Total"> <termstring endchar="\n"/> </number> <struct id="OrderLineType"> <field name="LineNo"> <typeref type="Number" /> </field> <field name="ProductNo"> <typeref type="Number" /> </field> <field name="Quantity"> <typeref type="Number" /> </field> <field name="LinePrice"> <typeref type="Price " /> </field> </struct> <struct id="OrderType"> <field name="OrderTotal"> <typeref type="Total" /> </field> <field name="OrderLines"> <limarray contchar="\n" endchar="\n\n"> <struct> <field name="OrderLine"> <typeref type="OrderLineType" /> </field> </struct> </limarray> </field> </struct> <number id="ID"> <termstring endchar="\n" /> </number> <imparray id="OrdersArrayType"> <struct> <field name="CustomerID"> <typeref type="ID" /> </field> <field name="CustomerName"> <termstring endchar="\n" /> </field> <field name="Order"> <typeref type="OrderType" /> </field> </struct> </imparray> <struct id="OrdersType"> <field name="OrdersArray"> <typeref type="OrdersArrayType" /> </field> </struct> </message>
The OrdersType structure consists of a single field OrdersArray which is an implicit array of three fields: a CustomerID, CustomerName and Order (of type OrderType). OrdersArrayType is an implicit array. As a result, it will consume all remaining bytes in the native byte input stream. The size of the array is first known when the input byte stream has been exhausted.
The OrderLines field is a (nested) array, where each array element is of type OrderLineType. The OrderLineType is a structure of four fields: LineNo, ProductNo, Quantity, and LinePrice.
This input stream must use the following structure to be parseable:
CustomerID CustomerName Order: OrderTotal OrderLines: LineNo, ProductNo, Quantity, LinePrice LineNo, ProductNo, Quantity, LinePrice ...
Data example
Native byte (character) stream:
1234 Boeing 1000 1,555,10,250.00; 2,666,10,750.00; 5678 Lockheed Martin 424 1,555,5,125.00; 2,777,1,100.00; 3,888,2,199.00;
Parsed values:
{OrdersArray=
[ { CustomerName=Boeing, CustomerID=1234.0,
Order=
{ OrderTotal=1000.0,
OrderLines = [
{OrderLine={LinePrice=250.0, ProductNo=555.0, Quantity=10.0,
LineNo=1.0}},
{OrderLine={LinePrice=750.0, ProductNo=666.0, Quantity=10.0,
LineNo=2.0}}
]
}
},
{ CustomerName=Lockheed Martin, CustomerID=5678.0,
Order=
{ OrderTotal=424.0,
OrderLines = [
{ OrderLine={LinePrice=125.0, ProductNo=555.0, Quantity=5.0,
LineNo=1.0}},
{ OrderLine={LinePrice=100.0, ProductNo=777.0, Quantity=1.0,
LineNo=2.0}},
{ OrderLine={LinePrice=199.0, ProductNo=888.0, Quantity=2.0,
LineNo=3.0}}
]
}
}
]
}
D3L supports data padding. Padding is unnamed gaps in a native format message that satisfy alignment constraints of the underlying native system. Padding is discarded in the Oracle Application Server Integration InterConnect application view message.
The following D3L example defines a number as a left-aligned string, which is padded at the end with blanks to a field width of 10.
<field name="Quantity">
<number>
<padstring length="10" padchar=' ' padstyle="tail" />
</number>
The following native byte (character) stream satisfies this format:
9876.5____
Pads can also be explicitly defined between fields in a structure by using the <pad> element.
The following D3L example shows two fields, which are separated by a pad of size 10.
<struct id="PROD"> <field name=PRODID"> <termstring endchar=";" /> </field> <pad length="10" /> <field name=PRODDESC"> <termstring endchar=";" /> </field> </struct>
The following native byte (character) stream would satisfy this format:
48682HW;~~~~~~~~~~WASHER AND DRYER; [...]
A comma-separated values (CSV) file consists of multiple lines. Each line contains values separated by commas that end when a new line is required:
a,b,c,d 1,2,3
The string types, termstring and simplestring, have been added to parse CSV files.
termstring: String type termstring is a variation of limstring. It requires only a terminating delimiter, but not a beginning delimiter. For example:
<termstring endchar="," />
This parses any string contents until encountering a comma.
simplestring: String type simplestring is a special data type. It is used when the nearest parent structure defines a valid set of delimiters, which for the current data definition description language (D3L) library is limited to limarray. For example:
<limarray contchar="," endchar="\n">
<simplestring />
</limarray>
The examples provided in the following sections use imparray so that input can be any number of elements, lines, or both.
This method assigns all CSVs on each line to named fields fixed number of fields per line. Example C-17 describes CSVs assigned to named fields.
Example C-17 CSVs Assigned to Named Fields
<message name="createPhone" object="Phone" type="phoneRecord">
<imparray id="lines">
<struct>
<field name="rectype"> <termstring endchar=","/ > </field>
<field name="quantity"><termstring endchar=","/ > </field>
<field name="endHour"> <termstring endchar=","/ > </field>
<field name="endMin"> <termstring endchar=","/ > </field>
<field name="cost"> <termstring endchar="\n"/> </field>
</struct>
</imparray> <struct id="phoneRecord">
<field name="csv"> <typeref type="lines" /> </field>
</struct>
</message>
The native format message payload for Example C-17 is as follows:
4,,9,22,2324.29 ,,,,, 55,2342,11,46,728372339.57
This method read all CSVs on each line into an array. There are variable number of fields per line. Example C-18 describes all the CSVs read into an array.
Example C-18 All CSVs are Read into an Array
<message name="createPhone" object="Phone" type="phoneRecord">
<limarray id="linearr" contchar="#44" endchar="\n">
<simplestring />
</limarray> <imparray id="myArray">
<struct>
<field name="line"> <typeref type="linearr" /> </field>
</struct>
</imparray> <struct id="phoneRecord">
<field name="csv"> <typeref type="myArray" /> </field>
</struct>
</message>
The native format message for Example C-18 is as follows:
4,,9,22,2324.29 55,2342,11,46,728372339.57 55,2342,11,46,728372339.57,4,,9,22,2324.29 1,2,3,4,5,6,7,8,9,0,1,2,3,4,5,6,7,8,9,0
The delimiters for limstring, termstring, and limarray are enhanced to allow multiple characters, as well as additional encoding styles. The associated ASCII table codes are shown in parentheses:
Escape code using "\": This works for "\r" (13), "\n" (10), "\t" (9), and "\f" (12).
where:
(13) is the ASCII code for a carriage return (CR)
(10) is the ASCII code for a line feed (LF)
(9) is the ASCII code for a horizontal tab (HT)
(12) is the ASCII code for a form feed (FF)
Escape ASCII code using "#": for example, "#13".
Escape ASCII hexadecimal code using "#x": for example, "#x0D".
End-of-file delimiter "\eof", which maps to a virtual end-of-file character: This delimiter can only be used once. No other fields can follow once it has been used.
Example C-19 provides several examples of delimiter encoding styles.
Example C-19 Delimiter Encoding Styles
<termstring endchar="#x2C"/> <termstring endchar="\n"/> <limarray id="linearr" contchar="," endchar="\r\n"> <simplestring/> </limarray> <termstring id="FileContents" endchar="\eof"/>
The "\r\n" on line 3 of Example C-19 represents a DOS line break. The "\eof" on the last line of Example C-19 represents an End of File.
This section provides information on the D3L translation engine and its files' integration with the OracleAS Integration InterConnect adapter agent and bridge subcomponents to perform events and translations. It contains the following topics:
Native Format Message to Common View Incoming Message Translations
Common View to Native Format Message Outgoing Messages Translations
The OracleAS Integration InterConnect Adapter agent reads .ini files (such as adapter.ini) at runtime to access each OracleAS Integration InterConnect adapter's configuration information. The OracleAS Integration InterConnect Adapter bridge are initialized and the configuration information provided by the OracleAS Integration InterConnect adapter agent. At the completion of a successful initialization, the OracleAS Integration InterConnect adapter bridge knows the following:
The Oracle Application Server Integration InterConnect application name and its default endpoint (message destination)
The various Oracle Application Server Integration InterConnect events to be handled by the OracleAS Integration InterConnect Adapter bridge
D3L files that describe each of these events
D3L files that are accessible and valid. If a file is invalid, then the OracleAS Integration InterConnect adapter cannot start
When the OracleAS Integration InterConnect adapter common transport layer detects an incoming message from an application, it receives the message in its native format. The message is then passed to the OracleAS Integration InterConnect adapter bridge. The bridge performs the following functions:
Using the D3L translation engine to translate the native format message into an application view an Oracle Application Server Integration InterConnect message object.
Raises an application view event
The agent transforms the application view event into a common view event and passes it on for further routing and processing. Table C-1 describes the data flow sequence if D3L message header attributes are used.
Table C-1 Message Header Attributes
| If The... | Then... |
|---|---|
|
The incoming native event might contain one of the following:
In the preceding cases, the bridge assumes that the matching D3L describes the incoming native event. Any conflicting header and value settings are detected and rejected by the bridge during initialization time. These operations are logged by OracleAS Integration InterConnect logging and tracing APIs for debugging, performance analysis, and business intelligence functions. |
|
|
A magic value is specified by using the following:
In the preceding cases, the bridge assumes the native event must be processed using the matching D3L. If multiple D3Ls specify magic values that may match the same native event, the bridge randomly picks a D3L. This can lead to undesirable bridge behavior because the resulting application view event raised may not be the correct one. |
depicts the data flow sequence.
Figure C-4 Native Format Message to Common View Incoming Messages
When a common view event is raised, the OracleAS Integration InterConnect Adapter agent subscribing to the event, performs the following:
Receives the associated message
Transforms it to an Oracle Application Server Integration InterConnect message object
Hands it to the OracleAS Integration InterConnect adapter bridge as an application view event
The OracleAS Integration InterConnect Adapter bridge queries the metadata associated with the event to determine the following:
The D3L file for the D3L translation engine for the translation of the application view event into a native format message.
The application to which the native format message event will be sent. There are two levels of rules to determine the application endpoint (the destination) of an OracleAS Integration InterConnect event:
If the event contains metadata that specifies an endpoint, then the bridge uses this endpoint for the event. With the exception of the MQ Series adapter, all OracleAS Integration InterConnect adapters follow this rule.
|
Note: Here the metadata itself names the endpoint and the content of the event is not searched. |
If the message metadata did not specify an endpoint, then the bridge uses its default endpoint, specified in the adapter.ini file, and made available to the bridge during initialization.
All OracleAS Integration InterConnect adapter operations are logged using the Oracle Application Server Integration InterConnect logging and tracing APIs for debugging, performance analysis, and other business intelligence functions.
shows the data flow sequence.
Figure C-5 Common View to Native Format Message Outgoing Messages
D3L is automatically installed with OracleAS Integration InterConnect.
|
See Also:
|
After installation, perform the following tasks to configure D3L:
Task 3: Create a D3L File Describing the Native Format Message
Task 5: Configure D3L with OracleAS Integration InterConnect Adapters
Task 7: Define Metadata Properties with Each Event (Optional)
You must define D3L in the browsers.init file. This enables you to import D3L files as attributes and select D3L as the message type in iStudio.
To integrate D3L with iStudio:
Use a text editor to open the
ORACLE_HOME\integration\interconnect\iStudio\browsers.init file.
Add the following information at the end of the file:
D3L;oracle.oai.agent.adapter.technology.D3LBrowser;
Save your changes and exit the file.
The native format is typically predefined by your third-party application.
Create a native format message. For example, this native format message updates the salary of employee number 33201 to 55000:
*UPDATE_EMPLOYEE_SALARY* 33201 |55000|
| Where... | Is... |
|---|---|
|
|
|
|
|
|
To create a D3L file (for example, updemp.xml) that describes the format of the native message:
Use a text editor. The following D3L file describes the contents of the native format message created in "Task 2: Create a Native Format Message".
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE message SYSTEM "d3l.dtd">
<message name="modify" object="Employee" type="modifyCommand"
header="D3L-Header" value="employee">
<struct id="modifyCommand">
<field name="action"><limstring delimiter="*"/></field>
<field name="EmployeeID"><limstring delimiter=" "/></field>
<field name="newSalary"><limstring delimiter="|"/></field>
</struct>
</message>
Store the D3L file in the ORACLE_HOME\integration\interconnect\adapters\application directory for direct access at deployment time.
Configure a native format message with the correct D3L file. This enables the D3L translation engine to use the correct D3L file to verify native format message contents. For example, the D3L file created in "Task 3: Create a D3L File Describing the Native Format Message" includes settings for name/value pair message header attributes:
<?xml version="1.0" encoding="US-ASCII"?> <!DOCTYPE message SYSTEM "d3l.dtd"> <message name="modify" object="Employee" type="modifyCommand" header="D3L-Header" value="employee">
These settings can match with the transport message header D3L-Header parameter name and employee value of a native format message:
POST /oai/servlet/transportServlet HTTP/1.1 Content-Type: application/x-www-form-urlencoded Host: acme.com:8888 Content-Length: 38 D3L-Header: employee
The adapter.ini file is read by the appropriate OracleAS Integration InterConnect Adapter at startup.
Use a text editor to open the
ORACLE_HOME\integration\interconnect\adapters\application\adapter.ini file.
In the preceding directory, application is the name of your application and the value of the application parameter in the adapter.ini file.
Ensure that parameter ota.type is set to the following value:
ota.type=D3L
This defines D3L as the message type for the OracleAS Integration InterConnect Adapter to handle incoming and outgoing messages.
Add the following line to define the D3L files for the bridge and D3L translation engine to use:
ota.d3ls=updemp.xml
where updemp.xml is the name of the D3L file created in "Task 3: Create a D3L File Describing the Native Format Message". Each event handled by the bridge must have its own D3L file. Whenever a new D3L file is imported in iStudio for use by an application, this parameter must be updated and the OracleAS Integration InterConnect adapter restarted.
Save your changes and exit the file.
iStudio enables you to import a D3L file for use with the following OracleAS Integration InterConnect features:
Common data types
Application data types
Published/subscribed events
Invoked/implemented procedures
Business object events and procedures
When a D3L file is associated with Oracle Application Server Integration InterConnect common data types, application data types, events, or procedures, an iStudio OracleAS Integration InterConnect Adapter browser plug-in verifies that the file conforms to the syntax and semantics of D3L. Table C-2 identifies the iStudio tasks and locations where you can import a D3L file as an attribute and select D3L as a message type. Documentation references that describe how to perform these tasks are also provided.
Table C-2 D3L Functionality in iStudio
| For this D3L Functionality... | Do This... |
|---|---|
|
Common Data Type Tasks: |
|
|
Refer to "Creating Common Data Types" |
|
Application Data Types Tasks: |
|
|
Select New from File, then select Application Data Type from the iStudio menu |
|
Event Tasks: |
|
|
Refer to "Creating Events" |
|
Refer to "Publishing an Event" |
|
Refer to "Subscribing to an Event" |
|
Procedure Tasks: |
|
|
Refer to "Creating a Procedure" |
|
Refer to "Invoking a Procedure" |
|
Refer to "Implementing a Procedure" |
|
Note: D3L functionality with procedures in iStudio is only available with the MQ Series adapter. |
You can associate metadata with each event in iStudio by selecting Modify Fields in the Subscribe Wizard - Define Application View. The Modify Fields is displayed after you select D3L as the Message Type in the preceding Subscribe Wizard - Select an Event. Such metadata is used for content-based routing of events at runtime.
The following application view event metadata is used by the OracleAS Integration InterConnect adapters. The property name is prefixed by ota to minimize namespace conflicts with user-defined metadata on application view events. The property name is considered a keyword/reserved name, and is used by both iStudio and the bridge, and must be kept consistent between these two components.
| Property Name | Property Value Type | Explanation |
|---|---|---|
ota.d3lPath
|
The D3L filename (string). This is automatically set. Do not modify this property. | The path name (relative or absolute) of the file that contains the D3L guidelines for this event. |
ota.isD3L
|
This value is always true (boolean) and automatically set. Do not modify this property. | A flag indicating that this event is based on D3L. |
ota.send.endpoint
|
The endpoint URL (string). This is mandatory. For example:
|
The actual endpoint to which this message is sent. This setting must match the type of OracleAS Integration InterConnect Adapter that subscribes to the event. |
http.sender.* file.sender.*
|
Refer to Chapter 2 of the appropriate OracleAS Integration InterConnect Adapter documentation for the adapter being defined in the ota.send.endpoint parameter URLFoot 1 ). This is optional. For example:
|
The properties define the transport layer configuration. |
smtp.sender properties. This is because the MQ Series adapter does not support multiple sending endpoints in this release.This section contains these topics:
This use case provides an example of a minimal Oracle Application Server Integration InterConnect configuration and setup that uses D3L. This use case involves two applications using OracleAS Integration InterConnect Adapters:
aqapp_pub, which is based on the Advanced Queuing adapter
fileapp_sub, which is based on the FTP adapter running in D3L mode
These applications use a business object called Employee, which has one defined event called newEmployee.
The aqapp_pub application publishes the newEmployee event, while fileapp_sub subscribes to it. Table C-3 describes the attributes (message structure) of the newEmployee event:
Table C-3 Common View Attributes
| Attribute Name | Attribute Type |
|---|---|
|
|
String |
|
|
Integer |
|
|
Date |
|
|
Double |
All these attributes are scalar (that is, there are no arrays). This message structure represents the common view of the newEmployee event. For simplicity, the application views for the two applications have the exact same structure as the common view.
In "Creating Data Type Definitions for Application Views", a DTD file and a D3L file are created that match the common view attributes shown in Table C-3. These files are used when the application views for the two applications are defined.
You must create data type definitions for the two application views.
This section contains these topics:
Task 2: Create a D3L File for the FTP Adapter
|
Note: This use case assumes that you have already installed and configured Oracle Application Server Integration InterConnect and iStudio. |
The application view for the Advanced Queuing adapter must be defined through a DTD. The DTD enables the Advanced Queuing adapter to translate a received XML (text) document into a runtime application view (Java) object. The agent component of the Advanced Queuing adapter can then transform it to a common view object before routing it to any application subscribers. A DTD is registered with (imported to) the application while defining, for example, a publication in iStudio.
Create a DTD file that matches the common view message structure shown in Table C-3:
<!ELEMENT NewEmpRec (EmpName, EmpDept, EmpHiredate, EmpSalary)> <!ELEMENT EmpName (#PCDATA)> <!ELEMENT EmpDept (#PCDATA)> <!ELEMENT EmpHiredate (#PCDATA)> <!ELEMENT EmpSalary (#PCDATA)>
Save this DTD in a text file named newemp.dtd. This file can be saved to any location.
When running in D3L mode, the FTP adapter must have its application view defined by a D3L (XML) file. The D3L file enables a bidirectional translation between the internal runtime application view (Java) object representation and an external binary/native format message representation. The D3L file is registered with (imported to) the application while defining, for example, a subscription in iStudio.
Assume the external binary native format message of the newEmployee event is as follows:
message ::= <empname> <empdept> <emphiredate> <empsalary> empname ::= char[20] // left adjusted string, 20 chars wide, right padded with spaces empdept ::= byte[2] // unsigned 2-byte integer, little endian emphiredate ::= '|' + <month> + <anysep> + <day> + <anysep> + <year> + '|' empsalary ::= '$' <number> '$'
| Where... | Is... |
|---|---|
<month>, <day>, and <year>
|
The date format elements MM, DD, and YYYY (all digits)
|
<anysep>
|
Any single character |
<number>
|
Any decimal number using the character "." as a decimal separator
|
Create a D3L file that describes the structure that the native format message must follow to communicate with Oracle Application Server Integration InterConnect. The native format message can be expressed/mapped in the D3L XML definition as shown in :
Example C-20 D3L Sample File
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE message SYSTEM "d3l.dtd">
<message type="NewEmpRec" name="newEmployee" object="Employee">
<!-- TYPE DECLARATIONS -->
<!-- string field 20 chars wide with trailing spaces -->
<padstring id="str20" padchar=" " padstyle="tail" length="20" />
<!-- unsigned 2-byte integer -->
<unsigned2 id="uword" endian="little" />
<!-- date format using pattern MM-DD-YYYY enclosed by '|' -->
<date id="date" format="MMDDYYYY"><limstring delimiter="|" />
</date>
<!-- decimal number format enclosed by '$' -->
<number id="number"><limstring delimiter="$" /></number>
<!-- MESSAGE STRUCTURE -->
<struct id="NewEmpRec">
<field name="EmpName"> <typeref type="str20" /> </field>
<field name="EmpDept"> <typeref type="uword" /> </field>
<field name="EmpHiredate"> <typeref type="date" /> </field>
<field name="EmpSalary"> <typeref type="number" /> </field>
</struct>
</message>
Save the D3L definition in to a file called newemp.xml.
Include a copy of this file on both the host computer where Oracle Application Server Integration InterConnect is installed and on the Windows computer where iStudio is installed.
|
Note: newemp.xml is also copied to the FTP adapter application directory in "Task 4: Copy the newemp.xml D3L File to the fileapp_sub Adapter Directory".
|
The following example shows a native format message that can be translated by the newemp.xml D3L file (The ? character means nonprintable):
Pos Bytes (in hexadecimal) Characters 0000000 4a6f 686e 2044 6f65 2020 2020 2020 2020 John Doe 0000020 2020 2020 4000 7c31 322f 3134 2f32 3030 @?|12/14/200 0000040 317c 2435 3432 3230 2e37 3524 1|$54220.75$
| Where... | Is... |
|---|---|
EmpName
|
John Doe
|
EmpDept
|
64 (hex: 0x40)
|
EmpHiredate
|
12/14/2001
|
EmpSalary
|
54220.75
|
In "Configuring the aqapp_pub and fileapp_sub Applications in iStudio", you complete all the steps necessary in iStudio, including defining the common view, defining the application creation, and so on.
This section describes the tasks to complete in iStudio.
This section contains these topics:
Task 5: Enable the aqapp_pub Application to Publish the newEmployee Event
Task 6: Define the Application Queue for the aqapp_pub Application
Task 8: Enable the fileapp_sub Application to Subscribe to the newEmployee Event
Start iStudio from the Start menu.
When iStudio starts, the last used workspace is automatically loaded. For this use case, define a new workspace and new Project.
Select File, and then New Workspace.
Enter d3l_tests for the Workspace Name, and click OK.
Select File, and then New Project.
Enter d3l_test_ftp for the Project Name, and click OK.
Enter the following values in the Hub Information dialog box:
| For... | Enter... |
|---|---|
| Hub database username | oaihub
|
| Hub database password | oaihub (the default)
|
| Hub database URL | hubDB-host:hubDB-port:hubDB-SID
For example:
|
Select File, New, and then Business Object.
Enter Employee for the Business Object name and click OK.
|
Note: TheEmployee Business Object name matches with the value for the object attribute of the <message> element in the D3L file created in "Task 2: Create a D3L File for the FTP Adapter".
|
Define the newEmployee event as described in "D3L Use Case Overview". Define the (common view) attributes of the event by importing the newemp.xml D3L file defined in "Task 2: Create a D3L File for the FTP Adapter". This D3L file defines the same data types as used by the common view. (Refer to Table C-3.)
Select File, New, and then Event.
Select Employee in the Business Object list.
Enter newEmployee in the Event Name field.
Click Import.
Select D3L from the list that appears.
Locate and select the newemp.xml D3L file created in "Task 2: Create a D3L File for the FTP Adapter". The contents of newemp.xml display in the Attributes fields of the Create Event dialog box. If you receive an error while importing, check if the contents of the newemp.xml file on your iStudio computer are identical to the text shown in .
|
Note: ThenewEmployee Event Name matches with the value for the name attribute of the <message> element in the D3L file created in "Task 2: Create a D3L File for the FTP Adapter".
|
Click Save.
Now create the aqapp_pub application, which publishes the defined event Employee.newEmployee.
Click File, New, and then Application.
Enter aqapp_pub for the Application Name, and click OK.
Use the Publish Wizard to publish the newEmployee event.
This section contains the following topics:
Select the event to publish with the Publish Wizard.
Select Event, and then Publish Event. The Publish Wizard - Select an Event dialog box is displayed.
Select aqapp_pub from the Application list.
Select AQ from the Message Type list. This choice means that the aqapp_pub application is based on the Advanced Queuing adapter.
Click the newEmployee event in the Select an Event list, which is a child of the Employee business object.
Click Next. The Publish Wizard - Define Application View dialog box is displayed.
Define the application view for the Advanced Queuing adapter-based application aqapp_pub in this dialog box. This view was defined in "Task 1: Create a DTD File for the Advanced Queuing Adapter" as an XML DTD, which is a requirement of the Advanced Queuing adapter. Import this DTD to define the application view.
Click Import.
Select XML from the list that appears.
Locate and select the newemp.dtd file, which you created in "Task 1: Create a DTD File for the Advanced Queuing Adapter".
Select NewEmpRec in the Choose Root Element dialog box.
Click OK. The Publish Wizard - Define Application View dialog box is displayed.
Click Next. The Publish Wizard - Define Mapping dialog box is displayed.
Define the application view to common view mapping on this dialog box.
Click New. The Mapping Parameters dialog box is displayed.
Expand newEmployee and NewEmpRec in the aqapp_pub View pane.
Expand newEmployee and NewEmpRec in the Common View pane.
Click the EmpName attribute in both panes.
Select CopyFields in the Transformations list.
Click OK.
Repeat Steps 4 through 6 for the remaining attributes EmpDept, EmpHiredate, and EmpSalary. When complete, the Publish Wizard - Define Mapping dialog box is displayed.
Click Finish. The Publication for application aqapp_pub is complete. The navigation pane on the left hand side of iStudio shows the structure for the aqapp_pub application.
As the aqapp_pub application publishes the newEmployee event and is based on the Advanced Queuing adapter, you must define the (Oracle Advanced Queuing) queue from which the Advanced Queuing adapter reads the event. When an XML message, which complies with the DTD defined in "Task 1: Create a DTD File for the Advanced Queuing Adapter", is enqueued onto the outbound queue, the Advanced Queuing adapter:
Picks the message up
Translates the message to an application view event
Passes the message to the adapter agent for further transformation to the common view representation
The following steps describe how to choose the queue name. The queue does not have to exist physically at this point, as you create it in a later step. (Refer to section "Task 2: Create the Application Queue AQAPP_NEWEMP".)
Click the Deploy navigation tab on top of the iStudio navigation list.
Expand the Applications node.
Expand the aqapp_pub node.
Expand the Routing node.
Right-click the Application Queues node.
Select the Edit option from the list that appears. The Edit Application Queues dialog box is displayed.
Click in the empty field under the Queue Name column header, and enter the queue name, for example, AQAPP_NEWEMP:
Click OK.
Create the fileapp_sub application to subscribe to the defined event Employee.newEmployee (which is published by aqapp_pub).
Use the Subscribe Wizard to subscribe to the newEmployee event.
This section contains these topics:
Select the event to which to subscribe with the Subscribe Wizard.
Select Event, and then Subscribe Event. The Subscribe Wizard - Select an Event dialog box is displayed.
Select fileapp_sub from the Application list.
Select D3L from the Message Type list.
Click newEmployee (under Employee) in the Select an Event list.
Click Next. The Subscribe Wizard - Define Application View dialog box is displayed.
Define the application view for the FTP adapter-based application fileapp_sub in this dialog box. This view was defined in "Task 2: Create a D3L File for the FTP Adapter" as a D3L file. This is a requirement of any OracleAS Integration InterConnect Adapter operating in D3L mode. Import this D3L file to define the application view.
Enter Employee as the business object name in the Object Name input field.
Click Import.
Select D3L from the list that appears.
Locate and select the newemp.xml file, which you saved in "Task 2: Create a D3L File for the FTP Adapter".
The contents of newemp.xml display in the Attributes fields:
Click Next. The Subscribe Wizard - Define Application View dialog box is displayed.
Define the application view to common view mapping in this dialog box.
Click Define Mappings. The Mapping Parameters dialog box is displayed.
Expand newEmployee node in the Common View pane.
Expand newEmployee node in the fileapp_sub View pane.
Select the NewEmpRec in both panes.
Select ObjectCopy in the Transformations list and click Add.
|
Note: You can selectObjectCopy here because the common view and application view are based on the same D3L file.
|
Click OK.
Click Finish. This completes the necessary setup steps in iStudio.
Now that iStudio setup is complete, you must install one instance of each of the two adapter types. This section contains these topics:
Task 1: Install the Advanced Queuing Adapter for Application aqapp_pub
Task 4: Copy the newemp.xml D3L File to the fileapp_sub Adapter Directory
Task 5: Set the D3L file and Payload Type in the adapter.ini Adapter Initialization File
Refer to "Advanced Queuing Adapter Installation" in Chapter 2 of the Oracle Application Server Integration InterConnect Adapter for AQ Installation and User's Guide for installation instructions.
During installation, enter the following specific values when prompted:
Enter aqapp_pub in the Application Name field of the Oracle Application Server Integration InterConnect AQ Adapter Configuration dialog box.
Enter the database connection information to connect to the database instance on the Application Spoke Database page. The AQAPP_NEWEMP application queue defined in "Task 6: Define the Application Queue for the aqapp_pub Application" is created here.
Enter the database username and password of the account and schema on the Spoke Application Database AQ Username dialog box, which owns the Application Queue (AQAPP_NEWEMP). Select the schema name aqapp and the password aqapp. Leave the Consumer Name field blank, as you are creating the AQAPP_NEWEMP queue as a single consumer queue.
Complete adapter installation by providing appropriate responses when prompted.
When installation is complete, the new adapter instance is located in the following directory:
| Platform | Directory |
|---|---|
| Windows | %ORACLE_HOME%\integration\interconnect\adapters\aqapp_pub
|
| UNIX | $ORACLE_HOME/integration/interconnect/adapters/aqapp_pub
|
To create the Advanced Queuing AQAPP_NEWEMP application queue, you must first create the queue table, create the queue, and start the queue.
Ensure that the database user issuing the commands in this section has been granted the following roles:
RESOURCE, CONNECT, AQ_ADMINISTRATOR_ROLE
Use SQL*Plus to log in to the database account specified in Step 1 of "Task 1: Install the Advanced Queuing Adapter for Application aqapp_pub".
Create the queue table using the same name as the application queue:
SQL> EXECUTE dbms_aqadm.create_queue_table('AQAPP_NEWEMP', 'RAW');
Create the queue:
SQL> EXECUTE dbms_aqadm.create_queue('AQAPP_NEWEMP', 'AQAPP_NEWEMP');
Start the queue:
SQL> EXECUTE dbms_aqadm.start_queue('AQAPP_NEWEMP');
Refer to "FTP Adapter Installation" in Chapter 2 of the Oracle Application Server Integration InterConnect Adapter for FTP Installation and User's Guide for installation instructions.
During installation, enter the following specific values when prompted:
Enter fileapp_sub in the Application Name field of the Oracle Application Server Integration InterConnect FTP Adapter Configuration dialog box.
Enter the following value in the URL field of the Oracle Application Server Integration InterConnect FTP Adapter Configuration Configure receiving endpoint information dialog box:
ftp://localhost/tmp/fileapp_sub/read
Enter the following value in the URL field of the Oracle Application Server Integration InterConnect FTP Adapter Configuration Configure sending endpoint information dialog box:
ftp://localhost/tmp/fileapp_sub/write
This action places every newEmployee message received by the fileapp_sub application (by way of its configured subscription created in "Task 8: Enable the fileapp_sub Application to Subscribe to the newEmployee Event") in the /tmp/fileapp_sub/write directory of the computer where the FTP adapter is installed. Ensure that you create these directories with global read and write permissions before starting the fileapp_sub application (based on the FTP adapter), for example:
$ umask 0 $ mkdir -p /tmp/fileapp_sub/read $ mkdir -p /tmp/fileapp_sub/write
Complete adapter installation by providing appropriate responses when prompted.
When installation is complete, the new adapter instance is located in the following directory:
| Platform | Directory |
|---|---|
| Windows | %ORACLE_HOME%\integration\interconnect\adapters\fileapp_sub
|
| UNIX | $ORACLE_HOME/integration/interconnect/adapters/fileapp_sub
|
Copy the newemp.xml D3L file defined in "Task 2: Create a D3L File for the FTP Adapter" to the platform-specific directory mentioned in the preceding Step 2.
Set the ota.d3ls and ota.type parameters in the adapter.ini adapter initialization file for the FTP adapter. The adapter.ini file is located in the platform-specific directory mentioned in the preceding Step 2.
Use a text editor to set the ota.d3ls parameter to newemp.xml in adapter.ini:
ota.d3ls=newemp.xml
If the ota.d3ls parameter line already exists in adapter.ini, replace it with the preceding version.
Use a text editor to set the ota.type parameter to D3L in adapter.ini:
ota.type=D3L
Now that both the Advanced Queuing adapter instance aqapp_pub and the FTP adapter instance fileapp_sub have been installed, use both to run the D3L use case.
This section contains these topics:
The first task is to start the adapters.
Follow these steps to start the adapters on UNIX:
To start the aqapp_pub (Advanced Queuing) adapter:
Change directories to where the aqapp_pub adapter is installed:
$ cd $ORACLE_HOME/integration/interconnect/adapters/aqapp_pub
Start the adapter as a background process:
$ start &
To start the fileapp_sub (FTP) adapter:
Change directories to where the fileapp_sub adapter is installed:
$ cd $ORACLE_HOME/integration/interconnect/adapters/fileapp_sub
Start the adapter as a background process:
$ start &
Follow these steps to start the adapters on Windows:
To start the aqapp_pub (Advanced Queuing) adapter:
Change directories to where the aqapp_pub adapter is installed:
cd %ORACLE_HOME%\integration\interconnect\adapters\aqapp_pub
Start the adapter:
start
To start the fileapp_sub (FTP) adapter:
Change directories to where the fileapp_sub adapter is installed:
cd %ORACLE_HOME%\integration\interconnect\adapters\fileapp_sub
Start the adapter:
start
|
Note: You can also start adapters from the Windows Control Panel. Refer to the OracleAS Integration InterConnect Adapter documentation for instructions. |
The next task generates the native event (that is, triggers the newEmployee event). As configured in iStudio, the aqapp_pub application publishes the newEmployee event. It does so when it sees a new (XML) message on the AQAPP_NEWEMP queue that conforms to the DTD defined in "Task 1: Create a DTD File for the Advanced Queuing Adapter".
To generate the native event, you must enqueue a message on the application queue (AQAPP_NEWEMP) for the application aqapp_pub. You do this through an anonymous PL/SQL block.
Change directories to where the aqapp_pub application (of the Advanced Queuing adapter) is installed, for example:
| On... | Change To... |
|---|---|
| UNIX | $ cd $ORACLE_HOME/integration/interconnect/adapters/aqapp_pub |
| Windows | cd %ORACLE_HOME%\integration\interconnect\adapters\aqapp_pub |
Create a file (named newemp.sql in this example) with the contents shown in :
Example C-21 File newemp.sql
DECLARE
enqueue_options dbms_aq.enqueue_options_t;
message_properties dbms_aq.message_properties_t;
msgid RAW(16);
raw_payload RAW(32767);
payload varchar2(2000);
BEGIN
payload :=
'<?xml version="1.0" standalone="no"?>
<NewEmpRec>
<EmpName>Scott Tiger</EmpName>
<EmpDept>257</EmpDept>
<EmpHiredate>05/01/2001</EmpHiredate>
<EmpSalary>52308.75</EmpSalary>
</NewEmpRec>';
raw_payload := utl_raw.cast_to_raw(payload);
dbms_aq.enqueue(queue_name => 'AQAPP_NEWEMP',
enqueue_options => enqueue_options,
message_properties => message_properties,
payload => raw_payload,
msgid => msgid);
commit;
END;
/
|
Note: Thepayload variable is assigned a string value, which contains a valid XML document that conforms to the DTD newemp.dtd defined in "Task 1: Create a DTD File for the Advanced Queuing Adapter".
|
Everything is now defined, created, and started. You must now trigger the newEmployee event, which was prepared in "Task 2: Create PL/SQL Code to Trigger the Native newEmployee Event".
As mentioned earlier, the event is triggered when you place an XML message on the AQAPP_NEWEMP queue, which is what the newemp.sql script does.
Run the PL/SQL script to generate the event.
Log in to the database account aqapp where the AQAPP_NEWEMP queue was defined. (Refer to "Task 2: Create the Application Queue AQAPP_NEWEMP".) For example, assuming no connect string is necessary, specify the following command:
sqlplus aqapp/aqapp
Run the newemp.sql script:
SQL> START newemp.sql
The following message is displayed:
PL/SQL procedure successfully completed.
Exit SQL*Plus:
SQL> EXIT
After some time (maybe several minutes depending on the system performance), a file appears in the /tmp/fileapp_sub/write directory, which represents the sending endpoint for the FTP adapter. The file is named after the pattern:
app-name-timestamp
Verify that the newEmployee event has been published and received by the fileapp_sub application. On UNIX, for example, perform the following commands:
$ cd /tmp/fileapp_sub/write
$ ls -l
total 2
-rw-rw-r-- 1 bstern svrtech 44 Dec 18 15:29 FILEAPP_SUB-1008718194783
The contents of the file can be displayed in different formats:
$ od -c FILEAPP_SUB-1008718194783 0000000 S c o t t T i g e r 0000020 001 001 | 0 5 / 0 1 / 2 0 0 0000040 1 | $ 5 2 3 0 8 . 7 5 $
or
$ od -x FILEAPP_SUB-1008718194783 0000000 5363 6f74 7420 5469 6765 7220 2020 2020 0000020 2020 2020 0101 7c30 352f 3031 2f32 3030 0000040 317c 2435 3233 3038 2e37 3524
Verify that this output corresponds to the D3L definition shown in "Task 2: Create a D3L File for the FTP Adapter" and the data enqueued by newemp.sql.
Repeat Step 2 to trigger and generate another event (file). The second time you trigger the event, the new file in the /write directory appears much faster (in approximately 3-4 seconds). This is because the adapter allocates and initializes all connections and data structures after processing the first message.
You have completed the use case.
This section briefly describes how to use adapters other than the FTP adapter, and how to run them in XML mode instead of D3L mode. It contains these topics:
Perform the following steps to use the D3L use case with a different OracleAS Integration InterConnect adapter.
Enter another application name that indicates which adapter you are using in "Task 7: Create the fileapp_sub Application" (for example, smtpapp_sub.)
Specify the parameters needed for the particular adapter in Step 1. Refer to the installation documentation for the appropriate OracleAS Integration InterConnect Adapter.
In "Task 4: Verify Receipt of newEmployee Event", the verification process depends entirely on the adapter type, or more specifically, the exact sending endpoint defined.
Replace the fileapp_sub application name where ever it appears with the new application name.
The remaining steps are the same as decribed in the previous section.
Perform the following steps to use XML as the operational mode of the OracleAS Integration InterConnect adapters.
Define the following common view event attributes in Step 4 and Step 5 of "Task 3: Create the newEmployee Event":
Manually create a common data type (right-click + New) named NewEmpRec that has the following attributes:
| Attribute Name | Attribute Type |
|---|---|
| ENAME | STRING |
| JOB | STRING |
| SAL | DOUBLE |
| COMM | DOUBLE |
Import the common data typedata type defined in Step 2 instead of importing a D3L file.
Select XML instead of D3L in Step 3 of "Select the Event to which to Subscribe".
Select to import XML and choose the file newemp.dtd in Step 4 of "Define the Application View".
Perform Steps 2 through 4 in "Define the Application View to Common View Mapping" like you did Steps 2 through 7 in "Define the Application View to Common View Mapping".
Skip Task 4: Copy the newemp.xml D3L File to the fileapp_sub Adapter Directory and "Task 5: Set the D3L file and Payload Type in the adapter.ini Adapter Initialization File".
|
Note: Step 2 assumes that you do not have the D3L file. However, as a shortcut, you can still define the common view event attributes as they were performed in Step 6 of "Task 3: Create the newEmployee Event". |
This section contains these topics:
This section provides several D3L sample files. These example files describe how to use the D3L language to define the content of native format messages.
Sample file msg-1.xml represents a structure named VehicleRegistration. Table C-4 describes the file fields and shows msg-1.xml file contents.
Table C-4 msg-1.xml File Fields
| Field | Description |
|---|---|
|
|
A fixed-length array of four signed, one-byte, little-endian integers, each aligned on two-byte boundaries (implying a one-byte padding between elements of the array.) |
|
|
An unsigned, two-byte, big-endian integer aligned on two-byte boundaries. |
|
|
An unsigned, eight-byte, big-endian integer aligned on two-byte boundaries. |
|
|
A length-prefixed array of dates in the |
|
|
An unsigned, two-byte, big-endian integer with a two-byte alignment. |
|
|
A single date in the |
Example C-22 Sample File msg-1.xml with Structure EmployeeRegistration
<?xml version="1.0" encoding="US-ASCII"?>
<message type="VehicleRegistration" name="Register" object="Vehicle">
<date format="MMDDYYYY" id="Date_T">
<padstring id="FixString10_T" length="10" padchar='' padstyle="none" />
</date>
<struct id="VehicleRegistration">
<!-- Width x Length x Height x Weight (inch/lb) -->
<field name="SizeWeight"><typeref type="ShortArray4_T" /></field>
<field name="ProductCode"><unsigned2 align="2" endian="big" /></field>
<field name="VIN"><unsigned8 align="2" endian="big" /></field>
<field name="PreviousOwners"><typeref type="StringArray_T" /></field>
<field name="Miles"><unsigned2 align="2" endian="big" /></field>
<field name="DateProduced"><typeref type="Date_T" /></field>
</struct>
<fixarray id="ShortArray4_T" length="4">
<unsigned2 align="2" endian="little" id="" />
</fixarray>
<unsigned1 align="2" endian="little" id="Short_T" />
<pfxarray id="StringArray_T" length="Short_T">
<typeref type="FixString10_T" />
</pfxarray>
</message>
The following native format message examples show a hexadecimal and character representation of the same message, which can be parsed by the msg-1.xml D3L file:
Hexadecimal format:
0000000 4500 b200 3400 8a0b 30d9 0000 0000 0072
0000020 55ff 0200 4a6f 6e65 732c 502e 2020 536d
0000040 6974 682c 522e 2020 5208 3131 2532 3225
0000060 3139 3939
Character format:
0000000 E \0 262 \0 4 \0 212 013 0 331 \0 \0 \0 \0 \0 r 0000020 U 377 002 \0 J o n e s , P . S m 0000040 i t h , R . R \b 1 1 % 2 2 % 0000060 1 9 9 9
Sample file msg-2.xml demonstrates a structure hierarchy named PersonRecord. Table C-5 describes the file fields and shows msg-2.xml file contents.
Table C-5 msg-2.xml File Fields
| Field | Description |
|---|---|
|
|
A string delimited by a comma. |
|
|
An unsigned, one-byte integer. |
|
|
A date in |
|
|
An unsigned, four-byte integer. |
|
|
A structure named
|
|
|
A structure named
|
Example C-23 Sample File msg-2.xml with Structure PersonRecord
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE message SYSTEM "d3l.dtd">
<message type="PersonRecord">
<signed4 id="s4" />
<struct id="CityRecord">
<field name="Name"><limstring delimiter="*" /></field>
<field name="State"><limstring delimiter="*" /></field>
<field name="Country"><limstring delimiter="," /></field>
<field name="Population"><unsigned4 /></field>
</struct>
<struct id="StateRecord">
<field name="Name"><limstring delimiter=" " /></field>
<field name="Capital"><limstring delimiter=" " /></field>
<field name="Population"><unsigned4 /></field>
</struct>
<struct id="PersonRecord">
<field name="Name"><limstring delimiter="," /></field>
<field name="Age"><unsigned1 /></field>
<field name="DOB">
<date format="MMDDYYYY">
<pfxstring id="dobstr" length="s4" />
</date>
</field>
<field name="Phone"><unsigned4 /></field>
<field name="City"><typeref type="CityRecord" /></field>
<field name="State"><typeref type="StateRecord" /></field>
</struct>
</message>
The following is a combined hexadecimal and character representation of a native message, which can be parsed by msg-2.xml:
000 2c4a 6f68 6e20 446f 652c 1e00 0000 000a ,John Doe,_..... 020 3131 2f32 352f 3139 3635 0000 002c a155 11/25/1965...,.U 040 2a50 6f72 746c 616e 642a 2a4f 522a 2c55 *Portland**OR*,U 060 5341 2c00 000f 4240 204f 7265 676f 6e20 SA,...B@_Oregon_ 100 2053 616c 656d 2000 003d 0900 _Salem_..=..
Sample file msg-3.xml defines a structure named ProductRecord. Table C-6 describes the file fields and shows msg-3.xml file contents.
Table C-6 msg-3.xml File Fields
| Field | Description |
|---|---|
|
|
A string delimited by a space. |
|
|
A single-precision, floating-point number. |
|
|
A length-prefixed array of
|
Example C-24 Sample File msg-3.xml with Structure ProductRecord
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE message SYSTEM "d3l.dtd">
<message type="ProductRecord">
<unsigned1 id="u1" />
<unsigned2 id="u2" />
<number id="pfxnum">
<padstring length="8" padchar="" padstyle="none" />
</number>
<pfxarray id="Unsigned1Tab" length="u1">
<unsigned1 />
</pfxarray>
<pfxarray id="Signed4Tab" length="pfxnum">
<unsigned4 />
</pfxarray>
<pfxarray id="StrTab" length="u1">
<limstring delimiter=" " />
</pfxarray>
<struct id="WidgetRecord">
<field name="Name"><limstring delimiter=" " /></field>
<field name="Color"><limstring delimiter=" " /></field>
<field name="Weight"><float /></field>
</struct>
<pfxarray id="WidgetTab" length="u2">
<typeref type="WidgetRecord" />
</pfxarray>
<struct id="ProductRecord">
<field name="Manufacturer"><limstring delimiter=" " /></field>
<field name="Weight"><float /></field>
<field name="Widgets"><typeref type="WidgetTab" /></field>
</struct>
</message>
shows the DTD to which D3L (XML) files must conform.
Example C-25 D3L DTD
<!ENTITY % Name "CDATA" >
<!ENTITY % Number "NMTOKEN" >
<!ENTITY % Comment "CDATA" >
<!ENTITY % DelimiterChar
"CDATA"
>
<!ENTITY % QuotationCharAttribute
"
quote %DelimiterChar; #IMPLIED
"
>
<!-- ======================================================== -->
<!ENTITY % GenericAttributes
"
name %Name; #IMPLIED
comment %Comment; #IMPLIED
id ID #IMPLIED
"
>
<!ENTITY % FieldAttributes
"
name %Name; #REQUIRED
comment %Comment; #IMPLIED
id ID #IMPLIED
"
>
<!ENTITY % NonTypeAttributes
"
name %Name; #IMPLIED
comment %Comment; #IMPLIED
"
>
<!-- ======================================================== -->
<!ENTITY % StructAttributes
"
%GenericAttributes;
%QuotationCharAttribute;
"
>
<!-- ======================================================== -->
<!ENTITY % Align
"%Number;"
>
<!ENTITY % IntegerSize
"( 1 | 2 | 4 | 8 )"
>
<!ENTITY % Endian
"( big | little )"
>
<!ENTITY % IntegerAttributes
"
%GenericAttributes;
endian %Endian; 'big'
"
>
<!ENTITY % IntegerTypes
" signed1 | unsigned1
| signed2 | unsigned2
| signed4 | unsigned4
| signed8 | unsigned8
"
>
<!ENTITY % FloatAttributes
"
%GenericAttributes;
"
>
<!ENTITY % FloatTypes
" float | double
"
>
<!-- ======================================================== -->
<!ENTITY % PadStyle
"( head | tail | none )"
>
<!ENTITY % PadChar
"CDATA"
>
<!ENTITY % StringAttributes
"
%GenericAttributes;
"
>
<!ENTITY % SimpleStringAttributes
"
%StringAttributes;
"
>
<!ENTITY % TerminatedStringAttributes
"
%StringAttributes;
endchar %DelimiterChar; #REQUIRED
"
>
<!ENTITY % QuotedTerminatedStringAttributes
"
%StringAttributes;
%QuotationCharAttribute;
endchar %DelimiterChar; #REQUIRED
"
>
<!ENTITY % PaddedStringAttributes
"
%StringAttributes;
length %Number; #REQUIRED
padchar %PadChar; #REQUIRED
padstyle %PadStyle; #REQUIRED
"
>
<!ENTITY % PrefixedStringAttributes
"
%StringAttributes;
length IDREF #REQUIRED
"
>
<!ENTITY % DelimitedStringAttributes
"
%StringAttributes;
delimiter %DelimiterChar; #REQUIRED
"
>
<!ENTITY % StringTypes
"padstring | pfxstring | limstring | qtdtermstring | termstring | simplestring "
>
<!-- ======================================================== -->
<!ENTITY % DateFormat
"( DDMMYY | DDMMYYYY | MMDDYY | MMDDYYYY )"
>
<!ENTITY % DateAttributes
"
%GenericAttributes;
format %DateFormat; #REQUIRED
"
>
<!-- ======================================================== -->
<!ENTITY % NumberAttributes
"
%GenericAttributes;
"
>
<!-- ======================================================== -->
<!ENTITY % ArrayAttributes
"
%GenericAttributes;
"
>
<!ENTITY % FixedArrayAttributes
"
%ArrayAttributes;
length %Number; #REQUIRED
"
>
<!ENTITY % PrefixedArrayAttributes
"
%ArrayAttributes;
length IDREF #REQUIRED
"
>
<!ENTITY % DelimitedArrayAttributes
"
%ArrayAttributes;
contchar %DelimiterChar; #REQUIRED
endchar %DelimiterChar; #REQUIRED
"
>
<!ENTITY % ImplicitArrayAttributes
"
%ArrayAttributes;
"
>
<!-- ======================================================== -->
<!ENTITY % ScalarElements
" signed1 | unsigned1
| signed2 | unsigned2
| signed4 | unsigned4
| signed8 | unsigned8
| float | double
| date | number
| padstring
| pfxstring
| limstring
| termstring
| qtdtermstring
| simplestring
"
>
<!ENTITY % TypeElements
"%ScalarElements;
| struct
| fixarray
| pfxarray
| limarray
| imparray
"
>
<!-- ======================================================== -->
<!ENTITY % FieldElements
"%TypeElements;"
>
<!ENTITY % MessageElements
"%TypeElements;"
>
<!ENTITY % StructElements
"field | pad"
>
<!ENTITY % ArrayElements
"%ScalarElements; | struct"
>
<!ENTITY % ImplicitArrayElements
"%ArrayElements; | limarray"
>
<!-- ======================================================== -->
<!ELEMENT message ( %MessageElements; )* >
<!ATTLIST message
name %Name; #REQUIRED
object CDATA #REQUIRED
type IDREF #REQUIRED
comment %Comment; #IMPLIED
id ID #IMPLIED
header CDATA #IMPLIED
value CDATA #IMPLIED
magic CDATA #IMPLIED
startsat %Number; #IMPLIED
reply (Y|N) "N"
%QuotationCharAttribute;
>
<!-- ======================================================== -->
<!ELEMENT struct ( %StructElements; )* >
<!ATTLIST struct
%StructAttributes;
>
<!-- ======================================================== -->
<!ELEMENT field ( typeref | %FieldElements; ) >
<!ATTLIST field
%FieldAttributes;
>
<!-- ======================================================== -->
<!ELEMENT signed1 EMPTY >
<!ATTLIST signed1
%IntegerAttributes;
size %IntegerSize; #FIXED "1"
align %Align; "1"
>
<!ELEMENT unsigned1 EMPTY >
<!ATTLIST unsigned1
%IntegerAttributes;
size %IntegerSize; #FIXED "1"
align %Align; "1"
>
<!ELEMENT signed2 EMPTY >
<!ATTLIST signed2
%IntegerAttributes;
size %IntegerSize; #FIXED "2"
align %Align; "2"
>
<!ELEMENT unsigned2 EMPTY >
<!ATTLIST unsigned2
%IntegerAttributes;
size %IntegerSize; #FIXED "2"
align %Align; "2"
>
<!ELEMENT signed4 EMPTY >
<!ATTLIST signed4
%IntegerAttributes;
size %IntegerSize; #FIXED "4"
align %Align; "4"
>
<!ELEMENT unsigned4 EMPTY >
<!ATTLIST unsigned4
%IntegerAttributes;
size %IntegerSize; #FIXED "4"
align %Align; "4"
>
<!ELEMENT signed8 EMPTY >
<!ATTLIST signed8
%IntegerAttributes;
size %IntegerSize; #FIXED "8"
align %Align; "8"
>
<!ELEMENT unsigned8 EMPTY >
<!ATTLIST unsigned8
%IntegerAttributes;
size %IntegerSize; #FIXED "8"
align %Align; "8"
>
<!-- ======================================================== -->
<!ELEMENT float EMPTY >
<!ATTLIST float
%FloatAttributes;
align %Align; "4"
>
<!ELEMENT double EMPTY >
<!ATTLIST double
%FloatAttributes;
align %Align; "8"
>
<!-- ======================================================== -->
<!ELEMENT simplestring EMPTY >
<!ATTLIST simplestring
%SimpleStringAttributes;
>
<!ELEMENT qtdtermstring EMPTY >
<!ATTLIST qtdtermstring
%QuotedTerminatedStringAttributes;
>
<!ELEMENT termstring EMPTY >
<!ATTLIST termstring
%TerminatedStringAttributes;
>
<!ELEMENT padstring EMPTY >
<!ATTLIST padstring
%PaddedStringAttributes;
>
<!ELEMENT pfxstring EMPTY >
<!ATTLIST pfxstring
%PrefixedStringAttributes;
>
<!ELEMENT limstring EMPTY >
<!ATTLIST limstring
%DelimitedStringAttributes;
>
<!-- ======================================================== -->
<!ELEMENT fixarray ( typeref | %ArrayElements; ) >
<!ATTLIST fixarray
%FixedArrayAttributes;
>
<!ELEMENT pfxarray ( typeref | %ArrayElements; ) >
<!ATTLIST pfxarray
%PrefixedArrayAttributes;
>
<!ELEMENT limarray ( typeref | %ArrayElements; ) >
<!ATTLIST limarray
%DelimitedArrayAttributes;
>
<!ELEMENT imparray ( typeref | %ImplicitArrayElements; ) >
<!ATTLIST imparray
%ImplicitArrayAttributes;
>
<!-- ======================================================== -->
<!ELEMENT date ( typeref | %StringTypes; ) >
<!ATTLIST date
%DateAttributes;
>
<!-- ======================================================== -->
<!ELEMENT number ( typeref | %StringTypes; ) >
<!ATTLIST number
%NumberAttributes;
>
<!-- ======================================================== -->
<!ELEMENT typeref EMPTY >
<!ATTLIST typeref
%NonTypeAttributes;
type IDREF #REQUIRED
>
<!-- ======================================================== -->
<!ELEMENT pad EMPTY >
<!ATTLIST pad
%NonTypeAttributes;
length %Number; #REQUIRED
>
<!-- ======================================================== -->
