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

response(title, timeout, preferences,
...elements...)


Parameter

Parameter

Definition

title

character string that is the title of the dialog box The title is the name of the dialog box that appears in the title bar of the dialog box when it is displayed. If you are updating a dynamic response() function that has already been created, the title is replaced with the rid of the dynamic response() function dialog box. For more information, see Dynamic response() Function Dialog Boxes.

timeout

number of seconds that the agent will wait for acknowledgment of the dialog before canceling it The timeout parameter defines how long the response() function waits for a PATROL Console response to the dialog box.

  • If timeout > 0, the response() function waits the designated number of seconds for a PATROL Console response.
  • If timeout = 0, the response() function returns immediately without waiting for a PATROL Console response.
  • If timeout < 0 or timeout = "", the response() function waits infinitely for a PATROL Console response.

preferences

list that specifies the properties of the dialog box 
The preferences are the general characteristics of the dialog box such as size, buttons, button labels, and behavior. The preferences string is required, but the individual preferences are all optional. Specifying the NULL string ( "" ) selects all the default preferences. 
Warning: Do not use the NULL string with the list operator. See PSL List Operator Format
For detailed information about the response() function preferences, see response() Function Preferences.

elements

lists that define the fields and controls that appear on the dialog box For detailed information about the response() function elements, see response() Function Elements.

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:

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

response("Default","","");-


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.)

Note

 

The functionality of the response() function changes slightly from one platform to another. Considering the large number of platforms supported by PATROL, this manual cannot list all platform differences for this function. Be prepared to test this function to accommodate whatever minor irregularities exist on a specific platform.

Design Considerations of a Dialog Box

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

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:

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

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. 

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: 

status\n
returnvalue01\n
. . .
returnvaluen



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):

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).

Note

 

Both Cancel and timeout have a status of 0, but Cancel returns the values of the dialog box and timeout returns the empty string.

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 

Return ValueReturn Value Description
response() Function Status Return Value:
status

flag identifying the button that closes the dialog box The status is always the first value in the list returned by the response() function.

Valid Values 
1 OK 
0 Cancel or timeout

Element Return Values:
Sliding Scalescale_value \n integer value identifying the position of the scale pointer on the sliding scale
Radio Boxesradio_number \n integer value identifying the radio button that is ON in the radio button box The radio buttons are numbered in order of their definition in the response() function, beginning with number 1. Each radio box returns exactly one radio_number .
Check Boxescstate1 cstate2 . . . cstaten \n 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.
Option Menuoption_number \n integer value indicating the option number selected from the option menu The options are numbered in order of their definition in the response function, beginning with number 1. Each option menu returns exactly one option.
Text Fieldstext_string \n character string value that was typed into the text field The text_string is a single line of text containing no new-line characters. The response() function return value method prevents the user from entering a new-line character in a text field request. The user can enter only one line of text.
Toggle Buttontstate \n binary value indicating that the toggle switch is ON (1) or OFF (0)
Single-Select Scrolled Listsscroll_number \n integer value identifying the scroll list entry that is SELECTED in the single-selection scroll list The scroll list entries are numbered in order of their definition in the response() function, beginning with number 1. Each radio box returns exactly one scroll_number . If no scroll list entry is selected, the return value is 0.
Multiple-Select Scrolled Listmscroll1 mscroll2 . . . mscrolln \n space-separated row of integer values identifying the n multiple-selection scroll list entries as SELECTED (1) or UNSELECTED (0) The mscrolln values are listed in order of the scroll list definitions in the response() function. If no scroll list entries are selected, the return value is 0.
Time Spinnerelapsed \n integer value that is the number of seconds that were indicated in the hours , minutes , and seconds windows of the spinner button 
The elapsed value is determined using the following conversion: 
elapsed = 3600( hours ) + 60( minutes ) + seconds 
Valid Values 
0-86,399
popup

pop_state \n integer value identifying the state of the popup when it was closed 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.

Valid Values 
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) 
A value of 0 or 1 gives no indication whether the popup was open when its parent was closed. For example, the user could display the popup, click Cancel, display it again, change the content, and close the main window with the popup still open. In this case, pop_state = 0 because the popup was last closed using the Cancel button.

Clickervalue \n integer value identifying the value on the clicker

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

dialogID = response("Title","","D=1", ...elements...);


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

success = response(dialogID,"","D=1", ...elements...);

Note

Specifying the D preference in subsequent response() function calls to the dynamic dialog is optional. The response() function ignores the D preference in calls that specify rid instead of a title string.

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:

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

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 

Can Update:

Cannot Update:


label (types 0, 1) 
sliding scale (types 2, 3) 
radio box (types 6, 7) 
check box (types 8, 9) 
text field (types 11, 12) 
toggle button (type 13) 
scrolled list (types 17, 18, 22, 23)


separators (types 4, 5) 
icon (type 19) 
popup (types 20, 21) 
frame (type 14) 
column (type 16) 
row (type 15) 
option menu (type 10) 
time spinner (type 24)

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:

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 

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.

Warning

 

The list operator ignores the NULL string ( "" ). The ["a", "", "b"] list is equal to "a\nb", but not "a\n\nb". Use the new-line character to separate the members of a list if the list contains the NULL string.


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

["h=height","w=width","b=color","H=id filename",
"e=echo","o=ok_label","c=cancel_label","N=notify",
"A=ack_required","B=broadcast","D=dynamic",
"K=end_dialog"]

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: 

"h=height\nw=width\nb=color\nH=id filename\ne=echo\n
o=ok_label\nc=cancel_label\nN=notify\nA=ack_required\n
B=broadcast\nD=dynamic\nK=end_dialog"


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: 

"h=height,w=width,b=color,H=id filename,e=echo,
o=ok_label,c=cancel_label,N=notify,A=ack_required,
B=broadcast,D=dynamic,K=end_dialog"

Note

When you are using the character string format, make sure that each item of the preference string starts with the character that designates the preference immediately following the comma with no spaces. You cannot have spaces at the beginning of a preference designation.

 

Preferences Parameters

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


 response() Function Preferences 

Parameter

Description


h= height 
and 
w= width

integer height and width of the dialog box in pixels Valid Values

  • value > 0 specifies the height or width of the dialog in pixels
  • value ≤ 0 specifies a dynamic height or width selected by the window manager

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. |

b= color

character string that specifies the name of the dialog background color Do not enclose the color character string in double quotation marks. The color parameter maps the Motif internals of the PATROL Console machine. If Motif cannot resolve color , it substitutes the color that the PATROL Console uses as a background in its dialogs.

Default 
colors used by PATROL

H= ID filename

text string that enables a Help button on the response() function dialog box and specifies the file name and topic ID that the PATROL Console should display when the Help button is pressed The Hspecification must consist of a numeric ID and a string filename . The ID and filename must be separated by a delimiter character: space, colon, or minus sign. Do not use commas, tab characters, or new-line characters because the response() function will interpret these characters as field delimiters. The filename is either the Windows Help file for the Windows console, or the .hlp file that contains the Help ID mapping for the Unix console. The file name can be specified with or without the.hlp file extension. If the extension is omitted, PATROL adds the .hlp extension when the help call is made.

Default 
If the H preference is not specified, the Help button does not appear on the dialog box.


o=accept _label 
o=@accept_label

character string that replaces "Accept" on the Accept button for the dialog and any popups activated from the dialog Placing @ in front of the button name disables the button from closing the dialog box when it is clicked. If the Accept button is disabled from closing the dialog box, the dialog box returns a value to the PATROL Agent and remains open for further user updates when the Accept button is clicked. This feature is generally used with dynamic response() function dialog boxes. (For more information, see Dynamic response() Function Dialog Boxes and response_get_value().) If you specify the o preference with no label ( o= ), the response() function does not display the Accept button on the dialog box. If you hide both the Accept and Cancel buttons, you must close the dialog box from PSL using the K preference. Do not enclose the accept_label character string in double quotation marks, and do not include commas, tab characters, or new-line characters in theaccept_label character string because these characters are interpreted as field delimiters.

Default 
Accept

*Examples*

  • o=@ disables the button labeled Accept from closing the dialog box
  • o=Done enables the button labeled Done to close the dialog box
  • o=@Done disables the button labeled Done from closing the dialog box
  • o= removes the button that would be labeled Accept from the dialog box


c=cancel_label 
c=@cancel_label

character string that replaces "Cancel" on the Cancel button for the dialog and for any popups activated from the dialog Placing @ in front of the button name disables the button from closing the dialog box when it is clicked. If the Cancel button is disabled from closing the dialog box, the dialog box returns a value to the PATROL Agent, and when the Cancel button is clicked, remains open for further user updates. This feature is generally used with dynamic response() function dialog boxes. (For more information, see Dynamic response() Function Dialog Boxes and response_get_value().) If you specify the c preference with no label (that is, "c=" ), the response() function does not display the "Cancel" button on the dialog box. If you hide both the Cancel and Accept buttons, you must close the dialog box from PSL using the K preference. Do not enclose the cancellabel character string in double quotation marks, and do not include commas, tab characters, or new-line characters in the cancellabel character string because these characters are interpreted as field delimiters.

Default 
Cancel 
Examples

  • c=@ disables the button labeled Cancel from closing the dialog box
  • c=Accept enables the button labeled Accept to close the dialog box
  • c=@Accept disables the button labeled Accept from closing the dialog box
  • c= removes the button that would be labeled Accept from the dialog box

N= notify

bit flag that specifies if the dialog is editable 

Valid Values 
0 dialog box is editable The response() function uses the timeout parameter to determine how long the PATROL Agent waits for a response to the editable dialog. 
1 dialog is not editable The dialog is presented to the PATROL Console as a nonblocking notification dialog. The response() function returns immediately without waiting for a PATROL Console response. The PATROL Console will display the noneditable dialog box until the user closes it using the OK or Cancel button. N=1 is equivalent to specifying timeout = 0 in the response()function.

Default 
0

A=ack_required

bit flag that specifies if the dialog requires an acknowledgment*Valid Values* 
0 does not require explicit acknowledgment The user does not need to acknowledge the dialog box when it is presented to a single PATROL user ( B=0 ) and the process that called the response() function continues when the dialog box is closed (in any manner) or when the dialog box has reached the timeout value. 
1 changes the text of the Accept button to Acknowledge, changes the text of the Cancel button to Dismiss, and requires explicit acknowledgment of the dialog in all cases If the dialog box is not acknowledged with the Acknowledge button, no dialog box values are returned, and the PSL process that called the response() function does not continue unless the dialog box has reached the timeoutvalue. 
When a user clicks the Acknowledge button, the status of the Response event changes from Open to Acknowledged, and the name of the button changes from Acknowledge to Accept. Clicking Accept changes the status of the event from Acknowledged to Closed, passes the return value to the PSL script, and closes the response dialog. 
Acknowledging a response event is different when the response dialog appears on multiple consoles (B=1). When one user clicks Acknowledge, the name of the Acknowledge button changes to Accept on all PATROL Consoles that display the dialog. When one user clicks Accept, the dialog closes on all consoles. 

Default 
0

B= broadcast

bit flag that specifies who receives the response to the dialog*Valid Values* 
0 the PATROL Console that started the process that executed the response() function 
1 all PATROL Consoles connected to the PATROL Agent that processed the response()function*Note* 
If a response dialog appears on multiple consoles (as allowed by B=1), the dialog requires explicit acknowledgement regardless of the setting for A= ack_required

Default 
0

D= dynamic

bit flag that enables the response() function dialog box to be dynamically updated from a PSL script; it also enables multiple return values returned to, and processed by the PSL script before the dialog box is closed 
For more information on dynamic response() functions, see Dynamic response() Function Dialog Boxes and response_get_value()
After the initial response() function call creates a dynamic dialog box, subsequent calls to modify the field values do not require the D preference. The response() function will ignore the D preference if it is present. 
All dynamic response() function calls return immediately to the caller and do not use the timeout parameter. If you specify the timeout parameter on a dynamic response() function call, theresponse() function ignores it. 
Once a dynamic response() function dialog box has been created, further use of the D option in subsequent response() function calls to rid is unnecessary. The response() function calls to a dynamic dialog box ignore the D option. 
Dynamic response() function calls ignore any specified timeout and immediately return an rid or operation status value:

  • If title and D=1 are specified, the response() function returns a new and unique rid based on host name and ID and opens a new dynamic dialog box on the PATROL Console display.
  • If rid is specified in place of title, the response() function sets the element values included in theresponse() function call and returns a 0 or 1 status value. (The state of the D option is irrelevant when an rid is specified in place of title.)

Valid Values 
0 disable dynamic updating of the dialog box 
1 enable dynamic updating of the dialog box

*Default* 
0

K=end_dialog

bit flag that enables the PSL script (that created this response() function dialog box) also closes it 
This preference can only be used against a response() function dialog box that was created using theD=1 preference. When specified, the dialog box will immediately close on all PATROL Consoles and return the closing status of the dialog box elements. 
This preference is for dynamic dialog boxes including those for which none of the existing dialog buttons will close the dialog box.

 Note 
If a dialog box must be acknowledged (A=1 or B=1), a user must click the appropriate button twice to close the dialog: once to change the status of the response event and once to pass the return value to the PSL script. 

 Valid Values 
0 do not close the response() function dialog box 
1 immediately close the dialog box on all consoles and return the values of the dialog box elements

*Default* 
0

 

Preferences Example

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

PSL List Internal Representation

 

# h=500 dialog box height is 500 pixels
# w=300 dialog box width is 300 pixels
# color change
# H=0 no help button on dialog box
# e=1 echo output to a text window
# o=Accept Accept label on dialog box OK button
# c=Cancel Cancel label on dialog box Cancel button
# N=0 Dialog box is editable
# A=0 acknowledgement is not required
# B=0 dialog box response is not broadcast
# D=0 dynamic updating is disabled
# K=0 do not close dialog box from this function call
# H=1 exthlp map help button to topic 1 in file exthlp
"h=500\nw=300\nH=0\ne=1\no=Accept\nc=Cancel\nN=0\nA=0\nB=0\nD=0\nK=0\nH=1 exthlp"

 

PSL List Operator Format

 

[
"h=500", # dialog box height is 500 pixels
"w=300", # dialog box width is 300 pixels
# no color change
"H=0", # no help button on dialog box
"e=1", # echo output to a text window
"o=Accept", # Accept label on dialog box OK button
"c=Cancel", # Cancel label on dialog box Cancel button
"N=0", # dialog box is editable
"A=0", # acknowledgement is not required
"B=0", # dialog box response is not broadcast
"D=0", # dynamic updating is disabled
"K=0", # do not close dialog box from this function call
"H=1 exthlp" # map help button to topic 1 in file exthlp
]

 

Character String Format

 

# h=500 dialog box height is 500 pixels
# w=300 dialog box width is 300 pixels
# color change
# H=0 no help button on dialog box
# e=1 echo output to a text window
# o=Accept Accept label on dialog box OK button
# c=Cancel Cancel label on dialog box Cancel button
# N=0 Dialog box is editable
# A=0 acknowledgement is not required
# B=0 dialog box response is not broadcast
# D=0 dynamic updating is disabled
# K=0 do not close dialog box from this function call
# H=1 exthlp map help button to topic 1 in file exthlp
"h=500,w=300,H=0,e=1,o=Accept,c=Cancel,N=0,A=0,B=0,D=0,K=0,H=1 exthelp"

 

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:

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 

Control Element

Page Number

text fields

Text Fields

radio buttons

Radio Buttons

check boxes

Check Boxes

toggle buttons

Toggle Buttons

single-selection lists

Lists

multiple-selection lists

Lists

option menus

Option Menus

clickers

Clickers

time spinners

Time Spinners

sliding scales

Sliding Scales

labels

Labels

icons

Icons

separators

Separators

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:

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 

Control Element

Page Number

frames

Frames

rows

Rows

columns

Rows

popup dialog boxes

Popup Dialog Boxes

 

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:

 

response("Some title"," "," ",[R_CHECK_HORIZ,...]);

 

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:

Elements Format

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

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:

 

[type,data1,data2, . . . ,datan]

 

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:

 

"type\ndata1\ndata2\n . . . \ndatan"

Note

If you are using the PSL list internal representation, and you are using the symbolic name of the PSL response() function element, you must not enclose the symbolic name in quotation marks. Use the following syntax for symbolic names used with the PSL list internal representation: SYMBOLIC_CONSTANT."\ndata1\ndata2\n . . . \ndatan" For more information on symbolic names, see Symbolic Names of Elements.

 

Defining response() Function Elements

This section describes the elements listed in the following table. 


 response() Function Elements 

No

Symbolic Name

Description

Page

0

R_LABEL

label (left-justified)

Labels

1

R_LABEL_CENTER

label (centered)

Labels

2

R_SCALE_HORIZ

sliding scale (horizontal)

Sliding Scales

3

R_SCALE_VERT

sliding scale (vertical)

Sliding Scales

4

R_SEP_HORIZ

separator (horizontal)

Separators

5

R_SEP_VERT

separator (vertical)

Separators

6

R_RADIO_VERT

radio buttons (vertical)

Radio Buttons

7

R_RADIO_HORIZ

radio buttons (horizontal)

Radio Buttons

8

R_CHECK_HORIZ

check box (horizontal)

Check Boxes

9

R_CHECK_VERT

check box (vertical)

Check Boxes

10

R_MENU

option menu

Option Menus

11

R_TEXT_FIELD

text field (without label)

Text Fields

12

R_TEXT_FIELD_LABEL

text field (with label)

Text Fields

13

R_TOGGLE

toggle button

Toggle Buttons

14

R_FRAME

frame compound element

Frames

15

R_ROW

row compound element

Rows

16

R_COLUMN

column compound element

Columns

17

R_LIST_SINGLE

scrolled list (single-select, default)

Lists

18

R_LIST_MULTIPLE

scrolled list (multiple-select, defaults)

Lists

19

R_ICON

icon

Icons

20

R_POPUP_SCROLLED

popup (scrolled)

Popup Dialog Boxes

21

R_POPUP

popup (nonscrolled)

Popup Dialog Boxes

22

R_LIST_SINGLE_ND

scrolled list (single-select, no default)

Lists

23

R_LIST_MULTIPLE_ND

scrolled list (multiple-select, no defaults)

Lists

24

R_SPINNER

time spinner button

Time Spinners

25

R_CLICKER

clicker widget

Clickers

 

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

 

[type,label,default_text,e=text_echo]

Parameter

Definition

type

integer value that identifies the element as a text field 

Valid Values 
11 (R_TEXT_FIELD) text field without label 
12 (R_TEXT_FIELD_LABEL) text field with label

label

character string label for the text box (not valid if type =11) The label character string must be enclosed in double quotation marks. The label may be specified as multiple lines of text. 

Note: omit label for type =11.

default_text

character string that is the default text within the text box If you are using the e=0 option to blank out the entered text to have a blank entry field, use the new-line character (\n) as the default text.

e=text_echo

character string that specifies whether text typed into the text box is displayed 
You can use the echo mode to blank out text entry for text fields that contain sensitive information, such as passwords.

Valid Values 
1 Display entered text 
0 Blank out entered text*Default* 
1

 

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:

 

text_string\n

 

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.

 

[R_TEXT_FIELD_LABEL,”Username:”,”\n”,”e=1”] # text field (echo text)
[R_TEXT_FIELD_LABEL,”Password:”,”\n”,”e=0”] # text field (blank 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.

 

[R_TEXT_FIELD, "LABEL", "Default Text"]
[R_TEXT_FIELD, "Default Text"]

 

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

 

[type,[setstring],radion[=rstaten]]

Parameter

Definition

type

integer value that identifies the element as a set of radio buttons*Valid Values* 
6 (R_RADIO_VERT) vertical radio box 
7 (R_RADIO_HORIZ) horizontal radio box

setstring

a character string in the form @ n where n specifies the button that defaults to ON (The other radio buttons default to OFF.) 
The preceding @ character is required to differentiate setstring from a radio button definition. There must be no space or delimiter between the @ and the radio box number.

Example 
@1 sets the first radion button that is defined as the default 
@3 sets the third radio button that is defined as the default

radio_n= [state_n]

radio_n is a character string label for the nth radio button 
If setstring is not specified for the radio button control, radion should be followed by = state_n to set the default state of the radio button. 

Valid Values (state_n) 
0 OFF 
1 ON 
Only one radio button in a radio button box is permitted to have state 1; all others must have state 0. 
When setstring is specified, the response() function will treat the following radio button definitions as text, so if you specify setstring and = state_n, = state_n appears as part of the radio button label.

 

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. 

radio_number\n

Example

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

 

[R_RADIO_VERT,"Unix=0","Windows=1"],
[R_RADIO_VERT,”@2”,"Unix","Windows"],

 

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

 

[type, [setstring], checkn[=cstaten]]

Parameter

Definition

type

integer value that identifies the element as a set of check boxes*Valid Values* 
8 (R_CHECK_HORIZ) horizontal check box 
9 (R_CHECK_VERT) vertical check box

setstring

a character string in the form @1 b,. . . n where each n is an integer that specifies the position of a check box in the sequence of check box definitions check1 ... checkn that is to default to CHECKED 
All check box numbers not included in setstring default to UNCHECKED. The preceding @ character is required to differentiate setstring from a button definition. There must be no space or delimiter between the @ character and the first integer. Subsequent integers may be preceded by a single space, comma, or tab character. 
When setstring is specified, the response() function ignores any default settings that appear in the check box definitions. Specifying setstring = @0 sets all check boxes UNCHECKED and ignores any settings specified in the button definitions.

checkn=cstaten

checkn is a character string label for the nth check box and may be specified as multiple lines of text 
Do not enclose the checkn character string in double quotation marks. 
cstaten is the binary state of the check box. 

Valid Values 
0 UNCHECKED 
1 CHECKED

 

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.

 

cstate1 cstate2 ... cstaten\n

 

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.

 

[R_CHECK_VERT,"Yes=0","No=1","Maybe=1"]

 

or

 

[9,"@2 3","Yes","No","Maybe"]

 

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

 

[type, toggle, [tstate]]

Parameter

Definition

type

integer value identifying the element as a toggle button 

Valid Value 
13 (R_TOGGLE)

toggle

character string that is the label for the toggle button

tstate

initial state of the toggle button

*Valid Values* 
0 OFF 
1 ON 
Default 
OFF

 

Return Value

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

 

tstate\n

 

Example

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

 

[13,"Automatic Return in 1 Hour",1], # toggle button element

 

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:

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

 

[type, scrolln=sstaten]

Parameter

Definition

type

integer value that identifies the element as a scrolled list

*Valid Values* 
17 (R_LIST_SINGLE) single-selection scrolled list with default 
18 (R_LIST_MULTIPLE) multiple-selection scrolled list with default 
22 (R_LIST_SINGLE_ND) single-selection scrolled list without default 
23 (R_LIST_MULTIPLE_ND) multiple-selection scrolled list without default 
If scroll-type is 22 or 23, the response() function ignores the equal sign (=) and any values specified in the list definition. (This function allows you to specify display text that contains equal signs.) 
For scrolled lists without defaults, all entries are UNSELECTED (that is, equal to 0).

scrolln=sstaten


scrolln is a character string that is the label for the nth entry in the scrolled list 
sstaten is the binary state of the nth scrolled list entry 
Valid Values 
0--UNSELECTED 
1--SELECTED 
If no states are specified for the scrolled list entries, all states default to 0.

 

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.

 

mscroll1... mscrolln\n

 

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:

 

[R_LABEL,"Our Menu:"],
[R_ROW,4],
[R_LIST_SINGLE,"Water=1","Coffee=0","Tea=0","Wine=0"],
[R_LIST_MULTIPLE,"Okra=1","Peas=1","Corn=0","Squash=0"],
[R_LIST_SINGLE_ND,"Beef","Hen","Pork","Fish","None"],
[R_LIST_MULTIPLE_ND,"Cake","Pie","Fruit","Mint","Candy"],

 

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

 

[type, label, default, [optionn]]

Parameter

Definition

type

integer value that identifies the element as an option menu

*Valid Value* 
10 (R_MENU )

label

character string label for the option menu The label character string must be enclosed in double quotation marks.

default

integer value that identifies the default option on the option menu If no default is specified, the first option defined in the list is the default.

optionn

optional character string that identifies the text of the nth option on the option menu The optionn character strings must be enclosed in double quotation marks.

 

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.

 

option_number\n

 

Example

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

 

[10,"Time:",2,"Month","Day","Year","Hour","Minute"],

 

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

 

[type, label, min, max, default-value]

 

 

Parameter

Definition

type

value that identifies the element as a clicker

*Valid Value* 
25 (R_CLICKER )

label

character string that specifies the label that appears on the dialog box

min

integer that specifies the minimum value of the clicker

max

integer that specifies the maximum value of the clicker

default-value

integer that specifies the default value of the clicker

 

Return Value

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

 

value\n

 

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.

 

[25, "Select a number", 0, 100, 50]

 

or

 

[R_CLICKER, "Select a number", 0, 100, 50]

 

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

 

[type, seconds]

 

 

Parameter

Definition

type

integer value identifying the element as a time spinner 

Valid Values 
24 (R_ SPINNER)

seconds

integer value that specifies the current time (in seconds past midnight) that will be displayed on the spinner 
The spinner button converts and displays the time in hh:mm:ss format. 

Valid Values 
0 - 86,399

 

Return Value

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

 

seconds\n

 

Example

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

#get the current time and parse the return values
current_time = asctime(time(),"%S\n%M\n%H\n%Y\n%d\n%a\n%b");
seconds = trim(nthlinef(current_time ,1),"\n");
minutes = trim(nthlinef(current_time ,2),"\n");
hours = trim(nthlinef(current_time ,3),"\n");
year = trim(nthlinef(current_time ,4),"\n");
day_num = trim(nthlinef(current_time ,5),"\n");
day_str = trim(nthlinef(current_time ,6),"\n");
month = trim(nthlinef(current_time ,7),"\n");
#get the number of seconds since midnight for the current time
current_seconds = 3600 * hours + 60 * minutes + seconds;
#display a dialog with the current time value in the spinner
spinner_result = response("Spinner Example","","",
[R_LABEL,"Select a time:"],[R_SPINNER,current_seconds]);
#construct a string of the current date to find the seconds
date_string=day_str." ".day_num." ".month." ".year." 00:00:00";
#get the number of seconds until midnight
base=convert_date(date_string);
#get the spinner result
spinner_result = trim(nthlinef(spinner_result,2),"\n");
#get a character string of the selected time
spinner_result = asctime(spinner_result+base);
#display the selected time
response("Spinner Example","","",
[R_LABEL,"Time selected:"],[R_LABEL,spinner_result]);


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 minimummaximum, and initialvalues:

Element Format

 

[type, scale-label, minimum, maximum, initial]

Parameter

Definition

type

integer value that identifies the element as a sliding scale definition

*Valid Values* 
2 (R_ SCALE_HORIZ) horizontal sliding scale 
3 (R_ SCALE_VERT) vertical sliding scale

scale-label

character string label for the sliding scale The scale-label character string must be enclosed in double quotation marks.

minimum

numeric value specifying the lower limit of the scale

*Default* 
0

maximum

numeric value indicating the upper limit of the scale

*Default* 
100

initial

numeric value indicating the initial position of the scale pointer on the sliding scale

*Default* 
midway between minimum and maximum

 

Return Value

The sliding scale returns the value selected by the user.

 

value\n

 

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.

 

[21,1,"Time Machine","Time Controls"], # popup dialog box
[16,2], # column compound element
[14,1], # frame compound element
[16,4], # column compound element
[1,"Clock Controls"], # label element
[2,"seconds",0,59,””], # slide bar element
[2,"minutes",0,59,””], # slide bar element
[2,"hours",0,23,””], # slide bar element
[14,1], # frame compound element:
[16,4], # column compound element
[1,"Calendar Controls"], # label element
[2,"day",1,31,””], # slide bar element
[2,"month",1,12,””], # slide bar element
[2,"year",””], # slide bar element

 

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

 

[type, label]

Parameter

Definition

type

integer value that identifies the element as a label

*Valid Value* 
0 (R_LABEL) left-justified label 
1 (R_LABEL_CENTER) centered label

label

character string that specifies the label that appears on the dialog box The label character strings must be enclosed in double quotation marks. The label may be specified as multiple lines of text by using the new-line character (\n).

 

Return Value

The label element does not have a return value.

Example

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

 

[R_LABEL_CENTER,"The BMC Software logo follows:"],
[R_ICON,"$PATROL_HOME/lib/images/BMC.xbm"],

 

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

 

[type, icon-filename]

Parameter

Definition

type

integer value identifying the element as an icon

*Valid Value* 
19 (R_ICON )

icon-filename

character string identifying the file containing the icon image The icon-filename character string must be enclosed in double quotation marks. The file extension will automatically be changed to .xpm for Unix console and .bmp for Windows console.

 

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.

 

[R_ICON,"BMC.xbm"],

 

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

 

[type]

Parameter

Definition

type

integer value that identifies the element as a separator

*Valid Values* 
4 (R_ SEP_HORIZ) horizontal separator 
5 (R_ SEP_VERT) vertical separator

 

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.

 

[15,3], # row compound element:
[6,"Unix=1","Windows=0"], # radio button
[5], # vertical separator
[6,"Binary=0","Text=0","Autoselect=1"], # radio button

 

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:

The following figure shows a typical frame. 

Frame Example 


Element Format

 

[type, felements]

Parameter

Definition

type

integer value identifying the element as a frame 

Valid Value 
14 (R_ FRAME)

felements

integer value specifying the number of subsequent element definitions that are included in the frame The felements value includes nested compound element definitions but does not include the elements that are specified for those nested compound elements. See Nested Compound Elements.

Note

The response() function ignores the felements parameter and sets its value to 1. To define multiple elements in a frame, define a frame element and then define a row or column as the frame's first element.

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.

 

[14,1],
[16,3],
[7,"Yes=0","No=0","Maybe=1"],
[7,"Don’t Know=0","Don’t Care=0","Good-bye=1"],
[7,"Great=0","Good=0","So-So=1"],

 

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

 

[type, celements]

Parameter

Definition

type

integer value identifying the element as a column

*Valid Value* 
16 (R_COLUMN)

celements

integer value specifying the number of subsequent element definitions that are included in the column The celements value includes nested compound-element definitions but does not include the elements that are specified for those nested compound elements. See Nested Compound Elements.

 

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.

 

[16,3],
[7,"Yes=0","No=0","Maybe=1"],
[7,"Don’t Know=0","Don’t Care=0","Good-bye=1"],
[7,"Great=0","Good=0","So-So=1"],

 

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

 

[type, relements]

Parameter

Definition

type

integer value identifying the element as a row

*Valid Values* 
15 (R_ROW)

relements

integer value specifying the number of subsequent element definitions that are included in the row The relements value includes nested-compound element definitions but does not include the elements that are specified for those nested-compound elements. See Nested Compound Elements.

 

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.

 

[15,3], # row compound element:
[6,"Unix=1","Windows=0"], # radio button
[5], # vertical separator
[6,"Binary=0","Text=0","Autoselect=1"], # radio button

 

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

 

[type, pelements, btitle, ptitle, h=pheight, w=pwidth, b=pcolor]

Parameter

Definition

type

integer value identifying the element as a popup

*Valid Values* 
20 (R_ POPUP_SCROLLED) scrolled popup 
21 (R_ POPUP) nonscrolled popup

pelements

integer value specifying the number of subsequent element definitions that are included in the popup The pelements value includes nested compound-element definitions but does not include the elements that are specified for those nested compound elements. See Nested Compound Elements.

btitle

character string that is the label for the popup button on the parent popup or dialog box

*Default* 
popup

ptitle

character string that is the title of the popup dialog box

*Default* 
popup

h=pheight

integer height of the popup in pixels On Windows the pheight and pwidth values are ignored, and the popup height and width are dynamically set by Windows.

Valid Values

  • pheight > 0 the height of the popup in pixels
  • pheight ≤ 0 a dynamic height

Default 
dynamic height selected by the window manager.

w=pwidth

integer width of the popup in pixels On Windows the pheight and pwidth values are ignored, and the popup height and width are dynamically set by Windows.

Valid Values

  • pwidth > 0 the width of the popup in pixels
  • pwidth ≤ 0 a dynamic width

b=pcolor

character string that specifies the name of the popup background color 
pcolor maps the Motif internals of the PATROL Console machine. If Motif cannot resolve pcolor, it substitutes the color that the PATROL Console uses.

Return Value

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

pop_state\n

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 .

 

response("Popup Example","",["o=OK"],
[21,2,"Click Here to See Popup","This Comes Up"], # popup 2 elements
[14,1], # frame with 1 element
[16,4], # column with 4 elements
[1,"Calendar Controls"], # label
[10,"month","January","February", # option menu
"March","April","May","June","July", # options
"August","September","October", # options
"November","December"], # options
[2,"day",1,31,16], # sliding scale
[12,"year",2001], # text field
[21,1,"Click Here to See Another Popup","Another Popup"], # popup
[1,"Another Popup"] # label
);

 

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

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

 

function response_analysis(status) {
# status line 1 is the check box status
print("Check box status:\n");
checks = nthlinef(status,1);
i = 1;
temp = nthargf(checks,i);
while(temp) {
switch (temp) {
case 1: {print(" Yes is checked\n");}
case 2: {print(" No is checked\n");}
case 3: {print(" Maybe is checked\n");}
}
i++;
temp = nthargf(checks,i);
}
print("\n");
# status lines 2 through 4 are the framed rows of radio boxes statuses:
print("Radio box frame status:\n");
i = 2;
while (i <= 4) {
switch (i) {
case 2: {label = ["Yes","No","Maybe"];}
case 3: {label = ["Left","Center","Right"];}
case 4: {label = ["More","Enough","Less"];}
}
radio = int(nthlinef(status,i));
switch (radio) {
case 1: {print(" ",trim(nthlinef(label,1),"\n")," is selected\n");}
case 2: {print(" ",trim(nthlinef(label,2),"\n")," is selected\n");}
case 3: {print(" ",trim(nthlinef(label,3),"\n")," is selected\n");}
}
i++;
}
print("\n");
# status line 5 is the option menu status
print("Option menu status:\n");
option = int(nthline(status,5));
switch (option) {
case 1: {print(" Month is selected\n\n");}
case 2: {print(" Day is selected\n\n");}
case 3: {print(" Year is selected\n\n");}
case 4: {print(" Hour is selected\n\n");}
case 5: {print(" Minute is selected\n\n");}
}
# status line 6 is the popup close status
print("popup dialog close status:\n");
popup = int(nthline(status,6));
switch (popup + 1) {
case 1: {print(" popup was displayed and closed using Cancel\n\n");}
case 2: {print(" popup was displayed and closed using Accept\n\n");}
case 3: {print(" popup was not displayed\n\n");}
case 4: {print(" popup was open when parent dialog closed\n\n");}
}
# status lines 7 through 10 are the time control values
print("Time control settings:\n");
control_time = trim(nthlinef(status,7),"\n");
hours = int(control_time / 3600);
printf(" hours control is set to %d\n",hours);
control_time = control_time - (hours * 3600);
minutes = int(control_time / 60);
printf(" minutes control is set to %d\n",minutes);
seconds = control_time - (minutes * 60);
printf(" seconds control is set to %d\n",seconds);
month_string = [
"January",
"February",
"March",
"April",
"May",
"June",
"July",
"August",
"September",
"October",
"November",
"December"
];
printf(" month control is set to
%s",nthlinef(month_string,trim(nthlinef(status,8),"\n")));
i = 9;
while (i <= 10) {
quantity = ["day","year"];
print(" ",trim(nthlinef(quantity,i - 8),"\n")," control is set to "
,nthlinef(status,i));
i++;
}
print("\n");
# status line 11 is the toggle status
print("Automatic return toggle status:\n");
if (int(nthlinef(status,11)) == 1) {
print(" Automatic return in 1 hour is set\n\n");
} else {
print(" Automatic return in 1 hour is NOT set\n\n");
}
# status lines 12 and 13 are the vertically separated radio box statuses:
print("Radio box status:\n");
i = 12;
while (i <= 13) {
switch (i) {
case 12: {label = ["Unix","Windows"];}
case 13: {label = ["Binary","Text","Autoselect"];}
}
radio = int(nthlinef(status,i));
switch (radio) {
case 1: {print(" ",trim(nthlinef(label,1),"\n")," is selected\n");}
case 2: {print(" ",trim(nthlinef(label,2),"\n")," is selected\n");}
case 3: {print(" ",trim(nthlinef(label,3),"\n")," is selected\n");}
}
i++;
}
print("\n");
# status line 14 is the single-select scrolling menu with default
print("Single-select scrolling menu status:\n");
option = int(nthline(status,14));
switch (option) {
case 1: {print(" Water is selected\n\n");}
case 2: {print(" Coffee is selected\n\n");}
case 3: {print(" Tea is selected\n\n");}
case 4: {print(" Wine is selected\n\n");}
}
# status line 15 is the multiple-select scrolling menu with default
print("Multiple-select scrolling menu status:\n");
option = nthlinef(status,15);
i = 1;
temp = nthargf(option,i);
while(temp) {
switch (temp) {
case 1: {print(" Potatoes are selected\n");}
case 2: {print(" Peas are selected\n");}
case 3: {print(" Carrots are selected\n");}
case 4: {print(" Squash is selected\n");}
}
i++;
temp = nthargf(option,i);
}
print("\n");
# status line 16 is the single-select scrolling menu with no default
print("Single-select scrolling menu status:\n");
option = int(nthline(status,16));
switch (option) {
case 1: {print(" Beef is selected\n\n");}
case 2: {print(" Poultry is selected\n\n");}
case 3: {print(" Fish is selected\n\n");}
case 4: {print(" None is selected\n\n");}
}
# status line 17 is the multiple-select scrolling menu with default
print("Multiple-select scrolling menu status:\n");
option = nthlinef(status,17);
i = 1;
temp = nthargf(option,i);
while(temp) {
switch (temp) {
case 1: {print(" Cake is selected\n");}
case 2: {print(" Pie is selected\n");}
case 3: {print(" Ice Cream is selected\n");}
case 4: {print(" Cookies are selected\n");}
case 5: {print(" Candy is selected\n");}
}
i++;
temp = nthargf(option,i);
}
print("\n");
# status line 18 is the username field content:
print("Username:\n");
print(" ",nthline(status,18),"\n");
# status line 19 is the password field content:
print("Password field content:\n");
print(" ",nthline(status,19),"\n");
return;
}
function main() {
psl_tm = asctime(time(),"%S\n%M\n%H\n%d\n%m\n%y\n%w\n%j");
seconds = trim(nthlinef(psl_tm,1),"\n");
minutes = trim(nthlinef(psl_tm,2),"\n");
hours = trim(nthlinef(psl_tm,3),"\n");
day = trim(nthlinef(psl_tm,4),"\n");
month = trim(nthlinef(psl_tm,5),"\n");
year = trim(nthlinef(psl_tm,6),"\n") + 1900;
current = 3600 * hours + 60 * minutes + seconds;
return_status = response(
"Dean's response() Example", # dialog box title
-1, # infinite timeout
["h=910","w=750","H=0","e=1","o=Accept","N=0","A=0","B=0"], # preferences
# The following are the dialog box control definitions.
# Those controls that return a value are identified by an
# asterisk preceding the label in the comment area on the
# right-hand side.
[15,3], # row:
[16,12], # column:
[1,"List Operator:"], # label
[9,"Yes=0","No=0","Maybe=1"], # *check box
[14,1], # frame:
[16,3], # column:
[7,"Yes=0","No=0","Maybe=1"], # *radio box
[7,"Left=0","Center=1","Right=0"], # *radio box
[7,"More=0","Enough=0","Less=1"], # *radio box
[1,"The BMC Software logo follows:"], # label
[19,"$PATROL_HOME/lib/images/BMC.xbm"], # icon
[10,"Time:",2,"Month","Day","Year","Hour","Minute"], # *option menu
[21,1,"Time Machine","Time Controls"], # *popup:
[16,4], # column:
[14,1], # frame:
[16,2], # column:
[1,"Clock Controls"], # label
[24,current], # *time spinner
[14,1], # frame:
[16,4], # column:
[1,"Calendar Controls"], # label
[10,"month",month,"January","February", # *option menu
"March","April","May","June","July", #
"August","September","October", #
"November","December"], #
[2,"day",1,31,day], # *slide
[12,"year",int(year)], # *text field
[13,"Automatic Return in 1 Hour",1], # *toggle button
[1,"Welcome to another time!"], # label
[15,3], # row:
[6,"Unix=1","Windows=0"], # *radio button
[5], # vertical separator
[6,"Binary=0","Text=0","Autoselect=1"], # *radio button
[0,"Our Menu:"], # label
[15,4], # row:
[17,"Water=1","Coffee=0","Tea=0","Wine=0"], # *scrolled s,d
[18,"Potatoes=1","Peas=1","Carrots=0","Squash=0"], # *scrolled m,d
[22,"Beef","Poultry","Pork","Fish","None"], # *scrolled s,~d
[23,"Cake","Pie","Ice Cream","Cookies","Candy"], # *scrolled m,~d
[12,"Username:"," ","e=1"], # *text (echo)
[12,"Password:"," ","e=0"], # *text (blank)
[5], # vertical separator
"16\n12", # column:
"1\nList Internal Representation:", # label
"9\nYes=0\nNo=0\nMaybe=1", # *check box
"14\n1", # frame:
"16\n3", # column:
"7\nYes=0\nNo=0\nMaybe=1", # *radio box
"7\nLeft=0\nCenter=1\nRight=0", # *radio box
"7\nMore=0\nEnough=0\nLess=1", # *radio box
"1\nThe BMC Software logo follows:", # label
"19\n$PATROL_HOME/lib/images/BMC.xbm", # icon
"10\nTime:\n2\nMonth\nDay\nYear\nHour\nMinute", # *option menu
"21\n1\nTime Machine\nTime Controls", # *popup:
"16\n4", # column:
"14\n1", # frame:
"16\n2", # column:
"1\nClock Controls", # label
"24\n" . current, # *time spinner
"14\n1", # frame:
"16\n4", # column:
"1\nCalendar Controls", # label
"10\nmonth\n" . month . "\nJanuary\n" . # *option menu
"February\nMarch\nApril\nMay\nJune\n" . #
"July\nAugust\nSeptember\nOctober\n" . #
"November\nDecember", #
"2\nday\n1\n31\n" . day, # *slide bar
"12\nyear\n" . int(year), # *text field
"13\nAutomatic Return in 1 Hour\n1", # *toggle button
"1\nWelcome to another time!", # label
"15\n3", # row:
"6\nUnix=1\nWindows=0", # *radio button
"5", # vertical separator
"6\nBinary=0\nText=0\nAutoselect=1", # *radio button
"0\nOur Menu:", # label
"15\n4", # row:
"17\nWater=1\nCoffee=0\nTea=0\nWine=0", # *scrolled s,d
"18\nPotatoes=1\nPeas=1\nCarrots=0\nSquash=0", # *scrolled m,d
"22\nBeef\nPoultry\nPork\nFish\nNone", # *scrolled s,~d
"23\nCake\nPie\nIce Cream\nCookies\nCandy", # *scrolled m,~d
"12\nUsername:\n\ne=1", # *text field (echo)
"12\nPassword:\n\ne=0" # *text field (blank)
);
print("Analysis of response() return value:\n");
print("------------------------------------\n\n");
# status line 1 is the dialog close status
print("Dialog close status:\n");
if (int(nthlinef(return_status,1)) == 1) {
print(" Dialog closed with Accept button\n\n");
} else {
print(" Dialog closed with Cancel button\n\n");
}
print("Analysis of response() dialog list operator fields:\n");
print("---------------------------------------------------\n\n");
list_op_status = nthlinef(return_status,"2-20");
response_analysis(list_op_status);
print("\n");
print("Analysis of response() dialog list internal representation fields:\n");
print("------------------------------------------------------------------\n\n");
internal_rep_status = tail(return_status,19);
response_analysis(internal_rep_status);
return;
}

 

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:

 

Analysis of response() return value:
------------------------------------
Dialog close status:
Dialog closed with Accept button
Analysis of response() dialog list operator fields:
---------------------------------------------------
Check box status:
Yes is checked
Radio box frame status:
Yes is selected
Left is selected
More is selected
Option menu status:
Month is selected
popup dialog close status:
popup was displayed and closed using Accept
Time control settings:
hours control is set to 5
minutes control is set to 42
seconds control is set to 22
month control is set to August
day control is set to 17
year control is set to 1955
Automatic return toggle status:
Automatic return in 1 hour is set
Radio box status:
Windows is selected
Binary is selected
Single-select scrolling menu status:
Coffee is selected
Multiple-select scrolling menu status:
Peas are selected
Squash is selected
Single-select scrolling menu status:
Beef is selected
Multiple-select scrolling menu status:
Cake is selected
Pie is selected
Username:
dherr1
Password field content:
pass1
Analysis of response() dialog list internal representation fields:
------------------------------------------------------------------
Check box status:
No is checked
Radio box frame status:
Maybe is selected
Right is selected
Less is selected
Option menu status:
Year is selected
popup dialog close status:
popup was not displayed
Time control settings:
hours control is set to 9
minutes control is set to 2
seconds control is set to 22
month control is set to June
day control is set to 19
year control is set to 1996
Automatic return toggle status:
Automatic return in 1 hour is set
Radio box status:
Unix is selected
Autoselect is selected
Single-select scrolling menu status:
Tea is selected
Multiple-select scrolling menu status:
Peas are selected
Carrots are selected
Single-select scrolling menu status:
None is selected
Multiple-select scrolling menu status:
Cookies are selected
Candy is selected
Username:
dherr2
Password field content:
pass2

 


Was this page helpful? Yes No Submitting... Thank you

Comments