Data Acquisition (DAQ) and Control from Microstar Laboratories

Changes to the DAPIO Interface in DAPIO32

Technical Note TN-196 Version 1.10

Note: This reference document assumes familiarity with the Microstar Laboratories Windows Toolkit and the DAPIO.DLL.

There have been significant changes with the release of the DAPIO32.DLL (32-bit DLL) from its predecessor the DAPIO.DLL (16-bit DLL). Immediately obvious to DAPIO users is the naming convention change. The 32-bit functions use an object oriented naming scheme: Dap<object><action> as in DapHandleOpen(). To convert the 16-bit function calls of an application to 32-bit function calls, the symbols must be changed. The association between the function names of the two releases can be found in the Cross Reference section at the end of this document.

Other changes in the new DAPIO32.DLL include the addition of new functions and variants, function removals, and syntax changes. For specific information about the services and their usage, please refer to the Accel32 or DAPIO32 for Windows documentation provided with DAPIO32.

Functional Changes

Changes to the following functions in the DAPIO32.DLL will affect most programs.

DapHandleOpen(. . .) -- This function now uses the new UNC (Universal Naming Convention) and requires a pipe direction specification. Handles are no longer bi-directional as with the previous 16-bit DLL, and for this reason, two separate handles must be opened to establish bi-directional communication with the DAP. This is illustrated in the example below which opens handles to the text communication pipe for read and write operations.

  HDAP hdapSysPut, hdapSysGet;
  hdapSysGet = DapHandleOpen("\\\\.\\Dap0\\$SysOut",DAPOPEN_READ);
  hdapSysPut = DapHandleOpen("\\\\.\\Dap0\\$SysIn",DAPOPEN_WRITE);

Handle names that indicate the direction of the data transfer are recommended to avoid any confusion over the direction of the communication for the handle. For example, hdapSysGet retrieves data from the DAP's communication pipe $SysOut while hdapSysPut transfers data to the DAP.

DapLineGet(. . .) -- This function is a replacement for the DAPIO.DLL function GetDapString(). DapLineGet() gets a string of characters from the DAP with user specified time-out, and returns the number of character read from the DAP excluding line-feed characters.

DapStringGet(. . .) -- This function is not the same as the DAPIO.DLL function GetDapString(). GetDapString() assumes that all carriage-return characters are followed by a line-feed character. The following two lines may be used as a direct replacement for GetDapString(). For new code use DapLineGet().

  DapStringGet(hdapSysGet, sizeof(ErrorMsg), ErrorMsg);
  DapCharGet(hdapSysGet, TempChar);

DapStringPut(. . .) -- This function is similar to the 16-bit function call PutDapString(), except that a carriage return character (\r) must be applied explicitly to the string. The carriage-return must be present for some versions of DAPL to correctly recognize the command. DapLinePut() may be a better direct replacement for PutDapString() than DapStringPut() because it naturally appends a carriage-return to the end of a string. The following two equivalent approaches send a stop command to the DAP.

  DapStringPut(hdapSysPut, "STOP\r");
  DapLinePut(hdapSysPut, "STOP");

DapCommandDownload(. . .) -- This function now uses a special structure as its parameter and returns TRUE or FALSE upon completion of its task. The TDapCommandDownload structure must be fully initialized before a call to DapCommandDownload() can be made, as displayed in the following example.

  TDapCommandDownload dcd;
  memset(&dcd, 0,             sizeof(dcd));
  dcd.iInfoSize               = sizeof(dcd);
  dcd.hdapSysPut              = hdapSysPut;
  dcd.hdapSysGet              = hdapSysGet;
  dcd.pszCCFileName           = pszFile;
  dcd.pszCCName               = NULL;
  dcd.iCCStackSize            = 1000;
  if (DapCommandDownload(&dcd))

Implementation Changes

Almost all functions in the new DAPIO32.DLL now return TRUE or FALSE upon completion. TRUE and FALSE are defined in WINDOWS.H or if WINDOWS.H is not used they are defined in DAPIO.H. For this reason, changes should be made to all code that currently checks the return value from a function call. Error messages are now handled through the Win32 API or by calling the function DapLastErrorTextGet(). The functions whose responses have changed in the DAPIO32.DLL are listed below with their new return values.

DAPIO32.DLL(32-bit)  Return Value    DAPIO.DLL(16-bit)  Return Value
Function                             Function
DapCharGet           TRUE or FALSE   GetDapChar         # Bytes or -1
DapCharPut           TRUE or FALSE   PutDapChar         # Bytes or -1
DapConfig            TRUE or FALSE   ConfigDap          error codes
DapConfigParamsClear TRUE or FALSE   ClearParam         (none)
DapConfigParamSet    TRUE or FALSE   SetParam           (none)
DapConfigRedirect    TRUE or FALSE   RedirectConfigDap  (none)
DapHandleClose       TRUE or FALSE   CloseHandle        0 or -1
DapHandleOpen        handle or 0     OpenHandle         handle or -1
DapInputAvail        # Bytes or -1   GetDapAvail        # Bytes or -1
DapInputFlush        # Bytes or -1   FlushDap           0 or -1
DapInt16Get          TRUE or FALSE   GetDapInt          # Bytes or -1
DapInt16Put          TRUE or FALSE   PutDapInt          # Bytes or -1
DapLinePut           TRUE or FALSE   PutDapString       # Bytes or -1
DapOutputSpace       # Bytes or -1   PutDapAvail        # Bytes or -1
DapStringPut         TRUE or FALSE   PutDapString       # Bytes or -1

New DLL Functions

The following functions are available only with the new DAPIO32 library. Additionally, the three functions: DapComPipeCreate, DapComPipeDelete, and DapHandleQuery are available only with the Accel32 (Windows NT) driver. Please refer to the 32-bit DLL documentation to obtain syntax and usage information for these functions.

  DapComPipeCreate(. . .)     Accel32 (WinNT) only
  DapComPipeDelete(. . .)     Accel32 (WinNT) only
  DapHandleQuery(. . .)       Accel32 (WinNT) only
  DapBufferGetEx(. . .)
  DapInputFlushEx(. . .)
  DapLastErrorTextGet(. . .)
  DapLinePut(. . .)
  DapStringFormat(. . .)
  DapInt32Get(. . .)
  DapInt32Put(. . .)

Replaced Function

The function GetAccelVersion() has been replaced by a new function DapHandleQuery() in the DAPIO32 library. DapHandleQuery() provides the same information that GetAccelVersion() did in the DAPIO.DLL. Please refer to the 32-bit DLL documentation for information on how to use DapHandleQuery().

  DAPIO.DLL(16-bit) Function    DAPIO32.DLL(32-bit) Function
  GetAccelVersion()             DapHandleQuery()

Obsolete Functions

The following functions have become obsolete and have no replacements in the DAPIO32.DLL. Most are low level ACCEL device routines that provide information beyond the need of the typical user or whose functionality has been provided by other routines.

  ReadIoCtl(. . .)
  WriteIoCtl(. . .)
  SetDapInput(. . .)
  SetDapOutput(. . .)
  IsVxdRunning(. . .)
  DownloadList(. . .)

Furthermore, downloading a list of custom commands is no longer supported in the DAPIO32.DLL. Instead, multiple calls to DapCommandDownload() can be used to load more than one custom command.

Import Libraries

The DAPIO32.DLL conforms to the Win32 API convention for selecting between ANSI and Unicode versions of functions. When using the import libraries included with DAPIO32, understanding this convention is not necessary. The DAPIO32.DLL does not support Unicode character mapping. However, developers needing to generate their own import library must understand the mapping scheme used in the DAPIO32.DLL.

Functions which support ANSI characters end with 'A', while functions which support Unicode end with 'W'. The base function name is then mapped to the correct version of the function based on a pre-processor symbol. For example, DapConfig() is mapped by the DAPIO32.H C header file to DapConfigA() using the ANSI convention. Following is a listing of the DAPIO32.DLL functions and structures and their actual ANSI mapping names.

  Function Name      Maps To  Actual Function Name
  DapCharGet           >>>    DapCharGetA
  DapCharPut           >>>    DapCharPutA
  DapCommandDownload   >>>    DapCommandDownloadA
  DapComPipeCreate     >>>    DapComPipeCreateA
  DapComPipeDelete     >>>    DapComPipeDeleteA
  DapConfig            >>>    DapConfigA
  DapConfigParamSet    >>>    DapConfigParamSetA
  DapConfigRedirect    >>>    DapConfigRedirectA
  DapHandleOpen        >>>    DapHandleOpenA
  DapHandleQuery       >>>    DapHandleQueryA
  DapLastErrorTextGet  >>>    DapLastErrorTextGetA
  DapLinePut           >>>    DapLinePutA
  DapStringFormat      >>>    DapStringFormatA
  DapStringGet         >>>    DapStringGetA
  DapStringPut         >>>    DapStringPutA

  Structure Name              Actual Structure Name
  TDapCommandDownload  >>>    TDapCommandDownloadA
  TDapHandleQuery      >>>    TDapHandleQueryA

Cross Reference

The following table relates the DAPIO (16-bit) library functions with the new DAPIO32 (32-bit) functions. The function calls are arranged alphabetically by their DAPIO.DLL name.

  DAPIO.DLL (16-bit) Function  DAPIO32.DLL (32-bit) Function

  ClearParams                  DapConfigParamsClear 1
  CloseHandle                  DapHandleClose 1
  ConfigDap                    DapConfig 1
  DownloadCmd                  DapCommandDownload 2
  DownloadList                 (none)
  FlushDap                     DapInputFlush 1
  GetAccelVersion              DapHandleQuery 1
  GetDapAvail                  DapInputAvail 1
  GetDapBuf                    DapBufferGet
  GetDapChar                   DapCharGet 1
  GetDapInt                    DapInt16Get 1
  GetDapString                 DapStringGet 2
  IsVxdRunning                 (none)
  OpenHandle                   DapHandleOpen 1 2
  PutDapAvail                  DapOutputSpace 1
  PutDapBuf                    DapBufferPut
  PutDapChar                   DapCharPut 1
  PutDapInt                    DapInt16Put 1
  PutDapString                 DapLinePut 1
                               DapStringPut 1 2
  ReadIoCtl                    (none)
  RedirectConfigDap            DapConfigRedirect 1
  SetDapInput                  (none)
  SetDapOutput                 (none)
  SetParam                     DapConfigParamSet 1
  WriteIoCtl                   (none)

1 The function's return values have changed with the DAPIO32.DLL library release.
2 There is a change in the usage of the function call.

Contents copyright © 1997, Microstar Laboratories, Inc. All rights reserved. No part of this publication may be photocopied, reproduced, or translated to another language without prior written consent of Microstar Laboratories, Inc. Microstar Laboratories assumes no responsibility for damages due to errors or omissions. Microstar Laboratories, Accel32, Data Acquisition Processor, DAP, and DAPL are trademarks of Microstar Laboratories, Inc. Other brand names and product names are trademarks of their respective holders.


View other Technical Notes.