User Defined Data Types
User-Defined Data Types
This chapter explains how to create fields with custom data types and fill them with data that has a structure of your own definition. Examples of such data include:
- Graphics formats that Domino and Notes do not understand
- Time stamps with a non-Domino time structure
- Encrypted data that uses your own encryption scheme
- Arbitrary data structures (created by any application) that you wish to store in a Domino database
Domino and Notes allow user-defined fields by assigning them to a new Domino data type called TYPE_USERDATA, explained in the next section. For more information, also see the sample program MISC\USER_DEF.
Structure of a User-Defined Data Type
The structure of a user-defined field is:
- BYTE descrip_len; /* length of the type description string */
char type_descrip[descrip_len]; /* type description string */
BYTE data[data_len]; /* the user-defined data */
The first byte contains the length of the type description string that follows. Since the number occupies one byte, the length may be from 0 to 255.
Domino and Notes make no attempt to interpret the type description string, but you should use this string to distinguish various data types that you create. You should make the description long enough that it will not accidentally be confused with someone else's data type. For example, "Acme Corp. Special Password" is a good type description string. "My Data" is not a good description, since someone else might use the same string.
You can store any data at all in the data portion of a user-defined field. Domino and Notes make no attempt to interpret the data or its structure.
The overall length of a single field must be less than 64 kilobytes. If you need to set the ITEM_SUMMARY flag, the field must be less than 15 kilobytes. You can have multiple fields with the same name and type description string. You can also have multiple TYPE_USERDATA fields with different field names and description strings.
You can retrieve documents containing TYPE_USERDATA fields just as you can any other documents. You can use either a sequential search (NSFSearch) or an indexed search (NIFOpenCollection and NIFReadEntries).
When you are creating a field of any type (including TYPE_USERDATA) you must decide whether to set the field's flag to ITEM_SUMMARY. Only fields with ITEM_SUMMARY set can be used in a view selection formula or an NSFSearch formula. If you need to set the ITEM_SUMMARY flag, you must keep the length of the field small (less than 15 kilobytes) because Domino and Notes impose a maximum of 15 kilobytes of summary data per note. If you do not plan to use these operations on the field, you may omit this flag.
At the Notes user interface, the only way you can see TYPE_USERDATA fields is to select File - Document Properties and then select the Fields tab. You cannot see them from a form or in a view. Since Domino and Notes can not interpret the data in a field of type TYPE_USERDATA, you cannot generally refer to fields of this type in formulas in form fields, view columns, or macros. However, if the ITEM_SUMMARY flag is set, the function @IsAvailable returns TRUE.