Oracle SALT SCA ATMI Binding Reference

The following sections provide SCA ATMI Binding reference information:

•	SCA ATMI Binding Schema

•	SCA ATMI Binding Attributes Description

SCA ATMI Binding Schema

Listing G‑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.

Parameters with a ? may be specified 0 or 1 times, and parameters with * may be specified 0 or more times.

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>.

Listing G‑1 SCA ATMI Binding Pseudoschema

<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>

 

SCA ATMI Binding Attributes Description

The <binding.atmi> element supports the following attributes

•	</binding.atmi/@requires>

•	</binding.atmi/tuxconfig>

•	</binding.atmi/map>

•	</binding.atmi/serviceType>

•	</binding.atmi/inputBufferType>, </binding.atmi/outputBufferType>, </binding.atmi/errorBufferType>

•	</binding.atmi/workStationParameters>

•	</binding.atmi/authentication>

•	</binding.atmi/fieldTablesLocation>

•	</binding.atmi/fieldTablesLocation32>

•	</binding.atmi/fieldTables>

•	</binding.atmi/fieldTables32>

•	</binding.atmi/viewFilesLocation>

•	</binding.atmi/viewFilesLocation32>

•	</binding.atmi/viewFiles>

•	</binding.atmi/viewFiles32>

•	</binding.atmi/remoteAccess>

•	</binding.atmi/transaction/@timeout>

</binding.atmi/@requires>

•

When this attribute contains the 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 G‑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:

•	In a <reference> element: the value specified in the /reference/@name is used to perform the Tuxedo call, with semantics used according to the interface method.

•	In a <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.

•	When this attribute contains a transaction value, it specifies the transactional behavior that the binding extension follows when this binding is used. Possible values are as follows:

•

not specified (no value) - all transactional behavior is controlled by the Tuxedo configuration. If the Tuxedo configuration supports transactions, then one may be propagated if it exists. If the Tuxedo configuration does not support transactions and one exists then an error will occur. However, a transaction cannot start if one does not already exist.

•

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.

</binding.atmi/tuxconfig>

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.

</binding.atmi/map>

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.

</binding.atmi/serviceType>

Optional element that specifies the type of call being handled. The accepted values are:

•	Oneway - the call will not expect a response.

•	RequestResponse - regular call paradigm, default value.

</binding.atmi/inputBufferType>, </binding.atmi/outputBufferType>, </binding.atmi/errorBufferType>

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 G‑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.

 

SCA Supported Tuxedo Buffer Types

/binding.atmi/bufferType value	Tuxedo buffer type	Note
STRING	STRING
CARRAY	CARRAY
X_OCTET	X_OCTET
VIEW	VIEW	Format is VIEW/<subtype>
X_C_TYPE	X_C_TYPE	Format is X_C_TYPE/<subtype>
X_COMMON	X_COMMON	Format is: X_COMMON/<subtype>
VIEW32	VIEW32	Format is VIEW32/<subtype>
XML	XML
FML	FML	Format is: FML/<subtype>, <subtype> is optional The <subtype> value allows to specify the SDO type to use for that message (request or response) when it is described in an XML schema Note: FML32 <subtype> is not available for JATMI binding.
FML32	FML32	Format is: FML32/<subtype>, <subtype> is optional The <subtype> value allows to specify the SDO type to use for that message (request or response) when it is described in an XML schema Note: FML32 <subtype> is not available for JATMI binding.
MBSTRING	MBSTRING

</binding.atmi/workStationParameters>

An optional element that specifies parameters specific to the Tuxedo WorksStation protocol. Only used in references.

•	/binding.atmi/workStationParameters/networkAddress

The address of the workstation listener to which this application will connect. Any address format accepted by the Tuxedo workstation software is allowed. The most common address format is:

//<hostname or IP address>:<port>.

For more information, see the SALT Programming Guide

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).

</binding.atmi/authentication>

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.

</binding.atmi/fieldTablesLocation>

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.

</binding.atmi/fieldTablesLocation32>

Same as fieldTablesLocation, but for FML32 buffers.

</binding.atmi/fieldTables>

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.

</binding.atmi/fieldTables32>

Same as fieldTables, but for FML32 buffers.

</binding.atmi/viewFilesLocation>

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.

</binding.atmi/viewFilesLocation32>

Same as viewTablesLocation, but for VIEW32 buffers.

</binding.atmi/viewFiles>

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.

</binding.atmi/viewFiles32>

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.

</binding.atmi/remoteAccess>

Optional element that specifies the communication protocol with one of the values below. The default is Native.

•	Native - indicates that components use standard Tuxedo native communications (IPC queues)

•	WorkStation - indicates that components use the Tuxedo /WS communication protocol.

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.

</binding.atmi/transaction/@timeout>

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.

See Also

•	buildscaclient, buildscacomponent, and buildscaserver in the Oracle SALT Command Reference.

•	Oracle SALT Programming Guide