swrite - write string to screen field
swrite (field_name, contents)
char *field_name;
char *contents;
Swrite puts the character string pointed to by the contents
parameter into the field named by the field_name parameter. The
field_name parameter is a pointer to the name of the field to be
written. This name must be defined in the current form, and can
be a field name or an edit name in the Field Description form. If
field_name is NULL or points to an empty string, the current
field is used (this is only useful in U_USEREDIT or U_CHANGED
user edit calls). If the field is also a data field in the
current record, then contents will also be stored in the data
record. For data fields that are not character strings, the
contents parameter will be converted to the proper data type
before storing the value into the data record. The contents
parameter must be the character string equivalent of the value to
be written, not the value itself.
Swrite is used for putting a value on the terminal screen, and
also for inserting values into the current data record. Swrite
can write to any field in the current form whether it is
displayed on the terminal screen or not. Thus, swrite can put
values into data fields not accessible to the operator. This is
very helpful for storing calculated values into a data record.
Swrite can write to invisible and display only fields.
Swrite reformats the contents parameter if necessary to display
the value in a standard format on the terminal screen.
It is permissible to rewrite the current data entry field with
swrite when the user edit routine is called with the type
parameter set to U_USEREDIT, U_CHANGED, or U_ENTERFIELD.
Swrite validates the data in the same way as form(C-3)
validates
data typed by the operator. Specifically, validation and lookups
are performed, edit/match formulas are evaluated, the user edit
routine is recursively called (with U_CHANGED), and calculated
fields are evaluated. Your user edit routine must be careful to
avoid infinite recursive swrite loops.
Some examples of using swrite are:
MONEY total;
DATE order_date;
/* zero the amount field */
swrite ("amount", "0");
/* clear the amount field */
swrite ("amount", "");
swrite ("grand_total", moneytoa (total));
swrite ("date", datetoa (order_date));
/* set date to the first of the year */
swrite ("date", "010182");
/* put "NONE" in the current field */
swrite (NULL, "NONE");
In the first example, the value will be reformatted and displayed
as a right-justified string 0.00. The second example will clear
the entire field. The third and fourth example shows how values
must first be converted to a character string before being passed
to swrite. In the fifth example, the date will be reformatted to
01/01/82 before being shown on the terminal screen. In the last
example, "NONE" is written to the current field.
Swrite returns a nonzero value if the operation is successful.
form(C-3)
Chapter 3, Form Programming Guide
DIAGNOSTICS
Swrite returns a zero if the operation is not successful. It
returns a zero value if it could not find the named field or if
the data being written is of the wrong data type. It also returns
a zero value if the contents parameter contains nonprintable
characters.
Swrite is only available in user edit routines.