Use case: INCO procedure with asynchronous part returning named results

INOS code

In addition to the use cases presented in Use case: INCO procedure with asynchronous part returning results, this page shows how to return 'named results'. 'Named results' is a feature that allows INOS code to return values to a caller (e.g. an HMI) by adding a string/name to it. Especially in case that a function returns multiple results, this feature offers some useful possibilities:

• There's no need for the caller to know the order of results (e.g. 1st results: "axis state", 2nd results: "axis position", etc.)
• As a consequence, the INOS code can change the order of results at any time
• The INOS code may add new results (e.g. "axis error state")
• The INOS code may remove existing results (e.g. "axis position") - if the caller code was programmed error safe

This page focus on the named results, therefore it assumes the reader has already studied the use cases here: Use case: INCO procedure with asynchronous part returning results.

The examples below assume the following code running on the target:

CMcResult CMyModule::MoveXAxisReturnTargetPosition(double arAxisPosition)
{
    CINOSTaskExMsg* msg = new CINOSTaskExMsg(eMsgCmd, CmdMoveXAxisReturnTargetPosition, apSync);
    msg->AddParam(arAxisPosition);  
    return PutMsg(msg);
}

//------------------------------------------------------------------------------

void CMyModule::iMoveXAxisReturnTargetPosition(CINOSTaskExMsg* apMsg)
{
    real64 rAxisPosition = apMsg->GetParam<real64>();
    ...
    // move axis and wait until move finishs
    if( pAxis->Move(rAxisPosition, DF_INOS_SYNCHRONOUS) == 0 ) {
        // increase move counter
        ++m_MoveCounter;
        // Success. Return various results to the caller. For the sake of 
        // demonstration we mix named and unnamed results:
        apMsg->AddResult(m_MoveCounter); // unnamed
        apMsg->AddResult(pAxis->GetState(), "AxisState"); // named
        apMsg->AddResult(pAxis->GetType());
        apMsg->AddResult(pAxis->GetError(), "AxisError");
        apMsg->AddResult(pAxis->GetActPosition());
        // mark the 'async part' as completed:
        MsgDone(apMsg);
    } else {
        MsgDone(apMsg, CINOSTaskEx::eRplError, INOS_MCMSG_CODE_MYMODULE_MOVEXAXISRETURNTARGETPOSITION_FAILED);
    }
}

The function does not return any results (except application errors of course).

PC code

Correct usage

• Get the results by order:

  int32 iTicketOrError = CallProcedureEx("TargetName", "PathToProcedure.MoveAxisReturnTargetPosition(0.1234:d)");
  if( iTicketOrError < 0 ) {
      // get the result (and thereby implicitely wait for the async part of the procedure to finish):
      uint32 uMoveCounter;
      uint32 uError = CallProcedureExResult("TargetName", iTicketOrError, &uMoveCounter, sizeof(uMoveCounter), DF_INCO_TYPE_UINT32);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  
      uint32 uAxisState;
      uError = CallProcedureExResult("TargetName", iTicketOrError, &uAxisState, sizeof(uAxisState), DF_INCO_TYPE_UINT32);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  
      char cAxisType[256];
      uError = CallProcedureExResult("TargetName", iTicketOrError, &cAxisType, sizeof(cAxisType), DF_INCO_TYPE_STRING);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  
      uint32 uAxisError;  
      uError = CallProcedureExResult("TargetName", iTicketOrError, &uAxisError, sizeof(uAxisError), DF_INCO_TYPE_UINT32);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  
      double dTargetPosition;
      uError = CallProcedureExResult("TargetName", iTicketOrError, &dTargetPosition, sizeof(dTargetPosition), DF_INCO_TYPE_DOUBLE);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  }

• Get the named results first, followed by the unnamed results:

  int32 iTicketOrError = CallProcedureEx("TargetName", "PathToProcedure.MoveAxisReturnTargetPosition(0.1234:d)");
  if( iTicketOrError < 0 ) {
      uint32 uAxisState;
      // get the result (and thereby implicitely wait for the async part of the procedure to finish):
      uint32 uError = CallProcedureExResultByName("TargetName", iTicketOrError, "AxisState", 
          &uAxisState, sizeof(uAxisState), DF_INCO_TYPE_UINT32);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  
      uint32 uAxisError;  
      uError = CallProcedureExResultByName("TargetName", iTicketOrError, "AxisError", 
          &uAxisError, sizeof(uAxisError), DF_INCO_TYPE_UINT32);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  
      uint32 uMoveCounter;
      uError = CallProcedureExResult("TargetName", iTicketOrError, &uMoveCounter, sizeof(uMoveCounter), DF_INCO_TYPE_UINT32);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  
      char cAxisType[256];
      uError = CallProcedureExResult("TargetName", iTicketOrError, &cAxisType, sizeof(cAxisType), DF_INCO_TYPE_STRING);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  
      double dTargetPosition;
      uError = CallProcedureExResult("TargetName", iTicketOrError, &dTargetPosition, sizeof(dTargetPosition), DF_INCO_TYPE_DOUBLE);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  }

• Get the results and their names by order:

  int32 iTicketOrError = CallProcedureEx("TargetName", "PathToProcedure.MoveAxisReturnTargetPosition(0.1234:d)");
  if( iTicketOrError < 0 ) {
      char cResultName[256];
      
      // get the result (and thereby implicitely wait for the async part of the procedure to finish):
      uint32 uMoveCounter;
      uint32 uError = CallProcedureExResult("TargetName", iTicketOrError, &uMoveCounter, sizeof(uMoveCounter), DF_INCO_TYPE_UINT32, 
          cResultName, sizeof(cResultName));
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
      cout << "Result name: " << cResultName << endl;
  
      uint32 uAxisState;
      uError = CallProcedureExResult("TargetName", iTicketOrError, &uAxisState, sizeof(uAxisState), DF_INCO_TYPE_UINT32,
          cResultName, sizeof(cResultName));
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
      cout << "Result name: " << cResultName << endl;
  
      char cAxisType[256];
      uError = CallProcedureExResult("TargetName", iTicketOrError, &cAxisType, sizeof(cAxisType), DF_INCO_TYPE_STRING,
          cResultName, sizeof(cResultName));
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
      cout << "Result name: " << cResultName << endl;
  
      uint32 uAxisError;  
      uError = CallProcedureExResult("TargetName", iTicketOrError, &uAxisError, sizeof(uAxisError), DF_INCO_TYPE_UINT32,
          cResultName, sizeof(cResultName));
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
      cout << "Result name: " << cResultName << endl;
  
      double dTargetPosition;
      uError = CallProcedureExResult("TargetName", iTicketOrError, &dTargetPosition, sizeof(dTargetPosition), DF_INCO_TYPE_DOUBLE,
          cResultName, sizeof(cResultName));
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
      cout << "Result name: " << cResultName << endl;
  }

Forbidden/invalid usage

• It's not possible to get the same result multiple times. Therefore, in the following use case, the final call to CallProcedureExResultByName will for sure return an error:

  int32 iTicketOrError = CallProcedureEx("TargetName", "PathToProcedure.MoveAxisReturnTargetPosition(0.1234:d)");
  if( iTicketOrError < 0 ) {
      // get the result (and thereby implicitely wait for the async part of the procedure to finish):
      uint32 uMoveCounter;
      uint32 uError = CallProcedureExResult("TargetName", iTicketOrError, &uMoveCounter, sizeof(uMoveCounter), DF_INCO_TYPE_UINT32);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  
      uint32 uAxisState;
      uError = CallProcedureExResult("TargetName", iTicketOrError, &uAxisState, sizeof(uAxisState), DF_INCO_TYPE_UINT32);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  
      char cAxisType[256];
      uError = CallProcedureExResult("TargetName", iTicketOrError, &cAxisType, sizeof(cAxisType), DF_INCO_TYPE_STRING);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  
      uint32 uAxisError;  
      uError = CallProcedureExResult("TargetName", iTicketOrError, &uAxisError, sizeof(uAxisError), DF_INCO_TYPE_UINT32);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  
      double dTargetPosition;
      uError = CallProcedureExResult("TargetName", iTicketOrError, &dTargetPosition, sizeof(dTargetPosition), DF_INCO_TYPE_DOUBLE);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  
      // ==> BAD IDEA: a result can be get only once! uError will be set.
      uint32 uAxisError2;
      uError = CallProcedureExResultByName("TargetName", iTicketOrError, "uAxisError", &uAxisError2, sizeof(uAxisError2), DF_INCO_TYPE_UINT32);
      if( uError != ER_INCO_NO_ERROR ) { /* do error handling */ }
  }