sread - read contents of data field


char *
sread (field_name)
char *field_name;


Sread allows the user edit routine to read the contents of a data
field in the current record. The field_name parameter is a
pointer to the name of the field to be read. This name 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). You can refer to a field in a previous form as
formname.fieldname. Sread returns a pointer to a character string
containing the contents of the data field formatted the same as
the data displayed on the screen. Numbers will be right-justified
with decimal places if necessary. Also, date fields read with
sread will return a character string formatted in the standard
date format. If the user edit routine must convert the character
string returned to a numerical value, functions such as
atomoney(C-3) must be used to perform the conversion.

MONEY price;
price = atomoney (sread ("amount"));

Sread can read any field in the current or a previous form
including fields that do not represent data in the current record
and invisible fields. If there are two or more fields in the
current form that have either the data name or the edit name
specified in the sread function call, then the first field found
in field order is the field that is returned.

It is possible for a data field to have two different names. One
name is the field name, and this is the same name as the field in
the data record. The other name is the edit field name, and this
can be any arbitrary name to rename the screen field. This allows
one user edit routine to be used with several formfiles and
several RMSfiles. If a common set of operations must be done for
each of the data files, then the screen fields in each of the
formfiles can be given the same set of edit field names,
regardless of what the data fields might be named. Then the user
edit routine could refer only to the edit names, and thus operate
in the same manner for each of the formfiles and RMSfiles.


Chapter 3, Form Programming Guide


Sread returns a NULL pointer if it is unable to find the
requested screen field. If the requested field is empty, then
sread returns a pointer to a zero length character string.
Trailing blanks are always stripped off of field values returned
by sread.


The value returned by sread points to static storage that is
overwritten with every call. If the value returned is to be
saved, it must be copied to another variable. Specifically, the
following will never work:

sdebug ("time=%s, money=%s", sread("hours"), sread("amount"));

In this example, the sread function is called twice before the
sdebug function is called, and thus the value from the first call
to sread is overwritten.


Sread is only available in user edit routines.