0001 VIEWFILE(5)
0002 ===========
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 viewfile - Enduro/X VIEW Buffer descriptor file
0009
0010
0011 SYNOPSIS
0012 --------
0013
0014 Formal specification:
0015
0016 ---------------------------------------------------------------------
0017 # First view in the file
0018 VIEW VIEWNAME
0019
0020 FLD_TYPE C_NAME UBF_NAME COUNT FLAGS SIZE NULL_VAL
0021 ...
0022 FLD_TYPE_N C_NAME_N UBF_NAME_N COUNT_N FLAGS_N SIZE_N NULL_VAL_N
0023
0024 END
0025
0026 ...
0027
0028 # N view in the view file
0029 VIEW VIEWNAME_N
0030
0031 ...
0032
0033 END
0034 ---------------------------------------------------------------------
0035
0036 Example view: (test.v):
0037
0038 ---------------------------------------------------------------------
0039 VIEW MYVIEW1
0040 #type cname fbname count flag size null
0041
0042 short tshort1 T_SHORT_FLD 1 FS - 2000
0043 short tshort2 T_SHORT_2_FLD 2 FSC - 2001
0044 short tshort3 T_SHORT_3_FLD 3 FSC - -
0045 short tshort4 - 1 N - NONE
0046
0047 long tlong1 T_LONG_FLD 1 FS - 0
0048 int tint2 T_LONG_2_FLD 2 FS - 0
0049 int tint3 - 1 - - -1
0050 int tint4 - 2 - - -1
0051
0052 char tchar1 T_CHAR_FLD 1 F - '\n'
0053 char tchar2 T_CHAR_2_FLD 5 SC - 'A'
0054 char tchar3 T_CHAR_3_FLD 2 CN - -
0055
0056 float tfloat1 T_FLOAT_FLD 4 FS - 1.1
0057 float tfloat2 T_FLOAT_2_FLD 2 S - -
0058 float tfloat3 - 1 N - 9999.99
0059
0060 double tdouble1 T_DOUBLE_FLD 2 FS - 55555.99
0061 double tdouble2 T_DOUBLE_2_FLD 1 F - -999.123
0062
0063 string tstring0 - 3 - 18 '\n\t\f\\\'\"\vHELLOWORLD'
0064 string tstring1 T_STRING_FLD 3 FSP 20 'HELLO WORLDB'
0065 string tstring2 T_STRING_2_FLD 3 FCL 20 -
0066 string tstring3 T_STRING_3_FLD 4 FSCL 20 'TESTEST'
0067 string tstring4 - 1 P 15 'HELLO TEST'
0068 string tstring5 - 1 - 15 'MEGA TEST'
0069
0070 carray tcarray1 T_CARRAY_FLD 1 FS 30 '\0\n\t\f\\\'\"\vHELLOWORLD'
0071 carray tcarray2 T_CARRAY_2_FLD 1 LFSP 25 '\0\n\t\f\\\'\"\vHELLOWORL\n'
0072 carray tcarray3 T_CARRAY_3_FLD 10 FSCLP 30 '\0\\\nABC\t\f\'\vHELLO'
0073 carray tcarray4 - 1 - 5 'ABC'
0074 carray tcarray5 - 1 - 5 -
0075
0076 END
0077
0078 ---------------------------------------------------------------------
0079
0080 Compiled header output (C language mode):
0081
0082 ---------------------------------------------------------------------
0083 struct MYVIEW1 {
0084 short tshort1; /* null=2000 */
0085 short C_tshort2;
0086 short tshort2[2]; /* null=2001 */
0087 short C_tshort3;
0088 short tshort3[3];
0089 short tshort4; /* null=NONE */
0090 long tlong1; /* null=0 */
0091 int tint2[2]; /* null=0 */
0092 int tint3; /* null=-1 */
0093 int tint4[2]; /* null=-1 */
0094 char tchar1; /* null="\n" */
0095 short C_tchar2;
0096 char tchar2[5]; /* null="A" */
0097 short C_tchar3;
0098 char tchar3[2];
0099 float tfloat1[4]; /* null=1.1 */
0100 float tfloat2[2];
0101 float tfloat3; /* null=9999.99 */
0102 double tdouble1[2]; /* null=55555.99 */
0103 double tdouble2; /* null=-999.123 */
0104 char tstring0[3][18]; /* null="\n\t\f\\\'\"\vHELLOWORLD" */
0105 char tstring1[3][20]; /* null="HELLO WORLDB" */
0106 short C_tstring2;
0107 unsigned short L_tstring2[3];
0108 char tstring2[3][20];
0109 short C_tstring3;
0110 unsigned short L_tstring3[4];
0111 char tstring3[4][20]; /* null="TESTEST" */
0112 char tstring4[15]; /* null="HELLO TEST" */
0113 char tstring5[15]; /* null="MEGA TEST" */
0114 char tcarray1[30]; /* null="\0\n\t\f\\\'\"\vHELLOWORLD" */
0115 unsigned short L_tcarray2;
0116 char tcarray2[25]; /* null="\0\n\t\f\\\'\"\vHELLOWORL\n" */
0117 short C_tcarray3;
0118 unsigned short L_tcarray3[10];
0119 char tcarray3[10][30]; /* null="\0\\\nABC\t\f\'\vHELLO" */
0120 char tcarray4[5]; /* null="ABC" */
0121 char tcarray5[5];
0122 };
0123 ---------------------------------------------------------------------
0124
0125
0126 DESCRIPTION
0127 -----------
0128 View files (usually with extension '.v') describe the data block or structure
0129 which later is generated by 'viewc(8)' binary. The view compiler generate C header
0130 file for view file. Also the compiler generate the 'object-file' with extension
0131 '.V'. The object-file basically is the same view file except it contains platform
0132 specific meta data. For each platform (OS/CPU changes), view file shall be re-
0133 compiled. How ever during the middleware operations, the message view message
0134 produced on one platform is transferable on the other platform. This basically
0135 is the core view feature, so that programmer may operate with C structures, but
0136 the middleware ensures that structure is successfully delivered to the target
0137 system in cross platform way.
0138
0139 View files may describe single element or array of the element (e.g. 'tshort1').
0140 The arrays are supported for STRING and CARRAY fields too. In those cases those
0141 are two dimensional arrays.
0142
0143 For STRING and CARRAY types, length can be specified. The length is given in total
0144 number of bytes. So if you want to store "ABC", you will need to specify 'count'
0145 4, one extra byte for EOS (zero terminator).
0146
0147 The next section describes each of the view file elements.
0148
0149
0150 FLD_TYPE C_NAME FB_NAME COUNT FLAGS SIZE NULL_VAL
0151
0152 VIEW FILE ELEMENTS
0153 ------------------
0154
0155 *FLD_TYPE*::
0156 Field type. This is how the field will be presented in the C structure. Following types
0157 are supported: *short*, *long*, *char*, *float*, *double*, *string* and *carray*.
0158 Carray is a blob, which might contain binary zero byte (0x00).
0159
0160 *C_NAME*::
0161 Field name in c structure. The rule against the field name applies the standard
0162 ones which applies to C variable names. *viewc* accepts max length of the 256
0163 for the C identifier. But actual size is determined by compiler.
0164
0165 *UBF_NAME*::
0166 Optional UBF buffer field name. This is used by *Bvstof(3)* - convert C struct
0167 to UBF buffer. And by *Bvftos(3)* - convert UBF buffer to c structure. If the
0168 setup of the UBF field is not needed, then field can be skipped with "-" (minus
0169 sign in view file). In that case no mappings are processed. During the *Bvstof*
0170 and *Bvftos* invocation. If field is set, then *FLAGS* field changes the logic
0171 how the mapping is processed.
0172
0173 *COUNT*::
0174 This array element count. As in view file each of the c fields can be array,
0175 this defines the behavior. If field is set to *1*, then field is created as
0176 a normal one. If count > 1, then array is defined. The count cannot be less
0177 than 1, in such case view compiler will give an error. For *CARRAY* and *string*
0178 fields, count greater that 1 will create basically two dimensional array,
0179 where one dimension is count and another dimension is size.
0180
0181 *FLAGS*::
0182 There are defined several flags for the view file. For values see the section
0183 bellow. If not flags are set, then value "-" shall be used in view descriptor.
0184 Some options of the flags can be changed in the runtime with *Bvopt(3)*
0185 function.
0186
0187 *SIZE*::
0188 Number of bytes for *string* or *carray* definition. For other field types
0189 it is not valid to be set and will cause *viewc* complication error. For
0190 *string* and *carray* it is mandatory to be set size set. For other types
0191 use value "-".
0192
0193 *NULL_VAL*::
0194 This is NULL value for the field. The NULL value indicates the value when
0195 it can be considered that field is empty. The NULL value is used for following
0196 cases: 1) When transferring data from C to UBF buffer by *Bvstof(3)*. Each
0197 field is tested against NULL value. If field is NULL and the updated mode
0198 *BUPDATE*, then field is not copied to target buffer. In case of multiple
0199 occurrences, the occurrence will be lost if next C array element is not NULL.
0200 To use default NULL specification, use "-" field. Which means 0 for short/long/int.
0201 0.0f for float/double, "" - for string and zero length carray. To encode
0202 special symbols, spaces in the NULL value, use single or double quoted string.
0203 The view compiler recognizes following escape sequences '\0' - for 0x00 byte,
0204 '\n', '\t' , '\f', '\\', "\'", '\"', '\v'. For string NULLs the EOS terminator
0205 0x00 byte is not needed. NULL values are used during the *tpcalloc(3)* operation.
0206 The buffer is initialized with default values by help of the *Bvsinit(3)* function.
0207 To set individual field to the NULL value use *Bvselinit(3)*. To test the
0208 field for NULL value use *Bvnull(3)*. If no NULL value is present for a field
0209 use keyworkd NONE wiht out quotes. In that case no value will be considered NULL.
0210 This will mean that any value will be transfered to UBF. And any value will be
0211 copied over to desination service when doing *tpcall(3)*.
0212
0213 VIEW FLAGS
0214 ----------
0215
0216 *F*::
0217 Map the field from C struct to UBF (will be processed by *Bvstof(3)*).
0218
0219 *S*::
0220 Map the field from UBF to C struct (will be processed by *Bvftos(3)*).
0221
0222 *N*::
0223 Do not perform UBF mappings at all (*Bvstof(3)*, *Bvftos(3)* will skip the
0224 field in the same way as "-" value used for flags.).
0225
0226 *C*::
0227 Flag means generate count indicator for the field. The count field type is
0228 'short'. The count field is made as 'C_' prefix for the C field name.
0229 If other field is named as combination of 'C_' and this field name,
0230 then C compiler will generate error as duplicate member of the structure.
0231 The count field participates during the data transfer to UBF buffer via
0232 *Bvstof(3)*, *Bvftos(3)* commands. For the transfer for to the UBF, the count
0233 will indicate occurrences to transfer. For example 0, will make zero transfer
0234 (buffer will not be setup). The count field participates also in structure
0235 transfer view *tpcall(3)* or other buffer related IPC operation. The actual
0236 data transferred to the target system will depend on count field. The other
0237 elements in target system will be initialized with NULL value, defined in view.
0238 If count field is not set (no *C* flag present), all occurrences will be sent
0239 to the target system. And all occurrences will be copied to the UBF buffer.
0240 When data is transferred from UBF to C structure, then count field is set to
0241 number occurrences are written in the structure. For sample reference,
0242 see 'C_tshort2' field and its original 'tshort2' definition.
0243
0244 *L*::
0245 If this flag is set, then additional length indicator(s) are generated. This
0246 is used to indicate the actual length for the *CARRAY* data, to be written
0247 to UBF buffer. If data is converted fro UBF buffer to C structure, then field
0248 will indicate the number of bytes copied to C structure. In case of strings,
0249 the field is updated only in case when data is copied from UBF to C struct,
0250 in that case it is set to number of bytes written to C struct. When converting
0251 from C to UBF, for strings this length value is ignored and EOS termination
0252 of the string are used for length indication. The length field is produced
0253 as prefix 'L_' for the given field. In the same way as for *C*, there might
0254 be conflict with duplicate field if another field is already as this field
0255 prefixed with 'L_'. The field type is 'unsigned short'. IF *COUNT* is greater
0256 than 1, then length indicators are array of 'unsigned short', because the
0257 length indication must be processed for each of the elements in array.
0258 If *L* flag is not set, then for *carray* full buffer size is copied to UBF
0259 and back. The length plays similar role for C struct data transfer over the
0260 *tpcall(3)* and other IPC operations. Only the number set it length are
0261 transferred to target service for the *CARRAY* fields.
0262
0263 *P*::
0264 Use last char of init value as filler of the rest for the *string or *carray*
0265 fields.
0266
0267 EXAMPLE
0268 -------
0269 See *atmitest/test040_typedview* for sample usage.
0270
0271 BUGS
0272 ----
0273 Report bugs to support@mavimax.com
0274
0275 SEE ALSO
0276 --------
0277 *viewc(8)*, *Bvftos(3)*, *Bvstof(3)*, *Bvsinit(3)*, *Bvselinit(3)*, *Bvnull(3)*,
0278 *Bvopt(3)*, *Bvrefresh(3)*
0279
0280
0281 COPYING
0282 -------
0283 (C) Mavimax, Ltd
0284
