Using the C API

Keep the following guidelines in mind when you begin to write Simulink® Real-Time™ C API programs with the Simulink Real-Time C API DLL:

  • Carefully match the function data types as documented in the function reference. For C, the API includes a header file that matches the data types.

  • You can call the API functions from non-C languages, such as C++ and Java®. Refer to the compiler documentation of the non-C language for a description of how to access C functions from a library DLL. To access the Simulink Real-Time C API DLL, follow these directions.

  • You can work with real-time applications with either MATLAB® or a Simulink Real-Time C API control application. However, only one control application can access the target computer at a time. To move from the MATLAB session to your application, in the MATLAB Command Window, type:

    close(slrt)

    This command frees the connection to the target computer for use by your Simulink Real-Time C API application. Conversely, to access the target from a MATLAB session, you must quit your control application, or do the equivalent of calling the function xPCClosePort.

  • The Simulink Real-Time C API functions that communicate with the target computer check for timeouts during communication. If the TCP/IP connection times out, they exit with the global variable xPCError set to ETCPTIMEOUT. Use the xPCGetLoadTimeOut and xPCSetLoadTimeOut functions to get and set the timeout values, respectively.

A few things that are common to almost all the functions in the Simulink Real-Time C API are not covered in the reference topics for the individual functions.

  • Almost every function (except xPCOpenTcpIpPort, xPCGetLastError, and xPCErrorMsg) has as one of its parameters the integer variable port. xPCOpenTcpIpPort returns this variable to represent the communications link with the target computer.

  • Almost every function (except xPCGetLastError and xPCErrorMsg) sets a global error value when an error occurs. The application obtains this value by calling the function xPCGetLastError, and retrieves a descriptive character string about the error by using the function xPCErrorMsg. The actual error values are subject to change. However, a zero value typically means that the operation completed without producing an error, while a nonzero value typically signifies an error condition. The library resets the error value every time an API function is called; therefore, check the error status as soon as possible after a function call.

    Some functions also use their return values (if applicable) to signify that an error has occurred. In these cases as well, you can obtain the exact error with xPCGetLastError.