Using MsgDefAdmin


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Search \| PDF Files \| Contact \| Glossary

eLink Information Integrator Doc Home \| eLink Information Integrator User Guide \| Previous Topic \| Next Topic \| Contents \| Index

Using MsgDefAdmin

The MsgDefAdmin Tool is a command line utility that allows the definition of a message format to be specified in an XML language called Message Format Language (MFL). Using your favorite text or XML editor, you can specify fields and the grouping of fields, according to the Message Format Language Document Type Definition (mfl.dtd). This XML document can then be imported using the MsgDefAdmin Tool to define the message format and all components (fields, controls, and formats).

The tasks involved in creating formats using MsgDefAdmin are as follows:

Creating an MFL Document

An MFL document is a description of a message that is sent to an application. To create an MFL document, you need to translate messages into a textual description that conforms to the MFL document type definition (mfl.dtd). The file mfl.dtd defines the elements and attributes necessary to create message formats.

To create an MFL document, follow the steps below. A sample MFL document is shown in Listing 3-2 following these steps.

Start a text editor.
Type the following as the first two lines in your MFL document.
<?xml version='1.0'?>
<!DOCTYPE MessageFormat SYSTEM `mfl.dtd'>

Note: These two lines must always be the first two lines of your MFL document.
Specify the name of the message format in the MessageFormat element (the third line in the MFL document) as shown below:
<?xml version='1.0'?>
<!DOCTYPE MessageFormat SYSTEM `mfl.dtd'>
<MessageFormat name='message_name'>
Add a FieldFormat element for the first field in the message. The FieldFormat element specifies the name of the field, as well as the field's type attributes. An example is shown below:
<?xml version='1.0'?>
<!DOCTYPE MessageFormat SYSTEM `mfl.dtd'>
<MessageFormat name='message_name'>
<FieldFormat name='field_name'
type='type_attribute'/>
If you need to group this field with others for purposes of defining a format for the group, add a StructFormat element. The StructFormat element defines the format for a group of fields. An example of the StructFormat element for a repeating field is shown below:
<?xml version='1.0'?>
<!DOCTYPE MessageFormat SYSTEM `mfl.dtd'>
<MessageFormat name=message_name>
<FieldFormat name='field_name'
type='type_attribute'/>
<StructFormat name='structure_format_name'
repeatField="repeating_field_name">

Note: Refer to Message Format Elements for a list of the elements you can include in an MFL document and their descriptions.
Add additional fields to the message format by defining FieldFormat elements for each of the additional fields. Set the type attribute according to each field's type.
Add the end tags for the StructFormat and MessageFormat elements. Listing 3-1 shows a sample MFL document. Refer to Message Format Elements for an explanation of the various elements in the MFL document.
Listing 3-1 Sample MFL Document

<?xml version='1.0'?>
<!DOCTYPE MessageFormat SYSTEM `mfl.dtd'>
<MessageFormat name='PAYROLL_MSG'>
<FieldFormat name='NUM_EMPLOYEES' type='LittleEndian4'/>
<StructFormat name='EMPLOYEE_REC'
repeatField="NUM_EMPLOYEES">
<FieldFormat name='EMPLOYEE_NAME' type='String'
delim='\xFF'/>
<FieldFormat name='EMPLOYEE_SSN' type='String'
length='11'/>
<FieldFormat name='EMPLOYEE_PAY' type='Upacked'
length='15'/>
</StructFormat>
</MessageFormat>
Save your message definition and exit from the text editor. You can now use MsgDefAdmin to add this message definition to the Database. Refer to Running MsgDefAdmin for instructions.

Message Format Elements

This section lists the message format elements that make up the MFL document and provides a description of each element.

Note: In the examples below, the following characters have special meaning:

Square brackets ([ ]) indicate optional parameters
Curly brackets ({ }) indicate choices
Forward slash (/) indicates "OR", as in "yes/no."

MessageFormat

Acts as the top-level element for a message type's format information. For example:

where xxx is the name of the message.

StructFormat

Defines the formatting for a group of fields. For example:

Listed below are the parameters that may be included in the StructFormat element:

name="xxx"

The name of the message format. Required.

repeat="99"

Flags the message as repeating and indicates the number of times the message will repeat.

repeatField="xxx"

The name of the field that contains the repeat count for the message.

repeatDelim="xxx"

The delimiter that ends the repeating of this message.

alternative="yes/no"

Indicates whether the message is defined as an alternative format message.

optional="yes/no"

Indicates whether the message is optional.

FieldFormat

Defines the formatting for a single field. For example:

Listed below are the parameters that may be included in a FieldFormat element:

name="xxx"

The name of the field. Required.

type="xxx"

The field type. Required. Refer to Data Types, for more information on the supported data types.

basetype="xxx"

Used only for Date and Time data types to indicate the base data type for the field. Valid values are: String, Numeric, and EBCDIC.

cutoff="99"

Used only for date formats containing a two digit year. Valid values are 00-99. This value is used to convert to a four digit year as follows:

yy >= cutoff --> 19yy
yy < cutoff --> 20yy

length="99"

Defines an exact length for the field data. For data types that do not have an implicit length (String, Numeric, etc.), either an exact length or a field delimiter must be specified.

delim="xxx"

Defines a delimiter denoting the end of the field data. For data types that do not have an implicit length (String, Numeric, etc.), either an exact length or a field delimiter must be specified. Delimiter values may contain escaped decimal or hexadecimal values.

optional="y/n"

Indicates whether the field should be marked as optional on both the input and output message formats.

accessMode="xxx"

Must be one of the following values:

Normal - Access the instance in the same repeating component as the current controlling field instance. If there is no controlling field, access the first instance.

Current - Access the same field instance as on the previous access (the first access will get the first instance of the field).

Next - Access the next field instance relative to the previous access.

Controlling - This field is the controlling field for the repeating component. On each repetition, access the next field instance that is still a child of the current controlling field instance of the parent format. If there is no parent controlling field, the repetitions end with the last field instance from the input message.

Relative - The first field in a repeating component that Formatter encounters with this access mode is the controlling field for the repeating component (see Controlling field). Any other field in the repeating component with this access mode behaves as if it has access mode Access sibling instance or Normal access (access the sibling of the controlling field).

Increment - A field with this access mode is the controlling field for the repeating component (see Controlling field). This accesses the current value and increments it.

value="xxx"

The value of the literal. This attribute is only valid if the type of the FieldFormat is "Literal."

TagField

Defines a tag for a field format and the value to be matched. For example:

<TagField type="xxx"

[length="99" value="xxx"]>

</TagField>

Listed below are the parameters that may be included in a TagField element:

type="xxx"

Required. The type of the field. Refer to Data Types, for more information on the supported data types.

value="xxx"

Required. Defines the value of the tag for this field.

LenField

Defines a length within the message data for a field. For example:

type="xxx"

Required. The type of the field. Refer to Data Types, for more information on the supported data types.

length="99"

Defines an exact length for the field data. For data types that do not have an implicit length (i.e. String, Numeric, etc.) either an exact length or a field delimiter must be specified.

Notes: The TagField and LenField elements must be child elements of a FieldFormat element. The order in which they appear in the FieldFormat element determines the order of the data in the message.

The same StructFormat element may not be defined in two different message definitions. If this happens, when these message definitions are imported, the StructFormat is redefined by the second message definition, leaving the first message definition in an invalid state. For example, suppose message definition A and message definition B both contain a structure called PAY_TABLE. When message definition A is imported, the import creates a format called PAY_TABLE. When message definition B is imported, the PAY_TABLE format is redefined. Message definition A then contains a reference to a format that no longer exists. When you try to access message definition A, you now receive an error.

Running MsgDefAdmin

To add message definitions created using an MFL file to the Information Integrator database, follow the steps below.

Note: Do not run the MsgDefAdmin utility and the Formatter GUI concurrently if they are connected to the same database.

Open a DOS command-prompt window.
Change to the directory where MsgDefAdmin is installed (for example, C:\BEAII)

Type MsgDefAdmin and press Enter. The MsgDefAdmin importer utility appears as shown in Listing 3-2.

Listing 3-2 MsgDefAdmin

- Copyright (c) 2000 BEA Systems, Inc. 
All Rights Reserved. 
Distributed under license by BEA Systems, Inc. 
BEA eLink Information Integrator is a registered trademark.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

- - -    BEA eLink Information Integrator 1.1    - - - 
- - -      Message Definition Importer Tool      - - -

Enter choice: 
1) Add Message Definition 
2) Get Message Definition 
3) Delete Message Definition 
4) List Message Definitions 
Q) Quit >

Type 1 to select the Add Message Definition choice and press Enter. An additional prompt displays asking you to specify the name of the file containing the XML message definition.
Type the path and name of the message file you created with your text editor and press Enter. MsgDefAdmin processes the file, stores the message definition in the Database, and returns a message that the definition was successfully created.
Type Q at the prompt and press Enter to quit MsgDefAdmin.

You can also run MsgDefAdmin in a non-interactive mode. There are two command-line options that allow you to import or export message definitions.

The command-line syntax is as follows:

MsgDefAdmin [-i | -e] <XML filename>

where

-i

Denotes an import operation. MsgDefAdmin will import the message definitions in <XML filename> into the Database. The following example shows how to use -i.

C:\BEAII>MsgDefAdmin -i payroll.xml employee_data.xml purchase_order.xml
Processing file: payroll.xml
Message Definition created!
Processing file: employee_data.xml
Message Definition created!
Processing file: purchase_order.xml
Message Definition created!

-e

Denotes an export operation. MsgDefAdmin will export the message definitions in <XML filename> from the Database. Each definition that is exported is saved to a file using the name of the message definition as the file name and .xml as the filename extension. The following example shows how to use -e.

C:\BEAII>MsgDefAdmin -e PAYROLL_MSG EMPLOYEE
XML Document retrieved:
Created file PAYROLL_MSG.xml
ML Document retrieved:
Created file EMPLOYEE.xml

<xml filenames>

Name of the XML file that contains or receives message definitions.

Example

This section outlines the procedure required to complete Step 3 in Using Information Integrator. In Step 3, you create the message format definitions. We need to define the layout of our data as a linear buffer. Since our input is actually an FML32 buffer, Information Integrator will map the data from FML to a linear buffer as defined by the input message format. This is done using MsgDefAdmin to create an XML file. We have provided two XML files for you to use in this example. You can use these files as a base for creating your own XML files to solve your own business needs.

In the steps that follow, we will view and discuss the XML files for this payroll example, and use MsgDefAdmin to create the message format definitions.

With your favorite text editor, open \sample\payroll\II_payroll_msg1.xml. This file is located in the \sample\payroll directory where you installed Information Integrator. The file is shown below:

<?xml version='1.0'?>
<!DOCTYPE MessageFormat SYSTEM 'mfl.dtd'>
MessageFormat name="II_payroll_msg1">
 <FieldFormat name="NAME" type="String"/>
 <FieldFormat name="EMPNO" type="BigEndian4"/>
 <FieldFormat name="$RPAYDATE" type="BigEndian2"/>
 <StructFormat name="II_payroll_msg1_rep" repeatField="$RPAYDATE">
     <FieldFormat name="PAYDATE" type="String" accessMode="Controlling"/>
     <FieldFormat name="RATE" type="String"/>
     <FieldFormat name="HOURS" type="String"/>
 </StructFormat>
</MessageFormat>

This file creates the input format for the data.

When you have finished viewing the first XML file, close it.

Open the file \sample\payroll\II_payroll_msg2.xml. This file is shown below:

<?xml version='1.0'?>
<!DOCTYPE MessageFormat SYSTEM 'mfl.dtd'>
<MessageFormat name="II_payroll_msg2">
   <FieldFormat name="EMPNO" type="String"/>
   <FieldFormat name="$RPAYDATE" type="String"/>
 <StructFormat name="II_payroll_msg2_rep" repeatField="$RPAYDATE">
   <FieldFormat name="PAYDATE" type="String" accessMode="Controlling"/>
   <FieldFormat name="PAY" type="String" controlName="CALC_PAY"/>
 </StructFormat>
</MessageFormat>

This file creates the output format for the data.

When you have finished viewing this file, close it.

Now you are ready to run MsgDefAdmin to create the format definitions.
From a command prompt, in the directory where you installed Information Integrator, type the following:

msgdefadmin -i \sample\payroll\II_payroll_msg1.xml

and press Enter. MsgDefAdmin processes the first XML file and displays a message when finished.
Type the following to process the second XML file:
msgdefadmin -i \sample\payroll\II_payroll_msg2.xml

and press Enter. MsgDefAdmin processes the XML file and displays a message when finished.