.ig
################################################################################
#
# man-page for Application Response Measurement (ARM) library routines
#
# (c) Copyright 1989-2001, Hewlett-Packard Company, all rights reserved.
#  
################################################################################
..
.TH arm 3
.ds )H Hewlett-Packard Company

.SH NAME
arm - Application Response Measurement (ARM) library routines

.nf
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.

.SH SYNOPSIS
.BR "#include <arm.h>"
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B "\-larm "
.RI "[ " "library" " \|.\|.\|. ]"

int32 \fBarm_init\fP(char* appname, char* appl_user_id, int32 flags, char* data, int32 data_size);

int32 \fBarm_getid\fP(int32 appl_id, char* tran_name, char* tran_detail, int32 flags, char* data, int32 data_size);

int32 \fBarm_start\fP(int32 tran_id, int32 flags, char* data, int32 data_size);

int32 \fBarm_update\fP(int32 arm_handle, int32 flags, char* data, int32 data_size);

int32 \fBarm_stop\fP(int32 arm_handle, const int32 comp_status, int32 flags, char* data, int32 data_size);

int32 \fBarm_complete_transaction\fP(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 \fBarm_end\fP(int32 appl_id, int32 flags, char* data, int32 data_size);

.SH 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 
.B 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.

.SH FUNCTIONS
The header file
.B arm.h
defines the ARM structures and prototypes.

The ARM library,
.B libarm,
provides the following functions:

.TP 5 
.B int32 arm_init\fP(
 \fBchar* appname,      \fP/* application name             */
 \fBchar* appl_user_id, \fP/* Name of the application user */
 \fBint32 flags,        \fP/* Reserved = 0                 */
 \fBchar* data,        \fP /* Reserved = NULL              */
 \fBint32 data_size\fP)    /* Reserved = 0                 */
.IP "" 10
The
.B arm_init
function call returns a unique ARM identifier based on the 
application name and the name of the user.  You must call
.B arm_init
at the beginning of each application you define and before any
other ARM API calls. 

.B appname 
is the name used to identify the application. The maximum length
is 128 characters including the NULL string terminator character.

.B appl_user_id
is the name of the application user.  The maximum 
length is 128 characters including the NULL string terminator.  
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.

.B flags
must be set to zero.

.B data
must be set to NULL.

.B data_size
must be set to zero.

.TP 5
.B int32 arm_getid\fP(
 \fBint32 appl_id,     \fP/* application handle                */
 \fBchar* tran_name,   \fP/* transaction name                  */
 \fBchar* tran_detail, \fP/* transaction additional info       */
 \fBint32 flags,       \fP/* Reserved = 0                      */
 \fBchar* data,        \fP/* format definition of user metrics */
 \fBint32 data_size\fP)   /* length of data buffuer            */
.IP "" 10
The
.B arm_getid
function call returns a unique ARM identifier based
on a transaction name.  The identifier is passed to the
.B arm_start
calls.  The call to
.B arm_getid
needs to be called only once inside the application for each 
transaction class.
The 
.B tran_id
generated can be used for multiple calls to 
.B arm_start\fP.

.B appl_id 
is the identifier returned by a prior call to
.B arm_init\fP.

.B 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 characters including the NULL 
string terminator.

.B 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 characters including the NULL string 
terminator.

.B flags
must be set to zero.

.B data
is a pointer to a buffer that describes the format of additional 
data that can be passed on 
.B arm_start\fP,
.B arm_update\fP,
and
.B arm_stop
calls. If no additional data is passed on these calls, this 
parameter must be set to zero.

.B data_size
is the length in bytes of the buffer pointed by
.B data\fP.
If
.B data
is set to zero,
.B data_size
must also be set to zero.

.TP 5
.B int32 arm_start\fP(
 \fBint32 tran_id,   \fP   /* transaction name identifier */
 \fBint32 flags,     \fP   /* Reserved = 0                */
 \fBchar* data,      \fP   /* user metrics data           */
 \fBint32 data_size\fP)    /* length of data buffer       */
.IP "" 10 
Use the 
.B 
arm_start 
function call to mark the beginning of a transaction.

.B tran_id
is the unique identifier assigned to the transaction name.  This
is the id generated by a prior call to
.B arm_getid\fP.  If 
.B tran_id
is negative, arm_start will function as a NOP and return a 
negative value.

.B flags
must be set to zero.

.B data
is a pointer to a buffer with additional data that can optionally
be passed, such as user defined metrics and correlator. If no 
additional data is passed, this parameter must be set to zero.

.B data_size
is the length in bytes of the buffer pointed by
.B data\fP.
If
.B data
is set to zero, 
.B data_size
must also be set to zero.

The value returned by
.B arm_start
must be passed to  
.B arm_stop
or
.B arm_update
as the 
.B start_handle\fP.
This
.B start_handle
defines the unique occurrence of a start/stop or pair for each
transaction that you define.


.TP 5
.B int32 arm_update\fP( 
 \fBint32 arm_handle, \fP/* unique transaction handle */
 \fBint32 flags,      \fP/* Reserved = 0              */
 \fBchar* data,       \fP/* user metrics data         */
 \fBint32 data_size\fP)  /* length of data buffer     */
.IP "" 10 
Use the
.B arm_update
function call to provide extra information about a transaction or
show the progress of a long transaction.

.B arm_handle
is the unique start_handle returned from a corresponding 
.B arm_start
call. The
.B arm_handle
parameter must be passed in an unaltered state from the 
corresponding
.B arm_start
call. If
.B arm_handle
is less than zero, this
.B arm_update
call will be treated as a NULL operation, and a negative value 
returned.

.B flags
must be set to zero.

.B data
is a pointer to a buffer with additional data that can optionally
be passed, such as user defined metrics (the correlator field is
not used in the 
.B arm_update
call). If no additional data is passed, this parameter must be
set to zero.

.B data_size
is the length in bytes of the buffer pointed by 
.B data\fP.
If
.B data
is set to zero, 
.B data_size
must also be set to zero.

.TP 5
.B int32 arm_stop\fP( 
 \fBint32 arm_handle,        \fP/* unique transaction handle */
 \fBconst int32 comp_status, \fP/* Good=0, Abort=1, Failed=2 */
 \fBint32 flags,             \fP/* Reserved = 0              */
 \fBchar* data,              \fP/* user metircs data         */
 \fBint32 data_size\fP)         /* length of data buffer     */
.IP "" 10 
Use the
.B arm_stop
function call to mark the end of a transaction.

.B arm_handle
is the unique start_handle returned from a corresponding 
.B arm_start
call.  The 
.B arm_handle
parameter must be passed in an unaltered state from the 
corresponding
.B arm_start
call.

.B 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)

.B flags
must be set to zero.

.B data
is a pointer to a buffer with additional data that can optionally
be passed, such as user defined metrics (the correlator field is 
not used in the 
.B arm_stop
call). If no additional data is passed, this parameter must be 
set to zero.

.B data_size
is the length in bytes of the buffer pointed to by 
.B data\fP.
If 
.B data
is set to zero, 
.B data_size 
must also be set to zero.

.TP 5
.B int32 arm_complete_transaction\fP(
 \fBchar* p_tran_id,   \fP   /* Pointer to tran id from arm_getid() */
 \fBchar* tran_handle, \fP   /* Reserved = NULL          */
 \fBchar* user_name,   \fP   /* Reserved = NULL          */
 \fBint32 tran_status, \fP   /* Completion status Good=0 */
 \fBint64 resp_nsecs,  \fP   /* Response time in nanoseconds  */
 \fBvoid* stop_time,   \fP   /* Reserved = NULL          */
 \fBint32 flags,       \fP   /* Reserved = 0             */
 \fBchar* data,        \fP   /* user metrics data        */
 \fBint32 data_size\fP)      /* length of data buffer    */
.IP "" 10 
Use the 
.B 
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.

.B tran_id
is a pointer to the unique identifier assigned to the transaction
name.  This is the id generated by a prior call to
.B arm_getid\fP.  Note that this call, unlike arm_start, is 
looking for a pointer to the transaction ID not the ID itself.

.B tran_handle
must be set to NULL.

.B user_name
must be set to NULL.

.B 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)

.B resp_nsecs
is the response time for the completed transaction.  It must be 
provided in nanosecond units, so a (64bit integer) value of 1 
billion would represent 1 second.

.B stop_time
must be set to NULL.

.B flags
must be set to zero.

.B data
is a pointer to a buffer with additional data that can optionally
be passed, such as user defined metrics and correlator. If no 
additional data is passed, this parameter must be set to zero.

.B data_size
is the length in bytes of the buffer pointed by
.B data\fP.
If
.B data
is set to zero, 
.B data_size
must also be set to zero.

.TP 5
.B int32 arm_end\fP(
 \fBint32 appl_id,   \fP/* application id  */
 \fBint32 flags,     \fP/* Reserved = 0    */
 \fBchar* data,      \fP/* Reserved = NULL */
 \fBint32 data_size\fP) /* Reserved = 0    */
.IP "" 10 
.B arm_end
marks the end of an application.  You should call arm_end just 
before the application program terminates.

.B appl_id 
parameter must be passed from the
corresponding 
.B arm_init
call in an unaltered state.  

.B flags
must be set to zero.

.B data
must be set to NULL.

.B data_size
must be set to zero.

.SH RETURN VALUE
.TP
.B arm_init()
returns an identifier which is a unique reference to an 
application/user. This identifier needs to be passed to the
.B arm_getid()
and
.B arm_end()
calls.  In case of failure,
.B arm_init()
returns one of the following negative values:

.B ARM_APPAMETOOLONG\fP. 
The application name parameter contains a value that is longer
than ARM_MAXNAMELEN.

.B ARM_USERNAMETOOLONG\fP. 
The user name parameter contains a value that is longer than
ARM_MAXNAMELEN.

.B ARM_NOMEMAVAIL\fP. 
There is no memory available to complete this operation.                 


.TP
.B arm_getid()
returns a unique transaction identifier that is >= 0.
The
.B 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 
.B arm_start()
function calls.
In the case of failure,
.B arm_getid()
returns one of the following negative values and
.I errno
is set accordingly:

.B ARM_INVID\fP.
.I errno
= EINVAL - Invalid arguments.

.B ARM_TTDNOTRUNNING\fP.  
.I errno
= EPIPE - ttd (registration daemon) not
running.  Also returned if the client application cannot connect
to a running ttd.

.B ARM_NAMENOTFOUND\fP. 
.I errno
= ESRCH - The name was not found or matched using the wildcard 
facility in the configuration file (see ttd.conf.4).

.B ARM_BADOSVERS\fP. 
.I errno
= EOPNOTSUPP - ARM library (libarm) not compatible with operating
system.

.TP
.B arm_start()\fP
returns a \fBstart_handle\fP
value which is passed in an unaltered state into corresponding 
.B arm_update()\fP or \fBarm_stop()\fP
calls.

.TP
.B arm_update()
returns an \fBerror_status\fP
value which is zero if there is no error, a negative value 
denotes an error has occured.

.TP
.B arm_stop()\fP
returns an \fBerror_status\fP
value which is zero if there is no error, a negative value 
denotes an error has occured.

.TP
.B arm_complete_transaction()\fP
returns an \fBerror_status\fP
value which is zero if there is no error, a negative value 
denotes an error has occured.

.TP
.B arm_end()\fP
returns an \fBerror_status\fP
value which is zero if there is no error, a negative value
denotes an error has occured.

.SH DEPENDENCIES
.TP
.B arm_init()\fP and
.B arm_getid()
will fail if the registration daemon
.B ttd
is not running. 

.TP
.B arm_start(), arm_update(), arm_stop(), and 
arm_complete_transaction() will fail if the processing daemon 
.B midaemon
is not running.

.SH MULTITHREAD USAGE
.RS 0
.TP 22
.PD 0
.B Thread Safe:
.BR Yes
.TP
.B Cancel Safe:
.BR Yes
.TP
.B Fork Safe:
.BR No
.TP
.B Async-cancel Safe:
.BR No
.TP
.B Async-signal Safe:
.BR No
.RE
.PD
.PP
The libarm code has a dependency on the pthread library.
These functions can be called safely in a multithreaded 
environment.  They may be cancellation points in that they call
functions that are cancel points.
.PP
In a multithreaded environment, these functions are
not safe to be called by a child process after
.CR fork()
and before
.CR exec() .
These functions should not be called by a multithreaded 
application that supports asynchronous cancellation or 
asynchronous signals.

.SH EXAMPLES

.P
ARM example programs are shipped with the product.  See the 
product ReleaseNotes for locations.

.SH SEE ALSO
.nf
ARM API Guide and Tracking Your Transactions manuals. 
Printable copies may reside under this product's paperdocs 
directory. Also, \fBttd(1)\fP, \fBttd.conf(4)\fP, and
\fBmidaemon(1)\fP