source: trunk/man/arm_stop_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_stop_transaction" 3 "August 2008" "arm4.org" "ARM 4 Programmer's Manual"
.SH NAME
arm_stop_transaction \- stop transaction
.SH SYNOPSIS
.B #include <arm4.h>
.sp
\fBarm_error_t
.br
arm_stop_transaction( 
.br
    const arm_tran_start_handle_t \fItran_handle\fB, 
.br
    const arm_tran_status_t \fItran_status\fB, 
.br
    const arm_int32_t \fIflags\fB,
.br
    const arm_buffer4_t *\fIbuffer4\fB);\fR
.SH DESCRIPTION
\fBarm_stop_transaction()\fR signals the end of a transaction.
 
Call \fBarm_stop_transaction()\fR just after a transaction completes. \fBarm_start_transaction()\fR signals 
the ARM library to start timing the transaction response time. \fBarm_stop_transaction()\fR signals 
the ARM library to stop timing the transaction response time. It can be called from any thread in 
the process that executed the \fBarm_start_transaction()\fR.
 
Implicit \fBarm_unbind_thread()\fR and \fBarm_unblock_transaction()\fR calls are made for any pending 
\fBarm_bind_thread()\fR and \fBarm_block_transaction()\fR calls, respectively, that have not been 
explicitly unbound or unblocked with \fBarm_unbind_thread()\fR and \fBarm_unblock_transaction()\fR.

\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 and \fBarm_subbuffer_metric_values_t\fR.
 
\fIflags\fR contains 32-bit flags. No values are currently defined. The field should be zero 
(\fBARM_FLAG_NONE\fR). 

\fItran_handle\fR is a handle returned in an out parameter from an \fBarm_start_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_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_bind_thread (3),
.BR arm_block_transaction (3),
.BR arm_start_transaction (3),
.BR arm_unbind_thread (3),
.BR arm_unblock_transaction (3)