STRING function

Converts a value of any data type into a character value.

Syntax

STRING ( source[ , format ] )

source

An expression of any data type that you want to convert to a character value.

format

The format you want to use for the new character value. This format must be appropriate to the data type of source. If you do not use this argument, ABL uses the EXPORT format for all data types (except DATETIME and DATETIME-TZ, in which case it uses the default display format). This is useful if you want to produce left-justified numbers. For information on data display formats, see OpenEdge Getting Started: ABL Essentials.

Example

In the example procedure, the TIME function returns the number of seconds since midnight. The first DISPLAY statement in this procedure uses the STRING function to convert that value into hours and minutes. TIME is the value and "HH:MM AM" is the format used to display the result of the STRING function.

The second DISPLAY statement displays some Customer information. It uses the concatenation (+) operator to join together the values of the City, State, and PostalCode fields. If these fields were not joined together, the spacing would be different for each Customer address depending on the length of the city name.

r-string.p

DISPLAY SKIP(2) "The time is now" STRING(TIME,"HH:MM AM") SKIP(2)
  WITH NO-BOX NO-LABELS CENTERED.
FOR EACH Customer NO-LOCK:
  DISPLAY Customer.Name + "  --" + 
    STRING(Customer.CustNum, ">>>9") FORMAT "x(30)" AT 1
    Customer.Address AT 33
    Customer.City + ", " + Customer.State + " " + Customer.PostalCode 
      FORMAT "x(22)" AT 33 SKIP(1)
    WITH NO-BOX NO-LABELS CENTERED.
END.

When you concatenate character fields, the AVM creates a new character field, at least for the duration of the procedure. The default display format for character expressions such as that resulting from the concatenation is x(8). This means that the AVM allows only 8 spaces for displaying the concatenation of the City, State, and PostalCode fields. The FORMAT x(22) option overrides that default x(8) format, telling the AVM to set aside 22 spaces for displaying the concatenation of the City, State, and PostalCode fields.

Notes

• The STRING function is double-byte enabled. The source argument can contain double-byte data.
• If source is an integer and format begins HH:MM or HH:MM:SS, STRING formats the source as a time. If the hour is greater than or equal to 12 and there is an A or an a in format, STRING subtracts 12 from the hour and converts the A or the a to a P or p (for A.M. and P.M.). The hour 0 is treated as 12 a.m., and noon is treated as 12 p.m. If you use AM/PM format, HH is replaced by a leading blank and a digit if the hour is between 0 and 9.

  If seconds (SS) are not in the format, then the time is truncated to hours and minutes.

• If source is a RAW value, you must specify an appropriate format to return the character string representation.
• When source is a DATETIME or DATETIME-TZ expression, the STRING function converts the expression to a character value in the specified format. If source is a DATETIME expression, and a time zone offset is present in the format string, the character value contains the time zone offset of the session. If source is a DATETIME-TZ expression, and time zone offset is not present in the format string, the character value contains the local date and time relative to the time zone of the DATETIME-TZ value.
• The STRING function converts a DATE, and the date part of a DATETIME or DATETIME-TZ, using the format specified by the DATE-FORMAT attribute or the Date Format (-d) startup parameter.

  For more information about the Date Format (-d) startup parameter, see OpenEdge Deployment: Startup Command and Parameter Reference.

• You can use the STRING function to convert an object reference for a class instance to a character value. The STRING function implicitly calls the ToString( ) method (Object) of the class to convert the specified object reference.
• When applied to an enum instance, the STRING function implicitly calls the ToString( ) method (Object), which returns the name of the enumeration member, or a comma-delimited list of members in the case of a flag enum with multiple flags set. If the flag enum instance has no flags set or an underlying numeric value of 0 and no specific member defined for 0, the function returns the empty string ("").

See also

DECIMAL function, INTEGER function, ToString( ) method (Object)