DDEML トランザクション

どの Content Manager OnDemand コマンドも DDEML XTYP_REQUEST トランザクションです。

コマンドによっては、操作が実行されたり、追加データが戻されたりします。また、どのコマンドでも、戻りコードが提供されます。

トランザクションを開始するには、DDEML DdeClientTransaction 関数を使用します。DDEML 項目名ストリングには、コマンドと連結パラメーターが含まれます。その構文は、実行可能名を置換する DDE コマンドのコマンド行と同じです。

DDEML DdeClientTransaction 関数は、戻りコードを含むデータ・ハンドルを戻し、オプションにより追加データも戻します。その戻りコードは、個々のコマンドについて記述されたいずれかの値を表す一連の ASCII 数字です。これらの ASCII 数字のあとには、必ず、1 つのスペース文字が続いています。追加データがある場合、このデータは、ヌル終了文字ストリングであり、スペース文字の直後の文字で始まります。

Content Manager OnDemand DDE コマンドを実行してリターン情報を受け取る C 関数について、以下の例で説明します。個々の Content Manager OnDemand DDE コマンドについての例はすべて、この C 関数の例をベースにしています。

 /* 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;
   }
 }