DDEML transactions

All Content Manager OnDemand commands are DDEML XTYP_REQUEST transactions.

Some cause an operation to be performed; some return additional data; and all provide a return code.

The DDEML DdeClientTransaction function is used to initiate the transaction. The DDEML item name string contains the command and concatenated parameters. The syntax is the same as the command line with the DDE command replacing the executable name.

The DDEML DdeClientTransaction function returns a data handle containing a return code, and optionally, additional data. The return code is a set of ASCII digits representing one of the values described for the individual commands. These ASCII digits are always followed by a single space character. If additional data is present, it is a null-terminated character string beginning at the character immediately following the space character.

The following example describes a C function that executes Content Manager OnDemand DDE commands and receives return information. All the examples for the individual Content Manager OnDemand DDE commands are based on this C function example. 
 /* Global Variables */
 DWORD DdeInstance;
 HCONV hDdeConv;

 #define ERROR_MAP struct _ErrorMap
 ERROR_MAP
 {
   int    code;
   char * pMsg;
 };

 static ERROR_MAP Errors[] =
   { { ARS_DDE_RC_UNKNOWN_COMMAND,      "Unknown command." },
     { ARS_DDE_RC_PARM_NOT_SPECIFIED,   "Parameter not specified." },
     { ARS_DDE_RC_INVALID_PARM_VALUE,   "Invalid parameter value." },
     { ARS_DDE_RC_SERVER_ERROR,         "Server error." },
     { ARS_DDE_RC_FILE_ERROR,           "File error." },
     { ARS_DDE_RC_NOT_LOGGED_ON,        "Not logged on." },
     { ARS_DDE_RC_MAX_FOLDERS_OPEN,     "Maximum folders open." },
     { ARS_DDE_RC_FOLDER_NOT_OPEN,      "Folder not open." },
     { ARS_DDE_RC_NO_DOC,               "No document exists." },
     { ARS_DDE_RC_OPEN_DOCS,            "Documents are open." } };
 #define NUM_ERRORS  ( sizeof(Errors) / sizeof(ERROR_MAP) )

     .
     .
     .
 BOOL DoDdeCommand( char * pCmd,    /* -> Command string           */
                    char * pParms,  /* -> Command parameters       */
                    char * pData )  /* -> Buffer for returned data */
 {
   HSZ hDdeString;
   HDDEDATA hDdeResult;
   DWORD data_len;
   char * pString;
   int j, rc;

   /* Add parameters to command line. */
   if ( pParms == NULL )
     pParms = "";
   pString = malloc( strlen( pCmd ) + strlen( pParms ) + 2 );
   strcpy( pString, pCmd ):
   strcat( pString, " " );
   strcat( pString, pParms );

   /* Perform Content Manager OnDemand DDE command. */
   hDdeString = DdeCreateStringHandle( DdeInstance, pCmd, 0 );
   hDdeResult = DdeClientTransaction( NULL,
                                      0,
                                      hDdeConv,
                                      hDdeString1,
                                      CF_TEXT,
                                      type,
                                      10000L,
                                      NULL );
   DdeFreeStringHandle( DdeInstance, hDdeString );
   free( pString);
   /* Process command result. */
   if ( hDdeResult == NULL )
   {
     /* This should never happen. */
     MESSAGE( "DDE Timeout." );
     return FALSE;
   }
   else
     {
     pString = (char*)DdeAccessData( hDdeResult, &data_len );
     rc = atoi( pString );
     if ( rc == ARS_DDE_RC_NO_ERROR )
     {
       if ( pData != NULL )
       strcpy( pData, strchr( pString, ' ' ) + 1 );
     }
     else
     {
      if ( pData != NULL )
        pData[0] = '\0';
      for ( j = 0; j < NUM_ERRORS; j++ )
        if ( Errors[j].code == rc )
          break;
      MESSAGE( j < NUM_ERRORS ? Errors[j].pMsg : "Error - invalid return code." );
     }
     DdeUnaccessData( hDdeResult );
     return rc == ARS_DDE_RC_NO_ERROR;
   }
 }