PURPOSE

viewfile - source file for view descriptions

DESCRIPTION

Viewfiles are source files for descriptions of one or more C data structures, or ``views.'' When used as input to the viewc(1) command, the viewfile forms the basis for a binary file (filename view_filename.V) and a header file (view_filename.h).

The binary .V files are used two ways in TUXEDO System/T:

for programs that use Fvftos(3fml) and Fvstof(3fml), the .V file is interpreted at runtime to effect the mapping between FML buffers and C structures

for programs allocating typed buffers of type VIEW the .V file is searched for a structure of the name provided in the subtype argument of tpalloc(3c)

The .h file must be included in all programs using the view so that structure members can be referenced by their logical names.

VIEW DESCRIPTIONS

Each view description in a source viewfile consists of three parts:

a line beginning with the keyword "VIEW", followed by the name of the view description; the name can have a maximum of 33 characters and must be a valid C identifier (that is, it must start with an underscore or an alphabetic character and contain only alphanumeric or underscore characters); when used with tpalloc(3c), the name can only have a maximum of 16 characters

a list of member descriptions, each line containing 7 fields

a line beginning with the keyword "END"

The first line of each view description must begin with the keyword "VIEW" followed by the name of the view description. A member description (or mapping entry) is a line with information about a member in the C structure. A line with the keyword "END" must be the last line in a view description. Lines beginning with a # are treated as comments and ignored.

Thus, a source view description has this general structure:


VIEW vname
# type   cname   fbname   count   flag   size   null
# ----   -----   ------   -----   ----   ----   ----
--------------member descriptions-------------------
END

In the view description, the variable fields have the following meaning:

vname: is the name of the view description, and should be a valid C identifier name, since it is also used as the name of a C structure.
type: is the type of the member, and is specified as one of the following: int, short, long, char, float, double, string, carray or dec_t; if type is '-', the type of the member is defaulted to the type of fbname if the view is mapped to FML buffers.
cname: is the identifier for the structure member, and should be a valid C identifier name, since it is the name of a C structure member. If the view is mapped to FML buffers, it can not be a valid fbname.
fbname: is the name of the field in the fielded buffer; this name must appear in either a field table file or a field header file. For views not mapped to FML buffers, this field is ignored but must contain a place holder value such as a dash ( - ).
count: is the number of elements to be allocated (that is, the maximum number of occurrences to be stored for this member); must be less than or equal to 65535
flag: is a list of options, optionally separated by commas, or '-' meaning no options are set; see below for a discussion of flag options. For views not mapped to FML buffers, this field may contain the C and/or L options, or must contain a dash ( - ) place holder value
size: is the size of the member if the type is either string or carray; must be less than or equal to 65535. For 32-bit FML, the max size is 2 to the 32nd or several gazillion. For the dec_t type, size is two numbers separated by a comma, the first being the number of bytes in the decimal value (it must be greater than 0 and less than 10) and the second being the number of decimal places to the right of the decimal point (it must be greater than 0 and less than two times the number of bytes minus one). For other field types, '-' should be specified, and the view compiler will compute the size.
null: is the user-specified null value or '-' to indicate the default null value for that field; see below for a discussion of null values.

FLAG OPTIONS

The following is a list of the options that can be specified as the flag element of a member description in a view description. Note that the L and C options generate additional structure members even for views that are not FML-based.

C

This option specifies that an additional structure member, called the associated count member (ACM), be generated, in addition to the structure member described in the member description (even for views that are not FML-based). When transferring data from a fielded buffer to a structure, each ACM in the structure is set to the number of occurrences transferred to the associated structure member. A value of 0 in an ACM indicates that no fields were transferred to the associated structure member; a positive value indicates the number of fields actually transferred to the structure member array; a negative value indicates that there were more fields in the buffer than could be transferred to the structure member array (the absolute value of the ACM equals the number of fields not transferred to the structure). During a transfer of data from a structure member array to a fielded buffer, the ACM is used to indicate the number of array elements that should be transferred. For example, if a member's ACM is set to N, then the first N non-null fields are transferred to the fielded buffer. If N is greater than the dimension of the array, it then defaults to the dimension of the array. In either event, after the transfer takes place, the ACM is set to the actual number of array members transferred to the fielded buffer. The type of an ACM is declared to be short (32-bit long integer for VIEW32), and its name is generated as "C_cname", where cname is the cname entry for which the ACM is declared. For example, an ACM for a member named parts would be declared as follows:


short C_parts;

It is possible for the generated ACM name to conflict with structure members whose names begin with a "C_" prefix. Such conflicts will be reported by the view compiler, and are considered fatal errors by the compiler. For example, if a structure member has the name "C_parts", it would conflict with the name of an ACM generated for the member "parts". Note also that the view compiler will generate structured record definitions for ACM and ALM (see the L option, below) members when you specify the -r command line option.

F

Specifies one-way mapping from structure to fielded buffer (this option is ignored for views that are not FML-based). The mapping of a member with this option is effective only when transferring data from structures to fielded buffers.

L

This option is used only for member descriptions of type carray or string to indicate the number of bytes transferred for these possibly variable length fields. If a string or carray field is always used as a fixed length data item, then this option provides no benefit. The L option generates an associated length member (ALM) for a structure member of type carray or string (even for views that are not FML-based). When transferring data from a fielded buffer to a structure, the ALM is set to the length of the corresponding transferred fields. If a field's length in the fielded buffer exceeds the space allocated in the mapped structure member, only the allocated number of bytes is transferred. The corresponding ALM is set to the size of the fielded buffer item. Therefore, if the ALM is greater than the dimension of the structure member array, the fielded buffer information was truncated on transfer. When transferring data from a structure member to a field in a fielded buffer, the ALM is used to indicate the number of bytes to transfer to the fielded buffer, if it is a carray type field. For strings, the ALM is ignored on transfer, but is set afterwards to the number of bytes transferred. Note that since carray fields may be of zero length, an ALM of 0 indicates that a zero length field should be transferred to the fielded buffer, unless the value in the associated structure member is the null value. An ALM is defined to be an unsigned short (32-bit unsigned long integer for VIEW32), and has a generated name of "L_cname", where cname is the name of the structure for which the ALM is declared. If the number of occurrences of the member for which the ALM is declared is 1 (or defaults to 1), then the ALM is declared as:


unsigned short L_cname;

whereas if the number of occurrences is greater than 1, say N, the ALM is declared as:


unsigned short L_cname[N];

and is referred to as an ALM Array. In this case, each element in the ALM array refers to a corresponding occurrence of the structure member (or field). It is possible for the generated ALM name to conflict with structure members whose names begin with a "L_" prefix. Such conflicts will be reported by the view compiler, and are considered fatal errors by the compiler. For example, if a structure member has the name "L_parts", it would conflict with the name of an ALM generated for the member "parts". Note also that the view compiler will generate structured record definitions for ACM and ALM (see the C option, above) members when you specify the -r command line option.

N

Specifies zero-way mapping, that is, no fielded buffer is mapped to the C structure (this option is ignored for views that are not FML-based). This can be used to allocate fillers in C structures.

P

This option can be used to affect what value is interpreted as a null value for string and carray type structure members (this option is ignored for views that are not FML-based). If this option is not used, a structure member is null if its value is equal to the user-specified null value (without considering any trailing null characters). If this option is set, however, a member is null if its value is equal to the user-specified null value with the last character propagated to full length (without considering any trailing null character). Note that a member whose value is null will not be transferred to the destination buffer when data is transferred from the C structure to the fielded buffer. For example, a structure member TEST is of type carray[25] and a user-specified null value "abcde" is established for it. If the P option is not set, TEST is considered null if the first five characters are a, b, c, d, and e, respectively. If the P option is set, TEST is null if the first four characters are a, b, c, and d, respectively, and the rest of the carray must contain the character 'e' (21 e's).

S

Specifies one-way mapping from fielded buffer to structure (this option is ignored for views that are not FML-based). The mapping of a member with this option is effective only when transferring data from fielded buffers to structures.

NULL VALUES

Null values are used in views to indicate empty C structure members. Default null values are provided, and you may also define your own.

The default null value for all numeric types is 0 (0.0 for dec_t); for char types, it is "\0"; and for string and carray types, it is "".

Escape convention constants can also be used to specify a null value. The view compiler recognizes the following escape constants: ddd (where d is an octal digit), \0, \n, \t, \v, \b, \r, \f, \\, \', and \"\.

String, carray, and char null values may be enclosed in double or single quotes. Unescaped quotes within a user-defined null value are not accepted by the view compiler.

Alternatively, an element is null if its value is the same as the null value for that element, except in the following cases:

if the P option is set for the structure member, and the structure member is of string or carray type; see above for details on the P option flag

if a member is of type string, its value must be the same string as the null value

if a member is of type carray, and the null value is of length N, then the first N characters in the carray must be the same as the null value

You can also specify the keyword "NONE" in the null field of a view member description, which means there is no null value for the member.

The maximum size of default values for string and character array members is 2660 characters.

Note that for string members, which usually end with a "\0", a "\0" is not required as the last character of a user-defined null value.

ENVIRONMENT VARIABLES

VIEWFILES: should contain a comma separated list of object viewfiles for the application. Files given as full pathnames are used as is; files listed as relative path names are searched for through the list of directories specified by the VIEWDIR variable (see below).
VIEWDIR: specifies a colon-separated list of directories where view object files can be found. If VIEWDIR is not set, then its value is taken to be the current directory.

For VIEW32, the environment variable VIEWFILES32 and VIEWDIR32 are used.

EXAMPLES


# BEGINNING OF AN FML-BASED VIEWFILE
VIEW custdb
$/* This is a comment */
#
#type	     cname    fbname count  flag   size    null
#
carray    bug     BUG_CURS  4       -     12     "no bugs"
long      custid  CUSTID    2       -      -      -1
short     super   SUPER_NUM 1       -      -      999
long      youid   ID        1       -      -      -1
float     tape    TAPE_SENT 1       -      -      -.001
char      ch      CHR       1       -      -      "0"
string    action  ACTION    4       -     20      "no action"
END
# BEGINNING OF AN INDEPENDENT VIEWFILE
VIEW viewx
$ /* View structure for viewx information */
#
#type	cname	fbname	count	flag	size	null
#
int	in	-	1	-	-	-
short	sh	-	2	-	-	-
long	lo	-	3	-	-	-
char	ch	-	1	-	-	-
float	fl	-	1	-	-	-
double	db	-	1	-	-	-
string	st	-	1	-	15	-
carray	ca	-	1	-	15	-
END