1arm_report_transaction(3) ARM 4 Programmer's Manual arm_report_transaction(3)
2
6 arm_report_transaction - report transaction statistics
7
9 #include <arm4.h>
10 arm_error_t
12 arm_report_transaction(
13 const arm_app_start_handle_t app_handle,
14 const arm_id_t *tran_id,
15 const arm_tran_status_t tran_status,
16 const arm_response_time_t response_time,
17 const arm_stop_time_t stop_time,
18 const arm_correlator_t *parent_correlator,
19 const arm_correlator_t *current_correlator,
20 const arm_int32_t flags,
21 const arm_buffer4_t *buffer4);
22
24 arm_report_transaction() is used to report statistics about a transac‐
25 tion that has already completed.
26 arm_report_transaction() may be used instead of a paired
28 arm_start_transaction() and arm_stop_transaction() call. The applica‐
29 tion would have measured the response time. The transaction could have
30 executed on the local system or on a remote system. If it executes on a
31 remote system, the system address sub-buffer passed on the
32 arm_start_application() provides the addressing information for the
33 remote system.
34 If the transaction represented by the arm_report_transaction() call is
36 the correlation parent of another transaction, arm_generate_correla‐
37 tor() must be used to get a parent correlator, prior to invoking the
38 child transaction (because it must be passed to the child). In this
39 case, the sequence is the following:
40 1. Call arm_generate_correlator() to get a correlator for this
43 transaction.
44 2. Invoke the child transaction, passing the correlator returned in
46 step (1) to the child.
47 3. When this transaction is complete, invoke arm_report_transac‐
49 tion() to report the statistics about the transaction.
50 When used, it prevents certain types of proactive management, such as
52 monitoring for hung transactions or adjusting priorities, because the
53 ARM implementation is not invoked when the transaction is started.
54 Because of this, the use of arm_start_transction() and arm_stop_trans‐
55 action() is preferred over arm_report_transaction().
56 The intended use is to report status and response time about transac‐
58 tions that recently completed (typically several seconds ago) in the
59 absence of an ARM-enabled application and/or ARM implementation on the
60 system on which the transaction executed.
61 app_handle is a handle returned in an out parameter from an
63 arm_start_application() call in the same process.
64 buffer4 is a pointer to the user data buffer, if any. If the pointer is
66 null (ARM_BUF4_NONE), there is no buffer. The sub-buffers that may be
67 used are arm_subbuffer_diag_detail_t, arm_subbuffer_metric_values_t,
68 arm_subbuffer_tran_context_t, and arm_subbuffer_user_t.
69 current_correlator is a pointer to the correlator for the transaction
71 that has completed, if any. If the pointer is null (ARM_CORR_NONE),
72 there is no current correlator.
73 flags contains 32-bit flags. In the least significant byte, 0x00000001
75 (ARM_FLAG_TRACE_REQUEST) is set if the application requests/suggests a
76 trace.
77 parent_correlator is a pointer to a parent correlator, if any. If the
79 pointer is null (ARM_CORR_NONE), there is no parent correlator.
80 response_time is the response time in nanoseconds.
82 stop_time is an arm_int64_t that contains the number of milliseconds
84 since Jan 1, 1970 using the Gregorian calendar. The time base is GMT
85 (Greenwich Mean Time). There is one special value, -1 (ARM_USE_CUR‐
86 RENT_TIME), which means use the current time.
87 tran_id is a transaction ID returned in an out parameter from an
89 arm_register_transaction() call in the same process.
90 tran_status indicates the status of the transaction. The following val‐
92 ues are allowed:
93 0 (ARM_STATUS_GOOD) = transaction completed successfully
96 1 (ARM_STATUS_ABORTED) = transaction was aborted before it com‐
98 pleted. For example, the user might have pressed "Stop" or
99 "Back" on a browser while a transaction was in process, causing
100 the transaction, as measured at the browser, to be aborted.
101 2 (ARM_STATUS_FAILED) = transaction completed in error
103 3 (ARM_STATUS_UNKNOWN) = transaction completed but the status was
105 unknown. This would most likely occur if middleware or some
106 other form of proxy instrumentation measured the transaction.
107 This instrumentation may know enough to know when the transac‐
108 tion starts and stops, but does not understand the application-
109 specific semantics sufficiently well to know whether the trans‐
110 action was successful.
111
113 On success, the function returns ARM_SUCCESS. A non-zero value indi‐
114 cates an error.
115
117 If the return code is negative, an error occurred. If the return code
118 is not negative, an error may or may not have occurred - the determina‐
119 tion of what is an error and whether an error code is returned is at
120 the discretion of the ARM implementation. The application can test the
121 return code if it wants to provide its own error logging.
122 The following errors are recognized by this implementation, but may not
124 be portable to other implementations:
125 ARM_FAILURE_NULL_ARGUMENT
128 The tran_id must not be null.
129 ARM_FAILURE_INVALID_ARGUMENT
131 The app_handle provided is invalid.
132 ARM_FAILURE_INTERNAL_ERROR
134 An internal error has occurred that prevented the operation from
135 completing. Check your system log for more details.
136
138 ARM Issue 4.0 C Language Bindings, Version 2
139
141 None.
142
144 arm_generate_correlator(3), arm_register_transaction(3),
145 arm_start_application(3), arm_start_transaction(3), arm_stop_transac‐
146 tion(3)
147arm4.org August 2008 arm_report_transaction(3)