*********************************************
  XAM SDK C LIBRARY README v1.0
*********************************************

=================
Table of Contents
=================

 1. Deliverables
      - XAM C API public headers
      - XAM C Library
      - VIM C API header
      - XAM Java API wrapper for C Library
      - XAM Toolkits
      - HTTP VIM
 2. Directory Structure
 3. Build Instructions
      - Required Dependencies
      - PATH requirements
      - Other requirements
      - Supported Platforms
      - Building on Windows with Visual Studio
      - Building with ant
 4. Configuring the XAM Library
      - XAM Library Configuration File
      - Supported Configuration Namespaces
      - Configuration File Syntax

===============
1. Deliverables
===============

  XAM C API public headers:

        Defines the XAM C API, which may be utilized by application
    developers in order to interact with multiple vendor implementation 
    (VIM) libraries.

  XAM C Library:

        Implements the XAM C API, which applications may link to 
    in order to interact with multiple vendor implementation (VIM) 
    libraries.

  VIM C API header:
   
        Defines the VIM C API, which may be utilized by vendors for
    developing Vendor Implementation Module libraries (i.e. VIMs).

  XAM Java API Wrapper for C Library:

        Implements the XAM Java API interfaces, which may be utilized by 
    application developers in order to interact with multiple vendor 
    implementation (VIM) libraries. The Java interfaces are implemented 
    in XAMLibrary.jar, which utilizes the XAM C Library via JNI.    

  XAM Toolkits:

        Simple XAM toolkit examples are included for both C and Java, 
    which include standard XAM-defined utility methods).

  HTTP VIM:

        A VIM which proxies all XAM operations to a HTTP server using 
    GET and POST. This can be useful in conjunction with the HTTP Protocol
    VIM as it allows the C versions of the API to use the Reference VIM
    which is written in Java.

======================
2. Directory structure
======================

/C_XAM_Library 

    /build_script     -  Contains ant build.xml and misc project files
        /<platform>   -  Platform specific build and project files

    /src              -  Source code tree
        /c            -  C API source code
          /api        -  Implementation of the XAM interfaces in xam.h
          /classlib   -  Class definitions for all XAM objects
          /doc        -  Contains doxygen documentation on the source code
                         (generated as part of the build)
          /http_vim   -  HTTP proxy VIM
          /include    -  Public header files
          /jni        -  Java Native Interface (supports java api)
          /logger     -  Logging framework and components
          /posix      -  POSIX compatibility interface
          /toolkit    -  XAM Toolkit library implementation
          /utils      -  Various XAM utilities
          /vim        -  Representation of a Vendor Implementation Library
                         (includes the vim.h interface for VIM development)
        /java         -  Java API source code

    /lib	      -  Place to put any needed librariess that are not 
                         installed in the native OS. The cURL libraries
                         should be manually placed here if there are not
                         otherwise installed.

    /objects          -  Generated as part of the build process
        /<platform>   -  Contains platform specific object files 

    /deliverables     -  Generated as part of the build process
        /<platform>   -  Deliverables for a specific platform
          /include    -  Public headers
          /lib        -  Binary deliverables
          /doc        -  Doxygen documentation for public header files 

/Java_Interfaces      -  Contains the java interfaces required to build 
                         the XAM Java API wrapper jar for interfacing
                         with the C XAM Library.

=====================
3. Build Instructions
=====================

 Required dependencies: 

    Ant     - http://ant.apache.org (tested with 1.6.5)               
    Doxygen - http://www.doxygen.org (required for doc generation)
    Java    - http://java.sun.com (or the platform JVM provider)

 Path requirements:

    The compiler for each platform must exist in the PATH.

    The JAVA_HOME environment variable should be set to point to the root
    java installation directory (e.g. "C:\j2sdk1.4.2_12").

    For doc generation, the "doxygen" executable must exist in the PATH.

    For Windows, the "devenv.exe" executable must also be in the PATH
    in order for the ant builds to work correctly.

 Other requirements:
 
    For Visual Studio Express Edition on Windows, the build must be 
    performed from the IDE directly (i.e. ant may not be used). 

 Supported platforms:

     Currently supported platforms are (32 and 64-bit where applicable): 

         AIX-5.1
         HP-UX-B.11.11
         HP-UX-B.11.23
         Linux-GCC3.3 
         Linux-GCC4
         SunOS-5.8
         Win32Dev8
         Win64Dev8    
      
     See the "build_script" directory for the current list of platforms.

 How to build the XAM SDK with Visual Studio on Windows:

  1. Load the "C_XAM_Library/build_script/Win32Dev8/XAM_SDK.sln" project file
  2. Select either the "Win32" or "x64" build configuration.
     (The 64-bit build will produce a Win64Dev8 deliverable.)
  3. Under the "Build" menu, select "Build solution"
  4. Binaries, public headers, and documentation are delivered to:
        C_XAM_Library/deliverables/Win32Dev8/lib
        C_XAM_Library/deliverables/Win32Dev8/include
        C_XAM_Library/deliverables/Win32Dev8/doc
 
 How to build the XAM SDK using ant:

  1. Enter the "C_XAM_Library/build_script" directory.
  2. Run "ant -v -f build.xml -Dplatform=<platform>", where <platform>
     if one of the directory names under the "build_script" directory.
  3. Deliverables will be generated at the following locations:
        C_XAM_Library/deliverables/<platform>/lib
        C_XAM_Library/deliverables/<platform>/include
        C_XAM_Library/deliverables/<platform>/doc
    
  Example:
     ant -v -f build.xml -Dplatform=Linux-GCC3.3

==============================      
4. Configuring the XAM Library
==============================

XAM Library Configuration File:

    A properties file may be used to configure any of the following 
    XAM Library options:

       - VIM specific XSystem configuration fields
       - Logging controls
       - VIM name aliasing
       - VIM "stack" definitions
       - VIM lookup order priority
       - Automatic VIM preloading
       - Automatic generation of XRI name/value pairs for a given VIM alias 

    By default, the XAM Library will check for a config file named 
    "xam.properties" in the working directory. Optionally, the 
    XAM_CONFIG_PATH env var may be used to specify an alternate path to the 
    configuration file. 

    In either case, a string property field named ".xam.config.path" will be 
    synthesized by the XAMLibrary object, with the value containing the
    specified path to the configuration file. 

    This field may also be set directly by applications. If this field is 
    modified (or deleted) by an application, the properties will be re-loaded 
    from any newly specified configuration file. This allows applications to 
    refresh the configuration contents on demand.
    
    Note that the configuration file is extensible. If a property is found in 
    the config file, a corresponding property field with the same name/value 
    is synthesized on the XAMLibrary object. Because all XSystem instances 
    inherit all XAMLibrary fields on construction, this allows for VIM 
    specific XSystem configuration options to be automatically supported by 
    the XAM Library configuration file.   

Supported Configuration Namespaces: 

    The C XAM Library recognizes the following string property namespaces:

      .xam.config.vim.alias.{aliasvalue}={vim path} 

             - A VIM alias. The "aliasvalue" string may be specified in an 
               XRI to reference the given "vim path", which may be either 
               the full path toa VIM library or a VIM name. Aliases may also 
               reference other aliases.

               Sample Alias Usage (using alias in place of vimname):
                    "snia-xam://aliasvalue!<connection string>" 
 

      .xam.config.vim.alias.stack.{aliasvalue}={aliasvalue1}:{aliasvalue2}:...

             - Identifies an alias for a chain of VIMs. The value of this 
               property is a chain of vim names or aliases (stacks or that 
               individual VIMs) are ":" delimited. 

               Sample Stack Alias Usage (using alias in place of vimname):
                    "snia-xam://aliasvalue!<connection string>"

      .xam.config.vim.alias.{aliasvalue}.param.{name}={value} 

             - Refers to a name/value pair that should be added to the XRI 
               name/value pair list by the XAM Library in the event that a 
               particular "aliasvalue" is utilized in the XRI during connect.
               May be used for any "aliasvalue" defined in the "vim.alias" or 
               "vim.alias.stack" namespaces.

               Sample Result (name/value pairs appended by the XAM Library):
                   "snia-xam://aliasvalue!<connection string>?name=value"

               Multiple name/value pairs my be specified resulting in:
                   [?name1=value1[&name2=value2[&...]]]"

      .xam.config.vim.lookuporder.{n}={aliasvalue} 
 
             - Refers to the order of the VIMs for locating one that can 
               leverage a particular XRI if multiple VIMs could be used (in 
               the absence of a specified VIM name). The value "n" must be a 
               positive integer value that is unique to the entire 
               lookuporder namespace and indicates the ordinal position of 
               the VIM to utilize for the lookup. The value of "n" must be
               both sequential (beginning with either 0 or 1) and >= 0.

      .xam.config.vim.preload.{n}={aliasvalue} 
    
             - Preloads a VIM library during XAMLibrary initialization 
               (instead of on first use), where "n" is a positive integer
               (starting at 0 or 1) that is unique to the entire namespace. 
               The preload order will define the lookup order in the 
               absence of both "vim.lookuporder" properties and a specified 
               VIM name in the XRI.

      .xam.log.{option}={value} 

            - Supports all defined logging field controls, including:
                xam_int..xam.log.level
                xam_int..xam.log.verbosity
                xam_string..xam.log.path                
                xam_int..xam.log.max.size
                xam_int..xam.log.max.rollovers
                xam_boolean..xam.log.append
                xam_string..xam.log.message.filter
                xam_string..xam.log.component.filter

Configuration File Syntax:

    The XAM configuration file has the following attributes (similar to
    the java "Properties" format):

      1. Each configured field name is specified as a name/value pair
         delimited by '='(e.g. my_field_name=my_field_value).
      2. Whitespace and commented lines (prefixed with the '#' character) 
         are ignored.
      3. All defined fields are of type "xam_string" unless otherwise 
         specified using a simple type prefix (e.g. <stype>.name=value),
         where "stype" may be either xam_string, xam_int, xam_double, 
         or xam_datetime (note that xam_xuid types are not currently 
         supported).

    Example Configuration File:

      # C VIM Aliases
      .xam.config.vim.alias.emc=C:\VIMS\centera_vim.dll
      .xam.config.vim.alias.http=C:\VIMS\http_vim.dll
      .xam.config.vim.alias.encrypter=C:\VIMS\encryption_vim.dll  

      # Java VIM Aliases
      .xam.config.vim.alias.hp=com.hp.xam.VIMImpl
      .xam.config.vim.alias.sun=com.sun.xam.VIMImpl

      # VIM Stacks
      .xam.config.vim.alias.stack.isolated_centera=http:emc
      .xam.config.vim.alias.stack.isolated_encrypted_hp=http:encrypter:hp
      .xam.config.vim.alias.stack.isolated_sun=http:sun

      # VIM Stack name/value pairs (passed to the http VIM in the XRI)
      .xam.config.vim.alias.isolated_centera.param.xsystem=10.241.44.10
      .xam.config.vim.alias.isolated_encrypted_hp.param.xsystem=10.241.44.20
      .xam.config.vim.alias.isolated_sun.param.xsystem=10.241.44.42

      # Preloaded VIMs
      .xam.config.vim.preload.1=emc
      .xam.config.vim.preload.2=isolated_encrypted_hp

      # Centera VIM XSystem specific properties
      xam_int.com.emc.centera.retrycount=100    

      # Logging
      xam_int..xam.log.level=5
      xam_int..xam.log.verbosity=5
      .xam.log.path=C:\xam.log 

==============================      
5. Configuring the HTTP VIM
==============================

The HTTP VIM can be configured using a configuration file, or by
the use of parameters passed as part of the XRI. 

HTTP VIM parameters:

    Parameters that control the HTTP VIM can be passed as part
    of the XRI.

    The HTTP VIM recognizes the following parameters:

      targetServer.ipAddress={IP address} 

             - The IP address the HTTP server should connect to.

      targetServer.port={port} 

             - The port that the HTTP server should connect to.

      targetServer.vimname={vimname} 

             - The vimname of the VIM to be loaded by the HTTP server.

    Example XRI (one string, with "\\" indicating line continuation):

      snia-xam://xam_vim_http_g!127.0.0.1?\\
       targetServer.vimname=Remote&\\
       targetServer.ipAddress=1.2.3.4&\\
       targetServer.port=9923";

HTTP VIM Configuration File:

    A properties file may be used to configure any of the following 
    HTTP VIM options:

       - IP Address of HTTP Server
       - Port of the HTTP Server
       - vimname of VIM to be loaded by the HTTP Server

    The HTTP VIM will check for a config file named "vim.properties" in
    the working directory.

Supported Configuration Namespaces: 

    The HTTP VIM recognizes the following string property namespaces:

      .org.snia.xam.vim.parameter.targetServer.ipAddress={IP address} 

             - The IP address the HTTP server should connect to.

      .org.snia.xam.vim.parameter.targetServer.port={port} 

             - The port that the HTTP server should connect to.

      .org.snia.xam.vim.parameter.targetServer.vimname={vimname} 

             - The vimname of the VIM to be loaded by the HTTP server.

Configuration File Syntax:

    The vim configuration file has the following attributes (similar to
    the java "Properties" format):

      1. Each configured field name is specified as a name/value pair
         delimited by '='(e.g. my_field_name=my_field_value).
      2. Whitespace and commented lines (prefixed with the '#' character) 
         are ignored.
      3. All defined fields are of type "xam_string" unless otherwise 
         specified using a simple type prefix (e.g. <stype>.name=value),
         where "stype" may be either xam_string, xam_int, xam_double, 
         or xam_datetime (note that xam_xuid types are not currently 
         supported).

    Example Configuration File:

      .org.snia.xam.vim.parameter.targetServer.ipAddress=1.2.3.4 
      .org.snia.xam.vim.parameter.targetServer.port=9923 
      .org.snia.xam.vim.parameter.targetServer.vimname=Remote 


