*mydirectindustry

Catalogs
The MathWorks
C and Fortran API Reference

C and Fortran API Reference

Product catalog summary

Contact Information: The document provides contact details for The MathWorks, including web resources, newsgroups, and email addresses for technical support, product suggestions, bug reports, documentation errors, sales, and general inquiries. Phone and fax numbers are also provided.

License and Copyright: The software is licensed and cannot be copied or reproduced without consent. Specific provisions apply to U.S. federal government acquisitions.

Trademarks and Patents: MATLAB and Simulink are registered trademarks. The document references patents protecting MathWorks products.

Revision History: The document has undergone multiple revisions from December 1996 to March 2008, reflecting updates for various MATLAB releases.

API Reference Overview: The document is structured into sections detailing the API reference for MAT-File Access, MX Array Manipulation, MEX-Files, and MATLAB Engine. Each section provides functions and their descriptions for interfacing MATLAB with C and Fortran.

MAT-File Access: Functions for opening, closing, reading, and writing MAT-files are detailed, allowing integration of MATLAB data in C and Fortran programs.

MX Array Manipulation: This section covers creating, manipulating, and querying MATLAB arrays from C and Fortran, including functions for memory management and data type conversions.

MEX-Files: Functions for executing operations within the MATLAB environment from C and Fortran MEX-files are described, including error handling and workspace variable management.

MATLAB Engine: The document outlines how to call MATLAB software from C and Fortran programs, facilitating integration and automation of MATLAB tasks.

Overview: This document provides a comprehensive reference for using the MATLAB Engine API in C and Fortran. It includes functions for managing MATLAB engine sessions, evaluating expressions, and handling variables within the MATLAB workspace.

Key Sections:

Engine Session Management: Functions like engOpen, engClose, and engOpenSingleUse are used to start and terminate MATLAB engine sessions. engOpen starts a MATLAB process and returns an engine handle, while engClose terminates the session. engOpenSingleUse is specific to Windows and allows for single, nonshared use.
Expression Evaluation: The engEvalString function evaluates expressions within the MATLAB engine session. It communicates with MATLAB using pipes on UNIX systems and COM interfaces on Windows.
Variable Management: Functions like engPutVariable and engGetVariable manage variables in the MATLAB workspace. engPutVariable writes an mxArray to the engine, while engGetVariable retrieves it.
Visibility Control: engSetVisible and engGetVisible manage the visibility of the MATLAB engine session on Windows, allowing user interaction to be enabled or disabled.
Output Buffering: engOutputBuffer specifies a buffer for MATLAB output, allowing the capture of output that would typically appear on the screen.

Examples: The document references example programs such as engdemo.c and engwindemo.c for C, and fengdemo.F for Fortran, which illustrate the use of these functions on different operating systems.

Important Notes: The document highlights differences in implementation between UNIX and Windows systems, particularly in how engine sessions are started and managed.

MAT-File Operations in C and Fortran

1. matClose Function
This function is used to close a MAT-file associated with a given pointer. It returns EOF in C (-1 in Fortran) for a write error, and 0 if successful. Examples can be found in the eng_mat subdirectory.

2. matDeleteVariable Function
This function deletes a named mxArray from a MAT-file. It returns 0 if successful, and nonzero otherwise. Examples are available in the eng_mat subdirectory.

3. MATFile Type
This is a handle to a MAT-file object used for reading and writing MAT-files. The header file is #include "mat.h". Examples are provided in the eng_mat directory.

4. matGetDir Function
This function retrieves the directory of mxArrays in a MAT-file. It returns a pointer to an internal array containing pointers to the names of the mxArrays. If it fails, it returns NULL in C (0 in Fortran).

5. matGetFp Function
This function obtains a C file handle to a MAT-file, useful for using standard C library routines to investigate error situations.

6. matGetNextVariable Function
This function reads the next mxArray from a MAT-file. It returns a pointer to a newly allocated mxArray structure. The order of variables returned is not guaranteed to be the same as the order in which they were written.

7. matGetNextVariableInfo Function
This function loads only the array header information for the next mxArray from a MAT-file. It should not be passed back to the MATLAB workspace or saved to MAT-files.

8. matGetVariable Function
This function copies an mxArray out of a MAT-file. It returns a pointer to a newly allocated mxArray structure.

9. matGetVariableInfo Function
This function loads only the array header information for a specified mxArray from a MAT-file.

10. matOpen Function
This function opens a MAT-file for reading and writing. It supports various modes such as reading, updating, writing, and creating files in different formats.

11. matPutVariable Function
This function writes an mxArray to a MAT-file. If the mxArray does not exist, it is appended; if it exists, it is replaced.

12. matPutVariableAsGlobal Function
This function is similar to matPutVariable but places the array into the global workspace when loaded by MATLAB.

13. mexAtExit Function
This function registers a function to be called just before a MEX-function is cleared or MATLAB software is terminated, allowing for tasks such as freeing memory and closing files.

Overview: This document provides technical details on various MEX-file functions used in MATLAB, focusing on their purpose, syntax, arguments, and behavior. It covers functions related to error handling, memory management, and interaction with MATLAB's workspace.

1. MEX-file Exit Functions:
Each MEX-function can register one active exit function using mexAtExit. If called multiple times, the most recent function is used. Locked MEX-files cannot be cleared, and their exit functions are not called.

2. mexCallMATLAB:
This function allows calling MATLAB functions or MEX-files from within a MEX-file. It requires specifying the number of input and output arguments and the function name. It returns 0 on success and a nonzero value on failure.

3. Error Handling Functions:

mexErrMsgIdAndTxt: Issues an error message with an identifier and returns control to MATLAB. It automatically frees allocated memory.
mexErrMsgTxt: Similar to the previous function but without an identifier.

4. mexEvalString:
Executes a MATLAB command in the caller's workspace. It does not return values to the MEX-file, unlike mexCallMATLAB.

5. mexFunction:
The entry point for C MEX-files. It handles input and output arguments and is mandatory for every MEX-file.

6. mexFunctionName:
Returns the name of the current MEX-function.

7. mexGet and mexSet:

mexGet: Retrieves the value of a specified Handle Graphics property.
mexSet: Sets a graphics property value.

8. mexGetVariable and mexGetVariablePtr:

mexGetVariable: Copies a variable from a specified workspace.
mexGetVariablePtr: Provides a read-only pointer to a variable in another workspace.

9. mexIsGlobal:
Determines if an mxArray has global scope.

10. mexIsLocked and mexLock:

mexIsLocked: Checks if a MEX-file is locked.
mexLock: Prevents a MEX-file from being cleared from memory.

11. mexMakeArrayPersistent:
Makes an mxArray persist after the MEX-file completes, preventing automatic memory deallocation.

Overview: This document provides technical guidance on using various MEX-file functions in MATLAB, focusing on memory management, error handling, and data manipulation. It includes detailed descriptions of functions such as mexMakeArrayPersistent, mexPrintf, mexPutVariable, and others, along with their syntax, arguments, and usage examples.

Memory Management: The document emphasizes the importance of managing memory when working with MEX-files. Functions like mexMakeArrayPersistent and mexMakeMemoryPersistent are used to make memory allocated by MATLAB persist after a MEX-function completes. Users are responsible for freeing persistent memory using mxDestroyArray or mxFree to prevent memory leaks.

Error Handling: Functions such as mexSetTrapFlag allow users to control MATLAB's response to errors in mexCallMATLAB. By setting a trap flag, users can decide whether MATLAB should terminate the MEX-file or return control to the MEX-file for error handling.

Data Manipulation: The document describes how to manipulate MATLAB data using mxArray and related functions. mxArrayToString converts an array to a C-style string, while mxAddField adds fields to structure arrays. These functions facilitate data exchange between MATLAB and MEX-files.

Output and Messaging: mexPrintf is used for displaying messages, similar to the C printf function, while mexWarnMsgIdAndTxt and mexWarnMsgTxt issue warning messages without terminating the MEX-file.

Examples and References: The document provides examples and references to additional resources for each function, aiding users in understanding and implementing the described functionalities effectively.

Overview: This document provides technical details on various MATLAB functions and procedures related to memory management, data handling, and debugging in C and Fortran environments. It includes descriptions of functions like mxAssert, mxCalcSingleSubscript, mxCalloc, and others, which are used for debugging, memory allocation, and data manipulation in MATLAB MEX-files.

1. Debugging Functions:

mxAssert: Used for checking assertion values during debugging. It prints an error message if the assertion fails and is disabled in optimized MEX-files.
mxAssertS: Similar to mxAssert but does not print the assertion text, only the error message.

2. Memory Management:

mxCalloc: Allocates dynamic memory using MATLAB's memory manager. It initializes memory to zero and registers it with the memory manager. In MEX-files, it automatically deallocates memory when the MEX-file ends unless made persistent.

3. Data Handling:

mxCalcSingleSubscript: Calculates the offset from the first element to a desired element in an mxArray. It uses zero-based indexing in C and one-based in Fortran.
mxCopyCharacterToPtr: Copies character values from a Fortran array to a pointer array in MATLAB.
mxCopyComplex16ToPtr and mxCopyComplex8ToPtr: Copy complex values from Fortran arrays to MATLAB pointer arrays, essential for compilers that do not support certain constructs.

4. Data Types and Classes:

mxChar: Represents string mxArray data elements as mxChar instead of char.
mxClassID: Enumerates the class of an mxArray, identifying how data is represented (e.g., mxDOUBLE_CLASS, mxINT8_CLASS).
mxComplexity: Specifies whether an mxArray has imaginary components, using flags mxREAL or mxCOMPLEX.

5. Fortran Specific Functions:

mxCopyInteger1ToPtr and mxCopyInteger2ToPtr: Copy integer values from Fortran arrays to MATLAB pointer arrays, facilitating data transfer between Fortran and MATLAB.

Conclusion: The document provides essential functions and procedures for efficient memory management, debugging, and data handling in MATLAB, particularly for those developing MEX-files in C and Fortran. It emphasizes the importance of using MATLAB's built-in functions for memory allocation and data manipulation to ensure compatibility and efficiency.

Overview: This document provides technical details on various Fortran subroutines used for copying data between Fortran arrays and MATLAB arrays. These subroutines are essential for interfacing Fortran code with MATLAB, especially when the Fortran compiler does not support the %VAL construct.

Key Sections:

Data Copying Subroutines: The document describes several subroutines for copying different data types between Fortran and MATLAB arrays. These include:

mxCopyInteger2ToPtr and mxCopyPtrToInteger2: For copying INTEGER*2 values.
mxCopyInteger4ToPtr and mxCopyPtrToInteger4: For copying INTEGER*4 values.
mxCopyPtrToCharacter: For copying character values.
mxCopyPtrToComplex16 and mxCopyPtrToComplex8: For copying complex numbers of different precisions.
mxCopyPtrToReal4 and mxCopyPtrToReal8: For copying real numbers of different precisions.

Array Creation Functions: Functions like mxCreateCellArray and mxCreateCellMatrix are used to create unpopulated cell arrays in MATLAB. These functions specify the dimensions and initialize the arrays.
String Handling: Functions such as mxCreateCharArray and mxCreateCharMatrixFromStrings are used for creating string arrays in MATLAB, either unpopulated or populated with strings.

Critical Information:

These subroutines are crucial for setting up standard Fortran arrays for passing as arguments to the computation routine of a MEX-file.
Examples are provided in the document to illustrate the usage of these subroutines in Fortran programs.
Common issues such as insufficient heap space are noted as potential causes for failure when creating arrays.

Recommendations: Users should ensure that their Fortran compilers are compatible with these subroutines and should refer to the provided examples for guidance on implementation.

Overview: This document provides technical specifications and usage guidelines for various MATLAB functions used to create different types of mxArrays in C and Fortran. These functions are essential for handling data structures in MATLAB, particularly when interfacing with C and Fortran code.

1. mxCreateCharMatrixFromStrings:

This function creates a two-dimensional string mxArray, where each row is initialized to a string from the input array. In C, the dimensions are m-by-max, where max is the length of the longest string. In Fortran, dimensions are m-by-n, where n is the number of characters in each string. The function returns a pointer to the created mxArray or NULL if unsuccessful due to insufficient heap space or fewer strings than expected.

2. mxCreateDoubleMatrix:

This function creates a 2-D, double-precision, floating-point mxArray initialized to zero. It requires specifying the number of rows (m), columns (n), and whether the data is real or complex (ComplexFlag). The function returns a pointer to the created mxArray or NULL if unsuccessful due to insufficient heap space.

3. mxCreateDoubleScalar:

This function creates a scalar, double-precision mxArray initialized to a specified value. It is a convenience function that simplifies the creation of a 1x1 double matrix. The function returns a pointer to the created mxArray or NULL if unsuccessful.

4. mxCreateLogicalArray:

This function creates an N-dimensional logical mxArray initialized to false. It automatically sets the number of dimensions to 2 if ndim is less than 2. The function returns a pointer to the created mxArray or NULL if unsuccessful due to insufficient heap space.

5. mxCreateLogicalMatrix:

This function creates a 2-D logical mxArray initialized to false. It is similar to mxCreateLogicalArray but limited to two dimensions. The function returns a pointer to the created mxArray or NULL if unsuccessful.

6. mxCreateLogicalScalar:

This function creates a scalar logical mxArray initialized to a specified logical value. It is a convenience function for creating a 1x1 logical matrix. The function returns a pointer to the created mxArray or NULL if unsuccessful.

7. mxCreateNumericArray:

This function creates an unpopulated N-D numeric mxArray. It requires specifying the number of dimensions (ndim), dimensions array (dims), class identifier (classid), and whether the data is real or complex (ComplexFlag). The function returns a pointer to the created mxArray or NULL if unsuccessful.

8. mxCreateNumericMatrix:

This function creates a numeric matrix and initializes data elements to zero. It requires specifying the number of rows (m), columns (n), class identifier (classid), and whether the data is real or complex (ComplexFlag). The function returns a pointer to the created mxArray or NULL if unsuccessful.

9. mxCreateSparse:

This function creates a 2-D unpopulated sparse mxArray. It requires specifying the number of rows (m), columns (n), and the maximum number of non-zero elements (nzmax). The function returns a pointer to the created mxArray or NULL if unsuccessful.

Conclusion: These functions are crucial for creating and managing different types of mxArrays in MATLAB, especially when integrating with C and Fortran code. Proper understanding and usage of these functions can significantly enhance the efficiency and capability of MATLAB applications.

Overview: The document provides detailed technical information on various functions used in C and Fortran for creating and managing mxArray structures in MATLAB. These functions are essential for handling different types of data structures, including sparse arrays, logical matrices, strings, and structures.

1. mxCreateSparse: This function is used to create an unpopulated sparse double mxArray. It requires specifying whether the array will contain imaginary data using the ComplexFlag. The function allocates space for pr, pi, ir, and jc arrays, and returns a pointer to the created mxArray or NULL if unsuccessful due to insufficient heap space.

2. mxCreateSparseLogicalMatrix: This function creates a sparse logical mxArray initialized to logical 0. It returns a pointer to the created mxArray or NULL if unsuccessful. The function is used to allocate space for logical data in a sparse format.

3. mxCreateString: This function creates a 1-by-N string mxArray initialized to a specified string. It returns a pointer to the created string mxArray or NULL if there is insufficient heap space. The function is useful for initializing string arrays required by various MATLAB functions.

4. mxCreateStructArray and mxCreateStructMatrix: These functions create unpopulated structure mxArrays. mxCreateStructArray can handle N-D structures, while mxCreateStructMatrix is limited to 2-D structures. Both functions require specifying the number of fields and their names, and they return a pointer to the created structure mxArray or NULL if unsuccessful.

5. mxDestroyArray: This function frees the dynamic memory allocated by mxCreate* functions. It deallocates the memory occupied by the mxArray and its associated data arrays, ensuring proper memory management.

6. mxDuplicateArray: This function creates a deep copy of an mxArray, copying all levels of data. It returns a pointer to the copied array, allowing for safe manipulation of data without altering the original array.

7. mxFree: This function deallocates heap space allocated by mxCalloc, mxMalloc, or mxRealloc. It ensures correct memory management and is essential for freeing memory parcels, especially in MEX-files.

8. mxGetCell and mxGetChars: mxGetCell retrieves the contents of a cell mxArray, while mxGetChars provides a pointer to character array data. Both functions are crucial for accessing specific data within mxArrays.

9. mxGetClassID and mxGetClassName: These functions determine the class of an mxArray, either as a numeric identifier or a string. They are useful for identifying the type of data an mxArray holds.

10. mxGetData: This function retrieves a pointer to the data within an mxArray, allowing for direct access and manipulation of the array's contents.

Conclusion: The document serves as a comprehensive guide for developers working with MATLAB's C and Fortran APIs, providing essential functions for creating, managing, and manipulating mxArray structures efficiently.

Overview: This document provides technical details on various functions used in C and Fortran for handling MATLAB mxArray structures. It covers functions for accessing data, dimensions, element sizes, and field values within these structures.

1. mxGetData:

Purpose: Returns the address of the first element of the real data in an mxArray.
Returns NULL if there is no real data.
Usage: Similar to mxGetPr but returns a void pointer in C.
Example: Refer to phonebook.c in the examples directory.

2. mxGetDimensions:

Purpose: Retrieves a pointer to the dimensions array of an mxArray.
Returns the number of elements in each dimension.
Example: See mxcalcsinglesubscript.c in the examples directory.

3. mxGetElementSize:

Purpose: Determines the number of bytes required to store each data element in an mxArray.
Returns 0 on failure, typically due to an unrecognized class.
Example: Refer to doubleelement.c in the examples directory.

4. mxGetEps:

Purpose: Returns the value of the MATLAB eps variable, indicating floating-point accuracy.
Example: See mxgeteps.c in the examples directory.

5. mxGetField:

Purpose: Retrieves the value of a specified field in a structure mxArray.
Returns NULL if the field is invalid or unassigned.
Example: Refer to phonebook.c in the examples directory.

6. mxGetFieldByNumber:

Purpose: Similar to mxGetField but uses a field number instead of a field name.
Example: See phonebook.c in the examples directory.

7. mxGetFieldNameByNumber:

Purpose: Retrieves the field name given a field number in a structure mxArray.
Returns NULL if the field number is invalid.
Example: Refer to phonebook.c in the examples directory.

8. mxGetFieldNumber:

Purpose: Returns the field number for a given field name in a structure mxArray.
Returns -1 if the field name is invalid.
Example: See mxcreatestructarray.c in the examples directory.

9. mxGetImagData:

Purpose: Retrieves a pointer to the imaginary data of an mxArray.
Returns NULL if there is no imaginary data.
Example: See mxisfinite.c in the examples directory.

10. mxGetInf:

Purpose: Returns the value of infinity as represented in MATLAB.
Example: Not explicitly provided.

Overview: This document provides technical details on various functions used in C and Fortran for handling mxArray structures, particularly in the context of sparse matrices and logical arrays. It includes descriptions of functions for retrieving specific data elements, dimensions, and properties of mxArray objects.

Key Sections:

Handling Infinity and NaN: Operations like division by zero or overflow result in infinity. The document references functions like mxGetInf and mxGetNaN to handle these cases.
mxGetIr and mxGetJc: These functions are used to retrieve the row and column indices of non-zero elements in a sparse matrix. They return pointers to the first elements of the respective arrays.
mxGetLogicals: This function retrieves the starting address of logical elements in an mxArray, allowing access to logical data.
mxGetM and mxGetN: These functions return the number of rows and columns in an mxArray, respectively. They are crucial for understanding the dimensions of the data structure.
mxGetNumberOfDimensions and mxGetNumberOfElements: These functions provide the number of dimensions and total elements in an mxArray, aiding in the manipulation of multi-dimensional arrays.
mxGetNzmax: This function returns the maximum number of non-zero elements that can be stored in a sparse mxArray, which is important for memory allocation and optimization.
mxGetPr and mxGetPi: These functions retrieve the real and imaginary parts of the data in an mxArray, respectively, allowing for complex number manipulations.
mxGetProperty: This function is used to get the value of a property from a MATLAB class object, providing access to object-oriented data.
mxGetScalar: This function retrieves the first real element of an mxArray, often used when dealing with scalar values.

Examples and References: The document includes references to example files such as mxgetinf.c, fulltosparse.c, and explore.c, which are located in various subdirectories of the examples directory. These examples illustrate the practical application of the functions described.

Conclusion: The document serves as a comprehensive guide for developers working with mxArray structures in C and Fortran, providing essential functions for data manipulation and retrieval in MATLAB environments.

Overview: This document provides technical details on various functions used in C and Fortran for handling mxArray data structures in MATLAB. It includes specifications, syntax, arguments, return values, and descriptions for each function, along with examples and related functions.

1. mxGetString:

Purpose: Copies a string mxArray to a C-style string.
C Syntax: #include "matrix.h" int mxGetString(const mxArray *pm, char *str, mwSize strlen);
Fortran Syntax: integer*4 mxGetString(pm, str, strlen)
Arguments:
- pm: Pointer to a string mxArray.
- str: Starting location for the string.
- strlen: Maximum number of characters to read.
Returns: 0 on success, 1 on failure.
Description: Copies character data into a C-style string or Fortran character array, terminating with a NULL character in C.

2. mxIsCell:

Purpose: Determines if input is a cell mxArray.
C Syntax: #include "matrix.h" bool mxIsCell(const mxArray *pm);
Returns: Logical 1 (true) if the array is a cell array, 0 (false) otherwise.
Description: Checks if the specified array is a cell array.

3. mxIsChar:

Purpose: Determines if input is a string mxArray.
C Syntax: #include "matrix.h" bool mxIsChar(const mxArray *pm);
Returns: Logical 1 (true) if the array is a string mxArray, 0 (false) otherwise.
Description: Checks if the specified array is a string mxArray.

4. mxIsClass:

Purpose: Determines if mxArray is a member of a specified class.
C Syntax: #include "matrix.h" bool mxIsClass(const mxArray *pm, const char *classname);
Arguments:
- pm: Pointer to an mxArray.
- classname: The class name to test against.
Returns: Logical 1 (true) if the array is of the specified class, 0 (false) otherwise.
Description: Checks if the mxArray is of a specified type.

5. mxIsComplex:

Purpose: Determines if data is complex.
C Syntax: #include "matrix.h" bool mxIsComplex(const mxArray *pm);
Returns: Logical 1 (true) if the array contains complex data, 0 (false) otherwise.
Description: Checks if an imaginary part is allocated for an mxArray.

6. mxIsDouble:

Purpose: Determines if mxArray represents data as double-precision, floating-point numbers.
C Syntax: #include "matrix.h" bool mxIsDouble(const mxArray *pm);
Returns: Logical 1 (true) if the array stores data as double-precision, 0 (false) otherwise.
Description: Checks if the mxArray represents data as double-precision numbers.

7. mxIsEmpty:

Purpose: Determines if mxArray is empty.
C Syntax: #include "matrix.h" bool mxIsEmpty(const mxArray *pm);
Returns: Logical 1 (true) if the array is empty, 0 (false) otherwise.
Description: Checks if an mxArray contains no data.

8. mxIsFinite:

Purpose: Determines if input is finite.
C Syntax: #include "matrix.h" bool mxIsFinite(double value);
Returns: Logical 1 (true) if the value is finite, 0 (false) otherwise.
Description: Checks if a number is finite.

9. mxIsFromGlobalWS:

Purpose: Determines if mxArray was copied from MATLAB global workspace.
C Syntax: #include "matrix.h" bool mxIsFromGlobalWS(const mxArray *pm);
Returns: Logical 1 (true) if the array was copied from the global workspace, 0 (false) otherwise.
Description: Useful for standalone MAT programs to check if an array is from the global workspace.

10. mxIsInf:

Purpose: Determines if input is infinite.
C Syntax: #include "matrix.h" bool mxIsInf(double value);
Returns: Logical 1 (true) if the value is infinite, 0 (false) otherwise.
Description: Checks if a number is equal to infinity or minus infinity.

11. mxIsInt16:

Purpose: Determines if mxArray represents data as signed 16-bit integers.
C Syntax: #include "matrix.h" bool mxIsInt16(const mxArray *pm);
Returns: Logical 1 (true) if the array stores data as signed 16-bit integers, 0 (false) otherwise.
Description: Checks if the mxArray represents data as 16-bit signed integers.

12. mxIsInt32:

Purpose: Determines if mxArray represents data as signed 32-bit integers.
C Syntax: #include "matrix.h" bool mxIsInt32(const mxArray *pm);
Returns: Logical 1 (true) if the array stores data as signed 32-bit integers, 0 (false) otherwise.
Description: Checks if the mxArray represents data as 32-bit signed integers.

13. mxIsInt64:

Purpose: Determines if mxArray represents data as signed 64-bit integers.
C Syntax: #include "matrix.h" bool mxIsInt64(const mxArray *pm);
Returns: Logical 1 (true) if the array stores data as signed 64-bit integers, 0 (false) otherwise.
Description: Checks if the mxArray represents data as 64-bit signed integers.

14. mxIsInt8:

Purpose: Determines if mxArray represents data as signed 8-bit integers.
C Syntax: #include "matrix.h" bool mxIsInt8(const mxArray *pm);
Returns: Logical 1 (true) if the array stores data as signed 8-bit integers, 0 (false) otherwise.
Description: Checks if the mxArray represents data as 8-bit signed integers.

15. mxIsLogical:

Purpose: Determines if mxArray is of type mxLogical.
C Syntax: #include "matrix.h" bool mxIsLogical(const mxArray *pm);
Returns: Logical 1 (true) if the array is logical, 0 (false) otherwise.
Description: Checks if MATLAB treats the data in the mxArray as Boolean.

16. mxIsLogicalScalar:

Purpose: Determines if scalar mxArray is of type mxLogical.
C Syntax: #include "matrix.h" bool mxIsLogicalScalar(const mxArray *array_ptr);
Returns: Logical 1 (true) if the mxArray is logical and has 1-by-1 dimensions, 0 (false) otherwise.
Description: Checks if the scalar data in the mxArray is treated as logical or numerical.

Overview: This document provides technical details on various functions used in MATLAB for handling mxArray data structures in C and Fortran. It covers functions for determining data types, memory management, and manipulating data structures.

1. Logical and Scalar Functions:

mxIsLogicalScalarTrue: Determines if a scalar mxArray of type mxLogical is true. Equivalent to checking if the array is logical, has one element, and the logical value is true.
mxIsNaN: Checks if a double value is NaN (Not-a-Number), which represents undefined operations like 0.0/0.0.

2. Numeric and Data Type Functions:

mxIsNumeric: Checks if an mxArray can contain numeric data, covering various numeric classes like mxDOUBLE_CLASS and mxINT32_CLASS.
mxIsSingle: Determines if an mxArray stores data as single-precision floating-point numbers.
mxIsUint16, mxIsUint32, mxIsUint64, mxIsUint8: Check if an mxArray represents data as unsigned integers of various bit sizes.

3. Memory Management:

mxMalloc: Allocates dynamic memory using MATLAB's memory manager, ensuring memory is managed and freed appropriately.
mxRealloc: Reallocates memory for an existing block, allowing for resizing while maintaining data integrity.

4. Data Structure Manipulation:

mxIsSparse: Determines if an mxArray is sparse, which is important for certain matrix operations.
mxIsStruct: Checks if an mxArray is a structure, which is necessary for functions that manipulate structure fields.
mxRemoveField: Removes a field from a structure array without destroying the field values.
mxSetCell: Sets the value of a specific cell in a cell mxArray, allowing for complex data structures within cells.

Conclusion: The document provides comprehensive details on handling mxArray data structures in MATLAB, focusing on logical checks, numeric data handling, memory management, and data structure manipulation. These functions are crucial for efficient data processing and memory management in MATLAB applications.

Overview: This document provides technical details on various MATLAB® functions used for manipulating mxArray structures in C and Fortran. It covers functions such as mxSetCell, mxSetClassName, mxSetData, mxSetDimensions, mxSetField, mxSetFieldByNumber, mxSetImagData, mxSetIr, and mxSetJc, explaining their purposes, syntax, arguments, and usage.

1. mxSetCell:

Purpose: Assigns a value to a specific cell in a cell array.
Important Note: Does not free memory for displaced data. Use mxDestroyArray to free memory before calling mxSetCell.
Examples: Refer to phonebook.c and mxcreatecellmatrix.c in the examples directory.

2. mxSetClassName:

Purpose: Converts a structure array to a MATLAB® object array.
Returns: 0 if successful, nonzero otherwise.
Important Note: If the class is undefined, the object reverts to a structure array upon loading.

3. mxSetData:

Purpose: Sets a pointer to data in an mxArray.
Important Note: Does not free memory for displaced data. Use mxFree to free memory before calling mxSetData.

4. mxSetDimensions:

Purpose: Modifies the number of dimensions and size of each dimension in an mxArray.
Important Note: Does not allocate or deallocate space for data arrays. Adjust pr and pi arrays if the number of elements changes.

5. mxSetField:

Purpose: Sets a field in a structure array given the field name and index.
Important Note: Does not free memory for displaced data. Use mxDestroyArray to free memory before calling mxSetField.

6. mxSetFieldByNumber:

Purpose: Similar to mxSetField but uses field number instead of field name.
Important Note: Does not free memory for displaced data. Use mxDestroyArray to free memory before calling mxSetFieldByNumber.

7. mxSetImagData:

Purpose: Sets the imaginary data pointer for an mxArray.
Important Note: Does not free memory for displaced data. Use mxFree to free memory before calling mxSetImagData.

8. mxSetIr:

Purpose: Sets the ir array of a sparse mxArray.
Important Note: The ir array must be sorted in column-major order. Does not free memory for displaced data. Use mxFree to free memory before calling mxSetIr.

9. mxSetJc:

Purpose: Sets the jc array of a sparse mxArray.
Important Note: The jc array defines the column indices for nonzero elements. Does not free memory for displaced data. Use mxFree to free memory before calling mxSetJc.

Conclusion: The document emphasizes the importance of managing memory when using these functions to avoid memory leaks and corruption. It provides examples and references to additional resources for further understanding.

Overview: The document provides technical details on various functions related to handling mxArray in C and Fortran, particularly focusing on memory management and manipulation of sparse matrices in MATLAB.

Key Sections:

Memory Management: Functions like mxSetM, mxSetN, and mxSetNzmax are used to set dimensions and manage storage space for nonzero elements in mxArray. These functions do not automatically allocate or deallocate memory, requiring manual adjustments using mxRealloc if the number of elements changes.
Data Manipulation: Functions such as mxSetPi and mxSetPr are used to set imaginary and real data for mxArray. These functions replace existing data without freeing memory, necessitating the use of mxFree to prevent memory leaks.
Property Management: The mxSetProperty function assigns values to properties of MATLAB class objects, making a copy of the value before assignment, which can impact memory usage.
Examples and References: The document references example files like mxsetdimensions.c and mxsetnzmax.c for practical implementation guidance.

Critical Information:

Memory management functions do not automatically handle memory allocation, requiring explicit calls to mxRealloc and mxFree.
Changing the shape of an mxArray with mxSetM or mxSetN requires careful management of associated arrays (pr, pi, ir, jc).
Setting properties with mxSetProperty involves copying values, which can be memory-intensive.

Catalog excerpts

MXArrayManipulation mxCreateLogicalMatrix(C) Create2-D,logical > mxArray initializedto > falsemxCreateLogicalScalar(C) Createscalar,logical > mxArray initializedto > falsemxCreateNumericArray(CandFortran) CreateunpopulatedN-Dnumeric > mxArraymxCreateNumericMatrix(CandFortran) Createnumericmatrixandinitializedataelementsto0 > mxCreateSparse(CandFortran) Create2-Dunpopulatedsparse > mxArraymxCreateSparseLogicalMatrix(C) Createunpopulated2-D,sparse,logical > mxArraymxCreateString(CandFortran) Create > 1 -by- > N string > mxArray initializedtospecifiedstring > mxCreateStructArray(CandFortran) CreateunpopulatedN-Dstructure...

Open the catalog to page 11

MXArrayManipulation mxMalloc(CandFortran) AllocatedynamicmemoryusingMATLABmemorymanager > mxRealloc(CandFortran) Reallocatememory > mxRemoveField(CandFortran) Removefieldfromstructurearray > mxSetCell(CandFortran) Setvalueofonecellof > mxArraymxSetClassName(C) ConvertstructurearraytoMATLABobjectarray > mxSetData(CandFortran) Setpointertodata > mxSetDimensions(CandFortran) Modifynumberofdimensionsandsizeofeachdimension > mxSetField(CandFortran) Setstructurearrayfield,givenfield nameandindex > mxSetFieldByNumber(CandFortran) Setstructurearrayfield,givenfieldnumberandindex > mxSetImagData(CandFortran)...

Open the catalog to page 15

MATLAB Engine mexPrintf(CandFortran) ANSI > ή C > printf -styleoutputroutine > mexPutVariable(CandFortran) Copy > mxArray fromMEX-functionintospecifiedworkspace > mexSet(C) SetvalueofspecifiedHandle Graphicsproperty > mexSetTrapFlag(CandFortran) Controlresponseof > mexCallMATLAB toerrors > mexUnlock(CandFortran) AllowMEX-filetobeclearedfrom memory > mexWarnMsgIdAndTxt(CandFortran) Issuewarningmessagewithidentifier > mexWarnMsgTxt(CandFortran) Issuewarningmessage > engClose(CandFortran) QuitMATLAB > ή enginesession > engEvalString(CandFortran) Evaluateexpressioninstring > engGetVariable(CandFortran)...

Open the catalog to page 17

APIReference engPutVariable(CandFortran) PutvariablesintoMATLABengineworkspace > engSetVisible(C) ShoworhideMATLABengine session >

Open the catalog to page 18

Note Thebufferreturnedby > engEvalString isnotguaranteedtobe > NULL terminated. >

Open the catalog to page 33

See > mexfunction.c inthe > mex subdirectoryofthe > examples directory Օ > phonebook.c inthe > refbook subdirectoryofthe > examples directory. > mexErrMsgIdAndTxt , > mexErrMsgTxt , > mexWarnMsgIdAndTxt , > mexWarnMsgTxt

Open the catalog to page 79

2 ThesecondMEX-fileiscalledwiththe > trapflag initializedto > withinthatfile. > 3 WhenthesecondMEX-fileexits,thesavedvalueofthe > trapflag inthefirstMEX-fileisrestoredwithinthatfile. > See > mexsettrapflag.c inthe > mex subdirectoryofthe > examples directory. >

Open the catalog to page 84

Various > mx* callsrequireorreturnan > mxClassID argument. > mxClassID identifiesthewayinwhichthe > mxArray representsitsdataelements. > See > explore.c inthe > mex subdirectoryofthe > examples directory. >

Open the catalog to page 105

> mxgeteps.c and > mxisfinite.c inthe > mx subdirectoryofthe > examples directory >

Open the catalog to page 164

> mxsetdimensions.c and > mxsetnzmax.c inthe > mx subdirectoryofthe > examples directory > mxGetJc , > mxGetNzmax , > mxSetIr , > mxSetJc , > mxSetNzmax

Open the catalog to page 180

Itismostefficienttousethe > mxIsDouble form. > See > mxisclass.c inthe > mx subdirectoryofthe > examples directory. > mxClassID , > mxGetClassID , > mxIsEmpty , > mxGetClassName

Open the catalog to page 203

> mexget.c , > mexlock.c , > mexsettrapflag.c ,and > yprime.c inthe > mex subdirectoryofthe > examples directory Օ > mxcalcsinglesubscript.c , > mxgeteps.c , > mxgetinf.c ,and > mxisfinite.c inthe > mx subdirectoryofthe > examples directory >

Open the catalog to page 206

All The MathWorks catalogs and technical brochures

Archived catalogs

*Prices are pre-tax. They exclude delivery charges and customs duties and do not include additional charges for installation or activation options. Prices are indicative only and may vary by country, with changes to the cost of raw materials and exchange rates.

Brand list