Use case: INCO procedure with asynchronous part

INOS code

The following INCO function (MoveXAxis) "just" puts a message into the tasks message queue. Later, when the message will be 'dispatched' by the task, it'll actually perform an axis Move (iMoveXAxis). The function does not return any results (except the INOS_MCMSG_CODE_MYMODULE_MOVEXAXIS_FAILED application error in case the move fails).

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

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

void CMyModule::iMoveXAxis(CINOSTaskExMsg* apMsg)
{
    real64 rAxisPosition = apMsg->GetParam<real64>();
    ...
    // move axis and wait until move finishs
    if( pAxis->Move(rAxisPosition, DF_INOS_SYNCHRONOUS) == 0 ) {
        // success
        MsgDone(apMsg);
    } else {
        MsgDone(apMsg, CINOSTaskEx::eRplError, INOS_MCMSG_CODE_MYMODULE_MOVEXAXIS_FAILED);
    }
}

PC code

Correct usage

• Standard case: Start move, wait until the move finishes and check whether it succeeded or failed.

  uint32 uError = CallProcedureExSync("TargetName", "PathToProcedure.MoveXAxis(0.1234:d)");
  // once this line is reached, the move has finished (either successful or with an error)
  if( uError != ER_INCO_NO_ERROR ) {
      // handle the error
  } 

  Another (sligthly more complicated) solution:

  int32 iTicketOrError = CallProcedureEx("TargetName", "PathToProcedure.MoveXAxis(0.1234:d)");
  
  ... // do whatever you want
  
  if( iTicketOrError < 0 ) {
      // ok, it's a ticket (not an error)
      uint32 uError = CallProcedureExResult("TargetName", iTicketOrError);
      if( uError != ER_INCO_NO_ERROR ) {
          // handle the error
      } 
  }

  Another possiblity to do the same (but even more complicated):

  int32 iTicketOrError = CallProcedureEx("TargetName", "PathToProcedure.MoveXAxis(0.1234:d)");
  
  ... // do whatever you want
  
  // Make sure the 'async part' has completed
  uint32 uError = CallProcedureExWait("TargetName", iTicketOrError);
  if( uError == ER_INCO_NO_ERROR ) {
      // the move finished. But we do not yet know whether it finished successful or not.
  
      ... // do whatever you want
  
      // finally, check whether the move succeeded or failed (by getting any application error):
      uError = CallProcedureExResult("TargetName", iTicketOrError);
      if( uError != ER_INCO_NO_ERROR ) {
          // Either getting the result failed (INCO error), or moving the axis failed (application error).
          ...
      }
  }

• Start move and check whether moving the axis succeeded or failed - wait for the result using a timeout:

  int32 uTimeoutMs = 5000; // timeout: 5s
  int32 iTicketOrError = CallProcedureEx("TargetName", "PathToProcedure.MoveXAxis(0.1234:d)");
  if( iTicketOrError < 0 ) {
      // ok, it's a ticket (not an error). Wait for the completion of the asyncronous part with timeout
      uint32 uError = CallProcedureExWait("TargetName", iTicketOrError, uTimeoutMs);
      if( uError == ER_INCO_NO_ERROR ) {
          // great, async part finished. Check whether a failure happened (by getting any application error):
          uError = CallProcedureExResult("TargetName", iTicketOrError);
          if( uError != ER_INCO_NO_ERROR ) {
              // Either getting the result failed (INCO error) or moving the axis failed (application error).
              ...
          }
      }
      else 
      {
          // The axis move did not finish within 5 seconds.
      }
  }

Strange (but valid) usage

• Start move and wait until finished (or failed) - but don't check whether the move succeeded or failed:

  int32 iTicketOrError = CallProcedureEx("TargetName", "PathToProcedure.MoveXAxis(0.1234:d)");
  if( iTicketOrError < 0 ) {
      // Wait for the 'async part' to complete.
      uint32 uError = CallProcedureExWait("TargetName", iTicketOrError);
      if( uError == ER_INCO_NO_ERROR ) { 
          // waiting succeeded. This means that the 'async part' has 
          // completed - but we do not know whether the move actually 
          // succeeded or failed.
      }
  } else {
      // error occurred!
  } 

  This use case is considered to be strange because the application should normally be interested in handling errors. Moreover, if the application really doesn't care about errors, MoveXAxis() should better be implemented to not return a ticket by changing the return type to 'void'. Like this it'd obvious that the function is just "fire'n'forget". When too many calls like this are done, the results that were sent by the target but never picked up by the application accumulate in libinco_32 and will eventually fill up the buffer used to store them. When that happens, to avoid unbounded memory usage, libinco_32 will start to drop the oldest stored results to make space for new ones when they arrive. This is accompanied by a warning printed to stderr.
• Start move but don't wait for any result (fire'n'forget):

  int32 iTicketOrError = CallProcedureEx("TargetName", "PathToProcedure.MoveXAxis(0.1234:d)");
  if( iTicketOrError > 0 ) {
      // error occurred!
  }

  This use case is considered to be strange because the application should normally be interested in handling errors. Moreover, if the application really doesn't care about errors, MoveXAxis() should better be implemented to not return a ticket by changing the return type to 'void'. Like this it'd obvious that the function is just "fire'n'forget". When too many calls like this are done, the results that were sent by the target but never picked up by the application accumulate in libinco_32 and will eventually fill up the buffer used to store them. When that happens, to avoid unbounded memory usage, libinco_32 will start to drop the oldest stored results to make space for new ones when they arrive. This is accompanied by a warning printed to stderr.
• Waiting multiple times for the same async procedure:

  int32 iTicketOrError = CallProcedureEx("TargetName", "PathToProcedure.MoveXAxis(0.1234:d)");
  if( iTicketOrError < 0 ) {
      uint32 uError;
      uError = CallProcedureExWait("TargetName", iTicketOrError);
      
      ... // do whatever (except chaning the value of iTicketOrError)
      
      uError = CallProcedureExWait("TargetName", iTicketOrError);
      
  } else {
      // error occurred!
  } 

  The code above waits twice for the same procedure to have finished it's asynchronous part. Doing so is not forbidden (but probably doesn't makes any sense either).

Forbidden/invalid usage

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

  int32 iTicketOrError = CallProcedureEx("TargetName", "PathToProcedure.MoveXAxis(0.1234:d)");
  if( iTicketOrError < 0 ) {
      // ok, it's a ticket (not an error)
      uint32 uError;
      uError = CallProcedureExResult("TargetName", iTicketOrError);
  
      // ===> BAD IDEA: uError will for sure be set because result 
      //                (namely: the apperror) has already been get
      uError = CallProcedureExResult("TargetName", iTicketOrError); 
  }