Why typed? In a distributed environment, an application may be installed on heterogeneous systems that communicate across multiple networks using different protocols. Different types of records require different routines to initialize, send and receive messages, and encode and decode data. Each record is designated as a specific type so that the appropriate routines can be called automatically without programmer intervention.
Table 3‑1 lists the typed records supported by the Oracle Tuxedo system and indicates whether or not:
|
•
|
The record is self-describing; in other words, the record data type and length can be determined simply by (a) knowing the type and subtype, and (b) looking at the data.
|
|
|
|
|
|
|
|
|
|
Undefined array of characters, any of which can be LOW-VALUE. This typed record is used to handle the data opaquely, as the Oracle Tuxedo system does not interpret the semantics of the array. Because a CARRAY is not self-describing, the length must always be provided during transmission. Encoding and decoding are not supported for messages sent between machines because the bytes are not interpreted by the system.
|
|
|
|
|
FML (Field Manipulation Language)
|
The FML record uses 16 bits for field identifiers and lengths of fields.
|
|
|
|
|
|
|
Equivalent to FML but uses 32 bits for field identifiers and lengths of fields, which allows for larger and more fields and, consequently, larger overall records.
However, the FML routines that are available for manipulating the FML typed record in the C programming language are not available in COBOL.The primary use of FML32 in COBOL is simply to work with C programs in which VIEW32 or FML32 typed records are used.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
COBOL data structure defined by the application. VIEW types must have subtypes that designate individual data structures. A view description file, in which the fields and types that appear in the data structure are defined, must be available to client and server processes that use a data structure described in a VIEW typed record. Encoding and decoding are performed automatically if the record is passed between machines of different types. Refer to “Using a VIEW Typed Record” on page 3‑7 for more information.
|
|
|
|
|
|
|
Equivalent to VIEW but uses 32 bits for length and count fields, which allows for larger and more fields and, consequently, larger overall records.
The primary use of VIEW32 in COBOL is simply to work with C programs in which VIEW32 or FML32 typed records are used.
|
|
|
|
|
|
|
Equivalent to VIEW, but used for compatibility between COBOL and C programs. Field types should be limited to short, long, and string.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
All record types are defined in a file called tmtypesw.c in the
$TUXDIR/lib directory. Only record types defined in
tmtypesw.c are known to your client and server programs. You can edit the
tmtypesw.c file to add or remove record types. In addition, you can use the
BUFTYPE parameter (in
UBBCONFIG) to restrict the types and subtypes that can be processed by a given service.
The tmtypesw.c file is used to build a shared object or dynamic link library. This object is dynamically loaded by both Oracle Tuxedo administrative servers, and application clients and servers.
|
•
|
tuxtypes(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
|
|
•
|
UBBCONFIG(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
|
The TPTYPE-REC COBOL structure is used whenever sending or receiving application data.
|
|
|
|
|
|
|
|
|
|
|
When data is being sent, specifies the number of bytes to be sent. After a successful transfer, LEN contains the number of bytes transferred. When data is being received, LEN in TPTYPE-REC specifies the number of bytes to be moved into the data record. After a successful call, LEN contains the number of bytes moved into the data record. If the size of the incoming message is larger than the size specified in LEN, the data is truncated, all data after the LEN length is reached is discarded, and TPTYPE-STATUS is set to TPTRUNCATE.
|
There are two kinds of VIEW typed records. The first,
FML VIEW, is a COBOL record generated from an
FML record. The second is simply an independent COBOL record.
The reason for converting FML records into COBOL records and back again (and the purpose of the
FML VIEW typed records) is that FML functions are not available in the COBOL programming environment.
To use VIEW typed records, you must perform the following steps:
To use a VIEW typed record in an application, you must set the following environment variables shown in
Table 3‑2.
To use a VIEW typed record, you must define the COBOL record in a view description file. The view description file includes, a view for each entry, a view that describes the characteristic COBOL procedure mapping and the potential
FML conversion pattern. The name of the view corresponds to the name of the copy file that is included in COBOL program.
Table 3‑3 describes the fields that must be specified in the view description file for each COBOL record.
|
|
|
|
|
Data type of the field. Can be set to short, long, float, double, char, string, or carray.
|
|
|
|
|
|
If you will be using the FML-to- VIEW or VIEW-to- FML conversion routines, 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.
|
|
|
|
|
|
|
|
|
For STRING and CARRAY record types, specifies the maximum length of the value. This field is ignored for all other record types.
|
|
|
User-specified LOW-VALUE value, or minus sign (-) to indicate the default value for a field. LOW-VALUE values are used in VIEW typed records to indicate empty COBOL record members.
The default LOW-VALUE value for all numeric types is 0 (0.0 for dec_t). For character types, the default LOW-VALUE value is ‘ \0’. For STRING and CARRAY types, the default LOW-VALUE value is “ ”.
Constants used, by convention, as escape characters can also be used to specify a LOW-VALUE 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, and LOW-VALUE values in double or single quotes. The view compiler does not accept unescaped quotes within a user-specified LOW-VALUE value.
|
Listing 3‑1 is an excerpt from an example view description file based on an
FML record. 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 3‑2 illustrates the same view description file for an independent
VIEW.
Note that 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.
To compile a VIEW typed record, run the
viewc -C command, specifying the name of the view description file as an argument. To specify an independent
VIEW, use the
-n option. You can optionally specify a directory in which the resulting output file should be written. By default, the output file is written to the current directory.
|
Note:
|
To compile a VIEW32 typed record, run the viewc32 -C command.
|
Listing 3‑3 provides an example of the COBOL
COPY file created by
viewc.
COBOL COPY files for views must be brought into client programs and service subroutines with
COPY statements.
The format of the packed decimal value, DEC1, is composed of five fields. Four fields—
DEC-EXP,
DEC-POS,
DEC-NDGTS, and
FILLER—are used only in C (they are defined in the
dec_t type); they are included in the COBOL record for filler. Do not use these fields in COBOL applications.
The fifth field, DEC-DGTS, is used by the system to store the actual packed decimal value. You should use this value within the COBOL program. ATMI calls operate on the
DEC-DGTS field to:
viewc creates a C version of the header file that you can use to mix C and COBOL service and/or client programs.
The FML interface was designed for use with the C language. For COBOL, routines are provided that allow you to convert a received
FML record type to a COBOL record for processing, and then convert the record back to
FML.
To use FML typed records, you must perform the following steps:
|
•
|
Create an FML header file and specify the header file in a #include statement C routines that share the same view in the application.
|
FML routines are used to manipulate typed records, including those that convert fielded records to C structures and vice versa. By using these functions, you can access and update data values without having to know how data is structured and stored. For more information on
FML routines, refer to the
Oracle Tuxedo ATMI FML Function Reference.
To use an FML typed record in an application program, you must set the following environment variables shown in
Table 3‑4.
$ /* FML structure */
*base value
name number type flags comments
Table 3‑5 describes the fields that must be specified in the
FML field table file for each
FML field.
Listing 3‑4 illustrates a field table file that may be used with the
FML-dependent VIEW example.
An FML typed record must be initialized using the
FINIT procedure. The
TPINIT procedure takes the specified
FML record (preferably aligned on a full-word boundary) and uses the value specified in the
FML-LENGTH field in the
FMLINFO record as the length.
If TPNOCHANGE is set, then any
FML record received by a program (rather than created by the program) is initialized automatically. In this case, it is unnecessary to call
FINIT.
In the preceding listing, the FVSTOF procedure converts an
FML record into a
VIEW record. The view is defined by including the copy file generated by the view compiler. The
FML-REC record provides the
VIEWNAME and the
FML-MODE transfer mode, which can be set to
FUPDATE,
FOJOIN,
FJOIN, or
FCONCAT. The actions associated with these modes are the same as those described in
Fupdate, Fupdate32(3fml),
Fojoin, Fojoin32(3fml),
Fjoin, Fjoin32(3fml), and
Fconcat, Fconcat32(3fml).
The FVFTOS procedure converts a
VIEW record into an
FML record. The parameters are the same as those for an
FVSTOF procedure but you do not need to set
FML-MODE. The system copies the fields from the fielded record into the structure, based on the element descriptions in the view. If there is no corresponding element in the COBOL record for a field in the fielded record, then the system ignores the field. If there is no corresponding field in the fielded record for an element specified in the COBOL record, the system copies a null value into the element. The null value used can be defined for each element in the view description.
For FML32 and
VIEW32, the
FINIT32,
FVSTOF32, and
FVFTOS32 procedures should be used.
In order to use an FML typed record in client programs or service subroutines, you must create an
FML header file and specify it in the application
#include statements.
To create an FML header file from a field table file, use the
mkfldhdr(1) command. For example, to create a file called
myview.flds.h, enter the following command:
For FML32 typed records, use the
mkfldhdr32 command.
Listing 3‑6 shows the
myview.flds.h header file that is created by the
mkfldhdr command.
XXML records enable Oracle Tuxedo applications to use XML for exchanging data within and between applications. Oracle Tuxedo applications can send and receive simple
XML records, and route those records to the appropriate servers. All logic for dealing with
XML documents, including parsing, resides in the application.
An XML document consists of:
The XML parser in the Oracle Tuxedo system performs the following routines:
Data-dependent routing is supported for XML records. The routing of an
XML document can be based on element content, or on element type and an attribute value. The
XML parser determines the character encoding being used; if the encoding differs from the native character sets (US-ASCII or EBCDIC) used in the Oracle Tuxedo configuration files (
UBBCONFIG and
DMCONFIG), the element and attribute names are converted to US-ASCII or EBCDIC.
