Non-DDE application programming interface

OpenTM2 provides an application programming interface (API) that enables an application to directly communicate with the OpenTM2 functions without OpenTM2 running. However, it is required thatOpenTM2 is installed, all OpenTM2 drives are configured, and shared resources are connected. The application can communicate with all functions currently covered by the dynamic data exchange (DDE) interface (that is, the EQFCMD command area). In addition, it can use all functions concerning dictionary and Translation Memory handling, namely retrieving dictionary and Translation Memory proposals and updating dictionaries and Translation Memory databases.

Contents

Overview and terminology

Each OpenTM2 function includes a generic data block, which is encapsulated in the session handle. This session handle is created by the EqfStartSession call (see EqfStartSession). It ensures that several OpenTM2 functions can run concurrently. The functions are delivered as a library and a dynamic-link library (DLL) following the standard PASCAL calling conventions. The include file EQFFUNC.H contains the prototypes of all available functions.

The long-running tasks, such as the export or the organization of a Translation Memory, are split into small units of work. The return code indicates if the task has completed successfully or if data is pending. The calling application must allocate the memory and free it when no longer used. In this way, the interface is independent of any compiler or runtime libraries used.

folderdefinition in non-DDE API subfolderdefinition in non-DDE API The term “folder” in the following descriptions also implies subfolders. Whenever a function requires the specification of a folder as a parameter, for example “folder_main”, you can also specify a subfolder, for example “folder_2001\\folder_sub1”. You can even expand subfolder specifications, up to the limits of the operating system, for example “folder_2001\\folder_sub1\\sub_sub\\sub_sub_sub\\…”.

Data types

The non-DDE interface for OpenTM2 functions uses the following data types for parameters and return codes:

HSESSION The session handle that is created by EqfStartSession . It must be specified in all other functions of the non-DDE interface.
PHSESSION The pointer to a HSESSION variable.
LONG A long (32-bit) signed integer. In the non-DDE interface, this data type is used for option flags. Use 0L if no options are to be specified.
PSZ The pointer to a zero-terminated string (C-language string). Use NULL if no parameter is specified.
USHORT A short (16-bit) unsigned integer value. This data type is used for return codes.
PUSHORT The pointer to a variable of type USHORT.
FORMLIST A structure consisting of two length fields and a memory block. The byte ch indicates the start of the memory block:

typedef struct 
{ 
   ULONG ulAllocated; 
   ULONG ulUsed; 
   BYTE ch; 
} FORMLIST, *PFORMLIST;

Sample code

The following sample is written in C. It shows how to create a new folder and how to import and analyze documents.

USHORT usRC = 0;
HSESSION hSession = 0L;

// start the Eqf session
usRC = EqfStartSession( &hSession );

// create the folder SAMPLE1
if ( !usRC )
{
 usRC = EqfCreateFolder( hSession, "SAMPLE1", NULL, '\0', "MEM1",
                         "EQFASCII", NULL, NULL, "English(U.S.)",
                         "German(national)" );
}

// import the documents TEST1.DOC and TEXT2.DOC into folder SAMPLE1
if ( !usRC )
{
 do
 {
 usRC = EqfImportDoc( hSession, "SAMPLE1", NULL,
                      "C:\\TEXT1.DOC,C:\\TEXT2.DOC",
                      NULL, NULL, NULL, NULL, NULL, NULL, 0L );
 } while( usRC == CONTINUE_RC );
}

// Analyze all documents of folder SAMPLE1
if ( !usRC )
{
 do
 {
 usRC = EqfAnalyzeDoc( hSession, "SAMPLE1", NULL, NULL, 0L );
 } while( usRC == CONTINUE_RC );
}

// end the Eqf session
if ( hSession != 0L )
{
 EqfEndSession( hSession );
}

Calling interface reference

The following sections describe the individual calls provided by OpenTM2. The following calls are available:

Call… described in
EqfAnalyzeDoc EqfAnalyzeDoc
EqfAnalyzeDocEx EqfAnalyzeDocEx
EqfArchiveTM EqfArchiveTM
EqfBuildSegDocName EqfBuildSegDocName
EqfChangeFolProps EqfChangeFolProps
EqfChangeFolPropsEx EqfChangeFolPropsEx
EqfChangeMFlag EqfChangeMFlag
EqfCleanMemory EqfCleanMemory
EqfCountWords EqfCountWords
EqfCreateCntReport EqfCreateCntReport
EqfCreateCountReport EqfCreateCountReport
EqfCreateControlledFolder EqfCreateControlledFolder
EqfCreateFolder EqfCreateFolder
EqfCreateITM EqfCreateITM
EqfCreateMem EqfCreateMem
EqfCreateSubFolder EqfCreateSubFolder
EqfDeleteDoc EqfDeleteDoc
EqfDeleteFolder EqfDeleteFolder
EqfDeleteMem EqfDeleteMem
EqfEndSession EqfEndSession
EqfExportDoc EqfExportDoc
EqfExportDict EqfExportDict
EqfExportFolder EqfExportFolder
EqfExportFolderFP EqfExportFolderFP
EqfExportFolderFPas EqfExportFolderFPas
EqfExportMem EqfExportMem
EqfFreeSegFile EqfFreeSegFile
EqfGetLastError EqfGetLastError
EqfGetProgress EqfGetProgress
EqfGetSegNum EqfGetSegNum
EqfGetSegW EqfGetSegW
EqfImportDoc EqfImportDoc
EqfImportDict EqfImportDict
EqfImportFolder EqfImportFolderEqfImportFolder
EqfImportFolderFP EqfImportFolderFP
EqfImportMem EqfImportMem
EqfLoadSegFile EqfLoadSegFile
EqfOrganizeMem EqfOrganizeMem
EqfProcessNomatch EqfProcessNomatch
EqfStartSession EqfStartSession
EqfUpdateSegW EqfUpdateSegW
EqfWriteSegFile EqfWriteSegFile

EqfAnalyzeDoc

Purpose

EqfAnalyzeDoc analyzes one or more documents. If no documents are specified, the function analyzes all documents in the selected folder.

This function performs the analysis in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure1.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession .
PSZ pszFolderName The name of the folder containing the documents.
PSZ pszDocument The name of one or more documents. If you want to analyze all documents in the folder, specify NULL or an empty list.
PSZ pszMemName The name of the Translation Memories to be used as search memories.
LONG lOptions The options to be used for the analysis:

  • TMMATCH_OPT
  • ADDTOMEM_OPT
  • AUTOSUBST_OPT
  • UNTRANSLATED_OPT
  • AUTOLAST_OPT
  • AUTOJOIN_OPT
  • AUTOCONTEXT_OPT
  • REDUNDCOUNT_OPT
  • OVERWRITE_OPT
  • IGNOREPATH_OPT
  • ADJUSTLEADWS_OPT
  • ADJUSTTRAILWS_OPT
  • NOBLANKATSEGEND_OPT
  • NOSUBSTIFIDENTICAL_OPT
  • PROTECTXMPSCREEN_OPT
  • RESPECTCRLF_OPT
  • STOPATFIRSTEXACT_OPT
  • IGNORECOMMENTED_OPT

These options correspond to those on the “Analyze Documents” window (see Analyzing a document). OVERWRITE_OPT must be specified if the translation of the documents has already started.

You can combine the constants using OR.

Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The analysis has not completed yet. Call EqfAnalyzeDoc again.
other Error code (EQF mesasge number). Use EqfGetLastError to retrieve the complete error information.
Code sample
{
 USHORT usRC = 0;
 HSESSION hSession = 0L;

 // start the Eqf calling interface session
 usRC = EqfStartSession( &hSession );

 // Analyze all documents of folder SAMPLE1 and
 // substitute exact matches automatically
 if ( !usRC )
 {
   do
   {
     usRC = EqfAnalyzeDoc( hSession, "SAMPLE1", NULL, ("Mem1", "Mem2"),
                           AUTOSUBST_OPT | OVERWRITE_OPT );
   } while ( usRC == CONTINUE_RC );
  } /* endif */

 // terminate the session
 EqfEndSession( hSession );
}

EqfAnalyzeDocEx

Purpose

EqfAnalyzeDocEx analyzes one or more documents. If no documents are specified, the function analyzes all documents in the selected folder.

This function performs the analysis in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure2.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder containing the documents.
PSZ pszDocument The name of one or more documents. If you want to analyze all documents in the folder, specify NULL or an empty list.
PSZ pszMemNames The name of one or more Translation Memories to be used as search memories. Use a comma separated list if more than one memory is specified, specify NULL if no search memory is to be used
PSZ pszMemNames The name of one or more Translation Memories to be used as search memories. Use a comma seperated list if more than one memory is specified, specify NULL if no search memory is to be used
PSZ pvReserved reserved for future enhancements, specify NULL
LONG lOptions The options to be used for the analysis:

  • TMMATCH_OPT
  • ADDTOMEM_OPT
  • AUTOSUBST_OPT
  • UNTRANSLATED_OPT
  • AUTOLAST_OPT
  • AUTOJOIN_OPT
  • AUTOCONTEXT_OPT
  • REDUNDCOUNT_OPT
  • OVERWRITE_OPT
  • IGNOREPATH_OPT
  • ADJUSTLEADWS_OPT
  • ADJUSTTRAILWS_OPT
  • NOBLANKATSEGEND_OPT
  • NOSUBSTIFIDENTICAL_OPT
  • RESPECTCRLF_OPT
  • STOPATFIRSTEXACT_OPT
  • IGNORECOMMENTED_OPT

These options correspond to those on the “Analyze Documents” window (see Analyzing a document). OVERWRITE_OPT must be specified if the translation of the documents has already started.

You can combine the constants using OR.

Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The analysis has not completed yet. Call EqfAnalyzeDocEx again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
{
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Analyze all documents of folder SAMPLE1 and
  // substitute exact matches automatically, use analysis profile Profile1
  if ( !usRC )
 {
   do
   {
     usRC = EqfAnalyzeDocEX( hSession, "SAMPLE1", NULL, ("Mem1", "Mem2"), "Profile1",
                             NULL, AUTOSUBST_OPT | OVERWRITE_OPT );
   } while ( usRC == CONTINUE_RC );
 } /* endif */

 // terminate the session
 EqfEndSession( hSession );
}

EqfArchiveTM

Purpose

EqfArchiveTM builds an Archive Translation Memory from an existing Translation Memory. At least one segment of at least one document you want to archive must have been translated (when SOURCESOURCEMEM_OPT option is not specified).
The SOURCESOURCEMEM_OPT option can be used to create a source-source Translation Memory. If the option is specified all translatable segments of the document are written to the specified Translation Memory. Without the option only segments already translated are processed.

Format

Chap21 Figure3.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder.
CHAR chTargetDrive The target drive where the folder is located, or '/0' if it is the drive where the eqf directory is located.
PSZ pszDocuments List of the documents that are searched for translated segments to be included in the Translation Memory, or NULL to search in all documents of the folder.
PSZ pszMemName The name of an existing Translation Memory.
LONG lOptions The options used for the Archive Translation Memory:

  • OVERWRITE_OPT (overwrites the contents of an existing Translation Memory)
  • USEASFOLDERTM_OPT (uses the Translation Memory as the new folder Translation Memory)
  • SOURCESOURCEMEM_OPT (creates a source-source Translation Memory containing all translatable segments of the document)
  • SETMFLAG_OPT (sets the machine translation flag of the segments written to the Translation Memory)
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The Archive Translation Memory has not completed yet. Call EqfArchiveTM again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession(&hSession);

  // Build Archive Translation Memory "MEM1" for the folder
  // "TEST" (including document "test.txt")
  if ( !usRC )
 {
   do
   {
     usRC = EqfArchiveTM(hSession, "TEST",'i',
                                   "test.txt",
                                   "MEM1",
                                   OVERWRITE_OPT|USEASFOLDERTM_OPT);
   } while ( usRC == CONTINUE_RC );
 } //endif

 // terminate the session
 EqfEndSession( hSession );
}

EqfBuildSegDocName

Purpose

Builds the fully qualified file name of a segmented document within a OpenTM2 folder.

Format

Chap21 Figure4.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName Long name of the folder
PSZ pszDocumentName Long document name
USHORT fSource Flag selection source or target document

  • 0 = build segmented source file name
  • 1 = build segmented target file name
PSZ pszSegFile Points to a buffer receiving the fully qualified document file name, must have a width of at least 60 characters
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
{
  USHORT usRC = 0;
  CHAR szFileName [60];
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  if ( !usRC )
  {
   usRC = EqfBuildSegDocName( hSession, "SAMPLE1", "Document1", 1, szFileName );
 } // endif

 // terminate the session
 EqfEndSession( hSession );
}

EqfChangeFolProps

Purpose

EqfChangeFolProps lets you change the following folder properties: the target language, the folder Translation Memory, and the dictionaries.

Format

Chap21 Figure5.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder.
CHAR chTargetDrive The target drive where the folder is located, if it is not the drive where the eqf directory is located. If you do not specify a drive, specify '/0' .
PSZ pszTargetLanguage The target language for the documents in this folder, or NULL if the target language should not be changed. Specify the language exactly as it appears in the “Language List “window, for example English(U.S.) . The target language must be different from the source language.
PSZ pszMemName The name of the Translation Memory, or NULL if the Translation Memory should not be changed.
PSZ pszDictionaries The list of dictionaries to be used during translation. You can specify up to 10 dictionaries. If the dictionaries should not be changed, specify NULL .
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession(&hSession);

  // Change the properties (target language, Memory, Dictionaries)
  // of the folder named "test"
  if ( !usRC )
  {
   usRC = EqfChangeFolProps(hSession, "test", 'e',
                            "English(U.S)",
                            "MEM1", "DICT1,DICT2");
 } //endif

 // terminate the session
 EqfEndSession( hSession );
}

EqfChangeFolPropsEx

Purpose

EqfChangeFolPropsEx lets you change the following folder properties: the target language, the folder Translation Memory, the dictionaries and the search Translation Memory databases.

Format

Chap21 Figure6.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder.
CHAR chTargetDrive The target drive where the folder is located, if it is not the drive where the eqf directory is located. If you do not specify a drive, specify '/0' .
PSZ pszTargetLanguage The target language for the documents in this folder, or NULL if the target language should not be changed. Specify the language exactly as it appears in the “Language List” window, for example English(U.S.) . The target language must be different from the source language.
PSZ pszMemName The name of the Translation Memory, or NULL if the Translation Memory should not be changed.
PSZ pszDictionaries The list of dictionaries to be used during translation. You can specify up to 10 dictionaries. If the dictionaries should not be changed, specify NULL .
PSZ pszMemories The list of search Translation Memory databases to be used during analysis and translation. You can specify up to 10 Translation Memory databases. If the search Translation Memory databases should not be changed, specify NULL .
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession(&hSession);

  // Change the properties (target language, Memory, Dictionaries)
  // of the folder named "test"
  if ( !usRC )
  {
   usRC = EqfChangeFolProps(hSession, "test", 'e',
                            "English(U.S)",
                            "MEM1", "DICT1,DICT2");
 } //endif

 // terminate the session
 EqfEndSession( hSession );
}

EqfChangeMFlag

Purpose

Segments that were translated by machine are prefixed with an [m]. OpenTM2 provides a command to have these m prefixes removed from machine-translated segments in a Translation Memory. Alternatively, this function lets you add m flags to segments that did not have such a flag before.

Format

Chap21 Figure7.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszTransMem The name of the Translation Memory that you want to work with.
LONG lAction Specifies whether you want to remove (CLEAR_MMOPT) or set (SET_MMOPT) the m flags in the specified Translation Memory.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession(&hSession);

  // Remove m flags in Translation Memory TestTM.
  if ( !usRC )
  {
   usRC = EqfCreateITM(hSession, "TestTM", CLEAR_MMOPT);
  } //endif

 // terminate the session
 EqfEndSession( hSession );
}

EqfCleanMemory

Purpose

The API call EqfCleanMemory removes all segments which are not relevant for a given translation package from an external memory. The “cleaned” memory can be created in internal or external format.

This function performs the cleanup in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure8.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolder The name of a OpenTM2 folder (already imported into TM and the documents have to be analyzed).
PSZ pszInMem The fully qualified file name of the input memory in Ansi or UTF-16 encoding.
PSZ pszOutMem The name of an new internal memory or the fully qualified name of an external.
LONG lOptions The option to be used for the cleanup of a memory:

  • CLEANMEM_INTERNAL_MEMORY_OPT to create an internal memory
  • CLEANMEM_EXTERNAL_MEMORY_OPT to create an external memory (default)
  • OVERWRITE_OPT to overwrite any existing output memory
  • CLEANMEM_COMPLETE_IN_ONE_CALL_OPT If set the API call does not return after each processing step but stays in the API call ntil the function has been completed
  • CLEANMEM_BESTMATCH_OPT if set only the best match is written to the output memory, if not set the best three matches are written to the output memory
  • CLEANMEM_MERGE_OPT when specified the cleaned memory matches are merged into an existing memory rather than creating a new one
  • CLEANMEM_KEEP_DUPS_OPT when specified duplicate exact matches are left in the memory (without this option only the first exact match is left in the memory). Fuzzy matches are left in the memory as long there is no exact match for the same segment (withhout this option only the best fuzzy match is left in the memory)
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The memory cleanup has not been completed yet. Call again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
HSESSION hSession;
USHORT usRC;

usRC = EqfStartSession( &hSession );
usRC = EqfCleanMemory( "TestFolder",
"C:\EXPMEMORY\SAMPLE2.EXP",
"C:\\EXPMEMORY\SAMPLEOUT.EXP",
CLEANMEM_EXTERNAL_MEMORY_OPT | CLEANMEM_COMPLETE_IN_ONE_CALL_OPT | OVERWRITE_OPT );

usRC = EqfEndSession( hSession );

EqfCountWords

Purpose

EqfCountWords counts the words of one or more documents. This function performs the counting in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure9.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder containing the documents which are to be counted.
PSZ pszDocuments The pointer to a list of documents or NULL if no documents are specified. If no documents are specified, the words of all documents in the folder are counted.
LONG lOptions The options to be used for the counting:

  • SOURCE_OPT (source word count)
  • TARGET_OPT (translated/untranslated word count)
  • TMMATCH_OPT (memory match count)
  • DUPLICATE_OPT (count duplicate words)
  • DUPMEMMATCH_OPT (count duplicate words and include memory match information)

For the TMMATCH_OPT the following option can be specified

  • SEPERATEREPLMATCH_OPT to count replace matches seperately

These constants are mutually exclusive, the can by combined with the format of the output file:

  • XML_OUTPUT_OPT (output as XML file)

or

  • TEXT_OUTPUT_OPT (output in text format)

or

  • HTML_OUTPUT_OPT (output in HTML format)

and the OVERWRITE_OPT (to overwrite existing output files) using “|” (bitwise OR operator).

If no output format is specified TEXT_OUTPUT_OPT is used as default.

PSZ pszOutFile The fully qualified name of the output file. If the file already exists, specify the OVERWRITE_OPT option (otherwise this call fails).
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC Word counting has not completed yet. Call EqfCountWords again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Count the source (=original) words of all documents in folder
  // SAMPLE1 and store the counting results in file C:\COUNT.OUT
  if ( !usRC )
  {
   do
   {
    usRC = EqfCountWords( hSession, "SAMPLE1", NULL, SOURCE_OPT,
                          "C:\\COUNT.OUT" );
   } while ( usRC == CONTINUE_RC );
  } /* endif */

 // terminate the session
 EqfEndSession( hSession );
}

EqfCreateCntReport

Purpose

EqfCreateCntReport creates Calculating, Preanalysis, Redundancy, Redundant segment list reports.

Format

Chap21 Figure10.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder.
PSZ pszDocuments List of documents, or NULL if all documents of the folder should be used.
PREPORT TYPE pstructReportType See Parameters for structReportType for details.
PSZ pszOutfileName The name of the file where the report is to be stored (along with the drive and directory information).
PSZ pszFormat Format of the Output file (“ASCII”,” HTML”, or “XML”).
PSZ pszProfile The name of the profile to be loaded, or NULL .
PREPORT SETTINGS pstructRepSettings See Parameters for structRepSettings for details.
PFACTSHEET pstructFactSheet [usColumn][usCategory] Array of structFactSheet. See Parameters for structFactSheets for details.
USHORT usColumn The first array index represents the column number according to the listed columns in the dialog “Create Counting Report”, tab “Fact Sheet”.
USHORT usCategory The second array index represents the category number according to the listed categories in the dialog “Create Counting Report”, tab “Fact Sheet”.
PFINAL FACTORS pstructFinalFactors See Parameters for structFinalFactors for details.
LONG lOptSecurity The options to be used for security:

  • PLAUS_OPT (Plausibility check)
  • LOST_OPT (Lost Data: Force new shipment)
  • LIST_OPT (List of Documents)

You can combine the options using OR.

BOOL bSingleShipment
  • TRUE = Single Shipments
  • FALSE = All Shipments
Parameters for structReportType
typedef struct _REPORTTYPE
{
 PSZ pszReport;
 LONG lRepType;
 PSZ pszDescription;
} REPORTTYPE, *PREPORTTYPE;

 

Type Parameter Description
PSZ pszReport Specifies one of the following reports:

  • “Calculating Report”
  • “Pre-Analysis Report”
  • “Redundancy Report”
  • “Redundant Segment List”
LONG lRepType One, or a combination, of the following report types:

  • BASE_TYP
  • FACT_TYP
  • SUM_TYP

Allowed combinations are:

  • Base
  • Summary
  • Fact Sheet
  • Base & Summary
  • Summary & Fact Sheet
  • Base, Summary & Fact Sheet
PSZ pszDescription The report description, or NULL .
Parameters for structRepSettings
typedef struct _REPORTSETTINGS
{
 PSZ pszCountType;
 BOOL bShow;
 BOOL bSummary;
 PSZ pszRepLayout;
 BOOL bShrink;
 PSZ pszStatisticType;
 BOOL bExProposal;
} REPORTSETTINGS, *PREPORTSETTINGS;
Type Parameter Description
PSZ pszCountType Specifies what to count:

  • “Source Words”
  • “Target Words”
  • “Segments”
  • “Modified Words”
BOOL bShow
  • TRUE = Show categories
  • FALSE = Hide categories
BOOL bSummary Build summary of categories
PSZ pszRepLayout Specifiy one of the following layouts:

  • “Standard”
  • “Standard and Group-Summary”
  • “Shrunk to Groups”
BOOL bShrink Automatic Shrink
PSZ pszStatisticType For pszReport = “Calculating Report” specify one of the following keywords:

  • “Standard”
  • “Advanced”

or NULL for all other reports or no statistics.

BOOL bExProposal Use Existing Proposals.
Parameters for structFactSheet
typedef struct _FACTSHEET
{
 LONG lComplexity;
 LONG lPayFactor;
} FACTSHEET,*PFACTSHEET;

 

Type Parameter Description
float lComplexity Specifies the Complexity Factor.
float lPayFactor Specifies the Pay Factor.
Parameters for structFinalFactors
typedef struct _FINALFACTORS
{
 LONG lUnit;
 LONG lCurrFactor;
 PSZ pszLocalCurrency;
} FINALFACTORS,*PFINALFACTORS;

 

Type Parameter Description
LONG lUnit Values (in words):

  • 1
  • 10
  • 250
float lCurrFactor Specifies the local currency factor.
PSZ pszLocalCurrency Specifies the local currency. The local currencies correspond to the values of the dialog “Create Counting Report”, tab “Fact Sheet”.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;
  int i,j;
  #define COLUMN 10;
  #define CATGORY 3;

  REPORTTYPE ReportType = {NULL, 0L, NULL};
  REPSETTINGS ReportSettings = {NULL, 0, 0, NULL, 0, NULL, 0};
  FACTSHEET FactSheet[COLUMN][CATEGORY];
  FINALFACT FinalFactors = {0L, 0L NULL};

  //fill ReportType structure
  ReportType.pszReport = "Calculating Report");
  ReportType.lRepType=BASE_TYP | FACT_TYP | SUM_TYP;
  ReportType.pszDescription[0]='\0';

  //fill ReportSettings strucure
  RepSettings.pszCountType = "Source Words";
  RepSettings.bShow=TRUE;
  RepSettings.bSummary=TRUE;
  RepSettings.pszRepLayout = "Standard";
  RepSettings.bShrink=FALSE;
  RepSettings.pszStatisticType = NULL;
  RepSettings.bExProposal=FALSE;

  //fill FactSheet structure
  for(i=0;i++,i<COLUMN)
  {
   for(j=0,j++,j<CATEGORY)
   {
    FactSheet[i][j].lComplexity = (float)1.0;
    FactSheet[i][j].lPayFactor = (float)1.0;
   }
  }

  // fill FinalFactors structure
  FinalFactors.lUnit = 1;
  FinalFactors.lCurrFactor = (float)1.0;
  FinalFactors.pszLocalCurrency = "EUR";

  // start the Eqf calling interface session
  usRC = EqfStartSession(&hSession);

  if ( !usRC )
  {
  usRC = EqfCreateCntReport(hSession, 'e', "TEST", "test.doc,
                            test2.doc", &ReportType,
                            "E:\\Project\\CalcReport", "HTML",
                            NULL,
                           &RepSettings,(void *)FactSheet,
                            COLUMN, CATEGORY, &FinalFactors,
                            PLAUS_OPT, TRUE);
  } //endif
  // terminate the session
  EqfEndSession( hSession );
 }

EqfCreateCountReport

Purpose

EqfCreateCountReport creates Calculating, Preanalysis, Redundancy, Redundant segment list reports using the supplied profile.

Format

Chap21 Figure11.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder.
PSZ pszDocuments List of documents, or NULL if all documents of the folder should be used.
PSZ pszOutfileName The name of the file where the report is to be stored (along with the drive and directory information).
PSZ pszProfile The name of the profile to be loaded.
USHORT usReport Type of report:

  • HISTORY_REP (History Report)
  • COUNTING_REP (Counting Report)
  • CALCULATING_REP (Calculation Report)
  • PREANALYSIS_REP (PreAnalysis Report)
  • REDUNDANCY_REP (Redundncy Report)
  • REDUNDANCYSEGMENT_REP (Redundancy Segment List)
USHORT usType Type of report:for HISTORY_REP

  • BRIEF_SORTBYDATE_REPTYPE
  • BRIEF_SORTBYDOC_REPTYPE
  • DETAIL_REPTYPE

for HISTORY_REP

  • WITHTOTALS_REPTYPE
  • WITHOUTTOTALS_REPTYPE

for CALCULATING_REP, PREANALYSIS_REP, and REDUNDANCY_REP

  • BASE_REPTYPE
  • BASE_SUMMARY_REPTYPE
  • BASE_SUMMARY_FACTSHEET_REPTYPE
  • SUMMARY_FACTSHEET_REPTYPE
  • FACTSHEET_REPTYPE
LONG lOptions Options for the counting report: OVERWRITE_OPT or 0
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;
  // start the Eqf calling interface session
  usRC 0 EqfStartSession(&hSession)

  if ( !usRC )
  {
   usRC = EqfCreateCountReport(hSession, 'e', "TEST", "test.doc,
                               test2.doc",
                               "E:\\Project\\CalcReport",
                               COUNTING_REP, BASESUMMARY_REPTYPE
                               "PUB0205", OVERWRITE_OPT);
  } //endif
  // terminate the session
  EqfEndSession( hSession );
}

EqfCreateControlledFolder

Purpose

EqfCreateControlledFolder creates a new controlled folder by using the specified values. Configure the target drive for the folder using the “Configure Drives” window of OpenTM2.

Format

Chap21 Figure12.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder to be created.
PSZ pszDescription The folder description, or NULL .
CHAR chTargetDrive The target drive for the new folder. If omitted, the primary EQF drive is used. The drive must be the primary EQF drive or one of the secondary EQF drives defined in the “Configure Drives” window.
PSZ pszTransMem The name of the Translation Memory to be used for the documents in the new folder.
PSZ pszMarkup The name of the markup table, for example EQFMRI.
PSZ pszEditor The name of the editor. If not specified, the editor STANDARD is used.
PSZ pszDictionaries The list of dictionaries to be used during translation. You can specify up to 10 dictionaries.
PSZ pszSourceLanguage The source language for the documents in this folder. Specify the language exactly as it appears in the “Language List” window, for exampleEnglish(U.S.) .
PSZ pszTargetLanguage The target language for the documents in this folder. Specify the language exactly as it appears in the “Language List” window, for exampleEnglish(U.S.). The target language must different from the source language.
PSZ pszConversion The export conversion type, or <tt> NULL for no conversion.
PSZ pszReadOnlyMems The list of Translation Memories to search through during translation, or NULL . You can specify up to 4 Translation Memories.
PSZ pszPassword The password to protect the folder against changes. The password can be up to six characters long.
PSZ pszProjCoordName The name of the project coordinator, or NULL .
PSZ pszProjCoordMail The e-mail address of the project coordinator, or NULL .
PSZ pszTranslatorName The name of the translator responsible for this folder, or NULL .
PSZ pszTranslatorMail The e-mail address of the translator, or NULL .
PSZ pszProductName The product name this folder is assigned to, or NULL .
PSZ pszProductFamily The product family this folder is assigned to, or NULL .
PSZ pszSimilarProduct The name of a similar product this folder is assigned to, NULL .
PSZ pszProductDict The product-specific dictionary to be used during translation, or NULL .
PSZ pszProductMem The product-specific memory to be used during translation, or NULL .
PSZ pszPreviousVersion The previous version number of the product specified above, or NULL .
PSZ pszVersion The actual version number of the product specified above, or NULL .
PSZ pszShipmentNumber The number of the shipment, or NULL .
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession(&hSession);

  // Create a new controlled folder name 'Test' on the
  // primary Eqf drive
  if ( !usRC )
  {
   usRC = EqfCreateControlledFolder(hSession, "Test",
                                    "Description of folder Test",
                                    '\0', // use primary Eqf drive
                                    "MEM1", "EQFASCII",
                                    "STANDARD", "DICT1,ENGLGERM",
                                    "English(U.S.)","German(national)",
                                    NULL, NULL, "passwd",
                                    "ProjCoordName", "ProjCoordMail",
                                    "TranslatorName","TranslatorMail", NULL,
                                    "Family", NULL, "Dict", "MemoryName",
                                    "1.0", "2.0", "1");
  } //endif

  // terminate the session
  EqfEndSession( hSession );
}

EqfCreateFolder

Purpose

EqfCreateFolder creates a new folder by using the specified values. Configure the target drive for the folder using the “Configure Drives” window of OpenTM2.

Format

Chap21 Figure13.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder to be created.
PSZ pszDescription The folder description, or NULL .
CHAR chTargetDrive The target drive for the new folder. If omitted, the primary EQF drive is used. The drive must be the primary EQF drive or one of the secondary EQF drives defined in the “Configure Drives”window.
PSZ pszTransMem The name of the Translation Memory to be used for the documents in the new folder.
PSZ pszMarkup The name of the markup table, for example EQFMRI.
PSZ pszEditor The name of the editor. If not specified, the editor STANDARD is used.
PSZ pszDictionaries The list of dictionaries to be used during translation. You can specify up to 10 dictionaries.
PSZ pszSourceLanguage The source language for the documents in this folder. Specify the language exactly as it appears in the “Language List” window, for exampleEnglish(U.S.) .
PSZ pszTargetLanguage The target language for the documents in this folder. Specify the language exactly as it appears in the “Language List” window, for exampleEnglish(U.S.) .
PSZ pszConversion Conversion to be used for the folder or NULL .
PSZ pszROMemory List of read-only memories to be searched or NULL .
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Create a new folder name SAMPLE1 on the primary Eqf drive
  if ( !usRC )
  {
   usRC = EqfCreateFolder( hSession, "SAMPLE1",
                           "Description of folder SAMPLE1",
                           '\0', // use primary Eqf drive 
                           "MEM01", "EQFASCII", "STANDARD",
                           "DICT1,ENGLGERM", "English(U.S.)",
                           "German(National)" );

  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfCreateITM

Purpose

EqfCreateITM creates an Initial Translation Memory (ITM) database from an existing Translation Memory. It can create an internal Translation Memory and an external Translation Memory. The internal Translation Memory must not be filled.

Important hint: If you want to generate a source English-English memory (i.e. a memory where the source sentence and the target sentence are identical), please always use EQFArchiveTM function with the option SOURCESOURCEMEM_OPT.

Format

Chap21 Figure14.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszMemDB The name of a previously created OpenTM2 Translation Memory (without the file extension). This Translation Memory can still be empty. It can be filled with original segments and their corresponding translations.
PSZ pszFilePairs List of file names to use when creating the ITM, in the form ( original1, translation1, original2, translation2 ).
PSZ pszMarkup The name of the markup table, for example EQFMRI.
PSZ pszSGMLMemFile The name you want to give to the external ITM, and the path where it is to be located. The ITM is in SGML format and can subsequently be imported into OpenTM2 after you have checked it.
PSZ pszSourceLanguage The source language for the documents in this folder. Specify the language exactly as it appears in the “Language List” window, for exampleEnglish(U.S.) .
PSZ pszTargetLanguage The target language for the documents in this folder. Specify the language exactly as it appears in the “Language List” window, for exampleEnglish(U.S.) .
PSZ pszSourceStartPath The path information that you do not want to become part of the document name when the original document is stored in the Initial Translation Memory.For example, if your source file is stored in e:\tm\project\english , and you do not want e:\tm\project to become part of the name under which it is stored, specify e:\tm\project .The path you specify here can differ from the pszTargetStartPath. However, if you specify a source start path, you must also specify apszTargetStartPath.
PSZ pszTargetStartPath The path information that you do want to become part of the document name when the target document is stored in the Initial Translation Memory.For example, if your source file is stored in e:\tm\project\english and you do not want e:\tm\project to become part of the name under which it is stored, specify e:\tm\project .The path you specify here can differ from the pszSourceStartPath. However, if you specify a source start path, you must also specify apszSourceStartPath.
LONG lType One or more of the following:

  • NOANA_TYP
Do not analyze the selected files because they have already been analyzed by OpenTM2.
  • NOTM_TYP
Do not fill the internal Translation Memory (pszMemDB). Fill the external Translation Memory. It is in SGML format and you can check it afterwards.
  • PREPARE_TYP
The source documents are related to their corresponding translations. The file pairs are prefixed with p.

You can combine the options using OR.

Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession(&hSession);

  // Create a new Initial Translation Memory TestITM
  if ( !usRC )
  {
   usRC = EqfCreateITM(hSession, "TestITM",
                                 "E:\TM\PROJECT\ENFGLISH\original1,
                                  E:\TM\PROJECT\GERMAN\translation1",
                                 "EQFASCII", NULL,
                                 "English(U.S.)", "German(national)",
                                 "E:\TM\PROJECT", "E:\TM\PROJECT", 0);
  } //endif

  // terminate the session
  EqfEndSession( hSession );
}

EqfCreateMem

Purpose

EqfCreateMem creates a new shared or local Translation Memory.

Format

Chap21 Figure15.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszMemName The name of the Translation Memory to be created.
PSZ pszDescription The description of the Translation Memory.
CHAR chToDrive The target drive for the new Translation Memory. If omitted, the primary EQF drive is used. The drive must be the primary EQF drive or one of the secondary EQF drives defined in the “Configure Drives” window.
LONG lOptions The type of the new Translation Memory :

  • LOCAL_OPT, which is the default
  • SHARED_OPT
PSZ pszSourceLanguage The source language to be used for the Translation Memory.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Create the new local Translation Memory MEMDB2 on the
  // primary Eqf system drive
  if ( !usRC )
  {
   usRC = EqfCreateMem( hSession, "MEMDB2",
                        "TM created via Func I/F",
                        '\0', "English(U.S.)", LOCAL_OPT );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfCreateSubFolder

Purpose

EqfCreateSubFolder creates a subfolder from a parent folder by using the specified values. The parent folder itself can be a subfolder.

Format

Chap21 Figure16.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszParentFolName The name of the parent folder, or the name of a subfolder that acts as a parent folder.
PSZ pszSubFolName The name of the subfolder to be created.
PSZ pszMemName The name of the Translation Memory to be used for the documents in the new folder. If you want the same as in the parent folder, specify NULL .
PSZ pszMarkup The name of the markup table, for example EQFMRI. If you want the same as in the parent folder, specify NULL .
PSZ pszSourceLanguage The source language for the documents in this folder. Specify the language exactly as it appears in the “Language List” window, for exampleEnglish(U.S.) . If you want the same as in the parent folder, specify NULL .
PSZ pszTargetLanguage The target language for the documents in this folder. Specify the language exactly as it appears in the “Language List” window, for exampleEnglish(U.S.) . The target language must different from the source language. If you want the same as in the parent folder, specify NULL .
PSZ pszEditor The name of the editor. If not specified, the editor STANDARD is used.
PSZ pszConversion The export conversion type. If you want the same as in the parent folder, specify NULL .
PSZ pszTranslator The name of the translator. If you want the same as in the parent folder, specify NULL .
PSZ pszTranslatorMail The e-mail address of the translator. If you want the same as in the parent folder, specify NULL .
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession(&hSession);

  // Create a subfolder "SUBSUBTEST" of the parent folder "SUBTEST",
  // which itself is a subfolder of parent folder "TEST".

  if ( !usRC )
   {
    usRC = EqfCreateSubFolder(hSession,
                              "TEST\\SUBTEST", "SUBSUBTEST",
                              "MEM1", "EQFASCII",
                              "English(U.S.)",
                              "German(national)", NULL, NULL,
                              "Translator",
                              "Translator@xyz.com");
   } //endif

   // terminate the session
   EqfEndSession( hSession );
}

EqfDeleteDoc

Purpose

EqfDeleteDoc deletes the specified documents.

Format

Chap21 Figure17.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder containing the documents to be deleted.
PSZ pszDocuments The name of the documents to be deleted.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Delete document DOC1.TXT in folder SAMPLE1
  if ( !usRC )
  {
   usRC = EqfDeleteDoc( hSession, "SAMPLE1", "DOC1.TXT" );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfDeleteFolder

Purpose

EqfDeleteFolder deletes the specified folder and all the documents that it contains.

Format

Chap21 Figure18.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder to be deleted.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error cod (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Delete the folder SAMPLE1
  if ( !usRC )
  {
   usRC = EqfDeleteFolder( hSession, "SAMPLE1" );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfDeleteMem

Purpose

EqfDeleteMem deletes a Translation Memory.

Format

Chap21 Figure19.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszMemName The name of the Translation Memory to be deleted.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Delete the Translation Memory MEMDB2
  if ( !usRC )
  {
   usRC = EqfDeleteMem( hSession, "MEMDB2" );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfEndSession

Purpose

EqfEndSession terminates an EQF batch session and cleans up all resources used by the batch function.

Format

Chap21 Figure20.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). You cannot use EqfGetLastError to retrieve complete error information if a call to EqfEndSessionfailed.

EqfExportDict

Purpose

EqfExportDict exports a dictionary in SGML format to the specified file. It fails if the output file exists already unless the OVERWRITE_OPT has been set. Default encoding of output SGML dictionary is Unicode (UTF16). Specify the option ASCII_OPT or ANSI_OPT if the export dictionary should have the corresponding format.

This function performs the export in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure21.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszDictName The name of the dictionary to be exported.
LONG lOptions The option to be used for the export:

  • OVERWRITE_OPT
  • ASCII_OPT
  • ANSI_OPT
  • UTF16_OPT
PSZ pszOutFile The fully qualified name of the output file. If the output file exists already, specify the OVERWRITE_OPT option.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The dictionary export has not completed yet. Call EqfExportDict again.
other Error code (EQF mesasge number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Export the dictionary ENGLGERM to SGML file C:\DICT1.SGM
  // and overwrite any existing SGML file with this name
  if ( !usRC )
  {
   do
   {
    usRC = EqfExportDict( hSession, "ENGLGERM", OVERWRITE_OPT | UTF16_OPT
                          "C:\\DICT1.SGM" );
   } while ( usRC == CONTINUE_RC );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfExportDoc

Purpose

EqfExportDoc exports one or more documents.

This function performs the export in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure22.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder containing the documents to be exported.
PSZ pszStartPath The start path if the documents are to be exported with relative path information. If a start path is specified, the files in the list only contain the relative path.
PSZ pszFiles The name, including the target path, of the documents to be exported.
LONG lOptions The options to be used for the document export:

  • TARGET_OPT, which is the default
  • SOURCE_OPT
  • SNOMATCH_OPT
  • OVERWRITE_OPT to replace existing documents

These options correspond to those in the “Export Documents” window (see Exporting a document in external format).

Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The document export has not completed yet. Call EqfExportDoc again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Export the translations of documents DOC1.TXT and DOC2.TXT of
  // folder SAMPLE1
  if ( !usRC )
  {
   do
   {
    usRC = EqfExportDoc( hSession, "SAMPLE1", NULL,
                         "C:\\DOC1.TXT,C:\\DOC2.TXT",
                         TARGET_OPT );

   } while ( usRC == CONTINUE_RC );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfExportFolder

Purpose

EqfExportFolder exports a folder to a specific target drive. The path is always \eqf\export.

This function performs the export in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure23.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder to be exported.
PSZ pszDescription The folder description, or NULL .
CHAR chTargetDrive The drive to which the folder is exported.
LONG lOptions The options to be used for the export:

  • WITHMEM_OPT
  • WITHREADONLYMEM_OPT
  • WITHDOCMEM_OPT
  • DELETE_OPT
  • WITHDICT_OPT
  • MASTERFOLDER_OPT
  • XLIFF_OPT
  • OVERWRITE_OPT

These options correspond to those in the “Export Folder” window (see Exporting a folder).

You can combine the constants using OR.

PSZ pszDocuments The name of one or more documents.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The folder export has not completed yet. Call EqfExportFolder again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Export the folder SAMPLE1 to drive C: with the folder
  // Translation Memory and all folder dictionaries, overwrite
  // any previously exported folder on drive C:
  if ( !usRC )
  {
   do
   {
    usRC = EqfExportFolder( hSession, "SAMPLE1", 'C',
                            WITHMEM_OPT | WITHDICT_OPT | OVERWRITE_OPT,
                            NULL, NULL );
   } while ( usRC == CONTINUE_RC );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfExportFolderFP

Purpose

EqfExportFolderFP exports a folder to a specific path.

This function performs the export in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure24.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder to be exported.
PSZ pszDescription The folder description, or NULL .
PSZ pszTargetPath The path to which the folder is exported.
LONG lOptions The options to be used for the export:

  • WITHMEM_OPT
  • WITHREADONLYMEM_OPT
  • WITHDOCMEM_OPT
  • DELETE_OPT
  • WITHDICT_OPT
  • MASTERFOLDER_OPT
  • XLIFF_OPT
  • OVERWRITE_OPT

These options correspond to those in the “Export Folder” window (see Exporting a folder).

You can combine the constants using OR.

PSZ pszDocuments The name of one or more documents.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The folder export has not completed yet. Call EqfExportFolderFP again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Export the folder SAMPLE1 to path C:\PROJECT with the
  // folder Translation Memory and all folder dictionaries,
  // overwrite any previously exported folder in path C:\PROJECT
  if ( !usRC )
  {
   do
   {
    usRC = EqfExportFolderFP( hSession, "SAMPLE1",
                              'C:\PROJECT',
                              WITHMEM_OPT | WITHDICT_OPT | OVERWRITE_OPT,
                              NULL, NULL );
   } while ( usRC == CONTINUE_RC );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfExportFolderFPas

Purpose

EqfExportFolderFPas exports a folder to a specific path with the option to specify a new filename to the exported folder.

This function performs the export in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure25.gif

 

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder to be exported.
PSZ pszTargetPath The path to which the folder is exported.
PSZ pszExportAs The filename of the exported folder, or NULL .
LONG lOptions The options to be used for the export:

  • WITHMEM_OPT
  • WITHREADONLYMEM_OPT
  • WITHDOCMEM_OPT
  • DELETE_OPT
  • WITHDICT_OPT
  • OVERWRITE_OPT

These options correspond to those in the “Export Folder” window (see Exporting a folder).

You can combine the constants using OR.

PSZ pszDocuments The name of one or more documents.
PSZ pszDescription The folder description, or NULL .
PSZ pszMemoryExportAs The filename of the exported memory in the folder, or NULL .
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The folder export has not completed yet. Call EqfExportFolderFP again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Export the folder SAMPLE1 to path C:\PROJECT with the
  // folder Translation Memory and all folder dictionaries,
  // overwrite any previously exported folder in path C:\PROJECT
  // the folder memory is renamed to "MEM1"
  if ( !usRC )
  {
   do
   {
    usRC = EqfExportFolderFPas( hSession, "SAMPLE1",
                                'C:\PROJECT', "MyFoll",
                                WITHMEM_OPT | WITHDICT_OPT | OVERWRITE_OPT,
                                NULL, NULL, "MEM1" );
   } while ( usRC == CONTINUE_RC );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfExportMem

Purpose

EqfExportMem exports a Translation Memory in external format. This function performs the export in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure26.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszMemName The name of the Translation Memory to be exported.
PSZ pszInFile The fully qualified name of the file receiving the exported Translation Memory.
LONG lOptions The option to be used for the Translation Memory export:

  • OVERWRITE_OPT to replace an existing Translation Memory.
  • ANSI_OPT (Export in Ansi)
  • ASCII_OPT (Export in ASCII)
  • UTF16_OPT (Export in Unicode UTF-16)
  • TMX_UTF16_OPT (Export in TMX format, use UTF-16 encoding)
  • TMX_UTF8_OPT (Export in TMX format, use UTF-8 encoding)
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
559 (ERROR_MEM_ DATACORRUPT) The export completed successfully but some characters habe been corrupted (i.e. these characters cannot be re-converted to Unicode without loss of data)
CONTINUE_RC The Translation Memory export has not completed yet. Call EqfExportMem again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Export the Translation Memory MEMDB1 to the external file MEM1.EXP
  if ( !usRC )
  {
   do
   {
    usRC = EqfExportMem( hSession, "MEMDB1", "C:\\MEM1.EXP", 0L );
   } while ( usRC == CONTINUE_RC );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfFreeSegFile

Purpose

Releases the memory occupied by a file loaded into memory using EqfLoadSegFile.

Format

Chap21 Figure27.gif

Parameters
Type Parameter Description
HPARSESEGFILE hSegFile Handle of loaded segmented file.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HPARSSEGFILE *hSegFile = NULL;
  HSESSION hSession = 0L;
  PARSSEGMENTW Segment;

  // start the Eqf calling interface session
  usRC = EqfStartSession(&hSession);

  if ( !usRC )
  {
   usRC = EqfBuildSegDocName( hSession, "SAMPLE1", "Document1",
                              1, szFileName );
  } //endif

  if ( !usRC )
  {
   usRC = EqfLoadSegFile( hSession, szFileName, &hSegFile );
  if ( !usRC )
   {
    usRC = EqfGetSegW( hSegFile, 1, &Segment );
    if ( !usRC )
    {
     wcslwr( Segment.szData );
     usRC = EqfUpdateSegW( hSegFile, 1, &Segment );
     if ( !usRC )
     {
      usRC = EqfWriteSegFile( hSegFile, szFileName );
     } //endif
    } //endif
    EqfFreeSegFile(hSegFile );
   } //endif
  } //endif

  // terminate the session
  EqfEndSession( hSession );
}

EqfGetFolderProp

Purpose

EqfGetFolderProp retrieves the following properties of the specified folder or subfolder:

  • Target drive
  • Target language
  • Name of the read-write memory
  • List of read-only memories
  • List of dictionaries.
Format

Chap21 Figure28.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder.
PEXTFOLPROP pstructExtFolProp See Parameters for structExtFolProp for details.
Parameters for structExtFolProp
typedef struct _EXTFOLPROP
{
 CHAR chDrive;
 CHAR szTargetLang[MAX_LANG_LENGTH];
 CHAR szRWMemory[MAX_LONGFILESPEC];
 CHAR szROMemTbl[MAX_NUM_OF_READONLY_MDB][MAX_LONGFILESPEC];
 CHAR szDicTbl[ NUM_OF_FOLDER_DICS][MAX_FILESPEC];
} EXTFOLPROP, *PEXTFOLPROP;

 

Type Parameter Description
CHAR chDrive Returns the target drive of the folder.
CHAR szTargetLang [MAX_LANG_LENGTH] Returns the target language.
CHAR szRWMemory [MAX_LONGFILESPEC] Returns the read-write memory.
CHAR szROMemTbl [MAX_NUM_OF_READONLY_MDB] [MAX_LONGFILESPEC] Returns a list of read-only memories.
CHAR szDicTbl [NUM_OF_FOLDER_DICS] [MAX_FILESPEC] Returns the list of dictionaries.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;
  EXTFOLPROP FolderProps;

  // start the Eqf calling interface session
  usRC = EqfStartSession(&hSession);

  // Retrieve properties of Folder Test.
  if ( !usRC )
  {
   usRC = EqfGetFolderProp(hSession,"Test",&FolderProps);
  } //endif

  // terminate the session
  EqfEndSession( hSession );
}

EqfGetLastError

Purpose

EqfGetLastError receives the text of the last error message.

Format

Chap21 Figure29.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PUSHORT pusRc The OpenTM2 return code (message number).
PSZ pszMsgBuf An allocated area to receive the message text.
USHORT usBufSize The size of the preallocated buffer.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.

EqfGetMatchLevel

Purpose

The API call EqfGetMatchLevel computes the match level of the given proposal for the supplied segment. The segment data and the proposal is passed to the function using a EQFSEGINFO structure.

Format

Chap21 Figure30.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PEQFSEGINFO pSegment Pointer to an EQFSEGINFO structure containing the segment data.Note: The target part has not to be filled.
PEQFSEGINFO pProposal Pointer to an EQFSEGINFO structure containing the proposal data.
PSHORT psMatchLevel Pointer to a SHORT variable receiving the match level. The returned match level is in the range from 0 to 100.
PSHORT pMatchState Pointer to a SHORT variable receiving the match state.The returned match state can be:

  • REPLACE_MATCHSTATE for a replace match
  • FUZZYREPLACE_MATCHSTATE for a fuzzy replace matche
  • FUZZY_MATCHSTATE for a fuzzy matche
  • NONE_MATCH if theproposal is no match at all
  • EXACT_MATCHSTATE for an exact matche
  • EXACTEXACT_MATCHSTATE for an exact match coming from the same document and same segment.
LONG lOptions The options to be used for the function:

  • NO_GENERIC_INLINETAG_REPL_OPT if set the function “generic inline tag replacement” is not used
  • USE_GENERIC_INLINETAG_REPL_OPT if set the function “generic inline tag replacement” is always used

If none of these values is specified, the settings from the “System preferences” are used.

Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
EQFSEGINFO structure
Type Field Description
WCHAR [2048] szSource The proposal source in UTF-16 encoding
WCHAR [2048] szTarget The proposal target in UTF-16 encoding
LONG lSegNumber The segment number
CHAR [256] szDocument The name of the document
CHAR [20] szSourceLanguage The source language of the proposal
CHAR [20] szTargetLanguage The target language of the proposal
CHAR [13] szMarkup The name of the markup table
Code sample
 // the segment data from the document
EQFSEGINFO SegmentData =
{
 L"The <strong>IBM Websphere Translation Server</strong> performs automatic translations.",
 L"",
 1,
 "document.idd",
 "English(U.S.)",
 "German(DPAnat)",
 "IBMIDDOC"
};

// data for a fuzzy match
EQFSEGINFO FuzzyMatch =
{
 L"The <strong>IBM Websphere Translation Server</strong> does automatic translations.",
 L"Der <strong>IBM Websphere Translation Server</strong> macht automatische Uebersetzungen.",
 7,
 "anotherdoc.idd",
 "English(U.S.)",
 "German(DPAnat)",
 "IBMIDDOC"
};

{
 USHORT usRC = 0;
 HSESSION hSession = 0L;

 // start the Eqf calling interface session
 usRC = EqfStartSession( &hSession );

 // check the match level of the match in FuzzyMatch
 if ( !usRC )
 {
  SHORT sMatchLevel = 0;
  EQFMATCHSTATE MatchState;

  usRC = EqfGetMatchLevel( hSession, &SegmentData , &FuzzyMatch, &sMatchLevel, &MatchState, 0 );
 } /* endif */

 // terminate the session
 EqfEndSession( hSession );
}

EqfGetProgress

Purpose

GetProgress Get the progress of the currently performed function. The progress values returned are in the range from 0 to 100. This API call can only be used for nonDDE API processes which are called repeatedly until the function has been completed (e.g. EqfImportFolder).

Format

Chap21 Figure31.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PUSHORT pusProgress Address of a variable receiving the current progress value
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
{
 USHORT usRC = 0;
 HSESSION hSession = 0L;
 HSESSION hSession = 0L;

 // start the Eqf calling interface session
 usRC = EqfStartSession( &hSession );

 if ( !usRC )
 {
  do
  {
   usRC = EqfImportFolder( hSession, "SAMPLE1", 'C', '\0', WITHMEM_OPT );
   if ( usRC == CONTINUE_RC )
   {
    EqfGetProgress ( hSession, &usProgress );
   } //endif
  } while ( usRC == CONTINUE_RC );
 } // endif

 // terminate the session
 EqfEndSession( hSession );
}

EqfGetSegNum

Purpose

Get the number of segments contained in a segmented file loaded into memory using EqfLoadSegFile.

Format

Chap21 Figure32.gif

Parameters
Type Parameter Description
HPARSESEGFILE hSegFile Handle of loaded segment file
PLONG pISegNum Pointer to a buffer receiving the number of segments in the loaded file.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
{
 USHORT usRC = 0;
 HPARSSEGFILE *hSegFile = NULL;
 HSESSION hSession = 0L;
 LONG lNumberOfSegments = 0;

 // start the Eqf calling interface session
 usRC = EqfStartSession(&hSession);

 if ( !usRC )
 {
  usRC = EqfBuildSegDocName( hSession, "SAMPLE1", "Document1",
                             1, szFileName );
  } //endif

 if ( !usRC )
 {
  usRC = EqfLoadSegFile( hSession, szFileName, &hSegFile );
  if ( !usRC )
  { 
   usRC = EqfGetSegNum( hSegFile, &lNumberOfSegments);
   EqfFreeSegFile(hSegFile );
  } //endif
 } //endif

 // terminate the session
 EqfEndSession( hSession );
}

EqfGetSegW

Purpose

GetSegW Get the data of a specific segment from a segmented file loaded into memory using EqfLoadSegFile.

Format

Chap21 Figure33.gif

Parameters
Type Parameter Description
HPARSESEGFILE hSegFile Handle of loaded segment file
LONG ISegNum Number of segment being rereived
PPARSESEGMENTW pSeg Pointer to structure receiving the segment data
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
{
 USHORT usRC = 0;
 HPARSSEGFILE *hSegFile = NULL;
 HSESSION hSession = 0L;
 PARSSEGMENTW Segment;

 // start the Eqf calling interface session
 usRC = EqfStartSession(&hSession);

 if ( !usRC )
 {
  usRC = EqfBuildSegDocName( hSession, "SAMPLE1", "Document1",
                             1, szFileName );
 } //endif

 if ( !usRC )
 {
  usRC = EqfLoadSegFile( hSession, szFileName, &hSegFile );
  if ( !usRC )
  {
   usRC = EqfGetSegW( hSegFile, 1, &Segment );
   if ( !usRC )
   {
    wcslwr( Segment.szData );
    usRC = EqfUpdateSegW( hSegFile, 1, &Segment );
    if ( !usRC )
    {
     usRC = EqfWriteSegFile( hSegFile, szFileName );
    } //endif
   } //endif
    EqfFreeSegFile(hSegFile );
  } //endif
 } //endif

 // terminate the session
 EqfEndSession( hSession );
}

EqfGetSegmentNumber

Purpose

EqfGetSegmentNumber computes the number of the segment to which the character at the given line and column position belongs to.

Format

Chap21 Figure34.gif

Parameters
Type Parameter Description
HPARSESEGFILE hSegFile The handle of a segmented file as returned by function EqfLoadSegFile.
LONG ILine Number of the line for which the segment number is requested
LONG IColumn Column position of the segment within the line
PLONG plSeg Pointer to a LONG buffer which reveives the segment number matching the line and column number
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
10009 (NOMATCHINGSEGMENT_RC) There is no segment with the given position (either the line number or the column number is out of range)
10008 (INVALIDFILEHANDLE_RC) The file handle hSegFile is invalid
other Error code (EQF message number). Use EqfGetLastError to retrieve complete error information.

EqfGetSourceLine

Purpose

EqfGetSourceLine computes the start line and the end line of the given segment based on the linefeeds contained in the document.

Format

Chap21 Figure35.gif

Parameters
Type Parameter Description
HPARSESEGFILE hSegFile The handle of a segmented file as returned by function EqfLoadSegFile.
LONG ISeg Number of segment for which the source line information is requested
PLONG plStartLine Pointer to a LONG buffer which receives the starting line number of the segment
PLONG plEndLine Pointer to a LONG buffer which receives the end line number of the segment
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
10006 (SEGMENTISJOINED_RC) The given segment is joined to a previous segment is not visible in the document
10007 (INVALIDSEGMENT_RC) The given segment number is invalid or out of range
10008 (INVALIDFILEHANDLE_RC) The file handle hSegFile is invalid
other Error code (EQF message number). Use EqfGetLastError to retrieve complete error information

EqfGetSysLanguage

Purpose

EqfGetSys Language allows to retrieve the currently active default target language of OpenTM2.

Format

Chap21 Figure36.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszSystemLanguage Buffer provided to contain the system language string at output. The length of the buffer has to be at least 20 characters.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;
  CHAR chSystemLanguage[20];

  // start the Eqf calling interface session
  usRC = EqfStartSession( hSession );

  // get the system language
  if ( !usRC )
  {
   usRC = EqfGetSysLanguage( hSession, chSystemLanguage );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
 }

EqfGetVersion

Purpose

EqfGetVersion retrieves the version info of OpenTM2.

Format

Chap21 Figure37.gif

Parameters

—none —

Return code

ULONG

Value Description
ulVersion The version of OpenTM2 in a byte array, see the code sample for details how to access the version info.
Code sample
 #include <stdlib.h>
 #include "eqf_api.h"

  int main( int argc, char *argv[], char *envp[] )
 {
  BYTE abVersion[4];
  ULONG ulVersion = EQFGETVERSION();

  memcpy( abVersion, &ulVersion, sizeof(ULONG) );

  printf( "TM Version %d\n", (short)abVersion[0] );
  printf( "TM Release %d\n", (short)abVersion[1] );
  printf( "TM Subrelease %d\n", (short)abVersion[2] );
  printf( "TM Build %d\n", (short)abVersion[3] );
 } /* end of main */

EqfImportDoc

Purpose

EqfImportDoc imports one or more documents and sets the document properties to the specified values. The specified values apply to all documents to be imported. If a document needs different settings, for example a different markup, import it separately.

This function performs the import in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure38.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder receiving the documents.
PSZ pszStartPath The start path if the documents are to be imported with relative path information. If a start path is specified, the files in the list only contain the relative path.
PSZ pszFiles The fully qualified name of the documents to be imported.
PSZ pszTransMem The name of the Translation Memory to be used for the document, if different from that of the folder.
PSZ pszMarkup The name of the markup table to be used for the document, if different from that of the folder.
PSZ pszEditor The name of the editor to be used for the document, if different from that of the folder.
PSZ pszSourceLanguage The name of the source language to be used for the document, if different from that of the folder.
PSZ pszTargetLanguage The name of the target language to be used for the document, if different from that of the folder.
PSZ pszAlias The alias name for the document.
LONG lOptions The option to be used for the document import: OVERWRITE_OPT to replace existing documents.
PSZ pszConversion Conversion to be used for document or NULL
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The document import has not completed yet. Call EqfImportDoc again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Import the documents DOC1.TXT and DOC2.TXT into folder SAMPLE1
  // and overwrite any existing documents, the format of the documents
  // is to EQFASCII for all other settings the folder settings will be
  // used
  if ( !usRC )
  {
   do
   {
    usRC = EqfImportDoc( hSession, "SAMPLE1", NULL,
                         "C:\\DOC1.TXT,C:\\DOC2.TXT",
                         NULL, "EQFASCII", NULL, NULL, NULL, NULL,
                         OVERWRITE_OPT );
   } while ( usRC == CONTINUE_RC );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfImportDict

Purpose

EqfImportDict imports a dictionary in SGML dictionary.

This function performs the import in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure39.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszInFile The fully qualified name of the SGML file to be imported.
PSZ psDictName The name of the dictionary to be exported.
PSZ pszPassword The dictionary password. Only required if the dictionary exists already and is protected.
LONG lOptions The options to be used for the merge of entries during the import:

  • IGNORE_OPT
  • REPLACE_OPT
  • COMBINE_OPT
  • ASCII_OPT
  • ANSI_OPT
  • UTF16_OPT
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The dictionary import has not completed yet. Call EqfImportDict again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Import the SGML file C:\DICT1.SGM into dictionary ENGLGERM
  // and replace existing entries with the imported data
  if ( !usRC )
  {
   do
   {
    usRC = EqfImportDict( hSession, "C:\\DICT1.SGN",
                          "ENGLGERM", NULL, REPLACE_OPT )
   } while ( usRC == CONTINUE_RC );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfImportFolder

Purpose

EqfImportFolder imports a folder from a specific drive to the specified OpenTM2 drive. The path from which the folder is imported is always \eqf\export.

This function performs the import in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

[Image:Chap21_Figure40.gif]]

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder to be imported.
CHAR chFromDrive The drive from which the folder is exported.
CHAR chToDrive The target drive for the imported folder. If omitted, the primary EQF drive is used. The drive must be the primary EQF drive or one of the secondary EQF drives defined in the “Configure Drives” window.
LONG lOptions The options to be used for the export:

  • WITHMEM_OPT
  • WITHDICT_OPT
  • XLIFF_OPT

These options correspond to those in the “Import Folder” window (see Importing a folder).

You can combine the constants using OR.

Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The folder import has not completed yet. Call EqfImportFolder again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Import the folder SAMPLE1 from drive C: to the primary Eqf
  // system drive, import the folder with Translation Memory databases
  // and dictionaries
  if ( !usRC )
  {
   do
   {
    usRC = EqfImportFolder( hSession, "SAMPLE1", 'C',
                            '\0', // use primary Eqf drive
                            WITHDICT_OPT | WITHMEM_OPT );
   } while ( usRC == CONTINUE_RC );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfImportFolderFP

Purpose

EqfImportFolderFP imports a folder from a specific path to the specified OpenTM2 drive.

This function performs the import in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure41.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszFolderName The name of the folder to be imported.
PSZ pszFromPath The path from which the folder is exported.
CHAR chToDrive The target drive for the imported folder. If omitted, the primary EQF drive is used. The drive must be the primary EQF drive or one of the secondary EQF drives defined in the “Configure Drives” window.
LONG lOptions The options to be used for the export:

  • WITHMEM_OPT
  • WITHDICT_OPT
  • XLIFF_OPT

These options correspond to those in the “Import Folder” window (see Importing a folder).

You can combine the constants using OR.

Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The folder import has not completed yet. Call EqfImportFolderFP again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Import the folder SAMPLE1 from path C:\PROJECT to the primary
  // Eqf system drive, import the folder with Translation Memory
  // databases and dictionaries
  if ( !usRC )
  {
   do
   {
    usRC = EqfImportFolderFP( hSession, "SAMPLE1", 'C:\PROJECT',
                              '\0', // use primary Eqf drive
                              WITHDICT_OPT | WITHMEM_OPT );
   } while ( usRC == CONTINUE_RC );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfImportMem

Purpose

EqfImportMem imports a Translation Memory into OpenTM2. This function performs the import in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure42.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszMemName The name of the Translation Memory to be imported. If a Translation Memory with this name already exists, the imported data is merged into the existing Translation Memory.
PSZ pszInFile The fully qualified name of the file containing the Translation Memory data.
LONG lOptions The options to be used for the Translation Memory import:

  • ANSI_OPT (Export/Import in Ansi)
  • ASCII_OPT (Export/Import in ASCII)
  • UTF16_OPT (Export/Import in Unicode UTF-16)
  • TMX_OPT (Import in TMX format)
  • CLEANRTF_OPT can be used together with the TMX_OPT to remove RTF tags from the imported data
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The Translation Memory import has not completed yet. Call EqfImportMem again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // Import the external Translation Memory MEM1.EXP into Translation
  // Memory MEMDB1
  if ( !usRC )
  {
   do
   {
    usRC = EqfImportMem( hSession, "MEMDB1", "C:\\MEM1.EXP", 0L );
   } while ( usRC == CONTINUE_RC );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfLoadSegFile

Purpose

Loads a segmented OpenTM2 document file into memory. The segments of the loaded file can be accessed using the EqfGetSegW API.

Format

Chap21 Figure43.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszMemName Fully qualified file name
HPARSESEGFILE * hSegFile Points to the buffer receiving the handle of the loaded segmented file
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HPARSSEGFILE *hSegFile = NULL;
  HSESSION hSession = 0L;
  PARSSEGMENTW Segment;

  // start the Eqf calling interface session
  usRC = EqfStartSession(&hSession);

  if ( !usRC )
  {
   usRC = EqfBuildSegDocName( hSession, "SAMPLE1", "Document1",
                              1, szFileName );
  } //endif

  if ( !usRC )
  {
   usRC = EqfLoadSegFile( hSession, szFileName, &hSegFile );
   if ( !usRC )
   {
    usRC = EqfGetSegW( hSegFile, 1, &Segment );
    if ( !usRC )
    {
     wcslwr( Segment.szData );
     usRC = EqfUpdateSegW( hSegFile, 1, &Segment );
     if ( !usRC )
     {
      usRC = EqfWriteSegFile( hSegFile, szFileName );
     } //endif
    } //endif
    EqfFreeSegFile(hSegFile );
   } //endif
  } //endif

  // terminate the session
  EqfEndSession( hSession );
}

EqfOrganizeMem

Purpose

EqfOrganizeMem organizes the specified Translation Memory. This function performs the organization in small units. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure44.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszMemName The name of the Translation Memory to be organized.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The organization of the Translation Memory has not completed yet. Call EqfOrganizeMemagain.
other Error code (EQF message number). Use EqfGetLastError To retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // organize the Translation Memory MEMDB1
  if ( !usRC )
  {
   do
   {
    usRC = EqfOrganizeMem( hSession, "MEMDB1" );
   } while ( usRC == CONTINUE_RC );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfProcessNomatch

Purpose

The API call EqfProcessNomatch reads one or more SNOMATCH files (created using the analysis option “Create file containing untranslated segments”) and looks up the segments contained in the SNOMATCH files in the input memory. Each matching proposal (exact and fuzzy match) is written to the output memory. The API call creates a memory match word count and a duplicate word count for the segments in the SNOMATCH files. The word count reports can be created in text and XML form.

This function performs the processing in small units unless told to complete in one call using the COMPLETE_IN_ONE_CALL_OPT flag. Call it repetitively until it returns a return code other than CONTINUE_RC.

Format

Chap21 Figure45.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszNomatch The specification for the SNOMATCH files to use for the processing. This parameter is evaluated in the following way:

  • the specified value contains wildcard characters
the specified value is used as fully qualified search pattern for the SNOMATCH FILES to be used e.g. “C:\EQF\TEST.F00\SNOMATCH\A*.*”
  • the specified value contains path delimiters
the specified value is used as fully qualified name of the SNOMATCH file to process, if the specified value points to a directory all files in the directory are processed e.g. “C:\EQF\TEST.F00\SNOMATCH\File1.txt”, “C:\EQF\TEST.F00\SNOMATCH”
  • the value contains no path delimiters
the specified value is used as name of a TM folder, all SNOMATCH files contained in the SNOMATCH directory of this folder are processed e.g. “TEST”
PSZ pszInMemory The name of the input memory (TM internal)
PSZ pszOutMemory The name of an existing or new internal memory receiving the relevant proposals from the input memory
PSZ pszMemMatchReportText The fully qualified name for the memory match word count report in text format, specify NULL if no report of this type should be created
PSZ pszMemMatchReportXml The fully qualified name for the memory match word count report in XML format, specify NULL if no report of this type should be created
PSZ pszDupReportText The fully qualified name for the duplicate word count report in text format, specify NULL if no report of this type should be created
PSZ pszDupReportXml The fully qualified name for the duplicate word count report in XML format, specify NULL if no report of this type should be created
LONG lOptions The option(s) to be used for the processing:

  • COMPLETE_IN_ONE_CALL_OPT
If set the API call does not return after each processing step but stays in the API call until the function has been completed
  • RESPECTCRLF_OPT
If set memory proposals having different linebreaks are not used as exact match

The options can be combined by using the logical OR operator

Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
CONTINUE_RC The SNOMATCH processing is not complete yet. Call EqfProcessNomatch again.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error code.
Code sample
HSESSION hSession;
USHORT usRC;

usRC = EqfStartSession( &hSession );
usRC = EqfProcessNomatch( hSession, "TestFolder",
            "PrevMemory", "NewMemory", NULL,
            "C:\Reports\MemMatch.XML", NULL,
            "C:\Reports\Dups.XML, COMPLETE_IN_ONE_CALL_OPT);
usRC = EqfEndSession( hSession );

The API EqfProcessNomatch is called to process all SNOMATCH files of folder “TestFolder”, the segments are looked up ion the memory “PrevMemory” and any relevant matches found are written to the memory “NewMemory”, the memory match count in XML format will be stored under “C:\Reports\MemMatch.XML” and the XML duplicate word count will be stored under“C:\Reports\Dups.XML”, the text versions of the reports are not being used. The API call will complete in one call.

EqfRename

Purpose

EqfRename renames a folder, a dictionary or a Translation Memory.

Format

Chap21 Figure46.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
USHORT usMode Descibes the type of object being renamed, valid are RENAME_FOLDER, RENAME_MEMORY or RENAME_DICTIONARY
PSZ pszOldName The name of the existing folder, dictionary or Translation Memory.
PSZ pszNewName The new name for the folder, dictionary or Translation Memory.
LONG lOptions Additional options for the rename function:

  • ADJUSTREFERENCES_OPT to adjust all references to the rename object (valid only for the rename of a Translation Memory)
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  // rename the Translation Memory MyMemory to MyNewMemory and adjust all references
  if ( !usRC )
  {
   usRC = EqfRename( hSession, RENAME_MEMORY, "MyMemory",
                     "MyNewMemory", ADJUSTREFERENCES_OPT );
  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
}

EqfSetSysLanguage

Purpose

EqfSetSysLanguage sets the default target language for the OpenTM2 system environment. All OpenTM2 internal character conversions (Unicode to ASCII/ANSI, ASCII/ANSI to Unicode) and linguistic functions will use the provided default target language if no other language settings are available.

This happens e.g. during Translation Memory import/export in ASCII. It is a good coding practice to retrieve the default target language first (EqfGetSysLanguage), set the requested default target language, do your processing and reset the default target language to the previously stored value. Using the EqfSetSysLanguage has the same effect as modifying the Default Target Language on the System Preferenece Dialog via the GUI.

Format

Chap21 Figure47.gif

Parameters
Type Parameter Description
HSESSION hSession The EQF session handle, as returned by EqfStartSession.
PSZ pszSystemLanguage Buffer provided to contain the system language string. The length of the buffer has to be at least 20 characters.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HSESSION hSession = 0L;

  // start the Eqf calling interface session
  usRC = EqfStartSession( hSession );

  // Set the default target language to be Japanese
  if ( !usRC )
  {
   usRC = EqfSetSysLanaguage( hSession, "Japanese" );

  } /* endif */

  // terminate the session
  EqfEndSession( hSession );
 }

EqfStartSession

Purpose

EqfStartSession prepares the internal data areas for other non-DDE batch function calls. Call it before any other batch function. After you are finished, call the EqfEndSession function to clean up all resources.

Format

Chap21 Figure48.gif

Parameters
Type Parameter Description
HSESSION hSession The variable receiving the EQF session handle.
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). You cannot use EqfGetLastError to retrieve complete error information if a call to EqfStartSessionfailed.

EqfUpdateSegW

Purpose

Update the segment data of a specific segment in a segmented file loaded into memory using EqfLoadSegFile.

Format

Chap21 Figure49.gif

Parameters
Type Parameter Description
HPARSESEGFILE hSegFile Handle of loaded segmented file
LONG lSegNum Number of segment being updated
PPARSESEGMENTW pSeg Pointer to structure containing the updated segment data
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HPARSSEGFILE *hSegFile = NULL;
  HSESSION hSession = 0L;
  PARSSEGMENTW Segment;

  // start the Eqf calling interface session
  usRC = EqfStartSession( &hSession );

  if ( !usRC )
  {
   usRC = EqfBuildSegDocName( hSession, "SAMPLE1", "Document1",
                              1, szFileName );
  } /* endif */

  if ( !usRC )
  {
   usRC = EqfLoadSegFile( hSession, szFileName, &hSegFile );
   if ( !usRC )
   {
    usRC = EqfGetSegW( hSegFile, 1, &Segment );
    if ( !usRC )
    {
     wcslwr( Segment.szData );
     usRC = EqfUpdateSegW( hSegFile, 1, &Segment );
     if ( !usRC )
     {
      usRC = EqfWriteSegFile( hSegFile, szFileName );
     } //endif
    } //endif
    EqfFreeSegFile(hSegFile );
   } //endif
  } //endif

  // terminate the session
  EqfEndSession( hSession );
}

EqfWriteSegFile

Purpose

Writes a segmented file loaded into memory using EqfLoadSegFile back to disk.

Format

Chap21 Figure50.gif

Parameters
Type Parameter Description
HPARSESEGFILE hSegFile Handle of loaded segmented file
PSZ pszFileName Fully qualified file name
Return code

USHORT

Value Description
0 (NO_ERROR) The function completed successfully.
other Error code (EQF message number). Use EqfGetLastError to retrieve the complete error information.
Code sample
 {
  USHORT usRC = 0;
  HPARSSEGFILE *hSegFile = NULL;
  HSESSION hSession = 0L;
  PARSSEGMENTW Segment;

  // start the Eqf calling interface session
  usRC = EqfStartSession(&hSession);

  if ( !usRC )
  {
   usRC = EqfBuildSegDocName( hSession, "SAMPLE1", "Document1",
                              1, szFileName );
  } //endif

  if ( !usRC )
  {
   usRC = EqfLoadSegFile( hSession, szFileName, &hSegFile );
   if ( !usRC )
   {
    usRC = EqfGetSegW( hSegFile, 1, &Segment );
    if ( !usRC )
    {
     wcslwr( Segment.szData );
     usRC = EqfUpdateSegW( hSegFile, 1, &Segment );
     if ( !usRC )
     {
      usRC = EqfWriteSegFile( hSegFile, szFileName );
     } //endif
    } //endif
    EqfFreeSegFile(hSegFile );
   } //endif
  } //endif

  // terminate the session
  EqfEndSession( hSession );
}