[This local archive copy is from the official and canonical URL, http://www.openapplications.org/oagis/specs/s4i.htm, 1999-03-24; please refer to the canonical source document if possible.]


Home

Who We Are

What's New

Join Us

FAQs

Members

OAGIS

OAMAS

XML

Meetings

Contacts

More Info

                         

 

I.1 Introduction

The World Wide Web Consortium (W3C) has recently released the first version of the XML (Extensible Markup Language) specification. XML is designed to fill a deficiency in other WWW standards, like HTML, by supporting data definition and processing requirements. It provides a middle ground between the restrictions and inflexibility of HTML, and the overall complexity of SGML. This specification has become widely supported as the beginning of the next generation of Internet capabilities.

The Open Applications Group is developing approaches for implementation within an XML framework. This document describes the process for development, translation, and implementation of OAGIS compliant Business Object Documents within the first XML standard release.

Implementation projects may be based on the original message structure, or the XML format described in this document. The decision to use one format or another is left to the integrators, vendors, and ultimately, our customers. It is expected that the need for support of both specifications will decrease over time, as migration to XML occurs. As migration and adoption progresses, the proprietary format may be phased out.

While this document reviews each component of the Interface Specification as implemented in XML, it is not intended to be a primer or training guide. A strong working knowledge of both XML and the OAGIS is assumed. Knowledge of the contents of the EBOD specification is also required.

 

I.2 Overview

XML solutions are comprised of two key components; the DTD (Document Type Definition), and the message itself. The DTD is key to defining and validating the structure and contents of a message. In some cases, the DTD information is embedded inside the message. For the purposes of OAGIS mapping, DTDs will always be implemented as separate files.

According to the W3C Frequently Asked Questions list,

"A DTD is usually a file (or several files to be used together) which contains a formal definition of a particular type of document. This sets out what names can be used for elements, where they may occur, and how they all fit together."

Mapping from the OAGIS specification to XML requires the development of a set of DTDs. The sections below describe the process for developing DTDs to support OAGIS messages, the structure of the DTDs that have been developed and will be released to validate messages, and the conversion of a few sample messages.

The OAGIS is implemented as a set of three resource DTDs, and an additional DTD for each service request. The 5.0 release of the specification included 84 service requests. The resource DTDs include information that is common across all requests. Resource DTDs are used to define Data Types, Fields, and Segments. The service request support files provide their unique definition and structure, as well as additional attributes or element restrictions that are not defined in the resource files.

I.2 Resource DTD – Data Domains

The first resource file used in XML mapping is the data type definition file, 5_0_domains.dtd. This file describes the data types used in all subsequent DTDs.

Below is the entire DTD for data types. We'll discuss each component of the resource file below. Most of this file is comments and revision control information. The actual specification of data types is a single line.

Note that the line numbers in the resource file examples are for reference only, and are not included in the actual files.

XML

001 <!--

002 $Revision: 1.0.1 $

003 $Date: 3 May 1998 $

004 Open Applications Group DTD

005 Copyright 1998, All Rights Reserved

006

007 $Name: 5_0_domains.dtd $

008 -->

009

010 <!-- ==================================================== -->

011 <!-- Entities - Domains

012 This section defines data domains for the

013 primitive element values. This is the only

014 area where the primitive #PCDATA should

015 appear.

016 -->

017

018 <!-- String Data: Generic Data Domain -->

019 <!ENTITY % STRDOM "(#PCDATA)">

Before working through the OAGIS-specific details, a few notes on XML in general.

Delimiters: Components of a DTD are defined by a set of delimiters. In the example above, two are introduced: comments and entities.

Comments: Comments within a DTD are delimited by the tokens <!-- and -->. Information between these tokens is considered a comment and is ignored. Comments may cross multiple lines.

Entities: Entities within a DTD are delimited by the tokens <!ENTITY and -->. In many cases, entities are used to define replacement text within the DTDs.

The DTD provided above is mostly comments, including revision information and documentation. A single entity is defined on line 019.

Revision Control

Each DTD starts with a set of header comments that indicate the distribution version of the file, and basic copyright information. These are defined in lines through 8 of the example above. The example is version 1.0.1 of the DTD for data types required in OAGIS release 5.0.

XML

001 <!--

002 $Revision: 1.0.1 $

003 $Date: 3 May 1998 $

004 Open Applications Group DTD

005 Copyright 1998, All Rights Reserved

006

007 $Name: 5_0_domains.dtd $

008 -->

009

Development Comments

Next, comments for development are provided. In this case, the DTD is used to define data domains. The most primitive element in XML is parsed character data (#PCDATA).

XML

010 <!-- ==================================================== -->

011 <!-- Entities - Domains

012 This section defines data domains for the

013 primitive element values. This is the only

014 area where the primitive #PCDATA should

015 appear.

016 -->

017

In future releases, additional data domain information will be provided in this resource file. All subsequent DTDs will reference the definitions in this file, allowing for global enhancement of data typing and additional attributes.

Data Domain Definitions

The final section of the data type resource file provides the XML definition of the STRDOM entity. This is the default type for fields within the OAGIS. Additional field definitions may be developed later.

XML

018 <!-- String Data: Generic Data Domain -->

019 <!ENTITY % STRDOM "(#PCDATA)">

Entity definitions act as macros for replacement text. References to these entities appear later in the specification DTDs. In the specification above, instances of the STRDOM entity are replaced with the text (#PCDATA).

 

I.3 Resource DTD – Fields

The next resource file used in XML mapping describes field definitions. These are the next most primitive element used in OAGIS mapping. Field definitions are shared across all segment and transaction DTDs.

Below is a portion of the field DTD, 5_0_fields.dtd. In the distributed DTD, all specification fields are provided.

XML

001 <!--

002 $Revision: 1.0.1 $

003 $Date: 3 May 1998 $

004 Open Applications Group DTD

005 Copyright 1998, All Rights Reserved

006

007 $Name: 5_0_fields.dtd $

008 -->

009

010 <!-- ==================================================== -->

011 <!-- Entities - Fields - Appendix C

012 -->

013

014 <!ELEMENT ACCTPERIOD %STRDOM;>

015 <!ELEMENT ACCTYEAR %STRDOM;>

016 <!ELEMENT ACKREQUEST %STRDOM;>

017 <!ELEMENT ADDRLINE %STRDOM;>

018 <!ELEMENT ADDRTYPE %STRDOM;>

019 <!ELEMENT AUTHID %STRDOM;>

020 <!ELEMENT BUSNAREA %STRDOM;>

021 <!ELEMENT CHARGEID %STRDOM;>

022 <!ELEMENT CITY %STRDOM;>

023 <!ELEMENT CODEPAGE %STRDOM;>

024 <!ELEMENT COMPONENT %STRDOM;>

025 <!ELEMENT CONFIRMATION %STRDOM;>

Lines 014 through 025 provided above define the specification fields. Each field is defined as type STRDOM. The STRDOM entity is replaced with the replacement definition. So, the line 14, the ACCTPERIOD element

XML

014 <!ELEMENT ACCTPERIOD %STRDOM;>

 

is parsed with the type definition defined above.

XML

014 <!ELEMENT ACCTPERIOD (#PCDATA)>

 

I.4 Resource DTD – Segments

The third resource file, 5_0_segments.dtd, defines OAGIS segments that are shared across all transactions. One segment, AMOUNT, is provided below, followed by a brief description of each key component.

XML

001 <!--

002 $Revision: 1.0.1 $

003 $Date: 4 May 1998 $

004 Open Applications Group DTD

005 Copyright 1998, All Rights Reserved

006

007 $Name: 5_0_segments.dtd $

008 -->

009

010 <!-- ==================================================== -->

011 <!-- Elements - Segments - Appendix D

012 -->

013

014 <!-- AMOUNT -->

015 <!ENTITY % SEG_AMOUNT_QUALIFIERS

016 "(ACTUAL | APPRVORD | AVAILABLE | BUDGET | DISCNT1 | DISCNT2 |

017 DISCNT3 | DISCNT4 | DISCNT5 | DISCNT6 | DISCNT7 | DISCNT8 |

018 DISCNT9 | DOCUMENT | EXTENDED | ITEM | OPENITEM | ORDER |

019 ORDLIMIT | TAX | TAXBASE | TOTLIMIT)">

020 <!ENTITY % SEG_AMOUNT_TYPES

021 "(T | F)">

022 <!ELEMENT AMOUNT (VALUE, NUMOFDEC, SIGN, CURRENCY, DRCR)>

023 <!ATTLIST AMOUNT

024 qualifier %SEG_AMOUNT_QUALIFIERS; #REQUIRED

025 type %SEG_AMOUNT_TYPES; #REQUIRED>

Each segment has a set of attributes, the QUALIFIER and TYPE. The QUALIFIER is defined as an entity below. In the definition of the AMOUNT element, this definition is referenced. The entity definition lists the set of valid values for the attribute.

XML

015 <!ENTITY % SEG_AMOUNT_QUALIFIERS

016 "(ACTUAL | APPRVORD | AVAILABLE | BUDGET | DISCNT1 | DISCNT2 |

017 DISCNT3 | DISCNT4 | DISCNT5 | DISCNT6 | DISCNT7 | DISCNT8 |

018 DISCNT9 | DOCUMENT | EXTENDED | ITEM | OPENITEM | ORDER |

019 ORDLIMIT | TAX | TAXBASE | TOTLIMIT)">

The second entity that is used to support the AMOUNT element are the type values used in attribute TYPE. These values are defined below.

XML

020 <!ENTITY % SEG_AMOUNT_TYPES

021 "(T | F)">

The AMOUNT element is comprised of six (6) required fields. The definitions of these fields were provided in the resource file 5_0_fields.dtd above. None of these fields are optional, or occur more than once.

XML

022 <!ELEMENT AMOUNT (VALUE, NUMOFDEC, SIGN, CURRENCY, DRCR)>

The AMOUNT element also has an associated set of attributes. They are both required in the XML message. The allowed values are defined through the use of the entities SEG_AMOUNT_QUALIFIERS and SEG_AMOUNT_TYPES.

XML

023 <!ATTLIST AMOUNT

024 qualifier %SEG_AMOUNT_QUALIFIERS; #REQUIRED

025 type %SEG_AMOUNT_TYPES; #REQUIRED>

The remaining segments are defined in the resource DTD with the same structure. Most of them have both attributes, the QUALIFIER and TYPES.

 

I.5 Transaction DTD - Confirm BOD

The three resource DTDs contain definitions that are shared across all transactions. Definitions that are unique to individual transactions are provided in the message DTD. A separate DTD file is distributed for each transaction. The simplest transaction, version 1 of the Confirm BOD, is described in this section. The complete DTD, 002_confirm_bod_001.dtd, is provided below.

The naming convention used for transaction DTD files is "<Chapter>_<Verb>_<Noun>_<Version>.dtd".

XML

001 <!--

002 $Revision: 1.0.1 $

003 $Date: 4 May 1998 $

004 Open Applications Group DTD

005 Copyright 1998, All Rights Reserved

006

007 $Name: 002_confirm_bod_001.dtd $

008 -->

009

010 <!-- ==================================================== -->

011 <!ENTITY % DOMAINS SYSTEM "5_0_domains.dtd">

012 %DOMAIN;

013

014 <!ENTITY % FIELDS SYSTEM "5_0_fields.dtd">

015 %FIELDS;

016

017 <!ENTITY % SEGMENTS SYSTEM "5_0_segments.dtd">

018 %SEGMENTS;

019

020 <!-- ==================================================== -->

021

022 <!ELEMENT BOD (CNTROLAREA, DOCUMENT+)>

023

024 <!ATTLIST VERB value CDATA #FIXED "CONFIRM">

025 <!ATTLIST NOUN value CDATA #FIXED "BOD">

026 <!ATTLIST REVISION value CDATA #FIXED "001">

027

028 <!ELEMENT DOCUMENT (CONFIRM_BOD)>

029

030 <!ELEMENT CONFIRM_BOD (CONFIRM)>

031

032 <!ELEMENT CONFIRM (SENDER, STATUSLVL, DESCRIPTN?, ORIGREF?,

033 USERAREA?)>

In the first section of the transaction DTD, resource information is loaded from the data domains, fields, and segments files. In order to load this information, entities are created to reference the external definitions. When the DTD is parsed, the contents of the external files replace the entity references. These are shown on lines 012, 015, and 018.

XML

011 <!ENTITY % DOMAINS SYSTEM "5_0_domains.dtd">

012 %DOMAINS;

013

014 <!ENTITY % FIELDS SYSTEM "5_0_fields.dtd">

015 %FIELDS;

016

017 <!ENTITY % SEGMENTS SYSTEM "5_0_segments.dtd">

018 %SEGMENTS;

Next, the root, or top-level, element is defined. The same definition is used for all transactions. The BOD element contains two sub-elements. The CNTROLAREA sub-element occurs exactly once. The DOCUMENT sub-element occurs one or many times. The CNTROLAREA element is an OAGIS segment, and is defined in the segment resource file.

XML

022 <!ELEMENT BOD (CNTROLAREA, DOCUMENT+)>

Additional attributes for CNTROLAREA elements are defined to restrict the values that may be provided in the VERB, NOUN, and REVISION elements. When the XML message is generated, the contents of these elements must exactly match the #FIXED values listed.

XML

024 <!ATTLIST VERB value CDATA #FIXED "CONFIRM">

025 <!ATTLIST NOUN value CDATA #FIXED "BOD">

026 <!ATTLIST REVISION value CDATA #FIXED "001">

After the CNTROLAREA is defined, the rest of the DTD describes the structure of the transaction data. The DOCUMENT element is always defined as the verb-noun combination of the transaction. This verb-noun element, CONFIRM_BOD in this example, is then developed from its member data types defined in the OAGIS.

The first OAGIS data type is represented by the CONFIRM element. This element contains two required elements and three optional elements. These elements are defined in the field resource file.

XML

028 <!ELEMENT DOCUMENT (CONFIRM_BOD)>

029

030 <!ELEMENT CONFIRM_BOD (CONFIRM)>

031

032 <!ELEMENT CONFIRM (SENDER, STATUSLVL, DESCRIPTN?, ORIGREF?,

033 USERAREA?)>

The remainder of the transactions defined in the OAGIS follow the same structure as the CONFIRM BOD just described. These transactions are more complex. In many cases, they require deeper element nesting and more sophisticated regular expressions.

 

I.6 Transaction Message – Confirm BOD

XML messages are developed based upon the structures defined in the DTDs. When the message is parsed, it is compared against the DTDs to validate that it is valid and well formed. Each required element must be present in the message, and the elements must be sent in the correct order.

An example of the CONFIRM BOD message implemented in XML follows. The four components of this message are described below.

XML

001 <?xml version="1.0"?>

002

003 <!DOCTYPE confirm_bod_001 SYSTEM "002_confirm_bod_001.dtd">

004

005 <BOD>

006 <CNTROLAREA>

007 <BSR>

008 <VERB>CONFIRM</VERB>

009 <NOUN>BOD</NOUN>

010 <REVISION>001</REVISION>

011 </BSR>

012 <SENDER>

013 <LOGICALID>XXX1234YYY</LOGICALID>

014 <COMPONENT>G/L</COMPONENT>

015 <TASK>CONFIRM</TASK>

016 <REFERENCEID>REF1</REFERENCEID>

017 <CONFIRMATION>0</CONFIRMATION>

018 <LANGUAGE>EN</LANGUAGE>

019 <CODEPAGE/>

020 <AUTHID>JOE DOE</AUTHID>

021 </SENDER>

022 <DATETIME qualifier = "CREATION">

023 <YEAR>1995</YEAR>

024 <MONTH>12</MONTH>

025 <DAY>31</DAY>

026 <HOUR>17</HOUR>

027 <MINUTE>59</MINUTE>

028 <SECOND>00</SECOND>

029 <SUBSECOND>0000</SUBSECOND>

030 <TIMEZONE>-0500</TIMEZONE>

031 </DATETIME>

032 </CNTROLAREA>

033 <DOCUMENT>

034 <CONFIRM_BOD>

035 <CONFIRM>

036 <SENDER>

037 <LOGICALID>XX141HG09</LOGICALID>

038 <COMPONENT>INVENTORY</COMPONENT>

039 <TASK>RECEIPT</TASK>

040 <REFERENCEID>95129945823449</REFERENCEID>

041 <CONFIRMATION/>

042 <LANGUAGE/>

043 <CODEPAGE/>

044 <AUTHID/>

045 </SENDER>

046 <STATUSLVL>00</STATUSLVL>

047 <DESCRIPTN>PROCESSED WITHOUT ERRORS</DESCRIPTN>

048 <ORIGREF>RCPT#12550699</ORIGREF>

049 </CONFIRM>

050 </CONFIRM_BOD>

051 </DOCUMENT>

052 </BOD>

The first line of the message includes the XML release version that was used. For this example, version 1.0 is indicated. The processor will parse the message based upon the 1.0 specification.

XML

001 <?xml version="1.0"?>

Line 003 defines the document type (DOCTYPE) element. This element is defined with three components. The first component is the name of the document type, in this example, "002_confirm_bod_001". The second component is the access path for the definition file, in this example, "SYSTEM". This indicates that the DTD location is an operating system path. The third and final component is the file name of the DTD, "002_confirm_bod_001.dtd".

XML

003 <!DOCTYPE confirm_bod_001 SYSTEM "002_confirm_bod_001.dtd">

Lines 005 through 033 and 051 through 052 contain control data for the message. All transactions include this information, in the same format. The BSR element contains the verb, noun, and version definitions that match the transaction type. SENDER and DATETIME elements are provided as well.

The actual transaction data is included between the DOCUMENT tags. These elements are discussed below.

XML

005 <BOD>

006 <CNTROLAREA>

007 <BSR>

008 <VERB>CONFIRM</VERB>

009 <NOUN>BOD</NOUN>

010 <REVISION>001</REVISION>

011 </BSR>

012 <SENDER>

013 <LOGICALID>XXX1234YYY</LOGICALID>

014 <COMPONENT>G/L</COMPONENT>

015 <TASK>CONFIRM</TASK>

016 <REFERENCEID>REF1</REFERENCEID>

017 <CONFIRMATION>0</CONFIRMATION>

018 <LANGUAGE>EN</LANGUAGE>

019 <CODEPAGE/>

020 <AUTHID>JOE DOE</AUTHID>

021 </SENDER>

022 <DATETIME qualifier = "CREATION">

023 <YEAR>1995</YEAR>

024 <MONTH>12</MONTH>

025 <DAY>31</DAY>

026 <HOUR>17</HOUR>

027 <MINUTE>59</MINUTE>

028 <SECOND>00</SECOND>

029 <SUBSECOND>0000</SUBSECOND>

030 <TIMEZONE>-0500</TIMEZONE>

031 </DATETIME>

032 </CNTROLAREA>

033 <DOCUMENT>

051 </DOCUMENT>

052 </BOD>

Transaction data is provided in lines 034 through 050. Each element provided is contained within a pair of tags, as defined in the DTD. Required tags with no value are shown in lines 041 through 044. The CONFIRMATION element, for example, is not transmitted, but is a required element, according to the DTD. Instead of a pair of tags with no data between (which is legal syntax as well), a single tag is provided instead. Empty tags are indicated by the slash, '/', at the end of the element name.

XML

034 <CONFIRM_BOD>

035 <CONFIRM>

036 <SENDER>

037 <LOGICALID>XX141HG09</LOGICALID>

038 <COMPONENT>INVENTORY</COMPONENT>

039 <TASK>RECEIPT</TASK>

040 <REFERENCEID>95129945823449</REFERENCEID>

041 <CONFIRMATION/>

042 <LANGUAGE/>

043 <CODEPAGE/>

044 <AUTHID/>

045 </SENDER>

046 <STATUSLVL>00</STATUSLVL>

047 <DESCRIPTN>PROCESSED WITHOUT ERRORS</DESCRIPTN>

048 <ORIGREF>RCPT#12550699</ORIGREF>

049 </CONFIRM>

050 </CONFIRM_BOD>

Each XML formatted message will have the same structure. The main components are the version header, DTD reference, control information, and transaction data. Each of these was briefly discussed above.

 

I.7 Translation Steps – Resource Files

Development of the XML resources required for OAGIS support is most easily facilitated by review and conversion of the EBOD distribution files. The EBOD files have been developed in a structure that is quite similar to the discussion above. This section describes the process to convert EBOD files to XML.

As a part of the conversion, some information that is provided in the EBODS is not directly supported by XML. These items will be noted in the discussion. The conversion process and resource file format will be enhanced over time to incorporate as much of this information as possible. These enhancements will be developed through proprietary extensions embedded in comments or attributes, or through adoption of additional capabilities that are released by the W3C.

Domain Resource DTD Definitions

The domain resource file contains data type and value restrictions. In the XML translation, only one domain is defined. Additional attributes are provided in the EBOD resource, OAGDICT.TXT. The differences between the two resource types are described below.

Each field that is defined in the EBOD specification is a member of a domain. One of the domains, dom_char_ls, is shown in the following figure. The name of this domain, by convention, is composed of the primitive type, justification, and padding of the field.

EBOD

001 [dom_char_ls]

002 name=DOM_CHAR_LS

003 dsc=Character – Left justified, space padded

004 datatype=CHAR

005 justification=L

006 pad=" "

The XML translation of this domain is shown below. This domain is currently used for all fields. Later, the DTDs may be extended to support the additional attributes defined in the OAGIS.

A number of attribute values are no longer are relevant, while others are simply not supported at this time.

 

name

internal domain name

changed to STRDOM

dsc

description

Not supported in this release

datatype

primitive type of data

All are character #PCDATA

justification

data alignment within field

Not applicable in XML

pad

filler characters

Not applicable in XML

 

XML

001 <!ENTITY % STRDOM "(#PCDATA)">

 

All fields in later DTDs reference the STRDOM definition.

Field Resource DTD Definitions

The next resource area for translation is the set of field definitions. Again, a number of attributes are provided for fields as a part of the EBOD reference. This information is also provided in the OAGDICT.TXT resource file. Please refer to the EBOD documentation for details on the definition of each field attribute.

EBOD

001 [f_drcr]

002 // Used in Amount segment

003 name=DRCR

004 dsc=Debit or credit flag

005 usage=S

006 domain=DOM_CHAR_LS

007 length=1

008 min=

009 max=

010 value="C", "Credit"

011 value="D", "Debit"

012 value=" ", "Default"

When translated into XML, the name and primitive data type are the only information provided. A number of attribute values are no longer are relevant, while others are simply not supported at this time.

 

name

internal field name

Used as the element name

dsc

description

Not supported in this release

usage

where field is used in specification

Not supported in this release

domain

data type domain

All defined as STRDOM

length

fixed length of field

Not applicable in XML

min

minimum value

Not supported in this release

max

maximum value

Not supported in this release

value

set of possible values and description

Not supported in this release

 

XML

001 <!ELEMENT DRCR %STRDOM;>

 

Each field that is used in the specification should be added to the field resource DTD. Fields used in segments are handled in the same manner as those defined directly in the transaction data types. Field alignment, padding, and length restrictions are no longer required in the XML translation.

Segment Resource DTD Definitions

The third resource that is translated in the conversion to XML is the set of segment definitions.

EBOD

001 [s_amount]

002 // Used in 001003 Post Journal

003 name=AMOUNT

004 dsc=Used to communicate monetary data between applications

005 version=001

006 size=57

007 field=f_qualifier

008 field=f_type

009 field=f_value

010 field=f_numofdec

011 field=f_sign

012 field=f_currency

013 field=f_drcr

014 qualifier=actual

015 qualifier=apprvord

016 qualifier=available

017 qualifier=budget

018 qualifier=discnt,1,9

019 qualifier=document

* Note: The qualifier list is not complete in this example. It has been

trimmed for readability.

A number of attribute values are no longer are relevant, while others are simply not supported at this time.

name

internal field name

Used as the element name

dsc

description

Not supported in this release

version

segment version

Not supported in this release

size

segment size

Not applicable in XML

field

member fields

Included in element definition

qualifier

valid segment qualifiers

QUALIFIER attribute

 

In some cases, additional information is provided in the translated XML resource.

AMOUNT

Transaction type qualifier

Included in XML definitions

 

XML

015 <!ENTITY % SEG_AMOUNT_QUALIFIERS

016 "(ACTUAL | APPRVORD | AVAILABLE | BUDGET | DISCNT1 | DISCNT2 |

017 DISCNT3 | DISCNT4 | DISCNT5 | DISCNT6 | DISCNT7 | DISCNT8 |

018 DISCNT9 | DOCUMENT | EXTENDED | ITEM | OPENITEM | ORDER |

019 ORDLIMIT | TAX | TAXBASE | TOTLIMIT)">

020 <!ENTITY % SEG_AMOUNT_TYPES

021 "(T | F)">

022 <!ELEMENT AMOUNT (VALUE, NUMOFDEC, SIGN, CURRENCY, DRCR)>

023 <!ATTLIST AMOUNT

024 qualifier %SEG_AMOUNT_QUALIFIERS; #REQUIRED

025 type %SEG_AMOUNT_TYPES; #REQUIRED>

Each segment defined in the OAGIS is provided in the segment resource file, 5_0_segments.dtd. These are then available to all transaction DTDs.

 

I.8 Translation Steps – Transaction Files

The differences in the way transaction files are defined in the EBOD and XML are significant. XML allows for a very flexible definition of the overall structure, with straightforward support for optional and multiple fields embedded in the message data. The original structure of an OAGIS format message was to provide sets of header meta-data to describe the message fields.

Control Area DTD Definitions

The first section of the control area defined in the EBOD specification provided meta-data and references its member sub-areas.

A number of attribute values are no longer are relevant, while others are simply not supported at this time.

name (BODSPEC)

internal area name

Element BOD

bodrelease

release of the specification for format

Defined in the resource files 5_0_*.dtd

version

sub-version of the specification

Defined in the resource files 5_0_*.dtd

startmarker

first placement marker in message

Replaced by <BOD> tag in XML

endmarker

last placement marker in message

Replaced by </BOD> tag in XML

area

member elements

Defined in XML element definition

field

member fields

Defined in XML element definition

 

The two areas, a_control_area and a_business_data_area, are renamed to CTROLAREA and DOCUMENT in the XML translation. The CNTROLAREA is defined as a segment. The DOCUMENT element is discussed in the next section.

EBOD

001 [bodspec]

002 name=BODSPEC

003 bodrelease=5

004 version=0

005 startmarker=MBBOD

006 endmarker=MEBOD

007 area=1,0,a_control_area

008 area=1,1,a_business_data_area

009

010 [a_control_area]

011 name=CNTROLAREA

012 startmarker=

013 endmarker=

014 field=1,S,s_cntrolarea,001

The EBOD area definition translation to XML warrant some additional discussion. The BOD element definition provides the same information in a different structure. In line 007 of the EBOD example above, a_control_area is defined as required and single instance. The BOD element in the XML example below has the same restrictions. The regular expression, "CNTROLAREA" indicates that it is required and only occurs once. In the same fashion, the required and possible multiple area, a_business_data_area, defined above is represented by the regular expression "DOCUMENT+".

The field definition components in the EBOD format are, simplified in the translation to XML. The first component, number 1, indicating that the field is mandatory, is defined in the regular expression for the BOD element. The type indicator, S for segment in this case, is not translated. The segment version number is also unsupported at this time.

XML

001 <!ELEMENT BOD (CNTROLAREA, DOCUMENT+)>

002

003 <!ATTLIST VERB value CDATA #FIXED "CONFIRM">

004 <!ATTLIST NOUN value CDATA #FIXED "BOD">

005 <!ATTLIST REVISION value CDATA #FIXED "001">

006

007 <!ELEMENT DOCUMENT (CONFIRM_BOD)>

Additional attributes are defined in the header information. The VERB, NOUN, and REVISION attributes are required, and must match the corresponding, appropriate transaction values. The remainder of the CNTROLAREA element definition is provided in the segment resource file, 5_0_segments.dtd. This is another significant change from the EBOD structure, where the member fields and structure of the entire control area are provided in the BOD definition file.

The structure of the transaction information is discussed in the next section.

Transaction DTD Definitions

In the EBOD definition, the transaction and control structures are handled as distinct resources. The conversion to XML merges the two structures together, causing some overlap in the discussion of file definitions.

The EBOD sample below is from the transaction definition file. Note that many of the same attributes defined above are provided here. A number of attribute values are no longer are relevant, while others are simply not supported at this time.

name (BSRSPEC)

internal area name

Element DOCUMENT

verb

verb for the transaction

Defined in the BOD attributes

noun

noun for the transaction

Defined in the BOD attributes

revision

revision number for the transaction

Defined in the BOD attributes

bodrelease

release of the specification for format

Defined in the resource files 5_0_*.dtd

bodversion

sub-version of the specification

Defined in the resource files 5_0_*.dtd

area

member elements

Defined in XML element definition

field

member fields

Defined in XML element definition

 

The first area in the [bsrspec] definition is the name of the OAGIS data type(s) for the transaction. These may occur multiple times, and additional fields may be present as well.

EBOD

001 [bsrspec]

002 verb=CONFIRM

003 noun=BOD

004 revision=001

005 bodrelease=5

006 bodversion=0

007 area=1,0,a_confirm

008

009 [a_confirm]

010 name=CONFIRM

011 field=1,S,s_sender,,,001

012 field=1,F,f_statuslvl

013 field=0,F,f_descriptn

014 field=0,F,f_origref

015 field=0,F,f_userarea

In the translation to XML, these are encapsulated in the DOCUMENT element. The DOCUMENT element contains a reference to only a single element created from the transaction's verb and noun. In this case, the element is CONFIRM_BOD. The CONFIRM_BOD element is then defined with its member data types.

Segments and fields are defined in the reference files, so the element definition simply lists the order of the fields, which are required, and which may have multiple instances. In the example below, two (2) fields and required, and three (3) are optional. Each may occur only once.

XML

001 <!ELEMENT BOD (CNTROLAREA, DOCUMENT+)>

002

003 <!ATTLIST VERB value CDATA #FIXED "CONFIRM">

004 <!ATTLIST NOUN value CDATA #FIXED "BOD">

005 <!ATTLIST REVISION value CDATA #FIXED "001">

006

007 <!ELEMENT DOCUMENT (CONFIRM_BOD)>

008

009 <!ELEMENT CONFIRM_BOD (CONFIRM)>

010

011 <!ELEMENT CONFIRM (SENDER, STATUSLVL, DESCRIPTN?,

012 ORIGREF?, USERAREA?)>

Conversion Steps

Generating DTDs from the OAGIS is a straightforward process. The steps in the conversion are described below. Many of the constructs have already been described.

1. Update CNTROLAREA attributes for the transaction. The VERB, NOUN, and REVISION values must match the transaction.

000 <!ATTLIST VERB value CDATA #FIXED "VERB">

000 <!ATTLIST NOUN value CDATA #FIXED "NOUN">

000 <!ATTLIST REVISION value CDATA #FIXED "REVISION">

2. Create transaction element within DOCUMENT. The DOCUMENT entity definition includes only one element. This element is the concatenation of the transaction verb and noun, with an underscore between.

000 <!ELEMENT DOCUMENT (VERB_NOUN)>

3. Add segments for Data Types.

3.1 Add required segments in the element definition.

000 <!ELEMENT SAMPLE (REQSEGMENT)>

3.2 Add optional segments in the element definition.

000 <!ELEMENT SAMPLE (REQSEGMENT, OPTSEGMENT?)>

4. Add fields in the element definition.

4.1 Add required fields in the element definition.

000 <!ELEMENT SAMPLE (REQSEGMENT, OPTSEGMENT?, REQFIELD1, REQFIELD2+)>

4.2 Add optional fields in the element definition.

000 <!ELEMENT SAMPLE (REQSEGMENT, OPTSEGMENT?, REQFIELD1, REQFIELD2+, OPTFIELD1?, OPTFIELD2*)>

5. Add USERAREA element.

000 <!ELEMENT SAMPLE (REQSEGMENT, OPTSEGMENT?, REQFIELD1, REQFIELD2+, OPTFIELD1?, OPTFIELD2*, USERAREA?)>

6. Add Rules. If processing rules are provided for the Data Type, the ELEMNAME_RULE element added to the element definition. The rule element name is the concatenation of the parent element and 'RULE', separated by an underscore ('_').

In the example below, the processing rule is "OPTFIELD1 and OPTFIELD2 are mutually exclusive".

000 <!ELEMENT SAMPLE (REQSEGMENT, OPTSEGMENT?, REQFIELD1, REQFIELD2+, OPTFIELD1?, OPTFIELD2*, USERAREA?, SAMPLE_RULE?)>

000 <!ELEMENT SAMPLE_RULE (OPTFIELD1 | OPTFIELD2)>

If more than one processing rule is required, elements are created with a numeric index concatenated to the element name.

000 <!ELEMENT SAMPLE (REQSEGMENT, OPTSEGMENT?, REQFIELD1, REQFIELD2+, OPTFIELD1?, OPTFIELD2*, USERAREA?, SAMPLE_RULE1?, SAMPLE_RULE2?)>

000 <!ELEMENT SAMPLE_RULE1 (OPTFIELD1 | OPTFIELD2*)>

000 <!ELEMENT SAMPLE_RULE2 (OPTFIELD3 | OPTFIELD4)>

6.1 Remove rule elements. Elements that are parts of a rule definition are removed from the parent element.

000 <!ELEMENT SAMPLE (REQSEGMENT, OPTSEGMENT?, REQFIELD1, REQFIELD2+, USERAREA?, SAMPLE_RULE?)>

000 <!ELEMENT SAMPLE_RULE (OPTFIELD1 | OPTFIELD2*)>

7. Add Sub-Data Type elements. The last elements that are added to the definition are references to sub-elements.

000 <!ELEMENT SAMPLE (REQSEGMENT, OPTSEGMENT?, REQFIELD1, REQFIELD2+, USERAREA?, SAMPLE_RULE?, SAMPLE_CHILD1, SAMPLE_CHILD2)>

000 <!ELEMENT SAMPLE_CHILD1 (…)>

000 <!ELEMENT SAMPLE_CHILD2 (…)>

8. Repeat steps 3 through 8 for each element.

 

http://www.openapplications.org -- Revised: 23 March 1999
Copyright 1999 Open Applications Group, Inc.  All Rights Reserved.
All other trademarks and copyrights are the property of their respective holders.
Legal Terms

For comments about the Open Applications Group's world wide web services contact our Webmaster