source: trunk/man/arm_report_transaction.3 @ 704

.\" Copyright (c) 2005-2008 David Carter <dcarter@arm4.org> and others.
.\" All rights reserved.   This program and the accompanying materials
.\" are made available under the terms of the Eclipse Public License v1.0
.\" which accompanies this distribution, and is available at
.\" http://www.eclipse.org/legal/epl-v10.html
.TH "arm_report_transaction" 3 "August 2008" "arm4.org" "ARM 4 Programmer's Manual"
.SH NAME
arm_report_transaction \- report transaction statistics
.SH SYNOPSIS
.B #include <arm4.h>
.sp
\fBarm_error_t
.br
arm_report_transaction( 
.br
    const arm_app_start_handle_t \fIapp_handle\fB, 
.br
    const arm_id_t *\fItran_id\fB, 
.br
    const arm_tran_status_t \fItran_status\fB, 
.br
    const arm_response_time_t \fIresponse_time\fB, 
.br
    const arm_stop_time_t \fIstop_time\fB, 
.br
    const arm_correlator_t *\fIparent_correlator\fB, 
.br
    const arm_correlator_t *\fIcurrent_correlator\fB, 
.br
    const arm_int32_t \fIflags\fB, 
.br
    const arm_buffer4_t *\fIbuffer4\fB);\fR
.SH DESCRIPTION
\fBarm_report_transaction()\fR is used to report statistics about a transaction that has already 
completed.
 
\fBarm_report_transaction()\fR may be used instead of a paired \fBarm_start_transaction()\fR and 
\fBarm_stop_transaction()\fR call. The application would have measured the response time. The 
transaction could have executed on the local system or on a remote system. If it executes on a 
remote system, the system address sub-buffer passed on the \fBarm_start_application()\fR provides 
the addressing information for the remote system. 

If the transaction represented by the \fBarm_report_transaction()\fR call is the correlation parent of 
another transaction, \fBarm_generate_correlator()\fR must be used to get a parent correlator, prior to 
invoking the child transaction (because it must be passed to the child). In this case, the sequence 
is the following: 

.IP 1.
Call \fBarm_generate_correlator()\fR to get a correlator for this transaction. 
.IP 2.
Invoke the child transaction, passing the correlator returned in step (1) to the child. 
.IP 3.
When this transaction is complete, invoke \fBarm_report_transaction()\fR to report the 
statistics about the transaction. 
.P
When used, it prevents certain types of proactive management, such as monitoring for hung 
transactions or adjusting priorities, because the ARM implementation is not invoked when the 
transaction is started. Because of this, the use of \fBarm_start_transction()\fR and 
\fBarm_stop_transaction()\fR is preferred over \fBarm_report_transaction()\fR.
 
The intended use is to report status and response time about transactions that recently completed 
(typically several seconds ago) in the absence of an ARM-enabled application and/or ARM 
implementation on the system on which the transaction executed.

\fIapp_handle\fR is a handle returned in an out parameter from an \fBarm_start_application()\fR call in the 
same process. 

\fIbuffer4\fR is a pointer to the user data buffer, if any. If the pointer is null (\fBARM_BUF4_NONE\fR), 
there is no buffer. The sub-buffers that may be used are 
\fBarm_subbuffer_diag_detail_t\fR, \fBarm_subbuffer_metric_values_t\fR, 
\fBarm_subbuffer_tran_context_t\fR, and \fBarm_subbuffer_user_t\fR. 

\fIcurrent_correlator\fR is a pointer to the correlator for the transaction that has completed, if any. If the pointer 
is null (\fBARM_CORR_NONE\fR), there is no current correlator.
 
\fIflags\fR contains 32-bit flags. In the least significant byte, 0x00000001 
(\fBARM_FLAG_TRACE_REQUEST\fR) is set if the application requests/suggests a 
trace. 

\fIparent_correlator\fR is a pointer to a parent correlator, if any. If the pointer is null (\fBARM_CORR_NONE\fR), 
there is no parent correlator. 

\fIresponse_time\fR is the response time in nanoseconds.
 
\fIstop_time\fR is an \fBarm_int64_t\fR that contains the number of milliseconds since Jan 1, 1970 using 
the Gregorian calendar. The time base is GMT (Greenwich Mean Time). There is 
one special value, -1 (\fBARM_USE_CURRENT_TIME\fR), which means use the 
current time. 

\fItran_id\fR is a transaction ID returned in an out parameter from an \fBarm_register_transaction()\fR
call in the same process. 

\fItran_status\fR indicates the status of the transaction. The following values are allowed: 
 
.IP 0
(\fBARM_STATUS_GOOD\fR) = transaction completed successfully 
.IP 1
(\fBARM_STATUS_ABORTED\fR) = transaction was aborted before it completed. For 
example, the user might have pressed "Stop" or "Back" on a browser while a 
transaction was in process, causing the transaction, as measured at the browser, to 
be aborted. 
.IP 2
(\fBARM_STATUS_FAILED\fR) = transaction completed in error 
.IP 3
(\fBARM_STATUS_UNKNOWN\fR) = transaction completed but the status was 
unknown. This would most likely occur if middleware or some other form of proxy 
instrumentation measured the transaction. This instrumentation may know enough 
to know when the transaction starts and stops, but does not understand the 
application-specific semantics sufficiently well to know whether the transaction 
was successful. 
.SH "RETURN VALUE"
On success, the function returns \fBARM_SUCCESS\fR. A non-zero value indicates
an error.
.SH ERRORS
If the return code is negative, an error occurred. If the return code is not negative, an error may
or may not have occurred - the determination of what is an error and whether an error code is
returned is at the discretion of the ARM implementation. The application can test the return code
if it wants to provide its own error logging.

The following errors are recognized by this implementation, but may not be portable to other implementations:

.TP
.B ARM_FAILURE_NULL_ARGUMENT
The \fItran_id\fR must not be null.
.TP
.B ARM_FAILURE_INVALID_ARGUMENT
The \fIapp_handle\fR provided is invalid.
.TP
.B ARM_FAILURE_INTERNAL_ERROR
An internal error has occurred that prevented the operation from completing. Check your
system log for more details.
.SH "CONFORMING TO"
ARM Issue 4.0 C Language Bindings, Version 2
.SH EXAMPLE
None.
.SH "SEE ALSO"
.BR arm_generate_correlator (3),
.BR arm_register_transaction (3),
.BR arm_start_application (3),
.BR arm_start_transaction (3),
.BR arm_stop_transaction (3)