source: trunk/man/arm_start_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_start_transaction" 3 "August 2008" "arm4.org" "ARM 4 Programmer's Manual"
.SH NAME
arm_start_transaction \- start transaction
.SH SYNOPSIS
.B #include <arm4.h>
.sp
\fBarm_error_t
.br
arm_start_transaction( 
.br
    const arm_app_start_handle_t \fIapp_handle\fB, 
.br
    const arm_id_t *\fItran_id\fB, 
.br
    const arm_correlator_t *\fIparent_correlator\fB, 
.br
    const arm_int32_t \fIflags\fB, 
.br
    const arm_buffer4_t *\fIbuffer4\fB, 
.br
    arm_tran_start_handle_t *\fItran_handle\fB,
.br
    arm_correlator_t *\fIcurrent_correlator\fB);\fR
.SH DESCRIPTION
\fBarm_start_transaction()\fR is used to indicate that a transaction is beginning execution. 

Call \fBarm_start_transaction()\fR just prior to a transaction beginning execution. 
\fBarm_start_transaction()\fR signals the ARM library to start timing the transaction response time. 
There is one exception: when \fBarm_get_arrival_time()\fR is used to get a start time before 
\fBarm_start_transaction()\fR executes. See \fBarm_get_arrival_time()\fR to understand this usage.
 
\fBarm_start_transaction()\fR is also the means to pass to ARM the correlation token (called a 
"correlator" in ARM) from a caller \- the "parent" \- and to request a correlator that can be passed 
to transactions called by this transaction. The correlation token may be used to establish a calling 
hierarchy across processes and systems. A correlator contains a two-byte length field, a one-byte 
format ID, a one-byte flag field, plus it may contain other data that is used to uniquely identify 
an instance of a transaction. Applications do not need to understand correlator internals. The 
maximum length of a correlator is 512 (\fBARM_CORR_MAX_LENGTH\fR) bytes. (In ARM 2.0 it 
was 168 bytes.) 

\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_arrival_time_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 a buffer into which the ARM implementation will store a correlator for 
the transaction instance, if any. The length of the buffer should be (at least) 512 
(\fBARM_CORR_MAX_LENGTH\fR) bytes. 
 
If the pointer is null (\fBARM_CORR_NONE\fR), the application is not requesting that a 
correlator be created. 

If the pointer is not null, the application is requesting that a correlator be created. In 
this case the ARM implementation may (but need not) create a correlator in the 
buffer. It may not create a correlator if it does not support the function or if it is 
configured to not create a correlator. 
 
After \fBarm_start_transaction()\fR completes, the application tests the length field using 
\fBarm_get_correlator_length()\fR to determine whether a correlator has been stored. If 
the length is still zero, no correlator has been stored. The ARM implementation 
must store zero in the length field if it does not generate a correlator. 

\fIflags\fR contains 32-bit flags. These may be combined using a binary or (|) operation. Three flags are defined: 
 
.IP 0x00000001
(\fBARM_FLAG_TRACE_REQUEST\fR) is set if the application 
requests/suggests a trace. 
 
.IP 0x00000002
(\fBARM_FLAG_BIND_THREAD\fR) is set if the started transaction is 
bound to this thread. Setting this flag is equivalent to immediately calling 
\fBarm_bind_thread()\fR after the \fBarm_start_transaction()\fR completes, except the timing 
is a little more accurate and the extra call is avoided. 
 
.IP 0x00000004
(\fBARM_FLAG_CORR_IN_PROCESS\fR) is set if the application is stating 
that it will not send the correlator outside the current process. An ARM 
implementation may be able to optimize correlator handling if it knows this, 
because it may be able to avoid serialization to create the correlator. 
.P
\fIparent_correlator\fR is a pointer to the parent correlator, if any. The pointer may be null 
(\fBARM_CORR_NONE\fR). 

\fItran_handle\fR is a pointer to an \fBarm_int64_t\fR into which the ARM library will store the value of the 
handle that will represent the transaction instance in all calls, up to and including 
the \fBarm_stop_transaction()\fR that indicates that the instance has completed executing. 
The scope of the handle is the process in which the \fBarm_start_transaction()\fR is 
executed. 
 
There are no defined behaviors for the value returned \- it is implementation 
defined. Note that the returned value will always be a value that the application can 
use in future calls that take a handle [\fBarm_bind_thread()\fR, \fBarm_block_transaction()\fR, 
\fBarm_stop_transaction()\fR, \fBarm_unbind_thread()\fR, \fBarm_unblock_transaction()\fR, and 
\fBarm_update()\fR].
 
\fItran_id\fR is a transaction ID returned in an out parameter from an \fBarm_register_transaction()\fR 
call in the same process. 

.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_handle\fR pointer must not be null.
.TP
.B ARM_FAILURE_INVALID_ARGUMENT
A valid \fItran_id\fR and \fIapp_handle\fR must be provided.
.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_get_arrival_time (3),
.BR arm_get_correlator_length (3),
.BR arm_register_transaction (3),
.BR arm_start_application (3),
.BR arm_stop_transaction (3),
.BR arm_unbind_thread (3),
.BR arm_unblock_transaction (3),
.BR arm_update_transaction (3)