Skip Headers

Oracle9iAS InterConnect User's Guide
Release 2 (9.0.2)
Part Number A92174-01
Go To Documentation Library
Home		 Go To Product List
Solution Area		 Go To Table Of Contents
Contents		 Go To Index
Index

Go to previous page Go to next page

B
Using the Data Definition Description Language

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

This appendix contains these topics:

About D3L

This section contains these topics:

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 Oracle9iAS InterConnect. Oracle Corporation provides several transport adapters (known as Oracle9iAS InterConnect Technology Adapters) that interact with the D3L message description language:

Oracle9iAS InterConnect Technology Adapters perform the following tasks:

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:

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:

Native Format Message and D3L File Example

This section provides an example of how the contents of a native format message are:

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

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 appx_d3l3.gif follows
Text description of the illustration appx_d3l3.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

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

Both methods enable the D3L translation engine to use the correct D3L file for translation after receiving the native format message.

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 Oracle9iAS InterConnect event name and business object, respectively.

Name/Value Pair Message Header Attributes

Oracle9iAS InterConnect Technology 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:

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:

Figure B-2 Name/Value Pair Message Header Attributes


Text description of appx_d3l4.gif follows
Text description of the illustration appx_d3l4.gif

The D3L translation engine retrieves the correct D3L file based on these settings.

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 appx_d3l5.gif follows
Text description of the illustration appx_d3l5.gif

The D3L translation engine retrieves the correct D3L file based on these settings.

See Also:

 

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:

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:

Lines 16 through 19

These lines define the fields of the structure named ItinRecord:

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"):

Supported D3L Data Types

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

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.

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.

Strings

D3L supports the following string types:

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 Oracle9iAS InterConnect message attribute names.

Sequences

D3L supports sequences (for example, arrays) of various types. These include:

The data being sequenced can be any other D3L type (predefined or user defined).

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

D3L Integration with Oracle9iAS InterConnect Technology Adapters

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

Runtime Initialization

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

Native Format Message to Common View Incoming Message Translations

When the Oracle9iAS InterConnect Technology 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 Oracle9iAS InterConnect Technology Adapter bridge. The bridge:

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. Oracle9iAS InterConnect Technology Adapter operations are logged by Oracle9iAS 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.

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


Text description of appx_d3la.gif follows
Text description of the illustration appx_d3la.gif

See Also:

 

Common View to Native Format Message Outgoing Messages Translations

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

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

All Oracle9iAS InterConnect Technology Adapter operations are logged using the Oracle9iAS 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 asiug001.gif follows
Text description of the illustration asiug001.gif

Installing D3L

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

See Also:

Your Oracle9iAS InterConnect Technology 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

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.2\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.2\adapters\application directory (for direct access at deployment time).

    See Also:

    The following sections for additional examples of D3L 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:

 

Task 5: Configure D3L with Oracle9iAS InterConnect Technology Adapters

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

  1. Use a text editor to open the %ORACLE_HOME%\oai\9.0.2\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 Oracle9iAS InterConnect Technology 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 Oracle9iAS InterConnect Technology 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 Oracle9iAS InterConnect features:

When a D3L file is associated with Oracle9iAS InterConnect common data types, application data types, events, or procedures, an iStudio Oracle9iAS InterConnect Technology 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 Oracle9iAS InterConnect Technology 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 Oracle9iAS InterConnect Technology Adapter that subscribes to the event. 

http.sender.* file.sender.* 

See Chapter 2 of the appropriate Oracle9iAS InterConnect Technology 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:

 

D3L Use Case

This section contains these topics:

D3L Use Case Overview

This use case provides an example of a minimal Oracle9iAS InterConnect configuration and setup that uses D3L. This use case involves two applications using Oracle9iAS InterConnect Technology Adapters:

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

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 Oracle9iAS InterConnect. The native format message can be expressed/mapped in the D3L XML definition as shown in Example B-1:

    Example B-1 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-1 to a file called newemp.xml.

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

  1. Start iStudio from the Windows NT 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:V902  

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

    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 CreateEvent2.gif 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

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 SelectEvent.gif follows.
    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 RootElem.gif follows.
    Text description of the illustration RootElem.gif

  5. Click OK.

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


    Text description of DefAppView.gif 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 Mapping.gif 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 DefineMapping.gif 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 aqapp_pub.gif follows.
    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:

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 Deploy.gif follows.
    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 AppQueue.gif follows.
    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

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 Oracle9iAS InterConnect Technology 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 ImportD3L.gif follows.
    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 DefineMappingFtp.gif 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

  1. See "Advanced Queuing Adapter Installation" in Chapter 2 of the Oracle9iAS 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 Oracle9iAS 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.2\adapters\aqapp_pub  

    UNIX 

    $ORACLE_HOME/oai/9.0.2/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 Oracle9iAS 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 Oracle9iAS InterConnect FTP Adapter Configuration dialog.

    2. Enter the following value in the URL field of the Oracle9iAS 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 Oracle9iAS 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.2\adapters\fileapp_sub  

    UNIX 

    $ORACLE_HOME/oai/9.0.2/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

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.2/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.2/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.2\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.2\adapters\fileapp_sub
  2. Start the adapter: 

    start

    Note:

    You can also start adapters from the Windows Control Panel. See your Oracle9iAS InterConnect Technology 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.2/adapters/aqapp_pub 

    Windows 

    cd %ORACLE_HOME%\oai\9.0.2\adapters\aqapp_pub 

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

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

Perform the following steps to use the D3L use case with a different Oracle9iAS InterConnect Technology 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 Oracle9iAS InterConnect Technology 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 Oracle9iAS InterConnect Technology 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

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.

Example One: 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-3 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-3 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:

Example Two: 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-4 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-4 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_..=..

Example Three: 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-5 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-5 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-6 shows the DTD to which D3L (XML) files must conform.

Example B-6 D3L DTD 

<?xml version="1.0" encoding="US-ASCII"?>
<!-- ======================================================== -->
<!ENTITY % Name     "CDATA"     >
<!ENTITY % Number   "NMTOKEN"   >
<!ENTITY % Comment  "CDATA"     >
<!-- ======================================================== -->
<!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;
    "
>
<!-- ======================================================== -->
<!ENTITY % Align
    "%Number;"
>
<!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 % DelimiterChar
    "CDATA"
>
<!ENTITY % StringAttributes
    "
    %GenericAttributes;
    "
>
<!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"
>
<!-- ======================================================== -->
<!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 % TypeElements
    " signed1 | unsigned1
    | signed2 | unsigned2
    | signed4 | unsigned4
    | signed8 | unsigned8
    | float   | double
    | date    | number
    | struct
    | padstring
    | pfxstring
    | limstring
    | fixarray
    | pfxarray
    | limarray
    | imparray
    "
>
<!-- ======================================================== -->
<!ENTITY % FieldElements
    "%TypeElements;"
>
<!ENTITY % MessageElements
    "%TypeElements;"
>
<!ENTITY % StructElements
    "field | pad"
>
<!ENTITY % ArrayElements
    "%TypeElements;"
>
<!-- ======================================================== -->
<!ELEMENT message ( %MessageElements; )* >
    <!ATTLIST message
        %GenericAttributes;
        type        IDREF           #REQUIRED
        header      CDATA           #IMPLIED
        value       CDATA           #IMPLIED
        magic       CDATA           #IMPLIED
        endpoint    CDATA           #IMPLIED
    >
<!-- ======================================================== -->
<!ELEMENT struct ( %StructElements; )* >
    <!ATTLIST struct
        %StructAttributes;
    >
<!-- ======================================================== -->
<!ELEMENT field ( typeref | %FieldElements; ) >
    <!ATTLIST field
        %FieldAttributes;
    >
<!-- ======================================================== -->
<!ELEMENT signed1 EMPTY >
    <!ATTLIST signed1
        %IntegerAttributes;
        align   %Align;     "1"
    >
<!ELEMENT unsigned1 EMPTY >
    <!ATTLIST unsigned1
        %IntegerAttributes;
        align   %Align;     "1"
    >
<!ELEMENT signed2 EMPTY >
    <!ATTLIST signed2
        %IntegerAttributes;
        align   %Align;     "2"
    >
<!ELEMENT unsigned2 EMPTY >
    <!ATTLIST unsigned2
        %IntegerAttributes;
        align   %Align;     "2"
    >
<!ELEMENT signed4 EMPTY >
    <!ATTLIST signed4
        %IntegerAttributes;
        align   %Align;     "4"
    >
<!ELEMENT unsigned4 EMPTY >
    <!ATTLIST unsigned4
        %IntegerAttributes;
        align   %Align;     "4"
    >
<!ELEMENT signed8 EMPTY >
    <!ATTLIST signed8
        %IntegerAttributes;
        align   %Align;     "8"
    >
<!ELEMENT unsigned8 EMPTY >
    <!ATTLIST unsigned8
        %IntegerAttributes;
        align   %Align;     "8"
    >
<!-- ======================================================== -->
<!ELEMENT float EMPTY >
    <!ATTLIST float
        %FloatAttributes;
        align   %Align;     "4"
    >
<!ELEMENT double EMPTY >
    <!ATTLIST double
        %FloatAttributes;
        align   %Align;     "8"
    >
<!-- ======================================================== -->
<!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 | %ArrayElements; ) >
    <!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
    >
<!-- ======================================================== -->
Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.
All Rights Reserved.
Go To Documentation Library
Home		 Go To Product List
Solution Area		 Go To Table Of Contents
Contents		 Go To Index
Index