

The Oregon Micro Systems Device Driver Interface DLL, NTDRV.DLL, provides a
simplified software interface to OMS's Windows NT PC38 and equivalent motor
controller device drivers.

 - "C" and C++  applications should place a copy of the NTDRV.DLL in the same
   directory  as the application and link with the import library NTDRV.LIB.
 - Microsoft Visual Basic applications should place a copy of the DLL in
   \windows\system.
 - "C" applications should include the ntdll.h header file to define
    constants and function prototypes.
 - C++ applications, that use the Microsoft Developer Studio's MFC, should
   include the ntmfc.h header file.
 - Visual Basic applications should include NTDRV.BAS in their project.   

Axis selection constant definitions include:
   {OMS_X_AXIS, OMS_Y_AXIS, OMS_Z_AXIS, OMS_T_AXIS, OMS_U_AXIS, OMS_V_AXIS,
    OMS_R_AXIS, OMS_S_AXIS} 
Controller status flag constant definitions include:
    COMMAND_ERROR     - An invalid text command string was sent to the controller.
    SLIP_ERROR        - A slip or stall was detected on an encoder axis.
    OVERTRAVEL_ERROR  - An Axis has execceded an overtravel limit.
    

DLL FUNCTIONS PROVIDED INCLUDE:

FUNCTION: HANDLE GetOmsHandle( LPSTR DeviceName)

  PURPOSE:
      To return a device handle to the specified OMS device driver.
  
    PARAMETERS:
      DeviceName  -  Pointer to a character array containing an OMS
                     device name. i.e.  "OMS1"
    RETURN VALUE:
      Device Handle to an OMS device driver

   "C" Example:
       HANDLE OmsHandle;
       ...
       ...      
       OmsHandle = GetOmsHandle("OMS1"); 

       if ( OmsHandle == (HANDLE)NULL )
       {
         //Device driver for specified device has not been loaded.

   Visual Basic Example:
       'Note this global definition of OmsHandle is contained in NTDRV.BAS.
       Public OmsHandle As Long
       ...
       ...      
       'Get a handle to the OMS device driver
       OmsHandle = GetOmsHandle("OMS1")

       if ( OmsHandle = 0 ) Then
         'Driver for specified device has not been installed.

       
FUNCTION: void CloseOmsHandle( HANDEL OmsHandle)

  PURPOSE:
      To close the OMS device handle.
  
    PARAMETERS:
      OmsHandle  -  Device handle.
  
    RETURN VALUE:
      void

   "C" Example:
       CloseOmsHandle(OmsHandle); 

   Visual Basic Example:
       Call CloseOmsHandle(OmsHandle) 


FUNCTION: long SendString(HANDLE OmsHandle,
                          LPSTR pCommand)

  PURPOSE:
    To send a command string to the controller.
  
  PARAMETERS:
    OmsHandle -  Device Handle to an OMS device driver
    pCommand  -  Pointer to the command string
  
  RETURN VALUE:
    Returns the number of command characters accepted by the controller.
    A return value less than the number of characters in the command string
    indicates an error condition.
    
  "C" Example:
      long CharsSent;
      ...
      ...
      // Send a command string
      CharsSent = SendString(OmsHandle, "axmr1000;goid"); 
      if(CharsSent != 13)
         //Handle the send error
                
  Visual basic Example:
      Dim CharsSent As Long
      ...
      ...
      'Send a command string
      CharsSent = SendString(OmsHandle, "axmr1000;goid") 
      if(CharsSent <> 13) Then
        'Handle send error


FUNCTION:   void SendAndGetString(HANDLE OmsHandle,
                                  LPSTR pCommand,
                                  LPSTR pResponse)

  PURPOSE
    To send a command string to the controller, wait for the controller
    to send a response and then return the response string to the application.
    A null response string is returned if the controller does not respond to
    the query command.
    
  PARAMETERS:
    OmsHandle -  Device Handle to an OMS device driver
    pCommand  -  Pointer to the command string
    pResponse -  Pointer to the buffer that will receive the
                 controller's response.
  RETURN VALUE:
    Void

  "C" Example:
     char Response[128];
     ...
     ...
     //Get the controller's who are you description string
     SendAndGetString(OmsHandle, "wy", Response);
                            
     if(Response[0] == (char)NULL)
        //Handle the lack of a response

  Visual Basic Example:
     'Allocate a fixed length string to receive the response
     Dim Response As String*128
     ...
     ...
     'Get the controller's who are you description string
      Call SendAndGetString(OmsHandle, "wy", Response)


FUNCTION: void GetDoneFlags(HANDLE OmsHandle,
                            LPBYTE pDoneFlags)
  PURPOSE:
    To get the driver's copy of the axis done flags.  When ever the controller
    signals a done the state of any axis done flags, that are on, are captured
    by the driver.  Note the flags will remain in the on state until the 
    application clears them.  See the ClrDoneFlags function described below.

  PARAMETERS:
    OmsHandle   -  Device Handle to an OMS device driver
    pDoneFlags  -  Pointer to the byte that will receive the done flags

  RETURN VALUE:
    Void
    
  "C" Example:
      BYTE  DoneFlags;
      BYTE  AxisSelection;
      ...
      ...
      //If the X and Y axis done flags have been set
      AxisSelection = OMS_X_AXIS | OMS_Y_AXIS;
      GetDoneFlags(OmsHandle, &DoneFlags);
      if((DoneFlags & AxisSelection) == AxisSelection)
      ...
    
  Visual Basic Example:
      Dim DoneFlags As Byte
      Dim AxisSelection As Byte
      ...
      ...
      'If the X and Y axis done flags have been set
      AxisSelection = OMS_X_AXIS + OMS_Y_AXIS
      Call GetDoneFlags(OmsHandle, DoneFlags)
      If((DoneFlags And AxisSelection) = AxisSelection) Then
      ...


  FUNCTION: void ClrDoneFlags(HANDLE OmsHandle,
                              BYTE FlagMask)

  PURPOSE:
    To clear selected controller axis done flags.

  PARAMETERS:
    OmsHandle -  Device Handle to an OMS device driver
    FlagMask  -  Flag Selection Mask

  RETURN VALUE:
    Void

  "C" Example:
     BYTE FlagMask;
     ...
     ...
     //Clear the X & Y  axis done flags
     FlagMask = OMS_X_AXIS | OMS_Y_AXIS;
     ClrDoneFlags(OmsHandle, FlagMask);

  Visual Basic Example:
     Dim FlagMask As Byte
     ...
     ...
     'Clear the X & Y  axis done flags
     FlagMask = OMS_X_AXIS + OMS_Y_AXIS
     Call ClrDoneFlags(OmsHandle, FlagMask)


FUNCTION: void GetStatusFlags(HANDLE OmsHandle,
                              LPBYTE pStatusFlags)

  PURPOSE:
    To get the driver's copy of the controller's status flags.
    The following status flags are detected and latched by the driver:
    {COMMAND_ERROR, SLIP_ERROR, DONE}
    Note if the driver detects any of the above flags, in the on state, they
    will remain on until the application clears them.  See the ClrStatusFlags
    function described below. 

  PARAMETERS:
    OmsHandle     -  Device Handle to an OMS device driver
    pStatusFlags  -  Pointer to the byte that will receive the status flags

  RETURN VALUE:
    Void

  "C" Example:
      BYTE ControllerFlags;
      ...
      ...
      GetStatusFlags(OmsHandle, &ControllerFlags);

  Visual Basic Example:
      Dim ControllerFlags As Byte
      ...
      ...
      Call GetStatusFlags(OmsHandle, ControllerFlags)


FUNCTION: void ClrStatusFlags(HANDLE OmsHandle,
                              BYTE FlagMask)

  PURPOSE:
    To clear selected controller error status flags.

  PARAMETERS:
    OmsHandle -  Device Handle to an OMS device driver
    FlagMask  -  Flag Selection Mask

  RETURN VALUE:
    Void
    
  "C" Example:
     BYTE FlagMask;
     ...
     ...
     //Clear the encoder slip error flag
     FlagMask = SLIP_ERROR;
     ClrStatusFlags(OmsHandle, FlagMask);
    
  Visual Basic Example:
     Dim FlagMask As Byte
     ...
     ...
     'Clear the encoder slip error flag
     FlagMask = SLIP_ERROR
     Call ClrStatusFlags(OmsHandle, FlagMask)


FUNCTION: BOOL ResetController(HANDLE hDevice)

  PURPOSE:
    To reset the OMS controller board.  All controller parameters will
    reset to their power up states.

  PARAMETERS:
    hDevice           -  Device Handle to an OMS device driver

  RETURN VALUE:
    If controller was reset return is TRUE.
    
  "C" Example:
     HANDLE OmsHandle;
     BOOL ResetOk;
     ...
     ...
     ResetOk = ResetController(OmsHandle);
     //If the reset was not successful
     if(!ResetOk)
     //Handle reset error
    
  Visual Basic Example:
     Dim OmsHandle As Long
     Dim ResetOk As Boolean
     ...
     ...
     ResetOk = Call ResetController(OmsHandle)
     'If the reset was not successful
     If(ResetOk <> TRUE)Then
       'Handle reset error

 
