Setting Up a Tuxedo Application

Managing The Tuxedo Service Metadata Repository

This topic includes the following sections:

Tuxedo Service Metadata Repository

The Tuxedo service metadata repository contains BEA Tuxedo service definitions that allow Tuxedo clients to access BEA Tuxedo service parameter information. It provides Tuxedo application developers and administrators the ability to store and retrieve detailed service parameter information on any or all Tuxedo application services.

The Tuxedo service metadata repository is designed to process interactive queries by developers and administrators during application development or modification. It is not designed to process high volumes of automated queries during the application production phase.

Five utilities are used in conjunction with the Tuxedo service metadata repository

TMMETADATA(5): Tuxedo service metadata repository server. It provides one service, .TMMETAREPOS, which uses an FML32 input and output buffer format described in METAREPOS(5)

Note: The .TMMETAREPOS buffer format is similar to MIB(5).

tmloadrepos(1): creates or updates the binary metadata repository file and loads it with service parameter information.
tmunloadrepos(1): displays service information from the Tuxedo service metadata repository. Output can be optionally specified as plain text format, WSDL format, or C pseudocode
tpgetrepos(3c): programmatically uses FML32 buffers to output service information from the Tuxedo service metadata repository
tpsetrepos(3c): programmatically uses FML32 buffers to add, delete, or update service parameter information to the metadata repository file

JOLT Repository Similarities and Differences

BEA Jolt also provides a service repository that allows applications to manually enter Tuxedo service information, including service names, input and output buffer types, parameter names, parameter data types, the number of times each parameter is expected, and whether each parameter is for input, output, or both. All of which seem very similar to the Tuxedo service metadata repository. However, there are also some distinct difference as noted in the following table:

Table 7-1 JOLT Repository Similarities and Differences

	Jolt Repository	Tuxedo Service Metadata Repository
Function	Designed for JAVA client communication with Tuxedo servers	Designed for Web service based communication with Tuxedo servers
GUI interface	Yes	No
Uses plain text repository input file	Yes (via bulkloader)	Yes (via `tmloadrepos`)
Service and Parameter keywords and values	Yes	Yes (but more than Jolt Repository to provide the user with more detailed service information)
Repository file format	Plain text	Binary (service indexed for quick access)
Access method	Administration utility, direct editing	Administration utility, programming API, system service
Unload output format	Plain text	Plain text, WDSL, and C-pseudocode
Inter operability	Cannot read Tuxedo service metadata repository file	Can read, but not modify, existing Jolt Repository file. Cannot create a Jolt Repository file.

MIB(5) Similarities and Differences

Programmatic access to the Tuxedo System Metadata Repository is accomplished through the use of a FML32 buffer format that is very similar to the Tuxedo MIB format. However, there are also some distinct difference as noted in the following table:

Table 7-2 MIB(5) Similarities and Differences

	`MIB(5)`	`METAREPOS(5)`
Input/out buffers	FML32	FML32
Generic MIB fields	Yes	Yes, but with some limitations. See METAREPOS(5)
Authentic MIB class entities	Many	No authentic MIB class entities, but uses similar type
Service entry	`.TMIB` in `BBL`	`.TMMETAREPOS` in `TMMETADA` server

Creating The Tuxedo Service Metadata Repository

The metadata repository file contains all the service parameter information that is accessed in the Tuxedo service metadata repository. The tmloadrepos command is used to create a metadata repository file. Metadata repository file service parameter information is input directly from the computer console (standard input) if a repository input file is not specified or from a specified plain text repository input file. For example:

tmloadrepos -i/usr/tuxedo/repository_input_file/usr/tuxedo/
service_metatdata_repository

The Tuxedo Service Metadata Repository Input File

The repository_input_file contains service parameter keywords and their associated values. Keywords are divided into two categories: service-level and parameter-level.

Note: Keyword abbreviations are also supported. Both keywords and abbreviations are case sensitive. For more information on keywords, abbreviations, and values, see Using Service-Level Keywords and Values and Using Parameter-Level Keywords and Values.

No more than one keyword/value combination can be specified per line. The maximum line character length is 1024 bytes. String parameter values do not need to be set off with quotation marks.

The repository_input file uses the following syntax: <keyword><=value> and has the following input conventions:

"(" and ")"

When a parameter must define a sub-parameter, a line consisting of a single left parenthesis '( 'and a line consisting of a single right parenthesis ') ' denotes the beginning and end of the embedded sub-parameter portion of the parameter. The left and right parentheses can be used recursively.

\ and "\"

You can include blank lines in the repository_input file as needed for readability. A new line is preceded by a \ character. To use an actual '\' character it must be written as '\\'.

#

Lines starting with a '#' are interpreted as comment lines. Unlike comments specified via the svcdescription or paramdescription keywords, comments are not stored in the binary repository_file or output by tmunloadrepos.

The repository_input file can consist of zero or more service parameter definitions. Each service definition starts with a line beginning with the <service> keyword followed by zero or more lines beginning with one of the other service-level keywords, followed by parameter-level keywords. A particular service-level keyword may not be repeated for a particular service.

Using Service-Level Keywords and Values

A service definition must begin with the keyword service<=NAME> or the abbreviation sv<=NAME>. Services using CARRAY, STRING, or XML buffer types can have only one parameter per service. The Tuxedo service metadata repository service-level keywords are as follows:

Table 1 Service-Level Keyword, Abbreviations, and Values

Service-Level Keyword	Keyword Abbreviation	Value
`service`	sv	Any Tuxedo service name Note: This key valued can only be once per Metadata Repository instance. It cannot be duplicated within the same Metadata Repository.
tuxservice	tsv	Actual Tuxedo service name Note: The difference between the `service` and `tuxservice` keywords is: `service` represents the service entry stored in the Metadata Repository. `tuxservice` represents the actual Tuxedo service name. Two or more `service` definitions can have the same value as `tuxservice`. When used together, these two keywords make it possible to have multiple service definitions for one Tuxedo service. By default, `tuxservice` has the same value as `service`
servicetype	st	Service invocation type. Legal values are: `service` - the service is a synchronous `oneway` - the service will not send response to the client `queue` - the service is a /Q related application
`export`	`ex`	Y (default) or N. In the Jolt repository, this keyword is used to determine service availability to the Jolt client. In the Tuxedo repository, this keyword does not have any meaning, but is nevertheless accepted to maintain compatibility with existing Jolt bulk loader files.
`inbuf`	`bt`	Select one of these buffer types: `FML`, `FML32`, `VIEW`, `VIEW32`, `STRING`, `CARRAY`, `XML`, `X_OCTET`, `X_COMMON`, `X_C_TYPE`, `MBSTRING` or an application defined buffer type. Note: `"inbuf"` value of each service definition cannot be NULL.
`outbuf`	`BT`	Select one of these buffer types: `FML`, `FML32`, `VIEW`, `VIEW32`, `STRING`, `CARRAY`, `XML`, `X_OCTET`, `X_COMMON`, `X_C_TYPE`, `MBSTRING` or an application defined buffer type. Note: The `"outbuf"` value of each service definition cannot be NULL for a "`service`" typed service or a "`queue`" typed service.
`inview`	`vn`	View name for input parameters (Optional) Note: This keyword is mandatory only if one of the following buffer types is used: `VIEW`, `VIEW32`, `X_COMMON`, `X_C_TYPE`.)
`outview`	`VN`	View name for output parameters (Optional) Note: This keyword is mandatory only if one of the following buffer types is used: `VIEW`, `VIEW32`, `X_COMMON`, `X_C_TYPE.`
`svcdescription`	`sd`	Any string value. A new-line break can be used to improve readability if the string is too long.
sendqspace	`sqs`	Send queue space name. Optional for a `"queue"` typed service.
sendqueue	`sqn`	Send queue name. Optional for a `"queue"` typed service.
rplyqueue	`rqn`	Reply queue name. Optional for a `"queue"` typed service.
errqueue	`eqn`	Error queue name. Optional for a `"queue"` typed service.
rcvqspace	`RQS`	Receive queue space name. Optional for a `"queue"` typed service.
rcvqueue	`RQN`	Receive queue name. Optional for a `"queue"` typed service.
`version`	`vs`	This parameter is exclusive to the Tuxedo service metadata repository and accommodates any string value used by the application. BEA Tuxedo does not interpret this parameter.
`attributes`	`att`	This parameter is exclusive to the Tuxedo service metadata repository and accommodates any string value used by the application. BEA Tuxedo does not interpret this parameter.
`fieldtbls`	`ftb`	This parameter is optional and specifies a comma-separated list of field tables where the FML or FML32 fields used by this service can be found. The `fieldtbls` parameter is intended for reference use by application developers.

Using Parameter-Level Keywords and Values

A parameter begins with the keyword <param><=NAME> or the abbreviation <pn><=NAME> followed by a listing of parameter keywords. It ends with another <param> or <service> keyword, or when end-of-file is encountered. The parameters can be listed in any order after <param><=NAME>.

Note: A particular service can specify multiple occurrences of the <param> keyword. That is to say, more than one parameter can exist for a particular service. For example, a parameter with an FML or VIEW buffer.

The Tuxedo service metadata repository parameter-level keywords are as follows:

Table 2 Parameter-Level Keyword, Abbreviations, and Values

Parameter-Level Keyword	Metadata Repository Abbreviation	Value
`param`	`pn`	Any parameter name
`type`	`pt`	`byte`, `short`, `integer`, `float`, `double`, `string`, `carray`, `dec_t`, `xml`, `ptr`, `fml32`, `view32`, `mbstring`. Note: The parameter type must be consistent with its service buffer type. For example, an `FML16` buffer only allow parameters with the following type: `byte (char)`, `short`, `integer`, `long`, `float`, `double`, `string`, `carray`. All other type parameters are not permitted. See following buffer type/parameter type matching table.
`subtype`	`pst`	A view name for a view32 typed parameter
`access`	`pa`	`in`, `out`, `inout`, `noaccess`. `in` - indicates a parameter that is used for input only. `out` - indicates a parameter that is used for output only. `inout` - indicates a parameter that is used for both input and output. `noacesss` - indicates a parameter that must be provided on input but which is not referenced in the server, such as an obsolete parameter or a parameter that must be provided as a filler field in a view. The set of parameters expected on input is those specified with `in,` `inout`, or `noacces`s access The set of parameters returned on output is those specified with either `out` or `inout` access.
`count`	`po`	Maximum number of occurrences (default is 1). The value for unlimited occurrences is 0. The value range is `[0, 32767]`. In the Jolt repository, this parameter is used only by the Repository Editor to format test screens. In the Tuxedo repository, this parameter is stored for display and is also used by tmunloadrepos(1)pseudocode generation options.
`paramdescription`	`pd`	Any string value. A new-line break can be used to improve readability if the string is too long.
`size`	`pl`	This optional parameter indicates the number of bytes allocated for the parameter. It is used in pseudo code generation for non-numeric parameters and can be used for programmer reference purposes. The following parameter types expect this value: `carray`, `string`, `xml`, `mbstring`.
`requiredcount`	`ro`	Minimum number of times that the parameter must be specified.The value range is `[0, 32767]`.
`fldnum`	`fno`	This optional parameter indicates the field number of the parameter if it is a `FML/FML32` `field`. Note: Users are not encouraged to provide this information if they have already defined `fieldtbl` files by indicating field table directories using environment `FLDTBLDIR(32)` and indicating field table files using environment `FIELDTBLS(32)`or `fieldtbl` service-level keyword.
vfbname	`vfb`	This parameter is optional for view structure members. It is used to indicate the field name in the fielded buffer. Please reference viewfile(5)
vflag	`vfl`	This parameter is optional for view structure members. Legal values are combination of the following options: `'C'`, `'F'`, `'L'`, `'N'`, `'P'`, `'S'`. Please reference viewfile(5).
vnull	`vnu`	This parameter is optional for view structure members. It indicates the view member default null value.
`(`		Indicates the beginning of the description of the parameters contained in an embedded `FML32` or `VIEW32` buffer field. It contains no associated value and is specified separately on a line by itself. It is valid only if a previous type keyword has been specified for this parameter with a `FML32` or `VIEW32` value. A closing right parenthesis ')' ends the embedded parameter description.
`)`		Ends an embedded `FML32` or `VIEW32` parameter definition of that began with an opening matching left parenthesis '('. It contains no associated value and is specified separately on a line by itself. It is valid only if a previous only if there is a previous matching '(' keyword. In addition, the maximum embedded level depends on the upper limit of embedded FML32 nesting level (18 at present).

Parameter Occurrences

As a generally applied Tuxedo rule, only FML/FML32, VIEW/VIEW32, X_COMMON, and X_C_TYPE typed buffers can specify multiple parameters (due to their information structure). All other typed buffers have only one parameter with the corresponding parameter type. For example, a CARRAY type buffer has only one CARRAY typed parameter to describe the necessary information that it contains. You must follow this rule to define application services.

Table 3 Service Buffer Type (SMALL CAPS)/Service Parameter Type (lower case) Matching Table I

	`byte` (char)	`short`	`integer`	`long`	`float`	`double`	`string`
`CARRAY`
`FML`	X	X	X	X	X	X	X
	`byte` (char)	`short`	`integer`	`long`	`float`	`double`	`string`
`FML32`	X	X	X	X	X	X	X
`STRING`							X
`VIEW`	X	X	X	X	X	X	X
`VIEW32`	X	X	X	X	X	X	X
`X_COMMON`		X		X			X
`X_C_TYPE`	X	X	X	X	X	X	X
`XML`							X
`X_OCTET`
`MBSTRING`

Table 4 Service Buffer Type (SMALL CAPS)/Service Parameter Type (lower case) Matching Table II

	`carray`	`dec_t`	`xml`	`ptr`	`fml32`	`view32`	`string`
`CARRAY`	X
`FML`	X
`FML32`	X			X	X	X	X
`STRING`
`VIEW`	X	X
`VIEW32`	X	X
`X_COMMON`
`X_C_TYPE`
`XML`			X

	`carray`	`dec_t`	`xml`	`ptr`	`fml32`	`view32`	`string`
`X_OCTET`	X
`MBSTRING`	X						X

Configuring The Tuxedo Service Metadata Repository Server

To configure the Tuxedo service metadata repository you must:

add TMMETADATA to the *SERVERS section of the UBBCONFIG(5).
run tmloadcf(1) on the UBBCONFIG file.
use tmloadrepos(1) to create and enter service parameter information into the metadata repository file.
boot the server.

Once the Tuxedo metadata server is running, the.TMMETAREPOS service is automatically activated. .TMMETAREPOS is a Tuxedo system service and cannot be modified.

All requests made to the server are responded to on a first-come-first-served basis.

Configuring Multiple Tuxedo Service Metadata
Repository Servers

Setting up multiple TMMETADATA servers on a particular Tuxedo node requires adherence to two crucial configuration rules:

Each TMMETADATA server must be configured to access the same metadata repository file or an exact copy of the file to provide consistent request results. Therefore, it is strongly recommended that a stable version of the metadata repository is made available for multiple TMMETADATA server access.
Permission settings must be consistently applied (either read only or read/write) for multiple TMMETADATA servers on a particular node.

Accessing The Tuxedo Service Metadata Repository File

The Tuxedo service metadata repository facilitates native and remote client access in order to view, update, add, or delete service metadata repository parameter information.

For native clients exclusively, tpgetrepos(3c), and tpsetrepos(3c)are used for Tuxedo service metadata repository access.

tpgetrepos(3c) and tpsetrepos(3c) can access the Tuxedo service metadata repository whether the server is booted or not.

For remote and native clients, TMMETADATA(5) can be used.