PUT statement

Sends the value of one or more expressions to an output destination other than the terminal.

Syntax


PUT [ STREAM `stream` \| STREAM-HANDLE `handle` ] [ UNFORMATTED ] [ { `expression` [ FORMAT `string` ] [ { AT \| TO } `expression` ] } \| SKIP [ ( `expression` ) ] \| SPACE [ ( `expression` ) ] ] ...


PUT [ STREAM `stream` \| STREAM-HANDLE `handle` ] CONTROL `expression` ...

STREAM name

Specifies the name of a stream. If you do not name a stream, the AVM uses the unnamed stream. See the DEFINE STREAM statement reference entry and chapter on alternate I/O sources in OpenEdge Development: Programming Interfaces for more information on streams.

STREAM-HANDLE handle

Specifies the handle to a stream. If handle it is not a valid handle to a stream, the AVM generates a run-time error. Note that stream handles are not valid for the unnamed streams. See the chapter on alternate I/O sources in OpenEdge Development: Programming Interfaces for more information on streams and stream handles.

UNFORMATTED

Tells the AVM to display each expression in the same format produced by the EXPORT statement, but without quotes.

expression

Specifies a constant, field name, variable name, or expression.

FORMAT string

The format in which you want to display the expression. If you do not use the FORMAT option, the AVM uses the defaults shown in Table 56.

Table 56: Default display formats
Type of expression	Default format
Field	Format from Dictionary
Variable	Format from variable definition
Constant character	Length of character string
Other	Default format for the data type of the expression

Table 57 shows the default formats for other expressions.

Table 57: Default data type display formats
Data type	Default display format
CHARACTER	x(8)
CLASS³	>>>>>>9
DATE	99/99/99
DATETIME	99/99/9999 HH:MM:SS.SSS
DATETIME-TZ	99/99/9999 HH:MM:SS.SSS+HH:MM
DECIMAL	->>,>>9.99
HANDLE²	>>>>>>9
INT64	->,>>>,>>9
INTEGER	->,>>>,>>9
LOGICAL	yes/no
MEMPTR¹	See the note at the end of the table.
RAW¹	See the note at the end of the table.
RECID	>>>>>>9
ROWID¹	See the note at the end of the table.
You cannot display a MEMPTR, RAW, or ROWID value directly. However, you can convert it to a character string representation using the STRING function and display the result. A ROWID value converts to a hexadecimal string, “0x`hexdigits`,” where `hexdigits` is any number of characters “0" through “9" and “A” through “F”. A MEMPTR or RAW value converts to decimal integer string. To display a HANDLE, you must first convert it using either the INT64 or INTEGER function and display the result. To display a CLASS, you must first convert it using the INT64, INTEGER, or STRING function and display the result.

AT expression

Specifies the column position where you want to place the output value. If that position has already been used on the current line, PUT skips to the next line and puts the expression in the specified column.

TO expression

Specifies the column position where you want to end the output value being output. If that position has already been used on the current line, PUT skips to the next line and puts the expression in the specified column.

SKIP [ ( expression ) ]

Specifies the number of new lines you want to output. If you do not use the SKIP option, PUT will not start a new line to the output stream. If you use the SKIP parameter, but do not specify expression (or if expression is 0), the AVM starts a new line only if output is not already positioned at the beginning of a new line.

SPACE [ ( expression ) ]

Specifies the number of spaces you want to output. Spaces are not placed between items being PUT unless you use the SPACE option.

CONTROL expression

The expression specifies a control sequence that you want to send without affecting the current line, page counters, and positions maintained within ABL. Following CONTROL, expression can be a character-string expression or a RAW variable. It can include null character constants of the form NULL or NULL( expression ), where expression specifies the number of NULLs to send. See the Notes section in this reference entry for details.

Example

This procedure creates a text file that contains the names of each customer. The names are separated from each other by a slash (/). The entire file consists of one long line.

r-put.p
DEFINE STREAM s1. OUTPUT STREAM s1 TO cus.dat. FOR EACH Customer NO-LOCK: PUT STREAM s1 name "/". END. OUTPUT STREAM s1 CLOSE.

Notes

In the AT, TO, SKIP, and SPACE options, if expression is less than or equal to 0, the AVM disregards the option.

The PUT statement never automatically starts a new line. You must use SKIP to explicitly start a new line.

The PUT statement uses the default display format for the data type of the field or variable you name in the PUT statement. The PUT statement does not overwrite an area that is already used by a previous format when it displays data. For example:

DEFINE VARIABLE myname AS CHARACTER NO-UNDO FORMAT "x(8)". DEFINE VARIABLE mynum AS CHARACTER NO-UNDO FORMAT "x(8)". ASSIGN myname = "abc" mynum = "123". OUTPUT TO myfile. PUT myname AT 8 mynum AT 12. OUTPUT CLOSE.

DEFINE VARIABLE myname AS CHARACTER NO-UNDO FORMAT "x(8)". 
DEFINE VARIABLE mynum  AS CHARACTER NO-UNDO FORMAT "x(8)". 
ASSIGN 
  myname = "abc" 
  mynum  = "123". 
OUTPUT TO myfile. 
PUT myname AT 8 mynum AT 12. 
OUTPUT CLOSE.


abc 123

Use the UNFORMATTED option with the PUT statement to override the format-sensitive display.

You can use the NULL keyword to output null characters (\0) in a control sequence. For example, the following statements write the control sequence ESC A \0 and 20 NULLs to output stream A:


PUT STREAM A CONTROL "~033A" NULL. PUT STREAM A CONTROL NULL(20).

You can use the PUT statement with an object reference for a class instance. The PUT statement implicitly calls the ToString( ) method of the class to convert the specified object reference to a character value before it sends the value to the output destination.