arm man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

arm(3)									arm(3)

NAME
       arm - 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 VALUE
       arm_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.

DEPENDENCIES
       arm_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)
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net