response()

Display a dialog on the PATROL Console. You can create a dialog box containing many different elements. The following table lists the elements that are available for response() function dialog boxes:

Syntax

Parameter

Description

The response() function defines a PATROL dialog box that is displayed by a PATROL console. 

The PATROL Console will display multiple response() function dialogs as it receives them from the PATROL Agent. There is no restriction on the number of response() function dialogs that the PATROL Console is permitted to display at any given time. The number of dialogs displayed is controlled solely by the number of PSL processes executing within the PATROL Agent  that are making response() function calls. 

When you create a dialog box with the response function, you must first define the preferences of the dialog box and then define the elements that are contained in the dialog box.

Preferences of the Dialog Box

The first three parameters supplied to the response() function define the general preferences of the dialog box:

• title

• timeout

• preferences (For more information on response() function dialog box elements, see response() Function Preferences.)

The following response() function call produces a dialog box with the title "Default" using all the default values: 

The following figure shows a response dialog produced with all default values that contains no GUI elements: 
Default response() Function Dialog Box 

Elements of the Dialog Box

After you define the dialog box, you define the elements that are contained in the dialog box with the element definitions. (For more information on response() function dialog box elements, see response() Function Elements.)

Design Considerations of a Dialog Box

While you are working on the design of a dialog box, you should consider the following items:

• amount of screen space

• purpose of the dialog box

• control elements to use

• logical order for the control elements

• how to group or separate the control elements

response() function and the PATROL Event Manager

Calls to the response() function are integrated with events processed by the PATROL Event Manager. The current status of a response() function event, whether Open, Acknowledged, or Closed, is shown by the Event Manager display. 

You can acknowledge a response() function event in either of the following ways:

• clicking on Acknowledge in the response() function event popup
• selecting the event and clicking on Acknowledge in the Event Manager display

In either case, assuming acknowledgment succeeds, the status change appears in the following places:

• Event Manager display
• response() function requests list window
• response() function dialog window

In the case of the response() function dialog window, the status is mirrored in the sensitivity of the response() function event popup, corresponding to the response() function event, rather than actually being displayed. This consistency across the three locations should apply to any status change in the response() function event. 

A response() function event popup can be displayed from within the Event Manager by selecting the event and clicking on Answer.

Return Values for the response() Function

The response() function return value is a PSL list. (Each item in a PSL list is separated by a new-line, \n, character.) The first item in the list is the status of the response() function, and the following items in the list are the return values of the dialog-box elements. The return value for a response() function dialog box takes the following form: 

The status value indicates if Cancel (0) or OK (1) was selected by the user on the dialog box. Regardless of which button is selected by the user, the response() function returns a full list of values selected by the user on the dialog box. 

The order of the return values is the order in which the elements are defined in the response() function. The following elements do not return values (not even new-line place holders):

• labels (element types 0 and 1)
• separators (element types 4 and 5)
• frames (element type 14)
• row and column compound elements (element types 15 and 16)
• icons (element type 17)

response() Function Timeout Return Values

When the PATROL Console does not acknowledge a response() function dialog box within the timeout period, aresponse() function timeout occurs. After the timeout period, the PATROL Agent wakes the process that called theresponse() function, returns the empty string as the response() function return value, and sets the PSL variable errno to 86 (E_PSL_RESPONSE_TIMEOUT).

Return Values for response() Function Elements

The following table lists the elements of the response() function that return values and describes the type of value returned by each element: 

 Return Values for response() Function Elements 

Dynamic response() Function Dialog Boxes

The dynamic response() function is an extension of the standard response() function that allows dynamic updates to the dialog box that is created on the PATROL Console. 

The dynamic response( ) function is implemented using the D preference of the response() function. (See response() Function Preferences.) When D=1, the response() function creates a dynamic dialog box and returns the rid for it. 

The rid identifier is used to perform the following tasks:

• response() function calls to update the dialog with new data
• response_get_value() calls to retrieve the status of the dialog box elements

Specifying a Dynamic response() Function Dialog Box

To create a dynamic response() function dialog box, call the response() function with the D=1 preference. The return value from the call is the rid: 

Subsequent calls to update the dialog box with new values use the rid in place of the dialog box title: 

If the subsequent response() function is successful, it returns 1 and sets the PSL variable errno = 0 (E_PSL_NO_ERROR). If the rid is invalid or no longer exists, the subsequent response() function returns 0 but does not set the PSL variable errno and does not produce a message. 

If the rid is so badly defined in a subsequent response() function that it is not recognizable as an rid, the response()function will assume it is a title and will create a dialog box with that title.

Updating a Dynamic response() Function Dialog Box

Once a dynamic dialog box has been created and the rid returned, subsequent response( rid,...) function calls have the following features:

• Each returns 1 if successful or 0 otherwise.
• All updates to the elements of the dynamic dialog box are immediately visible to the user.
• All updates overwrite any changes the user has made to the dynamic dialog box. The updated dynamic dialog box reflects the element definitions in the response() function call.
• If an element on the dynamic dialog box was modified by a user, and a response() function call to the dialog box did not modify the element, then the user modification will remain unchanged after the response() function is processed.

Along with these features, subsequent response ( rid,...) function calls to a dynamic dialog box have the following restrictions:

• You must match the arguments in subsequent response() function calls with the arguments in the original dynamic response function call. That is, if you want to update the nth element from the original response() function definition, it must be the nth element in the subsequent response ( rid,...) call.
• The response() function will not allow you to replace one element type with another. The response() function will ignore any and all element definitions in a subsequent response() function call that do not match the original call.
• The response() function cannot be used to change the structure of a dynamic dialog box, the number of elements in the dialog box, or their order. The response() function can only change the values of certain elements in the dialog box.
• The response() function cannot be used to change the preferences of a dynamic dialog box such as the background color or the label of the OK or Cancel button.
• The response() function will accept empty strings ( "" ) as place holders and to represent element definitions that you do not wish to modify. (Use the empty strings: repeatedly passing the original element definitions in subsequentresponse() function calls is inefficient because the response() function will interpret and replace the value each time even though it is unnecessary.)

The following table lists those response() function elements that can and cannot be updated with new values using a subsequent response() function call. Elements can be updated in either a dialog box or its popups. (The popup element cannot be updated, but the elements defined within it can be updated.

 Elements of a Dynamic response() Function 

Getting the Element Values of a Dynamic response() Function

The return values of the elements for a dynamic response() function dialog box are accessed using the response_get_value() function. 

The response_get_value() function returns the most recent return value for the response() function dialog box identified its rid. The response_get_value() function can get the values in one of the following ways:

• block the current PSL process and wait for a return value from the response() function dialog box
• poll a queue of return values and retrieve the most recent return value for response() dialog box identified by rid

For more information, see response_get_value().

response() Function Preferences

The preferences parameter of the response() function is a list of preferences that control how the response() function dialog box will look and behave. 

Although the individual preference parameters are optional, the preferences string is required. Specify the NULL string " "to choose all the preference parameter defaults.

Preferences Format

You can specify the preferences using one of three formats:

• PSL list operator format
• PSL list internal representation (new-line separated)
• PSL character string format (comma separated)

PSL List Operator Format 

The PSL list operator format uses the list operator to create a list of preferences. See the PATROL Script Language Reference Manual Volume 1--PSL Essentials for information about string operators. The PSL list operator format is less efficient than either the PSL list internal representation or the character string representation.

The following example shows the response() function preferences in PSL list operator format: 

PSL List Internal Representation (New-Line Separated)

The PSL list internal representation uses the internal PSL representation of a list to define the response() function preferences. A PSL list is a character string enclosed in quotes with each item in the list separated by a new-line, \n, character. The following example shows the response() function preferences in PSL list internal representation format: 

Character String Format (Comma Separated)

The PSL character string format is similar to the PSL list internal representation, but instead of each item in the list being separated by a new-line, \n, character, the character string format uses a comma. The following example shows the response() function preferences in PSL character string format: 

Preferences Parameters

The following table describes the response() function preferences parameters.

 response() Function Preferences 

Default 
dynamic height and width selected by the window manager 
The height and width parameters do not apply to PATROL Consoles running on Microsoft Windows. When a PATROL Console on Microsoft Windows displays a response() function dialog box, the dialog box is dynamically sized. 
If you specify a height and width on platforms that support the height and width values, scroll bars will appear if the dialog is larger than the window size. |

Preferences Example

The following examples show the valid formats for specifying the response() function preferences:

PSL List Internal Representation

PSL List Operator Format

Character String Format

response() Function Elements

The element parameter of the response() function is one or more lists that define the elements included in the response() function dialog box. Each element list is separated by a comma.  An element is any control, such as a button or text field, that is used in a dialog box. You can include up to 100 control elements in a dialog box.

Types of Elements

Every element has a specific purpose, so it is important for you to understand how each element functions when you are designing a dialog box. The following control element types are available:

• radio boxes (horizontal and vertical)
• check boxes (horizontal and vertical)
• text fields
• separator (dummy) fields
• sliding scales (horizontal and vertical)
• option menus
• labels and centered labels
• single-select and multiple-select scrolled lists
• icons
• toggle buttons
• row alignment compound element
• column alignment compound element
• frame enclosure compound element
• popup compound element
• time spinner button

Control elements can be classified as either simple control elements or compound control elements.

Simple Elements

Simple control elements are used for entering data, or as simple design elements such as icons, text labels, or separators. The following table lists the simple control elements.

 Simple Control Elements 

Compound Elements

Compound control elements are containers for other elements and can contain simple elements or other compound elements. The response() function default action is to build a dialog box and place all specified GUI elements in a vertical column in argument order. The response() function syntax provides compound GUI elements to provide flexibility in constructing dialogs with nested GUI elements. The following compound GUI elements are available:

• rows
• columns
• frames
• popup dialog boxes

By default, every definition that follows a compound-element definition is part of the compound element. The compound-element definition includes a value that specifies the number of subsequent element definitions that belong to the compound element. The response() function reads the value and processes the correct number of elements into the compound element. Any remaining element definitions are processed for the parent of the compound element. The following table lists the compound elements.

 Compound Control Elements 

Symbolic Names of Elements

Each response() function element is identified by its type. The type is either the symbolic name (a PSL constant) of the control or the numeric identifier of the control. 

When you define a response() function element you can use either the number or the symbolic name to describe the graphical elements you want to display. Whenever a built-in constant is used in a PSL script, its value is substituted by the compiler with the assigned numeric value. For example, consider the following function call:

When the PSL compiler processes this function call, the numeric value 8 is substituted for the PSL constant R_CHECK_HORIZ. 

The following table lists the numeric value, symbolic name, description, and reference page for each control that is supported by the response() function.

Nested Compound Elements

The response() function permits nesting of compound elements to a maximum of 50 levels with no limit on the number of elements permitted within a level. 

When one compound element is nested within another, the number of elements specified for the outer does not include those specified for the inner. The response() function processes nested compound elements in the following order:

• reads and processes elements in the outer compound element until it encounters the definition of the inner
• freezes the count for the outer compound element after counting the inner definition and begins a new count for the inner
• processes elements for the inner compound until it achieves the correct number of elements
• resumes processing elements for the outer compound element

Elements Format

You can specify each response() function element list using one of following formats.

• PSL list operator format
• PSL list internal representation (new-line separated)

PSL List Operator Format

The PSL list operator format uses the list operator to create a list of values that defines the element. (See the PATROL Script Language Reference Manual Volume 1--PSL Essentials for information about string operators.) The following example shows how an element is defined using the PSL list operator format:

PSL List Internal Representation (New-Line Separated)

The PSL list internal representation uses the internal PSL representation of a list to define the response() function elements. A PSL list is a character string enclosed in quotes with each item in the list separated by a new-line, \n, character. The following example shows how an element is defined using the PSL list internal representation format:

Defining response() Function Elements

This section describes the elements listed in the following table. 

 response() Function Elements 

Text Fields

Use text fields to allow a user to type free-form text. You can leave the text field empty for the user to fill in, or you can include default text. The following figure shows a typical text field. 
Text Field Example 

Element Format

Return Value

The response() function return value method prevents the user from entering a new-line character in a text field request. The user can only enter one line of text. The text field element returns a single line of text terminated with a new-line character and containing no internal new-line characters:

Example

The following are examples of the text field definition using the PSL list internal representation and PSL list operator format. The definition creates user name and password boxes. The password box blanks entered text.

The following examples show what happens when you forget to omit the label when type =11. In the first line, "LABEL" appears in the text field instead of the default text, and the default text is ignored. In the second line, the default text appears correctly in the text field.

Radio Buttons

Use radio buttons to indicate a list of items that are mutually exclusive. Radio buttons require that exactly one of the radio buttons be ON and all the others be OFF. If you do not specify the initial state of the radio buttons, the response() function sets the first radio button ON and all the others to OFF by default. If you have numerous items in a list, and the dialog box space is limited, consider using an option menu. The following figure shows a typical radio button: 

Radio Button Example 

Element Format

Return Value

The radio buttons are numbered in order of their definition in the response() function, beginning with number 1. The return value is an integer value that indicates the number of the radio button that is ON. 

Example

In both of the following examples of the radio button definition, the second radio button, Windows, is checked by default:

Check Boxes

Use check boxes when the user may select one or more items from a list of items that are not mutually exclusive or when the user is not required to select any items from the list. You may specify one or more default check boxes, but you are not required to specify any defaults. If you do not specify the initial state of the check boxes, the response() function sets all boxes UNCHECKED. 

The check box field definition permits a maximum of 31 label definitions. If you require more than 31 definitions in the check box, you should create a multiple-select scrolled list. For more information on scrolled lists, see Lists. 

The handling of check box return values can be aided by the PSL set functions, especially the subset() function, which can be used to determine whether a given check box number is set in the return value. The following figure shows a typical check box: 

Check Box Example 

Element Format

Return Value

The check boxes return a space-separated row of integer values identifying the check boxes that are CHECKED(1). The cstaten values are listed in order of the check box definitions in the response() function. If no check boxes are selected, the return value is 0.

Example

The following are examples of a check box definition that creates a vertical list of three check boxes titled Yes, No, and Maybe. The Maybe check box is checked, and the others are unchecked.

or

Toggle Buttons

Use a toggle button when you have one option that may or may not be selected by a user. A toggle button is a single check box. The following figure shows a typical toggle button: 

Toggle Button Example 

Element Format

Return Value

The toggle button returns a binary value indicating that the toggle switch is ON (1) or OFF (0).

Example

The following is an example of the toggle button definition using the PSL list internal representation and PSL list operator format.

Lists

Use a list when you have a listing of items from which the user can select. You can set up a list to be a single-choice selection list or a multiple-choice selection list:

• Use a single-choice selection list when you want the user to select one option only.
• Use a multiple-choice selection list when you want the user to select more than one option.

You can set one default in a single-selection list, one or more defaults in a multiple-selection list, or no defaults at all. You cannot have more than 2000 list items. 

The handling of multiple-selection, scrolled-list return values can be aided by the PSL set functions, especially the subset()function, which can be used to determine whether a given list-element number is set in the return value. The following figure shows both a single- and multiple-selection list: 

Selection List Example 

Element Format

Return Value

The scrolled list entries are numbered in order of their definition in the response() function, beginning with number 1. Each scrolled list returns one or more values in a space-separated list of values ( mscrolln) indicating the selected entries. If no scroll list entry is selected, the return value is 0.

Example

The following are examples of the scrolled list definition that create four scrolled lists: single-select with default, multiple select with default, single-select without default, multiple-select without default:

Option Menus

Use an option menu to indicate a list of mutually exclusive items if you do not have enough space in the dialog box for a single-selection list. Users can select the option they want by clicking the drop-down arrow or by typing the first few characters of the option's name. The following figure shows a typical option menu: 

Option Menu Example 

Element Format

Return Value

The options are numbered in order of their definition in the response function, beginning with number 1. Each option menu returns an integer value indicating the option number selected from the option menu.

Example

The following example creates an option menu with the label Time and the choices Month, Day, Year, Hour, and Minute, defaulting to Day.

Clickers

Use a clicker if you want the user to select from a set of integer values. The user selects the appropriate value by using the up and down arrows to click through sequential values. If you are displaying the dialog box on the PATROL Console for Unix, two digits are displayed. On the PATROL Console for Windows, three digits are displayed. The following figure shows a typical clicker: 

Clicker Example 

Element Format

Return Value

The clicker returns an integer value identifying the value selected on the clicker.

Example

The following examples create a clicker with a label of "Select a number," a minimum value of 0, a maximum value of 100, and a default value of 50.

or

Time Spinners

A time spinner is similar to a clicker; however, a time spinner can only be used to select increments of time. The user selects the appropriate time by using the up and down arrows to click through sequential values. The hours are selected by default. The user can select the minutes or the seconds by clicking them. The following figure shows a time spinner: 

Time Spinner Example 

Element Format

Return Value

The spinner returns the number of seconds past midnight that the user selected in the spinner.

Example

The following example demonstrates the spinner function by performing the following tasks:

• gets the current time
• computes the seconds past midnight to populate the spinner
• creates a response() function dialog with a spinner
• converts the return value to the corresponding time
• Displays the time in a response() function dialog

Sliding Scales

Use a sliding scale to allow the user to graphically select a value within a range by moving the slider arm to the correct position. All sliding scale values must be integers. If you are displaying the dialog box on the PATROL Console for Windows, two digits are displayed. On the PATROL Console for Unix, only the default value is displayed. When you create a sliding scale, the slider arm points to the relative location of the default value on the slider shaft, and the numeric default value appears centered on the slider shaft, as shown in the following figure. 

Sliding Scale Example 



The response() function performs the following consistency checks on the sliding scale minimum, maximum, and initialvalues:

• If minimum > maximum, set maximum = minimum + 100
• If initial < minimum or initial > maximum, set initial = ( minimum + maximum ) / 2

Element Format

Return Value

The sliding scale returns the value selected by the user.

Example

The following are examples of the sliding scale definition. The definition pops up a set of sliding bar "Time Machine" controls defaulting to the current date and time.

Labels

Use labels to provide users with information about a control element or group of control elements. Labels help users understand the dialog box. The following figure shows a typical label: 

 Label Example 

Element Format

Return Value

The label element does not have a return value.

Example

The following definition creates a label for a BMC Software logo.

Icons

Use icons to display graphics, such as logos or icons, in a dialog box. 

The creation of icons on the PATROL Console can sometimes consume significant processing time. Unless an icon is already cached internally, it takes time to load the image from disk. 

The second time a given icon is requested, the performance penalty will disappear if the icon is still in cache. The performance penalty may also disappear if the icon already appears elsewhere within the console GUI. However, the caching effect leading to better performance may only occur if you have actually viewed the window in which the icon appears. The following figure shows a typical icon: 

 Icon Example 

Element Format

Return Value

The icon element does not have a return value.

Example

The following example displays the BMC Software logo (BMC.xbm )from the directory $PATROL_HOME/lib/images in the dialog box.

Separators

Use separators to help users distinguish between different control elements or groups of control elements. You can use vertical separators or horizontal separators. Vertical separators must be put inside rows; horizontal separators must be put inside columns. 

The separator places a line on the dialog box and allows you to format and group the other fields you place on the dialog box. 

The following figure shows vertical and horizontal separators. 

Separator Example 

Element Format

Return Value

The separator element does not have a return value.

Example

The following example separates two columns of radio buttons with a vertical separator.

Frames

Use frames to group related control elements together. Frames can help to set related control elements apart from other control elements or from groups of control elements in the dialog box. 

The element definitions that are part of a frame compound definition are placed in an enclosed bordered region of the dialog or popup. The frame elements are aligned in the following manner:

• If the element is specified in a column, it is positioned on the left edge of the frame that contains it.
• If the element is specified in a row, it is positioned immediately to the right of the previous element definition.

The following figure shows a typical frame. 

Frame Example 

Element Format

Return Value

The frame element does not have a return value.

Example

The following example creates a frame enclosing a column of three rows of radio buttons, three buttons in each row.

Columns

You can use columns to position control elements in a dialog box. Columns position control elements vertically. 

All of the control elements in a response() function dialog box must be put inside rows or columns. You can put rows inside columns and columns inside rows. Rows and columns are used for design purposes only; they are invisible to the user. 

The element definitions that are part of a column-compound definition are placed vertically from top to bottom in the dialog or popup. The column is aligned along the left edge of the frame that contains it, immediately beneath the previous element definition. 

Unless otherwise specified, all response() function definitions are aligned in a single row. the following figure shows a typical column. 

Column Example 

Element Format

Return Value

The column element does not have a return value.

Example

The following example creates a column of three rows of radio buttons, three buttons in each row.

Rows

You can use rows to position control elements in a dialog box. Rows position control elements horizontally. 

All of the control elements in a response() function dialog box must be put inside rows or columns. You can put rows inside of columns and columns inside of rows. Rows and columns are used for design purposes only; they are invisible to the user.

The element definitions that are part of a row-compound definition are placed horizontally from left to right across the dialog box or popup. The row is aligned beginning at the left edge of the frame that contains it, immediately beneath the previous element definition. The following figure shows a typical row. 

Row Example 

Element Format

Return Value

The row element does not have a return value.

Example

The following example creates a row with three elements: two columns of radio buttons and a vertical separator between them.

Popup Dialog Boxes

You can include a secondary or popup dialog box in a main dialog box. The secondary dialog box may contain all of the control elements that a main dialog box can contain, including its own popup dialog box. 

The popup is a compound GUI element that is displayed by clicking on a popup button in the parent dialog box. The element definitions included in the popup definition are displayed in the popup dialog box. The element definitions for popups can include other popups and compound elements as well as common element definitions (like buttons, lists, and check boxes). The following figure shows a typical popup. 

Popup Example 

Element Format

Return Value

The popup returns an integer value identifying the state of the popup when it was closed. 

pop_state\n

• 0- popup displayed at least once and was most recently closed using Cancel
• 1- popup displayed at least once and was most recently closed using OK
• 2- popup was not displayed (initial value)
• 3- popup was displayed, but the parent window was closed while the popup was still open (neither OK nor Cancel was selected)

The return values of the elements defined in the popup dialog box are returned with the return values of the initial response() function dialog box. The element return values follow the pop_state value in the order they are defined in the popup.

Example

The following example creates a dialog box with a popup. This example response() function code produces the dialog box shown in The following figure .

Example

The following PSL script combines all the previous element examples to produce a response() function dialog box using PSL list internal representation and PSL list operator definitions. The script consists of

• response_analysis() function that decodes and provides a text summary of the response() function return value
• main() function that displays the response dialog and then calls the response_analysis() function to decode the return value

The response() function contains comments to assist you in recognizing the element definitions.

The following figure shows the response() function dialog box displayed by the example. 

 response() Function Example Dialog Box 



The following is a sample output from the response() function example: