## On this page # sos\_capi\_script.h File Reference Last update: 22.02.2024 C-API to run SoS scripts and exchange basic data. [More...](#details) `#include "sos_capi_common.h"` [Go to the source code of this file.](sos__capi__script_8h_source.xhtml) ## Typedefs typedef void \* [fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) 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](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) [FMOP\_globalScriptEngine](sos__capi__script_8h.xhtml#ace6f8c522f626dddbf5fc12d4d1d7a11) () 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...](sos__capi__script_8h.xhtml#ace6f8c522f626dddbf5fc12d4d1d7a11) DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) [FMOP\_script\_execute](sos__capi__script_8h.xhtml#a585497e6891f11a032944d26f3b0d9c0) ([fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) context, const char \*const script) Execute Lua script code. The script engine has the ability to parse and execute: [More...](sos__capi__script_8h.xhtml#a585497e6891f11a032944d26f3b0d9c0) DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) [FMOP\_script\_createMatrix](sos__capi__script_8h.xhtml#a86518674fc7aa5571d44f5d8544879f0) ([fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) 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...](sos__capi__script_8h.xhtml#a86518674fc7aa5571d44f5d8544879f0) DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) [FMOP\_script\_getMatrix](sos__capi__script_8h.xhtml#afe7c32369056cdee19411d3924538d5d) ([fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) 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...](sos__capi__script_8h.xhtml#afe7c32369056cdee19411d3924538d5d) DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) [FMOP\_script\_createNumber](sos__capi__script_8h.xhtml#acd830885fbde66f6d3133d7f1e943796) ([fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) context, const char \*const ident, double data) Creates a double precision floating point number variable in the Lua script context. [More...](sos__capi__script_8h.xhtml#acd830885fbde66f6d3133d7f1e943796) DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) [FMOP\_script\_getNumber](sos__capi__script_8h.xhtml#a6b01058d679a651d52882f928caa14e7) ([fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) 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...](sos__capi__script_8h.xhtml#a6b01058d679a651d52882f928caa14e7) DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) [FMOP\_script\_createString](sos__capi__script_8h.xhtml#a31383b3c0eb3e408c74430b1cd610183) ([fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) context, const char \*const ident, const char \*const data) Create a string variable in the Lua script context. [More...](sos__capi__script_8h.xhtml#a31383b3c0eb3e408c74430b1cd610183) DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) [FMOP\_script\_getString](sos__capi__script_8h.xhtml#ac1304b306d77e15fcfd1e99603bbff62) ([fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) 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...](sos__capi__script_8h.xhtml#ac1304b306d77e15fcfd1e99603bbff62) DYNARDO\_FMOP\_API bool [FMOP\_script\_identExists](sos__capi__script_8h.xhtml#adaf34349f4a16e537f5fe8a5ceb52856) ([fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) context, const char \*const ident) Check whether a variable exists in the Lua script context. [More...](sos__capi__script_8h.xhtml#adaf34349f4a16e537f5fe8a5ceb52856) ## Detailed Description C-API to run SoS scripts and exchange basic data. CopyrightDYNARDO 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()](sos__capi__common_8h.xhtml#a7e820b85d2ef2596b00bc82445dcf650 "Returns a string description for the error number given.") or call [FMOP\_getLastErrorString()](sos__capi__common_8h.xhtml#a5e19e7fe152759a80115e908c593245d "Returns internal log messages of level warning and above."). 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. WarningConcurrent library calls are NOT supported Unless stated otherwise, function calls overwrite log messages of any previous function call ## Function Documentation ## [◆ ](#ace6f8c522f626dddbf5fc12d4d1d7a11)FMOP\_globalScriptEngine() DYNARDO\_FMOP\_API [fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) 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](fmop__solver_8h.xhtml#aed65d1ae14f8c298a702ad5b828a70ef "Contains one specific single or cross correlated FMOP.") if the FMOP library was previously initialized with [FMOP\_initializeLibrary()](sos__capi__common_8h.xhtml#a9c8f0f808d3f27c57a3a57d5f9cf4834 "Initialize the FMOP library Allocates memory for the global script engine. Call FMOP_unloadLibrary() ...") - [fmop\_invalid\_handle](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8becacef5c059b0dd649f97d5404db95c3ccf "The function got an unexpected NULL pointer.") if the global script engine is unavailable ## [◆ ](#a86518674fc7aa5571d44f5d8544879f0)FMOP\_script\_createMatrix() DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) FMOP\_script\_createMatrix ( [fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) *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 contexthandle to a script engine \[in\]identthe ident in Lua script of the matrix to be created \[in\]rowsthe number of rows of the matrix to be created \[in\]colsthe number of columns of the matrix to be created \[in\]datathe 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](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8beca41a0a2e83b0ac20d414f4b015522ce55 "Function execution returned successfully.") on successful matrix creation - [fmop\_script\_no\_object](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8beca749f1c6edf13b1303018d7a3632dc316 "Object with ident not found in script engine.") ident could not be accessed - [fmop\_script\_error](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8becab6e0160bb71d6930176d907409618f4d "An error appeare while executing Lua script.") if an error occurred during LUA script execution - [fmop\_license\_error](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8becacf8dfe2eaba2eada73a26e487a04f8fe "No valid license available.") if a license error occurred, e.g. no license has been acquired ## [◆ ](#acd830885fbde66f6d3133d7f1e943796)FMOP\_script\_createNumber() DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) FMOP\_script\_createNumber ( [fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) *context*, const char \*const *ident*, double *data* ) Creates a double precision floating point number variable in the Lua script context. Parameters \[in\]contexthandle to a script engine \[in\]identthe number's variable name \[in\]datathe number's value Returns- [fmop\_success](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8beca41a0a2e83b0ac20d414f4b015522ce55 "Function execution returned successfully.") on successful number creation - [fmop\_invalid\_handle](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8becacef5c059b0dd649f97d5404db95c3ccf "The function got an unexpected NULL pointer.") - [fmop\_license\_error](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8becacf8dfe2eaba2eada73a26e487a04f8fe "No valid license available.") if a license error occurred, e.g. no license has been acquired ## [◆ ](#a31383b3c0eb3e408c74430b1cd610183)FMOP\_script\_createString() DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) FMOP\_script\_createString ( [fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) *context*, const char \*const *ident*, const char \*const *data* ) Create a string variable in the Lua script context. Parameters \[in\]contexthandle to a script engine \[in\]identthe string's variable name \[in\]datathe string's text Returns- [fmop\_success](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8beca41a0a2e83b0ac20d414f4b015522ce55 "Function execution returned successfully.") on successful string creation - [fmop\_invalid\_handle](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8becacef5c059b0dd649f97d5404db95c3ccf "The function got an unexpected NULL pointer.") - [fmop\_license\_error](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8becacf8dfe2eaba2eada73a26e487a04f8fe "No valid license available.") if a license error occurred, e.g. no license has been acquired ## [◆ ](#a585497e6891f11a032944d26f3b0d9c0)FMOP\_script\_execute() DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) FMOP\_script\_execute ( [fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) *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 contexthandle to a script engine scriptthe Lua script code to be executed Returns - [fmop\_success](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8beca41a0a2e83b0ac20d414f4b015522ce55 "Function execution returned successfully.") on successful script execution - [fmop\_script\_error](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8becab6e0160bb71d6930176d907409618f4d "An error appeare while executing Lua script.") if an error occurred during LUA script execution - [fmop\_license\_error](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8becacf8dfe2eaba2eada73a26e487a04f8fe "No valid license available.") if a license error occurred, e.g. no license has beend acquired See also[fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec "Error code definitions.") ## [◆ ](#afe7c32369056cdee19411d3924538d5d)FMOP\_script\_getMatrix() DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) FMOP\_script\_getMatrix ( [fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) *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\]contexthandle to a script engine \[in\]identthe ident of the tmath.Matrix variable in Lua. \[out\]rowsthe number of rows \[out\]colsthe number of columns \[out\]data\*data will point to the matrix data array on output. The dimension of the data array must be rows\*cols. The matrix data is stored in a column-major format. Returns- [fmop\_success](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8beca41a0a2e83b0ac20d414f4b015522ce55 "Function execution returned successfully.") on successful matrix access - [fmop\_script\_no\_object](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8beca749f1c6edf13b1303018d7a3632dc316 "Object with ident not found in script engine.") ident could not be accessed - [fmop\_license\_error](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8becacf8dfe2eaba2eada73a26e487a04f8fe "No valid license available.") if a license error occurred, e.g. no license has been acquired ## [◆ ](#a6b01058d679a651d52882f928caa14e7)FMOP\_script\_getNumber() DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) FMOP\_script\_getNumber ( [fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) *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\]contexthandle to a script engine \[in\]identthe number's variable name \[out\]datacontains the number's memory address on [fmop\_success](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8beca41a0a2e83b0ac20d414f4b015522ce55 "Function execution returned successfully."). The caller retains ownership of the pointer. Returns- [fmop\_success](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8beca41a0a2e83b0ac20d414f4b015522ce55 "Function execution returned successfully.") on successful number access - [fmop\_script\_wrong\_type](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8beca32eddc7d860101cdbb8e1571c726ee91 "Object with ident has wrong type.") - [fmop\_invalid\_handle](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8becacef5c059b0dd649f97d5404db95c3ccf "The function got an unexpected NULL pointer.") - [fmop\_license\_error](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8becacf8dfe2eaba2eada73a26e487a04f8fe "No valid license available.") if a license error occurred, e.g. no license has been acquired ## [◆ ](#ac1304b306d77e15fcfd1e99603bbff62)FMOP\_script\_getString() DYNARDO\_FMOP\_API [fmop\_error\_t](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8bec) FMOP\_script\_getString ( [fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) *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\]contexthandle to a script engine \[in\]identthe string's variable name \[out\]datacontain's the string's text on [fmop\_success](sos__capi__common_8h.xhtml#a4847f3fa2943ffd694eb6cbe169a8beca41a0a2e83b0ac20d414f4b015522ce55 "Function execution returned successfully.") Returns ## [◆ ](#adaf34349f4a16e537f5fe8a5ceb52856)FMOP\_script\_identExists() DYNARDO\_FMOP\_API bool FMOP\_script\_identExists ( [fmop\_script\_handle\_t](sos__capi__script_8h.xhtml#aab8ff16aaa9cf05fccc70920f4b62bfb) *context*, const char \*const *ident* ) Check whether a variable exists in the Lua script context. Parameters \[in\]contexthandle to a script engine \[in\]identthe variable's name Returns- true: the ident exists - false: the ident does not exist