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 COBOL

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:

• Set the appropriate environment variables.

• Describe the potential fields in an FML field table.

• Initialize the FML record using FINIT.

• 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 BEA Tuxedo FML Function Reference.

To use an FML typed record in an application program, you must set the following environment variables.

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

The following table describes the fields that must be specified in the FML field table file for each FML field.

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

The following example illustrates a field table file that may be used with the FML-dependent VIEW example.

# 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   -       -

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.

The following listing shows how to perform an initialization.

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.

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.

The following listing shows the myview.flds.h header file that is created by the mkfldhdr command.

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

• Using a VIEW Typed Record

• Using an XML Typed Record

• mkfldhdr, mkfldhdr32(1) in the BEA Tuxedo Command Reference