home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / icssrexx.zip / ICSSREXX.DOC < prev    next >
Text File  |  1994-05-05  |  10KB  |  241 lines
  1. ICSS REXX Interface 
  2. May 5, 1994
  3.  
  4. ******************************************************************************
  5. * The use of the ICSS REXX Interface DLL is licensed only to licensees       *
  6. * of the IBM Continuous Speech Series Developer's Tool Kit and is subject    *
  7. * to all the terms and conditions of the Program License Agreement that is   *
  8. * included with this Tool Kit.                                               *
  9. ******************************************************************************
  10.  
  11. ****************************************************************************** 
  12. *                                                                            * 
  13. * COPYRIGHT:                                                                 * 
  14. * ----------                                                                 * 
  15. * Copyright (C) International Business Machines Corp., 1994.                 * 
  16. *                                                                            * 
  17. * DISCLAIMER OF WARRANTIES:                                                  * 
  18. * -------------------------                                                  * 
  19. * The ICSS REXX Interface DLL is sample code created by IBM                  * 
  20. * Corporation.  This sample code is not part of any standard IBM product     * 
  21. * and is provided to you solely for the purpose of assisting you in the      * 
  22. * development of your applications.  The code is provided "AS IS",           * 
  23. * without warranty of any kind.  IBM shall not be liable for any damages     * 
  24. * arising out of your use of the sample code, even if they have been         * 
  25. * advised of the possibility of such damages.                                * 
  26. *                                                                            * 
  27. ****************************************************************************** 
  28.  
  29. -----------------
  30. Package Contents:
  31. -----------------
  32.  
  33.    ICSSREXX.DLL - The interface DLL enabling the ICSS API from REXX.
  34.    ICSSREXX.DOC - License information and usage documentation (this file).
  35.    REXXRECO.CMD - Sample REXX program using the ICSS API.  Similar to 
  36.                   the reco.c program included with the ICSS toolkit.
  37.    ICSSTEST.VRP - WATCOM* VX-REXX* project file for a sample program using the 
  38.                   ICSS API.
  39.    ICSSTEST.VRX - WATCOM VX-REXX project file for a sample program using the 
  40.                   ICSS API.
  41.    ICSSTEST.VRY - WATCOM VX-REXX project file for a sample program using the 
  42.                   ICSS API.
  43. ------------
  44. Description:
  45. ------------
  46.  
  47. ICSSREXX is a set of REXX external functions which call the ICSS APIs.  All
  48. APIs and parameters are enabled.  A non-zero return code means that you
  49. called the function with the wrong number of parameters.  Otherwise, each
  50. function returns a string consisting of the ICSS return value followed by the
  51. other ICSS output fields, if any.
  52.  
  53. To set up ICSSREXX on your own machine, just copy ICSSREXX.DLL into any
  54. directory in your LIBPATH.
  55.  
  56. For details on parameter values and return codes, refer to your ICSS 
  57. Developers Toolkit documentation.
  58.  
  59. * WATCOM and VX-REXX are trademarks of WATCOM International Corporation.
  60.  
  61. ---------------------------
  62. How To Call ICSS From REXX:
  63. ---------------------------
  64.  
  65. 1) Make sure ICSSREXX.DLL is in your LIBPATH.
  66.  
  67. 2) Include the following two lines in your REXX program before the first call to ICSS:
  68.  
  69.    call RxFuncAdd 'LoadFunctions', 'ICSSREXX', 'LoadFunctions' 
  70.    call LoadFunctions 
  71.  
  72. 3) Now you can call ICSS.  Here are the API calls and the data which is 
  73.    returned, if applicable.  The convention is to use icss_rc if the 
  74.    returned data is the ICSS return code, and icss_data if the returned
  75.    data is a string which must be parsed to get the ICSS return code and
  76.    other values associated with the API function.  A sample parse command
  77.    is also shown when the return string must be parsed.
  78.  
  79.    icss_rc = ICRXStart("")  /* Null string is required */
  80.  
  81.    icss_rc = ICRXStartConversation(ADCName, ADCNumber, RPSystemName,
  82.                  RPLinkType)
  83.  
  84.    icss_data = ICRXLoadContext(ContextName, InsertionPenalty, LanguageWeight,
  85.                 GrammarWeight)
  86.  
  87.                <<< parse var icss_data icss_rc ContextHandle >>>
  88.  
  89.    icss_data = ICRXGetValue(ParameterID)
  90.  
  91.                <<< parse var icss_data icss_rc ParameterValue >>>
  92.  
  93.    icss_rc = ICRXSetValue(ParameterID, ParameterValue)
  94.  
  95.    icss_rc = ICRXListen(ContextHandle, SpeechInputSource,
  96.                  SpeechInputFilename)
  97.  
  98.    icss_rc = ICRXInterruptListenState()  
  99.  
  100.    icss_data = ICRXGetSpokenWords()
  101.  
  102.                <<<parse var icss_data icss_rc SpokeTooSoon UtteranceLength ,
  103.                    AcquisitionTime RecognitionTime TextReturned; >>>
  104.  
  105.    icss_rc = ICRXPlayback(SampleRate, AudioOutputFileName)
  106.  
  107.    icss_rc = ICRXRemoveContext(ContextHandle)
  108.  
  109.    icss_rc = ICRXEndConversation()
  110.  
  111.    icss_rc = ICRXEnd()                                                             
  112.  
  113. 4) Unload the functions when done:
  114.  
  115.       call DropFunctions 
  116.  
  117.  
  118. ----------
  119. Constants:
  120. ----------
  121.  
  122. For convenience in using the REXX external functions, here are some useful
  123. constants from icssapi.h.  They may be copied directly into your REXX program
  124. if desired.
  125.  
  126. /*  return values from icssapi.h -- remember to add 1 to the icss returned */
  127. /*                                  value before translating with this     */
  128. /*                                  table.                                 */ 
  129.  
  130. retvals = 'ICSS_SUCCESS ',                   /* 0 */ 
  131.           'ICSS_ERR_ICSS_NOT_ACTIVE ',       /* 1 */
  132.           'ICSS_ERR_ICSS_ALREADY_INIT ',     /* etc... */
  133.           'ICSS_ERR_INITIALIZED ',  
  134.           'ICSS_ERR_CONV_ACTIVE ',
  135.           'ICSS_ERR_CONV_ALREADY_STARTED ',
  136.           'ICSS_ERR_LISTENING ',
  137.           'ICSS_ERR_INIT_MSG ',
  138.           'ICSS_ERR_INIT_GLOBAL ',
  139.           'ICSS_ERR_INIT_SEMAPHORE ',
  140.  
  141.           'ICSS_ERR_INIT_GLOBAL_DATA ',
  142.           'ICSS_ERR_INIT_ISTG_FAILED ',
  143.           'ICSS_ERR_INIT_POOL_SERVICE ',
  144.           'ICSS_ERR_TERM_ISTG_FAILED ',
  145.           'ICSS_ERR_LOAD_ADC_CODE ',
  146.           'ICSS_ERR_INVALID_ADCNUMBER ',
  147.           'ICSS_ERR_INVALID_RPLINKTYPE ',
  148.           'ICSS_ERR_CONTEXT_NOT_LOADED ',
  149.           'ICSS_ERR_CODEBOOKS_NOT_READ ',
  150.           'ICSS_ERR_MAX_CTX_REACHED ',
  151.  
  152.           'ICSS_ERR_INVALID_PARAMETER_ID ',
  153.           'ICSS_ERR_INVALID_PARM_VALUE ',
  154.           'ICSS_ERR_CONTEXT_NOT_AVAILABLE ',
  155.           'ICSS_ERR_INVALID_INSERTION_PENALTY ',
  156.           'ICSS_ERR_INVALID_LANGUAGE_WEIGHT ',
  157.           'ICSS_ERR_INVALID_GRAMMAR_WEIGHT ',
  158.           'ICSS_ERR_INVALID_SPEECH_INPUT_SOURCE ',
  159.           'ICSS_ERR_INVALID_SPEECH_INPUT_FILENAME ',
  160.           'ICSS_ERR_SPEECH_INPUT_SOURCE ',
  161.           'ICSS_ERR_INVALID_SAMPLE_RATE ',
  162.  
  163.           'ICSS_ERR_PLAYBACK_FAILED ',
  164.           'ICSS_ERR_EMPTY_RESPONSE ',
  165.           'ICSS_ERR_TRUNCATED_RESPONSE ',
  166.           'ICSS_ERR_EXCEEDED_MAX_SIL ',
  167.           'ICSS_ERR_EXCEEDED_MAX_TALK ',
  168.           'ICSS_ERR_LISTEN_STATE_INTERRUPTED ',
  169.           'ICSS_ERR_UNLOAD_ADC_CODE',
  170.           'ICSS_ERR_ISTG_START_CONVERSATION,             
  171.           'ICSS_ERR_ISTG_END_CONVERSATION,               
  172.           'ICSS_ERR_ISTG_FAILED,                         
  173.           
  174.           'ICSS_ERR_FBS_SEMAPHORE',                       
  175.           'ICSS_ERR_FBS_SHARED_MEMORY',                   
  176.           'ICSS_ERR_FBS_MEMORY',                          
  177.           'ICSS_ERR_FBS_UNKNOWN_CONTEXT',                 
  178.           'ICSS_ERR_FBS_NOT_SETUP',                       
  179.           'ICSS_ERR_FBS_NULL_REQUEST',                    
  180.           'ICSS_ERR_FBS_MAX_CONTEXTS',                    
  181.           'ICSS_ERR_FBS_OPEN_CONTEXT',                    
  182.           'ICSS_ERR_FBS_READ_CONTEXT',                    
  183.           'ICSS_ERR_FBS_OPEN_CPDFILE',                    
  184.           
  185.           'ICSS_ERR_FBS_INCOMPATIBLE_CPDFILE',            
  186.           'ICSS_ERR_FBS_INVALID_CONTEXT',                 
  187.           'ICSS_ERR_FBS_TOO_MANY_CPDFILES',               
  188.           'ICSS_ERR_FBS_READ_CPDFILE',                    
  189.           'ICSS_ERR_FBS_BUFFER_OVERFLOW',                 
  190.           'ICSS_ERR_FBS_RPC_FAILURE',                     
  191.           'ICSS_ERR_FBS_RPC_INVALID_HOST',                
  192.           'ICSS_ERR_FBS_RPC_SERVER_UNAVAIL',              
  193.           'ICSS_ERR_FBS',                                 
  194.           'ICSS_ERR_INVALID_ICSSDIR',                     
  195.           
  196.           'ICSS_ERR_INVALID_RPSYSTEMNAME',                
  197.           'ICSS_ERR_SHOULD_NOT_OCCUR';                     
  198.                    
  199.  /* Parmameter IDs for GetValue and SetValue              */
  200.  /* (parameter names have been shortened for convenience) */
  201.  
  202.  /* IDs for integer parms */
  203.  VERBOSE_LEVEL = 10;
  204.  UTT_START = 20;
  205.  UTT_END = 21;
  206.  ATTN_START = 30;
  207.  ATTN_END = 31;
  208.  
  209.  /* IDs for floating point parms */
  210.  BEAM_WIDTH = 110;
  211.  UTT_MIN_DURATION = 120;
  212.  UTT_MAX_DURATION = 121;
  213.  UTT_MAX_SIL = 122;
  214.  UTT_END_SIL = 123;
  215.  ATTN_MIN_DURATION = 130;
  216.  ATTN_MAX_DURATION = 131;
  217.  ATTN_INTERUTT_DURATION = 132;
  218.  
  219.  /* IDs for string parms */
  220.  RECORD_SESSION_NAME = 210;
  221.  RECORD_SPEECH_NAME = 211;
  222.  RECORD_FUTURE = 212;
  223.  RECORD_VQ_NAME = 213;
  224.  
  225.  /* default values */
  226.  DEFAULT_INT = '-1';  
  227.  DEFAULT_FLOAT = '-2.0';
  228.  DEFAULT_STRING = '';
  229.  
  230.  /* defined parameter values */
  231.  
  232.  /* ICRXStartConversation */
  233.  DIRECT = 2;          /* RPLinkType    */
  234.  RPC = 3;             /* RPLinkType    */
  235.  
  236.  /* ICRXListen */
  237.  LIVE_MIKE = 5;    /* SpeechInputSource  */
  238.  LIVE_LINE = 6;    /* SpeechInputSource  */
  239.  RECORDED = 7;     /* SpeechInputSource  */
  240.  
  241.