String

String has two syntaxes.

Syntax 1 For formatting data

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

Returns

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:

• Formats for date, DateTime, string, and time data can include one or two masks. The first mask is the format for the data; the second mask is the format for a null value.

• Formats for numeric data can have up to four masks. A format with a single mask handles both positive and negative data. If there are additional masks, the first mask is for positive values, and the additional masks are for negative, zero, and null values.

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 PowerBuilder 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 the chapter on internationalization 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

Example 1

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

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

Example 2

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

Example 3

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'")

Example 4

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"')

Example 5

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'")

Example 6

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

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

Example 7

These statements set string1 to 0123:

integer nbr = 123

string string1

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

Example 8

These statements set string1 to (123):

integer nbr = -123

string string1

string1 = String(nbr,"000;(000);****;empty")

Example 9

These statements set string1 to ****:

integer nbr = 0

string string1

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

Example 10

These statements set string1 to "empty":

integer nbr

string string1

SetNull(nbr)

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

Example 11

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", "@-@-@")

Example 12

This statement returns A*B:

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

Example 13

This statement returns ABC:

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

Example 14

This statement returns a space:

String("ABC", " ")

Example 15

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"')

Example 16

This statement returns 08:06:04 pm:

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

Example 17

This statement returns 8:06:04 am:

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

See also

• String method for DataWindows in the DataWindow Reference or online Help

Syntax 2 For blobs

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

Returns

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

Example 18

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

Example 19

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 DataWindow Reference or online Help

---

Copyright © 2008. Sybase Inc. All rights reserved.

View this document as PDF