NAME

arm_init - define the application or a unique instance of the application and user.

SYNOPSIS

appl_id=arm_init(appl_name,appl_user_id,flags,data,data_size)

DESCRIPTION

Use arm_init() to define the application or a unique instance of the application and user. Function arm_init() must be called before any other ARM API calls. It is often called when an application initializes. The return code is an application/user identifier that is input as a parameter on arm_getid(), to associate transactions with the application.

Each application needs to be identified by a unique name. It is the developer's responsibility to choose a name that is meaningful but which is not duplicated by other developers. Suggestions for names would be the product name and version number, or a project name.

There can be any number of application instances executing simultaneously that use the same application name, or the same application and user names. A measurement agent may assign a unique application identifier to each application instance, or it may assign an identifier that is shared across identically named instances.

PARAMETERS

appl_name (char*)

The name used to identify the application. The maximum length is 128 bytes including the NULL string terminator.

appl_user_id (char*)

The name of the application user. On UNIX and Windows NT, this value can be set to "*" to indicate the login user ID of the person running the application. The maximum length is 128 bytes including the NULL string terminator. If no value is preferred for this parameter, it should be specified as NULL value (0).

flags (int32)=0

Reserved for future use. It must be set to zero.

data (char*)=0

Reserved for future use. A NULL value (0) must be used.

data_size (int32)=0

Reserved for future use. It must be set to zero.

RETURN CODE

appl_id (int32)

A unique value to reference an application/user identifier. This id must be passed to the arm_getid call.

ERRORS

If the value returned in appl_id is less than zero, an error occurred in communicating with the measurement agent. The value returned on an error can be passed to arm_getid(), which will cause arm_getid() to function as a NULL operation. The error should be logged so corrective action can be taken.

EXAMPLE

my_appl_id = arm_init ("Parts Inventory Manager 1.1",  /* appl name */
                       "*",                            /* user id   */
                       0, 0, 0);         /* reserved for future use */