Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Doc Home   |   Programming   |   Topic List   |   Previous   |   Next   |   Contents

   Programming a BEA Tuxedo Application Using FML

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

• A line beginning with the keyword VIEW (never with a 32 suffix), followed by the name of the view description. This name may be composed of alphanumeric characters, including an underscore. Although viewc accepts names of up to 33 characters, the practical limit in most cases is 16 characters, since this is the maximum length for a subtype accepted by tpalloc(3c).

• A list of member descriptions.

• 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 or COBOL record. A line with the keyword END must be the last line in a view description.

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

In the previous listing:

• 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. Underscores are mapped automatically to dashes in the COBOL COPY file.

• 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 the value of type is "-", the default-the value of fbname-is used.

• 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. Underscores are mapped automatically to dashes in the COBOL COPY file.

• fbname is the name of the field in the fielded buffer. This name must appear in a field table file.

• count is the number of elements to be allocated (that is, the maximum number of occurrences to be stored for this member). The value of count must be less than or equal to 65,535 for FML, and less than or equal to 2,147,483,647 for FML32.

• flag is a comma-separated list of options or "-" (which means that no options are set). For details, see Specifying flag Options in a View Description.

• size is the size of the member if the type is string, carray, or dec_t. For other types, "-" should be specified; the view compiler computes the size.

  • For string or carray, the value of size must be less than or equal to 65,535 for FML and less than or equal to 2,147,483,647 for FML32.

  • For the dec_t type, the value of size must be two numbers separated by a comma. The first number represents the number of bytes in the decimal value; it must be greater than 0 and less than 10. The second number represents the number of decimal places to the right of the decimal point; it must be greater than 0 and less than twice the number of bytes minus one.

• null is the user-specified null value or "-" to indicate the default null value for that field. For details, see Using Null Values in VIEWS.

Specifying flag Options in a View Description

The following is a list of the options that can be specified as the flag element of a member description in a view description.

C

This option requests the generation of a structure member called the associated count member (ACM), in addition to the structure member described in the member description.

When data is being transferred 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 the ACM of a member 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 in the C header file is declared to be short for FML and long for FML32, 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 is declared as follows:

short C_parts;

For a COBOL COPY file, the name is generated as C-cname and the type is declared as follows:

For FML: PIC S9(4) USAGE COMP-5

For FML32: PIC S9(9) USAGE COMP-5

Note: It is possible for the generated ACM name to conflict with structure members with names that begin with a C_ prefix. Such conflicts are reported by the view compiler, and are considered fatal errors by the compiler. for example, the name C_parts for a structure member conflicts with the name of an ACM generated for the member parts.

F

Specifies one-way mapping from structure or record to fielded buffer. The mapping of a member with this option is effective only when transferring data from structures to fielded buffers. This option is ignored if the -n command-line option is specified.

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. When transferring data from a fielded buffer to a structure, the ALM is set to the length of the corresponding transferred fields. If the length of a field 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 is truncated on transfer.

When data is being transferred 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 because 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 in the C header file as an unsigned short for FML and an unsigned long for FML32, 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). For the COBOL COPY file, the type is declared to be PIC 9(4) USAGE COMP-5 for FML and PIC 9(9) USAGE COMP-5 for FML32, and its name is generated as L-cname. The COBOL OCCURS clause is used to define multiple occurrences if the member occurs multiple times.

Note: It is possible for the generated ALM name to conflict with structure members with names that begin with an L_ prefix. Such conflicts are reported by the view compiler, and are considered fatal errors by the compiler. For example, the name L_parts for a structure member conflicts with the name of an ALM generated for the member parts.

N

Specifies zero-way mapping; no fielded buffer is mapped to the structure. This option can be used to allocate fillers in C structures or COBOL records. It is ignored if the -n command-line option is specified.

P

This option can be used to affect what VIEWS interprets as a null value for string and carray type structure members. 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).

A member whose value is null is not transferred to the destination buffer when data is transferred from the C structure or COBOL record 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 contains the character "e" (that is, 21 e's).

This option is ignored if the -n command-line option is specified.

S

Specifies one-way mapping from fielded buffer to structure or record. The mapping of a member with this option is effective only when transferring data from fielded buffers to structures. This option is ignored if the -n command line option is specified.

Null values are used in VIEWS to indicate empty C structure or COBOL record members. Default null values are provided; 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 the preceding section 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 (carray) members is 2660 characters.

Note: 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.

 

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.