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, PocketBuilder 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 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, PocketBuilder 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.

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

The statements in the following table set the string variable string1:

integer nbr = 123

string string1

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

integer nbr = -123

string string1

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

integer nbr = 0

string string1

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

integer nbr

string string1

SetNull(nbr)

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

Example 8

The statements in the following table format string data, assigning a characer in the source string to each @ and inserting other characters in the format at the appropriate positions:

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

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

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

String("ABC", " ")

Example 9

The statements in the following table apply display formats to time data:

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

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

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

Example 10

PocketBuilder allows you to use the String function to convert numeric data to hexadecimal formatting. The statements in the following table apply hexadecimal formatting to the decimal value 12:

String(12,"hex")

String(12,"hex2")

String(12,"hex4")

String(12,"hex8")

See also

• String method for DataWindows in the DataWindow Reference

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 )

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

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 11

This example converts the blob instance variable ib_sblob, which contains string data, to a string and stores the result in sstr:

string sstr

sstr = String(ib_sblob)

Example 12

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

• String method for DataWindows in the DataWindow Reference

---

Copyright © 2007. Sybase Inc. All rights reserved.

View this document as PDF