smc_get_command_info

Description

Retrieves detailed information about an alarm or error notification.

Syntax

SMC_RETURN_CODE smc_get_command_info 
 (SMC_CONNECT_ID           clientId,
 	SMC_COMMAND_ID           commandId,
 	SMC_INFO_TYPE            infoType,
 	SMC_VALUE_UNIONP         infoValue,
 	SMC_SIZETP               outputLengthHandle)

Parameters

clientId: identifies the connection.

commandId: identifies an invocation of a callback function.

infoType: describes the type of requested information. See “Data available for alarm callbacks”.

infoValue: pointer to an SMC_VALUE_UNION structure receiving the value of infoType.

outputLengthHandle: a pointer to an integer variable. Upon a successful call to smc_get_command_info, the Monitor Client Library writes into this variable. The actual length, in bytes, of the data to be copied into *infoValue (not including the null-terminator byte). If the infoValue datatype is not SMC_CHARP, this parameter is ignored. Pass null if the information is not desired.

Returns

Return value	Indicates
SMC_RET_SUCCESS	Function succeeded.
SMC_RET_FAILURE	Function failed.
SMC_RET_INVALID_API_FUNCTION	Invalid use of obsolete and replacement functions within the same program.
SMC_RET_INVALID_COMMAND	Instance of command does not exist.
SMC_RET_INVALID_CONNECT	Connection does not exist.
SMC_RET_INVALID_INFOTYPE	Invalid context for requested information type.
SMC_RET_INVALID_PARAMETER	Invalid parameter value.

Examples

Example 1

This example assumes that:

An error callback function is executing.
You have created a connection and have a clientId.

The example code is being used in the context of a Monitor Client Library API callback function, which supplies the commandId.

SMC_VALUE_UNION myValue;
 SMC_VALUE_UNIONP myValuePtr = &myValue;
 if (smc_get_command_info(clientId,
                 commandId,
                 SMC_INFO_ERR_NUM,
                 myValuePtr,
                 NULL) != SMC_RET_SUCCESS) 
 {
 		printf("smc_get_command_info failed\n");
 		/* do some cleanup */
 }

Usage

For the definition of an SMC_VALUE_UNION structure, see “Union: SMC_VALUE_UNION”.
For data of type SMC_CHARP, stringValue points to the value. The Monitor Client Library allocates the memory for this string and the calling application must deallocate it using free().
To retrieve just the length in bytes of a string, pass null for infoValue and a valid pointer for outputLengthHandle.
Table 3-6 lists the command infoType and associated datatype:

**Table 3-6: Monitor Client Library command information types**
Information type	infoValue datatype	Available
SMC_INFO_ALARM_ACTION_DATA	SMC_CHARP	In an alarm callback function
SMC_INFO_ALARM_ALARMID	SMC_SIZET	In an alarm callback function
SMC_INFO_ALARM_CURRENT_ VALUE	Depends on the data item and statistic type combination. (See Chapter 2, “Data Items and Statistical Types”.)	In an alarm callback function
SMC_INFO_ALARM_DATAITEM	SMC_VOIDP	In an alarm callback function
SMC_INFO_ALARM_ROW	SMC_SIZET	In an alarm callback function
SMC_INFO_ALARM_THRESHOLD_ VALUE	Depends on data item/ statistic type combination. (See Chapter 2, “Data Items and Statistical Types”.)	In an alarm callback function
SMC_INFO_ALARM_TIMESTAMP	SMC_CHARP	In an alarm callback function
SMC_INFO_ALARM_VALUE_ DATATYPE	SMC_INT	In an alarm callback function
SMC_INFO_ALARM_VIEWID	SMC_SIZET	In an alarm callback function
SMC_INFO_ERR_MAPSEVERITY	SMC_SIZET	In an error callback function
SMC_INFO_ERR_MSG	SMC_CHARP	In an error callback function
SMC_INFO_ERR_NUM	SMC_SIZET	In an error callback function
SMC_INFO_ERR_SEVERITY	SMC_SIZET	In an error callback function
SMC_INFO_ERR_SOURCE	SMC_SIZET	In an error callback function
SMC_INFO_ERR_STATE	SMC_SIZET	In an error callback function

Valid server modes

Mode	Availability
SMC_SERVER_M_LIVE	Yes
SMC_SERVER_M_HISTORICAL	Yes

Errors

This function does not employ error callback functions.