@PickList (Formula Language)

Displays a modal window that contains either:

A view you specify from which the user can select one or more documents. @PickList returns a column value from the selected document(s).
A dialog box, displaying information from all available Domino® Directories. The user can select one or more person, group, server, room, or resource names, and @PickList returns those names.

Syntax

@PickList( [CUSTOM] : [SINGLE] ; server : file ; view ; title ; prompt ; column ; categoryname )

@PickList( [NAME] : [SINGLE] [; selectedoptions ])

@PickList( [ROOM] )

@PickList( [RESOURCE] )

@PickList( [FOLDERS] : [SINGLE] ; server:database )

@PickList( [FOLDERS] : [SHARED] ; server:database )

@PickList( [FOLDERS] : [PRIVATE] ; server:database )

@PickList( [FOLDERS] : [NODESKTOP] ; server:database )

Parameters

[CUSTOM]

Keyword. Indicates that you want to display a view in a dialog box.

[NAME]

Keyword. Opens dialog box for selecting one or more names.

[SINGLE]

Keyword. Optional. Limits the selection to a single document.

[ROOM]

Keyword. Opens dialog box for selecting room.

[RESOURCE]

Keyword. Opens dialog box for selecting resources.

[FOLDERS]

Keyword. Returns a multi-select, text list of all folder names both in the database and from the desktop. The following keywords can be combined with [Folders]:

[SINGLE]

Keyword. Optional. Limits selection to a single folder.

[SHARED]

Keyword. Optional. Limits selection to only shared folders.

[PRIVATE]

Keyword. Optional. Limits selection to only private folders (both in the database and on the desktop).

[SHARED]:[PRIVATE]

Keyword. Optional. Includes in selection all shared and private folders.

[NODESKTOP]

Keyword. Optional. Excludes folders in the desktop from selection.

selectedoptions

Text list. Optional. Pre-selects options.

server : file

Text list. The server is the name of the server where the database is. The file is the path and file name of the database you want to open. Specify the name and location of the database using the appropriate format for the operating system.

You can use a replica ID in place of a server and file name as the parameter following the [custom] keyword only. The replica ID must be text and must include the colon between the two sets of eight hex digits. For example:

@PickList([CUSTOM]; "852564A0:006B7872"; "By Category"; "Testing replica ID"; "Test prompt"; 3)

Use "" to specify the currently open database.

view

Text. The name of the view that you want to open in the database.

title

Text. The window title for the dialog box.

prompt

Text. The prompt that you want to appear inside the dialog box. Only one line of text is displayed. Longer lines are truncated.

column

Number. A number indicating which column value you want @PickList to return. Use 1 to indicate the first column, 2 to indicate the second column, and so on. Unlike @DbColumn and @DbLookup, @PickList counts all columns, regardless of the types of formula they contain.

categoryname

Note: This parameter is new with Release 5.

Text. Optional. Displays the specified category in the view. The view should be categorized in order to use this parameter.

Return value

columnValue

Text list. The value(s) in the specified column for the document(s) that the user selected.

Usage

This function is useful in button, manual agent, paste agent, form action, and view action formulas. It does not work in column, selection, mail agent, scheduled agent, hide-when, window title, or form formulas.

Although @PickList([CUSTOM]) operates similarly to @DbColumn and @DbLookup, @PickList is preferable because it:

Stores more data
Performs the lookup faster
Allows you to quickly locate the desired document by typing the first few characters

@PickList doesn't offer a NoCache option like @DbColumn and @DbLookup because lookup results are never stored. Each time @PickList is executed, a new lookup is performed.

For a calendar view, @PickList displays two days starting with today, without time slots. The user can click on the date picker button to navigate to other days.

You cannot use this function in Web applications.

@PickList can return no more than 64K bytes of data. Use the following equations to determine how much of your data can be returned using @PickList.

For lookups that return text:

2 + (2 * number of entries returned) + total text size of all entries

For lookups that return numbers or dates:

(10 * number of entries returned) + 6

However, @PickList can access a view of any size, so there are no limits to the number of choices it can present. Only the return value is limited in size.

Examples

This formula displays the Products view of PROD.NSF in a dialog box. If the user selects a Staple remover and Stapler from the products view, the temporary variable choice gets assigned the following text list: Staple remover; Stapler
```
choice:=@PickList( [CUSTOM] ; "" ; "Products" ; "Select a product" ; "Please select the products you want to order" ; 1 );
```
This formula achieves the same result as the preceding one, but uses @DbName to display the Products view of the current database.
```
choice:=@PickList( [CUSTOM] ; @DbName ; "Products" ; "Select a product" ; "Please select the products you want to order" ; 1 );
```
This formula also displays the Products view of the current database, but returns the contents of the second column in the view.
```
choice:=@PickList( [CUSTOM] ; @DbName ; "Products" ; "Select a product" ; "Please select the products you want to order" ; 2 );
```

This formula is the same as the preceding one but limits the selection to a single document.

choice:=@PickList( [CUSTOM] : [SINGLE] ; @DbName ; "Products" ; "Select a product" ; "Please select the products you want to order" ; 2 );

This formula opens the By Category view of the current database and displays only the items in the Leather category.

choice:=@PickList( [CUSTOM] ; "" ; "By Category" ; "Select a product" ; "Please select the products you want to order" ; 5;  "Leather");

This formula displays the Names dialog box. The names of the people, groups, or servers that the user selects are placed in the person field on the current document.
```
FIELD person:=person;
@SetField( "person"; @PickList( [NAME] ) )
```
This formula displays the Names dialog box, with the current value of myNames preselected. The names of the people the user selects are placed in the myNames field on the current document.
```
FIELD myNames := @PickList([NAME]; myNames)
```