For detailed information on the individual functions, use the selection box on the right.
int nni_get_interface( int iVersion, void** ppnni_func );
The function returns an instance of the Natural Native Interface.
An application calls this function after having retrieved and loaded the interface library with platform depending system calls. The function returns a pointer to a structure that contains function pointers to the individual interface functions. The functions returned in the structure may differ between interface versions.
Instead of a specific interface version, the caller can also specify the
constant NNI_VERSION_CURR, which always refers to the most recent
interface version. The interface version number belonging to a given Natural
version is defined in the header file natni.h that is
delivered with that version. In Natural Version n.n,
the interface version number is defined as
NNI_VERSION_nn.
NNI_VERSION_CURR is also defined as
NNI_VERSION_nn. If the Natural version
against which the function is called does not support the requested interface
version, the error code NNI_RC VERSION_ERROR is returned.
Otherwise the return code is NNI_RC_OK.
The pointer returned by the function represents one instance of the interface. In order to use this interface instance, the application holds on to that pointer and passes it to subsequent interface calls.
Usually the application will subsequently initialize a Natural session
by calling nni_initialize on the
given instance. After the application has finished using that Natural session,
it calls nni_uninitialize on that
instance. After that it can initialize a different Natural session on the same
interface instance. After the application has finished using the interface
instance entirely, it calls nni_free_interface on
that instance.
| Parameter | Meaning |
|---|---|
iVersion |
Interface version number.
(NNI_VERSION_nn or
NNI_VERSION_CURR).
|
ppnni_func |
Points to an NNI interface instance on return. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_VERSION_ERROR
|
int nni_free_interface(void* pnni_func);
An application calls this function after it has finished using the interface instance and has uninitialized the Natural session it hosts. The function frees the resources occupied by that interface instance.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
int nni_initialize(void* pnni_func, const char* szCmdLine, void*, void*);
The function initializes a Natural session with a given command line. The syntax and semantics of the command line is the same as when Natural is started interactively. If a Natural session has already been initialized on the given interface instance, that session is implicitly uninitialized before the new session is initialized.
The command line must be specified in the way that the Natural
initialization can be completed without user interaction. This means especially
that if a program is passed on the stack or a startup program is specified,
that program must not perform an INPUT statement that is not
satisfied from the stack. Otherwise the subsequent behavior of the Natural
session is undetermined.
The Natural session is initialized as batch session and in server mode. This means that the usage of certain statements and commands in the executed Natural modules is restricted. These restrictions and error conditions are the same as documented in the section Using Statements and Commands in a NaturalX Server Environment of the Operations documentation.
When initializing a Natural session under Natural Security, the command
line must contain a LOGON command to a freely
chosen default library under which the session will be started, and an
appropriate user ID and password.
Example:
int iRes = pnni_func->nni_initialize( pnni_func, "STACK=(LOGON,MYLIB,MYUSER,MYPASS)", 0, 0);
If the application later calls nni_logon to a different
library with a different user ID and afterwards calls
nni_logoff, the
Natural session will be reset to the library and user ID that was passed during
nni_initialize.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
szCmdLine |
Natural command line. May be a null pointer. |
void* |
For future use. Must be a null pointer. |
void* |
For future use. Must be a null pointer. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_PARM_ERROR
|
|
rc, where
rc < NNI_RC_SERR_OFFSET
|
Natural startup error. The real Natural startup error number as
documented in
Natural Startup Errors (which is
part of the Operations documentation) can be determined by
the following calculation:
startup-error-nr = -
(rc - Warnings that occur during session initialization are ignored. |
| > 0 | Natural error number. |
int nni_is_initialized( void* pnni_func, int* piIsInit );
The function checks if the interface instance contains an initialized Natural session.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
piIsInit |
Returns 0, if no Natural session is initialized, a non-zero value otherwise. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_PARM_ERROR
|
int nni_uninitialize(void* pnni_func);
The function uninitializes the Natural session hosted by the given interface instance.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
int nni_enter(void* pnni_func);
The function lets the current thread wait for exclusive access to the
interface instance and the Natural session it hosts. A thread calls this
function if it wants to issue a series of interface calls that may not be
interrupted by other threads. The thread releases the exclusive access to the
interface instance by calling nni_leave.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
int nni_try_enter(void* pnni_func);
The function behaves like nni_enter except that it does
not block the thread and instead always returns immediately. If a different
thread already has exclusive access to the interface instance, the function
returns NNI_RC_LOCKED.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_LOCKED
|
int nni_leave(void* pnni_func);
The function releases exclusive access to the interface instance and allows other threads to access that instance and the Natural session it hosts.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
int nni_logon(void* pnni_func, const char* szLibrary, const char* szUser, const char* szPassword);
The function performs a
LOGON to the specified
Natural library.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
szLibrary |
Name of the Natural library. |
szUser |
Name of the Natural user. May be a null pointer, if the Natural
session is not running under Natural Security or if
AUTO=ON was
used during initialization.
|
szPassword |
Password of that user. May be a null pointer, if the Natural
session is not running under Natural Security or if
AUTO=ON was used during initialization..
|
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
| > 0 | Natural error number. |
int nni_logoff(void* pnni_func);
The function performs a
LOGOFF from the current
Natural library. This corresponds to a
LOGON to the previously
active library and user ID.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
| > 0 | Natural error number. |
int nni_callnat(void* pnni_func, const char* szName, int iParm, struct parameter_description* rgDesc, struct natural_exception* pExcep);
The function calls a Natural subprogram.
The function receives its parameters as an array of
parameter_description structures. The caller creates
these structures using NNI functions in the following way:
Use one the functions create_parm or
create_module_parm to create an appropriate parameter set for the
subprogram.
If you have used create_parm, use the functions
init_parm_* to initialize each parameter to the appropriate
Natural data format. If you have used create_module_parm, the
parameters are already initialized to the appropriate Natural data format.
Assign a value to each parameter, using one the functions
nni_put_parm or
nni_put_parm_array.
Call nni_get_parm on each
parameter in the set. This fills the
parameter_description structures.
Pass the array of parameter_description
structures to the function nni_callnat.
After the call has been executed, extract the modified parameter
values from the parameter set using the function
nni_get_parm or
nni_get_parm_array.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
szName |
Name of the Natural subprogram. |
iParm |
Number of parameters. Indicates the number of occurrences of the
array rgDesc.
|
rgDesc |
An array of parm_description structures
containing the parameters for the subprogram. If the subprogram does not expect
parameters, the caller passes a null pointer.
|
pExcep |
Pointer to a natural_exception structure.
If a Natural error occurs during execution of the subprogram, this structure is
filled with Natural error information. The caller may specify a null pointer.
In this case no extended error information is returned.
|
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_NO_MEMORY
|
|
| > 0 | Natural error number. |
int nni_create_object(void* pnni_func, const char* szName, int iParm, struct parameter_description* rgDesc, struct natural_exception* pExcep);
Creates a Natural object (an instance of a Natural class).
The function receives its parameters as a one-element array of
parameter_description structures. The caller creates the
structures using NNI functions in the following way:
Use the function nni_create_parm to create
parameter set with one element.
Use the function nni_init_parm_s to
initialize the parameter with the type HANDLE OF OBJECT.
Call nni_get_parm_info on
this parameter. This fills the parameter_description
structure.
Pass the parameter_description structure to the
function nni_create_object.
After the call has been executed, extract the modified parameter value
from the parameter set using one the function
nni_get_parm.
The parameters passed in rgDesc have the
following meaning:
The first (and only) parameter must be initialized with the data type
HANDLE OF OBJECT and contains on return the Natural object handle
of the newly created object.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
szName |
Name of the class. |
iParm |
Number of parameters. Indicates the number of occurrences of the
array rgDesc.
|
rgDesc |
An array of parm_description structures
containing the parameters for the object creation. The caller always passes one
parameter, which will contain the object handle on return.
|
pExcep |
Pointer to a natural_exception structure.
If a Natural error occurs during object creation, this structure is filled with
Natural error information. The caller may specify a null pointer. In this case
no extended exception information is returned.
|
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_NO_MEMORY
|
|
| > 0 | Natural error number. |
int nni_send_method(void* pnni_func, const char* szName, int iParm, struct parameter_description* rgDesc, struct natural_exception* pExcep);
Sends a method call to a Natural object (an instance of a Natural class).
The function receives its parameters as an array of
parameter_description structures. The caller creates
these structures using NNI functions in the following way:
Use the function nni_create_parm or
nni_create_method_parm
to create a matching parameter set.
If you have used create_parm, use the functions
init_parm_* to initialize each parameter to the appropriate
Natural data format. If you have used
nni_create_method_parm,
the parameters are already initialized to the appropriate Natural data
format.
Assign a value to each parameter using one the functions
nni_put_parm or
nni_put_parm_array.
Call nni_get_parm_info on
each parameter in the set. This fills the
parameter_description structures.
Pass the array of parameter_description
structures to the function nni_send_method.
After the call has been executed, extract the modified parameter
values from the parameter set using one of the
nni_get_parm
functions.
The parameters passed in rgDesc have the
following meaning:
The first parameter contains the object handle.
The second parameter must be initialized to the data type of the method return value. If the method does not have a return value, the second parameter remains not initialized. On return from the method call, this parameter contains the return value of the method.
The remaining parameters are the method parameters.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
szName |
Name of the method. |
iParm |
Number of parameters. Indicates the number of occurrences of the
array rgDesc. This is always 2 + the number of method
parameters.
|
rgDesc |
An array of parm_description structures
containing the parameters for the method. If the method does not expect
parameters, the caller still passes two parameters, the first for the object
handle and the second for the return value.
|
pExcep |
Pointer to a natural_exception structure.
If a Natural error occurs during execution of the method, this structure is
filled with Natural error information. The caller may specify a null pointer.
In this case no extended exception information is returned.
|
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_NO_MEMORY
|
|
| > 0 | Natural error number. |
int nni_get_property(void* pnni_func, const char* szName, int iParm, struct parameter_description* rgDesc, struct natural_exception* pExcep);
Retrieves a property value of a Natural object (an instance of a Natural class).
The function receives its parameters as an array of
parameter_description structures. The caller creates
these structures using NNI functions in the following way:
Use the function nni_create_parm or
nni_create_method_parm
to create a matching parameter set.
If you have used create_parm, use the functions
init_parm_* to initialize each parameter to the appropriate
Natural data format. If you have used create_method_parm, the
parameters are already initialized to the appropriate Natural data format.
Assign a value to each parameter using one the functions
nni_put_parm or
nni_put_parm_array.
Call nni_get_parm_info on
each parameter in the set. This fills the
parameter_description structures.
Pass the array of parameter_description
structures to the function nni_send_method.
After the call has been executed, extract the modified parameter
values from the parameter set using one of the
nni_get_parm
functions.
The parameters passed in rgDesc have the
following meaning:
The first parameter contains the object handle.
The second parameter is initialized to the data type of the property. On return from the property access, this parameter contains the property value.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
szName |
Name of the property. |
iParm |
Number of parameters. Indicates the number of occurrences of the
array rgDesc. This is always 2.
|
rgDesc |
An array of parm_description structures
containing the parameters for the property access. The caller always passes two
parameters, the first for the object handle and the second for the returned
property value.
|
pExcep |
Pointer to a natural_exception structure.
If a Natural error occurs during property access, this structure is filled with
Natural error information. The caller may specify a null pointer. In this case
no extended exception information is returned.
|
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_NO_MEMORY
|
|
| > 0 | Natural error number. |
int nni_set_property(void* pnni_func, const char* szName, int iParm, struct parameter_description* rgDesc, struct natural_exception* pExcep);
Assigns a property value to a Natural object (an instance of a Natural class).
The function receives its parameters as an array of
parameter_description structures. The caller creates
these structures using NNI functions in the following way:
Use the function nni_create_parm or
nni_create_prop_parm
to create a matching parameter set.
If you have used create_parm, use the functions
init_parm_* to initialize each parameter to the appropriate
Natural data format. If you have used create_prop_parm, the
parameters are already initialized to the appropriate Natural data format.
Assign a value to each parameter using one of the
nni_put_parm
functions.
Assign a value to each parameter using one the functions
nni_put_parm or
nni_put_parm_array.
Call nni_get_parm_info on
each parameter in the set. This fills the
parameter_description structures.
Pass the array of parameter_description
structures to the function nni_set_property.
The parameters passed in rgDesc have the
following meaning:
The first parameter contains the object handle.
The second parameter contains the property value.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
szName |
Name of the property. |
iParm |
Number of parameters. Indicates the number of occurrences of the
array rgDesc. This is always 2.
|
rgDesc |
An array of parm_description structures
containing the parameters for the property access. The caller always passes two
parameters, the first for the object handle and the second for the property
value.
|
pExcep |
Pointer to a natural_exception structure.
If a Natural error occurs during property access, this structure is filled with
Natural error information. The caller may specify a null pointer. In this case
no extended exception information is returned.
|
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_NO_MEMORY
|
|
| > 0 | Natural error number. |
int nni_delete_object(void* pnni_func, int iParm, struct parameter_description* rgDesc, struct natural_exception* pExcep);
Deletes a Natural object (an instance of a Natural class) created with
nni_create_object.
The function receives its parameters as a one-element array of
parameter_description structures. The caller creates the
structures using NNI functions in the following way:
Use the function nni_create_parm to create
parameter set with one element.
Use the function nni_init_parm_s to
initialize the parameter with the type HANDLE OF OBJECT.
Assign a value to the parameter using one the functions
nni_put_parm.
Call nni_get_parm_info on
this parameter. This fills the parameter_description
structure.
Pass the parameter_description structure to the
function nni_delete_object.
The parameters passed in rgDesc have the
following meaning:
The first (and only) parameter must be initialized with the data type
HANDLE OF OBJECT and contains the Natural object handle of the
object to be deleted.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
szName |
Name of the class. |
iParm |
Number of parameters. Indicates the number of occurrences of the
array rgDesc. This is always 1.
|
rgDesc |
An array of parm_description structures
containing the parameters for the object creation. The caller always passes one
parameter, which contains the object handle.
|
pExcep |
Pointer to a natural_exception structure.
If a Natural error occurs during object creation, this structure is filled with
Natural error information. The caller may specify a null pointer. In this case
no extended exception information is returned.
|
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_NO_MEMORY
|
|
| > 0 | Natural error number. |
int nni_create_parm(void* pnni_func, int iParm, void** pparmhandle);
Creates a set of parameters that can be passed to a Natural module.
The parameters contained in the set are not yet initialized to specific
Natural data types. Before using the parameter set in a call to
nni_callnat,
nni_create_object,
nni_send_method,
nni_set_property or
nni_get_property:
Initialize each parameter to the required Natural data type using one
of the functions nni_init_parm_s,
nni_init_parm_sa,
nni_init_parm_d
or nni_init_parm_da.
Assign a value to each parameter using one of the functions
nni_put_parm or
nni_put_parm_array.
Turn each parameter into a parm_description
structure using the function nni_get_parm_info.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
iParm |
Requested number of parameters. The maximum number of parameters is 32767. |
pparmhandle |
Points a to a pointer to a parameter set on return. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_ILL_PNUM
|
|
| > 0 | Natural error number. |
int nni_create_module_parm(void* pnni_func, char chType, const char* szName, void** pparmhandle);
Creates a set of parameters that can be used in a call to
nni_callnat. The
function enables an application to dynamically explore the signature of a
callable Natural module.
The parameters contained in the returned set are already initialized to
Natural data types according to the parameter data area of the specified
module. Before using the parameter set in a call to
nni_callnat:
Assign a value to each parameter using one of the functions
nni_put_parm or
nni_put_parm_array.
Turn each parameter into a parm_description
structure using the function nni_get_parm_info.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
chType |
Type of the Natural module. Always N (for
subprogram).
|
szName |
Name of the Natural module. |
pparmhandle |
Points a to a pointer to a parameter set on return. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
| > 0 | Natural error number. |
int nni_create_method_parm( void* pnni_func, const char* szClass, const char* szMethod, void** pparmhandle );
Creates a set of parameters that can be used in a call to
nni_send_method. The
function enables an application to dynamically explore the signature of a
method of a Natural class.
The returned parameter set contains not only the method parameters, but
also the other parameters required by nni_send_method. This
means: If the method has n parameters, the parameter
set contains n + 2 parameters.
The first parameter in the set is initialized to the data type
HANDLE OF OBJECT.
The second parameter in the set is initialized to the data type of the method return value. If the method does not have a return value, the second parameter is not initialized.
The remaining parameters in the set are initialized to the data types of the method parameters.
Before using the parameter set in a call to
nni_send_method:
Assign a value to each parameter using one of the functions
nni_put_parm or
nni_put_parm_array.
Turn each parameter into a parm_description
structure using the function nni_get_parm_info.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
szClass |
Name of the Natural class. |
szMethod |
Name of the Natural method. |
pparmhandle |
Points a to a pointer to a parameter set on return. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
| > 0 | Natural error number. |
int nni_create_prop_parm(void* pnni_func, const char* szClass, const char* szProp,void** pparmhandle);
Creates a set of parameters that can be used in a call to
nni_get_property or
nni_set_property. The
returned parameter set contains all parameters required by
nni_get_property or
nni_set_property. The
function enables an application to determine the data type of a property of a
Natural class.
The first parameter in the set is initialized to the data type
HANDLE OF OBJECT.
The second parameter in the set is initialized to the data type of the property.
Before using the parameter set in a call to
nni_get_property or
nni_set_property:
Assign a value to each parameter using one of the functions
nni_put_parm or
nni_put_parm_array.
Turn each parameter into a parm_description
structure using the function nni_get_parm_info.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
szClass |
Name of the Natural class. |
szProp |
Name of the Natural property. |
pparmhandle |
Points a to a pointer to a parameter set on return. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
| > 0 | Natural error number. |
int nni_parm_count( void* pnni_func, void* parmhandle, int* piParm )
The function retrieves the number of parameters in a parameter set.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
parmhandle |
Pointer to a parameter set. |
piParm |
Returns the number of parameters in the parameter set. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
int nni_init_parm_s(void* pnni_func, int iParm, void* parmhandle, char chFormat, int iLength, int iPrecision, int iFlags);
Initializes a parameter in a parameter set to a static data type.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
iParm |
Index of the parameter. The first parameter in the set has the index 0. |
parmhandle |
Pointer to a parameter set. |
chFormat |
Natural data type of the parameter. |
iLength |
Natural length of the parameter. |
iPrecision |
Number of decimal places (NNI_TYPE_NUM and
NNI_TYPE_PACK only).
|
iFlags |
Parameter flags. The following flags can be used:
|
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_ILL_PNUM
|
|
NNI_RC_NO_MEMORY
|
|
NNI_RC_BAD_FORMAT
|
|
NNI_RC_BAD_LENGTH
|
int nni_init_parm_sa (void* pnni_func, int iParm, void* parmhandle, char chFormat, int iLength, int iPrecision, int iDim, int* rgiOcc, int iFlags);
Initializes a parameter in a parameter set to an array of a static data type.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
iParm |
Index of the parameter. The first parameter in the set has the index 0. |
parmhandle |
Pointer to a parameter set. |
chFormat |
Natural data type of the parameter. |
iLength |
Natural length of the parameter. |
iPrecision |
Number of decimal places (NNI_TYPE_NUM and
NNI_TYPE_PACK only).
|
iDim |
Array dimension of the parameter. |
rgiOcc |
Three dimensional array of int values, indicating the occurrence count for each dimension. The occurrence count for unused dimensions must be specified as 0. |
iFlags |
Parameter flags. The following flags can be used:
NNI_FLG_*VAR* flags is set,
the array is an x-array. In each dimension only the lower bound or the upper
bound (not both) can be variable. Therefore for instance the flag
IF4_FLG_LBVAR_0 may not be combined with
IF4_FLG_UBVAR_0.
|
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_ILL_PNUM
|
|
NNI_RC_NO_MEMORY
|
|
NNI_RC_BAD_FORMAT
|
|
NNI_RC_BAD_LENGTH
|
|
NNI_RC_BAD_DIM
|
|
NNI_RC_BAD_BOUNDS
|
int nni_init_parm_d(void* pnni_func, int iParm, void* parmhandle, char chFormat, int iFlags);
Initializes a parameter in a parameter set to a dynamic data type.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
iParm |
Index of the parameter. The first parameter in the set has the index 0. |
parmhandle |
Pointer to a parameter set. |
chFormat |
Natural data type of the parameter (NNI_TYPE_ALPHA
or NNI_TYPE_BIN).
|
iFlags |
Parameter flags. The following flags can be used:
|
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_ILL_PNUM
|
|
NNI_RC_NO_MEMORY
|
|
NNI_RC_BAD_FORMAT
|
int nni_init_parm_da (void* pnni_func, int iParm, void* parmhandle, char chFormat, int iDim, int* rgiOcc, int iFlags);
Initializes a parameter in a parameter set to an array of a dynamic data type.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
iParm |
Index of the parameter. The first parameter in the set has the index 0. |
parmhandle |
Pointer to a parameter set. |
chFormat |
Natural data type of the parameter (NNI_TYPE_ALPHA
or NNI_TYPE_BIN).
|
iDim |
Array dimension of the parameter. |
rgiOcc |
Three dimensional array of int values, indicating the occurrence count for each dimension. The occurrence count for unused dimensions must be specified as 0. |
iFlags |
Parameter flags. The following flags can be used:
NNI_FLG_*VAR* flags is set,
the array is an x-array. In each dimension only the lower bound or the upper
bound (not both) can be variable. Therefore for instance the flag
IF4_FLG_LBVAR_0 may not be combined with
IF4_FLG_UBVAR_0.
|
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_ILL_PNUM
|
|
NNI_RC_NO_MEMORY
|
|
NNI_RC_BAD_FORMAT
|
|
NNI_RC_BAD_DIM
|
|
NNI_RC_BAD_BOUNDS
|
int nni_get_parm_info (void* pnni_func, int iParm, void* parmhandle, struct parameter_description* pDesc);
Returns detailed information about a specific parameter in a parameter set.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
iParm |
Index of the parameter. The first parameter in the set has the index 0. |
parmhandle |
Pointer to a parameter set. |
pDesc |
Parameter description structure. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_ILL_PNUM
|
int nni_get_parm(void* pnni_func, int iParm, void* parmhandle, int iBufferLength, void* pBuffer);
Returns the value of a specific parameter in a parameter set. The value
is returned in the buffer at the address specified in
pBuffer, with the size specified in
iBufferLength. On successful return, the buffer contains
the data in Natural internal format. See
Natural Data
Types on how to interpret the contents of the buffer.
If the length of the parameter according to the Natural data type is
greater than iBufferLength, Natural truncates the data
to the given length and returns the code NNI_RC_DATA_TRUNC. The
caller can use the function nni_get_parm_info to
request the length of the parameter value in advance.
If the length of the parameter according to the Natural data type is
smaller than iBufferLength, Natural fills the buffer
according to the length of the parameter and returns the length of the copied
data in the return code.
If the parameter is an array, the function returns the whole array in
the buffer. This makes sense only for fixed size arrays of fixed size elements,
because in other cases the caller cannot interpret the contents of the buffer.
In order to retrieve an individual occurrence of an arbitrary array use the
function nni_get_parm_array.
If no memory of the size specified in
iBufferLength is allocated at the address specified in
pBuffer, the results of the operation are unpredictable.
Natural only checks that pBuffer is not null.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
iParm |
Index of the parameter. The first parameter in the set has the index 0. |
parmhandle |
Pointer to a parameter set. |
iBufferLength |
Length of the buffer specified in
pBuffer.
|
pBuffer |
Buffer in which the value is returned. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_ILL_PNUM
|
|
NNI_RC_DATA_TRUNC
|
|
| = n, where n > 0 | Successful operation, but only n bytes were returned in the buffer. |
int nni_get_parm_array(void* pnni_func, int parmnum, void* parmhandle, int iBufferLength, void* pBuffer, int* rgiInd);
Returns the value of a specific occurrence of a specific array parameter
in a parameter set. The only difference to nni_get_parm is that array
indices can be specified. The indices for unused dimensions must be specified
as 0.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
iParm |
Index of the parameter. The first parameter in the set has the index 0. |
parmhandle |
Pointer to a parameter set. |
iBufferLength |
Length of the buffer specified in
pBuffer.
|
pBuffer |
Buffer in which the value is returned. |
rgiInd |
Three dimensional array of int values, indicating a specific array occurrence. The indices start with 0. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_ILL_PNUM
|
|
NNI_RC_DATA_TRUNC
|
|
NNI_RC_NOT_ARRAY
|
|
NNI_RC_BAD_INDEX_0
|
|
NNI_RC_BAD_INDEX_1
|
|
NNI_RC_BAD_INDEX_2
|
|
| = n, where n > 0 | Successful operation, but only n bytes were returned. |
int nni_get_parm_array_length(void* pnni_func, int iParm, void* parmhandle, int* piLength, int* rgiInd);
Returns the length of a specific occurrence of a specific array parameter in a parameter set.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
iParm |
Index of the parameter. The first parameter in the set has the index 0. |
parmhandle |
Pointer to a parameter set. |
piLength |
Pointer to an int in which the length of the value is returned. |
rgiInd |
Three dimensional array of int values, indicating a specific array occurrence. The indices start with 0. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_ILL_PNUM
|
|
NNI_RC_DATA_TRUNC
|
|
NNI_RC_NOT_ARRAY
|
|
NNI_RC_BAD_INDEX_0
|
|
NNI_RC_BAD_INDEX_1
|
|
NNI_RC_BAD_INDEX_2
|
int nni_put_parm(void* pnni_func, int iParm, void* parmhandle, int iBufferLength, const void* pBuffer);
Assigns a value to a specific parameter in a parameter set. The value is
passed to the function in the buffer at the address specified in
pBuffer, with the size specified in
iBufferLength. See
Natural Data
Types on how to prepare the contents of the buffer.
If the length of the parameter according to the Natural data type is smaller than the given buffer length, the data will be truncated to the length of the parameter. The rest of the buffer will be ignored. If the length of the parameter according to the Natural data type is greater than the given buffer length, the data will copied only to the given buffer length, the rest of the parameter value stays unchanged. See Natural Data Types on the internal length of Natural data types.
If the parameter is a dynamic variable, it is automatically resized according to the given buffer length.
If the parameter is an array, the function expects the whole array in
the buffer. This makes sense only for fixed size arrays of fixed size elements,
because in other cases the caller cannot provide the correct contents of the
buffer. In order to assign a value to an individual occurrence of an arbitrary
array use the function nni_put_parm_array.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
iParm |
Index of the parameter. The first parameter in the set has the index 0. |
parmhandle |
Pointer to a parameter set. |
iBufferLength |
Length of the buffer specified in
pBuffer.
|
pBuffer |
Buffer in which the value is passed. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_ILL_PNUM
|
|
NNI_RC_WRT_PROT
|
|
NNI_RC_DATA_TRUNC
|
|
NNI_RC_NO_MEMORY
|
|
| = n, where n > 0 | Successful operation, but only n bytes of the buffer were used. |
int nni_put_parm_array(void* pnni_func, int iParm, void* parmhandle, int iBufferLength, const void* pBuffer, int* rgiInd);
Assigns a value to a specific occurrence of a specific array parameter
in a parameter set. The only difference to nni_get_parm is that array
indices can be specified. The indices for unused dimensions must be specified
as 0.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
iParm |
Index of the parameter. The first parameter in the set has the index 0. |
parmhandle |
Pointer to a parameter set. |
iBufferLength |
Length of the buffer specified in
pBuffer.
|
pBuffer |
Buffer in which the value is passed. |
rgiInd |
Three dimensional array of int values, indicating a specific array occurrence. The indices start with 0. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_ILL_PNUM
|
|
NNI_RC_WRT_PROT
|
|
NNI_RC_DATA_TRUNC
|
|
NNI_RC_NO_MEMORY
|
|
NNI_RC_NOT_ARRAY
|
|
NNI_RC_BAD_INDEX_0
|
|
NNI_RC_BAD_INDEX_1
|
|
NNI_RC_BAD_INDEX_2
|
|
| = n, where n > 0 | Successful operation, but only n bytes of the buffer were used. |
int nni_resize_parm_array(void* pnni_func, int iParm, void* parmhandle, int* rgiOcc);
Changes the occurrence count of a specific x-array parameter in a parameter set. For an n-dimensional array an occurrence count must be specified for all n dimensions. If the dimension of the array is less than 3, the value 0 must be specified for the not used dimensions.
The function tries to resize the occurrence count of each dimension either by changing the lower bound or the upper bound, whatever is appropriate for the given x-array.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
iParm |
Index of the parameter. The first parameter in the set has the index 0. |
parmhandle |
Pointer to a parameter set. |
rgiOcc |
Three dimensional array of int values, indicating the new occurrence count of the array. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
NNI_RC_ILL_PNUM
|
|
NNI_RC_WRT_PROT
|
|
NNI_RC_DATA_TRUNC
|
|
NNI_RC_NO_MEMORY
|
|
NNI_RC_NOT_ARRAY
|
|
NNI_RC_NOT_RESIZABLE
|
|
| > 0 | Natural error number. |
int nni_delete_parm(void* pnni_func, void* parmhandle);
Deletes the specified parameter set.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
parmhandle |
Pointer to a parameter set. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
int nni_from_string(void* pnni_func, const char* szString, char chFormat, int iLength, int iPrecision, int iBufferLength, void* pBuffer);
Converts the string representation of a Natural P, N, D or T value into
the internal representation of the value, as it is used in the functions
nni_get_parm,
nni_get_parm_array,
nni_put_parm and
nni_put_parm_array.
The string representations of these Natural data types look like this:
| Format | String representation |
|---|---|
| P, N | For example, -3.141592, where the decimal character
defined in the DC parameter is
used.
|
| D | Date format as defined in the
DTFORM
parameter, (e. g. "2004-07-06", if
DTFORM=I).
|
| T | Date format as defined in the DTFORM
parameter, combined with a Time value in the form hh:ii:ss:t (e. g.
2004-07-06 11:30:42:7, if DTFORM=I) or Time
value in the form hh:ii:ss:t (e. g. 11:30:42:7).
|
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
szString |
String representation of the value. |
chFormat |
Natural data type of the value. |
iLength |
Natural length of the value. The total number of significant
digits in the case of NNI_TYPE_NUM and NNI_TYPE_PACK,
0 otherwise.
|
iPrecision |
Number of decimal places in the case of
NNI_TYPE_NUM and NNI_TYPE_PACK, 0 otherwise.
|
iBufferLength |
Length of the buffer provided in
pBuffer.
|
pBuffer |
Buffer that contains the internal representation of the value on return. The buffer must be large enough to hold the internal Natural representation of the value. The required sizes are documented in Format and Length of User-Defined Variables. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
| > 0 | Natural error number |
int nni_to_string(void* pnni_func, int iBufferLength, const void* pBuffer, char chFormat, int iLength, int iPrecision, int iStringLength, char* szString);
Converts the internal representation of a Natural P, N, D or T value, as
it is used in the functions nni_get_parm,
nni_get_parm_array,
nni_put_parm and
nni_put_parm_array,
into a the string representation.
The string representations of these Natural data types look as described
with the function nni_from_string.
| Parameter | Meaning |
|---|---|
pnni_func |
Pointer to an NNI interface instance. |
iBufferLength |
Length of the buffer provided in
pBuffer.
|
pBuffer |
Buffer that contains the internal representation of the value. The required sizes are documented in Format and Length of User-Defined Variables. |
chFormat |
Natural data type of the value. |
iLength |
Natural length of the value. The total number of significant
digits in the case of NNI_TYPE_NUM and NNI_TYPE_PACK,
0 otherwise.
|
iPrecision |
Number of decimal places in the case of
NNI_TYPE_NUM and NNI_TYPE_PACK, 0 otherwise.
|
iStringLength |
Length of the string buffer provided in
szString including the terminating zero.
|
szString |
String buffer that contains the string representation of the value on return. The string buffer must be large enough to hold the external representation including the terminating zero. |
The meaning of the return codes is explained in the section Return Codes.
| Return Code | Remark |
|---|---|
NNI_RC_OK
|
|
NNI_RC_NOT_INIT
|
|
NNI_RC_PARM_ERROR
|
|
| > 0 | Natural error number |