6.16.1 Including APIs in UAPs

(1) UAPs in which APIs can be included

A UAP that satisfies all the following conditions can use APIs:

• Programmed in C (ANSI C)

• None of the following function and area names that are used in APIs provided by HA Monitor is used:

  • hamon_patrolstart

  • hamon_patrolstop

  • hamon_upapi_env

  • hamon_upapi_inf

• Neither of the following environment variables that are used by APIs provided by HA Monitor is used:

  • HAMON_UAPNAME

  • HAMON_API_PATROL

• The UAP does not contain processing for releasing all file descriptors of a process.

  When an API is issued, the API connects to HA Monitor via UNIX domain communication and holds one file descriptor. Therefore, APIs cannot be used if the UAP contains processing that releases all file descriptors of a process.

• The UAP is not monitored by any program product other than HA Monitor.

  For example, APIs cannot be issued from an SPP of OpenTP1.

• Because an API generates one thread and uses that thread to transmit signals specified in the arguments of the API, the following conditions are all satisfied:

  • Threads can be generated.

  • Signals can be used.

  • There is one or more signals that can be used by APIs. For a corresponding signal, the signal handler is undefined and unblocked.

  • The UAP has been designed to handle return of a system call due to signal interruption (error number: EINTR).

    For example, if control is returned due to a signal interruption (error number: EINTR), system calls (sleep, usleep, and nanosleep) might be retried for the remainder of the processing time or system calls (read and write) might retry processing after control is returned from the interruption.

To Page Top

(2) Files provided by HA Monitor

HA Monitor provides the files listed below so that UAPs can issue APIs.

Table 6‒15: Files provided by HA Monitor to issue APIs

Name	File storage path	Description
Header file	/opt/hitachi/HAmon/api/include/HA_mon_uap.h	Header file required for using APIs
Object file for API	/opt/hitachi/HAmon/api/lib/hamon_api32.a	Object file that requires a static link to the UAP to use APIs. This is for UAPs that run in a 32-bit environment.
	/opt/hitachi/HAmon/api/lib/hamon_api64.a	Object file that requires a static link to the UAP to use APIs. This is for UAPs that run in a 64-bit environment.
Shared library file for API#	/opt/hitachi/HAmon/api/lib/hamon_api32.so	API library file that is used dynamically during UAP execution. This is for UAPs that run in a 32-bit environment.
	/opt/hitachi/HAmon/api/lib/hamon_api64.so	API library file that is used dynamically during UAP execution. This is for UAPs that run in a 64-bit environment.

#

This is a library that is loaded dynamically from the object file of API during UAP execution. It cannot be linked to UAPs.

To Page Top

(3) Creating UAPs

Create a UAP in C. Specify APIs provided by HA Monitor in the UAP.

To use a shell that is run in the event of a UAP slowdown, code the processing for collecting trace information before and after a system call or a function such as an SQL function is issued. An effective method is to collect trace information in memory and then analyze it from core and output messages.

To Page Top

(4) Compiling and linking

Use the gcc command to compile the UAP source file that contains APIs.

The following table lists and describes the options required during compilation.

Table 6‒16: Options required during compilation

Option	Meaning
-o	Specifies a name for the binary file to be created.
-I/opt/hitachi/HAmon/api/include	Specifies the path of the header file.
-L/opt/hitachi/HAmon/api/lib	Specifies the path of the shared library.
-Wl,-Bdynamic	Specifies to the linker that the dynamic library is to be linked (because this is the default value, this option can be omitted).
-ldl	Uses a library such as for the dlopen function.

Shown below are examples of compilation in a 64-bit environment and a 32-bit environment.

Example for a 64-bit environment

Name of the UAP source program created in C

sample.c (main function)

Example of command line during UAP compilation

gccΔ-oΔsampleΔ-I/opt/hitachi/HAmon/api/includeΔ-L/opt/hitachi/HAmon/api/libΔsample.cΔ/opt/hitachi/HAmon/api/lib/hamon_api64.aΔ-Wl,-BdynamicΔ-ldl

Legend:

Δ: Single-byte space

Example for a 32-bit environment

Name of the UAP source program created in C

sample.c (main function)

Example of command line during UAP compilation

gccΔ-oΔsampleΔ-I/opt/hitachi/HAmon/api/includeΔ-L/opt/hitachi/HAmon/api/libΔsample.cΔ/opt/hitachi/HAmon/api/lib/hamon_api32.aΔ-Wl,-BdynamicΔ-ldl

Legend:

Δ: Single-byte space

To Page Top