6
Message Description Language Reference

This chapter describes message description language and its concepts. The following topics are discussed:

What is Message Description Language?

Message oriented technology does not have any type description which object-technologies, like OracleAS InterConnect, require. The language specification describes the internal data format of each message buffer. The CICS adapter uses the message description language to describe the CICS buffer.

Message description language elements are message buffers sent or received by the CICS adapter mapped as message description language method arguments. The mapping allows object-oriented technologies to have a familiar view of the message buffers, with each message treated as a single argument or separated into multiple arguments. The CICS adapter automatically concatenates the arguments at run-time. The request and reply messages are grouped as a single method with input and output arguments. One message description language interface groups message description language methods (performing similar tasks) for a specific message queue.

Message Description Language Classes

To make CICS servers visible as components to OracleAS InterConnect, you must first describe a set of methods using message description language. A method call translates into a request message and a reply message. The request message contains all the input arguments and the reply message contains all the output arguments.

The CICS adapter uses message description language *.cls files as the representation of component interfaces with methods having elements as arguments. For example, the message definition:

method GetBalance
  in BankName bank
  in CustName customer
  out Balance balance
  out CustStatus status
end method

defines a method containing four arguments with the type defined using message description language fixed length string types:

typedef string(54,' ',tail) BankName
typedef string(30,' ',tail) CustName
typedef string(20,' ',head) Balance
typedef string(20,' ',tail) CustStatus

Message Description Language File

An message description language file is a text file with an *.cls extension. It contains four types of declarations:

Every message description language file requires a class declaration; it is always the first declaration in an message description language file. All other declarations are written within it. The typedef and struct declarations are optional. All declarations reside on separate lines, there are no delimiters (such as semi-columns, or commas) required in any declarations.

Class Declaration

A class describes the set of functions and class specific complex types. Classes are always the topmost level of a CLS file. They are declared with a class classname [(default URL)] [endianness] and [character encoding] declarator, and are terminated with an end class terminator. All class declarations should be on a separate line and the class declarator and terminator must be defined on separate lines. Interfaces may not be nested. A single public class declaration may reside within a CLS file and the name of the file must match the name of the class. Class definitions may contain:

Type definitions (typedef declaration):
- Structures definitions (struct declaration)
- Method definitions (method declaration)
Layout of a class declaration:
```
class class name [(default URL)] [endianness][character encoding]
```
```
struct declarations...
typedef declarations...
method declarations...
```
```
end class
```
where:
- class name--The name of the class. This name must be the same as the file name.
- (default URL)--Specifies the default URL on the class declaration line.
- [endianness]--The bigendian and littleendian keywords act as endian convention gateways, and they specify in which format the CICS adapter sends the binary integral types. Use these keywords when the CICS adapter receives integral types regardless of its platform`s convention. For example, if all integral types sent to the CICS adapter are always in the bigendian convention, prefix the message description language endainness with the bigendian keyword. Similarly, if all integral types sent from the CICS adapter are in the bigendian convention, declare message description language endianness on message description language class declarations such as bigendian.littleendian modifiers follow the same logic. In the absence of such keywords, the CICS adapter treats these types as opaque entities and provides them the same way as it receives them--which means the CICS adapter always expects to receive and send integral types using the platform`s format where the CICS adapter is running.
  
  See Also:
  "Integral Types" for an explanation of binary integral types
[character encoding]--The ASCII and EBCDIC keywords act as character encoding convention gateways. They specify in which format the CICS adapter sends and receives the string type. Use these keywords when the CICS adapter receives string types of a certain convention regardless of your platform's convention.
struct declarations--A declaration for a collection of variables grouped together for convenient handling.
typedef declarations--Provides a new name for an existing type.
method declarations--Sends messages through the messaging system and receive replies by abstracting incoming and outgoing messages as method input and output parameters.
end class--The class terminator.

Typedef Declaration

Typedef declarations do not create a new type; their purpose is to provide a new name for an existing type. The following is an example of a typedef declaration:

typedef composite type new name

Struct Declaration

Structures can contain:

Binary
String
Complex Types
Predefined Structures

Structures are declared with a structure declarator struct struct name and a terminator end struct which must reside on separate lines. Structures may be nested using predefined structures.

The layout of a struct declaration is as follows:

struct struct name
   field declaration
   field declaration
end struct

Note:

Field declarations are specific to the declared type, and are identical to the type declarations described in "Supported Data Types" .

Method Declaration

Methods describe the act of sending a message through the messaging system, and of receiving replies to those messages. The concatenation of the in and inout parameters form the contents of a message sent to the destination specified by the URL. The return, out, and inout parameters form the reply message and the in and inout parameters form the request message. Contextual information that is part of the requests and reply messages map as inout parameters. When mapping the reply message, the return value precedes the out and inout parameters, in the same parameter order. Methods map to corresponding methods in other systems as synchronous calls, which emit a blocking wait for the reply message.

Methods are described in message description language as method <method name> [(method properties)] [async] and terminator end method, residing on different lines. They always contain a return argument description on the next line (using the keyword return), and a list of argument declarations directly following the return statement.

The layout of a method declaration is as follows:

method <method name> [(method properties)] [async]

return <return type>
argument declarations

end method

where:

<method name> is the name of the method.
(method properties) provides the message-oriented server a list of properties. There is no property for the lu62cpic protocol.

The format of the properties list for the ECI protocol is:

(<property>=<value>...)

where:

<property> is the name of the property. 
<value> is the value accepted by the property..

Table 6-1 describes method properties, an explanation, and an acceptable value.

Table 6-1 Method Properties

Method Properties	Explanation	Acceptable Values
`commarea`	The size of the commarea used by the remote CICS program. The maximum size is determined by CICS software, which is 32500 bytes	A number up to 32500

Note:

The commarea size is calculated at run time. It is the actual size of the in and inout arguments. If the value specified in commarea is smaller than the computed value a warning message is included in the CICS adapter log file and the computed value is used. If a value greater than the acceptable maximum (32500) is used, a warning is also logged and the maximum is used.

[async]--Indicates the OracleAS InterConnect adapter will not wait for a server reply message and, in the case of a message OracleAS InterConnect adapter, the CICS adapter will not send a reply message.
<return type>--Returns a certain supported type or a void argument if is the method does not return anything.
<argument declarations>--Arguments may consist of binary, string, and complex types, and structures.
End method is the method terminator.

Return Type Declaration

Return type arguments may consist of:

void arguments
binary types
string types
complex types
structures

It is recommended to always void for the return argument as most messaging systems do not have a notion of a return argument. If a method returns a certain supported type, the return declaration is formulated as the return keyword, followed by the type declaration.

See Also:

"Supported Data Types"

For example:

return type declaration

A method that does not return anything must explicitly declare it to include the void keyword. For example:

return void

An EOL delimiter separates return declarations from the rest of the method declaration.

Argument Declarations

The syntax declaration of an argument declaration is the following:

  arg direction_type declaration

where:

arg direction--Describes the argument direction and may be either of the keywords in, inout or out. The in keyword describes arguments whose contents are initialized by the client, and are useful to the server. The inout keyword describes parameters which may contain information for both the client and the server (a variable initialized by the client, and which may be modified by the server). The out parameter describes arguments initialized by the server and serves as a data recipient for information returned to the caller.

For example:

#describes an "in" parameter which contains data for the server
in type declaration 

#describes an "out" parameter which serves as data recipient for the client
out type declaration

#describes an "inout" parameter which serves as data recipient for both the
server and the client
inout type declaration

Argument names are significant only to the systems to which the method that is exposed. An EOL (End of line) delimiter separates argument declarations.

Note:

You can insert comments anywhere in an message description language file by inserting pound signs "#" at the beginning of a line. Throughout this chapter comments will precede the example.

Supported Data Types

An message description language file supports the following data types:

Table 6-2 identifies the different types belonging to the three supported types:

Table 6-2 Supported Types

BINARY	STRING	COMPLEX
Floating Point	Length Prefixed	Date
Integral	Delimited	Numerical: Floating Point Fixed Scale, Variable Precision Numbers Fixed Scale, Fixed Precision Numbers Packed Decimal
	Fixed-Length Padded	Array (tables):` Fixed Length Tables Prefixed Length Tables Explicitly Delimited Variable Length Sequences Implicitly Delimited Variable Length Sequences
	Null Terminated	Structured Types
	Implicit

Binary Types

Supported binary types must be in your system platform endianness, or in that endianness which is specifically indicated for the class it is used, align on a 1 byte boundary. They include integer and floating point, up to 32 bits.

See Also:

"Class Declaration"

Binary types are all simple types of binary nature separated into two main subclasses:

Integral Types--Binary types describing integral numbers.
Floating Point Types--Real numbers, containing a mantissa and an exponent.

Integral Types

Integral types come in various formats: 8, 16, 32 bits signed or unsigned. They are always declared as their sign concatenated with their size in bits. For example:

signed8 aChar
signed16 aShort
signed32 aLong
unsigned8 aByte
unsigned16 aWord
unsigned32 aDoubleWord

Floating Point Types

There are two supported floating point types. 32 bit IEEE binary floating point is declared with the type specifier single, and 64 bit IEEE floating point is declared with the type specifier double. For example:

single myFloat
double aBigNumber

The run-time data format of binary floating point types always follow the IEEE binary standard.

Floating point types are generally mapped to similar (IEEE), binary entities in other systems.

String Types

All character types are assumed to be in your native system platform character set where the CICS adapter is running. The strings can be of fixed or variable length, with a length prefix or a terminating delimiter. Strings are declared with the keyword string and may come in five string styles.

Note:

The presence of NULL characters in any of the following string types may cause unwanted behavior when the latter are mapped into other systems.

Length-Prefixed Strings

Length prefixed strings are variable length strings where a length specifier precedes the string at run-time. They are declared by following the string type with its length type specifier. The length specifier may be any of the numerical or integral types, and should immediately follow the string keyword. Prefixed string types do not take any parameters. For example:

string prefixed length type declaration_string name

where:

length type declaration may be any of the numerical or integral types, and consists in a standard type declaration.

For example:

 #this string is length prefixed with a binary double-word
 string prefixed unsigned32 myPrefixedString
 #this string is length prefixed with a fixed numerical value 
 #for which there are 5 digits reserved for the integer part, 
 #no decimal digits or decimal separator enclosed in a dot
 #delimited string.
 string prefixed number(5, 0, none) in string(`.`) 
   myNumPrefixedString

Length prefixed strings are expected to have their length prefixed with a numerical type or integral type (as described in the message description language) which should directly precede the string itself. They map such strings in other systems if they are available in the target system or as null terminated strings if they are not. The decimal component of numerical types passed as the string`s length is always ignored if present.

See Also:

"Complex Types"

Delimited Strings

Variable length strings for which the length is determined at run-time by the presence of a delimiter. They are declared the string type and have a type parameter for delimiter.

 string(delimiter ) string name

Delimiters are not considered part of the displayable string, and are generally replaced by null terminated strings in other systems, in which the delimiter has been removed.

For example:

  string(`,`) myCommaTerminatedString

Null Terminated Strings

Delimited strings map in general as null terminated strings, the EOS (End of String) delimiter is considered as an inherent part of the string and appear in the final data.

For example:

string(0) myNullTerminatedString

Fixed-Length Padded Strings

A fixed string's maximum length is known in advance. Declared by passing three parameters to the string type keyword, which are, respectively the size of the string, the padding character, and the padding convention. The padding convention parameter consists of the tail, head or none keywords, which indicates where the padding occurs. The none keyword indicates no padding occurs, and that the string is always assumed to take up the full fixed length (a date string, for example, may always contain a certain count of characters).

string(str size, padding char, pad convention) name

For example:

#declares an 80 character wide string padded with spaces
   string(80, ` `, tail) myString

#declares a 40 character string front padded with spaces
   string(40, ` `, head) myString 

#declares a 40 character wide string front padded with zeros
   string(40, `0`, head) myString

#declares a 40 character wide string with no padding
   string(40, none, none) myString

Fixed length strings map fixed length strings if such notions exist in the target other system. They may also map into variable length strings for which the maximum length is the fixed length described in the message description language, and the actual length is always at maximum.

Implicit Strings

Implicit strings are implicit sequences where the base type is signed8. The declaration is string implicit. The CICS adapter assumes that meeting this type means that the entire data buffer is a string.

Implicit strings have the following limitations:

Cannot be defined in arrays.
If defined in a structure, it must be the only field.
Must be the only in, out, or inout argument defined in a method.

Complex Types

Complex types come in as a composition of different or similar sets of string types and binary types.

Date Types

Date types are stored in any of the supported string types. The date type represents the date under the form of a fixed length string. The supported date formats are respectively DDMMYY, DDMMYYY, MMDDYY and MMDDYYYY. The date type parameter string defines the date field separators.

date(date format ) in string type  myDateVar

For example:

date("DD-MM-YY") in string(8,none,none) myYear2000bug
date("DD/MM/YYYY") in string (10,none, none)
  myYear2000compliantDate
date("MM DD YYYY") in string (10,none, none)
  mySpaceSepY2KCompDate
date("MM.DD.YY") in string(10,none,none) mydotSeparatedY2KBug

Separators are mandatory, although their nature may be of any sort.

When delimited strings are used, the date string should exclusively contain the date and delimiter, or have the date left aligned within the string.

Date types map other system date formats, if any exist. For example, they would map DATE structures in the case of COM, for example. If no such date formats exist, they map as variable length strings.

Numerical Types

Numerical types are formatted numbers stored within any of the supported string types (for example, numerical types are stored in ASCII). They always have a string declaration following their type declaration. The following lists supported numerical types:

Floating Point Numbers

Represented as exponent based ANSI floats. They are declared as follows:

number in string type declaration name

For example:

number in string(`*`) MyStarTerminatedFloat
number in string(30,``, tail) MyFixedLengthFloat
number in string unsigned16 MyPrefixedLengthFloat

#This is a number within a prefixed string itself prefixed with a 
#number within a prefixed string prefixed with a binary byte.
#This is not the best design, but still legal
number in string prefixed number in string prefixed signed8 MyNumber

Fixed Scale, Variable Precision Numbers

Strings in which the decimal separator may freely reside. They are declared as follows:

number (dec separator) in string type_name

where:

decimal separator may be the keyword none, specifying an entirely integral number.
name is the name of the defined type.

For example:

#declaration for the form 398.029
number(`.`) in string(`_`) myDotDecimalUnderscoreTerminatedNb

Note:

When the decimal separator is specified, the maximum number of integral and integral precision is 7 digits. For example, 1234567.1234567

#declaration for the form word len "98372"
number(none) in string prefixed unsigned16
myIntegralWordPrefixedNumber

A fixed scale, variable precision number is always confined in the limits the string it resides in imposes. For example:

#This number may NOT exceed 20 characters.
#"12345678901234567890"
#The following is the declaration definition
number(none) in string(20,`0`,head) my20CharNumber

Fixed Scale, Fixed Precision Numbers

Strings in which the number integral digits and decimal digit is constant. They are declared as follows:

number (Idigits, Ddigits, dec sep) in string type name

where:

Idigits and Ddigits respectively represent the count of integer and decimal digits.

decimal separator may be the keyword none, indicating that the decimal separator`s position is implied in the number`s format, and not expected in the run-time string.

name is the name of the defined type

#declaration in the form of "1234567890.12345_"
number (10, 5, `.`) in string(`_`) myUnderscoreFixedNumber

#declaration of the form of "00000123456789012345" = 1234567890.12345
number(10,5,none) in string(20, `0`, head) myNumber

As for the preceding Number type, the fixed scale, fixed precision numbers may be bounded by the string type in which case the decimal, then digits, should be truncated in order to fit inside the string constraints.

#declaration of the form of "123456789012" = 1234567890.12
number(10,5,none) in string(12, `0`, head) myNumber

Packed Decimal

An internal representation of numbers. It is also called BCD (Binary Code Decimal). The field size is variable and can be determined by the number of digits divided by two (truncated) plus one. For example, if you have the number +123.45 the internal representation is 0x12345c and the length is 3 bytes. If you have the number -12.34, the internal representation is 0x1234D and the length is 3 bytes.

number (Ydigits, Zdigits) packed name

where:

Ydigits and Zdigits respectively represent the number of integer and fractional digits.
name is the name of the defined type.

Array Types (Tables)

Arrays come in four variants: fixed length, length prefixed, explicitly delimited, and implicitly delimited. Each element has the same type. Unless the array is explicitly delimited, there are no special delimiters between the elements of an array itself since the delimiters of the contained data type act as implicit delimiters. Array types consist of variable or fixed sequences of a certain type. They are defined with a base type (the sequence`s element type) and of subscript operators, in the case of fixed arrays.

The base type may be any of the structures, binary, string, complex types, or tables:

Fixed length tables map to bound sequences in other systems.
All variable length tables map to unbound sequences in other systems.
Tables may be nested in any given combination provided the inner tables' definition has been defined.

For example:

#variable length table of bytes length prefixed with a DWord
typedef table prefixed unsigned32 of unsigned8 varByteTbl_t
#fixed length table of the preceding table type
table(80) of varByteTbl_t myNestedTables

#This is incorrect syntax because a nested array where the inner array must be 
predefined cannot use the table keyword table(80) of table prefixed unsigned32 
of unsigned8 myNestedTables

Fixed Length Tables

Fixed length tables do not have any associated run-time data overhead.

table(subscript ) of base type declaration  table name

For example:

table(30) of signed8 myVariableByteTable

Prefixed Variable Length Tables

Prefixed variable length tables have an message description language described length indicator preceding the table at run-time.

table prefixed length type decl of base type decl name

For example:

#table of prefixed length with a word of null terminated string
typedef table prefixed unsigned16 of string(0) myT

Explicitly Delimited Variable Length Sequences

Explicitly delimited variable length sequences have a delimiter between each element.

table(cont del , end del ) of base type decl  name

For example:

#each element has a comma separator between them until
#the last element is reached, where a dot appears.
#declaration for the form dword , dword  ... dword .
table(`,`,`.`) of signed32 myDWordTbl

#declaration for the form string(`.`) , string(`.`)  " string(`.`) .
#example: "helloworld.,helloworld2.,helloworld3.."
table(`,`,`.`) of string(`.`) myDelimitedStringTbl

One message description language-specified delimiter is used to indicate the table`s continuation while the other indicates a terminator. For example, the run-time format is:

elmnt 1  cont del  elmnt 2  cont del  ... elmnt n  end del

where:

elemnt 1 is the first element and elemnt n is the last.
cont del is the continuation delimiter (first type parameter).
end del is the end delimiter (second type parameter).

Implicitly Delimited Variable Length Sequences

Implicitly delimited variable length sequences terminate at the end of the provided buffer.

table implicit of base type decl  name

Example:

#This is the same as a string implicit
table implicit of unsigned8 myByteTable

Some of the reply messages have items in a sequence where the length is determined by how many items are in the message buffer (there is no length prefix). COM and CORBA arrays and sequences must have a length defined before they can be filled.

Structured Types

These are structures or records containing a set of named fields where each field can have a different type. Field types are binary, string, date, or numerical types. The syntax of the fields determines the layout of the structure. There are no special delimiters for fields of a structure itself, the delimiters of the data types of the fields themselves act as implicit delimiters between fields. Fields are not named within the message itself; they are intended for systems such as CORBA and COM.

Message Description Language File Format General Syntax Conventions

This section describes the general syntax conventions for the message description language file format.

Type parameters

Certain types require fully-defined parameters, such as fixed-length table (array) types, requiring subscript parameters, or fixed-length strings, requiring a description of their length and formatting style. Enclose these parameters within parenthesis "()" or brackets "[]". Separate the parameters by commas "," if more than one parameter qualifies the given type. Type parameters always directly follow the type they modify. When passing characters as parameters, pass them enclosed respectively in quotes ` ` and double quotes " ". If passing non-printable characters, type their binary values instead. Parameter ordering is specific to the type concerned.

For example:

The following is a null terminated string:

string(0) myString

The following declares a fixed array of 40 bytes:

table(40) of signed8 myCharTable

The following is equivalent to the preceding line:

table[40] of signed8 myCharTable2

The following is a date declaration:

date("DD/MM/YYYY") in string(10,` `,tail) myDate

Type modifiers

There are two different classes of type modifiers, Keyword and Type Declaration modifiers.

Keyword Modifiers

Modifiers, such as specifying the alignment specifiers for fixed length strings, always follow the type itself. Type keyword modifiers never have parameters.

The following is a fixed length string, of 34 bytes, aligned to the right and padded with zeros:

string(34, `0`, head) myString

Type Declaration Modifiers

Certain types require other types to be defined (declared) in order to be completely defined, for example, when the primary type aggregates, is contained in, or prefixed by another type. Insert the keywords of, in, and prefixed, to describe these different cases. Define the additional types following the original type declaration. Tables, for example, contain elements of another type. To fully define the table, declare the elements within the type declaration.

The following declares an array of 40 bytes:

table(40) of unsigned8

The following declares an array of 40 dot delimited strings:

table(40) of string(`.`)

The following declares a variable length array of (variable length strings prefixed with dot delimited fixed numbers) length prefixed with a byte:

table of string prefixed number(5,5,none) in string
`.`)prefixed signed8

Types which prefix another are either numerical or binary types.
Types which aggregate (in) another are always string types.
Types contained in (of) may be of any type.

Expression

Expressions are not supported by the message description language parser. For example, the following expression is valid:

string(25)myString

The following expression is invalid:

string(10 + 50)myOtherString

Alias

To create an alias for a given type, use a typedef:

typedef type declaration  typedef name

For example:

typedef string prefixed number(5,0,none) in string(`.`)
   myString_t
  struct myStruct
     MyString_t structName
   table(80) of myString_t myAddressList
end struct

Typedef declarations are always global to the file where they are defined. Their declarations must precede their usage.

Comment Insertion

Insert comments anywhere in the file by inserting pound signs "#" at the beginning of a line. For example:

   #commented line
   signed16 myShort this part is NOT commented

Case Sensitivity

The message description language is case sensitive, and its reserved keywords are always lower cased. Keywords with different case conventions as identifiers are legal. For example:

#valid statement
signed16 Signed16
#valid method
method Method

Message Description Language File Example

The following is an example of a message description language file called CLS.

#MyClassName.CLS
#Tabs (or spaces) and Extra EOLs are here only for readability.
#Keywords are in bold.
   class MyClassName
   typedef string(`.`) string_t
   typedef number(5,5,`.`) in string(11,` `,none) number_t
       #this structure declaration is private to MyClassName
struct Account
       string_t structName
       string_t clientName
       unsigned16 accntID
       number_t balance
   end struct
       typedef table(`,`,`.`) of Account AccountList_t
       struct BankInfo
       string_t structName
       string_t bankName
       AccountList_t accountList
       table(80) of string_t debtorNameList
       date("DD-MM-YY") in string_t lastModificationDate
  end struct
  #Get account info method
   method GET 
       return void
       in string_t clientName
       out Account account
   end method
   #Add new account method
       method ADD
       return BankInfo bankInfo
       out string_t result
    end method
end class

6Message Description Language Reference

What is Message Description Language?

Message Description Language Classes

Message Description Language File

Class Declaration

Typedef Declaration

Struct Declaration

Method Declaration

Table 6-1 Method Properties

Return Type Declaration

Argument Declarations

Supported Data Types

Table 6-2 Supported Types

Binary Types

Integral Types

Floating Point Types

String Types

Length-Prefixed Strings

Delimited Strings

Null Terminated Strings

Fixed-Length Padded Strings

Implicit Strings

Complex Types

Date Types

Numerical Types

Floating Point Numbers

Fixed Scale, Variable Precision Numbers

Fixed Scale, Fixed Precision Numbers

Packed Decimal

Array Types (Tables)

Fixed Length Tables

Prefixed Variable Length Tables

Explicitly Delimited Variable Length Sequences

Implicitly Delimited Variable Length Sequences

Structured Types

Message Description Language File Format General Syntax Conventions

Type parameters

Type modifiers

Keyword Modifiers

Type Declaration Modifiers

Expression

Alias

Comment Insertion

Case Sensitivity

Message Description Language File Example

6
Message Description Language Reference