PowerScript Reference
PowerScript Functions

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

String ( data {, format } )

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:

dec{2} amount
string = ls_result
amount = 123456.32
ls_result = string(amount,"\*\*\*\*0.00")

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.

String(dw_1.GetItemTime(1, "start_date"))

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

ls_temp = String(long, "address" )
lb_blob = blob(ls_temp) //EncodingUTF16LE! is default
ls_result = string(lb_blob, EncodingANSI!)

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:

String(2002-01-31, "mmm dd, yyyy")

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

Date order_date = 2002-06-11
string date1
date1 = String(order_date,"m-d-yy")

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

Date order_date = 2002-06-11
string date1
SetNull(order_date)
date1 = String(order_date, "m-d-yy;'none'")

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

String(DateTime(2001-01-31, 06:08:00), &
   'mmm dd, yyyy h "hrs and" m "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:

DateTime sys_datetime
string datetime1
sys_datetime = DateTime(Today(), Now())
sle_date.text = String(sys_datetime, &
   "m-d-yy h:mm am/pm;'none'")

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

String(5,"$#,##0.00")

These statements set string1 to 0123:

integer nbr = 123
string string1
string1 = String(nbr,"0000;(000);****;empty")

These statements set string1 to (123):

integer nbr = -123
string string1
string1 = String(nbr,"000;(000);****;empty")

These statements set string1 to ****:

integer nbr = 0
string string1
string1 = String(nbr,"0000;(000);****;empty")

These statements set string1 to "empty":

integer nbr
string string1
SetNull(nbr)
string1 = String(nbr,"0000;(000);****;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:

String("ABC", "@-@-@")

This statement returns A*B:

String("ABC", "@*@")

This statement returns ABC:

String("ABC", "@@@")

This statement returns a space:

String("ABC", " ")

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

String(06:08:02,'h "hrs and" m "min"')

This statement returns 08:06:04 pm:

String(20:06:04,"hh:mm:ss am/pm")

This statement returns 8:06:04 am:

String(08:06:04,"h:mm:ss am/pm")

See also

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

Description

Converts data in a blob to a string value. If the blob's value is not text data, String attempts to interpret the data as characters.

Syntax

String ( blob {,encoding} )

Return value

String.

Returns the value of blob as a string if it succeeds and the empty string ("") if it fails. It the blob does not contain string data, String interprets the data as characters, if possible, and returns a string. If blob is null, String returns null.

Usage

If the encoding argument is not provided, String converts a Unicode blob to a Unicode string. You must provide the encoding argument if the blob has a different encoding.

If the blob has a byte-order mark (BOM), String filters it out automatically. For example, suppose the blob's hexadecimal display is: FF FE 54 00 68 00 69 00 73 00. The BOM is FF FE, which indicates that the blob has UTF-16LE encoding, and is filtered out. The string returned is "This".

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 example converts the blob instance variable ib_sblob, which contains string data in ANSI format, to a string and stores the result in sstr:

string sstr
sstr = String(ib_sblob, EncodingANSI!)

This example stores today's date and test status information in the blob bb. Pos1 and pos2 store the beginning and end of the status text in the blob. Finally, BlobMid extracts a "sub-blob" that String converts to a string. Sle_status displays the returned status text:

blob{100} bb
long pos1, pos2
string test_status
date test_date
 
test_date = Today()
IF DayName(test_date) = "Wednesday" THEN &
   test_status = "Coolant Test"
IF DayName(test_date) = "Thursday" THEN &
   test_status = "Emissions Test"
 
// Store data in the blob
pos1 = BlobEdit( bb, 1, test_date)
pos2 = BlobEdit( bb, pos1, test_status )
 
... // Some processing
 
// Extract the status stored in bb and display it
sle_status.text = String( &
   BlobMid(bb, pos1, pos2 - pos1))

See also

Blob

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