DioFileImport

Applies To

General utility function.

Purpose

Convert WGL, STIL, VCD or eVCD file type to a DIO file.

Syntax

DioFileImport (pszInputFile, pszOutputDioFile, nBoardType, bRealtimeCompare, pszImportOptions, pnImportOptionsMaxLen, bWait, phHandle, pszError, nErrMaxLen, pnStatus)

Parameters

Name
Type
Comments
pszInputFile
PCSTR
Specified input WGL, STIL, VCD or eVCD file name.
pszOutputDioFile
PCSTR
Specified output DIO file name. Pass NULL or empty string to this parameter to request the default import options string as explained in the pszImportOptions parameter.
nBoardType
SHORT
Sets the target supported DIO board type:
0x55     DIO_BOARD_TYPE_GX5055 – Gx5055 DIO board type.
0x70     DIO_BOARD_TYPE_GX5290 - Gx5290 DIO board type.
0x75     DIO_BOARD_TYPE_GX5290E - Gx5290 Express DIO board type.
0x7A     DIO_BOARD_TYPE_GX5295 - Gx5295 board type.
bRealtimeCompare
BOOL
If TRUE then the generated output DIO file will be Real Time compare type.
pszImportOptions
PSTR
Optional buffer to specify or receive import options string (null terminated).
When pszOutputDioFile is not NULL, this parameter specifies the import options such as unused signals, signal direction and cycle-based timing (VCD/eVCD only), this parameter can be NULL. See Software User's Guide - Import File for more details info and examples of import options string.
When requesting default import options string and pszImportOptions is NULL or the buffer is not large enough to hold the return string then no data is copied and the required buffer size is stored in pnImportOptionsMaxLen. See Software User's Guide - Import File section for more details.
pnImportOptionsMaxLen
PSHORT
The size of the import options buffer size. see Software User's Guide - Import File.
bWait
BOOL
Determine if the function returns immediately or wait until the file import is complete:
0 The function returns immediately and the import file will be done at the background. In this case the user can check the import file progress using the DioFileImportGetProgress API.
1 The function returns only when file import in complete or in case of an error.
NOTE: If pszOutputDioFile is set to NULL, i.e. the user wants to get back the pszImportOptions string , then bWait is ignored (internally set to TRUE).
phHandle
PHANDLE
If bWait was set to FALSE, the function returns a HANDLE to the file import object. The user can then use that handle to monitor the progress  by polling the DioFileImportGetProgress API. The returned handle can be used with WaitForSingleObject Windows API to wait until import completed or timed out.
If bWait was set to TRUE, this parameter will be ignored and can be passes as NULL.
pszError
PSTR
Buffer to contain the returned error or warning string (null terminated).
nErrMaxLen
SHORT
Size of the buffer to contain the error string.
pnStatus
PSHORT
Returned status: 0 on success, negative number on failure.

Comments

The function converts the specified file to DIO file format.

Using the pszImportOptions string:

The pszImportOptions string specified the diffent options for each signal. The options are direction, dpendency on other signals for direction and to be use or not in the convetered file.

In the following pszImportOptions example string, the MCLK signal is bidirectional and its direction is set to input whenever ACKHW signal is high. Also MRB is set to be unused in this

Signals]

MCLK : Bidir  In When [ACKHW 1];

MRB : Unused Output;

ACKHW Input;

AUTOEN;

 [End]

The user can get the pszImportOptions string form the import file API by calling DioFileImport with the pszOutputDioFile parameter  set to NULL. In that case the function will not convert the input file but instead will fill the pszImportOptions string and pnImportOptionsMaxLen returns the size of the string.

If the user wants  to know the eaxct size of the  returned pszImportOptions string, and have buffer ready for it with the corrct size, then call DioFileImport with the pszOutputDioFile parameter and pszImportOptions both set to NULL.

Example

Importing a file with bWait=TRUE and using default szImportOptions string:

The following example convert a STIL file to a Gx5295 DIO with Real time compare file:

 

SHORT nStatus;

CHAR szError[512];

Convert the STIL file to a DIO file.

DioFileImport (“InputStilFile.stil”, “OutputDioFile.dio”, DIO_BOARD_TYPE_GX5295, TRUE, NULL, NULL, TRUE, NULL, szError, sizeof (szError), &nStatus);

 

Importing a file with bWait=TRUE and using szImportOptions string:

The following example convert a STIL file to a Gx5295 DIO with Real time compare file using the following steps:

  1. Get the input STIL file szImportOptions string size.

  2. Allocate a buffer with the correct szImportOptions string size.

  3. Convert the STIL file to a DIO file.

 

SHORT nStatus;

SHORT nImportOptionsMaxLen;

CHAR  szError[512];

PCHAR pszImportOptions=NULL;

// request the buffer size to receive the default import options string  by passing NULL to  pszOutputDioFile and pszImportOptions

DioFileImport (“InputStilFile. stil”, NULL, DIO_BOARD_TYPE_GX5295, TRUE, NULL, &nImportOptionsMaxLen, TRUE, NULL, szError, sizeof (szError), &nStatus);

// Allocate a buffer with the correct szImportOptions string size

pszImportOptions = new char[nImportOptionsMaxLen];

// request the default import options string by passing NULL to pszOutputDioFile

DioFileImport (“InputStilFile. stil”, NULL, DIO_BOARD_TYPE_GX5295, TRUE, NULL, &nImportOptionsMaxLen, TRUE, NULL, szError, sizeof (szError), &nStatus);

// modify the default import options string, for example, set SignalA to unused …

[Signals]

    SignalA : unused Output;

[End]

// Convert the STIL file to a DIO file using modified import options.

DioFileImport (“InputStilFile.stil”, “OutputDioFile.dio”, DIO_BOARD_TYPE_GX5295, TRUE, pszImportOptions, &nImportOptionsMaxLen, TRUE, NULL, szError, sizeof (szError), &nStatus);

 

Importing a file using default szImportOptions string and monitoring the progress (bWait=FALSE):

The following example convert a STIL file to a Gx5295 DIO with Real time compare file

 

SHORT nStatus;

CHAR szStatus[512];

HANDLE hHandle=NULL;

DioFileImport (“InputStilFile.stil”, “OutputDioFile.dio”, DIO_BOARD_TYPE_GX5295, TRUE, NULL, 0, FALSE, &hHandle, szStatus, sizeof (szStatus), &nStatus);

// Monitor the import file process

// Monitor the import file process

while (nStatus>=0)

{

    DioFileImportGetProgress(hHandle, szStatus, sizeof (szStatus), &nStatus);

if (nStatus>0)

        printf(“Progress = %i”, (int) nStatus);   // continue

    else

       break;

     // wait for import to finish or time out every 250ms without consuming the CPU

     WaitForSingleObject(hHandle, 250);

}

printf(szStatus);   // print complete (nStatus=0), warning, errrors

 

See Also

DioFileImportPanel, DioFileImportGetProgress, DioGetErrorString