File sos_capi_script.h

Location: sos_capi_script.h

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

!> Warning
Unless stated otherwise, function calls overwrite log messages of any previous function call

Includes

sos_capi_common.h

graph LR
2["sos_capi_common.h"]
click 2 "sos__capi__common_8h.md#sos__capi__common_8h"

1["sos_capi_script.h"]
click 1 "sos__capi__script_8h.md#sos__capi__script_8h"
1 --> 2

Included by

FMOPSolver.h

graph RL
2["FMOPSolver.h"]

1["sos_capi_script.h"]
click 1 "sos__capi__script_8h.md#sos__capi__script_8h"
2 --> 1

Create / Initialize Data Objects

API handling data object life time

Function 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

Return type: DYNARDO_FMOP_API fmop_script_handle_t

Function 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
ident: the ident in Lua script of the matrix to be created
rows: the number of rows of the matrix to be created
cols: the number of columns of the matrix to be created
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

Parameters:

fmop_script_handle_t context
const char *const ident
int rows
int cols
const double *const data

Return type: DYNARDO_FMOP_API fmop_error_t

Function 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:

context: handle to a script engine
ident: the number's variable name
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

Parameters:

fmop_script_handle_t context
const char *const ident
double data

Return type: DYNARDO_FMOP_API fmop_error_t

Function 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:

context: handle to a script engine
ident: the string's variable name
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

Parameters:

fmop_script_handle_t context
const char *const ident
const char *const data

Return type: DYNARDO_FMOP_API fmop_error_t

Function 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

Parameters:

fmop_script_handle_t context
const char *const script

Return type: DYNARDO_FMOP_API fmop_error_t

Function 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:

context: handle to a script engine
ident: the ident of the tmath.Matrix variable in Lua.
rows: the number of rows
cols: the number of columns
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

Parameters:

fmop_script_handle_t context
const char *const ident
int * rows
int * cols
const double ** data

Return type: DYNARDO_FMOP_API fmop_error_t

Function 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:

context: handle to a script engine
ident: the number's variable name
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

Parameters:

fmop_script_handle_t context
const char *const ident
double *const data

Return type: DYNARDO_FMOP_API fmop_error_t

Function 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:

context: handle to a script engine
ident: the string's variable name
data: contain's the string's text on fmop_success

Returns:

Parameters:

fmop_script_handle_t context
const char *const ident
const char ** data

Return type: DYNARDO_FMOP_API fmop_error_t

Function 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:

context: handle to a script engine
ident: the variable's name

Returns:

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

Parameters:

fmop_script_handle_t context
const char *const ident

Return type: DYNARDO_FMOP_API bool

Typedefs

Typedef fmop_script_handle_t

Definition: sos_capi_script.h (line 44)

typedef void* fmop_script_handle_t

Contains the data required to post-process any Field-MOP.

Return type: void *

Source


#ifndef DYNARDO_SOS_SCRIPT_H
    #define DYNARDO_SOS_SCRIPT_H

#include "sos_capi_common.h"

#ifdef __cplusplus
extern "C" {
#endif

/*********************************************/

#ifdef DYNARDO_FMOP_DLL_EXPORTS
    typedef class FMOP_ScriptInterpreter* fmop_script_handle_t;
#else
    typedef void* fmop_script_handle_t;
#endif

/*********************************************/

/*
 *
#ifndef DOXYGEN_IGNORE
DYNARDO_FMOP_API fmop_error_t FMOP_loadDbBuf
    ( fmop_db_handle_t * database, const char* buffer, const size_t * length );

// FMOP_saveDbBuf

#endif

*/

DYNARDO_FMOP_API fmop_script_handle_t FMOP_globalScriptEngine();

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

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);

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);

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

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

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

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

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

#ifdef __cplusplus
}
#endif

#endif // DYNARDO_SOS_SCRIPT_H

// (c) 2018, DYNARDO Austria GmbH (proprietary license)

optiSLang FMOPSolver API 2026 R1

Includes

Included by

Create / Initialize Data Objects

Function FMOP_globalScriptEngine

Function FMOP_script_createMatrix

Function FMOP_script_createNumber

Function FMOP_script_createString

Function FMOP_script_execute

Function FMOP_script_getMatrix

Function FMOP_script_getNumber

Function FMOP_script_getString

Function FMOP_script_identExists

Typedefs

Typedef fmop_script_handle_t

Source

Connect with Ansys