Version 6.3.8 for OpenVMS
Quick Reference

 —  Programming Guide  —

Interface Functions

For detailed information on the individual functions, use the selection box on the right.


nni_get_interface

Syntax

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.

Parameters

Parameter Meaning
iVersion Interface version number. (NNI_VERSION_nn or NNI_VERSION_CURR).
ppnni_func Points to an NNI interface instance on return.

Return Codes

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  

Top of page

nni_free_interface

Syntax

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.

Parameters

Parameter Meaning
pnni_func Pointer to an NNI interface instance.

Return Codes

The meaning of the return codes is explained in the section Return Codes.

Return Code Remark
NNI_RC_OK  

Top of page

nni_initialize

Syntax

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.

When initalizing 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.

Parameters

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.

Return Codes

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

Warnings that occur during session initialization are ignored.

> 0 Natural error number.

Top of page

nni_is_initialized

Syntax

int nni_is_initialized( void* pnni_func, int* piIsInit );

The function checks if the interface instance contains an initialized Natural session.

Parameters

Parameter Meaning
pnni_func Pointer to an NNI interface instance.
piIsInit Returns 0, if no Natural session is initialized, a non-zero value otherwise.

Return Codes

The meaning of the return codes is explained in the section Return Codes.

Return Code Remark
NNI_RC_OK  
NNI_RC_PARM_ERROR  

Top of page

nni_uninitialize

Syntax

int nni_uninitialize(void* pnni_func);

The function uninitializes the Natural session hosted by the given interface instance.

Parameters

Parameter Meaning
pnni_func Pointer to an NNI interface instance.

Return Codes

The meaning of the return codes is explained in the section Return Codes.

Return Code Remark
NNI_RC_OK  

Top of page

nni_enter

Syntax

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 eclusive access to the interface instance by calling nni_leave.

Parameters

Parameter Meaning
pnni_func Pointer to an NNI interface instance.

Return Codes

The meaning of the return codes is explained in the section Return Codes.

Return Code Remark
NNI_RC_OK  

Top of page

nni_try_enter

Syntax

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.

Parameters

Parameter Meaning
pnni_func Pointer to an NNI interface instance.

Return Codes

The meaning of the return codes is explained in the section Return Codes.

Return Code Remark
NNI_RC_OK  
NNI_RC_LOCKED  

Top of page

nni_leave

Syntax

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.

Parameters

Parameter Meaning
pnni_func Pointer to an NNI interface instance.

Return Codes

The meaning of the return codes is explained in the section Return Codes.

Return Code Remark
NNI_RC_OK  

Top of page

nni_logon

Syntax

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.

Parameters

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..

Return Codes

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.

Top of page

nni_logoff

Syntax

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.

Parameters

Parameter Meaning
pnni_func Pointer to an NNI interface instance.

Return Codes

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.

Top of page

nni_callnat

Syntax

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:

Parameters

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.

Return Codes

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.

Top of page

nni_create_object

Syntax

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:

The parameters passed in rgDesc have the following meaning:

Parameters

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.

Return Codes

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.

Top of page

nni_send_method

Syntax

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:

The parameters passed in rgDesc have the following meaning:

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.

Return Codes

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.

Top of page

nni_get_property

Syntax

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:

The parameters passed in rgDesc have the following meaning:

Parameters

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.

Return Codes

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.

Top of page

nni_set_property

Syntax

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:

The parameters passed in rgDesc have the following meaning:

Parameters

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.

Return Codes

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.

Top of page

nni_delete_object

Syntax

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:

The parameters passed in rgDesc have the following meaning:

Parameters

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.

Return Codes

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.

Top of page

nni_create_parm

Syntax

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:

Parameters

Parameter Meaning
pnni_func Pointer to an NNI interface instance.
iParm Requested number of parameters. The maxinum number of parameters is 32767.
pparmhandle Points a to a pointer to a parameter set on return.

Return Codes

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.

Top of page

nni_create_module_parm

Syntax

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:

Parameters

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.

Return Codes

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.

Top of page

nni_create_method_parm

Syntax

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.

Before using the parameter set in a call to nni_send_method:

Parameters

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.

Return Codes

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.

Top of page

nni_create_prop_parm

Syntax

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.

Before using the parameter set in a call to nni_get_property or nni_set_property:

Parameters

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.

Return Codes

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.

Top of page

nni_parm_count

Syntax

int nni_parm_count( void* pnni_func, void* parmhandle, int* piParm )

The function retrieves the number of parameters in a parameter set.

Parameters

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.

Return Codes

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  

Top of page

nni_init_parm_s

Syntax

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.

Parameters

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:

NNI_FLG_PROTECTED

Return Codes

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  

Top of page

nni_init_parm_sa

Syntax

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.

Parameters

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_PROTECTED
NNI_FLG_LBVAR_0
NNI_FLG_UBVAR_0
NNI_FLG_LBVAR_1
NNI_FLG_UBVAR_1
NNI_FLG_LBVAR_2
NNI_FLG_UBVAR_2

If one of the 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.

Return Codes

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  

Top of page

nni_init_parm_d

Syntax

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.

Parameters

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:

NNI_FLG_PROTECTED

Return Codes

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  

Top of page

nni_init_parm_da

Syntax

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.

Parameters

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_PROTECTED
NNI_FLG_LBVAR_0
NNI_FLG_UBVAR_0
NNI_FLG_LBVAR_1
NNI_FLG_UBVAR_1
NNI_FLG_LBVAR_2
NNI_FLG_UBVAR_2

If one of the 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.

Return Codes

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  

Top of page

nni_get_parm_info

Syntax

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.

Parameters

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.

Return Codes

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  

Top of page

nni_get_parm

Syntax

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 adress specified in pBuffer, the results of the operation are unpredictable. Natural only checks that pBuffer is not null.

Parameters

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.

Return Codes

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.

Top of page

nni_get_parm_array

Syntax

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.

Parameters

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.

Return Codes

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.

Top of page

nni_get_parm_array_length

Syntax

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.

Parameters

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.

Return Codes

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  

Top of page

nni_put_parm

Syntax

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.

Parameters

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.

Return Codes

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.

Top of page

nni_put_parm_array

Syntax

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.

Parameters

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.

Return Codes

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.

Top of page

nni_resize_parm_array

Syntax

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.

Parameters

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.

Return Codes

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.

Top of page

nni_delete_parm

Syntax

int nni_delete_parm(void* pnni_func, void* parmhandle);

Deletes the specified parameter set.

Parameters

Parameter Meaning
pnni_func Pointer to an NNI interface instance.
parmhandle Pointer to a parameter set.

Return Codes

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  

Top of page

nni_from_string

Syntax

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

Parameters

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.

Return Codes

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

Top of page

nni_to_string

Syntax

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.

Parameters

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.

Return Codes

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

Top of page