HP NonStop ASAP Hybrid Manual Abstract HP NonStop™ ASAP Hybrid is an extension to the ASAP product family that integrates application availability information from external systems running the Linux operating system into ASAP on one or more HP NonStop servers running the NonStop operating system. This document describes how to install, configure, and use NonStop ASAP Hybrid. Product Version V1 Supported Release Version Updates (RVUs) This manual supports D46.00 and all subsequent D-series RVUs, G06.
Document History Part Number Product Version Published 529729-001 529729-002 529729-003 529729-004 V1 V1 V1 V1 January 2005 May 2006 January 2007 September 2009
HP NonStop ASAP Hybrid Manual 1. OVERVIEW ...................................................................................................................1-1 INTRODUCTION TO ASAP HYBRID ...............................................................................................1-1 ASAP HYBRID ARCHITECTURE ....................................................................................................1-1 2. MANAGING ASAP HYBRID FOR NONSTOP SERVER ....................................................
. THE ASAP HYBRID FOR LINUX API..................................................................................4-1 DEVELOPING APPLICATIONS USING THE ASAP HYBRID API ...............................................................4-3 ASAP HYBRID FOR LINUX API LIBRARIES ......................................................................................4-4 DIFFERENCES FROM NONSTOP ASAPX ........................................................................................4-5 THREADING ..................
What’s New in This Manual Manual Information HP NonStop ASAP Hybrid Manual Abstract HP NonStop™ ASAP Hybrid is an extension to the ASAP product family that integrates application availability information from external systems running the Linux operating system into ASAP on one or more HP NonStop servers running the NonStop operating system. This document describes how to install, configure, and use NonStop ASAP Hybrid. Product Version V1 Supported Release Version Updates (RVUs) This manual supports D46.
New and Changed Information ASAP Hybrid Extension for Linux 1.1.9 This manual update includes this change: Updated installation information on page 3-1. ASAP Hybrid Extension for Linux 1.1.6/ASAP 2.8 This manual update includes this change: Corrected syntax for STATUS PROXY command on page 2-10. ASAP Hybrid Extension for Linux 1.1.6/ASAP 2.7 This manual update includes these changes: Added the TERM option to GATEWAY Statement on page 2-5. Added the SYSMSG option to CONFIG Statement on page 2-7.
About This Manual Audience The intended audience for this document is system managers or administrators responsible for deploying ASAP Hybrid, as well as developers who are instrumenting applications to use the ASAP Hybrid API on Linux. Related Documents ASAP Server Manual ASAP Extension Manual ASAP Client Manual ASAP Messages Manual Notation Conventions Hypertext Links Blue underline is used to indicate a hypertext link within text.
System Services (OSS) keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: myfile.c italic computer type. Italic computer type letters within text indicate C and Open System Services (OSS) variable items that you supply. Items not enclosed in brackets are required. For example: pathname [ ] Brackets. Brackets enclose optional syntax items. For example: TERM [\system-name.
times. For example: M address [ , new-value ]… [ - ] {0|1|2|3|4|5|6|7|8|9}… An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example: "s-char…" Punctuation. Parentheses, commas, semicolons, and other symbols not previously described must be typed as shown. For example: error := NEXTFILENAME ( file-name ) ; LISTOPENS SU $process-name.
manual and its preceding version. Change bars are vertical rules placed in the right margin of changed portions of text, figures, tables, examples, and so on. Change bars highlight new or revised information. For example: The message types specified in the REPORT clause are different in the COBOL environment and the Common Run-Time Environment (CRE). The CRE has many new message types and some new message type codes for old message types.
1. Overview Introduction to ASAP Hybrid ASAP Hybrid extends the capabilities of ASAP application monitoring to remote systems running the Linux operating system. Application metrics from the remote systems are seamlessly integrated into ASAP on one or more NonStop servers, thereby providing an overall view of the entire application as it spans one or more NonStop servers and one or more Linux servers. For an application, using ASAP on Linux is the same as using ASAP on a NonStop server.
Figure 1-1: ASAP Hybrid Components and Architecture Each of these components has a specific role within the overall ASAP infrastructure: ASAP Hybrid Linux API Library The ASAP Hybrid Linux API Library provides the interface layer between Linux applications and the ASAP subsystem. Applications link to this library and call ASAP Hybrid API procedures in order to register domains and update metric counters in shared memory. Both thread-safe and non-thread-safe versions are supplied for most procedures.
ASAP Proxy SGP The ASAP Proxy SGP is a NonStop server-based component responsible for startup, shutdown, and command processing for the ASAP Hybrid subsystem. The SGP provides full integration of other ASAP Hybrid components into the main ASAP environment. ASAP Hybrid Gateway The ASAP Hybrid Gateway is a NonStop server-based component that provides gateway services to ASAP Hybrid Servers running on Linux.
2. Managing ASAP Hybrid for NonStop Server This section covers the procedures for installing, configuring, and managing the NonStop server-based components of ASAP Hybrid. Installing ASAP Hybrid on the NonStop Server ASAP Hybrid is packaged as a 2-CD set. The first CD contains the Linux components, and the second contains the NonStop server components. To install ASAP Hybrid on a NonStop server, proceed as follows using the CD containing the NonStop server components: 1.
SET PROXY ON 3. If the Hybrid object files described in Step 1 were not installed to $SYSTEM.SYSTEM, also add this line to the ASAPCONF file: SET PROXYOBJECT $..ASAPPXY where $. specifies the volume and subvolume where the ASAP Hybrid object files were placed in Step 1. 4. Create a new configuration file for the ASAP Proxy SGP to define the characteristics of the overall Hybrid environment. By default, this file should be named ASAPPCNF and should be located in $SYSTEM.SYSTEM.
Configuring ASAP Hybrid on the NonStop Server ASAP Hybrid for NonStop servers is configured in three different locations. ASAP is configured to know about and control ASAP Hybrid; the Hybrid SGP is configured to start Hybrid Gateways; and each Hybrid Gateway is configured independently. Configuring ASAP to Enable ASAP Hybrid ASAP Hybrid is configured within ASAP by placing SET commands in the ASAPCONF file. SET PROXY Command The SET PROXY ON command enables ASAP Hybrid within ASAP Server.
Example SET PROXYCONFIG $SYSTEM.ASAP.ASAPPCNF SET PROXYCPU Command The SET PROXYCPU command defines the CPU in which the Hybrid Proxy SGP runs. The default is the CPU where ASAPMON executes. SET PROXYCPU is a valid CPU number from 0 through 15. Example SET PROXYCPU 2 SET PROXYOBJECT Command The SET PROXYOBJECT command defines the object file for the Hybrid Proxy SGP. The default is $SYSTEM.SYSTEM.ASAPPXY.
Proxy SGP. SET PROXYPARAM “ […]” is a Hybrid parameter. This item is for future use. Currently there are no user-configurable Hybrid parameters. Configuring the Proxy SGP The Proxy SGP is configured by placing GATEWAY statements in a configuration file that the SGP reads at startup. GATEWAY Statement The GATEWAY statement defines Hybrid Gateway processes to be started by the Proxy SGP. There must be at least one GATEWAY statement in the Proxy SGP configuration file.
CPU defines the CPU in which the Gateway runs. This value must be a valid CPU number from 0 through 15. Hybrid Gateways should be spread across processors to take advantage of the parallelism inherent on the NonStop platform. The default is CPU 0. OBJECT is the object filename for the Hybrid Gateway. The default is $SYSTEM.SYSTEM.ASAPGATE. PRI is the execution priority for the Hybrid Gateway. The default is 150. TERM is the home terminal for the Gateway process.
Configuring Hybrid Gateways Hybrid Gateway processes are configured by placing statements in a configuration file that is read by each Gateway at startup time. Each Hybrid Gateway requires its own unique configuration file. CONFIG Statement The CONFIG statement is used to control memory sizing and other configuration options within the Hybrid Gateway. The CONFIG statement is required.
entity and report detailed statistics about itself. If you choose this option, you must include the ASAP Hybrid EDL file in the EDL definitions for the ASAP environment into which the Hybrid Gateway will register. To do so, place an INCLUDE statement in the ASAPUSER file that references the name of the Hybrid EDL file. That file is normally located at $SYSTEM.SYSTEM.ASAP2HYB but might have been placed in another location during the installation process.
CONFIG TCPIP $ZTCP1 SYSMSG CONFIG TCPIP $ZTCP1 SYSMSG (5) CONFIG TCPIP $ZTCP1 SYSMSG (10,5) SYSTEM Statement The optional SYSTEM statement is used to preregister application domains from an external system into ASAP. The Gateway registers domains defined with SYSTEM statements at the first audit interval after it starts up. The SYSTEM statement must be entered on a single line.
option. FLAGS is the domain flags value. If this value is 1, it instructs the Gateway to register the domain in a deactivated state.
The STATUS PROXY $ form of the command directs the command to the Hybrid Gateway process named $. This form of the command is used to return status from a Hybrid Gateway process. It is also used to send TRACE and REMOVE commands to a Hybrid Gateway process. $ specifies the name of a running Hybrid Gateway process to send the command to. This form of the command returns the status of the Hybrid Gateway process when it is entered without any other command options.
Examples To retrieve status information from the Proxy SGP: STATUS PROXY To retrieve status information from a Hybrid Gateway process named $GATE1: STATUS PROXY $GATE1 To remove an inactive, up, or down domain named Linuxapp\Domain\Server from Hybrid Gateway process $GATE1: STATUS PROXY $GATE1 REMOVE LINUXAPP\DOMAIN\SERVER To remove all inactive, up, and down domains whose names start with L: STATUS PROXY $GATE1 REMOVE L* To remove all inactive, up, and down domains from the Hybrid Gatewa
STATUS PROXY $GATE1 TRACE DATA $VOL.SUBVOL.FILE To stop a running trace: STATUS PROXY $GATE1 TRACE STOP To start a Gateway process that is no longer running: STATUS PROXY START $GATE1 Considerations At times, domains might need to be manually removed from ASAP. When a Linux application registers one or more domains but then fails or stops without first removing those domains, ASAP reports the domains as down at each sample interval thereafter unless they are reregistered by the Linux application.
Linux system to report on the domain so that it can notify that system of the removal. Use the FORCE option to remove a down domain from ASAP on the NonStop server when the domain is no longer known on the Linux side. Domains that are up or inactive must be removed from the Linux system prior to being removed from ASAP on the NonStop server. ASAP on the NonStop server does not notify ASAP on Linux when up or inactive domains are removed; it assumes that the Linux side no longer has knowledge of the domains.
The ASAP Hybrid Entity Each Hybrid Gateway process has the ability to register itself into ASAP to report detailed statistics about its own performance.
3. Managing ASAP Hybrid for Linux This section covers the procedures for installing, configuring, and managing the Linux-based components of ASAP Hybrid. Installing ASAP Hybrid for Linux Installing ASAP Hybrid for Linux essentially involves getting the ASAP Hybrid files onto the Linux system. Once the files are placed, no further steps are required. ASAP Hybrid does not need to be installed to a specific location, nor are additional install scripts necessary to perform initial configuration.
have access, but ideally the directory should be empty and should be named appropriately (for example, asaphybrid.1.1.9). This directory is referred to throughout the remainder of this section as the installation directory. 3. Extract the files contained in the archive using the tar command with the –xzvf options. For example: tar –xzvf asaphybridforlinux.1.1.9.tar.
and simplifies the process of upgrading to newer versions of ASAP Hybrid as they are released. However, you can move the files to the standard Linux locations (/usr/include for the header file, /usr/lib for library files, and so on) or any other location if you prefer. The only restrictions are: The server configuration file (asap.conf) must either reside in the same directory as the Linux server executable (aspaxserver.1.1.
directories identified in Installing ASAP Hybrid for Linux. Because the ASAP Hybrid for Linux installation process does not automatically update any system configuration files or startup scripts, removing the product involves nothing more than removing the component files from the system. Starting the ASAP Hybrid for Linux Server The ASAP Hybrid for Linux server is a daemon and is responsible for providing ASAP services to the API.
controlled shutdown or stops immediately. Controlled Shutdown To stop the ASAP Hybrid for Linux server in an orderly manner, send it a SIGTERM, SIGINT, or SIGQUIT signal. For example: kill –s SIGTERM where is the process ID of the ASAP Hybrid for Linux server process.
Specifying the Configuration File Location The server expects to find configuration information in the asap.conf file located in the server’s program directory. However, you can change this location when you run the server by using the –conf command line option. The –conf option overrides the default server behavior and causes configuration data to be loaded from the location you specify.
[Tracing] The [Tracing] section contains settings related to the server’s built-in trace facility. Each section of the configuration file can contain one or more option settings that relate to that section. These options are specified using keyword/value pairs, with one such pair given per line. The format for a keyword/value pair is:
for the ASAP Hybrid for Linux server, including the name or IP address of the NonStop system to which metric data will be sent, network message size, and pacing interval. Each option is described in detail below. LocalMachine Description: The local Linux machine name. By default, this name is retrieved from the system itself. However, in some cases this name might not be set or might be too long to be useful within ASAP.
Value Range: 512 through 32000 Default Value: 512 Example: MessageSize = 1472 Pacing Description: This value specifies the delay, in milliseconds, between messages sent to the NonStop server. Increasing this value reduces spikes in network activity and equalizes the flow of traffic, but it increases the overall time it takes to get sample data to the NonStop server.
Default Value: 6301 (the standard ASAP Hybrid port) Example: RemotePort = 5555 Logging Options Logging configuration options are contained in the Logging section of the configuration file. These options control the ASAP Hybrid for Linux server’s built-in logging mechanism. These options affect the server’s logging facility only, and do not in any way relate to messages logged by the server to the Linux system log. Each option is described in detail below.
FileName Description: The name of the server log file. If logging is enabled, log records are written to this file, in HTML format. If you change this value, be sure to fully qualify the file name. The ASAP Hybrid for Linux server changes its default directory to the root directory at startup. Therefore, specifying a file name only, without path information, causes the log file to be created in the system’s root directory, which might not be desirable.
AuditInterval Description: Interval, in seconds, at which the server performs automated status and cleanup operations. Value Range: 0 through 2147483647 Default Value: 60 Example: AuditInterval = 120 DomainCleanup Description: If True, down and removed domains are cleaned up when the ASAP Hybrid for Linux server shuts down. If False, these domains remain in shared memory, and the server reattaches to them the next time it is started.
Value Range: True or False Default Value: False Example: FlushRegistrations = True HTMLStatus Description: If True, the server generates a domain report every sample interval. This file is named asapdomains.html and is located in the same directory as the server executable. Value Range: True or False Default Value: False Example: HTMLStatus = True MaxDomains Description: The maximum number of domains allowed on the Linux system.
SampleInterval Description: Interval, in seconds, at which the server sends data to NonStop ASAP. If HTMLStatus is set to True, domain status data is also written at this interval to the asapdomains.html file. The SampleInterval value should not exceed the smallest ASAP RATE value among all the ASAP environments into which applications on the Linux system are registered.
Example: Enabled = True FileName Description: The name of the ASAP Hybrid for Linux server trace output file. If tracing is enabled, trace data is written to this file in HTML format. All trace data is captured in memory in order to reduce the impact of tracing on the server process. Trace data is written to the trace output file only when tracing is stopped or when the server process shuts down. If you change this value, be sure to fully qualify the file name.
0x00000020 0x00000040 0x00000080 0x00000100 0x00000200 0x00000400 0x00000800 0x00001000 0x00002000 0x00004000 0x00008000 0x00010000 0x00020000 0x00040000 0x00080000 0x00100000 0x00200000 0x00400000 0x00800000 0x01000000 0x02000000 0x04000000 0x08000000 Data sent via interprocess communication Insertion of queue items Removal of queue items Creation of objects (Do not enable unless instructed to do so by HP support. It could significantly affect the performance of the server.
Description: Defines the maximum number of trace records to capture, where 0 = no limit. Once this limit is reached, no further trace records are captured unless Wrap is True. Value Range: 0 through 2147483647, where 0 = no limit Default Value: 1000 Example: RecordLimit = 2500 Wrap Description: If True, the server trace wraps when the record limit is reached. Whenever a new trace record is captured, the oldest trace record is deleted.
Sample Configuration File The ASAP Hybrid for Linux installation archive contains a sample configuration file named asap.conf.sample. You can use this file as a basis for creating a configuration for your specific environment. At minimum, you will need to provide an asap.conf file containing the RemoteIPAddress value of the NonStop server to which the Linux system will connect. The asap.conf.sample file follows.
then send the server process a SIGHUP signal to cause it to reload configuration information. For example: kill –s SIGHUP where is the process ID of the ASAP Hybrid for Linux server process. On receipt of the SIGHUP signal, the server process reloads its configuration file and applies any changed option settings.
Cleaning Up Domains Interactively In general, applications that utilize the ASAP Hybrid API operate as follows: Register one or more domains Update domain data items, operational state, and so on Remove domains at shutdown or if the domains no longer need to be monitored When the application finally removes a domain, the ASAP Hybrid for Linux server notifies NonStop ASAP.
If any of these conditions are not met, domains cannot be removed and/or cleaned up, resulting in the presence of unused domains on the NonStop host, on the Linux system, or both. To address this issue, ASAP provides several mechanisms for removing and cleaning up domains interactively: the host-based ASAP command interpreter, use of Linux signals, and the Linux-based asapremove utility.
Important note: Sending a SIGUSR1 signal to the ASAP Hybrid Linux server causes all down domains to be removed. There is no means for picking and choosing which down domains to remove if you use this approach. Removing Down Domains Using the asapremove Utility The asapremove utility supplied with ASAP Hybrid for Linux is intended to be used to remove individual domains that are down. It works by accepting a domain name, registering that domain, and then immediately removing it.
./asapremove My\\DomainName Most Linux command shells interpret backslashes as special escape characters, so two are needed to indicate a single backslash. Cleaning Up Removed Domains Using Linux Signals If the communication link to the NonStop host is down, or ASAP is not running on the host, all domain removals performed on the Linux system remain pending until communication is restored, ASAP is started, and the ASAP Hybrid for Linux server can notify the host that the removals have occurred.
Recovery ASAP Hybrid for Linux incorporates mechanisms to prevent the loss of metric data in the event of a failure of either a client application or the ASAP Hybrid for Linux server itself. Client Recovery If a client application stops or fails for any reason, without first removing all domains it has registered, the data for those domains is preserved by the Hybrid for Linux server. When the application is restarted and reregisters the domains, it is reconnected to the preserved domain data.
ASAP Hybrid for Linux Server Output The ASAP Hybrid for Linux server generates several types of output: The server writes messages to the Linux system log as necessary. In general the server attempts to be judicious about the use of this log, and only writes messages at startup, shutdown, and if significant errors are encountered while the server is running. The ASAP Hybrid for Linux API library also writes messages to the Linux system log if it encounters a major error.
These columns appear in the report: Column Name ASAPX Server PID # Domains Time Updated Update Interval Remote Host : Port ACKs Outstanding Domain Name PID Ver ID New Rst Upd Rem Description PID of the ASAP Hybrid for Linux server process Number of domains registered The last time the domain sample was performed The update interval, in seconds The IP address and port of the NonStop server to which the Linux system is connected Acknowledgement requests pending on this Linux machine; typically this value s
Down Dloc Rank Err ErrD Stat Text D0 – D11 Sample Time True if the domain is down; false if not.
4. The ASAP Hybrid for Linux API The ASAP Hybrid for Linux API Library allows Linux applications to interface to the ASAP subsystem. Applications utilize the API to register domains and update metric counters in shared memory. No other interaction with ASAP is required. The ASAP Hybrid for Linux server extracts domain and counter data from shared memory and passes it to NonStop ASAP where it is processed along with all other ASAP data.
for the AMD64 platform. Multiple libraries provided Both static and shared library versions are provided. You can choose to use the one that makes the most sense for your environment.
Developing Applications Using the ASAP Hybrid API To use the ASAP Hybrid for Linux API from a client application: 1. Define client application entities using the ASAP Entity Definition Language (EDL), and load these definitions into your ASAP environment. For more information on EDL, see the ASAP Extension Manual and the ASAP Client Manual. 2. Include the asapx.h header file in your application source. For example: #include “asapx.h” 3. Modify your make file or compiler commands to search for the asapx.
Optionally update data items for the domains. Single-threaded applications would use the asap_update, asap_updatelist procedures, or both. Multithreaded applications would use the asap_update_ts, asap_updatelist_ts procedures, or both. Optionally update the operational state and text for the domains. Singlethreaded applications would use the asap_opstate procedure, and multithreaded applications would use the asap_opstate_ts procedure.
The advantage of the static library is that it encapsulates ASAP functionality within the given executable. This approach eliminates potential versioning issues and makes it easy to move application executables from system to system because no additional ASAP libraries are necessary. (However, the ASAP Hybrid for Linux server must reside on each of those systems in order to provide services to the client applications.
made to tailor the API to the Linux environment. For example, procedure names are slightly different in order to follow standard Linux practices, in some cases the number or types of parameters have changed slightly, and in every case the range of returned values varies from the range used in ASAPX because the error scenarios on Linux differ widely from those on the NonStop server.
API Details This section describes each of the ASAP Hybrid for Linux API procedure calls in detail. asap_register Register a new domain with ASAP. This procedure must be called once for each domain before you attempt to update data items for that domain. Once a domain has been successfully registered, the application can use the other ASAP Hybrid library procedures to update information for the domain, including data items and operational state and text.
1. They can contain no more than five logical, hierarchical levels, using the backslash (\) character as a level separator. The name cannot begin with a backslash. 2. The ASAP Entity name for this domain must be the leftmost level of the domain name. 3. The entity must be defined in ASAP EDL and must be loaded into the copy of ASAP referenced by the ASAP ID parameter on the NonStop servers configured to accept data from the Linux system. 4. The name must be null-terminated. 5.
const bool rank_enabled_ind Flag to enable or disable ranking when the domain is registered. This parameter is optional. The default value is true, which means ranking is enabled by default. const bool concat_ind Flag indicating whether ASAP should automatically append the current process ID (PID), in text form, to the end of the domain name. This parameter is optional. The default value is true, which means the PID is appended as the last level of the domain name.
ASAP_ERROR_INVALID_ID (-103) The specified ASAP ID exceeded ASAP_MAX_ID_LENGTH characters in length, did not begin with a dollar sign ($), did not contain any characters after $, the first character after $ was not alphabetic, or a subsequent character was not alphanumeric. ASAP_ERROR_INVALID_APP_VERSION (-104) The specified application version either exceeded ASAP_MAX_APP_VERSION_LENGTH characters or contained non-ASCII printable characters.
Differences from the NonStop ASAPX API The domain name parameter is supplied as a standard C null-terminated string, and the domain name length parameter (domain^name^len) has been eliminated. The segment^id parameter has been eliminated. The segment^base parameter has been eliminated. The ASAP ID parameter is supplied as a standard C null-terminated string, and the ID length parameter (id^len) has been eliminated.
asap_remove and asap_remove_ts Removes a domain from the list of domains monitored by ASAP. This procedure must be called whenever ASAP is to stop monitoring a given domain. This procedure affects active monitoring only. It does not remove historical data from the ASAP database. When a domain is removed, ASAP writes a final record for the domain to the ASAP database and then cleans up all resources associated with that domain.
The handle returned from the call to asap_register. This parameter is required. short *ptr_error_detail A detailed error code, if any. This parameter is optional. The default value is NULL, which means no detailed error code is returned. const bool deallocate_ind Flag to indicate whether resources should be deallocated for this domain. If the domain is being removed as part of application or process shut down, resources should be deallocated.
A different range of values and possible errors is returned.
asap_update and asap_update_ts Update a single data item for a domain, using the supplied value and math (operation type). Data items are defined in the EDL for the application. This EDL must be loaded into the running ASAP environment.
const short math The type of math to be done when applying the new value to the in-memory data item. Possible values are given by the ASAP_MATH constants defined in the asapx.h header file. This parameter is optional. The default value is ASAP_MATH_ADD. short *ptr_error_detail A detailed error code, if any. This parameter is optional. The default value is NULL, which means no detailed error code is returned. Return Values ASAP_ERROR_NONE (0) No error. Update was successful.
Example short ErrorDetail; short ReturnValue; // Error detail from call // Return value from call ReturnValue = ::asap_update(Handle, 11, 1234LL, ASAP_MATH_ADD, &ErrorDetail); // // // // // Handle from asap_register Data item 11 Value = 1234 Add it to the data item Returned error information HP NonStop ASAP Hybrid Manual – 529729-004 Page 4-17
asap_updatelist and asap_updatelist_ts Update a list of data items (up to ASAP_MAX_DATAITEMS - 1) for a single domain. Data items are defined in the EDL for the application. This EDL must be loaded into the running ASAP environment.
NULL, which means no detailed error code is returned. Return Values ASAP_ERROR_NONE (0) No error. Update was successful. ASAP_ERROR_INVALID_PARAM (-101) A parameter was invalid. If specified, *ptr_error_detail contains the incorrect parameter number (first param = 1). If one of the asap_triplet items in *ptr_asap_list is incorrect, the value in *ptr_error_detail is: (10 * (index in list + 1)) + one of the following: 0 if the data_item is incorrect, 1 if the val is incorrect, or 2 if the math is incorrect.
Differences from the NonStop ASAPX API A different range of values and possible errors is returned. Example short ErrorDetail; short ReturnValue; struct asap_list List; // Error detail from call // Return value from call // asap_list struct for call List.idx[0].data_item = 5; List.idx[0].val = 1234LL; List.idx[0].math = ASAP_MATH_ADD; List.idx[1].data_item = 9; List.idx[1].val = 2LL; List.idx[1].
asap_control and asap_control_ts Activate or deactivate ranking for the domain. Deactivation is useful in the case of a domain that enters a dormant state for some time. ASAP sets the state of domain to exists, and no further alerts are issued for that domain until ranking is activated. An application should call asap_control for a domain if the domain is not updating its data for a time but will become active again in the future.
Return Values ASAP_ERROR_NONE (0) No error. Operation was successful. ASAP_ERROR_INVALID_PARAM (-101) A parameter was invalid. If specified, *ptr_error_detail contains the incorrect parameter number (first param = 1). ASAP_ERROR_REMOVED (-111) The domain has been removed. Once cleanup occurs, the domain can be reregistered. ASAP_ERROR_HOST_DOMAIN (-112) There is a problem with this domain on the NonStop server. Updates continue to occur locally on the Linux system and are sent to the server.
asap_opstate and asap_opstate_ts Set the operational state for the domain, independent of the state of any of the domain's data items. Calling applications can use these procedures to explicitly specify the state of a given domain and associate a textual description with that state. If asap_opstate is called for a given domain, the state specified overrides any state calculated by ASAP while analyzing the domain’s metric values.
The ASAP OEM state to assign for this domain. This value can be from ASAP_STATE_EXISTS (object exists) through ASAP_STATE_DOWN (object is down). For ASAP_STATE values, see the asapx.h header file. This parameter is required. short *ptr_error_detail A detailed error code, if any. This parameter is optional. The default value is NULL, which means no detailed error code is returned. Return Values ASAP_ERROR_NONE (0) No error. Operation was successful. ASAP_ERROR_INVALID_PARAM (-101) A parameter was invalid.
A different range of values and possible errors is returned.
asap_getlastsampletime Return the time that the domain was last sampled, in seconds since the system was booted. Calling applications can use the standard Linux "sysinfo" system call to get the current time since boot and compare it to the value returned by this procedure. Note that because this procedure does not update any values, there is no need for a thread-safe variant. Both single-threaded and multi-threaded applications can safely call this procedure at any time.
Return Values ASAP_ERROR_NONE (0) No error. Operation was successful. ASAP_ERROR_INVALID_PARAM (-101) A parameter was invalid. If specified, *ptr_error_detail contains the incorrect parameter number (first param = 1). ASAP_ERROR_INVALID_SERVER(-114) The currently running version of the asapxserver does not support this capability. Note you must be running asapxserver version 1.1.6 or later to use this function.
Sample Client Application This small sample application for ASAP Hybrid for Linux takes a domain name that you specify, registers it, updates data items, and then removes the domain. It demonstrates the use of the asap_register, asap_update, asap_opstate, and asap_remove API procedures. // ASAP Hybrid for Linux sample client application // // Include the asapx.h header file #include "asapx.h" #include #include
::printf("asap_opstate returned %d, error detail = %d\n", ReturnValue, ErrorDetail); // // // // At this point, if HTMLStatus is TRUE in the asap.conf configuration file, you can look at the asapdomains.html file in the ASAP Hybrid for Linux server directory, and this domain and data will appear. Note: You might have to wait a few seconds for the next server sample interval. // Pause to give yourself a chance to look at the data.
5. Appendix A: ASAP Hybrid EMS Event Messages This appendix lists detailed information about the EMS event messages generated by ASAP Hybrid. 1901: ASAP INFO HYBRID version date started name cpu An ASAP Hybrid component has successfully started in a processor. version is the version of the ASAP component; for example, V01. date is the release date of this version. name is the process name of the starting component. cpu is the processor where the component started. Cause. Someone started ASAP.
1903: ASAP ERR HYBRID name Server I/O Error pname, FE: err The Proxy SGP could not communicate with the process identified by pname. name is the name of the Proxy SGP process. pname is the name of the process that the SGP was attempting to communicate with. err is the file error encountered by the file-system operation. Cause. The Proxy SGP encountered a file error while attempting to communicate with a Hybrid Gateway process. Effect. The Proxy SGP cannot communicate with the Gateway process.
cname process. err is the name of the configuration file that ASAP was attempting to is the file-system error number. Cause. The Hybrid component encountered a file-system error. Effect. The Hybrid component cannot successfully process its configuration file. Recovery: Correct the file-system error and restart ASAP. 1906: ASAP ERR HYBRID name Unknown Config Opt: text The ASAP Hybrid component found an error in its configuration file. name is the process name of the Hybrid component.
name is the process name of the Hybrid component. err is the file error encountered by the file-system operation. Cause. An ASAP Hybrid component encountered a file error on $Receive. Effect. The $Receive operation is not completed. Failure to open $Receive causes the process to abnormally terminate. Recovery: Correct the file-system error and retry the operation.
Cause. The datagram has probably been corrupted. Effect. The Gateway stops processing the datagram. Recovery: Attempt to identify and correct network problems that could corrupt UDP data. 1911: ASAP ERR HYBRID name Unknown Datagram Received from ipaddr A Hybrid Gateway process received a foreign or corrupt datagram. name is the name of the Hybrid Gateway process. Ipaddr is the IP address and port number of the sending system. Cause. A datagram was received that the Hybrid Gateway was not expecting.
operation is the operation that encountered the error. errno is the socket error number. Cause. TCP/IP returned an error when creating, configuring, setting, binding, getting info about, receiving from, or sending to a socket. Effect. The socket operation does not complete. Recovery: Correct the socket error and retry the operation. 1914: ASAP ERR HYBRID name Unknown Request on $Receive: buf A Hybrid component received a server request it did not understand.
The Gateway process has detected new Linux systems sending it data. name is the name of the Hybrid Gateway process. number is the number of new Linux systems that have sent data since last report. Cause. New Linux systems have recently started sending data to the Gateway process. Effect. The Gateway process processes the new data. Recovery: None required.
