Generating a trace record

The Vue functions for generating system trace (and LMT trace) records have the syntax that is similar to the kernel interfaces that are invoked by the Vue functions.

There are some restrictions as follows:

• If system trace is not started, or the hookid value is not being captured by system trace, these operations do not produce system trace records (LMT tracing to the common buffer for TRCHKLx traces will still be attempted, but LMT might also be disabled).
• You cannot generate a trace record from within a @@systrace Vue clause. Calls to the tracing functions only generate the LMT common buffer trace records for TRCHKLx traces in this case, assuming that LMT is enabled.
• You cannot probe these ProbeVue-generated trace events; only kernel and application generated tracing can be probed.
• You must be privileged, either as root or with the aix.ras.probevue.rase authorization.

The following Vue functions exist for writing system trace records. All data words are of type long long integers:

TRCHKL0(hookID)

Trace with no data words.

TRCHKL1(hookID, D1)

Trace with 1 data word.

TRCHKL2(hookID, D1,D2)

Trace with 2 data words.

TRCHKL3(hookID, D1,D2,D3)

Trace with 3 data words.

TRCHKL4(hookID, D1,D2,D3,D4)

Trace with 4 data words.

TRCHKL5(hookID, D1,D2,D3,D4,D5)

Trace with 5 data words.

void trcgenk(int channel, int hook_ID, unsigned long long data_word, int length, untyped buffer)

Trace a buffer.

These trace functions always append a timestamp to the event data. The hookid parameter to these functions is of the form 0xhhhh0000. This does not mean that the hookid value is required to be a constant, it just indicates how a hookid value is formed.

With the trcgenk kernel service, the buffer parameter is a pointer to length bytes of data to trace, at most 4096 bytes. The buffer parameter can be an external variable like a kernel or application pointer to pinned data, or a script variable like a Vue string or structure instance. The "untyped" specification is a shorthand for this.

You can use a non-zero channel number, but you must ensure that the specified channel is enabled for tracing. The return value from the trace command that started the trace of interest can be passed to the Vue script for this purpose. Using a disabled channel will result in no tracing.

These tracing functions do not return a value.

Stopping the trace

To freeze the system trace as soon as possible after a required event has occurred, you can use void trcoff() in a Vue script. This function disables channel zero tracing immediately. You must still stop the trace in the normal way, with the trcstop command external to ProbeVue, in order for trace processing to be completed normally.

You can immediately stop LMT and component traces so that ongoing tracing does not wrap data of interest. The corresponding resuming functions are needed because there is no command line equivalent available to restart these traces. There are following new Vue functions:

void mtrcsuspend()
void ctsuspend()
void mtrcresume()
void ctresume()

The ctsuspend routine stops all component tracing. You cannot use this routine for selective trace stop by component. It stops component trace only, not any other tracing that the CT_HOOKx macros might have requested, such as system and LMT trace recording.

You must use these trace control functions with caution, as there is no serialization of the kernel tracing code being affected. You must manually ensure that only one script or command will be affecting tracing at a time.

Stopping the system

You can terminate the system and take a full dump using the following routine:

void abend(long long code, long long data_word, ...)

This routine is similar to the abend kernel service, except that only up to 7 data parameters (which will be loaded into registers r3 through up to r10) are accepted here.

Untyped parameters

In function prototypes to follow, some parameters of the equivalent kernel functions are typed ambiguously. The Vue compiler generally performs type checking on all parameters passed to a Vue function, but the parameters designated as having an "untyped" type are exempted from type checking. For example, an optional string might be passed as NULL when using these kernel services directly in the kernel, but if the Vue function was defined as taking a parameter of type String, a NULL cannot be accepted. To avoid the inconvenience of having to pass an empty string instead and to let the Vue functions take the same parameters as the following kernel interface, these functions have been defined as taking untyped parameters. An untyped parameter provides us with the liberty of passing NULL instead of a real Vue string, but be careful when specifying values for "untyped" parameters, because the compiler will accept any type for the parameter.