Programming an Oracle Tuxedo Application Using COBOL

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Managing Typed Records

This topic includes the following sections:

 


Overview of Typed Records

In order to send data to another application program, the sending program first places the data in a record. Oracle Tuxedo ATMI clients use typed records to send messages to ATMI servers. The term “typed record” refers to a pair of COBOL records: a data record and an auxiliary type record. The data record is defined in static storage and contains application data to be passed to another application program. An auxiliary type record accompanies the data record. It specifies the interpretation and translation rules of the data record to be used by the Oracle Tuxedo system when passing the information between heterogeneous systems. Typed records make up one of the fundamental features of the distributed programming environment supported by the Oracle Tuxedo system.

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:

If any routing routines are required, the application programmer must provide them as part of the application.Records.

Table 3-1 Typed Buffers 
Typed Record
Description
Self-
Describing
Subtype
Data-
Dependent Routing
Encoding/
Decoding
CARRAY
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.
No
No
No
No
FML (Field Manipulation Language)
Proprietary Oracle Tuxedo system type of self-describing record in which each data field carries its own identifier, an occurrence number, and possibly a length indicator. T record offers data-independence and greater flexibility
The FML record uses 16 bits for field identifiers and lengths of fields.
Refer to Using an FML Typed Record for more information.
Yes
No
Yes
Yes
FML32
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.
Refer to Using an FML Typed Record for more information.
Yes
No
Yes
Yes
STRING
Array of characters that terminates with a LOW-VALUE character. The Oracle Tuxedo system can convert data automatically when data is exchanged by machines with different character sets.
No
No
No
No
VIEW
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 for more information.
No
Yes
Yes
Yes
VIEW32
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.
Refer to Using a VIEW Typed Record for more information.
No
Yes
Yes
Yes
X_COMMON
Equivalent to VIEW, but used for compatibility between COBOL and C programs. Field types should be limited to short, long, and string.
No
Yes
Yes
Yes
XML
An XML document that consists of:
  • Text, in the form of a sequence of encoded characters
  • A description of the logical structure of the document and information about that structure
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(5) and DMCONFIG(5)), the element and attribute names are converted to US-ASCII or EBCDIC. Refer to Using an XML Typed Record for more information.
No
No
Yes
No
X_OCTET
Equivalent to CARRAY.
No
No
No
No

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.

See Also

 


Defining Typed Records

The TPTYPE-REC COBOL structure is used whenever sending or receiving application data.

The following table lists the TPTYPE-REC structure fields.

Field
Description
REC-TYPE
Specifies which record type the application wishes to send or receive.
SUB-TYPE
Specifies the subtype of the record type, if further classification is required (as it is, for example, in a VIEW record).
LEN
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.

The following shows the TPTYPE data structure:

05 REC-TYPE PIC X(8).
88 X-OCTET VALUE “X_OCTET”.
88 X-COMMON VALUE “X_COMMON”.
05 SUB-TYPE PIC X(16).
05 LEN PIC S9(9) COMP-5.
88 NO-LENGTH VALUE 0.
05 TPTYPE-STATUS PIC S9(9) COMP-5.
88 TPTYPEOK VALUE 0.
88 TPTRUNCATE VALUE 1.

 


Using a VIEW Typed Record

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.

For more information on the FML typed record, refer to the Oracle Tuxedo ATMI FML Function Reference.

To use VIEW typed records, you must perform the following steps:

Setting Environment Variables for a VIEW Typed Record

To use a VIEW typed record in an application, you must set the following environment variables shown in Table 3-2.

Table 3-2 Environment Variables for a VIEW Typed Record
Environment Variable
Description
FIELDTBLS or FIELDTBLS32
Comma-separated list of field table filenames for FML or FML32 typed records. Required only for FML VIEW types.
FLDTBLDIR or FLDTBLDIR32
Colon-separated list of directories to search for the field table files for FML and FML32 typed records. For Microsoft Windows, use a semicolon-separated list. Required only for FML VIEW types.
VIEWFILES or VIEWFILES32
Comma-separated list of allowable filenames for VIEW or VIEW32 description files.
VIEWDIR or VIEWDIR32
Colon-separated list of directories to search for VIEW or VIEW32 files. For Microsoft Windows, use a semicolon-separated list.

Creating a View Description File

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.

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

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

Table 3-3 describes the fields that must be specified in the view description file for each COBOL record.

Table 3-3 View Description File Fields 
Field
Description
type
Data type of the field. Can be set to short, long, float, double, char, string, or carray.
cname
Name of the field as it appears in the COBOL record.
fbname
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.
count
Number of times field occurs.
flag
Specifies any of the following optional flag settings:
  • P—change the interpretation of the LOW-VALUE value
  • S—one-way mapping from fielded record to structure
  • F—one-way mapping from structure to fielded record
  • N—zero-way mapping
  • C—generate additional field for associated count member (ACM)
  • L—hold number of bytes transferred for STRING and CARRAY
size
For STRING and CARRAY record types, specifies the maximum length of the value. This field is ignored for all other record types.
null
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.
You can also specify the keyword NONE in the LOW-VALUE field of a view member description, which means that there is no LOW-VALUE value for the member. The maximum size of default values for string and character array members is 2660 characters. For more information, refer to the 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.

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-1 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'
END

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

Listing 3-2 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 -
END

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.

Executing the VIEW Compiler

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.

For example, for an FML-dependent VIEW, the compiler is invoked as follows:

viewc -C myview.v
Note: To compile a VIEW32 typed record, run the viewc32 -C command.

For an independent VIEW, use the -n option on the command line, as follows:

viewc -C -n myview.v

The output of the viewc command includes:

Listing 3-3 provides an example of the COBOL COPY file created by viewc.

Listing 3-3 COBOL COPY File Example
*    VIEWFILE: "myview.v"
* VIEWNAME: "MYVIEW"
05 FLOAT1 USAGE IS COMP-1.
05 DOUBLE1 USAGE IS COMP-2.
05 LONG1 PIC S9(9) USAGE IS COMP-5.
05 SHORT1 PIC S9(4) USAGE IS COMP-5.
05 FILLER PIC X(02).
05 INT1 PIC S9(9) USAGE IS COMP-5.
05 DEC1.
07 DEC-EXP PIC S9(4) USAGE IS COMP-5.
07 DEC-POS PIC S9(4) USAGE IS COMP-5.
07 DEC-NDGTS PIC S9(4) USAGE IS COMP-5.
* DEC-DGTS is the actual packed decimal value
07 DEC-DGTS PIC S9(1)V9(16) COMP-3.
07 FILLER PIC X(07).
05 CHAR1 PIC X(01).
05 STRING1 PIC X(20).
05 FILLER PIC X(01).
05 L-CARRAY1 OCCURS 2 TIMES PIC 9(4) USAGE IS COMP-5.
* LENGTH OF CARRAY1
05 C-CARRAY1 PIC S9(4) USAGE IS COMP-5.
* COUNT OF CARRAY1
05 CARRAY1 OCCURS 2 TIMES PIC X(20).
05 FILLER PIC X(02).

COBOL COPY files for views must be brought into client programs and service subroutines with COPY statements.

In the previous example, the compiler includes FILLER files so that the alignment of fields in COBOL code matches the alignment in C code.

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:

The only restriction is that a COBOL program cannot directly pass a record to a C function outside of the ATMI interface because the decimal formats in the COBOL program and C function do not match.

Finally, note that the sample COBOL COPY file includes an L-CARRAY1 length field that occurs twice, once for each occurrence of CARRAY1, and a C-CARRAY1 count field.

viewc creates a C version of the header file that you can use to mix C and COBOL service and/or client programs.

See Also

 


Using an FML Typed Record

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:

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.

Setting Environment Variables for an FML Typed Record

To use an FML typed record in an application program, you must set the following environment variables shown in Table 3-4.

Table 3-4 FML Typed Record Environment Variables
Environment Variable
Description
FIELDTBLS or FIELDTBLS32
Comma-separated list of field table filenames for FML or FML32 typed records, respectively.
FLDTBLDIR or FLDTBLDIR32
Colon-separated list of directories to search for the field table files for FML and FML32, respectively. For Microsoft Windows, use a semicolon-separated list.

Creating a Field Table File

Field table files are always required when FML records and/or FML-dependent VIEWs are used. A field table file maps the logical name of a field in an FML record to a string that uniquely identifies the field.

The following format is used for the description of each field in the FML field table:

$ /* 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.

Table 3-5 Field Table File Fields
Field
Description
*base value
Specifies a base for offsetting subsequent field numbers, providing an easy way to group and renumber sets of related fields. The *base option allows field numbers to be reused. For a 16-bit record, the base plus the relevant number must be greater than or equal to 100 and less than 8191. This field is optional.

Note: The Oracle Tuxedo system reserves field numbers 1-100 and 6000-7000 for internal use. Field numbers 101-8191 are available for application-defined fields with FML; field numbers 101-33, 554, and 431, for FML32.

name
Identifier for the field. The value must be a string of up to 256 characters, consisting of alphanumeric and underscore characters only.
rel-number
Relative numeric value of the field. This value is added to the current base, if specified, to calculate the field number.
type
Type of the field. This value can be any of the following: char, string, short, long, float, double, or carray.
flag
Reserved for future use. A dash (-) should be included as a placeholder.
comment
Optional comment.

All fields are optional, and may be included more than once.

Listing 3-4 illustrates a field table file that may be used with the FML-dependent VIEW example.

Listing 3-4 Field Table File for FML VIEW
# name       number    type     flags   comments
FLOAT1 110 float - -
DOUBLE1 111 double - -
LONG1 112 long - -
SHORT1 113 short - -
INT1 114 long - -
DEC1 115 string - -
CHAR1 116 char - -
STRING1 117 string - -
CARRAY1 118 carray - -

Initializing a Typed Record

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.

Listing 3-5 shows how to perform an initialization.

Listing 3-5 FML/VIEW Conversion
WORKING-STORAGE SECTION.
*RECORD TYPE AND LENGTH
01 TPTYPE-REC.
COPY TPTYPE.
*STATUS OF CALL
01 TPSTATUS-REC.
COPY TPSTATUS.
* SERVICE CALL FLAGS/RECORD
01 TPSVCDEF-REC.
COPY TPSVCDEF.
* TPINIT FLAGS/RECORD
01 TPINFDEF-REC.
COPY TPINFDEF.
* FML CALL FLAGS/RECORD
01 FML-REC.
COPY FMLINFO.
*
*
* APPLICATION FML RECORD - ALIGNED
01 MYFML.
05 FBFR-DTA OCCURS 100 TIMES PIC S9(9) USAGE IS COMP-5.
* APPLICATION VIEW RECORD
01 MYVIEW.
COPY MYVIEW.
.....
* MOVE DATA INTO MYVIEW
.....
* INITIALIZE FML RECORD
MOVE LENGTH OF MYFML TO FML-LENGTH.
CALL "FINIT" USING MYFML FML-REC.
IF NOT FOK
MOVE "FINIT Failed" TO LOGMSG-TEXT
PERFORM DO-USERLOG
PERFORM EXIT-PROGRAM
END-IF.
* Convert VIEW to FML Record
SET FUPDATE TO TRUE.
MOVE "MYVIEW" TO VIEWNAME.
CALL "FVSTOF" USING MYFML MYVIEW FML-REC.
IF NOT FOK
MOVE "FVSTOF Failed" TO LOGMSG-TEXT
PERFORM DO-USERLOG
PERFORM EXIT-PROGRAM
END-IF.
* CALL THE SERVICE USING THE FML RECORD
MOVE "FML" TO REC-TYPE IN TPTYPE-REC.
MOVE SPACES TO SUB-TYPE IN TPTYPE-REC.
MOVE LENGTH OF MYFML TO LEN.
CALL "TPCALL" USING TPSVCDEF-REC
TPTYPE-REC
MYFML
TPTYPE-REC
MYFML
TPSTATUS-REC.
IF NOT TPOK
MOVE "TPCALL MYFML Failed" TO LOGMSG-TEXT
PERFORM DO-USERLOG
PERFORM EXIT-PROGRAM
END-IF.
* CONVERT THE FML RECORD BACK TO MYVIEW
CALL "FVFTOS" USING MYFML MYVIEW FML-REC.
IF NOT FOK
MOVE "FVFTOS Failed" TO LOGMSG-TEXT
PERFORM DO-USERLOG
PERFORM EXIT-PROGRAM
END-IF.

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.

To store multiple occurrences of a field in the COBOL record, a record element should be defined with OCCURS. If the number of occurrences of the field in the record is smaller than the number of occurrences of the element, the extra element slots are assigned null values. Alternatively, if the number of occurrences of the field in the record is higher than the number of occurrences of the element, then the surplus occurrences are ignored.

For FML32 and VIEW32, the FINIT32, FVSTOF32, and FVFTOS32 procedures should be used.

Upon successful completion, the system sets the FML-STATUS to FOK. On error, the system sets the FML-STATUS to a non-zero value.

Creating an FML Header File

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:

mkfldhdr myview.flds

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.

Listing 3-6 myview.flds.h Header File
/*       fname    fldid            */
/* ----- ----- */

#define FLOAT1 ((FLDID)24686) /* number: 110 type: float */
#define DOUBLE1 ((FLDID)32879) /* number: 111 type: double */
#define LONG1 ((FLDID)8304) /* number: 112 type: long */
#define SHORT1 ((FLDID)113) /* number: 113 type: short */
#define INT1 ((FLDID)8306) /* number: 114 type: long */
#define DEC1 ((FLDID)41075) /* number: 115 type: string */
#define CHAR1 ((FLDID)16500) /* number: 116 type: char */
#define STRING1 ((FLDID)41077) /* number: 117 type: string */
#define CARRAY1 ((FLDID)49270) /* number: 118 type: carray */

Specify the new header file in the #include statement of your application. Once the header file is included, you can refer to fields by their symbolic names.

See Also

 


Using an XML Typed Record

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:

Formatting and filtering for Events processing (which are supported when a STRING record type is used) are not supported for the XML record type. Therefore, the _tmfilter and _tmformat pointers in the record type switch for XML records are set to LOW-VALUE.

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.

Attributes configured for routing must be included in an XML document. If an attribute is configured as a routing criteria but it is not included in the XML document, routing processing fails.

The content of an element and the value of an attribute must conform to the syntax and semantics required for a routing field value. The user must also specify the type of the routing field value. XML supports only character data. If a range field is numeric, the content or value of that field is converted to a numeric value during routing processing.

See Also


  Back to Top       Previous  Next