15.1 Send Request

The Send Request option is used to send a data or event request from the selected element. The Send Request option is dimmed if an element was not selected prior to selecting the Requests button or if the selected element has no agents specified.

Figure 15-3

Data and event requests send information such as the number of reports and reporting intervals to the specified agents on the target machine. The agents automatically generate reports at specified intervals without intervention (polling) from the Console. The activity daemon running on the Console workstation periodically verifies that the specified agent is running on the target machine. In the case of proxy agents, the proxy agent polls the target system at the intervals specified in the data or event request.

See the Tasks section of this Manual for examples of sending data and event requests.

15.1.0.1 Data Request Template

Figure 15-4 is an example of a data request named DataReachable. A description of the fields in the template are provided in Figure 15-4.

Figure 15-4

The description of the agent group for the request is displayed in the lower left corner of the window. The properties fields for this data request need to be specified at this time. Each field is described below.

Reporting Characteristics The fields on the left side of the Data Request window specify reporting characteristics. Each field is described below.

Name: The optional name you wish to assign to the request. This allows you to assign a recognizable name to a request. The request manager assigns a request name, if one is not specified, using the following format:

<agent>.<group>.<number> (for example, hostperf.data.0)

Proxy System: The name of the system the data request is to be sent to.

Interval: Specifies the interval (in seconds) for the agent on the target system to send reports. An Interval value of 0 indicates that the agent should use its default interval. See the agent's man page for its default interval.

Count: Specifies the number of times for the agent on the target system is to send reports. A count of 0 specifies that the agent is to send reports until the request is stopped or killed. If a count is specified, and a Stop Date/Time is/are specified, the request stops if the specified number of reports are generated before the Stop Date/Time are reached. If the Stop Date/Time is/are reached before the specified number of reports are generated, the request stops at the specified time.

Key:

Identifies a particular row in a table (for example, ie0 or le0 in an Ethernet interface table). The use of a key is agent-specific and is indicated in the bottom left corner of the Data Request Properties window. See the man page for the particular agent for information regarding keys. If no key is specified, the entire table is returned.

Restart: Specifies whether the agent should attempt to restart the request if the system on which the agent is running reboots, the agent terminates unexpectedly, or the Console itself is restarted. If Restart is off (no check mark appears in the accompanying box), the request is discarded if the agent fails or if you quit the Console. If Restart is on (a check mark appears in the accompanying box), the request is restarted. The default setting of this field is determined by the Restart Request upon Agent Failure setting in the Console Properties Requests category. Click SELECT on the box next to this field to toggle the check mark on or off.

Defer Reports: Specifies whether or not the agent should cache reports and send them to the Console only when asked to. If Defer Reports is on (a check mark appears in the accompanying box), the agent is directed to collect the statistics, but send them to the Console only when directed. Defer Reports

tells the agent to cache the last 32 reports. If 32 reports are cached, or if the agent runs out of memory, the oldest report is deleted when a new report is cached. You should not specify Defer Reports for agents that return a large amount of data (for example, a routing table).

In many cases an agent collects information useful for debugging problems. This information might not be of interest in your normal daily operation. Furthermore, if a request were started before the error occurred, data reports will continually stream back to the Console causing unnecessary network traffic and increased CPU load. If, on the other hand, the request was started after the error happened, the debugging information would not have been collected. By setting Deferred Sending on, reports are held in the agent's system until you need to ask for them.

The data request must be active for Defer Reports to work properly; that is, issue the request with a long Interval and high Count. Refer to the "Viewing and Modifying Requests" section for more information on how to obtain deferred reports.

On Completion: Specifies whether the request should be deleted or saved upon completion. To specify that the request be saved, drag MENU over the On Completion abbreviated menu button--release MENU over Save Request. If you choose to save the request, the request glyph is dimmed after the request has been completed but remains in the view of the target element. You can examine, modify, or restart the saved request.

If you choose Delete Request on Completion, stopping the request is the same as killing it. (Refer to the "Viewing and Modifying Requests" section for more information.)

Options: Specifies any options (such as arguments) that the agent expects. To specify Options, type in an option string. For example, with SNMP requests you can specify an SNMP read-community name. The information that you can specify in the Options field is agent-specific--not all agents accept options. See the man page for the particular agent for information regarding options.

---

Note - Starting with version 2.3, there is a new flag called get-requested-attribute-only. By default it is set to true. Only the requested attributes will be retrieved. When this flag is set to false, all attributes are retrieved.

---

Log to File: Specifies the file name where reports are to be stored. If you specify a file name with no path, the Console uses the current directory. If you fully qualify the file name and the left-most characters scroll left, they are not lost.

To Program: A shell command line specifying a program or shell script to be run. Include the directory path, if necessary. Data reports are passed to the standard input of the program or shell script. Every active program to which data reports are sent keeps a file descriptor open. The default maximum number of file descriptors allowed for a single process is 64. You can increase this number up to 256 by using the limit command in the C-shell.

Schedule: Set this field to "On" in order to activate the scheduling options below.

Date Format: Select one of the four formats in which you will enter the start and stop dates.

Start Date: When you enter a date here, and click the Start button, the request will start on the specified date.

Stop Date: When you enter a date here, the request will stop on the specified date.

Start Time: When you enter a time here, and click the Start button, the request will start at the specified time.

Stop Time: When you enter a time here, the request will stop at the specified time.

Selecting Attributes The fields in the right portion of the Data Request window are used to specify attributes.

Attributes: A scrolling list that contains those attributes for which you are requesting data. You choose an attribute and how you want the attribute data displayed with the fields beneath the Attributes scrolling list (described below). When you click SELECT on the Apply button at the bottom right of the window, the attribute is added to the Attributes scrolling list.

Following is a description of the Attribute and attribute display fields:

Attribute: Specifies the attribute you want the agent to return data on. When the Data Request window is first displayed, the Attribute field displays the name of the first attribute in the group/table from the agent schema file. To specify a particular Attribute, press MENU on the Attribute abbreviated menu button and release MENU on the desired entry. When an attribute is selected, a description is displayed in the lower-right footer.

---

Note - If no attribute is specified, all attributes for the selected group or table are written to the Data Reports log. For tables, the values of the keys are also returned. However, if you specify a particular table attribute, the key values are not returned.

---

Data Log: Specifies whether or not the attribute data should be written in the Data Reports Log. To specify that the data not be written in the Data Reports log, drag MENU over the Data Log abbreviated menu button--release MENU over False.

Indicator: Specifies whether or not the attribute data should be displayed in an Indicator. An Indicator shows the last reported value for a particular attribute. Refer to the "Indicators" section for more information.

To specify the Indicator display option, click SELECT on the Indicator box.

Strip Chart: Specifies whether or not the attribute data should be displayed in a Strip Chart. A Strip Chart contains an auto-scaled strip chart of values for an attribute. Refer to the "Strip Charts" section for more information.

To specify the Strip Chart display option, drag MENU over the Strip Chart abbreviated menu button--release MENU over either Absolute Values (chart the received values) or Delta Values (chart the differences between received values).

Graph Tool: Specifies whether or not the attribute data should be displayed by the Grapher. The Graph Tool, also known as the Results Grapher, is an application that allows the display of data received by the Console. Only data of types integer, float, counter, gauge, timestamp, or UNIX time can be plotted. Refer to Chapter 21, "Results Grapher," for more information about the Graph Tool. To specify the Graph Tool display option, drag MENU over the Graph Tool abbreviated menu button--release MENU over either Absolute Values (graph the received values) or Delta Values (graph the differences between received values).

Adding Attributes The buttons below the Attributes fields in the Data Request window allow you to add, change, and delete attribute selections in the Attributes scrolling list. The buttons are described below:

• Apply tells the request manager to add the Attribute selected to the Attributes scrolling list.
• Reset tells the request manager to reset the Attributes scrolling list back to its default value.
• Delete tells the request manager to remove the Attribute selected from the Attributes scrolling list.

An entry in the scrolling list may be selected at any time by pointing the mouse pointer at the entry and clicking the SELECT button. This updates the window to the settings for the selected attribute. An entry may be deleted by selecting it and clicking on the Delete button.

Sending the Data/Event Request The buttons at the bottom left of the Data/Event Request window allow you to send, hold, and reset the data/event request. The buttons are described below:

• Start tells the request manager to send the data/event request.
• Hold tells the request manager to hold the data/event request.
• Reset tells the request manager to set the data/event request to its default values.

Once you have specified the options that you desire in the Request Builder template, click SELECT on the Apply button. Refer to "Data Request Template," above for a description of the template that will be displayed next. Again, specify the desired options and then click on the Start button to send the data request to the desired agent.

15.1.0.2 Event Request Template

Figure 15-5 is an example of an event request named if System Reboot.

Figure 15-5

Reporting Characteristics The fields on the left side of the Event Request window specify reporting characteristics. Each field is described below.

Name: The optional name you wish to assign to the request. This allows you to assign a recognizable name to a request. The request manager assigns a request name, if one is not specified, using the following format:

<agent>.<group>.<number> (for example, hostperf.data.0)

Proxy System: The name of the system the data request is to be sent to.

Interval: Specifies the interval (in seconds) for the agent on the target system to send reports. An Interval value of 0 indicates that the agent should use its default interval. See the agent's man page for its default interval.

Count: Specifies the number of times for the agent on the target system is to send reports. A count of 0 specifies that the agent is to send reports until the request is stopped or killed. If a count is specified, and a Stop Date/Time is/are specified, the request stops if the specified number of reports are generated before the Stop Date/Time are reached. If the Stop Date/Time is/are reached before the specified number of reports are generated, the request stops at the specified time.

Key:

Identifies a particular row in a table (for example, ie0 or le0 in an Ethernet interface table). The use of a key is agent-specific and is indicated in the bottom left corner of the Data Request Properties window. See the man page for the particular agent for information regarding keys. If no key is specified, the entire table is returned.

Restart: Specifies whether the agent should attempt to restart the request if the system on which the agent is running reboots, the agent terminates unexpectedly, or the Console itself is restarted. If Restart is off (no check mark appears in the accompanying box), the request is discarded if the agent fails or if you quit the Console. If Restart is on (a check mark appears in the accompanying box), the request is restarted. The default setting of this field is determined by the Restart Request upon Agent Failure setting in the Console Properties Requests category. Click SELECT on the box next to this field to toggle the check mark on or off.

Send Once: If you check this box, the event request is killed after the console receives the event. If the box is not checked, an event report is sent for every event occurrence.

Defer Reports: Specifies whether or not the agent should cache reports and send them to the Console only when asked to. If Defer Reports is on (a check mark appears in the accompanying box), the agent is directed to collect the statistics, but send them to the Console only when directed. Defer Reports

tells the agent to cache the last 32 reports. If 32 reports are cached, or if the agent runs out of memory, the oldest report is deleted when a new report is cached. You should not specify Defer Reports for agents that return a large amount of data (for example, a routing table).

In many cases an agent collects information useful for debugging problems. This information might not be of interest in your normal daily operation. Furthermore, if a request were started before the error occurred, data reports will continually stream back to the Console causing unnecessary network traffic and increased CPU load. If, on the other hand, the request was started after the error happened, the debugging information would not have been collected. By setting Deferred Sending on, reports are held in the agent's system until you need to ask for them.

The data request must be active for Defer Reports to work properly; that is, issue the request with a long Interval and high Count. Refer to the "Viewing and Modifying Requests" section for more information on how to obtain deferred reports.

On Completion: Specifies whether the request should be deleted or saved upon completion. To specify that the request be saved, drag MENU over the On Completion abbreviated menu button--release MENU over Save Request. If you choose to save the request, the request glyph is dimmed after the request has been completed but remains in the view of the target element. You can examine, modify, or restart the saved request.

If you choose Delete Request on Completion, stopping the request is the same as killing it. (Refer to the "Viewing and Modifying Requests" section for more information.)

Options: Specifies any options (such as arguments) that the agent expects. To specify Options, type in an option string. For example, with SNMP requests you can specify an SNMP read-community name. The information that you can specify in the Options field is agent-specific--not all agents accept options. See the man page for the particular agent for information regarding options.

---

Note - Starting with version 2.3, there is a new flag called get-requested-attribute-only. By default it is set to true. Only the requested attributes will be retrieved. When this flag is set to false, all attributes are retrieved.

---

Alternate Proxy Use this field to specify an alternate proxy you wish to use to launch a request that has previously been launched with a different proxy agent. See "Alternate Proxy" for more information on this feature.

Schedule: Set this field to "On" in order to activate the scheduling options below.

Date Format: Select one of the four formats in which you will enter the start and stop dates.

Start Date: When you enter a date here, and click the Start button, the request will start on the specified date.

Stop Date: When you enter a date here, the request will stop on the specified date.

Start Time: When you enter a time here, and click the Start button, the request will start at the specified time.

Stop Time: When you enter a time here, the request will stop at the specified time.

Important Information About Interval and Count fields For event requests, interval and count fields simply specify when the agent is to send a report. A report is forwarded to the Console system only if it has been determined that an event has occurred. For agents that are shipped with the product, the value reported for an attribute is the value noted at the reporting interval. Thus, it is possible for event conditions to occur between reporting intervals and not cause an event report.

If Send Once has been selected (a check mark appears in the accompanying box), the request is terminated after the Console receives the first event report. Click SELECT on the Send Once box to toggle the check mark on or off.

Alternate Proxy Starting with version 2.3, you can use an alternate proxy to create an event request against a device. When an event is generated against a device and a value name is specified in the alternate proxy field, the request is started on

this proxy agent on the specified host. This become useful in a troubleshooting a situation such as the following: You are pinging a device in a remote location, and it responds by indicating that the device is down. To verify that it is the device and not, for example, an intermediate router, you can send the same request using an alternate proxy agent. You might then want to try an alternate route through another proxy agent on an alternate network. This way, you can verify the router is down, not the device. The alternate proxy feature enables you to do this verification automatically.

The alternate proxy field is enabled only when you send requests against proxy agents.

Descriptions of the Attribute fields are provided below:

Attributes: A scrolling list that contains attributes for which you want event information.

Attribute: Specifies the attributes that you want to use to specify an event. Click SELECT on the button to see the list of available attributes. After you set attribute threshold(s), click SELECT on Apply to add the attribute to the Attributes list.

Relation1, Relation2: Specify threshold conditions for reporting an event. You can specify up to two threshold relational operators; the event is reported if either of the two threshold conditions are met. To set the threshold relational operator(s) for

Relation1 or Relation2, drag MENU over the Relation abbreviated menu button to display the following list of relational operators in a pop-up menu--release MENU over the desired relational operator.

Threshold Not Set means you have not set a threshold for this attribute. This is the default choice.

Equal To tells the agent to report an event if the attribute value equals "Thresholdn".

Not Equal To tells the agent to report an event if the attribute value does not equal "Thresholdn".

Less Than tells the agent to report an event if the attribute value is less than "Thresholdn."

Less Than Or Equal To tells the agent to report an event if the attribute value is less than or equal to "Thresholdn."

Greater Than tells the agent to report an event if the attribute value is greater than "Thresholdn."

Greater Than Or Equal To tells the agent to report an event if the attribute value is greater than or equal to "Thresholdn."

Changed tells the agent to report an event if the attribute value differs from the last sampled value.

Increased By tells the agent to report an event if the attribute value has increased by "Thresholdn" compared to the last sampled value.

Decreased By tells the agent to report an event if the attribute value has decreased by "Thresholdn" compared to the last sampled value.

Increased By More Than tells the agent to report an event if the attribute value has increased by more than "Thresholdn" compared to the last sampled value.

Increased By Less Than tells the agent to report an event if the attribute value has increased by less than "Thresholdn" compared to the last sampled value.

Decreased By More Than tells the agent to report an event if the attribute value has decreased by more than "Thresholdn" compared to the last sampled value.

Decreased By Less Than tells the agent to report an event if the attribute

value has decreased by less than "Thresholdn" compared to the last sampled value.

---

Note - For the Changed, Increased By, Decreased By, Increased By More Than, Increased By Less Than, Decreased By More Than, and Decreased By Less Than operators, the Count field of the report characteristics must not be '1.' A Key must be supplied if a table of attributes is selected.

---

Threshold1, Threshold2: Specify the threshold value if the selected operator is other than Threshold Not Set, or Changed.

Priority: Specifies the priority of the request. Click SELECT on the desired priority button (Low, Medium, or High) for the request.

Glyph Effect: Specifies a visible indicator when the specified event is reported. Press MENU on the Glyph Effect abbreviated menu button to display a signal options pop-up menu. Release MENU on the signal option you want. You can choose only one visual signal option. In order to have the "decay" feature in effect, you must select the Priority by Color option.

The following options are available: Blink Glyph

Blinks the glyph of the element for which an event has been reported.

Dim Glyph

Dims the glyph of the element for which an event has been reported.

Priority by Color

Causes the glyph to change color, based on the priority of the reported event. The defaults are:

• red = high priority
• orange = medium priority
• yellow = low priority
• blue = decay

Starting with version 2.3, you can customize colors, including the "decay" color. See Chapter 4, "Requesting Data," or Chapter 5, "Specifying Event Requests," for procedures to customize Color by Priority.

If multiple reports are received for a system, the highest priority is used. In association with the Priority by Color option is the "decay" feature. This feature pertains to events and traps that have reached a threshold and then fallen below it, or that have had an event or trap stop being reported. In response to these conditions, the glyph for the affected element turns blue, which is the default color, or to the color you have customized. Once a glyph has decayed to blue, the event must be acknowledged in order for the glyph to return to its original color. To get a glyph to return to its original color, you can either:

• Select the Console's View >> Event Summary option
• Highlight the name of the glyph
• Press the Drop from List button.

  Or

• From the Glyph Menu for the specific element, pull right over the Glyph State >> Normal option.

Audio Effect: Specifies an audible indicator when the specified event is reported. Press MENU on the Audio Effect abbreviated menu button to display a signal options pop-up menu--drag and release MENU on the desired signal option. Only one audio signal option can be chosen. The following options are available:

Ring Bell sounds an audible bell on the Console workstation.

Play Audio File causes the file specified in the Audio File field to be played.

Audio File: Defines the audio file to be played when the specified event is reported. Type in the file name of the audio file. The option Play Audio File must be specified in the Audio Effect field. You can use the volume function of the Audio Tool in OpenWindows 3.2 to control the sound level.

---

Note - The Console must be running (not merely displaying) on a machine with an audio port. If you are running the Console on a server but displaying the Console windows on a local workstation, the Console will attempt to play the audio file on the server.

---

Mail To: Defines one or more mail recipients to send the event report to when the specified event is reported. Type in a list of mail recipients. If there is more than one recipient, use a space between each entry.

To Program: A shell command line specifying a program or shell script to be run. Include the directory path, if necessary. A new copy of the program or shell script is forked for each event report. The event report is passed to the standard input of the program or shell script. Every active program that receives an event report keeps a file descriptor open. The default maximum number of file descriptors allowed for a single process is 64. You can increase this number up to 256 by using the limit command in the C-shell.

Stop Request: This field is new starting with version 2.3. If this field is checked, the request will be stopped when a specific event is received. This feature enables you to specify a stop request at the attribute level. You can set thresholds against different attributes in an event request and also specify that the request stop only when a specific attribute exceeds a threshold's level.

Start Request: This field is new starting with version 2.3. A new request name (including predefined requests) can be specified in this field. A different request name can be specified for each event atrtribute. Whenever an event is generated against the given event request, the reqeust specified in this field is launched automatically upon receipt of the event. This can be used in conjunction with the other event based options such as stopping the request or trying an alternate proxy.

15.2 Create Predefined

The Create Predefined option is used to build a predefined data or event request. This is a global operation, not element based. Therefore, this menu item will be dimmed if an element has been selected prior to clicking the Requests button. Refer

to the "Creating, Modifying, or Deleting Predefined Requests" section for information about using the Create Predefined option.

---

Note - The predefined data and event record names are not case sensitive, as is true with most of the Console related name fields. Since the predefined data and event records reside in the runtime database with all of the elements, it is strongly recommended that the names assigned to newly created predefined requests consist of at least two words, as is the case with the predefined data and event requests provided with this product. Otherwise, a conflict may arise between the names of hosts and the names of the predefined data and event request records, as they all must be unique.

---

15.2.1 Supplied Predefined Requests

A number of predefined data and event requests are supplied and recorded in the .SNMpredefined file in the struct directory. Upon invoking the Console, a check is made to see if the $HOME/.SNMpredefined file exists. If it does, the file is loaded into the runtime database for use by the Console. If it does not exist, the .SNMpredefined file is loaded into the runtime database. The first time the Console is invoked, the .SNMpredefined file will be loaded into the runtime database. The records in this file, along with any predefined data and event requests you modify or create after the Console is started, are stored in your $HOME/.SNMpredefined file upon exiting from the Console. You can also save the runtime database version of the predefined data and event requests records by using the File >> Save >> Predefined Requests option. Using this option, you can save these records to your $HOME/.SNMpredefined file or to any other file you desire. For information about creating, modifying, deleting, and sending predefined data and event requests, refer to the sections that follow.

15.2.2 Predefined Data Request Records

The following table lists the predefined data requests that are provided with this product, their Agent, Group, and Attribute settings, as well as a description of their intended function(s).

Table 15-1

Request Name	Agent Name	Group Name	Attributes Supported	Function
Graph Host Performance	hostperf	data	cpu% intr disk ipkts opkts	CPU utilization # of device interrupts # of disk transfers # of if input pkts # of if output pkts
Record Disk Space	diskinfo	diskSpace	all	disk space information
Record Host Performance	hostperf	data	all	Statistics of Host
Show Host Interfaces	hostif	if	all	host interface statistics
Show NFS Statistics	rpcnfs	client	all	RPC and NFS statistics
Show Path to Host	ippath	path	all	trace IP packet's path between proxy and target system
Show Routing Statistics	iproutes	routes	all	Routing statistics
Show snmp System Info	snmp	system	all	System information
Show snmp-mibII System Info	snmp-mibII	system	all	System information
Show sun-snmp System Info	sun-snmp	system	all	System information

15.2.3 Predefined Event Request Records

The following table lists the predefined event requests that are provided with this product, their Agent, Group, and Attribute settings, as well as a description of their intended function(s).

Table 15-2

Request Name	Agent Name	Group Name	Attributes Supported	Event to be Reported
When Disk is Full	diskinfo	diskSpace	capacity	Disk file system is full
If System Reboot	hostperf	data	uptime	If system reboots
When Printer Error	lpstat	status	statusCode	Line printer error
When System is not Reachable	ping	reach	reachable	System not reachable

15.2.4 Predefined Requests Management

A Predefined Data Request Template similar to the one in Figure 15-6 appears after you select the Request Type, Request Name, Agent Schema, and Group Name.

Figure 15-6

15.2.4.1 Reporting Characteristics

The fields on the left side of the Predefined Data/Event Request window specify reporting characteristics. Each of the fields isdescribed below.

Request Name: The name you are assigning to the predefined request. You must specify a name for this request. Request Names are limited to a maximum of 64 characters. If you selected a predefined data or event request, the Request Name field will contain the name of the predefined data or event request you selected.

Case Sensitivity The predefined data and event record names are case insensitive. Since the predefined data and event records reside in the runtime database with all of the elements, it is strongly recommended that the names assigned to newly created predefined requests consist of at least two words, as is the case with the predefined data and event requests provided with this product. Otherwise, a conflict may arise between the name of an element and the name of the predefined data and/or event request record being created, as they must be unique. When an attempt to create a predefined data or event request with a duplicate name of an element or an existing predefined request is made, an error message will be placed in the error reports log and the predefined request will not be created.

Agent Schema: The name of the agent schema with which the predefined data request is associated.

Group/Table: The name of the group or table associated with the agent schema with which the predefined data request is associated.

Polling Interval: Specifies the interval (in seconds) for the agent on the target system to send reports. An Interval value of 0 indicates that the agent should use its default interval. See the specific agent's man page for its default interval value.

Count: Specifies the number of times for the agent on the target system to send reports. A count of 0 specifies that the agent is to send reports until the request is stopped or killed. If a count is specified, and a Stop Date/Time is/are specified, the request stops if the specified number of reports are generated before the Stop Date/Time are reached. If the Stop Date/Time is/are reached before the specified number of reports are generated, the request stops at the specified time.

Key:

Identifies a particular row in a table (for example, ie0 or le0 in an Ethernet interface table). The use of a key is agent-specific and is indicated in the bottom left corner of the Data Request Properties window. See the man page for the particular agent for information regarding keys. If no key is specified, the entire table is returned.

Options: Specifies any options (such as arguments) that the agent expects. To specify Options, type in an option string. For example, with SNMP requests you can specify an SNMP read-community name. The information that you can specify in the Options field is agent-specific--not all agents accept options. See the man page for the particular agent for information regarding options.

Restart: Specifies whether the agent should attempt to restart the request if the system on which the agent is running reboots, the agent terminates unexpectedly, or the Console itself is restarted. If Restart is off (no check mark appears in the accompanying box), the request is discarded if the agent fails or if you quit the Console. If Restart is on (a check mark appears in the accompanying box), the request is restarted. The default setting of this field is determined by the Restart Request upon Agent Failure setting in the Console Properties Requests category. (Refer to Chapter 17, "Props Menu," under "Requests" for more information.) Click SELECT on the box next to this field to toggle the check mark on or off.

Defer Reports: Specifies whether or not the agent should cache reports and send them to the Console only when asked to. If Defer Reports is on (a check mark appears in the accompanying box), the agent is directed to collect the statistics, but send them to the Console only when directed. Defer Reports tells the agent to cache the last 32 reports. If 32 reports are cached, or if the agent runs out of memory, the oldest report is deleted when a new report is cached. You should not specify Defer Reports for agents that return a large amount of data (for example, a routing table).

In many cases an agent collects information useful for debugging problems. This information might not be of interest in your normal daily operation. Furthermore, if a request were started before the error occurred, data reports will continually stream back to the Console causing unnecessary network traffic and increased CPU load. If, on the other hand, the request was started after the error happened, the debugging information would not have been collected. By setting Deferred Sending on, reports are held in the agent's system until you need to ask for them.

The data request must be active for Defer Reports to work properly; that is, issue the request with a long Interval and high Count. Refer to Chapter 14, "Console," under "Viewing and Modifying Requests" for information on how to obtain deferred reports.

On Completion: Specifies whether the request should be deleted or saved upon completion. To specify that the request be saved, drag MENU over the On Completion abbreviated menu button--release MENU over Save Request. If you choose to save the request, the request glyph is dimmed after the request has been completed but remains in the view of the target element. You can examine, modify, or restart the saved request.

If you select Delete Request On Completion, then stopping the request is the same as killing it. (Refer to Chapter 14, "Console," under "Viewing and Modifying Requests" for more information.)

Log to File: Specifies the file name where reports are to be stored. If you specify a file name with no path, the SunNet Manager Console uses the current directory. If you fully qualify the file name and the left-most characters scroll left, they are not lost.

---

Note - Starting with version 2.3, there is a new flag called get-requested-attribute-only. By default it is set to true. Only the requested attributes will be retrieved. When this flag is set to false, all attributes are retrieved.

---

To Program: A shell command line specifying a program or shell script to be run. Include the directory path, if necessary. Data reports are passed to the standard input of the program or shell script. Every active program to which data reports are sent keeps a file descriptor open. The default maximum number of file descriptors allowed for a single process is 64. You can increase this number up to 256 by using the limit command in the C-shell.

Schedule: Set this field to "On" in order to activate the scheduling options below.

Date Format: Select one of the four formats in which you will enter the start and stop dates.

Start Date: When you enter a date here, and click the Start button, the request will start on the specified date.

Stop Date: When you enter a date here, the request will stop on the specified date.

Start Time: When you enter a time here, and click the Start button, the request will start at the specified time.

Stop Time: When you enter a time here, the request will stop at the specified time.

15.2.4.2 Selecting Attributes

The fields in the right portion of the Predefined Data Request window are used to specify attributes.

Selected Attributes: A scrolling list that contains those attributes for which you are requesting data. You choose an attribute and how you want the attribute data displayed with the fields beneath the Available Attribute values scrolling list (described below). When you click SELECT on the Add button at the right of the window, the attribute is added to the Selected Attributes values scrolling list.

Following is a description of the Available Attributes and attribute display fields:

Available Attributes: Specifies the attribute you want the agent to return data on. When the Predefined Data Request window is first displayed, the Available Attributes field displays the name of the first attribute in the group/table from the agent schema file. To specify a particular Available Attribute, press MENU over the Available Attributes abbreviated menu button and release MENU on the desired entry. When an attribute is selected, a description is displayed in the lower-right footer.

---

Note - If no attribute is specified, all attributes for the selected group or table are written to the Data Reports log. For tables, the values of the keys are also returned. However, if you specify a particular table attribute, the key values are not returned.

---

Data Log: Specifies whether or not the attribute data should be written in the Data Reports Log. To specify that the data not be written in the Data Reports log, drag MENU over the Data Log abbreviated menu button--release MENU over False.

Indicator: Specifies whether or not the attribute data should be displayed in an Indicator. An Indicator shows the last reported value for a particular attribute. Refer to Chapter 16, "View Reports," under "Indicators" for more information.

To specify the Indicator display option, click SELECT on the Indicator box.

Strip Chart: Specifies whether or not the attribute data should be displayed in a Strip Chart. A Strip Chart contains an auto-scaled strip chart of values for an attribute. Refer to the section on "Strip Charts" for more information.

To specify the Strip Chart display option, drag MENU over the Strip Chart abbreviated menu button--release MENU over either Absolute Values (chart the received values) or Delta Values (chart the differences between received values).

Graph Tool: Specifies whether or not the attribute data should be displayed by the Grapher. The Graph Tool, also known as the Results Grapher, is an application that allows the display of data received by the Console. Only data of types integer, float, counter, gauge, timestamp, or UNIX time can be plotted. Refer to Chapter 21, "Results Grapher," for more information about the Graph Tool. To specify the Graph Tool display option, drag MENU over the Graph Tool abbreviated menu button--release MENU over either Absolute Values (graph the received values) or Delta Values (graph the differences between received values).

15.2.4.3 Adding Attributes

The buttons to the right of the Selected Attributes field in the Predefined Data Request window allow you to add, change, and delete attribute selections in the Selected Attributes values scrolling list. The buttons are described below:

• Add tells the request manager to add the Available Attribute selected to the Selected Attributes scrolling list.
• Change tells the request manager to apply the changes made to the attribute setting(s).
• Delete tells the request manager to remove the Available Attribute selected from the Selected Attributes scrolling list.

An entry in the scrolling list may be selected at any time by pointing the mouse pointer at the entry and clicking the SELECT button. This updates the window to the settings for the selected attribute. An entry may be deleted by selecting it and clicking on the Delete button.

15.2.5 Define and Reset Data Record Fields

Use the buttons at the bottom of the Predefined Data Request window to define and reset all the data record fields for the predefined data request, as well as to delete the record from the runtime database. The buttons are described below:

• Define creates or updates the predefined data request runtime database record to the values specified in the Predefined Data Request Window.
• Reset returns the request specifications back to the originally applied selections.
• Undefine deletes the selected predefined data request from the runtime database record.

15.2.6 Predefined Event Request Management

When you specify a predefined Event Request, the window in Figure 15-7 appears after you select the Request Type, Request Name, Agent Schema, and Group Name in the Request Builder window.

Figure 15-7

Descriptions of the reporting characteristics fields are provided below:

Request Name: The optional name you wish to assign to the request. This allows you to assign a recognizable name to a request. The request manager assigns a request name, if one is not specified, using the following format:

<agent>.<group>.<number> (for example, hostperf.data.0)

Agent Schema: The file containing the attribute group/table.

Group/Table: the set of attribute values for which you are requesting data.

Polling Interval: Specifies the interval (in seconds) for the agent on the target system to send reports. An Interval value of 0 indicates that the agent should use its default interval. See the agent's man page for its default interval.

Count: Specifies the number of times for the agent on the target system is to send reports. A count of 0 specifies that the agent is to send reports until the request is stopped or killed. If a count is specified, and a Stop Date/Time is/are specified, the request stops if the specified number of reports are generated before the Stop Date/Time are reached. If the Stop Date/Time is/are reached before the specified number of reports are generated, the request stops at the specified time.

Key:

Identifies a particular row in a table (for example, ie0 or le0 in an Ethernet interface table). The use of a key is agent-specific and is indicated in the bottom left corner of the Data Request Properties window. See the man page for the particular agent for information regarding keys. If no key is specified, the entire table is returned.

Options: Specifies any options (such as arguments) that the agent expects. To specify Options, type in an option string. For example, with SNMP requests you can specify an SNMP read-community name. The information that you can specify in the Options field is agent-specific--not all agents accept options. See the man page for the particular agent for information regarding options.

Restart: Specifies whether the agent should attempt to restart the request if the system on which the agent is running reboots, the agent terminates unexpectedly, or the Console itself is restarted. If Restart is off (no check mark appears in the accompanying box), the request is discarded if the agent fails or if you quit the Console. If Restart is on (a check mark appears in the accompanying box), the request is restarted. The default setting of this field is determined by the Restart Request upon Agent Failure setting in the Console Properties Requests category. Click SELECT on the box next to this field to toggle the check mark on or off.

Send Once If Send Once has been selected (a check mark appears in the accompanying box), the request is terminated after the Console receives the first event report. Click SELECT on the Send Once box to toggle the check mark on or off.

Defer Reports: Specifies whether or not the agent should cache reports and send them to the Console only when asked to. If Defer Reports is on (a check mark appears in the accompanying box), the agent is directed to collect the statistics, but send them to the Console only when directed. Defer Reports tells the agent to cache the last 32 reports. If 32 reports are cached, or if the agent runs out of memory, the oldest report is deleted when a new report is cached. You should not specify Defer Reports for agents that return a large amount of data (for example, a routing table).

In many cases an agent collects information useful for debugging problems. This information might not be of interest in your normal daily operation. Furthermore, if a request were started before the error occurred, data reports will continually stream back to the Console causing unnecessary network traffic and increased CPU load. If, on the other hand, the request was started after the error happened, the debugging information would not have been collected. By setting Deferred Sending on, reports are held in the agent's system until you need to ask for them.

The data request must be active for Defer Reports to work properly; that is, issue the request with a long Interval and high Count. Refer to the "Viewing and Modifying Requests" section for more information on how to obtain deferred reports.

On Completion: Specifies whether the request should be deleted or saved upon completion. To specify that the request be saved, drag MENU over the On Completion abbreviated menu button--release MENU over Save Request. If you choose to save the request, the request glyph is dimmed after the request has been completed but remains in the view of the target element. You can examine, modify, or restart the saved request.

If you choose Delete Request on Completion, stopping the request is the same as killing it. (Refer to the "Viewing and Modifying Requests" section for more information.)

Schedule: Set this field to "On" in order to activate the scheduling options below.

Date Format: Select one of the four formats in which you will enter the start and stop dates.

Start Date: When you enter a date here, and click the Start button, the request will start on the specified date.

Stop Date: When you enter a date here, the request will stop on the specified date.

Start Time: When you enter a time here, and click the Start button, the request will start at the specified time.

Stop Time: When you enter a time here, the request will stop at the specified time.

Important Information About Polling Interval and Count Fields For predefined event requests, these fields specify when the agent is to send a report. A report is forwarded to the Console system only if it has been determined that an event has occurred. For agents that are shipped with the product, the value reported for an attribute is the value noted at the reporting interval. Thus, it is possible for event conditions to occur between reporting intervals and not cause an event report.

If a count is specified, and a Stop Date/Time is/are specified, the request stops if the specified number of reports are generated before the Stop Date/Time are reached. If the Stop Date/Time is/are reached before the specified number of reports are generated, the request stops at the specified time.

15.2.6.1 Selecting Attributes

Use the fields in the right portion of the Predefine Event Request properties window to specify attributes.

Selected Attributes: A scrolling list that contains those attributes for which you are requesting event information. You specify attributes, event thresholds, and how you want the event signalled with the fields under the Selected Attributes values scrolling list. When you click SELECT on the Add button to the right of the Selected Attributes window, the attribute is added to the Selected Attributes values scrolling list.

Following is a description of the available attributes, event threshold, signal options, receiver, and priority fields:

Available Attributes: Specifies the attributes that you want to use to specify an event. When the window is first displayed, the Available Attributes field displays the name of the first attribute in the group/table from the agent schema file. To specify an attribute, press MENU on the Available Attributes field and release the mouse button on the desired entry. When an attribute is selected, a description is displayed in the lower-right footer of the window.

Relation1, Relation2: Specify threshold conditions for reporting an event. You can specify up to two threshold relational operators; the event is reported if either of the two threshold conditions are met. To set the threshold relational operator(s) for

Relation1 or Relation2, drag MENU over the Relation abbreviated menu button to display the following list of relational operators in a pop-up menu--release MENU over the desired relational operator.

Threshold Not Set means you have not set a threshold for this attribute. This is the default choice.

Equal To tells the agent to report an event if the attribute value equals "Thresholdn."

Not Equal To tells the agent to report an event if the attribute value does not equal "Thresholdn."

Less Than tells the agent to report an event if the attribute value is less than "Thresholdn."

Less Than Or Equal To tells the agent to report an event if the attribute value is less than or equal to "Thresholdn."

Greater Than tells the agent to report an event if the attribute value is greater than "Thresholdn."

Greater Than Or Equal To tells the agent to report an event if the attribute value is greater than or equal to "Thresholdn."

Changed tells the agent to report an event if the attribute value differs from the last sampled value.

Increased By tells the agent to report an event if the attribute value has increased by "Thresholdn" compared to the last sampled value.

Decreased By tells the agent to report an event if the attribute value has decreased by "Thresholdn" compared to the last sampled value.

Increased By More Than tells the agent to report an event if the attribute value has increased by more than "Thresholdn" compared to the last sampled value.

Increased By Less Than tells the agent to report an event if the attribute value has increased by less than "Thresholdn" compared to the last sampled value.

Decreased By More Than tells the agent to report an event if the attribute value has decreased by more than "Thresholdn" compared to the last sampled value.

Decreased By Less Than tells the agent to report an event if the attribute

value has decreased by less than "Thresholdn" compared to the last sampled value.

---

Note - For the Changed, Increased By, Decreased By, Increased By More Than, Increased By Less Than, Decreased By More Than, and Decreased By Less Than operators, the Count field of the report characteristics must not be '1.' A Key must be supplied if a table of attributes is selected.

---

Threshold1, Threshold2: Specify the threshold value if the selected operator is other than Threshold Not Set, or Changed.

Priority: Specifies the priority of the request. Click SELECT on the desired priority button (Low, Medium, or High) for the request.

Glyph Effect: Specifies a visible indicator when the specified event is reported. Press MENU on the Glyph Effect abbreviated menu button to display a signal options pop-up menu. Release MENU on the signal option you want. You can choose only one visual signal option. In order to have the "decay" feature in effect, you must select the Priority by Color option.

The following options are available: Blink Glyph

Blinks the glyph of the element for which an event has been reported.

Dim Glyph

Dims the glyph of the element for which an event has been reported.

Priority by Color

Causes the glyph to change color, based on the priority of the reported event. The defaults are:

• Red = high priority
• Orange = medium priority
• Yellow = low priority
• Blue = decay

Starting with version 2.3, you can customize colors, including the "decay" color. See Chapter 4, "Requesting Data," or Chapter 5, "Specifying Event Requests," for procedures to customize Color by Priority.

If multiple reports are received for a system, the highest priority is used. In association with the Priority by Color option is the "decay" feature. This feature pertains to events and traps that have reached a threshold and then fallen below it, or that have had an event or trap stop being reported. In response to these conditions, the glyph for the affected element turns blue, which is the default color, or to the color you have customized. Once a glyph has decayed to blue, the event must be acknowledged in order for the glyph to return to its original color. To return a glyph to its original color, you can either:

• Select the Console's View >> Event Summary option
• Highlight the name of the glyph
• Press the Drop from List button.

  Or

• From the Glyph Menu for the specific element, pull right over the Glyph State >> Normal option.

Pending State Starting with version 2.3, you can place an object in pending state. In this state, the color of the glyph is dimmed, and all outstanding events are cleared. New events/traps do not change the color of the glyph nor do they propagate the effect of the trap/event to the parent object. A parent object in pending state is not affected by a change in state on any children.

Audio Effect: Specifies an audible indicator when the specified event is reported. Press MENU on the Audio Effect abbreviated menu button to display a signal options pop-up menu--drag and release MENU on the desired signal option. Only one audio signal option can be chosen. The following options are available:

Ring Bell sounds an audible bell on the Console workstation.

Play Audio File causes the file specified in the Audio File field to be played.

Audio File: Defines the audio file to be played when the specified event is reported. Type in the file name of the audio file. The option Play Audio File must be specified in the Audio Effect field. You can use the volume function of the Audio Tool in OpenWindows 3.2 to control the sound level.

---

Note - The Console must be running (not merely displaying) on a machine with an audio port. If you are running the Console on a server but displaying the Console windows on a local workstation, the Console will attempt to play the audio file on the server.

---

Mail To: Defines one or more mail recipients to send the event report to when the specified event is reported. Type in a list of mail recipients. If there is more than one recipient, use a space between each entry.

To Program: A shell command line specifying a program or shell script to be run. Include the directory path, if necessary. A new copy of the program or shell script is forked for each event report. The event report is passed to the standard input of the program or shell script. Every active program that receives an event report keeps a file descriptor open. The default maximum number of file descriptors allowed for a single process is 64. You can increase this number up to 256 by using the limit command in the C-shell.

Stop Request: This field is new starting with version 2.3. If this field is checked, the request will be launched one time. If this field is checked, it will override any number specified in the Count field.

Start Request: This field is new starting with version 2.3. This field defines a child request that is to be launched when the parent request in the Request Name field is launched. When this sequence is launched, the child request becomes a parent request enabling you to specify another child request, and so forth. In this way, you can launch as many requests as you choose.

15.2.6.2 Adding Attributes

The buttons to the right of the Selected Attributes field in the Predefined Event Request window allow you to add, change, and delete attribute selections in the Selected Attributes values scrolling list. The buttons are described below:

• Add tells the request manager to add the Available Attribute selected to the Selected Attributes scrolling list.
• Change tells the request manager to apply the changes made to the attribute setting(s).
• Delete tells the request manager to remove the selected attribute from the Selected Attributes scrolling list.

An entry in the scrolling list may be selected at any time by pointing the mouse pointer at the entry and clicking the SELECT button. This updates the window to the settings for the selected attribute. An entry may be deleted by selecting it and clicking on the Delete button.

15.2.6.3 Define and Reset Event Record Fields

The buttons at the bottom of the Predefined Event Request window allow you to define and reset all of the event record fields for the predefined event request, as well as delete the record from the runtime database. The buttons are described below:

• Define creates or updates the predefined event request runtime database record to the values specified in the Predefined Event Request window.
• Reset returns the request specifications back to the originally applied selections.
• Undefine deletes the selected predefined event request from the runtime database record.

15.3 Requests Summary

To get a summary of the data and event requests, click SELECT on the Requests Summary button. The window shown in Figure 15-8 on page 15-41 appears. For a description of the fields in the Requests Summary Window, refer to Chapter 16, "View Reports."

To display the Requests Summary window, press MENU over the Console Requests >> Requests Summary option and release.

Figure 15-8

The following information is displayed in the Requests Summary window:

• Type defines the request as one of the following:

  · D: data request

  · E: event request

• EA: event request launched by the Automatic Node Management feature of the Console

• Request Name lists the name you have assigned to the request or, if you have not assigned a name, a name of the format <agent>.<group>.<number>, for example, ping.reach.4.
• Target Host is the name of the target element for the request.
• Request Timestamp is the date that the request was started or restarted. Dates are only displayed for requests that have been started at least once.
• Request State is one of the following:

  · Active

  · Stopped

  · Awaiting stop

  · Stopping

  · Awaiting activation

  · Being activated

  · Scheduled for later

The footer of the window indicates the total number of requests (whether active or stopped) and the number of active requests.

Using the buttons at the top of the window, you can restart, stop, sort, or kill requests. The operation applies to all requests that you have selected (highlighted). To select requests, press MENU in the scrolling list area of the window to bring up the Select menu. The Select menu is shown in Figure 15-9.

If the On Completion field in the properties of a request is set to Delete Request (rather than the default Save Request), then stopping that request is the same as killing the request. A description of the fields in requests can be found in Section 15.1.0.1, "Data Request Template.'

Figure 15-9

If you choose Select By Request Name, Select By Target Host, Select by Request Type, or Select By View, a pop-up window is displayed where you can specify the request name, target element, request type, or view name. Wild card characters (* and ?) may be used when specifying the request name, target element, or request type. View name cannot be specified with wild card characters.

---

Note - If an element is selected (highlighted) in a Console view, the element name appears in the target element or view name pop-up window.

---

Use the Sort button menu to sort the displayed requests by request name, target host, request timestamp, request type, or request state. Sorting by timestamp displays the requests from earliest to latest start times. Sorting by request state displays requests according to the following order of request states:

1. Stopped

2. Awaiting activation

3. Being activated

4. Active

5. Awaiting stop

6. Stopping

7. Scheduled for later

All other sorting is done in alphabetical order.

Use the Props button to display the Request Properties window. You can then modify any of the properties of the request. If more than one request is selected when you click SELECT on the Props button, only the Properties window for the first selected request is displayed.

15.4 Request Glyph Popup Menu

Requests are represented by glyphs in the subview of the target element. To display the request glyph view, you can either double-click SELECT on the target element or choose the element Glyph >> Show Subview menu option.

---

Note - Held requests or requests that are completed and saved are displayed as dimmed.

---

There is a pop-up menu associated with each request glyph. To display the request glyph's menu, move the mouse pointer over a the request glyph and press MENU. This is shown in Figure 15-10.

Figure 15-10

Following is a description of the options in the Request Glyph Menu:

• Properties shows the properties of a particular request. Figure 15-11 is an example.

Figure 15-11

You can modify the request in several ways. For example, you can choose a different attribute, change the report frequency, stop an active request, or start a request that was placed on hold. When you modify a request, you are actually changing the specifications for that request, not launching a new one. The request manager stops the original request and restarts it with the new specifications.

Clicking the Stop button stops the request and saves it only if you have previously specified that the request be saved upon completion. Otherwise, the Stop button effectively kills the request. Use the Restart button to launch held or saved requests. If the request has already been started, Restart restarts the modified request with the new attribute specification and report characteristics.

• Kill allows you to kill a request that you no longer wish to run. Kill deletes a request even if you have previously set the Upon Completion request properties field to Save Request.

---

Note - Quitting the Console causes any active requests to be discarded unless the Restart field is on (a check mark appears in the accompanying box) or the On Completion field is set to Save Request.

---

• Send Deferred indicates you are now ready to receive deferred reports. The agent system now sends the deferred reports (up to 32) to the Console. Refer to the Defer Reports discussion in the "Reporting Characteristics" section of Chapter 20, "Browser," for a description of deferred reports.