viewfile-source file for view descriptions
Viewfiles are source files for descriptions of one or more C data structures, or \Q\Qviews.'' 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 the BEA TUXEDO system:
Fvftos(3) and Fvstof(3), the .V file is interpreted at runtime to effect the mapping between FML buffers and C structures
The Each view description in a source viewfile consists of three parts:
.h file must be included in all programs using the view so that structure members can be referenced by their logical names.
VIEW Descriptions
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(3), the name can only have a maximum of 16 characters
The first line of each view description must begin with the keyword " Thus, a source view description has this general structure:
In the view description, the variable fields have the following meaning:
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.
VIEW vname
# type cname fbname count flag size null
# ---- ----- ------ ----- ---- ---- ----
--------------member descriptions-------------------
.
.
.
END
vname
type
fbname if the view is mapped to FML buffers.
cname
fbname.
fbname
count
flag
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
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
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.
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.
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.
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 "\"; 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:
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 defaults 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
VIEWDIR variable (see below).
VIEWDIR
VIEWDIR is not set, then its value is taken to be the current directory.
For VIEW32, the environment variable VIEWFILES32 and VIEWDIR32 are used.
# 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
viewc(1), tpalloc(3), Fvftos(3), Fvstof(3), BEA TUXEDO FML Programmer's Guide