8 Programming own composit function
8.1 CORBA_Environment setting
Here is the complete definition of the CORBA_Environment structure, defined in file "ic.h" :
/* Environment definition */ typedef struct { /*----- CORBA compatibility part ---------------------------------------*/ CORBA_exception_type _major; /* Exception tag, initially set to CORBA_NO_EXCEPTION */ /*----- External Implementation part - initiated by the user -----------*/ int _fd; /* File descriptor */ char *_inbuf; /* Pointer to buffer for input */ int _inbufsz; /* Max size of input buffer */ char *_outbuf; /* Pointer to buffer for output */ char _regname[256]; /* Pointer for registered name */ erlang_pid *_to_pid; /* Process identity for caller */ erlang_pid *_from_pid; /* Process identity for callee */ /*----- Internal Implementation part - used by the server/client -------*/ int _iin; /* Index for input buffer */ int _iout; /* Index for output buffer */ char _operation[256]; /* Pointer for operation name */ int _received; /* Used to count parameters */ erlang_pid _caller; /* Used to identify the caller */ erlang_ref _unique; /* Used to identify the call */ CORBA_char *_exc_id; /* Exception id field */ void *_exc_value; /* Exception value field */ } CORBA_Environment; #endifThe structure is semantically divided into three areas :
- The Corba Compatibility area, the area demanded by the standard OMG IDL mapping v2.0
- The External Implementation area, the implementation part used for standard implementation of the generated client/server model.
- The Internal Implementation area, the implementation part usefull for those who wish to define their own composit/switch functions.
Observe that the advanced user that wishes to write it's own composit functions have to have good knowledge of Erl_interface or/and EI-* functions.
8.2 The Corba Compatibility area of CORBA_Environment
Containes only one (1) field, the _major which is defined as a CORBA_Exception_type. The CORBA_Exception type is forced to be an integer type due to implementation details and in the current version can be one of :
- CORBA_NO_EXCEPTION, by default equal to 0, can be set by the application programmer to another value.
- CORBA_SYSTEM_EXCEPTION, by default equal to -1, can be set by the application programmer to another value.
The current definition of these values looks like :
#ifndef CORBA_NO_EXCEPTION #define CORBA_NO_EXCEPTION 0 #endif #ifndef CORBA_SYSTEM_EXCEPTION #define CORBA_SYSTEM_EXCEPTION -1 #endif8.3 The External Implementation area of CORBA_Environment
This area contains seven (7) fields :
- int _fd - a file descriptor returned from erl_connect. Used for connection setting.
- char* _inbuf - pointer to a buffer used for input.
- int _inbufsz - maximum size of input buffer. Used only for connection setting under initialization of the Erl_Interface function ei_receive_encoded/4. Observe that this is a guard for received messages ONLY for the generated composit functions. The advanced user that wish to define it's own composit functions have to place own checks, use for this.
- char* _outbuf - pointer to a buffer used for output. Observe that no checks are done that the buffer overflows, it is the responsibility of the user to guarantee this.
- char regname[256] - a registered name for a process.
- erlang_pid* _to_pid - an erlang process identifier, is only used if the registered_name parameter is the empty string.
- erlang_pid* _from_pid - your own process id so the answer can be returned
8.4 The Internal Implementation area of CORBA_Environment
This area contains eight (8) fields :
- int _iin - Index for input buffer. Initially set to zero. Updated to agree with the length of the received encoded message.
- int _iout - Index for output buffer Initially set to zero. Updated to agree with the length of the message encoded to the communication counterpart.
- char _operation[256] - Pointer for operation name Set to the operation to be called.
- int _received - Used to count parameters. Initially set to zero.
- erlang_pid _caller - Used to identify the caller. Initiated to a value that identifies the caller.
- erlang_ref _unique - Used to identify the call. Set to a default value in the case of generated composit functions.
- CORBA_char *_exc_id - Exception id field. Initially set to NULL to agree with the initial value of _major (CORBA_NO_EXCEPTION).
- void *_exc_value - Exception value field Initially set to NULL to agree with the initial value of _major (CORBA_NO_EXCEPTION).
The advanced user that defines it's own composit/switch functions have to update/support these values at a way similat to the use of these in the generated code.
8.5 Setting System Exceptions
If the advanced user wishes to set own system exceptions at critical positions on the code, it is strongly recommended to use one of the current values :
- CORBA_NO_EXCEPTION on success The value of the _exc_id field should be then set to NULL The value of the _exc_value field should be then set to NULL
- CORBA_SYSTEM_EXCEPTION on system failure The value of the _exc_id field should be then set to one of the values defined in "ic.h" :
#define UNKNOWN "UNKNOWN" #define BAD_PARAM "BAD_PARAM" #define NO_MEMORY "NO_MEMORY" #define IMPL_LIMIT "IMP_LIMIT" #define COMM_FAILURE "COMM_FAILURE" #define INV_OBJREF "INV_OBJREF" #define NO_PERMISSION "NO_PERMISSION" #define INTERNAL "INTERNAL" #define MARSHAL "MARSHAL" #define INITIALIZE "INITIALIZE" #define NO_IMPLEMENT "NO_IMPLEMENT" #define BAD_TYPECODE "BAD_TYPECODE" #define BAD_OPERATION "BAD_OPERATION" #define NO_RESOURCES "NO_RESOURCES" #define NO_RESPONSE "NO_RESPONSE" #define PERSIST_STORE "PERSIST_STORE" #define BAD_INV_ORDER "BAD_INV_ORDER" #define TRANSIENT "TRANSIENT" #define FREE_MEM "FREE_MEM" #define INV_IDENT "INV_IDENT" #define INV_FLAG "INV_FLAG" #define INTF_REPOS "INTF_REPOS" #define BAD_CONTEXT "BAD_CONTEXT" #define OBJ_ADAPTER "OBJ_ADAPTER" #define DATA_CONVERSION "DATA_CONVERSION" #define OBJ_NOT_EXIST "OBJECT_NOT_EXIST"The value of the _exc_value field should be then set to a string that explains the problem in an informative way. The user should use the functions CORBA_exc_set/4 and CORBA_exception_free/1 to free the exception. The user have to use CORBA_exception_id/1 and CORBA_exception_value/1 to access exception information. Prototypes for these functions are declared in "ic.h"
8.6 Guidlines for the advanced user :
Here are some guidelines for the composit function programmer:
- Try to define buffers for input/output that are big enough to host the coresponding data.
- Always set the _inbufsz field to the value equal to the size of _inbuf field.
- Set the exceptions by using the function CORBA_exc_set/4
- Set exceptions only when really needed. Do not overuse system exceptions.
- Always free the CORBA_Environment exception fields by use of CORBA_exception_free/1 after a system failure.