1arm_start_application(3) ARM 4 Programmer's Manual arm_start_application(3)
2
6 arm_start_application - check application is running
7
9 #include <arm4.h>
10 arm_error_t
12 arm_start_application(
13 const arm_id_t *app_id,
14 const arm_char_t *app_group,
15 const arm_char_t *app_instance,
16 const arm_int32_t flags,
17 const arm_buffer4_t *buffer4,
18 arm_app_start_handle_t *app_handle);
19
21 arm_start_application() indicates that an instance of an application
22 has started running and is prepared to make ARM calls. In many cases,
23 there will be only one application instance in a process, but there are
24 cases in which there could be multiple instances. An example of multi‐
25 ple application instances in the same process is if several Java appli‐
26 cations run in the same JVM (Java Virtual Machine) in the same process,
27 and they each call the ARM 4.0 C interface (either directly, or indi‐
28 rectly via an implementation of the ARM 4.0 Java interface). They might
29 share the same application ID or they might be separately registered.
30 Application context properties may be used to differentiate between
32 instances. The values do not have to be different from other instances,
33 though making them unique is suggested. The context properties are pro‐
34 vided through function parameters and/or a sub-buffer.
35 The group and instance names are provided as function parameters.
37 Up to twenty (name,value) pairs of context properties may be provided
39 in a sub-buffer.
40 There is a special case in which a system address sub-buffer is pro‐
42 vided. The system address sub-buffer is provided when arm_report_trans‐
43 action() will be used to report data about transactions that executed
44 on a different system. In this case, the arm_start_application() pro‐
45 vides a scoping context for the transaction instances, but does not
46 indicate that the application instance is running on the local system.
47 The combination of arm_register_application() and arm_start_applica‐
49 tion() is equivalent to the ARM 2.0 call arm_init().
50 app_group is a pointer to a null-terminated string containing the iden‐
52 tity of a group of application instances, if any. Application instances
53 for a given software product that are started for a common runtime pur‐
54 pose are typically very good candidates for using the same group name.
55 For example, identical replica instances of a product started across
56 multiple processes or servers to address a specific transaction work‐
57 load objective can be, advantageously to the ARM agent, commonly iden‐
58 tified by the group name. The maximum length of the string is 256
59 (ARM_PROPERTY_VALUE_MAX_CHARS) characters, including the termination
60 character. A null pointer (ARM_STRING_NONE) indicates that there is no
61 group.
62 app_handle is a pointer to an arm_int64_t into which the ARM library
64 will store the value of the handle that will represent the application
65 instance in all calls, up to and including the arm_stop_application()
66 that indicates that the instance has completed executing. The scope of
67 the handle is the process in which the arm_start_application() is exe‐
68 cuted. There are no requirements on the value it is set to, except that
69 it must be possible to pass it on other calls, such as arm_start_trans‐
70 action(), without the application needing to do any error checking.
71 Whether the data is meaningful, or partially meaningful, is at the dis‐
72 cretion of the ARM implementation.
73 app_id is a pointer to a 16-byte ID returned by an arm_register_appli‐
75 cation() call.
76 app_instance is a pointer to a null-terminated string containing the
78 identity of this instance of the application. It might contain the
79 process ID, or a UUID in printable characters, for example. The maximum
80 length of the string is 256 (ARM_PROPERTY_VALUE_MAX_CHARS) characters,
81 including the termination character. A null pointer (ARM_STRING_NONE)
82 indicates that there is no instance value.
83 buffer4 is a pointer to the user data buffer, if any. If the pointer is
85 null (ARM_BUF4_NONE), there is no buffer. The sub-buffer formats that
86 might be used are arm_subbuffer_app_context_t and arm_subbuffer_sys‐
87 tem_address_t.
88 If no system address sub-buffer is provided on arm_start_application(),
90 all transactions reported by this application instance execute in the
91 current process.
92 If a system address sub-buffer is provided on arm_start_application(),
94 all transactions execute in a different process.
95 If a system address sub-buffer is provided in which the system address
97 length is zero, or the system address pointer is null, the system is
98 the "local" system, as determined by the ARM implementation.
99 If a system address sub-buffer is provided in which there is a non-null
101 system address and length, the system may be the local system or a
102 remote system. Interpretation of what is local versus remote is at the
103 discretion of the ARM implementation.
104 flags contains 32-bit flags. No values are currently defined. The field
106 should be zero (ARM_FLAG_NONE).
107
110 On success, the function returns ARM_SUCCESS. A non-zero value indi‐
111 cates an error.
112
114 If the return code is negative, an error occurred. If the return code
115 is not negative, an error may or may not have occurred - the determina‐
116 tion of what is an error and whether an error code is returned is at
117 the discretion of the ARM implementation. The application can test the
118 return code if it wants to provide its own error logging.
119 The following errors are recognized by this implementation, but may not
121 be portable to other implementations:
122 ARM_FAILURE_NULL_ARGUMENT
125 The app_handle pointer must not be null.
126 ARM_FAILURE_INVALID_ARGUMENT
128 One or both of app_group or app_instance are non-null and
129 invalid strings.
130 ARM_FAILURE_INTERNAL_ERROR
132 An internal error has occurred that prevented the operation from
133 completing. Check your system log for more details.
134
136 ARM Issue 4.0 C Language Bindings, Version 2
137
139 None.
140
142 arm_register_application(3), arm_report_transaction(3),
143 arm_start_transaction(3), arm_stop_application(3)
144arm4.org August 2008 arm_start_application(3)