SWRITE C-3

NAME

swrite - write string to screen field

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:

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)

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.