HP NonStop ASAP Extension Manual Abstract This manual describes use of the HP NonStop™ Availability Statistics and Performance Extension (ASAPX) to collect, measure, view, and analyze application service-level metrics to track the productivity, performance, and availability of applications on the NonStop server.
Document History Part Number Product Version Published 422769-001 ASAPX SE31V1 June 1999 425038-001 ASAPX SE31V1 December 1999 425265-001 ASAPX SE31V2 June 2001 425265-002 ASAPX SE31V2 June 2002 425265-003 ASAPX SE31V2 October 2003 425265-004 ASAPX SE31V2 May 2006
HP NonStop ASAP Extension Manual Index Figures What’s New in This Manual v Manual Information v New and Changed Information v About This Manual ix Manual Organization ix Notation Conventions ix 1. Introducing the ASAP Extension Overview of ASAP Architecture 1-1 ASAP Client 1-1 ASAP Server 1-2 ASAP Extension Architecture 1-3 ASAPX 1-5 ASAPX API 1-5 ASAPXMON 1-6 ASAPXSGP 1-6 ASAPX 2.0 Versus ASAPX 1.0 1-7 2.
2. Configuring the ASAP Extension (continued) Contents 2.
4. Implementing the ASAP Extension in an Application (continued) Contents 4.
Figures Contents HP NonStop ASAP Extension Manual—425265-004 iv
What’s New in This Manual Manual Information HP NonStop ASAP Extension Manual Abstract This manual describes use of the HP NonStop™ Availability Statistics and Performance Extension (ASAPX) to collect, measure, view, and analyze application service-level metrics to track the productivity, performance, and availability of applications on the NonStop server.
New and Changed Information What’s New in This Manual • ° ° ° ° SET AGGREGATESTATUS on page 2-19 SET AGGREGATETEXT on page 2-19 SET DETAILEVENTSOFF on page 2-20 SET STATUSEVENTSON on page 2-22 Added the ASAP_GETLASTSAMPLETIME_ procedure and Obtaining the Last Sample Time on page 4-24 Previous Changes The fifth edition of this manual contains these changes: • • • • • • • ASAP Extension Architecture on page 1-3 includes a new ASAPX component. Configuring ASAPX on page 2-2 includes new options.
New and Changed Information What’s New in This Manual • • • • • • • Added SET AGGREGATE on page 2-18, which lets you control aggregation across entities and subdomains. Added SET COLLECTOR on page 2-19, which lets you place ASAPXMON processes in Write-to-Collector mode. Added Migrating From ASAPX Release 1 to Release 2 on page 2-27 for users migrating to ASAPX 2.0 from ASAPX 1.0.
What’s New in This Manual New and Changed Information HP NonStop ASAP Extension Manual—425265-004 viii
About This Manual This manual describes the ASAP Extension product, ASAPX. ASAPX is part of the ASAP product, which provides a network-wide system monitoring, statistics collection, and presentation infrastructure for the HP NonStop™ Kernel operating system. Using ASAP, you can monitor the performance of Application, CPU, Disk, Expand, File, Node, Process, ProcessBusy, RDF, Spooler, System, Tape, and TMF entities.
General Syntax Notation About This Manual UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name computer type. Computer type letters within text indicate C and Open System Services (OSS) keywords and reserved words.
General Syntax Notation About This Manual … Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of 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.
Notation for Messages About This Manual !i:i. In procedure calls, the !i:i notation follows an input string parameter that has a corresponding parameter specifying the length of the string in bytes. For example: error := FILENAME_COMPARE_ ( filename1:length , filename2:length ) ; !i:i !i:i !o:i. In procedure calls, the !o:i notation follows an output buffer parameter that has a corresponding input parameter specifying the maximum length of the output buffer in bytes.
Notation for Management Programming Interfaces About This Manual either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: obj-type obj-name state changed to state, caused by { Object | Operator | Service } process-name State changed from old-objstate to objstate { Operator Request. } { Unknown. } | Vertical Line.
Change Bar Notation About This Manual Change Bar Notation Change bars are used to indicate substantive differences between this 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 COBOL85 environment and the Common Run-Time Environment (CRE).
1 Introducing the ASAP Extension The ASAP Extension (ASAPX) is part of the ASAP product, which provides a networkwide system monitoring, statistics collection, and presentation infrastructure for the NonStop Kernel. Using ASAPX you can collect, measure, view, and analyze application service-level metrics to track the productivity, performance, and availability of applications.
ASAP Server Introducing the ASAP Extension ASAP Server The ASAP Server consists of all the ASAP components that run on the NonStop Kernel, including the ASAP Database, the ASAP Collection Server, ASAP Remote Monitors, and the standard ASAP Stats Gathering Processes. Figure 1-1.
ASAP Extension Architecture Introducing the ASAP Extension ASAP Extension Architecture Through the ASAP Extension, you can extend ASAP collection and presentation functions to your own applications. The ASAP Extension provides an Application Programming Interface (API) so you can add customer application metrics to the ASAP infrastructure. Applications use ASAPX by calling the ASAP_REGISTER_ API procedure to register with ASAPX.
Introducing the ASAP Extension ASAP Extension Architecture How applications use ASAPX: 1. Applications call the ASAP_REGISTER_ API procedure to register with ASAP. 2. The ASAP_REGISTER_API procedure communicates with the ASAPXMON process in the processor where the application resides to register and obtain the shared memory offset for the application domain. 3. The applications call one of the API update procedures to update their statistics directly within shared memory. 4.
ASAPX Introducing the ASAP Extension The final components of ASAPX reside in the ASAPX installation subvolume (ISV): File Description ZASPXC The ASAPX API structure definitions for C programs ZASPXCOB The ASAPX API structure definitions for COBOL programs ZASPXTAL The ASAPX API structure definitions for TAL programs ASAPX To start the ASAPX Conversational Interface (CI): • Type ASAPX at a TACL prompt.
Introducing the ASAP Extension ASAPXMON ASAPXMON The ASAPXMON processes execute in each processor where an application process resides. They allocate the shared memory and parcel out segments of the memory to application processes and are responsible for metrics production, objective analysis and state production. The application processes register with ASAPX by making a library call to the ASAP_REGISTER_ procedure.
ASAPX 2.0 Versus ASAPX 1.0 Introducing the ASAP Extension ASAPX 2.0 Versus ASAPX 1.0 Some of the commands used with version 1.0 of the ASAP Extension were replaced by ASAP commands or by function in the Entity Definition Language (EDL), or they are obsolete: ASAPX 1.0 Configuration Command ASAP DOTs Configuration (for ASAPX 2.0) Page SET DATABASE SET OBJECTIVESDB 2-24 SET DATAITEMS Replaced by EDL n.a. SET METRICS Replaced by EDL n.a. SET NAMEFILE Obsolete n.a.
Introducing the ASAP Extension ASAPX 2.0 Versus ASAPX 1.
2 Configuring the ASAP Extension This section describes how to configure the ASAP Extension (ASAPX): Topic Page Getting Started With ASAPX 2-1 Configuring ASAPX 2-2 Multiple Entity Support 2-3 Configuring DataItems and Metrics 2-8 SET Commands 2-18 Configuring Objectives 2-24 Migrating From ASAPX Release 1 to Release 2 2-27 Getting Started With ASAPX ASAPX is delivered as an independent product on CD and is installed using the IPSETUP installation procedure and the ASAPX Installer macro.
Configuring ASAPX Configuring the ASAP Extension 6. Start or restart ASAP. Use EMS to verify that all components start successfully: ASAP START [\] 7. Change application source code to use the ASAPX API procedures. 8. Point your applications to the ASAPX procedure library (ASAPXLIB) or the native shared-runtime library (ASAPXSRL). Use the ?library or ?search compiler directive, the LIB runtime parameter, or bind the library into your application object file. 9.
Configuring the ASAP Extension Multiple Entity Support Multiple Entity Support Starting with ASAPX Release 2, you describe applications using the ASAP Entity Definition Language (EDL). Many configuration settings previously set with the ASAPX configuration file are now set in EDL. Each application or part of an application is defined as an ASAP entity using EDL. Develop EDL to describe each application.
APP Attributes Configuring the ASAP Extension APP Attributes The attributes associated with the generic APP entity. These attributes are associated with the generic APP entity. They also represent the header attributes that must be present in the order shown in all user-defined entities.
Configuring the ASAP Extension Custom Entity Properties 2. Change the entity name in the EDL entity statement from APP to the name of your entity. 3.
Configuring the ASAP Extension Custom Attributes Example These Entity properties are defined for a Funds Transfer application (entity) that has one custom attribute, the transaction rate. Note the changes in the Command, Detail, Help, Version and DataItem Entity properties. Also, note the addition of the TransRate and TransRateState Attribute definitions in Custom Attributes on page 2-6 to describe the transaction rate metric.
Custom Attributes Configuring the ASAP Extension 10. StateRule—set to UseStateGraphState to evaluate the value against objective values 11. You must also define the associated state attribute as the next attribute in the EDL file. Associated states have these properties: • • • • • Attribute name. Keep names short for associated state attributes: for example, S0, S1, and so on. Grid NO Graph NO GraphMax 9.
Configuring the ASAP Extension Configuring DataItems and Metrics Configuring DataItems and Metrics The ASAP Extension works with two forms of data: • • The application data structure allocated to each registered domain within the shared memory segments. This structure contains up to 12 DataItems—internal counters or other data units that application processes can use to record statistics about their registered domains. The ASAP Extension-generated metric.
Configuring DataItems Configuring the ASAP Extension are REAL numbers stored in scientific notation with a possible range up to approximately 1.15792E78, accurate to approximately 17 digits. The applications can update data in the DataItem structure by calling ASAP_UPDATE_ to update a single DataItem or ASAP_UPDATELIST_ to update many DataItems. The procedures normally add the supplied value to the existing value in memory.
Configuring Metrics (EDL Attributes) Configuring the ASAP Extension Configuring Metrics (EDL Attributes) To define metrics, use the EDL MetricRule attribute property to define the metric formula. For all DataItem types except constants, ASAPX uses the difference between samples as the base value to begin the calculation. For example, if DataItem 0 is defined as an integer and contains a value of 12 at the first sample and a value of 15 at the second, the difference between sample 1 and sample 2 is 3.
Configuring Metrics (EDL Attributes) Configuring the ASAP Extension Assume the six example DataItems have these values in the two samples used by ASAPX to create metrics for a 60-second sampling interval: First sample: DATAITEM 0 1 2 3 4 5 120 12 45 15 2 0 DATAITEM 0 1 2 3 4 5 180 24 90 30 3 1 Second sample: These MetricRule formulas result in these values for the metrics: Metric TransCount Trans Rate ErrorRate Success RespT Server Busy SendBusy State Alert 60 1.0 0.
Configuring the ASAP Extension Aggregation Control Aggregation Control ASAPX 2.0 introduced aggregation by doing aggregation of individual DataItems using the original MetricRule formula for the attribute. For DataItems that are not constants ASAPX used the sum of all DataItems. However, it did nothing for constants because it didn't know how to treat a constant. ASAPX 2.
Configuring the ASAP Extension Aggregation Control Cn The "C" character designates the number following as an integer constant. Any 31-bit positive integer value is acceptable. S[sac] The "S" instructs ASAPX to use the number of seconds in the interval in the calculation. sac An optional aggregate code of one of these values: SUM - Use the sum of seconds in the interval. AVG - Use the average of seconds in the interval. The aggregate code must immediately follow the "S", with at least one space.
Aggregation Control Configuring the ASAP Extension AT TransRate MetricRule "#0/S" Note. The average of "S" is used because the other operand is an integer DataItem.
Built-In Metrics Configuring the ASAP Extension Built-In Metrics ASAPX provides 11 built-in metrics that you can use in an application definition by defining them as attributes in your application EDL file: Attribute Description EDL Attribute Definition (page 1 of 2) Nak Negative acknowledgement counter. It is incremented each time an interval passes when the application has not updated any of its DataItems.
Built-In Metrics Configuring the ASAP Extension Attribute Description EDL Attribute Definition (page 2 of 2) WState Wait state of the registering process. AT WState GRID YES GRAPH YES GRAPHMAX 10 HELP "Wait State" STATEPAIR YES STATERULE USESTATEGRAPHSTATE TYPEDATA CHAR8; AT WstateState GRID NO GRAPH NO GRAPHMAX 9 HELP "State of Wait State"; RegTime Registration date, and time the domain was registered.
Configuring the ASAP Extension Formatting Metric Output Formatting Metric Output ASAPX DataItems other than text are stored as 64-bit floating point numbers, and all metrics are initially computed as 64-bit floating values. The EDL TYPEDATA and FORMAT properties control how ASAPX treats the data once a metric is computed. If TYPEDATA is set to something other than REAL64, ASAPX translates the data to the requested type before storing it in the APP record.
SET Commands Configuring the ASAP Extension SET Commands SET commands are placed in the ASAPXCNF edit file to configure the ASAP Extension subsystem.
Configuring the ASAP Extension SET AGGREGATESTATUS When you use the ONLY option, it is useful to use the MEMORY and MINSTATE options in the EDL Detail command for the entity. This lets a user right-mouse on an aggregate-only domain from the ASAP Client and select Show Object Details to view the individual detail domains that are causing the aggregate domain to alert.
Configuring the ASAP Extension SET CPUS Note. If the ASAP Collector resides on a node that is remote to the ASAPXMON process, the ASAP ID cannot exceed three characters, including the dollar sign ($). For example, the default ASAP ID $ZOO must be replaced with a shortened form of the name ($ZO) if the collector resides on a node other than the ASAPXMON node. ASAP automatically adds two characters to the ASAP ID to name ASAPXMON processes. Examples SET COLLECTOR \CENT.
Configuring the ASAP Extension SET MAXAGGREGATES SET MAXAGGREGATES The MAXAGGREGATES setting in ASAPXCNF specifies how much space ASAPX should allocate internally to contain aggregate domain records. SET MAXAGGREGATES x x is the number of aggregate application domains per CPU. The range is 1024 through 10000. The default is 1024. SET MAXDOMAINS The MAXDOMAINS setting in ASAPXCNF controls the number of domains per CPU and is used by ASAPX to determine the size of the application shared-segment file.
Configuring the ASAP Extension SET PRIORITY SET PRIORITY SET PRIORITY sets the priority for the ASAPXMON processes. SET PRIORITY priority priority is the priority at which ASAPXMON processes should execute. The value must be a valid NonStop Kernel priority number from 1 through 199. The default is SET PRIORITY 100.
Configuring the ASAP Extension SET TEST subvolume is a legal subvolume name where the swap files are created. It must be in the form: $volume.subvolume Note. After an ASAPXMON creates its swap files in a specific location, always point it back to that location when you stop and restart it. Otherwise it cannot access needed contextual information and must re-create the swap files from the Domain table. Examples SET SWAPVOLS 0 $SYSTEM.ASAPX, 1-5 $DATA.ASAPX, 7-15 $DATA5.ASAPX SET SWAPVOLS 1-7 $DATA1.
Configuring the ASAP Extension Configuring Objectives Configuring Objectives Metrics provide greater value when you evaluate them against their perceived objectives. For example, knowing that the average transaction rate for the ATM application is 1,000 transactions per second at 10 a.m. on a Friday morning provides an objective to measure the collected metric values against. If the ATM application processes only 500 transactions per second next Friday morning at 10 a.m.
Configuring the ASAP Extension Ranking Ranking The ASAP Extension produces ranks for the metric versus objective comparisons it performs using ASAP DOTs. ASAPX supports the three different types of ranking that ASAP provides: • • • Standard ranking creates a rank based directly on a pass or fail comparison against the objective. Percentage-based ranking determines rank value by computing the percentage amount the metric was over or under its objective values.
Configuring the ASAP Extension Metrics and ASAP States OEM State Alert Description 4 Medium An objective was exceeded by between 15 and 24 percent. 5 High An objective was exceeded by between 25 and 34 percent. 6 Warning An objective was exceeded by between 35 and 44 percent. 7 Critical An objective was exceeded by 45 percent or more. 8 Down The process that registered the domain is down. (Generated by all ranking modes.
Migrating From ASAPX Release 1 to Release 2 Configuring the ASAP Extension Migrating From ASAPX Release 1 to Release 2 1. Create new ASAPCONF and ASAPXCNF files. You can make a copy of your existing files and modify them: a. Remove any of these commands that appear in the ASAPXCNF file: SET DATABASE SET NAMEFILE SET DATAITEMS SET RANK SET METRIC SET TMF b. Remove the FORMAT command if it appears in the ASAPCONF file. c.
Configuring the ASAP Extension Example: Release 1 to Release 2 File Migration 11. Start ASAPX Release 2. 12. Watch the EMS log to ensure ASAPX is performing normally. Note. Because ASAPX 2.0 uses increased segment sizes to support 1024 domains per processor, the segments are not compatible with ASAPX 1.0 segments. Applications must reregister in ASAPX 2.0 once it is installed. Due to this limitation, you cannot install ASAPX 2.0 in an ASAPX 1.0 environment with active domains.
Configuring the ASAP Extension Example: Release 1 to Release 2 File Migration This example of a Release 1 ASAPXCNF file indicates which commands are the same and which to delete to convert it to a Release 2 ASAPXCNF file: ASAPXCNF File: Release 1 ASAPXCNF File: Release 2 ----------------------------------------------SET DATABASE $SYSTEM.ASAPX delete SET PRIORITY 150 same SET SWAPVOLS 0-15 $SYSTEM.ASAPX same SET RANK STANDARD delete SET NAMEFILE $SYSTEM.ASPXV01.
Configuring the ASAP Extension Example: Release 1 to Release 2 File Migration AT Nak AT AT AT AT AT AT AT AT AT AT AT AT AT GRID YES GRAPH YES GRAPHMAX 10 HELP “Negative Acknowledgement Count” STATEPAIR YES STATERULE UseStateGraphState TypeData INT64 Format “I4”; NakState GRID NO GRAPH NO GRAPHMAX 9 HELP “State of Nak” HEADING “S”; UnAvail GRID YES GRAPH YES GRAPHMAX 10 HELP “Unavailable percent” STATEPAIR YES STATERULE UseStateGraphState TypeData REAL64 Format “F6.
Configuring the ASAP Extension Example: Release 1 to Release 2 File Migration AT Success AT AT AT AT AT AT AT AT AT GRID YES GRAPH YES GRAPHMAX 10 HELP “Percent successful transactions” STATEPAIR YES STATERULE UseStateGraphState TypeData REAL64 MetricRule “#0/ (#0+#1)” Format “F6.
Configuring the ASAP Extension Example: Release 1 to Release 2 File Migration HP NonStop ASAP Extension Manual—425265-004 2- 32
3 Running the ASAP Extension The ASAPX command interpreter (CI) supports the application-specific portions of the ASAP Extension that do not logically fit within the ASAP management framework CI. ASAPX is used to process commands to the ASAPXSGP and ASAPXMON processes on each node. At startup, ASAPX automatically reads the ASAP configuration file (ASAPCONF) and the ASAP Extension configuration file (ASAPXCNF) to define the ASAP Extension environment.
ASAPX Commands Running the ASAP Extension ASAPX Commands All ASAPX commands support the /OUT filename/ option to direct the output of the command to a file other than the current output file.
Control Commands Running the ASAP Extension Examples ASAP $SYSTEM.SYSTEM.ASAPCONF ASAP $ZOO, $SYSTEM.SYSTEM.ASAPXCNF CLEANUP The CLEANUP command cleans up ASAP Extension domain and objective entries. CLEANUP [\node[.]] {ALL | DOMAINS | OBJECTIVES} \node is the remote node where the command should execute. ALL cleans up all domain and objective entries by purging the Domain and Objectives tables and all shared memory swap files.
Control Commands Running the ASAP Extension Caution. Misuse of the DISABLE STATS command can cause serious problems. The ASAPX API update procedures return error –6 to all callers while STATS processing is disabled. Example DISABLE STATS DISABLE STATS \REMOTE ENABLE STATS The ENABLE STATS command causes the ASAP_UPDATE_ and ASAP_UPDATELIST_ procedures to stop returning error –6 to all callers. ENABLE STATS [\node] \node is the remote node where the command should execute.
Control Commands Running the ASAP Extension FC The FC command is the standard NonStop Kernel fix command. Use it to fix the last command entered or a command from the history buffer. FC [n | text] n is a line number from the history buffer. text is partial text to use for a search through the history buffer. Examples FC FC 3 FC ADD HELP The HELP command displays help text from the ASAPXHLP file. HELP [ALL | command [subcommand]] ALL displays a brief list of all of the commands available in ASAPX.
Control Commands Running the ASAP Extension n is the number of lines to display from the history buffer. The default is 20 lines. The maximum is 100 lines. Examples HISTORY HISTORY 40 HISTORY 5 OBEY The OBEY command executes ASAPX commands contained in an edit file. O[BEY] filename filename is the obey file name. It must be in the form: [\node.][$volume.][subvolume.]filename. Examples OBEY $SYSTEM.ASAP.
Control Commands Running the ASAP Extension Process The process name of the process that registered the domain Cpu The processor where the ASAPX process is executing Pin The NonStop Kernel process identification number of the ASAPX process Stats The status of STATS processing for the ASAPX process Regst The number of domains registered in the ASAPX process Avail The number of registered domains in the ASAPX process that are available HDmn# The high domain number in use in the ASAPX process S
ASAPX Commands Summary Running the ASAP Extension ASAPX Commands Summary ALLOW {ALL | n [ERRORS]} ASAP [asapconf | $asapid, asapxcnf] CLEANUP [\node[.
4 Implementing the ASAP Extension in an Application The ASAP Extension lets you configure applications to use the ASAP suite of services through six provided API procedures. This section describes programming for the ASAP Extension: Topic API Procedure Page Implementing the ASAPX API in Your Application n.a. 4-1 Designing Domain Names n.a. 4-3 Setting a Version Identifier n.a.
Implementing the ASAP Extension in an Application 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.
Implementing the ASAP Extension in an Application • • • • Designing Domain Names All callers to all ASAPX procedures must be named. ASAPX uses the process name of the registering process to track domain availability and to ensure uniqueness of domain names. All ASAPX API procedures return a completion code that the application processes calling those procedures must check. If the ASAP_REGISTER_ procedure returns an error, the registration failed.
Implementing the ASAP Extension in an Application • • Domain Name Uniqueness Domain names must be unique. Domain names must follow the Balanced Tree Design on page 4-4. Domain Name Uniqueness To ensure domain name uniqueness, ASAPX stores all domain names in a Domain table file in its database subvolume. One record is added to the table during the registration process for each domain.
Implementing the ASAP Extension in an Application Domain Name Examples Domain Name Examples These domain names are all valid: Atmapplicationserver1 Atm\Withdrawals\Requesters\Test\$Test23 Atm\Deposit\Zeist-north\Local\$Line.#su387 Setting a Version Identifier Using a version identifier helps show the impact of new versions on application statistical data.
ASAP_REGISTER_ Procedure Implementing the ASAP Extension in an Application • • The domain name, in its final form, must be unique on the system where the ASAP Extension executes. If the application process allocated any extended segment files before calling the Register procedure, the application must supply a value for the segment ID and base address that are allocated by the Register process. If a value is not supplied, segment ID 0 is used.
Implementing the ASAP Extension in an Application ASAP_REGISTER_ Procedure Value Definition –8 Max domains reached. No more domains can be registered in that CPU. –9 Duplicate domain name found. Registration is rejected. –10 Memory slot for this domain is already allocated to another domain. –11 Invalid reply received from ASAPXMON. -12 Memory address trap detected. The shared memory address returned from ASAPXMON causes a memory trap. domain^name:domain^name^len STRING .
Implementing the ASAP Extension in an Application ASAP_REGISTER_ Procedure segment^base INT(32) is the segment base address to be used by the registration procedure in its call to SEGMENT_ALLOCATE_. Supply this value if your application previously called SEGMENT_ALLOCATE_ to allocate a flat extended segment or if the application registers into multiple copies of ASAP. For more information, see the SEGMENT_ALLOCATE_ procedure in the Guardian Procedure Calls Reference Manual.
Implementing the ASAP Extension in an Application ASAP_REGISTER_ Procedure Syntax for C Programmers #include ASAPXH(ASAP_REGISTER_) /* #pragma asap_register_ */ _tal _extensible short asap_register_ ( const char _far *, /* IN REQUIRED */ /* Application domain name being registered */ short , /* IN REQUIRED */ /* domain name length */ long _far *, /* OUT */ /* Shared memory segment offset for this domain */ short _far *, /* OUT OPTIONAL */ /* Detailed error */ short , /* IN OPTIONAL */ /* Segment to be use
Removing a Domain Implementing the ASAP Extension in an Application Example 2 – Application Uses an Extended Data Segment int(32) int seg^offset ,.ext s^offset ; error ,version ,segment^id ; domain^name[0:63]; string . . . error := segment_allocate_(segment^id,….. . . .
ASAP_REMOVE_ Procedure Implementing the ASAP Extension in an Application The final time a process calls the remove procedure, when it removes its last domain from the ASAP Extension, it should supply the control flag indicator to cause the ASAP Extension to deallocate the extended memory segment for the process. You can manually remove domains using the ASAP command interpreter MONITOR command: • • • • To remove domains that belong to user-defined entities, specify an entity name in the MONITOR command.
Implementing the ASAP Extension in an Application ASAP_REMOVE_ Procedure seg^offset INT(32) is the offset into the shared memory segment allocated to the metrics for this domain. This was initially returned to the caller in its call to ASAP_REGISTER_. error^detail INT .EXT:ref:1 is returned here when this parameter is used and an error occurs. segment^id INT is the segment identifier to be used by the registration procedure in its call to SEGMENT_DEALLOCATE_. The default is 0.
Implementing the ASAP Extension in an Application int Updating DataItems string error ; domain^name[0:26] ; domain^name domain^name ‘:=’ “ “ & domain^name for 26; !load domain ‘:=’ my^domain^name for name^len; !27 bytes if (error := ASAP_REMOVE_ ( seg^offset ,!error^detail! ,!segment^id! ,!flags! ))<> 0 then begin call write(ems^collector,error^message…..
Disable Statistics Processing Implementing the ASAP Extension in an Application for the domain was corrupted. In addition to the checksum, boundary tags are used to segment each memory area to protect from moves across structure boundaries. The checksum procedure performs tag validation during each invocation and returns the –4 error if boundary tags are corrupted.
Implementing the ASAP Extension in an Application Disable Statistics Processing Value Definition –6 Statistics shutdown request has been issued. Statistics are disabled. –7 Attempt to replace a nonconstant DataItem. –8 The DataItem in memory experienced an arithmetic overflow and has been reset to zero. This is only a warning. –9 Memory address trap detected. The supplied shared memory address causes a memory trap.
ASAP_UPDATELIST_ Procedure Implementing the ASAP Extension in an Application Syntax for C Programmers #include ASAPXH(ASAP_UPDATE_) /*#pragma asap_update_ */ _tal _extensible short asap_update_ ( long , /* IN REQUIRED */ /* Shared memory segment offset for this domain */ short _far *, /* OUT OPTIONAL */ /* Detailed error */ short , /* IN REQUIRED */ /* Data item being updated.
Implementing the ASAP Extension in an Application ASAP_UPDATELIST_ Procedure seg^offset INT(32) is the offset into the shared memory segment allocated to the metrics for this domain. This was initially returned to the caller in its call to ASAP_REGISTER_. error^detail INT .EXT:ref:1 a detailed error, if any, is returned here when this parameter is used and an error occurs. num INT is the number of DataItems to be updated, from 1 through 12.
Implementing the ASAP Extension in an Application if (error:= ASAP_REGISTER_(… . . . call begintransaction(…. . . . call endtransaction(…..
Implementing the ASAP Extension in an Application ASAP_UPDATELIST_ Procedure . . state := get^my^state; !get my state data^item := 3; !set to state value := $fix(state); !convert to fixed if updates then if (error := ASAP_UPDATE_ ( seg^offset ,!error^detrail! ,data^item ,value ,1 )) <> 0 then call report^error; Example 4 – Update Many int(32) seg^offset; int error, data^item, state; string domain^name[0:63]; fixed value; struct .list(asap^list^def); . . . if (error := ASAP_REGISTER_… . . .
Controlling the Ranking of a Domain Implementing the ASAP Extension in an Application Controlling the Ranking of a Domain You can turn off ranking for a domain to instruct ASAPX to return ASAP State 1 for all metrics within the domain. The domain then appears gray on the ASAP graph displays. You can control the ranking of a domain through the ASAP RANK command and through programmatic use of the ASAP_CONTROL_ procedure.
Implementing the ASAP Extension in an Application ASAP_CONTROL_ Procedure flags INT is a control word indicating: flags.<13> Reserved for future use. flags.<14> Enable ranking for this domain. flags.<15> Disable ranking for this domain. Note. If bit 14 is on, ASAPX ignores bit 15.
Operational Status and State Implementing the ASAP Extension in an Application Operational Status and State Application records contain a 15-byte text field used to indicate the operational status and state of the domain. ASAPX sets this to Up, Down, Error, or Removed. The application can set the status text and associated state directly with a new API procedure ASAP_OPSTATE_.
Implementing the ASAP Extension in an Application ASAP_OPSTATE_ OpState INT:value is a valid OEM state corresponding to the operational status of the domain. OEM states range from 1 (existence) to 8 (down). Usage Consideration Use this procedure to have your applications control the status text displayed for each domain. You might want to do this for failure conditions, reliance on outside resources, and so on. Usage Examples Proc Update^Text(Text:Len,State,Offset); String .
Implementing the ASAP Extension in an Application Obtaining the Last Sample Time Obtaining the Last Sample Time A program can obtain the last ASAP sample time by calling the ASAP_GETLASTSAMPLETIME_ procedure. The time unit returned is the number of seconds since system cold load that ASAP last sampled the shared memory segment to gather and compute application statistics.
Implementing the ASAP Extension in an Application Syntax for C Programmers sample^secs FIXED .EXT:ref:1 is the number of seconds since system cold load of the last ASAP sample time.
Implementing the ASAP Extension in an Application Example GETLASTSAMPLETIME Procedure Call HP NonStop ASAP Extension Manual—425265-004 4- 26
Index A Architecture ASAP 1-1 ASAPX 1-3 ASAP Client product 1-1 command 3-2 Server product 1-2 ASAPX API 1-3, 1-5 API procedures 4-1 architecture 1-3 components ASAPX 1-4 ASAPXDLL 1-4 ASAPXLIB 1-4 ASAPXMON 1-4 ASAPXSGP 1-4 ASAPXSRL 1-4 ASAPXSRO 1-4 ASAPXTST 1-4 ZASPXC 1-5 ZASPXCOB 1-5 ZASPXTAL 1-5 configuration 2-2, 2-18 Conversational Interface 1-5 Installer 1-4 Installer files ASAPXDECS 1-4 ASAPXH 1-4 ASAPXCNF 2-10 ASAPXDECS 1-4 ASAPXDLL 1-4 ASAPXH 1-4 ASAPXLIB 1-4 ASAPXMON 1-4, 1-6 ASAPXSGP 1-4, 1-6 ASA
D Index Commands (continued) SET STATUSEVENTSON 2-22 SET SWAPVOLS 2-22 SET TEST 2-23 STATUS 3-6 ! 3-7 Configuring ASAPX 2-2, 2-18 DataItems 2-8 metrics 2-10 Control commands ASAP 3-2 CLEANUP 3-3 DISABLE STATS 3-3 ENABLE STATS 3-4 ENV 3-4 EXIT 3-4 FC 3-5 HELP 3-5 HISTORY 3-5 list of 3-2 OBEY 3-6 STATUS 3-6 ! 3-7 Conversational Interface, ASAPX 1-5 F FC command 3-5 H HELP command 3-5 Historical ranking 2-26 HISTORY command 3-5 I Installing and configuring ASAPX 2-1 M MetricRule attribute property 2-10 M
P Index P Percentage-based ranking 2-25 Procedures ASAP_CONTROL_ 4-20 ASAP_GETLASTSAMPLETIME_ 4-24 ASAP_OPSTATE_ 4-22 ASAP_REGISTER_ 1-4, 4-6 ASAP_REMOVE_ 4-11 ASAP_UPDATELIST_ 4-16 ASAP_UPDATE_ 4-14 removal 4-10 R STATUS command 3-6 Swap parameter 2-22 V Version identifier 4-5 Z ZASPXC 1-5 ZASPXCOB 1-5 ZASPXTAL 1-5 Special Characters ! command 3-7 Ranking historical 2-26 percentage-based 2-25 standard 2-25 Registration procedure 4-5 verification 4-5 Removal procedure 4-10 S SET AGGREGATE 2-18 SET
Special Characters Index HP NonStop ASAP Extension Manual—425265-004 Index -4
Content Feedback First Name: __________________ Phone: _____________________ Company: ___________________ Last Name: _________________ e-mail address: ______________ (All contact information fields are required.) If you’re reporting an error or omission, is your issue: Minor: I can continue to work, but eventual resolution is requested. Major: I can continue to work, but prompt resolution is requested. Critical: I cannot continue to work without immediate response.
What’s New in This Manual What’s New in This Manual v Manual Information v New and Changed Information v About This Manual ix Manual Organization ix Notation Conventions ix 1. Introducing the ASAP Extension Overview of ASAP Architecture 1-1 ASAP Client 1-1 ASAP Server 1-2 ASAP Extension Architecture 1-3 ASAPX 1-5 ASAPX API 1-5 ASAPXMON 1-6 ASAPXSGP 1-6 ASAPX 2.0 Versus ASAPX 1.0 1-7 2.
3. Running the ASAP Extension SET MAXAGGREGATES 2-21 SET MAXDOMAINS 2-21 SET OBJECT 2-21 SET PRIORITY 2-22 SET STATUSEVENTSON 2-22 SET SWAPVOLS 2-22 SET TEST 2-23 Example: ASAPXCNF File 2-23 Configuring Objectives 2-24 Domains of Service 2-24 Ranking 2-25 Metrics and ASAP States 2-26 Migrating From ASAPX Release 1 to Release 2 2-27 Example: Release 1 to Release 2 File Migration 2-28 3. Running the ASAP Extension Running ASAPX 3-1 ASAPX Commands 3-2 Control Commands 3-2 ASAPX Commands Summary 3-8 4.
Index ASAP_CONTROL_ Procedure 4-20 Operational Status and State 4-22 ASAP_OPSTATE_ 4-22 Obtaining the Last Sample Time 4-24 ASAP_GETLASTSAMPLETIME_ 4-24 Syntax for C Programmers 4-25 Example GETLASTSAMPLETIME Procedure Call 4-25 Index HP NonStop ASAP Extension Manual—425265-004 3
Index HP NonStop ASAP Extension Manual—425265-004 4
Examples Examples HP NonStop ASAP Extension Manual—425265-004 1
Examples HP NonStop ASAP Extension Manual—425265-004 2
Figures Figures Figure 1-1. Figure 1-2.
Figures HP NonStop ASAP Extension Manual—425265-004 2
Tables Tables HP NonStop ASAP Extension Manual—425265-004 1
