1arm_register_transaction(3)ARM 4 Programmer's Manualarm_register_transaction(3)
2
6 arm_register_transaction - describe transaction
7
9 #include <arm4.h>
10 arm_error_t
12 arm_register_transaction(
13 const arm_id_t *app_id,
14 const arm_char_t *tran_name,
15 const arm_id_t *input_tran_id,
16 const arm_int32_t flags,
17 const arm_buffer4_t *buffer4,
18 arm_id_t *output_tran_id);
19
21 arm_register_transaction() describes metadata about a transaction.
22 The application uses arm_register_transaction() to inform the ARM
24 library of metadata about the transaction measured by the application.
25 This metadata does not change from one application instance to another.
26 It is the equivalent of the ARM 2.0 call arm_getid().
27 ARM generates an ID that is passed in to arm_start_transaction() and
29 arm_report_transaction().
30 app_id is an application ID returned from an arm_register_application()
32 call in the same process.
33 buffer4 is a pointer to the user data buffer, if any. If the pointer is
35 null (ARM_BUF4_NONE), there is no buffer. The sub-buffers that may be
36 used are arm_subbuffer_metric_bindings_t and arm_subbuffer_tran_iden‐
37 tity_t.
38 The names of any transaction context properties are supplied in the
40 arm_subbuffer_tran_identity_t sub-buffer. They do not change after‐
41 wards; that is, the names are immutable. The transaction context values
42 may change with each arm_start_transaction() or arm_report_transac‐
43 tion().
44 flags contains 32-bit flags. No values are currently defined. The field
46 should be zero (ARM_FLAG_NONE).
47 input_tran_id is a pointer to an optional 128-bit ID (16 bytes) that is
49 unique and that can be treated as an alias for the other metadata. It
50 can be any value except all zeros or all ones. If the pointer is null
51 (ARM_ID_NONE), no ID is provided.
52 An ID is unique if the probability of the ID being associated with more
54 than one set of metadata is vanishingly small. The selection of 128-bit
55 IDs yields 3.4 x 10**38 unique IDs, so the objective is to select an ID
56 that makes use of all 128 bits and is reasonably likely to not be
57 selected by another person creating an ID of the same form. Two sug‐
58 gested algorithms that generate 128-bit values with these characteris‐
59 tics are:
60 1. The Universal Unique Identifier (UUID) algorithm that is part of
63 The Open Group specification: DCE 1.1: Remote Procedure Call. A
64 developer could use the algorithm at the time the application is
65 developed using a utility on his or her system, and be reason‐
66 ably certain that nobody else would generate the same 128-bit
67 ID.
68 2. The MD5 Message-Digest Algorithm, described in IETF RFC 1321.
71 Applying this algorithm to a concatenation of all the metadata
72 properties would almost certainly result in a value that would
73 not collide with any other ID created with a different set of
74 metadata properties.
75 If an ARM implementation is passed an ID that was previously registered
77 within this process, the implementation can ignore the other metadata
78 parameters and assume they are identical to the previously registered
79 metadata. The transaction metadata consists of the following fields:
80 app_id, tran_name, and the arm_subbuffer_metric_bindings_t and arm_sub‐
81 buffer_tran_identity_t sub-buffers passed in buffer4.
82 output_tran_id is a pointer to a 16-byte field. ARM will store a
84 16-byte value. There are no requirements on the value it is set to,
85 except that it must be possible to pass it on other calls, such as
86 arm_start_transaction(), without the application needing to do any
87 error checking.
88 tran_name is a pointer to a null-terminated string containing the name
90 of the transaction. Each transaction registered by an application must
91 have a unique name. The maximum length of the string is 128 characters,
92 including the termination character. It serves no purpose and is ille‐
93 gal to make this call if the pointer is null. The name should not con‐
94 tain trailing blank characters or consist of only blank characters.
95
97 On success, the function returns ARM_SUCCESS. A non-zero value indi‐
98 cates an error.
99
101 If the return code is negative, an error occurred. If the return code
102 is not negative, an error may or may not have occurred - the determina‐
103 tion of what is an error and whether an error code is returned is at
104 the discretion of the ARM implementation. The application can test the
105 return code if it wants to provide its own error logging.
106 The following errors are recognized by this implementation, but may not
108 be portable to other implementations:
109 ARM_FAILURE_NULL_ARGUMENT
112 The output_tran_id pointer must not be null.
113 ARM_FAILURE_INVALID_ARGUMENT
115 The tran_name argument doesn't match the string requirements.
116 ARM_FAILURE_BAD_ALIAS
119 The alias provided contains all 0's or all 1's.
120 ARM_FAILURE_DUPLICATE_ALIAS
122 The alias provided already refers to a transaction with
123 different metadata. ARM_FAILURE_INTERNAL_ERROR An inter‐
124 nal error has occurred that prevented the operation from
125 completing. Check your system log for more details.
126
128 ARM Issue 4.0 C Language Bindings, Version 2
129
131 None.
132
134 arm_register_application(3), arm_report_transaction(3),
135 arm_start_transaction(3)
136arm4.org August 2008 arm_register_transaction(3)