Storages & Files SFField object

See also object creation information - ClassID/ProgID 

SFField object, together with SFRecord and SFFilter defines a record of values of well-known types. This record then could be saved or read to/from any binary stream or file. The effect is a technique very similar to the technique used with the DB tables but applicable for files, memory blocks and anything else that resembles stream of bytes. If you ever heard/used to the so called flat files or files with random access - this is the way a script application such as ASP page could access them.

Fields have properties that define their type and size. The size is applicable only for types with variable size - such as strings (the only type that supports size in version 2.0). The SFFiled object describes the type of the value in COM terms or also we can say in automation terms. The representation of the field in the stream may differ depending on the filter (SFFilter) used and its settings. Therefore the application defines the records and their fields in a way convenient for itself and only "instructs" the filter how to read or write them. This allows support for different formats without need to change nothing else than the filter settings or the filter object used.

Record definition members
Value (default) Access field's value. Read/write default property. Syntax:
field_object.Value = variable
variable = field_object.Value

most often the SFField object is part of a record (SFRecord). Thus if the r is a SFRecord object its fields will be referred like this:
r("Field name").Value = variable
variable = r("Field name").Value

or even shorter syntax based on the fact the Value is default property:
 r("Field name") = variable
variable = r("Field name")

When assigning value to a field it is converted to the type configured with the field object. The SFField object is configured through the  Type and Size properties. Therefore the value kept in the field is not the value assigned but the result of its conversion to the configured type (and size if applicable). For example if the field is configured to keep a string with length 30 characters the assigned strings will be truncated if they are bigger.

The field's value cannot be set or read if the field is not yet configured. In other words the error will occur if the Type/size parameters are not set earlier. The field setup is done automatically if it is implicitly created and configured through the SFRecord's AddField method.

Name Get/Set the name of the field. The name of the field object takes effect if it is part of a record. Usually there is no need to set the name if the SFRecord.AddField method is used to create and add the field to a record. However if certain application prefers to create the fields, configure them and then add them to the record - the application should take care to name them as appropriate for its purposes. 
Type Get/Set the type of the field. Specifies the type of the value that will be kept in the field. Most types do not require Size setting because they have well-known size defined by the COM standards. The property accepts numeric values identical to the COM VT_XXX constants. They are also available in many languages - for example in VB and VBScript you can use vbLong, vbByte, vbInt and so on. If you prefer independent constant names include the naxp1vbs.asp or naxp1js.asp files and use the type constants defined there.

If you want to read/write some popular binary file formats through SFRecord/SFFiled we strongly recommend reading the VARIANTARG articles in MSDN.

Note that setting the type will remove the current value of the field.

Exclude Get/Set exclude flag (exclude the field from read/write operations without removing it from the record). This property is important only if the field is part of a record and allows the application to exclude the field from the actual record structure that will be read/written without removing the field. Can be useful if the application manipulates almost similar records in different streams for example. Default is false.
Size Size of the field (if applicable for the Type specified). Currently this value is applicable only for strings (VT_BSTR, vbString) and limits the string size.
Clear Clear all the settings except the field name.


One single SFField object should be part of only one record but it is possible to achieve interesting results by attaching a given field object to more than one record at a time (using the SFRecord.Add method). If you think such a technique will be useful in your application note that the field's name is kept in the field itself. The same is true for the exclude property and the type. We do not recommend this technique but there are certain applications where it may help to minimize the code drastically. For example conversion from one file format (record format) to another. In this case some fields will be different in the both records but you can use common field objects for the same fields - this will allow the application to avoid the copy operations and just read from the first and write to the second stream. The developers should be careful about the order of the read/write and the navigation operations.

Supported on:

Windows 95/NT and later
Windows CE 3.0 and later
Pocket PC/Windows Mobile 2003 and later
Windows CE.NET 4 and later