DPL 9 Help

Displaying Formatted Strings (DPL Code)

Displaying Formatted Strings (DPL Code)

The second argument of the display function is optional. It is a string or string literal called a format string. It contains information, plus leading or trailing text, that tells the function how to display the first argument.

   display(ReportTitle,"%-40s\n")

The fundamental parts of the format string are the following:

- Double-quote characters ("). Like a string literal, the format string starts and ends with " characters.

- The characters % and s. The format string needs to contain a conversion specification for the string specified in the first argument. This conversion specification consists of the % character, representing the string in the first argument, followed by a lowercase s (which classifies it as a string).

- Optional formatting information, like the new line character, \n, or specifications of field width. To start a new line after a display, type \n at any point in the argument where you would like a new line. If the format string does not include a new line character, the output will be held in memory until another display statement with a new line specification is executed. This is useful for concatenating output lines.

- To specify a field width for the display of the function's first argument, insert a decimal constant, called the field width, between the % sign and the lowercase s. The function displays its first argument in a field containing at least that number of characters. If the field width is smaller than the number of characters in the string represented by the function's first argument, the function expands the field to display the entire string. If the field is larger than the number of characters in the string, the function right justifies the string or string literal in the field. If the field width is preceded by a minus sign, the function left justifies the string or string literal in the field.

- Leading or trailing text, if desired. Any text between the first " character and the conversion specification is displayed immediately before the function's first argument, whereas any text between the conversion specification and the second " character is displayed immediately after the first argument.

Consider the following clause, which incorporates a field width and the new line specification:

   display(ReportTitle,"2010\n%-40s\nConclusions\n")

This causes the function to display several lines. Some of the text in these lines comes from ReportTitle, and some comes from the format string.

   2010
   Financial Analysis - Western Region
   Conclusions

You could also write a clause that has for its first argument a string literal instead of a string. To simplify formatting specifications that are used repeatedly, it is recommended that you specify formats in the program ahead of time.

   string Format = "%40s\n";
   display("Final Report",Format)

This example uses a format string that is a string called Format, instead of a string literal. The conversion specification in this clause includes the decimal constant 40. This means that the function will display the string literal right justified in a field 40 characters wide. As a result, it displays the following line:

                                  Final Report

The display function, like all other DPL functions, always returns a number, not a string. If the first argument of the display function is a string or string literal, the function returns a 0.

Versions: DPL Professional, DPL Enterprise, DPL Portfolio