arm(3)arm(3)NAMEarm - Application Response Measurement (ARM) library routines
Note: The following terminology is used to define each of the parameters.
int32 - A signed 32-bit integer
char* - A 32-bit pointer to a character string or data
structure. Strings must be NULL terminated.
SYNOPSIS
#include <arm.h>
cc [ flag ... ] file ... -larm [ library ... ]
int32 arm_init(char* appname, char* appl_user_id, int32 flags, char*
data, int32 data_size);
int32 arm_getid(int32 appl_id, char* tran_name, char* tran_detail,
int32 flags, char* data, int32 data_size);
int32 arm_start(int32 tran_id, int32 flags, char* data, int32
data_size);
int32 arm_update(int32 arm_handle, int32 flags, char* data, int32
data_size);
int32 arm_stop(int32 arm_handle, const int32 comp_status, int32 flags,
char* data, int32 data_size);
int32 arm_complete_transaction(char* p_tran_id, char* tran_handle,
char* user_name, int32 tran_status, int64 resp_nsecs, void* stop_time,
int32 flags, char* data, int32 data_size);
int32 arm_end(int32 appl_id, int32 flags, char* data, int32 data_size);
DESCRIPTION
ARM library routines allow you to define and measure response time of
transactions in any application that uses a programming language that
can call a C function.
The ARM library is named libarm and is provided in two versions: a
shared library version, and a "NO-OP" version which can be used for
testing.
The locations of the include file and libraries vary by platform and
are listed in the product ReleaseNotes file. See also the Tracking
Your Transactions manual.
FUNCTIONS
The header file arm.h defines the ARM structures and prototypes.
The ARM library, libarm, provides the following functions:
int32 arm_init(
char* appname, /* application name */
char* appl_user_id, /* Name of the application user */
int32 flags, /* Reserved = 0 */
char* data, /* Reserved = NULL */
int32 data_size) /* Reserved = 0 */
The arm_init function call returns a unique ARM identifier
based on the application name and the name of the user. You
must call arm_init at the beginning of each application you
define and before any other ARM API calls.
appname is the name used to identify the application. The
maximum length is 128 characters including the NULL string
terminator character.
appl_user_id is the name of the application user. The maxi‐
mum length is 128 characters including the NULL string termi‐
nator. Set this value to "*" to indicate the login user ID
of the process making this call. If you do not provide a
value for this parameter, you must specify the NULL value.
flags must be set to zero.
data must be set to NULL.
data_size must be set to zero.
int32 arm_getid(
int32 appl_id, /* application handle */
char* tran_name, /* transaction name */
char* tran_detail, /* transaction additional info */
int32 flags, /* Reserved = 0 */
char* data, /* format definition of user metrics */
int32 data_size) /* length of data buffuer */
The arm_getid function call returns a unique ARM identifier
based on a transaction name. The identifier is passed to the
arm_start calls. The call to arm_getid needs to be called
only once inside the application for each transaction class.
The tran_id generated can be used for multiple calls to
arm_start.
appl_id is the identifier returned by a prior call to
arm_init.
tran_name is the unique name of the transaction class. You
must select a unique name for each type of transaction you
want to track. The maximum length of the name is 128 charac‐
ters including the NULL string terminator.
tran_detail provides a way for you to provide additional
information about a transaction class. If no tran_detail is
associated with this transaction, then pass a zero (0) for
this parameter. The maximum length of the name is 128 charac‐
ters including the NULL string terminator.
flags must be set to zero.
data is a pointer to a buffer that describes the format of
additional data that can be passed on arm_start, arm_update,
and arm_stop calls. If no additional data is passed on these
calls, this parameter must be set to zero.
data_size is the length in bytes of the buffer pointed by
data. If data is set to zero, data_size must also be set to
zero.
int32 arm_start(
int32 tran_id, /* transaction name identifier */
int32 flags, /* Reserved = 0 */
char* data, /* user metrics data */
int32 data_size) /* length of data buffer */
Use the arm_start function call to mark the beginning of a
transaction.
tran_id is the unique identifier assigned to the transaction
name. This is the id generated by a prior call to arm_getid.
If tran_id is negative, arm_start will function as a NOP and
return a negative value.
flags must be set to zero.
data is a pointer to a buffer with additional data that can
optionally be passed, such as user defined metrics and corre‐
lator. If no additional data is passed, this parameter must
be set to zero.
data_size is the length in bytes of the buffer pointed by
data. If data is set to zero, data_size must also be set to
zero.
The value returned by arm_start must be passed to arm_stop or
arm_update as the start_handle. This start_handle defines
the unique occurrence of a start/stop or pair for each trans‐
action that you define.
int32 arm_update(
int32 arm_handle, /* unique transaction handle */
int32 flags, /* Reserved = 0 */
char* data, /* user metrics data */
int32 data_size) /* length of data buffer */
Use the arm_update function call to provide extra information
about a transaction or show the progress of a long transac‐
tion.
arm_handle is the unique start_handle returned from a corre‐
sponding arm_start call. The arm_handle parameter must be
passed in an unaltered state from the corresponding arm_start
call. If arm_handle is less than zero, this arm_update call
will be treated as a NULL operation, and a negative value
returned.
flags must be set to zero.
data is a pointer to a buffer with additional data that can
optionally be passed, such as user defined metrics (the cor‐
relator field is not used in the arm_update call). If no
additional data is passed, this parameter must be set to
zero.
data_size is the length in bytes of the buffer pointed by
data. If data is set to zero, data_size must also be set to
zero.
int32 arm_stop(
int32 arm_handle, /* unique transaction handle */
const int32 comp_status, /* Good=0, Abort=1, Failed=2 */
int32 flags, /* Reserved = 0 */
char* data, /* user metircs data */
int32 data_size) /* length of data buffer */
Use the arm_stop function call to mark the end of a transac‐
tion.
arm_handle is the unique start_handle returned from a corre‐
sponding arm_start call. The arm_handle parameter must be
passed in an unaltered state from the corresponding arm_start
call.
comp_status is one of the following transaction completion
codes. 0 = Transaction was successful (defined as ARM_GOOD
in arm.h) 1 = Transaction aborted (defined as ARM_ABORT in
arm.h) 2 = Transaction failed (defined as ARM_FAILED in
arm.h)
flags must be set to zero.
data is a pointer to a buffer with additional data that can
optionally be passed, such as user defined metrics (the cor‐
relator field is not used in the arm_stop call). If no addi‐
tional data is passed, this parameter must be set to zero.
data_size is the length in bytes of the buffer pointed to by
data. If data is set to zero, data_size must also be set to
zero.
int32 arm_complete_transaction(
char* p_tran_id, /* Pointer to tran id from arm_getid() */
char* tran_handle, /* Reserved = NULL */
char* user_name, /* Reserved = NULL */
int32 tran_status, /* Completion status Good=0 */
int64 resp_nsecs, /* Response time in nanoseconds */
void* stop_time, /* Reserved = NULL */
int32 flags, /* Reserved = 0 */
char* data, /* user metrics data */
int32 data_size) /* length of data buffer */
Use the arm_complete_transaction function call to mark the
end of a transaction, ONLY for transaction instances where
arm_start/arm_stop could not be called. This is an extension
to the ARM 2.0 specification unique to HP's ARM agentry and
is not portable.
tran_id is a pointer to the unique identifier assigned to the
transaction name. This is the id generated by a prior call
to arm_getid. Note that this call, unlike arm_start, is look‐
ing for a pointer to the transaction ID not the ID itself.
tran_handle must be set to NULL.
user_name must be set to NULL.
tran_status is one of the following transaction completion
codes. 0 = Transaction was successful (defined as ARM_GOOD
in arm.h) 1 = Transaction aborted (defined as ARM_ABORT in
arm.h) 2 = Transaction failed (defined as ARM_FAILED in
arm.h)
resp_nsecs is the response time for the completed transac‐
tion. It must be provided in nanosecond units, so a (64bit
integer) value of 1 billion would represent 1 second.
stop_time must be set to NULL.
flags must be set to zero.
data is a pointer to a buffer with additional data that can
optionally be passed, such as user defined metrics and corre‐
lator. If no additional data is passed, this parameter must
be set to zero.
data_size is the length in bytes of the buffer pointed by
data. If data is set to zero, data_size must also be set to
zero.
int32 arm_end(
int32 appl_id, /* application id */
int32 flags, /* Reserved = 0 */
char* data, /* Reserved = NULL */
int32 data_size) /* Reserved = 0 */
arm_end marks the end of an application. You should call
arm_end just before the application program terminates.
appl_id parameter must be passed from the corresponding
arm_init call in an unaltered state.
flags must be set to zero.
data must be set to NULL.
data_size must be set to zero.
RETURN VALUEarm_init()
returns an identifier which is a unique reference to an applica‐
tion/user. This identifier needs to be passed to the arm_getid()
and arm_end() calls. In case of failure, arm_init() returns one
of the following negative values:
ARM_APPAMETOOLONG. The application name parameter contains a
value that is longer than ARM_MAXNAMELEN.
ARM_USERNAMETOOLONG. The user name parameter contains a value
that is longer than ARM_MAXNAMELEN.
ARM_NOMEMAVAIL. There is no memory available to complete this
operation.
arm_getid()
returns a unique transaction identifier that is >= 0. The
arm_getid() function call is used to assign a unique identifier
to a unique name of a transaction class. The identifier is
passed to the arm_start() function calls. In the case of fail‐
ure, arm_getid() returns one of the following negative values
and errno is set accordingly:
ARM_INVID. errno = EINVAL - Invalid arguments.
ARM_TTDNOTRUNNING. errno = EPIPE - ttd (registration daemon)
not running. Also returned if the client application cannot
connect to a running ttd.
ARM_NAMENOTFOUND. errno = ESRCH - The name was not found or
matched using the wildcard facility in the configuration file
(see ttd.conf.4).
ARM_BADOSVERS. errno = EOPNOTSUPP - ARM library (libarm) not
compatible with operating system.
arm_start()
returns a start_handle value which is passed in an unaltered
state into corresponding arm_update() or arm_stop() calls.
arm_update()
returns an error_status value which is zero if there is no
error, a negative value denotes an error has occured.
arm_stop()
returns an error_status value which is zero if there is no
error, a negative value denotes an error has occured.
arm_complete_transaction()
returns an error_status value which is zero if there is no
error, a negative value denotes an error has occured.
arm_end()
returns an error_status value which is zero if there is no
error, a negative value denotes an error has occured.
DEPENDENCIESarm_init() and
arm_getid() will fail if the registration daemon ttd is not run‐
ning.
arm_start(), arm_update(), arm_stop(), and
arm_complete_transaction() will fail if the processing daemon
midaemon is not running.
MULTITHREAD USAGE
Thread Safe: Yes
Cancel Safe: Yes
Fork Safe: No
Async-cancel Safe: No
Async-signal Safe: No
The libarm code has a dependency on the pthread library. These func‐
tions can be called safely in a multithreaded environment. They may be
cancellation points in that they call functions that are cancel points.
In a multithreaded environment, these functions are not safe to be
called by a child process after and before These functions should not
be called by a multithreaded application that supports asynchronous
cancellation or asynchronous signals.
EXAMPLES
ARM example programs are shipped with the product. See the product
ReleaseNotes for locations.
SEE ALSO
ARM API Guide and Tracking Your Transactions manuals.
Printable copies may reside under this product's paperdocs
directory. Also, ttd(1), ttd.conf(4), and
midaemon(1)arm(3)