0. General
----------


  o Running ME10  Application  Interface  (AI)  version  04.20 on Series
    300/400  requires at least HP-UX  version 8.0.  Your  additional  AI
    modules to ME10 AI version 04.20 for Series 300/400 must be compiled
    and - in case of complete  linking - linked under HP-UX version 8.0.
    To check  whether you have a proper  HP-UX 8.0 version log in as the
    root user, set the  current  directory  to the  directory  where the
    ME10AI  software is installed  (for  example  /me10ai),  and type in
    what_hpux.

  o ME10 AI version  04.20 for Series  300/400 is written  in ANSI C and
    compiled  with the HP-UX ANSI C delivered  with HP-UX  version  8.0.
    This  means  that  this  HP-UX  ANSI C  development  environment  is
    required for debugging purposes.

  o There are no  extensions  of ME10 AI version  04.20  compared to the
    ME10 AI versions 03.20, 04.12 and 04.15.

  o The  examples  for ME10 AI are no longer part of the  manuals.  They
    are only part of the AI tape.



1. Limitations in AI functionality
----------------------------------

  o me_new_arithm_function()

    me_new_arithm_function() is not usable from the AI any more.

  o Events and event handling

    As no event is offered in the ME10 AI the event related  functions

    * me_subscribe_event()
    * me_unsubscribe_event()

    are not usable together with the ME10 AI.


2. Hints for use of AI functionality
------------------------------------

  o ME_TRY .. ME_RECOVER .. ME_END_TRY

    The macros ME_TRY ..  ME_RECOVER  ..  ME_END_TRY  are based on calls
    of  setjump.  Be careful if you use setjump or the macros  mentioned
    above   together  with  global   optimization   switched  on  during
    compilation.  Due to the global optimization, non volatile variables
    might have been  overwritten  if the RECOVER  block is entered (by a
    longjump).


The sections 4 to 9 in this README file replace the chapters  "Static or
Dynamic Link?"  and  "Development  steps for application  set-up" in the
Concepts & Tutorials Manual for ME10/30 AI.

3. Complete (Static) vs. Dynamic Link
-------------------------------------

    There is a change in using the term  "Static  Link".  From HP-UX 8.0
    on  the  term  "Static   Link"  is  already  used  for  building  an
    application  without using shared libraries.  Shared libraries are a
    new feature,  provided from HP-UX 8.0 on.  Therefore we will use the
    term "Complete Link" instead of "Static Link" from now on.

    There  are  different   requirements   for  integrating  a  specific
    application program into ME10/30 AI.  There are questions like:

    "How do I, as an application  integrator, offer the application code
    to the end user?"

    -OR-

    "What's the  mechanism  to activate  the  application  module at the
    customer's site?"

    -OR-

    "How  independent  is my  application  program  code from ME10/30 AI
    code?"

    One goal is to offer a mechanism that provides the highest  possible
    degree of flexibility  and  independence  from the ME10/30 AI system
    revisioning process.  This goal is reached as follows:

    Here we have to distinguish two different phases:

    * The Development Phase of an AI Application

      During  the  development  phase,  there is the  requirement  to do
      debugging  (for  example,  with cdb) on the code to be  developed.
      This is possible when the ME10/30 AI code is complete linked.  The
      function  main() within  ME10/30 AI is always  compiled with debug
      mode which assures that the complete  linked AI  application  code
      can be debugged if specified in the appropriate makefile.

    * The  Execution/Activation  Phase  of  an  AI  Application  at  the
      Customer's Site

      In this phase the developed code is assumed to be stable (debugged
      and tested) and it is possible to integrate the  application  code
      into ME10 or into ME30 at runtime of ME10/30 AI.  This  process is
      called "Dynamic linking at run time".


4. Complete Link of an AI Application
-----------------------------------------

    The  complete  link  process  typically  will  be  used  during  the
    development phase of the application.

    The process of linking the different  relocatable  object code files
    within a makefile  results in a  complete  linked  executable  code.
    This is called "Complete Link".

    In the example  below (see item 9), the  ai_demo.o  module is linked
    together with, for example,  me10ai.o, and the resulting  executable
    is mexx.  mexx is ready to run.

    Within  the frame  module  there is one  static  integration  "hook"
    provided  which  represents  the  interface  between  the CAD system
    ME10/30 AI and the application module(s) to be integrated.

    All the commands,  functions, and keywords will be made known to the
    ME10/30 AI system by means of this "hook".


    Complete Link Command Syntax
    ============================

    The command syntax at the ME10/30 user interface/macro level is

      LOAD_MODULE "AI"

    The  module  name "AI" is a  reserved  name  similar  to  "MODEL2D",
    "MODEL3D".

    The corresponding C function  activated by this ME10/30  LOAD_MODULE
    "AI" function is "ai_initialize".

    This  function  "ai_initialize"  has to be provided  once within the
    application program.

    The function syntax is as follows:

	void ai_initialize()
	{
	 static int initialized;

	 /* inform ME10/30 AI about new functions just once */
	 if (initialized++) return;  

	 /* specify here all newly to be defined Keywords,  Commands and */
	 /* Functions the following is an example, see ai_demo.c example */
	 /* file.                                                        */

	 me_new_function("AI_DEMO", ai_demo_fnc);
	 keyword_done = me_new_qualifier("DONE");
	}


5. Dynamic Link of an AI Application
------------------------------------

    The command syntax of the hook at ME10/30 user interface/macro level
    is

      LOAD_MODULE "Application_module_name.sl"

    The  Application_module_name.sl  is the file,  which is  relocatable
    linked   and   then   linked   to  a   shared   library   file.  The
    Application_module_name     can     be     determined     by     the
    AI-application-integrator.  The   ME10/30  AI  system   architecture
    supports the dynamic loading with the following specifications:

    * One Application_module_name.sl  contains the overall functionality
      for the complete application.

    * The  debugger cdb works only very  restrictedly  with  dynamically
      loaded modules.

    * The  AI-application  integrator  has to assure  that all  required
      modules out of libraries to run the application code are contained
      in the relocatable application code object module (see below).

    The corresponding C function activated by this LOAD_MODULE statement
    is "init_load_init".

    This  function  "init_load_init"  has to be provided once within the
    application module to be linked.

    The function syntax is as follows:

	void init_load_init()
	{
	  /* provide here ALL functions,  commands,  keywords which */
	  /* will be made known to the system ; an example is:      */

	  me_new_function("TEST", test_fnc);
	}


    Special Considerations for Dynamic Linking
    ------------------------------------------

    Dynamic  linking  requires  special  understanding  of  some  system
    boundary  conditions.  One is to satisfy all  unresolved  references
    out of libraries.

    Typically  ME10 or ME30  have  linked in  information  where  shared
    libraries are needed for all required drivers.  Very special library
    functionality,  which an application  might require in order to load
    and run  without  problems,  should be linked in the shared  dynamic
    loadable  application.sl  file.  The application  module must not be
    linked  together  directly  with  libraries.  All  shared  libraries
    already  loaded from me10ai.o or me30ai.o are  accessible for the AI
    application  without additional  linking.  However, if you get error
    messages after LOAD_MODULE "xxxx.sl" concerning  unresolved external
    references  in your  AI  application  module,  then go  through  the
    following steps.

    * Find out which external references are still missing.

    * Find the library  that fits to the  unresolved  reference  (use ar
      command).

    * Extract  with ar  (archive)  the  required  object  file  from the
      library.

    * Link it relocatable (ld -r) to the application.o  file, then build
      a shared library (ld -b -o application.sl application.sl).

    * Try to execute LOAD_MODULE "xxxx.sl" again.


6. Development Steps for Application Set-Up
-------------------------------------------

    To  write,  compile,  and  link  a new  application  module,  the AI
    integrator  has  to go  through  the  following  steps.  (Here  it's
    assumed that during the AI application development the complete link
    facility  is used.  Later  when the code is  thoroughly  tested  and
    quality  assured  the  dynamic  link  facility  will be applied  and
    tested).

    * Specify and design your application.

    * Write an initialization routine (ai_initialize) which contains the
      keywords and action routine functions (commands, functions).

    * Write the action  routines  which, for example, prompt the user to
      do further actions and/or call further functions.

    * The  error  handling  should  be set  up  carefully  (see  ME_TRY,
      ME_RECOVER)  in order to prevent  abnormal  system  exceptions  or
      terminations.

    * Configure  the  makefile  appropriately  and  make  sure  that ALL
      required modules and libraries required are linked.

    * Run make which generates the complete linked  executable code, for
      example, mexx.

    * Define  and  implement  the  user  interface  extensions  and, for
      example,  integrate  LOAD_MODULE  "AI" into the ME10/30 AI startup
      macro.

    * Do tests and debug the application.

    After the system has been debugged then  re-configure the system for
    dynamic  link  (replace   "ai_initialize"  by  "init_load_init"  and
    replace  LOAD_MODULE  "AI"  by  LOAD_MODULE   "Application_name.sl",
    filling in the appropriate module name)

    Set up a new makefile and generate a relocatable  Application_name.o
    and then a shared library Application_name.sl file.

    Run ME10/30 AI and load  dynamically  by  execution  of  LOAD_MODULE
    "Application_name.sl"  Test the system under specified configuration
    conditions (such as check RAM and swap space requirements)


7. Programming Guidelines and Tips
----------------------------------

    If your  application  uses the  functions  of the ME10 AI then  your
    application  program  has to  include  the AI  header  files  in the
    following order:

      #include "frame.h"
      #include "model2d.h"

    Be sure that the header file include  statements  appear in the same
    order as shown above.

    Here are some hints in case  something  goes  wrong  during  program
    development.

    A  checklist  of what to do if ME10/30 AI says your new  function is
    not defined:

    * Was the module loaded?

    * Complete  link:  Is the  module  and file in  makefile?  And up to
      date?

    * Checking the initialization in own source for mis-types or illegal
      names.

    * Checking the actual code for the function.

    The most  effective (but  primitive) way to debug the code is with a
    liberal  application  of  printf  statements,  variable  values  and
    fflush's.

    Upon  segmentation  violation  - check the  variables  in that area.
    Make sure all have their memory space declared  explicitly.  This is
    a common  mistake to forget to save space and just provide a pointer
    for some routine.

    Use  normal  disciplined  software  development  techniques  such as
    adding comments at suitable points in the program.


8. Example of a makefile for complete linking :
-----------------------------------------------

    CC = cc -c -ldld
    CFLAGS = -g -I. -I/usr/include/X11R4 -I/usr/include/X11 \
	     -Aa -D_HPUX_SOURCE -Dhpux -Dhp9000s300 
    ME_MODULES = me10ai.o
    AI_MODULES = ai_demo.o
    LIBS =  -L/usr/lib/X11R4 \
	    -ldld \
	    -lddbyte \
	    -lddhil \
	    -lddCADplt \
	    -lddhpgl \
	    -lddsox11 \
	    -lXwindow \
	    -lsb \
	    -lXhp11 \
	    -lX11 \
	    -lF77 \
	    -lI77 \
	    -lm \
	    -ln 

    mexx_deb: $(AI_MODULES)
	    rm -f mexx
            cc -g -q -Wl,-E,-X 16000 \
            $(ME_MODULES) \
            $(AI_MODULES) \
            $(LIBS) \
            -o mexx

    mexx: $(AI_MODULES)
	    rm -f mexx
            cc -q -Wl,-E,-X 16000 \
            $(ME_MODULES) \
            $(AI_MODULES) \
            $(LIBS) \
            -o mexx

    ai_demo.o: ai_demo.c
	    $(CC) $(CFLAGS) -o ai_demo.o ai_demo.c
