Software Version

Web Services Integration Toolkit
Version 3.0 Field Test

Hewlett-Packard Company

Palo Alto, Calif.

© 2008 Hewlett-Packard Development Company, L.P.

Intel, Intel Inside, and Itanium are trademarks of Intel Corporation in the U.S. and/or other countries.

Microsoft, Windows, Windows XP, Visual Basic, Visual C++, and Win32 are trademarks of Microsoft Corporation in the U.S. and/or other countries.

Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

All other product names mentioned herein may be trademarks of their respective companies.

Confidential computer software. Valid license from HP and/or its subsidiaries required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license.

Neither HP nor any of its subsidiaries shall be liable for technical or editorial errors or omissions contained herein. The information in this document is provided “as is” without warranty of any kind and is subject to change without notice. The warranties for HP products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

About Web Services Integration Toolkit for OpenVMS Documentation

This IDL Reference describes the layout of the WSIT Interface Definition Language (IDL) file in order to make it as easy as possible for a developer to manually read and modify it.

The Installation Guide and Release Notes includes system requirements and installation instructions for OpenVMS, as well as release notes for the current release of the Web Services Integration Toolkit for OpenVMS.

The Developer’s Guide contains information about how to use the tools in the Web Services Integration Toolkit for OpenVMS, and things to consider as you prepare your legacy application.

For the latest release information, refer to the Web Services Toolkit for OpenVMS web site at http://www.hp.com/products/openvms/webservices/.  

 
Contents

1    Overview. 4

2    <OpenVMSInterface> Block. 4

2.1   <Enumeration> Block. 5

    2.1.1 <Enumerator> Block. 6

2.2    <Typedef> Block. 6

2.3    <Primitive> Block. 7

2.4    <Structure> Block. 8

         2.4.1 <Field> Block. 8

               2.4.1.1 <Array> Tag. 9

2.5    <Routine> Block. 10

         2.5.1  <Parameter> Block. 10

               2.5.1.1 <Array> Tag. 11

2.6     Valid Property Values. 12

3    Example WSIT IDL File. 13

4    Mapping Language Definitions to IDL. 14

 
    4.1    Mapping Binary Types. 14

    4.2    Mapping Decimal Types. 15

    4.3    Mapping String Types. 16

    4.4    Mapping Arrays. 18

    4.5    Mapping Structures. 19

5    Mapping BLOBs and Other Unformatted Data (New Feature in V2.0) 20

 
1    O V E R V I E W

The Web Services Integration Toolkit (WSIT) provides tools to expose the API of an existing non-java application as a java based API. The first step in this process is to create an Interface Definition Language (IDL) file which describes the API to be wrapped.  This IDL is an XML formatted file which may be created by a WSIT provided tool or it may be created by hand.  In either case, it is often necessary to modify this file during the development of the WSIT application. This document will describe the XML tags and their relationship to each other.

A WSIT IDL file has an easy to understand nested layout that allows a developer to completely describe their application’s interface in a language-neutral way.  It does this by allowing the definition of all routines and structures that are to be exposed by the application.   Within these routine and structure definitions, all parameter and field datatypes are mapped (translated) into their OpenVMS equivalent datatypes (DSC$K_DTYPE_*).  

In general, the mapping of parameters within routines, and fields within structures, take one of the following two forms:

“User datatype specification” -> typedef translation[n] -> Primitive translation -> OpenVMS primitive (datatype)

-or-

“User datatype specification” -> typedef translation[n] -> Structure definition

Structure definitions contain an ordered set of fields which in turn go through the above translations until all definitions have been mapped into their equivalent OpenVMS datatypes.

Note: The [n] states that zero or more typedef translations may occur before the final translation to an OpenVMS datatype (primitive) or structure definition.   

The sections below describe how each component (routine, structure, and so on), including translation (mapping), is defined within the WSIT IDL file.

2 <OpenVMSInterface>  BLOCK

The <OpenVMSInterface> block s is the main block that encapsulates all of the blocks that collectively describe the application’s interface.   It has the following format:

<OpenVMSInterface

  xmlns="hp/openvms/integration"

  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="hp/openvms/integration openvms-integration.xsd"

ModuleName="DISK:[MYDIR.STOCK]stock.OBJ"
  Language="C89">

  .

<Enumerations>

</Enumerations>

  .

  <Typedefs>

</Typedefs>

  .

<Primitives>

  </Primitives>

  .

<Structures>

</Structures>

  .

  <Routines>

</Routines>

  .

</OpenVMSInterface>

Except for the first line in the XML file, which is <?xml version="1.0" encoding="UTF-8"?>, all lines within the WSIT IDL file reside within the <OpenVMSInterface> block.

The properties within the <OpenVMSInterface> tag (in bold above) are primarily generic header information that is required, and is identical, for all WSIT IDL files.   The two notable exceptions are the ModuleName and Language properties, described below:

The blocks nested within the <OpenVMSInterface> block contain the collection of definitions corresponding to that component or translation type.   For example:

·         The <Routines> block contains all of the individual <Routine> blocks that describe the exposed routines of an application.  

·         The <Structures> block contains the list of <Structure> definitions.

·         The <Primitives> block contains the list of <Primitive> or OpenVMS datatype translations.

·         The <Typedefs> block contains the list of <Typedef> definitions.

·         The <Enumerations> block contains the list of <Enumeration> definitions.   

All of the individual definition blocks and tags are described in greater detail below.

2.1 <Enumeration> Block

The collection of <Enumeration> blocks contains all of the constant definitions that are defined as enumerations within the application.  An <Enumeration> is made up of a name, an OpenVMS datatype, an optional size in bytes, and the list of Name/Value pairs.   The format of the block is as follows:

<Enumerations>

    <Enumeration Name = “myenums”

VMSDataType = “DSC$K_DTYPE_L”

ByteSize = “4”>

[…see Enumerator block for more information…]

</Enumeration>

</Enumerations>

The properties of the <Enumeration> tag are defined as follows:

2.1.1    <Enumerator> Block

Each <Enumerator> within an enumerator collection (an Enumeration) specifies a name/constant value pair.   These pairs make up the set of valid values for the Enumeration.  The format of an Enumerator is:

<Enumeration …>

<Enumerator Name = “PIC$SIZE1” ConstantValue = “1”/>

<Enumerator Name = “PIC$SIZE2” ConstantValue = “2”/>

</Enumeration>

The properties within the <Enumerator> tag are as follows:

2.2 <Typedef> Block

The collection of <Typedef> blocks contains all of the typedef translations used within the application.  Each <Typedef> tag describes a user defined mapping of a type name to an equivalent type. In C, this would look something like:

     typedef myint unsigned int;

Each <Typedef> tag has the following format:

     <Typedef Name = “myint”

              TargetName = “unsigned int”/>

Where each property is defined below:

2.3 <Primitive> Block

The collection of <Primitive> blocks contains the datatype translations to their OpenVMS equivalents for all datatypes used within an application.   Each <Primitive> mapping contains the datatype, the OpenVMS datatype (primitive) that it maps to, along with any other information needed to completely describe that primitive.   The <Primitive> tag has the following formats.

The following describes a Packed Decimal:

<Primitive Name = "DSC$K_DTYPE_P_5_2"

Size = "5"

Scale = "2"

VMSDataType = "DSC$K_DTYPE_P" />

The following describes a simple Longword:

<Primitive Name = "int"

Size = "4"

VMSDataType = "DSC$K_DTYPE_L" />

The following describe different string types (a dynamic string and a varying string):

<Primitive Name = “String_Dynamic"

Size = "0"

           FixedFlag = "0"

           NullTerminatedFlag = "1"

           VMSDataType = "DSC$K_DTYPE_T" />

<Primitive Name = “Varying_String_20"

Size = "20"

           FixedFlag = "0"

           NullTerminatedFlag = "1"

           VMSDataType = "DSC$K_DTYPE_VT" />

The properties of the <Primitive> tag are described below:

 ** All Primitive Names must be unique.  For primitives that are the same but differ in size and/or scale, one way force uniqueness is to embed the size and scale values into the Primitive Name itself. (See the Packed Decimal example above.)

*** The size is specified in bytes for all datatypes except Scaled Numerics, where the size specifies the number of digits.   Note that for Varying Strings, the size specifies the maximum length of the string.  (The actual length of the varying string is determined at runtime.  If the varying string size is specified as 0, then the actual length at runtime is used as the maximum size.)

2.4 <Structure> Block

Although a language may refer to them as Records, Workspaces, or Structures, all languages support the concept of a structure.  The collection of <Structure> blocks contains all of the user defined structure definitions that will be passed in or out of the application’s interface.   Each <Structure> block represents a single user defined structure definition.   All parameters and fields must eventually map to an OpenVMS primitive, or one of these structure definitions.  The format of the <Structure> block is:

<Structures>

<Structure Name = "MyStruct"

TotalPaddedSize = "128">

[…See Field Block below for more information…]

</Structure>

</Structures>

The properties of the <Structure> tag are:

2.4.1 <Field> Block

Each <Field>…</Field> block describes a single field within a structure.  The format of a <Field> block is as follows:

<Structure … >

     <Field Name = "Fld1"

            Type = "signed int"

Offset = "0"/>

     <Field Name = "Fld2"

Type = "FixedString16"

Offset = "4"/>

     <Field Name = "AryFld3"

Type = "signed int"

Offset = "20"

ArrayDimension = "1"

RowByColumn = "0">

<Array LowerBound = "0"

UpperBound = "9"/>

</Field>

</Structure>

The properties of the <Field> tag are: