EvmVarSet(3)						     Library Functions Manual						      EvmVarSet(3)

NAME

       EvmVarSet,  EvmVarSetXxx,  EvmVarSetStringI18N,	EvmVarSetOpaque, EvmVarGet, EvmVarGetType, EvmVarGetXxx, EvmVarGetString, EvmVarGetOpaque,
       EvmVarRelease, EvmVarListGet, EvmVarListFree - Manipulate event variables

LIBRARY

       EVM Support Library (libevm.so, libevm.a)

SYNOPSIS

       #include <evm/evm.h>

       EvmStatus_t EvmVarSet(
	       EvmEvent_t event,
	       EvmVarName_t v_name,
	       EvmVarType_t type,
	       EvmVarValue_t item_value,
	       EvmI18NMsgId_t msg_id,
	       EvmSize_t size);

       EvmStatus_t EvmVarSetXxx(
	       EvmEvent_t event,
	       EvmVarName_t v_name,
	       const evm_type item_value);

       EvmStatus_t EvmVarSetStringI18N(
	       EvmEvent_t event,
	       EvmVarName_t v_name,
	       const EvmString_t item_value,
	       EvmI18NMsgId_t msg_id);

       EvmStatus_t EvmVarSetOpaque(
	       EvmEvent_t event,
	       EvmVarName_t v_name,
	       const EvmOpaque_t item_value,
	       EvmSize_t size);

       EvmStatus_t EvmVarGet(
	       EvmEvent_t event,
	       EvmVarName_t v_name,
	       EvmVarStruct_t *var);

       EvmStatus_t EvmVarGetType(
	       EvmEvent_t event,
	       EvmVarName_t v_name,
	       EvmVarType_t *type);

       EvmStatus_t EvmVarGetXxx(
	       EvmEvent_t event,
	       EvmVarName_t v_name,
	       evm_type *item_value);

       EvmStatus_t EvmVarGetString(
	       EvmEvent_t event,
	       EvmVarName_t v_name,
	       EvmString_t *item_value,
	       EvmI18NMsgId_t *msg_id);

       EvmStatus_t EvmVarGetOpaque(
	       EvmEvent_t event,
	       EvmVarName_t v_name,
	       EvmOpaque_t *item_value,
	       EvmSize_t *size);

       EvmStatus_t EvmVarRelease(
	       EvmVarStruct_t *var);

       EvmStatus_t EvmVarListGet(
	       EvmEvent_t event,
	       EvmCount_t *var_count,
	       EvmVarList_t *varList);

       EvmStatus_t EvmVarListFree(
	       EvmVarList_t varlist);

OPERANDS

       The event to be processed.  The name of a variable in the event for which data is to be set or obtained.

	      For EvmVarSet(), if the named variable exists, the associated data is modified.  If the variable does not exist, it is  created  and
	      added  to the event.  The value to be stored is passed in item_value.  The enumeration constant for the type of the item_value to be
	      stored in the variable indicated by v_name.  Possible values for this field are:

	      EvmTYPE_BOOLEAN, EvmTYPE_CHAR, EvmTYPE_INT16, EvmTYPE_INT32,  EvmTYPE_INT64,  EvmTYPE_UINT8,  EvmTYPE_UINT16,  EvmTYPE_UINT32,  Evm-
	      TYPE_UINT64, EvmTYPE_FLOAT, EvmTYPE_DOUBLE, EvmTYPE_STRING, EvmTYPE_OPAQUE

	      For  EvmVarGetType(), this parameter is a returned value.  The value to be stored in the variable indicated by v_name.  For a string
	      variable being set in an internationalized event, this argument may contain an I18N message identifier corresponding to the value of
	      the  variable.   The  identifier	must refer to a message in the catalog and message set associated with the event (see the EvmItem-
	      Set(3) reference page).  This parameter is ignored for variables whose type is not  EvmTYPE_STRING.   The  size  of  the	associated
	      item_value  in bytes.  The caller must specify the correct size when setting a variable of type EvmTYPE_OPAQUE.  For all other vari-
	      able types, the size is ignored.	For the EvmVarGet() routine, this is a pointer to the location where the  output  data	is  to	be
	      stored.

	      For the EvmVarRelease() routine, this is a pointer to the storage space to be released.  This is the number of names in the var_list
	      obtained by EvmVarListGet(), not including the terminating NULL pointer.	On return from the EvmVarListGet() routine, this is a list
	      of pointers to the names of the variables associated with the event.  The last item in the list is a NULL pointer.

	      For  the	EvmVarListFree()  routine, this is a list of names of variables for which memory should be freed.  The list must be termi-
	      nated by a NULL pointer.

DESCRIPTION

       The EvmVarSet() routine sets the value of a variable data item, indicated by v_name, in an event.  This routine is used both for  adding  a
       variable and for altering its value.  If the v_name variable is not already present in the event, it is added.

       The  EvmVarSetXxx(), EvmVarSetStringI18N() and EvmVarSetOpaque() routines offer a simpler means of setting a variable than the generic Evm-
       VarSet() routine.  Using these routines, you can set a variable of any type with a single call.	To use them, replace the Xxx() in the rou-
       tine  name  with the required type name, and supply a value of the corresponding type as the item_value parameter.  The following types are
       supported:

       Boolean, Char, Int16, Int32, Int64, Uint8, Uint16, Uint32, Uint64, Float, Double, String

       Use EvmVarSetStringI18N() to set a string variable with a non-zero I18N message-ID, and EvmVarSetOpaque() to set an opaque variable.   Each
       of these routines requires one more parameter than the others in this group.

       The  EvmVarGet()  routine  returns  the event variable indicated by v_name in the var variable.	The caller must free any space used by the
       variable by calling EvmVarRelease().

       The EvmVarGetType() routine returns the type of the named variable.

       The EvmVarGetXxx(), EvmVarGetString() and EvmVarGetOpaque() routines offer a simpler means of retrieving a variable value than the  generic
       EvmVarGet()  routine.   Using  these routines, you can retrieve a variable of a specific type with a single call.  To use them, replace the
       Xxx() in the routine name with the required type name, and supply a pointer to a location of  the  corresponding  type  as  the	item_value
       pointer.  Refer to the description of EvmVarSetXxx() above for details of the supported types.

       Use  EvmVarGetString()  to  retrieve a string variable, specifying NULL for the msg_id parameter if you do not want to receive an I18N mes-
       sage-ID.  Use EvmVarGetOpaque() to retrieve an opaque variable.	Each of these routines requires one more parameter than the others in this
       group.

       Note that EvmVarGetStringI18N(), EvmVarGetStringI18N() and EvmVarGetOpaque() all return their variable values in heap memory.  You must use
       free() to free this space when you have finished with it.

       The EvmVarRelease() routine releases any storage space that was allocated when the specified var was retrieved from an event using  EvmVar-
       Get().	It  is	important that this routine is called when the variable is no longer needed, to ensure that all memory associated with the
       variable is released.  You must not use this routine to release variables retrieved with any of the EvmVarGetXxx() routines.

       The EvmVarListGet() routine returns, in the varList reference argument, a pointer to an array of pointers to names  of  all  the  variables
       contained  in  the event.  The last entry in the array is a NULL pointer.  The var_count argument receives the number of names in the list,
       not counting the terminating null value.  The caller must free the memory used by the list by calling EvmVarListFree().

       The EvmVarListFree() routine frees the memory used by a variable list (varList).

NOTES

       The caller must specify the size when adding an opaque variable to an event.

RESTRICTIONS

       To avoid memory leakage, memory that is supplied to the caller from API routines must be freed with the appropriate routine.

RETURN VALUES

       The operation was completed without error.  One of the arguments to the function was invalid.  A value in a structure  member  is  invalid.
       An  operation  failed because an attempt to acquire heap memory failed.	A request specified an item or variable name component in an item-
       List or a varList that is not part of the event being processed.

ERRORS

       None

FILES

       None

SEE ALSO

       Event Management: EVM(5)

       EVM Events: EvmEvent(5)

       Common Desktop Environment: Programmer's Guide delim off

																      EvmVarSet(3)