source: trunk/man/arm_register_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_register_transaction" 3 "August 2008" "arm4.org" "ARM 4 Programmer's Manual"
.SH NAME
arm_register_transaction \- describe transaction
.SH SYNOPSIS
.B #include <arm4.h>
.sp
\fBarm_error_t
.br
arm_register_transaction( 
.br
    const arm_id_t *\fIapp_id\fB, 
.br
    const arm_char_t *\fItran_name\fB, 
.br
    const arm_id_t *\fIinput_tran_id\fB, 
.br
    const arm_int32_t \fIflags\fB,
.br
    const arm_buffer4_t *\fIbuffer4\fB,
.br
    arm_id_t *\fIoutput_tran_id\fB);\fR 
.SH DESCRIPTION
\fBarm_register_transaction()\fR describes metadata about a transaction.
 
The application uses \fBarm_register_transaction()\fR to inform the ARM library of metadata about 
the transaction measured by the application. This metadata does not change from one application 
instance to another. It is the equivalent of the ARM 2.0 call \fBarm_getid()\fR.
 
ARM generates an ID that is passed in to \fBarm_start_transaction()\fR and \fBarm_report_transaction()\fR.

\fIapp_id\fR is an application ID returned from an \fBarm_register_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_metric_bindings_t\fR and \fBarm_subbuffer_tran_identity_t\fR. 
 
The names of any transaction context properties are supplied in the 
\fBarm_subbuffer_tran_identity_t\fR sub-buffer. They do not change afterwards; that 
is, the names are immutable. The transaction context values may change with each 
\fBarm_start_transaction()\fR or \fBarm_report_transaction()\fR.
 
\fIflags\fR contains 32-bit flags. No values are currently defined. The field should be zero 
(\fBARM_FLAG_NONE\fR).
 
\fIinput_tran_id\fR is a pointer to an optional 128-bit ID (16 bytes) that is unique and that can be treated as 
an alias for the other metadata. It can be any value except all zeros or all ones. If the 
pointer is null (\fBARM_ID_NONE\fR), no ID is provided. 
 
An ID is unique if the probability of the ID being associated with more than one set 
of metadata is vanishingly small. The selection of 128-bit IDs yields 3.4 x 10**38 
unique IDs, so the objective is to select an ID that makes use of all 128 bits and is 
reasonably likely to not be selected by another person creating an ID of the same 
form. Two suggested algorithms that generate 128-bit values with these
characteristics are: 
 
.IP 1.
The Universal Unique Identifier (UUID) algorithm that is part of The Open 
Group specification: DCE 1.1: Remote Procedure Call. A developer could use the 
algorithm at the time the application is developed using a utility on his or her 
system, and be reasonably certain that nobody else would generate the same 128-bit 
ID. 
 
.IP 2.
The MD5 Message\-Digest Algorithm, described in IETF RFC 1321. Applying 
this algorithm to a concatenation of all the metadata properties would almost 
certainly result in a value that would not collide with any other ID created with a 
different set of metadata properties. 
.P 
If an ARM implementation is passed an ID that was previously registered within 
this process, the implementation can ignore the other metadata parameters and 
assume they are identical to the previously registered metadata. The transaction 
metadata consists of the following fields: \fIapp_id\fR, \fItran_name\fR, and the 
\fBarm_subbuffer_metric_bindings_t\fR and \fBarm_subbuffer_tran_identity_t\fR
sub-buffers passed in \fIbuffer4\fR. 

\fIoutput_tran_id\fR is a pointer to a 16-byte field. ARM will store a 16-byte value. There are no 
requirements on the value it is set to, except that it must be possible to pass it on 
other calls, such as \fBarm_start_transaction()\fR, without the application needing to do 
any error checking. 

\fItran_name\fR is a pointer to a null-terminated string containing the name of the transaction. Each 
transaction registered by an application must have a unique name. The maximum 
length of the string is 128 characters, including the termination character. It serves 
no purpose and is illegal to make this call if the pointer is null. The name should not 
contain trailing blank characters or consist of only blank characters. 
.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 \fIoutput_tran_id\fR pointer must not be null.
.TP
.B ARM_FAILURE_INVALID_ARGUMENT
The \fItran_name\fR argument doesn't match the string requirements.
.TP
.TP
.B ARM_FAILURE_BAD_ALIAS
The alias provided contains all 0's or all 1's.
.TP
.B ARM_FAILURE_DUPLICATE_ALIAS
The alias provided already refers to a transaction with different metadata.
.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_register_application (3),
.BR arm_report_transaction (3),
.BR arm_start_transaction (3)