|
<< Click to Display Table of Contents >> Navigation: References > Developing with Concordance |
DDE stands for Dynamic Data Exchange. It allows two applications to communicate through programmed commands in the Windows environment. It is not a simple interface and it should only be used by experienced programmers.
Any parameters used in communicating with Concordance are referenced by name. Commands tell Concordance to do something, or they send or receive data.
The examples given here are provided for the C programming language. There are four types of DDE commands that Concordance will recognize. The first command establishes the link between your program and Concordance. This is referred to as opening a DDE conversation.
All DDE conversations are established by connecting to the DDE server, Concordance. Establishing the conversation requires your program to provide two parameters: the service and the topic. The service is the name of the DDE server, in this case Concordance. The topic is defined by the service and it varies from server to server. Concordance supports database names as topics. The database topic should use the full file path in either standard or UNC format. Concordance opens the database specified as the topic for use in the DDE conversation. Use an asterisk, *, as the topic to open the conversation using any database currently open and in use by an end-user. You can close that database later and open another using the DDE Execute commands.
Example
The following example is written in C. It opens a DDE conversation with a Concordance server. The OpenConcordanceDDE() function receives two parameters: the instance identifier and the database name. The instance identifier, idInst, is a value returned by DdeInitialize() when your program performed the required DDE initialization. The pszDatabase parameter is a pointer to a zero terminated string containing the name of a database to open, or NULL to open the DDE conversation based on the currently open database, i.e., using * as the topic.
HCONV OpenConcordanceDDE( DWORD idInst, char *pszDatabase)
{
HSZ hszService, // Name of service to connect.
hszTopic; // Topic of conversation.
HCONV hConv; // Handle to DDE conversation.
// Set the handle to a NULL value.
hConv = NULL;
// Use the database name if provided, otherwise
// use * if no database is specified, this will
// open the DDE conversation using the current
// database being viewed by the end-user.
if (pszDatabase == NULL)
pszDatabase = "*";
// Create the service’s string handle.
hszService = DdeCreateStringHandle(idInst, "Concordance", CP_WINANSI);
// Create the topic’s string handle.
hszTopic = DdeCreateStringHandle(idInst, pszDatabase, CP_WINANSI);
// Connect to the service, Concordance.
hConv = DdeConnect( idInst, hszService, hszTopic, (PCONVCONTEXT)NULL);
// Free the DDE string handles.
DdeFreeStringHandle(idInst, hszService);
DdeFreeStringHandle(idInst, hszTopic);
// Return the handle to this DDE conversation.
// The handle is required for all further
// communication with the Concordance DDE server.
return(hConv);
}
Once a DDE conversation has been established, all further communication between your program and Concordance takes place through the Microsoft Windows’ DdeClientTransaction() function. The DdeClientTransaction() function has eight parameters:
DdeClientTransaction( void *lpvData, DWORD cbData, HCONV hConv, HSZ hszItem, UINT uFmt, UINT uType, UINT uTimeout, DWORD *lpuResult);
Execute commands request Concordance to perform actions. These include moving between records, performing a search, appending and deleting records, and opening and closing databases. These commands return success codes, but they do not return data. Several commands contain two parts: the command and the command parameter. For instance, opening a database also requires the name of the database you want to open. The command is sent as the single string open drive:path\filename.dcb.
DdeClientTransaction() Parameters
Execute commands use two DdeClientTransaction() parameters, lpvData and cbData. lpvData is a pointer to the command string. This may simply be the command string in quotes. cbData is the number of bytes in the command string, lpvData, including the terminating zero. For instance, strlen(lpvData) + 1.
Returns
The XTYP_EXECUTE commands return DDE_FACK, DDE_FBUSY, or DDE_FNOTPROCESSED. DDE_FACK and DDE_FBUSY are returned to indicate success or TRUE and failure or FALSE. For instance, the lock command returns DDE_FACK if the record was successfully locked and DDE_FBUSY if it could not be locked, i.e., someone else already has it locked.
DDE_FNOTPROCESSED is only returned if the command is not recognized, usually due to a misspelling, or if the database is not open. The return codes are defined in the Windows ddeml.h include file, provided with your compiler.
EXECUTE Commands |
||
|---|---|---|
Command |
Parameter |
Function |
append
|
|
Appends the current record to the end of the database. This is generally used with blank, to create a new record. For E-documents databases created using Concordance version 10.21 and later, this function is disabled. To append a document to an E-documents database, drag the document onto the database. |
blank |
|
Creates a blank record. If the current record has been edited, it is automatically saved before being blanked. Use blank records with the append command to add records to the database. |
browse |
|
Brings up the Browse screen. |
close |
|
Closes Concordance. This also terminates the DDE conversation. |
closedatabase |
|
Closes the current database. |
closealldatabases |
|
Closes all open databases. |
first |
|
Retrieves the first record in the query. |
goto |
FIELD = VALUE |
This performs a search for the record whose field exactly matches the value. The search is not limited to the current query set, it looks throughout the database. Wildcards and Boolean logic are not allowed in the query. The field must be a key field. The matching record is retrieved, but a new query is not incremented. |
|
Record number |
Moves to any record in the current set of retrieved records. |
gotoreference |
/d=database /k=key /o=offset /l=length |
This opens a specific database specified by database, goes to a key (the replication key) specified by key, and highlights a range of characters specified by the offset and length. database is the full path to the database.dcb file. key is the replication key. offset is the offset in characters to start highlighting from. length is the number of characters to highlight. |
isdeleted |
|
Checks if the record is marked for deletion. |
isedited |
|
Checks if the record has been edited since last indexed or reindexed. |
last |
|
Moves to the last record in the current set. |
lock |
|
Locks the current record so that you can edit it. |
next |
|
Moves to the next record. |
open |
Database path. |
Opens a database. |
pgdn |
|
Moves to the next record for Browse or Table views. It is not necessary to send a repaint command after a pgdn. |
pgup |
|
Moves to the previous record for Browse or Table views. It is not necessary to send a repaint command after a pgup. |
prev |
|
Moves to the previous record. |
repaint |
|
Updates the Browse or Table display. Use this if your program changes the contents of the displayed record, or moves to another record. |
search |
Search string. |
Executes a search. |
unlock |
|
Unlocks the record. |
setfocus |
|
Concordance sets focus to itself. This is equivalent to the Windows SetFocus() function. |
table |
|
Places Concordance into Table view. |
zap |
|
The database is zapped. Every record in the database is erased and permanently deleted. |
DDE request commands return data values. This group of Concordance DDE commands returns information about the database, such as a list of fields or the database’s name, as well as the field contents.
DdeClientTransaction() Parameters
hszItem is a string handle created with DdeCreateStringHandle() and it contains the command string in CP_WINANSI format. Use the CF_TEXT format for field names when retrieving data from the database fields. Field names must be in all upper case. Set uFmt to either CP_WINANSI or CF_TEXT as appropriate.
Returns
XTYP_REQUEST commands return an HDDEDATA value containing the requested information. Use DdeGetData() to both obtain the length of the data and to copy it to local memory. Note that the data may not be terminated with a zero. Allocate one extra byte to your buffer before you copy the returned data. Null terminate the string yourself.
Numeric fields are returned as text strings. Date fields are returned in YYYYMMDD format.
REQUEST Commands |
|
|---|---|
Command |
Data Returned |
Database status |
This command returns information about the database in eight lines of text, delimited with carriage returns and line feeds. Each line contains a number indicating: •Records in the database •Fields in the database •Needs reindexing •Current physical record number •Current record number in the query •Active query number •Records in the query •Total queries |
Database name |
The full path and file name of the database. |
List of Fields |
A list of fields in the database. Each field is on a line terminated with a carriage return and a line feed. The field name is followed by six items indicating: •The field type: P, N, D, or T. •The field’s length. •The decimal places, applies to numeric fields. •A Y(es) or N(o) to indicate if it is a key field. •A Y(es) or N(o) to indicate if it is an image field. |
Image field |
The contents of the image field, if an image field has been defined, otherwise NULL is returned. |
Total count |
A string containing the count of all records in the database, including any concatenated databases. |
Query count |
A string containing the number of records in the current query. |
FIELD |
The contents of the named field. |
DDE Poke commands send data to a Concordance field. The new data replaces any data already in the field. Data on the end-user’s screen is not updated unless you send a repaint message.
DdeClientTransaction() Parameters
hszItem is a string handle created with DdeCreateStringHandle() and it contains the name of the field that will receive the data. You must set uFmt to CF_TEXT and use the CF_TEXT format to create hszItem. lpvData points to the data for the field, and cbData is the length of the data in bytes, i.e., strlen(lpvData). The data does not need to be a zero terminated string.
All data is sent as text strings, including values for numeric fields. Data destined for a date field must be in YYYYMMDD format, without slashes or any punctuation. For instance, 19991231 is valid but 31/12/1999 is invalid.
Returns
DDE_FACK if the data was accepted. DDE_FNOTPROCESSED is returned if the command failed because:
•the field was not found
•the data format was not CF_TEXT
•the database isn't open
•you do not have sufficient security rights to change the field’s contents
DDE_FBUSY is returned if the record is not locked and Concordance could not lock it to complete the command.