Programming a Tuxedo Application Using COBOL
This topic includes the following sections:
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
Undefined array of characters, any of which can be LOW-VALUE. This typed record is used to handle the data opaquely, as the BEA Tuxedo system does not interpret the semantics of the array. Because a |
|||||
Proprietary BEA 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 Refer to Using an FML Typed Record for more information. |
|||||
Equivalent to However, the Refer to Using an FML Typed Record for more information. |
|||||
Array of characters that terminates with a LOW-VALUE character. The BEA Tuxedo system can convert data automatically when data is exchanged by machines with different character sets. |
|||||
COBOL data structure defined by the application. |
|||||
Equivalent to The primary use of Refer to Using a VIEW Typed Record for more information. |
|||||
Equivalent to |
|||||
An XML document that consists of: 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(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. |
|||||
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.
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.
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:
COPY
files (one per view), each of which contains data description records. These records can be used in the LINKAGE
section or the WORKING STORAGE
section of the DATA DIVISION
, according to the demands of the program.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
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
The following table 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 |
|
If you will be using the |
|
For |
|
User-specified LOW-VALUE value, or minus sign ( The default LOW-VALUE value for all numeric types is 0 (0.0 for 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: You may enclose 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 BEA 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.
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
$ /* 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
The following listing 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.
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:
COPY
files; for example, MYVIEW.cbl
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:
dec_t
type when passed from the COBOL program to the C program. 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.
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
record using FINIT.
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 ATMI FML Function Reference.
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
Field table files are always required when FML
records and/or FML
-dependent VIEW
s 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 */
*basevalue
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.
Table 3-5 Field Table File Fields
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
# 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.
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.
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.
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.
X
XML
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.
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.