ASAP 2.7 Extension Manual

Implementing the ASAP Extension in an Application
HP NonStop ASAP Extension Manual—425265-004
4-2
Programming Considerations
5. Call the ASAP_REGISTER_ procedure to register a domain with ASAP. The
procedure validates your request, allocates shared memory, and returns the
address.
6. Call ASAP_UPDATE_ or ASAP_UPDATELIST_ to update DataItems in shared
memory at the appropriate points within the application.
7. Optionally, call the ASAP_OPSTATE_ procedure to set the operational status text
and the OpState for the domain.
8. Optionally, call the ASAP_CONTROL_ procedure to turn ranking on and off for the
domain if it is a preferred feature for this application.
9. Optionally, call the ASAP_REMOVE_ procedure to remove a domain from ASAP.
You never have to call ASAP_REMOVE_. If you do not, the domain is tracked as
an outage when the process that registered it stops running.
Programming Considerations
•
Domain names must be unique across a node. By default, ASAP_REGISTER_
adds one level to a domain name, appending the process name of the registering
process to ensure the domain is unique. To turn off this behavior, set flags bit 14 to
on in the procedure call. For more information, see Designing Domain Names on
page 4-3.
•
Use the Timeout parameter to ASAP_REGISTER_ to ensure your application does
not wait for ASAPXMON to register the domain, in case ASAPXMON is busy or
cannot get processor time. The default wait time is 180 seconds. Set Timeout to 5,
3, or fewer seconds to ensures an application does not wait for ASAPXMON.
•
Do not immediately retry failed registration attempts. If ASAP_REGISTER_ returns
an error, wait for a period time before you call it again. Normally, a wait time of 3, 5,
or even 10 minutes is acceptable.
•
If ASAP_UPDATE_ or ASAP_UPDATELIST_ returns an error, the best corrective
action is to call ASAP_REMOVE_ to remove the domain and then re-register the
domain and continue processing, being sure to wait before re-registering as
described above. This action should clear up any problems that exist, and it
provides a mechanism to upgrade the shared-memory segment without restarting
the application.
•
HP highly recommends developing a wrapper for the API that automatically
handles registration, removal, and wait times.
•
Unless it failed and restarted, a single process must not register the same domain
name more than once. Any process using multiple domains must ensure domain
name uniqueness internally. ASAPX assumes that any process reregistering the
same domain has failed and restarted, and ASAPX allocates the same memory
location as the previous registration.