8 Managing the Oracle Tuxedo Service Metadata Repository
This topic includes the following sections:
8.1 Oracle Tuxedo Service Metadata Repository
The Oracle Tuxedo service metadata repository contains Oracle Tuxedo service definitions that allow Oracle Tuxedo clients to access Oracle Tuxedo service parameter information. It provides Oracle Tuxedo application developers and administrators the ability to store and retrieve detailed service parameter information on any or all Oracle Tuxedo application services.
The Oracle 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 Oracle Tuxedo service metadata repository
-
TMMETADATA(5)
: Oracle 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 Oracle 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 Oracle Tuxedo service metadata repository. -
tpsetrepos(3c)
: programmatically uses FML32 buffers to add, delete, or update service parameter information to the metadata repository file.
See Also:
TMMETADATA(5)
, METAREPOS(5), and MIB(5) in the Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Referencetmloadrepos(1)
andtmunloadrepos(1)
in the Section 1 - Commandstpgetrepos(3c)
andtpsetrepos(3c)
in the Section 3c - C Functions
Parent topic: Managing the Oracle Tuxedo Service Metadata Repository
8.1.1 MIB(5) Similarities and Differences
Programmatic access to the Oracle Tuxedo System Metadata Repository is accomplished through the use of a FML32 buffer format that is very similar to the Oracle Tuxedo MIB format. However, there are also some distinct difference as noted in the following table:
Table 8-1 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
|
Parent topic: Oracle Tuxedo Service Metadata Repository
8.2 Creating The Oracle Tuxedo Service Metadata Repository
The metadata repository file contains all the service parameter
information that is accessed in the Oracle 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.
Parent topic: Managing the Oracle Tuxedo Service Metadata Repository
8.2.1 The Oracle 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
orparamdescription
keywords, comments are not stored in the binaryrepository_file
or output bytmunloadrepos
.
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
- Using Parameter-Level Keywords and Values
- Parameter Occurrences
Parent topic: Creating The Oracle Tuxedo Service Metadata Repository
8.2.1.1 Using Service-Level Keywords and Values
A service definition must begin with the keyword
service<=NAME>
or the abbreviation
sv<=NAME>
. Services usingCARRAY
,
STRING
, or XML
buffer types can have only
one parameter per service. The Oracle Tuxedo service metadata
repository service-level keywords are in the following table:
Table 8-2 Service-Level Keyword, Abbreviations, and Values
Service-Level Keyword | Keyword Abbreviation | Value |
---|---|---|
service
|
sv
|
Any Oracle 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 Oracle Tuxedo service name
Note: The difference between theservice and tuxservice keywords is:
When used together, these two keywords make it possible to have multiple service definitions for one Oracle Tuxedo service. By default, |
servicetype
|
st
|
Service invocation type. Legal values are:
|
SNAISC
|
ISC | Enables outbound Tuxedo service requests to map to APPC transaction programs or CICS programs. It is only valid when the value of servicemode is "sna". Its valid value list is: APPC,ATI, DPL, DTP. The default value APPC indicates the remote service is a transaction program that may or may not be running under CICS. The DPL value indicates the remote service maps to a program running under CICS. |
servicemode
|
sm
|
Type of service origination(Optional). Legal values are:
Note: Do not specifywebservice for any Oracle Tuxedo service, webservice is reserved for SALT proxy service only.
|
export
|
ex
|
Y (default) or N.
This keyword is used to determine service availability to the Oracle Jolt client. In the Oracle Tuxedo repository, this keyword does not have any meaning, but is nevertheless accepted to maintain compatibility with existing Oracle Jolt bulk loader files. Note: If export is set toN , the service will not be exported for C pseudo-code or text format.
|
inbuf
|
bt
|
Oracle Tuxedo service request (input) buffer type. Select one of the following type values (case sensitive): FML, FML32, VIEW, VIEW32, STRING, CARRAY, XML, X_OCTET, X_COMMON, X_C_TYPE, MBSTRING or other arbitrary string representing an application defined custom buffer type.
Note: The "inbuf " value of each service definition cannot be NULL .
|
outbuf
|
BT
|
Oracle Tuxedo service response (output) buffer type with TPSUCCESS . Select one of the following type values (case sensitive): FML, FML32, VIEW, VIEW32, STRING, CARRAY, XML, X_OCTET, X_COMMON, X_C_TYPE, MBSTRING or other arbitrary string representing an application defined custom buffer type.
Note: The "outbuf " value of each service definition cannot be NULL for a "service " typed service or a "queue " typed service.
|
errbuf
|
ebt
|
Oracle Tuxedo service response (error) buffer type with TPFAIL. Select one of the following type values (case sensitive): FML, FML32, VIEW, VIEW32, STRING, CARRAY, XML, X_OCTET,X_COMMON, X_C_TYPE, MBSTRING or other arbitrary string representing an application defined custom buffer type.
|
inview
|
vn
|
View name for input buffer(Optional)
Note: This keyword is mandatory only if one of the following buffer types is used:VIEW, VIEW32, X_COMMON, X_C_TYPE, FML and FML32 .
|
outview
|
VN
|
View name for output buffer (Optional)
Note: This keyword is mandatory only if one of the following buffer types is used:VIEW, VIEW32, X_COMMON, X_C_TYPE, FML and FML32 .
|
errview
|
evn
|
View name for error buffer (Optional)
Note: This keyword is mandatory only if one of the following buffer types is used:VIEW, VIEW32, X_COMMON,X_C_TYPE .
|
inbufschema
|
isc
|
Customized message schema association for input buffer (Optional). Value format is: XSD_E:@namespaceURI For example, XSD_E:Book@http://example.org represents the input buffer is associated with a XML element defined in the XML namespace “http://example.org ”.
Note: This keyword is introduced for supporting Oracle SALT extensible message mapping and conversion feature. For more information about SALT message conversion, see Data Type Mapping and Message Conversion in Oracle SALT Programming Web Services |
outbufschema
|
osc
|
Customized message schema association for output buffer (Optional). Value format is: XSD_E:@namespaceURI
|
errbufschema
|
esc
|
Customized message schema association for error buffer (Optional). Value format is: XSD_E:@namespaceURI
|
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 Oracle Tuxedo service metadata repository and accommodates any string value used by the application. Oracle Tuxedo does not interpret this parameter |
attributes
|
att
|
This parameter is exclusive to the Oracle Tuxedo service metadata repository and accommodates any string value used by the application. Oracle 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.
|
Parent topic: The Oracle Tuxedo Service Metadata Repository Input File
8.2.1.2 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 Oracle Tuxedo service metadata repository parameter-level keywords are in the following table:
Table 8-3 Parameter-Level Keyword, Abbreviations, and Values
Parameter-Level Keyword | Metadata Repository Abbreviation | Value |
---|---|---|
param
|
pn
|
Any parameter name |
type
|
pt
|
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
|
The set of parameters expected on input is those specified with The set of parameters returned on output is those specified with The set of parameters returned on error output is those specified with |
count
|
po
|
Maximum number of occurrences (default is 1). The value for unlimited occurrences is 0. The value range is [0, 32767] . In the Oracle 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
|
p1
|
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: |
requiredcount
|
ro
|
Minimum number of times that the parameter must be specified. The value range is [0, 32767] .
|
fieldindex
|
fi
|
The occurrence number of the field. This applies to FML/FML32 only. It only supports Jolt client. |
fieldname
|
fn
|
FML's field name. This applies to FML/FML32 only. It only supports Jolt client.
Note: For FML/FML32, you should use this "fieldname " to specify the field name instead of another parameter-level keyword "param ".
|
fldnum
|
fno
|
This optional parameter indicates the field number of the parameter if it is a FML/FML32 field .
Note: It is not recommended that you use this information if thefieldtbl files have already been defined by indicating field table directories using environment FLDTBLDIR(32) and indicating field table files using environment FIELDTBLS(32) or fieldtbl service-level keyword. If you configured the fldnum field, you will receive the responding fldid according to the fldnum value instead of the param value.
|
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
|
vf1
|
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. |
paramschema
|
psc
|
This parameter is optional to save the XML Schema information for the decomposed FML32 field.
Note: This parameter keyword is introduced especially for “servicemode=webservice ” typed service definition, i.e. SALT proxy service for outbound call. The parameter value is generated by Oracle SALT wsdlcvt utility from converting an external WSDL file. Do not manually specify or modify this keyword value.
|
primetype
|
pxt
|
This parameter is optional to save the original XML primitive data type for the decomposed FML32 field.
Note: This parameter keyword is introduced especially for “servicemode=webservice ” typed service definition, i.e. SALT proxy service for outbound call. The parameter value is generated by Oracle SALT wsdlcvt utility from converting an external WSDL file. Do not manually specify or modify this keyword value.
|
isarray
|
arr
|
This parameter is optional for SALT RESTful service. If it set to "Y ", SALT REST/JSON service maps Tuxedo buffer to JSON array type - even if there is only one occurrence of a field.
Currently, only |
inheader
|
- | Retrieved from the SOAP header portion of the SOAP envelope message received. Message can be a request (native Tuxedo service) or reply (external web service call). |
outheader
|
- | Added to the SOAP header portion of the SOAP envelope message sent. Message can be a reply (native Tuxedo service) or request (external web service call). |
inoutheader
|
- | Combination of inheader and outheader. This parameter is both added to and retrieved from the SOAP header portion of the SOAP message. |
whitespace
|
ws
|
If this parameter is set to collapse, and the type is string, when GWWS is doing Tuxedo buffer-to-XML-data mapping, the white space is collapsed, which causes:
|
(
|
- | 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 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). |
Parent topic: The Oracle Tuxedo Service Metadata Repository Input File
8.2.1.3 Parameter Occurrences
As a generally applied Oracle 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 8-4 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 |
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 8-5 Service Buffer Type (SMALL CAPS)/Service Parameter Type (lower case) Matching Table II
bool |
Unsigned char |
Signed char |
Wchart |
Unsigned int |
Unsigned long |
Long long |
Unsigned long long |
Long double |
|
---|---|---|---|---|---|---|---|---|---|
VIEW |
X | X | X | X | X | X | X | X | X |
VIEW32 |
X | X | X | X | X | X | X | X | X |
Table 8-6 Service Buffer Type (SMALL CAPS)/Service Parameter Type (lower case) Matching Table III
carray |
dec_t |
xml |
ptr |
fml32 |
view32 |
mbstring |
|
---|---|---|---|---|---|---|---|
CARRAY |
X | - | - | - | - | - | - |
FML |
X | - | - | - | - | - | - |
FML32 |
X | - | - | X | X | X | X |
STRING |
- | - | - | - | - | - | - |
VIEW |
X | X | - | - | - | - | - |
VIEW32 |
X | X | - | - | - | X | X |
X_COMMON |
- | - | - | - | - | - | - |
X_C_TYPE |
- | - | - | - | - | - | - |
XML |
- | - | X | - | - | - | - |
X_OCTET |
X | - | - | - | - | - | - |
MBSTRING |
X | - | - | - | - | - | X |
Parent topic: The Oracle Tuxedo Service Metadata Repository Input File
8.3 Configuring The Oracle Tuxedo Service Metadata Repository Server
To configure the Oracle Tuxedo service metadata repository you must:
- add
TMMETADATA
to the*SERVERS
section of the UBBCONFIG(5). - run
tmloadcf(1)
on theUBBCONFIG
file. - use
tmloadrepos(1)
to create and enter service parameter information into the metadata repository file. - boot the server.
Once the Oracle Tuxedo metadata server is running,
the.TMMETAREPOS
service is automatically activated.
.TMMETAREPOS
is an Oracle Tuxedo system service and
cannot be modified.
All requests made to the server are responded to on a first-come-first-served basis.
See Also:
- UBBCONFIG(5) in the Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference
tmloadcf(1)
in the Section 1 - Commands
Parent topic: Managing the Oracle Tuxedo Service Metadata Repository
8.3.1 Configuring Multiple Oracle Tuxedo Service Metadata Repository Servers
Setting up multiple TMMETADATA
servers on a
particular Oracle 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 multipleTMMETADATA
server access. - Permission settings must be consistently applied (either read
only or read/write) for multiple
TMMETADATA
servers on a particular node.
8.4 Accessing The Oracle Tuxedo Service Metadata Repository File
The Oracle 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)
, andtpsetrepos(3c)
are used for Oracle Tuxedo service metadata repository access.t
pgetrepos(3c)
andtpsetrepos(3c)
can access the Oracle Tuxedo service metadata repository whether the server is booted or not. - For remote and native clients,
TMMETADATA(5)
can be used.
See Also:
TMMETADATA(5)
andMETAREPOS(5)
in the Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Referencetmloadrepos(1)
andtmunloadrepos(1)
in the Section 1 - Commandstpgetrepos(3c)
andtpsetrepos(3c)
in the Section 3c - C Functions
Parent topic: Managing the Oracle Tuxedo Service Metadata Repository