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
SEE ALSO
viewc(1),
tpalloc(3c),
Fvftos(3fml),
Fvstof(3fml),
BEA TUXEDO FML Programmer's Guide