|
|
The following sections provide SCA ATMI Binding reference information:
Listing F-1 shows how the ATMI binding element (<binding.atmi>) is defined. This is a pseudoschema that depicts how the grammar is used and what parameters are legal.
| Notes: | The parameters "transactionalintent legacyintent" are not literal values. transactionalintent can be substituted with "suspendsTransaction" or "propagatesTransaction" or omitted. "legacyintent" can be substituted with "legacy" or omitted. |
| Note: | Parameters with a ? may be specified 0 or 1 times, and parameters with * may be specified 0 or more times. |
| Note: | When using the <binding.atmi>element, the total length of /reference/@name (or/service/@name) and method name must be equal to or less than the maximum length of a Tuxedo service name (this varies depending on the Tuxedo release). To overcome this limitation, see
</binding.atmi/map>. |
<binding.atmi requires="transactionalintent legacyintent"?>
<tuxconfig>...</tuxconfig>?
<map target="name">...</map>*
<serviceType target="name">...</serviceType>*
<inputBufferType target="name">...</inputBufferType>*
<outputBufferType target="name">...</outputBufferType>*
<errorBufferType target="name">...</errorBufferType>*
<workStationParameters>?
<networkAddress>...</networkAddress>?
<secPrincipalName>...</secPrincipalName>?
<secPrincipalLocation>...</secPrincipalLocation>?
<secPrincipalPassId>...</secPrincipalPassId>?
<encryptBits>...</encryptBits>?
</workStationParameters>
<authentication>?
<userName>...</userName>?
<clientName>...</clientName>?
<groupName>...</groupName>?
<passwordIdentifier>...</passwordIdentifier>?
<userPasswordIdentifier>...
</userPasswordIdentifier>?
</authentication>
<fieldTablesLocation>...</fieldTablesLocation>?
<fieldTables>...</fieldTables>?
<fieldTablesLocation32>...</fieldTablesLocation32>?
<fieldTables32>...</fieldTables32>?
<viewFilesLocation>...</viewFilesLocation>?
<viewFiles>...</viewFiles>?
<viewFilesLocation32>...</viewFilesLocation32>?
<viewFiles32>...</viewFiles32>?
<remoteAccess>...</remoteAccess>?
<transaction timeout="xsd:long"/>?
</binding.atmi>
The <binding.atmi> element supports the following attributes
legacy value, it is used to perform interoperability with existing Tuxedo services. When not specified, communications are assumed to have SCA to SCA semantics where the actual Tuxedo service name is constructed from /service/@name or /reference/@name and actual method name (see Listing F-1), unless a /binding.atmi/map element is defined. When this attribute encounters a legacy value, and no /binding.atmi/map element is defined for the method being called, it has the following run-time behavior:<reference> element: the value specified in the /reference/@name is used to perform the Tuxedo call, with semantics used according to the interface method.<service> element: the Tuxedo service specified in the /binding.atmi/map element is advertised, and mapped to the method specified in the /binding.atmi/map/@target attribute.suspendsTransaction - transaction context is propagated to the called service. For a <service> element when a transaction is present, it is automatically suspended before invoking the application code. It resumes afterwards, regardless of the outcome of the invocation. For a <reference> element, it is equivalent to making a tpcall() with the TPNOTRAN flag.propagatesTransaction - only applicable to <reference> elements. It is ignored for <service> elements. This value starts a new transaction if one does not already exist, otherwise it participates in the existing transaction.
Such behavior can be obtained in a component or composite <service> element by configuring AUTOTRAN in the UBBCONFIG file. An error is generated if a Tuxedo server hosts the SCA component implementation and it is not configured in a transactional group in the UBBCONFIG file.
Used in <reference> elements when /binding.atmi/workstationParameters is not set, and for client-only processes. It indicates the Tuxedo application that the process should join. One process can join multiple applications, or switch applications without having to restart.
If not set, the TUXCONFIG environment variable is used. If not set, but one is required, the process exits and returns an error.
For <reference> elements, </binding.atmi/map>provides the Tuxedo service name that should be used when performing the invocation to the corresponding /binding.atmi/map/@target value, this value being the name of the method being called.
For <service> elements, </binding.atmi/map> provides the Tuxedo service name that should be advertised for the corresponding /binding.atmi/map/@target value.
The /binding.atmi/map/@target value must match the method name of the corresponding service interface.
If a /binding.atmi/map element is present, it takes precedence over any other form of service/method to Tuxedo service name mapping. See </binding.atmi/@requires> attribute.
Optional element that specifies the type of call being handled. The accepted values are:
Optional elements that specify the type of buffer that the processes exchange. The inputBufferType element is used by the binding extension to determine or check the type of the request.
The outputBufferType element is used by the binding extension to determine or check the type of the reply.
The errorBufferType element is used to determine the type of buffer specified in the data portion of the Exception thrown received by a client or thrown by a server.
Table F-1 lists supported values and corresponding Tuxedo buffer types. An incorrect value or syntax is detected at run time and causes the call to fail. If not specified, the default value used is STRING.
An optional element that specifies parameters specific to the Tuxedo WorksStation protocol. Only used in references.
More than one address can be specified (if required), by specifying a comma-separated list of pathnames for WSNADDR Addresses are tried in order until a connection is established. Any member of an address list can be specified as a parenthesized grouping of pipe-separated network addresses. For example:
<networkAddress> (//m1.acme.com:3050|//m2.acme.com:3050),//m3.acme.com:3050 </networkAddress>Tuxedo randomly selects one of the parenthesized addresses. This strategy distributes the load randomly across a set of listener processes. Addresses are tried in order until a connection is established.
On versions of Tuxedo that support ipv6, the corresponding addressing format will also be supported, following the same format as used in WSNADDR for Tuxedo /WS clients.
secPrincipalName, secPrincipalLocation, secPrincipalPassId
These parameters specify the necessary parameters when an SSL connection is required by a workstation client. The password is stored in a separate file and accessed using a callback mechanism. The default callback uses the password.store file maintained using the scapasswordtool command. For more information, see the SALT Programming Guide
encryptBits
Specifies the encryption strength that this client connection will attempt to negotiate. The format is <minencryptbits>/<maxencprytbits> (for example, 128/128), those values being numerical. Invalid values will result in a configuration exception being thrown. Values can be 0 (if no encryption is used), or 40, 56, 128, or 256 (if the number specified is the number of significant bits in the encryption key).
Specifies the security parameters used in reference-type calls to establish a connection with the Tuxedo application. The following values respectively correspond to the TPINFO structure elements usrname, cltname, grpname and passwd (for more information, see tpinit(3c) in the Oracle Tuxedo ATMI C Function Reference guide):
/binding.atmi/authentication/userName/binding.atmi/authentication/clientName/binding.atmi/authentication/groupName/binding.atmi/authentication/passwordIdentifier-(application password)/binding.atmi/authentication/userPasswordIdentifier-(user password in per-user authentication)
Passwords are not stored in clear text, but are looked up using an identifier. A callback function may be used to retrieve passwords. For more information, see setSCAPasswordCallback()in the Oracle SALT Reference Guide.
By default, passwords are maintained encrypted in a passwords store file located in the same directory as the composite file that contains the /reference/binding.atmi/authentication/passwordIdentifier or /reference/binding.atmi/authentication/userPasswordIdentifier element. This identifier is read as necessary to perform authentication.
For more information, see scapasswordtool and setSCAPasswordCallback(3c) in the Oracle SALT Reference Guide.
| Note: | This information should be handled with policy sets and intents when the SCA Kernel supports it. |
Optional element that specifies a directory in the local file system where field tables should be searched. If a relative path is specified, files are searched in that location relative to $APPDIR, otherwise the location is assumed to be absolute.
Same as fieldTablesLocation, but for FML32 buffers.
Optional element that specifies the FML field tables available. Field tables are searched in the location specified by the /binding.atmi/fieldTablesLocation element.
If the /binding.atmi/bufferType value is FML and this element is not specified or invalid (that is, the tables indicated cannot be found or are not field tables), an error is displayed at initialization time for client processes, or boot time for server processes.
Same as fieldTables, but for FML32 buffers.
Optional element that specifies a directory in the local file system where view tables should be searched. If a relative path is specified, files are searched in that location relative to $APPDIR, otherwise the location is assumed to be relative.
Same as viewTablesLocation, but for VIEW32 buffers.
Optional element that specifies the VIEW files to be used by the affected component(s). If the /binding.atmi/bufferType value is VIEW and this element is not specified or invalid (that is, the files indicated cannot be found, or are not view files), an error is displayed at run time for client processes, or boot time for server processes.
Same as ViewFiles but for VIEW32 buffers.
| Note: | FML/FML32 and VIEW/VIEW32 parameters are optional and may be omitted, in which case the corresponding Tuxedo environment variables are required (FLDTBLDIR/32, FLDTBLS/32, VIEWDIR/32 and VIEWFILES/32). If neither are used, an error message is printed at run time when attempting to use a fielded buffer. If both are set, the parameters contained in the SCDL code take precedence. |
Optional element that specifies the communication protocol with one of the values below. The default is Native.
If set to this value, the binding extension checks that the /binding.atmi/workStationParameters element is also populated and valid; if not, it reports a run-time error message.
Specifies the amount of time, in seconds, a transaction can execute before timing out. This attribute affects components or clients that effectively start a global transaction. It is mandatory for <reference> components and ignored if set on <service> components. Additionally, the value is ignored on components for which the transaction has already been started. If a transaction needs to be started and this attribute is not present (for example, "requires=propagatesTransaction" is set), a configuration error occurs.
buildscaclient, buildscacomponent, and buildscaserver in the Oracle SALT Command Reference.
|