Set_Field_Value

Purpose

To set the value of a column for the current record of a database table.

Syntax

Set_Field_Value
    table_num
    column_num
    to
    new_value
    ;
    [length data_length
    [offset data_offset
    [no_clear_eol]]]

Argument Explanation

table_num: The number used to open the table.
column_num: The number of the column.
new_value: The value to be put into the column. Can be any simple data type or UChar[].
data_length: The length of the data to be used. By default, all data (or as much as can be) is written into the column. A value of 0 causes all data to be written.
data_offset: The first byte in the column where data will be written, starting from 0. Default is that data will be written into the column starting at Byte 0.
no_clear_eol: Whether the column is cleared before new_value is set. The value can be True, which does not clear the column, or False, which clears. The default value is False.

What It Does

Database tables from DBMSes other than DataFlex do not in all cases support the tablename.column construct by which DataFlex database tables are customarily addressed. This command is capable of addressing such tables by their table and column numbers. It can be used in the same manner on DataFlex tables as well.

Set_Field_Value sets the value of a column to new_value, doing any type conversion necessary. The data will be put into the record buffer for the specified table and column, replacing the current record's data, if any.

You can also specify how much of new_value will be put into the column with the data_length parameter, and where to put it (how many bytes from the beginning of the column) with the data_offset parameter.

Set_Field_Value 3 5 to "abcdefgh" length 3 offset 4 True

In the above example, only the first 3 bytes of the string abcdefgh will be put into the fifth column. They will be put in the 5th - 7th positions of the column (remember that the numbering starts at 0). If the column previously contained the string 305.238.0012, it will now contain 305.abc.0012.

Set_Field_Value 3 5 to "abcdefgh" length 3 offset 4

This example behaves just as the previous one, except that no_clear_eol is set to False by default. If the column previously contained 305.238.0012, it will now contain 305.abc.

Working with UChar Arrays

The Set_Field_Value command can be passed a UChar array and it will write the entire array to the table's column buffer. This can be used in place of a string variable and has the advantage that you don't have to worry about maximum string size and you don't have to concern yourself with embedded zeros.

If the variable passing the data is a UChar array, it will write each byte of the array to the table buffer.

Procedure WriteToTable UChar[] PDFManual
    Set_Field_Value Product.File_Number (RefTable(Product.PdfManual)) to PDFManual
End_Procedure

Notes

This command is useful when dealing with text and binary columns. Data can be inserted anywhere within the variable by using the data_offset parameter.

All type conversion is done automatically. For example, if you are setting the value of a Date column, you can use string manipulation:

// This example sets the current record of table Number 3,
// column Number 3 (assumed to be a Date column) to 1/12/2016.
Set_Field_Value 3 3 to "1/12/2016"

When you use the data_offset parameter with a non-ASCII type column (e.g., Number or Date), the contents of the column are converted to a string, the data is inserted, and then the final string is converted back to the original type and put back into the record buffer.
```
// If the column currently contains the date
// 11/12/2016,
// this statement will reset it to
// 11/11/2016.
Set_Field_Value 3 3 to "11" length 0 offset 3 True
```