CHARLIST

The CHARLIST function transforms an expression into a multiline text value with a separate line for each value of the original expression.

Return Value

TEXT or NTEXT

The data type of the return value depends on the data type of the expression:

When the expression is TEXT, the return value is TEXT.
When the expression is NTEXT, the return value is NTEXT.
When the expression has a data type other than TEXT or NTEXT, CHARLIST automatically converts its values to TEXT to create the result.

Syntax

CHARLIST(expression [dimensions])

Arguments

expression: The expression to be transformed into a multiline text value.
dimensions: The dimensions of the return value. When you do not specify a dimension, CHARLIST returns a single value. When you provide one or more dimensions for the return value, CHARLIST returns a multiline text value for each value in the current status list of the specified dimension. Each dimension must be an actual dimension of the expression; it cannot be a related or base dimension.

Notes

Creating Lists of Workspace Objects

You can use CHARLIST with the NAME dimension to create lists of workspace objects. Such lists are useful when you want to perform a task on a group of objects. To create a list of objects, limit NAME to the names of the objects in which you are interested (for example, worksheets). You can then use CHARLIST to loop over the NAME dimension and perform the task on each item in this group. You can use CHARLIST in this way with any statement that can take a list of names as its argument. See "Deleting Workspace Objects".

Empty Composites

CHARLIST cannot return values of a variable dimensioned by a composite when you have not assigned any values to the variable. In this case, the variable and the composite are considered to be empty, and CHARLIST returns NA.

Examples

Example 8-44 Deleting Workspace Objects

Suppose you want to delete all objects of a certain type in your workspace, for example, all worksheets. You can use CHARLIST and an ampersand (&) to do this.

LIMIT NAME TO OBJ(TYPE) EQ 'WORKSHEET'
DELETE &CHARLIST(NAME)

Example 8-45 Creating a List of Top Sales People

Assume you have stored the names of the sales people who sold the most for each product in product.memo, a text variable with the dimensions of product and month. You then want to create a list of top sales people broken out by product. To do this, you can create a variable dimensioned by product and then use CHARLIST with the product dimension to create a separate list of all the top sales people for each product.

DEFINE topsales VARIABLE TEXT <product>
topsales = CHARLIST(product.memo product)