arm_start_application (3) - Linux Manuals

arm_start_application: check application is running

NAME

arm_start_application - check application is running

SYNOPSIS

#include <arm4.h>

arm_error_t
arm_start_application(

 const arm_id_t *app_id, 

 const arm_char_t *app_group, 

 const arm_char_t *app_instance, 

 const arm_int32_t flags,

 const arm_buffer4_t *buffer4, 

 arm_app_start_handle_t *app_handle);

DESCRIPTION

arm_start_application() indicates that an instance of an application has started running and is prepared to make ARM calls. In many cases, there will be only one application instance in a process, but there are cases in which there could be multiple instances. An example of multiple application instances in the same process is if several Java applications run in the same JVM (Java Virtual Machine) in the same process, and they each call the ARM 4.0 C interface (either directly, or indirectly via an implementation of the ARM 4.0 Java interface). They might share the same application ID or they might be separately registered.

Application context properties may be used to differentiate between instances. The values do not have to be different from other instances, though making them unique is suggested. The context properties are provided through function parameters and/or a sub-buffer.

The group and instance names are provided as function parameters.

Up to twenty (name,value) pairs of context properties may be provided in a sub-buffer.

There is a special case in which a system address sub-buffer is provided. The system address sub-buffer is provided when arm_report_transaction() will be used to report data about transactions that executed on a different system. In this case, the arm_start_application() provides a scoping context for the transaction instances, but does not indicate that the application instance is running on the local system.

The combination of arm_register_application() and arm_start_application() is equivalent to the ARM 2.0 call arm_init().

app_group is a pointer to a null-terminated string containing the identity of a group of application instances, if any. Application instances for a given software product that are started for a common runtime purpose are typically very good candidates for using the same group name. For example, identical replica instances of a product started across multiple processes or servers to address a specific transaction workload objective can be, advantageously to the ARM agent, commonly identified by the group name. The maximum length of the string is 256 (ARM_PROPERTY_VALUE_MAX_CHARS) characters, including the termination character. A null pointer (ARM_STRING_NONE) indicates that there is no group.

app_handle is a pointer to an arm_int64_t into which the ARM library will store the value of the handle that will represent the application instance in all calls, up to and including the arm_stop_application() that indicates that the instance has completed executing. The scope of the handle is the process in which the arm_start_application() is executed. 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 arm_start_transaction(), without the application needing to do any error checking. Whether the data is meaningful, or partially meaningful, is at the discretion of the ARM implementation.

app_id is a pointer to a 16-byte ID returned by an arm_register_application() call.
  app_instance is a pointer to a null-terminated string containing the identity of this instance of the application. It might contain the process ID, or a UUID in printable characters, for example. The maximum length of the string is 256 (ARM_PROPERTY_VALUE_MAX_CHARS) characters, including the termination character. A null pointer (ARM_STRING_NONE) indicates that there is no instance value.

buffer4 is a pointer to the user data buffer, if any. If the pointer is null (ARM_BUF4_NONE), there is no buffer. The sub-buffer formats that might be used are arm_subbuffer_app_context_t and arm_subbuffer_system_address_t.
  If no system address sub-buffer is provided on arm_start_application(), all transactions reported by this application instance execute in the current process.
  If a system address sub-buffer is provided on arm_start_application(), all transactions execute in a different process.
  If a system address sub-buffer is provided in which the system address length is zero, or the system address pointer is null, the system is the "local" system, as determined by the ARM implementation.
  If a system address sub-buffer is provided in which there is a non-null system address and length, the system may be the local system or a remote system. Interpretation of what is local versus remote is at the discretion of the ARM implementation.

flags contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).

RETURN VALUE

On success, the function returns ARM_SUCCESS. A non-zero value indicates an error.

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:

ARM_FAILURE_NULL_ARGUMENT

The app_handle pointer must not be null.

ARM_FAILURE_INVALID_ARGUMENT

One or both of app_group or app_instance are non-null and invalid strings.

ARM_FAILURE_INTERNAL_ERROR

An internal error has occurred that prevented the operation from completing. Check your system log for more details.

CONFORMING TO

ARM Issue 4.0 C Language Bindings, Version 2

EXAMPLE

None.