Syntax 1: For formatting data – PB Docs 2021

Description

Formats data, such as time or date values, according to a format
mask. You can convert and format date, DateTime, numeric, and time data.
You can also apply a display format to a string.

Syntax

Return value

String.

Returns data in the specified format if it succeeds and the empty
string (“”) if the datatype of data does not match the type of display
mask specified, format is not a valid mask, or data is an incompatible
datatype.

Usage

For date, DateTime, numeric, and time data, PowerBuilder uses the
system’s default format for the returned string if you do not specify a
format. For numeric data, the default format is the [General]
format.

For string data, a display format mask is required. (Otherwise,
the function would have nothing to do.)

The format can consist of one or more masks:

To display additional characters as part of the mask for a decimal
value, you must precede each character with a backslash. For example, to
display a decimal number with two digits of precision preceded by four
asterisks, you must type a backslash before each asterisk:

The resulting string is ****123456.32.

For more information on specifying display formats, see the section called “Defining display formats” in Users Guide. Note that, although a format can
include color specifications, the colors are ignored when you use String
in PowerScript. Colors appear only for display formats specified in the
DataWindow painter.

If the display format does not match the datatype, PowerBuilder
tries to apply the mask, which can produce unpredictable results.

International deployment

When you use String to format a date and the month is displayed as
text (for example, the display format includes “mmm”), the month is in
the language of the runtime DLLs available when the application is run.
If you have installed localized runtime files in the development
environment or on a user’s machine, then on that machine, the month in
the resulting string is in the language of the localized files.

For information about the localized runtime files, which are
available in French, German, Italian, Spanish, Dutch, Danish, Norwegian,
and Swedish, see the section called “Internationalizing an Application” in Application Techniques.

Handling ANSI data

Since this function does not have an encoding argument to allow
you to specify the encoding of the data, the string returned can contain
garbage characters if the data has ANSI encoding. You can handle this by
converting the ANSI string returned from the String function to a
Unicode blob, and then converting the ANSI string in the blob to a
Unicode string, using the encoding parameters provided in the Blob and
String conversion functions:

Message object

You can also use String to extract a string from the Message
object after calling TriggerEvent or PostEvent. For more information,
see the TriggerEvent or PostEvent functions.

Examples

This statement applies a display format to a date value and
returns Jan 31, 2002:

This example applies a format to the value in order_date and sets
date1 to 6-11-02:

This example includes a format for a null date value so that when
order_date is null, date1 is set to none:

This statement applies a format to a DateTime value and returns
Jan 31, 2001 6 hrs and 8 min:

This example builds a DateTime value from the system date and time
using the Today and Now functions. The String function applies
formatting and sets the text of sle_date to that value, for example,
6-11-02 8:06 pm:

This statement applies a format to a numeric value and returns
$5.00:

These statements set string1 to 0123:

These statements set string1 to (123):

These statements set string1 to ****:

These statements set string1 to “empty”:

This statement formats string data and returns A-B-C. The display
format assigns a character in the source string to each @ and inserts
other characters in the format at the appropriate positions:

This statement returns A*B:

This statement returns ABC:

This statement returns a space:

This statement applies a display format to time data and returns 6
hrs and 8 min:

This statement returns 08:06:04 pm:

This statement returns 8:06:04 am:

See also

String method for DataWindows in the section called “String” in DataWindow Reference.