TWGSdEvt and TWGEvent

The following table describes the syntax of the two forms of the C call used to send events. Refer to Creating and sending an event for more information on how to use these calls.

Purpose
Formats and sends an event to specified servers
Syntax
The event-sending function might be called in either of two forms, depending on whether the calling program is supplying event details data.

int TWGSdEvt (char **type, char *text, short severity, char *dest);

int TWGEvent (TCHAR *family, TCHAR **qualifiers, TCHAR *template, char *locale, TCHAR **subst, short severity, struct _EventDetail **EvtDet, unsigned long groupid, unsigned long eventflags, char *dest, unsigned long controlflags);

type
An array of strings specifying the event type to TWGSdEvt. The first string specifies the family; succeeding strings specify its qualifiers. The family string and at least one qualifier string are required for TWGSdEvt. For example, a well-formed family string is Questor. A valid qualifier string is ring 3.

Specify a NULL string to end the array.

family
An string specifying the event family. As type (TCHAR *) the string can be type PCHAR on any platform. Alternatively, the string can be type (WCHAR *) on Unicode platforms. The family string is required for TWGEvent.
qualifiers
An array of strings specifying the type qualifier. As type (TCHAR *) the strings can be type PCHAR on any platform. Alternatively, the strings can be type (WCHAR *) on Unicode platforms. At least one qualifier string is required for TWGEvent.

Specify a NULL string to end the array.

text
A nonempty string specifying the event text.
template
A TCHAR string, which specifies the event text. As type (TCHAR *) the string can be type PCHAR on any platform. Alternatively, the string can be type (WCHAR *) on Unicode platforms.
locale
A locale string of the form defined below. This locale will apply to the event text string and to any event details which could be passed. The format of the locale string is:
  • The first two characters are an ISO 639 Language Code,
  • The next two characters (optional) are an ISO 3166 Country Code, and
  • These might be followed by a variant code, if appropriate
subst
An optional array of strings specifying values to substitute at positions within the template. The first string will be substituted wherever the symbol %1 appears in the text. The second string will be substituted wherever the symbol %2 appears in the text, and so on. If there are no substitution variables, subst is NULL. Otherwise, the first NULL pointer ends the array.
severity
A short integer code for the event severity.

Define name Decimal value Meaning
SDEVT_EVENT_SEVERITY_FATAL 0 Fatal: The source of the event has caused a program failure and should be resolved before the program is restarted.
SDEVT_EVENT_SEVERITY_CRITICAL 1 Critical: The source of the event might cause program failure and should be resolved immediately.
SDEVT_EVENT_SEVERITY_MINOR 2 Minor: The source of the event should not cause immediate program failure, but should be resolved.
SDEVT_EVENT_SEVERITY_WARNING 3 Warning: The event is not necessarily problematic, but might warrant investigation.
SDEVT_EVENT_SEVERITY_HARMLESS 4 Harmless: The event is for information only; no potential problems should occur.
SDEVT_EVENT_SEVERITY_UNKNOWN 5 Unknown: No severity level was assigned to the event.

EvtDet
A pointer to a vector of pointers to _EventDetail structures. The format of an _EventDetail structure is:
struct _EventDetail {
       TCHAR *ID;                    //  ID
       TCHAR *keyword;               //  keyword
       TCHAR *reference;             //  a reference string
       ULONG ValueType;              //  a data type code from the table below
       void *value;                  //  length of raw data depends on type
        }
If there are no event details, EvtDet is NULL. Otherwise, the first NULL pointer ends the vector. Of the five members of the _EventDetail structure, three (keyword, value, and reference) are optional; each might be a NULL pointer. The other two fields are required. As type (TCHAR *) the ID, keyword, and reference strings can be type PCHAR on any platform. Alternatively, they can be type (WCHAR *) on Unicode platforms.

Define name Decimal value Meaning
SDEVT_DATATYPE_CHAR8 1 8-bit signed
SDEVT_DATATYPE_INT16 2 16-bit signed
SDEVT_DATATYPE_INT32 3 32-bit signed
SDEVT_DATATYPE_INT64 4 64-bit signed
SDEVT_DATATYPE_BOOL 5 an 8-bit value which if zero means FALSE; otherwise TRUE
SDEVT_DATATYPE_REAL32 6 32-bit floating point
SDEVT_DATATYPE_REAL64 7 64-bit floating point
SDEVT_DATATYPE_OCTET 8 an array of octets, preceded by a 32-bit length value
SDEVT_DATATYPE_STRING16 9 a string of Unicode characters
SDEVT_DATATYPE_DATETIME 10 Date and time encoded as a 64-bit unsigned long, expressed as the number of milliseconds elapsed since 00:00:00 Coordinated Universal Time, January 1, 1970
SDEVT_DATATYPE_CHAR16 11 a 16-bit unsigned, or Unicode character
SDEVT_DATATYPE_INT8 12 8-bit signed

groupid
An unsigned long integer representing the Director ID associated with the group for which the event is being generated. If no group is defined for the event, use zero for groupid.
eventflags
An unsigned long integer containing flags defined for the category of the event. Supported values are:
Event Category Description
0 Alert
1 Resolution
dest
A string specifying the event destination. When the particular server name is known, this string takes the form:
protocol[ordinal]::id
where supported values are:
Protocol Ordinal ID ID example
IPX [none] Internetwork address A1:0005A296AC80
TCPIP digit Hostname or IP address Director.raleigh.tivoli.com
NETBIOS digit Computer name User98

Notes:

  • The ordinal is optional and when used is a single digit representing the ordinal of the logical adapter associated with the protocol. The IPX protocol does not use an ordinal.
  • The NETBIOS protocol is not supported on Netware.
  • When the path to the server is not known, the dest string can be specified as @EventServer. TWGSdEvt or TWGEvent will send the event to all servers that have been in communication with this agent.
controlflags
An unsigned long integer containing control flags affecting the generation and transmission of the event. For information on sending commands synchronously or asynchronously, see Sending the command.
Define name Bit position Meaning
CONTROL_FLAG_ASYNCH 0 If 1, send the command asynchronously.
Returns
A 32-bit integer encoding the result of the operation. The table of names and defined values is in the file TWGSDEVT.H.

Use TWGSDEVT.H as an included header to set the prototype for the entry points you want to call. You must define to the preprocessor the variable UNICODE when compiling if you are using type (WCHAR *) strings.
Define name Decimal value Meaning
EXIT_SUCCESS 0 The operation was successful.
SDEVT_CANT_OPEN_LOG 2 Could not open the log file.
SDEVT_CANT_ALLOCATE_MEMORY 3 Could not allocate memory.
SDEVT_NO_CONNECT 5 Could not establish a service node.
SDEVT_NO_UNIQUE_ID 6 Could not determine system unique ID.
SDEVT_NO_TYPE 7 No type provided.
SDEVT_SEND_FAILED 8 Error response from SendCommand.
SDEVT_NO_TEXT 9 No event text provided.
SDEVT_BAD_SEVERITY 10 Incorrect severity code provided.
SDEVT_NO_FAMILY 11 No family in type.
SDEVT_MISSING_QUALIFIER 12 Missing qualifier in type.
SDEVT_BAD_PROTOCOL 13 Unknown transport protocol.
SDEVT_NO_ADDRESS 16 No target address provided.
SDEVT_NO_QUALIFIERS 17 Type had no sublevels.
SDEVT_SEND_TIMEOUT 18 Waited too long for response to SendCommand.
SDEVT_ERROR_COMMUNICATING 19 Could not connect to destination.
SDEVT_BAD_POINTER 20 Incorrect memory address was passed.
SDEVT_CANT_GET_SERVERS 21 Failure requesting event servers.
SDEVT_BAD_DETAIL_TYPE 22 An event detail has an incorrect data type.
SDEVT_BAD_LANGUAGE 23 The locale has an incorrect language code.
SDEVT_MISSING_DETAIL 24 An event detail was missing the required ID field.