This chapter provides information about the response time measurement facilities of the Performance Toolbox and the Performance Aide. Except where otherwise noted, the facilities described are available on all platforms supported by the Performance Aide. Monitoring of response times across the network can be done from AIX workstations only.
Response time measurement is especially important in a client/server environment and is ideally done on a transaction basis. The problem is that a "transaction" is an elusive concept. Between client and server, transactions may range from causing a single network transmission with no response to involving a large number of transmissions. In any one customer installation, one or a few "typical" transactions may be found, and the selected transactions can then be instrumented (possibly through the implementation of the Application Response Measurement API (ARM) described in the section Application Response Time Measurement (ARM) . Using the response time measurement of a few transaction types representing a large percentage of the actual transactions performed, it is possible to get a feel for the responsiveness of all or most transaction types.
Transaction instrumentation is the most precise vehicle for response time measurement but for this concept to work, the installation must be willing to invest in the analysis of transaction patterns and instrumentation of transaction programs. The installation must also be able to modify the transaction programs, which is not always possible. For example, how does one instrument a standard SQL query program? Because it's expensive, somewhat complex, and often plain impossible to use the transaction instrumentation concept, other means must be used in an attempt to monitor system responsiveness.
Those other means involve the measurement of the atomic components that, together, add up to the response time of a given transaction. The following is a list of some major steps in a client/server application. Each is followed by some resources that are required by the task and, hence, will influence the response time component if they are scarce.
All of the resources in the above list can be monitored by PTX when it comes to activity counts. Disks can be monitored for the percent of time they are busy, which give a good feel for their responsiveness, but networks can be monitored only for the activity counts. Furthermore, while activity counts for disks can be used to judge how close a disk is to being saturated, the activity counts for one machine's network adapter may have little or no connection to the actual load on the network. Maybe one machine is constantly accessing remote files while another seldom is. The low activity count on the second machine is no guarantee for a fast response when the machine does need remote access.
It only makes the situation worse that, in a typical client/server application, the largest response time component is usually the time is takes to get the request sent and the response back. That's why the IP response time measurement facility was added to PTX. IP response time measurement works by using the low level Internet Control Management Protocol (ICMP) to send responses to selected hosts and measuring the time it takes to get a response back. The ICMP protocol was chosen because it doesn't require an application to be running on the remote host, since the protocol is handled by the IP implementation itself.
In PTX, IP response time measurement is implemented through a daemon and corresponding contexts in the Spmi data hierarchy. The Spmi will start the daemon as required and will dynamically add contexts for all the remote hosts, for which monitoring is started.
Measuring of response times is done by a daemon called SpmiResp. If this daemon is not running when the Spmi receives a request for IP response time measurements, it is started by the Spmi library code. The daemon will continue to run until it has been the only user of the Spmi interface for 60 seconds or no data consumer has requested response time data for 300 seconds. When running, the SpmiResp daemon is controlled by an interval timer loop. The interval timer is, by default, set to interrupt the daemon every 10 seconds but the interval value can be changed from the daemon's configuration file /etc/perf/Resptime.cf.
Whenever the daemon is interrupted by the timer, it starts a new cycle, sending one ICMP packet to each host for which response time is being monitored and calculating the response time from the time it takes for the response to come back. The daemon will not attempt to send more frequently than specified by a variable maxrate, which defaults to 10 packets per second but can be changed from the daemon's configuration file /etc/perf/Resptime.cf. When sending packets, the daemon will attempt to spread its activity evenly over the the interval seconds a cycle lasts. If the number of monitored hosts is too large for all hosts to be contacted within interval seconds without exceeding maxrate, then interruptions by the interval timer are ignored until a full cycle has been completed. The reason for having the maxrate parameter is to prevent the measurement of network activity from being distorted by burst of ICMP packets from the response time monitor.
When a response is received to an ICMP package, the response time is calculated as a fixed point value in milliseconds. In addition. the weighted average response time is calculated as a floating point value using a variable weight, that defaults to 75%. The average response time is calculated as weight percent of the previous value of the average plus (100 - weight) percent of the latest response time observation. The value of weight can also be changed from the daemon's configuration file /etc/perf/Resptime.cf.
The following metrics are maintained. Except where noted, all values are floating point values:
The SpmiResp daemon looks for a configuration file in /etc/perf/Resptime.cf. Three values can be specified in this file. A keyword identifies which value is being set. The keyword must appear in column one of a line and white space must separate the keyword and the value. The three values, as identified by the corresponding keywords are:
If no configuration file is found, SpmiResp continues with default control values. The detailed meaning and use of the three values is described in the section IP Response Time Daemon .
The daemon will catch all major signals. All, with the exception of SIGHUP, will cause the daemon to shut gracefully down. SIGHUP will cause the daemon to reread its configuration file. Any value specified in the configuration file will replace whichever corresponding value is currently active.
For applications to be able to monitor response time through the Spmi and, ultimately, the RSi interface, the data must be available in context and metric data structures in the Spmi shared memory area. However, it would be very resource consuming to create these data structures for all hosts in a large network, so the Spmi has been modified to handle response time contexts different from all other context types. What happens is that a context for a particular host is not created until some consumer of data refers to that context by its path name.
For a data consumer program to see the IP response time context for a host, either some other program must have created the context, or the program itself must attempt to get to the context through the context's path name. For example, to create (or access if somebody else created it) the context for the host farvel, the application could issue the call:
SpmiPathGetCx("RTime/LAN/farvel", NULL);
The same effect is achieved by issuing the RSiPathGetCx subroutine call , which ultimately leads to an SpmiPathGetCx subroutine call on the agent host the RSi call is issued against.
This implementation leaves the Data Consumer applications with the responsibility of identifying hosts to monitor for IP response time. This is contrary to all other contexts in the Spmi, which can be instantiated simply by traversing their parent contexts. If an installation wants to make sure all IP response time contexts are created, the sample Data Consumer program in /usr/samples/perfagent/server/iphosts.c, which is also shipped as the executable iphosts, can be executed from the xmservd.res file whenever xmservd starts. This program will take a file with a list of hostnames as input and will issue the SpmiPathGetCx call for each host.
Because IP response time measurement uses the ICMP protocol, the hosts you want to monitor do not need to run the xmservd daemon. All that is required is that they can respond properly to ICMP echo requests. Because of this, response time to any node that talks ICMP - including dedicated routers and gateways - can be measured.
Two PTX applications use their knowledge of hosts in the network to present their users with lists of potential IP response time contexts. The two are xmperf and 3dmon. This is described in sections Monitoring IP Response Time from xmperf and Monitoring IP Response Time from 3dmon .
The xmperf program presents its user with potential IP response time contexts in two situations:
In both cases, the list of potential IP response time contexts includes the hosts whose xmservd daemons responded to invitations from xmperf, as well as hosts for which contexts were added by other means such as by the iphosts program. If the host is known by two names (typically by the short hostname and the full host/domain name) the same host may appear twice in the list. The same may happen if the iphosts program identifies hosts by their IP addresses rather than their hostnames.
When the user wants to add a statistic to an instrument or exchange one statistic value with another, the value selection windows are used to select the new statistic. If the user selects RTime from the top value selection window and from the next window selects LAN, then the new value selection window displayed will show one context for each host that can be monitored. By selecting a host, you automatically create the context for measurement of response time for that host if the context doesn't exist. You then proceed to the value selection window for that context.
When a user instantiates an IP response time measurement skeleton console, the list of hosts to select from looks like any other host selection list, except that the list may contain lines that do not show an IP address. Such lines represent hosts for which an IP response time context exists but that have not responded to the xmperf invitation. If instantiation is tried again after the host list has been refreshed, more hosts may have IP addresses shown. This reflects how the host list is created: If the same hostname is available from both the list of hosts that responded to invitations and from existing IP response time contexts, then the entry from the list of responding hosts is used. Also, if a host is a little late responding to an invitation, it may first show up without its IP address. After the response to the invitation finally is received, it will show up with its IP address.
It is possible to create xmperf instruments that monitor response times for multiple hosts. This illustrates that even though it looks like the instrument receives data_feed packets from multiple hosts, in reality it receives packets from only one host. As always, all values in an instrument must come from the same host and must be defined in the same statset. What really happens is, of course, that the Spmi on the measurement host receives ICMP responses (not data feeds) from the monitored hosts and has been instructed to supply the calculated response time data in statsets.
The looks of an instrument measurement IP response time for multiple hosts and of a console with multiple instruments, each monitoring IP response time for multiple hosts can be deceiving, though. You may be tempted to change the path of an instrument or the entire console, expecting to be able to select a new list of hosts to monitor. What you get, though, is a list of hosts from which you can select one host, which will then be the new monitoring host (not the new monitored) host.
The 3dmon program takes a different approach to monitoring IP response time. It does so in a matrix that monitors the response time in both directions. For example, if you elect to monitor response times for three hosts, trist, ked, and nede, then the matrix would look like this:
NN
KN NK
TN KK NT
nede TK KT nede
ked TT ked
trist trist
The right side of the matrix represents the monitoring hosts and the left side represents the monitored hosts. Thus, the value represented in the cell marked NT is the response time for a response to an ICMP echo packet sent from host nede to host trist. The response time for a response to an ICMP echo packet sent in the other direction is shown in the cell marked TN. This measuring of response time in both directions allows for the detection of situations where two hosts use different routes to reach each other and it can also be used to pinpoint other anomalities in a network.
Because of the way 3dmon monitors IP response time, all of the hosts must be running the xmservd daemon. Therefore, when 3dmon shows a list of hosts to monitor IP response times for, only hosts that responded to invitations from 3dmon are included. The distributed 3dmon.cf sample configuration file includes a configuration set named lanresp for monitoring of IP network response time.
This section describes the Performance Aide and Performance Toolbox implementation of the Application Response Measurement API (ARM). To see where ARM would be useful, let's revisit the list of common steps a client/server transaction goes through:
An application can be instrumented at many levels. For example, one set of measurements could cover the entire period from the beginning of step 1 to the end of step 9. Another, potentially simultaneous, set of measurements could cover the server side beginning with step 4 or 5 and ending with step 6. The ARM API, in its current, unfinished state, depends on the instrumentation to supply meaningful names to applications and transactions. Without such names, measurement would be impossible.
As implemented in PTX, the ARM support is limited by the design of ARM as done by the original designers. Specifically, the two-level naming structure of PTX, where every context and metric has a short name and a long descriptive name was not implemented in ARM. This puts a single requirement on how an application is instrumented: The first 31 bytes of the description of an application and a transaction must uniquely define that application and transaction within the application.
Applications are added to the Spmi data hierarchy as contexts. An application with the description "Checking Account Query" will be added as the context:
RTime/ARM/CheckingAccountQuery
A transaction of that application called "Last Check Query" would be added to the above context as another context level and get a full path name of:
RTime/ARM/CheckingAccountQuery/LastCheckQuery
If the transaction was named "Check if any check of this account has bounced during the past 12 months", the full path name of the transaction context would be:
RTime/ARM/CheckingAccountQuery/Checkifanycheckofthisaccounthas
With the short name being truncated to 31 characters. The full name of the transaction would appear in the description of the transaction context, truncated to 63 characters if necessary.
For each transaction, the following metrics are maintained. All metrics, with the exception of respavg are fixed point values:
In order to reduce the memory usage, we do not attempt to determine the median response time or the 80-percentile.
The ARM API is not implemented by Performance Aide on the SunOS operating system.
At this point, the arm_update subroutine is implemented as a null function. This is because the current monitors of PTX wouldn't be able to monitor transaction progress in a well-defined manner. This may change in a future version of PTX. Other implementation restrictions are listed under each API function.
For the SpmiArmd daemon to get write access to the Spmi common shared memory, the daemon must be started with root or system group authority. The safest way to make this happen is to make sure the xmservd daemon is always running. This can be accomplished by entering the flag -l0 (lower case L followed by a zero) to the server's line in /etc/inetd.conf. It is also recommended that the following line is added to the appropriate xmservd.res file, which is used to (among other things) start data suppliers:
supplier: /usr/bin/SpmiArmd
Because the PTX implementation uses shared memory, and because library code can't feasibly catch all relevant signals, application instrumentors must make sure that an arm_end call is issued for each active application. If a program exits while applications it defined are still active, the shared memory area will not be released and the SpmiArmd daemon will assume that data is still being supplied and will not attempt to exit. This is not likely to be a major draw-back but if things get tricky, it may be necessary to stop the daemon (and all other programs using the Spmi) and clear shared memory manually as described in the PTX Guide and Reference manual.
The ARM specifications prescribe that the ARM library is shipped as a shared library such as libarm.a or libarm.so. Replacing the installed library with another library with the same interfaces will redirect application subroutine calls to the library installed last. The implementation of ARM in PTX follows these specifications but also allows a customer installation to invoke both an existing ARM library and the PTX implementation of ARM. This is achieved by shipping two libraries:
To use the replacement library, convert the preexisting ARM library by running the following command:
armtoleg /usr/lib/libarm.a /usr/lib/libarmrepl.a > /dev/null
Then copy /usr/lib/libarm2.a over /usr/lib/libarm.a. The replacement library will invoke the ARM functions in /usr/lib/libarmrepl.a before invoking the PTX ARM implementation in the replacement library. This way, a customer installation can continue to use an earlier ARM instrumentation and at the same time take advantage of the PTX implementation of ARM. When the replacement library is used, the behavior of the PTX ARM implementation changes but remains compliant with the ARM specifications. This is explained in the section ARM Replacement Library Implementation .
Note:IBM can't and doesn't warrant that it is possible or feasible to convert some third party vendor's library as described.
IBM can not be held responsible for any damages, whether directly or indirectly resulting from converting a third party vendor's library as described. It is the customer's responsibility to take all necessary precautions agains destruction of data or programs, including the responsibility to keep a copy of the original library for backup purposes.
Both PTX libraries depend on the SpmiResp daemon to be started by the Spmi library code. This daemon must run with root authority in order to interface directly with the Spmi common shared memory area. The daemon is described in the SpmiArmd Daemon section .
The library code maintains state in a private shared memory area, which can be accessed with any authority, thus allowing applications to do so through the library calls. The library communicates with the Spmi through the SpmiArmd daemon, which issues standard Spmi subroutine calls. No direct communication takes place between the Spmi and the ARM library.
The use of two environment variables allows an application to turn both levels of ARM instrumentation on and off. Since they are environment variables, they work for the shell from which the application is executed and have no effect on the execution from other shells. The two environment variables are:
INVOKE_ARM
Controlls the PTX ARM instrumentation. If the environment variable is not defined or if it has any value other than "false", PTX ARM instrumentation is active. If the replacement library is not used, the effect of setting this environment variable to "false" is that the PTX ARM library will function as a no-operation library, return zero on all calls.
INVOKE_ARMPREV
Controlls any ARM instrumentation that can be invoked from the PTX implementation through the replacement library. If the environment variable is not defined or if it has any value other than "false", the preexisting ARM instrumentation will be invoked, regardless of whether the PTX ARM instrumentation is active. If the replacement library is not used, this environment variable has no effect.
If both environment variables are set to "false", either PTX ARM library will function as a no-operation library, return zero on all calls.
Collection of application response times is done by a daemon called SpmiArmd. If this daemon is not running when the Spmi receives an SpmiGetCx subroutine call referencing ARM contexts, it is started by the Spmi. The daemon will continue to run until it has been the only user of the Spmi interface for 15 minutes and no data has been recieived from an instrumented application for 15 minutes. The time to live can be changed from the daemon's configuration file /etc/perf/SpmiArmd.cf. When running, the SpmiArmd daemon is controlled by an interval timer loop. The interval timer is, by default, set to interrupt the daemon every second but the interval value can be changed from the daemon's configuration file /etc/perf/SpmiArmd.cf.
Whenever the daemon is interrupted by the timer, it empties the entire queue of post structures with the exception of the last entry (see ATake ), using each to update the corresponding metrics. The metrics are updated as follows:
To eliminate the daemon from the need to lock data in the ARM library's private shared memory area, the following technique is used to control the linked list of post structures. Three fields in the shared memory control area are used as anchors:
The daemon catches all viable signals and will exit for all but SIGHUP. When the daemon receives a SIGHUP signal, it rereads the configuration file and re-initializes its control variables to any new values specified in the configuration file.
The SpmiArmd daemon looks for a configuration file in /etc/perf/SpmiArmd.cf. Three values can be specified in this file. A keyword identifies which value is being set. The keyword must appear in column one of a line and white space must separate the keyword and the value. The three values, as identified by the corresponding keywords are:
If no configuration file is found, SpmiArmd continues with default control values.
The xmperf program presents its user with ARM contexts in two situations:
When the user wants to add a statistic to an instrument or exchange one statistic value with another, the value selection windows are used to select the new statistic. If the user selects RTime from the top value selection window and from the next window selects ARM, then the new value selection window displayed will show one context for each application that can be monitored. By selecting an application you are taken to the next selection window, which will present a list of the transactions defined for the application. By selecting a transaction context you proceed to the value selection window for that application/transaction context.
ARM skeleton consoles must be defined for each application you want to monitor because xmperf doesn't support dual wildcards (as does 3dmon). When a user instantiates an ARM skeleton console, a list of transactions within the application is presented for the user to select from. Each line represent an application/transaction context. One or multiple lines can be selected.
It is not possible to create xmperf instruments that monitor ARM data for multiple hosts. However, consoles can be constructed with instruments that each monitor a different host. ARM instruments can be remounted on different hosts as any other instrument.
The 3dmon program permits wildcarding in multiple levels. This allows you to create configurations corresponding to those available for file systems. You can chose to be presented first with a list of hosts and then by a list of all application/transaction combinations defined for that host. You can also restrict the list to the application/transaction combinations for a single host.
The resulting 3dmon display will show the host/application/transaction name on the left side and the name of configured metrics on the right side. A configuration set named armresp for monitoring of application response time is available in the distributed 3dmon.cf configuration file.
Source code for an instrumented application is not supplied with PTX but a modified version of the xmpeek program is shipped as /usr/samples/perfagent/server/armpeek. This program is an instrumented version of the ordinary xmpeek. It creates an application called armpeek and one transaction for each combination of command line flag and hostname. For example, the command armpeek -l myhost will create and measure a transaction called myhost-l; the command armpeek refers to the local host and would create a transaction called localhost; the command armpeek -a server would create the transaction server-a.
This section describes the use and implementation of the PTX version of the ARM library.
The arm_init subroutine is used to define an application or a unique instance of an application to the ARM library. In the PTX implementation of ARM, instances of applications can't be defined. See Implementation Specifics . An application must be defined before any other ARM subroutine is issued.
ARM Library (libarm.a).
#include <arm.h>
arm_appl_id_t arm_init( arm_ptr_t *appname, /* application name
*/
arm_ptr_t *appl_user_id, /* Name of the application user */
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0
*/
Each application needs to be defined by a unique name. An application can be defined as loosely or as rigidly as required. It may be defined as a single execution of one program, multiple (possibly simultaneous) executions of one program, or multiple executions of multiple programs that together constitue an application. Any one user of ARM may define the application so it best fits the measurement granularity desired. Measurements are always collected for each unique combination of:
appname
A unique application name. The maximum length is 128
characters including the terminating zero. The argument is
converted to a key by removing all blanks and truncating the
string to 32 characters, including a terminating zero. This
key is used to look for an application structure in the
library's private shared memory area. If a structure is
found, its use-count is incremented and the application ID
stored in the structure is returned to the caller. If the
structure is not found, one is created, assigned the next
free application ID and given a use-count of one. The new
assigned application ID is returned to the caller.
Up-to 64 bytes, including the terminating zero, of the appname parameter is saved as the description of the SpmiCx context that represents the application in the Spmi hierarchy. The key is used as the short name of the context.
appl_user_id
Can be passed in as NULL or some means of specifying a
user ID for the application. This allows the calling program
to define unique instances of an application. In the PTX
implementation of the ARM API, this parameter is
ignored. Consequently, it is not possible to define unique
instances of an application. If specified as non-NULL, this
parameter must be a string not exceeding 128 bytes in length,
including the terminating zero.
For our implementation to take this argument in use, another context level would have to be defined between the application context and the transaction context. This was deemed excessive.
flags, data, data_size
In the current API definition, the last three arguments
are for future use and they are ignored in our
implementation.
If successful, the subroutine returns an appl_id application identifier. If the subroutine fails, a value less than zero is returned.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product.
Note that the implementation of arm_init doesn't allow unique instances of an application to be defined. The appl_id associated with an application is stored in the ARM shared memory area and will remain constant throughout the life of the shared memory area. Consequently, subsequent executions of a program that defines one or more applications will normally have the same ID returned for the application each time. The same is true when different programs define the same application: As long as the shared memory area exists, they will all have the same ID returned. This is done to minimize the use of memory for application definitions and because it makes no difference from a PTX point of view.
If this is not acceptable from an application point of view, programs can dynamically generate application names to pass on the arm_init subroutine call.
/usr/include/arm.h
Declares the subroutines, data structures, handles, and
macros that an application program can use to access the ARM
library.
ARM Contexts in Spmi Data Space .
The arm_getid subroutine is used to register a transaction as belonging to an application and assign a unique identifier to the application/transaction pair. In the PTX implementation of ARM, multiple instances of a transaction within one application can't be defined. See Implementation Specifics rel="pagenum">. A transaction must be registered before any ARM measurements can begin.
ARM Library (libarm.a).
#include <arm.h>
arm_tran_id_t arm_getid( arm_appl_id_t appl_id, /* application handle
*/
arm_ptr_t *tran_name, /* transaction name */
arm_ptr_t *tran_detail, /* transaction additional info */
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0
*/
Each transaction needs to be defined by a unique name within an application. Transactions can be defined so they best fit the application environment. For example, if a given environment has thousands of unique transactions, it may be feasible to define groups of similar transactions to prevent data overload. In other situations, you may want to use generated transaction names that reflect what data a transaction carries along with the transaction type. For example, the type of SQL query could be analyzed to group customer query transactions according to complexity, such as customer_simple, customer, customer_complex. Whichever method is used to name transactions, in the PTX implementation of the ARM API, measurements are always collected for each unique combination of:
appl_id
The identifier returned by an earlier call to arm_init. The PTX implementation
does not require that the arm_init subroutine call was
issued by the same program or process now issuing the arm_getid
subroutine call. However, the number of issued arm_init
subroutine calls for the application name must exceed the
number of issued arm_end subroutine calls for this
appl_id.
The appl_id is used to look for an application structure. If one is not found or if the use-count of the one found is zero, no action is taken and the function returns -1.
tran_name
A unique transaction name. The name only needs to be
unique within the appl_id. The maximum length is 128
characters including the terminating zero. The argument is
converted to a key by removing all blanks and truncating the
string to 32 characters, including a terminating zero. This
key is used to look for a transaction structure (that belongs
to the application identified in the first argument) in the
library's private shared memory area. If a transaction
structure is found, its use-count is set to one and the
transaction ID stored in the structure is returned to the
caller. If the structure is not found, one is created and
assigned the next free transaction ID, given a use-count of
one and added to the application's linked list of
transactions. The new assigned transaction ID is returned to
the caller.
Up-to 64 bytes, including the terminating zero, of the tran_name parameter is saved as the description of the SpmiCx context that represents the transaction in the Spmi hierarchy. The key is used as the short name of the context.
tran_detail
Can be passed in as NULL or some means of specifying a
unique instance of the transaction. In the PTX implementation
of the ARM API, this parameter is ignored. Consequently,
it is not possible to define unique instances of a
transaction. If specified as non-NULL, this parameter must be
a string not exceeding 128 bytes in length, including the
terminating zero.
For our implementation to take this argument in use, another context level would have to be defined between the application context and the transaction context. This was deemed excessive.
flags, data, data_size
In the current API definition, the last three arguments
are for future use and they are ignored in our
implementation.
If successful, the subroutine returns an tran_id application identifier. If the subroutine fails, a value less than zero is returned. In compliance with the ARM API specifications, the error return value can be passed to the arm_start subroutine, which will cause arm_start to function as a no-operation.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product.
Note that the use-count for a transaction structure is either one or zero. This ensures that as long as the application structure is active, so are all transactions for which an arm_getid call was issued after the application was activated by an arm_init call. The transaction use-count is reset to zero by the arm_end call if this call causes the application use-count to go to zero.
Note that the implementation of arm_getid doesn't allow unique instances of a transaction to be defined. The tran_id associated with a transaction is stored in the ARM shared memory area and will remain constant throughout the life of the shared memory area. Consequently, subsequent executions of a program that defines one or more transactions under a given application will normally have the same ID returned for the transactions each time. The same is true when different programs define the same transcation within an application: As long as the shared memory area exists, they will all have the same ID returned. This is done to minimize the use of memory for transaction definitions and because it makes no difference from a PTX point of view.
If this is not acceptable from an application point of view, programs can dynamically generate transaction names to pass on the arm_getid subroutine call.
/usr/include/arm.h
Declares the subroutines, data structures, handles, and
macros that an application program can use to access the ARM
library.
ARM Contexts in Spmi Data Space , arm_init subroutine , arm_end subroutine .
The arm_start subroutine is used to mark the beginning of the execution of a transaction. Measurement of the transaction response time starts at the execution of this subroutine.
ARM Library (libarm.a).
#include <arm.h>
arm_start_handle_t arm_start( arm_tran_id_t tran_id, /* transaction name identifier
*/
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0
*/
Each arm_start subroutine call marks the beginning of another instance of a transaction within an application. Multiple instances (simultaneous executions of the transaction) may exist. Control information for the transaction instance is held until the execution of a matching arm_stop subroutine call, at which time the elapsed time is calculated and used to update transaction measurement metrics for the transaction. Metrics are accumulated for each unique combination of the following three components:
tran_id
The identifier returned by an earlier call to arm_getid. The PTX
implementation does not require that the arm_getid
subroutine call was issued by the same program or process now
issuing the arm_start subroutine call. However, the
transaction's application structure must be active, which
means that the number of issued arm_init subroutine
calls for the application name must exceed the number of
issued arm_end subroutine calls for the application's
appl_id.
If an application was inactivated by issuing a sufficient
number of arm_end calls, all transactions defined for
that application will have their use_count set to zero. The
count remains zero (and the transaction inactive) until a new
arm_getid subroutine is issued for the transaction.
The tran_id argument is used to look for a transaction structure. If one is not found or if the use-count of the one found is zero, no action is taken and the function returns -1. If one is found, a transaction instance structure (called a slot structure) is allocated, assigned the next free instance ID, and updated with the start time of the transaction instance. The assigned instance ID is returned to the caller.
In compliance with the ARM API specifications, if the tran_id passed is one returned from a previous arm_getid subroutine call that failed, the arm_start subroutine call functions as a no-operation function. It will return a NULL start_handle, which can be passed to subsequent arm_update and arm_stop subroutine calls with the effect that those calls are no-operation functions.
flags, data, data_size
In the current API definition, the last three arguments
are for future use and they are ignored in our
implementation.
If successful, the subroutine returns a start_handle, which uniquely defines this transaction execution instance. If the subroutine fails, a value less than zero is returned. In compliance with the ARM API specifications, the error return value can be passed to the arm_update and arm_stop subroutines, which will cause those subroutines to operate as no-operation functions.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product.
/usr/include/arm.h
Declares the subroutines, data structures, handles, and
macros that an application program can use to access the ARM
library.
ARM Contexts in Spmi Data Space , arm_init subroutine , arm_getid subroutine , arm_end subroutine .
The arm_update subroutine is used to collect information about a transaction's progress. It is a no-operation subroutine in the PTX implementation.
ARM Library (libarm.a).
#include <arm.h>
arm_ret_stat_t arm_update( arm_start_handle_t arm_handle, /* unique transaction handle
*/
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0
*/
The arm_update subroutine is implemented as a no-operation in the PTX version of the ARM API. It is intended to be used for providing status information for a long-running transaction. Because there's no feasible way to display such information in current PTX monitors, the subroutine is a NULL function.
start_handle
The identifier returned by an earlier call to arm_start. The start_handle
argument is used to look for the slot structure
created by the arm_start subroutine call. If one is
not found , no action is taken and the function returns -1.
Otherwise a zero is returned.
In compliance with the ARM API specifications, if the start_handle passed is one returned from a previous arm_start subroutine call that failed, or from an arm_start subroutine operating as a no-operation function, the arm_update subroutine call executes as a no-operation function. It will return a zero to indicate successful completion.
flags, data, data_size
In the current API definition, the last three arguments
are for future use and they are ignored in our
implementation.
If successful, the subroutine returns zero. If the subroutine fails, a value less than zero is returned.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product. It is implemented as a NULL subroutine call.
/usr/include/arm.h
Declares the subroutines, data structures, handles, and
macros that an application program can use to access the ARM
library.
ARM Contexts in Spmi Data Space , arm_init subroutine , arm_getid subroutine , arm_start subroutine , arm_stop subroutine , arm_end subroutine .
The arm_stop subroutine is used to mark the end of the execution of a transaction. Measurement of the transaction response time completes at the execution of this subroutine.
ARM Library (libarm.a).
#include <arm.h>
arm_ret_stat_t arm_stop( arm_start_handle_t arm_handle, /* unique transaction handle
*/
const arm_status_t comp_status, /* Good=0, Abort=1, Failed=2 */
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0
*/
Each arm_stop subroutine call marks the end of an instance of a transaction within an application. Multiple instances (simultaneous executions of the transaction) may exist. Control information for the transaction instance is held from the execution of the arm_start subroutine call and until the execution of a matching arm_stop subroutine call, at which time the elapsed time is calculated and used to update transaction measurement metrics for the transaction. Metrics are accumulated for each unique combination of the following three components:
arm_handle
The identifier returned by an earlier call to arm_start. The arm_handle
argument is used to look for a slot structure created
by the arm_start call, which
returned this arm_handle. If one is not found, no
action is taken and the function returns -1. If one is found,
a post structure is allocated and added to the linked
list of post structures used to pass data to the SpmiArmd
daemon. The post structure is updated with the start time
from the slot structure, the path to the transaction context,
and the stop time of the transaction instance.
In compliance with the ARM API specifications, if the start_handle passed is one returned from a previous arm_start subroutine call that failed, or from an arm_start subroutine operating as a no-operation function, the arm_stop subroutine call executes as a no-operation function. It will return a zero to indicate successful completion.
comp_status
User supplied transaction completion code. The following
codes are defined:
flags, data, data_size
In the current API definition, the last three arguments
are for future use and they are ignored in our
implementation.
If successful, the subroutine returns zero. If the subroutine fails, a value less than zero is returned.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product.
/usr/include/arm.h
Declares the subroutines, data structures, handles, and
macros that an application program can use to access the ARM
library.
ARM Contexts in Spmi Data Space , arm_init subroutine , arm_getid subroutine , arm_start subroutine , arm_end subroutine .
The arm_end subroutine is used to mark the end of an application. This subroutine call must always be called when a program that issued an arm_init subroutine call terminates. In the PTX implementation of ARM, application data structures may persist after arm_end is issued. See Implementation Specifics.
ARM Library (libarm.a).
#include <arm.h>
arm_ret_stat_t ARM_API arm_end( arm_appl_id_t appl_id, /* application id
*/
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0
*/
By calling the arm_end subroutine, an application program signals to the ARM library that it has ceased issuing ARM subroutine calls for the application specified and that the library code can remove references to the application. As far as the calling program is concerned, all references to transactions defined for the named application can be removed as well.
appl_id
The identifier returned by an earlier call to arm_init. The PTX implementation
does not require that the arm_init subroutine call was
issued by the same program or process now issuing the arm_end
subroutine call. However, each time the arm_end
subroutine call is issued against an appl_id, the
use-count of the transaction structure is decremented. When
the count reaches zero, the application structure and all
associated transaction structures are marked as inactive.
Subsequent arm_init calls can reactivate the
application structure but transaction structures formerly
associated with the application are not automatically
activated. Each transaction must be reactivated through the arm_getid subroutine call.
The appl_id is used to look for an application structure. If none is found, no action is taken and the function returns -1. If one is found, the use-count of the application structure is decremented. If that makes the counter zero, the use-counts of all associated transaction structures are set to zero. The total number of application structures that have been initialized for the calling process but not ended is decremented. If this count reaches zero, access to the shared memory from the process is released and the count of users of the shared memory area is decremented. If the count of users of the shared memory segment reaches zero, the shared memory segment is deleted.
flags, data, data_size
In the current API definition, the last three arguments
are for future use and they are ignored in our
implementation.
If successful, the subroutine returns zero. If the subroutine fails, a value less than zero is returned.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product.
Note that, in the PTX implementation of ARM, multiple processes can issue arm_init subroutine calls for a given application with the effect that multiple simultaneous definitions of the application are effective. The ARM library code points all these definitions to a single application structure in the ARM private shared memory area. A use-count keeps track of the number of simultaneous definitions. Each time arm_init is issued for the application name, the counter is incremented and each time the arm_end subroutine call is issued for the associated appl_id, the counter is decremented. No call to arm_end is permitted to decrement the counter below zero.
Only when the counter reaches zero is the application structure inactivated. As long as the counter is non-zero, transactions defined for the application remain active and new transactions can be defined for the application. It does not matter which process created the definition of the application.
This implementation was chosen because it makes perfect sense in a PTX environment. Any more restrictive implementation would have increased memory use significantly and would be useless for PTX monitoring purposes.
/usr/include/arm.h
Declares the subroutines, data structures, handles, and
macros that an application program can use to access the ARM
library.
ARM Contexts in Spmi Data Space , arm_init subroutine , arm_getid subroutine .
This section describes the implementation of the PTX version of the ARM replacement library. The replacement library differs from the standard PTX ARM implementation by invoking an earlier installed ARM implementation in addition to invoking the PTX implementation. For the following description, the previously installed ARM library is referred to as the lower library.
The arm_init subroutine is used to define an application or a unique instance of an application to the ARM library. While, in the PTX implementation of ARM, instances of applications can't be defined, the ARM implementation in the lower library may permit this. An application must be defined before any other ARM subroutine is issued.
ARM Library (libarm.a).
#include <arm.h>
arm_appl_id_t arm_init( arm_ptr_t *appname, /* application name
*/
arm_ptr_t *appl_user_id, /* Name of the application user */
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0
*/
Each application needs to be defined by a unique name. An application can be defined as loosely or as rigidly as required. It may be defined as a single execution of one program, multiple (possibly simultaneous) executions of one program, or multiple executions of multiple programs that together constitue an application. Any one user of ARM may define the application so it best fits the measurement granularity desired. For the PTX implementation, measurements are always collected for each unique combination of:
Before the PTX implementation code is executed, the lower library is called. If this call returns a value greater than zero, that return value is passed to the caller as the application ID. If the returned value from the lower library is zero or negative, the return value is the one generated by the PTX library code.
appname
A unique application name. The maximum length is 128
characters including the terminating zero. The PTX library
code converts this value to a key by removing all blanks and
truncating the string to 32 characters, including a
terminating zero. This key is used to look for an application
structure in the library's private shared memory area. If a
structure is found, its use-count is incremented and the
application ID stored in the structure is saved. If the
structure is not found, one is created, assigned the next
free application ID and given a use-count of one. The new
assigned application ID is saved. If the call to the lower
library was successful, a cross-reference is created from
the lower library's application ID to the PTX
library's application ID for use by arm_getid
and arm_end.
Up-to 64 bytes, including the terminating zero, of the appname parameter is saved as the description of the SpmiCx context that represents the application in the Spmi hierarchy. The key is used as the short name of the context.
appl_user_id
Can be passed in as NULL or some means of specifying a
user ID for the application. This allows the calling program
to define unique instances of an application. In the PTX
implementation of the ARM API, this parameter is
ignored. Consequently, it is not possible to define unique
instances of an application. If specified as non-NULL, this
parameter must be a string not exceeding 128 bytes in length,
including the terminating zero.
For the PTX implementation to take this argument in use, another context level would have to be defined between the application context and the transaction context. This was deemed excessive.
For the lower library implementation of this subroutine call, the appl_user_id argument may very well have significance. If so, it's transparent to the PTX implementation.
flags, data, data_size
In the current API definition, the last three arguments
are for future use and they are ignored in our
implementation.
If the call to the lower library was successful, the subroutine returns an appl_id application identifier as returned from the lower library. If the subroutine call to the lower library fails but the PTX implementation doesn't fail, the appl_id returned is the one assigned by the PTX library. If both implementations fail, a value less than zero is returned.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product.
Note that the implementation of arm_init doesn't allow unique instances of an application to be defined. The appl_id associated with an application is stored in the ARM shared memory area and will remain constant throughout the life of the shared memory area. Consequently, subsequent executions of a program that defines one or more applications will normally have the same ID returned for the application each time. The same is true when different programs define the same application: As long as the shared memory area exists, they will all have the same ID returned. This is done to minimize the use of memory for application definitions and because it makes no difference from a PTX point of view.
If this is not acceptable from an application point of view, programs can dynamically generate application names to pass on the arm_init subroutine call.
Regardless of the implementation restrictions of the PTX library, the lower library may or may not have its own implementation restrictions.
/usr/include/arm.h
Declares the subroutines, data structures, handles, and
macros that an application program can use to access the ARM
library.
ARM Contexts in Spmi Data Space .
The arm_getid subroutine is used to register a transaction as belonging to an application and assign a unique identifier to the application/transaction pair. In the PTX implementation of ARM, multiple instances of a transaction within one application can't be defined. The lower library implementation of this subroutine may provide support for instances of transactions. A transaction must be registered before any ARM measurements can begin.
ARM Library (libarm.a).
#include <arm.h>
arm_tran_id_t arm_getid( arm_appl_id_t appl_id, /* application handle
*/
arm_ptr_t *tran_name, /* transaction name */
arm_ptr_t *tran_detail, /* transaction additional info */
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0
*/
Each transaction needs to be defined by a unique name within an application. Transactions can be defined so they best fit the application environment. For example, if a given environment has thousands of unique transactions, it may be feasible to define groups of similar transactions to prevent data overload. In other situations, you may want to use generated transaction names that reflect what data a transaction carries along with the transaction type. For example, the type of SQL query could be analyzed to group costomer query transactions according to complexity, such as customer_simple, customer, customer_complex. Whichever method is used to name transactions, in the PTX implementation of the ARM API, measurements are always collected for each unique combination of:
Before the PTX implementation code is executed, the lower library is called. If this call returns a value greater than zero, that return value is passed to the caller as the transaction ID. If the returned value from the lower library is zero or negative, the return value is the one generated by the PTX library code.
appl_id
The identifier returned by an earlier call to arm_init. The identifier is
passed to the arm_getid function of the lower
library. If the lower library returns an
identifier greater than zero, that identifier is the one
that'll eventually be returned to the caller. After the
invocation of the lower library, the
PTX implementation attempts to translate the appl_id argument
to its own identifier by consulting the cross-reference table
created by arm_init. If one can be found, it is used
for the PTX implementation; if no cross reference is
found, the appl_id is used as passed in. The PTX
implementation does not require that the arm_init
subroutine call was issued by the same program or process now
issuing the arm_getid subroutine call. However, the
number of issued arm_init subroutine calls for the
application name must exceed the number of issued arm_end
subroutine calls for this appl_id.
In the PTX implementation, the appl_id (as retrieved from the cross-reference table) is used to look for an application structure. If one is not found or if the use-count of the one found is zero, the PTX implementation is considered to have failed and no action is taken by the PTX library.
tran_name
A unique transaction name. The name only needs to be
unique within the appl_id. The maximum length is 128
characters including the terminating zero. In the
PTX implementation, the argument is converted to a key
by removing all blanks and truncating the string to 32
characters, including a terminating zero. This key is used to
look for a transaction structure (that belongs to the
application identified in the first argument) in the
library's private shared memory area. If a transaction
structure is found, its use-count is set to one and the
transaction ID stored in the structure is saved. If the
structure is not found, one is created and assigned the next
free transaction ID, given a use-count of one and added to
the application's linked list of transactions. The new
assigned transaction ID is saved. If the call to the lower
library was successful, a cross-reference is created from
the lower library's transaction ID to the PTX
library's transaction ID for use by arm_start.
Up-to 64 bytes, including the terminating zero, of the tran_name parameter is saved as the description of the SpmiCx context that represents the transaction in the Spmi hierarchy. The key is used as the short name of the context.
tran_detail
Can be passed in as NULL or some means of specifying a
unique instance of the transaction. In the PTX implementation
of the ARM API, this parameter is ignored. Consequently,
it is not possible to define unique instances of a
transaction. If specified as non-NULL, this parameter must be
a string not exceeding 128 bytes in length, including the
terminating zero.
For our implementation to take this argument in use, another context level would have to be defined between the application context and the transaction context. This was deemed excessive.
For the lower library implementation of this subroutine call, the tran_detail argument may very well have significance. If so, it's transparent to the PTX implementation.
flags, data, data_size
In the current API definition, the last three arguments
are for future use and they are ignored in our
implementation.In the current API definition, the last three
arguments are for future use and they are ignored in our
implementation.
If successful, the subroutine returns an tran_id application identifier. If the subroutine fails, a value less than zero is returned. In compliance with the ARM API specifications, the error return value can be passed to the arm_start subroutine, which will cause arm_start to function as a no-operation.
If the call to the lower library was successful, the tran_id transaction identifier returned is the one assigned by the lower library. If the subroutine call to the lower library failed but the PTX implementation didn't fail, the tran_id returned is the one assigned by the PTX library. If both implementations fail, a value less than zero is returned. In compliance with the ARM API specification, an error return value can be passed to the arm_start subroutine, which will cause arm_start to function as a no-operation.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product.
Note that the use-count for a transaction structure is either one or zero. This ensures that as long as the application structure is active, so are all transactions for which an arm_getid call was issued after the application was activated by an arm_init call. The transaction use-count is reset to zero by the arm_end call if this call causes the application use-count to go to zero.
Note that the implementation of arm_getid doesn't allow unique instances of a transaction to be defined. The tran_id associated with a transaction is stored in the ARM shared memory area and will remain constant throughout the life of the shared memory area. Consequently, subsequent executions of a program that defines one or more transactions under a given application will normally have the same ID returned for the transactions each time. The same is true when different programs define the same transcation within an application: As long as the shared memory area exists, they will all have the same ID returned. This is done to minimize the use of memory for transaction definitions and because it makes no difference from a PTX point of view.
If this is not acceptable from an application point of view, programs can dynamically generate transaction names to pass on the arm_getid subroutine call.
Regardless of the implementation restrictions of the PTX library, the lower library may or may not have its own implementation restrictions.
/usr/include/arm.h
Declares the subroutines, data structures, handles, and
macros that an application program can use to access the ARM
library.
ARM Contexts in Spmi Data Space , arm_init subroutine , arm_end subroutine .
The arm_start subroutine is used to mark the beginning of the execution of a transaction. Measurement of the transaction response time starts at the execution of this subroutine.
ARM Library (libarm.a).
#include <arm.h>
arm_start_handle_t arm_start( arm_tran_id_t tran_id, /* transaction name identifier
*/
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0
*/
Each arm_start subroutine call marks the beginning of another instance of a transaction within an application. Multiple instances (simultaneous executions of the transaction) may exist. Control information for the transaction instance is held until the execution of a matching arm_stop subroutine call, at which time the elapsed time is calculated and used to update transaction measurement metrics for the transaction. Metrics are accumulated for each unique combination of the following three components:
Before the PTX implementation code is executed, the lower library is called. If this call returns a value greater than zero, that return value is passed to the caller as the start handle. If the value returned by the lower library is zero or negative, the return value is the one generated by the PTX library code.
tran_id
The identifier returned by an earlier call to arm_getid. The identifier is
passed to the arm_start function of the lower
library. If the lower library returns an
identifier greater than zero, that identifier is the one
that'll eventually be returned to the caller. After the
invocation of the lower library, the
PTX implementation attempts to translate the tran_id argument
to its own identifier from the cross-reference table created
by arm_getid. If one can be found, it is used for the
PTX implementation; if no cross reference is found, the tran_id
is used as passed in.The PTX implementation does not
require that the arm_getid subroutine call was issued
by the same program or process now issuing the arm_start
subroutine call. However, the transaction's application
structure must be active, which means that the number of
issued arm_init subroutine calls for the application
name must exceed the number of issued arm_end
subroutine calls for the application's appl_id.
If an application was inactivated by issuing a sufficient
number of arm_end calls, all transactions defined for
that application will have their use_count set to zero. The
count remains zero (and the transaction inactive) until a new
arm_getid subroutine is issued for the transaction.
In the PTX implementation, the tran_id (as retrieved from the cross-reference table) is used to look for a transaction structure. If one is not found or if the use-count of the one found is zero, the PTX implementation is considered to have failed and no action is taken by the PTX library. If one is found, a transaction instance structure (called a slot structure) is allocated, assigned the next free instance ID, and updated with the start time of the transaction instance. The assigned instance ID is saved as the start_handle. If the call to the lower library was successful, a cross-reference is created from the lower library's start_handle to the PTX library's start_handle for use by arm_update and arm_stop.
In compliance with the ARM API specifications, if the tran_id passed is one returned from a previous arm_getid subroutine call that failed, the arm_start subroutine call functions as a no-operation function. It will return a NULL start_handle, which can be passed to subsequent arm_update and arm_stop subroutine calls with the effect that those calls are no-operation functions.
flags, data, data_size
In the current API definition, the last three arguments
are for future use and they are ignored in our
implementation.In the current API definition, the last three
arguments are for future use and they are ignored in our
implementation.
If successful, the subroutine returns a start_handle, which uniquely defines this transaction execution instance. If the subroutine fails, a value less than zero is returned. In compliance with the ARM API specifications, the error return value can be passed to the arm_update and arm_stop subroutines, which will cause those subroutines to operate as no-operation functions.
If the call to the lower library was successful, the start_handle instance ID returned is the one assigned by the lower library. If the subroutine call to the lower library failed but the PTX implementation didn't fail, the start_handle returned is the one assigned by the PTX library. If both implementations fail, a value less than zero is returned.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product.
/usr/include/arm.h
Declares the subroutines, data structures, handles, and
macros that an application program can use to access the ARM
library.
ARM Contexts in Spmi Data Space , arm_init subroutine , arm_getid subroutine , arm_end subroutine .
The arm_update subroutine is used to collect information about a transaction's progress. It is a no-operation subroutine in the PTX implementation but may be fully implemented by the lower library.
ARM Library (libarm.a).
#include <arm.h>
arm_ret_stat_t arm_update( arm_start_handle_t arm_handle, /* unique transaction handle
*/
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0
*/
The arm_update subroutine is implemented as a no-operation in the PTX version of the ARM API. It is intended to be used for providing status information for a long-running transaction. Because there's no feasible way to display such information in current PTX monitors, the subroutine is a NULL function.
The lower library implementation of the arm_update subroutine is always invoked.
start_handle
The identifier returned by an earlier call to arm_start. The identifier is
passed to the arm_update function of the lower
library. If the lower library returns a zero
return code., that return code is returned to the caller.
After the invocation of the lower library, the
PTX implementation attempts to translate the arm_handle
argument to its own identifier from the cross-reference
table created by arm_start. If one can be found, it is
used for the PTX implementation; if no cross reference
is found, the arm_handle is used as passed in. The PTX
implementation uses the start_handle argument to look
for the slot structure created by the arm_start
subroutine call. If one is found the PTX implementation
is considered to have succeeded, otherwise it is considered
to have failed.
In compliance with the ARM API specifications, if the start_handle passed is one returned from a previous arm_start subroutine call that failed, or from an arm_start subroutine operating as a no-operation function, the arm_update subroutine call executes as a no-operation function. It will return a zero to indicate successful completion.
flags, data, data_size
In the current API definition, the last three arguments
are for future use and they are ignored in our
implementation.In the current API definition, the last three
arguments are for future use and they are ignored in our
implementation.
If successful, the subroutine returns zero. If the subroutine fails, a value less than zero is returned. If the call to the lower library was successful, a zero is returned. If the subroutine call to the lower library failed but the PTX implementation didn't fail, a zero is returned. If both implementations failed, a value less than zero is returned.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product. It is implemented as a NULL subroutine call.
/usr/include/arm.h
Declares the subroutines, data structures, handles, and
macros that an application program can use to access the ARM
library.
ARM Contexts in Spmi Data Space , arm_init subroutine , arm_getid subroutine , arm_start subroutine , arm_stop subroutine , arm_end subroutine .
The arm_stop subroutine is used to mark the end of the execution of a transaction. Measurement of the transaction response time completes at the execution of this subroutine.
ARM Library (libarm.a).
#include <arm.h>
arm_ret_stat_t arm_stop( arm_start_handle_t arm_handle, /* unique transaction handle
*/
const arm_status_t comp_status, /* Good=0, Abort=1, Failed=2 */
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0
*/
Each arm_stop subroutine call marks the end of an instance of a transaction within an application. Multiple instances (simultaneous executions of the transaction) may exist. Control information for the transaction instance is held from the execution of the arm_start subroutine call and until the execution of a matching arm_stop subroutine call, at which time the elapsed time is calculated and used to update transaction measurement metrics for the transaction. Metrics are accumulated for each unique combination of the following three components:
Before the PTX implementation code is executed, the lower library is called. If this call returns a value of zero, that return value is passed to the caller. If the value returned by the lower library is non-zero, the return value is the one generated by the PTX library code.
arm_handle
The identifier returned by an earlier call to arm_start. The identifier is
passed to the arm_stop function of the lower
library. If the lower library returns a zero
return code, that return code is returned to the caller.
After the invocation of the lower library, the
PTX implementation attempts to translate the arm_handle
argument to its own identifier from the cross-reference
table created by arm_start. If one can be found, it is
used for the PTX implementation; if no cross reference
is found, the arm_handle is used as passed in. The PTX
implementation uses the start_handle argument to look
for the slot structure created by the arm_start
subroutine call. If one is found, a post structure is
allocated and added to the linked list of post structures
used to pass data to the SpmiArmd daemon. The post
structure is updated with the start time from the slot
structure, the path to the transaction context, and the stop
time of the transaction instance. If no slot structure
was found, the PTX implementation is considered to have
failed.
In compliance with the ARM API specifications, if the start_handle passed is one returned from a previous arm_start subroutine call that failed, or from an arm_start subroutine operating as a no-operation function, the arm_stop subroutine call executes as a no-operation function. It will return a zero to indicate successful completion.
comp_status
User supplied transaction completion code. The following
codes are defined:
flags, data, data_size
In the current API definition, the last three arguments
are for future use and they are ignored in our
implementation.In the current API definition, the last three
arguments are for future use and they are ignored in our
implementation.
If successful, the subroutine returns zero. If the subroutine fails, a value less than zero is returned. If the call to the lower library was successful, a zero is returned. If the subroutine call to the lower library failed but the PTX implementation didn't fail, a zero is returned. If both implementations failed, a value less than zero is returned.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product.
/usr/include/arm.h
Declares the subroutines, data structures, handles, and
macros that an application program can use to access the ARM
library.
ARM Contexts in Spmi Data Space , arm_init subroutine , arm_getid subroutine , arm_start subroutine , arm_end subroutine .
The arm_end subroutine is used to mark the end of an application. This subroutine call must always be called when a program that issued an arm_init subroutine call terminates. In the PTX implementation of ARM, application data structures may persist after arm_end is issued. See Implementation Specifics. This may not be the case for the lower library implementation.
ARM Library (libarm.a).
#include <arm.h>
arm_ret_stat_t ARM_API arm_end( arm_appl_id_t appl_id, /* application id
*/
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0
*/
By calling the arm_end subroutine, an application program signals to the ARM library that it has ceased issuing ARM subroutine calls for the application specified and that the library code can remove references to the application. As far as the calling program is concerned, all references to transactions defined for the named application can be removed as well.
Before the PTX implementation code is executed, the lower library is called. If this call returns a value of zero, that return value is passed to the caller. If the value returned by the lower library is non-zero, the return value is the one generated by the PTX library code.
appl_id
The identifier returned by an earlier call to arm_init. The identifier is
passed to the arm_end function of the lower library.
If the lower library returns a zero, a zero is
returned to the caller. After the invocation of the lower
library, the PTX implementation attempts to
translate the appl_id argument to its own identifier
from the cross-reference table created by arm_init. If one can be found,
it is used for the PTX implementation; if no cross
reference is found, the appl_id is used as passed in.
The PTX implementation does not require that the arm_init
subroutine call was issued by the same program or process now
issuing the arm_end subroutine call. However, each
time the arm_end subroutine call is issued against an appl_id,
the use-count of the transaction structure is decremented.
When the count reaches zero, the application structure and
all associated transaction structures are marked as inactive.
Subsequent arm_init calls can reactivate the
application structure but transaction structures formerly
associated with the application are not automatically
activated. Each transaction must be reactivated through the arm_getid subroutine call.
In the PTX implementation, the appl_id (as retrieved from the cross-reference table) is used to look for an application structure. If none is found, no action is taken and the PTX function is considered to have failed. If one is found, the use-count of the application structure is decremented. If that makes the counter zero, the use-counts of all associated transaction structures are set to zero. The total number of application structures that have been initialized for the calling process but not ended is decremented. If this count reaches zero, access to the shared memory from the process is released and the count of users of the shared memory area is decremented. If the count of users of the shared memory segment reaches zero, the shared memory segment is deleted.
flags, data, data_size
In the current API definition, the last three arguments
are for future use and they are ignored in our
implementation.
If successful, the subroutine returns zero. If the subroutine fails, a value less than zero is returned. If the call to the lower library was successful, a zero is returned. If the subroutine call to the lower library failed but the PTX implementation didn't fail, a zero is returned. If both implementations failed, a value less than zero is returned.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product.
Note that, in the PTX implementation of ARM, multiple processes can issue arm_init subroutine calls for a given application with the effect that multiple simultaneous definitions of the application are effective. The ARM library code points all these definitions to a single application structure in the ARM private shared memory area. A use-count keeps track of the number of simultaneous definitions. Each time arm_init is issued for the application name, the counter is incremented and each time the arm_end subroutine call is issued for the associated appl_id, the counter is decremented. No call to arm_end is permitted to decrement the counter below zero.
Only when the counter reaches zero is the application structure inactivated. As long as the counter is non-zero, transactions defined for the application remain active and new transactions can be defined for the application. It does not matter which process created the definition of the application.
This implementation was chosen because it makes perfect sense in a PTX environment. Any more restrictive implementation would have increased memory use significantly and would be useless for PTX monitoring purposes.
For the implementation of arm_end in the lower library, other restrictions may exist.
/usr/include/arm.h
Declares the subroutines, data structures, handles, and
macros that an application program can use to access the ARM
library.
ARM Contexts in Spmi Data Space , arm_init subroutine , arm_getid subroutine .