B
Using the Data Definition Description Language

This appendix describes how to use the data definition description language (D3L) in its native format message-to-application view and application view-to-native format message translations.

This appendix contains these topics:

• About D3L

• Native Format Message and D3L File Example

• D3L File Structure

• D3L Integration with OracleAS InterConnect Adapters

• Installing D3L

• Configuring D3L

• D3L Use Case

• Additional D3L Sample Files and DTD

About D3L

This section contains these topics:

• What Is D3L?

• When Is D3L Used?

What Is D3L?

D3L is an XML-based message description language that describes the structure that an application's native, non-XML format message (known also as its native view) must follow to communicate with Oracle Application Server InterConnect. Oracle Corporation provides several transport adapters (known as OracleAS InterConnect Adapters) that interact with the D3L message description language:

• FTP

• HTTP(S)

• MQ Series

• SMTP

OracleAS InterConnect Adapters perform the following tasks:

• Validate the D3L message description (XML) files during runtime 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 a participating application and Oracle Application Server InterConnect.

  Note: Native format messages already in XML format are not translated by OracleAS InterConnect Adapters if the ota.type parameter is set to XML in the adapter.ini file.

  See Also: "D3L Integration with OracleAS InterConnect Adapters" for detailed information on how D3L is integrated with OracleAS InterConnect Adapters

When Is D3L Used?

Not all applications use XML as their native message payload format. Applications also use other native formats, which are best described as structured records of bytes and/or characters. For these native formats to be successfully translated into a format understood by other applications, the content of their messages 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. Specifically, 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 into an application view, or vice versa

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:

• Descriptions of arbitrarily-structured data (like regular XML)

• Name-value pair data

• Conditional data structures, which require token look-ahead to parse.

  See Also: "Native Format Message and D3L File Example" "Supported D3L Data Types" "D3L DTD"

Native Format Message and D3L File Example

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

Satisfying both these requirements enables the native format message to be successfully translated. This section contains the following topics:

• Native Format Message Contents Description in a D3L File

• Native Format Message Configuration with a D3L File

Native Format Message Contents Description in a D3L File

This example shows an application's native format message (named price) that contains payload data for updating the price of personal computer model number 2468 to 199.99. The native message uses the following format to describe this payload data:

message ::=  <action>  <model>  <price>







Where...


Is...





<action>



UPDATE_PRICE




<model>



2468




<price>



199.99

The payload data must strictly follow the structure defined in a D3L file (for this example, price.xml) for the D3L translation engine (subcomponent of the bridge) to successfully translate it into an application view. Figure B-1 shows how a D3L file (price.xml) defines the structure that the native format message price must follow to successfully define the three preceding elements of payload data.

Figure B-1 Native Format Message Payload Data and D3L File Syntax

Text description of the illustration asiug003.gif

All three payload data elements are defined as strings with different delimiters for separating their data.

Native Format Message Configuration with a D3L File

When the D3L translation engine receives a native format message (for example, price), it must determine the exact D3L file to use to verify the native format message contents (for example, price.xml). This section describes the methods for configuring the correct D3L file with the native format message:

• adapter.ini Parameter File Setting

• Message Header Attributes

adapter.ini Parameter File Setting

The ota.d3ls parameter in the %ORACLE_HOME%\oai\9.0.4\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

This setting enables price.xml in Figure B-1 to be configured with the native format message price. 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, for example:

ota.d3ls=price.xml,emp.xml,booking.xml

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, unless one of the methods described in "Message Header Attributes" is used.

Message Header Attributes

The D3L file includes message header attributes that guide the D3L engine in choosing the correct D3L file for translating a native format message to an application view. The values for these message header attributes match with the same 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 message header attribute setting methods are available:

• Name/Value Pair Message Header Attributes

• Magic Value Message Header Attribute

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), the <message> element attributes name and object in the D3L file define the Oracle Application Server InterConnect event name and business object, respectively.

Name/Value Pair Message Header Attributes

OracleAS 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 sending application (for example, an HTTP client). The D3L file <message> element enables the user to specify two attributes, header and value, that 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 to the D3L translation engine which D3L file to use to translate an incoming native format message. The following steps must be performed:

• 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.

Figure B-2 provides an example using the HTTP adapter where D3L-Header and price are the header name and header value, respectively. Each 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 B-2 Name/Value Pair Message Header Attributes

Text description of the illustration appx_d3l3.gif

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 example is relevant for the FTP adapter, which provides a header property called filename that holds the name of a received file.

The above D3L will be selected to parse incoming files which filename match the name pattern in the value attribute, such as,

cust_create01 <-- match! 
cust_create02 <-- match! 
po_int_ext01
cust_create03 <-- match! 
po_int_ext02 
  

The "fuzzy" 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%

Magic Value Message Header Attribute

You can set the magic attribute of the <message> element in the D3L file to match the first n bytes of payload 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 against 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.

Figure B-3 provides an example where *UPDATE_PRICE is the value that configures the native format message with the correct D3L file.

Figure B-3 Magic Value Message Header Attribute

Text description of the illustration asiug005.gif

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 that magic matching should start.

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, counting from 0.

See Also: "Native Format Message to Common View Incoming Message Translations" for additional information on message header attributes "Additional D3L Sample Files and DTD" for additional D3L file examples

D3L File Structure

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 through 2

These lines define standard information, such as the Prolog and Document Type Declaration (DTD) that must always be these values (for example, specifying d3l.dtd as the DTD).

Lines 3 through 4

These lines define the following:

• Message element attribute name (value replyFlight), which must correspond to the associated Oracle Application Server 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).

• Message element attribute type (value BookingReplyType) names a structure that is defined in subsequent lines of this D3L file.

• Message element attribute object (value Booking), which must match the Oracle Application Server InterConnect business object defined in iStudio.

• Message element attribute header (value D3L-Header), which is identified in the set of protocol level transport message headers associated with a native format message.

• Message element attribute value (value replyOptions), which must match the actual value of the corresponding protocol level transport message header (defined through the header attribute).

  See Also: "Creating Business Objects" "Creating Events" "Name/Value Pair Message Header Attributes" "Task 6: Import a D3L File in iStudio"

Lines 5 through 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 fields of a structure named DateTimeRecord:

• Field DateInfo defines a date format of MMDDYY and length prefixed by an unsigned four-byte integer.

• Field TimeHour defines a string delimited by the character *.

• Field TimeMinute defines a string delimited by the character *.

Lines 16 through 19

These lines define the fields of the structure named ItinRecord:

• Fields DepartureTime and ArrivalTime both consist of the DataTimeRecord structure defined in "Lines 7 through 15" .

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 fields of the message structure BookingReplyType (which satisfies the BookingReplyType type declaration in the message document element, as shown in "Lines 3 through 4"):

• Field AirportCodeFrom is a string delimited by the character *.

• Field AirportCodeTo is a string delimited by the character *.

• Field Itineraries is a field of type ItinArray (which is an array of ItinRecord).

Supported D3L Data Types

D3L supports use of the following data types and declarations in a D3L file:

• Signed or Unsigned Integers

• Floating Point Numbers

• Strings

• Structures

• Sequences

Signed or Unsigned Integers

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 B-1 Quantity Field

<field name="quantity">
   <unsigned4 endian="big" align="6"/>
</field>

The field "quantity" 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 B-2 Weight and Lengeh Field

<field name="weight"> <unsigned2 align="3"/> </field>
<field name="length"> <unsigned2 align="3"/> </field>

The fields "weight" and "length" define two bytes unsigned binary integers, using big endian, and at 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 B-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 field "temperature" defines a two byte signed binary integer, using little endian, and no alignment.

The field "pressure" defines a four byte unsigned binary integer, using big endian, and no alignment.

The field wind defines a two 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

Floating Point Numbers

D3L supports single and double-precision, IEEE format, floating-point data. Single precision floating point numbers (known as floats) take up four bytes/octets, whereas double precision floating point numbers (known as doubles) take up eight bytes/octets.

Example B-4 Distance and Age Field

<field name="distance"> <double align="6"/> </field>
<field name="age">      <float />           </field>

The field "distance" defines an eight byte double-float (floating-point value according to the IEEE 754 floating-point double precision bit layout), at an alignment of 6 bytes.

The field "age" defines a four 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:           java.io.DataInput.readFloat()           java.io.DataInput.readDouble()           java.io.DataOutput.writeFloat()           java.io.DataOUtput.writeDouble()

      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

Strings

D3L supports the following string types:

• Constant length strings (without delimiters, and 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 one of the 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 (for example, 12!24=01).

• Numbers not defined as binary data, but as strings. Any one of the three string formats 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 B-5 Constant length strings--padstring

<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 field "CURRENCY_CODE" defines a fixed length string of 4 characters. Any blank (" ") characters (pads) towards the end (padstyle="tail") of the string are not considered part of the data value.

The field "COUNTRY_CODE" defines a fixed length string of 2 characters. Since padstyle is "none", all characters in this field are prt of the data value.

The field "TO_USD_RATE" defines a fixed length string of 12 characters. Any zero's ("0" pads) 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 B-6 Delimited strings--limstring

<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 five fields "State", "Region", "City", "Landmark" and "Street" are delimited strings each respectively enclosed by ".", ".", "|", "|" and "+".

      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 B-7 Length prefixed strings--pfxstring

<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 field "user" defines a string the length of which is defined by a one-byte binary integer preceeding the string contents.

The field "encr_user" defines a string the length of which is defined by a two-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 B-8 Terminated strings--termstring

<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> 
            

The first four fields will each be populated with input characters until the terminating/ending character (endchar) is encountered (",") whereas the last field be ended 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 B-9 Simple strings--simplestring

<limarray id="CSV_Type" contchar="," endchar="\n"> 
   <simplestring /> 
</limarray> 
<struct> 
   <field name="CSV"> <typeref type="CSV_Type" /> </field> 

The field "CSV" references a type declaration "CSV_Type" which is a delimited array where array members are separated by commas (the continuation character contchar=",") and ended by the ending character 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 B-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 four fields contain dates, representing the currently available 4 different date format.

      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 the D3L parser will accept any character between the DD, 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). Currently hours, minutes and seconds are not parseable.

Example B-11 String based numbers--number

<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 one-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 field "Red" is a number defined as a fixed length string of 4 characters, which can be padded with '0's at the beginning.

The field "Green" 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 field "Blue" is a number defined as a "." delimited string, the string beginning and end is demarcated by ".".

The field "Brightness" is a number defined as a string which is read from the current point until the ending character ("|") is encountered.

The field "Hue" is a number defined as a string of type "HueType" (defined above).

      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 double's.

Structures

D3L supports structured types, that is, 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, data structures, however, are not supported in D3L.

All data fields in a message format description must be named. These names are used as Oracle Application Server InterConnect message attribute names. All names within the same structure must be mutually unique.

Within a D3L file the first allowable element is <message>. The message element must refer to a <struct> (via the IDREF type attribute) which then becomes the top level data structure of the message.

Example B-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 the <message> element.

Sequences

D3L supports sequences (for example, 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 (This data type uses 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 B-13 Delimited arrays--limarray

<field name="members"> 
   <limarray contchar=";" endchar="."> 
      <limstring delimiter="." /> 
   </limarray> 
</field> 

The field "members" will become an array of data elements separated by semicolons (contchar=";"). The end of the array will be marked by a period (endchar="."). Each data element in the array will be 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 B-14 Length prefixed arrays--pfxarray

<unsigned2 id="u2" endian="little" align="4" /> 
<struct> 
   <field name="measurements"> 
      <pfxarray length="u2" > <signed1 /> </pfxarray> 
   </field> 
       

The field "measurements" will become an array of signed one-byte binary integers (signed1). The number of elements in the array will be 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 B-15 Fixed length arrays--fixarray

<field name="digits"> 
   <fixarray length="10"> 
      <number> 
         <termstring endchar="-">
      </number 
   </fixarray> 
            

The field "digits" will become 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 will/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 B-16 Implicit length arrays--imparray

<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"). Since "OrdersArrayType" is an implicit array, it will consume all remaining bytes in the native byte input stream, i.e. the size of the array is first known when the input byte stream has been exhausted.

The field "OrderLines" 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 abstract structure of the input stream would have to follow the below 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}} 
                 ] 
              } 
         } 
      ] 
}

Data Padding

D3L supports data padding. Pads are unnamed gaps in a native format message that satisfy alignment constraints of the underlying native system. Pads are discarded in the Oracle Application Server InterConnect application view message.

The following D3L example defines a number as a left-aligned string, right padded 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 to fields, which are separated by a pad of size 5.

<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; 
[...]

Comma-Separated Values File Parsing with D3L

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

Two string types, termstring and simplestring, have been added to make it easier to parse CSV files.

• termstring

  String type termstring is a variation of limstring, but requires only a terminating delimiter and, not a beginning delimiter. For example:

  <termstring endchar="," />
  
  

  This parses any string contents until a comma is encountered.

• simplestring

  String type simplestring is a special data type only 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>
  
  

These new string types provide two ways for parsing CSV files. The examples provided in the following sections use imparray so that input can be any number of elements, lines, or both.

• CSVs are Assigned to Named Fields

• All CSVs are Read into an Array

CSVs are Assigned to Named Fields

With this method, all CSVs on each line are assigned to named fields (fixed number of fields per line). Example B-17 provides an example.

Example B-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 B-17 is as follows:

4,,9,22,2324.29 
,,,,, 
55,2342,11,46,728372339.57

All CSVs are Read into an Array

With this method, all CSVs on each line are read into an array (variable number of fields per line). Example B-18 provides an example.

Example B-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 payload for Example B-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

Delimiter Encoding Styles

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:

1. Escaping 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)

2. Escaping ASCII code using "#"-- for example, "#13".

3. Escaping ASCII hexadecimal code using "#x"-- for example, "#x0D".

4. 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 B-19 provides several examples of delimiter encoding styles.

Example B-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 B-19 represents a DOS style line break.

D3L Integration with OracleAS InterConnect Adapters

This section provides information on how the D3L files and D3L translation engine are integrated in runtime events and message translations with the OracleAS InterConnect Adapter agent and bridge subcomponents. This section contains these topics:

• Runtime Initialization

• Native Format Message to Common View Incoming Message Translations

• Common View to Native Format Message Outgoing Messages Translations

Runtime Initialization

The OracleAS InterConnect Adapter agent reads .ini files (such as adapter.ini) at runtime to access each OracleAS InterConnect Adapter's configuration information. The OracleAS InterConnect Adapter bridge initializes itself and the common transport layer with configuration information provided by the OracleAS InterConnect Adapter agent. At the completion of a successful initialization, the OracleAS InterConnect Adapter bridge knows:

• The Oracle Application Server InterConnect application name and its default endpoint (message destination)

• The various Oracle Application Server InterConnect events to be handled by the OracleAS InterConnect Adapter bridge

• The D3L files that describe each of these events

• The D3L files that are accessible and valid. If a file is invalid, the OracleAS InterConnect Adapter cannot start.

  See Also: Chapter 1, "Getting Started with OracleAS InterConnect" for additional information on bridges and agents Chapter 2, "Using iStudio" for additional information about events

Native Format Message to Common View Incoming Message Translations

When the OracleAS InterConnect Adapter common transport layer detects an incoming message from an application, it receives the message in its native format. The common transport layer passes it to the OracleAS InterConnect Adapter bridge. The bridge:

• Uses the D3L translation engine to translate the native format message into an application view (an Oracle Application Server InterConnect message object) using the D3L file with which it is configured.

• 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 B-1 describes the data flow sequence if D3L message header attributes are used.

Table B-1 Message Header Attributes

If The...	Then...
Name/value pair message header attributes are used	If the incoming native event: Contains transport message headers/properties (made available to the bridge by the transport layer) Has a transport message header parameter name (for example, D3L-Header) that matches the header attribute of the <message> element in the D3L file (header="D3L-Header") Has a transport message header value (for example, D3L-Header: price) that matches the value attribute of the <message> element in the D3L file (value="price") the bridge assumes the matching D3L describes the incoming native event. Any conflicting header and value settings are detected and rejected by the bridge at initialization time. OracleAS InterConnect Adapter operations are logged by Oracle Application Server InterConnect logging and tracing APIs for debugging, performance analysis, and business intelligence functions. See Also: Figure B-2 for complete syntax examples
Magic value message header attribute is used	If a magic value is: Specified for the D3L file (length = n bytes) The first n bytes of payload data in an incoming native event (for example, *UPDATE_PRICE) match the magic attribute of the <message> element in the D3L file (for example, magic="*UPDATE_PRICE"> 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 (the resulting application view event raised may not be the correct one). See Also: Figure B-3 for complete syntax examples

Figure B-4 shows the data flow sequence.

See Also: "Message Header Attributes" "Task 4: Configure a Native Format Message with a D3L File"

Figure B-4 Native Format Message to Common View Incoming Messages

Text description of the illustration asiug002.gif

Common View to Native Format Message Outgoing Messages Translations

When a common view event is raised, the OracleAS InterConnect Adapter agent subscribing to the event:

• Receives the associated message

• Transforms it to an Oracle Application Server InterConnect message object

• Hands it to the OracleAS InterConnect Adapter bridge (as an application view event)

The OracleAS InterConnect Adapter bridge queries the metadata associated with the event to determine:

• The D3L file for the D3L translation engine to use to translate the application view event into a native format message

• The application to which to send the native format message event. There are two levels of rules to determine the application endpoint (the destination) of an Oracle Application Server InterConnect event:
  • If the event contains metadata that specifies an endpoint (note that here, the metadata itself names the endpoint; the content of the event is not searched), the bridge uses this endpoint for this event. With the exception of the MQ Series adapter, all OracleAS InterConnect Adapters follow this rule.

  • If the message metadata did not specify an endpoint, the bridge uses its default endpoint (that was specified at installation time, added to the adapter.ini file, and made available to the bridge during initialization).

All OracleAS InterConnect Adapter operations are logged using the Oracle Application Server InterConnect logging and tracing APIs for debugging, performance analysis, and other business intelligence functions.

Figure B-5 shows the data flow sequence.

Figure B-5 Common View to Native Format Message Outgoing Messages

Text description of the illustration asiug001.gif

Installing D3L

D3L is automatically installed with Oracle Application Server InterConnect. See Oracle Application Server InterConnect Installation Guide for information on installing Oracle Application Server InterConnect.

See Also: Your OracleAS InterConnect Adapter documentation for instructions on installing and configuring the appropriate adapter to use with D3L

Configuring D3L

After installation, perform the following tasks to configure D3L:

• Task 1: Configure D3L with iStudio

• Task 2: Create a Native Format Message

• Task 3: Create a D3L File Describing the Native Format Message

• Task 4: Configure a Native Format Message with a D3L File

• Task 5: Configure D3L with OracleAS InterConnect Adapters

• Task 6: Import a D3L File in iStudio

• Task 7: Define Metadata Properties with Each Event (Optional)

Task 1: Configure D3L with iStudio

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:

1. Use a text editor to open the ORACLE_HOME\oai\9.0.4\iStudio\browsers.init file.

2. Add the following information:

   D3L;oracle.oai.agent.adapter.technology.D3LBrowser; 
   
   

3. Save your changes and exit the file.

   See Also: "Task 6: Import a D3L File in iStudio" for the locations of D3L functionality in iStudio

Task 2: Create a Native Format Message

1. Create a native format message. The native format is typically predefined by your third-party application. For example, this native format message updates the salary of employee number 33201 to 55000:

   *UPDATE_EMPLOYEE_SALARY* 33201 |55000|
   

   Where...	Is...
   <action>	UPDATE_EMPLOYEE_SALARY
   <EmployeeID>	33201
   <newSalary>	55000

Task 3: Create a D3L File Describing the Native Format Message

1. Use a text editor to create a D3L file (for example, named updemp.xml) that describes the format of the native message. For example, 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>
   

2. Store the D3L file (updemp.xml) in the ORACLE_HOME\oai\9.0.4\adapters\application directory (for direct access at deployment time).

   See Also: The following sections for additional examples of D3L files: Figure B-1 Example B-20 "Additional D3L Sample Files"

Task 4: Configure a Native Format Message with a D3L File

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

See Also: Figure B-2 Table B-1

Task 5: Configure D3L with OracleAS InterConnect Adapters

Define D3L in the following places in the adapter.ini file. The adapter.ini file is read by the appropriate OracleAS InterConnect Adapter at startup.

1. Use a text editor to open the ORACLE_HOME\oai\9.0.4\adapters\application\adapter.ini file.

   where application is the name of your application and the value of the application parameter in the adapter.ini file.

2. Ensure that parameter ota.type is set to the following value:

   ota.type=D3L
   
   

   This defines D3L as the message type for the OracleAS InterConnect Adapter to handle for both incoming and outgoing messages.

3. 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 an example 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 InterConnect Adapter restarted.

4. Save your changes and exit the file.

Task 6: Import a D3L File in iStudio

iStudio enables you to import a D3L file for use with the following Oracle Application Server 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 InterConnect common data types, application data types, events, or procedures, an iStudio OracleAS InterConnect Adapter browser plug-in verifies that the file conforms to the syntax and semantics of D3L. Table B-2 identifies the tasks and locations in iStudio 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 B-2 D3L Functionality in iStudio

For this D3L Functionality...	Do This...
Common Data Type Tasks:
Create a common data type that imports a D3L file as an attribute	See "Creating Common Data Types"
Application Data Types Tasks:
Creating an application data type that imports a D3L file as an attribute	Select File > New > Application Data Type from the iStudio menu
Event Tasks:
Create an event that imports a D3L file as an attribute	See "Creating Events"
Publish an event that uses D3L as the message type and imports a D3L file as an attribute	See "Publishing an Event"
Subscribe to an event that uses D3L as the message type and imports a D3L file as an attribute	See "Subscribing to an Event"
Procedure Tasks:
Create a procedure that imports a D3L file as an attribute	See "Creating a Procedure"
Invoke a procedure that uses D3L as the message type and imports a D3L file as an attribute	See "Invoking a Procedure"
Implement a procedure that uses D3L as the message type and imports a D3L file as an attribute	See "Implementing a Procedure"

Note: D3L functionality with procedures in iStudio is only available with the MQ Series adapter.

Task 7: Define Metadata Properties with Each Event (Optional)

You can associate metadata with each event in iStudio by selecting the Modify Fields buttons on the Subscribe Wizard - Define Application View dialog. The Modify Fields button appears after you select D3L as the Message Type on the preceding Subscribe Wizard - Select an Event dialog. Such metadata is used for content-based routing, for example, of events at runtime.

The following application view event metadata is used by the OracleAS 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: http://foo.com/servlet/ test	The actual endpoint to which this message is sent. This setting must match the type of OracleAS InterConnect Adapter that subscribes to the event.
http.sender.* file.sender.*	See Chapter 2 of the appropriate OracleAS InterConnect Adapter documentation for the adapter being defined in the ota.send.endpoint parameter URLFoot 1). This is optional. For example: http.sender.timeout=5000	The properties define the transport layer configuration.

1 The SMTP adapter does not define any smtp.sender properties. The MQ Series adapter does not support multiple sending endpoints in this release.

See Also: "Subscribing to an Event" "D3L Use Case"

D3L Use Case

This section contains these topics:

• D3L Use Case Overview

• Creating Data Type Definitions for Application Views

• Configuring the aqapp_pub and fileapp_sub Applications in iStudio

• Installing the Advanced Queuing and FTP Adapters

• Running the D3L Use Case

• Using Other Adapters and XML Mode

D3L Use Case Overview

This use case provides an example of a minimal Oracle Application Server InterConnect configuration and setup that uses D3L. This use case involves two applications using OracleAS 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.

aqapp_pub publishes the newEmployee event, while fileapp_sub subscribes to it. Table B-3 describes the attributes (message structure) of the newEmployee event:

Table B-3 Common View Attributes

Attribute Name	Attribute Type
EmpName	String
EmpDept	Integer
EmpHiredate	Date
EmpSalary	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 B-3. These files are used when the application views for the two applications are defined.

Creating Data Type Definitions for Application Views

You must create data type definitions for the two application views.

This section contains these topics:

• Task 1: Create a DTD File for the Advanced Queuing Adapter

• 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 InterConnect and iStudio.

Task 1: Create a DTD File for the Advanced Queuing Adapter

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.

1. Create a DTD file that matches the common view message structure shown in Table B-3:

   <!ELEMENT NewEmpRec (EmpName, EmpDept, EmpHiredate, EmpSalary)> 
   <!ELEMENT EmpName     (#PCDATA)> 
   <!ELEMENT EmpDept     (#PCDATA)> 
   <!ELEMENT EmpHiredate (#PCDATA)> 
   <!ELEMENT EmpSalary   (#PCDATA)>
   

2. Save this DTD in a text file named newemp.dtd. This file can be saved to any location.

Task 2: Create a D3L File for the FTP Adapter

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

1. Create a D3L file that describes the structure that the native format message must follow to communicate with Oracle Application Server InterConnect. The native format message can be expressed/mapped in the D3L XML definition as shown in Example B-20:

   Example B-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> 
   
   
   
   

2. Save the D3L definition in Example B-20 to a file called newemp.xml.

3. Include a copy of this file on both the host computer where Oracle Application Server 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.

Configuring the aqapp_pub and fileapp_sub Applications in iStudio

This section describes the tasks to complete in iStudio.

This section contains these topics:

• Task 1: Create a New Workspace and New Project

• Task 2: Create the Employee Business Object

• Task 3: Create the newEmployee Event

• Task 4: Create the aqapp_pub Application

• Task 5: Enable the aqapp_pub Application to Publish the newEmployee Event

• Task 6: Define the Application Queue for the aqapp_pub Application

• Task 7: Create the fileapp_sub Application

• Task 8: Enable the fileapp_sub Application to Subscribe to the newEmployee Event

Task 1: Create a New Workspace and New Project

1. 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.

2. Select File > New Workspace.

3. Enter d3l_tests for the Workspace Name and click OK.

4. Select File > New Project.

5. Enter d3l_test_ftp for the Project Name and click OK.

6. Enter the following values in the Hub Information dialog:

   For...	Enter...
   Hub database username	oaihub
   Hub database password	oaihub (the default)
   Hub database URL	hubDB-host:hubDB-port:hubDB-SID For example: dlsun10:1521:V904

Task 2: Create the Employee Business Object

1. Select File > New > Business Object.

2. Enter Employee for the Business Object name and click OK.

   Note: The Employee 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".

Task 3: Create the newEmployee Event

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. (See Table B-3.)

1. Select File > New > Event.

2. Select Employee in the Business Object drop down list.

3. Enter newEmployee in the Event Name field.

4. Click Import.

5. Select D3L from the list that appears.

6. 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. 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 Example B-20.

   Note: The newEmployee 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".

   The Create Event dialog looks as follows:

   

   Text description of the illustration createevent2.gif

7. Click Save.

   See Also: "Creating Events"

Task 4: Create the aqapp_pub Application

Now create the aqapp_pub application, which publishes the defined event Employee.newEmployee.

1. Select File > New > Application.

2. Enter aqapp_pub for the Application Name and click OK.

Task 5: Enable the aqapp_pub Application to Publish the newEmployee Event

Use the Publish Wizard to publish the newEmployee event.

This section contains these topics:

• Select the Event to Publish

• Define the Application View

• Define the Application View to Common View Mapping

Select the Event to Publish

Select the event to publish with the Publish Wizard.

1. Select Event > Publish Event.

   The Publish Wizard - Select an Event dialog appears.

2. Select aqapp_pub from the Application drop down list.

3. Select AQ from the Message Type drop down list. This choice means that the aqapp_pub application is based on the Advanced Queuing adapter.

4. Click the newEmployee event in the Select an Event tree, which is a child of the Employee business object.

   

   Text description of the illustration selectevent.gif

5. Click Next.

   The Publish Wizard - Define Application View dialog appears.

Define the Application View

Define the application view for the Advanced Queuing adapter-based application aqapp_pub in this dialog. 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.

1. Click the Import button.

2. Select XML from the list that appears.

3. Locate and select the newemp.dtd file, which you created in "Task 1: Create a DTD File for the Advanced Queuing Adapter".

4. Select NewEmpRec in the Choose Root Element dialog.

   

   Text description of the illustration rootelem.gif

5. Click OK.

   The Publish Wizard - Define Application View dialog looks as follows:

   

   Text description of the illustration defappview.gif

6. Click Next.

   The Publish Wizard - Define Mapping dialog appears.

Define the Application View to Common View Mapping

Define the application view to common view mapping on this dialog.

1. Click the New button.

   The Mapping Parameters dialog appears.

2. Expand newEmployee and NewEmpRec (clicking the '+') in the aqapp_pub View pane.

3. Expand newEmployee and NewEmpRec (clicking the '+') in the Common View pane.

4. Click the EmpName attribute in both panes.

5. Select CopyFields in the Transformations list.

   The Mapping Parameters dialog appears as follows:

   

   Text description of the illustration mapping.gif

6. Click OK.

7. Repeat Steps 4 through 6 for the remaining attributes EmpDept, EmpHiredate, and EmpSalary.

   When complete, the Publish Wizard - Define Mapping dialog appears as follows:

   

   Text description of the illustration definemapping.gif

   There is one line for each attribute.

8. Click Finish.

   The Publication for application aqapp_pub is complete. The navigation tree pane on the left hand side of iStudio shows the following structure for the aqapp_pub application:

   

   Text description of the illustration aqapp_pub.gif

Task 6: Define the Application Queue for the aqapp_pub Application

Since 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. (See section "Task 2: Create the Application Queue AQAPP_NEWEMP".)

1. Click the Deploy navigation tab on top of the iStudio navigation tree.

2. Expand the Applications node.

3. Expand the aqapp_pub node.

4. Expand the Routing node.

5. Right click the Application Queues node.

6. Select the Edit option from the list that appears.

   

   Text description of the illustration deploy.gif

   The Edit Application Queues dialog appears.

7. Click in the empty field under the Queue Name column header, and enter the chosen queue name, for example, AQAPP_NEWEMP:

   

   Text description of the illustration appqueue.gif

8. Click OK.

Task 7: Create the fileapp_sub Application

Create the fileapp_sub application to subscribe to the defined event Employee.newEmployee (which is published by aqapp_pub).

1. Select File > New > Application.

2. Enter fileapp_sub for the Application Name and click OK.

Task 8: Enable the fileapp_sub Application to Subscribe to the newEmployee Event

Use the Subscribe Wizard to subscribe to the newEmployee event.

This section contains these topics:

• Select the Event to which to Subscribe

• Define the Application View

• Define the Application View to Common View Mapping

Select the Event to which to Subscribe

Select the event to which to subscribe with the Subscribe Wizard.

1. Select Event > Subscribe Event.

   The Subscribe Wizard - Select an Event dialog appears.

2. Select fileapp_sub from the Application drop down list.

3. Select D3L from the Message Type drop down list.

4. Click newEmployee (under Employee) in the Select an Event tree.

5. Click Next.

   The Subscribe Wizard - Define Application View dialog appears.

Define the Application View

Define the application view for the FTP adapter-based application fileapp_sub in this dialog. 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 InterConnect Adapter operating in D3L mode. Import this D3L file to define the application view.

1. Enter Employee as the business object name in the Object Name input field.

2. Click the Import button.

3. Select D3L from the list that appears.

4. 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:

   

   Text description of the illustration importd3l.gif

5. Click Next.

   The Publish Wizard - Define Mapping dialog appears.

Define the Application View to Common View Mapping

Define the application view to common view mapping in this dialog.

1. Click the New button.

   The Mapping Parameters dialog appears.

2. Expand newEmployee (clicking the '+') in the Common View pane.

3. Expand newEmployee (clicking the '+') in the fileapp_sub View pane.

4. Click the NewEmpRec node in both panes.

5. Select ObjectCopy in the Transformations list and click OK.

   Note: You can choose ObjectCopy here because the common view and application view are based on the same D3L file.

The Subscribe Wizard - Define Mapping dialog appears as follows:

Text description of the illustration definemappingftp.gif

6. Click Finish.

   This completes the necessary setup steps in iStudio.

Installing the Advanced Queuing and FTP Adapters

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 2: Create the Application Queue AQAPP_NEWEMP

• Task 3: Install the FTP Adapter for Application fileapp_sub

• 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

Task 1: Install the Advanced Queuing Adapter for Application aqapp_pub

1. See "Advanced Queuing Adapter Installation" in Chapter 2 of the Oracle Application Server InterConnect Adapter for AQ Installation and User's Guide for installation instructions. During installation, enter the following specific values when prompted:
   1. Enter aqapp_pub in the Application Name field of the Oracle Application Server InterConnect AQ Adapter Configuration dialog.

   2. 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.

   3. Enter the database username and password of the account and schema on the Spoke Application Database AQ Username dialog, 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.

2. 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%\oai\9.0.4\adapters\aqapp_pub
   UNIX	$ORACLE_HOME/oai/9.0.4/adapters/aqapp_pub

Task 2: Create the Application Queue AQAPP_NEWEMP

To create the Advanced Queuing AQAPP_NEWEMP application queue, you must first create the queue table, create the queue, and start the queue.

1. Ensure that the database user issuing the commands in this section has been granted these roles:

   RESOURCE, CONNECT, AQ_ADMINISTRATOR_ROLE
   
   

2. Use SQL*Plus to log in to the database account specified in Steps 1b and 1c of "Task 1: Install the Advanced Queuing Adapter for Application aqapp_pub".

3. Create the queue table using the same name as the application queue:

   SQL> EXECUTE dbms_aqadm.create_queue_table('AQAPP_NEWEMP', 'RAW'); 
   

4. Create the queue:

       SQL> EXECUTE dbms_aqadm.create_queue('AQAPP_NEWEMP', 'AQAPP_NEWEMP'); 
   
   

5. Start the queue:

       SQL> EXECUTE dbms_aqadm.start_queue('AQAPP_NEWEMP');   
   

Task 3: Install the FTP Adapter for Application fileapp_sub

1. See "FTP Adapter Installation" in Chapter 2 of the Oracle Application Server InterConnect Adapter for FTP Installation and User's Guide for installation instructions. During installation, enter the following specific values when prompted:
   1. Enter fileapp_sub in the Application Name field of the Oracle Application Server InterConnect FTP Adapter Configuration dialog.

   2. Enter the following value in the URL field of the Oracle Application Server InterConnect FTP Adapter Configuration Configure receiving endpoint information dialog:

      ftp://localhost/tmp/fileapp_sub/read
      

   3. Enter the following value in the URL field of the Oracle Application Server InterConnect FTP Adapter Configuration Configure sending endpoint information dialog:

      ftp://localhost/tmp/fileapp_sub/write
      

      This 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
       
      

2. 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%\oai\9.0.4\adapters\fileapp_sub
   UNIX	$ORACLE_HOME/oai/9.0.4/adapters/fileapp_sub

Task 4: Copy the newemp.xml D3L File to the fileapp_sub Adapter Directory

1. 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.

Task 5: Set the D3L file and Payload Type in the adapter.ini Adapter Initialization File

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.

1. 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 this version.

2. Use a text editor to set the ota.type parameter to D3L in adapter.ini:

   ota.type=D3L
   

Running the D3L Use Case

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:

• Task 1: Start the Adapters

• Task 2: Create PL/SQL Code to Trigger the Native newEmployee Event

• Task 3: Trigger the newEmployee Event

• Task 4: Verify Receipt of newEmployee Event

Task 1: Start the Adapters

To Start the Adapters on UNIX:

Follow these steps to start the adapters on UNIX:

To start the aqapp_pub (Advanced Queuing) adapter:

1. Change directories to where the aqapp_pub adapter is installed:

       $ cd $ORACLE_HOME/oai/9.0.4/adapters/aqapp_pub 
   
   

2. Start the adapter as a background process:

       $ start & 
   
   

To start the fileapp_sub (FTP) adapter:

1. Change directories to where the fileapp_sub adapter is installed:

       $ cd $ORACLE_HOME/oai/9.0.4/adapters/fileapp_sub 
   
   

2. Start the adapter as a background process:

       $ start & 
   

To Start the Adapters on Windows:

Follow these steps to start the adapters on Windows:

To start the aqapp_pub (Advanced Queuing) adapter:

1. Change directories to where the aqapp_pub adapter is installed:

   cd %ORACLE_HOME%\oai\9.0.4\adapters\aqapp_pub 
   

2. Start the adapter:

   start
   

To start the fileapp_sub (FTP) adapter:

1. Change directories to where the fileapp_sub adapter is installed:

   cd %ORACLE_HOME%\oai\9.0.4\adapters\fileapp_sub 
   

2. Start the adapter:

   start
   

   Note: You can also start adapters from the Windows Control Panel. See your OracleAS InterConnect Adapter documentation for instructions.

Task 2: Create PL/SQL Code to Trigger the Native newEmployee Event

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.

1. Change directories to where the aqapp_pub application (of the Advanced Queueing adapter) is installed, for example:

   On...	Go To...
   UNIX	$ cd $ORACLE_HOME/oai/9.0.4/adapters/aqapp_pub
   Windows	cd %ORACLE_HOME%\oai\9.0.4\adapters\aqapp_pub

2. Create a file (named newemp.sql in this example) with the contents shown in Example B-21:

Example B-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: The payload variable is being 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".

Task 3: Trigger the newEmployee Event

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.

1. Log in to the database account aqapp where the AQAPP_NEWEMP queue was defined. (See "Task 2: Create the Application Queue AQAPP_NEWEMP".) For example, assuming no connect string is necessary:

   sqlplus aqapp/aqapp
   
   

2. Execute the newemp.sql script:

   SQL> START newemp.sql 
   
   

   The following message appears:

   PL/SQL procedure successfully completed. 
   

3. Exit SQL*Plus:

   SQL> EXIT 
   

Task 4: Verify Receipt of newEmployee Event

After some time (maybe several minutes depending on overall 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

1. 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
   

2. 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.

3. 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 allocated and initialized all connections and data structures after processing the first message.

4. You have completed the use case.

Using Other Adapters and XML Mode

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.

This section contains these topics:

• Using the HTTP, SMTP, or MQ Series Adapters in D3L Mode

• Using XML Mode

Using the HTTP, SMTP, or MQ Series Adapters in D3L Mode

Perform the following steps to use the D3L use case with a different OracleAS InterConnect Adapter.

1. Enter another application name that indicates which adapter you are using in "Task 7: Create the fileapp_sub Application" (for example, smtpapp_sub).

2. Specify the parameters needed for the particular adapter in Steps 1b and 1c. See the installation documentation for the appropriate OracleAS InterConnect Adapter.

3. 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.

4. Replace the fileapp_sub application name where ever it appears with the new application name.

The remaining steps are the same.

Using XML Mode

Perform the following steps to use XML as the operational mode of the OracleAS InterConnect Adapters.

1. Skip "Task 2: Create a D3L File for the FTP Adapter".

2. Define the following common view event attributes in Step 4 and Step 5 of "Task 3: Create the newEmployee Event":
   1. Manually create a common data type (right click + New) named NewEmpRec that has the same attributes as shown in the Create Event dialog.

   2. Import the common data type defined in Step 2a instead of importing a D3L file.

3. Select XML instead of D3L in Step 3 of "Select the Event to which to Subscribe".

4. Select to import XML and choose the file newemp.dtd in Step 4 of "Define the Application View".

5. 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".

6. 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: Replacement steps Steps 2a and 2b assume 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".

Additional D3L Sample Files and DTD

This section contains these topics:

• Additional D3L Sample Files

• D3L DTD

Additional D3L Sample Files

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 with Structure VehicleRegistration

• Sample File with Structure Hierarchy PersonRecord

• Sample File with Structure ProductRecord

Sample File with Structure VehicleRegistration

Sample file msg-1.xml represents a structure named VehicleRegistration. Table B-4 describes the file fields and Example B-22 shows msg-1.xml file contents.

Table B-4 msg-1.xml File Fields

Field	Description
SizeWeight	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)
ProductCode	An unsigned, two-byte, big-endian integer aligned on two-byte boundaries
VIN	An unsigned, eight-byte, big-endian integer aligned on two-byte boundaries
PreviousOwners	A length-prefixed array of dates in the MMDDYYYY format (the length of the array is a signed, one-byte, little-endian integer with a two-byte alignment)
Miles	An unsigned, two-byte, big-endian integer with a two-byte alignment
DateProduced	A single date in the MMDDYYYY format

Example B-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 with Structure Hierarchy PersonRecord

Sample file msg-2.xml demonstrates a structure hierarchy named PersonRecord. Table B-5 describes the file fields and Example B-23 shows msg-2.xml file contents.

Table B-5 msg-2.xml File Fields

Field	Description
Name	A string delimited by a comma
Age	An unsigned, one-byte integer
DOB	A date in MMDDYYYY format, length prefixed by a signed, four-byte integer
Phone	An unsigned, four-byte integer
City	A structure named CityRecord that consists of the following fields: Name A string delimited by * State A string delimited by * Country A string delimited by * Population An unsigned, four-byte integer
State	A structure named StateRecord that consists of the following fields: Name A string delimited by a space Capital A string delimited by a space Population An unsigned, four-byte integer

Example B-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 with Structure ProductRecord

Sample file msg-3.xml defines a structure named ProductRecord. Table B-6 describes the file fields and Example B-24 shows msg-3.xml file contents.

Table B-6 msg-3.xml File Fields

Field	Description
Manufacturer	A string delimited by a space
Weight	A single-precision, floating-point number
Widgets	A length-prefixed array of WidgetRecord structures. A WidgetRecord consists of: Name A string delimited by a space Color A string delimited by a space Weight A single-precision, floating point number

Example B-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>

D3L DTD

Example B-25 shows the DTD to which D3L (XML) files must conform.

Example B-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
         >
     <!-- ======================================================== -->