trnstring -n resource-manager-name [-i resource-manager-extension[,resource-manager- extension]...] [-o "transaction-service-xa_open-function-character-string"] [-c "transaction-service-xa_close-function-character-string"] [-O "user-server-xa_open-function-character-string"] [-C "user-server-xa_close-function-character-string"][-d] [-e][-m][-r]

The trnstring command specifies the character string or extension for access to the resource manager.

The OpenTP1 transaction service executes a transaction in collaboration with the resource manager in accordance with the X/Open XA interface. The XA interface must report the xa_open function character string and xa_close function character string that are defined by the resource manager.

If the user server accesses the resource manager provided by a system other than OpenTP1 within a transaction under OpenTP1 (that is, if the trnmkobj command is executed to specify a resource manager provided by a system other than OpenTP1, and this resource manager creates a transaction control object file and links with the user server), specify the xa_open function character string and xa_close function character string for that resource manager. The xa_open and xa_close functions are issued by the transaction service with the specified characters strings used as arguments at startup and termination of the user server.

The transaction service recovers the transaction being processed by a user server when the user server terminated abnormally or when the OpenTP1 system resumed. Because this recovery process uses the two functions, their character strings for all resource managers the user server is to access must be defined in the transaction service.

The -i option can be specified only when more than one extension is assigned to one resource manager to be accessed as more than one control unit. The OpenTP1 system modifies the resource manager name to a resource manager name + resource manager extension to control the manager for which the -i option has been specified. This means that a user server cannot access the resource manager by its name alone. It is necessary to specify the trnrmid command in the user service definition or user service default definition.

The character string for identifying a resource manager that is specified in the -i option must not be duplicated in any trnstring command. If more than one trnstring command for the same resource manager extension is specified under the same resource manager name within one definition file, only the last definition specified is valid.

In the -o and -c options, specify the character strings to be used when the transaction service process issues the xa_open and xa_close functions. Also in the -O and -C options, specify the character strings to be used when the user service process issues the xa_open and xa_close functions. These options must not be specified for resource managers provided by OpenTP1.

Specify the -e option to retry issuing the xa_close function, the xa_open function, and the xa_start function in this order to the static resource manager. If an error occurs in the xa_start function when a transaction branch starts for the static resource manager, you can use the -e option. If you do not specify the -e option, the xa_open function and the xa_start function are re-issued in this sequence.

For the character strings to be specified, see the manual for each resource manager.

If reporting the NULL characters is necessary, omit the -o, -c, -O, or -C option.

If the following two conditions are satisfied, the trnstring command need not be defined:

• where it is unnecessary to access one resource manager with more than one extension assigned to it to configure more than one control unit.
• where it is necessary to report both the xa_open and xa_close function character strings in the form of NULL characters.

If no required character string or an invalid character string is specified, an error occurs with user server startup or termination, or with transaction recovery.

-n resource-manager-name~<1-31 character identifier>

Specify the name of the resource manager to be accessed by a transaction under OpenTP1. When OpenTP1 provides the resource, you can omit this specification except for OpenTP1_MCF. However, you can omit the specification of OpenTP1_MCF for the following case:

• The id operand is omitted or A is specified in the mcfmenv MCF manager environment definition.

-i resource-manager-extension~<1-2 character identifier>

When one resource manager is accessed as more than one control unit, this option specifies a character string for modifying the manager name to a resource manager name + resource manager extension.

If more than one extension uses the same xa_open or xa_close function character string, they can be specified in the -i option. In this case, a comma (,) must be placed between extensions.

Any extension specified by the trnstring command must not be duplicated. To control an MCF relating to transactions, the resource manager extensions for that MCF must be specified in the -i operand. They must include process identifiers that can be accessed by user servers and the MCF manager process identifiers that are specified by the manager definition for the MCF operating at each applicable node.

-o "transaction-service-xa_open-function-character-string"~<1-256 character string>

Specify the character string to be used when the transaction service process under OpenTP1 issues the xa_open function. For the character string to be specified, see the manual for each resource manager. If it is necessary to report the NULL character string, omit the -o operand.

-c "transaction-service-xa_close-function-character-string"~<1-256 character string>

Specify the character string to be used when the transaction service process under OpenTP1 issues the xa_close function. For the character string to be specified, see the manual for each resource manager. If it is necessary to report the NULL character string, omit the -c operand.

-O "user-server-xa_open-function-character-string"~<1-256 character string>

Specify the character string to be used when the user server process issues the xa_open function. For the character string to be specified, see the manual for each resource manager. If it is necessary to report the NULL character string, omit the -O operand.

-C "user-server-xa_close-function-character-string"~<1-256 character string>

Specify the character string to be used when the user server process issues the xa_close function. For the character string to be specified, see the manual for each resource manager. If it is necessary to report the NULL character string, omit the -C operand.

-d

This operand must be specified if this resource manager does not correspond to the commit optimization and prepare optimization. If this specification is omitted for the resource manager that does not correspond to the commit optimization and prepare optimization, the transaction may not be terminated or the resource manager may go down.

If the resource manager with this operand participates in a transaction, the transaction branch does not perform the commit optimization and prepare optimization.

-e

Specify this option to retry issuing the xa_close function, the xa_open function, and the xa_start function in this order to the resource manager. The -e option is useful, if an error occurs in the xa_start function when a transaction branch starts for the resource manager specified in the -n option. If an error occurs in the xa_start function while the -e option is not specified, the xa_open function and the xa_start function are re-issued in this sequence.

-m

Specify this option to recover undetermined transactions in the applicable resource manager before OpenTP1 goes online.

When you specify this option, the resource manager monitoring service issues the xa_recover function to the resource manager when OpenTP1 starts. Then the resource manager recovers transactions based on the acquired undetermined transaction information as specified in the trn_start_recovery_mode, trn_start_recovery_watch_time, and trn_start_recovery_interval operands.

-r

Specify this option to suspend the recovery of transactions until the resource manager reports the information about undetermined transactions during OpenTP1 startup processing or online processing. Transactions are not recovered until the xa_recover function issued from the transaction recovery process to the resource manager acquires the information about undetermined transactions. If you specify this option, make sure that you secure transaction parallel recovery processes for the number of specified resource managers (specify the number of transaction parallel recovery processes in the trn_recovery_process_count operand). This option can be changed or deleted at restart.

To enable this option, you need to specify an open character string^#.

#

In Oracle 9i and earlier versions, specify OPS_FAILOVER=T for an open character string.

In Oracle 10g and later versions, specify RAC_FAILOVER=T for an open character string.