Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > E

EvmVarGet(3)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

EvmVarGet(), EvmVarGetOpaque(), EvmVarGetString(), EvmVarGetType(), EvmVarGetXxx(), EvmVarListFree(), EvmVarListGet(), EvmVarRelease(), EvmVarSet(), EvmVarSetOpaque(), EvmVarSetStringI18N(), EvmVarSetXxx() — manipulate event variables

SYNOPSIS

#include <evm/evm.h> EvmStatus_t EvmVarGet( EvmEvent_t event, EvmVarName_t v_name, EvmVarStruct_t *var ); EvmStatus_t EvmVarGetOpaque( EvmEvent_t event, EvmVarName_t v_name, EvmOpaque_t *item_value, EvmSize_t *size ); EvmStatus_t EvmVarGetString( EvmEvent_t event, EvmVarName_t v_name, EvmString_t *item_value, EvmI18NMsgId_t *msg_id ); 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 EvmVarListFree( EvmVarList_t varlist ); EvmStatus_t EvmVarListGet( EvmEvent_t event, EvmCount_t *var_count, EvmVarList_t *varList ); EvmStatus_t EvmVarRelease( EvmVarStruct_t *var ); 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 EvmVarSetOpaque( EvmEvent_t event, EvmVarName_t v_name, const EvmOpaque_t item_value, EvmSize_t size ); EvmStatus_t EvmVarSetStringI18N( EvmEvent_t event, EvmVarName_t v_name, const EvmString_t item_value, EvmI18NMsgId_t msg_id ); EvmStatus_t EvmVarSetXxx( EvmEvent_t event, EvmVarName_t v_name, const evm_type item_value );

Library

EVM Support Library (libevm.so).

Parameters

event

The event to be processed.

v_name

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.

type

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 EvmTYPE_UINT64 EvmTYPE_FLOAT EvmTYPE_DOUBLE EvmTYPE_STRING EvmTYPE_OPAQUE

For EvmVarGetType(), the type operand is a returned value.

item_value

The value to be stored in the variable indicated by v_name.

msg_id

For a string variable being set in an internationalized event, msg_id may contain an I18N (internationalization) 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 EvmItemSet(3) manpage).

The msg_id operand is ignored for variables whose type is not EvmTYPE_STRING.

size

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 variable types, the size is ignored.

var

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.

var_count

This is the number of names in the var_list obtained by EvmVarListGet(), not including the terminating NULL pointer.

varlist

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 terminated 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 EvmVarSet() routine. Using these routines, a single call can set a variable of any type. To use these routines, replace the Xxx() in the routine name with the required type name, and supply a value of the corresponding type as the item_value operand. 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. Use EvmVarSetOpaque() to set an opaque variable. Each of these routines requires one more operand 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. These routines can retrieve a variable of a specific type with a single call. To use these routines, 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 operand if you do not want to receive an I18N message-ID. Use EvmVarGetOpaque() to retrieve an opaque variable. Each of these routines requires one more operand than the others in this group.

Note that EvmVarGetString() and EvmVarGetOpaque() return their variable values in heap memory. Use free() to free this space when it is no longer needed.

The EvmVarRelease() routine releases any storage space allocated when the specified var was retrieved from an event using EvmVarGet(). 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. Do 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.

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

RETURN VALUE

EvmERROR_NONE

The operation completed without error.

EvmERROR_INVALID_ARGUMENT

One of the arguments to the function is invalid.

EvmERROR_INVALID_VALUE

A value in a structure member is invalid.

EvmERROR_NO_MEMORY

An operation failed because an attempt to acquire heap memory failed.

EvmERROR_NOT_PRESENT

A request specified an item or variable name component in an itemList or a varList that is not part of the event being processed.

ERRORS

The value of errno is not set.

SEE ALSO

Event Management

EVM(5).

EVM Events

EvmEvent(5)

EVM Programmer's Guide.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.