e-docs > Tuxedo > Programming a Tuxedo Application Using COBOL > Managing Typed Records |
Programming a Tuxedo Application Using COBOL |
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. BEA 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 BEA 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 BEA 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.
The following table lists the typed records supported by the BEA 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
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 BEA 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.
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 BEA 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.
Table 3-2 Environment Variables for a VIEW Typed Record
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 */ The following table describes the fields that must be specified in the view description file for each COBOL record.
VIEW viewname
type cname fbname count flag size null
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 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 The following listing illustrates the same view description file for an independent VIEW. Listing 3-2 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. 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: 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: The output of the viewc command includes:
$ /* 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$ /* 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 -
ENDviewc -C myview.v
viewc -C -n myview.v
Note: On case-insensitive platforms (for example, Microsoft Windows), the extension used for the names of such files is vv; for example, myview.vv.
The following listing 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 BEA 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.
Table 3-4 FML Typed Record 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: The following table describes the fields that must be specified in the FML field table file for each FML field. Table 3-5 Field Table File Fields$ /* FML structure */
*base value
name number type flags comments
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. Listing 3-4 Field Table File for FML VIEW 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. The following listing shows how to perform an initialization. Listing 3-5 FML/VIEW Conversion 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: 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. Listing 3-6 myview.flds.h Header File 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# 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 - -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.mkfldhdr myview.flds
/* 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 */
Using an XML Typed Record
XXML records enable BEA Tuxedo applications to use XML for exchanging data within and between applications. BEA 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 BEA 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 BEA 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