6.16.1 Including APIs in UAPs
If you use the monitor-mode program management function to monitor a UAP, you must edit the UAP's source code to issue the APIs provided by HA Monitor from the UAP. This subsection explains how in include APIs .
- Organization of this subsection
(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.
-
(2) Files provided by HA Monitor
HA Monitor provides the files listed below so that UAPs can 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.
(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.
(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.
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