C-API to run SoS scripts and exchange basic data. More...

#include "sos_capi_common.h"

Typedefs
typedef void *	fmop_script_handle_t
	Contains the data required to post-process any Field-MOP.

Functions
Create / Initialize Data Objects
API handling data object life time
DYNARDO_FMOP_API fmop_script_handle_t	FMOP_globalScriptEngine ()
	Get the handle to the global script engine from the initialized library. The routine checks if the Lua interpreter is available. If no, it returns 0. If yes, it returns the handle to the Lua interpreter. There is only a single instance available. Repeated calls of this functions always return the same handle. More...

DYNARDO_FMOP_API fmop_error_t	FMOP_script_execute (fmop_script_handle_t context, const char *const script)
	Execute Lua script code. The script engine has the ability to parse and execute: More...

DYNARDO_FMOP_API fmop_error_t	FMOP_script_createMatrix (fmop_script_handle_t context, const char const ident, int rows, int cols, const double const data)
	Creates a tmath.Matrix in Lua script context. This version may be more efficient than creating a matrix through a text based script - at least for large matrices. More...

DYNARDO_FMOP_API fmop_error_t	FMOP_script_getMatrix (fmop_script_handle_t context, const char const ident, int rows, int cols, const double *data)
	Retrieves the binary data of a tmath.Matrix existing in the Lua script context The matrix must be saved in a Lua variable. The data can be retrieved in an efficient way by accessing only the data buffers in memory. Do not change the data from outside. Memory management remains with the Lua interpreter. Thus, the garbage collector may free the memory to which the output of this method refers to. More...

DYNARDO_FMOP_API fmop_error_t	FMOP_script_createNumber (fmop_script_handle_t context, const char *const ident, double data)
	Creates a double precision floating point number variable in the Lua script context. More...

DYNARDO_FMOP_API fmop_error_t	FMOP_script_getNumber (fmop_script_handle_t context, const char const ident, double const data)
	Retrieve the pointer to a number variable in the Lua script context. The number is is stored in double precision floating point format. More...

DYNARDO_FMOP_API fmop_error_t	FMOP_script_createString (fmop_script_handle_t context, const char const ident, const char const data)
	Create a string variable in the Lua script context. More...

DYNARDO_FMOP_API fmop_error_t	FMOP_script_getString (fmop_script_handle_t context, const char const ident, const char *data)
	Retrieve the char array pointer to a string variable in the Lua script context. The data can be retrieved in an efficient way by accessing only the data buffers in memory. Do not change the data from outside. Memory management remains with the Lua interpreter. Thus, the garbage collector may free the memory to which the output of this method refers to. More...

DYNARDO_FMOP_API bool	FMOP_script_identExists (fmop_script_handle_t context, const char *const ident)
	Check whether a variable exists in the Lua script context. More...

Detailed Description

C-API to run SoS scripts and exchange basic data.

Copyright: DYNARDO Austria GmbH

This API follows the Basic exception safety rule. If any of the operations fail, the original data, e.g. the fmop_handle*_t, might have been overwritten, but there should be no resource leak.
Return values are typically of type fmop_error_t. To get a human readalbe interpretation forward this value to FMOP_getErrnoString() or call FMOP_getLastErrorString(). More information can be found in the Error Handling section
Log messages from the SoS kernel are all bufferd in an internal variable. Unless otherwise stated in a function description, this internal variable gets reset(!) right at the beginning of each function call. Therefore, the user is forced into fetching all log messages of interest before proceeding.

Warning: Concurrent library calls are NOT supported; Unless stated otherwise, function calls overwrite log messages of any previous function call

Function Documentation

◆ FMOP_globalScriptEngine()

DYNARDO_FMOP_API fmop_script_handle_t FMOP_globalScriptEngine ( )

Get the handle to the global script engine from the initialized library. The routine checks if the Lua interpreter is available. If no, it returns 0. If yes, it returns the handle to the Lua interpreter. There is only a single instance available. Repeated calls of this functions always return the same handle.

Returns

fmop_handle_t if the FMOP library was previously initialized with FMOP_initializeLibrary()
fmop_invalid_handle if the global script engine is unavailable

◆ FMOP_script_createMatrix()

DYNARDO_FMOP_API fmop_error_t FMOP_script_createMatrix	(	fmop_script_handle_t	context,
		const char *const	ident,
		int	rows,
		int	cols,
		const double *const	data
	)

Creates a tmath.Matrix in Lua script context. This version may be more efficient than creating a matrix through a text based script - at least for large matrices.

Parameters

	context	handle to a script engine
[in]	ident	the ident in Lua script of the matrix to be created
[in]	rows	the number of rows of the matrix to be created
[in]	cols	the number of columns of the matrix to be created
[in]	data	the data array of the matrix to be created. The dimension of the data array must be rows*cols. The matrix data is stored in a column-major format.

Returns

fmop_success on successful matrix creation
fmop_script_no_object ident could not be accessed
fmop_script_error if an error occurred during LUA script execution
fmop_license_error if a license error occurred, e.g. no license has been acquired

◆ FMOP_script_createNumber()

DYNARDO_FMOP_API fmop_error_t FMOP_script_createNumber	(	fmop_script_handle_t	context,
		const char *const	ident,
		double	data
	)

Creates a double precision floating point number variable in the Lua script context.

Parameters

[in]	context	handle to a script engine
[in]	ident	the number's variable name
[in]	data	the number's value

Returns

fmop_success on successful number creation
fmop_invalid_handle
fmop_license_error if a license error occurred, e.g. no license has been acquired

◆ FMOP_script_createString()

DYNARDO_FMOP_API fmop_error_t FMOP_script_createString	(	fmop_script_handle_t	context,
		const char *const	ident,
		const char *const	data
	)

Create a string variable in the Lua script context.

Parameters

[in]	context	handle to a script engine
[in]	ident	the string's variable name
[in]	data	the string's text

Returns

fmop_success on successful string creation
fmop_invalid_handle
fmop_license_error if a license error occurred, e.g. no license has been acquired

◆ FMOP_script_execute()

DYNARDO_FMOP_API fmop_error_t FMOP_script_execute	(	fmop_script_handle_t	context,
		const char *const	script
	)

Execute Lua script code. The script engine has the ability to parse and execute:

any SoS script code (check the command log in the SoS GUI and the scripting examples provided with your SoS installation, in the public documents folder on Windows)
any Lua code
Parameters

context handle to a script engine
script the Lua script code to be executed
Returns
- fmop_success on successful script execution
- fmop_script_error if an error occurred during LUA script execution
- fmop_license_error if a license error occurred, e.g. no license has beend acquired
See also
fmop_error_t

◆ FMOP_script_getMatrix()

DYNARDO_FMOP_API fmop_error_t FMOP_script_getMatrix	(	fmop_script_handle_t	context,
		const char *const	ident,
		int *	rows,
		int *	cols,
		const double **	data
	)

Retrieves the binary data of a tmath.Matrix existing in the Lua script context The matrix must be saved in a Lua variable. The data can be retrieved in an efficient way by accessing only the data buffers in memory. Do not change the data from outside. Memory management remains with the Lua interpreter. Thus, the garbage collector may free the memory to which the output of this method refers to.

Parameters

[in]	context	handle to a script engine
[in]	ident	the ident of the tmath.Matrix variable in Lua.
[out]	rows	the number of rows
[out]	cols	the number of columns
[out]	data	data will point to the matrix data array on output. The dimension of the data array must be rowscols. The matrix data is stored in a column-major format.

Returns

fmop_success on successful matrix access
fmop_script_no_object ident could not be accessed
fmop_license_error if a license error occurred, e.g. no license has been acquired

◆ FMOP_script_getNumber()

DYNARDO_FMOP_API fmop_error_t FMOP_script_getNumber	(	fmop_script_handle_t	context,
		const char *const	ident,
		double *const	data
	)

Retrieve the pointer to a number variable in the Lua script context. The number is is stored in double precision floating point format.

Parameters

[in]	context	handle to a script engine
[in]	ident	the number's variable name
[out]	data	contains the number's memory address on fmop_success. The caller retains ownership of the pointer.

Returns

fmop_success on successful number access
fmop_script_wrong_type
fmop_invalid_handle
fmop_license_error if a license error occurred, e.g. no license has been acquired

◆ FMOP_script_getString()

DYNARDO_FMOP_API fmop_error_t FMOP_script_getString	(	fmop_script_handle_t	context,
		const char *const	ident,
		const char **	data
	)

Retrieve the char array pointer to a string variable in the Lua script context. The data can be retrieved in an efficient way by accessing only the data buffers in memory. Do not change the data from outside. Memory management remains with the Lua interpreter. Thus, the garbage collector may free the memory to which the output of this method refers to.

Parameters

[in]	context	handle to a script engine
[in]	ident	the string's variable name
[out]	data	contain's the string's text on fmop_success

Returns

◆ FMOP_script_identExists()

DYNARDO_FMOP_API bool FMOP_script_identExists	(	fmop_script_handle_t	context,
		const char *const	ident
	)

Check whether a variable exists in the Lua script context.

Parameters

[in]	context	handle to a script engine
[in]	ident	the variable's name

Returns

true: the ident exists
false: the ident does not exist

SoS C API of FMOPSolver library 2023 R2

sos_capi_script.h File Reference

Typedefs

Functions

Detailed Description

Function Documentation

◆ FMOP_globalScriptEngine()

◆ FMOP_script_createMatrix()

◆ FMOP_script_createNumber()

◆ FMOP_script_createString()

◆ FMOP_script_execute()

◆ FMOP_script_getMatrix()

◆ FMOP_script_getNumber()

◆ FMOP_script_getString()

◆ FMOP_script_identExists()

Connect with Ansys