2.7.2 Creating a View Description File

To use a VIEW typed buffer, you must define the C record in a view description file. The view description file includes, a view for each entry, a view that describes the characteristic C structure mapping and the potential FML conversion pattern. The name of the view corresponds to the name of the C language structure.

The following format is used for each structure in the view description file:

$ /* View structure */
  VIEW viewname
  type    cname     fbname    count    flag    size     null
        

The following table describes the fields that must be specified in the view description file for each C structure.

Table 2-7 View Description File Fields

Field	Description
type	Data type of the field. Can be set to short, long, float, double, char, string, or carray. Note: mbstring data type is supported by the VIEW32 typed buffer only.
cname	Name of the field as it appears in the C structure.
fbname	f you will be using the FML-to-VIEW or VIEW-to-FML conversion functions, this field must be included to indicate the corresponding FML name. This field name must also appear in the FML field table file. This field is not required for FML-independent VIEWs.
count	Number of times field occurs.
flag	Specifies any of the following optional flag settings: P— change the interpretation of the NULL value S— one-way mapping from fielded buffer to structure F— one-way mapping from structure to fielded buffer N— zero-way mapping C— generate additional field for associated count member (ACM) L— hold number of bytes transferred for STRING, CARRAY, and MBSTRING Note: The view32 command automatically adds the L option flag for MBSTRING typed buffers
size	For STRING and CARRAY buffer types, specifies the maximum length of the value. This field is ignored for all other buffer types.
null	User-specified NULL value, or minus sign (-) to indicate the default value for a field. NULL values are used in VIEW typed buffers to indicate empty C structure members. The default NULL value for all numeric types is 0 (0.0 for dec_t). For character types, the default NULL value is ‘\0’. For STRING, CARRAY, and MBSTRING types, the default NULL value is “ ”. Constants used, by convention, as escape characters 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, \r, \f, \\, \’, and \”. You may enclose STRING, CARRAY, MBSTRING, and char NULL values in double or single quotes. The view compiler does not accept unescaped quotes within a user-specified NULL value. You can also specify the keyword NONE in the NULL field of a view member description, which means that there is no NULL value for the member. The maximum size of default values for string and character array members is 2660 characters. For more information, see Oracle Tuxedo ATMI FML Function Reference.

You can include a comment line by prefixing it with the # or $ character. Lines prefixed by a $ sign are included in the .h file.

The following listing is an excerpt from an example view description file based on an FML buffer. In this case, the fbname field must be specified and match that which appears in the corresponding field table file. Note that the CARRAY1 field includes an occurrence count of 2 and sets the C flag to indicate that an additional count element should be created. In addition, the L flag is set to establish a length element that indicates the number of characters with which the application populates the CARRAY1 field.

Listing View Description File for FML VIEW

$ /* View structure */
  VIEW MYVIEW
  #type                       cname                     fbname     count     flag     size     null
  float                       float1                    FLOAT1       1        -        -       0.0
  double                      double1                   DOUBLE1      1        -        -       0.0
  long                        long1                     LONG1        1        -        -        0
  short                       short1                    SHORT1       1        -        -        0
  int                         int1                      INT1         1        -        -        0
  dec_t                       dec1                      DEC1         1        -       9,16      0
  char                        char1                     CHAR1        1        -        -       '\0'
  string                      string1                   STRING1      1        -        20      '\0'
  carray                      carray1                   CARRAY1      2       CL        20      '\0' 
  bool                        bool1                     BOOL1        1        -        -        0
  signedchar               signedchar1                 SIGNEDCHAR1   1        -        -        0
  unsignedchar             unsignedchar1               UNSIGNEDCHAR1 1        -        -        0
  wchar_t                     wchar_t1                   WCHAR_T1    1        -        -        0
  unsignedint              unsignedint1                UNSIGNEDINT1  1        -        -        0
  unsignedlong             unsignedlong1               UNSIGNEDLONG1 1        -        -        0
  longlong                   longlong1                   LONGLONG1   1        -        -        0
  unsignedlonglong         unsignedlonglong1     UNSIGNEDLONGLONG1   1        -        -        0
  longdouble                 longdouble1              LONGDOUBLE1    1        -        -        0
  struct                     struct1                    STRUCT1      1        -        -        0
END

Listing illustrates the same view description file for an independent VIEW.

Listing View Description File for an Independent View

$ /* View data structure */
 VIEW MYVIEW
 #type                     cname             fbname     count     flag     size     null
 float                   float1                 -         1         -        -        -
 double                  double1                -         1         -        -        -
 long                    long1                  -         1         -        -        -
 short                   short1                 -         1         -        -        -
 int                     int1                   -         1         -        -        -
 dec_t                   dec1                   -         1         -       9,16      -
 char                    char1                  -         1         -        -        -
 string                  string1                -         1         -        20       -
 carray                  carray1                -         2         CL       20       -
bool                     bool1
signedchar               signedchar1
unsignedchar             unsignedchar1
wchar_t                  wchar_t1
unsignedint              unsignedint1
unsignedlong             unsignedlong1
longlong                 longlong1
unsignedlonglong         unsignedlonglong1
longdouble               longdouble1
struct struct1
END

Note:

The format is similar to the FML-dependent view, except that the fbname and null fields are not relevant and are ignored by the viewc compiler. You must include a value (for example, a dash) as a placeholder in these fields.